reframe-video 0.6.3 → 0.6.5

package/dist/bin.js

@@ -380,6 +380,7 @@ function validateScene(ir) {
       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 (typeof props.fit === "string" && !IMAGE_FITS.has(props.fit)) problems.push(`node "${node.id}": unknown fit "${props.fit}" \u2014 use ${[...IMAGE_FITS].join(", ")}`);
       if (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {
@@ -594,7 +595,7 @@ function validateComposition(comp) {
   }
   if (problems.length > 0) throw new SceneValidationError(problems);
 }
-var FX_PROPS, BLEND_MODES, COMMON_PROPS, CAMERA_PROPS, PROPS_BY_TYPE, SceneValidationError, TRANSITIONS;
+var FX_PROPS, BLEND_MODES, IMAGE_FITS, COMMON_PROPS, CAMERA_PROPS, PROPS_BY_TYPE, SceneValidationError, TRANSITIONS;
 var init_validate = __esm({
   "../core/src/validate.ts"() {
     "use strict";
@@ -612,6 +613,7 @@ var init_validate = __esm({
       "hard-light",
       "difference"
     ]);
+    IMAGE_FITS = /* @__PURE__ */ new Set(["fill", "cover"]);
     COMMON_PROPS = ["x", "y", "opacity", "rotation", "scale", "scaleX", "scaleY", "skewX", "skewY", "anchor", "fixed", ...FX_PROPS];
     CAMERA_PROPS = ["x", "y", "zoom", "rotation"];
     PROPS_BY_TYPE = {
@@ -619,7 +621,7 @@ var init_validate = __esm({
       ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
       line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
       text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
-      image: [...COMMON_PROPS, "src", "width", "height"],
+      image: [...COMMON_PROPS, "src", "width", "height", "fit"],
       path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
       group: COMMON_PROPS
     };
@@ -952,6 +954,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;
@@ -1410,6 +1421,7 @@ var init_src = __esm({
     init_camera();
     init_gradient();
     init_effects();
+    init_montage();
     init_presets();
     init_devicePreset();
     init_cursor();

package/dist/browserEntry.js

@@ -341,7 +341,7 @@
     ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
     line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
     text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
-    image: [...COMMON_PROPS, "src", "width", "height"],
+    image: [...COMMON_PROPS, "src", "width", "height", "fit"],
     path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
     group: COMMON_PROPS
   };
@@ -780,6 +780,7 @@
             height,
             offsetX: -width * ax,
             offsetY: -height * ay,
+            ...node.props.fit && node.props.fit !== "fill" ? { fit: node.props.fit } : {},
             ...fx,
             ...clipSpread
           });
@@ -972,7 +973,13 @@
         case "image": {
           const img = images2?.get(op.src);
           if (img) {
-            ctx2.drawImage(img, op.offsetX, op.offsetY, op.width, op.height);
+            if (op.fit === "cover") {
+              const [iw, ih] = intrinsicSize(img);
+              const { sx, sy, sw, sh } = coverRect(iw, ih, op.width, op.height);
+              ctx2.drawImage(img, sx, sy, sw, sh, op.offsetX, op.offsetY, op.width, op.height);
+            } else {
+              ctx2.drawImage(img, op.offsetX, op.offsetY, op.width, op.height);
+            }
           } else {
             ctx2.fillStyle = "#2A2A30";
             ctx2.fillRect(op.offsetX, op.offsetY, op.width, op.height);
@@ -1029,6 +1036,17 @@
   function mapBlend(blend) {
     return blend === "add" ? "lighter" : blend;
   }
+  function coverRect(iw, ih, dw, dh) {
+    if (iw <= 0 || ih <= 0 || dw <= 0 || dh <= 0) return { sx: 0, sy: 0, sw: iw, sh: ih };
+    const s = Math.max(dw / iw, dh / ih);
+    const sw = dw / s;
+    const sh = dh / s;
+    return { sx: (iw - sw) / 2, sy: (ih - sh) / 2, sw, sh };
+  }
+  function intrinsicSize(img) {
+    const a = img;
+    return [a.naturalWidth || a.width || 0, a.naturalHeight || a.height || 0];
+  }
   function quoteFamily(family) {
     return family.includes(" ") && !family.includes('"') ? `"${family}"` : family;
   }

package/dist/cli.js

@@ -338,6 +338,7 @@ var BLEND_MODES = /* @__PURE__ */ new Set([
   "hard-light",
   "difference"
 ]);
+var IMAGE_FITS = /* @__PURE__ */ new Set(["fill", "cover"]);
 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 = {
@@ -345,7 +346,7 @@ var PROPS_BY_TYPE = {
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
   line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
   text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
-  image: [...COMMON_PROPS, "src", "width", "height"],
+  image: [...COMMON_PROPS, "src", "width", "height", "fit"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS
 };
@@ -392,6 +393,7 @@ function validateScene(ir) {
       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 (typeof props.fit === "string" && !IMAGE_FITS.has(props.fit)) problems.push(`node "${node.id}": unknown fit "${props.fit}" \u2014 use ${[...IMAGE_FITS].join(", ")}`);
       if (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {

package/dist/index.js

@@ -348,6 +348,7 @@ var BLEND_MODES = /* @__PURE__ */ new Set([
   "hard-light",
   "difference"
 ]);
+var IMAGE_FITS = /* @__PURE__ */ new Set(["fill", "cover"]);
 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 = {
@@ -355,7 +356,7 @@ var PROPS_BY_TYPE = {
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
   line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
   text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
-  image: [...COMMON_PROPS, "src", "width", "height"],
+  image: [...COMMON_PROPS, "src", "width", "height", "fit"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS
 };
@@ -402,6 +403,7 @@ function validateScene(ir) {
       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 (typeof props.fit === "string" && !IMAGE_FITS.has(props.fit)) problems.push(`node "${node.id}": unknown fit "${props.fit}" \u2014 use ${[...IMAGE_FITS].join(", ")}`);
       if (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {
@@ -1012,6 +1014,122 @@ 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",
+        fit: "cover",
+        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",
@@ -1021,7 +1139,7 @@ var PRESET_NAMES = [
   "reveal-orbit",
   "spin-forge"
 ];
-function makeRng(seed) {
+function makeRng2(seed) {
   let a = seed >>> 0 || 2654435769;
   return () => {
     a = a + 1831565813 | 0;
@@ -1033,7 +1151,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),
@@ -1588,7 +1706,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;
@@ -1599,7 +1717,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,
@@ -3063,6 +3181,7 @@ function evaluate(compiled, t) {
           height,
           offsetX: -width * ax,
           offsetY: -height * ay,
+          ...node.props.fit && node.props.fit !== "fill" ? { fit: node.props.fit } : {},
           ...fx,
           ...clipSpread
         });
@@ -3273,6 +3392,7 @@ export {
   path,
   pathPoint,
   pathTangentAngle,
+  photoMontage,
   poseTo,
   radialGradient,
   rect,

package/dist/labels.js

@@ -332,6 +332,7 @@ var BLEND_MODES = /* @__PURE__ */ new Set([
   "hard-light",
   "difference"
 ]);
+var IMAGE_FITS = /* @__PURE__ */ new Set(["fill", "cover"]);
 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 = {
@@ -339,7 +340,7 @@ var PROPS_BY_TYPE = {
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
   line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
   text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
-  image: [...COMMON_PROPS, "src", "width", "height"],
+  image: [...COMMON_PROPS, "src", "width", "height", "fit"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS
 };
@@ -386,6 +387,7 @@ function validateScene(ir) {
       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 (typeof props.fit === "string" && !IMAGE_FITS.has(props.fit)) problems.push(`node "${node.id}": unknown fit "${props.fit}" \u2014 use ${[...IMAGE_FITS].join(", ")}`);
       if (node.type === "group") {
         const clip = node.props.clip;
         if (clip) {

package/dist/renderer-canvas.js

@@ -119,7 +119,13 @@ function drawDisplayList(ctx, ops, images) {
       case "image": {
         const img = images?.get(op.src);
         if (img) {
-          ctx.drawImage(img, op.offsetX, op.offsetY, op.width, op.height);
+          if (op.fit === "cover") {
+            const [iw, ih] = intrinsicSize(img);
+            const { sx, sy, sw, sh } = coverRect(iw, ih, op.width, op.height);
+            ctx.drawImage(img, sx, sy, sw, sh, op.offsetX, op.offsetY, op.width, op.height);
+          } else {
+            ctx.drawImage(img, op.offsetX, op.offsetY, op.width, op.height);
+          }
         } else {
           ctx.fillStyle = "#2A2A30";
           ctx.fillRect(op.offsetX, op.offsetY, op.width, op.height);
@@ -176,6 +182,17 @@ function drawDisplayList(ctx, ops, images) {
 function mapBlend(blend) {
   return blend === "add" ? "lighter" : blend;
 }
+function coverRect(iw, ih, dw, dh) {
+  if (iw <= 0 || ih <= 0 || dw <= 0 || dh <= 0) return { sx: 0, sy: 0, sw: iw, sh: ih };
+  const s = Math.max(dw / iw, dh / ih);
+  const sw = dw / s;
+  const sh = dh / s;
+  return { sx: (iw - sw) / 2, sy: (ih - sh) / 2, sw, sh };
+}
+function intrinsicSize(img) {
+  const a = img;
+  return [a.naturalWidth || a.width || 0, a.naturalHeight || a.height || 0];
+}
 function quoteFamily(family) {
   return family.includes(" ") && !family.includes('"') ? `"${family}"` : family;
 }
@@ -193,6 +210,7 @@ function pathLength(d) {
   return len;
 }
 export {
+  coverRect,
   drawDisplayList,
   renderFrame
 };

package/dist/trace-cli.js

@@ -13,7 +13,7 @@ var PROPS_BY_TYPE = {
   ellipse: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth"],
   line: ["x1", "y1", "x2", "y2", "stroke", "strokeWidth", "opacity", "progress", ...FX_PROPS],
   text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
-  image: [...COMMON_PROPS, "src", "width", "height"],
+  image: [...COMMON_PROPS, "src", "width", "height", "fit"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
   group: COMMON_PROPS
 };

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 { BlendMode, ClipShape, Paint, PropValue } from "./ir.js";
+import type { BlendMode, ClipShape, ImageFit, 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,
@@ -78,6 +78,8 @@ export type DisplayOp = (OpBase & {
     height: number;
     offsetX: number;
     offsetY: number;
+    /** Box-fit; present only when authored and not "fill". */
+    fit?: ImageFit;
 }) | (OpBase & {
     type: "path";
     /** SVG path data, drawn via Path2D. */

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

@@ -182,7 +182,16 @@ export interface ImageProps extends BaseProps {
     src: string;
     width: number;
     height: number;
+    /**
+     * How the image maps into its width×height box. `"fill"` (default) stretches to
+     * the box (today's behavior); `"cover"` crops the image to fill the box at its
+     * natural aspect (centered) — no distortion, no pre-cropping. Discrete (not
+     * keyframed); the cover crop is done by the renderer, which knows the decoded size.
+     */
+    fit?: ImageFit;
 }
+/** Image box-fit mode. `cover` = crop-to-fill at the image's aspect (centered). */
+export type ImageFit = "fill" | "cover";
 export type NodeIR = {
     type: "rect";
     id: string;

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.
+ *
+ * Each layer is sized to the frame and uses `fit: "cover"`, so images of ANY aspect
+ * ratio fill the frame (cropped, centered) with no distortion — no pre-cropping. 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

@@ -47,9 +47,11 @@ Factories return plain data. Every node needs a unique `id`.
   same structure (e.g. both 4-cubic ovals). Arcs (`A`) can't morph (their 0/1
   flags aren't interpolable) and incompatible shapes snap at the midpoint; build
   morph targets from `M/L/C/Q/Z` only.
-- `image({ id, src, x, y, width, height, opacity?, rotation?, scale?, anchor? })` —
-  `src` is a file path, absolute or relative to the scene file; drawn stretched
-  to `width`×`height` (png/jpg/webp). `src` switches discretely (no crossfade) —
+- `image({ id, src, x, y, width, height, fit?, opacity?, rotation?, scale?, anchor? })` —
+  `src` is a file path, absolute or relative to the scene file (png/jpg/webp).
+  `fit` controls how it maps into `width`×`height`: `"fill"` (default) stretches;
+  `"cover"` crops to fill the box at the image's natural aspect, centered (no
+  distortion — drop in any-aspect photos). `src` switches discretely (no crossfade) —
   for hard-cut frame sequences stack image nodes and step their `opacity`; for
   a dissolve, crossfade two nodes' opacity.
 - `group({ id, x, y, opacity?, rotation?, scale?, anchor? }, children)` — children's
@@ -289,6 +291,32 @@ 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}`.
+- **Any-aspect photos work** — each layer uses `fit: "cover"`, so the renderer
+  crops to fill the frame at the image's aspect (no pre-cropping, no distortion).
+  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.3",
+  "version": "0.6.5",
   "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",