Root cause: the per-worker capture calls in captureFrameRange
(parallelCoordinator.ts) take no abort signal of their own, and only
checked `signal.aborted` BEFORE starting each frame — a no-op once a
worker is already awaiting an in-flight call. On WSL2, the native
drawElement/BeginFrame capture call can hang indefinitely at frame 0
with no error. The DE parallel-router's existing stall watchdog
(captureStreamingStage.ts) correctly fires `stallController.abort()`
after HF_DE_STALL_MS, but that abort had no way to reach a
worker already wedged inside a hung capture call — so
executeParallelCapture's Promise.all waited forever, the render hung
indefinitely, and the CLI's circuit breaker (which only runs after
executeRenderJob settles) never got a chance to trip.
Fix: race each per-frame capture call against the signal actually
firing (raceAgainstAbort), the same "can't cancel, only race" pattern
already used by the sequential capture path. Once the watchdog's abort
is observed, the wedged worker rejects, executeParallelCapture settles,
and the existing pinned-fallback retry / "reverted" outcome / circuit
breaker machinery (already correct) runs end to end.
Also widen the CLI breaker's trip condition from the literal string
"reverted" to "not a clean routed success", so any future non-success
outcome the observability layer records also latches the breaker
instead of silently falling through.
Closes#3441
Co-authored-by: Miga <noreply@anthropic.com>
`docs/changelog.mdx` reached 512 KB and started failing the 500 KB pre-commit
check, so `chore: release v0.8.14` could only be committed by passing
`HF_MAX_NONLFS_KB`. Every release from here would need the same override, and
the file grows a few KB each time.
The check is for binaries. Its own error message says "large binaries are being
committed to git instead of LFS", and its header explains why: an ONNX model,
HDR-regression MP4s, demo clips, each of which lives in history forever and is
paid for by every clone. That cost is specific to binaries. Git delta-compresses
text, so release notes that grow a few KB per commit add a few KB to the pack,
while a binary of the same size re-enters the pack whole on every edit.
Text is now exempt regardless of size, detected with `grep -I` (a file with NUL
bytes is binary), the same heuristic git uses for "Binary files differ". The
binary rule, the `registry/` exemption, the LFS check and the size threshold are
all unchanged.
The alternative was an allowlist entry for the one file, which would leave the
next legitimately growing text file to hit the same wall and get the same
one-off exemption.
`scripts/check-large-files.sh` had no test. It has one now, wired into
`test:scripts` so it actually runs: an over-limit binary fails, an over-limit
text file passes, an under-limit binary passes, and multiple offenders are all
named. Verified the text case fails with the exemption removed, so the test
pins the behaviour rather than describing it.
`registry_item_added` fires when a catalog block is installed and
`render_complete` fires when a video is produced, but nothing joined them, so
"did this video use the catalog?" had no answer.
`hyperframes add` now records each installed item in `hyperframes.json`
(installed files are plain composition HTML with no provenance marker, so this
manifest is the only record that a file came from the registry), and
`render_complete` reports both the items the project installed and the blocks
the rendered composition actually reaches. An item installed and then never
mounted was tried and dropped, which no add-time event can express.
The scan answering "which sub-compositions does this file mount" now has one
owner, `collectSubCompositionSrcs` in `@hyperframes/parsers`, shared with
lint's `lintMissingOrEmptySubComposition`. It holds two invariants that were
previously restated per call site and got re-derived wrongly: it is a text scan
rather than a DOM query, because `<template>` content is inert and every
sub-composition except the render entry is wrapped in one; and references
resolve root-relative at every nesting level, matching `parseSubCompositions`.
It walks tag by tag rather than running open-ended spans across the whole file,
so a malformed composition cannot stall the render plan.
Also: `registryItems` is declared in the config schema, which closes with
`additionalProperties: false`, with an ajv-backed test pinning every key the CLI
writes; counts are never truncated by the name cap, and the reported used blocks
stay a subset of the reported installed ones, with `registry_items_truncated`
marking a windowed list; and an unreadable manifest reports itself rather than
posing as a project that never used the catalog.
The runtime absorbed a series of authoring mistakes over time and `runtime/init.ts`
says so in its own comments, but the skills kept teaching the old rules. Four of
them actively cost an agent a failing run: add `crossorigin` (lint rejects it
unconditionally), never build a timeline inside `async` (lint calls that the
documented contract), never `gsap.set` later-scene clips (two fixHints instruct
exactly that), and 12 copyable media snippets with no `id`, which render silent.
Corrected in every place each claim appeared, including `hyperframes-animation`,
three workflow scripts, the scaffolded project instructions, the CLI `docs`
command, and the public docs site: `data-track-index` is a Studio display lane
the render never reads, `class="clip"` is a layout convention rather than a
visibility requirement, timed elements may nest, the visibility window is
half-open, sub-composition host dimensions are backfilled, and the root-fill rule
applies only to the layered-composite path.
Behaviour changes, each backed by a render rather than by reading code:
- `timeline_registry_missing_init` deleted. The runtime creates the registry
before any inline script; a composition without the guard line renders and
animates correctly.
- `video_nested_in_timed_element` kept, message corrected. A rendered repro shows
the nested-with-local-start case really does break, so the rule guards a real
defect, but nothing is "FROZEN": the extractor ignores the wrapper's offset
while visibility uses it, so the clip shows wrong frames and then vanishes.
- `mediaRenderIds` now stamps media whose source is a `<source>` child, closing a
duplicate-id gap the old `[src]`-only selector left open.
- Stale messages fixed on `subcomposition_root_styled_by_class` and
`deprecated_data_layer`.
`coreSkillContent.test.ts` pinned the literal sentence that made root
`data-start` look required, so it is narrowed to structure plus the regression it
genuinely catches.
Not covered, and flagged in the PR: the media global-vs-local start heuristic in
`runtime/init.ts` is the root cause behind the nested-video defect. Removing it
changes the meaning of existing compositions and needs its own deprecation.
* feat(studio): drag automation segments
* fix(studio): clear clip selection for group effects
* fix(studio): replace clip selection with audio bus
* fix(studio): make audio bus selection authoritative
Grouped audio shipped and its three canaries were deleted rather than raised.
Solo and the group meter shipped and were removed in the same week, so the
digest says so. Notes that the v0.8.0 minor bump marks two catalog component
removals rather than the week's headline.
Generated with bun run changelog:weekly, then rewritten for publication.
Every sha was machine-verified: 40 chars, prefix-matched, an ancestor of main,
and inside the 2026-08-17..2026-08-25Z window. npx mint validate passes from docs/.
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
seam-gate verify --project has failed with "preview server exited early" since #3310, which made `hyperframes preview` pick its launch mode from the TTY. The gate spawns with stdio [ignore,pipe,pipe], so interactive is false and it silently took the background path: the launcher exits 0 before the server is serving (read as a dead server), and the detached server escapes the gate's process-group cleanup (leaking a preview per run).
Pass the CLI's own --foreground opt-out in the default --server-cmd. Both skill mirrors updated.
— Rames
* fix(core): harden audio FX and group identity
* fix(core): address audio group review feedback
* fix(core): align preview transport with grouped audio
* test(core): pin audio group gain ceiling
* fix(core): preserve solo bridge through stack
* fix(engine): harden grouped audio rendering
* docs(engine): explain grouped mix fallback invariant
* test(engine): allow grouped mixes to finish on Windows
* feat(lint): validate audio group membership and timing
* test(lint): pin audio group membership guards
* fix(studio): unify audio IDs and group state
* fix(studio): make audio-group edits transactional
* fix(studio): keep preview state synchronized
* fix(studio): align audio rows, automation lanes and headers
* fix(studio): stabilize timeline audio derivations
* refactor(studio): simplify group metadata memoization
* style(studio): keep timeline layout within size gate
* fix(studio): keep timeline preset apply off auditions
* fix(studio): harden carve and FX rack behavior
* fix(studio): repeat audio FX reveal requests
* fix(studio): reconnect property-panel audio controls
* fix(studio): unify property panel audio detection
* fix(studio): satisfy panel and deletion gates
* feat(studio,core)!: remove solo and the group meter
* docs(audio): keep removal rationale current
* refactor(core): retire studio solo bridge
* docs(audio): document grouped audio and its guardrails
* docs(audio): point handoff at replacement stack
* fix(core): harden audio FX and group identity
* fix(core): address audio group review feedback
* fix(core): align preview transport with grouped audio
* test(core): pin audio group gain ceiling
* fix(core): preserve solo bridge through stack
* fix(engine): harden grouped audio rendering
* docs(engine): explain grouped mix fallback invariant
* test(engine): allow grouped mixes to finish on Windows
* feat(lint): validate audio group membership and timing
* test(lint): pin audio group membership guards
* fix(studio): unify audio IDs and group state
* fix(studio): make audio-group edits transactional
* fix(studio): keep preview state synchronized
* fix(core): harden audio FX and group identity
* fix(core): address audio group review feedback
* fix(core): align preview transport with grouped audio
* test(core): pin audio group gain ceiling
* fix(core): preserve solo bridge through stack
* fix(engine): harden grouped audio rendering
* docs(engine): explain grouped mix fallback invariant
* test(engine): allow grouped mixes to finish on Windows
* feat(lint): validate audio group membership and timing
* test(lint): pin audio group membership guards
* fix(studio): unify audio IDs and group state
* fix(studio): make audio-group edits transactional
* fix(core): harden audio FX and group identity
* fix(core): address audio group review feedback
* fix(core): align preview transport with grouped audio
* test(core): pin audio group gain ceiling
* fix(core): preserve solo bridge through stack
* fix(engine): harden grouped audio rendering
* docs(engine): explain grouped mix fallback invariant
* test(engine): allow grouped mixes to finish on Windows
* feat(lint): validate audio group membership and timing
* test(lint): pin audio group membership guards
* fix(studio): unify audio IDs and group state
* fix(core): harden audio FX and group identity
* fix(core): address audio group review feedback
* fix(core): align preview transport with grouped audio
* test(core): pin audio group gain ceiling
* fix(core): preserve solo bridge through stack
* fix(engine): harden grouped audio rendering
* docs(engine): explain grouped mix fallback invariant
* test(engine): allow grouped mixes to finish on Windows
* feat(lint): validate audio group membership and timing
* test(lint): pin audio group membership guards
* fix(core): harden audio FX and group identity
* fix(core): address audio group review feedback
* fix(core): align preview transport with grouped audio
* test(core): pin audio group gain ceiling
* fix(core): preserve solo bridge through stack
* fix(engine): harden grouped audio rendering
* docs(engine): explain grouped mix fallback invariant
* test(engine): allow grouped mixes to finish on Windows
* fix(core): harden audio FX and group identity
* fix(core): address audio group review feedback
* fix(core): align preview transport with grouped audio
* test(core): pin audio group gain ceiling
* fix(core): preserve solo bridge through stack
Reported as "the grouping button did nothing — I clicked it and nothing
happened". The dialog WAS opening. It positioned itself at
`anchorRect.bottom + 4` with no flip and no clamp, and this button lives in a
track header at the bottom of the studio window, so it opened past the viewport
edge. It was the last floating surface in the timeline with no viewport handling
at all.
It now goes through `resolveFloatingPanelPosition`, the helper the other body
portals already position with (`RenderQueue`, `propertyPanelColor`), so it flips
above the anchor when there is no room below and clamps so neither edge leaves
the viewport. `GROUP_DIALOG_SIZE` is a declared estimate in the same style as
`FORMAT_PANEL_SIZE` and `COLOR_PICKER_SIZE`: `w-56` is exact, only the flip
decision reads the height, and the clamp keeps the dialog on screen either way.
Two tests, at a realistic bottom-of-window anchor and hard against the right
edge. Both verified to fail against the raw positioning.
Worth noting why this shipped: the existing `group-pointer` test passes with or
without the fix. happy-dom reports an all-zero rect for an unlaid-out button, so
the dialog landed at top:4 — on screen, and nothing like the real app. A geometry
test that never sets a geometry proves nothing.
Deliberately NOT included: a toast for the grouping write's silent
`elements.length < 2` bail. That path is real in code but I could not reach it
from the UI — the button only renders on a track with 2+ ungrouped clips, and
sub-composition audio arrives as separate single-clip rows, so the offer never
appears there. Adding a message for an unreachable branch, plus the file split it
would force to stay under the 600-line studio cap, is not justified by evidence.
* test(sdk): render-faithfulness test for serialize() bake contract (WS-F)
Adds session.render-faithful.test.ts with 8 assertions covering the full
op batch (setStyle + setText + setTiming + addGsapTween + moveElement).
Confirms serialize() emits fully override-baked, render-ready HTML — this
is the SDK-side guarantee that the backend render input needs no separate
override-set field. Also asserts GSAP <script> edits and data-composition-
variables survive serialization unchanged.
Decision recorded: no SDK bake helper. session.serialize() IS the bake.
Content-address → zip → S3 upload → pointer-swap is host/backend (WS-P/WS-R).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* test(sdk): close the two false-positive slots in the bake-contract assertions
`toContain('data-end="5"')` in the setTiming case and `toContain('data-y="50"')`
in the full-batch case both match a DIFFERENT element in the fixture —
hf-title already ends at 5, hf-box already sits at y=50 — so either assertion
would still pass if its write regressed to a no-op. Paired each with the
disappearance of the target element's own pre-mutation value, which is the
pattern the setText case already uses.
* test(sdk): assert the canonical data-duration timing shape, not legacy data-end
The false-positive slot was hiding a real behaviour change. `setTiming` now
routes through the parsers' `writeClipTiming`, which canonicalizes timing onto
`data-start` + `data-duration` and REMOVES the legacy `data-end`. The
full-batch case asserted `data-end="4.5"` and failed once rebased onto main;
the standalone case asserted `data-end="5"` and passed only because hf-title
carries that exact value in the fixture — the very collision this pass set out
to close.
Both now assert the start/duration pair and the disappearance of the target's
own legacy end.
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The render POST's catch took no binding, so the exception was discarded and
every transport failure produced one sentence: "Could not reach render server.
Use `hyperframes render` from the CLI instead."
A dead server, a DNS failure, an aborted request and a server that died
mid-render are all indistinguishable under that string — and it is not only a
UI message, it is what travels into the feedback report. Three separate field
reports carried it verbatim, one of them describing a render that fails every
single time. A guaranteed reproduction that tells us nothing is worse than an
intermittent one that does.
Bind the error and append it. The CLI guidance stays, since it is still the
right next step for the user; it just no longer stands alone.
Regression test asserts both halves: the cause appears, and the guidance
survives. It fails on the unfixed code with `expected 'Could not reach render
server. Use `h…' to contain 'Failed to fetch'`.
* docs(audio): document the audio effects system
The effects feature had no documentation at all — the only mentions anywhere in
docs/ were changelog entries. This adds the three pages the color-grading feature
already has, one per audience, and closes a gap in the existing audio guide.
- prompting/audio-effects — a new Level 5 chapter on asking for a mix in
symptoms rather than in filters, with the voiceover carve as the headline, the
level-before-depth check, groups, and the three requests that have no honest
answer (de-essing, noise removal, tone matching).
- studio/audio-effects — the rack, presets by symptom, the carve module, groups,
the deliberately asymmetric mute/solo, automation lanes, and troubleshooting.
- reference/audio-effects — the contract: all four attributes, every effect and
parameter range, why some parameters cannot be automated, the 19 presets, the
five jobs and five one-knob profiles, carve semantics, the group model, the
render bus, preview/render parity, and the three lint rules.
Also points the existing "duck music under important speech" advice in
guides/voice-and-audio at the carve, which does that properly and was never
named there.
Facts verified against source rather than the shipped skill prose: the panel
section is "Audio FX" (the neighbouring "Effects" section is visual effects, and
an earlier draft of this page named the wrong one), MAX_AUTOMATION_POINTS is 512,
fromPreset carries a preset id rather than a boolean, the leveller targets the
track's own 80th percentile, group mute reaches the render while solo never
leaves Studio, and the CLI carve currently writes clip ids.
No screenshots in this pass, and no placeholders for them either — the pages
carry concrete markup and tables instead. Screenshots of the rack, the carve
module, and a group row would each earn their place later.
mint validate and mint broken-links both pass.
* docs(audio): give audio its own Studio group, split by task
Review feedback: the audio page did not belong in Studio / Edit. That group is
already one task per page — canvas, timeline, animation, captions — and a single
page covering the rack, the carve, groups, and automation lanes was four tasks
bundled together and dropped in beside them.
Studio now has an Audio group holding four task pages:
- Effects and presets — the rack, presets by symptom, adding single effects in a
working order, the one-knob controls, Even Out Levels
- Voiceover carve — its own page, because it is the feature people come for
- Groups, mute, and solo — including why mute reaches the export and solo cannot
- Automation lanes — drawing envelopes, the shape menu, and which parameters
cannot move at all
Not a new top-level tab: the tabs here are audience-scoped (Guides, Studio,
Catalog, Developers), so a feature tab would be the only one of its kind and
would strand the prompting chapter out of its Level 5 sequence and the reference
page out of Developers.
Repointed the deep link in guides/voice-and-audio at the carve's own page.
Lane interactions verified in source before documenting: the right-click menu
offers Ramp up, Ramp down, Swell, Dip, and Simplify (which needs three points).
Deliberately not documented: "clicking a lane label reveals it in the rack",
which is not on main.
mint validate and mint broken-links both pass.
* docs(audio): fix the four review blockers
All four verified in source before fixing; the review was right on every count.
**The registry was incomplete.** `pitchshift` ships at `audioFx.ts:509-535`
(`semitones` −12–12, `mix` 0–1, worklet-backed so neither automatable) and was
missing entirely — sixteen effects, not fifteen. It also joins the worklet list,
so five effects expose no automatable parameters rather than four.
**Three presets were missing.** `chipmunk`, `giant`, and `monster` ship at
`audioFxPresets.ts:336-357`, all built on `pitchshift`. Twenty-two presets, and
Character holds ten. Fixed in both the reference table and the Studio list.
**The copyable markup contradicted the warning above it.** The page said
`carve.mjs` only finds double-quoted attributes and then gave three
single-quoted examples — copying the chain example would make a later carve miss
the existing chain and overwrite it. All three are now double-quoted with
`"`, each followed by its unescaped reading so it stays legible.
**The attribute table over-claimed.** `data-audio-group` is a plain id, not JSON,
and is ignored on `<video>`; the other three also live on `<hf-audio-group>` for
a group. The table now carries shape and valid host per attribute.
**The automation contract was wrong on two axes.** A clip lane's `t` is
clip-relative but a GROUP lane's is composition time, because a group has no
`data-start` (`webAudioTransport.ts:337-342`, `audioMixer.ts:1311-1344`) — both
pages now split the two clocks. And `volume` is not 0–1: the ceiling is
`MAX_AUDIO_GAIN`, +12 dB or about 3.981 (`audioGain.ts:8-9`), so a boosting lane
is valid and documented.
**Current-main drift.** #3416 is merged, so the CLI now records the voices'
shared group when it is safe and falls back to clip ids when that group contains
the bed or a music/SFX member. Documented, including why neither refusal shows
up on the run that writes it, and rebased onto main.
mint validate and mint broken-links both pass.
* docs(audio): name the real add-menu family, and finish propagating pitchshift
Second review round. All three findings were my own incomplete propagation — I
corrected the reference for `pitchshift` last round and left the reader-facing
pages behind it.
**The add-menu family is `Time`, not `Space`.** `propertyPanelFxAddMenu.tsx:22-28`
labels the four groups Filters / Dynamics / Non-linear / Time, and the time group
holds pitchshift, delay, chorus, phaser, and reverb. The Studio page sent readers
looking for a group that does not exist. It is now a table naming the family and
its contents, and the reference's "Time — space and width" heading is retitled,
since that description stopped covering the family the moment pitch shift joined
it.
Also from the same file: the menu offers the named jobs in place of a bare
`peaking`, because picking `peaking` is picking a machine and leaving the real
decision — which range — for afterwards. Worth saying on the task page.
**Pitch shift was missing from both no-automation lists** that a reader actually
follows — `studio/audio-automation` and, unflagged but the same defect, the
prompting chapter. Five worklet effects in all four places now. Called out
explicitly on the Studio page, because a rising pitch is exactly the thing
someone reaches for a lane to do, and the lane will not report that it cannot.
**Narrowed the group-metadata sentence.** "The other three are JSON, and on a
group they live on `<hf-audio-group>`" swept in `data-fx-carve`, contradicting the
table directly above it. Only `data-fx-chain` and `data-automation` are group
metadata.
mint validate and mint broken-links both pass.
* fix(studio): put the timeline's portaled surfaces on the tier the other portals use
The FX popover, the grouping dialog it swaps for, and the automation selection
menu are all portaled to `document.body`, so they land in the root stacking
context — where they sat at `z-50` while the app's own chrome occupies 60, 90,
91, 92, 94, 100 and 110, and every other portal that has to clear that chrome
(`Tooltip`, `AssetContextMenu`, `InlineTextToolbar`, `RenderQueue`) already uses
`z-[200]`. These three were the odd ones out.
Scoped honestly: the clipping in the report is fixed by the height cap in the
previous commit, which is what actually cut the popover off at the timeline
chrome. This commit is tier consistency — it removes the standing risk of a
portaled timeline surface losing to any of those seven higher tiers, rather than
a demonstrated repro. Confirm against a real window before claiming more.
* fix(studio): move the remaining body-portaled context menus to the same tier
The all-sites audit in review was right and the previous commit did half the set.
Using `createPortal(…, document.body)` as the predicate rather than the timeline
directory, four more surfaces sit in the root stacking context at `z-50` below
the seven chrome tiers (60, 90, 91, 92, 94, 100, 110):
- `player/components/ClipContextMenu.tsx:51`
- `player/components/TrackGapContextMenu.tsx:78`
- `player/components/KeyframeDiamondContextMenu.tsx:99`
- `components/editor/CanvasContextMenu.tsx:215`
The fourth is the easy one to miss — it is the only one outside
`player/components/`, so a timeline-scoped sweep finds exactly the other three.
It belongs to the same set by its own account: its className is byte-identical
to `ClipContextMenu`'s and its header comment says it mirrors that file's look,
positioning, and dismiss behaviour, portaled to `document.body`.
Two body portals deliberately left alone. `sidebar/BlocksTab.tsx:125` portals
`PromptPreviewModal`, which carries its own `z-[100]`/`z-[110]` modal tier — a
`z-` class on the portal wrapper would be dead weight. `RenderQueue.tsx:235` is
already `z-[200]`. `FileTree.tsx:336` and `FileTreeNodes.tsx:103` are `fixed
z-50` but are NOT portaled — they render inside the sidebar's own stacking
context, so the root-context argument does not reach them and raising them would
be an unrelated change.
Crossing the `z-[100]`/`z-[110]` modal backdrops is unreachable for the same
reason it was for the first three: all four dismiss on an outside pointerdown,
so the press that opens a modal closes the menu first.
`CanvasContextMenu.test.tsx:95` asserted on `.fixed.z-50` to prove the menu did
NOT render; left as-is it would have passed vacuously against any tier. Updated
to the new class so it still fails if the menu renders.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(studio): correct the interval in the popover in-bounds test comment
`bottom: 32` with `maxHeight: 160` in a 200px viewport puts the box at y = 8..168,
not y = 8..40 — the bottom edge sits at `innerHeight - bottom`, and the comment
read it as the height instead. The assertions below already computed the right
geometry; only the stated interval was wrong, on a regression test whose comment
is the next reader's model of what it pins.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(studio): give the group row's caret the panel's glyph and size back
The timeline group row was the only disclosure caret in the studio still drawn as
a rotated 11px non-mono glyph. Both of the property panel's carets
(`hf-fx-preset-run-caret` in propertyPanelFxPresetRun, and
propertyPanelFxNodeOpenBody) swap between ▸ and ▾ in `font-mono`, so the same
affordance was rendering smaller and differently on the row than in the panel it
opens.
Now mono, a size up, and swapped rather than rotated — a rotated ▸ also sits
off-centre in its box because the glyph is not square.
Three tests, mounting the header: the swap, the absence of a rotate transform,
and the mono/size class. Verified all three fail against the previous caret.
* fix(studio): stop the caret comment and test name claiming a size match
Both reached past what was actually verified, and the comment is the part that
stays in the tree.
The comment said the caret matches the property panel's carets and "should not be
smaller here than it is there". Inverted for one of the two: the node-body caret
sits under `text-[9px]` (`propertyPanelFxNodeOpenBody.tsx:240`), so at 13px this
one is materially larger, and `hf-fx-preset-run-caret` has no size rule of its
own — its rendered size is unmeasured. Narrowed to the two claims that hold:
mono, and swapped rather than rotated.
The third test was named "matches the property panel's carets" but reads only
this component's own className, so the panel carets could move and it would stay
green. Renamed to what it pins.
No behaviour change.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(skills): make the carve CLI work against the published core, and honour its own group invariant
Two defects found by using the shipped feature end to end on a real project
rather than inside this repo.
**It could not load core at all.** `loadCore` resolved `./audio-carve` and
`./audio-fx` with `require.resolve`. The workspace manifest declares a `node`
condition, so that resolved fine here — but the PUBLISHED manifest
(`publishConfig.exports`) carries only `import` + `types`, so every consumer of
the released package got ERR_PACKAGE_PATH_NOT_EXPORTED for a package that ships
those files perfectly well. The script was broken everywhere except where it was
developed, and its error text blamed a missing/outdated package, which no
install can fix. It now keeps the project anchor and falls back to the manifest's
declared `import` target.
**It violated the invariant its own SKILL.md sets.** SKILL.md is explicit: "A
carve against more than one clip id is wrong. Group the clips and carve against
the group. This is an invariant, not a tip." The script wrote
`sources: voices.map((v) => v.id)` unconditionally, so every run against grouped
voices produced output that tripped the repo's own
`audio_carve_ungrouped_sources` lint rule, and a voice added to the group later
would silently play outside the carve's awareness. When every voice shares one
group it now records the group; mixed, partially grouped or ungrouped voices keep
their ids so the lint rule still fires on the case it is meant to catch.
`main()` moves behind an entry guard so the pure helper can be imported and
tested; `node carve.mjs` is unaffected (verified against a real composition).
Six tests, and the manifest hash is regenerated for the changed skill.
* fix(skills): run the carve CLI through symlinks, and keep the bed out of its own sources
Two blockers from review, both of the class this PR's first fix was about:
correct where it was developed, broken for the audience it ships to.
**The entry guard silently skipped `main()` through any symlinked path.**
`process.argv[1]` keeps the spelling the caller typed while `import.meta.url` is
derived from the realpath, because node resolves the main module's symlinks. So
the raw compare added to make the helpers importable turned the CLI into a no-op
that wrote nothing and exited 0. Reachable with no symlink of one's own: on macOS
`/tmp` is a link to `/private/tmp`, and `SKILL.md` documents the entry point as
`node <SKILL_DIR>/scripts/carve.mjs`, so any install placed behind a link breaks
too. Reproduced against the published core by a reviewer, not only inferred.
Fixed by realpathing the left side. This repo already documents and solves the
same trap in three scripts (`frame-packets-core.mjs`, `preflight.mjs`,
`project-dir.mjs`); the canonical comment is carried over verbatim. A local copy
rather than an import, because skills install independently — `hyperframes-audio`
has no dependency on `hyperframes-core` being present.
**`carveSources` could make the bed its own carve source.** It decided from the
voices alone, so a bed sharing their group (`mix`) got `sources: ["mix"]` written
onto it. `resolveCarveSourceIds` expands a group id to every current member and
takes no host element to exclude, so the next analysis in Studio hands the bed to
itself and the duck envelope fights the bed's own content instead of speech —
the "never carve a track against itself" invariant, arriving one re-analysis
after a first pass that was genuinely correct (`main()` sums the detected voices
directly and never round-trips through group resolution, which is why the PR's
own end-to-end check could not catch it).
The fix is at the call site, not in the resolver: neither `resolveCarveSourceIds`
nor `resolveCarveVoices` receives the host, so "make the resolver skip the
target" would be a signature change on shared core. `carveSources(voices, bed)`
declines the group form when the bed is a member and records clip ids, which is
exactly what `audio_carve_ungrouped_sources` exists to raise — plus a stderr note
saying why, so the lint message does not read as "group clips you already
grouped". Scoped to `<audio>` beds: group membership is audio-only, so a `<video>`
bed cannot be pulled in by an expansion and declining there would be a false
positive. SKILL.md now states the constraint next to the group invariant it
belongs to.
Tests: six added, closing both gaps review named. The bed-in-group regression and
a symlinked CLI invocation both fail on the previous commit (silent exit 0 vs the
usage error) and pass now; three more pin the cases that must NOT decline
(different group, ungrouped bed, video bed). `loadCore` is now exported and
covered by a fixture package carrying an import-only export map — the published
manifest's shape — so this PR's first fix is pinned without depending on npm.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(skills): refuse the carve group when a non-voice member would widen it
Closes the second branch of the original blocker, which the bed fix did not
cover: detected voices sharing `voiceover` with an existing SFX or music member.
Detection correctly leaves that member out, but the persisted `sources:
["voiceover"]` resolves wider on the next Studio analysis —
`resolveCarveSourceIds` expands the group to every current member and
`resolveCarveVoices` keeps any audio with a src — so the extra clip enters the
sidechain and the bed starts ducking under a whoosh. Same shape as the bed case:
the first pass is genuinely correct because `main()` sums the voice list
`detectTracks` returned and never round-trips through group resolution.
Taking the first of the two suggested fixes (membership + classification in the
collapse decision) rather than deriving the first pass from the resolved group:
analysing whatever the group happens to hold would make the CLI measure clips it
classified as non-voice, which is the arrangement problem rather than a licence
to sidechain them.
`groupSourceRefusal(voices, bed, members)` replaces `bedInVoiceGroup` and returns
`{group, reason, ids}` or null, so the decision and the stderr note come from one
place. `members` is every `<audio>` in the composition as `{id, group, nameKind}`
with `nameKind` from core's `classifyAudioName`, so this and Studio's picker
classify identically. `detectTracks` now returns the media list it already built.
Classification, not membership, is what makes this safe. A member classified
`music` or `sfx` blocks the group; a member classified `voice` or `unknown` does
not. That distinction is load-bearing: `detectTracks` only analyses voices that
overlap the bed, so an outro line that starts after the bed ends is routinely a
group member this run did not measure — and covering it on a later analysis
without editing `sources` is the entire reason SKILL.md says to name the group.
Refusing on "any member the run did not analyse" would collapse the group form
into clip ids for every ordinary narration sequence. `unknown` follows detection's
own loose-in-the-safe-direction rule, since detection treats an unknown name as a
possible voice.
The note now names the blocking member, for either reason, since "sources are
clip ids" plus `audio_carve_ungrouped_sources` reads as nonsense to an author who
did group their clips.
Tests: six added, 18 in the file. The two regressions (sfx member, music member)
and the refusal shape fail with the mixed branch ablated and pass with it; three
more pin the cases that must NOT refuse — a non-overlapping voice member, an
`unknown` member, and an sfx member of a different group. SKILL.md states both
refusals and the voice-member exemption next to the group invariant.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* test(skills): make `members` required so dropping it cannot undo the widening fix
Review finding, and the one link no test covered. `carveSources` and
`groupSourceRefusal` defaulted `members = []`, and with an empty list the `mixed`
refusal cannot fire — so a refactor that dropped the third argument at the call
site would return the group form again with the entire suite green.
That is the same signature as the bug the argument exists to prevent: `main()`
sums the detected voice list directly, so the first CLI pass is correct either
way and only a later Studio re-analysis reads the widened attribute. Nothing goes
red. `main()` is also the only code that BUILDS `members`, and no test runs it —
the symlink test stops at the usage error and a real run needs ffmpeg.
Both defaults are gone, so a missing argument throws on `members.filter`. The
nine cases that predate the membership check now pass `[]` explicitly, which
also documents that they are about the bed and the group attributes alone, and a
new test asserts both functions throw when the argument is omitted. Verified it
fails when the defaults are restored.
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(studio): put the timeline's portaled surfaces on the tier the other portals use
The FX popover, the grouping dialog it swaps for, and the automation selection
menu are all portaled to `document.body`, so they land in the root stacking
context — where they sat at `z-50` while the app's own chrome occupies 60, 90,
91, 92, 94, 100 and 110, and every other portal that has to clear that chrome
(`Tooltip`, `AssetContextMenu`, `InlineTextToolbar`, `RenderQueue`) already uses
`z-[200]`. These three were the odd ones out.
Scoped honestly: the clipping in the report is fixed by the height cap in the
previous commit, which is what actually cut the popover off at the timeline
chrome. This commit is tier consistency — it removes the standing risk of a
portaled timeline surface losing to any of those seven higher tiers, rather than
a demonstrated repro. Confirm against a real window before claiming more.
* fix(studio): move the remaining body-portaled context menus to the same tier
The all-sites audit in review was right and the previous commit did half the set.
Using `createPortal(…, document.body)` as the predicate rather than the timeline
directory, four more surfaces sit in the root stacking context at `z-50` below
the seven chrome tiers (60, 90, 91, 92, 94, 100, 110):
- `player/components/ClipContextMenu.tsx:51`
- `player/components/TrackGapContextMenu.tsx:78`
- `player/components/KeyframeDiamondContextMenu.tsx:99`
- `components/editor/CanvasContextMenu.tsx:215`
The fourth is the easy one to miss — it is the only one outside
`player/components/`, so a timeline-scoped sweep finds exactly the other three.
It belongs to the same set by its own account: its className is byte-identical
to `ClipContextMenu`'s and its header comment says it mirrors that file's look,
positioning, and dismiss behaviour, portaled to `document.body`.
Two body portals deliberately left alone. `sidebar/BlocksTab.tsx:125` portals
`PromptPreviewModal`, which carries its own `z-[100]`/`z-[110]` modal tier — a
`z-` class on the portal wrapper would be dead weight. `RenderQueue.tsx:235` is
already `z-[200]`. `FileTree.tsx:336` and `FileTreeNodes.tsx:103` are `fixed
z-50` but are NOT portaled — they render inside the sidebar's own stacking
context, so the root-context argument does not reach them and raising them would
be an unrelated change.
Crossing the `z-[100]`/`z-[110]` modal backdrops is unreachable for the same
reason it was for the first three: all four dismiss on an outside pointerdown,
so the press that opens a modal closes the menu first.
`CanvasContextMenu.test.tsx:95` asserted on `.fixed.z-50` to prove the menu did
NOT render; left as-is it would have passed vacuously against any tier. Updated
to the new class so it still fails if the menu renders.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(studio): correct the interval in the popover in-bounds test comment
`bottom: 32` with `maxHeight: 160` in a 200px viewport puts the box at y = 8..168,
not y = 8..40 — the bottom edge sits at `innerHeight - bottom`, and the comment
read it as the height instead. The assertions below already computed the right
geometry; only the stated interval was wrong, on a regression test whose comment
is the next reader's model of what it pins.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(studio): cap the timeline FX popover to its gap, and scroll the list inside
The popover grew to whatever the preset list needed, so on a short window it ran
off the top or the bottom of the viewport and took its footer ('+ effect' /
'Open rack') with it — nothing scrolled, so the presets past the edge were
simply unreachable.
It now caps to the space on whichever side it opens toward, and the preset list
scrolls inside that while the footer stays put. `min-h-0` on the scroller is
load-bearing: a flex child defaults to min-height:auto and would refuse to
shrink, pushing the footer out instead of scrolling.
`spaceAbove` is named for the cap's benefit; it equals `anchorRect.top`, so the
flip condition is unchanged.
Four tests cover it, because this shipped once before with none: the downward
cap, the upward cap, the usable-minimum clamp, and the footer being a sibling of
the scroller rather than inside it. Verified they fail without the cap.
* fix(studio): slide the FX popover in-bounds instead of hanging it off the edge
Review found the minimum defeating the viewport cap: `Math.max(MIN_POPOVER_HEIGHT,
available)` kept the box 160px tall even when the chosen gap was smaller, so the
box extended past the edge it opened away from. At 200px of viewport with the
anchor at 100..120 it flipped up to `bottom: 104px` and spanned y = -64..96 —
every preset still reachable, but through a ~57px window with the top third of
the dialog off-screen. Reachable at high browser zoom, not only in a synthetic
short window: `available` drops under 160 once the gap is under ~172px, which
400% zoom on a 1080p display produces on both sides.
Shrinking to the gap would undo the floor on purpose (a 20px gap gives a 20px
popover — the vanishing popover in a new costume), so honour the floor and clamp
the resulting box into the viewport the way `left` already is. Two parts:
- Cap the floor by the window itself (`innerHeight - 2 * VIEWPORT_MARGIN`). The
minimum is a floor against a tight gap, not against a tight window; below
176px of viewport, physical space has to win.
- Inset the `top` / `bottom` offset to `innerHeight - height - VIEWPORT_MARGIN`,
so a floor larger than the gap slides the box back in rather than off the top.
The tight case now lands at `bottom: 32px` with `maxHeight: 160px` — the box at
y = 8..40, one margin on each side. The two ordinary cases are unchanged
(34/726 down, 72/688 up), which the existing tests pin.
Tests: two added — both edges in-bounds when the minimum exceeds the gap, and
the floor yielding when the whole window is shorter than it. Both fail on the
previous arithmetic (104px vs 32px, 160px vs 104px). The three pre-existing
geometry tests now pin `window.innerHeight` through one shared helper instead of
inheriting happy-dom's 768 default, so their expected numbers are derivable from
the test and immune to a dependency bump.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
## What
Adds a one-shot ffmpeg-psnr filter probe at drawElement session bootstrap.
When the resident ffmpeg is missing or lacks libpostproc (no `psnr` filter),
the capture-session router now force-fallbacks to the screenshot capture
path and emits a `de_gate_reason = "ffmpeg_no_psnr_filter"` telemetry
signal via the existing `render_complete` breakdown.
Also tightens `psnrForDiskSample`'s catch: infrastructure-class ffmpeg
failures (ENOENT, "No such filter") no longer silently skip the sample —
they abort the render so the safety net cannot fail-open post-preflight.
## Why
The drawElement self-verify safety net (parallelCoordinator's
`psnrForDiskSample` → `psnrDb`) shells to `ffmpeg -lavfi psnr`. If ffmpeg
is missing, or was compiled without libpostproc (so the `psnr` filter is
absent), every per-sample compare throws. The existing catch swallows the
error and returns `null` — callers treat that as "skip this sample" and
the render completes with the safety net inoperative.
Field signal (⭐ 9/10 CLI feedback, Slack ts=1787380767.210079,
hyperframes 0.8.7, darwin/arm64, tid=93ff9910-2207-45c2-bc1f-54c0b347d4fe):
> "host ffmpeg lacked psnr filter used by drawElement self-verification,
> but render completed."
The user's frames happened to be byte-identical so no visual damage
shipped — but the safety net silently wasn't running. Any future
compositor-damage bug on that host would have shipped straight through.
## How
Two-part fix, both in `packages/engine`:
1. New `utils/psnrFilterAvailability.ts` — cached probe that runs
`ffmpeg -hide_banner -filters` once per process and word-boundary-
matches `psnr` in the output. Any failure (ENOENT, non-zero exit,
timeout, unparseable output) returns `false`; never rejects.
2. Wired into `services/frameCapture.ts` `initDrawElementOrTransparentBackground`
right after the Chrome capability probe: when useDrawElement resolves
true and the preflight returns false, set
`session.deGateReason = "ffmpeg_no_psnr_filter"` (same low-cardinality
bucket every other DE gate uses; flows through `getCapturePerfSummary`
→ `render_complete.de_gate_reason` in PostHog), emit a stderr warning
naming what's missing, and call `routeToFallback()` — the same
fail-graceful shape as the SwiftShader / CSS-effect / at-risk-timeline
gates. Skipped under `HF_FORCE_DRAWELEMENT=1` (matches the diagnostic
knob's policy of bypassing every other gate).
Belt-and-braces: `psnrForDiskSample` now discriminates infrastructure-
class failures (ENOENT / "No such filter" / "Unknown filter") from
per-sample noise (readFile races, transient EPERM). Only the former
re-throw — per-sample noise still returns `null` (skipped sample). The
preflight normally catches this at bootstrap; the re-throw covers
ffmpeg-swapped-mid-render.
## Test plan
- [x] Unit tests added:
`packages/engine/src/utils/psnrFilterAvailability.test.ts` — mocked
`execFile` covers: `psnr` present → true; `psnr` absent → false; ENOENT
→ false; non-zero exit → false; result memoized + reset works;
substring-not-word-boundary → false.
- [x] Unit tests added:
`isFfmpegInfrastructureFailure` in
`packages/engine/src/services/parallelCoordinator.test.ts` covers
ENOENT, "No such filter", "Unknown filter", per-sample EACCES, parse
errors, null/non-object.
- [x] `bun run test` — `packages/engine/src/utils/psnrFilterAvailability.test.ts`
(6 tests) + `packages/engine/src/services/parallelCoordinator.test.ts`
(50 tests) + `frameCapture.test.ts` (26 tests) all pass. Pre-existing
ffprobe test failures (4) on the base commit are unrelated (missing PNG
fixture bytes — the file is 129 B on disk, likely LFS-stored).
- [x] `bunx tsc --noEmit -p packages/engine/tsconfig.json` — clean.
- [x] `bunx oxlint <files>` — 0 warnings, 0 errors.
- [x] `bunx oxfmt --check <files>` — clean.
Not covered here: an integration test that boots
`initDrawElementOrTransparentBackground` end-to-end. That path is
Puppeteer-driven and has no unit-scale bootstrap harness in the
repository — the pure preflight + pure discriminator coverage above are
what this PR can prove at the vitest layer.
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Closes#3370
## What
When `hyperframeRuntimeLoader` could not locate `hyperframe.manifest.json`, the loader reported a single fallback path that was never searched for (`/usr/local/lib/core/dist/hyperframe.manifest.json`). Inside a Docker render the user is then told to look at the wrong directory; the file that was actually missing (`/usr/local/lib/node_modules/hyperframes/dist/hyperframe.manifest.json`) was nowhere in the message.
## Why
`resolveHyperframeManifestPath()` built a 5-element `candidates` array, walked it with `existsSync`, and on total miss returned the last candidate. The error then quoted that candidate verbatim. The reporter even shows the exact reproducing command from a published image.
A second issue rode the same failure path: `packages/cli/src/commands/render.ts:902` keeps attaching the hint `"Try --docker for containerized rendering"` to users who are *already inside* the container. The container sets `ENV CONTAINER=true` and nothing reads it.
A third small thing came along: `CWD_RELATIVE_MANIFEST_PATHS[0]` was a byte-identical duplicate of `SIBLING_MANIFEST_PATH` — same path, two names.
## How
1. Hoist the candidate list to a single `MANIFEST_CANDIDATES` owner in `hyperframeRuntimeLoader.ts` and share it between the resolver and the error reporter. De-duplicate while doing it.
2. Add `triedManifestPaths()` as a tiny export so callers (and tests) can see what was actually searched.
3. Replace the source-text regex test that asserted on string positions inside `const candidates = [...]` with a behaviour test that points `PRODUCER_HYPERFRAME_MANIFEST_PATH` at a missing file and asserts the thrown error names it. Also exercise the no-override branch to confirm the sibling path is the first entry.
4. In `render.ts`, check `process.env.CONTAINER === "true"` before attaching the `--docker` hint. The chrome-launch and macos-old-chrome remediation branches already short-circuit before the hint, so an empty string is a safe value when the user is in the container.
## Test plan
- [x] `bunx vitest run src/services/hyperframeRuntimeLoader.test.ts` — 7/7 pass (`hyperframeRuntimeLoader error path (#3370)` describe covers the missing-manifest message and the tried-paths export).
- [x] `bunx tsc --noEmit` in `packages/producer` and `packages/cli` — clean.
- [x] `bunx oxfmt --check` and `bunx oxlint` on the touched files — clean.
- [x] `bunx fallow audit --base origin/main` — no new findings on the touched files.
- [x] Targeted producer unit lane: `node scripts/run-test-lane.mjs unit` — same 7 pre-existing failures as `origin/main` before the change (htmlCompiler.parity, audioPadTrim.integration); no regressions introduced.
Files touched:
- `packages/producer/src/services/hyperframeRuntimeLoader.ts`
- `packages/producer/src/services/hyperframeRuntimeLoader.test.ts`
- `packages/cli/src/commands/render.ts`
Miguel Ángel