reframe-video 0.6.25 → 0.6.27

package/dist/diff.js

@@ -13,6 +13,30 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // ../core/src/ir.ts
+var SFX_NAMES = [
+  "whoosh",
+  "swish",
+  "rise",
+  "riser",
+  "warp",
+  "tick",
+  "click",
+  "blip",
+  "pop",
+  "select",
+  "thud",
+  "boom",
+  "knock",
+  "chime",
+  "ding",
+  "coin",
+  "sparkle",
+  "shimmer",
+  "success",
+  "zap",
+  "error"
+];
+var BGM_SYNTHS = ["ambient-pad", "lofi", "pulse", "tension", "uplift"];
 var DEFAULT_TO_DURATION = 0.5;
 var DEFAULT_TWEEN_DURATION = 0.5;
 var DEFAULT_MOTIONPATH_DURATION = 1;
@@ -662,7 +686,6 @@ function validateScene(ir) {
       }
     }
   }
-  const SFX_NAMES = ["whoosh", "pop", "tick", "rise", "shimmer", "thud"];
   for (const [i, cue] of (ir.audio?.cues ?? []).entries()) {
     if (typeof cue.at === "string" && !labels.has(cue.at)) {
       problems.push(
@@ -698,6 +721,10 @@ function validateScene(ir) {
   if (ir.audio?.bgm?.file !== void 0 && ir.audio.bgm.synth !== void 0) {
     problems.push('audio.bgm: use either "file" or "synth", not both');
   }
+  const bgmSynth = ir.audio?.bgm?.synth;
+  if (bgmSynth !== void 0 && !BGM_SYNTHS.includes(bgmSynth)) {
+    problems.push(`audio.bgm.synth: unknown synth "${bgmSynth}" \u2014 valid: ${BGM_SYNTHS.join(", ")}`);
+  }
   if (problems.length > 0) throw new SceneValidationError(problems);
 }
 var TRANSITIONS = ["cut", "crossfade"];

package/dist/frame.js

@@ -40,6 +40,30 @@ import { existsSync } from "node:fs";
 import { extname, isAbsolute, resolve } from "node:path";
 
 // ../core/src/ir.ts
+var SFX_NAMES = [
+  "whoosh",
+  "swish",
+  "rise",
+  "riser",
+  "warp",
+  "tick",
+  "click",
+  "blip",
+  "pop",
+  "select",
+  "thud",
+  "boom",
+  "knock",
+  "chime",
+  "ding",
+  "coin",
+  "sparkle",
+  "shimmer",
+  "success",
+  "zap",
+  "error"
+];
+var BGM_SYNTHS = ["ambient-pad", "lofi", "pulse", "tension", "uplift"];
 var DEFAULT_TO_DURATION = 0.5;
 var DEFAULT_TWEEN_DURATION = 0.5;
 var DEFAULT_MOTIONPATH_DURATION = 1;
@@ -689,7 +713,6 @@ function validateScene(ir) {
       }
     }
   }
-  const SFX_NAMES = ["whoosh", "pop", "tick", "rise", "shimmer", "thud"];
   for (const [i, cue] of (ir.audio?.cues ?? []).entries()) {
     if (typeof cue.at === "string" && !labels.has(cue.at)) {
       problems.push(
@@ -725,6 +748,10 @@ function validateScene(ir) {
   if (ir.audio?.bgm?.file !== void 0 && ir.audio.bgm.synth !== void 0) {
     problems.push('audio.bgm: use either "file" or "synth", not both');
   }
+  const bgmSynth = ir.audio?.bgm?.synth;
+  if (bgmSynth !== void 0 && !BGM_SYNTHS.includes(bgmSynth)) {
+    problems.push(`audio.bgm.synth: unknown synth "${bgmSynth}" \u2014 valid: ${BGM_SYNTHS.join(", ")}`);
+  }
   if (problems.length > 0) throw new SceneValidationError(problems);
 }
 var TRANSITIONS = ["cut", "crossfade"];

package/dist/index.js

@@ -1,4 +1,28 @@
 // ../core/src/ir.ts
+var SFX_NAMES = [
+  "whoosh",
+  "swish",
+  "rise",
+  "riser",
+  "warp",
+  "tick",
+  "click",
+  "blip",
+  "pop",
+  "select",
+  "thud",
+  "boom",
+  "knock",
+  "chime",
+  "ding",
+  "coin",
+  "sparkle",
+  "shimmer",
+  "success",
+  "zap",
+  "error"
+];
+var BGM_SYNTHS = ["ambient-pad", "lofi", "pulse", "tension", "uplift"];
 var DEFAULT_CROSSFADE = 0.5;
 var DEFAULT_TO_DURATION = 0.5;
 var DEFAULT_TWEEN_DURATION = 0.5;
@@ -785,7 +809,6 @@ function validateScene(ir) {
       }
     }
   }
-  const SFX_NAMES = ["whoosh", "pop", "tick", "rise", "shimmer", "thud"];
   for (const [i, cue] of (ir.audio?.cues ?? []).entries()) {
     if (typeof cue.at === "string" && !labels.has(cue.at)) {
       problems.push(
@@ -821,6 +844,10 @@ function validateScene(ir) {
   if (ir.audio?.bgm?.file !== void 0 && ir.audio.bgm.synth !== void 0) {
     problems.push('audio.bgm: use either "file" or "synth", not both');
   }
+  const bgmSynth = ir.audio?.bgm?.synth;
+  if (bgmSynth !== void 0 && !BGM_SYNTHS.includes(bgmSynth)) {
+    problems.push(`audio.bgm.synth: unknown synth "${bgmSynth}" \u2014 valid: ${BGM_SYNTHS.join(", ")}`);
+  }
   if (problems.length > 0) throw new SceneValidationError(problems);
 }
 var TRANSITIONS = ["cut", "crossfade"];
@@ -1208,6 +1235,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);
 }
@@ -2881,12 +2916,32 @@ function motionOp(name, target, opts = {}) {
 
 // ../core/src/audio.ts
 var SFX_DURATION = {
+  // transition
   whoosh: 0.35,
-  pop: 0.12,
-  tick: 0.03,
+  swish: 0.32,
   rise: 0.5,
+  riser: 0.85,
+  warp: 0.5,
+  // ui
+  tick: 0.03,
+  click: 0.05,
+  blip: 0.1,
+  pop: 0.12,
+  select: 0.18,
+  // impact
+  thud: 0.25,
+  boom: 0.6,
+  knock: 0.14,
+  // positive
+  chime: 0.7,
+  ding: 0.5,
+  coin: 0.3,
+  sparkle: 0.6,
   shimmer: 0.9,
-  thud: 0.25
+  success: 0.6,
+  // alert
+  zap: 0.22,
+  error: 0.4
 };
 var FILE_CUE_DURATION = 0.4;
 function collectClipAudio(ir, duration, warnings) {
@@ -2946,7 +3001,11 @@ function resolveAudioPlan(compiled) {
       fadeIn: cue.fadeIn ?? 0,
       fadeOut: cue.fadeOut ?? 0,
       pan: cue.pan ?? 0,
-      source: cue.sfx ? { kind: "sfx", name: cue.sfx, params: cue.params ?? {} } : { kind: "file", path: cue.file }
+      source: cue.sfx ? (
+        // auto-vary: default the seed to the cue's order so repeated sfx differ
+        // (pitch/texture); an explicit params.seed always wins.
+        { kind: "sfx", name: cue.sfx, params: { seed: index, ...cue.params } }
+      ) : { kind: "file", path: cue.file }
     });
   }
   cues.sort((a, b) => a.t - b.t);
@@ -3026,7 +3085,11 @@ function resolveCompositionAudioPlan(comp) {
       fadeIn: cue.fadeIn ?? 0,
       fadeOut: cue.fadeOut ?? 0,
       pan: cue.pan ?? 0,
-      source: cue.sfx ? { kind: "sfx", name: cue.sfx, params: cue.params ?? {} } : { kind: "file", path: cue.file }
+      source: cue.sfx ? (
+        // auto-vary: default the seed to the cue's order so repeated sfx differ
+        // (pitch/texture); an explicit params.seed always wins.
+        { kind: "sfx", name: cue.sfx, params: { seed: index, ...cue.params } }
+      ) : { kind: "file", path: cue.file }
     });
   }
   if (!audio?.bgm && cues.length === 0 && clipAudio.length === 0) return null;
@@ -3585,6 +3648,7 @@ function sketchToTimeline(sketch, nodeIds) {
   return par(...steps);
 }
 export {
+  BGM_SYNTHS,
   CAMERA_ID,
   CAMERA_PROPS2 as CAMERA_PROPS,
   CHARACTER_PRESET_NAMES,
@@ -3600,8 +3664,10 @@ export {
   PRESET_NAMES,
   PROPS_BY_TYPE,
   SFX_DURATION,
+  SFX_NAMES,
   SceneValidationError,
   beat,
+  cameraFit,
   cameraMatrix,
   cameraTo,
   characterPreset,

package/dist/labels.js

@@ -1,6 +1,30 @@
 #!/usr/bin/env tsx
 
 // ../core/src/ir.ts
+var SFX_NAMES = [
+  "whoosh",
+  "swish",
+  "rise",
+  "riser",
+  "warp",
+  "tick",
+  "click",
+  "blip",
+  "pop",
+  "select",
+  "thud",
+  "boom",
+  "knock",
+  "chime",
+  "ding",
+  "coin",
+  "sparkle",
+  "shimmer",
+  "success",
+  "zap",
+  "error"
+];
+var BGM_SYNTHS = ["ambient-pad", "lofi", "pulse", "tension", "uplift"];
 var DEFAULT_TO_DURATION = 0.5;
 var DEFAULT_TWEEN_DURATION = 0.5;
 var DEFAULT_MOTIONPATH_DURATION = 1;
@@ -650,7 +674,6 @@ function validateScene(ir) {
       }
     }
   }
-  const SFX_NAMES = ["whoosh", "pop", "tick", "rise", "shimmer", "thud"];
   for (const [i, cue] of (ir.audio?.cues ?? []).entries()) {
     if (typeof cue.at === "string" && !labels.has(cue.at)) {
       problems.push(
@@ -686,6 +709,10 @@ function validateScene(ir) {
   if (ir.audio?.bgm?.file !== void 0 && ir.audio.bgm.synth !== void 0) {
     problems.push('audio.bgm: use either "file" or "synth", not both');
   }
+  const bgmSynth = ir.audio?.bgm?.synth;
+  if (bgmSynth !== void 0 && !BGM_SYNTHS.includes(bgmSynth)) {
+    problems.push(`audio.bgm.synth: unknown synth "${bgmSynth}" \u2014 valid: ${BGM_SYNTHS.join(", ")}`);
+  }
   if (problems.length > 0) throw new SceneValidationError(problems);
 }
 

package/dist/types/audio.d.ts

@@ -8,7 +8,7 @@
  */
 import type { CompiledScene } from "./compile.js";
 import type { CompiledComposition } from "./composeComposition.js";
-import type { SfxName } from "./ir.js";
+import type { BgmSynth, SfxName } from "./ir.js";
 /** Nominal cue lengths (s) for duck-window math; file cues use a default. */
 export declare const SFX_DURATION: Record<SfxName, number>;
 export interface ResolvedCue {
@@ -55,7 +55,7 @@ export interface AudioPlan {
             path: string;
         } | {
             kind: "synth";
-            name: "ambient-pad";
+            name: BgmSynth;
         };
         gain: number;
         fadeIn: number;

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/dist/types/ir.d.ts

@@ -412,7 +412,20 @@ export interface BehaviorIR {
         };
     };
 }
-export type SfxName = "whoosh" | "pop" | "tick" | "rise" | "shimmer" | "thud";
+/**
+ * The procedural sfx palette — the single source of truth (the type, validation,
+ * and the render-cli synth recipes all key off this). Grouped by use:
+ *   transition: whoosh swish rise riser warp   · ui: tick click blip pop select
+ *   impact: thud boom knock   · positive: chime ding coin sparkle shimmer success
+ *   alert: zap error
+ * Every cue's pitch/texture varies with its `seed` (auto-seeded by cue order), so
+ * repeated cues sound different; `params.pitch` is an explicit multiplier.
+ */
+export declare const SFX_NAMES: readonly ["whoosh", "swish", "rise", "riser", "warp", "tick", "click", "blip", "pop", "select", "thud", "boom", "knock", "chime", "ding", "coin", "sparkle", "shimmer", "success", "zap", "error"];
+export type SfxName = (typeof SFX_NAMES)[number];
+/** Synthesized background-music beds (license-free). */
+export declare const BGM_SYNTHS: readonly ["ambient-pad", "lofi", "pulse", "tension", "uplift"];
+export type BgmSynth = (typeof BGM_SYNTHS)[number];
 export interface AudioCueIR {
     /** Anchor: a timeline label (the step's start) or absolute seconds. */
     at: string | number;
@@ -430,14 +443,18 @@ export interface AudioCueIR {
     fadeOut?: number;
     /** Stereo balance: -1 full left, 0 centre (default), +1 full right. */
     pan?: number;
-    /** Synth parameter overrides (seed, duration, …) — numbers only. */
+    /**
+     * Synth parameter overrides — numbers only. `seed` varies pitch/texture
+     * (defaults to the cue's order so repeats differ); `pitch` is an explicit
+     * frequency multiplier (1 = unchanged, 2 = an octave up); `gainDb` trims level.
+     */
     params?: Record<string, number>;
 }
 export interface AudioIR {
     bgm?: {
         file?: string;
-        /** License-free synthesized bed. */
-        synth?: "ambient-pad";
+        /** License-free synthesized bed (see {@link BGM_SYNTHS}). */
+        synth?: BgmSynth;
         gain?: number;
         fadeIn?: number;
         fadeOut?: number;

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
@@ -542,12 +558,28 @@ audio: {
 }
 ```
 
-Procedural sfx names: `whoosh` `pop` `tick` `rise` `shimmer` `thud` (deterministic,
-seedable via `params: { seed }`). Exactly one of `sfx`/`file` per cue.
-**Mixing**: any cue takes `fadeIn`/`fadeOut` (seconds) and `pan` (-1 left … 0 centre …
-+1 right). A `video` clip's audio takes `fadeIn` and `pan` too (clip fade-out isn't
-supported yet — a clip has no fixed length in the plan). The bed auto-ducks under cues
-(`bgm.duck`).
+**Procedural sfx palette** (deterministic; exactly one of `sfx`/`file` per cue):
+
+| group | names |
+| --- | --- |
+| transition | `whoosh` `swish` `rise` `riser` `warp` |
+| ui | `tick` `click` `blip` `pop` `select` |
+| impact | `thud` `boom` `knock` |
+| positive | `chime` `ding` `coin` `sparkle` `shimmer` `success` |
+| alert | `zap` `error` |
+
+**Variation — repeats don't sound the same.** Each cue's `seed` shifts the sound's
+PITCH (a musical step) and texture, and it **defaults to the cue's order**, so a run of
+the same sfx becomes a little phrase instead of a stuck note — no setup needed. Override
+explicitly with `params`: `{ sfx: "blip", params: { seed: 4 } }` (pick the variant) or
+`{ sfx: "tick", params: { pitch: 1.5 } }` (an explicit frequency multiplier; `2` = octave
+up). `params.gainDb` trims a single hit.
+
+**bgm beds** (`bgm.synth`): `ambient-pad` `lofi` `pulse` `tension` `uplift` — or
+`bgm.file` for your own. **Mixing**: any cue takes `fadeIn`/`fadeOut` (seconds) and `pan`
+(-1 left … 0 centre … +1 right). A `video` clip's audio takes `fadeIn` and `pan` too
+(clip fade-out isn't supported yet). The bed auto-ducks under cues (`bgm.duck`). See
+`examples/scenes/sfx-showcase.ts` to audition the whole palette.
 
 ## Rules
 

package/package.json

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