1243 Commits

Author	SHA1	Message	Date
Miguel Ángel	10e8447ac0	chore: release v0.8.38 (#3929)	2026-09-13 22:02:19 -04:00
Miguel Ángel	95bea1631f	refactor(skills): keep hyperframes-core as the HTML contract (#3928) ... * refactor(skills): keep hyperframes-core as the HTML contract Move brief, storyboard, review, production, dispatch, and frame-worker docs to hyperframes. Slim remaining core references. * fix(skills): restore camera recipes and root sizing Restore Zoom, Ken Burns, crop, and clip-path recipes. #root is 100 percent. * fix(skills): stamp size on the composition root Runtime sizes the composition root, not html/body. Overlap pin requires is valid.	2026-09-13 21:20:58 -04:00
Miguel Angel Simon Sierra	7a5d2bf769	chore: release v0.8.37	2026-09-13 12:51:02 -04:00
Miguel Ángel	f86aae655a	chore: release v0.8.36 (#3911)	2026-09-12 13:03:01 -04:00
Miguel Ángel	4c6fa9a790	fix(studio): the preview stays paused, survives typing, and opens without a re-encode (#3910) ... * chore(studio): remove the write-only self-write timestamp ref `domEditSaveTimestampRef` was assigned at 26 sites across 54 files and read nowhere. It used to feed a 2 s "suppress the watcher reload after our own write" window; that mechanism was replaced by content-hash identity in sdkSelfWriteRegistry, whose header still says why (a clock cannot tell an SDK self-write echo from an undo landing in the same window). The reader went with that change, the writers did not, and three comments kept describing the timestamp as protection that no longer existed. Pure deletion: the ref, every prop and parameter that threaded it, every assignment, the five comments citing it, and the orphaned test helpers. No behaviour change; the studio suite, typecheck, lint and format are green. Not removed: the __hfSuppressSceneMutations wrapper in gsapSoftReload.ts. It looked undefined from inside the studio package, but shader-transitions installs it on the preview window (hyper-shader.ts) so soft reloads do not invalidate cached transitions. It is live. * docs(studio): plan for loading the preview during the shell's first layout * fix(runtime): a paused preview stays still after any seek Sub-compositions kept animating while the transport was paused and the Studio button showed play. A render-seek unpauses every sibling timeline so GSAP propagates the root's totalTime into them, and nothing paused them again; parented to the global ticker, they free-ran at 1x while the master timeline and the clock stayed stopped. The Studio reaches that seek path through its seek-driven fallback adapter right after a preview reload, which is why editing text was what set it off. Captured live in the user's preview: seven child timelines advancing 0.210s per 200ms sample, all gsapPaused=false, transport not playing. Three fixes under one invariant: while the clock is paused nothing runs, and the button never disagrees with the runtime. - The sibling rearm is a lease, not a resting state: seekTimelineAndAdapters now returns every timeline it unpaused to paused in a finally. The second rearm after the child re-seek only ever changed the leaked state and is gone, with the comment that justified the leak by describing one caller. - The paused side of the transport tick policed nothing; it now stops any timed media element found running. A parked transport runs no ticks, so a capture-phase play listener wakes it. - Studio's canvas click resumed by setting the store flag alone; it now requests playback through the player so adapter, rAF loop and flag agree. Regression tests fail without each of the three changes. * perf(studio-server): stop re-encoding videos the browser already plays on open Opening a project kicked off a background transcode for every asset whose codec some browser might not decode. VP9 is on that list for Safari's sake, so a Chrome user opening a project with a VP9 avatar paid a ~10s, ~60 CPU-second re-encode across six cores on every open, concurrently with the browser's first layout, for an output nothing ever requested: across four recorded sessions the browser asked for the proxy zero times. One predicate was doing two jobs. "Could some browser fail on this" is a property of the asset and decides what gets injected into the page; "will this client request the substitute" decides whether to spend CPU before being asked. The codec table now carries an explicit prewarm flag: HEVC and ProRes (no browser decodes them) still warm; VP9 and AV1 are injected but transcoded lazily by the existing ?hf-proxy= request, which already reports failure as a 502. Pre-warms requested and proxies served are now counted on the existing structured-stderr telemetry channel, because a speculative job with a 0% hit rate emits no error and had been invisible. A single lookup helper also closes a prototype-key gap where one path used Object.hasOwn and the other a bare index. Regression test: a VP9 and an HEVC asset in one composition yield exactly one pre-warm, for the HEVC. Fails on the previous gate. * perf(cli): serve the studio bundle compressed and cache hashed assets The 4.1MB studio bundle was served uncompressed with Cache-Control: no-store, so every open of the studio re-downloaded and re-parsed it. Vite names built assets with an 8-character content hash, so their bytes can never change: those now ship gzip-compressed (1.25MB on the wire, byte-identical after inflation) with a one-year immutable cache policy. Unhashed files under public/ keep no-store, and the HTML shell, which previously sent no Cache-Control at all, now sends no-store explicitly: it is the only thing that names the current hashed bundle, and it must keep revalidating for the immutable policy to be safe. The hash test only accepts the segment after the last hyphen and requires a digit, underscore or capital, so an ordinary hyphenated name like user-Guide-v2.js is not mistaken for a hash and served forever. * perf(cli): warm the preview route before the browser opens The browser's first request for a project's preview paid the server's cold compiler import and first bundle in the request path, after the studio shell's own first-layout stall, so both costs landed on the user's time-to-first-frame in series. The CLI now issues one fire-and-forget request for the preview route from openStudioBrowser, the single funnel for every launch path, before the --no-open early return so pasted URLs benefit too. Measured on the demo project: first client request 231ms before, 101ms after; the ETag 304 path afterwards is under 1ms. The fetch carries a 10s abort so an unsettled connection cannot keep an otherwise-finished CLI process alive, matching the package's existing convention. The shader query params the player appends are not part of the route's cache key, so the plain route URL warms the same entry. * perf(studio): request the player chunk before the shell's first layout The dynamic import of @hyperframes/player ran inside the preview's mount effect, which React schedules after the shell's first layout. On a cold open that layout stalls the main thread for seconds, so the chunk request waited behind it for no reason. The import is now kicked at module scope, behind a typeof window guard that preserves the documented SSR contract (the module registers a custom element at load), and the mount effect awaits the already-in-flight promise. Verified in the built bundle: the preload call sits at module top level, so the request goes out on bundle evaluation. * fix(studio): editing a text property no longer reloads the preview Every keystroke in the Design panel writes the composition file, the file watcher announces the change to the studio, and the studio decides whether the change was its own. Over the CLI's event stream that decision has never worked: the browser hands the handler a MessageEvent whose data is a JSON string, and three of the four payload readers (version, write token, content) only understood an already-parsed object, so they read every field as absent. An absent token means "someone else edited the file", and the studio hard-reloaded the preview iframe on its own edit, blanking it for seconds. The path reader alone knew how to unwrap the string, which is why the event was recognised well enough to reload and never well enough to suppress. The envelope is now decoded once, at the boundary, by one function that all three transports feed; the readers share one field accessor so they cannot diverge again. The production event-stream rung is extracted into an exported channel so a test can drive a real MessageEvent through the listener it registers, which was impossible before because vitest defines import.meta.hot and the selection never reached that rung under test. A second, smaller cause: the server attached the write receipt to the first subscriber only and deleted it on read, so any other listener saw an unlabelled change. Reads are now non-destructive with the TTL as the only eviction, scanning newest-first because identical bytes written twice inside the TTL (undo, retyping a value) share a version and the older token was already spent. The file version now ships with every event, receipt or not, so duplicate deliveries of one change dedupe instead of reloading once each. shouldReloadSdkSession had no production callers and a signature that invited an undecoded delivery straight back into this bug; it is removed. consumeFileWriteReceipt stays as a deprecated alias for one release. Regression tests: a Studio write delivered as a real SSE MessageEvent is suppressed; two subscribers of one watcher event reload once; a genuinely external write still reloads; a repeat of earlier bytes gets the newest token; a receipt past the TTL is not recognised. Each fails on the code before it. * fix(runtime): paused-time media playback is borrowed, not banned The paused-side enforcement added in the previous commit had no notion of provenance, so it stopped two features that legitimately play media while the transport clock is paused. Both were deterministic, not racy: the capture-phase `play` listener means the very play() that starts them wakes the transport that stops them. - The colour-grading preview (colorGrading.ts startPreviewPlayback) plays a video while paused to render grading previews. It went dark on the first paused tick. - The Studio's scrub audition (timelineIframeHelpers.ts applyScrub) plays the music track for ~140 ms while paused so a playhead drag is audible. Same path killed it. A runtime-owned lease fixes both without weakening the enforcement. One owner: a WeakSet in the runtime closure, with lease/release published on the existing window.__hf surface for the Studio, which reaches the element across the iframe boundary and cannot call into the closure. The grading runtime is constructed with the pair directly. Both the cheap probe and the sync path skip leased elements while the clock is paused; during playback the transport owns everything again. Anything that plays while paused without a lease is, by definition, the defect the enforcement exists for, and is still stopped. Two corrections to the previous commit's reasoning: The old leak broke the render path too, deterministically, not only the preview. packages/producer/src/services/fileServer.ts:375-379 seekToTime flushes the virtualized rAF queue, and GSAP's global ticker with it, after renderSeek and before the frame screenshot (fileServer.ts:657-664, hf.seek). A sibling left unpaused therefore advanced by the full inter-frame delta into the captured frame. The finally added in the previous commit fixes that as well. Deleting the second activateSiblingTimelines is safe because nothing between frames reads a sibling's paused(), verified by grep over the deterministic adapters, syncTimedElementVisibility, the hf-timelines-built handler and __hfReseekGpu. Not merely because seekStandaloneRegisteredTimelines pauses each child. The code comment now gives that reason. Tests, each proven non-vacuous by reverting the piece it guards: - a leased element survives repeated paused ticks and is stopped once released - the colour-grading preview survives, through the real init wiring - the scrub borrows the element and gives it back on stop - the existing test that an unleased element is still stopped keeps passing * test(runtime): a lease ends when the transport plays or the borrower stops Two assertions the review found not load-bearing. Dropping the isPlaying branch so leased media stayed exempt during playback left every test green; a leased out-of-window clip is now asserted stopped the moment the transport plays. Deleting the release in the grading stop closure also left the suite green, because the pause on the next line satisfied the assertion; a restart after stop is now asserted stopped, which only the release makes true. * test(studio): the event-stream channel must open /api/events * fix(studio-server): stop printing a proxy diagnostic line per clip on every render Review of the pre-warm commit found the diagnostic louder than the thing it diagnoses, and the two counters measuring different things under one name. The per-asset `prewarm_requested` line is now behind HYPERFRAMES_DEBUG_MEDIA_PROXY, matching isGpuProbeDebugEnabled in packages/engine/src/utils/gpuEncoder.ts. A composition with fifty hostile clips printed fifty JSON lines into a clack-formatted terminal on every re-render. One summary line is written at process exit instead, using the same process.on("exit") shutdown hook as packages/cli/src/cli.ts. The counters now share a unit. prewarmsRequested counts per asset per render; proxyRequests counted every HTTP request, including 304s. It now increments once per resolveProxy call, after the ETag shortcut, so a revalidated repeat no longer reads as fresh demand. An unconditional Range refill still counts, and the docstring says so rather than claiming otherwise. The HEVC justification was false on macOS Chrome, which answers canPlayType for hvc1 with "probably" and keeps the source, so the pre-warm is redeemed there only through the reactive zero-videoWidth path. prewarm stays true because Chrome on Windows/Linux and Firefox do need the substitute; the comment and test names now say "no cross-platform decode" instead of "browsers never decode it". Two test gaps closed. Nulling vp9's representativeMime left the suite green while making the client skip canPlayType and proxy on every browser, which would reinstate exactly the transcodes this work removed; the mimes are now pinned. The Object.prototype test passed with the hasOwn guard deleted, so it now goes through probeAssetCodec, the input that actually misbehaves without it. Both fail when the change is reverted. * perf(cli): stop gzipping the studio bundle on loopback Compression made the cold open slower on the only transport this server has. It binds 127.0.0.1 with no --host, and measured there the six bundle assets took 69.8 ms with gzip against 7.9 ms raw; the 4.1 MB chunk alone was 49.4 ms against 3.1 ms. hono/compress is removed, which also retires the Vary header question it raised. If remote serving ever matters, compress at build time rather than per request. The cache policy is now decided by route instead of by filename. Reading a content hash out of a name cannot work: rollup's alphabet is base64url and includes a hyphen, so roughly one hashed file in ten was misread as unhashed, and the immutable header also leaked onto hand-authored public/ files served by the same handler. packages/studio/vite.config.ts sets neither build.assetsDir nor publicDir, so dist/assets holds only rollup's hashed emits and every public/ file lands at the dist root. /assets/* is therefore immutable and /icons/* and /favicon.svg keep revalidating, with no heuristic in between. The shell is no-cache rather than no-store. It carries no ETag, so both force the same full refetch, but no-store puts the document on Chrome's bfcache blocklist: leaving Studio and pressing Back would cold-boot the app instead of restoring it. * docs(runtime): say what the paused-media probe actually filters * revert(cli): drop the preview prewarm that held the CLI event loop The fire-and-forget warm added in c9b4263c7 keeps the CLI alive until it settles. cli.ts drains the event loop instead of calling process.exit, and two launch paths return straight into exit, so the warm delays them: 2660 ms with the warm suppressed, 8779 ms against a server answering in 6 s, 13293 ms against one that hangs. The 10 s abort bounds the hold, it does not remove it. This is the hazard already documented at preview.ts:1605-1609. Moving the warm into the server process was the obvious fix, but measurement says there is nothing there to warm. tsup bundles @hyperframes/core/compiler into cli.js -- bundleToSingleHtml is a plain inline function in the artifact -- so the await import() at studioServer.ts:397 resolves an already-evaluated namespace. A probe at listen time measures that import at 1 ms, and a paired run shows no gain: first request 256 ms without a compiler kick, 308 ms with one. The cold cost the plan attributed to the module load is somewhere else. Two claims in the reverted comment were also wrong: routes/preview.ts:332 is an ETag, not a bundle cache, and the player appends no shader params -- the only query param is variables, which IS part of the ETag. Reverts packages/cli to origin/main exactly. * fix(studio): let a remount retry the player chunk after a failed load 1037456aa hoisted the dynamic import to module scope and shared one promise across every mount. On rejection the .then never ran again: retryPreviewRef and previewError stayed null, compositionLoading stayed true, so the preview sat on an infinite spinner with the retry button at Player.tsx:462 unreachable, and remounting <Player key={activeKey}> -- the recovery path that used to work -- awaited the same rejected promise. Memoize through a getter that clears the memo on rejection instead. The module-scope kick still fires the chunk request before the shell's first layout, and a remount performs a fresh import as it did before the hoist. Discloses what the earlier commit did not: the player barrel re-exports Player, so every studio module importing that barrel now evaluates this one and eagerly loads the real player bundle. That is 27 DOM-env test files; the full studio suite passes, 439 files and 4838 tests. * docs(studio-server): trim the proxy-counter comment to the repo's four-line cap * fix(studio): stop one failed player import poisoning every later mount The previous commit claimed a remount could retry the player chunk after a failed load. In a browser it cannot: the module map caches a failed fetch as an errored entry for the document's lifetime, so a repeated import of the same specifier rejects from cache without touching the network (measured in headless Chrome: three attempts, one request). Clearing the memo on rejection is still right, because it stops every later mount awaiting the same poisoned promise, but recovery is a page reload, and the comment now says so. The tests said what vitest does, not what the browser does. Two assertions survived their own mutation: removing the memoisation left the attempt counter unchanged because vitest caches a resolved mock, and deleting the module-scope kick, the optimisation this branch exists for, left the suite green. Both are now asserted directly: the kick has run once at import time before any mount, and every mount receives the identical promise. * chore(ci): allow the deletion of the dead sdk-session reload test * fix(runtime): the timeline resolver no longer unpauses children it cannot drive Exercising the branch in a real browser still showed sub-compositions free-running while paused, on a path no seek follows: the timeline resolver, which runs on every rebind (after an edit, on the periodic bind), unpaused every registered child BEFORE trying to nest it into the root. A child the root actually holds is driven by the paused root and is harmless; a child the root never takes stays on GSAP's global ticker, and unpaused there means running. The seek fix in this branch could not reach it, because a rebind is not a seek. The resolver now reads back which children the root holds and unpauses only those; the same rule applies to the composite fallback timelines. Standalone registry children stay paused, as the transport's per-child seek already requires. Regression test: a hosted registry child whose root cannot nest it stays paused across a forced rebind. Fails on the previous resolver. * test(runtime): pin that the resolver unpauses a child only once the root holds it The resolver's positive half had no fixture: nothing anywhere nested a candidate for real, so computing the held set before the add loop instead of after it left the suite green. A root that reports children only once added now distinguishes the two orders, and the unpause is asserted at the moment it happens, because the transport's first seek pauses every hosted child again straight after resolution. Also drops a cast that re-declared getChildren, which RuntimeTimelineLike already has. * fix(runtime): the paused side stops every clip the transport drives The paused-side enforcement scanned only media carrying its own data-start. A clip inside a composition inherits its timing from the host and has no data-start of its own, yet the transport plays it, so it could start while paused and run unopposed, exactly the hole the invariant was written to close. Reviewer probe: a hosted video with data-duration only kept running while paused; the same element started under __player.play(). "Media the transport drives" now has one definition, shared by the media cache and the paused-side probe, so neither can be narrower than the other. Regression test: hosted media with no data-start started while paused is stopped. Fails against the data-start-only scan.	2026-09-12 12:56:00 -04:00
Vance Ingalls	4ba8396c27	chore: release v0.8.35 ... Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>	2026-09-11 14:30:23 -07:00
miga-heygen	14b9e2039b	fix(studio): tolerate WebMCP execute calls without an options object (#3860) ... * fix(studio): tolerate WebMCP execute calls without an options object Every Studio write tool (studio_set_text, studio_set_style, studio_transform, studio_add_animation, studio_update_animation, studio_add_keyframe, studio_delete_animation) registered its handler as `execute: (input, { signal }) => ...`. The W3C shape passes an options object, but the bundled `@mcp-b/global` polyfill invokes a registered `execute` with the input alone, both from its in-page BrowserMcpServer wrapper and from the descriptor it mirrors into a native `document.modelContext`. The destructure therefore threw `TypeError: Cannot destructure property 'signal' of 'undefined'` before the handler ran, while the read tools, which ignore the second parameter, kept working. Route the seven signal-taking tools through one `writeTool` helper in `buildStudioTools` that reads `options?.signal`, so a missing options object yields an undefined signal at a single boundary. The handlers already default an undefined signal to a never-aborted one, so nothing downstream changes. `ModelContextTool.execute` now declares `options` optional to match what callers actually do. Upstream check: `@mcp-b/global` 5.0.1 (pinned), 5.0.3 and 5.1.0 ship a byte-identical `@mcp-b/webmcp-polyfill` chunk and the same one-argument call in `@mcp-b/webmcp-ts-sdk`, so a dependency bump would not fix this. Tests: drive `studio_set_text` through the real `@mcp-b/global` package under jsdom (registry entry `execute` and Chromium-style `executeTool`) and assert a saved result; call every write tool with one argument against a fake model context and assert none reports an `internal` failure. The existing spec-shaped tests, including the early abort path, still pass, which proves a provided signal still reaches the handler. Shared inert deps builders move to `webmcpTestUtils.ts`. Closes #3858 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * test(studio): cover the native-mirror WebMCP execute path Install a native-looking `document.modelContext` before importing `@mcp-b/global` so the bridge wraps it and mirrors every Studio registration into it. One setup then exercises both one-argument call paths the package ships: the in-page BrowserMcpServer wrapper (registry entry and Chromium-style `executeTool`) and the descriptor mirrored into the native context. Both fail with "Cannot destructure property 'signal' of 'undefined'" without the fix and save with it. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>	2026-09-10 20:12:14 -04:00
Miguel Ángel	59def1b66d	chore(release): v0.8.34 (#3854)	2026-09-10 14:45:17 -04:00
Miguel Ángel	9549e038c4	perf(studio): a paused editor stops redrawing its overlays sixty times a second (#3846) ... * perf(studio): run the editor overlays on one parkable frame loop The composition rect, the selection and hover boxes, the off-canvas indicators and the snap guides each owned an animation-frame loop that re-armed unconditionally. On a paused, untouched editor that is four callbacks per frame reading layout, and the snap-guide loop writes style on every one of them, so the compositor kept committing 55 frames a second with nothing moving. None of the four has a clock of its own; each only changes when something observable happens. They now share one loop that runs at full rate for a moment after a pointer, key, wheel, scroll, resize or visibility change, after a preview message reporting a frame the overlays have not drawn, or after a mutation inside the preview document, and otherwise polls four times a second so a wake source nobody thought of costs a quarter second of staleness rather than a frozen overlay. The frame comparison on preview messages is load-bearing rather than an optimisation: the paused preview posts an unchanged status message every 80 ms so any listener can confirm its position, and treating that as news held the overlays at 60 fps for the life of the tab. * fix(studio): one overlay's throw must not stop the other four The shared frame loop re-armed after running its subscribers, so a subscriber that threw took down the loop and its idle-poll safety net permanently. The four loops it replaced each re-armed first, which kept that failure to the one overlay that caused it. It now re-arms before running anything and isolates each subscriber, rethrowing out of band so the error still reaches the page's error reporting. The wake also sat outside the recognised-message check, so postMessage traffic from an extension, devtools or any other embed on the page held the overlays awake for 400ms at a time. Only the preview's own messages wake it now, and a repeated paused status post still does not. useMotionPathData had the same unconditional loop and is live whenever a keyframed element is selected; it joins the shared one. * fix(studio): wake the overlays only for the preview	2026-09-10 18:20:37 +00:00
renovate[bot]	eae4892ae8	chore(deps): update dependency vitest to v4 [security] (#3789) ... * chore(deps): update dependency vitest to v4 [security] * fix(test): preserve test behavior on Vitest 4 --------- Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: James <james.russo@heygen.com>	2026-09-10 13:55:52 -04:00
James Russo	c98d6fbac8	fix: keep caption transcript data inside generated scripts (#3847) ... * fix: keep caption transcript data inside generated scripts * test: locate caption data without an HTML filtering regex	2026-09-10 12:53:30 -04:00
Miguel Ángel	73dfe35e46	fix(preview): show the correct scene instead of every scene at once on some loads (#3848) ... * fix(runtime): show the right scene when the preview DOM comes from another window The Studio preview sometimes builds the composition body in the editor window and adopts it into the preview frame's document. Adopted nodes keep the prototypes of the realm that created them, so `node instanceof HTMLElement` is false for every element in the composition even though the elements are ordinary HTML sitting in that document. Every guard in the runtime written as `if (!(node instanceof HTMLElement))` then skipped the whole document, silently: nothing threw, nothing logged, and readiness still reported success. The timed-element visibility pass wrote no inline visibility at all, so on those loads the preview painted every scene on top of every other and the editor drew off-canvas markers for elements the user could not see. The auto-stamp pass stopped stamping too, which is why the composition came up one timeline clip short. Replace every realm-sensitive element check in the runtime with structural predicates that ask what a node IS (node type, namespace, tag name) rather than which window's constructor made it. Two local `doc.defaultView.HTMLElement` workarounds are deleted with it: they fix only the case where the nodes belong to the document's own realm, and adoption is exactly what breaks that. * fix(studio): scrub the music track the timeline named, not the first audio `resolveScrubAudioEl` tested `byId instanceof HTMLAudioElement` on a node from the preview iframe's document. That node is an instance of the IFRAME's `HTMLAudioElement`, never this module's, so the check was false on every load and the `musicId` hint was dead. Scrub fell through to the first `<audio>` in the document, which the comment right above it warns can be the voiceover, so dragging the playhead could preview the wrong track. Ask what the node is instead. Also close the gaps an independent review found in the runtime fix: - the cross-realm predicate test had no `<audio>` and no `<img>`, so reverting `isAudioElement` or `isImageElement` to `instanceof` left it green. It no longer does, and the audio case also pins `isMediaElement`, which composes from it and gates the media sync path. - nothing stopped the runtime regressing. `lint-runtime-preview-guards.ts` gains a second check kind: patterns that must be ABSENT under a directory, seeded with DOM-typed `instanceof` under `src/runtime`, pointing at domRealm.ts. Comment lines and tests are exempt, both on purpose. - domRealm.ts stated the adoption mechanism as settled fact. The mixed prototypes are measured; how the nodes get into the frame is not identified, and the docstring now says which is which. Its ownership claim is scoped to the runtime, since packages/studio still hand-rolls its own checks.	2026-09-10 08:06:43 -07:00
Miguel Ángel	0408fbcd99	perf(studio): scrubbing a large composition no longer stalls the editor (#3842) ... * perf(studio): ask each ancestor once per off-canvas rebuild, not once per element The dashed off-canvas markers are rebuilt whenever anything in the preview changes, which during playback or a scrub is several times a second. Most of what a rebuild asked about an element was really a question about its ANCESTORS: does each node up to the root render, what does each contribute to the composed transform, which node is the source-file boundary. Two siblings share their whole chain, so a preview of a thousand elements asked the platform the same questions about the same ancestors a thousand times over. A rebuild now threads one measure pass through the walk, and each node answers once. On a 1689-element carousel that takes computed-style reads from 11,159 to 2,526 per rebuild and the rebuild itself from 59 to 12-18 ms per seek, with the rendered marker set byte-identical. The pass is deliberately not a cache. A cache would have to say what could have changed since last time, and for a measurement the answer is anything: an image finishing decode, a font swapping in, a transition frame, a container query, an inserted stylesheet rule all move an element's box with nothing written to the DOM and no record to invalidate on. A pass lives inside one synchronous measurement that only reads, so nothing can move under it, and it is dropped when the measurement ends. Every rebuild still measures every element. Layout reads are untouched on purpose: each element still takes its own client rect every rebuild, because that is the read that cannot be shared and must not be remembered. * test(studio): give one PropertyPanel case the file's own render timeout Every other render test in that file passes RENDER_TIMEOUT_MS; this it.each was left on vitest's 5s default and times out when the whole suite runs on a loaded machine. Unrelated to any behaviour: it passes on either side of the change when the machine is quiet, and fails in a full-suite run on either side when it is not. * refactor(studio): share the source-boundary walk and dedupe the rebuild fixtures Three follow-ups from review of the measure pass, none of them behaviour: The source boundary was memoized against the element that asked for it, so two siblings still walked their whole chain separately and only the answer was reused. It now memoizes every node on the way up, like the other two walks: an element's boundary IS its parent's unless the element is one itself. `isElementVisibleThroughAncestors` returns what it always returned, but it now resolves top-down, so the set of nodes it takes a style read for is different (smaller for a subtree hidden near the root). Three callers use it with no memo, so that is written down next to it rather than left to be discovered. The three rebuild fixtures in the indicator tests each carried their own copy of the iframe/overlay/layout-stub scaffolding, which is four clone groups and 126 duplicated lines. One `mountPreview` helper now serves all of them and the pre-existing selector-index fixture too. * test(studio): pin the measure pass to one rebuild through an ancestor-derived input The existing no-mutation-record test varies an element's own box, and the pass never memoizes a box — so hoisting the pass to module scope, which is exactly the mistake that would reintroduce cross-rebuild staleness, left every test green. This one fades a wrapper between two rebuilds and asserts the marker under it goes away. Visibility through ancestors IS memoized, so the pass surviving the rebuild serves the stale answer: with `createOverlayMeasurePass()` hoisted the suite exits 1 on this test alone, and exits 0 at head.	2026-09-10 14:48:30 +00:00
Miguel Ángel	8bf5b4423e	perf: sublinear Studio rebuilds and seeks (#3837) ... * perf(studio): resolve the overlay coordinate basis once per composition The iframe->overlay basis (composition root, root scale, iframe and overlay rects) was resolved inside every geometry call, so measuring a preview cost one querySelector("[data-composition-id]") plus three layout reads PER ELEMENT to rediscover something that is a property of the composition and the canvas zoom. It is now threaded through orientedGroupAwareOverlayRect, groupAwareOverlayRect, orientedOverlayRect, orientedVisibleOverlayRect and toVisibleOverlayRect the way toVisibleOverlayRects already batched it, and resolved once by the two callers that measure many elements in one synchronous pass: the off-canvas indicator rebuild and the overlay RAF loop. Both passes only read the DOM, so nothing can move the canvas between two measurements inside one of them. * perf(studio): rebuild the layer walk from the mutation, not the document A MutationObserver marked the off-canvas indicators dirty and the rebuild then re-derived every element in the preview from scratch. The observer's loudest source is inline style, which is what animation writes, so a composition just sitting there re-derived the whole document several times a second, and each element costs two getComputedStyle reads, two ancestor walks for its source file, and a textContent read over its whole subtree. The records now say WHAT to drop, not merely that something changed, and the per-element derivations are memoized between rebuilds. Two lifetimes, because they do not go stale together: whether an element renders (and how many layer children it has) dies on any nearby attribute write, while how it is ADDRESSED survives every style write and dies only on something that can renumber a selector. That split is what makes an ordinary animation frame cost no document queries at all. Not attributable to specific elements, so still a full rebuild: nodes added or removed, and any change to an identity attribute, which renumbers every element sharing a selector. Two supporting changes: - getDirectLayerChildren asked getDomLayerPatchTarget for a full patch target per child and used it as a boolean. The target carries the selector's occurrence index, which is a whole-document query the yes/no does not depend on. isDomLayerElement answers it without one, for every caller. Its unused options parameter goes with it. - The observer no longer filters attributes. An attribute it never hears about is one the cache would answer stale for, and the old filter omitted id and the data-composition-* attributes that decide a layer's identity. Widening only makes indicators refresh sooner; a rebuild is a pure read and is throttled either way. Every other caller of collectDomEditLayerItems passes no cache and is unchanged. * perf(runtime): visit only the clips a seek can flip Every seek, and every frame of playback, rebuilt the window of every video and audio element in the document and handed all of them to the per-clip sync loop. On a composition of eighty videos that is eighty window derivations and eighty per-clip passes to conclude that one clip is on screen. A clip is active only while start <= t < end, so a clip whose window excludes the new time is inactive there whatever its element state is. Sorting the windows by each endpoint turns a seek into two binary searches: the clips whose start or end lies between the old time and the new one, plus the ones that were in window at the old time. Anything outside both was out of window before and is out of window now, and was already paused and already evicted by the pass that last saw it go out. A one-frame step visits the clip or two that flip; a jump over a hundred clips still visits the hundred boundaries it crosses. The index carries only the windows, and it rides the revision the duration floors already ride: the same timing attributes, the same media metadata events, the same timeline registry signature. Nothing else is cached. Every field handed to syncRuntimeMedia is re-read from the element on every pass, because el.duration can be reset under us by the load() retry, and a cached copy of it would be exactly the stale duration the two-resolver-scope rule exists to prevent. The render/export path does not consult the index at all and visits every element on every frame, and a render seek clears the sweep so a later live seek cannot inherit a position it did not establish. Also folds the duration floors' own invalidation into that shared revision. Draining the observer is what detects a change, and only the first reader in a task gets the records, so two caches each checking for themselves would have had the second told nothing changed. * refactor(studio): split the overlay basis and the layer-walk read into their own modules Clears the 600-line file cap and the fallow audit on this branch. Behaviour is unchanged: this moves code, it does not alter any of it. File size. Both files were already near the cap on main and my three levers pushed them over (615 vs 598, and 605 vs 584): - domEditOverlayGeometry.ts -> 561. The iframe->overlay coordinate basis (OverlayRootScale, computeOverlayRootScale and the root/dimension lookups it owns) moves to domEditOverlayBasis.ts. It is the one piece of that file every other piece depends on, and nothing in it is about a single element's geometry. Its two callers now import it from there. - domEditingLayers.ts -> 587. The per-element read that the walk performs moves to readDomEditLayerWalkEntry in domEditLayerWalkCache.ts, the module that owns the memoization it reads through. The walk keeps the traversal and the depth bookkeeping, which are the parts that are actually about walking. No unrelated code was trimmed to make room. Duplication, all three clone groups fallow flagged: - The runtime seek fixture (createMockTimeline, the synchronous animation-frame clock, the CSS.escape shim, stubDuration) was copied between init.timingResolver.test.ts and init.mediaClipIndex.test.ts. It moves to runtimeSeekFixture.test-helpers.ts. Each suite keeps its own vi.mock calls, which are file-scoped and cannot be shared. The file is excluded from tsconfig.runtime.json alongside the test files it serves, for the same reason. - domEditLayerWalkCache.test.ts repeated its mount/observe/first-walk setup in three tests; that is now withWarmWalk. Complexity. Only one of fallow's three findings is attributable to this branch, and fallow agrees: it marks the other two inherited and excludes them from the gate. - offCanvasIndicatorRefresh.ts update was NEW (absent from main's report, 10 cyclomatic / 31.6 CRAP here). The optional-chain-and-default I added to drain the observer becomes drainPendingLayerMutations, with its own unit tests, and the function drops off the report entirely. - useDomEditOverlayRects.ts update: 37 cyclomatic / 69 cognitive on main AND here. My change added one statement and no branch; the function grew 139 -> 147 lines, which is what resurfaced it. Left alone. - domEditingDom.ts escapeCssIdentifier: 24 cyclomatic / 19 cognitive / 148.4 CRAP on main AND here. Untouched by this branch; only its line number moved (173 -> 182) because the composition-source-map revision counter sits above it. Left alone.	2026-09-10 03:55:28 +00:00
Miguel Ángel	ac27b1534f	perf(studio): resolve a selector's occurrence index once per layer walk (#3831) ... The preview flattens several composition files into one DOM, so a layer's identity is its selector plus its occurrence index WITHIN its own source file. `getSourceScopedSelectorIndex` derived that per element: a whole -document `querySelectorAll(selector)`, `resolveSourceFile` on every match, then `indexOf`. Every element sharing a class paid for all of them, so a walk over n such elements did n whole-document queries and n^2 source-file resolutions — the shape a composition of repeated cards or tiles has by construction. Build the occurrence index ONCE per selector instead and share it across one walk. `withSelectorIndexPass(doc, run)` opens that scope; outside it the helper behaves exactly as before, per call. The pass lives in `collectDomEditLayerItems`, which owns the loop, rather than at a call site — its four callers (off-canvas indicators, the layers panel, the marquee hit-test and the agent look tool) all walked the same way and all paid the same cost. Behaviour is unchanged. The occurrence indices are identical, including the misses: an element outside the requested source file, or one not matching the selector, still yields undefined, as do `#`-prefixed and `[data-composition-id=` selectors and an invalid selector. Measured on a 1689-element preview over 80 single-frame seeks, per rebuild: class-selector document queries 171.6 -> 10.8, and the walk's self-timed cost 15.25ms -> 5.37ms. Elements walked per rebuild is unchanged at 973.7, so the two arms did the same work. Tests assert complexity invariance rather than a threshold: the query count must be IDENTICAL at n and 4n elements sharing a selector, which a fixture -sized threshold would not catch. Both fail on the previous algorithm.	2026-09-09 19:11:22 -07:00
James Russo	4f77c282da	fix(studio): authenticate preview message senders (#3812)	2026-09-09 09:32:03 -04:00
James Russo	f54ba56136	fix(studio): contain project IDs across client and server routes (#3808) ... * fix(studio): contain project IDs across client and server routes * test(studio): use a portable project directory fixture * fix(studio): reject drive-relative IDs and filter project discovery	2026-09-09 05:27:36 -04:00
miga-heygen	6e3308be4f	chore: release v0.8.33 (#3796) ... Co-authored-by: Miguel Ángel <miguel.sierra@heygen.com>	2026-09-08 22:12:51 -04:00
miga-heygen	662f96b3f4	chore: release v0.8.32 (#3788) ... Co-authored-by: Miguel Ángel <miguel.sierra@heygen.com>	2026-09-08 19:40:29 -04:00
Miguel Ángel	ab07d67380	fix(studio): preserve timeline DOM identity during hydration (#3681)	2026-09-08 18:08:55 +00:00
Miguel Ángel	30d6f43bdb	chore: release v0.8.31 (#3747) ... * chore: release v0.8.31 * docs(release): describe the range fix on its own terms	2026-09-07 12:12:35 -04:00
Miguel Ángel	3874990449	chore: release v0.8.30 (#3733)	2026-09-05 23:14:12 -04:00
James Russo	7d7003aa64	fix(studio): match style attributes with explicit quote boundaries (#3712) ... * fix(studio): match style attributes with explicit quote boundaries * fix(studio): apply quote boundaries to active source writers	2026-09-05 14:50:27 -04:00
James Russo	c564daf210	fix(studio): avoid inline style regex backtracking (#3708)	2026-09-05 12:58:26 -04:00
miga-heygen	ae3d80c30f	chore: release v0.8.29 (#3690)	2026-09-04 21:50:46 -04:00
miga-heygen	00c575d23b	fix(studio): prevent preview hang on burst external file rewrites (#3648) ... * fix(studio): prevent preview hang on burst external file rewrites Two interacting bugs caused Studio to freeze when multiple processes (generator, check, snapshot) burst-wrote index.html within seconds: 1. SSE listener leak: the /api/events handler added a watcher listener per client connection but never removed it on disconnect. Reconnects accumulated dead listeners, each triggering readFileSync on every file change and writing to closed streams. 2. Generation starvation: processChange incremented generationRef and awaited drainPendingChanges. A second event arriving mid-drain bumped the generation, causing the first drain to bail at the generation check. With rapid writes, no drain ever completed and Studio stayed frozen on stale content. Fix 1: use stream.onAbort() to remove the watcher listener when the SSE connection closes. Fix 2: gate processChange with a draining ref. While a drain is in progress, stash the latest event. On completion, process the stashed event — the last write in a burst always completes its reload. Closes #3646 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(studio): align coordinator tests with drain serialization Update existing test to expect the new behavior: when two events fire in quick succession, the first drain completes and triggers a reload (previously it was silently discarded). The stashed event then starts a second drain. Also fix the burst-write test to use the drains array pattern and explicit act() flushes for stashed event processing. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(studio): stash events with allowDuplicate and harden listener cleanup Address Rames's review findings: - Stash with allowDuplicate: true so re-dispatched events are not swallowed by the duplicate guard (the identity was already written on the way in, so the stashed event matched itself on re-entry). - Wrap SSE keepalive loop in try/finally so the listener is removed on both abort and throw, not just abort. - Restore stale-completion guard test coverage lost in the rename. - Use await act(async () => {...}) for burst dispatches so assertions depend on the stash guard rather than scheduling. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(studio): simplify drain serialization and restore SSE cleanup Restructure processChange into intake + drain loop: - processChange is now synchronous — validates, dedupes, checks own echoes, enqueues the accepted payload, and starts the drain loop - startDrainLoop runs while the pending slot is non-null, draining one event per iteration via drainOnePending - No recursive void processChange(...) from finally, so no allowDuplicate escape hatch needed — stashed events never re-enter intake guards SSE listener: restore stream.onAbort alongside try/finally. Hono's sleep() never throws, so finally alone doesn't fire on disconnect. Both paths call removeListener (Set.delete is idempotent). Tests: remove stale-drain test that contaminated subsequent tests by emptying the shared roots array mid-test. Use sync act() for burst dispatches — the stash decision is synchronous. All 10 coordinator tests pass locally (NODE_ENV=test). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-09-04 21:44:25 -04:00
Miguel Ángel	64ce9fdf1f	chore: release v0.8.28 (#3689)	2026-09-04 21:01:08 -04:00
James Russo	1f9f86c857	docs(studio): align stack note with package dependency contract (#3675) ... Co-authored-by: yoma <yingwaizhiying@gmail.com>	2026-09-04 19:53:07 -04:00
James Russo	3bc46a8ade	fix(studio-server): cascade GSAP cleanup when deleting subtrees (#3655)	2026-09-04 17:38:33 -04:00
Miguel Ángel	19ab83f929	chore: release v0.8.27 (#3608)	2026-09-03 00:27:31 -04:00
Miguel Ángel	84ed587f33	chore: release v0.8.26 (#3597)	2026-09-02 10:36:01 -04:00
Miguel Ángel	81f1a903e1	fix(studio): rebind paused preview after live edits (#3596)	2026-09-02 10:23:09 -04:00
Miguel Ángel	6b360f56f7	chore: release v0.8.25 (#3595)	2026-09-02 01:29:06 -04:00
Miguel Ángel	6b5b4cb988	feat(studio): make agent edits live and explicit (#3581)	2026-09-02 01:11:13 -04:00
James Russo	aceaaebd68	chore: release v0.8.24 (#3593)	2026-09-01 21:54:42 -04:00
Miguel Ángel	6cbe3fbe90	chore: release v0.8.23 (#3586)	2026-09-01 13:58:14 -04:00
Miguel Ángel	38e356fba4	chore: release v0.8.22 (#3575) ... * chore: release v0.8.22 * docs: include encoder retry in v0.8.22 notes --------- Co-authored-by: James <james.russo@heygen.com>	2026-08-31 22:54:13 -04:00
Miguel Ángel	f3099dcb27	chore: release v0.8.21 (#3570)	2026-08-31 15:16:22 -04:00
Miguel Ángel	2d6b055f31	feat(studio): let an agent author motion (#3520) ... * feat(studio): let an agent drive Studio's selection and playhead Adds `studio_select` and `studio_seek`, so an agent and the human are looking at the same element and the same instant. Selecting reveals the inspector, exactly as a click does, which is what makes the agent's move visible. Selection is shared state, not a per-call argument, and that is forced rather than chosen. Most of Studio's edit handlers read the ambient React selection, and `applyDomSelection` only schedules a state update, so selecting and committing inside ONE call would write to whatever was selected before. Two tool calls are separated by a render, so the contract is select first, then act. That is also how a human works: click, then type. `studio_seek` uses `requestSeek`, not `setCurrentTime`. The latter only moves the timeline's displayed number and leaves the composition where it was. Two things the tools refuse to fake: Seek does not clamp. `seek()` already clamps against the adapter's duration, which can differ from the store's, and clamping again would give that invariant two owners that can disagree. The tool reports where the playhead actually landed instead, read back afterwards. `requestSeek` is fire-and-forget, so it cannot report that no adapter was mounted to receive it. The tool compares the playhead before and after and fails rather than claiming a seek that never happened. Select separates three failures that a single message would have merged: the preview is not mounted yet (wait), no element matches the handle (re-read), and the element cannot be selected (try a neighbour). The agent's next move differs for each, so collapsing them would cost it a round trip or a retry loop. * feat(studio): give an agent eyes with studio_frame Renders the composition to a PNG at a given time and returns the URL. This is what turns the tool set from a remote control into a loop: author a change, capture the instant it affects, look, adjust. No agent can judge motion from source, because "what does this look like at 2.4 seconds" is not a question a file answers. Reuses Studio's existing capture endpoint via `buildFrameCaptureUrl` rather than inventing a second one. Two things this does not fake: It reports the time the playhead LANDED on, not the time requested. The player clamps, so those differ at the ends, and attaching the wrong time to a frame is how an agent draws a confident wrong conclusion about motion. It waits before capturing, by default 150ms. The frame is rendered from the file on disk, and the render cache is cleared by a file watcher with a 40ms write-stability threshold, so a capture that beats the watcher renders the PRE-edit composition. That exact staleness was a real bug here once. An agent reading a stale frame as "my edit failed" would thrash, so the wait is on by default, `settleMs` makes it tunable, and the tool description names the failure rather than leaving it to be rediscovered. It probes with HEAD before returning, so a URL that 404s comes back as a failure with a hint instead of as a link the agent cannot render. * feat(studio): add studio_inspect, so an agent reads before it writes Everything about one element in one call: resolved styles, text fields, box, data attributes, GSAP animations, and what the element will and will not accept. The point is to prevent a failed write rather than to satisfy curiosity. `can.reasonIfDisabled` is passed through verbatim from Studio's own capabilities, so an agent that reads first should never attempt an edit the element would refuse. Three things it refuses to get wrong: Animations are reported ONLY for the current selection, because that is the only element Studio parses them for. Attributing them to any other element would be reporting the wrong element's motion, which is worse than reporting none. When a handle names something else the field is empty and `animationEditingBlocked` says why. `animationEditingBlocked` also carries the two states where animation editing is off entirely, multiple timelines and an unsupported timeline pattern. Both live on the selection context. Learning them from a read costs one call; learning them from a failed write costs a retry loop. Inspecting a handle does NOT change what is selected. It is a read, and stealing the human's selection would be a side effect they did not ask for. There is a test asserting `applySelection` is never called. Nothing selected and no handle given is a failure, not an empty result. An empty result would assert "this element has nothing", which is a different and false claim. * feat(studio): let an agent edit text and styles, guarded The first tools that change the composition. Both act on the current selection and take no handle, which is forced rather than chosen: the handlers read the ambient React selection, and `applyDomSelection` only schedules a state update, so selecting and committing inside one call would write to whatever was selected before. Select first, then edit. Also plumbs the write-blocked state, which was the blocker for shipping any write at all. `domEditSaveQueuePaused` and the external-file conflict both lived on App and were unreachable from the tool surface, so `canWrite` was optimistic and a comment said so. They now derive into a single `writeBlockedReason` on the shell context: one field, one owner, conflict taking precedence because resolving it is what unblocks the queue. That guard matters more than it looks. Both states are BANNERS in Studio with no lock behind them, so nothing else was stopping a programmatic write from landing on top of a conflict the user had been asked to adjudicate. Three things the tools refuse to fake: They check the outcome, not the absence of a throw. Studio has several paths where a failed commit resolves anyway, so awaiting the handler proves nothing. The tagged outcome added earlier is what proves the write landed. A partial style result is reported as partial. `handleDomStyleCommit` is one property per call, so N properties are N commits; the result carries `applied` and `rejected` maps rather than a single boolean that would have to pick a side. Style commits run sequentially, never concurrently. Two commits racing through Studio's client-side read-modify-write can record undo entries that both claim the same starting content. There is a test that measures concurrency rather than trusting the loop. Every decline reason maps to a hint naming what to do instead, so a refusal routes the agent rather than just stopping it. * feat(studio): move, resize and rotate, verified by reading back `studio_transform` does what a drag does, and then checks. The box in the result is READ BACK after the write, never echoed from the request, and `applied` lists what actually took effect. That is not belt-and-braces. The plan for this unit said to re-derive the geometry handlers' behaviour rather than trust any description of them, and doing that turned up three different behaviours behind one interface. The handlers on `DomEditActionsValue` are the GSAP-AWARE wrappers, aliased in `useDomEditSession.ts:534-538`, not the CSS ones in `useDomGeometryCommits.ts` that an earlier note in this workstream described. `handleGsapAwarePathOffsetCommit` and `handleGsapAwareRotationCommit` are `if (gsapCommitMutation) { ...intercept... }` with no else branch. Their own comments say the absence is deliberate: position and rotation are written as GSAP code and there is no CSS fallback to write to. So they can return having done nothing. `handleGsapAwareBoxSizeCommit` is not like the other two. It runs through `runGestureTransaction` with separate scale and width/height routes, so resize works more generally. Reading back is what turns that middle case from a silent lie into a reported one. A move that did nothing comes back in `unchanged` with a reason. Three smaller decisions: Operations re-read between each other, so a move is judged against the box AFTER a resize in the same call. Comparing against the original would credit the resize's change to the move. Rotation is reported as dispatched, not verified. `rotate` is an individual transform property and does not appear in the computed transform, so there is no honest box-derived signal, and claiming one would be worse than saying so. x pairs with y and width pairs with height. Accepting one alone would mean inventing the other from the current value, which moves the element somewhere the caller did not ask for. The pairing rule and its minimum live in one `parsePair` helper rather than as four separate branches. * feat(studio): let an agent author motion Four tools: add an animation, change its duration/ease/position, add a keyframe, delete it. This is the capability that makes the tool set worth having, because motion is the one thing an agent cannot judge or author from source. These are deliberately less confident than the rest of the set, and the reason is the handlers underneath them: `handleGsapAddAnimation(method)` takes only a method. Its insert position comes from the live playhead, not the caller, and the call is `void ...catch()` so it returns nothing. `handleGsapAddKeyframeBatch` returns a promise but catches its own failure, so awaiting proves the call finished, not that it landed. `handleGsapDeleteAnimation` discards its promise entirely. `handleGsapUpdateMeta` is the one honest signal. It returns a boolean. U8 handled the same problem by reading the result back. That does not work here: the animation list comes from React state that only refreshes on a render, and no render happens inside one tool call. Rather than fake a verification with a frame-timer, these report what was DISPATCHED and the descriptions tell the agent to call studio_inspect to see the result. Saying "I asked for this" is honest; saying "this happened" would not be. Three consequences worth stating: `studio_add_animation` takes no position. The handler reads the playhead, so accepting one would report a number that had no effect. It reports where the playhead actually was and tells the agent to seek first. `studio_update_animation` rules out the no-selection case BEFORE dispatch. The handler answers `false` for both "nothing selected" and "the write failed", so eliminating one is what makes the other legible. Keyframe percent and properties are validated in the tool, because nothing in the platform checks input against the declared schema. * feat(studio): add studio_inspect, so an agent reads before it writes (#3517) Everything about one element in one call: resolved styles, text fields, box, data attributes, GSAP animations, and what the element will and will not accept. The point is to prevent a failed write rather than to satisfy curiosity. `can.reasonIfDisabled` is passed through verbatim from Studio's own capabilities, so an agent that reads first should never attempt an edit the element would refuse. Three things it refuses to get wrong: Animations are reported ONLY for the current selection, because that is the only element Studio parses them for. Attributing them to any other element would be reporting the wrong element's motion, which is worse than reporting none. When a handle names something else the field is empty and `animationEditingBlocked` says why. `animationEditingBlocked` also carries the two states where animation editing is off entirely, multiple timelines and an unsupported timeline pattern. Both live on the selection context. Learning them from a read costs one call; learning them from a failed write costs a retry loop. Inspecting a handle does NOT change what is selected. It is a read, and stealing the human's selection would be a side effect they did not ask for. There is a test asserting `applySelection` is never called. Nothing selected and no handle given is a failure, not an empty result. An empty result would assert "this element has nothing", which is a different and false claim. * feat(studio): move, resize and rotate, verified by reading back (#3519) `studio_transform` does what a drag does, and then checks. The box in the result is READ BACK after the write, never echoed from the request, and `applied` lists what actually took effect. That is not belt-and-braces. The plan for this unit said to re-derive the geometry handlers' behaviour rather than trust any description of them, and doing that turned up three different behaviours behind one interface. The handlers on `DomEditActionsValue` are the GSAP-AWARE wrappers, aliased in `useDomEditSession.ts:534-538`, not the CSS ones in `useDomGeometryCommits.ts` that an earlier note in this workstream described. `handleGsapAwarePathOffsetCommit` and `handleGsapAwareRotationCommit` are `if (gsapCommitMutation) { ...intercept... }` with no else branch. Their own comments say the absence is deliberate: position and rotation are written as GSAP code and there is no CSS fallback to write to. So they can return having done nothing. `handleGsapAwareBoxSizeCommit` is not like the other two. It runs through `runGestureTransaction` with separate scale and width/height routes, so resize works more generally. Reading back is what turns that middle case from a silent lie into a reported one. A move that did nothing comes back in `unchanged` with a reason. Three smaller decisions: Operations re-read between each other, so a move is judged against the box AFTER a resize in the same call. Comparing against the original would credit the resize's change to the move. Rotation is reported as dispatched, not verified. `rotate` is an individual transform property and does not appear in the computed transform, so there is no honest box-derived signal, and claiming one would be worse than saying so. x pairs with y and width pairs with height. Accepting one alone would mean inventing the other from the current value, which moves the element somewhere the caller did not ask for. The pairing rule and its minimum live in one `parsePair` helper rather than as four separate branches. * docs: document Studio's WebMCP agent tools, proven end-to-end in a browser (#3521) * docs: document Studio's WebMCP agent tools Adds `guides/webmcp`, under Developers > Agent setup. Its first job is to defuse a name collision. `guides/mcp` already exists and covers HeyGen's HOSTED MCP connector, which builds a video from a chat. This page is about an agent working inside Studio on a composition already open in front of you. Different feature, confusingly similar name, so the page says what it is not before it says what it is. Written to DOCS_GUIDELINES: one-sentence intro, outcome before implementation, real values rather than placeholders, and three callouts. The three things a reader most needs are the ones easiest to get wrong: The API is `document.modelContext`, not `navigator.modelContext`. Most published examples use the second, which is a polyfill compatibility shim rather than a spec member, so feature-detecting it misleads. Select first, then edit. Most editing tools act on the current selection, and an agent that skips it gets an error rather than a wrong-element write. Leave Studio visible. Some of Studio's write paths report failure through a toast rather than a return value, so the human is the one who sees it. That is a real property of the co-pilot design, not a nicety, so the page says it plainly. Verified with `npx mint validate` and `npx mint broken-links --check-redirects`, both passing. * fix(studio): target the text field that exists, not one named self Found by running the tools end to end in a browser, which is the only way it could have been found: the unit tests mock `setText`, so they never crossed the boundary where this breaks. An element's text usually lives in a CHILD field, keyed like `self:0:h1` or `child:0:h1`. `studio_set_text` passed no field key, so `buildNextDomTextFields` planned zero operations, the request went out with an empty patch, and the server answered: POST /api/projects/<id>/file-mutations/patch-element -> 400 {"error":"target and operations required"} Which surfaced as `persist-failed`. The tool was telling the truth, so the reporting work in the earlier PRs did its job, but the failure looked like a server problem and was not. The tool now resolves the field: the one the caller named, or the element's single field when it has exactly one. An element with several fields is asked to name one; an element with none is reported blocked. Naming a field the element does not have is rejected with the list of the ones it does have, rather than silently writing nowhere. Four regression tests, including the exact `child:0:h1` shape that failed. One existing assertion changed: it expected the field to be `undefined`, which is precisely the bug, so it now expects the resolved key. Also documents two things the browser run surfaced, both real and neither a defect: registration is asynchronous, so a caller reading `getTools()` too early sees a partial list; and the tools that act on the current selection need a render between the select and the edit, which a real agent gets for free because its calls arrive as separate messages. * docs: give the agent-tools kill switch instructions that work The page told readers to set agentToolsEnabled in Studio's preferences. Nothing writes that flag: it is read in useStudioAgentTools and parsed in studioUiPreferences, but there is no settings UI and no toggle, so the instruction could not be followed. Replace it with the localStorage write that actually flips it, and spell out the merge, since overwriting the key drops every other stored preference. * docs: do not promise a per-call permission prompt we have not verified The page said the browser asks before any agent calls a tool. Prompt granularity is browser-specific and unsettled during the origin trial, and we have not observed it on the native path. Say what holds, that access is gated, and name the part that is still moving. * fix(studio): re-apply WebMCP test polyfill fix (#3532 regression) The squash merge of #3518 re-introduced the old assertion that document.modelContext is absent. The polyfill from #3514 installs it as a fallback — that is expected behavior. Same fix as #3532: remove the assertion, keep the boot-cleanly contract. --------- Co-authored-by: miga-heygen <miguel.sierra_miga@heygen.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-08-31 14:45:09 -04:00
Felipe Caldas	f18964de0c	fix(studio): let a hidden sub-composition child be shown again (#3559) ... The eye on an expanded sub-composition child always rendered as "Hide", whatever the source said. One click hid the element and every click after that rewrote the same attribute, so the row could never be shown again, not even after a reload, since data-hidden is in the file. buildChildElements synthesizes a child row from a manifest clip with no element to read, and compensated by inheriting hidden/timelineLocked/ timelineRole/fxChain/automation from the child's flat store twin. That twin does not exist for a real sub-composition: processTimelineMessage drops any clip whose parent composition is itself in the manifest before building the flat store, so the lookup always missed and the inheritance was dead code for the one case it was written for. It worked only for a phantom-wrapper parent, where the child does keep a store entry. Read the state off the live element instead. collectSubCompositionHostState walks each sub-composition host in the preview document and records the data-* state of every id'd descendant, keyed by dom id. The existing sibling walk cannot serve this: it defines which rows exist and writes parentMap, and it stops at the first id'd descendant, so scene footage sitting one level below an id'd region wrapper is never reached. The new walk descends the whole subtree and touches neither rows nor parentage. Reproduced on a 9-scene storyboard project where every scene is a sub-composition. Before: a scene video and title carrying data-hidden both announced "Hide track N", and clicking left the file byte-identical. After: both announce "Show track N", and hide/show round-trips the attribute. A top-level clip with the same attribute always announced "Show", which is what made the gap specific to expanded child rows. The existing regression test passed throughout because its fixture hands the child a flat twin with hidden: true and gives the host no compositionSrc, so the child key falls back to the index.html scope and a twin can exist. The added test models a real sub-composition instead.	2026-08-31 17:23:47 +00:00
Miguel Ángel	f84b4c23dc	feat(studio): let an agent edit text and styles, guarded (#3518) ... * feat(studio): let an agent drive Studio's selection and playhead Adds `studio_select` and `studio_seek`, so an agent and the human are looking at the same element and the same instant. Selecting reveals the inspector, exactly as a click does, which is what makes the agent's move visible. Selection is shared state, not a per-call argument, and that is forced rather than chosen. Most of Studio's edit handlers read the ambient React selection, and `applyDomSelection` only schedules a state update, so selecting and committing inside ONE call would write to whatever was selected before. Two tool calls are separated by a render, so the contract is select first, then act. That is also how a human works: click, then type. `studio_seek` uses `requestSeek`, not `setCurrentTime`. The latter only moves the timeline's displayed number and leaves the composition where it was. Two things the tools refuse to fake: Seek does not clamp. `seek()` already clamps against the adapter's duration, which can differ from the store's, and clamping again would give that invariant two owners that can disagree. The tool reports where the playhead actually landed instead, read back afterwards. `requestSeek` is fire-and-forget, so it cannot report that no adapter was mounted to receive it. The tool compares the playhead before and after and fails rather than claiming a seek that never happened. Select separates three failures that a single message would have merged: the preview is not mounted yet (wait), no element matches the handle (re-read), and the element cannot be selected (try a neighbour). The agent's next move differs for each, so collapsing them would cost it a round trip or a retry loop. * feat(studio): give an agent eyes with studio_frame Renders the composition to a PNG at a given time and returns the URL. This is what turns the tool set from a remote control into a loop: author a change, capture the instant it affects, look, adjust. No agent can judge motion from source, because "what does this look like at 2.4 seconds" is not a question a file answers. Reuses Studio's existing capture endpoint via `buildFrameCaptureUrl` rather than inventing a second one. Two things this does not fake: It reports the time the playhead LANDED on, not the time requested. The player clamps, so those differ at the ends, and attaching the wrong time to a frame is how an agent draws a confident wrong conclusion about motion. It waits before capturing, by default 150ms. The frame is rendered from the file on disk, and the render cache is cleared by a file watcher with a 40ms write-stability threshold, so a capture that beats the watcher renders the PRE-edit composition. That exact staleness was a real bug here once. An agent reading a stale frame as "my edit failed" would thrash, so the wait is on by default, `settleMs` makes it tunable, and the tool description names the failure rather than leaving it to be rediscovered. It probes with HEAD before returning, so a URL that 404s comes back as a failure with a hint instead of as a link the agent cannot render. * feat(studio): add studio_inspect, so an agent reads before it writes Everything about one element in one call: resolved styles, text fields, box, data attributes, GSAP animations, and what the element will and will not accept. The point is to prevent a failed write rather than to satisfy curiosity. `can.reasonIfDisabled` is passed through verbatim from Studio's own capabilities, so an agent that reads first should never attempt an edit the element would refuse. Three things it refuses to get wrong: Animations are reported ONLY for the current selection, because that is the only element Studio parses them for. Attributing them to any other element would be reporting the wrong element's motion, which is worse than reporting none. When a handle names something else the field is empty and `animationEditingBlocked` says why. `animationEditingBlocked` also carries the two states where animation editing is off entirely, multiple timelines and an unsupported timeline pattern. Both live on the selection context. Learning them from a read costs one call; learning them from a failed write costs a retry loop. Inspecting a handle does NOT change what is selected. It is a read, and stealing the human's selection would be a side effect they did not ask for. There is a test asserting `applySelection` is never called. Nothing selected and no handle given is a failure, not an empty result. An empty result would assert "this element has nothing", which is a different and false claim. * feat(studio): let an agent edit text and styles, guarded The first tools that change the composition. Both act on the current selection and take no handle, which is forced rather than chosen: the handlers read the ambient React selection, and `applyDomSelection` only schedules a state update, so selecting and committing inside one call would write to whatever was selected before. Select first, then edit. Also plumbs the write-blocked state, which was the blocker for shipping any write at all. `domEditSaveQueuePaused` and the external-file conflict both lived on App and were unreachable from the tool surface, so `canWrite` was optimistic and a comment said so. They now derive into a single `writeBlockedReason` on the shell context: one field, one owner, conflict taking precedence because resolving it is what unblocks the queue. That guard matters more than it looks. Both states are BANNERS in Studio with no lock behind them, so nothing else was stopping a programmatic write from landing on top of a conflict the user had been asked to adjudicate. Three things the tools refuse to fake: They check the outcome, not the absence of a throw. Studio has several paths where a failed commit resolves anyway, so awaiting the handler proves nothing. The tagged outcome added earlier is what proves the write landed. A partial style result is reported as partial. `handleDomStyleCommit` is one property per call, so N properties are N commits; the result carries `applied` and `rejected` maps rather than a single boolean that would have to pick a side. Style commits run sequentially, never concurrently. Two commits racing through Studio's client-side read-modify-write can record undo entries that both claim the same starting content. There is a test that measures concurrency rather than trusting the loop. Every decline reason maps to a hint naming what to do instead, so a refusal routes the agent rather than just stopping it. * feat(studio): add studio_inspect, so an agent reads before it writes (#3517) Everything about one element in one call: resolved styles, text fields, box, data attributes, GSAP animations, and what the element will and will not accept. The point is to prevent a failed write rather than to satisfy curiosity. `can.reasonIfDisabled` is passed through verbatim from Studio's own capabilities, so an agent that reads first should never attempt an edit the element would refuse. Three things it refuses to get wrong: Animations are reported ONLY for the current selection, because that is the only element Studio parses them for. Attributing them to any other element would be reporting the wrong element's motion, which is worse than reporting none. When a handle names something else the field is empty and `animationEditingBlocked` says why. `animationEditingBlocked` also carries the two states where animation editing is off entirely, multiple timelines and an unsupported timeline pattern. Both live on the selection context. Learning them from a read costs one call; learning them from a failed write costs a retry loop. Inspecting a handle does NOT change what is selected. It is a read, and stealing the human's selection would be a side effect they did not ask for. There is a test asserting `applySelection` is never called. Nothing selected and no handle given is a failure, not an empty result. An empty result would assert "this element has nothing", which is a different and false claim. * feat(studio): move, resize and rotate, verified by reading back (#3519) `studio_transform` does what a drag does, and then checks. The box in the result is READ BACK after the write, never echoed from the request, and `applied` lists what actually took effect. That is not belt-and-braces. The plan for this unit said to re-derive the geometry handlers' behaviour rather than trust any description of them, and doing that turned up three different behaviours behind one interface. The handlers on `DomEditActionsValue` are the GSAP-AWARE wrappers, aliased in `useDomEditSession.ts:534-538`, not the CSS ones in `useDomGeometryCommits.ts` that an earlier note in this workstream described. `handleGsapAwarePathOffsetCommit` and `handleGsapAwareRotationCommit` are `if (gsapCommitMutation) { ...intercept... }` with no else branch. Their own comments say the absence is deliberate: position and rotation are written as GSAP code and there is no CSS fallback to write to. So they can return having done nothing. `handleGsapAwareBoxSizeCommit` is not like the other two. It runs through `runGestureTransaction` with separate scale and width/height routes, so resize works more generally. Reading back is what turns that middle case from a silent lie into a reported one. A move that did nothing comes back in `unchanged` with a reason. Three smaller decisions: Operations re-read between each other, so a move is judged against the box AFTER a resize in the same call. Comparing against the original would credit the resize's change to the move. Rotation is reported as dispatched, not verified. `rotate` is an individual transform property and does not appear in the computed transform, so there is no honest box-derived signal, and claiming one would be worse than saying so. x pairs with y and width pairs with height. Accepting one alone would mean inventing the other from the current value, which moves the element somewhere the caller did not ask for. The pairing rule and its minimum live in one `parsePair` helper rather than as four separate branches. --------- Co-authored-by: miga-heygen <miguel.sierra_miga@heygen.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-08-31 07:47:11 +00:00
Miguel Ángel	3337cc8990	feat(studio): give an agent eyes with studio_frame (#3516) ... * feat(studio): let an agent drive Studio's selection and playhead Adds `studio_select` and `studio_seek`, so an agent and the human are looking at the same element and the same instant. Selecting reveals the inspector, exactly as a click does, which is what makes the agent's move visible. Selection is shared state, not a per-call argument, and that is forced rather than chosen. Most of Studio's edit handlers read the ambient React selection, and `applyDomSelection` only schedules a state update, so selecting and committing inside ONE call would write to whatever was selected before. Two tool calls are separated by a render, so the contract is select first, then act. That is also how a human works: click, then type. `studio_seek` uses `requestSeek`, not `setCurrentTime`. The latter only moves the timeline's displayed number and leaves the composition where it was. Two things the tools refuse to fake: Seek does not clamp. `seek()` already clamps against the adapter's duration, which can differ from the store's, and clamping again would give that invariant two owners that can disagree. The tool reports where the playhead actually landed instead, read back afterwards. `requestSeek` is fire-and-forget, so it cannot report that no adapter was mounted to receive it. The tool compares the playhead before and after and fails rather than claiming a seek that never happened. Select separates three failures that a single message would have merged: the preview is not mounted yet (wait), no element matches the handle (re-read), and the element cannot be selected (try a neighbour). The agent's next move differs for each, so collapsing them would cost it a round trip or a retry loop. * feat(studio): give an agent eyes with studio_frame Renders the composition to a PNG at a given time and returns the URL. This is what turns the tool set from a remote control into a loop: author a change, capture the instant it affects, look, adjust. No agent can judge motion from source, because "what does this look like at 2.4 seconds" is not a question a file answers. Reuses Studio's existing capture endpoint via `buildFrameCaptureUrl` rather than inventing a second one. Two things this does not fake: It reports the time the playhead LANDED on, not the time requested. The player clamps, so those differ at the ends, and attaching the wrong time to a frame is how an agent draws a confident wrong conclusion about motion. It waits before capturing, by default 150ms. The frame is rendered from the file on disk, and the render cache is cleared by a file watcher with a 40ms write-stability threshold, so a capture that beats the watcher renders the PRE-edit composition. That exact staleness was a real bug here once. An agent reading a stale frame as "my edit failed" would thrash, so the wait is on by default, `settleMs` makes it tunable, and the tool description names the failure rather than leaving it to be rediscovered. It probes with HEAD before returning, so a URL that 404s comes back as a failure with a hint instead of as a link the agent cannot render. * feat(studio): add studio_inspect, so an agent reads before it writes (#3517) Everything about one element in one call: resolved styles, text fields, box, data attributes, GSAP animations, and what the element will and will not accept. The point is to prevent a failed write rather than to satisfy curiosity. `can.reasonIfDisabled` is passed through verbatim from Studio's own capabilities, so an agent that reads first should never attempt an edit the element would refuse. Three things it refuses to get wrong: Animations are reported ONLY for the current selection, because that is the only element Studio parses them for. Attributing them to any other element would be reporting the wrong element's motion, which is worse than reporting none. When a handle names something else the field is empty and `animationEditingBlocked` says why. `animationEditingBlocked` also carries the two states where animation editing is off entirely, multiple timelines and an unsupported timeline pattern. Both live on the selection context. Learning them from a read costs one call; learning them from a failed write costs a retry loop. Inspecting a handle does NOT change what is selected. It is a read, and stealing the human's selection would be a side effect they did not ask for. There is a test asserting `applySelection` is never called. Nothing selected and no handle given is a failure, not an empty result. An empty result would assert "this element has nothing", which is a different and false claim. --------- Co-authored-by: miga-heygen <miguel.sierra_miga@heygen.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-08-30 10:00:23 -07:00
Miguel Ángel	0e558d5916	feat(studio): let an agent drive Studio's selection and playhead (#3515) ... Adds `studio_select` and `studio_seek`, so an agent and the human are looking at the same element and the same instant. Selecting reveals the inspector, exactly as a click does, which is what makes the agent's move visible. Selection is shared state, not a per-call argument, and that is forced rather than chosen. Most of Studio's edit handlers read the ambient React selection, and `applyDomSelection` only schedules a state update, so selecting and committing inside ONE call would write to whatever was selected before. Two tool calls are separated by a render, so the contract is select first, then act. That is also how a human works: click, then type. `studio_seek` uses `requestSeek`, not `setCurrentTime`. The latter only moves the timeline's displayed number and leaves the composition where it was. Two things the tools refuse to fake: Seek does not clamp. `seek()` already clamps against the adapter's duration, which can differ from the store's, and clamping again would give that invariant two owners that can disagree. The tool reports where the playhead actually landed instead, read back afterwards. `requestSeek` is fire-and-forget, so it cannot report that no adapter was mounted to receive it. The tool compares the playhead before and after and fails rather than claiming a seek that never happened. Select separates three failures that a single message would have merged: the preview is not mounted yet (wait), no element matches the handle (re-read), and the element cannot be selected (try a neighbour). The agent's next move differs for each, so collapsing them would cost it a round trip or a retry loop.	2026-08-30 05:11:55 +00:00
Miguel Ángel	724796e2f0	chore: release v0.8.20 (#3555)	2026-08-30 00:31:08 -04:00
Miguel Ángel	28be8dddfa	fix(studio): correct save failure telemetry (#3499)	2026-08-30 00:24:46 -04:00
Miguel Ángel	0fd70b1d21	chore: release v0.8.19 (#3551)	2026-08-29 13:58:33 -04:00
Miguel Ángel	b71f45981c	fix(studio): export the composition the user has selected (#3550) ... The header's Export button started renders with no options at all, so the request carried no `composition` and the server fell back to index.html. Selecting a sub-composition in the Comps panel showed its canvas and timeline but exported the root file instead. Studio starts renders from three controls, and the render target was owned by each of them separately: the Renders panel resolved it, the header omitted it, the sidebar's per-composition button named one explicitly. Give it one owner in `startRender`, which all three route through, defaulting to the active composition and leaving an explicit argument to win. Fixes #3549	2026-08-29 13:54:27 -04:00
Miguel Ángel	5cc2f1bef5	chore: release v0.8.18	2026-08-29 15:38:26 +00:00
rajanpanth	adf9b0ccee	fix(studio): activate a composition at any path, not just compositions/ ... The Comps panel sets activeCompositionPath to the selected file, but useCompositionStack's effect only pushed a stack level when that path started with compositions/. A project laying its comps out anywhere else, for example a generated multi-part build with parts/part-1.html next to the root index.html, matched no branch at all: the row highlighted and the URL hash updated while the stack silently kept the master mounted, so the canvas and timeline stayed on index.html and any edit landed in the root file instead of the part. Replaced the prefix test with a plain truthiness check, so the root stays on the master level and every other path pushes its own level. Label derivation is unchanged, matching CompositionsTab's own convention.	2026-08-29 20:50:16 +05:45
miga-heygen	da6514d458	fix(studio): update WebMCP test for polyfill fallback ... The "registers nothing when the browser has no WebMCP" test asserted that document.modelContext was absent after mount. Since #3514 added the @mcp-b/global polyfill fallback, the hook now installs document.modelContext even when the browser has no native support — that is the polyfill's job. The real assertion is that mounting does not throw, which still holds. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-08-28 03:34:28 +00:00