reframe-video 0.6.4 → 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
     };

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) {
@@ -1072,6 +1074,7 @@ function photoMontage(images, opts = {}) {
         width: W,
         height: H,
         anchor: "center",
+        fit: "cover",
         scale: kA,
         opacity: i === 0 ? 1 : 0
       })
@@ -3178,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
         });

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/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

@@ -9,10 +9,10 @@
  * 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.
+ * 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";

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
@@ -307,9 +309,10 @@ scene({ size, nodes: [...m.nodes, ...titles], timeline: par(m.timeline, titleTra
   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.
+- **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe-video",
-  "version": "0.6.4",
+  "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",