fix(skill)!: reference pixel-point/animate-text — stop vendoring

Per James and Miguel's review feedback:
  James: "you can only reference the skill or recreate things"
  Miguel: "I'd just reference the skill without trying to copy
           everything"
  James: "we can't vendor their artifacts in our own repo"

The 48 vendored text-effects JSON files were direct copies from
pixel-point/animate-text (verified: typewriter.json matches the
upstream byte-for-byte at duration_ms: 240, stagger_ms: 46,
easing: steps(1, end)). That repo has no LICENSE file, so the
files default to "all rights reserved" — Apache 2.0 redistribution
in our repo is a compliance violation.

The earlier "rewrite from scratch" attempt produced JSON that
didn't render correctly (7 of 24 effects broke when I built a demo
HTML to validate them). Rather than keep iterating on a rewrite
that doesn't match the upstream's calibration, this commit drops
the vendored files entirely and updates skill prose to REFERENCE
the upstream skill instead.

### Changes

- Delete `skills/hyperframes/assets/text-effects/` (48 JSON files
  + the dual-directory structure, 8451 lines).
- Rewrite `skills/hyperframes/references/text-effects.md` as a
  reference page that:
  - Names pixel-point/animate-text as the source of truth
  - Explains why we don't ship the catalog (licensing gap)
  - Tells sub-agents to load `/animate-text` via Claude Code skill
    invocation or `npx skills add pixel-point/animate-text`
  - Lists the 24 effect IDs by category as vocabulary (so agents
    can name effects in STORYBOARD.md before loading the upstream)
  - Documents the fallback path: implement from name + GSAP
    knowledge if the upstream skill isn't available
- Update 5 cross-references to reframe the catalog as upstream-
  referenced instead of repo-bundled:
  - skills/hyperframes/references/techniques.md (TOC pointer)
  - skills/hyperframes/references/beat-direction.md (text-anim
    guidance bullet)
  - skills/website-to-hyperframes/references/capabilities.md
    (registry-overview entry)
  - skills/website-to-hyperframes/references/step-3-storyboard.md
    (storyboard template + Text Animations section format)
  - skills/website-to-hyperframes/references/beat-builder-guide.md
    (references table row)

### What sub-agents see

Before: read `text-effects.md` → see 24 named effects → read each
spec from in-repo `assets/text-effects/effects/<id>.json`.

After: read `text-effects.md` → see 24 named IDs and a load
instruction → invoke `/animate-text` (or `npx skills add
pixel-point/animate-text`) → read each spec from
`.agents/skills/animate-text/assets/effects/<id>.json` (the
upstream's own files, not vendored copies).

End-user UX cost: one extra `npx skills add` for projects that
want the deterministic catalog. Or accept the fallback where
sub-agents implement from effect name + GSAP knowledge — works
fine for simple effects, less ideal for the 3 layout-aware ones
(kinetic-center-build, short-slide-right, short-slide-down).

Net diff on #991: -8488 lines.
This commit is contained in:
ukimsanov
2026-05-21 11:09:31 -07:00
parent ae9bac69a0
commit 0253c2ccc8
54 changed files with 72 additions and 8564 deletions
@@ -15,7 +15,7 @@ You are building ONE beat of a multi-beat video composition. This file tells you
| Resource | What it covers | Read when |
| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| [techniques.md](../../hyperframes/references/techniques.md) | 13 primitive animation techniques: SVG path drawing, Canvas 2D, CSS 3D, kinetic type, variable fonts, MotionPath, etc. | Beat uses any of these techniques |
| [text-effects.md](../../hyperframes/references/text-effects.md) | 24 named text animations: soft-blur-in, typewriter, kinetic-center-build, line-reveal, stagger, crossfade, shared-axis | Beat has text animation |
| [text-effects.md](../../hyperframes/references/text-effects.md) | 24 named text animations from `pixel-point/animate-text` (separate skill — load via `/animate-text` for specs) | Beat has text animation |
| [html-in-canvas-patterns.md](../../hyperframes/references/html-in-canvas-patterns.md) | HTML-in-Canvas: iPhone/MacBook mockups, liquid glass, magnetic, portal, shatter, text cursor | Beat uses device mockups or WebGL effects on HTML |
| [transitions.md](../../hyperframes/references/transitions.md) | Shader transition API, HyperShader.init() pattern, all 14 WebGL shaders | Beat has shader transitions |
| [transitions/](../../hyperframes/references/transitions/) | 14 CSS transition category files: push, scale, dissolve, blur, 3D flip, light leak, distortion, grid, mechanical, destruction | Beat uses CSS transitions |
@@ -688,7 +688,7 @@ Control bridge actions: play, pause, seek, set-muted, set-playback-rate, enable-
16 reference docs covering:
- text-effects.md — 24 named text animation effects (per-character, per-word, per-line, whole) with exact GSAP specs; bundled in `assets/text-effects/`
- text-effects.md — 24 named text animation effects (per-character, per-word, per-line, whole) — vocabulary reference for the separate `pixel-point/animate-text` skill (load it via `npx skills add pixel-point/animate-text` or `/animate-text`). Specs live in that upstream skill, not in this repo.
- transitions.md + transitions/catalog.md + 14 category subfiles
- css-patterns.md (marker patterns)
- dynamic-techniques.md (caption animation)
@@ -63,7 +63,7 @@ Beat 3: composed kanban (4 cards-as-divs per column) + counter chip on In-Progre
- **DESIGN.md** — your color palette, font rules, components, Do's/Don'ts. Every visual must be grounded in this brand identity. If it says "white backgrounds with purple accent" — plan light scenes, not dark moody ones.
- **Asset discovery — view the contact sheets carefully, every cell.** Open `capture/assets/contact-sheet-*.jpg` and `capture/assets/svgs/contact-sheet-*.jpg`. Both are paginated — view every page (`contact-sheet-1.jpg`, `contact-sheet-2.jpg`, etc.). **For each page, name 5 specific assets you can see before moving on.** Past agents have reported "viewed the contact sheet" after one glance and then wrote beats referencing assets that didn't exist or missed the brand logo entirely. Don't be that agent. When you find an asset that earns its place in a beat, note the filename from the label and reference it as `capture/assets/<filename>`. If a thumbnail is too small to judge resolution / fine detail, open the individual file. Also read `capture/extracted/asset-descriptions.md` for one-line summaries. **Never use contact sheets or scroll screenshots in the video itself** — contact sheets have grid labels baked in; scroll screenshots are raw browser captures. Both are for AI to BROWSE and understand the site, not to place in compositions.
- **[techniques.md](../../hyperframes/references/techniques.md)** — 13 primitive animation techniques with code patterns. Pick for beats, these are starting points to adapt, not templates to copy.
- **[text-effects.md](../../hyperframes/references/text-effects.md)** — 24 named text animation effects bundled in the repo. Read the catalog now and assign a specific effect ID to every headline, label, and copy element in every beat — not generic "fades in" descriptions.
- **[text-effects.md](../../hyperframes/references/text-effects.md)** — 24 named text animation effects from the separate `pixel-point/animate-text` skill. The reference page tells you how to load the upstream skill; the IDs are listed inline. Assign a specific effect ID to every headline, label, and copy element in every beat — not generic "fades in" descriptions.
The storyboard is the creative north star. It tells the engineer exactly what to build for each beat — mood, camera, animations, transitions, assets, appearance, sound. Write it as if you're briefing a motion designer who's never seen the website.
@@ -318,14 +318,14 @@ Write this section for THIS project's actual brand and the assets audited above
### Text Animations
Every text element in this beat must name a specific effect from `skills/hyperframes/references/text-effects.md`. Read the catalog, pick what fits the brand and this beat's mood — don't default to the same effect every beat.
Every text element in this beat must name a specific effect from the catalog at `skills/hyperframes/references/text-effects.md`. The catalog lists 24 effect IDs (from the separate `pixel-point/animate-text` skill); pick what fits the brand and this beat's mood — don't default to the same effect every beat.
Format (FORMAT EXAMPLES of structure, not prescriptions — pick based on brand/mood/context):
- `[element — e.g. "main headline"]`: `[effect-id]``skills/hyperframes/assets/text-effects/effects/[id].json`
- `[element — e.g. "eyebrow label"]`: `[effect-id]``skills/hyperframes/assets/text-effects/effects/[id].json`
- `[element — e.g. "main headline"]`: `[effect-id]`
- `[element — e.g. "eyebrow label"]`: `[effect-id]`
The sub-agent reads the named JSON file and implements from `showcase.library_adapters.gsap`. No creative decisions at build time.
At build time, the sub-agent loads `/animate-text` (the upstream skill) and reads each named effect's spec from `.agents/skills/animate-text/assets/effects/<id>.json`. No creative decisions at build time — just spec retrieval and implementation.
### Beat Timing