Commit Graph
386 Commits
Author SHA1 Message Date
Miguel Ángel fa44d7621d feat(core): a composition with no authored length takes it from its clips (#4174)
* feat(core): a composition with no authored length takes it from its clips

A new resolver in @hyperframes/parsers returns a composition length as authored,
derived from its latest clip end, or unresolved, and counts clips whose length is
still pending. The runtime uses it in its two existing max-end loops with identical
results, and as a last resort only when no timeline, floor or caller length exists,
so a composition that has a length today keeps it. The derived source is published
on window.__hf.durationSource for render telemetry.

Lint reports a root that has timed clips but no data-duration as a warning that says
where to author it, and still errors when there is nothing to derive from.

* refactor(core): resolve the runtime duration floor in one call

The declared duration and sub-composition ends were resolved separately and
maxed by hand; one resolver call over both gives the same latest end.

* fix(core): a derived composition length waits for every clip length and reports honestly

Review follow-up. The runtime returns a content-derived length only when no clip is
still pending, so a renderer that reads duration once cannot lock in a short one.
window.__hf.durationSource is cleared whenever a timeline or floor supplies the length,
and the diagnostic fires only for a derived length. Lint says "at least Ns", counts
reference-start clips as known only at runtime, and ignores a data-end before data-start.

* fix(core): a sub-composition with no known length counts as pending

A host whose own timeline is not registered yet no longer lets the content-derived length
show early. Tests pin the pending host and that the diagnostic fires only for a derived length.

* fix(core): a loaded Lottie with no registered animation keeps the length pending

Lottie registers from author scripts with no DOM marker, and nothing re-derives the length
after it registers. A composition with clips and a loaded Lottie library therefore stays at
zero, as before, instead of locking in the clips length and cutting the animation short.

* test(core): a registered Lottie supplies the length and the clips length is not used

Pins the other side of the pending Lottie rule. Once an animation reports a length it enters the
duration floor, so the content-derived fallback is never consulted.

* test(core): the declared and DotLottie pending branches are covered
2026-09-19 11:27:33 -04:00
Miguel Ángel ac0d8ced2a fix(cli): timeline lists every clip of a kind in one flat list, nested ones included (#4173)
Text: one absolute-start list per kind, nested clips marked with host and file.

JSON: a track's rows hold every clip of that kind; children are index pointers, not copies.
2026-09-19 10:36:30 -04:00
Miguel Ángel 7597b80c95 fix(cli): timeline reports real media durations instead of unauthored (#4169)
* fix(cli): timeline resolves real media durations instead of printing unauthored

Media rows call the shared resolveMediaDuration with an ffprobe source length.

Each row shows its duration source, or pending with the reason a probe failed.

Absolute time (absStart/absEnd) is carried across sub-compositions.

Remote, absolute and parent-relative srcs are never probed.

* fix(cli): timeline probe leaves the authored-duration rule to the resolver

The gate test now launches jobs while slots are held.

* fix(cli): timeline reports a zero-length probe as pending instead of a measurement

A still image or duration-less container is pending with a reason, never duration=media.

The runOneLiner test helper now cleans up its own fixture directory.

* fix(cli): timeline probe is injectable and the fixture path works on windows

Two unit tests used real ffprobe, which the Ubuntu Test job lacks, and the audio

fixture path doubled the drive letter on Windows. describeProject now takes the

measure function, the tests pass a recorded fake, and one real-ffprobe test remains.
2026-09-19 09:27:28 -04:00
Miguel Ángel 2f24573395 docs(skills): an agent adds media with the duration Studio gives a dropped file (#4144)
* docs(skills): an agent adds media with the duration Studio gives a dropped file

* docs(skills): add-media recipe matches Studio's full-frame geometry and z-index

* docs(skills): recipes start with hyperframes timeline to see tracks and clips

* test(skills): split the add-media drift test so each check stays small and formatted

* test(skills): split addMediaFacts into single-purpose helpers to clear the CRAP-score gate

* docs(skills): add-media recipe needs only data-start for video and audio

* docs(skills): add-media intro names the video and audio difference and a test guards it

* docs(skills): add-media image duration is optional and defaults to 3 seconds

* chore(skills): regenerate the skills manifest after rebasing onto main

* docs(skills): tracks-and-clips says image duration is optional, and a test pins the 3

* test(skills): split the add-media example check into small helpers

Clears the Fallow complexity finding on the test callback.
2026-09-19 09:07:32 -04:00
Miguel Ángel 09aadd86a5 feat(core): video, audio and image length come from one shared resolver (#4166)
A new resolver in @hyperframes/parsers decides how long a video, audio or image
occupies the timeline. The core runtime start resolver, clip manifest and clip
tree now read length through it. An image with data-start and no data-duration
gets the dropped-image default of 3 seconds; a bare image stays a static layer.
Video and audio take their length from the file until an authored duration trims it.

The playback rate bound (0.1 to 10) now lives in parsers, and core re-exports it.
A rate lane keeps its own arithmetic in core.

The lint rule that asked images for data-duration is removed, and the docs no
longer say an image requires it.
2026-09-19 08:01:28 -04:00
Miguel Ángel 0a5c235173 feat(cli): hyperframes timeline prints a project's tracks and clips (#4138)
* feat(cli): hyperframes timeline prints a project's tracks and clips

* docs(cli): list the timeline command

* feat(cli): timeline command reports unreadable lanes; add skill docs

* fix(cli): timeline stays inside the project, shares one start cache, keeps small volumes

* fix(cli): timeline resolves symlinks before the project containment check

* fix(cli): timeline accepts project folders whose name starts with two dots

* refactor(cli): timeline and compositions share the engine's start resolver

* docs(skills): point agents at the timeline command where they decide how to read a project

* fix(cli): timeline prints absolute main-timeline times and the owning file for nested clips

Nested rows carry absStart/absEnd on the main timeline and their owning
file, alongside existing local start/end. Text prints absolute time first,
local time in parentheses. Adds jq/node one-liners for common queries,
tested against a fixture.

* fix(cli): timeline places nested media at the runtime start and tests its query one-liners

A nested media clip with a negative literal data-start was reported later than it plays,
because the raw start was clamped before the host offset was added. The skill's jq and node
one-liners now run against the fixture in the test suite.

* fix(cli): timeline clamps a negative media start to 0 when its host starts at 0

The runtime skips the host-offset formula for a host at t=0 and clamps the start, so the
timeline command now does the same.

* refactor(core): one media-start rule shared by the runtime and the timeline command

The runtime and the CLI each carried a copy of the rule for when a nested media clip's
start takes the host offset, and the copies had drifted. Both now call
resolveMediaStartSeconds.

* test(cli): timeline fixture for a media start written as an expression

parseNumeric and the runtime's parseStrictFiniteTimingNumber are the same function, so the
two callers cannot disagree on what counts as a literal; this pins the expression case.
2026-09-19 04:27:45 -04:00
752b552789 feat(registry): blur an element by marking it, not by calling a function (#4045)
attachMotionBlur(el, tl) has an ordering contract: it has to run after every
tween is defined and before the composition registers its timeline. Getting it
wrong makes the blur silently do nothing, which is the worst shape a failure can
take in a renderer nobody watches. An attribute has no order to get wrong.

data-hf-motion-blur on any element is now the contract. Empty means defaults;
anything else is a JSON object of the same options. The element finds its own
timeline: its nearest [data-composition-id] ancestor names the key, and the
snippet reads window.__timelines[key]. attachMotionBlur stays exported for a
target built after the page has settled.

claim(el) is the only thing that attaches, and two triggers call it. An accessor
on window.__timelines wraps the registry in a Proxy whose set trap sweeps on
every per-key registration, which is what attaches before the renderer captures
frame zero. A bounded poll, 32 ms by 250 ticks, reads the registry directly and
needs no cooperation from whoever wrote it. The poll is not belt and braces: a
registry reference captured before the snippet installs bypasses the trap
outright, and a composition that mounts its DOM after registering its timeline
has no marked element to sweep at trap time. It runs its whole budget every time
rather than stopping the first tick nothing is pending, because on an ordinary
page the top-level target is claimed on the registration write, so an early exit
kills the poll one tick in, before any late composition arrives.

Every refusal is by name, once, and never silent: a value that is not JSON, a
value that parses but is not an options object, an option name that is not one
of the four, an option value that is not a finite number, a target inside
another target, and a second timeline registered under one key. Parsing runs
before the timeline lookup, so a malformed value is reported as malformed rather
than as a composition that never registered.

Two properties of the primitive this change made load-bearing:

- Frame rate is resolved from the target's own composition root, not from the
  first root in the document. The document-wide lookup was survivable while
  every caller could pass fps explicitly; the declarative form has no per-call
  argument. Two compositions on one page at different rates now each get their
  own shutter window, and one call naming both says it cannot.
- An attach is all-or-nothing. The mark, the copies and the resize observer go
  in together and come back out together, so a throw partway through leaves the
  element untouched rather than marked blurred with copies in the page and no
  tracker driving them. The sweep is also bounded per element, because the write
  trap runs it inside the author's own registration statement.

Copies are stripped of data-hf-motion-blur, data-composition-id and data-fps,
on the clone and every descendant: the first would make a copy a target of its
own, and the other two would let a copy win the fps lookup, since copies are
inserted before the original.

skills/hyperframes-animation/references/motion-blur.md is the agent-facing half,
mirroring how colour grading is surfaced. It leads with when NOT to blur,
because the attribute makes blurring everything trivial and a smear on motion
that was never fast enough reads as a soft, cheap render.

Co-authored-by: Miguel Ángel <miguel.sierra@heygen.com>
Co-authored-by: Vance Ingalls <vance@heygen.com>
Co-authored-by: Claude Code <noreply@anthropic.com>
2026-09-18 22:55:15 -07:00
Miguel Ángel 1a9668b6d6 docs(skills): the agent presents a tailor-made storyboard instead of a Studio board (#4150)
* docs(skills): the agent presents a tailor-made storyboard page instead of a Studio board

Adds the storyboard recipe (decisions first, beat fields, a self-contained
storyboard.html contact sheet, a review round) distilled from the launch
films, and rewrites the review loop, brief contract, storyboard format and
workflow steps that still described the deleted board and comments file.

* docs(skills): reconcile the sketch pass with the beautiful storyboard sheet

Review found: the recipe's storyboard.html cell spec (real fonts, real
colors) contradicted review-loop's own sketch definition (wireframe, no
brand treatment). The sketch is static, not unstyled; only motion is
deferred to the build pass. Also fixes a frame-packet boundary note, a
craft-device citation, and a provenance overclaim.
2026-09-19 01:07:24 -04:00
Miguel Ángel a25da94b77 refactor(studio): remove the storyboard view and its Storyboard/Preview switch (#4140)
* refactor(studio): remove the storyboard view and its Storyboard/Preview switch

* refactor(studio): fold the thumbnail output branches left after the storyboard mode went

* docs(studio): drop leftover storyboard references after the view was removed

* ci: allow the storyboard view deletions in the no-deletions guard

* docs(studio): wrap an over-long comment line in the caption overlay helper

* style(studio): reindent App.tsx after the view-mode wrapper was removed
2026-09-18 23:47:12 -04:00
Miguel Ángel 2db126d4c8 docs(skills): one owner doc for everyday edits and a hyperframes-studio skill (#4125)
* docs(skills): one owner doc for everyday edits and a hyperframes-studio skill

Agents got contradictory advice on volume fades and were blocked from splits
and copies by the Ask-agent guardrails.

- creator-editing-recipes.md is the single owner: adds align-to-event,
  copy-a-group and swap-media recipes and the one volume rule (use the lane)
- variables-and-media, data-attributes (skill and CLI copy), the gsap adapter
  and tracks-and-clips now defer to it
- Ask-agent guardrails allow the neighbour edits a split, retime, copy or swap
  requires and point at the owner doc
- new hyperframes-studio skill: sub-compositions for every scene, one caption
  track, one element kind per track, safe zones
- drift test lints every html example in the owner doc with the real linter
  and fails on any doc teaching a volume tween

* refactor(skills): drop unused tween allowlist from recipes drift test

* docs(skills): name the track kind attribute in the studio skill

* docs(skills): stop claiming lint rules that do not exist yet and fix track numbering

Review fixes:

- studio skill: drop the severity claim and the preview-overlay claim,
  group tracks by data-track-kind instead of numeric ranges that clashed
  with the recipes
- recipes: audio data-start is root time only in the root composition;
  scene-local inside a sub-composition file
- guardrails: timeline edits are exempt from the element-only and timing
  lines; the pointer names the skill reference, not a repo path
- montage doc defers to the volume lane; skill count is 21 everywhere
- drift test also scans the montage doc

* fix(skills): the ducking generator emits a volume lane and captions defer to the studio safe zones

- audio-duck.mjs prints a data-automation lane (clip-local times from the
  target data-start) instead of a timeline volume tween; --json adds the lane
- operations.md shows the generated lane; the drift test scans it
- embedded-captions safe-zone lines point at the studio skill, which owns
  the values

* chore(skills): regenerate the skills manifest after rebase

* docs(skills): remotion translation docs point volume ramps at the automation lane

* docs(skills): studio safe zones use the action-safe 90 and title-safe 80 boxes

* docs(skills): caption docs defer to the studio safe boxes

* chore(skills): regenerate the skills manifest after rebase

* fix(skills): studio skill names the safe margins; guardrail test matches the timeline-edit wording
2026-09-18 23:19:40 -04:00
Miguel Ángel ae0e8fcae1 fix(skills): teach and ship the remotion translation as sub-compositions (#4141)
* fix(skills): teach and ship the remotion translation as sub-compositions

The converter reference fixtures now emit one sub-composition per scene
under a mounting root, and the api map, sequencing guide and tier-2 README
teach that shape instead of the flat data-start div. SSIM per tier is
unchanged (t1 0.974415, t2 0.985993, t3 0.953275 to 0.953281).

* docs(skills): make every remotion translation doc teach the sub-composition shape

SKILL.md step 3, the sequencing guide (nested, series, crossfade), the api map
asset rows, and the parameters guide now match the shipped fixtures.

* docs(skills): say where scene cuts versus cross-scene fades live
2026-09-18 21:01:59 -04:00
Miguel Ángel f2976536de fix(skills): mount music-to-video motion primitives as sub-compositions (#4136)
* fix(skills): mount music-to-video motion primitives as sub-compositions

Each primitive's root now only mounts scene.html, so the root is built from
a sub-composition and the structure lint has nothing to flag. Renders match
the originals (31 of 37 identical, the rest above 54 dB PSNR).
Registry examples mark their caption layer with data-track-kind=captions.

* fix(skills): keep primitive variables and page styles where the runtime reads them

Composition variables move onto the sub-composition element, the dead
#scene rule is dropped, and the frame-worker doc names where page styles
live.

* fix(skills): shorten a carried-over comment in the kinetic-letter-in scene
2026-09-18 20:57:54 -04:00
Miguel Ángel 6995a4c2f7 feat(studio): the agent sees every timeline clip, audio included (#4123) 2026-09-18 18:47:32 -04:00
Miguel Ángel e36a53d6b6 fix(core): hold render-ready on declared compute, not just adapter loaders (#4065)
* feat(core): hold render-ready on declared compute and a build-ready hold, not just duration

Adds the compute and paint-and-idle inputs to the composition readiness gate,
plus window.__hf.buildReady: a promise registry a piece registers when it has
setup work no adapter can see (mesh building, shader compiles). The runtime
holds render-ready on it and the player shows its loading state instead of a
blank frame while it resolves.

* refactor(core): dedupe the paint-and-idle readiness test setup

Simplify pass on 23810da1b: fallow flagged the two paintAndIdleReadinessInput
tests as a 12-line clone; extracted the shared doc/tracking setup.

* fix(core): stop the readiness settled-tracker hanging on 2+ pending promises

Promise.all allocates a new promise every call, so comparing ITS identity
across repeat polls (isAdapterReadinessSettled, isBuildReadinessSettled) never
observes settled once 2+ promises are combined: every poll rebuilds a new
combined promise, re-arms, and republishes forever without the caller ever
seeing true. Reproduced with two already-resolved window.__hf.buildReady
entries, which is the exact multi-piece usage the new authoring doc describes.

Fixes both trackers at once with a shared createSettledTracker that compares
the source promise array by element instead of the Promise.all wrapper.

* fix(core): cancel readiness inputs once settleCompositionReadiness settles

computeReadinessInput's poll timer and paintAndIdleReadinessInput's rAF chain kept
running after the shared timeout won the race, since nothing told the losing
inputs to stop. One AbortSignal now threads through all three inputs and is
aborted the instant the race settles.

* docs(core): fix a stale sync-callback claim in settleCompositionReadiness

paintAndIdleReadinessInput always has a frame to wait on for any real
document, so the sync fast path this docstring described is no longer
reachable with the default inputs except for a viewless document.
Found by the simplify pass on this branch.

* fix(core): clear a stale buildReady entry on runtime teardown

A never-resolved window.__hf.buildReady promise from a torn-down
composition survived into the next init in the same window (window.__hf
is never reset), permanently blocking render-ready for whatever loaded
next -- the exact black-screen class this branch fixes, reproduced
through its own new mechanism. Found by the independent review.

Also fixes a stale hyperframes-player.ts docstring (media/images/fonts
had not been updated to compute + paint-and-idle) and documents the
buildReady key-collision hazard in three.md.

* fix(core): skip the compute readiness wait when no runtime ever ran

computeReadinessInput polled window.__renderReady for the full shared
timeout on any same-origin document with no HyperFrames runtime
injected (a probe-only composition using native video/duration, or a
blank test iframe) — nothing was ever going to set that flag. Checking
window.__hf first (the same signal composition-probe.ts already treats
as "has a runtime") lets it return null instead of waiting.

* fix(player): debounce the loading overlay and diagnose compute timeouts

paintAndIdleReadinessInput always has a frame to wait on for an
attached iframe, so settleCompositionReadiness's synchronous-settle
path is unreachable in practice now — the loading overlay showed on
every single Play, even ones with nothing genuinely pending. Debounce
the overlay itself instead: a wait that resolves fast never shows it.

Also names compute (window.__renderReady) in the stuck-assets timeout
diagnostic, which previously only re-scanned media, images and fonts.

* fix(engine): name a stuck buildReady key in the zero-duration diagnostic

A build promise a composition registers on window.__hf.buildReady that
never resolves left the export path's zero-duration timeout naming
nothing useful — hasHf/hasSeek/duration all looked fine, since the
runtime was genuinely present and just waiting on that one promise.
Probes buildReady's keys for pending ones and names them in the hint.

* fix(engine): stop the buildReady diagnostic from crashing on a rejection

A microtask race against a bare resolved promise rejected the whole
diagnostic expression on any rejected buildReady entry (the runtime's
own createSettledTracker rejects deliberately) and mis-sorted a settled
non-native thenable as pending, since its extra adoption tick loses the
race. Both measured directly, not inferred.

Settle each key onto its own record past one macrotask instead: no
throw, and pending/resolved/rejected are distinguished correctly. A
rejected key gets its own hint, separate from a merely pending one.

* fix(player): report a backgrounded document instead of overclaiming a paint bound

MAX_PAINT_WAIT_MS only bounds a document that keeps producing frames; one
that stops entirely (backgrounded tab suspends rAF, or fewer than 3 frames
ever fire) still rides the full shared 8s timeout, same as before this
input existed. Corrected the comments that claimed otherwise.

That gap is exactly why the stuck-assets diagnostic left paint-and-idle
unreported: there was no accurate way to say it might be the cause. Added
documentHidden (doc.hidden) to the diagnostic instead, since a backgrounded
tab is the reachable, directly observable case.

* refactor(engine): simplify the buildReady diagnostic rewrite

Skip the macrotask wait entirely when a composition registers no
buildReady keys — the common case, since it's opt-in. Nothing to settle
means nothing to wait on.

Collapse buildZeroDurationDiagnostic's inline parameter type into the
existing HfDiagnostic interface instead of maintaining two copies of
the same shape.

* docs(engine): note the setTimeout(0)-thenable gap the review found

An independent adversarial review, executing hostile inputs rather than
tracing, found the macrotask wait can still misreport a thenable that
resolves via its own internal setTimeout(0), since the diagnostic's own
timer is registered before the thenable's. Bounded and self-correcting
(only feeds the message text, and the diagnostic re-runs every ~1s), so
documenting the boundary rather than chasing an unbounded fix.
2026-09-18 11:12:44 -04:00
Aditya Poudyal e4b1832fad feat(cli): add hls output format (#4022) 2026-09-16 21:09:14 -04:00
miga-heygenandMiguel Ángel 3704863d96 feat(telemetry): per-tag, provenance, and failure-taxonomy properties on render events (#4004)
* feat(telemetry): add per-tag element and a-roll counts to render_complete

countElementTags's single regex scan (the ~83% of renders that get no
live probe session) is extended into scanElementTags, which returns a
per-tag breakdown and an a-roll video count alongside the same total,
all from one pass over the same script/style-stripped markup — the
total is the sum of the per-tag map by construction, so the two
properties can't drift apart. countElementTags itself is removed; it
had zero production callers after this change.

New render_complete properties: composition_element_tags ({tag: count},
raw lowercase tag names, capped at the top 50 by count with the rest
folded into an "other" key) and aroll_video_count (<video
data-aroll="true"> elements from the same scan). Both are static-scan-
only, mirroring the existing composition_element_count_source split —
the live probe-DOM path never runs this scan.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>

* feat(telemetry): count HeyGen-provenance video from the same tag scan

heygenVideoCount joins arollVideoCount/byTag as a third property
derived from scanElementTags's single pass: <video
data-media-source="heygen"> elements. media-use's resolve.md now
documents that the skill stamps this attribute on a mounted video only
when the ledger record's provider is "heygen.video" (the mount itself
is always the agent's own composition edit, never written by resolve
scripts) — the ledger stays the single source of truth for provenance,
the HTML attribute is a projection of it, and no other provider value
is invented beyond this one signal.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>

* feat(telemetry): add a bucketable failure taxonomy to render_error

error_name (error.name, e.g. one of the ~20 typed producer error
classes) and failed_stage_code (job.currentStage/failedStage
normalized to a stable snake_case code via normalizeStageCode)
join the existing free-text error_message/failed_stage, so a fleet
query can bucket failures without parsing prose. Error-conditional by
nature — render_complete has no equivalent, since a successful render
has no error to name or stage to blame.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>

---------

Co-authored-by: Miguel Ángel <miguel.sierra@heygen.com>
2026-09-16 12:37:57 -04:00
heygengenesis[bot]andmiguel.sierra 5d2478c6fa fix: report HDR auto-promotion (#3985)
Report HDR auto-promotion consistently from the render media set, including remote media, and make its regression coverage portable across supported paths.

Co-authored-by: heygengenesis[bot] <262951085+heygengenesis[bot]@users.noreply.github.com>
Co-authored-by: miguel.sierra <229591595+miguel-heygen@users.noreply.github.com>
2026-09-16 06:13:24 +00:00
Miguel Ángel f059a6eb53 feat(cli): default BeginFrame, agent blank, and looks quality (#3927)
* feat(cli): render summary names the capture path, gpu mode and stage timings

* fix(lint): drop gsap_exit_missing_hard_kill, its hazard does not reproduce on cold workers

* fix(cli): render slow-path hint fires only when the gpu was auto-probed

* test(cli): isolate agent hint suite from ambient agent env keys

The suite runs inside agent sessions. Ambient env keys fill the 16-key
hint cap and fail assertions that a plain shell would pass.

* docs(music-to-video): drop leftover hard-kill mandate after lint rule removal

Frame workers still required a tl.set hard-kill that the dropped lint
rule no longer enforces. Align the self-check with montage.md.

* refactor(cli): share hint-key pattern and collapse render summary args

Export HINT_KEY_PATTERN for the test isolation strip. Read duration and
frame count from the perf summary instead of passing them beside it.

* test(cli): lock capture-mode preference and 16-key hint isolation

Session mode, including drawelement, must print over observability.
The hint suite now fails if ambient keys already fill the 16-key cap.

* feat(cli): default BeginFrame, agent blank, and looks quality

Local auto render opts out of the software-GPU screenshot clamp so
BeginFrame can run. init --agent scaffolds a centered Inter blank with
no prompts. --quality looks (now the default) is CRF 16; delivery is high.

* fix(cli): honor screenshot env and teach agent pitfalls on the happy path

Local auto still requests BeginFrame unless PRODUCER_FORCE_SCREENSHOT=true.
The agent blank fills its canvas so --resolution can resize it. Skills now
name the four pitfalls and tell agents to read the render summary line.

* feat(cli): default init to the centered blank

Bare init scaffolds the centered Inter stage. --agent is a hidden alias.

* fix(cli): pack from-file and use it for video init

TTY --video with no --example selects from-file. Pack copies that template.

* fix(cli): wire --video onto from-file even with --example blank

One resolver picks the scaffold. Spawned init --video asserts a-roll src.

* fix(cli): narrow looks CRF on the quality alias

Only looks carries crf. Typecheck failed on the union without a guard.

* style(cli): shorten render-pipeline summary comment
2026-09-13 21:44:19 -04:00
Miguel Ángel 95bea1631f refactor(skills): keep hyperframes-core as the HTML contract (#3928)
* refactor(skills): keep hyperframes-core as the HTML contract

Move brief, storyboard, review, production, dispatch, and
frame-worker docs to hyperframes. Slim remaining core references.

* fix(skills): restore camera recipes and root sizing

Restore Zoom, Ken Burns, crop, and clip-path recipes. #root is 100 percent.

* fix(skills): stamp size on the composition root

Runtime sizes the composition root, not html/body. Overlap pin requires is valid.
2026-09-13 21:20:58 -04:00
heygengenesis[bot]andmiguel.sierra 4aa6e17b76 docs: fix skill documentation cross-references (#3920)
Co-authored-by: miguel.sierra <229591595+miguel-heygen@users.noreply.github.com>

Co-authored-by: heygengenesis[bot] <262951085+heygengenesis[bot]@users.noreply.github.com>
2026-09-13 03:19:21 +00:00
Vance Ingalls b848d81681 Merge pull request #3878 from heygen-com/docs/require-voiceover-carve
feat(audio): require the voiceover carve, default strength 0.8, slower release
2026-09-11 14:20:04 -07:00
Miguel Ángel 849ce0176a fix(catalog): name the better search tier when a search finds nothing (#3872)
* fix(catalog): name the better search tier when a search finds nothing

The hint that tells a scripted caller the on-device tier exists was wired
to the branch where the search succeeded, and was silent on the branch
where it found nothing. The caller with the most reason to hear it was the
only one who never did.

It also only ever reached stderr, so a --json caller never saw it at all.
The hint is now a returned sentence pushed into the same warnings array the
zero-result envelope already serializes, and printed from that one value, so
the terminal and the envelope cannot drift.

Withheld when the query parsed to no searchable tokens, where the advice is
already to search in English, and when a warning has already explained why
the tier cannot run here.

The consent gate is untouched: nothing downloads, and the sentence still
asks the caller to check with a person before enabling it.

* fix(review): pass the resolved model status, and pin both hint guards

Deriving the status inside the hint helper re-read and re-hashed the
on-device model from disk to answer a question the caller had already
answered a few lines earlier. It now takes the resolved value.

Both guards below the status check were invisible to the suite: every
other case pinned a status that already returned null, so deleting either
guard passed everything. Two tests now hold them, and each fails for its
own mutation.

* docs(skills): tell agents to read the tier hint the envelope now carries

The CLI skill said that under --json nothing about the offline tier is
printed at all. An agent following that sentence would never read the
warnings array this branch writes the tier sentence into, so the fix
would land in the code and never reach the caller it was written for.

It also described warnings as firing only when a tier was asked for and
could not run. That is now too narrow: a zero-result search emits the
hint with no tier requested.

Regenerate skills-manifest.json for the changed content hash.
2026-09-11 17:14:10 -04:00
Vance IngallsandClaude Fable 5.1 06897fe0be style(audio): format carve.test.mjs and re-sync the skills manifest
The pre-commit format hook's glob does not include .mjs, so the new test
file reached CI unformatted while oxfmt --check . covers it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-11 14:08:10 -07:00
Vance IngallsandClaude Fable 5.1 e488871ce1 fix(audio): pin the slower release and the carve default, fold the requirement, sync the manifest
Review at fe53f51a: the moved test points passed at both 1.6s and 2.4s, so a
revert of DUCK_RELEASE_S was silent. Add the 9s probe that reds on 1.6s. Export
DEFAULT_STRENGTH and parseArgs from carve.mjs and pin 0.8 in carve.test.mjs.
Fold the new requirement paragraph into the existing 'Carve by default' one so
the rule is stated once. Regenerate skills-manifest.json after the last edit.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-11 13:57:07 -07:00
miga-heygenandClaude Sonnet 5 42a3e7a519 fix(skills): loop-extended BGM writes .mp3, not MP3-in-a-.wav (#3884)
ensureBgmCovers() (duplicated in faceless-explainer, pr-to-video, and
product-launch-video's assemble-index.mjs) always re-encodes a short BGM
track with libmp3lame, but preserved the source asset's own extension when
naming the loop-extended output — so a "bgm.wav" source produced
"bgm.loop.wav" containing genuine MP3 audio. ffprobe/ffmpeg/Chromium all
decode this correctly via the WAVE_FORMAT_MPEGLAYER3 tag, but a naive/strict
WAV parser (e.g. Python's stdlib `wave` module) hard-fails on it. The
function's own doc comment already documented the intended output as
"*.loop.mp3" — the code just didn't match it.

Fix: always emit a .loop.mp3 path regardless of the source extension.
music-to-video's assemble-index.mjs does not have this function (it uses
the raw BGM asset directly, no loop-extension), so only 3 of the 4 skills
needed the change.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-11 16:07:49 -04:00
Vance IngallsandClaude Fable 5.1 2e2b5c8530 feat(hyperframes-audio): default the voiceover carve strength to 0.8
0.25 left the bed audibly fighting the voice; a build carved at 0.25 had to be
redone at 0.8 before it was accepted. Make carve.mjs default to 0.8 and rewrite
the strength prose and the sample output to match. The core DEFAULT_CARVE used
by the Studio panel is unchanged.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-11 11:24:18 -07:00
Vance IngallsandClaude Fable 5.1 0b9852fee4 docs(skills): require the voiceover carve whenever music plays under a voice
The hyperframes-audio skill described the carve as one option among several,
so builds with BGM under narration shipped with only a volume duck. Make it a
requirement in the three places an agent reads while assembling audio: the
carve section of hyperframes-audio, general-video's Assemble step, and the
production loop's Audio stage.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-11 10:25:50 -07:00
James Russo c98d6fbac8 fix: keep caption transcript data inside generated scripts (#3847)
* fix: keep caption transcript data inside generated scripts

* test: locate caption data without an HTML filtering regex
2026-09-10 12:53:30 -04:00
James Russo a7e2e3853a fix(media): validate every download redirect target (#3841)
* fix(media): validate every download redirect target

* fix(media): apply redirect policy to logo HEAD probes
2026-09-10 06:16:25 -04:00
Miguel Ángel 622ea5b38c test(skills): pin the catalog exemption as a capability and lint the templates list (#3838)
The two skills exempt from the catalog search were pinned only by the
sentence that declares the exemption, so the exemption would go stale the
day either gained a way to install a registry item. The test now also
asserts neither skill contains an install command or a registry path.

The templates list in the scaffold reference claimed to be lint-checked
but lacked the marker that arms the check, so a misspelt template would
have passed. It now carries the marker with its presets and skill names
allowlisted, and a misspelt template fails the lint.
2026-09-10 03:49:21 +00:00
Miguel Ángel 0f8eb892e3 fix(skills): search the component catalog before hand-building a look (#3829)
* fix(motion-graphics): make the catalog search fire before hand-authoring

The workflow's only reuse instruction pointed at catalog-map.md, a
hand-maintained snapshot of ~60 registry items, and no file in the skill
ever named `hyperframes catalog --query`. An agent asked mid-build for
CRT scanlines and a glitch effect had no instruction to search, so it
hand-authored both while caption-glitch-rgb ("RGB chromatic aberration
with CRT scanline overlay") ranks first for that query on either tier.

The search reads the hosted registry and needs nothing installed, from
any directory with no project, so "the components were not installed"
was never the cause. Say that where the reader is, since the wrong
diagnosis is the intuitive one.

Director Part 2 and the Builder now run the search before naming a
block, and catalog-map.md is labelled a partial snapshot whose misses
prove nothing. Pinned by a content test in coreSkillContent.test.ts.

* fix(skills): search the component catalog before hand-building a look

Authoring workflows never told the agent to search the component library,
so agents rebuilt effects the registry already shipped. A user reported
building an effect from scratch that the registry already contained; the
search that would have found it needs nothing installed, which is why the
usual self-diagnosis ("I forgot to install the components") is wrong.

All ten workflow skills carried zero mentions of `hyperframes catalog`.
The instruction lived only in hyperframes-cli and hyperframes-registry,
both loaded on demand, and the registry skill's own trigger named the
command rather than the symptom - circular, because an agent that never
thought to search could not reach the doc telling it to search.

- Eight workflows now run the search at the point they decide what to
  build, before authoring. The two that compile through a closed
  authoring vocabulary (embedded-captions, talking-head-recut) document
  why they deliberately do not.
- hyperframes-registry triggers on the symptom (a named look, effect,
  treatment or transition) instead of the command name; the router table
  and the catalog surfaces carry the same framing.
- Fixes hand-maintained lists that had drifted: bar-chart-race was listed
  as a hand-author gap in two files while shipping in the registry;
  stat-motion was named as an installable block and is not one; the
  caption-* family count was one high; the registry discovery tables
  claimed to be the block list while covering 97 of 180.
- bun run lint:skills now fails when a doc marked as a registry snapshot
  names an item the registry does not have.

* refactor(scripts): reuse native recursive readdir and the shared registry type

Simplify pass on the new registry-snapshot check, behaviour identical:
- collectMarkdownFiles uses readdirSync({ recursive: true }) instead of
  hand-rolled recursion, matching scripts/generate-template-previews.ts.
- registryItemNames types registry.json with the exported RegistryManifest
  instead of an ad hoc inline shape, matching scripts/catalog/build-local-vectors.ts.
  The runtime guard stays: a cast describes the file, it does not validate it.
- One report() helper replaces the duplicated print-and-count block in both
  lint passes.

* refactor(scripts): name the registry check's blind spots and stop self-arming

Applies the review findings on the new check, behaviour identical except
where noted:
- lintRegistryItemRefs returns null for an unmarked file instead of an
  empty array, so "not a snapshot" and "a clean snapshot" have one owner
  and the marker is matched once rather than twice.
- Marker detection ignores fenced blocks, so a doc that documents the
  marker syntax in an example no longer arms the check on itself. The id
  scan still reads full content, so fenced examples stay covered.
- The header comment and two tests now pin both known false negatives:
  identifiers outside backticks, and single-word item names. Measured on
  the six marked files, dropping the hyphen requirement would monitor 3
  more items and force 46 allow= entries for ordinary prose words, so the
  requirement stays and the gap is stated instead of silent.

* chore(skills): regenerate skills manifest after catalog-search edits
2026-09-10 03:21:33 +00:00
James Russo efe2404cbd fix(skills): stage media downloads in private directories (#3787) 2026-09-08 19:29:26 -04:00
James Russo a7bf0d23d9 fix(skills): retain audio metadata file identity during generation (#3778)
* fix(skills): retain audio metadata file identity during generation

* test(skills): isolate audio metadata CLI credentials
2026-09-08 17:35:12 -04:00
James Russo a92dc6865e fix(skills): read BGM logs without pathname prechecks (#3769) 2026-09-08 16:40:20 -04:00
Miguel Ángel 01744f2b0c fix(media): unify nested start coordinate mapping (#3732) 2026-09-08 18:10:51 +00:00
Miguel Ángel 78dacc828c fix(skills): accept durationless transition roots (#3683) 2026-09-08 18:10:24 +00:00
Miguel Ángel 131336f5dc fix(skills): bootstrap npm safely on Windows (#3705)
* fix(skills): bootstrap npm safely on Windows

* test(skills): verify npm bootstrap on Windows Node 24
2026-09-08 18:09:10 +00:00
Miguel Ángel 672ea844a5 fix(cli): clarify publish visibility and claim links (#3730)
* fix(cli): clarify publish visibility and claim links

* style(cli): apply oxfmt to publish visibility test

* chore(skills): regenerate skills manifest for updated references

* fix(cli): stop an in-place re-publish claiming it made the project private

* test(cli): pin in-place visibility copy to the plain re-publish route
2026-09-05 23:10:42 -04:00
James Russo eec04340b3 fix(core): avoid grade stats regex backtracking (#3706) 2026-09-05 12:28:59 -04:00
James Russoandyoma 7fcb5be6ea docs(registry): clarify catalog preview staging and published URLs (#3676)
Co-authored-by: yoma <yingwaizhiying@gmail.com>
2026-09-04 19:53:18 -04:00
James Russoandyoma a93106aebf docs(skills): fix creative house style reference links (#3668)
Co-authored-by: yoma <yingwaizhiying@gmail.com>
2026-09-04 19:19:25 -04:00
James Russo 924b98a0dc fix(captions): preserve zero plate grain in generated postfx (#3656) 2026-09-04 17:38:43 -04:00
heygengenesis[bot]andmiguel.sierra 62d3304caf fix(embedded-captions): support heroless themes (#3632)
Co-authored-by: heygengenesis[bot] <262951085+heygengenesis[bot]@users.noreply.github.com>
Co-authored-by: miguel.sierra <229591595+miguel-heygen@users.noreply.github.com>
2026-09-04 18:27:47 +00:00
heygengenesis[bot]andmiguel.sierra 0154b40b65 fix(captions): derive preview GSAP integrity (#3631)
Co-authored-by: heygengenesis[bot] <262951085+heygengenesis[bot]@users.noreply.github.com>
Co-authored-by: miguel.sierra <229591595+miguel-heygen@users.noreply.github.com>
2026-09-04 18:04:26 +00:00
Xuanru Li 45cc343525 fix(cli): flag caption-zone by DOM box overlap (#3580)
A card centered at y=.860 can still cover the painted V2A pill. Intersect the element's getBoundingClientRect with the keepout instead of testing whether its center sits inside the band.
2026-09-01 04:41:57 +00:00
James RussoandClaude Opus 5 8392e84a18 fix(media-use): repoint the dead videogen tier, demote past unusable local models (#3509)
* fix(media-use): repoint the dead videogen tier, demote past unusable models

`LOCAL_MODELS.videogen`'s `large` tier named `dgrauet/ltx-2.3-mlx-bf16`, which
returns HTTP 401 and cannot be downloaded at all. It was not a dormant entry:
`rankedByPreference` sorts by descending `needs.ramMB` when no `rank` is set,
so the largest fitting tier is tried FIRST by design. Any machine clearing
32 GB *available* RAM selected the dead entry, `ltxVideoGenerate` caught the
failure and returned a bare `null`, and since `ltx.local` is last in
`["heygen.video", "ltx.local"]` and network providers are skipped under
`--local-only` (`registry.mjs:206`), local video generation failed outright
instead of falling back to the tier that works.

It survived review because the table landed with "live verification on a 24GB
M-series Mac" - and a 24 GB machine cannot select a 32 GB tier, so that entry
was unreachable on the only machine that validated it. The unit fixtures
inherit the same ceiling (`fittingSpecs` is 20000MB), so every existing test
exercised the medium tier alone.

Two changes:

1. Repoint to `dgrauet/ltx-2.3-mlx-q8` (reachable) and correct `sizeMB` from
   45000 to 28800. Measured against the HF API: the q8 repo totals 87.5 GB,
   and the registry's own targeted `--include` subset is 28.76 GB. That
   matches the sibling q4 entry's convention (`sizeMB: 20000` vs a measured
   19.48 GB subset), so 45000 was wrong under either reading. `--low-ram` is
   added because the entry's own note calls it required at this tier's 32 GB
   floor, and the invoke omitted it.

2. A repoint alone is one bad URL from a repeat, so add the missing recovery.
   `selectModelLadder` returns every fitting model best-first;
   `selectModel`'s pick is now defined as that list's head. All three sites
   that previously selected exactly one model and failed terminally walk the
   ladder instead, demoting past a tier that cannot run here - gated weights,
   runner off PATH, an OOM at a tier that nominally fits:

   - `ltx-video-provider.mjs` (videogen, the reported failure)
   - `mflux-provider.mjs` (imagegen - same shape, and its 32 GB/64 GB tiers
     are equally unverifiable on a 24 GB machine)
   - `local-run.mjs` (tts/asr/upscale - `fish-speech` missing should still
     get you Kokoro)

   Every demotion is logged rather than silent, so a quietly smaller model is
   never mistaken for the tier the machine nominally qualified for.

Also fixes the `install` string both videogen entries share: it ended at
`uv sync --all-extras`, which leaves the entry point in `.venv/bin`, so the
"`ltx-2-mlx` not on PATH" hint named a command that following the instruction
would not put on PATH.

The q8 tier is NOT live-verified - no 32 GB+ Apple Silicon machine was
available - and its notes say so. Shipping it unverified is safe precisely
because of change 2: a wrong tier now costs one failed attempt, not the whole
local path.

- Rames Jusso

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(media-use): report the real videogen download size, disclose it, discard failed partials

Addresses review feedback on #3509 (CHANGES_REQUESTED at 90df164a), plus the
follow-on ask to tell the user what a download costs before they accept it.

1. `sizeMB` described a targeted `--include` subset that no run ever gets.
   Both videogen invokes pass a repo id to `--model`, and upstream
   `resolve_model_dir()` (`ltx_pipelines_mlx/utils/_orchestration.py:35-40`)
   calls `snapshot_download(repo)` with no `allow_patterns`, so the full repo
   lands regardless of what was pre-fetched. Corrected to measured repo
   totals: q8 87500 (87,511,991,375 B) and q4 59700 (59,686,429,583 B). q4 was
   wrong the same way at 20000, so both are fixed together rather than leaving
   one convention on each side.

   My earlier claim that 28800 "matches the sibling q4 entry's convention" was
   wrong in the way that matters: the convention itself described a subset the
   runner does not honor. The file's own comment already said "blind
   snapshot-downloads the lot (60 GB q4, 88 GB q8)" three lines above the
   fields that contradicted it, and the original report measured it too ("the
   q4 cache ended at 56 GB and q8 at 82 GB"), which reconciles exactly once
   read as GiB: 59.69 GB = 55.6 GiB, 87.51 GB = 81.5 GiB. So the download is
   the complete repo both times, not a partial fetch.

   Removed the `--include` recipe rather than repairing it: it is ineffective
   (the runner refetches at generate time) and insufficient (`--two-stage` is
   "dev model + CFG at half-res, upscale, distilled LoRA refine" per upstream's
   own help text, so it needs transformer-dev AND transformer-distilled AND
   spatial_upscaler_x2; `--distilled` needs an upscaler too). The q4 tier
   verified on a 24 GB Mac only worked BECAUSE the download is unfiltered.

2. Nothing told the user what they were agreeing to before a tool started
   pulling tens of GB. `describeDownload()` in `specs.mjs` names the size and
   the directory the weights land in, and checks free space with `statfs`
   against that directory rather than cwd, since the weights do not land in
   cwd. A tier that will not fit is still offered, with a plain statement that
   it will not fit: hiding it would make a machine that could free up space
   look like it has no large tier. Unknown free space reports as unknown, not
   as zero. Wired into both providers' install hints, the `runLocalModel`
   install payload (now carrying `sizeMB`), and `describeModelLadder`.

3. Each retry attempt mints its own timestamped temp path, so a partial
   artifact from a failed tier was orphaned rather than overwritten, and a
   lower tier then succeeding hid it. Both providers discard the partial before
   demoting, guarded so a file that cannot be removed never masks the generate
   failure it came from. Video is the material case: a partial mp4 is large.

   `local-run.mjs` is deliberately unchanged here. Its `out` is caller-provided
   and identical across attempts, so a partial is overwritten rather than
   orphaned, and unlinking a path the caller named would be a footgun. The rule
   the two providers follow is: clean up what you allocate.

Tests: 553/553 across `skills/**/*.test.mjs` (+15). New coverage pins the
cleanup (failed tier's partial removed, returned artifact survives, one discard
per attempt on the all-fail path, an unremovable partial still surfaces the
real failure) and the disclosure (cache-dir precedence, statfs walk-up to the
deepest existing ancestor, unknown-vs-zero, and the will-not-fit wording).
Every new guard mutation-tested: removing any one of them turns tests red.

- Rames Jusso

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-26 16:15:51 -07:00
Miguel Ángel b2fc18b2df fix(skills,lint): correct composition-contract claims the code contradicts (#3468)
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.
2026-08-24 18:04:39 -04:00
Miguel Ángel e5a5e6b151 fix(cli): keep overlap waivers local to marked text (#3464)
* fix(cli): scope overlap waiver to marked text

* fix(skills): guard changelog caption rail

* fix(skills): densify changelog caption checks

* test(skills): satisfy strict seek typing
2026-08-24 14:22:03 -04:00
Vance Ingalls 2685c8f223 docs(audio): document grouped audio and its guardrails (#3455)
* 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
2026-08-23 19:19:27 -07:00
Vance IngallsandClaude Opus 5 f0cc9b1a34 fix(skills): make the carve CLI work against the published core, and honour its own group invariant (#3416)
* 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>
2026-08-22 05:16:50 -07:00