* 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>
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>
* 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
* 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.
* 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.
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>
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>
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>
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>
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>
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.
* 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
* 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
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.
* 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>
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.
* 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(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>
* feat(core): route grouped audio through a group bus in preview
An audio element carrying `data-audio-group` no longer lands its gain on
the master bus directly — it feeds a per-group `GainNode` (built lazily on
first use, one per group id) which itself feeds master, so members of the
same group sum before the ear, ready for a group-level FX chain and
volume/mute in later steps. An id with no matching `<hf-audio-group>`
element still gets a plain, unprocessed bus rather than losing the track.
The group's own chain and volume lane are wired through the same
`attachElementFxChain`/`scheduleVolumeLane` every element already uses,
against the group's clock — composition time (design doc §1.3), since a
group has no `data-start` and a missing one parses as 0. The bus persists
across `stopAll()` (mirroring `_masterGain`'s own lifecycle) so replaying a
group does not rebuild its chain; only `destroy()` disposes it.
Render is untouched — stays flat until B4; `audio-groups` is still a 0%
canary so nothing ships this to a real composition without hand-authoring
`data-audio-group`.
Also: `audioGroupOf` (B1) crashed on any element lacking a real `tagName`/
`getAttribute` — exactly the shape of most `HTMLMediaElement` test doubles
in this suite, including this file's own `mockEl`. Made it tolerant, same
style as `readChain`'s existing guard in `runtime/audioFx.ts`.
`schedulePlayback` was already 110 lines pre-existing before this diff;
extracted `resolveDestination` and `handleSourceEnded` to shrink it to 92,
then suppressed the remainder (inherently sequential graph wiring, not a
decision tree) per the same precedent B2 used on `TimelineLogicalRow`.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(studio,lint): carve targets voiceover groups — always, when plural
Plural voiceover carve now targets a group instead of naming each clip:
`resolveCarveSourceIds` (core `audioGroups.ts`) expands a group id to its
current members at analysis time, so a clip added to the group later is
covered without touching `sources`. The picker (`useFxCarve.ts`) offers a
grouped voice as one option instead of one row per member, tests overlap
as a union of member spans (a group overlaps the bed if ANY member does),
and prefers a qualifying group over its individual members in
`autoSourceIds`.
Picking two or more ungrouped voice clips in the carve flow now mints a
group behind them (`mintGroupId`, de-duped against every id in the
document) and writes `data-audio-group` on each picked clip atomically,
one undo entry — `createAudioGroupAndAssignMembers` in
`timelineTrackVisibility.ts` copies `setElementsHidden`'s multi-target
write shape. The DSP is untouched: `mixCarveSources` already sums
multiple sources correctly (verified in the design doc's own
investigation) — this only fixes the picker.
New lint rule `audio_carve_ungrouped_sources` (`packages/lint/src/rules/
media.ts`, alongside `audio_volume_double_automation`) warns when a
`data-fx-carve`'s `sources` names two or more plain clip ids instead of a
group — the shape that silently rots when a clip is added. `/hyperframes-
audio` states the same rule as an invariant, not a tip, with the grouped-
narration HTML example from the design doc.
The group-matching and auto-group logic (`withAutoGroupedSources`,
`collectCarveCandidates`) is split into `useFxCarveGrouping.ts` —
`useFxCarve.ts` was pushing past the 600-line cap. `resolveNextCarveSettings`
is deliberately NOT an `async function`: wrapping it in one would force a
microtask on every call, including the synchronous branch — the exact bug
`withAutoGroupedSources`'s own sync-when-possible contract exists to avoid,
and one caught via `propertyPanelAudioFxGroup.test.tsx` (10 failures)
before fixing it back to a plain function the caller conditionally awaits.
Also extracted `useEffectiveTimelineDuration` out of `App.tsx` and
`useRemoveBackground` out of `StudioRightPanel.tsx` (both pushed past 600
lines from an added prop wire), and decomposed `useFxCarve.ts`'s picker
IIFE to clear fallow's complexity gate.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Replace "run silently, don't ask" with explicit confirmation guidance
in ten workflow SKILL.md files so agents do not auto-run npx updates
without the user. Regenerate skills-manifest.json.
Refs heygen-com/hyperframes#2613
Linting the primitive-clip example from packages/core/docs/core.md produced
two errors against the docs' own linter:
error timed_element_missing_clip_class el-3 <img data-start ...>
error self_closing_media_tag el-4 <audio ... />
Both are now fixed, in opposite directions — one was the rule's fault, one was
the docs'.
`timed_element_missing_clip_class` claimed the element "will be visible for the
entire composition instead of only during its scheduled time range". That is
not what happens. `syncTimedElementVisibility` walks
`querySelectorAll("[data-start]")` and toggles `style.visibility` off the
ATTRIBUTE, with no reference to the class; the runtime's own init test pins it
with a bare `<div data-start data-duration>` carrying no `class="clip"`. Every
other consumer of the string "clip" — Studio's label derivation, the runtime's
timeline labels, core's selector helper — treats it as a name to skip, never as
a behaviour key. So the class is an authoring convention the tooling reads, not
the mechanism that hides the element.
The rule is therefore a warning rather than an error, and its message now says
what is actually true. `img` joins `audio` and `video` in skipTags: the three
media primitives sit on adjacent lines of the same documented clip block, all
three authored without `class="clip"`, and flagging only the `<img>` is what
made the documented pattern fail.
`self_closing_media_tag` was right and the docs were wrong: `/` is ignored on a
non-void element, so `<audio ... />` leaves the element open and everything
after it nests inside. Changed to `<audio ...></audio>`. The `<img ... />` on
the line above is a genuine void element and stays as it is.
The same false mechanism claim had been copied into the talking-head-recut
skill, in both the annotated example and the rules list, where agents read it
as fact. Corrected there too.
No effect on the 643 shipped registry files (this rule fires on none of them);
the change is to the documented pattern and to agent-authored compositions.
Regression test lints the canonical block verbatim and asserts it produces no
errors or warnings, so docs and linter cannot drift apart again silently.
* fix(skills): resolve the blueprint id from a qualified `blueprint:` field
visual-design.md documents `blueprint:` as the id plus a `(Reproduce)` /
`(Adapt)` qualifier, and prints `dataviz-countup (Adapt)` as its worked example.
The packet builder used that raw field as a filename, so a qualified blueprint
looked for `<id> (Adapt).md`, found nothing, and inlined an empty string:
`selectedFile()` returns "" for a missing path. Every packet shipped without the
one document the frame was designed against, and the run still exited 0 with
nothing on stderr. `compose (Adapt)` missed the `compose` check the same way.
Parse the field into the id it names, once, so no caller resolves a raw field
value against the blueprints directory. A blueprint that resolves to no file is
now a named error rather than an empty section, matching how the builder already
treats a missing `src` and an oversize packet.
The existing tests only used bare ids, which is how the qualified form escaped;
they now cover both, and the missing-file case.
One owner: product-launch-video, faceless-explainer, pr-to-video and
general-video all delegate to frame-packets-core.mjs.
Co-Authored-By: anikam13 <22992075+anikam13@users.noreply.github.com>
* fix(skills): degrade, not fail, when the blueprints library is absent
Self-review catch on the previous commit. hyperframes-animation installs on
demand, so its blueprints/ directory can legitimately be missing — that is a
skill that isn't installed yet, not a frame naming a bad id. Throwing there
turned a silent degrade into a hard failure for a valid setup.
Distinguish the two: an absent blueprints/ warns and inlines nothing, exactly
as an absent rules/ already does in knownRuleIds; a present library that has no
file for this id still throws, because that is a typo or an unstripped
qualifier.
Co-Authored-By: anikam13 <22992075+anikam13@users.noreply.github.com>
* fix(skills): point two dead blueprint references at real shapes
CI surfaced these once an unresolvable blueprint stopped being silent. Both
named ids that have never existed in hyperframes-animation/blueprints/:
- faceless-explainer's frame template taught `messaging-multi-phase`, so an
agent copying the template verbatim tagged a blueprint that resolves to
nothing. dataviz-countup is what the same skill already uses in its own
visual-design template and tests.
- pr-to-video's diff-excerpt guardrail fixture used `number-lockup`. The test is
about diff excerpting and the id was incidental; the frame's own
`counting-dynamic-scale` rule makes dataviz-countup the natural real shape.
A sweep of every `blueprint:` value across skills/ finds no others.
Co-Authored-By: anikam13 <22992075+anikam13@users.noreply.github.com>
---------
Co-authored-by: anikam13 <22992075+anikam13@users.noreply.github.com>
`hyperframes capture` extracts inline SVGs into capture/assets/svgs/, and the
capture manifest advertises them to the agent as `assets/svgs/<name>.svg`, so a
frame names one in `asset_candidates` exactly the way it names a screenshot.
stageAssets searched only capture/{assets,assets/videos,screenshots}, so every
captured SVG resolved to nothing: logged as a non-fatal anomaly, and the frame
404'd the brand mark it had been told to use.
Add the directory to the search list, and cover it with a test that fails
without the fix.
lib/assets.mjs is byte-identical across product-launch-video,
faceless-explainer and pr-to-video, so the fix lands in all three. Folding it
into hyperframes-core/scripts/lib/, where frame-packets-core.mjs already lives,
is a separate change.
Co-authored-by: anikam13 <22992075+anikam13@users.noreply.github.com>
* feat(skills): anchored-connector rule + source-traceable visuals doctrine
Two advisory rules absorbed from a community-skill comparison study
(4-cell sandbox replay vs geekjourneyx/hyperframes-motion-director;
ideas only — no upstream text, the repo is AGPL-3.0):
- Connector lines earn their place: any beam/rail/scan/underline must
name both anchors and its job (reveal/route/validate) or be cut.
Lands in motion-principles (composition) + svg-path-draw (constraints).
- Visuals point back to the source: when a video derives from concrete
material, each frame's key visual should trace to a specific source
line — real filenames/numbers over stock props. Lands as story-spine
rule 4; the four SKILL.md index lines that enumerate story-spine's
rules are synced.
Both are self-checks, not hard gates. lint:skills + skill-mirror green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(skills): regen stale manifest + add emphasize to connector job list
Review 4975048154 follow-ups:
- skills-manifest.json was hashed mid-commit before oxfmt renormalized
the four SKILL.md tables (lefthook pre-commit runs format and
skills-manifest in parallel — they raced). Regenerated at head;
second regen is a no-op.
- The connector rule's job list read literally would cut lines this
same doctrine prescribes (dividers, hairlines, underline_sweep):
emphasis was a missing job, not a forbidden one. Added 'emphasize'
to both motion-principles and svg-path-draw.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(studio): make the volume fader tell the truth about the gain it writes
The fader travels in dB, so its stops are irrational values; serializing them
through the generic two-decimal numeric formatter collapsed the bottom quarter
of its travel onto "0" — a hard mute — and made the knob jump on release
everywhere below unity. Both panels now use the exact serializer, which
round-trips every integer stop back to itself.
Raise the volume automation lane to the same ceiling the fader reaches.
Clamping the lane at unity meant automating a boosted clip silently discarded
the boost, and the panel disables the fader while a lane owns the level, so
there was no way back. This rescales the lane's vertical axis: unity now sits
a quarter of the way up rather than at the top.
Add audio_volume_tween_overrides_gain. Tween values on `volume` are absolute —
they replace the authored gain rather than scaling it — so a clip carrying both
plays at whatever the tween names, and the fader gives no sign of it. The rule
reuses the tween detector the sibling lane/tween rule already has.
* fix(lint): treat a missing data-volume as unity, not as silence
readAttr returns null when the attribute is absent, and Number(null) is 0 —
finite, and not 1 — so a clip carrying NO data-volume cleared both filters and
was reported as authored at silence. Both halves of that were false: absent
means unity everywhere else in the runtime.
It fired on exactly the case the rule exists to bless. The docs this PR edits
say data-volume is the baseline for elements no tween touches, so a tweened
clip is expected not to carry one — the common audio fade. A warning does not
fail check, but an agent reading the fixHint would have written a gain to
correct a level that was never wrong.
* feat(cli): add normalize-audio to match one clip's loudness to another
Measures two authored `<audio>` clips with FFmpeg's integrated EBU R128
loudness and writes the target's matching `data-volume`, leaving the
reference untouched.
The measurement is bounded to the window the composition actually plays.
`data-end` bounds a clip's timeline window just as `data-duration` does, and
`-ss`/`-t` belong before `-i`: after it they bound the OUTPUT, and with
`-f null` there is none, so ebur128 keeps integrating past the clip. On a
fixture whose played window is -61.8 LUFS inside a file that measures -27.9
whole, either mistake reports a loudness the composition never plays and
"corrects" an already-matched clip by tens of dB.
Two EBU R128 passes run between reading the composition and writing it, each
bounded only by a two-minute timeout, and the skill docs tell agents to keep
Studio open meanwhile — so the attribute patch is re-applied to a fresh read
and written through a temp file and a rename.
Under `--json` the failures are documents too: an agent doing
`JSON.parse(stdout)` on a bare error line throws. A pair needing more than the
+12 dB ceiling has a source-file problem rather than a mixer one — mixer gain
raises the noise floor with the signal — so the refusal names the remedy.
* fix(cli): validate --tolerance before paying for the measurement
Each EBU R128 pass is bounded at 120s and normalize-audio runs two, so
parsing the argument afterwards made a typo'd --tolerance cost both of them
before failing on something that was wrong from the start.
Not pinned by a test: the ordering is internal to the command and neither it
nor the parser is exported, so covering it would mean restructuring for a spy
rather than asserting the behaviour.
* docs(cli): restore the blank line between the preview and normalize-audio sections
Lost when I resolved the rebase conflict against the background-preview docs
by hand instead of letting the formatter near it. oxfmt --check failed on the
one file, which fails Preflight — and because preview-parity needs Preflight it
skipped, and the preview-regression gate fails closed on a skip, so a missing
newline read as a preview defect.
The quieter half: the same needs chain meant the required Test context was
never created at that head. Not failing — absent, so there was no test signal
at all on the PR.
`--background` was rejected outside the embedded server. It now re-execs the
CLI in foreground, which makes it mode-agnostic by construction: whichever
server the child resolves to serves the config endpoint the readiness probe
looks for. `--foreground` is its counterpart, for a non-interactive shell that
wants to stay attached, and a bare launch keeps the same promise — attached in
an interactive terminal, managed in an agent session.
That generalization exposed an existing hole. Local-studio mode runs Vite with
the studio package as its cwd and needs that package's own Vite config, which
the published tarball does not carry, but resolving the package was treated as
proof the mode was usable. An npm-installed studio therefore took a path that
can never come up — previously a clear error, now a ten-second silent timeout.
The predicate becomes "can this studio actually be served", so a published
install falls back to embedded mode, which works.
Over the 1k line budget at ~1.3k. The overage is one command file and its
tests carrying one invariant, and the seam that would split it further is
inside a single request-handling function — a split there would produce two
PRs neither of which starts a preview on its own.
enumerateTweens dropped every tween whose targets() held no Element:
if (!targets.length) return;
That silently deleted the proxy-driver idiom — tween a plain object, apply the
motion inside onUpdate — which is real, visible animation. The consequence was
not just a missing row: computeDensity counted zero active tweens across the
tween's span, so findDeadZones reported animating time as DEAD, telling agents
to add motion to a stretch that already had it.
A target-less tween is now kept when a driver reaches it, marked
driver:"onUpdate". The driver can be the tween's own onUpdate, or the
TIMELINE's — the WebGL/uniform idiom is gsap.timeline({ onUpdate: renderFrame })
over children that tween plain uniform objects and carry no onUpdate of their
own, so walk() threads a `driven` flag beside parentOffset.
The discriminator is what keeps this from trading one false reading for
another. A bare `tl.to({}, { duration: D })` spacer produces nothing, and every
preset caption skin ends with exactly such a full-span anchor; counting those
would mask genuine dead zones. So a tween's own onUpdate is proof of work by
itself (a repaint loop need not animate a property), while an inherited driver
additionally requires the tween to change something.
There is no element to select or measure for a driver tween:
* selectorHint is null rather than a placeholder — it feeds
document.querySelector, so it must be absent, not unmatchable;
* bbox sampling is skipped; the report shows "(onUpdate driver)";
* computeFlags guards its geometry flags on bboxes.length, since [].every()
is vacuously true and would report an unmeasured tween as both degenerate
and invisible;
* describeTween says the motion is applied in JS and no geometry was measured;
* the per-element analyses (buildElementLifecycles, detectStaggers) run over
element-backed tweens only, so drivers cannot collapse into one pseudo-
element or invent a stagger. Density, dead zones and the timeline still
count them — those are per-span, which is what a driver has.
Verified end to end: a 4s composition with an element tween over 0-1s and a
proxy driver over 2-4s went from "1/1 tweens, dead zones: 1.5-4s" to "2/2
tweens" with no dead zone.
A font filename encodes more than a weight, but only the weight was ever read
out of it, so two faces of one family collapsed onto a single slot.
Google Fonts ships Newsreader as Newsreader-Italic-VariableFont_opsz,wght.ttf
and Newsreader-VariableFont_opsz,wght.ttf. The italic sorts first, both scored
400, so the italic claimed the family's only 400 slot, the upright was dropped
as a duplicate, and the surviving face was declared with no font-style at all.
@font-face is deliberately global — the composition CSS scoper exempts it,
since a face declaration cannot be scoped — so mounting captions re-pointed the
whole document's Newsreader at the italic file and every sibling composition
rendered in italics.
Faces now carry a font-style descriptor and dedupe on weight AND style.
The same fix had to land in build-frame.mjs, which renames captured fonts
BEFORE captions.mjs sees them. It dropped the style token while renaming, so an
italic file arrived as "Newsreader-Regular.ttf" and was then asserted upright —
leaving the global normal slot pointing at italic bytes even once brandFontFaces
understood styles. The staged filename is a contract: it must carry every axis
that distinguishes one face from another, and the dedup key must be the whole
face.
Second axis, same misparse: weight parsing matched WORDS only, so a Fontsource
capture (inter-latin-500-normal.woff2) scored a whole family 400 and shipped one
of its faces. A numeric axis in the filename now wins over the word heuristic,
anchored so it is not read out of the middle of a hash-named capture file —
a non-digit before it and no alphanumeric after, which keeps both the 4-digit
guard and separator-free names like Roboto900.ttf.
Tests pin both ends of the contract: a round-trip asserting the names
build-frame stages map back to the right weight+style through the real
brandFontFaces, plus a source check that no copy reverts to a weight-only name
or a hardcoded font-style:normal. captions.mjs also gains a parity pin across
the three workflows that ship it.
Not addressed: a VariableFont file is still declared at a single font-weight
rather than its range, so weights it could interpolate are still synthesized.
Windows sizes Python's stdio and text-mode file IO to the ANSI code page
(cp1252), not UTF-8. Every skill Python script relied on that default:
* analyze-beatgrid.py --print writes the glyphs cp1252 has no slot for
(delta, arrow), so the brief died with UnicodeEncodeError on every Windows
run — the reported crash;
* its audiomap write_text() pairs ensure_ascii=False with the default file
encoding, so a non-ASCII payload is unwritable there too;
* lint_source.py read_text() raises UnicodeDecodeError before any rule runs
when a Remotion source carries an em dash or a curly quote;
* gen-stroke-path.py reads an SVG font whose glyph keys ARE literal
characters, so a mis-decoded key stops matching the requested text.
Stdio is reconfigured to UTF-8 at import and every text-mode IO call names its
encoding. `errors` is carried across the reconfigure: it resets to "strict",
and CPython gives stderr "backslashreplace" on purpose so the diagnostic path
can never itself raise.
extract-audio-data.py also decoded ffmpeg's stderr strictly while reporting a
failure, which would bury the very error being reported on a Windows ffmpeg.
skills/python-encoding.test.mjs guards the class: it fails if any skill Python
script drops the stdio block or omits encoding= on a text-mode IO call. The
mode is read as a whole comma-delimited argument of mode characters only, so a
payload key like {"bpm": 120} cannot spell the check away.
Verified with a cp1252 stdio stream installed before module load, matching how
Windows starts the interpreter: pre-fix UnicodeEncodeError, post-fix both
glyphs present in the UTF-8 bytes. Not run on real Windows hardware.
* fix(catalog): rank on where a word appears and how rare it is
Word search returned the right move in the top three for 87% of a
39-query eval set built from real catalog intents. Three defects, all in
the same 75-line scorer, and all found by running the queries rather than
by reading the code.
A token matching an item's NAME counted exactly as much as one buried in
a description. Searching "typewriter effect on a title" ranked the item
literally called `typewriter` seventh, behind entries that merely mention
typing. Name and title now carry three times the weight: an author who
types a move's name is giving the strongest signal available and it was
being averaged away.
Plurals shared no vocabulary with the singular. "a stat that counts up
and then pulses once" matched nothing in a description reading "lands
with a restrained scale pulse", because `counts` is not `count`. Adding
detail to a query made results strictly worse, which is the opposite of
what a search should do. Plurals now fold, and only plurals: Porter would
fold `counter` to `count` and `values` to `valu`, merging moves that mean
different things.
Field weighting alone made one case worse, which is why inverse document
frequency is here too. "reveal a headline one line at a time" put every
item merely NAMED `*-reveal` on top, because one strong hit on the
catalog's most common word outscored several weak hits on the words that
actually narrowed it down. Rarity now scales each term.
Separately: a query in a script this ranker cannot index no longer
reports itself as an empty catalog. Tokenising on [a-z]+ leaves nothing
of a Japanese query, and returning "no items match" told the author the
catalog lacked a move it may well have, then invited them to file a gap
report about it. That case now says what actually happened and withholds
the gap prompt, since nothing was searched.
Measured on the same 39 queries, before and after:
top-1 31/39 (79%) -> 33/39 (85%)
top-3 34/39 (87%) -> 39/39 (100%)
Test plan: 13 new tests, each a real failing query reduced to the
smallest fixture that still reproduces it. Existing tests migrated to the
fields API (two callers total). Full CLI suite 2643 passed, 2
pre-existing transcribe failures unchanged. Verified against the real
CLI: "typewriter effect on a title" now returns typewriter first, and
"chat conversation between a user and an assistant" returns chat-message,
chat-thread, ai-chat-reveal instead of transitions-blur.
* docs(skills): say to query the catalog in English
The runtime message added alongside this explains an unsearchable query
after the fact. Saying it up front is cheaper: an agent that never writes
the query in Japanese never sees the error, never wastes the turn, and
never files a gap report about a component that exists.
Worth stating rather than assuming, because the mistake is a reasonable
one. On a Japanese or Chinese project the brief, the narration and the
captions are all in that language and the query naturally follows. The
rule is that the query language and the video language are unrelated:
describe the move in English, write the on-screen copy in whatever the
video needs.
Both skills that own `catalog --query` carry it, and those are the only
two that mention the command at all.
* fix(catalog): fail a non-English query instead of returning nothing
The message explaining an unsearchable query went to stdout and the
command exited 0. An agent that checks the exit code, which is most of
them, read that as "searched successfully, the catalog has nothing" and
went off to hand-author a move that is sitting in the registry. The
explanation only helped a human who happened to be reading the terminal.
It is bad input, not an empty shelf, so it now behaves like one: the
guidance goes to stderr and the command exits 1, matching what an invalid
--type already does. A genuine empty result, where the query parsed fine
and the catalog simply has nothing, still exits 0 -- that distinction is
the whole point, and both halves are pinned by tests.
The wording now also says what to do rather than only what happened:
search in English, and let the on-screen copy of the video stay in
whatever language it needs. That was the part agents were getting wrong,
since a Japanese project makes a Japanese query feel natural.
Test plan: 3 new tests covering the exit code, the wording, and the
genuine-empty case that must stay at 0. Also asserts the gap-report line
is absent, since nothing was searched and a report there is noise in the
one signal that tells us what to build. catalog.test.ts 32 passed;
commands + registry suites 887 passed with the 2 pre-existing transcribe
failures unchanged. Verified against the real CLI: a CJK query exits 1, a
genuine miss exits 0.
Aditya Poudyal