66 Commits

Include renames

Author	SHA1	Message	Date
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
Miguel Ángel	9ec75a485f	docs: drop --full-depth from skills install commands (#3399) ... * Update skills.mdx * docs: drop --full-depth from skills install commands	2026-08-21 14:45:01 -04:00
Vance IngallsandClaude Opus 5	56d8df65ca	docs(skills): add /hyperframes-audio, and key the waveform cache by file (#3211) ... * feat(studio): show every automated knob at the playhead, and carve as one module An automated parameter has two values: the number sitting in the chain, which is only the seed a lane replaced, and the number the envelope is on right now. The second is the true one, so the panel shows it — on the carve rack's readouts and on every effect's own fader and number field. A rack that showed the seed stood still while the carve was audibly working. Off the clip it keeps sampling rather than falling back to the stored number: a lane holds its first value backwards and its last forwards, so before the clip starts it already knows what it will open on, and the stored seed is a value nothing will ever play. Showing it made the fader jump the moment the clip came under the playhead. The playhead comes off the liveTime channel, throttled to 30 Hz — the RAF loop deliberately keeps frames out of the store, so a panel watching only the store would sit still for a whole take. PropertyPanel had that subscription inline; it is now one shared hook with two callers. Readouts reserve the width their parameter can need rather than what its current value takes, because an updating value one character narrower shunted everything after it sideways 30 times a second. The carve's effects are presented as one module: an author switched on a carve, and the peaking filters plus the level stage are how it is built, not six things to remove one at a time. Opening it lists every member's settings as readouts, since strength is what sets them. No carve control is offered on a track another track already carves against — that track is the voice, not the bed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(studio-server): key the waveform cache on the file, not just its path Two takes written to the same path returned the first one's waveform, so a re-recorded track drew the shape of the audio it replaced. The key now carries size and mtime, which is enough to notice the bytes changed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(engine): render audio FX in an OfflineAudioContext Reads `data-fx-chain` off an audio element and runs the chain over the trimmed WAV before volume automation is baked in — effects should see the raw signal, and the envelope belongs on their output. The processing happens in an OfflineAudioContext inside the headless browser the engine already drives, running the same graph builders the studio previews with. That is the point of the approach: one implementation per effect, so the render agreeing with the preview is a property of the architecture rather than a tolerance to police. Reimplementing each effect as an FFmpeg filter would mean two implementations to keep in step, and for the dynamics processors and modulated delays there is no filter that behaves the same way. `build:audio-fx-runtime` bundles the graph builders into an injectable IIFE, following the same pattern as the existing runtime artifacts, so the browser runs exactly the code the studio does. The page loads from a file:// URL rather than about:blank because AudioWorklet is only exposed in a secure context — the compressor, limiter, gate and bitcrush processors would otherwise fail to register with an opaque error. file:// qualifies and needs no listening socket. The chain is serialised into the attribute the way colour grading carries its config, so there is no side-car file to resolve or lose. An FX failure is fatal for the whole mix rather than a per-track soft failure. Every other audio failure mode degrades gracefully — the track drops, siblings continue — but substituting the dry signal for a processed one ships a render that sounds plausible and is not what the author set up. Since the per-element work races under Promise.all, an internal AbortController chained off the caller's signal aborts in-flight siblings before workDir is removed. * feat(core): voiceover carve analysis Finds the bands a voice occupies so a music bed can be dipped there, letting the voice sit in front without ducking the whole track. Carve is a relationship between two tracks rather than an effect on one, so it stays out of the FX chain. What it emits is an ordinary chain of peaking filters, so a carve composes with whatever else is on the track and needs no separate rendering path. Selection is weighted toward intelligibility rather than raw voice energy. Ranking purely by power lands on the fundamental almost every time, because that is where a voice is loudest — but the masking that actually hurts a voiceover happens higher up, and dipping 160 Hz mostly just thins the bed. The bias is a control, not a constant: at 0 it follows raw energy, at 1 it weights toward 1-3 kHz. Ranking happens in dB, which matters more than it looks. Speech spreads 20-30 dB across these bands — it falls off roughly 6 dB per octave above the fundamental — so a weighting has to be on that scale to move anything at all. A multiplicative weight of `1 - bias + bias * shaped` is bounded below by `1 - bias`, capping its influence at 10*log10(1/(1 - bias)): 5.2 dB at the 0.7 default, 3 dB at 0.5. That is no influence against a real voice — every bias short of ~0.95 would rank exactly like bias 0 and carve the fundamental, the outcome the bias exists to prevent, while looking decisive against a fixture whose bands sit 2 dB apart. So the bias is a dB penalty, zero at 2 kHz and worth up to 30 dB at full strength, and relative cut depths come from a dB difference rather than a ratio of weighted linear powers. The bias reweights ranking without overriding the spectrum — a band the voice has no energy in is not worth carving, and scores -Infinity rather than competing — so a strongly low-pitched voice can still select low at full bias. What the tests hold is that biasing never selects lower than the unbiased ranking, that the DEFAULT bias reaches the presence region on a voice with a realistic tilt, and that bias 0 still follows raw power exactly. Includes a radix-2 FFT rather than a dependency; one Welch-style averaged spectrum over third-octave bands does not justify pulling in a DSP library. * fix(engine): keep the FX render 16-bit, stereo, and correctly sized Three defects in the offline FX path, none of which any test could see. **Float output silently disabled sample-accurate volume automation.** The writer emitted 32-bit IEEE float; the very next mixer step bakes the volume envelope into the samples and accepts only 16-bit PCM, returning null otherwise. So enabling any effect downgraded that track to the ffmpeg expression path — capped at 32 straight segments, quantising a curved envelope, and on a dense one falling back to base volume. It now writes 16-bit PCM, clamped rather than wrapped so a limiter at 0 dB or a resonant filter cannot turn overshoot into a click. A test asserts the baker accepts the writer's own output and actually fades it. **Everything was folded to mono.** `prepareAudioTrack` goes out of its way to emit stereo — its pan filter exists to dodge ffmpeg's 3 dB mono-to-stereo rematrix — and this folded it, then wrote one channel. So adding a single peaking EQ collapsed a bed's width and cost ~3 dB in the render, while preview stayed stereo. Channels now travel as one plane each, through an OfflineAudioContext of the same width, and come back interleaved. **Small results decoded the wrong length.** `new Float32Array(buf.buffer)` discards byteOffset and byteLength, and Node pools small allocations: a 400-byte payload sits at offset 8 inside an 8 KiB pool, so a clip under ~1024 samples decoded as 2048 samples of unrelated memory — and the empty-result guard could not see it. The reader has the mirror-image fix: a float data chunk on an odd boundary (ffmpeg's pcm_f32le writes fmt(18) + fact, landing `data` at 58) now copies instead of throwing RangeError on an unaligned view. The tail limitation is now stated rather than mis-stated: the context is exactly as long as the input, so a reverb or delay still ringing is cut there. The old comment claimed the opposite. How far a tail may run past a clip's end changes the clip's length in the mix, so it is a product decision, not one to make here. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(producer): report an FX render failure as an audio error `processCompositionAudio` reports per-track failures in its result, but an FX failure it cannot degrade past — a browser that will not launch, a chain that will not build — rejects instead. `runAudioStage` had no try, so that rejection escaped to the orchestrator as an unclassified pipeline exception, losing the stage/owner/retryable classification this stage exists to attach, and skipping its abort check on the way out. It now lands in `audioError` alongside every other cause, while an abort still keeps its own shape rather than being reported as an audio problem. Not done here: committing the generated `audio-fx-runtime-inline.ts` so a fresh clone typechecks packages/engine without building first. The bundle is built from the stub, and the stub changes three times across this stack — so the artifact differs per branch and would conflict on every restack. Its model, position-edits-render-inline.ts, is committed only because it is stable. Building before testing is this monorepo's existing contract (studio's tests need core's dist too), so the gap is not specific to audio FX and is better closed by a build ordering gate than by committing a per-branch artifact. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(engine): skip the browser FX render cases when there is no browser CI's `Test` job was red on this PR with four failures, all the same cause: Failed to launch the browser process: spawn /home/runner/.cache/hyperframes/chrome/chrome-headless-shell The job installs ffmpeg and no browser, deliberately — every other suite that needs an external binary already guards on it (`describe.skipIf(!HAS_FFMPEG)`). These cases were the only ones assuming a Chrome, so they failed on an absent dependency rather than on anything about the code. Guards on `resolveHeadlessShellPath()` — the same resolver `acquireBrowser` launches through, so the check cannot drift from the thing it guards the way a hard-coded cache path would. A configured path that does not exist throws; that is caught and read as "cannot run here". Checked both directions rather than just the green one: with a browser all 11 cases run and pass, and with `HYPERFRAMES_BROWSER_PATH` pointed at a missing binary exactly 3 skip and the other 8 still run. A guard that silently skipped everything would have looked identical in CI. They keep their value where it exists — every developer machine, and any job that has run `hyperframes browser ensure`. Not touched: the CodeQL failure on this PR is a run from 2026-08-07, five days and several force-pushes stale. None of the 17 open repo alerts are in files this PR changes; it re-runs on this push. * chore(engine): suppress the temp-file alert with the reason it is safe CodeQL flags `writeWav`'s `writeFileSync` as js/insecure-temporary-file (high) — the one new alert on #3021, and the reason its CodeQL check is red. It is a false positive, and the comment says why rather than just silencing it: `path` is always inside a directory made by `mkdtempSync`, never a name assembled directly under `tmpdir()`. Both callers are covered — the browser host page writes into `mkdtempSync(join(tmpdir(), "hf-fx-host-"))`, and the render output goes to the producer work dir, itself `mkdtempSync(join(tempRoot, "producer-project-"))`. mkdtemp picks the random suffix and creates the directory 0700 in one syscall, so the predictable filename inside it cannot be pre-created or symlinked by another user, which is the attack the rule is about. The analyzer sees the dataflow reach `tmpdir()` and not the mkdtemp in between. Suppressed inline rather than dismissed in the UI, so the justification lives next to the code and the rule stays live for anything added later in this file. Matches the repo's existing convention — `planV2.ts:222` carries an `lgtm[js/insecure-temporary-file]` for a different reason on the same rule. Correcting myself: I first reported this alert as not real, having intersected the PR's files against the default-branch alert list, which does not contain PR-ref alerts. Querying ?ref=refs/pull/3021/merge returns it straight away. * test(engine): probe ffmpeg and Chrome instead of assuming them Two failures on #3021's Test job, both about the environment rather than the code under test. **Bare `ffmpeg` is not on PATH in CI.** The 16-bit fixture shelled out to `execFileSync("ffmpeg", ...)` and died with ENOENT. The job does provide ffmpeg, through `prepare-ffmpeg-bin`, which is what `getFfmpegBinary()` resolves — every other ffmpeg-dependent suite in this package already goes through it. Now this one does too, and the case is `skipIf(!HAS_FFMPEG)` so a contributor without ffmpeg skips rather than fails. **The browser guard trusted the wrong thing.** It asked `resolveHeadlessShellPath()` and treated a returned path as "a browser is here". CI's cache holds a chrome-headless-shell that resolves and then fails to spawn — a partial download is indistinguishable from a working one by `existsSync`, which is all that resolver checks. So the three browser cases ran anyway and failed on the launch. It now runs `--version` and requires exit 0, which is the same probe the ffmpeg suites use: ask the binary, do not infer from the filesystem. Checked both directions rather than just the green one. With a working browser all 11 cases run and pass; with `HYPERFRAMES_BROWSER_PATH` pointed at a binary that exits non-zero — CI's exact situation — exactly 3 skip and the other 8 still run. A guard that quietly skipped everything would have looked identical on the CI summary. * feat(core): register the audio-fx-rack canary at 0% Lands the rollout switch dark, per the registry's own procedure: "Start at percentage: 0 and merge that — a canary at 0 is dead code you can land safely and ramp without a code review." Declared at the bottom of the stack so every branch above can read it. The gate itself goes in at wa-4-fx-panel, where the rack first appears. Scope is deliberate and stated in the description: it gates the AUTHORING surface only. A composition that already carries `data-fx-chain` still plays and renders it. A canary should stage who can REACH a feature, not make an attribute somebody already wrote silently inert — an agent that writes a chain through the skill would otherwise produce a file whose audio processing vanishes with no error. * feat(studio): audio FX panel generated from the registry Controls for the whole chain: add, remove, reorder, bypass, and every knob each effect declares. Nothing in the panel knows what a compressor is. The registry supplies each parameter's range, step, unit and scale and the panel renders what it finds, so adding an effect or a knob upstream needs no change here, and the panel cannot offer a value the renderer would reject — a typed-in figure is clamped into the declared range on the way through. Frequency and time controls span three or four decades, so those declare a log scale and the slider maps exponentially; a linear slider would spend most of its travel somewhere useless. Reorder is a first-class control because chain order changes the sound: a reverb before a compressor is not the same as after. Carve gets its own block rather than an entry in the add menu, with a picker for the voice track to listen to. It processes this track based on another one, which is how a sidechain control works — it lives on the track that changes, and names the source. * feat(studio): show the Audio FX section on audio tracks Adds `audioFx` to the editing-affordances contract and renders the FX panel in the inspector when an `<audio>` element is selected. The section is audio-only. A `<video>` carries its sound on a separate `<audio>` element, so an FX chain on the video would have nothing to process. Chain and carve settings are written straight back onto the element as serialised attributes, the way colour grading carries its config, so persistence is an ordinary attribute write and needs no new server route. A chain that cannot be parsed renders as empty rather than breaking the panel, and the attribute is left untouched until the user changes something. The collapsed group summarises what is on the track ("2 effects + carve") so the state is visible without expanding it. Wired into PropertyPanelFlat rather than PropertyPanel: STUDIO_FLAT_INSPECTOR_ENABLED defaults to true, so the flat inspector is what actually renders. * refactor(studio): lift audioFxSummary out of PropertyPanelFlat `PropertyPanelFlat.tsx` is 612 lines here against the repo's 600-line cap, so the required File size check is red — the sole reason this PR is blocked. The review says as much: "mechanical fix (~5 min), not a design problem. Code itself is LGTM." Moves `audioFxSummary` to `audioFxSummary.ts`, the same file a later branch creates for it. Deliberately the smallest cut that clears the cap rather than the whole `AudioFxGroup` extraction: every later commit in the stack edits AudioFxGroup, so moving it here would collide with each of them, while almost nothing touches this function. 595 lines. * feat(core,studio): hear the FX chain in preview, and run the carve analysis Splices an element's FX chain into the playback graph so preview stops being silent about effects, and wires the carve button that was previously inert. The chain goes between the decoded source and its gain stage: effects see the raw signal and volume automation rides on their output, matching the order the offline render uses. Since preview and render call the same graph builders, what is heard while scrubbing is what gets written. The splice lives in the transport rather than on the `<audio>` element. The transport plays each track from a decoded AudioBuffer and mutes the element to avoid doubling, so capturing the element with createMediaElementSource would have processed a stream nothing is listening to — it looked like it worked because the call succeeded, and the audio was unchanged. A chain that cannot be built plays dry rather than silencing the track, which is the right failure in preview: the author keeps working and hears the source. The render still refuses, because shipping the dry signal there would be wrong. Carve now analyses for real: it decodes the chosen voice track, ranks its bands and writes the resulting peaking filters onto this track. Generated nodes are tagged `fromCarve`, so re-running replaces the previous carve instead of stacking another set on top of hand-added effects. Known limitation: the graph is built when a source is scheduled, so a knob turned mid-playback takes effect on the next play or seek rather than immediately. Live re-parameterisation needs the transport to hold the handle and forward updates. * fix(studio,core): stop parameter drags from restarting playback Dragging a knob wrote the chain through the persisting attribute path on every input event. That path refreshes the preview, which reloads the composition and reschedules audio — so a single drag reloaded dozens of times and playback stuttered the whole way. Drags now go through `onSetAttributeLive`, the same path colour grading uses for scrubs: it coalesces undo entries and sets `skipRefresh`, so no reload happens. The persisting write fires once, when the gesture ends — pointer-up or blur for a slider, Enter or blur for a typed value. A select commits immediately since there is no drag to wait for. While dragging, the control is driven from local state. Waiting for the value to round-trip through the element attribute made the knob lag behind the pointer. For the change to be audible without a reload, the graph now follows the attribute: the chain installed by the transport observes the element and re-parameterises itself in place, so a value change lands on the next 128-sample quantum. A shape change (effect added, bypassed, pole count) cannot be patched into a running graph, so it still waits for the next schedule rather than cutting the audio mid-play. The regression test drags a slider through several values and asserts the persisting handler is untouched until release. * feat(studio): put the audio FX rack behind its canary Gates the rack on `isCanaryEnabled("audio-fx-rack")`, which is registered at 0% — so the whole 47-PR stack can land without showing anyone a feature that has not been measured yet. The gate sits on the AUTHORING surface and nowhere else. The runtime and the render still honour a `data-fx-chain` already on an element, so a composition written through the skill or by `carve.mjs` keeps its processing rather than going silently dry for anyone outside the cohort. A canary should stage who can REACH a feature, not make an attribute somebody already wrote stop working with no error. Gated at the panel rather than in `resolveEditingSections`: the affordance resolver is a pure function in core describing what an element CAN support, and rollout state is not a property of an `<audio>` tag. Pinned the 0% with a test, and checked it fails at 25 — a ramp should have to break something that says "this ships dark" out loud. One gap, stated rather than papered over: the gate itself has no unit test. I wrote one and deleted it, because `PropertyPanel.test.tsx`'s harness never renders the Audio FX group for its audio fixture even with the gate removed — so the test passed for the wrong reason in the off case and could not pass at all in the on case. A test that cannot fail for the right reason is worse than none. Verifying the gate needs the panel harness to mount that section first, which is its own change. * fix(core): register FX worklets before building nodes that need them An AudioWorkletNode cannot be constructed before its processor is registered — it throws, and the surrounding chain is lost with it. `attachElementFxChain` built the chain first and only then called `ensureAudioFxWorklets`, so every worklet-backed effect (compressor, limiter, gate, bitcrush) threw on construction and the track fell back to dry. Instrumenting the preview showed `hf-compressor: InvalidStateError` with addModule never called at all. When the module has not landed yet the track now plays dry and the graph is swapped in once registration resolves, so the effect arrives a moment late instead of never. Registration is also tracked per context rather than in one module-level promise. A processor registered on one AudioContext does not exist on another, so the shared promise made every context after the first believe it was ready when it was not — the studio's transport owns its own context, which is exactly that case. With the worklets actually running, the compressor's per-sample log10 and pow became real audio-thread work. Samples below the knee have a gain of exactly unity and need neither, so the envelope is now compared in the linear domain and the transcendentals only run for samples that are actually being compressed. * refactor(studio): split the FX node row out of FxSection Clears the health findings the FX stack left behind: the chain-node render callback was a 70-line closure over half of FxSection's state, and the two reorder arrows were the same button written twice. Also drops two exports with no consumers, and registers the audio FX runtime stub as an entry point — it is bundled by file path, so nothing imports it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(core): automation envelope model for audio tracks Adds the data model behind Ableton-style automation lanes: breakpoint envelopes over track volume or one knob of one effect in the track's FX chain, stored on the element as `data-automation`. Times are clip-local, so an envelope travels with the clip when it moves — the clip-envelope model rather than arrangement automation. `sampleAutomationLane` is the single interpolator. The lane drawing, the preview scheduler and the render bake all call it, so the picture and the sound cannot disagree about the curve. Log-scaled parameters interpolate in log space, matching what their own knob already promises. FX nodes gain a stable `id`, minted by count rather than randomly so the document is the same on every machine. Lanes address nodes by id, so reordering a chain never re-points a lane at a different effect, and a lane whose effect was deleted is dropped rather than left to reattach. Also warns when a track carries both a volume lane and a GSAP volume tween, since only the lane is heard and the tween silently does nothing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * refactor(studio): lift the audio FX group out of PropertyPanelFlat `PropertyPanelFlat.tsx` was 672 lines against the repo's 600-line cap, so the required File size check was red — the sole reason #3014 and #3022 are blocked. Both reviews say the same thing: "mechanical fix, not a design problem. Code itself is LGTM." Moves `AudioFxGroup` and `audioFxSummary` into `propertyPanelAudioFxGroup.tsx`, which is where a later branch puts them anyway — done here so the file is under the cap from the point it first crosses it, rather than ten branches later. 533 lines now. The four audio imports it no longer needs go with it. Not fixed here: three `FxSection carve` tests fail on this branch with "Cannot read properties of undefined (reading 'toFixed')". Confirmed pre-existing by stashing this change and re-running — that is the separate `Test` failure the review also flags. * feat(core): expose the AudioParams behind automatable FX knobs Marks the knobs an automation lane can drive and has each graph builder hand back the AudioParam behind them, so a scheduler can write to a running effect without knowing what the effect is. A knob is not always one AudioParam. A wet/dry mix is two gains moving in opposition, and a knob in milliseconds drives a delay time in seconds, so each target carries the mapping out of the knob's own declared unit. What stays unautomatable is stated where it is decided: a WaveShaper curve, a convolution impulse and a one-pole filter's coefficients are all rebuilt wholesale rather than scheduled, and the four worklet effects take values by postMessage rather than through AudioParams. The registry flag is written by hand, so a test builds every effect and checks the exposure both ways — nothing flagged is missing, nothing exposed is unflagged. A flag that lied would offer a lane that silently did nothing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(core): play automation envelopes in preview Schedules each lane onto the AudioParams behind its knob using native ramps and value curves. Nothing evaluates the envelope per frame: it is handed to the audio thread once, so it stays sample-accurate however busy the main thread is, and the offline render will schedule it the same way. Timing comes from the transport, so an envelope survives seeking into the middle of a clip, a clip that has not started yet, and a playback rate that compresses clip seconds into context seconds. A straight line is only scheduled as a ramp when nothing bends it — no curvature, a linear parameter scale, and no unit mapping. Log-scaled parameters and mapped ones are sampled instead, since a delay knob in milliseconds and a wet/dry pair moving in opposition are not linear in the parameter they drive. Lanes with nowhere to write are skipped rather than reported: a one-pole filter exposes no frequency param, and the worklet effects expose none at all. Editing an envelope mid-playback re-aims it at the live playhead rather than restarting the track. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(core): make the volume lane audible in preview The envelope was scheduled onto the transport's gain AudioParam, but the runtime rewrites that gain every tick from `data-volume` and the GSAP-seeked value — so it was erased within a frame. Volume automation was correct in the render and inaudible while previewing. The lane now feeds the per-tick path where the probed volume keyframes already sit, checked ahead of them so the two cannot fight, and the transport no longer schedules volume at all: one mechanism instead of two racing. The cost is honest — in preview the level steps per tick rather than per sample, exactly as the existing keyframe path does. The render still bakes it into the PCM sample-accurately, and FX parameters are still scheduled on their own AudioParams, since nothing rewrites those. Parsed lanes are cached by attribute text: the runtime asks once per tick per track, and parsing there would run the JSON parser 60 times a second for a value that only changes on an edit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(engine): bake automation envelopes into the render The offline render schedules FX lanes with the same scheduler preview uses, inside the OfflineAudioContext that already runs the same graph builders. The input WAV is the clip's own audio from its first sample, so clip-local time is offline time and the envelope needs no offset. Volume lanes take the existing PCM bake rather than a second mechanism: the lane is converted to keyframes, so a straight fade stays two of them and only a bent segment is sampled — the baker interpolates linearly and would otherwise quietly straighten the curve. A volume lane supersedes keyframes probed from the timeline, which `lint` already warns about. A browser test sweeps a lowpass from below a 2 kHz tone to well above it and measures both ends. Parsing the envelope is not the same as scheduling it, and only running the real thing tells the two apart. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(core): apply chain edits to the running graph A structural edit — an effect added, removed, bypassed, or a filter's pole count switched — was dropped. `buildFxChain`'s update reports false when the change is not merely new values, and the attribute observer ignored that, so the edit only took hold when the persisting write reloaded the composition. That reload restarted every playing track, which is what was heard as the audio chopping. The graph is now swapped in place: the old effects are detached, the new ones built and connected between the same source and gain, and any lanes re-scheduled onto the new nodes. The source node is never touched, so playback does not restart. A track with no chain is watched too, rather than wired through and forgotten, so adding its first effect is heard the same way. That means the function always returns a disposer instead of null for the empty case. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(studio): drop the FX panel's dead __testables export Fallow audit flagged it — no test imports the module. * fix(core,studio): clear the remaining Fallow audit findings on the FX panel - Split FxSection's per-node row into FxNodeRow + FxNodeControls so the CRAP score (31.6, threshold 30) splits across two smaller units instead of moving wholesale with one extraction. - Dedupe the repeated "open the add menu, read its items" block in propertyPanelFxSection.test.tsx into openAddMenuItems(). - Merge build-audio-fx-runtime.ts and build-position-edits-render.ts into one build-inline-artifact.ts, config-selected by CLI arg — the two scripts were a byte-for-byte clone save for names. - Exempt canary.test.ts's rawFnv (a deliberate independent reimplementation used to cross-check canaryBucket, per its own docstring) and the property-panel test files' shared renderInto/mount scaffolding (pre-existing across 9 files, 2 outside this stack) in .fallowrc.jsonc, consistent with this file's existing exemptions for the same class of intentional/pre-existing duplication. * fix(ci): allowlist the build-script consolidation in the no-main-deletions guard build-audio-fx-runtime.ts and build-position-edits-render.ts were merged into build-inline-artifact.ts to kill a fallow duplication finding; the deletion guard flagged that as an accidental loss since main still has both originals. * fix(core): dedupe the wet/dry mix math between delayFeedback and chorusLfo Both effect builders set wet.gain to the mix and dry.gain to its complement in identical two-line blocks; fallow kept re-flagging it as a 10-line clone on every unrelated change. Extracted setWetDryMix. * fix(core): remove the build-audio-fx-runtime.ts stray resurrected by a main merge An earlier merge with main brought this deleted file back (git's merge/delete handling on an unchanged-on-one-side file); package.json already points at build-inline-artifact.ts, so it sat unreachable and duplicating that file's config, both of which fallow flagged. * fix(studio): pull TimelineLanes under the 600-line cap TimelineLanes.tsx hit 620 lines. Extracted the three per-clip pointer gestures (resize-start, pointer-down move-arm, click/razor-split) into createClipGestureHandlers — one factory call per rendered clip instead of ~120 lines of inline handler bodies in the render loop. 529 lines now. * fix(studio): split the extracted pointerdown handler under the CRAP threshold Moving the ~120-line gesture logic into timelineClipGestureHandlers.ts concentrated it into two functions fallow flagged (onPointerDown at CRAP 63.6, onResizeStart at 31.6). Split the decision logic (which gesture a pointerdown implies) into a pure resolvePointerDownAction, then split its own intent-blocking check into isIntentBlocked. onResizeStart's guard moved into canStartResize. Every function now scores under 30. * fix(studio): drop the unused DomEditSelection import in PropertyPanelFlat CI caught it on PR #3026 (wa-12-panel-params); a later refactor in the stack removed the last use of the type here without removing the import. * fix(studio): close the typecheck and fallow gaps wa-18b-reschedule opened useAutomationLanes.ts's write() assumed gesture-scoped coalescing and a preview-only commit that useDomEditAttributeCommits.ts never grew — backported that option support from its own later commit so the two sides of the API agree. The paste path and its tests were missing the box selection's v0/v1 bounds a sibling commit added to AutomationSelection. The FX panel's carve controls still edited the six mechanism numbers (maxCutDb, bands, intelligibilityBias) after carveProfile() collapsed authoring to one Strength knob, so those fields no longer existed on HfCarveSettings; UI now edits strength, and analyseCarveBands is called with carveProfile(strength). Also closes fallow's complexity, dead-code and duplication findings on this PR's diff: extracted automationLaneDragMath.ts (pure group/point-move math) and useAutomationRangeDrag.ts (the marquee-select gesture) out of useAutomationLaneGestures.ts, pulled a couple of render-loop ternaries and a resolver into named functions, dropped an export nothing outside its file used, and shared a step-simplifier between audioCarve's two envelope builders. The edge-stretch vs. box-select priority test in TimelineAutomationLane.test was still pinning the pre-box-select rule (edge wins over a point sitting on it) that a sibling commit deliberately reversed — a point inside the box is now selected content, so grabbing it drags the group instead. Updated the test to the shipped rule instead of the old one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(core): cap the via conic's weight so an edge-clamped via point can't NaN A via point pulled out past the segment (viaX: 5, viaY: -3) clamps to (0.999, 0.001) — exactly on the steady region's edge, where edge - viaX is 0. viaConic divided by that zero to get an infinite weight, and shapeVia turned Infinity into NaN a few steps later (Infinity - Infinity in the quadratic coefficient). NaN reaching setValueCurveAtTime silences the automated parameter for the rest of the render. Capped the weight at 1e6 instead of leaving it unbounded — past that point the arc already reads as touching the via point, so nothing visible is lost. Also hardened shapeVia's existing denominator guard (`<= 0`) to `!(> 0)`, since NaN fails the original comparison and fell through it. Review by Miga (PR #3208). * fix(studio-server): fingerprint the proactive waveform cache key too The route already keys the waveform cache on the asset's size and mtime as well as its path, so a rebuilt-in-place file gets fresh peaks instead of stale ones. generateWaveformCache — the proactive path that runs on upload — still called buildWaveformCacheKey with the path alone, so it wrote to a different key than the route reads from (making the pre-generated cache never found) and kept the exact collision bug this fingerprint exists to fix on its own path. Review by Miga (PR #3211). * style(docs): run oxfmt on the /hyperframes-audio skill docs Table column widths had drifted out of alignment with oxfmt's own rules, failing format:check and blocking the Preflight gate every downstream branch inherits. Whitespace only, no content change. * fix(studio): widen PropertyPanel's resetModules render timeout again The 20s margin (already once widened for the same reason) is timing out in CI's full-monorepo Test run — the resetModules()+fresh-import render this test needs is uncached and competes with every other package's test suite for the same worker pool, and the same test passes in well under 2s standalone. Went to 45s rather than re-tuning to whatever number happens to clear the current CI load, since that number moves every time CI gains a package. * feat(core): carve against every voice over a bed, always (#3212) * feat(core): carve against every voice over a bed, always dynamically A bed usually runs under a whole sequence — a narrator, an interview answer, a second presenter — and carving against one of them left the others fighting it. `source` becomes `sources`, and `mixCarveSources` sums every voice onto the BED's clock before anything is measured. That is what keeps one analysis sufficient: the chain is fixed, so there is no per-voice filter to switch between, and bands drawn from all the speech there is with envelopes that rise wherever any of it happens answer the actual question — where and when is speech masking this bed. Summed rather than averaged: two people talking at once mask more than either alone. Audio before the bed starts is dropped rather than folded in at zero, since it plays over nothing and shifting it would put a cut where there is no voice. `dynamic` is gone. A fixed depth thins the bed through every pause, and once both have been heard there is no reason to want it, so every carve follows the speech. Two helpers the panel and the headless script now share instead of each carrying a copy — two definitions of "what does this name suggest" drift, and then the two disagree about which track is the voice: - `classifyAudioName` reads a track's kind from its id and filename together. `unknown` is deliberately common: treating an unrecognised name as "not a voice" would hide the one track somebody needs to pick. - `clipsOverlap` keeps out a voice that never plays while the bed does. An unwritten duration counts as unbounded, not zero — refusing a clip whose length the composition leaves to the media would drop the commonest case there is. Files written before this still load: a single `source` reads as a one-voice list, a stored `dynamic` is ignored, and an absent attribute means the defaults whole. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(core): stop \b from missing underscore-separated names, guard clipsOverlap's negative duration \b treats `_` as a word character, so \bbed\b never matched bed_01, music_bed_loop, or theme_song, and \bvo\b/\bvox\b/\btts\b had the same gap — an underscore-separated bed classified as "unknown" and could end up offered as its own carve source. Replaced the short hints with a boundary that actually excludes letters and digits on both sides. clipsOverlap computed end = start + duration without guarding sign, so a negative duration put end before start — an interval that does not describe anything, and one specific case showed it silently dropping a real overlap (a shorter, earlier broken end rejected a clip that genuinely contained the point). Duration clamps to zero instead: a clip cannot un-play time, and a zero-length clip at its start is the sane reading of "duration nobody wrote down as positive." Review by Miga (PR #3212). --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(studio): port the carve UI off the removed source/dynamic fields #3212 (accidentally squash-merged into this branch instead of main) changed HfCarveSettings from a single `source` + `dynamic` toggle to a `sources` list with dynamic mode removed outright — the multi-voice UI consumer that goes with that shape lands in the very next PR, so this branch was left with a type that no longer matched its own code. Minimal port, not the multi-voice redesign that PR does properly: the "Listen to" picker and analyse() treat sources[0] as the one voice this UI still understands, and every dynamic-mode branch (the automated envelope lanes, the toggle, the checkbox) is gone along with the field — a carve is now always the static value the analysis computes, matching what the type change made permanent. Test suite trimmed the same way: the automation-lane and toggle tests covered behavior that no longer exists. --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-13 02:16:36 -07:00
James Russo	27d113e56c	docs: add user interview booking links (#3059)	2026-08-05 12:35:58 -07:00
WaterrrForever	2efbfd4758	docs(prompting): document the intent interview and align pages with skill contracts (#2872) ... * docs(prompting): correct workflow one-liners against skill contracts general-video leads with its positive identity and companion mode; faceless-explainer keys on invented visuals instead of TTS; talking-head-recut uses the 'graphic overlays' trigger term; motion-graphics gains its input side and overlay output; music-to-video stops implying images are required. * docs(prompting): make vocabulary video grids readable Replace the 4-5 column table hack with a 3-column CSS grid, switch demo clips to autoplay muted loops (no black poster frame, no player chrome over tiny videos), and align cells at 16:9. * docs(prompting): document the opening interview and run-shape questions The guide taught prompt shapes but never prepared readers for the conversation that follows: the intent interview, the two run-shape questions (storyboard, automation vs companion), the just-build-it skip, and BRIEF.md as the resumable artifact. Add that section to the overview, a disambiguation note on the storyboards page, and free up 'companion' as a reserved term in media-and-audio. * docs(guides): make BRIEF.md the pipeline's Step 3 artifact Step 3 (Strategy & Messaging) listed no output while describing exactly what BRIEF.md now captures. Name the artifact in the step table, project tree, step body, gate, and iterating list, and fix SCRIPT.md's step label in the tree (Step 4, not 3). * docs(quickstart): realign the setup surface with the skills catalog The quickstart drifted from docs/guides/skills.mdx, CLAUDE.md, and the prompting overview — it had never been updated when those surfaces were: - `--full-depth` on both install commands, with the reason inline. Without it `skills add` fetches the skills.sh registry blob, which lags `main` by hours, so a reader following the quickstart installs stale skills. - `check` in the `/hyperframes-cli` row, and a validate step in the manual dev loop, which went preview → render with no gate at all. The prompting overview calls `check` "the step people skip and regret" and states both `lint` and `check` must pass before rendering. - `/hyperframes-keyframes` in the core-skills table (8 rows → 9). - `/figma` in the optional-workflow list (10 → 11). * docs(skills): close the catalog drift class and complete the music-to-video input Follow-up on the two review nits from #2872. `/music-to-video`'s SKILL.md names three inputs — an audio file, a video to pull audio from, or a track generated from a mood brief. Every compressed copy of that description carried only the first two, and the third is the one that makes "a complete video needs zero assets" true. Fixed on all eight surfaces that state it, so no surface is now more correct than its siblings: the prompting overview and quickstart setup tables, docs/guides/skills.mdx, the README catalog, root CLAUDE.md + AGENTS.md, both CLI project templates, and the router's own routes/music-to-video.md Input line (whose Interview must-haves already listed all three). The drift was structural, not accidental: the sync set declared in docs/guides/skills.mdx and in CLAUDE.md's "Skill catalog maintenance" named four surfaces and never the two setup tables, so those two were free to rot while the declared four stayed correct. Both declarations now name them, and both say the set applies to a *changed contract* — a reworded description — not only to an added or renamed skill. skills-manifest.json regenerated for the touched route file. * docs(claude): point the routing-surface rule at routes/, not the moved stubs Item 3 of "Skill catalog maintenance" still sent readers to `references/workflow-catalog.md` for a workflow's input/output/trigger contract and `references/route-briefs.md` for its interview entry. Both are now "moved" stubs — the contract and the interview entry live together in `references/routes/<workflow>.md`, one read per candidate route. Same failure class the previous commit fixed at item 1: a maintenance rule outliving the layout it describes. Swept the tree for other pointers at the two stubs; there are none, so this closes it rather than fixing one instance.	2026-07-31 01:17:11 +08:00
James RussoandMiao Yang	696cbdbbd0	chore(skills): package Codex plugin upload (#2668) ... * chore(skills): package Codex plugin upload * chore(skills): harden Codex plugin content * fix(skills): satisfy plugin quality gates * fix(skills): address plugin packaging review * fix(plugin): simplify asset validation * fix(skills): correct embedded-captions catalog count to 35 after nightcity removal The nightcity theme removal left SKILL.md claiming 36 identities in four places, including the frontmatter description the router reads. The catalog now has 35 entries (10 classic + 25 themed). --------- Co-authored-by: Miao Yang <miao.yang@heygen.com>	2026-07-22 00:41:40 +08:00
WaterrrForever	3bb26b0f08	docs(skills): make the core set the default install on every surface (#2554) ... * docs(skills): make the core set the default install on every surface A field test showed an agent with a real 'make videos' intent installing all 19 skills: at install time, every surface it could read pointed at the full set, while the core-eager / workflow-on-demand design only exists inside hyperframes/SKILL.md - unreadable until after the install decision. Two traps made full-install the documented default: - The README Quick Start used 'skills add --yes': skills.sh force-detects agent environments into non-interactive mode, and a non-interactive run without --skill installs all 19. Dropping --yes fixes the human path (the picker opens with nothing pre-selected), but not the agent path. - marketplace.json listed the full 'hyperframes' bundle first, under the name an agent installing 'hyperframes' matches; core-skills sat second. Changes, each behavior verified by an isolated run: - README Quick Start drops --yes (humans get the picker; verified via a pty capture that nothing is pre-selected) and points agents and non-interactive runs at 'npx hyperframes skills update', which from a clean HOME installs exactly the 8 core skills, refreshes stale ones and prunes unpublished ones on an existing machine, and is idempotent. - CLAUDE.md and the docs install guide lead with the same one-liner; --all is reworded to explicit-request-only at every surface. - marketplace.json puts core-skills first and both descriptions steer the default choice; the full entry keeps auto-discovery (no allowlist), per the skillsManifest core-pin test (56/56 pass). * docs(skills): close the same install trap in AGENTS.md Review follow-up on the core-default change: AGENTS.md still carried a bare 'npx skills add heygen-com/hyperframes' - no --full-depth, and the same non-interactive-installs-everything trap the README fix closed. AGENTS.md is the first file Codex/Cursor-family agents read for repo intent, so it leaked the full-set default to exactly the readers the core-default policy targets. It now leads with the same core-set one-liner and policy line as CLAUDE.md.	2026-07-17 00:49:43 +08:00
WaterrrForever	b9be0b2625	feat(skills,studio,media-use): the intent layer, review loop, and user memory — BRIEF.md, companion mode, recipes; /website-to-video folds into /product-launch-video (#2133) ... * feat(studio,cli): per-frame board comments, self-refreshing storyboard, status-aware preview landing Per-frame comment boxes on the storyboard board batch into .hyperframes/frame-comments.json (a resubmit wins per frame; unconsumed comments on other frames are kept). Submitted-but-unconsumed comments stay visible — a toolbar banner plus a per-tile echo — until the agent consumes the file; the banner also says what to do next (reply anything in the agent chat). The board keeps itself current: GET /projects/:id/signature exposes the watcher-cached project signature, the storyboard payload carries the signature it was derived from, and the view polls at 2s (hidden tabs skipped, re-checked on visibility), refetching in place with no loading flash. Posters bake the signature into their URL so tiles fill in as sketches land and a poster that failed mid-write retries on the next version; the empty state upgrades itself when STORYBOARD.md appears, and its handoff prompt now points the agent at the review loop and uses the parser's real status vocabulary (outline, not planned). preview lands the browser on the storyboard view while the board is the review surface — any frame built, or pure planning (srcs declared, none on disk yet) — and on the timeline once the video is assembled. * feat(skills): the review loop — plan, sketch, build as one shared process hyperframes-core/references/review-loop.md is the single source for the three-pass collaborative review: the plan proposed on a live board (§ 1), wireframe sketches marked built with one layout question (§ 2 — real words on plain blocks, run no CLI; a confirmed board is itself a valid deliverable when the user asked for a storyboard, not a video), the build dressing confirmed layouts (§ 3, worker or inline), and the final look (§ 4). Autonomous runs skip every gate and keep one question before render. The three narrative workflows' Steps 3/4/6 collapse to references plus their sketch stand-ins (captured-asset blocks for product-launch-video, plain code panels for pr-to-video); the confirmed-sketch handoff stays in each frame-worker prompt. general-video plans on a board for multi-scene narrative pieces in collaborative mode — its sketch pass is layout-before-animation with the user watching. The router treats "I want a storyboard" as a process request rather than a route, and closes exploratory intake by recommending a route plus how the run will review. The supporting contracts land next door: the comments channel (silent submit, one reply picks it up, check the file before the words) in brief-contract § 1; the sidecar schema and the built status rung in storyboard-format; the mode question asked first and alone in the three workflows' Step 0. * feat(media-use): user memory — remembered preferences and frozen recipes Two tiers of memory on media-use's existing two-tier storage split. Preferences (lightweight): confirmed brief answers — destination, aspect, language, mode, voice, style preset — recorded to the project's .media/preferences.json (committed, the team inherits it) and promoted to the personal ~/.media/preferences.json once the same value is confirmed in two different projects (a sightings ledger accumulates the cross-project evidence user-side, since project files can't see each other). prefs.mjs get/record; merge reads project-over-user; a changed value restarts its provenance. Recipes (heavyweight): one approved run frozen as a named, versioned bundle — frame.md, the storyboard skeleton (structure kept: durations, transitions, srcs, Video direction; statuses reset to outline; content blanked to per-frame fill-ins naming the beat's role), and the confirmed brief values. Named folders, not content hashes: re-freezing bumps version and archives <name>@v<N>; a freeze is already confirmed, so it promotes to the user tier immediately. recipe.mjs freeze/list/use, plus resolve --type recipe --entity <name> delegating like grade/lut. 16 new node --test cases; the media-use lib suite is 168/168. * feat(skills): wire user memory into the brief and the review loop brief-contract § 2 gains Remembered defaults: read the merged preferences before Round 2 and let a remembered value become the recommended option with a receipt naming its source project. Memory changes the default, never the question — every ask-marked field still gets asked, and what the request says this time beats what was picked last time. Record only what the user actually confirmed (a defaulted voice nobody chose is not an answer; a "go" that accepts the recommended defaults is). The first record announces itself once; after that the receipts carry the reminder. In autonomous mode a remembered value becomes the decided value, receipt included. The three narrative workflows read the remembered defaults before Round 2, record the confirmed answers at the Step 0 gate, record the chosen preset at the Step 2 gate (pr-to-video excepted — its preset is fixed), and fall back to the remembered voice when the request names none. general-video's discovery reads the same defaults. Recipes wire in at both ends: Step 0 checks for a matching recipe before the mode question — one question, plural-aware, and adopting one fills the brief, skips the design step, and drafts the storyboard from the frozen skeleton while every review gate still runs. The review loop's final look (§ 4) offers the freeze once after approval, and the confirmation teaches the recall phrase — the name is something the system reminds the user of, never something they must remember. The router recognizes a named recipe or "like last time" as a route. * docs(skills): the sketch pass names check, not the deprecated validate * feat(skills): intent-layer references — process, route briefs, capability menu, BRIEF.md format * feat(media-use): brief skeleton as the recipe's fourth artifact; flow/storyboard preference keys * feat(skills): the intent layer conducts every brief — workflows execute BRIEF.md * feat(skills): retire the mode preference key; sync catalog surfaces for intent layer * refactor(skills): dedupe router vs intent-layer guidance — one owner per rule * feat(skills): the design ask — own spec, pick by eye from showcases, or defer * docs(skills): the design ask says the honest line on capture routes * feat(skills): product-launch-video absorbs website-to-video as the tour angle * refactor(skills): keep product-launch-video pristine — a tour is brief intent, not a pipeline branch * feat(skills): production loop + genre lenses; general-video goes freeform (route yours, laws hold) * refactor(skills): /hyperframes is the front door - route tables and scope lists leave the workflows * docs(skills): review-loop pass across skill catalog * fix(cli): pass project dir to openStudioBrowser in background-server path * feat(skills): add pitch-round reference - verbalized sampling concept gate * feat(skills): wire pitch round into intent layer - completeness triage + route eligibility * feat(skills): editorial capability recommendations, handoff disciplines, menu-probe split * feat(skills): pitches carry their machinery; source-only-formed requests pitch the telling * feat(skills): companion goes director - ceiling treatment plus blueprint/rule citation discipline * fix(scripts): sandbox npx-leak guard - private npm global prefix keeps npx on the branch CLI * chore(skills): resync manifest hash after formatter pass reflowed general-video tables * fix(skills): recipe freeze reads workflow from BRIEF.md; style_preset records require workflow scope Two holes found by a live companion-run freeze: the agent-supplied --workflow contradicted the run's actual workflow (recipe.json said faceless-explainer, brief-skeleton said general-video), and the style_preset lookup missed because the preference had been recorded under the bare key. - freezeRecipe resolves the workflow from BRIEF.md frontmatter; the flag is a fallback for briefless projects and a contradicting flag is ignored (noted). - recordPreference refuses a bare style_preset — the scoped key is the only writable shape; freeze tolerates legacy bare records via read fallback. - review-loop § 4 / media-use SKILL / brief-format wording follow the machinery.	2026-07-15 21:19:14 +08:00
WaterrrForeverandClaude Fable 5	4a4903b49a	feat(skills): group core skills in the skills add picker (#2412) ... Add a `core-skills` entry to .claude-plugin/marketplace.json declaring the core skill set (the /hyperframes router, the hyperframes-* domain skills, and media-use). The upstream vercel-labs/skills CLI reads that entry's `skills` array for its interactive picker: the core set renders under a "Core Skills" group and everything else falls into "Other", so a human running `npx skills add heygen-com/hyperframes --full-depth` can tell the always-needed core set apart from the on-demand creation workflows — mirroring the core/on-demand tiers `hyperframes skills update` already enforces (isCoreSkill in skillsManifest.ts). The array deliberately lives on a separate marketplace entry, NOT on plugin.json or the `hyperframes` entry: Claude Code treats a manifest `skills` array as that plugin's skill allowlist (verified against claude CLI), so attaching it to the full plugin would narrow it from all skills to the core 8. As a side effect the new entry is itself a coherent Claude Code plugin — `core-skills@hyperframes` installs just the core set — while `hyperframes@hyperframes` keeps auto-discovering everything. A new pin test keeps the marketplace list in lockstep with isCoreSkill and the skills/ tree (alongside the existing FALLBACK_CORE_SKILLS pin), and asserts the full plugin carries no allowlist. Agent installs are unaffected — the upstream CLI detects agent environments and installs non-interactively, and the hyperframes CLI always passes explicit --skill flags. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>	2026-07-14 20:41:42 +08:00
Miguel Ángel	78b9a814d5	docs(skills): add cloud render + variables to CLI skill, media-use generative use cases (#2356) ... * docs(skills): add cloud render + variables to CLI skill, media-use generative use cases The hyperframes-cli skill only documented self-managed AWS Lambda rendering; the zero-infra HeyGen-hosted `cloud render` path (a real, shipped command with its own docs page) was absent from every skill, so agents never surfaced it. - hyperframes-cli: add `cloud` to the frontmatter verb list + entry point; new Cloud and Variables sections; new references/cloud.md distilled from docs/deploy/cloud.mdx; routing + workflow rows. - media-use: add image-to-video recipe (heygen video create type:image) plus a table of other HeyGen generative use cases (photo avatar, digital twin, video translation, lipsync, voice design) in references/operations.md; surface them in the SKILL coverage/provider rows. - Sync README + docs/guides/skills.mdx catalog entries to mention cloud render. * docs(media-use): point HeyGen generative use cases at --request-schema Verified against the installed heygen CLI (v0.3.0): no capability gap that would need the raw API. Replace hardcoded body-field lists with a pointer to `heygen video create --request-schema` (self-documenting, can't rot), correct the image-to-video motion_prompt/expressiveness support, and add the cinematic_avatar, ai-clipping, and photo-avatar creation paths. * fix(skills): correct media-use manifest hash (clean-tree regen) The prior regen was polluted by the gitignored skills/media-use/eval-report.html (a suppressed mv error left it present), so the committed media-use hash didn't match a clean checkout. Regenerate with no untracked artifacts present.	2026-07-13 18:53:19 -04:00
Miguel Angel Simon Sierra	cf7c1d7609	docs(cli,skills): teach check as the canonical verification gate ... Scaffolded projects' npm run check now invokes the single check command instead of chaining lint, validate, and inspect (three Chrome boots become one). The CLI skill, its correctness reference, the entry skill's capability map, README/docs catalog rows, the Mintlify CLI page (new check section, deprecation banner on inspect), template CLAUDE/AGENTS (byte-identical), root CLAUDE/AGENTS, and every creation-workflow skill that taught the old sequence all point at check. snapshot keeps its standalone sections; validate/inspect stay documented as deprecated aliases with their check equivalents.	2026-07-10 13:30:09 -04:00
Miguel ÁngelandClaude Opus 4.8	57b3c78987	feat(media-use): color grading — grade/lut resolve, smart-grade, grade-compare + compare (#2041) ... * feat(media-use): color grading — grade/lut resolve, smart-grade, grade-compare CLI Add color grading to media-use as first-class resolve types plus a faithful comparison command. All local, offline, deterministic — no model, no GPU. - resolve -t grade / -t lut: produce a data-color-grading block (or a frozen .cube). Look cascade: core preset (no file) -> bundled .cube library -> parametric buildCube. Emitted .cube is Rec.709 and validated against core's colorLuts constraints (LUT_3D_SIZE <= 64) before it is frozen. - smart grade (grade --for <media>): ffmpeg signalstats -> adjust suggestion (exposure / contrast / white balance), surfaced with the measured evidence on stderr as a starting point; never auto-applied. - hyperframes grade-compare: renders N candidate grades onto a reference frame through the real runtime shader into one labeled comparison PNG, so an agent picks a look without opening Studio. Prepends an "original" baseline cell by default (--no-baseline to omit). Shares the headless-capture pipeline with snapshot via capture/captureCompositionFrame. - media-use SKILL: proactive "media opportunity pass" guidance (grounded signal -> offer, ask once, surface don't mutate). Verified: media-use 116/116, grade-compare 7/7, snapshot 9/9, lint + format clean, full build green, comparison renders end to end. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv * test(cli): narrow grade-compare baseline assertion off unknown-typed grading Assert the whole cell via toEqual instead of reaching into .grading.preset / .grading.lut on the unknown-typed field, keeping the test typecheck-clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv * feat(media-use): agent-authored LUTs via --params + validate --from cube; never-read-.cube guardrail - resolve -t lut / -t grade --params '<json>': build a parametric .cube from explicit params (bypassing the intent cascade), validate, and freeze in one step. --intent becomes the optional description. Lets an agent commit a look it computed itself. - --from <file.cube> now validates the ingested LUT for lut/grade types and rejects an invalid/oversized cube (no partial write) — the escape hatch for a LUT the agent generated with its own code. - SKILL.md: hard rule to never read a .cube body into context (~size^3 lines, zero legible signal) — inspect via grade-compare (see it) or cube-validate (ok/size), read the manifest description for meaning; plus both authoring paths and the parametric-vs-film-stock ceiling note. Verified: media-use 116/116, lint + format clean; smokes — --params builds a valid frozen cube, grade --params returns a lut block, bad JSON and an oversized --from cube are both rejected with no stray file. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv * fix(cli): grade-compare validates referenced LUTs, warns on no-op cells, caps candidates Bug-bash follow-ups — grade-compare silently accepted bad input: - Validate LUT *content*, not just existence: each referenced .cube is parsed with core's parseCubeLut (now exported from @hyperframes/core) and rejected with a per-cell error ("LUT for \"<label>\" is not a valid .cube: ..."). A file that exists but isn't a valid cube no longer renders a silent no-op cell. - Warn on inactive cells: a grading that normalizes to inactive (e.g. a malformed {lut:12345}) emits a stderr warning naming the cell; the auto-prepended "original" baseline is intentionally inactive and stays silent. stdout remains valid JSON. - Cap candidates at 16 (excluding baseline): over-cap input renders the first N and reports {truncated:true, total:M} on stdout + a stderr note — no silent drop, no unbounded giant sheet. Verified: grade-compare 10/10; non-cube LUT → clear error; {lut:12345} → warning + ok; 20 cells → cells=17 truncated total=20; valid runs unchanged. Lint/format clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv * feat(cli): general `hyperframes compare` visual-variant primitive Generalize grade-compare's "render N variants → one labeled sheet → the agent looks and picks" loop into a standalone command that works on ANY variation (font, layout, motion, grade, whole compositions) — the tool never needs to know what differs. - `hyperframes compare <path...> [--at <sec>] [--labels a,b,c] [--out] [--cols] [--json]`: renders each agent-authored composition variant through the real runtime (captureCompositionFrame) and stitches one labeled comparison sheet + JSON ({ok, sheet, rendered, variants, truncated?/total?}). 2+ paths required; caps at 16 with loud truncation. It presents, it does not judge — choosing is the caller's job. - Factored the shared "render a labeled set → contact sheet" path so compare, grade-compare, and snapshot all sit on it (no duplication). grade-compare is now the first color-specific specialization of this primitive. - New pathArgs util + contactSheet test; hyperframes-cli SKILL documents compare as the agent's "see your own renders and choose" primitive. Verified: 26/26 across compare + grade-compare + snapshot + contactSheet (no regressions); compare renders 3 variants into one visibly-distinct labeled sheet; 2+-path error path clean; lint/format clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv * fix(ci): green the skills CI — skip ffmpeg tests when absent, oxfmt markdown The "Test: skills" CI job runs bare `node --test` with no ffmpeg on PATH (by design — skills tests are meant to be node-builtin-only). The grade-analyzer + smart-grade tests shell to ffmpeg and were failing there with ENOENT. Guard them to skip when ffmpeg isn't on PATH; they still run locally / where it is. Also oxfmt README.md + hyperframes/media-use SKILL.md (the whole-repo `oxfmt --check .` Format job caught markdown left unformatted by the rebase conflict resolution). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv * fix(ci): skip core-conformance test when tsx is unavailable The "Test: skills" CI job installs no deps, so the normalizeHfColorGrading conformance test (which imports core's TS via `node --import tsx`) failed there. Guard it to skip when tsx can't resolve; runs locally / in the deps-installed Test job. Completes the skills-CI greening (the ffmpeg guards handled the rest). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv * fix(cli): escape grade-compare src double-quotes (CodeQL XSS) + Windows-safe compare test - grade-compare built `<img src="...">` (double-quoted) with the single-quote escaper, leaving `"` unescaped — a `"` in the frame path could break out (CodeQL: incomplete HTML attribute sanitization). Use escapeXml for src. - compare label test hard-coded POSIX paths that can't match on Windows; assert the derived labels (the subject); path resolution is covered elsewhere. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv * refactor(media-use): generate LUT library from params (drop committed .cube files) The 3 bundled .cube files were 733 lines each (2,199 total) and were themselves buildCube output — pure repo bloat. Replace with compact per-look params in luts/index.json, generated on resolve; add an optional `url` for future scanned LUTs to be CDN-hosted + downloaded on demand (freezeUrl) instead of committed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv * feat(media-use): serve library LUTs from CDN on-demand (static.heygen.ai/luts), params fallback Looks now carry a CDN `url` (hosted at s3://heygen-public/luts → static.heygen.ai/luts/<id>.cube); resolve downloads + validates + freezes on demand, like bgm/image. `params` stays as the deterministic offline fallback (--local-only, or if the download fails), so resolution is never blocked on the network. Provider prefers url, falls back to params. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv * fix(media-use): address #2041 review — atomic LUT writes, compare telemetry, follow-ups - Atomic .cube writes: library provider (url + params) and the parametric generator now write to a .tmp path, validate, then rename, so a crash can never orphan an invalid .cube at the final path (was validate-after-write). - track("media_use_resolve") now emits provenance.via (url/params-fallback/params). - grade-compare + compare: --timeout flag (was hardcoded 5000) and a media_use_compare event (cells, truncated, total, render_ready_timed_out); openSettledCompositionPage now surfaces the render-ready timeout. - compare staging skips node_modules/.git; --for gets an upfront existence check. - Rec.709 luma comment; HYPERFRAMES_ANALYZE_TIMEOUT_MS override; measured note uses basename; LUT s3 hosting moved from index.json into luts/README.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-08 22:20:16 -04:00
4 people	81884a7495	fix(cli,skills): install workflow skills on demand instead of re-pulling the full set (#2012) ... * fix(cli,skills): install workflow skills on demand instead of re-pulling the full set Users report every init re-pulls all 21 skills into ~/.agents/skills whenever anything is stale or missing - heavy, noisy, and it re-expands deliberate partial installs. Split the set into two tiers: - core: the /hyperframes router + hyperframes-* domain skills + media-use, which every workflow references structurally. init and bare 'skills update' keep these (plus anything already installed) fresh, and never expand the install. - on demand: the end-user workflow skills (and figma). They install at trigger time via 'skills update <name...>' - positional names are the only way update expands an install: one targeted 'skills add --skill <name>' covering only stale/missing targets, a fast no-op when current, presence-verified after install, exit 1 on unknown names, and a presence-only degrade when GitHub is unreachable. The /hyperframes router now runs 'skills update <workflow>' after routing and before reading the workflow skill, so a routed workflow is guaranteed present even on a machine that only has the core set. Each on-demand skill also opens with the same self-maintenance step (run 'npx hyperframes skills update <name>' silently), so a workflow triggered directly - without the router - still refreshes itself and restores any missing core skill before relying on it. When the manifest is unreachable (offline / rate-limited) the engine degrades honestly instead of claiming success: named runs presence-check the request plus a pinned fallback core list (unit-pinned to skills/) and blind-install whatever is absent; a bare strict update fails loudly so the 'check || update' chain can't pass while everything stays stale; init reports the skipped freshness check. --json emits structured errors on failure paths. skills check still lists every skill, but exits non-zero only for stale installed skills, an incomplete core set, or removed leftovers - workflow skills not yet installed are reported as available on demand. Bare 'hyperframes skills' (and 'skills add --all') remain the explicit full-set installs. Verified end-to-end with a sandboxed $HOME: fresh init installs the 9 core skills only; 'skills update slideshow' adds exactly that skill (no-op on re-run, exit 1 on unknown names); bare update refreshes without expanding; a live Claude Code run routed PR-to-video, executed the router's update step, and the workflow skill appeared before use; and a second live run triggered an installed workflow directly, whose opening maintenance step restored a deliberately removed core skill. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(skills): clarify update-engine contracts + document lazy-install model - skills.ts: note the UpdateSkillsResult.unknown strict-mode contract, verifyInstalled's non-strict (warn-not-throw) intent, and that a partial install stays "refreshed but never expanded" (review nits). - docs/guides/skills.mdx: add a "Keeping skills current" section covering the core-eager / workflow-on-demand model and the skills check|update commands, per the repo's catalog-maintenance rule. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: kiritowoo <295860553+kiritowoo@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: Miao Yang <miao.yang@heygen.com>	2026-07-09 01:30:51 +08:00
WaterrrForever	4d3cdc3e4b	feat(media-use): resolve official brand logos via a four-tier cascade (#2061) ... * feat(media-use): resolve official brand logos via a four-tier cascade Third-party brand logos (the meeting's 'credibility signals lost' gap) had no acquisition path: capture only grabs the product's own site assets, and HeyGen asset search returns generic look-alike icons for brand queries (0/3 in testing — an X-in-a-circle for LinkedIn). Workers could only fake a mark or drop it. New resolve type 'logo', four tiers verified by a 54-brand stress test (100% cascade hit across dev tools / big tech / non-tech / CN brands): - svgl — official full-color vector SVGs + wordmark variants (40/54 first-hits); search is substring-based, so entities pass through alias normalization (nextjs → 'next.js', aws → 'amazon web services') - simple-icons (pinned CDN build) — official monochrome glyphs; catches the long tail (nike, visa, toyota, wechat, bytedance) - github org avatar — known-org map only; a brand name is not a GitHub login, guessing risks same-named personal accounts - domain favicon (DuckDuckGo ip3) — small-raster last resort; sub-500B responses are DDG's placeholder and rejected; frozen with a low_res provenance flag (chip-size use only) logo joins the icon/image equivalence group (typesMatch) and the images/ subdir, so entity cache hits interop with figma-imported marks. A total miss falls through resolve's normal failure path — no special casing. HeyGen search stays the icon provider; it is deliberately absent from the logo cascade. Docs: media-use gap/types/providers tables + example; the five workflow banners now cover logos (catalog claim kept for media, 'from their official sources' added for logos); product-launch story-design and motion-graphics logo-reveal point at the new type; catalog surfaces (CLAUDE.md / README / docs) updated in lockstep. Verified: 19 unit tests + coverage row green; live smoke across all four tiers (linkedin→svgl, nike→simple-icons, heygen→github.avatar, amazon→favicon) plus a fabricated brand exiting 1 on the default miss path. oxlint + oxfmt clean. * test(media-use): sanction the four logo providers in the registry allowlist svgl / simple-icons / github.avatar / favicon.ddg join the sanctioned list — the logo cascade added in the previous commit. Full lib suite 95/95 green. * test(media-use): gate the logo cascade behavior in CI + single-fetch favicon tier Review follow-ups (miga-heygen, jrusso1020 on #2061): - Eight mocked-network tests pin what the manual 54-brand stress test only asserted: descriptor shape, alias retry (svgl non-array payload → next query, simple-icons 404 → next slug), network-error → null fallthrough, the sub-500B placeholder rejection, github's no-guessing (zero fetches for unmapped entities), and the real cascade order landing tier by tier under a mocked network. - faviconSearch now hands its verified bytes over as a local file, so the freeze step copies instead of re-downloading — one round-trip, and the size check is authoritative over what gets frozen. - The header's hit counts are labeled as a stress-test snapshot, not a live invariant. Full lib suite 103/103; live smoke re-verified (amazon → favicon.ddg, frozen .ico).	2026-07-08 23:58:41 +08:00
Miguel Ángel	401dd1d27f	fix: media-use bug-bash fixes (codex gate, id race, provider/reuse/adopt guards) + CLI unknown-flag rejection (#2033) ... * fix(media-use): codex gate misfires as 'not logged in' when piped codexUnavailableReason() gated generation on parsing `codex login status` stdout, but that command prints 'Logged in using ChatGPT' to stderr and exits 0 — so the piped stdout media-use captures (execFileSync returns stdout only on success) was empty, and the gate falsely reported 'not logged in'. Every headless / CI / agent run was blocked from codex image gen even when fully authed. Gate on the durable credentials file ($CODEX_HOME/auth.json) instead of the TTY/stderr-only human text. Token validity is still proven by the exec, which fails cleanly on a stale login. The stdout `features list` capability check is unchanged. Verified: reproduced the false 'not logged in' block, then after the fix generated end-to-end via `resolve -t image --provider codex` (valid 1254x1254 PNG, source=generated, provider=codex.image_gen). * fix(media-use): bug-bash fixes — id race, provider/reuse/adopt guards From the bug-bash against main: - MU-23 (HIGH): concurrent resolves raced on nextId (read-max-then-append, non-atomic), so parallel agents got duplicate ids and clobbered each other's files. Add allocateId(): a coarse per-project lock (.media/.lock, 15s stale-steal) around id allocation that scans the manifest AND the type dir for reserved ids, then O_EXCL-creates a placeholder file so the slow download between allocate and append can't collide. 5 parallel resolves now yield 5 distinct ids + files. - X4: --reuse imported across a type mismatch (bgm asset under images/). Apply typesMatch on the --reuse path; reject mismatches (icon<->image still interchangeable). - X5: --provider silently overrode --local-only and made a network call. --local-only is now a hard guard: network providers are skipped even under a forced provider; the miss message explains the conflict. - BUG-2: --provider ignored the exact-cache floor and could hand back an asset from a different provider. A forced --provider now bypasses all reuse rungs (regenerate with THIS provider); the unforced floor is intact. - MU-26/X6: 0-byte assets accepted. --adopt skips 0-byte files (loud); ingest refuses a 0-byte local file (freezeUrl already rejects empty responses). - BUG-4: unknown/unavailable --provider now errors with the available list instead of a generic 'no provider could resolve' (typo != catalog miss). - BUG-5: --reuse "" gave the wrong 'type and intent required' error; it now routes to a clear empty-sha message. - BUG-3: voice duration leaked an unrounded float into index.md; round all durations to 0.1s centrally at record build (matches probe). - Nits: whitespace-only --intent is rejected; nudge grammar (exists/exist). Tests: allocateId reservation + registry local-only-wins added; full media-use suite green. All fixes verified e2e. * fix(cli): reject unknown flags instead of silently ignoring them citty is permissive: an unrecognized flag was dropped, not rejected — so `render . --out x` (the flag is --output/-o) silently ignored --out and rendered to the default renders/<name>.mp4 path. A mistyped flag read as a render/catalog miss. Add assertKnownFlags(): validate every dash-prefixed token against the command's declared args + aliases + the global set (help/version/json) before the command runs, in the shared trackCommandFailures run-wrapper so every leaf command is covered. Handles --flag=value, --no-<bool> negation, camelCase<->kebab arg names, and combined shorts; stops at --; positionals and flag values pass through. Verified: `render . --out x` -> 'Error: Unknown flag: --out'; --output/-o/ --json/--help still accepted. Unit tests added. * docs(skills): install with --full-depth so agents get current main The documented `npx skills add heygen-com/hyperframes` fetched the skills.sh registry blob, which lags GitHub main by hours — so users following the docs got a stale skill (e.g. media-use v1: no --candidates, voice stubbed). The CLI's own `hyperframes skills` command already forces a full clone via --full-depth to bypass this; the docs didn't pass it. Add --full-depth to every documented install command (README, CLAUDE.md, docs/guides/skills.mdx) with a one-line note on the lag. Addresses the user-facing half of the publish/registry lag (#2034). * chore(media-use): collapse resolve.mjs import to satisfy oxfmt --check * fix(cli): extract longFlagName to keep flag validator under complexity gate Also regenerate skills-manifest.json (resolve.mjs formatting change re-hashed the media-use skill). Fixes the Fallow audit + skills-manifest-in-sync CI gates.	2026-07-07 19:19:28 -04:00
WaterrrForever	306a291dea	fix(skills): audit descriptions — trim routing prose, fix stale facts, add missing triggers (#1990) ... * fix(skills): audit descriptions — trim routing prose, fix stale facts, add missing triggers Descriptions are the always-loaded routing tier; this audit rebuilds them on one principle: discriminate by input shape, not pipeline internals. - Trim creation-workflow descriptions to positive trigger + nearest-neighbor disambiguation + /hyperframes escape hatch; full routing prose already lives in each skill body's route-confirm block and the router - Codify the workflow-vs-domain split as ownership (owns the end-to-end deliverable vs capability layer pulled in mid-flight) in /hyperframes, and widen "make me a video" framing to deck / composition port - Fix stale facts: embedded-captions identity count (desc 32, body 17 → actual 36 = 10 classic + 26 themed), six→ten visual languages, retired RVM/Standard wording in router details, figma shader transport (MCP → MCP source / native export), keyframes "cursor demos" (no backing content), hyperframes-media scripts/audio.mjs leak - Register missing capabilities: motion-graphics maps category (was in categories/ but absent from its own table, description, and router), asset-fusion + news triggers, slideshow page-to-deck + presenter mode, general-video editing, talking-head-recut 16:9/9:16/4:5 canvas, cli feedback + lambda sites, product demos, mood-brief BGM generation - website-to-video: relabel promo-shaped video types to keep the promo boundary with /product-launch-video; drop headless-Chrome wording - music-to-video: lyric timing via /hyperframes-media transcription or user-supplied lyrics, placed on the beat grid - Sync catalogs in lockstep (CLAUDE.md, AGENTS.md, README, docs/guides/skills.mdx, CLI project templates): add music-to-video + slideshow entries, complete the domain-skill lists, and extend the catalog-maintenance rule to cover AGENTS.md and the templates Validated with a 35-case description-only routing eval: 35/35 both before and after the rewrite (including new maps / asset-fusion / news probes). * fix(skills): post-media-v2 consistency — stale media ref, router figma wording, catalog rows - music-to-video: lyric transcription now routes to /media-use (the retired /hyperframes-media was still referenced) - router capability map: figma row gains the shaders fact (MCP source / native export), matching the SKILL.md source of truth - media-use catalog rows (CLAUDE.md, README, docs/guides/skills.mdx): add image models + captioning, aligning with the v2 description - catalog rule #1: root AGENTS.md carries the workflow list only (it has no domain-skill section) — rule wording now says so	2026-07-07 14:28:46 +08:00
Miguel Ángel	68a8547f47	fix: align README skills table padding so oxfmt --check passes (#2014) ... The media-use v2 row is the widest cell in the domain-skills table; oxfmt re-pads every other row's trailing pipe to match. The merge added the row without re-aligning, so oxfmt --check flagged README on CI (linux). Content is unchanged; only trailing whitespace in 10 table rows.	2026-07-07 00:16:50 -04:00
Miguel Angel Simon Sierra	5fe957363d	feat(media-use): v2 media OS core (resolve cascade, providers, local generation, telemetry) + retire hyperframes-media	2026-07-06 23:41:05 -04:00
Vance IngallsandClaude Fable 5	ccc1308839	docs(figma): storyboard blurb reworded + frames-are-app-states escalation (#2004) ... Field feedback from a raw-API agent build (join-the-world-flow): the catalog blurb's word 'animatics' encodes the PNG-slideshow architecture the skill body explicitly forbids — an agent routing by the blurb concludes the shipped behavior is frames-as-pictures. Reworded to 'reconstructed motion (frames read as states, not slides)' across all catalog surfaces (skill frontmatter, CLAUDE.md, README, skills.mdx, hyperframes router, figma guide). Also codifies the stronger doctrine that build demonstrated as storyboard rule 10: when every frame is the same product UI in successive states, rebuild the app as live DOM (Phase-3 for stateful parts, real pixels for static chrome — code what changes state, freeze what doesn't) and perform frame deltas as interactions instead of tweens. Spec §5.1 records the escalation + field origin. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>	2026-07-06 16:55:47 -07:00
Miguel Ángel	c2862eae1b	docs: update README.md	2026-07-05 20:57:24 -04:00
Vance IngallsandClaude Fable 5	566d49382c	feat(skills): reroute /figma by capability - REST/CLI for phases 1-3, MCP for 4-5 (M4) (#1873) ... * feat(skills): reroute /figma by capability - REST/CLI for phases 1-3, MCP for 4-5 (M4) Rewrites the skill from MCP-first to the spec 2 split: asset/tokens/ component route through the hyperframes figma CLI (FIGMA_TOKEN), motion/ shaders stay agent-driven over MCP (no REST equivalent). Adds two- credential guidance, Starter rate-limit tactics (recursive:true, raw- response cache, opt-in screenshots), the 7.1 binding flow (tokens before components, one ask per unknown library, never value matching), and the shader manual-export default. Catalog blurbs updated in lockstep. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(cli): register figma component subcommand Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(skills): add storyboard-to-animatic guidance to /figma Field-tested against a real 26-scene storyboard section: the parsing grammar (frame-sized nodes incl. loose rectangles = scenes, x-order = time order, TEXT below the strip = director notes paired by x-overlap), batched still export (chunk ~4 ids per render call - big frames timeout past ~12), a note-verb -> transition vocabulary (EXPLOSION/SLIDE/MORPH/ CYCLE), and the stills-vs-component routing rule for within-scene motion notes. Catalog blurbs updated in lockstep. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(skills): storyboard frames are keyframes, not slides Field-tested against a second real storyboard section: frames sharing an element (matched by name, else geometry similarity) define that element's states through time - tween the element between states, crossfade only when pixels genuinely differ, enter/exit unmatched children, tween frame backgrounds as a color track. Stills demoted to fallback for frames that don't decompose. Validated live: a 4-frame logo-rise reconstructed as one element with four keyframes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(figma): self-explanatory first-run experience + mintlify guide - NO_TOKEN/BAD_TOKEN errors now carry the full one-time setup (mint URL, read-only scope checklist, persist hint) instead of a bare pointer - figma subcommands print clean guidance on typed client errors, not a stack trace (shared withFigmaErrors boundary) - CLI help gains component subcommand, FIRST-TIME SETUP and WHAT TO EXPECT blocks - /figma skill: preflight the token before the first CLI call and walk the user through setup up front; narrate landed-artifact + next action at every step - new docs/guides/figma.mdx (setup, per-phase walkthroughs, provenance, troubleshooting table) wired into docs.json nav Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(figma): review fixes — missing withFigmaErrors imports, 401/403 semantics, docs accuracy - tokens.ts/component.ts called withFigmaErrors without importing it (tsup doesn't typecheck, so every invocation shipped as an immediate ReferenceError); imports added, tsc --noEmit now clean - error boundary widened to all Errors so bad-ref/bad-format input errors print their message instead of a stack trace - 401 no longer claims 'missing scopes' (figma signals that as 403); new FORBIDDEN code maps non-variables 403 to scope/access guidance - docs: asset/component refs require a node id (bare fileKey is tokens-only), example snippet matches real output, FORBIDDEN row - skill: preflight counts a project-.env token as configured (CLI auto-loads it); BAD_TOKEN/FORBIDDEN guidance split Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(cli): present figma errors via standard errorBox Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>	2026-07-03 19:13:08 -07:00
Vance IngallsandClaude Fable 5	e92700acde	feat(core): figma motion → GSAP translator + /figma skill v1 (#1869) ... * feat(core): add figma motion easing mapping * feat(core): translate figma motion doc to gsap timeline spec * feat(core): emit paused GSAP timeline script from figma motion spec * fix(core): restore type exports dropped from figma barrel in Task 8 * feat(skills): add /figma import skill + catalog wiring Add the agent-facing /figma skill (asset + Figma Motion import via the Figma MCP connector, built on @hyperframes/core/figma) and wire it into the skill catalog across CLAUDE.md, README.md, docs/guides/skills.mdx, and the hyperframes router's capability map. Bumps the skill count from 19 to 20 in CLAUDE.md and README.md. * fix(core): use replaceAll for figma node-id dash-to-colon conversion * style: format skills catalog tables oxfmt-align the README and router SKILL.md tables after the /figma + /hyperframes-keyframes merge left uneven column padding. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(cli): add missing cache fields to telemetry test fixture ExtractionPhaseBreakdown gained cachePublishFailures/cacheGcEvictions/ cacheGcBytesFreed/cacheAgedPartialsCleared; the studioRenderTelemetry test fixture was never updated, breaking Typecheck on main and every PR based on it. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>	2026-07-03 15:45:07 -07:00
Miguel Ángel	a908af11a8	feat(cli): keyframes command (surface GSAP/CSS/Anime keyframes + 3D onion-skin --shot) (#1603) ... Renames the motion-surfacing tool from `hyperframes keyframes` to `hyperframes motion`, renames the implementation from keyframes*.ts to motion*.ts (keeping the keyframe data model name where still accurate), and renames the shipped skill from hyperframes-keyframes to hyperframes-motion. Expands the skill from a command reference into a full motion-design workflow: reading motion, 3D angle verification, layered GSAP motion, one-shot reference reproduction, diagnostic checks, and eval-derived craft guidance.	2026-07-01 19:51:55 -07:00
Miguel Ángel	38c6cd1113	docs: trim README motion hero (#1780)	2026-06-29 10:20:04 -07:00
James Russo	f7bc0384f0	docs: add 19-skills catalog to README, CLAUDE.md, and Mintlify docs (#1722) ... * docs: list all 19 skills in README + add CLAUDE.md maintenance reminder Agents discover skills via the README, so silently-out-of-date entries kill discovery. This change: - Adds a `## Skills` section to the README listing all 19 skills, grouped Router / Creation workflows / Domain skills, with a one-line "use when" blurb for each (sourced from each skill's SKILL.md frontmatter `description:`). - Updates the existing CLAUDE.md `## Skills` section to cover all 19 skills (was missing the domain skills, `/media-use`, `/slideshow`, and `/music-to-video`), mirroring the README's Router / Creation / Domain grouping. - Adds a "Skill catalog maintenance" section to CLAUDE.md so future skill additions / renames update both surfaces and the `/hyperframes` router skill in lockstep. Docs-only — no source or test changes. — Jerrai (https://claude.com/claude-code) * docs(mintlify): add skills catalog page + extend maintenance reminder Per follow-up on HF#1722: the Mintlify docs at hyperframes.heygen.com also need the skills catalog so agent discoverability is consistent across README and docs site. - New: docs/guides/skills.mdx (3-group catalog — router / creation workflows / domain skills — mirrors README structure, sourced from the same SKILL.md frontmatter) - Update: docs/quickstart.mdx — completes the workflow-skills list (was missing /music-to-video, /slideshow, /general-video) and cross-links the new page - Update: docs/introduction.mdx — adds a skills-catalog card to the hero CardGroup and the Next Steps section - Update: docs/docs.json — adds /guides/skills to the Guides nav - Update: CLAUDE.md "Skill catalog maintenance" — adds docs/guides/skills.mdx as the third sync target alongside README and skills/hyperframes/SKILL.md, and notes the count drift surface (README + CLAUDE.md mention "19 AI agent skills" in their intros; the new docs page deliberately omits a count to avoid drift) Docs-only — no source, packages, or test changes. — Jerrai (https://claude.com/claude-code) * docs(readme): oxfmt table column-alignment fix Pure whitespace — oxfmt's table-column alignment caught README.md after the previous commit. No content change. — Jerrai (https://claude.com/claude-code) * docs(skills): reconcile install-command contract across README/CLAUDE/Mintlify Per Magi's review on HF#1722: the new README/CLAUDE/skills.mdx pages described bare `npx skills add heygen-com/hyperframes` as installing all 19 skills, while existing quickstart/prompting docs said the bare command opens a picker and `--all` installs everything. Verified actual CLI behavior with `npx skills add --help` and a clean-dir run: bare command opens an interactive picker for human users (the CLI help documents `--all` as "Shorthand for --skill '*' --agent '*' -y" — the picker-skipping form). Inside an agent the bare command auto-installs all non-interactively, but that's an agent-detection UX shortcut, not the public contract — documenting the picker is correct for human readers. All touched docs now use the consistent contract: - `npx skills add heygen-com/hyperframes` -> interactive picker - `npx skills add heygen-com/hyperframes --all` -> install all 19 (skips picker) - `npx skills add heygen-com/hyperframes --skill <name>` -> install just one Files updated: README.md, CLAUDE.md, docs/guides/skills.mdx. Existing docs/quickstart.mdx and docs/guides/prompting.mdx already used this contract and are unchanged. — Jerrai (https://claude.com/claude-code)	2026-06-25 12:12:44 -07:00
3 people	8fcbb63a37	docs(readme): swap hero media to hyperframes-logo-motion (#1315) ... * docs(readme): swap hero media to hyperframes-logo-motion Replaces the prior hfgif-1280.webp hero with a new logo-motion clip Bin trimmed for the launch. Converted the source MP4 to animated webp (the existing hero's format) so it auto-plays in the GitHub README the same way the old one did - MP4 sources don't render inline or autoplay in <img> tags. - New asset: static.heygen.ai/hyperframes-oss/docs/images/ hyperframes-logo-motion-1280.webp (1280x720, 85 frames, 199KB) - ffmpeg conversion: scale=1280, libwebp_anim, q=80, loop=0 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix(studio): format 5 hooks files (oxfmt) * style: remove unused imports in studio hooks (pre-existing lint failures) CI Lint on main was already failing with 5 unused-import errors in packages/studio/src/hooks/. Removed the unused symbols to unblock the README hero PR's CI: - gsapRuntimeBridge.ts: resolveTweenStart, resolveTweenDuration - useGsapScriptCommits.ts: usePlayerStore - useTimelineEditing.ts: PatchTarget (type-only) - gsapDragCommit.ts: readGsapProperty Bundled into the README PR per James's request to fix CI in-place. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * test(studio): add childRects: [] to DomEditOverlay test mock useDomEditOverlayRects' return type added a childRects: OverlayRect[] field; the DomEditOverlay test's mock didn't get updated and was returning an object without it, so DomEditOverlay.tsx's 'childRects.length > 0' check threw TypeError on undefined. One-line mock-vs-hook contract realignment. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * test(studio): drive player-store currentTime in selection-hydration test (#1311 follow-up) The 'hydrates seek first, preserves the initial url state, then restores selection' test was failing because PR #1311 (keyframes feat) changed useStudioUrlState to read currentTime from the player store via usePlayerStore((s) => s.currentTime), removing it from the hook's prop shape. The test was still trying to drive currentTime via the harness prop, which is now a no-op — so the selection-hydration useEffect's time-stability guard Math.abs(currentTime - stableTimeRef.current!) > 0.05 never passed (store currentTime stayed at 0 while stableTimeRef caught the 4.2 seek target). buildDomSelectionFromTarget was never reached, applyDomSelection was never called, and the assertion got 0 calls. Fix: setState the store's currentTime to 4.2 ahead of the rerender so the hook's selector picks it up and the time-stability guard passes. Harness prop kept as-is — it's a no-op but doesn't hurt. Pre-existing failure on main HEAD 81416ab3; surfaced as CI gate on the unrelated docs/readme-hero-motion-update PR. * test(studio): stub getBoundingClientRect + flush RAF in DomEditOverlay test The 'renders selected bounds right after clicking a movable selection' test asserts the selection box appears after pointerdown, but happy-dom returns 0 for newly-created elements' getBoundingClientRect. The overlay's compRect updates via a RAF loop that early-returns when iframe width is 0; the keyframes PR a468550f added a compRect.width > 0 guard to the selection-box render path, so compRect=0 silently gates the box off and the assertion fails. Stub Element.prototype.getBoundingClientRect to return 800x450 for the test, and flush two RAFs after render so the compRect state update lands before the pointerdown assertion. Restore the prototype at test end. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com> Co-authored-by: Miguel Sierra <miguel.sierra@heygen.com>	2026-06-09 23:39:22 -07:00
Vance Ingalls	1a617d30ff	docs(readme): add Frame.md design template gallery (#1182) ... ## What Adds a **Frame.md** section to the main README — `frame.md` is the design-system-for-video translation layer (a `DESIGN.md` superset rewritten for the frame). Includes a 10-template gallery. Each thumbnail links to its design page on `hyperframes.dev/design/<slug>`. ## Templates Biennale Yellow · BlockFrame · Blue Professional · Bold Poster · Broadside · Capsule · Cartesian · Cobalt Grid · Coral · Creative Mode ## Image hosting Preview PNGs uploaded to `static.heygen.ai/hyperframes-oss/docs/images/design-templates/<slug>.png` (heygen-public bucket), matching the existing demo-gif convention. All verified `200 image/png`. Design pages all verified `200`. <img width="652" height="996" alt="image" src="https://github.com/user-attachments/assets/832fd87d-0421-4906-9f46-c5c9bf5b48e9" /> 🤖 Generated with [Claude Code](https://claude.com/claude-code)	2026-06-03 13:22:53 -07:00
James Russo	8106556e00	docs: add HyperFrames showcase (#1108)	2026-05-28 11:14:16 -07:00
James	23717a9911	docs(readme): clarify HyperFrames positioning	2026-05-27 16:29:34 -04:00
Kiyeon Jeon	711c4ff9f9	docs: update rendering comparison and license wording	2026-05-23 17:20:18 +09:00
JamesandClaude Opus 4.7	50c8a66114	docs: switch README hero to animated WebP for autoplay + higher quality ... GitHub strips autoplay/loop from <video> tags in markdown, so the MP4 required a click to play. WebP autoplays via <img> while preserving full HD source quality (1280x720 vs the previous GIF's 400x225). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-08 12:17:37 -07:00
JamesandClaude Opus 4.7	67901349eb	docs: replace README demo GIF with higher-quality MP4 ... Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-08 12:01:49 -07:00
James	051e985868	refactor(skills): split asset preprocessing out of hyperframes-cli ... Move tts/transcribe/remove-background guidance into a new hyperframes-media sibling skill so the CLI skill stays focused on the dev loop (init/lint/inspect/preview/render/doctor). Two motivations: 1. Description bloat. The CLI skill listed every subcommand as a trigger keyword, which made agents auto-load it for any mention of audio, transcription, or backgrounds — even when the task was just rendering a composition. 2. Body bloat. Voice tables, the .en-translates-non-English whisper rule, and codec selection guidance all loaded on every CLI invocation. With three preprocessing commands now in the CLI (tts, transcribe, remove-background), this is only going to grow. The split keeps a single sibling (hyperframes-media), not three: the commands share a workflow (preprocess asset → drop into composition) and the same first-run-downloads-a-model pattern, so they belong together. CLI skill now references hyperframes-media from a one-paragraph "Asset Preprocessing" stub. Doc references updated in README.md, CLAUDE.md, docs/quickstart.mdx, and docs/guides/prompting.mdx.	2026-05-04 21:59:35 +00:00
Miguel Ángel	4760afd3fc	fix: readme (#599)	2026-05-02 07:08:08 +02:00
Tom Huangandpftom	351beb9fca	docs: add Open Design guide alongside Claude Design (#585) ... Add a parallel handoff path for users of [Open Design](https://github.com/nexu-io/open-design), the Apache-2.0, local-first, BYOK alternative to Claude Design that drives whichever coding-agent CLI the user already has on their PATH (Claude Code, Codex, Cursor, Gemini, OpenCode, Qwen, Copilot, Hermes, Kimi, Pi). Mirrors the existing Claude Design integration: - README: a paragraph next to the Claude Design one, pointing at the new guide and explaining the drop-into-skills/SKILL.md install path - docs/guides/open-design.mdx: Mintlify page parallel to claude-design.mdx, with Steps, comparison table, prompts, limitations, handoff - docs/guides/open-design-hyperframes.md: SKILL.md-shaped instruction file users drop into skills/hyperframes-handoff/SKILL.md (Open Design auto-discovers it on next request) or attach to chat as a one-shot - docs/docs.json: nav entry for the new page The instruction file deliberately defers to claude-design-hyperframes.md as the canonical reference for skeleton catalogs, shader patterns, HDR, and audio-reactive animation — it stays focused on what Open Design's prompt stack needs at emission time (active-DESIGN.md binding, 5-dim self-critique gate, structural rules) so the two guides don't drift. Open Design already ships a motion-frames skill that says "hand-off ready for HyperFrames" — this PR closes the loop on the HyperFrames side so the route is discoverable from the HyperFrames docs. Co-authored-by: pftom <huan1043269996@gmail.com>	2026-05-01 13:48:11 +02:00
Miguel Ángel	68bd52ac6d	feat: add init tailwind flag (#577) ... ## Problem Users who want Tailwind utilities in a plain HyperFrames composition currently have to know which Tailwind browser script to add and where to place it. The first pass added `--tailwind`, but review caught three production-facing gaps: the CDN version was major-only, the insertion helper could silently no-op on compact HTML, and the render pipeline did not explicitly wait for Tailwind's async browser compilation before capturing frame 0. There is also a version-specific agent risk: HyperFrames `init --tailwind` uses Tailwind v4.2 through `@tailwindcss/browser@4.2.4`, while `packages/studio` still uses Tailwind v3. Without a dedicated skill, agents can easily mix v3 `tailwind.config.js` / `@tailwind` patterns into v4 browser-runtime composition HTML. ## What this fixes - Adds `hyperframes init --tailwind`. - Pins the Tailwind browser runtime to `@tailwindcss/browser@4.2.4/dist/index.global.js` with SRI and `crossorigin="anonymous"`. - Injects a `window.__tailwindReady` promise next to the browser runtime. - Makes frame capture wait for `window.__tailwindReady` in both screenshot and BeginFrame capture modes before capturing frame 0. - Inserts Tailwind support before `</head>` case-insensitively, including single-line/minified heads, and falls back to prepending when there is no head tag. - Skips recursive Tailwind injection under `.git`, `dist`, and `node_modules`. - Tracks whether init used Tailwind in the existing `init_template` telemetry event. - Adds a first-party `/tailwind` skill for Tailwind v4.2 browser-runtime HyperFrames composition work. - Updates README, docs, generated project agent files, CLI skill guidance, and plugin metadata so the Tailwind skill is discoverable. - Documents the browser-runtime tradeoff and production/offline guidance. ## Root cause `scaffoldProject()` copied the selected example and patched media placeholders, then immediately wrote project metadata and `package.json`. There was no optional post-copy step for framework-specific HTML support. The initial Tailwind post-copy step also treated the browser runtime like a static script, but Tailwind compiles utilities asynchronously after scanning the DOM, so the capture engine needed an explicit readiness contract. On the agent side, the repo exposed HyperFrames, CLI, GSAP, registry, and runtime adapter skills, but had no Tailwind-specific instruction to separate the v4 browser-runtime composition path from Studio's v3 internal setup. ## Verification ### Local checks - `bunx vitest run packages/cli/src/commands/init.test.ts` - `bun run --filter @hyperframes/cli test src/commands/init.test.ts` - `bun run --filter @hyperframes/cli typecheck` - `bun run --filter @hyperframes/engine typecheck` - `bun run lint:skills` - `bun run lint` - `npx skills add . --list` showed 12 local skills, including `tailwind`. - `bunx oxfmt --check packages/cli/src/commands/init.ts packages/cli/src/commands/init.test.ts packages/cli/src/telemetry/events.ts packages/engine/src/services/frameCapture.ts docs/packages/cli.mdx` - `bunx oxfmt --check README.md docs/quickstart.mdx docs/packages/cli.mdx CLAUDE.md packages/cli/src/templates/_shared/CLAUDE.md packages/cli/src/templates/_shared/AGENTS.md skills/hyperframes-cli/SKILL.md skills/tailwind/SKILL.md .codex-plugin/plugin.json .cursor-plugin/plugin.json` - `bunx oxlint packages/cli/src/commands/init.ts packages/cli/src/commands/init.test.ts packages/cli/src/telemetry/events.ts packages/engine/src/services/frameCapture.ts` - `git diff --check` - Lefthook pre-commit: lint/format/typecheck for code commit; format for docs/skill commit - Lefthook commit-msg: commitlint Generated-project render proof at `/tmp/hf-tailwind-render-proof`: - `bun packages/cli/src/cli.ts init /tmp/hf-tailwind-render-proof --example blank --tailwind --non-interactive --skip-skills` - Added a temporary Tailwind-only card using `flex`, `h-full`, `w-full`, `items-center`, `justify-center`, `bg-slate-950`, `rounded-3xl`, `bg-white`, `px-20`, `py-12`, `text-8xl`, `font-black`, `text-black`, and `shadow-2xl`. - `bun packages/cli/src/cli.ts lint /tmp/hf-tailwind-render-proof` → 0 errors, 0 warnings. - `bun packages/cli/src/cli.ts validate /tmp/hf-tailwind-render-proof` → 0 errors, 0 regular warnings; the temp proof still reports validator contrast warnings even though the rendered/browser pixels show black text on white background. - `bun packages/cli/src/cli.ts render /tmp/hf-tailwind-render-proof --workers 1 --fps 24 --quality draft --output /tmp/hf-tailwind-render-proof-artifacts/output.mp4` - Render compiler inlined both GSAP and `https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4.2.4/dist/index.global.js`. - `ffprobe -v error -select_streams v:0 -show_entries stream=codec_name,width,height,r_frame_rate,duration -of default=noprint_wrappers=1 /tmp/hf-tailwind-render-proof-artifacts/output.mp4` → H.264, 1920x1080, 24fps, 10s. - Extracted frame-0 proof: `/tmp/hf-tailwind-render-proof-artifacts/frame-000.png`. ### Browser verification - Started Studio preview for `/tmp/hf-tailwind-render-proof`. - Used `agent-browser` to open `http://localhost:5194`. - Verified the Tailwind-styled composition rendered in Studio preview. - Captured screenshot: `/tmp/hf-tailwind-render-proof-artifacts/browser/tailwind-preview.png`. - Captured agent-browser-driven recording: `/tmp/hf-tailwind-render-proof-artifacts/browser/tailwind-preview.webm`. - Served the PR worktree locally and used `agent-browser` to open the new Tailwind skill proof page. - Verified the browser-visible skill content includes `@tailwindcss/browser@4.2.4`. - Captured screenshot: `/Users/miguel07code/.codex/worktrees/pr-577-tailwind-comments/tmp/agent-browser-proof/tailwind-skill.png`. - Captured agent-browser-driven recording: `/Users/miguel07code/.codex/worktrees/pr-577-tailwind-comments/tmp/agent-browser-proof/tailwind-skill.webm`. ## Notes - This still intentionally uses Tailwind's browser runtime rather than adding a generated Tailwind build pipeline. That keeps `hyperframes init --tailwind` small and compatible with the current no-install generated project workflow. - The `/tailwind` skill cites official Tailwind v4 docs plus community skill references, but its instructions are HyperFrames-specific and tuned for the pinned v4.2 browser runtime. - Browser proof artifacts are local-only under `/tmp/hf-tailwind-render-proof-artifacts/` and `tmp/agent-browser-proof/` and intentionally not committed.	2026-05-01 00:07:00 +02:00
Miguel Ángel	8662598a3a	docs: add runtime adapter skills (#572) ... * docs: add runtime adapter skills * docs: address adapter skill review comments	2026-04-30 16:08:43 +02:00
JamesandClaude Opus 4.7	be1fcfc4e6	docs(readme): add Discord community badge ... Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-04-28 23:59:24 +00:00
James	7ed3d0485a	feat(skills): scaffold remotion-to-hyperframes skill (1/7) ... Adds the directory + SKILL.md frontmatter for a new skill that translates Remotion (React) compositions to HyperFrames (HTML+GSAP). This is the foundation PR; subsequent PRs in the stack add the eval harness, test corpus, translation references, and finally the SKILL.md body. The frontmatter description enumerates trigger phrases and explicit out-of-scope cases (useState/useEffect, async metadata, @remotion/lambda) so the skill bows out cleanly when a Remotion composition isn't a clean translation target — those should use the runtime interop pattern from PR #214 instead. Validated with skill-creator's package_skill.py.	2026-04-27 05:16:02 +00:00
Ular Kimsanov	9322ff9c74	refactor: move Claude Design instructions from skills/ to docs/ (#495)	2026-04-25 22:50:16 +02:00
ukimsanovandClaude Opus 4.6	c6da00d9c8	docs: fix SKILL.md download UX across all references ... Raw GitHub URLs serve as text/plain — clicking opens a text tab instead of downloading. Updated all 5 references across 4 files: - claude-design.mdx (2 refs): "right-click → Save Link As" - prompting.mdx (1 ref): "right-click → Save Link As" - README.md (1 ref): "click download button on GitHub" - quickstart.mdx (1 ref): "click download button on GitHub" Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-23 21:06:27 -04:00
ukimsanovandClaude Opus 4.6	95ca0200d4	docs: update all Claude Design references for template-first skill ... Update docs, quickstart, prompting guide, and README to reflect: - Template-first approach (attach file, not paste URL) - Claude Design produces drafts, refine in any AI coding agent - Known limitations (vertical shaders, seeking, no linting) - Practical example prompts (feature announcement, founder pitch) - Removed outdated references (invisible bridges, fetch-the-skills-tree) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-23 20:52:40 -04:00
Miguel Ángel	154511247a	feat: add Claude Code plugin manifest (#462) ... * feat(claude-code-plugin): add Claude Code plugin manifest Adds .claude-plugin/plugin.json so the repo can be loaded as a Claude Code plugin. Reuses the existing skills/ directory — all 5 skills (hyperframes, gsap, hyperframes-cli, hyperframes-registry, website-to-hyperframes) are auto-discovered under the hyperframes: namespace. * docs(readme): document Claude Code plugin usage * chore(claude-code-plugin): add submission branding assets * docs(claude-code-plugin): address review notes	2026-04-23 23:07:57 +02:00
Miguel Ángel	25d7a54330	docs: add Claude Design HyperFrames entry point (#353) ... ## Summary - add a GitHub-hosted `claude-design-hyperframes` skill entry point that tells Claude Design to fetch the upstream HyperFrames skills tree - add a dedicated Claude Design docs guide and link it from quickstart, prompting, and the README - fix `@hyperframes/player` CDN docs to show a working ESM include and the explicit global-build fallback ## Verification - `bunx oxfmt --check README.md docs/docs.json docs/guides/prompting.mdx docs/packages/player.mdx docs/quickstart.mdx packages/player/README.md docs/guides/claude-design.mdx skills/claude-design-hyperframes/SKILL.md` - `bun run lint:skills` - `bunx mintlify broken-links` - browser-engine screenshots captured with Playwright CLI for the changed docs/source surfaces: - `/tmp/hyperframes-pr-artifacts/claude-design-guide-source.png` - `/tmp/hyperframes-pr-artifacts/player-docs-source.png` ## Notes - `mintlify dev`, `mintlify validate`, and `mintlify export` stalled in this environment during preview/bootstrap, so I used the broken-links check plus screenshot-based browser fallback instead of claiming a full rendered-site pass. - The GitHub entry-point setup reflects current Claude Design behavior discussed in the task: point Claude Design at the repo-hosted skill URL rather than a ZIP upload flow.	2026-04-23 22:55:00 +02:00
James Russo	d125d65164	feat(plugins): add Cursor plugin manifest + refresh marketplace branding (#461) ... Adds .cursor-plugin/plugin.json at the repo root alongside the existing .codex-plugin/, so this repo is the single source of truth for the Codex plugin AND the new Cursor Marketplace submission. Refreshes the shared assets/logo.png + assets/icon.png to a 1024x1024 / 512x512 symbol-only mark rasterized from docs/favicon.svg (white background), and renames the marketplace display title from "HyperFrames" to "HyperFrames by HeyGen" in both Codex and Cursor manifests. No skill content changes; purely marketplace-visible branding and the new Cursor manifest file.	2026-04-23 16:35:56 -04:00
James Russo	6accf099ac	docs(readme): note git-lfs requirement for full clones (#423) ... * docs(readme): note git-lfs requirement for full clones Repo uses Git LFS for regression-test baselines (~240 MB of .mp4 files under packages/producer/tests/**/output.mp4). Users cloning without git-lfs installed hit a cryptic 'git-lfs: command not found' error, as reported in #407. Document the requirement with install instructions and the GIT_LFS_SKIP_SMUDGE=1 escape hatch. * docs(readme): add Windows install instructions for git-lfs Per review from @miguel-heygen. * chore(ci): fix oxfmt formatting on renovate.json Drive-by to unblock CI. Landed unformatted in #422 because Renovate's config-migration PR bypasses the lefthook pre-commit hook, so every subsequent PR's `bun run format:check` (which scans the whole repo) was failing on this file.	2026-04-22 14:33:02 -07:00
James Russo	4ce1792601	feat(codex-plugin): add OpenAI Codex plugin at repo root (#387)	2026-04-21 15:33:32 -07:00
James Russo	733d454d11	docs: add Hyperframes vs Remotion comparison (#355) ... Adds honest Hyperframes vs Remotion comparison: README section with paragraph + table + open-source-vs-source-available callout, plus a full guide at docs/guides/hyperframes-vs-remotion.mdx walking through the core React-vs-HTML decision, practical differences (including a GSAP side-by-side), and licensing. Closes #318	2026-04-20 15:21:03 -07:00
James Russo	7b0c7e73b2	refactor: frame reorder buffer + port probe cleanup; add CREDITS.md and missing skill (#341) ... * refactor(engine): restructure frame reorder buffer with Map-keyed storage Rewrites createFrameReorderBuffer to use a Map<number, Array<() => void>> keyed by frame index instead of a flat Array<{frame, resolve}> scanned on every advance. O(1) lookups in enqueue/flush, fast-paths for the matching- cursor and overshoot cases, and a small fix: waitForAllDone now coexists with the writer still waiting on the final frame instead of colliding on the same waiter slot. Also adds 5 unit tests (there were none before) covering the fast-path, out-of-order gating, multi-waiter-per-frame semantics, waitForAllDone normal path, and the overshoot case. Comment tweaks on buildChromeArgs — the flag profile is the standard headless-for-capture set (Puppeteer / Playwright / Chrome headless-shell all converge on similar flags); rephrased for clarity. * refactor(cli): simplify port availability probe with async/await Rewrites isPortAvailableOnHost from a single new-Promise callback into an async/await form with an intermediate `bindError: ErrnoException | null` variable. Makes the bind-then-release flow explicit as two sequential awaits, and broadens the non-EADDRINUSE errno commentary (EADDRNOTAVAIL for disabled IPv6, EACCES for privileged ports, EAFNOSUPPORT for missing address families — all treated as "this host doesn't apply", not "port occupied"). No behavior change to existing callers; all four portUtils tests still pass. * docs: add CREDITS.md and surface website-to-hyperframes skill - New CREDITS.md acknowledging prior art in the browser-based video rendering space (Remotion) and the ecosystem HyperFrames builds on (Puppeteer, FFmpeg, GSAP, Hono). Standard OSS practice. - Adds the `website-to-hyperframes` skill to the skills tables in README.md, docs/guides/prompting.mdx, and the project template at packages/cli/src/templates/_shared/CLAUDE.md. The skill ships in skills/ but was missing from every table. - Adds `/hyperframes-registry` to the prose mention in the repo CLAUDE.md.	2026-04-19 16:33:42 -07:00
James RussoandClaude Opus 4.7	4ae5c0340f	chore(docs): migrate docs/images/ media to static.heygen.ai CDN (#301) ... Move all preview mp4/png/gif assets under docs/images/ out of the repo and serve them from https://static.heygen.ai/hyperframes-oss/docs/images/ (backed by s3://heygen-public/hyperframes-oss/docs/images/, CloudFront). Drops ~49MB from the working tree and, more importantly, ~49MB from every future Mintlify build checkout. Combined with the (already-LFS-tracked) producer snapshots, the remaining bloat in 'npx skills add heygen-com/ hyperframes' (see #300) is LFS smudge during clone — separate fix needed in the skills CLI to pass GIT_LFS_SKIP_SMUDGE=1. Changes: - Delete docs/images/** (103 files, ~49MB). Files are uploaded to S3 already. - Rewrite /images/* references in 44 MDX files, TemplateCard.jsx, and catalog-index.json to absolute CDN URLs. - Update README.md img src to CDN URL (renders correctly on GitHub). - Add docs/images/ to .gitignore so regenerated previews aren't committed. - Add scripts/upload-docs-images.sh to sync docs/images/ → S3 after running the preview generators. - Wire up bun run upload:docs-images and bun run generate:catalog-previews scripts in package.json. - Update generator script docstrings to point at the upload step. External contributors can still regenerate previews locally (mintlify dev reads the CDN URLs, so broken previews appear only for newly added items pending a maintainer upload). Maintainers run: bun run generate:catalog-previews --only <name> bun run upload:docs-images Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-04-16 23:13:43 -07:00