feat(studio): add Blocks panel for browsing registry blocks

[miguel-heygen]

Summary

Full Blocks panel for Studio — browse, search, add, drag-and-drop, live preview, and customize 52 registry blocks.

Phase 1: Browse & Add

• 52 blocks from the registry, 5 categories: VFX (purple), Transitions (blue), Social (pink), Data (green), Scenes (amber)
• Search bar with instant filtering by title/description
• Category filter pills to narrow results
• One-click Add — hover → click "Add" → block HTML copied to compositions/, preview refreshes

Phase 1b: Drag-and-Drop to Timeline

• Block cards are draggable with styled ghost preview label
• Drop on Timeline → copies block HTML, injects data-composition-src sub-composition at drop position
• New TIMELINE_BLOCK_MIME type following existing TIMELINE_ASSET_MIME pattern

Phase 2: Live Previews

• Animated thumbnails per block — actual composition renders in scaled iframes (1920px → 175px)
• Hover preview tooltip — 500ms hover shows 400x225px enlarged preview above the card
• Recently Used section — up to 6 recently added blocks shown as quick-access accent-colored pills

Phase 3: Block Parameters

• BlockParam interface — color, text, number, select types with CSS variable mapping
• Parameter controls — color pickers with hex display, range sliders, text inputs, select dropdowns
• Params panel appears after adding a block that has defined parameters (6 blocks have params: Liquid Glass, Liquid Background, Portal, Chart, Logo Outro)
• CSS variable injection deferred to follow-up (params currently log changes)

Files Changed

File	Change
blockCatalog.ts	BlockParam interface, params on 6 blocks
BlocksPanel.tsx	Draggable cards, thumbnails, hover preview, recently used, params panel
BlockThumbnail.tsx	New — iframe-based scaled live preview component
BlockParamsPanel.tsx	New — type-aware parameter controls (color/number/text/select)
timelineAssetDrop.ts	TIMELINE_BLOCK_MIME constant
Timeline.tsx	onBlockDrop prop, block MIME handling
NLELayout.tsx	onBlockDrop pass-through
App.tsx	handleTimelineBlockDrop, handleAddBlock, blocks panel wiring
registry.ts	/registry/blocks/:name/preview route for live thumbnails

Testing (agent-browser, Vite dev mode)

• 52 blocks render with search + category filters
• Live thumbnails load (iframe-scaled compositions)
• Click-to-add writes block to compositions/, timeline updates with sub-composition structure
• Params panel shows after adding block with params (Background color, Accent color, Speed slider)
• Recently Used section populates after add
• Drag start fires correct TIMELINE_BLOCK_MIME payload
• Registry API serves block content and HTML preview
• Zero console errors
• Build passes (lint + format + typecheck + commitlint)

🤖 Generated with Claude Code

[vanceingalls]

First review at 433c6a7b. CI is mostly "skipping" (Build, CLI smoke, Test, Typecheck, Lint, all windows) — the only run checks are WIP (pass). Required-checks coverage on this PR is effectively zero. Per Rule 5, that's a finding on its own.

Audited:

• Diff exceeded the API's 20000-line cap; couldn't pull full diff. Audited via file list (274 files) + targeted reads of the key code files (BlocksPanel.tsx, BlockThumbnail.tsx, BlockParamsPanel.tsx, blockCatalog.ts).

Trusting:

• evals/editframe/artifacts/devbox-2026-04-30/** (binary artifacts — read as "shouldn't be in this PR" not as code review)
• docs/contributing/studio-manual-dom-editing.mdx (read structure only)
• The 274-file diff in full

Blocker — --width is a literal file at the repo root

{"filename":"--width", "status":"added", "additions":0, "deletions":0, "changes":0}

gh api repos/heygen-com/hyperframes/contents/--width?ref=433c6a7b confirms there's a zero-byte file literally named --width at the repo root. This is from a stray mkdir --width or touch --width shell invocation where someone meant to pass --width as a flag and the shell parsed it as a positional arg. Should not ship — delete it before merge.

Blocker — eval artifacts (PNGs, MP4, WEBM, devbox reports) shipped in a feature PR

evals/editframe/artifacts/devbox-2026-04-30/** contains:

• 4 browser-proof PNGs + 1 WEBM screen recording
• 7+ snapshot PNGs (editframe-{1200,5000,8500,9400}ms.png, frame-00…05.png)
• editframe/index.html, editframe/render-vp9.mjs (a 96-line VP9 render script)
• HTML reports + JSON results

These are evaluation artifacts from a one-off comparison test, not source code for the Blocks panel feature this PR ships. They bloat the repo (PNGs/MP4 in git are forever) and have nothing to do with the feature in the PR title. Either move them to a separate "evals: editframe comparison" PR or to an out-of-tree artifact bucket (S3, GH release asset).

Blocker — base is next, not main; release-merge will widen the surface

baseRefName: "next". The PR targets the next branch, which presumably batches into main on a separate release cadence. That means the diff that lands on main is this + whatever else is on next at release time. The 274-file shape combined with no green required checks combined with the --width debris means a release-merge from next could ship anything in this surface area. Per Rule 8, this is the "human-approved-large-PR" failure mode — even if the Blocks-panel code is fine, the surrounding cruft sneaks in.

Recommend: clean up --width + evals artifacts before this lands on next, so the eventual next → main release has a clean surface.

Strengths (Blocks panel code, where I could read it)

• TIMELINE_BLOCK_MIME follows the existing TIMELINE_ASSET_MIME pattern in timelineAssetDrop.ts. New constant alongside existing one, no fork of the convention. ✓
• BlockParam interface (color/text/number/select) is a sensible four-type schema for the params panel. CSS variable mapping per param is the right shape for live updates.
• BlockThumbnail.tsx (new component) for iframe-scaled live previews is the right factoring — keeps the heavy scaled-iframe logic out of BlocksPanel.tsx's render loop. Should be React.memo-wrapped (Rule 6) at the boundary where the parent's state changes faster than the thumbnail's props; I couldn't verify this without reading the full file but the import line in BlocksPanel.tsx looks named-export style which suggests it's a direct functional component — worth adding memo if not.
• registry.ts adds /registry/blocks/:name/preview route for the live-iframe content — proper separation from the API surface.

Important — listener / timer cleanup audit (Rule 6) blocked by diff size

Can't audit BlocksPanel.tsx / BlockThumbnail.tsx / BlockParamsPanel.tsx for useEffect cleanup pairs (return functions matching addEventListener / setTimeout / MutationObserver) without reading the full file content. The hover-preview tooltip (500ms hover) implies a setTimeout that needs clearTimeout on unmount or hover-end; the iframe thumbnails imply a useEffect mount lifecycle that needs to clean up iframe.src = "about:blank" or remove the iframe before unmount or the browser keeps loading. If a hover starts and the user unmounts the panel mid-debounce, the timer fires against a stale ref. Highly recommend: include a grep -E "setTimeout|setInterval|addEventListener" packages/studio/src/components/blocks/ output in the PR description, with the matching cleanup site for each. Standard refactor-discipline ask per Rule 6.

Important — no test coverage for the new feature

Phase 1, 1b, 2, 3 are all called out as "tested in agent-browser, Vite dev mode." That's exploratory testing; no unit/component/E2E tests are added in the diff (file list shows 0 *.test.tsx for the new components). For a 29k-line feature, the long-term cost of zero test coverage is high — every future refactor of BlocksPanel/BlockThumbnail/BlockParamsPanel will be eyes-and-prayers.

Minimum bar: a couple of component tests for BlocksPanel.tsx (renders 52 blocks, search filter applies, category pill filters, "Add" button writes the block to disk). The drag-and-drop and live-preview iframe paths are E2E and can wait — but the synchronous render logic should have RTL coverage.

Important — .gitignore change to +2 lines is small but worth confirming

The .gitignore modification is +2/-0. Without diff access I can't see what's being ignored — verify it's not ignoring the eval artifacts that DID get committed (that'd be a sign the author intended to exclude them but the gitignore was added after the commit).

Nit

• --width file aside, ensure the eval artifacts move to a separate location regardless of PR scope.
• Phase 3 "params currently log changes" — note in the PR or block-catalog docs that the params controls are wired but don't actually apply yet. Otherwise an author who hits "Add" with params expects live application and gets a no-op.

Verdict

Verdict: REQUEST CHANGES
Reasoning: Three blockers: literal --width file at repo root (shell-flag-as-arg artifact), ~12+ MB of eval artifacts (PNGs/MP4/WEBM/reports) shipped inside a feature PR, and effectively zero required-check coverage (all skipped). The Blocks-panel code I could read looks well-factored, but the diff is too large for a one-pass audit and zero tests + zero CI makes that a real risk. Clean up the repo debris, split eval artifacts to their own location, and either land tests or split the feature into Phase-1 / Phase-1b / Phase-2 / Phase-3 sub-PRs.

— Vai