mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
feat(motion,runtime): wire the three craft capabilities to the video-authoring dev (#544)
Playwright, the taste-skill design bar, and hyperframes were all implemented — and each stopped one hop short of the hands doing video work: playwright reached only fe-qa/ux-qa, the design bar's web-UI dials actively pointed a video task at 'dense product UI -> motion 2-3', and hyperframes' agent-facing doctrine never reached any agent. Three wires: - vendor the official HyperFrames agent skills (hyperframes-core, -keyframes, -creative) under motion/skills/ at a pinned upstream commit (Apache-2.0, attribution headers; prose reflowed to house style, re-vendor note in each header); README and the dev video prompt block point at them - register the playwright MCP for a ux-dev spawned onto a source=video task (_is_video_authoring_spawn: fail-closed role/team/task-source probe) so the composition author can watch their HTML live in a real browser between renders — gating-only, agent-ux already bakes the browser; QA gating unchanged, be-qa/ordinary ux-dev still excluded - design bar video-mode override in the ux_ui team prompt: video tasks are films, the web dials do not apply — use the cinematography bar and the vendored doctrine instead Co-authored-by: Renn F <rennf93@users.noreply.github.com>
This commit is contained in:
Renzo F
@@ -0,0 +1,226 @@
|
||||
<!-- Vendored from https://github.com/heygen-com/hyperframes (skills/hyperframes-keyframes/SKILL.md @ 9d148d28, Apache-2.0).
|
||||
Authoring doctrine for the HyperFrames renderer the video sidecar runs. Re-vendor when bumping @hyperframes/producer, then run make reflow-docs (prose is reflowed to house style). -->
|
||||
|
||||
---
|
||||
name: hyperframes-keyframes description: > Use when a HyperFrames composition needs seek-safe 2D/3D keyframes, GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth, or `hyperframes keyframes` diagnostics. Don't use for broad scene strategy, brand design, media sourcing, captions, or general video planning.
|
||||
---
|
||||
|
||||
# HyperFrames Keyframes
|
||||
|
||||
Keyframes are a pose contract: visible states, continuous subject identity, seek-safe runtime, verified pixels.
|
||||
|
||||
Use `hyperframes-animation` for broad scene recipes. Use `hyperframes-cli` for full command docs. Use `references/keyframe-patterns.md` only when choosing implementation mechanisms, not visual style.
|
||||
|
||||
## Procedure
|
||||
|
||||
1. Identify the animated subject, visible states, final state, and runtime.
|
||||
2. Choose the smallest mechanism that proves the prompt. Read `references/keyframe-patterns.md` only if the mechanism is unclear.
|
||||
3. Author seek-safe keyframes in the declared runtime. Build synchronously and register the runtime instance.
|
||||
4. Verify with `hyperframes lint`, `hyperframes check`, `hyperframes keyframes`, one focused `--shot`, and snapshots at proof times.
|
||||
5. If proof fails, fix the source keyframes and rerun the smallest failing diagnostic before rendering.
|
||||
|
||||
## Contract
|
||||
|
||||
- Name the moving subject.
|
||||
- Name the poses needed to prove the intended motion, including the final state.
|
||||
- Keyframe visible channels, not hidden helper state.
|
||||
- Preserve object identity when continuity matters.
|
||||
- Crossfade only when the intended motion is replacement or dissolve.
|
||||
- Hold readable or semantic states long enough to see.
|
||||
- Final frame is part of the animation, not cleanup.
|
||||
- Do not reset to rest unless requested.
|
||||
- Do not end on black unless requested.
|
||||
- If editing a starter scene, preserve layout, copy, assets, colors, and final state unless asked to redesign.
|
||||
|
||||
## Runtime Rules
|
||||
|
||||
GSAP:
|
||||
|
||||
- build synchronously at page load
|
||||
- use `gsap.timeline({ paused: true })`
|
||||
- register as `window.__timelines[compositionId]`
|
||||
- registry key must match `data-composition-id`
|
||||
- do not call `tl.play()` for render-critical motion
|
||||
- keep repeats finite
|
||||
|
||||
CSS keyframes:
|
||||
|
||||
- finite duration and iteration count
|
||||
- deterministic delay
|
||||
- `animation-fill-mode: both`
|
||||
- use `data-start` when timing belongs to a clip
|
||||
|
||||
Anime.js:
|
||||
|
||||
- create synchronously
|
||||
- `autoplay: false`
|
||||
- finite duration and loops
|
||||
- push every instance to `window.__hfAnime`
|
||||
|
||||
WAAPI:
|
||||
|
||||
- finite `duration`
|
||||
- `fill: "both"`
|
||||
- deterministic construction
|
||||
- the text surface does not list WAAPI; verify with `--shot` (it seeks WAAPI) and snapshots
|
||||
|
||||
Never use for render-critical motion:
|
||||
|
||||
- `Date.now()`
|
||||
- `performance.now()`
|
||||
- unseeded `Math.random()`
|
||||
- hover/scroll triggers
|
||||
- timers
|
||||
- async-created timelines
|
||||
- unregistered `requestAnimationFrame`
|
||||
- infinite loops
|
||||
|
||||
## GSAP Skeleton
|
||||
|
||||
```js
|
||||
const root = document.querySelector("[data-composition-id]");
|
||||
const compositionId = root.dataset.compositionId;
|
||||
const tl = gsap.timeline({ paused: true });
|
||||
|
||||
tl.addLabel("state-a", 0);
|
||||
tl.to(".subject", {
|
||||
keyframes: [
|
||||
{ x: 0, opacity: 1, duration: 0.2 },
|
||||
{ x: 120, opacity: 1, duration: 0.4, ease: "power2.out" },
|
||||
{ x: 100, opacity: 1, duration: 0.2, ease: "power2.inOut" },
|
||||
],
|
||||
ease: "none",
|
||||
});
|
||||
|
||||
window.__timelines = window.__timelines || {};
|
||||
window.__timelines[compositionId] = tl;
|
||||
```
|
||||
|
||||
Use labels for semantic states. Use position parameters instead of chained delays. Use `immediateRender: false` for later `from()`/`fromTo()` tweens touching the same property.
|
||||
|
||||
## Keyframe Forms
|
||||
|
||||
- Array keyframes: pose ladder with per-step duration/ease.
|
||||
- Percentage keyframes: exact timing inside one tween.
|
||||
- Property arrays: compact multi-stop changes.
|
||||
- `ease: "none"` on the parent when each stop carries its own easing.
|
||||
- `easeEach` when every segment should share the same feel.
|
||||
|
||||
Do not copy numeric distances or timing from examples. Derive them from the actual composition geometry and duration.
|
||||
|
||||
For one subject moving between two boxes, prefer one continuous transform tween or FLIP. Split `x/y/scale` into multiple eased keyframes only when the viewer should feel distinct beats; every segment changes velocity and can read as a hitch.
|
||||
|
||||
## Channels
|
||||
|
||||
Prefer compositor/visual channels: `x/y/z`, `xPercent/yPercent`, `scale`, `rotationX/Y/Z`, `skew`, `transformOrigin`, `svgOrigin`, `opacity`, `autoAlpha`, `clip-path`, masks, CSS vars, SVG path/dash values, camera transforms, shader uniforms.
|
||||
|
||||
Avoid layout/lifecycle channels: `top/left/right/bottom`, `width/height`, `margin/padding`, `display`, `visibility`, late DOM creation, helper overlays doing subject motion.
|
||||
|
||||
For visibility changes, use `autoAlpha` on the registered seekable GSAP timeline, or a zero-duration `tl.set()` at an explicit boundary. Target only a non-clip element or a wrapper inside the clip; never target `.clip` itself. Never duration-tween raw `visibility`, and never tween `display`.
|
||||
|
||||
## Mechanism Choice
|
||||
|
||||
Choose the smallest mechanism that proves the prompt:
|
||||
|
||||
| Need | Mechanism |
|
||||
| ------------------------------------- | -------------------------------------------------- |
|
||||
| Same subject changes box or hierarchy | shared element / FLIP |
|
||||
| Subject travels a visible route | path travel |
|
||||
| Stroke grows or traces | stroke draw |
|
||||
| Shape becomes another shape | shape interpolation |
|
||||
| Reveal boundary is visible | clip, mask, or shader uniform |
|
||||
| Many items move with order | stagger / indexed delay |
|
||||
| Text itself moves | line, word, character, or band subdivision |
|
||||
| Surface bends, stretches, or crops | parent/child counter-transform |
|
||||
| UI has states | explicit state machine |
|
||||
| Scene has depth | DOM 3D, Three.js, or WebGL camera/object keyframes |
|
||||
|
||||
Mechanisms can combine, but each one must clarify the idea. Decoration is not proof.
|
||||
|
||||
## Timing
|
||||
|
||||
- Anticipation only when it clarifies cause or direction.
|
||||
- Acceleration leaves rest.
|
||||
- Peak proof shows the mechanism unmistakably.
|
||||
- Follow-through sells energy and direction.
|
||||
- Overshoot only when the subject should feel elastic or tactile.
|
||||
- Constant-speed path travel usually needs `ease: "none"`.
|
||||
- Discrete UI states usually need a sharp ease-out.
|
||||
- Repeated elements need ordered offsets, not identical timing.
|
||||
- Final lockups need longer holds than transition poses.
|
||||
- Smoothness means continuous velocity on the same subject.
|
||||
- Do not overlap tweens that write the same transform property unless the overlap is intentional and verified.
|
||||
- Avoid animating large `clip-path`/mask changes while the same hero surface is also scaling or traveling; use nested reveals after the main move settles.
|
||||
|
||||
## Text
|
||||
|
||||
Preserve line boxes, word spacing, readability, and final fit. If text moves internally, move the glyphs or masked bands, not only decorations around the text. Snapshot readable frames.
|
||||
|
||||
## SVG
|
||||
|
||||
For stroke growth prefer `DrawSVGPlugin`, then `stroke-dasharray`/`stroke-dashoffset`. For shape interpolation prefer `MorphSVGPlugin`; convert primitives to paths when needed and split complex silhouettes into simpler parts.
|
||||
|
||||
## 3D
|
||||
|
||||
Scale alone is fake depth. Use perspective on a stable parent, `transform-style: preserve-3d`, z travel, rotation, camera/world motion, occlusion, and layer order when objects cross.
|
||||
|
||||
Use one or two diagnostic angles that expose the depth relationship. If angled proof shows no depth crossing, improve z/camera/occlusion.
|
||||
|
||||
## Canvas / WebGL
|
||||
|
||||
Keyframe camera position, camera target, object transform, material opacity, shader uniforms, and postprocess intensity through deterministic state. Render from HyperFrames time. Use `--ghost` because marker boxes cannot see internal canvas motion.
|
||||
|
||||
## CLI Proof
|
||||
|
||||
```bash
|
||||
npx hyperframes lint
|
||||
npx hyperframes check
|
||||
npx hyperframes keyframes .
|
||||
npx hyperframes keyframes . --json
|
||||
npx hyperframes keyframes . --runtime all
|
||||
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --samples <n>
|
||||
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --layout strip --from <t0> --to <t1>
|
||||
npx hyperframes keyframes . --shot "<file>" --ghost --angle <angle>
|
||||
npx hyperframes snapshot . --at <times>
|
||||
```
|
||||
|
||||
Choose `<selector>` for the real animated subject. Choose `<times>` for first frame, proof poses, final-minus-hold, and exact final. Choose `<angle>` only when depth must be proven.
|
||||
|
||||
| Tool | Proves |
|
||||
| ---------------- | --------------------------------------------------------------------------------------------------- |
|
||||
| `keyframes` | targets, explicit stops, paths, traces, composed parent/child motion, CSS stops, Anime registration |
|
||||
| `--shot` | ghosts, route shape, time spacing, DOM 3D projection, focused selector proof |
|
||||
| `--layout strip` | in-place motion, overlaps, contact, subtle scale/opacity, text waves |
|
||||
| `--ghost` | canvas, WebGL, shader motion, rendered 3D |
|
||||
| `snapshot --at` | masks, text readability, full state, final lockup, black/reset tails |
|
||||
|
||||
If selector proof looks wrong:
|
||||
|
||||
1. rerun `--json`
|
||||
2. find the actual animated target
|
||||
3. shoot that target
|
||||
4. snapshot full frames
|
||||
5. trust painted pixels over logs
|
||||
|
||||
## Diagnostic Reading
|
||||
|
||||
`flat` means no explicit middle poses. `keyframes` means explicit stops exist. `motionPath` means a route exists. `trace` means multi-stroke drawing. `composed with` means child motion inherits parent motion.
|
||||
|
||||
Even ghost spacing means constant speed. Clustered ghosts mean slow-in or settle. Large gaps mean fast travel.
|
||||
|
||||
A helper-selector shot is not proof. An onion shot over a broken full frame is not proof.
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Failure | Fix |
|
||||
| ------------------ | ---------------------------------------------------------------------------------- |
|
||||
| endpoint-only | add middle poses, hold peak proof, rerun `--shot` |
|
||||
| identity break | keep one element alive, use shared source/final boxes, remove substitute crossfade |
|
||||
| fake 3D | add z/camera travel, occlusion, angled proof |
|
||||
| wrong final | add final hold, snapshot final-minus-hold and exact final |
|
||||
| unseekable runtime | pause autoplay, register instance, remove timers, build synchronously |
|
||||
| unreadable text | preserve line boxes, reduce displacement, add final hold, snapshot text frames |
|
||||
|
||||
## Done
|
||||
|
||||
Run `hyperframes lint`, `hyperframes check`, `hyperframes keyframes`, one focused `--shot`, and snapshots. Confirm first frame, proof poses, final-minus-hold, exact final, subject-owned motion, and no debug overlays.
|
||||
Reference in New Issue
Block a user