* fix(studio): an offline preview says GSAP could not load instead of an unhandled Event
* fix(studio): the preview error list survives a second capture attach without duplicates
* fix(studio): the console capture keeps listening after a long early error list
* refactor(studio): the console capture owns every reset of its findings
* test(studio): bundle the real-Chrome undo test with esbuild so its setup fits on Windows
* test(studio): stub only the Node built-ins the undo test bundle reaches
* feat(cli): catch up on what the desktop app did since a project was handed over
The desktop app records each chat turn in .hyperframes/app-history.jsonl.
`hyperframes catch-up [dir]` prints the turns since the hand-off or the last
catch-up (what the person asked, what Framey did, which files changed) plus
the project files changed since, by the app or by hand, then marks them seen.
`hyperframes open` and Studio's Edit with Framey mark the hand-off moment.
Any command run on a project with unseen turns ends with a line naming
catch-up, so an agent back in the terminal hears about it even when it
forgets. /hyperframes and /hyperframes-cli tell the agent to catch up as
soon as the person writes again.
* feat(cli): hand a Grok terminal session over to the desktop app
Grok gives every tool command its session as GROK_SESSION_ID (grok 1.0.4),
so `hyperframes open` and Edit with Framey now name a Grok session in
.hyperframes/agent-handoff.json, after Claude Code and Codex. The desktop
app reads its turns from Grok's own session files.
* feat(cli): tell a new project's agent to catch up after the desktop app
Scaffolded projects' CLAUDE.md and AGENTS.md now say to run
`npx hyperframes catch-up` before the next change once the project was
opened in the desktop app. Claude Code, Codex and Grok read these files on
their own, so a resumed session catches up even when it never loaded a
HyperFrames skill: a resumed Claude Code session that had not, asked to
change the title, ran catch-up first.
catch-up also prints each reply on one line.
* fix(cli): read and write .hyperframes records without following links, mark seen after showing
Review (Jerrai, Rames):
- One helper (projectRecords.ts) now reads and writes every record in
.hyperframes/. A linked folder is refused. A read opens once with
O_NOFOLLOW and checks the open file is a plain file, which clears the
CodeQL race. A write goes to a temp file renamed over the record, so a
link is replaced, never written through. agent-handoff.json, the seen
record and the history all go through it.
- catch-up marks a turn seen only after showing it, and only up to the
newest turn shown, so a turn written just after the read shows next
time. Changed files have their own "checked" time.
- Turns show only once the project was handed over from this machine, so
a history file shipped in a cloned repo is never shown as the person's
words. The end-of-command check skips reading when the history is
older than the seen record.
- The skills mention catch-up only when the CLI printed a line naming it,
so an older CLI never meets an unknown command.
- The notice test uses basename, which fixes Windows.
* feat(cli): add the catch-up line to an older project's instructions on hand-off
A project scaffolded before catch-up existed has no line telling its agent
to catch up, and a resumed session that never loaded a HyperFrames skill
then edits without knowing what happened in the app. When `hyperframes open`
or Edit with Framey hands such a project over, its scaffolded CLAUDE.md and
AGENTS.md (they start "# HyperFrames Composition Project") gain the
template's line, in the template's place. A file of the person's own, a
link, a missing file, or one that has the line is left alone. The file is
rewritten through a temp file with its mode kept. A test keeps the line the
same as the template's.
* fix(cli): keep catch-up's cursor in the person's home, never reset it, read without links on Windows
Review (Rames, Jerrai):
- The seen record moved from the project to ~/.hyperframes/catch-up/,
keyed by the project's real path. A seen file a cloned repo commits
can no longer make its history read as the person's words.
- A second hand-off (`open` again, or another Edit with Framey click)
keeps the cursor, so turns the app recorded meanwhile still show.
- Reads lstat the path, open it once, and refuse a file whose dev/ino
differs from what lstat saw. That holds where O_NOFOLLOW doesn't
exist, fixing the Windows test. The note writer reads the same way,
which clears the new CodeQL alert.
- Writes use core's replaceFileAtomically, which retries a rename that
Windows briefly refuses.
- catch-up names every changed file, and the cursor is the newest `at`
shown, not the last line's.
- `open --json` carries `catchUp` after a hand-off.
- The bin scripts are back to mode 644.
* fix(cli): open before checking for CodeQL, never show a turn dated ahead
Review (Rames, Jerrai):
- readPlainFile opens the file first, then requires lstat to find the same
plain file (dev/ino) at the path, and reads only through the fd. That is
just as safe, and it clears CodeQL's check-then-use alert.
- catch-up skips turns dated after the moment it reads. So a cloned history
can't show a far-future turn as the person's words or park the cursor
past real ones.
- The seen key uses core's realpath (realpathSync.native), so letter case
can't split a project in two. ~/.hyperframes/catch-up is made 0700, and
a hand-off that can't note itself says so.
- Tests stub HOME with vi.stubEnv and restore it.
* fix(studio-server): keep the desktop app's hand-off and chat history out of the file routes
The file and preview routes reach any path inside the project. The desktop
app keeps two files there that hold the person's agent session and their
chat: .hyperframes/agent-handoff.json and .hyperframes/app-history.jsonl.
No route now reads, writes, renames onto, duplicates or uploads over them,
by any spelling or through a link. The rest of .hyperframes/ (Studio's
motion file, prepared GIF assets) is served as before.
* fix(studio-server): keep the desktop app's run log out of the file routes too
The app records every chat run, the person's words included, in
.hyperframes/agent-runs.jsonl. Only the app's main process reads it.
* fix(studio-server): refuse everything under .hyperframes/ but Studio's own files
Review (Jerrai, Rames): a list of three names missed the read marks the
desktop app and the CLI also keep there, and renaming the folder reached
them under a new name. The check is now an allow-list: no route reaches
.hyperframes/ or anything in it, by any spelling or through a link, except
Studio's studio-motion.json, studio-manual-edits.json and prepared-assets/.
Studio's own internal files (backups, preview documents, history id) are
read by path inside the server, not through a request path.
The project's file tree leaves out the same paths. The upload test now
sends a file uploads accept elsewhere, so the folder is the only reason
it is refused.
* fix(studio-server): serve the app's request pictures, close the renders and rename paths
Review (Rames, Jerrai):
- Desktop loads each request's picture from .hyperframes/requests/ through
the preview route, so that folder joins the allow-list. An allowed
folder's own path is allowed too.
- The render-file route resolves against renders/, so a renders/ linked
into .hyperframes/ reached the records. It now also checks the file
against the project.
- A rename's reference update walked every JSON/MD file, records
included, and could rewrite them. It now skips private paths.
- The allow-list reuses STUDIO_MOTION_PATH and STUDIO_MANUAL_EDITS_PATH.
* chore(studio-server): keep render.ts's comment share at the base
* fix(studio-server): list, view and download only renders the render-file route would serve
Review (Jerrai, Rames): the render list found files in renders/ with join
and statSync, which follow links, and registered them for /render/:id/view
and /download, which read them with no check. A project shipping
renders/leak.mp4 -> ../.hyperframes/app-history.jsonl had its chat served.
The list now keeps an entry only when resolveWithinProject accepts it and
it isn't private, and registers the resolved path. View and download serve
only a plain file, so a link swapped in after the list is refused. This
predates the PR; it's the same shipped-link case.
Dockview keeps inactive "always"-rendered panel overlays in the DOM with
visibility:hidden and no position, so each one falls to its static position
below the dock at full dock height. That made the document ~2x the viewport
tall (1954px in a 997px window). body overflow:hidden only blocks user
scrolling, so the scrollIntoView that runs when a property group opens
scrolled the viewport 124px and cut off the header and panel tabs.
overflow:clip on #root (not hidden, which is itself programmatically
scrollable) removes the overflow: scrollHeight drops to the viewport height
and scrollIntoView on a hidden overlay no longer moves anything.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(core): namespace SVG ids in runtime-mounted compositions
* fix(core): keep SVG selectors and captured ids working after loaded scenes rename them
* chore(core): generated artifacts carry a plain do-not-edit banner
* test(catalog): record the font subsets the new scene-script installer requests
* test(catalog): keep earlier mirror recordings, as re-records only add
* test(studio): keep the undo socket gate's sockets pinned past Chrome's idle media suspend
* test(studio): the socket gate retries its video scan and says only what its pins prove
* docs(cli): map the pinned Sherpa runtime loading contract
* fix(cli): use a healthy pinned Sherpa copy beside the CLI
* chore(cli): keep runtime loader comments within the ratchet
* docs(cli): wrap the runtime contract palette declarations
* chore(cli): keep the Sherpa contract note out of the repo
* fix(catalog): 3D previews load their scripts under the docs host's script policy
* fix(catalog): preserve script text through HTML parsing
* docs(catalog): describe the shared script bundle
* test: pin the guards that keep script-placed scenes and unparseable scripts out of the in-place move
* test: make the script-placed scene check able to fail and pin its page order
* fix(parsers): dragging a keyframe keeps the keyframes' ease
* fix(parsers): splitting a keyframed tween into groups keeps its eases
* fix(studio): keyframed tweens keep their eases when Studio rewrites them
Extending a keyframed tween to the playhead and merging a gesture recording into it now carry the tween's eases and each keyframe's own ease. The parsers no longer report a tween-level easeEach, which GSAP ignores, as the keyframes' ease.
* fix(studio): a gesture merged into a tween writes rounded keyframe percentages
* fix(studio): a gesture merged into an eased tween plays at the times it was recorded
Merged keyframes are placed through the tween's run ease, as the extend path already does, and recorded constant-speed segments stay linear.
* fix(studio): the ease card describes a keyframed tween by its keyframes and eases
The summary line read 'no properties yet using a none curve' for every keyframed tween. It now names the keyframed properties, the keyframe count, the segment ease and the run ease that GSAP plays.
* fix(studio): a gesture merged over a strong ease-out keeps its keyframes and the ones before it
The merge keeps or replaces old keyframes by when they play, and rounds percentages only when the run ease does not warp time.
* fix(studio): the ease card labels an unset segment with the ease GSAP plays
* fix(studio): the ease card header shows the segment ease its rows play
The header shows the one ease every segment plays, or Mixed, and a run ease other than none gets its own line.
* fix(parsers): keyframe percentages are written as decimal keys the parsers read back
A percentage below 1e-6 printed as '1.28e-7%', which both parsers reject. One plainPercentKey owner now writes every percentage key in both writers and the unroller.
* fix(studio): the ease card's segment rows show rounded percentages
The three adapter skill had no guidance for camera cuts made inside one
canvas. A visibility window written as its own literal near a cut shows
the next shot's objects for the last frames of the previous shot, a
two-frame pop-in that a still per shot does not reveal. The skill now
says to declare each cut once, read it in both the shot selector and
every visibility window, and snapshot the last frame before each cut.
It also explains why a MeshStandardMaterial lit by a single key light
renders as a flat black cutout when the camera faces that light, and to
add a fill such as a HemisphereLight driven at a fixed ratio to the key.
Signed: Miga
Co-authored-by: Miguel Ángel <miguel.sierra@heygen.com>
* fix(studio): a size edit right after a resize is its own undo step
* fix(studio): a nudge still saving is recorded before the next edit
* fix(studio): published types name cn by its package, not a node_modules path
* fix(studio): drop baseUrl so declarations never name a node_modules path
* fix(studio): an edit started inside the save of another edit never flushes
* fix(studio): an edit made while a nudge is still saving writes after it
* fix(studio): a later edit never overtakes one still waiting on a nudge save
* fix(studio): undoing a gsap.set clears what it applied from the preview
* fix(studio): an edit never waits on itself behind a nudge save
* fix(studio): a second nudge burst saves when its commit runs behind the first
* fix(studio): undoing a W on an animated box clears the width it set live
* fix(studio): any GSAP edit that drops a live-applied set clears it from the preview
* fix(studio): a soft reload clears exactly the set props a live patch applied
* fix(studio): name width and height as set-patch props
* fix(studio): Layers rows show a kind icon, and only a group's row has a caret
Rows show what an element is (image, video, audio, vector, group, text or shape) instead of the tag's first letters. The caret column sits only on rows with children, a group's children indent under its icon, and rows are inset with rounded corners so the selection reads centred.
* style(studio): name the Layers indent and phrasing tags instead of commenting them
* refactor(studio): Layers text and host checks reuse the editor's own rules
* fix(studio): a Layers child's icon starts where its parent's label starts
* refactor(studio): Layers text icon uses the inline editor's text check
* fix(studio): a Layers row with children shows the group icon, and its icon keeps the row's hint
* fix(studio): Layers text with styled spans keeps the Text icon
* fix(engine): a render fails when a composition script throws before its timeline binds
* fix(engine): an unrelated page error no longer fails a render whose timeline registers late
* fix(engine): only the composition's own scripts fail a render, local or distributed
* style(engine): format the script failure change
* fix(engine): a third-party browser rejection no longer fails a render
* refactor(engine): one page URL for navigation and error attribution
* fix(engine): a rejection after a hash change or in an iframe no longer fails a render
* fix(engine): a widget's error no longer fails a render once its script is inlined
* fix(core): name injected and inlined scripts without building code from library input
* fix(engine): a third-party embed's eval or inserted script no longer fails a render
* fix(producer): a widget's inline handler or a sub-composition no longer misreports a render
* refactor(engine): read each script response once and keep comments within 120 characters
* fix(engine): a scene that throws after registering its timeline no longer cuts a render short
* fix(engine): a composition script failure names the error and its real cause
* fix(engine): a failed VFX chain fails the render at once instead of shipping a missing layer
* fix(core): a VFX layer that is empty on one frame renders empty instead of failing or going stale
* fix(core): a VFX layer that grows from zero size renders instead of staying missing
* fix(core): a VFX layer hidden or late while empty renders once it has a size
* test(producer): cover a VFX layer that is 0×0 under a host that starts later
* test(producer): pin both VFX 0×0 marks, with a GSAP-shaped wipe and a real late host
* test(producer): a late VFX host with a GSAP wipe catches a walk that skips hidden hosts
* fix(core): a sub-composition follows its host clip when the host moves without a reload
* perf(studio): move live tweens in place for a sub-composition host's clip too
* fix(core): keep sub-compositions nested where a fresh load nests them across rebinds and re-runs
* fix(studio): match the preview's re-printed script by its tokens and check every other timeline
* fix: compare preview scripts by syntax tree and keep scenes a re-run script places
* fix(parsers): keep a tagged template's raw text and a __proto__ key in the script compare
* fix(parsers): keep only a tagged template's raw text in the script compare
* perf(studio): read each preview script once across repeat timeline drags
* style(studio): format the preview script read test
* perf(studio): keep only script shapes and refresh them on reuse
* test(studio): bench a plain element animated through auto-record and Add keyframe
* fix(studio): seed a first tween from the offset a plain move left in CSS translate
* test(studio): bench resize then drag on a GSAP tween, root and nested
* fix(studio): a resize under auto-record keys size at the playhead, held at all times
* fix(studio): keyframe tweens Studio writes end on their last key, so a seek matches playback
* test(studio): keep the plain-to-keyframes moves inside the nested frame
* fix(studio): a resize moves its anchor from the drag stamp it read at release
* fix(studio): an undo shown in place is no longer replaced by an older reload
* refactor: split the trailing keyframe trim and drop an unused GSAP reader
* test(studio): settle the resize-then-drag bench steps so a two-save resize is one undo
* fix(studio): a preview reload waits for an undo shown before its write lands
* fix(studio): Add keyframe reads a subtracted calc() translate with its sign
* refactor: tidy the keyframe hold, trim and resize code after review
* fix(parsers): the keyframe trim leaves looping, chained and relatively placed tweens alone
* fix(parsers): a size hold pins only a lone key, so an edit never changes frames left alone
* fix(studio): every undo applied in place counts as a preview change, script-only ones too
* fix(studio): a resize keys size only when a move or size is keyframed, not a fade
* test(studio): a bench step whose save never lands fails the case
* fix(parsers): holds and trims change only the tweens an edit touches
* test(studio): bank the plain-to-keyframes and resize-then-drag bench cases
* docs: add Studio app pages for getting started with the Mac app
Six short pages in a new Studio app tab: get the app, connect Claude Code or Codex, make your first video, change it with the agent, export, and updates and troubleshooting. Screenshots come from a neutral fixture project.
* docs: cover Linux in the Studio app pages
The app ships a Linux AppImage beside the Mac app. Install steps get Mac and Linux tabs, platform labels name both, and troubleshooting lists where projects, settings and exports live.
* docs: correct Studio app sign-in, install and edit details
First launch asks for HeyGen sign-in on the first click; the Mac download is a disk image with an installer inside; Select shows Prompt to edit; the Connect screen sends the waiting request itself; billing, export quality and update wording match the app. Open Terminal is described for both systems.
* docs: keep Studio app tables readable on phones
Three-column tables scrolled sideways at 390 px and the data-folder table broke paths mid-word; they become two-column tables and a short list.
* docs: quote Studio app messages without their periods
Quoted UI text no longer carries its own period into a sentence or table cell, and the Mac install step says the HeyGen check can take a minute or two.
* docs: match Studio app installer and update messages
Quote the installer's HeyGen check, damaged-download and slow-check messages, and the stalled-update messages with Download it instead and Settings' Download the latest version.
* docs: fix Studio app sign-in timeout and Codex setup wording
* docs: name Framey's stuck-update line in Studio app troubleshooting
* docs: use one Studio app message per update state
A stalled update says 'The update is taking longer than it should' and a failed one 'The update didn't finish', in Framey's line and on the card alike; Try again starts the update over.
* docs: say Try again starts a new update, not one from zero
* fix(studio): a row move restacks only the clip you moved, so nothing else goes behind
Moved up, the clip rises above the clips it overlaps on the rows now below it; moved down, it
sinks below the ones now above it, never under z-index 0. Neighbours keep their z, so a
full-frame scene on the top row no longer jumps over a caption moved up a row beneath it.
* refactor(studio): stacking sync comments match the moved-clip-only rule
Drops the stale cascade wording, checks the time overlap before the paint-scope string compare,
and every test case names its move direction.
* fix(studio): a row move restacks only the dragged clip and a move down never hides it
Selected clips that only shifted in time keep their z-index. A move down stops at the clips on
lower rows it paints over, instead of dropping under them when z-index 0 cannot get it behind
the clip above.
* style(studio): drop a comment the drag commit's doc already covers
* feat(studio): a host can hold playback so nothing starts while it is held
* feat(studio): a held player seeks without scrub audio
* fix(studio): a held player neither loops nor changes speed on J and L
* fix(studio): pause clears playing even before the preview has a player
* chore(studio): keep the play hold's comment share flat
* refactor(studio): keep the play hold out of seek's and the subscription's branches
* test(studio): a timeline reset keeps the host's play hold
* fix(studio): a host can claim its writes under the key Studio's edit history uses
* fix(studio): drop the claimKey comment, the comment share may not rise
* feat(studio): a host app can mount the Layers panel outside Studio
LayersPanel is exported from @hyperframes/studio with an optional host prop carrying the preview iframe, active composition, toast, timeline elements and playing state. Studio's own mount still reads its contexts.
* fix(studio): a layer reorder no longer moves timeline rows a host cannot save
Without a TimelineEditProvider the z-order lane mirror changed the clip's row in the store only, unsaved. It now skips the mirror there. LayersPanelHost is built from Studio's context types.
* chore(studio): keep the lane mirror's comment share flat
Miguel Ángel