reframe-video 0.6.2 → 0.6.4

package/dist/bin.js

@@ -379,6 +379,7 @@ function validateScene(ir) {
       checkPaint(`node "${node.id}" stroke`, props.stroke);
       if (typeof props.blur === "number" && props.blur < 0) problems.push(`node "${node.id}": blur must be >= 0`);
       if (typeof props.shadowBlur === "number" && props.shadowBlur < 0) problems.push(`node "${node.id}": shadowBlur must be >= 0`);
+      if (typeof props.blend === "string" && !BLEND_MODES.has(props.blend)) problems.push(`node "${node.id}": unknown blend "${props.blend}" \u2014 use ${[...BLEND_MODES].join(", ")}`);
       if (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {
@@ -593,11 +594,24 @@ function validateComposition(comp) {
   }
   if (problems.length > 0) throw new SceneValidationError(problems);
 }
-var FX_PROPS, COMMON_PROPS, CAMERA_PROPS, PROPS_BY_TYPE, SceneValidationError, TRANSITIONS;
+var FX_PROPS, BLEND_MODES, COMMON_PROPS, CAMERA_PROPS, PROPS_BY_TYPE, SceneValidationError, TRANSITIONS;
 var init_validate = __esm({
   "../core/src/validate.ts"() {
     "use strict";
-    FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY"];
+    FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY", "blend"];
+    BLEND_MODES = /* @__PURE__ */ new Set([
+      "normal",
+      "multiply",
+      "screen",
+      "overlay",
+      "lighten",
+      "darken",
+      "add",
+      "color-dodge",
+      "soft-light",
+      "hard-light",
+      "difference"
+    ]);
     COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed", ...FX_PROPS];
     CAMERA_PROPS = ["x", "y", "zoom", "rotation"];
     PROPS_BY_TYPE = {
@@ -938,6 +952,15 @@ var init_effects = __esm({
   }
 });
 
+// ../core/src/montage.ts
+var init_montage = __esm({
+  "../core/src/montage.ts"() {
+    "use strict";
+    init_dsl();
+    init_gradient();
+  }
+});
+
 // ../core/src/presets.ts
 function makeRng(seed) {
   let a = seed >>> 0 || 2654435769;
@@ -1396,6 +1419,7 @@ var init_src = __esm({
     init_camera();
     init_gradient();
     init_effects();
+    init_montage();
     init_presets();
     init_devicePreset();
     init_cursor();

package/dist/browserEntry.js

@@ -334,7 +334,7 @@
   }
 
   // ../core/src/validate.ts
-  var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY"];
+  var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY", "blend"];
   var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed", ...FX_PROPS];
   var PROPS_BY_TYPE = {
     rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
@@ -689,6 +689,7 @@
         fx.shadowX = num(id, "shadowX", p.shadowX ?? 0);
         fx.shadowY = num(id, "shadowY", p.shadowY ?? 0);
       }
+      if (p.blend !== void 0 && p.blend !== "normal") fx.blend = p.blend;
       return fx;
     };
     const walk = (node, parent, parentOpacity, clips) => {
@@ -914,6 +915,7 @@
         ctx2.shadowOffsetX = op.shadowX ?? 0;
         ctx2.shadowOffsetY = op.shadowY ?? 0;
       }
+      if (op.blend) ctx2.globalCompositeOperation = mapBlend(op.blend);
       switch (op.type) {
         case "rect": {
           const box = { x: op.offsetX, y: op.offsetY, w: op.width, h: op.height };
@@ -1024,6 +1026,9 @@
       ctx2.restore();
     }
   }
+  function mapBlend(blend) {
+    return blend === "add" ? "lighter" : blend;
+  }
   function quoteFamily(family) {
     return family.includes(" ") && !family.includes('"') ? `"${family}"` : family;
   }

package/dist/cli.js

@@ -324,7 +324,20 @@ function compileScene(ir) {
 }
 
 // ../core/src/validate.ts
-var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY"];
+var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY", "blend"];
+var BLEND_MODES = /* @__PURE__ */ new Set([
+  "normal",
+  "multiply",
+  "screen",
+  "overlay",
+  "lighten",
+  "darken",
+  "add",
+  "color-dodge",
+  "soft-light",
+  "hard-light",
+  "difference"
+]);
 var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed", ...FX_PROPS];
 var CAMERA_PROPS = ["x", "y", "zoom", "rotation"];
 var PROPS_BY_TYPE = {
@@ -378,6 +391,7 @@ function validateScene(ir) {
       checkPaint(`node "${node.id}" stroke`, props.stroke);
       if (typeof props.blur === "number" && props.blur < 0) problems.push(`node "${node.id}": blur must be >= 0`);
       if (typeof props.shadowBlur === "number" && props.shadowBlur < 0) problems.push(`node "${node.id}": shadowBlur must be >= 0`);
+      if (typeof props.blend === "string" && !BLEND_MODES.has(props.blend)) problems.push(`node "${node.id}": unknown blend "${props.blend}" \u2014 use ${[...BLEND_MODES].join(", ")}`);
       if (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {

package/dist/index.js

@@ -334,7 +334,20 @@ function compileScene(ir) {
 }
 
 // ../core/src/validate.ts
-var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY"];
+var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY", "blend"];
+var BLEND_MODES = /* @__PURE__ */ new Set([
+  "normal",
+  "multiply",
+  "screen",
+  "overlay",
+  "lighten",
+  "darken",
+  "add",
+  "color-dodge",
+  "soft-light",
+  "hard-light",
+  "difference"
+]);
 var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed", ...FX_PROPS];
 var CAMERA_PROPS = ["x", "y", "zoom", "rotation"];
 var PROPS_BY_TYPE = {
@@ -388,6 +401,7 @@ function validateScene(ir) {
       checkPaint(`node "${node.id}" stroke`, props.stroke);
       if (typeof props.blur === "number" && props.blur < 0) problems.push(`node "${node.id}": blur must be >= 0`);
       if (typeof props.shadowBlur === "number" && props.shadowBlur < 0) problems.push(`node "${node.id}": shadowBlur must be >= 0`);
+      if (typeof props.blend === "string" && !BLEND_MODES.has(props.blend)) problems.push(`node "${node.id}": unknown blend "${props.blend}" \u2014 use ${[...BLEND_MODES].join(", ")}`);
       if (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {
@@ -998,6 +1012,121 @@ function dropShadow(color, blur = 24, x = 0, y = 12) {
   return { shadowColor: color, shadowBlur: blur, shadowX: x, shadowY: y };
 }
 
+// ../core/src/montage.ts
+function makeRng(seed) {
+  let a = seed >>> 0 || 2654435769;
+  return () => {
+    a = a + 1831565813 | 0;
+    let t = Math.imul(a ^ a >>> 15, 1 | a);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+var norm = (img) => typeof img === "string" ? { src: img } : img;
+function photoMontage(images, opts = {}) {
+  const id = opts.id ?? "shot";
+  const W = opts.size?.width ?? 1920;
+  const H = opts.size?.height ?? 1080;
+  const hold = Math.max(0.5, opts.hold ?? 3.2);
+  const zoom = Math.max(1.001, opts.zoom ?? 1.18);
+  const grade = opts.grade !== false;
+  const rand2 = makeRng((opts.seed ?? 0) + 1);
+  const slides = images.map(norm);
+  const cx = W / 2;
+  const cy = H / 2;
+  const nodes = [];
+  const shots = [];
+  slides.forEach((slide, i) => {
+    const nid = `${id}-${i}`;
+    const slideHold = Math.max(0.5, slide.hold ?? hold);
+    const transition = Math.min(opts.transition ?? 0.6, slideHold * 0.9);
+    const kind = slide.ken ?? ["in", "out", "pan"][Math.floor(rand2() * 3)] ?? "in";
+    const angle = rand2() * Math.PI * 2;
+    const panFrac = 0.4 + rand2() * 0.35;
+    const dx = Math.cos(angle);
+    const dy = Math.sin(angle);
+    let kA, kB;
+    let xA, xB, yA, yB;
+    if (kind === "pan") {
+      kA = kB = zoom;
+      const sx = dx * (zoom - 1) * (W / 2) * panFrac;
+      const sy = dy * (zoom - 1) * (H / 2) * panFrac;
+      xA = cx - sx;
+      xB = cx + sx;
+      yA = cy - sy;
+      yB = cy + sy;
+    } else {
+      kA = kind === "in" ? 1 : zoom;
+      kB = kind === "in" ? zoom : 1;
+      xA = cx + dx * (kA - 1) * (W / 2) * panFrac;
+      xB = cx + dx * (kB - 1) * (W / 2) * panFrac;
+      yA = cy + dy * (kA - 1) * (H / 2) * panFrac;
+      yB = cy + dy * (kB - 1) * (H / 2) * panFrac;
+    }
+    nodes.push(
+      image({
+        id: nid,
+        src: slide.src,
+        x: xA,
+        y: yA,
+        width: W,
+        height: H,
+        anchor: "center",
+        scale: kA,
+        opacity: i === 0 ? 1 : 0
+      })
+    );
+    const ken = tween(
+      nid,
+      { scale: kB, x: xB, y: yB },
+      { duration: slideHold, ease: "easeInOutQuad", label: `shot-${i}` }
+    );
+    const shot = i === 0 ? par(ken) : par(
+      ken,
+      tween(`${id}-${i - 1}`, { opacity: 0 }, { duration: transition, ease: "linear", label: `cross-${i}` }),
+      tween(nid, { opacity: 1 }, { duration: transition, ease: "linear" })
+    );
+    shots.push(shot);
+  });
+  if (grade) {
+    nodes.push(
+      rect({
+        id: `${id}-vignette`,
+        x: 0,
+        y: 0,
+        width: W,
+        height: H,
+        fill: radialGradient(
+          [
+            { offset: 0.55, color: "#FFFFFF" },
+            { offset: 1, color: "#6E6E6E" }
+          ],
+          { cx: 0.5, cy: 0.5, r: 0.72 }
+        ),
+        blend: "multiply"
+      })
+    );
+    nodes.push(
+      rect({
+        id: `${id}-scrim`,
+        x: 0,
+        y: 0,
+        width: W,
+        height: H,
+        fill: linearGradient(
+          [
+            { offset: 0, color: "#00000000" },
+            { offset: 0.62, color: "#00000000" },
+            { offset: 1, color: "#000000B0" }
+          ],
+          { angle: 90 }
+        )
+      })
+    );
+  }
+  return { nodes, timeline: beat("montage", { nodes: nodes.map((n3) => n3.id) }, [seq(...shots)]) };
+}
+
 // ../core/src/presets.ts
 var PRESET_NAMES = [
   "draw-bloom",
@@ -1007,7 +1136,7 @@ var PRESET_NAMES = [
   "reveal-orbit",
   "spin-forge"
 ];
-function makeRng(seed) {
+function makeRng2(seed) {
   let a = seed >>> 0 || 2654435769;
   return () => {
     a = a + 1831565813 | 0;
@@ -1019,7 +1148,7 @@ function makeRng(seed) {
 var clamp01 = (x) => Math.max(0, Math.min(1, x));
 var SET = 1 / 120;
 function ctx(o) {
-  const rand2 = makeRng((o.seed ?? 0) + 1);
+  const rand2 = makeRng2((o.seed ?? 0) + 1);
   return {
     e: clamp01(o.energy ?? 0.5),
     sp: Math.max(0.25, o.speed ?? 1),
@@ -1574,7 +1703,7 @@ var CHARACTER_PRESET_NAMES = ["walk", "run", "jump", "dance", "wave", "cheer"];
 var THIGH = 76;
 var SHIN = 72;
 var clamp012 = (x) => Math.max(0, Math.min(1, x));
-function makeRng2(seed) {
+function makeRng3(seed) {
   let a = seed >>> 0 || 2654435769;
   return () => {
     a = a + 1831565813 | 0;
@@ -1585,7 +1714,7 @@ function makeRng2(seed) {
 }
 var dur2 = (base, sp) => base / sp;
 function ctx2(o) {
-  const rand2 = makeRng2((o.seed ?? 0) + 1);
+  const rand2 = makeRng3((o.seed ?? 0) + 1);
   return {
     g: o.target,
     label: o.label,
@@ -2958,6 +3087,7 @@ function evaluate(compiled, t) {
       fx.shadowX = num(id, "shadowX", p.shadowX ?? 0);
       fx.shadowY = num(id, "shadowY", p.shadowY ?? 0);
     }
+    if (p.blend !== void 0 && p.blend !== "normal") fx.blend = p.blend;
     return fx;
   };
   const walk = (node, parent, parentOpacity, clips) => {
@@ -3258,6 +3388,7 @@ export {
   path,
   pathPoint,
   pathTangentAngle,
+  photoMontage,
   poseTo,
   radialGradient,
   rect,

package/dist/labels.js

@@ -318,7 +318,20 @@ function compileScene(ir) {
 }
 
 // ../core/src/validate.ts
-var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY"];
+var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY", "blend"];
+var BLEND_MODES = /* @__PURE__ */ new Set([
+  "normal",
+  "multiply",
+  "screen",
+  "overlay",
+  "lighten",
+  "darken",
+  "add",
+  "color-dodge",
+  "soft-light",
+  "hard-light",
+  "difference"
+]);
 var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed", ...FX_PROPS];
 var CAMERA_PROPS = ["x", "y", "zoom", "rotation"];
 var PROPS_BY_TYPE = {
@@ -372,6 +385,7 @@ function validateScene(ir) {
       checkPaint(`node "${node.id}" stroke`, props.stroke);
       if (typeof props.blur === "number" && props.blur < 0) problems.push(`node "${node.id}": blur must be >= 0`);
       if (typeof props.shadowBlur === "number" && props.shadowBlur < 0) problems.push(`node "${node.id}": shadowBlur must be >= 0`);
+      if (typeof props.blend === "string" && !BLEND_MODES.has(props.blend)) problems.push(`node "${node.id}": unknown blend "${props.blend}" \u2014 use ${[...BLEND_MODES].join(", ")}`);
       if (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {

package/dist/renderer-canvas.js

@@ -62,6 +62,7 @@ function drawDisplayList(ctx, ops, images) {
       ctx.shadowOffsetX = op.shadowX ?? 0;
       ctx.shadowOffsetY = op.shadowY ?? 0;
     }
+    if (op.blend) ctx.globalCompositeOperation = mapBlend(op.blend);
     switch (op.type) {
       case "rect": {
         const box = { x: op.offsetX, y: op.offsetY, w: op.width, h: op.height };
@@ -172,6 +173,9 @@ function drawDisplayList(ctx, ops, images) {
     ctx.restore();
   }
 }
+function mapBlend(blend) {
+  return blend === "add" ? "lighter" : blend;
+}
 function quoteFamily(family) {
   return family.includes(" ") && !family.includes('"') ? `"${family}"` : family;
 }

package/dist/trace-cli.js

@@ -6,7 +6,7 @@ import { resolve as resolve2 } from "node:path";
 import { pathToFileURL } from "node:url";
 
 // ../core/src/validate.ts
-var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY"];
+var FX_PROPS = ["blur", "shadowColor", "shadowBlur", "shadowX", "shadowY", "blend"];
 var COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed", ...FX_PROPS];
 var PROPS_BY_TYPE = {
   rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],

package/dist/types/evaluate.d.ts

@@ -4,7 +4,7 @@
  * always. Renderers only draw; they never compute animation.
  */
 import type { CompiledScene } from "./compile.js";
-import type { ClipShape, Paint, PropValue } from "./ir.js";
+import type { BlendMode, ClipShape, Paint, PropValue } from "./ir.js";
 /** Canvas-style 2D affine matrix [a, b, c, d, e, f]. */
 export type Mat2D = [number, number, number, number, number, number];
 /** A clip from an ancestor group: its shape in the group's coordinate space,
@@ -30,6 +30,8 @@ interface OpBase {
     shadowBlur?: number;
     shadowX?: number;
     shadowY?: number;
+    /** Compositing mode (discrete; present only when authored and not "normal"). */
+    blend?: BlendMode;
 }
 export type DisplayOp = (OpBase & {
     type: "rect";

package/dist/types/index.d.ts

@@ -8,6 +8,7 @@ export { pathPoint, pathTangentAngle, type Pt } from "./path.js";
 export { cameraTo, cameraMatrix, CAMERA_ID, CAMERA_PROPS } from "./camera.js";
 export { linearGradient, radialGradient, conicGradient, isGradient } from "./gradient.js";
 export { glow, dropShadow } from "./effects.js";
+export { photoMontage, type MontageImage, type MontageOpts, type MontageResult, type KenBurns } from "./montage.js";
 export { motionPreset, PRESET_NAMES, type PresetName, type PresetRig, type PresetOpts } from "./presets.js";
 export { devicePreset, deviceScreen, deviceScreenCenter, deviceBounds, deviceScreenPoint, DEVICE_PRESET_NAMES, type DevicePresetName, type DevicePresetOpts } from "./devicePreset.js";
 export { cursor, cursorTo, cursorPath, cursorClick, cursorDouble, type CursorStyle, type CursorOpts, type CursorToOpts, type CursorPathOpts, type CursorClickOpts } from "./cursor.js";

package/dist/types/ir.d.ts

@@ -47,7 +47,12 @@ export interface BaseProps {
     shadowBlur?: number;
     shadowX?: number;
     shadowY?: number;
+    /** How this node composites with what's already drawn (default "normal"). `screen`/
+     *  `add` brighten (additive light/glow), `multiply` tints/deepens. No-op on a group. */
+    blend?: BlendMode;
 }
+/** Compositing modes (Canvas `globalCompositeOperation`; `add` maps to `lighter`). */
+export type BlendMode = "normal" | "multiply" | "screen" | "overlay" | "lighten" | "darken" | "add" | "color-dodge" | "soft-light" | "hard-light" | "difference";
 /**
  * A paint is a solid color string OR a gradient. Coordinates are normalized to the
  * node's bounding box (0..1, SVG `objectBoundingBox` style) so a gradient is just an

package/dist/types/montage.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Photo montage — a SEEDED GENERATOR that turns a list of images into a polished
+ * slideshow: layered image nodes + a retimable `beat` that crossfades between
+ * slides and pans/zooms each (Ken Burns), with an optional cinematic grade
+ * (vignette + bottom scrim) built from gradients + blend modes. The photo analog
+ * of `motionPreset` / `splitText`.
+ *
+ * Pure and deterministic: the per-slide Ken Burns direction / framing is chosen by
+ * a seeded PRNG (mulberry32) — same (images, opts) → identical IR; a different
+ * `seed` re-frames within the same family. No Math.random / Date.
+ *
+ * Constraint it works around: the `image` node draws STRETCHED to width×height
+ * (no object-fit). So images must already be the frame's aspect ratio; each layer
+ * is sized to the frame and the Ken Burns keeps `scale >= 1` with the pan bounded
+ * to the scale's slack, so an edge is never revealed.
+ */
+import type { NodeIR, TimelineIR } from "./ir.js";
+export type KenBurns = "in" | "out" | "pan";
+/** One slide: a bare src, or a src with per-slide overrides. */
+export type MontageImage = string | {
+    src: string;
+    hold?: number;
+    ken?: KenBurns;
+};
+export interface MontageOpts {
+    /** Node-id prefix → stable regen addresses `${id}-${i}`. Default "shot". */
+    id?: string;
+    /** Frame size; must match the scene size. Default 1920×1080. */
+    size?: {
+        width: number;
+        height: number;
+    };
+    /** Seconds each slide is held (incl. its incoming crossfade). Default 3.2. */
+    hold?: number;
+    /** Crossfade seconds between slides. Default 0.6. */
+    transition?: number;
+    /** Max Ken Burns zoom (>1). Default 1.18. */
+    zoom?: number;
+    /** Emit the vignette + bottom-scrim grade overlays. Default true. */
+    grade?: boolean;
+    /** Deterministic framing. Same seed → identical IR. Default 0. */
+    seed?: number;
+}
+export interface MontageResult {
+    /** Image layers (+ grade overlays) — place these in `scene({ nodes })`. */
+    nodes: NodeIR[];
+    /** The montage beat — place in `scene({ timeline })` (compose with `seq`). */
+    timeline: TimelineIR;
+}
+/**
+ * Build a montage from a list of frame-aspect images.
+ *
+ *   const m = photoMontage(["a.jpg", "b.jpg", "c.jpg"], { seed: 7 });
+ *   scene({ size, nodes: [...m.nodes, ...titles], timeline: seq(m.timeline) });
+ */
+export declare function photoMontage(images: MontageImage[], opts?: MontageOpts): MontageResult;

package/guides/edsl-guide.md

@@ -194,6 +194,23 @@ rect({ id: "card", /* … */, blur: 18 }); tween("card", { blur: 0 }, { duration
 - No-op on a `group` (apply to a child; group/composite blur is a later add). See
   `examples/scenes/shadow-demo.ts`.
 
+### Blend modes (compositing)
+
+`blend` selects how a shape composites with what's already drawn beneath it — the
+primitive that makes light read.
+
+```ts
+ellipse({ id: "glow", fill: radialGradient(["#FF2D6A", "#FF2D6A00"]), blend: "screen" }) // additive light: brightens where blobs overlap
+rect({ id: "tint", fill: "#1E5BFF", blend: "multiply" })                                 // tint/deepen the layer beneath
+rect({ id: "neon", fill: linearGradient([...]), shadowColor: "#7A4DFF", blend: "screen" }) // compose with glow
+```
+
+- Modes: `normal` (default), `multiply`, `screen`, `overlay`, `lighten`, `darken`,
+  `add` (additive light), `color-dodge`, `soft-light`, `hard-light`, `difference`.
+- **Discrete**, not interpolated — set per node (a static string). Default `normal`.
+- Per-shape. A whole-group blend (composite the subtree, then blend) is a later add;
+  on a `group` the prop is a no-op. See `examples/scenes/blend-demo.ts`.
+
 ## Character rig (skeleton, poses, IK)
 
 A first-class, declarative character rig that **compiles to plain IR** (nested
@@ -272,6 +289,31 @@ const T = splitText("MOTION IS DATA", { id: "t", x: 960, y: 470, fontSize: 130 }
 Every effect is seeded (same `seed` → identical) and pure keyframes. To time a
 `textLoop` window, add up the `textIn` beat length (≈ `(n-1)·stagger + glyphDur`).
 
+## Photo montage (`photoMontage`)
+
+Turn a list of images into a polished slideshow — crossfades + seeded Ken Burns
+(pan/zoom) + an optional cinematic grade (vignette + bottom scrim via gradients +
+blend) — without hand-wiring each move. The photo analog of `motionPreset`.
+
+```ts
+const m = photoMontage(["a.jpg", "b.jpg", "c.jpg"], {
+  id: "shot", size: { width: 1920, height: 1080 },
+  hold: 3.4, transition: 0.7, zoom: 1.16, seed: 7,
+});
+scene({ size, nodes: [...m.nodes, ...titles], timeline: par(m.timeline, titleTrack) });
+```
+
+- Returns `{ nodes, timeline }` (like `splitText` owns its glyph nodes). `nodes` are
+  the stacked image layers (+ `${id}-vignette` / `${id}-scrim` grade overlays);
+  `timeline` is a retimable `beat("montage", …)`. Stable addresses: `${id}-${i}`,
+  labels `shot-${i}` / `cross-${i}`.
+- **Images must be the frame's aspect ratio** — the `image` node draws stretched
+  (no object-fit), so cover-crop your photos to `size` first. The Ken Burns keeps
+  `scale ≥ 1` with the pan bounded to its slack, so an edge is never revealed.
+- Per-slide overrides: `{ src, hold?, ken? }` where `ken` is `"in" | "out" | "pan"`.
+- Seeded + pure (same `(images, opts)` → identical IR). Note: image-node sources do
+  not render in `reframe player` / artifacts — montage ships as mp4.
+
 ## Cursor (UI demos)
 
 A vector mouse pointer that glides across the scene and clicks things — for app

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe-video",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Declarative motion graphics that AI can write and humans can tweak — human edits survive AI regeneration. Deterministic mp4 renders from a plain-data scene format.",
   "keywords": [
     "motion-graphics",