Files
hyperframes/skills/motion-graphics/agents/builder.md
Miguel Ángel 0f8eb892e3 fix(skills): search the component catalog before hand-building a look (#3829)
* fix(motion-graphics): make the catalog search fire before hand-authoring

The workflow's only reuse instruction pointed at catalog-map.md, a
hand-maintained snapshot of ~60 registry items, and no file in the skill
ever named `hyperframes catalog --query`. An agent asked mid-build for
CRT scanlines and a glitch effect had no instruction to search, so it
hand-authored both while caption-glitch-rgb ("RGB chromatic aberration
with CRT scanline overlay") ranks first for that query on either tier.

The search reads the hosted registry and needs nothing installed, from
any directory with no project, so "the components were not installed"
was never the cause. Say that where the reader is, since the wrong
diagnosis is the intuitive one.

Director Part 2 and the Builder now run the search before naming a
block, and catalog-map.md is labelled a partial snapshot whose misses
prove nothing. Pinned by a content test in coreSkillContent.test.ts.

* fix(skills): search the component catalog before hand-building a look

Authoring workflows never told the agent to search the component library,
so agents rebuilt effects the registry already shipped. A user reported
building an effect from scratch that the registry already contained; the
search that would have found it needs nothing installed, which is why the
usual self-diagnosis ("I forgot to install the components") is wrong.

All ten workflow skills carried zero mentions of `hyperframes catalog`.
The instruction lived only in hyperframes-cli and hyperframes-registry,
both loaded on demand, and the registry skill's own trigger named the
command rather than the symptom - circular, because an agent that never
thought to search could not reach the doc telling it to search.

- Eight workflows now run the search at the point they decide what to
  build, before authoring. The two that compile through a closed
  authoring vocabulary (embedded-captions, talking-head-recut) document
  why they deliberately do not.
- hyperframes-registry triggers on the symptom (a named look, effect,
  treatment or transition) instead of the command name; the router table
  and the catalog surfaces carry the same framing.
- Fixes hand-maintained lists that had drifted: bar-chart-race was listed
  as a hand-author gap in two files while shipping in the registry;
  stat-motion was named as an installable block and is not one; the
  caption-* family count was one high; the registry discovery tables
  claimed to be the block list while covering 97 of 180.
- bun run lint:skills now fails when a doc marked as a registry snapshot
  names an item the registry does not have.

* refactor(scripts): reuse native recursive readdir and the shared registry type

Simplify pass on the new registry-snapshot check, behaviour identical:
- collectMarkdownFiles uses readdirSync({ recursive: true }) instead of
  hand-rolled recursion, matching scripts/generate-template-previews.ts.
- registryItemNames types registry.json with the exported RegistryManifest
  instead of an ad hoc inline shape, matching scripts/catalog/build-local-vectors.ts.
  The runtime guard stays: a cast describes the file, it does not validate it.
- One report() helper replaces the duplicated print-and-count block in both
  lint passes.

* refactor(scripts): name the registry check's blind spots and stop self-arming

Applies the review findings on the new check, behaviour identical except
where noted:
- lintRegistryItemRefs returns null for an unmarked file instead of an
  empty array, so "not a snapshot" and "a clean snapshot" have one owner
  and the marker is matched once rather than twice.
- Marker detection ignores fenced blocks, so a doc that documents the
  marker syntax in an example no longer arms the check on itself. The id
  scan still reads full content, so fenced examples stay covered.
- The header comment and two tests now pin both known false negatives:
  identifiers outside backticks, and single-word item names. Measured on
  the six marked files, dropping the hyphen requirement would monitor 3
  more items and force 46 allow= entries for ordinary prose words, so the
  requirement stays and the gap is stated instead of silent.

* chore(skills): regenerate skills manifest after catalog-search edits
2026-09-10 03:21:33 +00:00

3.7 KiB
Raw Permalink Blame History

Motion-Graphics Builder

Turn shot-plan.json into one renderable HyperFrames composition (compositions/index.html). Everything stays in the HF ecosystem — HTML is the source of truth; a single paused GSAP timeline carries all motion; the engine seeks it. Category-specific build rules live in categories/<id>/module.md; this file is the shared contract.

Reuse-first (the default)

Default = compose existing catalog capabilities, not hand-author:

  • Search first, for every named effect — npx hyperframes catalog --query "<the move, in plain English>" --json, including an effect the user names after the plan is written. It needs nothing installed and no project. Author by hand only after a search came back with nothing that does the job, and report that miss with npx hyperframes feedback --search-miss.
  • npx hyperframes add <block> (registry) → customize in place. Most blocks bake content/data into their own script (only a few expose CSS-var params), so reuse = add + edit.
  • hyperframes-animation rules / blueprints / transitions for motion; runtime adapters (GSAP default).

Hand-author only (a) gaps no block/rule covers, (b) the asset-fusion affordance binding. The Director named the block(s) + customizations in shot-plan.json (content.block + content.customize); see catalog-map.md.

The HF contract (non-negotiable)

  • Root #stage carries data-composition-id, data-start="0", data-duration=<s>, data-fps, data-width, data-height.
  • Exactly ONE gsap.timeline({ paused:true }); register window.__timelines["<id>"] = tl;; end with tl.seek(0). Never tl.play() for render-critical motion. No timers / async / event-driven timeline build. Finite repeats only.
  • Timed clips need class="clip" + a stable id. Timeline-driven groups inside one full-duration clip don't each need timing attrs.
  • Fonts: prefer local @font-face (.woff2) for deterministic / offline render; CDN Google Fonts do render (compiler caches + injects @font-face) but warn + need network.
  • Deterministic only — no Date.now() / Math.random() / network.

Layout before animation

Build the hero-frame end-state in CSS first (flex + padding; never absolute offsets on content containers; the root must be sized). Use fromTo() for elements inside .clip and for any delayed entrance; from() is safe only for non-clip elements active from t=0. Exits belong to transitions or the final scene. Full rules: references/builder-contract.md.

IR → composition

  • content.block → hyperframes add it (or inline) + apply content.customize.
  • per-category content (text scenes / chart data / fusion positions / news-tweet content) → realize per categories/<id>/module.md.
  • resolved asset_needs → reference frozen project-local paths (never a remote URL or a prompt).
  • palette[-1] / bg + font from the envelope.
  • export: alpha-overlay → transparent bg; render --format webm (or mov).

Critical correctness (GSAP / seek)

Opacity-gate delayed elements (set hidden until their entrance). Clamp at tween bounds (no overshoot past a held value). Allowed eases: power1–4, back, bounce, circ, elastic, expo, sine (.in/.out/.inOut). One motif per scene. Run hyperframes check for overflow / collisions.

Hand off for verification

Self-check the authored file, then return it to the orchestrator. Step 5 runs hyperframes lint, hyperframes check, and proof snapshots on the assembled project. Do not render. When redispatched with a finding, fix the offending element and never change a fixed data-duration during repair. Remotion-source migrations use /remotion-to-hyperframes and its SSIM harness instead.