reframe-video 0.6.11 → 0.6.13

package/dist/index.js

@@ -358,7 +358,7 @@ var PROPS_BY_TYPE = {
   rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
   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"],
+  text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "prefix", "suffix", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
   image: [...COMMON_PROPS, "src", "width", "height", "fit"],
   video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
@@ -1032,6 +1032,38 @@ function dropShadow(color, blur = 24, x = 0, y = 12) {
   return { shadowColor: color, shadowBlur: blur, shadowX: x, shadowY: y };
 }
 
+// ../core/src/layout.ts
+function row(count, opts = {}) {
+  if (count <= 0) return [];
+  const center = opts.center ?? 0;
+  if (count === 1) return [center];
+  if (opts.span !== void 0) {
+    const start2 = center - opts.span / 2;
+    const pitch2 = opts.span / (count - 1);
+    return Array.from({ length: count }, (_, i) => start2 + i * pitch2);
+  }
+  const iw = opts.itemWidth ?? 0;
+  const gap = opts.gap ?? 0;
+  const pitch = iw + gap;
+  const total = count * iw + (count - 1) * gap;
+  const start = center - total / 2 + iw / 2;
+  return Array.from({ length: count }, (_, i) => start + i * pitch);
+}
+var column = row;
+function grid(rows, cols, opts = {}) {
+  const axis = (center, gap, item, span) => ({
+    center,
+    ...gap !== void 0 ? { gap } : {},
+    ...item !== void 0 ? { itemWidth: item } : {},
+    ...span !== void 0 ? { span } : {}
+  });
+  const xs = row(cols, axis(opts.center?.x ?? 0, opts.gapX, opts.cellW, opts.spanX));
+  const ys = row(rows, axis(opts.center?.y ?? 0, opts.gapY, opts.cellH, opts.spanY));
+  const out = [];
+  for (let r = 0; r < rows; r++) for (let c = 0; c < cols; c++) out.push({ x: xs[c], y: ys[r] });
+  return out;
+}
+
 // ../core/src/montage.ts
 var VIDEO_EXT = /\.(mp4|mov|webm|m4v|mkv)$/i;
 var isVideoSrc = (src) => VIDEO_EXT.test(src);
@@ -3345,12 +3377,14 @@ function evaluate(compiled, t) {
           0,
           Math.round(num(id, "contentDecimals", node.props.contentDecimals ?? 0))
         );
+        const body = typeof raw === "number" ? formatNumber(raw, decimals, node.props.contentThousands === true) : raw;
         ops.push({
           type: "text",
           id,
           transform: projDraw(matrix, 0, 0),
           opacity,
-          content: typeof raw === "number" ? formatNumber(raw, decimals, node.props.contentThousands === true) : raw,
+          // static affixes wrap the (possibly counting-up) body; absent ⇒ body unchanged
+          content: (node.props.prefix ?? "") + body + (node.props.suffix ?? ""),
           fontFamily: str(id, "fontFamily", node.props.fontFamily),
           fontSize: num(id, "fontSize", node.props.fontSize),
           fontWeight: num(id, "fontWeight", node.props.fontWeight ?? 400),
@@ -3486,6 +3520,7 @@ export {
   characterPreset,
   collectImageSrcs,
   collectVideoSrcs,
+  column,
   compileComposition,
   compileScene,
   composeScene,
@@ -3507,6 +3542,7 @@ export {
   figure,
   formatComposeReport,
   glow,
+  grid,
   group,
   humanoid,
   ikReach,
@@ -3536,6 +3572,7 @@ export {
   resolveEase,
   rig,
   rigPose,
+  row,
   sampleBehavior,
   sampleProp,
   scene,

package/dist/labels.js

@@ -342,7 +342,7 @@ var PROPS_BY_TYPE = {
   rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
   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"],
+  text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "prefix", "suffix", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
   image: [...COMMON_PROPS, "src", "width", "height", "fit"],
   video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],

package/dist/trace-cli.js

@@ -12,7 +12,7 @@ var PROPS_BY_TYPE = {
   rect: [...COMMON_PROPS, "width", "height", "fill", "stroke", "strokeWidth", "radius"],
   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"],
+  text: [...COMMON_PROPS, "content", "contentDecimals", "contentThousands", "prefix", "suffix", "fontFamily", "fontSize", "fontWeight", "fill", "letterSpacing"],
   image: [...COMMON_PROPS, "src", "width", "height", "fit"],
   video: [...COMMON_PROPS, "src", "width", "height", "fit", "start", "rate", "clipStart", "volume"],
   path: [...COMMON_PROPS, "d", "fill", "stroke", "strokeWidth", "progress", "originX", "originY"],
@@ -525,7 +525,7 @@ var INPLACE_RATIO = 0.3;
 var mean2 = (xs) => xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0;
 function backgroundLevel(diff) {
   const flat = [];
-  for (const row of diff) for (const v of row) flat.push(v);
+  for (const row2 of diff) for (const v of row2) flat.push(v);
   if (flat.length === 0) return 0;
   flat.sort((a, b) => a - b);
   return flat[Math.floor(flat.length / 2)];

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 { row, column, grid, type RowOpts, type GridOpts } from "./layout.js";
 export { photoMontage, videoMontage, 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";

package/dist/types/ir.d.ts

@@ -139,6 +139,11 @@ export interface TextProps extends BaseProps {
     contentDecimals?: number;
     /** Group the integer part with thousands separators (e.g. 35,786). */
     contentThousands?: boolean;
+    /** Static affixes wrapped around the rendered content — so a count-up can read
+     *  "$2.4M" or "+32%" from ONE node (prefix `"$"`, suffix `"M"`) instead of three
+     *  hand-positioned ones. Absent ⇒ no change. */
+    prefix?: string;
+    suffix?: string;
     fontFamily: string;
     fontSize: number;
     fontWeight?: number;

package/dist/types/layout.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Layout helpers — pure coordinate math for the common "evenly space N things"
+ * jobs (a row of cards, a grid of tiles) so authors don't hand-roll a `cx(i)`
+ * every time. They return coordinates you spread into node `x`/`y`; no nodes,
+ * no renderer involvement — authoring sugar only. Deterministic.
+ *
+ *   const xs = row(3, { center: 960, gap: 60, itemWidth: 440 });
+ *   xs.map((x, i) => rect({ id: `card-${i}`, x, y: 540, ... }));
+ */
+export interface RowOpts {
+    /** Centre of the row/column (default 0). */
+    center?: number;
+    /** Gap between adjacent items, paired with `itemWidth` (packed layout). */
+    gap?: number;
+    /** Item extent along the axis, paired with `gap` (packed layout). */
+    itemWidth?: number;
+    /** Alternative to gap+itemWidth: spread the item CENTRES evenly across this span. */
+    span?: number;
+}
+/** N evenly-spaced positions along one axis, centred on `center`. Give either
+ *  `span` (spread centres across it) or `gap`+`itemWidth` (pack fixed-width items). */
+export declare function row(count: number, opts?: RowOpts): number[];
+/** N evenly-spaced positions along the vertical axis — `row` for the y axis. */
+export declare const column: typeof row;
+export interface GridOpts {
+    center?: {
+        x: number;
+        y: number;
+    };
+    gapX?: number;
+    gapY?: number;
+    cellW?: number;
+    cellH?: number;
+    /** Alternatives to gap+cell: spread cell centres across these spans. */
+    spanX?: number;
+    spanY?: number;
+}
+/** `rows × cols` cell centres in row-major order, centred on `center`. */
+export declare function grid(rows: number, cols: number, opts?: GridOpts): {
+    x: number;
+    y: number;
+}[];

package/guides/directing-guide.md

@@ -0,0 +1,96 @@
+# reframe directing guide — high-end, reference-heavy pieces
+
+Read this (after the syntax guide, `reframe guide`) when the ask is a CINEMATIC or
+REFERENCE-FAITHFUL piece — a product teaser, a UI/session reproduction, a title
+sequence, a data story — not a simple lower-third or KPI card (those you just write).
+Simple jobs render first-try; the ceiling needs a process. This is that process.
+
+## What to get from the user (before writing anything)
+
+Ask for / confirm these — vague prompts are why these pieces take many rounds:
+
+- **Concept** in one line ("a faithful Claude Code session that builds a logo", "an app
+  that goes viral, everywhere").
+- **References** — screenshots / a reference video / pasted real content (terminal output,
+  copy, data). For fidelity work, the reference IS the spec. Save them to disk so you can
+  `diff` against them.
+- **Brand** — exact colors (hex), the wordmark, the font feel.
+- **Format** — length (~10–20s is a good ceiling clip), aspect (16:9 / 9:16), with or
+  without sound.
+- **Tone** — "Apple teaser" (slow, premium, lots of negative space) vs "faithful UI sim"
+  (exact, dense) vs "kinetic/energetic". This sets pacing and camera.
+
+## The loop
+
+### 1. Storyboard the beats FIRST (structure, not a flat timeline)
+
+Name the acts with `beat("...", {}, [ ... ])` before animating. A beat is a labeled,
+retimable narrative unit; its label anchors audio and lets you restructure whole sections.
+A reliable arc: **setup → inciting beat → rising → climax → resolution.** Decide what each
+beat shows and how long, THEN fill in motion. (See `device-hero.ts`: `beat("ki"/"seung"/
+"jeon"/"gyeol", …)` — entrance → it-takes-off → everywhere → resolve.)
+
+### 2. Match references with `diff` (stop eyeballing)
+
+Reproducing a screenshot pixel-faithfully is the hardest part. Use the tool:
+
+```
+reframe diff ref.png --mode grid            # labelled 100px grid over the screenshot → read coords, place nodes
+reframe diff ref.png scene.ts --mode side   # reference | your render, side by side
+reframe diff ref.png scene.ts --mode diff   # absolute difference — bright where you're off
+reframe diff ref.png scene.ts --mode blend  # 50% overlay — spot drift
+```
+
+Loop: `--mode grid` to measure → write the node tree → `--mode side`/`diff` to compare →
+fix coordinates/sizes/colors → repeat until faithful. Pick the frame with `--t <sec>`.
+
+### 3. Apply the cinematic-craft checklist
+
+These are what make a piece read as premium, not a slideshow. Patterns proven in the
+flagship scenes — reuse the technique, vary the content:
+
+- **Camera moves with the story.** Push in on each beat: a `cameraTo(...)` running in `par`
+  with the beat's content. Frame the detail that matters, pull back to resolve. (See
+  `terminal-claude.ts` helpers `cam()`/`scroll()`/`show()` — focus + scroll + reveal as
+  parameterized eased moves.)
+- **Curved entrances, not straight slides.** A hero enters on a `motionPath` arc with
+  `easeOutBack` (overshoot, then settle). (`device-hero.ts` `motionPath("phone-cam", [[…]],
+  { ease: "easeOutBack" })`.)
+- **Fake depth.** Layer a backdrop of many faint concentric ellipses (a smooth glow, no hard
+  edge) + a spotlight + a cast shadow that tracks the hero + an impact ring on landing.
+  (`device-hero.ts` backdrop/spot/shadow/ring rig.) Or use real depth: `camera.perspective`
+  + per-node `z` (see the syntax guide's "Depth & perspective").
+- **Layered idle motion.** Nothing should sit perfectly still. `oscillate` a few nodes at
+  DIFFERENT frequencies (slow float, slower tilt, a fast accent) for life during holds.
+- **Sound on the beats.** `scene.audio` cues anchor to your beat/timeline labels, so they
+  survive retiming: `{ at: "land", file: "bong_001.ogg" }`, `{ at: "viral", offset: 0.4,
+  sfx: "pop" }`. An `ambient-pad` bgm with `duck` under the hits. Quote `reframe labels` to
+  see exact seconds.
+
+### 4. Verify objectively (don't argue about "more dynamic")
+
+- `reframe labels scene.ts` — every label → exact seconds. The timing source for audio + a
+  sanity check that beats land when you think.
+- `reframe motion out.mp4` — speeds, static fraction, oscillation rhythm, spikes. A vague
+  note like "make it punchier" becomes measurable: compare `meanSpeed`/`peakSpeed` before
+  and after; `staticFraction` too high = it drags.
+- `reframe trace ref.mp4 --apply scene.ts` — when you have a reference VIDEO (not image),
+  extract its timing/easing and re-apply it onto YOUR node ids. Borrow the motion, keep your
+  assets.
+
+### 5. Hand-tune via preview → overlay
+
+`reframe preview` to scrub, drag motionPath waypoints, and retime steps; export the overlay
+JSON and render with `--overlay`. Those nudges survive a later regeneration (stable
+addresses), so the human's polish isn't lost when you redo the base.
+
+## Pitfalls
+
+- Don't animate before the structure is right — fixing pacing after everything is keyframed
+  is painful. Beats first.
+- Reference fidelity is coordinates + color + type, mostly STATIC layout; get the held frame
+  matching with `diff` before adding motion.
+- Keep `id`s/labels stable across rewrites (see `reframe guide --regen`) so the user's
+  overlay edits survive.
+- It's still iterative. The tools cut the rounds; they don't remove the loop. Render, look,
+  adjust — the agent should render frames and read them, not guess.

package/guides/edsl-guide.md

@@ -4,6 +4,10 @@ You write a motion-graphics scene as **declarative data** using the reframe
 TypeScript eDSL. Your output is a single `.ts` file that default-exports a
 `scene({...})` call. Everything imports from `@reframe/core`.
 
+> `See examples/scenes/…` pointers below refer to the GitHub repo
+> (github.com/kiyeonjeon21/reframe), not the installed npm package — this guide is
+> self-contained; you don't need them to write a scene.
+
 ```ts
 import { scene, group, rect, ellipse, line, text,
          seq, par, stagger, to, tween, wait,
@@ -30,10 +34,13 @@ Factories return plain data. Every node needs a unique `id`.
 - `ellipse({ id, x, y, width, height, fill?, stroke?, strokeWidth?, ... })`
 - `line({ id, x1, y1, x2, y2, stroke, strokeWidth?, opacity?, progress? })` —
   `progress` 0..1 draws the line on (1 = full line).
-- `text({ id, x, y, content, contentDecimals?, fontFamily, fontSize, fontWeight?, fill?, letterSpacing?, ... })` —
+- `text({ id, x, y, content, contentDecimals?, contentThousands?, prefix?, suffix?, fontFamily, fontSize, fontWeight?, fill?, letterSpacing?, ... })` —
   `content` may be a number; numeric content interpolates (count-up) and renders
   via `toFixed(contentDecimals ?? 0)`. For a "8.2"-style label, set
-  `contentDecimals: 1`.
+  `contentDecimals: 1`; `contentThousands: true` groups the integer (35,786).
+  **`prefix`/`suffix`** wrap the value so a count-up reads `$2.4M` or `+32%` from
+  ONE node (`{ content: 2.4, contentDecimals: 1, prefix: "$", suffix: "M" }`) —
+  don't hand-position separate `$`/`%` nodes.
 - `path({ id, d, x, y, fill?, stroke?, strokeWidth?, progress?, originX?, originY?, opacity?, rotation?, scale?, anchor? })` —
   a true vector shape from an SVG path `d` string (crisp at any zoom; recolour by
   animating `fill`/`stroke`). `progress` 0..1 draws the stroke OUTLINE on (animate
@@ -63,6 +70,23 @@ Factories return plain data. Every node needs a unique `id`.
 Example: a bar that grows upward = `anchor: "bottom-left"` + animate `height`.
 Font: use `fontFamily: "Inter"` (weights 400/700/800 are available).
 
+### Layout helpers (evenly spacing things)
+
+Positions are absolute pixels. For a row of cards or a grid of tiles, use the
+layout helpers instead of hand-rolling the column math — they return coordinates
+you spread into `x`/`y`:
+
+```ts
+import { row, grid } from "@reframe/core";
+// 3 cards, 440px wide, 60px apart, centred on the frame:
+row(3, { center: 960, gap: 60, itemWidth: 440 }).map((x, i) =>
+  rect({ id: `card-${i}`, x, y: 540, width: 440, height: 300, anchor: "center", fill: "#1A1F2E" }));
+// or spread centres across a span: row(3, { center: 960, span: 900 })
+// grid(rows, cols, { center: {x,y}, gapX, gapY, cellW, cellH }) → { x, y }[] (row-major)
+```
+
+`column` is `row` for the y axis.
+
 ## States: declare looks, not motion
 
 Base props on nodes describe the **finished design**. A state is a sparse
@@ -98,7 +122,8 @@ them with normal TS (`Object.fromEntries`, `.map`) for data-driven scenes.
   later `tween` can chain from there. Use it for swoops/arcs/orbits — straight
   `tween`s on x and y can't curve. `closed: true` loops the waypoints (orbit).
   `curviness` shapes the path: `1` smooth (default), `0` sharp corners, `>1` loopier.
-- `wait(seconds)` — hold.
+- `wait(seconds, label?)` — hold; the optional `label` names the hold so audio
+  cues and overlay retiming can address it.
 
 Eases: `linear`, `easeIn/Out/InOutQuad`, `easeIn/Out/InOutCubic`,
 `easeIn/Out/InOutQuart`, `easeIn/Out/InOutExpo`, or `{ cubicBezier: [x1,y1,x2,y2] }`.

package/package.json

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