`--width 3840 --height 2160` against a composition with
`data-width="1920"` silently produces a 1080p output because the
runtime lays out the page at the composition's authored dimensions —
real footgun we hit during a cost-analysis sweep. Warn early and point
at `--output-resolution` (the supersampling escape hatch) so the user
doesn't burn a 30-minute render learning the override rule.
Skipped when `--output-resolution` is set (the supported supersampling
path — the user is opting in), when `--json` is set (machine consumers),
or when `index.html` isn't on disk (typical with `--site-id`).
Helper lives in a shared module so render + render-batch agree on the
parse + message. Tests cover both attribute orders, single/double
quotes, the silent paths, and the warning path. Best-effort regex over
the canonical attr shape — malformed HTML falls through to no warning
rather than blocking the render.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The CDK construct compiles tasks.LambdaInvoke to the optimized
arn:aws:states:::lambda:invoke integration, which emits Task* history
events with the Lambda response wrapped in .Payload. getRenderProgress
was only listening for the older LambdaFunction* events, so every CDK-
deployed stack reported $0 total cost and zero invocations on success
— a high-visibility regression that only surfaced when we manually
walked SFN history during a cost-analysis sweep.
Add cases for TaskScheduled (count invocation), TaskSucceeded (parse
Payload + accumulate billed duration / frame counts), and TaskFailed
(record error). Keep the LambdaFunction* paths so anyone wiring the
raw lambda:invokeFunction.sync task type still works. Factor out the
shared FramesEncoded-attribution logic so both branches agree on the
"only RenderChunk frames count" rule.
Tests pin a real-shape regression: replay the inspector-launch
1080p/30fps history (1 Plan + 16 RenderChunks + 1 Assemble) and assert
lambdaUsd lands at ~$0.582 — matching the cost-analysis script's
direct read against SFN history.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Vai (vanceingalls) caught a 10× tolerance mismatch between the script
and the prose. Rames confirmed as blocking:
step-5-build.md:458 (per-beat evidence rule): ±0.05s
step-6-validate.md (playback verification): ±0.1s
w2h-verify.mjs:29 (SFX_DRIFT_TOLERANCE_S): 0.5s
So an agent writing per-beat evidence at ±0.05s reports a 0.3s drift
as FAIL, while the script reports the same drift as PASS. The pasted-
verbatim report contradicts the agent's evidence block — exactly the
kind of internal contradiction this PR was built to eliminate.
Converged on ±0.1s everywhere:
- w2h-verify.mjs:29: SFX_DRIFT_TOLERANCE_S = 0.1 (3 frames at 30fps)
- step-5-build.md:458: ±0.05s → ±0.1s, with cross-reference noting it
matches the script + step-6 playback floor
The other ±0.5s constants in step-6 are for total audio/video duration
and storyboard beat-range matching — those are coarser-grained timing
checks (not SFX-to-visual sync). Left as-is intentionally.
Regression check: huly-v3 now flags 4 SFX drifts instead of 3 — the
new one is glitch-1.mp3 at 0.20s drift (6 frames). The old 0.5s
tolerance was masking this real timing issue.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Allows authored-at-1080p compositions to render at 4K/2K via Chrome
deviceScaleFactor supersampling without re-laying-out the composition.
Plain --width 3840 silently lays out at 1920×1080 because data-width/
data-height attrs override Config.width — this flag is the supported
way to ask the renderer to supersample.
Accepts canonical CanvasResolution names (landscape, landscape-4k,
portrait, portrait-4k, square, square-4k) and aliases (1080p, 4k, uhd,
hd, 1080p-portrait, 4k-portrait, 1080p-square, 4k-square). Wired
through render + render-batch.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three issues from Miguel's + Rames's reviews:
**[Blocking] find / violates CLAUDE.md guidance (Miguel)**
CLAUDE.md says: "When running find, search from . (or a specific path),
not / — scanning the full filesystem can exhaust system resources on
large trees." I introduced 3 instances of `find /` in skill prose to
help sub-agents locate skill files from unknown CWDs. Replaced all 3
with `find "$HOME" ... -maxdepth 10`. Verified all 4 skill files
resolve correctly under $HOME on the testbed setup.
Files: step-3-storyboard.md (×2), step-5-build.md, step-6-validate.md.
**[Blocking] SFX audio regex assumed attribute ordering (Miguel + Rames)**
The v2 audioRegex required src= to appear lexically BEFORE data-start=
in the same <audio> tag. But capabilities.md:365 — in the same skill —
documents the canonical pattern with src= LAST:
<audio id="..." data-start="..." data-duration="..." data-volume="..."
data-track-index="..." src="...">
Real compositions following the docs would have audio tags that don't
match the regex → SFX reported as MISSING → false FAIL in the script
output → false alarm in the user-facing summary. Exactly what v2 was
supposed to fix.
Replaced with the same two-step shape that readBeatDurationsFromIndex
already uses correctly: match `<audio[^>]*?>` to grab the whole tag,
then extract src= and data-start= from the tag string with independent
regexes. Verified both attribute orderings (src first, src last) now
work via inline node test.
**[Minor] readBeatCompositions / readBeatDurationsFromIndex re-read on
every call (Rames)**
Added process-scoped caches to both helpers. The script is a one-shot
CLI so no invalidation needed — first call hits disk, subsequent calls
return the cached result. readBeatCompositions was called 3×,
readBeatDurationsFromIndex 2× — now 1× each.
**Regression checks**
- huly-v3: 4 PASS · 3 FAIL · 1 INFO (unchanged — same 3 real issues
flagged: 48px wordmark, missing shaders, 3 SFX drifts)
- huly-launch-v4: 6 PASS · 0 FAIL · 2 INFO (unchanged)
- Lint + format: clean
2 files changed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The rational `Fps = { num, den }` refactor in 5dcc89c broke callers
passing `fps: 30` (the form documented in every code example and used
by external consumers). FFmpeg received `undefined/undefined` as the
framerate, causing a cryptic exit-code error.
Add `FpsInput = number | Fps` and `toFps()` normalizer in
@hyperframes/core. `createRenderJob` now accepts both forms —
plain integers are promoted to `{ num, den: 1 }` at the boundary;
`RenderConfig.fps` stays strict `Fps` internally so no downstream
code changes.
Also fixes the producer and engine docs, which showed phantom
`input`/`output` fields on `createRenderJob` and a wrong
`executeRenderJob(job)` signature (missing `projectDir`/`outputPath`
args).
Closes#1031
Two fixes for the 3M+ unhandled_promise_rejection events/day spike:
1. Filter: suppress "Error fetching ... 404" rejections from composition
code — these are asset-not-found content errors, not Studio bugs.
2. Rate-limit: cap both error and rejection telemetry at 50 per session.
After the cap, emit a single *_cap_reached event so we know capping
occurred without generating unlimited events.
3. Root cause: webAudioTransport now checks response.ok before decode
and caches failed URLs in _failedSrcs so repeat ticks don't re-fetch
the same 404 on every playback frame.
Also add playground/ to fallow ignorePatterns — local experiment
directory was tripping the audit gate.
A fresh agent session ran the v1 verify script and the disclosure pasted
into their final summary showed 3 FAIL rows for things that weren't
actually defects:
Headline font-size: flagged Beat 2 (wordmark SVG), Beat 3 (UI grid),
Beat 5 (terminal). None of these legitimately have text headlines.
Timeline coverage: flagged 5/6 beats because the script's regex only
saw `tl.X(..., 2.5)` literal positions and missed forEach loops,
variable-position tweens, and long-duration scaler tweens.
Beat durations: flagged 2 beats because my "duration X.Xs near beat
label" fallback false-matched non-beat durations
(e.g., "shader runs — duration 0.7s" near a "Beat 1" mention).
The agent had to write ~5 paragraphs defensively justifying each false
FAIL. That's friction we can fix.
Tested against the agent's actual project (huly-launch-v4): went from
4 FAIL (3 false positives + 1 real bare-table parser miss) to 0 FAIL.
Also re-verified huly-v3 still correctly catches its 3 real issues
(48px wordmark, missing shaders, 3 SFX drifts) — no regression.
**Brand visuals check**
Switched from "≥30% asset usage" (gameable, rewards quantity over quality)
to "at least 1 beat references a captured hero/image/svg" — quality
signal that's cheap to satisfy when real, hard to fake. Excludes fonts,
logos, favicons, contact-sheets.
**Headline check**
Now only flags beats where the LARGEST font-size is in the 40–<80px
range — the "aspiring headline but too small" zone. Below 40px = beat
has no text headline by design (terminal, UI labels, SVG-only); skip.
≥80px = proper headline; pass. Eliminates the false positives on
SVG-dominated and UI-grid beats while still catching the real "headline
too small" failure (Beat 4 at 72px in this run; Beat 1 wordmark at 48px
in another).
**Timeline coverage check**
Three improvements:
1. Detects forEach loops + for-loops containing tl.X() calls — beats
with these have events at positions the static parser can't read;
mark as INFO-skipped rather than failed.
2. Detects long-duration tweens — if a single tween's duration covers
≥70% of the beat duration (camera dolly, breathing animation), the
beat has full coverage via persistent motion; skip the position check.
3. New paren-balanced parser for extracting tl.X() position arguments —
the v1 regex was matching `rgba(86,131,218,0.35)` and capturing 0.35
as a tween position. The new parser walks paren depth and only
captures top-level trailing numeric args. No more rgba false matches.
**Shader transitions check**
Two fixes:
1. Filter out inventory lines — lines listing 3+ shader names are
"what's available," not "what's planned for use." Real use
mentions one or two shaders per line.
2. Apply the same SFX-context exclusion to the declared side that the
present-check side already had — "glitch" inside `sfx/glitch-1.mp3`
no longer counts as a declared shader transition.
For huly-v3: was 6 declared (1 phantom from inventory + 5 + glitch
from SFX), now 2 declared (light-leak, cinematic-zoom) — matches the
storyboard's actual plan.
**Beat duration check**
1. Dropped the "duration X.Xs within 200 chars of beat label" fallback
— too loose; matched shader durations, animation durations, anything
labeled "duration". This was the source of the 0.70s misread in the
debrief.
2. Added a bare-number timing-table parser for the format
`| 1 | 0.00s | 5.20s | 5.20s | ... |` (with optional `>` blockquote
prefix). Computes duration = end - start.
3. Added a negative lookahead so `\bB3\b` doesn't false-match "B3.1"
sub-beats and grab the wrong row.
4. Filter buildBeatIds to only numbered beats — skips the root
composition (`data-composition-id="main"`) so it doesn't inflate
"parseable" count.
**Brand visuals + asset count**
Excluded fonts/ subdirectory (always-used via @font-face → would
always pass) and contact-sheet-*.jpg (pipeline outputs, not website
inputs). Both inflated the denominator and weakened the signal.
**Edge case fixes**
- Removed `basename` unused import (oxlint).
- Fixed shader-name substring overlap: longest-name-first matching so
"cross-warp-morph" doesn't double-count as "cross-warp".
- SFX timestamps now collect ALL audio tags per file (multi-timestamp
SFX like click×3); picks closest index timestamp to each storyboard
timestamp instead of just keeping the last.
**Step 6 doc**
Updated the skill's "w2h-verify — the source of truth" section to
describe the new checks accurately and what failure mode each catches.
2 files changed, +486/-109. Format + lint clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Flip the fallback from false to true so the blocks panel is on for
everyone out of the box. Users can still disable it via
VITE_STUDIO_ENABLE_BLOCKS_PANEL=false if needed.
Three rounds of text-based enforcement plateaued. A third agent debrief
showed the same failures: 9% asset usage (vs ≥30% floor), shader
transitions declared in STORYBOARD.md but not in shipping index.html,
SFX timestamps drifted up to 12.4s, animation-map skipped, MP4 not
rendered, honest-disclosure section omitted from final summary.
The pattern is clear: language-only enforcement is selectively
interpretable by the agent under ship pressure. Move enforcement into
tooling — facts the agent can't fudge.
**New script: `skills/website-to-hyperframes/scripts/w2h-verify.mjs`**
Pure file-analysis script (no shell spawns). Computes six checks and
prints a PASS/FAIL/INFO table:
1. Asset usage — assets referenced in compositions ÷ assets captured;
target ≥30%. Tested against videos/huly-v3: caught 6/74 = 8% FAIL.
2. Shader transitions consistency — STORYBOARD.md-declared shaders vs
index.html. Longest-name matching to avoid substring false positives
(cross-warp-morph not double-counted as cross-warp). Tested: caught
6 declared / 1 present / 5 missing.
3. SFX timestamp drift — parses STORYBOARD.md table rows for
`sfx/X.mp3` + time-with-`s`, parses index.html <audio data-start>,
flags drift >0.5s. Tested: caught 12.4s drift on click.mp3 that
the agent debrief didn't even mention.
4. animation-map.json existence — explicit file check.
5. Rendered MP4 existence — scans project root, output/, renders/.
6. Required artifacts — STORYBOARD.md, DESIGN.md, SCRIPT.md, index.html
all present.
Exit code: 0 (all pass) or 1 (one or more fail). The script's output
becomes the Step 6 deliverable — paste verbatim into the user-facing
summary.
**Skill update: `step-6-validate.md`**
Adds `w2h-verify report` to the DoD checklist with the rule: paste the
FULL output verbatim into the final summary. Cherry-picking rows,
substituting adjectives for percentages, or omitting FAIL lines is
explicitly forbidden. If a row says FAIL, either fix it and re-run
until PASS or include the FAIL line verbatim in "What I did NOT
verify" with a one-sentence reason.
Test run against the project that prompted this:
```
SUMMARY: 1 PASS · 4 FAIL · 1 INFO
- Asset usage: FAIL 6/74 (8%) target ≥30%
- Shader transitions: FAIL 6 declared, 1 present, 5 missing
- SFX timestamps: FAIL 3 drifted >0.5s (max 12.4s)
- animation-map.json: FAIL missing
- Rendered MP4: INFO no .mp4 found
- Required artifacts: PASS
```
The agent could selectively ignore "the WCAG warnings are false
positives." The agent cannot selectively ignore a line that says
`6/74 (8%) — target ≥30%`.
2 files changed (+ 1 new script, ~330 lines). Format checks pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
`injectInterceptor` used `String.prototype.replace(target, replacement)`
to inject the runtime `<script>` before `</head>`. The replacement
string is a substitution template — `$&` expands to the matched
substring, and the minified runtime IIFE contains legitimate `$&`
sequences (e.g. `if(te&&$&!y.hasAttribute(...))`), so every `$&` in
the body was silently rewritten to `</head>`, producing
`Unexpected token '<'` SyntaxErrors and breaking every timeline in
the bundle.
Switch to the function-replacer form so the runtime body is passed
through verbatim. Add a regression test that diffs the bundled
runtime body against `getHyperframeRuntimeScript()` and asserts only
one `</head>` survives in the document — the test exercises the
`<head>`-present injection path (the only branch that uses the
substitution template; the no-`<head>` fallback uses slice+concat
and was unaffected).
Only the bundler is affected — `producer/fileServer.ts` already uses
the function form via `injectScriptsIntoHtml` in
`htmlDocument.ts`, so render output was correct. Snapshot, preview,
studio, layout, and validate all consume `bundleToSingleHtml` and
were broken before this fix.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
A second agent debrief (different session, with the prior enforcement edits
applied) revealed the most damning failure yet: the agent used 1 of 65
captured assets. They wrote their own "Asset Audit" table saying SKIP for
64 hero illustrations, brand SVGs, and signature visuals. The entire point
of capture is to USE the brand's assets — that gate was bypassed entirely.
The debrief also revealed 5 other patterns the prior enforcement missed.
This commit closes all 6.
**Pattern A — Asset Audit gate (step-3-storyboard.md)** — BIGGEST FIX
Adds a non-skippable Asset Audit section in Step 3 that requires viewing
every page of capture/assets/contact-sheet-*.jpg + svgs/contact-sheet-*.jpg,
pasting 5 distinctive assets per page (with descriptions of what's actually
pictured), and choosing USE/SKIP per asset with one-sentence justification
for each SKIP. Brand-defaults floor: at least one beat MUST use a captured
hero illustration/photograph/signature diagram — not just the logo. The
forbidden list explicitly calls out: reading asset-descriptions.md alone
without opening the contact sheets, and rebuilding signature graphics in
CSS when the brand's own SVG of that graphic is in capture/assets/.
**Pattern B — Auto mode scope (SKILL.md + step-2-brief.md)**
Clarifies that auto mode covers user-PREFERENCE gates (TTS provider,
voice, beat count, captions yes/no — where the agent decides on the
user's behalf) but NOT quality-VERIFICATION gates (Asset Audit, per-beat
HTML read, DoD checklist, honest disclosure). Adds explicit test for
distinguishing: if the answer changes the content of the video, it's a
preference; if the answer is "did the verification happen?", it's a
quality gate. The agent that skipped the captions question by reasoning
"auto mode says bias toward action" was misusing auto mode.
**Pattern C — 3-path audio/motion verification (step-6-validate.md)**
Replaces the prior "Path 1 or explicit deferred" with three explicit
paths: (1) Play preview in Playwright, (2) render low-res MP4 and read
frames at ≥5fps, or (3) explicit deferred disclosure with QUANTIFIED
coverage gap ("18/900 frames = 2% coverage"). The percentage in Path 3 is
mandatory — vague "deferred to user" was the loophole. Forbidden: claiming
"confirmed via snapshot" as audio/motion evidence; 18 PNGs from a 900-
frame video is 2% coverage, not verification.
**Pattern D — Sub-agent diagnoses are hypotheses (beat-builder-guide.md)**
When a sub-agent reports "this is a linter false positive" / "this is a
known bug", that is a HYPOTHESIS from one symptom — not a verified
finding. Before propagating the workaround to other beats, main agent
must EITHER read the source to confirm OR explicitly disclose the
unverified claim. The debrief showed the main agent applied beat-2's
"linter false positive" diagnosis to beat-4 without ever reading
packages/core/src/lint/utils.ts to confirm.
**Pattern E — Re-snapshot after parallel sub-agents (step-5-build.md)**
When sub-agents run in parallel, each snapshots a project where sibling
beats may not exist yet. Their snapshots at beat boundaries or during
shader transitions show the WRONG content (typically previous beat).
Required after all complete: a canonical project-wide snapshot via the
CLI — that's what Step 6's DoD uses. Sub-agents' intermediate snapshots
are sanity checks, not the deliverable.
**Pattern F — STORYBOARD.md must be updated when divergence accepted
(beat-builder-guide.md)**
When a sub-agent diverges from spec ("the real brand mark is lowercase
'huly' not uppercase 'HULY'") AND the main agent accepts the divergence,
the main agent MUST patch STORYBOARD.md to reflect reality. Otherwise
the spec lies and the next session reading it as ground truth gets the
wrong information. Examples covered: brand mark casing, cell size at
scale, SFX timing alignment.
6 files changed, +131/-11 (net +120 lines of enforcement).
Format checks pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
After the audit-fix commit (e47bc6c6) landed clarity fixes, a real test run
revealed that the skill still got skipped at the gates that matter most.
The agent's honest debrief listed 9 distinct patterns where it judged
"deliver fast" over "verify what the skill said to verify."
This commit forces evidence at each of those gates so silent skips are no
longer possible without lying — at which point the gate fails by design.
**Patterns 1, 3, 8 — step-5-build.md**
- Pattern 1: "Read each beat HTML top-to-bottom" gate now requires a
structured evidence block per beat with quoted CSS hex codes, headline
font-size, captured asset paths, GSAP first/last events, and SFX trigger.
"I read it and it looks fine" / "the sub-agent confirmed" are not
acceptable. Snapshots are 3 frames out of 300+ in motion.
- Pattern 3: SFX timestamp computation rule. Every data-start MUST be
computed (beat-local + beat global start = global timestamp), not
estimated by eye. The agent typed `data-start="6.0"` for a storyboard
moment at 5.0s — a 1-second drift, not a rounding error.
- Pattern 8: Recurring sub-agent workarounds must be surfaced under
"Tooling issues encountered" — burying them means the next session
hits the same bug.
**Patterns 2, 6, 7, 9 — step-6-validate.md**
- Pattern 2: WCAG contrast warnings now require per-warning verification
with quoted validator output and opacity check at the sampled timestamp.
Blanket dismissal as "mostly transition-window false positives" is
explicitly forbidden.
- Pattern 6: animation-map.json check added to the DoD checklist —
runs `skills/hyperframes/scripts/animation-map.mjs` and confirms
per-beat event coverage.
- Pattern 7: Audio + motion verification is now a separate DoD item from
snapshot verification. Snapshots are silent stills; you must actually
play the preview and confirm SFX lands at storyboard timestamps within
±0.1s. CLI-only sessions must explicitly disclose this as deferred.
- Pattern 9: Honest disclosure section added — final user-facing summary
MUST end with "What I verified" and "What I did NOT verify" blocks.
"Looks great, ready to ship" with no disclosure now fails the gate.
**Patterns 4, 5 — beat-builder-guide.md**
- Pattern 4: Sub-agent FLAG protocol. Required phrasing for non-blocking
issues is concrete and actionable with line numbers. Forbidden phrasing:
"if X feels too long, you could...", "consider tweaking...", "might
want to...". Main agent must address each FLAG or write a rejection.
- Pattern 5: Spec ambiguity escalation. If the storyboard names a
transition without establishing the start state ("Row 1 transitions
blue → orange" but Row 1's initial color isn't specified), sub-agent
MUST flag it and ask for confirmation rather than guess. Picking an
interpretation silently means the build "looks fine" while diverging
from intent.
3 files changed, +170/-21 (net +149 lines of enforcement language).
Format checks pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Create a Tooltip component with styled popover (dark bg, border,
shadow) that appears on hover with a 400ms delay. Applied to:
- Left sidebar tabs: Code, Comps, Assets, Catalog
- Right panel tabs: Design, Layers, Motion, Renders
Replaces native title attributes with proper styled tooltips.
Add title attributes to interactive elements that were missing them:
- PlayerControls: Play/Pause, playback speed, shortcuts panel, clear
in/out-point buttons, and jump-to-frame Go button
- StudioRightPanel: Design, Layers, Motion, and Renders tab buttons
Call tl.pause() both before AND after tl.seek() in the adapter.
GSAP's seek() can reactivate a timeline depending on internal state;
the second pause() guarantees it stays frozen at the seeked position.
When seeking via the slider or timeline scrub, explicitly pause all
<video> and <audio> elements inside the preview iframe. The GSAP
timeline pauses but iframe media elements can continue playing
independently, causing audio to keep going after a seek.
10 fixes from an audit of skills/website-to-hyperframes/ targeting clarity for
AI agents following the pipeline. Each fix is a surgical edit; no behavior
changes for human readers.
**Critical contradictions resolved:**
- capabilities.md: `onUpdate`/`tl.call` was simultaneously documented as required
(canvas/WebGL/typing patterns) and banned (determinism). Sub-agents reading
the ban would silently strip working code from Canvas 2D and Three.js beats.
- step-1-design.md: Removed "Depth & Elevation" section template that the same
file's Rules section forbade. Renumbered remaining sections (6→5).
- beat-builder-guide.md: Narrowed "no onUpdate for counters" rule so canvas
rendering loops aren't caught by the prohibition.
**Path resolution fixes for sub-agents:**
Sub-agents run from `<project-dir>` (e.g. videos/foo/), not repo root, so
repo-relative paths like `skills/website-to-hyperframes/assets/sfx/manifest.json`
fail silently. Replaced with `find / -path ...` patterns that work from any CWD.
- step-3-storyboard.md: sfx/manifest.json + text-effects.md paths
- step-5-build.md: beat-builder-guide.md path
**Missing fallbacks added:**
- step-3-storyboard.md Gate: autonomous mode now propagates from Step 2 — gate
no longer blocks on explicit approval when user said "surprise me".
- step-4-vo.md: timing-formula recalibration now has concrete steps for both
"too short" (add pauses) and "too long" (cut highest-density beat).
- step-6-validate.md: agent-authored descriptions fallback when GEMINI_API_KEY
is unavailable — DoD checklist no longer has a dead end.
**Quick Reference polish:**
- SKILL.md: step-1-design entry now mentions 50-line fast-path exception.
8 files changed, +32/-37 (net -5 lines). Format checks pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Clicking "Ask agent" now opens a modal that shows the full generated
prompt so the user can read it before copying. The modal has a "Copy
prompt" button that turns green on success. This replaces the silent
clipboard copy that gave no visibility into what was copied.
- Ask agent button turns green with checkmark on copy
- Add button shows tooltip "Add to composition at current time"
- Ask agent shows tooltip "Copy a prompt to paste into your AI agent"
- Tab tooltips: Code, Comps, Assets, Catalog each explain their purpose
- Search placeholder updated to "Search by name, category, or tag…"
Add button rules: VFX, Social, Scenes get Add + Ask agent. Captions,
Transitions, Effects, Data get Ask agent only.
Search now matches category names and tags, so searching "captions"
shows all caption blocks.
Components (hyperframes:component) get both "Add" and "Ask agent"
buttons since they work as drop-in overlays. Blocks (scenes, data,
VFX, transitions) show only "Ask agent" since they need agent-guided
customization.
The "Ask agent" button now copies the current composition state along
with the category-specific prompt: playback time, active composition
path, dimensions, and all elements visible at the current time with
their track, timing, and source paths. Gives the agent full context
to place and customize the block correctly.
When previewing a component (compositions/components/*), render the
main composition player as a backdrop behind the transparent component
overlay. This lets users see captions, vignettes, and other overlays
in context instead of against a black void.
Registry blocks are authored at 1920x1080 but projects may use
different dimensions (e.g. 1280x720). After installing a block, the
server now reads the host project's data-width/data-height from
index.html and rewrites the block's viewport meta and CSS dimensions
to match, preventing overflow.
Remove the Add button and drag-and-drop from catalog cards — blocks
and components need agent-guided customization, not blind insertion.
Each card now shows a single "Ask agent" button that copies a rich,
category-specific prompt to clipboard with context about what the
block does and how to customize it (captions: transcribe + style,
transitions: place at cut point, data: replace values, etc.).
Each catalog card now shows two hover buttons:
- "Add" — inserts the block/component into the composition at the
current playhead position (existing behavior, now with + icon)
- "Agent prompt" — copies a contextual prompt to clipboard tailored
to the block's category (captions, transitions, VFX, etc.) so the
user can paste it into their AI agent for guided customization
Blocks and components now start at the current playhead position
instead of being appended after all existing content. If the new
element extends beyond the root composition's data-duration, the
root is automatically extended to fit.
insertTimelineAssetIntoSource now detects the parent indent level and
adds the new element with matching child indentation. Block attributes
are written one-per-line for readability.
Blocks were using their own native dimensions (e.g. 1920x1080) instead
of the host composition dimensions (e.g. 1280x720), causing them to
overflow the viewport and break the layout. The block's iframe scales
its content to fit the container, so using host dimensions is correct.
Replace fragile regex z-index parsing with getComputedStyle on the
preview iframe elements — the same source of truth the inspector uses.
Rename "Layer" to "Z-index" in the design panel for clarity.
The DomEditOverlay sits at z-10 with pointer-events:auto over the
preview, intercepting all drag events before they reach NLEPreview's
viewport. Move block drop handling from NLEPreview up to the wrapper
div in NLELayout that contains both the preview and the overlay, so
drag-and-drop from the Catalog panel onto the preview area works
regardless of inspector state.
