Commit Graph
830 Commits
Author SHA1 Message Date
ukimsanov 01e0098ed7 feat(skill): examples library batch 5 - 6 lifts from team archive
Mined /Users/ularkimsanov/Downloads/Archive and Archive 2 (37 production
HyperFrames projects from the team) and lifted 6 standout techniques into
the library that fill technique gaps not covered by the 43 existing scenes.

Section 07 html-in-canvas (now 3 scenes)
  scene-03-cursor-blur-sweeps     <- Archive/vfx-text-cursor
  Canvas 2D cursor-driven light sweeps (cyan + magenta gradient bars
  follow a virtual cursor) with chromatic-aberration text passes.
  Source used WebGL + bg video; rebuilt in pure Canvas 2D + procedural
  background to eliminate asset deps.

Section 10 particles-and-ambient (now 3 scenes)
  scene-03-scan-line-grid         <- Archive 2/hyperframes-codex-plugin-announcement
  CRT-adjacent ambient with 2px gradient sweep bar (3 passes), 80px+400px
  grid overlay with parallax drift, scanline texture, viewfinder ticks,
  telemetry HUD counters. Rebranded HyperFrames/Codex -> generic OBSERVE
  wordmark + SCAN/HOLD/REPEAT tagline.

Section 11 3d-and-parallax (now 4 scenes)
  scene-02-vercel-triangle-roll   <- Archive/vercel-triangle-roll
  Three.js 3D pyramid rotating through 6 distinct orientations with
  multi-material grayscale faces. Stripped Vercel SVG mark + energy
  shader (brand IP). Replaced source's onUpdate render with
  gsap.ticker.add() reading tl.time() per beat-builder-guide rule.

  scene-03-card-flyby-deck        <- Archive 2/card-flyby
  CSS 3D card deck tumble with diagonal clip-path wipe reveal. 6 colored
  cards (EMERALD, CRIMSON, PLUM, AMBER, MIDNIGHT, COBALT) fly through
  perspective viewpoint. Stripped brand titles to generic color names.

  scene-04-anamorphic-text-crt    <- Archive 2/anamorphic-text-crt
  Three.js 3D text morphing MOTION <-> DESIGN with full CRT HUD overlay
  (scan-lines, top/bottom HUD boxes, blinking dot). Uses TextGeometry +
  CSG Boolean ops. Rebranded source HYPERFRAMES/HERMES -> MOTION/DESIGN
  (both 6 chars for symmetric morph).

Section 12 combined-vignettes (now 2 scenes)
  scene-02-binary-rain-boot       <- Archive/hermes-hyperframes
  Matrix-style binary rain (Canvas 2D, 96 columns of falling 0/1 with
  white-hot heads + green tails) as background, with centered terminal
  panel typing in a generic boot sequence:
    > system.init
    > loading kernel...
    > [OK] memory mapped
    > [OK] network ready
    > ready.
  Combines techniques from source's binary-break.html + boot-sequence.html
  into one scene. Stripped HYPERFRAMES/Hermes references.

Conversion process per scene: standalone HTML5 wrapper, composition id
renamed, scene-label at bottom-left, project-specific branding stripped,
GSAP CDN linked, data-start/data-duration on root, canvas-render-loops
use gsap.ticker.add() per the beat-builder-guide rule. Each lift was
lint-clean (0 errors) and snapshot-verified across 6-8 frames.

Library state after this batch:
  Section 01 typography:               11 scenes
  Section 02 markers-and-emphasis:      6 scenes
  Section 03 easing-variety:            1 scene
  Section 04 composed-ui:              10 scenes
  Section 05 transitions-shader:        1 scene
  Section 06 transitions-css:           1 scene
  Section 07 html-in-canvas:            3 scenes (+1)
  Section 08 svg-and-path:              1 scene
  Section 09 counters-and-data:         2 scenes
  Section 10 particles-and-ambient:     3 scenes (+1)
  Section 11 3d-and-parallax:           4 scenes (+3)
  Section 12 combined-vignettes:        2 scenes (+1)
  Section 13 anti-patterns:             4 scenes
  Total: 49 production-grade scenes across 13/13 sections.

All 49 scenes rendered at draft quality + uploaded to HeyGen Verse +
browseable in the gallery app at:
https://www.heygenverse.com/a/1636f2fe-3ddc-4543-9a56-0d0b99538807
2026-05-19 08:52:55 -07:00
ukimsanov 68235f50e1 feat(skill): examples library scene 04-10 - terminal + live preview
One more lift bringing section 04 (composed-ui) to 10 scenes.

scene-10-terminal-with-preview <- launch-video/compositions/cta.html
  Two-column 8s scene. Left: terminal emulator with 2 sequential
  commands typing in ('npx create-app starter' then 'build me a
  launch page with hero + cta') + scaffold output streaming + status
  badges. Right: preview pane slides in, mock product card builds
  incrementally (avatar -> skeleton text -> headline -> CTA button ->
  decoration ring). Status badge flips 'Building...' -> 'Ready'.
  Continuous-motion holds throughout (card breath, decoration rotate,
  button shadow pulse).

Rebranded from HyperFrames-specific (npx hyperframes init, video
composition mockup) to generic (npx create-app starter, generic
product landing card). Source's tl.call() typewriter pattern (which
doesn't fire under tl.seek()) refactored to pre-built char spans +
steps(1) opacity stagger so the scene snapshots cleanly.

Library final state:
  Section 01 typography:               11 scenes
  Section 02 markers-and-emphasis:      6 scenes
  Section 03 easing-variety:            1 scene
  Section 04 composed-ui:              10 scenes
  Section 05 transitions-shader:        1 scene
  Section 06 transitions-css:           1 scene
  Section 07 html-in-canvas:            2 scenes
  Section 08 svg-and-path:              1 scene
  Section 09 counters-and-data:         2 scenes
  Section 10 particles-and-ambient:     2 scenes
  Section 11 3d-and-parallax:           1 scene
  Section 12 combined-vignettes:        1 scene
  Section 13 anti-patterns:             4 scenes
  Total: 43 production-grade scenes across 13/13 sections.

All sections now have at least one bar scene. Future sessions can
deepen the slim sections (03, 07, 08, 11, 12 each have only 1-2 scenes)
or move to the remaining deferred work: stitched reels, HeyGen Verse
arena upload, agent self-test on a fresh worktree to verify the
wiring shifts technique usage vs the v9 baseline.
2026-05-19 07:50:21 -07:00
ukimsanov 01ef436888 feat(skill): examples library batch 4 - sections 05 + 06 complete, library reaches 13/13
Two new bar scenes filling the final empty sections.

Section 05 transitions-shader (NEW, 1 scene PASS QC):
  scene-01-shader-transitions-showcase
    4-panel grid demonstrating 4 shader-transition effects between
    A/B beats — chromatic-split (RGB channel offset + scanlines),
    sdf-iris (circle reveal with edge ring), domain-warp (organic FBM
    noise dissolve), whip-pan (horizontal motion-blur swipe).
    Implemented in Canvas 2D + GLSL-style algorithms so the scene is
    standalone (no @hyperframes/shader-transitions module dependency).
    Uses gsap.ticker.add() reading tl.time() per the new
    beat-builder-guide CANVAS RENDER LOOPS rule.

Section 06 transitions-css (NEW, 1 scene PASS QC):
  scene-01-css-transitions-grid
    2x3 grid of 6 CSS transitions between Beat A and Beat B states:
    push (translateX coordinated), scale (down+fade -> up+fade with
    back.out overshoot), blur dissolve (filter:blur ramp), 3D flip
    (preserve-3d + perspective + backface-visibility:hidden coin
    flip), light leak wipe (rotated gradient div with blur), classic
    dissolve (opacity crossfade). Transitions staggered to catch
    different completion states across snapshot frames. Frame 4
    catches the 3D flip mid-rotation — the money shot.

Top-level README lookup table:
- Replaced all .html paths with directory paths (matches actual
  scaffolded layout).
- Added all 11 newly-added scenes (typography 04-11, all of 02
  markers, 03 easing, 05/06 transitions, 07-08 svg/canvas-ascii,
  09-10 counters/particles, 11 3d, 12 combined, 13 anti-patterns).
- Lookup is now accurate to filesystem.

Library state after this batch:
  Section 01 typography:               11 scenes
  Section 02 markers-and-emphasis:      6 scenes
  Section 03 easing-variety:            1 scene
  Section 04 composed-ui:               9 scenes
  Section 05 transitions-shader:        1 scene  (new)
  Section 06 transitions-css:           1 scene  (new)
  Section 07 html-in-canvas:            2 scenes
  Section 08 svg-and-path:              1 scene
  Section 09 counters-and-data:         2 scenes
  Section 10 particles-and-ambient:     2 scenes
  Section 11 3d-and-parallax:           1 scene
  Section 12 combined-vignettes:        1 scene
  Section 13 anti-patterns:             4 scenes
  Total: 42 production-grade scenes across 13/13 sections.

Library is now structurally complete. Future work: add more scenes
per section to widen technique coverage (especially 03, 07, 08, 11,
12 which have only 1-2 scenes each), build stitched reels for the
arena, run agent self-test to verify the wiring actually shifts
technique usage.
2026-05-19 07:42:01 -07:00
ukimsanov 128e0f8829 feat(skill): examples library batch 3 - sections 02 + 13 + beat-builder-guide updates
10 new scenes filling sections 02 (markers-and-emphasis) and 13 (anti-patterns), plus 3 rule additions to beat-builder-guide.md.

Section 02 markers-and-emphasis (NEW, 6 scenes all PASS QC):
  scene-01 highlight-sweep            yellow bar scaleX 0->1 behind key word
  scene-02 hand-drawn-circle          SVG ellipse stroke-dashoffset draw
  scene-03 burst-radial               12 radial spikes from key word (back.out(2))
  scene-04 scribble-underline         wavy sine-path stroke-dashoffset draw
  scene-05 sketchout-x                two diagonal strokes + replacement phrase
  scene-06 combined-marker-cascade    all 5 marker techniques in one phrase

Section 13 anti-patterns (NEW, 4 scenes all PASS QC):
  scene-01 slideshow-trap             3 screenshot panels + Ken Burns + crossfade
  scene-02 static-after-entrance      entrance in 1.5s then 7.5s of nothing (countdown overlay)
  scene-03 power2-everywhere          side-by-side LEFT all power2.out vs RIGHT varied easings
  scene-04 screenshot-ken-burns       fake-screenshot rectangle + linear drift (the eval-default failure)

Each anti-pattern scene has on-screen red ANTI-PATTERN banner + inline THE PROBLEM source comments + counter-reference paths to the GOOD scene for that failure mode.

beat-builder-guide.md added 3 rules:
- COUNTERS: 20-30 tl.set() calls along duration is canonical seekable pattern (cite scene-05-dashboard-counters)
- CANVAS RENDER LOOPS: do NOT tl.to(proxy, onUpdate:render); doesn't fire under tl.seek(). Use gsap.ticker.add() reading tl.time() (cite scene-02-canvas-ascii)
- DOM MUTATION IN TIMELINE: do NOT tl.call() to build DOM; build all DOM upfront (cite scene-01-soft-blur-in)

Library state after this batch:
  Section 01 typography:               11 scenes
  Section 02 markers-and-emphasis:      6 scenes (new)
  Section 03 easing-variety:            1 scene
  Section 04 composed-ui:               9 scenes
  Section 07 html-in-canvas:            2 scenes
  Section 08 svg-and-path:              1 scene
  Section 09 counters-and-data:         2 scenes
  Section 10 particles-and-ambient:     2 scenes
  Section 11 3d-and-parallax:           1 scene
  Section 12 combined-vignettes:        1 scene
  Section 13 anti-patterns:             4 scenes (new)
  Total: 40 production-grade scenes across 11 of 13 sections.

Sections 05 (transitions-shader) and 06 (transitions-css) remain empty - these need fresh authoring or shader-transitions package integration.
2026-05-19 02:52:47 -07:00
ukimsanov 7a6ffc282a feat(skill): examples library batch 2 — 6 more lifts from production projects
Mined launch-video, launch-video-2, and claude-design-hyperframes-video
projects for another 6 production-grade scenes, populating 4 more sections.

Lifts (all PASS QC via contact sheet review):

  Section 04 composed-ui (now 9 scenes)
    scene-09-phone-mockups            ← claude-design/compositions/phones.html
    Two 3D iPhone mockups in perspective with realistic bezels, dynamic
    island, home indicator. Scene 1: fictional Pulse fitness app (orange
    ride card + Activity rings + Today calendar). Scene 2: fictional Echo
    music player (Road trip playlist + Echo album with waveform +
    Visualizer EQ bars). All composed from CSS+SVG, no screenshots.
    Rebranded from Strava/Spotify; replaced Photos+Camera screens (asset-
    dependent) with all-CSS Activity rings + SVG Visualizer. All 9 counter
    animations converted from onUpdate to discrete tl.set(textContent).

  Section 07 html-in-canvas (now 2 scenes)
    scene-02-canvas-ascii              ← launch-video/compositions/canvas-close.html
    Canvas 2D ASCII art with procedural noise + BFS depth map + lightning
    + 5x5 bitmap font. Lightning strikes reveal 'THE END' in amber ASCII
    glyphs with 'GO MAKE SOMETHING' subtext. Pure JS canvas (no external
    deps). **Key finding**: source's gsap proxy + onUpdate render pattern
    does NOT fire under tl.seek(); refactored to gsap.ticker.add()
    reading tl.time() each frame. This is the reliable pattern for
    canvas-render-by-time scenes under HyperFrames' seekable engine —
    documented in section README so future canvas scenes copy this.

  Section 09 counters-and-data (new, 2 scenes)
    scene-01-timeline-diagram         ← launch-video/compositions/anatomy.html
    Editorial cream/parchment background. Multi-phase build: eyebrow
    'anatomy of a composition' → div rectangles dock on timeline → SVG
    easing curve draws → teal slider follows curve via MotionPath →
    camera zooms onto curve → exit blur. Strong educational viz pattern.

    scene-02-pipeline-diagram         ← launch-video/compositions/engine.html
    Vertical scroll-pan camera through Agent → Renderer → MP4 pipeline.
    SVG dashed flow connectors with orange pip markers slide between
    stages. Climaxes with side-by-side card stack proving determinism
    + 'Identical output, every time.' badge.

  Section 10 particles-and-ambient (new, 2 scenes)
    scene-01-radial-bloom-grid        ← launch-video/compositions/flex-gsap.html
    15x25 grid of 375 dots with GSAP stagger.from='center'. Three-phase
    timeline: center-out bloom → elastic cursor-sweep ripple →
    explosion+blur exit. Duration extended from 0.69s to 3s for visible
    bloom progression across snapshot frames.

    scene-02-aurora-end-card          ← launch-video-2/act-4-end-card.html
    Radial gradient aurora (violet/cyan/mint/magenta) + 12 floating
    particles + 'MOTION STUDIO' wordmark with tri-color text gradient +
    install command 'npx create-motion-studio' typing in with cursor +
    breath accent dot. Rebranded from HyperFrames; local Inter-Variable/
    JetBrainsMono-Variable.woff2 swapped to Google Fonts CDN.

Library state after this batch:
  Section 01 typography:        11 scenes
  Section 03 easing-variety:    1 scene
  Section 04 composed-ui:       9 scenes
  Section 07 html-in-canvas:    2 scenes
  Section 08 svg-and-path:      1 scene
  Section 09 counters-and-data: 2 scenes (new)
  Section 10 particles-and-ambient: 2 scenes (new)
  Section 11 3d-and-parallax:   1 scene
  Section 12 combined-vignettes: 1 scene
  Total: 30 production-grade scenes across 9 sections.

Sections 02, 05, 06, 13 still empty. Future sessions can fill them with
fresh authoring (no obvious lifts from source projects for those
categories).
2026-05-19 02:41:09 -07:00
ukimsanov 7ec923cb0f feat(skill): examples library lifts from 3 production projects (6 scenes)
Mined launch-video, launch-video-2, and claude-design-hyperframes-video
projects for production-grade compositions and lifted 6 of them into the
examples library as the BAR scenes for previously-empty sections.

Lifts (all PASS QC via contact sheet review):

  Section 03 easing-variety
    scene-01-css-animation-grid       ← launch-video/compositions/flex-css.html
    6x3 grid of pure-CSS animations: spinners, pulses, morphs, waves,
    orbits, gradient cycles, flip cards, bars, bounces. Duration extended
    from 1.71s to 3.5s so snapshot intervals catch distinct motion states.

  Section 07 html-in-canvas
    scene-01-webgl-shader             ← launch-video/compositions/flex-shader.html
    WebGL fragment shader with domain-warp FBM noise + cosine palette.
    Canvas 2D fallback UPGRADED from static gradient to animated multi-stop
    radial + iridescent linear sweep so the fallback is also a good pattern
    to copy.

  Section 08 svg-and-path
    scene-01-vinyl-record             ← launch-video/compositions/flex-music.html
    SVG vinyl record (7 concentric grooves, label, shine, tonearm
    pivot/shaft/cartridge/stylus). Duration extended 0.58s → 3s for visible
    spin across snapshot intervals.

  Section 11 3d-and-parallax
    scene-01-css-3d-torus             ← launch-video/compositions/flex-threejs.html
    16-segment orbital ring of pastel rounded squares rotating through 3D
    space via transform-style: preserve-3d + perspective. Pure CSS, no
    Three.js library required despite the source's filename.

  Section 12 combined-vignettes
    scene-01-techniques-grid          ← claude-design-hyperframes-video/compositions/grid.html
    GOLD: 6x4 grid of 24 cells, each running a different visual technique
    (clock, rings, stripes, 3D cube, dot grid, QR, stock chart, blob morph,
    particle vortex, glowing orb, spirograph, DNA helix, neural network,
    burst rays, kinetic MOTION word, glitch SYSTEM->RENDER text, sine waves,
    code editor, spinners, binary rain, maze, audio bars, neon globe,
    weather card). Single highest-density technique reference in the library.
    Rebranded CLAUDE -> MOTION and DESIGN -> RENDER. Source's innerHTML build
    replaced with createElementNS for security-hook compliance.

  Section 01 typography (bonus scene)
    scene-11-orbital-title            ← claude-design-hyperframes-video/compositions/letters.html
    KINETIC TYPE Fraunces serif title with per-character alternating-side
    entrance + SVG accent line stroke draw + orbital ring rotation + radial
    glow breathing + 4-segment type-on tagline. Rebranded HYPER FRAMES ->
    KINETIC TYPE and HTML in. Video out. -> Code in. Motion out. (same char
    counts so stagger math is unchanged). Source's onUpdate-driven tagline
    refactored to pre-rendered char spans with autoAlpha stagger to fix
    seek determinism.

Conversion process per scene: standalone HTML5 wrapper added (was a
<template> sub-composition), composition id renamed everywhere, scene-label
added at bottom-left, project-specific branding stripped, GSAP CDN linked,
data-start/data-duration added on root. Each lift was lint-clean (0 errors)
and snapshot-verified across 6-8 frames.

Library state after this batch:
  Section 01 typography:        11 scenes
  Section 03 easing-variety:    1 scene
  Section 04 composed-ui:       8 scenes
  Section 07 html-in-canvas:    1 scene
  Section 08 svg-and-path:      1 scene
  Section 11 3d-and-parallax:   1 scene
  Section 12 combined-vignettes: 1 scene
  Total: 24 production-grade scenes across 7 sections.

Sections 02, 05, 06, 09, 10, 13 still empty. Future sessions can lift
anatomy.html and engine.html (launch-video) into section 09 counters,
flex-gsap.html into section 10 particles, and continue filling out the
library.
2026-05-19 02:07:15 -07:00
ukimsanov ba0098ca3a feat(skill): wire examples library into the workflow
Make the example library load-bearing in 4 places:

1. SKILL.md — new 'Step -1: Study the Example Library' BEFORE Step 0.
   Mandatory: read examples/README.md + at least 3 scene HTMLs before
   planning. Names which scenes are 'the bars' (04-composed-ui scene 01
   kanban + scene 02 chat). Non-negotiable rule: if you'd reach for a
   product screenshot of an interface as a primary visual, STOP and
   build that UI from divs using the matching example scene.

2. step-3-storyboard.md — Technique-pick checklist after the pacing
   table. Every beat must name 2-4 techniques AND cite the matching
   example scene path. Beats with <2 cited techniques must be redesigned.
   Forbidden: 'show the kanban' as a beat with no scene citation.

3. step-5-build.md — Copy-closest mandate added to the build section.
   Concrete map from beat type to example scene path. Do not write
   any beat from scratch; there is always a closer example.

4. beat-builder-guide.md — Example scene moved to the #1 mandatory
   read for every beat. Sub-agents copy the cited scene's index.html
   to compositions/beat-N-name.html and mutate, not write from scratch.
   Specific call-out: if the beat has narration, also study
   examples/04-composed-ui/scene-02-chat-with-typing — the canonical
   narration-sync pattern (every meaningful phrase = one visual event).

This is the lever HANDOFF Recommendation 2 named: agents pattern-match
to what they study, not to skill prose. With 18 production-grade scenes
in the library and the workflow now requiring agents to copy them as
starting points, the screenshot+Ken-Burns default has somewhere better
to go.
2026-05-19 01:41:04 -07:00
ukimsanov a877da7088 feat(skill): examples library section 04 — composed UI, 8 scenes
The highest-leverage section in the library. Every scene demonstrates a
product UI element built from divs + GSAP — zero screenshots, zero
captured assets. Directly addresses the 'every agent screenshots the
kanban / chat / dashboard / terminal' failure mode from the 11 eval runs.

Section 04 scenes (all PASS QC):
  01 kanban-board          — 3-column kanban with cards entering staggered,
                             drag-from-Todo-to-In-Progress with shadow ramp,
                             column count chip pulse on drop
  02 chat-with-typing      — chat panel with 3 messages, reaction emoji
                             burst, typing indicator (3 bouncing dots),
                             self-reply slide-in. Every visual event lands
                             at a narration anchor timestamp. THE
                             narration-sync gold standard.
  03 terminal-typeon       — terminal window with multi-line command +
                             output type-on (steps(1) ease), green exit
                             badge with elastic settle + floor glow.
  04 command-palette       — Cmd+K modal with backdrop blur, keystroke
                             entry, real-time filter, focus ring on top
                             result, dismiss + action toast + new activity.
  05 dashboard-counters    — 4 KPI cards, counter 0→128K via deterministic
                             tl.set(textContent), sparkline stroke-dashoffset
                             draw, donut fill 0→87%, multi-stat ticks,
                             live mode with status pulses.
  06 file-tree-reveal      — VS Code-style file tree, folders expand
                             progressively, selection bar slides into
                             place, editor opens parse.ts with syntax
                             colors, git modified badges pulse.
  07 code-editor-typing    — multi-line type-on with per-span syntax colors,
                             red error squiggle + tooltip + status bar
                             flip, fix typed via tl.set(textContent),
                             status returns to blue.
  08 calendar-events       — weekly grid with today highlighted, 6 events
                             slide in staggered, 'happening now' event
                             pulses, popover slides up with attendees,
                             red 'now' time indicator drifts.

Authored by hand: scenes 01 and 02 (the bars). Scenes 03-08 dispatched
to parallel sub-agents using scenes 01-02 as templates; every return was
visually QC'd via contact-sheet review before being marked PASS in the
section README.
2026-05-19 01:14:36 -07:00
ukimsanov 04827b98ce feat(skill): examples library scaffold + section 01 (typography) — 10 scenes
First slice of the HyperFrames Capability Showcase library at
skills/website-to-hyperframes/examples/. Each scene is a self-contained
mini-project (index.html in its own directory) that lints, snapshots, and
renders standalone.

Section 01 (typography) — 10 production-grade scenes, all PASS QC:
  01 soft-blur-in              — Apple keynote per-character reveal
  02 typewriter-mechanical     — stepped per-char terminal type-on
  03 kinetic-center-build      — words push in right-to-left, lock center
  04 line-reveal-staggered     — editorial mask-reveal-up with Fraunces italic
  05 stagger-wave              — center-out vs edges-in stagger origins
  06 variable-font-weight-shift — wght 100→900 animation via @property
  07 shared-axis-crossfade     — Material Design Z-axis depth transition
  08 glitch-rgb-split          — RGB channel offset with mechanical jitter
  09 scramble-decrypt          — per-char intermediate substitution decrypt
  10 per-word-emphasis         — per-word crossfade + hand-drawn marker

Plus catalog + shared assets:
  - examples/README.md             — top-level index + lookup by technique
  - 01-typography/README.md        — section spec + QC log per scene
  - _shared/hyper-shader-local.js  — copied from packages/shader-transitions/dist/
  - _shared/shared-styles.css      — design tokens
  - _shared/easing-glossary.md     — single source of truth for easings

Authoring conventions are documented in examples/README.md so future scenes
follow the same shape: full HTML doc, GSAP CDN, CustomEase, data-composition-id/
start/duration/width/height on root, scene-label at bottom-left, continuous
motion (no static periods >1.5s), easing variety (3+ different easings).

.gitignore: fixed bare 'examples/' rule (matched anywhere) to '/examples/'
(root-only), and added rule to skip snapshot artifacts inside the library.
2026-05-19 00:57:06 -07:00
ukimsanov e1bd22d4c8 fix(skill): beats must have continuous motion, not just entrance animations
The #1 quality problem: agents write entrance tweens in the first 1-2 seconds
of a beat, then nothing happens for the remaining duration. A 13-second beat
with 6 tweens = 11 seconds of static content.

step-3: Animation Sequence section now explicitly requires events spanning
the FULL beat duration. Nothing unchanged for more than ~2 seconds.

beat-builder-guide: "Continuous motion" added as the first and most important
rule — above all technical rules. Ken Burns drift, parallax, breathing,
secondary elements appearing mid-beat.
2026-05-18 12:18:47 -07:00
ukimsanov ec5edfa1df feat(snapshot): font verification + pacing-first + creative summary removal
snapshot: report loaded vs failed fonts via document.fonts API
step-3: pacing is FIRST decision at top of file
step-2 + SKILL.md: no more creative summary confirmation
step-5: sub-agent prompt includes explicit snapshot + lint commands
2026-05-18 01:45:06 -07:00
ukimsanov 7a283b6c40 fix(skill): asset selection guidance + remove creative direction summary
step-3: distinguish product assets from decorative assets — product
screenshots show what the product does, decorative images can be backgrounds
but shouldn't be the beat content. Never use contact sheets or scroll
screenshots in the video (they have grid labels baked in).

step-2: remove Creative Direction Summary confirmation — agents were
rephrasing the user's prompt and asking "does this match?" The storyboard's
Global Direction section already captures the same info. Proceed directly
to Step 3.

HeyGen TTS v3 API verified: response shape { "data": { "audio_url",
"duration", "word_timestamps" } } is correctly documented.
2026-05-18 00:33:59 -07:00
ukimsanov f5e4a67605 feat(skill): beat-builder-guide.md — self-contained sub-agent workflow
Sub-agents now read beat-builder-guide.md directly instead of relying on the
main agent to paste rules into the prompt (which truncated easing, validation,
and file references). The guide has:

- Full reference table: capabilities.md, techniques.md, text-effects.md,
  html-in-canvas-patterns.md, transitions/, css-patterns.md, audio-reactive.md,
  captions.md, typography.md, motion-principles.md, dynamic-techniques.md,
  video-composition.md + all loadable skills (gsap, animate-text, lottie, three, etc.)
- Build → lint → snapshot → verify → report workflow
- Rules, easing vocabulary, composition template
- Self-verification: sub-agents snapshot their own beats and fix issues before reporting

Step-5 template simplified: just paste beat spec + brand values + asset paths,
tell sub-agent to read beat-builder-guide.md. No more 90-line inline rules block.

SKILL.md: sub-agent mode on by default, "no sub-agents" option for sequential build.
2026-05-18 00:12:44 -07:00
ukimsanov 853d92eff8 fix(skill): move easing vocabulary into RULES section so sub-agents see it
The easing table was after the RULES section in step-5. Sub-agent prompts
paste ═══ RULES ═══ through the end of rules but stop before the easing
section. Result: 0/4 v8 agents used any non-default easing.

Fix: condensed easing guidance into a single RULES bullet that gets pasted
into every sub-agent prompt. power4.out for snap, back.out(1.7) for impact,
expo.out for soft land, elastic.out for bounce, expo.inOut for dramatic.
2026-05-17 23:30:09 -07:00
ukimsanov cefd03fcd9 fix(skill): don't ask questions the user already answered in their prompt
step-2-brief.md previously said "Do NOT skip this step" and forced agents to
ask all 5 questions even when the user's prompt already specified video type,
style, and specific scenes. Now: parse the prompt first, skip questions that
are already answered, only ask about gaps.
2026-05-17 22:37:41 -07:00
ukimsanov f606cdfc0f refactor(pipeline): strip dead capture outputs, add easing vocabulary, streamline skill
Capture CLI:
- Remove detected-libraries.json, assets-catalog.json, full-page.png generation
- Remove detectedLibraries from AGENTS.md generator and buildPrompt

Skill:
- step-5: pro easing vocabulary + stacked-beats code pattern for fast pacing
- step-3: contact sheet asset discovery, marketing assets vs screenshots distinction
- SKILL.md: lighter DESIGN.md for fast pacing, no arbitrary GSAP call count
2026-05-17 21:26:56 -07:00
ukimsanov 5e33c32565 feat(pipeline): pacing system, launch-video skill, verification gates, skill cleanup
Pipeline pacing:
- step-3: add pacing → beat structure table mapping Fast/Moderate/Slow/Arc to
  concrete beat count, duration, and architecture choices
- step-5: add architecture selection based on pacing (stacked beats for fast,
  HyperShader sub-comps for moderate/slow) with cinematic beat patterns

Launch-video skill (from upstream PR #699):
- Billboard-per-beat pattern for fast-paced videos
- Stacked divs with GSAP opacity sequencing, no sub-compositions

Verification improvements:
- step-6: Definition of Done checklist, per-beat verdict protocol, critic scoring

Skill cleanup (~1,600 lines saved per session):
- capabilities.md (704 lines) → capabilities-overview.md (34 lines)
- beat-direction.md inlined into step-3 (motion verbs + transition matrix)
- narration.md inlined into step-3 (pacing formula + hook patterns)

Other fixes:
- agentPromptGenerator.ts: fix outputDir scope crash
- step-1: font availability check
- step-3: block name ≠ shader name warning
- step-4: TTS test clip, background music prompt
- step-5: HyperShader.init() pattern, sequential track indices, GSAP FROM TRAP
- step-6: GEMINI_API_KEY export for subshell inheritance
2026-05-17 16:21:23 -07:00
ukimsanov a997f79c37 fix(pipeline): auto-load .env, second-based snapshot names, banner dismissal, critic sub-agent
cli: auto-load .env from CWD so GEMINI_API_KEY/HEYGEN_API_KEY work without
source .env — agents no longer need to manually export keys

snapshot: rename frames to seconds (e.g. frame-00-at-4.2s) instead of
pct (frame-00-at-20pct) — more useful when comparing against storyboard

screenshotCapture: dismiss marketing banners, cookie consents, and
modals before scrolling — prevents popups contaminating screenshots

step-6: replace verbose manual review instructions with:
- required reads: descriptions.md AND contact-sheet.jpg (both)
- critic sub-agent prompt for honest constructive quality assessment
  before showing anything to the user
2026-05-16 14:34:07 -07:00
ukimsanov 0df846b2c6 fix(skill): warn against published CLI for capture and snapshot
Both commands have critical fixes only in the local build:
- capture: paginated contact sheets, SVG root scan
- snapshot: sub-comp wait, local-time seek, Gemini descriptions

Published npx hyperframes 0.6.6 missing all of these.
Added warnings to step-0 and step-6 so agents cannot miss it.
2026-05-16 12:41:44 -07:00
ukimsanov 215b41dc46 fix(linter): add invalid_capture_path error rule
Catches ../capture/ in sub-composition files — the most persistent
sub-agent mistake across v1-v4 (100% failure rate on framer, 4+ rounds).
Documentation rules in sub-agent prompts were not sufficient.

The rule fires as a hard error so lint fails until paths are corrected.
../capture/ works on disk but breaks in Studio and renders (Studio rewrites
base URLs to the project root). Must use capture/ not ../capture/.

Verified: fires correctly on compositions with ../capture/ paths.
2026-05-16 12:22:05 -07:00
ukimsanov 841f877061 feat(snapshot): gemini vision descriptions + v4 skill fixes
snapshot: add --describe flag (default on) for Gemini vision analysis
- describes every frame with the default prompt or a custom question
- auto-resizes 1920x1080 PNGs via sharp to stay under Gemini 4MB limit
- writes snapshots/descriptions.md for agents to compare against storyboard
- errors visible in descriptions.md instead of silently swallowed
- silent skip when GEMINI_API_KEY not set

step-5: block-name vs shader-name, css centering, last-scene workaround
step-4: kokoro ssml tags read as literal text
skill: autonomous mode when user signals skip collaborative gates
step-6: document --describe usage and descriptions.md workflow
2026-05-16 12:18:02 -07:00
ukimsanov 07c5679019 docs: add v4 agent feedback with root cause analysis 2026-05-16 11:52:50 -07:00
ukimsanov 4ae59e5a7d fix(snapshot): two sub-composition seek bugs causing black beats
Bug 1: snapshot fired before all sub-compositions loaded
- Old: resolved when keys.length >= 2 (first sub-comp registered)
- Fix: wait until all data-composition-src hosts have timelines
- Verified: beats 2-4 now visible in huly-promo v4 snapshots

Bug 2: sub-comp timelines seeked to global time, not local time
- Old: tls[key].seek(globalTime) — with exit animations, global t=29
  clamps to GSAP end (t=7), elements at opacity:0 from exit fade
- Fix: seek to global_t - host.data_start (correct local time)
- Verified: beat-5 (starts at t=26.7) seeked to local t=2.3 at
  global t=29 — 'Join the Movement' now visible in snapshots

Both bugs confirmed via render vs snapshot comparison before fixing.

Also fix HeyGen v3 API docs: response is data.audio_url not audio_url
directly; word_timestamps uses 'word' key not 'text' — normalize before
saving as transcript.json
2026-05-16 11:48:09 -07:00
ukimsanov a5a405efd1 refactor(pipeline): reduce overengineering — cut reading burden
skill/SKILL.md: remove Step 5.5 Self-Critique (agents couldn't verify
visuals via snapshots anyway; step was theoretical without visual feedback)

step-1-design.md: 9 sections → 8
- remove Responsive Behavior section (video is fixed 1920x1080)
- remove Inputs/Forms, Navigation, Links from Component Stylings
  (these are never used in video compositions)
- rename and keep Agent Prompt Guide (most-consulted section per docs)
- remove 200-400 line target (was driving padding)

step-3-storyboard.md: remove Implementation References per-beat block
- was the most verbose part of the storyboard template
- sub-agent template in step-5 already handles targeted file reads
- agents were filling it mechanically without adding value

evidence: v2+v3 agents reporting 40% of session time spent reading docs;
storyboard writing cited as second biggest time sink
2026-05-16 06:48:36 -07:00
ukimsanov ebdc8d3725 fix(pipeline): loom v3 fixes, HeyGen v3 API, snapshot auto-clear, beat timing docs
snapshot: auto-clear png/jpg files before each run so old frames don't
mix into contact sheets (confirmed issue from loom v3 agent report)

step-4-vo: update HeyGen TTS to v3 API (current; v1/v2 deprecated Oct 2026)
- list voices: GET /v3/voices?engine=starfish, response is data[] direct list
- generate: POST /v3/voices/speech, returns audio_url + word_timestamps
- HeyGen v3 no longer needs separate transcription step
- v2 data.voices shape documented as legacy

step-5-build RULES: add HyperShader+beat timing rules from v3 findings
- timeline:tl pattern breaks scrubber — let HyperShader create timeline
- proxy+onUpdate doesn't fire in seek mode — use discrete tl.set() calls
- shader name validation: check ls registry/blocks/ before writing

step-3-storyboard: add Beat Timing section to each beat template
- agents specify transition-in time + GSAP duration so step-5 can set
  data-start and data-duration without guessing
2026-05-16 06:26:05 -07:00
ukimsanov d7d0ee6e6a docs: update HANDOFF with v3 run results and new P0 findings 2026-05-16 05:11:50 -07:00
ukimsanov ba9aa4c791 docs: data-start rule in sub-agent RULES, v3 feedback with arc root cause 2026-05-16 05:05:21 -07:00
ukimsanov f74beb8362 fix(pipeline): document data-start/data-duration rule for HyperShader beats
root cause verified from arc-launch v3 render analysis:
- all beats had data-start=0 and data-duration=26 (total video length)
- engine seeks each beat's sub-composition to global_time - data_start
- with data-start=0, beat-2 (BEAT=5.5s GSAP) is seeked to global_t=7
- gsap timeline exhausted at t=5.5, engine marks sub-comp invisible
- content disappears exactly at each beat's GSAP timeline end

fix verified: sequential data-start per transition point + data-duration
matching each beat's GSAP duration → all beats render correctly

added concrete code example to step-5-build.md with explanation
2026-05-16 04:40:25 -07:00
ukimsanov a2ccc1e6fa fix(pipeline): transcript CWD footgun and template script/style rules
cli/transcribe: default output dir to dirname(inputPath) instead of CWD
- transcript.json now lands next to narration.wav regardless of CWD
- fixes silent stale-transcript poisoning when running from repo root

step-5 sub-agent RULES: script+style inside template (verified root causes)
- mercury v3: scripts outside template caused ALL GSAP to silently fail
- workos v3: CSS style blocks inside template not applied after injection
- expanded querySelector null guard: getTotalLength crash documented
2026-05-16 04:20:13 -07:00
ukimsanov ca4c5cc18e docs: add v3 agent feedback with root cause analysis and cross-iteration comparison 2026-05-16 04:06:53 -07:00
ukimsanov 8db7300bda docs: mark v3-prep fixes in agent feedback status table 2026-05-16 02:19:31 -07:00
ukimsanov 36953172bf fix(pipeline): sfx timing rules, font wiring, asset paths, captions, kokoro
step-3: sfx placement rules grounded in audio production standards
- impact sounds: trigger at visual moment, let decay tail bleed (J-Cut)
- riser/build-up: trigger at climax_time - sfx_duration so peak lands on moment
- data-duration must equal manifest duration, never trimmed to fit beat time
- volume under narration: 0.2-0.3 max (no auto-ducking in HyperFrames)
- vo start timing: explicit storyboard decision, document in Global Direction

step-5: asset path rule as first sub-agent rule, impossible to miss
- @font-face: paste declaration into sub-agent prompt explicitly
- Inter Variable -> Inter (compiler only maps base name)
- querySelector null guard: getElementById for elements inside beat hosts
- wcag gradient false positive: data-layout-ignore for decorative elements
- captions stacking: initial opacity:0, one group visible, verify with snapshot

step-4: kokoro pronunciation guidance
- known failure patterns: Vercel, WorkOS, One API
- phonetic substitution workflow: test first sentence, fix in narration.txt
2026-05-16 02:18:30 -07:00
ukimsanov 65533efa8e docs: update HANDOFF and feedback doc with v2 run fixes and status 2026-05-16 01:59:25 -07:00
ukimsanov f8e733b976 fix(pipeline): snapshot wait, SFX ownership, VO timing, optional shader
snapshot: fix two shader pre-render wait failure modes
- Cold cache: overlay stays in DOM as display:none after hiding,
  element-absence check never resolved, always timed out at 60s
- Warm cache: IndexedDB hydration runs without overlay, absence check
  resolved instantly while prewarming was still in progress
- Fix: primary signal is window.__hf.shaderTransitions[].ready;
  overlay display:none is fallback for older builds
- Verified: huly-promo snapshots show composition content, not loader

shader-transitions: optional shader field for CSS crossfade mixing
- TransitionConfig.shader is now optional (ShaderName | undefined)
- Omitting shader = smooth CSS opacity crossfade via fallback path
- CSS-only transitions skip program compilation and prewarming
- HfTransitionMeta.shader made optional in engine/src/types.ts
- Verified: mixed CSS + WebGL composition renders all three beats correctly

step-3-storyboard: SFX assigned here with exact files, not in Step 5
- Agent reads sfx/manifest.json and assigns exact filenames per moment
- Less-is-more: most beats need zero SFX, one max per beat
- Removed duplicate HTML-in-Canvas API detail (build concern, not storyboard)

step-5-build: implement storyboard SFX exactly, zero creative decisions

step-4-vo: required timing reconciliation gate before Step 5
- Compare real audio vs planned total; if delta >15% rescale or trim
- Hard cap on CTA hold: 2-3s after last word, not extended dead silence
2026-05-16 01:55:39 -07:00
ukimsanov f4f6739510 docs: add HANDOFF.md, agent feedback, and CLAUDE.md session header
- HANDOFF.md: 747-line context doc for the May 15-16 pipeline quality session
  (git state, all skill changes, eval arena, video locations, key discoveries)
- AGENT-FEEDBACK-V2.md: 7-agent post-run friction report with priority action
  items (P0: HyperShader CSS crossfade bug, snapshot loading-screen blindspot)
- CLAUDE.md: add READ HANDOFF.md FIRST notice at top for new sessions
2026-05-16 00:55:09 -07:00
ukimsanov 309a641c38 chore: gitignore review-package and scratch files; fix SKILL.md step-1 gate 2026-05-15 23:11:58 -07:00
ukimsanov a80f761c48 chore(skills): remove old pipeline files left over from prior commits
Old step files from before the pipeline v2 restructure were still tracked
alongside the new versions, causing agents to see a conflicting dual pipeline.
Removed: step-1-capture, step-4-storyboard, step-5-vo, step-6-build,
step-7-validate, composition-guide, generate-skeleton.mjs
2026-05-15 22:51:20 -07:00
ukimsanov 91c16cd00b chore(skills): remove deprecated step-2-design and step-3-script files
These were superseded by the new 7-step pipeline structure in the
website-to-hyperframes skill restructure.
2026-05-15 22:28:54 -07:00
ukimsanov d895bdb94f feat(skills): website-to-hyperframes pipeline v2
- SKILL.md: creative tension principle, Step 5.5 self-critique, vision note
- visual-vocabulary.md: inverted to brand-cues→dimensions (replaces user-words→recipes table)
- step-0-capture.md: paginated contact sheet filenames, tighten individual asset reads
- step-1-design.md: user gate after DESIGN.md, generic-vs-specific iteration guide examples
- step-2-brief.md: personalized capabilities pitch + Q2/Q3 anti-prescriptive rewrites
- step-3-storyboard.md: creative tension check, Text Animations + Implementation References per beat
- step-4-vo.md: HeyGen TTS first, music gap for non-narrated videos
- step-5-build.md: agent-agnostic sub-agents, captions stub ban, orphaned comp check
- step-6-validate.md: snapshot formula max(beats×3, ceil(duration/2)), density vs storyboard spec
- capabilities.md: fix VFX count, add text-effects reference
- html-in-canvas-patterns.md: Three.js 0.147→0.181.2 ESM, Math.random→mulberry32
2026-05-15 22:07:18 -07:00
ukimsanov e643d8827d feat(skills): hyperframes core — remove prescriptive tables, fix tone, bundle text-effects
- visual-styles.md: replace YAML recipes with design tradition descriptions + pitfalls
- visual-vocabulary.md moved to w2h skill; house-style.md light/dark mapping removed
- transitions.md: Energy table converted to motion qualities; Mood table to characteristics
- beat-direction.md: rhythm table removed; verb table restructured by physical character
- dynamic-techniques.md: energy table restructured with explanatory principles
- motion-principles.md: replace shouty tone with common-defaults framing
- typography.md: replace guardrails with defaults-to-watch-for framing
- video-composition.md: fix density contradiction (3-layer rule vs 8-10 target)
- techniques.md: remove When-to-Use-What table; fix Lottie package name
- text-effects.md (new): 24 bundled text animation effects with GSAP specs
- assets/text-effects/ (new): full JSON specs for all 24 effects
2026-05-15 22:04:53 -07:00
ukimsanov 3cffd37386 fix(cli): paginated contact sheets, fit-contain, SVG root scan, semantic colors
- contactSheet.ts (new): paginated grids for all asset types
- fit:contain replaces fit:cover — no more aspect-ratio cropping
- SVG scanner covers both assets/svgs/ and assets/ root directories
- agentPromptGenerator: semantic color role labels + dynamic page listing
- snapshot.ts: updated for string[] return from contact sheet functions
2026-05-15 21:36:50 -07:00
ukimsanov d4f18acb0a feat(skills): add SFX manifest, device models, and local CLI documentation
- Add 20 SFX files to website-to-hyperframes/assets/sfx/ with manifest.json
- Add device GLTF models (iphone.glb, macbook.glb) and reference images
- CLAUDE.md: document local CLI path for capture, snapshot, and shader-transitions
- .gitignore: update patterns
2026-05-15 21:34:50 -07:00
ukimsanov 9af33071d3 feat(skills): add skeleton generator for website-to-hyperframes pipeline
Generates pre-valid index.html + composition templates from STORYBOARD.md.
Bakes in: position:absolute, HyperShader wiring, autoAlpha toggles,
SFX placement from manifest, narration audio, grain overlays, scene
visibility management.

Sub-agents only fill creative content — no pipeline mechanics to learn.
Follows the claude-design-hyperframes.md pattern: code handles structure,
AI handles creativity.

Tested: passes lint with 0 errors on first generation.
2026-05-11 01:51:00 -07:00
ukimsanov a8e470bb9c fix(cli): wait for shader loading overlay before snapshots + fix svgs/ captioning
Snapshot: HyperShader shows a loading overlay ([data-hyper-shader-loading])
while pre-rendering transition frames. Snapshots taken during loading show
"Preparing scene transitions" instead of content. Now waits up to 60s for
the overlay to disappear before capturing.

SVG captioning: Gemini captions for svgs/ subdirectory were generated but
never used in asset-descriptions.md. The generateAssetDescriptions function
had a separate code path for svgs/ that used bare "icon:" labels instead
of checking geminiCaptions. Now checks geminiCaptions first.
2026-05-11 01:09:49 -07:00
ukimsanov b1f773178a fix(skills): improve CTA beat guidance and remove implicit beat count
CTA beats are consistently under-animated (13 GSAP calls for 8-second
duration in v3 tests). Added explicit guidance: treat CTA with same
animation density as feature beats, minimum 15 GSAP calls, logo entrance
as an event not a fade.

Also clarified that beat count is agent's decision based on content —
no fixed number.
2026-05-10 21:21:44 -07:00
ukimsanov f14c781075 feat(skills): add SFX manifest with durations and AI descriptions
Created manifest.json for all 19 SFX files with exact duration from
ffprobe and Gemini audio analysis description. Updated Step 6 to
reference manifest instead of generic moment-type table.
2026-05-10 21:07:10 -07:00
ukimsanov aec70f8b57 fix(skills): add critical position:absolute CSS for beat host divs
Root cause of snapshot seeking bug: without position:absolute, beat divs
stack vertically in normal flow. The runtime sets visibility:hidden/visible
to toggle beats, but this only works when beats overlap in the same frame.

Verified: with position:absolute + local CLI, snapshots at t=15 correctly
show beat-4 content instead of beat-1 stuck at every timestamp.
2026-05-10 21:00:17 -07:00
ukimsanov 921d3d24b4 feat(skills): add verified shader transition pattern for sub-compositions
Tested and confirmed: shader transitions work with sub-composition
pipelines. The pattern:
1. Add class="scene" to beat host divs in index.html
2. Load shader-transitions CDN script
3. Call HyperShader.init() with host div IDs and transition configs
4. Engine detects window.__hf.transitions and composites with shaders

Verified with minimal test: cross-warp-morph between two sub-compositions
rendered successfully (layered composite, 180 frames, SDR).
2026-05-10 20:37:30 -07:00
ukimsanov a8ece0dacd fix(skills): address 4 root causes from transcript analysis
1. Capabilities Discovery: replace descriptive guidance with executable
   commands (npx hyperframes list, ls registry/blocks/). Agent was told
   to "check" but never ran the commands — now it has exact bash to run
   and paste results.

2. SFX decoupled from storyboard: removed SFX listing from Step 4
   Capabilities Audit. SFX are now wired in Step 6 Audio Wiring only,
   matched to the storyboard's creative moments. Prevents creative
   direction from revolving around the SFX inventory.

3. Font @font-face: rewritten to explain the auto-resolve system.
   Common fonts (Inter, Roboto, etc.) skip @font-face. Brand fonts
   use tokens.json for family mapping. Hashed filenames = Google Fonts
   subsets that auto-resolve. Prevents agents from giving up on hashed
   filenames.

4. SFX wiring table: added moment-type → SFX mapping so agents match
   sound to emotion instead of listing files arbitrarily.
2026-05-10 20:13:01 -07:00
ukimsanov 0cdbe0311e fix(core): font lint rule skips producer-bundled fonts
The producer's deterministicFonts.ts pre-bundles 18 font families as
data URIs (Inter, Roboto, JetBrains Mono, etc.). The lint rule was
falsely flagging these as missing @font-face. Now only warns for fonts
not in the pre-bundled FONT_ALIASES list — brand-specific fonts like
GT Walsheim or Aeonik that the producer genuinely can't resolve.

Fonts available via Google Fonts (Path 2) still trigger warnings since
they require network access at render time and may fail in sandboxed
environments.
2026-05-10 20:13:01 -07:00