mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-07 18:26:17 +00:00
Miguel Ángel
68bd52ac6d
## Problem Users who want Tailwind utilities in a plain HyperFrames composition currently have to know which Tailwind browser script to add and where to place it. The first pass added `--tailwind`, but review caught three production-facing gaps: the CDN version was major-only, the insertion helper could silently no-op on compact HTML, and the render pipeline did not explicitly wait for Tailwind's async browser compilation before capturing frame 0. There is also a version-specific agent risk: HyperFrames `init --tailwind` uses Tailwind v4.2 through `@tailwindcss/browser@4.2.4`, while `packages/studio` still uses Tailwind v3. Without a dedicated skill, agents can easily mix v3 `tailwind.config.js` / `@tailwind` patterns into v4 browser-runtime composition HTML. ## What this fixes - Adds `hyperframes init --tailwind`. - Pins the Tailwind browser runtime to `@tailwindcss/browser@4.2.4/dist/index.global.js` with SRI and `crossorigin="anonymous"`. - Injects a `window.__tailwindReady` promise next to the browser runtime. - Makes frame capture wait for `window.__tailwindReady` in both screenshot and BeginFrame capture modes before capturing frame 0. - Inserts Tailwind support before `</head>` case-insensitively, including single-line/minified heads, and falls back to prepending when there is no head tag. - Skips recursive Tailwind injection under `.git`, `dist`, and `node_modules`. - Tracks whether init used Tailwind in the existing `init_template` telemetry event. - Adds a first-party `/tailwind` skill for Tailwind v4.2 browser-runtime HyperFrames composition work. - Updates README, docs, generated project agent files, CLI skill guidance, and plugin metadata so the Tailwind skill is discoverable. - Documents the browser-runtime tradeoff and production/offline guidance. ## Root cause `scaffoldProject()` copied the selected example and patched media placeholders, then immediately wrote project metadata and `package.json`. There was no optional post-copy step for framework-specific HTML support. The initial Tailwind post-copy step also treated the browser runtime like a static script, but Tailwind compiles utilities asynchronously after scanning the DOM, so the capture engine needed an explicit readiness contract. On the agent side, the repo exposed HyperFrames, CLI, GSAP, registry, and runtime adapter skills, but had no Tailwind-specific instruction to separate the v4 browser-runtime composition path from Studio's v3 internal setup. ## Verification ### Local checks - `bunx vitest run packages/cli/src/commands/init.test.ts` - `bun run --filter @hyperframes/cli test src/commands/init.test.ts` - `bun run --filter @hyperframes/cli typecheck` - `bun run --filter @hyperframes/engine typecheck` - `bun run lint:skills` - `bun run lint` - `npx skills add . --list` showed 12 local skills, including `tailwind`. - `bunx oxfmt --check packages/cli/src/commands/init.ts packages/cli/src/commands/init.test.ts packages/cli/src/telemetry/events.ts packages/engine/src/services/frameCapture.ts docs/packages/cli.mdx` - `bunx oxfmt --check README.md docs/quickstart.mdx docs/packages/cli.mdx CLAUDE.md packages/cli/src/templates/_shared/CLAUDE.md packages/cli/src/templates/_shared/AGENTS.md skills/hyperframes-cli/SKILL.md skills/tailwind/SKILL.md .codex-plugin/plugin.json .cursor-plugin/plugin.json` - `bunx oxlint packages/cli/src/commands/init.ts packages/cli/src/commands/init.test.ts packages/cli/src/telemetry/events.ts packages/engine/src/services/frameCapture.ts` - `git diff --check` - Lefthook pre-commit: lint/format/typecheck for code commit; format for docs/skill commit - Lefthook commit-msg: commitlint Generated-project render proof at `/tmp/hf-tailwind-render-proof`: - `bun packages/cli/src/cli.ts init /tmp/hf-tailwind-render-proof --example blank --tailwind --non-interactive --skip-skills` - Added a temporary Tailwind-only card using `flex`, `h-full`, `w-full`, `items-center`, `justify-center`, `bg-slate-950`, `rounded-3xl`, `bg-white`, `px-20`, `py-12`, `text-8xl`, `font-black`, `text-black`, and `shadow-2xl`. - `bun packages/cli/src/cli.ts lint /tmp/hf-tailwind-render-proof` → 0 errors, 0 warnings. - `bun packages/cli/src/cli.ts validate /tmp/hf-tailwind-render-proof` → 0 errors, 0 regular warnings; the temp proof still reports validator contrast warnings even though the rendered/browser pixels show black text on white background. - `bun packages/cli/src/cli.ts render /tmp/hf-tailwind-render-proof --workers 1 --fps 24 --quality draft --output /tmp/hf-tailwind-render-proof-artifacts/output.mp4` - Render compiler inlined both GSAP and `https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4.2.4/dist/index.global.js`. - `ffprobe -v error -select_streams v:0 -show_entries stream=codec_name,width,height,r_frame_rate,duration -of default=noprint_wrappers=1 /tmp/hf-tailwind-render-proof-artifacts/output.mp4` → H.264, 1920x1080, 24fps, 10s. - Extracted frame-0 proof: `/tmp/hf-tailwind-render-proof-artifacts/frame-000.png`. ### Browser verification - Started Studio preview for `/tmp/hf-tailwind-render-proof`. - Used `agent-browser` to open `http://localhost:5194`. - Verified the Tailwind-styled composition rendered in Studio preview. - Captured screenshot: `/tmp/hf-tailwind-render-proof-artifacts/browser/tailwind-preview.png`. - Captured agent-browser-driven recording: `/tmp/hf-tailwind-render-proof-artifacts/browser/tailwind-preview.webm`. - Served the PR worktree locally and used `agent-browser` to open the new Tailwind skill proof page. - Verified the browser-visible skill content includes `@tailwindcss/browser@4.2.4`. - Captured screenshot: `/Users/miguel07code/.codex/worktrees/pr-577-tailwind-comments/tmp/agent-browser-proof/tailwind-skill.png`. - Captured agent-browser-driven recording: `/Users/miguel07code/.codex/worktrees/pr-577-tailwind-comments/tmp/agent-browser-proof/tailwind-skill.webm`. ## Notes - This still intentionally uses Tailwind's browser runtime rather than adding a generated Tailwind build pipeline. That keeps `hyperframes init --tailwind` small and compatible with the current no-install generated project workflow. - The `/tailwind` skill cites official Tailwind v4 docs plus community skill references, but its instructions are HyperFrames-specific and tuned for the pinned v4.2 browser runtime. - Browser proof artifacts are local-only under `/tmp/hf-tailwind-render-proof-artifacts/` and `tmp/agent-browser-proof/` and intentionally not committed.
154 lines
7.1 KiB
Markdown
154 lines
7.1 KiB
Markdown
---
|
|
name: hyperframes-cli
|
|
description: HyperFrames CLI tool — hyperframes init, lint, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting, validating, inspecting visual layout in compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, or troubleshooting the HyperFrames environment.
|
|
---
|
|
|
|
# HyperFrames CLI
|
|
|
|
Everything runs through `npx hyperframes`. Requires Node.js >= 22 and FFmpeg.
|
|
|
|
## Workflow
|
|
|
|
1. **Scaffold** — `npx hyperframes init my-video`
|
|
2. **Write** — author HTML composition (see the `hyperframes` skill)
|
|
3. **Lint** — `npx hyperframes lint`
|
|
4. **Visual inspect** — `npx hyperframes inspect`
|
|
5. **Preview** — `npx hyperframes preview`
|
|
6. **Render** — `npx hyperframes render`
|
|
|
|
Lint and inspect before preview. `lint` catches missing `data-composition-id`, overlapping tracks, and unregistered timelines. `inspect` opens the rendered composition in headless Chrome, seeks through the timeline, and reports text spilling out of bubbles/containers or off the canvas.
|
|
|
|
## Scaffolding
|
|
|
|
```bash
|
|
npx hyperframes init my-video # interactive wizard
|
|
npx hyperframes init my-video --example warm-grain # pick an example
|
|
npx hyperframes init my-video --video clip.mp4 # with video file
|
|
npx hyperframes init my-video --audio track.mp3 # with audio file
|
|
npx hyperframes init my-video --example blank --tailwind # with Tailwind v4 browser runtime
|
|
npx hyperframes init my-video --non-interactive # skip prompts (CI/agents)
|
|
```
|
|
|
|
Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decision-tree`, `kinetic-type`, `product-promo`, `nyt-graph`.
|
|
|
|
`init` creates the right file structure, copies media, transcribes audio with Whisper, and installs AI coding skills. Use it instead of creating files by hand.
|
|
|
|
When using `--tailwind`, invoke the `tailwind` skill before editing classes or theme tokens. The scaffold uses Tailwind v4.2 via the browser runtime, not Studio's Tailwind v3 setup.
|
|
|
|
## Linting
|
|
|
|
```bash
|
|
npx hyperframes lint # current directory
|
|
npx hyperframes lint ./my-project # specific project
|
|
npx hyperframes lint --verbose # info-level findings
|
|
npx hyperframes lint --json # machine-readable
|
|
```
|
|
|
|
Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (with `--verbose`).
|
|
|
|
## Visual Inspect
|
|
|
|
```bash
|
|
npx hyperframes inspect # inspect rendered layout over the timeline
|
|
npx hyperframes inspect ./my-project # specific project
|
|
npx hyperframes inspect --json # agent-readable findings
|
|
npx hyperframes inspect --samples 15 # denser timeline sweep
|
|
npx hyperframes inspect --at 1.5,4,7.25 # explicit hero-frame timestamps
|
|
```
|
|
|
|
Use this after `lint` and `validate`, especially for compositions with speech bubbles, cards, captions, or tight typography. It reports:
|
|
|
|
- Text extending outside the nearest visual container or bubble
|
|
- Text clipped by its own fixed-width/fixed-height box
|
|
- Text extending outside the composition canvas
|
|
- Children escaping clipping containers
|
|
|
|
Errors should be fixed before rendering. Warnings are surfaced for agent review; add `--strict` to fail on warnings too. Repeated static issues are collapsed by default so JSON output stays compact for LLM context windows. If overflow is intentional for an entrance/exit animation, mark the element or ancestor with `data-layout-allow-overflow`. If a decorative element should never be audited, mark it with `data-layout-ignore`.
|
|
|
|
`npx hyperframes layout` remains available as a compatibility alias for the same visual inspection pass.
|
|
|
|
## Previewing
|
|
|
|
```bash
|
|
npx hyperframes preview # serve current directory
|
|
npx hyperframes preview --port 4567 # custom port (default 3002)
|
|
```
|
|
|
|
Hot-reloads on file changes. Opens the studio in your browser automatically.
|
|
|
|
When handing a project back to the user, use the Studio project URL, not the
|
|
source `index.html` path:
|
|
|
|
```text
|
|
http://localhost:<port>/#project/<project-name>
|
|
```
|
|
|
|
Use the actual port from the preview output and the project directory name. For
|
|
example, after `npx hyperframes preview --port 3017` in `codex-openai-video`,
|
|
report `http://localhost:3017/#project/codex-openai-video`.
|
|
|
|
Treat `index.html` as source-code context only. It is fine to link it as an
|
|
implementation file, but do not label it as the project or preview surface.
|
|
|
|
## Rendering
|
|
|
|
```bash
|
|
npx hyperframes render # standard MP4
|
|
npx hyperframes render --output final.mp4 # named output
|
|
npx hyperframes render --quality draft # fast iteration
|
|
npx hyperframes render --fps 60 --quality high # final delivery
|
|
npx hyperframes render --format webm # transparent WebM
|
|
npx hyperframes render --docker # byte-identical
|
|
```
|
|
|
|
| Flag | Options | Default | Notes |
|
|
| -------------- | --------------------- | -------------------------- | --------------------------- |
|
|
| `--output` | path | renders/name_timestamp.mp4 | Output path |
|
|
| `--fps` | 24, 30, 60 | 30 | 60fps doubles render time |
|
|
| `--quality` | draft, standard, high | standard | draft for iterating |
|
|
| `--format` | mp4, webm | mp4 | WebM supports transparency |
|
|
| `--workers` | 1-8 or auto | auto | Each spawns Chrome |
|
|
| `--docker` | flag | off | Reproducible output |
|
|
| `--gpu` | flag | off | GPU-accelerated encoding |
|
|
| `--strict` | flag | off | Fail on lint errors |
|
|
| `--strict-all` | flag | off | Fail on errors AND warnings |
|
|
|
|
**Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery.
|
|
|
|
## Transcription
|
|
|
|
```bash
|
|
npx hyperframes transcribe audio.mp3
|
|
npx hyperframes transcribe video.mp4 --model medium.en --language en
|
|
npx hyperframes transcribe subtitles.srt # import existing
|
|
npx hyperframes transcribe subtitles.vtt
|
|
npx hyperframes transcribe openai-response.json
|
|
```
|
|
|
|
## Text-to-Speech
|
|
|
|
```bash
|
|
npx hyperframes tts "Text here" --voice af_nova --output narration.wav
|
|
npx hyperframes tts script.txt --voice bf_emma
|
|
npx hyperframes tts --list # show all voices
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
```bash
|
|
npx hyperframes doctor # check environment (Chrome, FFmpeg, Node, memory)
|
|
npx hyperframes browser # manage bundled Chrome
|
|
npx hyperframes info # version and environment details
|
|
npx hyperframes upgrade # check for updates
|
|
```
|
|
|
|
Run `doctor` first if rendering fails. Common issues: missing FFmpeg, missing Chrome, low memory.
|
|
|
|
## Other
|
|
|
|
```bash
|
|
npx hyperframes compositions # list compositions in project
|
|
npx hyperframes docs # open documentation
|
|
npx hyperframes benchmark . # benchmark render performance
|
|
```
|