reframe-video 0.6.34 → 0.6.39

package/guides/edsl-guide.md

@@ -135,6 +135,16 @@ them with normal TS (`Object.fromEntries`, `.map`) for data-driven scenes.
   `curviness` shapes the path: `1` smooth (default), `0` sharp corners, `>1` loopier.
 - `wait(seconds, label?)` — hold; the optional `label` names the hold so audio
   cues and overlay retiming can address it.
+- `beat(name, opts, children)` — a named, retimable, reorderable span (the unit
+  humans/AI revise; its `name` is a stable overlay address). `opts`: `parallel`,
+  `at` (absolute start — a NUMBER, or a **label string to anchor to**), `gap`,
+  `scale`/`duration` (time-stretch), `order` (reorder within a `seq`), `nodes`.
+  **Label anchor**: `beat("caption", { at: "shot-2" }, [...])` starts the beat at
+  the `shot-2` label's time (with `gap` as the offset), so a title/lower-third/
+  caption laid over a montage stays locked to its shot when the cut is retimed
+  (via an overlay or AI regen) — the same retime-survival `audio.cues` get. Put
+  anchored beats in a `par` branch (an overlay layer), not inside a sequential
+  flow. See `examples/scenes/media-story.ts`.
 
 Eases: `linear`, `easeIn/Out/InOutQuad`, `easeIn/Out/InOutCubic`,
 `easeIn/Out/InOutQuart`, `easeIn/Out/InOutExpo`, or `{ cubicBezier: [x1,y1,x2,y2] }`.
@@ -421,6 +431,37 @@ scene({ size, nodes: [...m.nodes, ...titles], timeline: par(m.timeline, titleTra
 - Seeded + pure (same `(shots, opts)` → identical IR). Note: image/video sources do
   not render in `reframe player` / artifacts — montage ships as mp4. See
   `examples/scenes/video-montage.ts`.
+- **Assemble from files**: `reframe assemble <media...> [-o name] [--title "…"]
+  [--bgm <synth>] [--hold s] [--seed N]` probes each clip's real duration (so a
+  video shot's `hold` = its actual length, never a freeze) and scaffolds an editable
+  scene `.ts` wiring `photoMontage` + an optional `title` + a bed. The probed
+  numbers are baked in, so the emitted scene is a normal deterministic scene — edit
+  it (reorder, retime, swap a `src`), then `reframe render` it.
+
+## Titles & lower-thirds (`title` / `lowerThird`)
+
+The motion-graphic overlay vocabulary for a media piece — generators that return
+`{ nodes, timeline }` to compose over a montage (or anything). Stable ids so overlays
+address them; pure + deterministic.
+
+- `title({ text, id?, x?, y?, fontSize?, fontWeight?, fill?, letterSpacing?,
+  entrance?, exit?, speed?, seed?, hold? })` → `{ nodes, timeline, block }`. A kinetic
+  headline built on `splitText` + `textIn` (entrance presets: `cascade` `rise`
+  `bounce` `typewriter` `assemble` `decode`). Set `exit` (a `textOut` preset) and it
+  plays in, holds `hold`s, then exits. Glyph ids `${id}-${i}`; labels `${id}-in` /
+  `${id}-out`. `block` is returned so you can add `textLoop` behaviors or extra tweens.
+- `lowerThird({ name, role?, id?, x?, y?, accent?, fill?, subFill?, fontSize?, hold? })`
+  → `{ nodes, timeline }`. A name/role strap: an accent bar grows in, the text slides +
+  fades. Ids `${id}` (group) / `${id}-bar` / `${id}-name` / `${id}-role`; labels
+  `${id}-in` / `${id}-out`. Defaults to a bottom-left title-safe position.
+
+```ts
+const ttl = title({ text: "OUR YEAR", id: "ttl", x: 960, y: 540, fontSize: 132, entrance: "rise", exit: "dissolve", hold: 1.6 });
+const lt  = lowerThird({ name: "Nantes, France", role: "spring 2026", id: "lt" });
+// nodes:    [...m.nodes, ...ttl.nodes, ...lt.nodes]
+// timeline: par(m.timeline, ttl.timeline, seq(wait(6.6), lt.timeline))
+```
+See `examples/scenes/media-story.ts`.
 
 ## Video clips (`video`)
 
@@ -437,6 +478,9 @@ tween("clip", { scale: 1.08 }, { duration: 5 })  // transform composes with play
   `fit` (`"cover"` like the image node), `start` (scene-time playback begins), `rate`
   (speed), `clipStart` (source in-point s), `volume` (clip-audio gain, default 1; `0` mutes).
   Transform/opacity/effects compose as usual.
+- **`start` can be a label** (not just a number): `start: "shot-2"` anchors playback to that
+  timeline label's time (like `beat.at`), so the clip **ripples** when its shot is retimed (by an
+  overlay or AI regen) instead of desyncing. `photoMontage` does this automatically for video shots.
 - **Deterministic by frame extraction**: render-cli runs `ffmpeg -vf fps=<sceneFps>` to pull
   the clip's frames, and the renderer draws frame `round(t·fps)` — no live `<video>` seek, so
   it stays byte-identical (same machine).
@@ -506,6 +550,20 @@ vector frame (bezel, rounded body, phone notch / dynamic island, browser chrome)
   (overlay/regen addresses) — keep `id` across rewrites.
 - It's one node: animate the device group for the float/entrance (`tween`/
   `motionPath` its `x`/`y`/`scale`/`rotation`, `oscillate` for an idle drift).
+- **Premium by default** — `material:"premium"` (the default) gives a gradient
+  body, an ambient screen glow, a soft contact shadow and (glass) a sheen; the
+  `style` knob picks `"glass"` (realistic glass/metal, default) or `"neon"` (flat
+  body + additive accent edge-glow, graphic punch). `material:"flat"` opts back to
+  clean solid fills. All of this is purely cosmetic — the screen rect, the clip,
+  and the stable ids are identical across materials/styles, so `deviceScreen`
+  coords and existing `content`/overlays are unaffected.
+- **Auto-varied per instance** — each device's look (bezel, corner, glare angle,
+  neon hue) is derived deterministically from its `id`, so two devices differ
+  while staying on-model. Pass `seed` to pin or explore a variation; same `seed`
+  → identical, different `seed` → same family. Reproducible (no `Math.random`).
+- `notch?: "island" | "notch" | "punch" | "none"` selects the phone front-camera
+  treatment (default `"island"` — keep it explicit for an iOS vs Android read).
+- See `examples/scenes/device-gallery.ts` for glass/neon + seed variation.
 
 ```ts
 // a phone floating centre, a chat bubble inside the screen:

package/guides/regen-contract.md

@@ -27,3 +27,17 @@ each joint is `${id}-${jointName}` (e.g. `hero-armUpperR`) and its bone art is
 joint `name`s** for any character/device that survives the redesign — overlay
 edits (a retimed wave, a nudged limb angle) reference those exact ids. Renaming a
 joint orphans the edit, exactly like renaming a hand-authored node id.
+
+## Tooling
+
+Three read-only commands make the address namespace queryable and the contract
+checkable (no render):
+
+- `reframe manifest <scene> [--json]` — list every editable address (nodes +
+  their editable/animated props, states, timeline labels with patchable params,
+  beats, behaviors). Read it before patching so you target real, stable addresses.
+- `reframe lint <scene> [--strict]` — flag motion with no `label` (timing an
+  overlay can't reach and a regen can silently drop) + a `motionAddressableRatio`.
+- `reframe verify-overlay <base> <overlay>...` — compose the overlay onto a base
+  and report applied vs orphaned. Run it against the regenerated base to prove
+  every edit survived; it exits non-zero if any address broke.

package/package.json

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

package/skills/reframe/SKILL.md

@@ -72,8 +72,34 @@ to handle explicitly:
   mask (update the scene AND remove/update the superseded overlay entry) and
   tell them why.
 
+Addressability tooling (read-only, no render — use it when editing):
+
+- `npx -y reframe-video manifest <scene> [--json]` — list the scene's editable
+  surface (every node + its editable/animated props, states, timeline labels
+  with patchable params, beats, behaviors, each with its overlay address). Read
+  this BEFORE patching so you target real, stable addresses instead of guessing.
+- `npx -y reframe-video lint <scene> [--strict]` — flag motion with no `label`
+  (timing a later overlay can't reach, and a regen can silently drop) plus a
+  `motionAddressableRatio`. When authoring motion the user may want to tweak,
+  give the step a stable `label`.
+- `npx -y reframe-video verify-overlay <base> <overlay>... ` — after you rewrite
+  a base that has overlays, run this to confirm every edit still applies (it
+  reports orphans and exits non-zero if any address broke). The regen-survival
+  check, without a full render.
+
 ## Other capabilities
 
+- **Assemble media → scene**: when the user hands you images/videos for a piece,
+  `npx -y reframe-video assemble <media...> [-o name] [--title "…"] [--bgm <synth>]`
+  probes each clip's real duration and scaffolds an editable montage scene `.ts`
+  (clip-aware holds, so a short clip never freezes) wiring `photoMontage` + an
+  optional `title` + a bed. Then edit the `.ts` (reorder shots, retime, swap a
+  `src`) and `render` it. For motion-graphic overlays use the `title()` (kinetic
+  headline) and `lowerThird()` (name/role strap) generators — both return
+  `{ nodes, timeline }` you compose over the montage; see the guide. **Anchor an
+  overlay beat to a shot label** — `beat("cap", { at: "shot-2" }, [lt.timeline])`
+  in a `par` branch — so the caption stays synced to its shot if the cut is
+  retimed (don't pin it to a fixed `wait`).
 - **Batch**: `npx -y reframe-video batch scene.ts data.json` — one mp4 per
   data row; row keys are overlay addresses (`nodes.<id>.<prop>`,
   `timeline.<label>.duration`, ...). CSV works too (headers = addresses).