On hover the thumbnail slot swaps from the static extracted frame to a
live muted looping video in the same w-20 h-[45px] cell — no overlay,
no expansion. Static frame fades out (150ms opacity) as the video takes
over; video is only mounted while hovered so it doesn't run in the
background.
Extracted shared ExpandedVideoPreview component (src/components/ui/)
used by both AssetsTab (video assets) and RenderQueueItem (rendered
videos). Wraps completed render rows in ExpandOnHover with the same
spring-expand + video autoplay pattern as the Compositions and Assets
tabs. No code duplication: AssetsTab video case delegates to the shared
component, RenderQueueItem reuses it with an Open action button.
Extracts a first-representative-frame from the rendered MP4 using a
hidden video + canvas (same technique as VideoThumbnail). The thumbnail
cell matches CompCard's w-20 h-[45px] sizing so Renders, Compositions,
and Assets tabs all share the same visual language. Rendering/failed/
cancelled rows show a status indicator in the thumbnail slot instead.
The video[src][data-start] selector excluded production compositions
whose video elements have id+src but no data-start, breaking all visual
frames while audio passed. Now unions both selectors so videos are
discovered if they match either video[id][src] (original) or
video[src][data-start] (sub-composition without explicit id).
Clicking a completed render row now opens the video inline in the
browser instead of forcing a download. Added /render/:jobId/view
endpoint with Content-Disposition: inline so the browser plays the
video natively. Download button is preserved on hover for explicit
saves. stopPropagation on action buttons prevents row click conflicts.
When bundleToSingleHtml inlined sub-compositions, external <script src>
tags were silently dropped because $content(s).html() returns "" for
external scripts. This caused CDN libraries like lottie-web loaded only
in a sub-composition to be missing from the bundle, breaking animations.
Now external script URLs are collected and deduped into the bundle,
preserving CDN dependencies from any sub-composition.
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
parseVideoElements used "video[id][src]" which silently excluded video
elements without an id attribute — common in sub-compositions. Changed
selector to "video[src][data-start]" and auto-assign stable ids for
any video that lacks one, so the frame injection pipeline processes all
timed video clips.
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
The CLI adapter was missing generateThumbnail, so the thumbnail route
always returned 501 and composition thumbnails showed as blank black
rectangles in both the Compositions sidebar and the Timeline.
The SSE progress stream already sent error details on failure but
the client never stored or displayed them. Failed renders now show
the error message below the status indicator, matching the detail
level of the CLI render command.
Two issues caused GSAP-controlled Lottie animations to display at the
wrong frame or not at all:
1. Adapter order: Lottie ran after GSAP, overriding the correct frame
from GSAP's onUpdate with wrong absolute-time ms.
Fix: move Lottie before GSAP so GSAP's onUpdate fires last and wins.
2. play() conflict: adapter called anim.play() causing Lottie to
advance independently, fighting GSAP's goToAndStop scrubbing.
Fix: remove play() from the Lottie adapter (it is optional).
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
When a root composition declares data-duration="5" but the captured
GSAP timeline only has 3s of content, playback stopped at 3s.
resolveRootTimelineFromDocument now pads the timeline with a duration
floor tween to match the declared data-duration, so the composition
plays for its full declared length.
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
The static asset server was responding 200 OK with the full file for
all requests, including browser Range requests. Browsers send Range
requests when seeking audio/video elements; without 206 Partial
Content responses the seek fails silently and audio goes silent.
Now responds with 206 + Content-Range for byte-range requests and
always includes Accept-Ranges + Content-Length headers.
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
The download endpoint only checked the in-memory renderJobs map, which
is empty after a server restart. The list endpoint now registers on-disk
renders into the map when it serves them, so subsequent download
requests find the correct output file.
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
The spread operator created a shallow copy of jobState at call time.
Async mutations to the original state (progress, status) were never
reflected in the copy stored in renderJobs, so the SSE stream always
emitted progress:0.
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
## Summary
- **Lint rules** catch media elements missing `id` (renderer silently skips them), missing `src`, `preload="none"` (blocks renderer), and video nested in timed divs (freezes playback). Upgraded `video_nested_in_timed_element` from warning to error.
- **Compiler** strips `preload="none"` from media during compilation. Runs parallel, cached keyframe interval analysis via ffprobe — warns on sparse keyframes (>2s) that cause seek failures and audio/video desync. Suggested ffmpeg command preserves audio (`-c:a copy`).
- **Pre-render lint** lints `index.html` + all `compositions/*.html` sub-compositions before render via shared `lintProject()` helper. Warns by default; `--strict` blocks on errors, `--strict-all` blocks on errors + warnings.
- **Render orchestrator** logs a hint to retry with `--workers 1` when parallel capture times out on video-heavy compositions.
- **Refactor**: extracted `runFfprobe()` + `parseProbeJson()` helpers to deduplicate ~80 lines of spawn boilerplate across 3 ffprobe functions. Extracted `shouldBlockRender()` so strict flag tests exercise production code. Shared `lintProject()` used by both `lint` and `render` commands.
## Context
Discovered during a real composition build session where:
1. `<audio>` without `id` rendered silently (preview worked fine because runtime queries `[data-start]`, but renderer queries `[id][src]`)
2. `<video>` inside timed `<div>` froze on first frame
3. `preload="none"` caused 45s renderer timeout
4. YouTube clips with sparse keyframes from `yt-dlp --download-sections` caused audio/video desync
5. Parallel workers timed out on video-heavy compositions
## Test plan
- [x] Core: 365/365 tests passing (5 new lint tests)
- [x] Engine: 24/24 tests passing
- [x] CLI: 14/14 tests passing (7 lintProject + 7 shouldBlockRender)
- [x] Lint + format hooks pass
- [ ] Manual: create a composition with `<audio data-start="0" src="test.wav">` (no id) — verify `npx hyperframes lint` catches it
- [ ] Manual: run `npx hyperframes render --strict` with lint errors — verify it blocks
- [ ] Manual: run `npx hyperframes render --strict-all` with lint warnings — verify it blocks
## Summary
- Surfaces error message when render fails due to producer server not running
- Two cases covered: initial POST failure and SSE connection drop
- Failed jobs now show the error reason in red text in the Renders panel
## Test plan
- [x] Start studio without producer server
- [x] Click render → should show "Could not reach render server" in red
- [x] Start render then kill producer → should show "Connection lost"
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Summary
- `hyperframes lint` now scans ALL HTML files in the project (not just index.html)
- Includes composition files in `compositions/` directory
- `--json` output includes `file` field and `filesScanned` count
- Exit code 1 on errors for CI integration
## Examples
```bash
# Human-friendly output
hyperframes lint
# Agent/CI-friendly JSON
hyperframes lint --json
```
## Test plan
- [ ] `hyperframes lint` on a project with compositions → shows findings from all files
- [ ] `hyperframes lint --json` → outputs valid JSON with all findings
- [ ] Exit code 1 when errors found, 0 when clean
## Summary
- When running `hyperframes dev .` inside a symlinked directory, the project name showed the resolved target name instead of the visible directory name
- Now uses `$PWD` to preserve the user-facing name
- Added `projectName` option to `StudioServerOptions` for explicit override
## Test plan
- [ ] `ln -s /path/to/project my-project && cd my-project && hyperframes dev .` → should show "my-project"
- [ ] `hyperframes dev /path/to/project` → should show "project" (basename of path)
## Summary
- Replaces ~850 lines of inline route handlers in `vite.config.ts` with the shared `createStudioApi(adapter)` module
- Implements `StudioApiAdapter` for the Vite dev server context (SSR-loaded bundler/linter, producer HTTP proxy, Puppeteer thumbnails)
- Bridges Hono `fetch()` to Vite's Connect middleware with streaming support for SSE
Now **both** consumers (CLI + studio) use the same shared API module, ensuring feature parity.
## Test plan
- [x] `pnpm --filter @hyperframes/studio dev` starts correctly
- [x] Home page shows project grid with thumbnails
- [x] Preview plays with correct fonts/animations
- [x] Sub-composition drill-down works
- [x] Lint modal shows findings
- [x] File read/write works in code editor
- [x] Render queue works (requires producer server)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Summary
Extracts all studio API routes into a shared Hono-based module at `@hyperframes/core/studio-api`.
### Architecture
- **`StudioApiAdapter` interface** — consumers inject host-specific behavior (project resolution, bundling, rendering, thumbnails)
- **Shared route modules**: projects, files, preview, lint, render, thumbnail
- **Shared helpers**: `isSafePath`, `walkDir`, `getMimeType`, `buildSubCompositionHtml`
### What this PR does
- Creates the shared module with all API routes extracted from both `vite.config.ts` and `studioServer.ts`
- Both consumers will be refactored in follow-up commits to mount this module with their own adapter
### What stays in each consumer
- **Vite**: SSR module loading, Puppeteer thumbnails, file watcher + HMR, producer HTTP proxy, multi-project scanning
- **CLI**: in-process `executeRenderJob`, local runtime serving, browser management, SPA static file serving
### Follow-up needed
- [ ] Refactor `packages/studio/vite.config.ts` to use `createStudioApi(adapter)` via `@hono/node-server`'s `getRequestListener`
- [ ] Refactor `packages/cli/src/server/studioServer.ts` to use `createStudioApi(adapter)`
- [ ] Add `./studio-api` export path to `packages/core/package.json`
- [ ] Add `hono` as peer dependency of `@hyperframes/core`
## Test plan
- [ ] Verify shared module compiles without type errors
- [ ] After consumer refactoring: all studio features work identically via both vite dev and CLI embedded servers
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Summary
- Composition HTML files are always wrapped in `<template id="...">` tags
- The linter was checking the raw HTML including the template wrapper, causing false positives:
- `missing-composition-id` on files that have it inside `<template>`
- `missing-dimensions` on files that have `data-width`/`data-height` inside `<template>`
- Fix: strip `<template>` wrapper before linting, matching how the runtime and preview server handle these files
## Test plan
- [x] Added test: `strips <template> wrapper before linting composition files`
- [x] All 345 existing tests pass
- [ ] Verify lint panel no longer shows false positives for composition files
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Summary
- CLI render: use timestamped filenames (`project_date_time.ext`) matching the studio's naming convention, preventing overwrites of previous renders
- studioServer: read `fps`/`quality`/`format` from POST body instead of hardcoding `fps:30`/`quality:standard`/`mp4`
- studioServer: use timestamped job IDs matching the studio pattern
- studioServer: fix download endpoint to serve correct content-type for WebM
## Test plan
- [x] `hyperframes render --format webm` outputs timestamped WebM file
- [x] `hyperframes render` outputs timestamped MP4 (no overwrite)
- [x] Studio embedded server (`hyperframes dev`) renders with correct format when selected in UI
- [x] Download endpoint serves correct MIME type for WebM renders
## Summary
- Add render queue panel with progress tracking, download, and delete actions
- Restructure App layout: home page with project picker, session-based routing
- Add ExpandOnHover component for preview-on-hover interactions (uses motion/react)
- CompositionsTab now supports hover preview with expanded iframe view
- Vite config: guard setInterval cleanup to dev-only (fixes CI build timeout)
- Add favicon and update studio package deps
## Test plan
- [x] Render queue shows progress, completes, and allows download
- [x] Home page lists projects and navigates to session view
- [x] ExpandOnHover shows expanded preview on mouse hover with spring animation
- [x] `vite build` exits cleanly (no hanging process from setInterval)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Summary
- Add collapsible left sidebar with Compositions and Assets tabs
- Compositions tab lists all sub-compositions with thumbnail previews and navigation
- Clicking a composition opens it in the code editor AND navigates the preview to show that composition
- Assets tab categorizes project files by type (images, fonts, media)
- Race condition guard on composition fetch with functional state update
- Thumbnail error fallback shows name initial instead of empty box
## Test plan
- [x] Sidebar opens/closes with smooth transition
- [x] Compositions tab lists files from project API
- [x] Clicking a composition changes the preview iframe to that composition
- [x] Assets tab categorizes files by type
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Summary
- Replace Split/Delete buttons with Edit Range toolbar
- Edit button opens a time-range selection on the timeline
- "Copy to Agent" exports the selected range as a prompt-ready description
- Range selection shows start/end times with drag handles
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Summary
- **NLELayout**: Add toolbar slot, composition breadcrumb navigation, improved responsive layout
- **Vite config**: Add full project API (preview, thumbnail, render, file CRUD) for standalone dev mode
- Remove AgentActivityTrack component (replaced by timeline clips)
- Add HTML editor utilities for composition source editing
- Guard setInterval cleanup to dev-only to prevent `vite build` from hanging in CI
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Summary
- Add zoom state (zoomMode, pixelsPerSecond) to player store
- Add timeline element updates (setElements, clearElements)
- Remove unused/duplicate exports from player barrel file
🤖 Generated with [Claude Code](https://claude.com/claude-code)
* feat(cli): add system metrics to telemetry and expand doctor command
Enrich render telemetry with device/environment metadata (CPU, memory,
OS, Docker/CI/WSL detection) following patterns from Next.js and
Turborepo. Add speed_ratio (render time / composition duration),
per-frame capture timing, and resource usage to render events.
Expand the doctor command with CPU, memory, disk, /dev/shm, and
environment checks to help debug rendering issues on user machines.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(cli): invert speed_ratio to match experiment-framework convention
composition_duration / render_time — higher is better, >1 means faster
than realtime. Matches magic_edit.render.speed_ratio in experiment-framework.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(cli): wire errorMessage into render error telemetry
Address review feedback — the errorMessage field was declared in the
trackRenderError interface but never populated.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(cli): add render telemetry to embedded studio server
Track render_complete and render_error from the studio's render API
endpoint (hyperframes dev). Uses dynamic imports so telemetry is
resolved at call time within the CLI package — no telemetry coupling
added to @hyperframes/studio or @hyperframes/producer.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Namespace skill names with `hyperframes-` prefix for clearer identity in
OSS contexts where users may have other skills installed.
Updates skill directories, SKILL.md frontmatter, CLAUDE.md, README.md,
CLI build script, init command, and project template.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Changes
Added a new lint rule `gsap_css_transform_conflict` that detects when GSAP animations will silently overwrite CSS transforms.
**`gsap_css_transform_conflict` (error)** — fires when an element has `transform: translateX(-50%)` or `transform: scale()` in CSS and a GSAP `tl.to/from` tween animates `x`, `y`, `xPercent`, `yPercent`, or `scale`. GSAP silently overwrites the full CSS transform, discarding centering tricks like `translateX(-50%)`. Fix hint guides authors to the safe `fromTo` + `xPercent` pattern.
## Root cause
This bug surfaced while building compositions where title reveals were placed off-center because `tl.to("#title", { x: 0 })` stripped the `translateX(-50%)` centering from CSS.
## Test coverage
- [x] `gsap_css_transform_conflict` — `tl.to` with `x` on CSS `translateX` element → error
- [x] `gsap_css_transform_conflict` — `tl.to` with `scale` on CSS `scale()` element → error
- [x] `gsap_css_transform_conflict` — `tl.fromTo` without CSS transform → no finding
Detects querySelector/querySelectorAll calls that use template literal
variables (e.g. `${compId}`) inside script tags. The HTML bundler's
cheerio/css-what parser crashes on these during compilation, causing
silent fallback to raw HTML without runtime injection.
Severity: error (breaks bundling)
Fix: replace template literal with hardcoded composition ID string
## What
Adds 4 new composition templates and fixes structural issues across all templates.
### New templates
- **decision-tree** — animated flowchart with branching paths
- **kinetic-type** — bold kinetic typography promo
- **product-promo** — multi-scene product showcase with SVG assets (3 scenes)
- **nyt-graph** — animated data chart in NYT print editorial style
### Fixes across all templates
- GSAP updated from 3.12.2 → 3.14.2 (all templates, including warm-grain, swiss-grid, vignelli, play-mode)
- New templates restructured with proper root wrapper div, `data-duration`, sub-composition refs with `data-composition-id` / `data-width` / `data-height`
- nyt-chart: replaced `${compId}` template literal variables with hardcoded `"nyt-chart"` string — cheerio's css-what parser crashes on template literals during bundling, causing silent fallback to raw HTML without runtime injection
- nyt-chart: added DOM readiness retry for dynamically created SVG elements
- kinetic-type: removed external S3 audio URL
- All templates: GSAP script loaded in `<head>` before any scripts reference it
## Why
The new templates expand the range of content types available via `hyperframes init`. The fixes ensure all templates work correctly in the studio preview (bundler inlines sub-compositions and injects the runtime).
## Test plan
- [x] All 4 new templates render in studio preview
- [x] nyt-graph chart animates bars, line, and labels on playback
- [x] Existing templates unaffected (GSAP version bump is backwards compatible)
- [x] `hyperframes lint` passes on all templates
- [x] `generators.ts` updated with new template IDs
## Summary
- Adds `process.exit(0)` after render completes in the CLI `render` command
- Fixes the process hanging indefinitely after `npx hyperframes render --output video.mp4`
- Root cause: Node.js `fetch()` keep-alive pool (from update checks and telemetry) keeps TCP connections open, preventing the event loop from draining
- Telemetry is preserved — the `exit` handler in `cli.ts` calls `flushSync()` which spawns a detached child process
## Test plan
- [x] Run `npx hyperframes render --output test.mp4` and verify the process exits after completion
- [x] Verify telemetry events are still sent (check PostHog)
Adds a contextual menu to every docs page with options to copy page
content, open in Claude, connect via MCP to Cursor/VS Code/Windsurf,
and file a GitHub issue — all directly from the docs header.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- README quick start now leads with opening in an AI agent after init
- Quickstart docs updated: interactive wizard is default, --non-interactive
replaces --human-friendly, edit step mentions AI agent workflow
- Init "next steps" now leads with opening in an AI agent as step 1,
followed by dev preview and render as steps 2 and 3
- Interactive init shows a tip about AI agent workflow after scaffolding
- Dev command output hints that compositions can be edited with an
AI agent and changes reload automatically in the studio
The shared CLAUDE.md in scaffolded projects mentioned
hyperframes.heygen.com alongside doc topic names, causing AI agents
to guess incorrect URLs like /compositions instead of using the local
`hyperframes docs` CLI command or the correct /concepts/compositions
path. Now explicitly directs agents to use the CLI for quick reference
and llms.txt for full doc URL discovery.
- Interactive wizard is now the default when running in a TTY terminal
- Non-interactive mode (for CI/agents) uses --non-interactive flag
- Template defaults to "blank" when not specified in non-interactive mode
- --template flag skips the template picker prompt in interactive mode
- Replaces --human-friendly flag with --non-interactive (inverted logic)
Miguel Ángel