Files
Miguel Ángel bda5a60392 feat(cli): keyframes --shot onion-skin (3D, framing, camera) + multi-stroke traces
- multi-stroke pen-up traces for shapes with holes / detached parts
- --shot: 3D onion-skin self-verify — samples the live timeline and renders the
  real element at each step (true 3D, every channel), supersedes the ASCII path
- framing controls: --layout strip / --from/--to / --no-fit / --angle (orbit camera)
- pure geometry + SVG in keyframesShotLayout.ts (unit-tested)
- skill rewritten; ASCII motion-path grid dropped
2026-06-19 19:25:28 -04:00

36 lines
3.0 KiB
Markdown

# Gotchas & anti-patterns
The failure modes that actually bite, each with the fix.
## Coordinates
- **x/y are offsets, not absolute coordinates.** `{x:0,y:0}` is the element's CSS layout spot, not the canvas origin. The #1 mistake is treating them as absolute and authoring a path that's translated off where you expect. Author deltas from the element's home.
- **Center your tracer in CSS first.** If you're tracing a shape, put the element at the visual center via CSS (e.g. `left:50%;top:50%;margin:-h -w`), then author x/y as offsets around `0,0`. Keep offsets within the visible canvas (for 1080² centered, roughly ±480).
## Reading the surface
- **The text is data, not a picture.** The surface lists keyframes; to judge shape, timing, or 3D, render `--shot` and look at the PNG. (Equal-time sampling means ghost spacing already shows the ease — no need to flatten it to `ease: "none"` to preview.)
- **A head-on `--shot` lies twice.** In-place motion stacks on one spot; 3D flattens to a stack. Frame the edit with `--layout strip`, `--from/--to`, or `--angle` (SKILL.md → Frame what you're editing).
## Shape / strokes
- **One continuous line can't make holes or gaps.** If the surface shows a connector across a gap you didn't want (the line from a `?` stem to its dot, or between two letters), the fix is **multi-stroke** (`multi-stroke.md`) — separate tweens with a `set()` pen-up — not more keyframes.
- **A trace only forms with ≥2 strokes on one element.** A single stroke stays a normal per-tween block; that's expected.
## Iterating
- **Don't thrash.** Quality plateaus by ~5 rounds; beyond that, more iterations tend to over-edit a good path. Stop when faithful, or ask the user. (See `SKILL.md` → Stop condition.)
- **Use the formula when one exists.** Heart, ∞, star, spiral, circle — author from the parametric form and verify once. Iterating a formula shape is wasted effort.
- **Keep the target in view.** When tracing a known shape (logo/glyph/icon), re-check the path against the reference each round — reasoning from the actual target beats reasoning from memory.
## Parser / runtime
- **Studio holds are internal.** `set("#el", { …, data: "hf-hold" })` is a position-hold the Studio injects before a keyframed position tween; it's filtered from the surface. Never author or hand-edit it.
- **Dynamic tweens don't fully resolve.** Computed selectors or data-driven keyframes can't be statically read and surface with fewer details. If you want a tween to be editable here, author literal `keyframes: { … }` with literal numbers.
- **GSAP only.** Lottie / Three.js / CSS / WAAPI motion doesn't surface — use the matching `hyperframes-animation` adapter.
## Workflow
- **This command never writes.** It reads and screenshots; every edit is yours to make in source. `--shot` to verify.
- **Pair it.** `keyframes` for the path, `inspect` for layout/overflow across the timeline, `render` to ship. Don't skip `inspect` — a path can be right while the element clips.