reframe-video 0.6.3 → 0.6.4

package/dist/bin.js

@@ -952,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;
@@ -1410,6 +1419,7 @@ var init_src = __esm({
     init_camera();
     init_gradient();
     init_effects();
+    init_montage();
     init_presets();
     init_devicePreset();
     init_cursor();

package/dist/index.js

@@ -1012,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",
@@ -1021,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;
@@ -1033,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),
@@ -1588,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;
@@ -1599,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,
@@ -3273,6 +3388,7 @@ export {
   path,
   pathPoint,
   pathTangentAngle,
+  photoMontage,
   poseTo,
   radialGradient,
   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/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

@@ -289,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.3",
+  "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",