reframe-video 0.1.3 → 0.3.0

package/guides/edsl-guide.md

@@ -41,6 +41,12 @@ Factories return plain data. Every node needs a unique `id`.
   the art's centre (e.g. the viewBox centre) so `scale`/`rotation` happen about the
   middle. `d` is drawn in its own coords; `x`/`y` place that pivot. Classic logo
   reveal: a stroke path drawing on, then a fill path fading in over it.
+  **`d` is animatable (shape morph):** `tween(id, { d: otherShape }, …)` morphs
+  the path vertex-by-vertex (the Lottie-style shape tween) when both `d` strings
+  share the same command sequence and arg counts — author the two poses with the
+  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) —
@@ -82,13 +88,14 @@ them with normal TS (`Object.fromEntries`, `.map`) for data-driven scenes.
 - `to(stateName, opts)` — transition into a named state (see above).
 - `tween(nodeId, { prop: value, ... }, { duration, ease })` — low-level escape hatch
   for one node. Colors (`"#rrggbb"`) interpolate; numbers interpolate.
-- `motionPath(nodeId, [[x,y], ...], { duration, ease, autoRotate?, rotateOffset?, closed? })`
+- `motionPath(nodeId, [[x,y], ...], { duration, ease, curviness?, autoRotate?, rotateOffset?, closed? })`
   — drive a node's `x`/`y` along a smooth Catmull-Rom curve through the waypoints
   (parent-space coords). `autoRotate: true` banks the node along the path tangent
   (`rotateOffset` degrees if the art faces "up", e.g. `-90`). The node HOLDS at the
   final point after the path finishes (a positioning move, not a one-shot), so a
   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.
 
 Eases: `linear`, `easeIn/Out/InOutQuad`, `easeIn/Out/InOutCubic`,
@@ -114,6 +121,52 @@ bound — e.g. a pulse only during the hold:
 `oscillate("title", "scale", { amplitude: 0.04, frequency: 1.2 }, { from: 1.5, until: 3.5 })`.
 Omit the window to run for the whole scene.
 
+## Character rig (skeleton, poses, IK)
+
+A first-class, declarative character rig that **compiles to plain IR** (nested
+`group` joints + bone paths) — the character analog of `devicePreset`. It needs
+no new renderer concept, so overlays/preview/determinism all apply.
+
+- `humanoid({ id, x, y, scale, opacity?, color?, fill?, glow? })` → a NodeIR: a
+  ready upright body. Joints (stable ids `${id}-${name}`): `chest`, `head`,
+  `armUpperL/armLowerL`, `armUpperR/armLowerR`, `legUpperL/legLowerL`,
+  `legUpperR/legLowerR`. Drop it in `nodes`.
+- `rig(boneTree, opts)` → build your own skeleton. A `Bone` is
+  `{ name, at:[x,y], length?, width?, rotation?, shape?, children? }`. The joint
+  sits at the group origin; the bone extends **+Y at rotation 0**; a child's `at`
+  pivot is in the PARENT bone's local space (e.g. an elbow at `[0, upperLength]`).
+  Nested groups give forward kinematics — a child's rotation composes on its
+  parent's. Default bone = a bezier capsule (morphable); pass `shape` for custom art.
+- A **pose** is `{ jointName: angleDeg }` (0 = bone points down). Animate it:
+  - `poseTo(id, pose, { duration, ease, stagger? })` → a timeline step (a `par`
+    of rotation tweens). Sequence poses for wave/jump/run.
+  - `rigPose(id, pose)` → a `states` fragment, to transition with `to(state, …)`.
+- `ikReach(upper, lower, dx, dy, flip?)` → `[shoulderDeg, elbowDeg]` that place a
+  2-bone limb's tip at `(dx,dy)` relative to its shoulder joint (law of cosines;
+  clamps when out of reach). Feed the two angles into a pose.
+- Joint names are the **stable regen addresses** — never rename them across a
+  regen; each rig instance needs a distinct `id` (duplicates collide via scene
+  validation). Squash/stretch and expressions are per-bone `d` morphs (above),
+  composed on top of FK posing. Idle sway/breathing = `oscillate` on a joint.
+- `figure(opts)` — a **dressed** character (the styled sibling of `humanoid`):
+  same skeleton, but coloured flat-design shapes. `style: "clean"` (corporate-flat
+  / undraw register, the default) or `"cute"` (mascot); `palette` knobs
+  (`skin`/`hair`/`top`/`pants`/`shoe`/`accent`) re-skin it — for `clean` the top
+  follows `accent`, so `figure({ palette: { accent: "#3B82F6" } })` recolours the
+  whole figure; `face: false` makes it faceless. It exposes the humanoid joint
+  ids, so `characterPreset` / `ikReach` drive it unchanged. Use it as the
+  supporting actor in a product promo (gesturing at a `devicePreset`), not the hero.
+- `characterPreset(name, opts)` — a **seeded motion generator** for a `humanoid`
+  or `figure` rig (the character analog of `motionPreset`). Returns a composable `beat`;
+  drop it in the timeline: `seq(characterPreset("walk", { target: "hero", at:
+  [cx, cy], cycles: 4 }))`. Names: `walk`, `run`, `jump`, `dance`, `wave`,
+  `cheer`. Knobs: `target` (rig id), `energy` 0..1, `speed` (>0, divides
+  durations), `seed` (varies within the family), `cycles` (walk/run/dance),
+  `facing` (±1), `at: [x,y]` (the rig's scene position — needed for walk travel
+  & jump lift), `travel` (px/cycle, 0 = in place), `label` (unique beat name —
+  set it when the same preset is used more than once in a scene). Legs use
+  `ikReach`, arms FK; pure keyframes, so add continuous idle yourself with `oscillate`.
+
 ## Audio (optional)
 
 Label-anchored sound design — cues follow retiming and regeneration:

package/guides/regen-contract.md

@@ -16,3 +16,14 @@ source):
 When the contract is broken anyway, `composeScene` skips the affected edits
 and reports them as orphans with the known-ids list — loud, diagnosable,
 never a silent drop and never a render failure.
+
+## Generated subtrees (devicePreset, rig/humanoid)
+
+Generators emit nodes with deterministic ids under an instance prefix, and those
+ids are stable addresses too. For `devicePreset(name,{id})` the screen/content
+parts are `${id}-screen` / `${id}-content`. For `rig(...)` / `humanoid({id})`
+each joint is `${id}-${jointName}` (e.g. `hero-armUpperR`) and its bone art is
+`${id}-${jointName}-shape`. Across a regen, **keep the instance `id` and the
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reframe-video",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "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/preview/index.html

@@ -11,8 +11,11 @@
   #content { flex: 1; display: flex; min-height: 0; }
   #stage-wrap { flex: 1; display: flex; align-items: center; justify-content: center; min-width: 0; padding: 16px; }
   canvas { max-width: 100%; max-height: 100%; box-shadow: 0 4px 32px rgba(0,0,0,.5); }
-  #bar { display: flex; gap: 12px; align-items: center; padding: 12px 16px; background: #232329; }
-  #scrub { flex: 1; }
+  #bar { display: flex; gap: 8px; align-items: center; padding: 12px 16px; background: #232329; }
+  #scrub-wrap { flex: 1; position: relative; display: flex; align-items: center; }
+  #scrub { width: 100%; }
+  #loop-band { position: absolute; top: 50%; transform: translateY(-50%); height: 6px; background: rgba(125,154,255,.35); border-radius: 3px; pointer-events: none; display: none; }
+  button.on { background: #3a4a86; border-color: #7d9aff; color: #fff; }
   select, button, input[type=text], input[type=number] { background: #2e2e36; color: #ddd; border: 1px solid #444; border-radius: 4px; padding: 3px 8px; font: 12px system-ui; }
   input[type=number] { width: 64px; }
   input[type=color] { width: 40px; height: 22px; padding: 0; border: 1px solid #444; background: none; }
@@ -42,6 +45,42 @@
   #report details { color: #8a8a96; }
   #io { display: flex; gap: 6px; flex-wrap: wrap; margin-top: 8px; }
   #overlay-name { width: 100%; margin-bottom: 6px; box-sizing: border-box; }
+  .beat-group { margin: 4px 0 2px; border-left: 2px solid #3a4a86; padding-left: 6px; }
+  .beat-lane { padding: 1px 4px; border-radius: 3px; cursor: pointer; color: #b9c2da; font-size: 12px; }
+  .beat-lane:hover { background: #2a2a32; }
+  .beat-lane.selected { background: #31313c; color: #fff; }
+  .beat-lane.missing { color: #ff7b72; cursor: default; }
+  .beat-markers { color: #7d9aff; font-size: 11px; margin-top: 3px; opacity: 0.85; }
+  /* bottom timeline: scene bands (composition) or top-level beat bands (one scene) */
+  #comp-timeline { display: none; padding: 8px 16px 10px; background: #1f1f25; border-top: 1px solid #333; }
+  #comp-timeline.on { display: block; }
+  #comp-timeline .ct-title { color: #8a8a96; font-size: 11px; text-transform: uppercase; letter-spacing: 1px; margin-bottom: 6px; }
+  .ct-bandrow { display: flex; align-items: flex-start; }
+  .ct-bandrow .tk-label { padding-top: 4px; }
+  #comp-track { position: relative; flex: 1; min-width: 0; background: #16161b; border-radius: 6px; }
+  .ct-scene { position: absolute; background: #2a2a32; border: 1px solid #3a3a44; border-radius: 5px; cursor: pointer; overflow: hidden; box-sizing: border-box; padding: 4px 8px; white-space: nowrap; }
+  .ct-scene:hover { border-color: #7d9aff; }
+  .ct-scene.active { background: #31313c; border-color: #7d9aff; color: #fff; }
+  .ct-scene.beat { border-style: dashed; }
+  .ct-scene .ct-range { color: #8a8a96; font-size: 10px; margin-left: 6px; font-variant-numeric: tabular-nums; }
+  #ct-playhead { position: absolute; top: -2px; bottom: -2px; width: 2px; background: #ff4d00; pointer-events: none; }
+  /* node tracks (dope sheet): each node a lane, its motion segments as bars */
+  .tk-toggle { background: none; border: 1px solid #3a3a44; color: #8a8a96; font-size: 11px; border-radius: 4px; padding: 2px 8px; cursor: pointer; margin-top: 8px; }
+  .tk-toggle:hover { border-color: #7d9aff; color: #ddd; }
+  #comp-tracks { position: relative; margin-top: 6px; max-height: 150px; overflow-y: auto; display: none; }
+  #comp-tracks.on { display: block; }
+  .tk-row { display: flex; align-items: center; height: 18px; }
+  .tk-label { width: 120px; flex: none; color: #99a; font-size: 11px; padding: 0 6px; cursor: pointer; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; box-sizing: border-box; }
+  .tk-label:hover { color: #fff; }
+  .tk-row.selected .tk-label { color: #fff; font-weight: 600; }
+  .tk-lane { position: relative; flex: 1; height: 12px; background: #16161b; border-radius: 3px; }
+  .tk-bar { position: absolute; top: 1px; height: 10px; background: #3a4a86; border-radius: 2px; cursor: pointer; min-width: 3px; box-sizing: border-box; }
+  .tk-bar:hover { background: #7d9aff; }
+  .tk-bar.path { background: #b06a2a; }
+  .tk-bar.group { background: #4a4a58; }
+  .tk-bar.group:hover { background: #5e5e70; }
+  .tk-row.selected .tk-bar { background: #7d9aff; }
+  #tk-playhead { position: absolute; top: 0; bottom: 0; width: 2px; background: #ff4d00; pointer-events: none; }
 </style>
 </head>
 <body>
@@ -52,9 +91,23 @@
   <div id="bar">
     <select id="scene-select"></select>
     <button id="play">play</button>
-    <input id="scrub" type="range" min="0" max="1" step="0.001" value="0" />
+    <button id="play-all" title="play the whole composition across scenes" style="display:none">play all</button>
+    <button id="mark-in" title="set loop start to current time">[</button>
+    <button id="loop" title="loop the in/out range">loop</button>
+    <button id="mark-out" title="set loop end to current time">]</button>
+    <select id="speed" title="playback speed">
+      <option value="0.25">0.25×</option>
+      <option value="0.5">0.5×</option>
+      <option value="1" selected>1×</option>
+      <option value="2">2×</option>
+    </select>
+    <div id="scrub-wrap">
+      <div id="loop-band"></div>
+      <input id="scrub" type="range" min="0" max="1" step="0.001" value="0" />
+    </div>
     <span id="time">0.000 / 0.000</span>
   </div>
+  <div id="comp-timeline"></div>
   <script type="module" src="/src/main.ts"></script>
 </body>
 </html>