reframe-video 0.6.25 → 0.6.26

package/dist/index.js

@@ -1208,6 +1208,14 @@ function cameraMatrix(cam, size) {
   const d = Math.cos(r) * zoom;
   return [a, b, c, d, W / 2 - a * x - c * y, H / 2 - b * x - d * y];
 }
+function cameraFit(box, opts = {}) {
+  const W = opts.size?.width ?? 1920;
+  const H = opts.size?.height ?? 1080;
+  const m = opts.margin ?? 80;
+  const fit = Math.min(W / (box.width + 2 * m), H / (box.height + 2 * m));
+  const zoom = Math.min(fit, opts.maxZoom ?? 2.4);
+  return { x: box.x + box.width / 2, y: box.y + box.height / 2, zoom };
+}
 function cameraTo(props, opts = {}) {
   return tween(CAMERA_ID, props, opts);
 }
@@ -3602,6 +3610,7 @@ export {
   SFX_DURATION,
   SceneValidationError,
   beat,
+  cameraFit,
   cameraMatrix,
   cameraTo,
   characterPreset,

package/dist/types/camera.d.ts

@@ -24,6 +24,33 @@ export declare const CAMERA_PROPS: readonly ["x", "y", "zoom", "rotation", "pers
  * collapse to the identity.
  */
 export declare function cameraMatrix(cam: CameraIR, size: Size): Mat2D;
+/**
+ * Frame a scene-space bounding box in the viewport — returns `{ x, y, zoom }` to
+ * spread into `cameraTo`, GUARANTEED not to clip the box. The visible scene rect
+ * is `W/zoom × H/zoom` centred on `(x, y)`; fitting `box` (+ `margin` padding on
+ * the tight axis) means `zoom = min(W/(box.w+2m), H/(box.h+2m))`, capped by
+ * `maxZoom` so a tiny target doesn't zoom absurdly close.
+ *
+ *   cameraTo(cameraFit({ x: 200, y: 760, width: 740, height: 360 }, { margin: 90 }),
+ *            { duration: 1, ease: "easeInOutCubic" })
+ *
+ * `box` is a top-left rect in scene coords (a centre-anchored panel at (px,py) of
+ * size (pw,ph) is `{ x: px-pw/2, y: py-ph/2, width: pw, height: ph }`).
+ */
+export declare function cameraFit(box: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, opts?: {
+    size?: Size;
+    margin?: number;
+    maxZoom?: number;
+}): {
+    x: number;
+    y: number;
+    zoom: number;
+};
 /** Keyframe the camera: a `tween` on the reserved "camera" target. */
 export declare function cameraTo(props: CameraIR, opts?: {
     duration?: number;

package/dist/types/index.d.ts

@@ -5,7 +5,7 @@ export { compileComposition, type CompiledComposition, type ScenePlacement, } fr
 export { composeScene, formatComposeReport, type OverlayDoc, type ComposeReport, } from "./compose.js";
 export { compileScene, type CompiledScene, type PropertySegment, type LabelSpan, type MotionDriver } from "./compile.js";
 export { pathPoint, pathTangentAngle, type Pt } from "./path.js";
-export { cameraTo, cameraMatrix, CAMERA_ID, CAMERA_PROPS } from "./camera.js";
+export { cameraTo, cameraFit, cameraMatrix, CAMERA_ID, CAMERA_PROPS } from "./camera.js";
 export { linearGradient, radialGradient, conicGradient, isGradient } from "./gradient.js";
 export { glow, dropShadow } from "./effects.js";
 export { row, column, grid, type RowOpts, type GridOpts } from "./layout.js";

package/guides/edsl-guide.md

@@ -90,6 +90,14 @@ row(3, { center: 960, gap: 60, itemWidth: 440 }).map((x, i) =>
 
 `column` is `row` for the y axis.
 
+**Charts/widgets in a panel — derive geometry from the box, and `clip` it.** Don't
+hand-pick a pixels-per-unit scale (bars routinely overflow the panel that way).
+Define the panel rect ONCE, then size from it — bar height `(v/max) · innerH`, x via
+`row(...)` across the panel width — so a tall value can't exceed the box. As a safety
+net, wrap the chart in a clipped group so nothing can ever punch out the panel:
+`group({ clip: { kind: "rect", x, y, width, height, radius } }, [ ...bars ])`. See
+`examples/scenes/annual-report.ts` (and `cameraFit` above to frame the panel).
+
 ## States: declare looks, not motion
 
 Base props on nodes describe the **finished design**. A state is a sparse
@@ -178,6 +186,14 @@ scene({
   `tween` on the `"camera"` target, so `motionPath("camera", pts, …)` (pan along
   a curve) and `oscillate/wiggle("camera", "rotation"|"x"|…)` (handheld drift)
   also work.
+- **Frame a region without clipping — use `cameraFit`, not a guessed `zoom`.** The
+  visible scene rect is `W/zoom × H/zoom` centred on `(camera.x, camera.y)`, so a
+  hand-picked `zoom` that's too big crops the target. `cameraFit(box, { margin })`
+  returns `{ x, y, zoom }` that frames a scene-space bbox (top-left `{x,y,width,
+  height}`) with padding, guaranteed in-bounds: `cameraTo(cameraFit({ x, y, width,
+  height }, { margin: 80 }), { duration: 1, ease: "easeInOutCubic" })`. A centre-
+  anchored panel at `(px,py)` size `(pw,ph)` is `{ x: px-pw/2, y: py-ph/2, width:
+  pw, height: ph }`. `maxZoom` (default 2.4) caps absurd close-ups.
 - **Pin HUD/titles to the screen** with `fixed: true` on a TOP-LEVEL node — the
   camera won't move it (for overlays, watermarks, captions).
 - Defaults are the identity, so a scene without a camera is unchanged. Don't name

package/package.json

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