feat(studio,cli): add an Edit with Framey button and hyperframes open for HyperFrames Studio

[WaterrrForever]

What

Point people from the CLI and the Studio preview to HyperFrames Studio, the desktop app (b249 is downloadable today at hyperframes.dev/studio/download).

Studio header — "Edit with Framey"

• A ghost button with Framey, the app's cursor mascot: the eye follows the pointer, a small wiggle on hover, a flight towards the app while it opens. All motion is off under reduced motion.
• A press shows a Meet Framey card (chat to change anything, draw on a frame, watch me act out each edit) with Get HyperFrames Studio → the download.
• Shown only where the preview server answers GET /api/open-in-desktop with available: true (macOS). The desktop app's embedded Studio has no such route, so the button never appears inside the app.
• Framey's colours are tokens in theme.css (--color-framey, --color-framey-ink).

CLI

• hyperframes open [dir] hands the project folder to the app with open -b (released app, then Canary). Run by Claude Code or Codex it leaves .hyperframes/agent-handoff.json (CLAUDE_CODE_SESSION_ID / CODEX_THREAD_ID) so the app's next chat can pick up that conversation. Exits 1 whenever nothing opened; --json answers in JSON for a bad directory too.
• render and preview print one line about the app. Nothing for a --quality draft render, a batch row, or a run inside the app (HYPERFRAMES_DESKTOP_PROJECT).

One gate until the app opens handed-over folders

The app learns to open a handed-over folder in hyperframes-internal#2601 (approved, not released). Until then HANDOFF_READY = false in packages/cli/src/utils/desktopApp.ts — the only copy:

• openInDesktop returns handoff-unavailable: nothing opens and nothing is written, so hyperframes open prints the download line and exits 1, and no hand-off file can wait for a later release.
• GET /api/open-in-desktop reports handoff: false; Studio's button reads it and only shows the Meet Framey card (no POST).
• render/preview print the download line.

Flipping it to true after that release makes the button open the project in the app and prints Edit it with Framey: hyperframes open . for people who have the app. Tests drive that live path through a ready option, so CI covers it today.

POST guard: POST /api/open-in-desktop answers only Studio's own same-origin request (loopback Host via identityAllowed, Origin equal to http://<host>, Sec-Fetch-Site: same-origin when present). A cross-site POST and a rebound-host POST both get 403 (server/desktopRoutes.test.ts).

Before

Header today (0.8.111), light and dark:

After

Header with Edit with Framey, and the Meet Framey card a press opens, light and dark:

Testing

• desktopApp.test.ts (16): gated path writes nothing; live path opens, falls back to Canary, tells not-installed from open-failed, skips non-macOS, still opens a read-only project with nothing handed over; hints for gated / missing / installed / in-app. Path-portable for Windows.
• desktopRoutes.test.ts (5): GET flags; cross-site and rebound-host POST → 403 and nothing opened; gated POST answers with the download; live POST opens this server's project.
• render/execute.test.ts: the hint is skipped for a draft and for a batch row (wantsDesktopHint, batchRowRenderOptions).
• Studio OpenInDesktopButton.dom.test.tsx (5, no skips): hidden without the route or off macOS; gated press shows the card and sends no POST; live press opens and toasts; live press with the app missing shows the card.
• The load smoke mocks the route. Full CLI suite: 288 files pass; fileWatcher.atomic fails the same way on main.
• By hand: Studio served by this branch's CLI at 1440×900 in both themes (captures above); the card fits with a one-line footer; no POST is sent while gated.

[github-actions]

Edit accuracy: accurate 1556 (base branch 1556), smooth 1430 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (0)

[jerrai-bot-heygen]

Changes requested at 58934a3. The code reads well, but four checks are red because of this PR, and the new POST route needs the same guard its neighbours have.

Blockers

1. Tests on windows-latest fail in desktopApp.test.ts:
   • openCommandFor returns films\a where the test expects films/a;
   • the desktopInstalled stub only knows the /Applications/... paths.
2. Studio: load smoke fails with unmocked API request: GET /api/open-in-desktop. The button probes the route on mount, and the smoke harness doesn't mock it.
3. Comments: studioServer.ts and the new desktopApp.ts raise the comment share above the gate.
4. Studio and player captures: the body has no Before/After for the new header button and the Meet Framey card.
5. POST /api/open-in-desktop (studioServer.ts:973) has no Host/Origin check. A bodiless cross-origin no-cors POST is a simple request, so any page that finds the localhost port can launch the app on the project and write agent-handoff.json. The impact is small, because the folder and the content are both fixed, but /api/telemetry-identity in the same file is already Host-guarded against DNS rebinding (identityAllowed). Gate this route the same way. It is also live today even though HANDOFF_READY = false.

On the stated gate: the hints and the Studio button are gated. hyperframes open is not: open.ts:25 calls openInDesktop directly, so on a Mac with the released app it runs open -b and writes the handoff file. That is fine if it's deliberate, but the description says the gate covers both surfaces.

Non-blocking

• mkdirSync/writeFileSync for the handoff file run unwrapped after the app has opened. A read-only project throws in the CLI and returns a 500 from the server.
• Any non-zero exit from open -b is reported as "not installed".
• HANDOFF_READY is defined in two files. A shared constant would keep the gate from going half-flipped.
• The tests branch on HANDOFF_READY, so CI never exercises the live path, and nothing tests the server route.

Checked and fine:

• open -b and mdfind are spawned with argument arrays and no shell;
• the hint is skipped for draft quality (render.ts:893/1147), for batch rows, and inside the app (HYPERFRAMES_DESKTOP_PROJECT).

— Jerrai

[jrusso1020]

Requesting changes. This adds to the existing review at this head, and I agree with its CI findings:

• the Windows path failures in desktopApp.test.ts, which are a required check;
• the missing Before/After for the captures check, also required;
• the load-smoke mock for GET /api/open-in-desktop;
• the missing Host/Origin guard on the POST.

1. hyperframes open isn't gated, and with today's app it says something that isn't true.

• open.ts:25 calls openInDesktop directly, so on a Mac with the released app it runs open -b and writes agent-handoff.json.
• It then prints "Opening X in HyperFrames Studio" and "Its chat picks up this Claude Code conversation." (open.ts:31-34).
• The released app doesn't handle a folder handed to it yet. That's the unreleased desktop change this gate waits for. So the app comes to the front without the project, and nothing reads the hand-off file.
• The command is also listed in root help (help.ts:30), so people and agents will find it before the gate flips.

Either gate open behind HANDOFF_READY the same way the hints are (print the download line and write nothing), or leave it out of help and change the wording until the gate flips.

2. A hand-off written now can be picked up much later. While gated, both hyperframes open and the POST route write .hyperframes/agent-handoff.json. The app release that reads it takes it once, on a project's next fresh chat. A file written today could then bring in a conversation from weeks earlier. The file isn't gitignored in user projects either, because init creates no .gitignore. Gating item 1 also fixes this for the CLI. The POST route needs the same treatment.

On the POST guard: I reproduced the missing guard with a throwaway test. A POST with Host evil.example:3002, Origin https://evil.example and Sec-Fetch-Site: cross-site returned 200 and called openInDesktop. A {dir:"/etc"} body was ignored, so the folder stays this server's project. The other review's guard (identityAllowed) fixes it.

Nits

• open exits 0 when the app isn't installed or the platform isn't supported, even with --json (open.ts:38-43). An agent can't tell from the exit code that nothing opened. I reproduced it on Linux: opened:false, exit 0.
• open --json on a bad directory prints the human error box, not JSON (open.ts:24 uses resolveProject). preview uses resolveProjectOrThrow under --json.
• No test covers the draft skip (render.ts:893, :1147) or the batch skip (render/execute.ts:368). Removing either one leaves all 144 render and desktop-hint tests green. The in-app skip is covered: removing it turns a test red.

What holds

• Both HANDOFF_READY constants gate what they cover. While gated, the button sends no POST. Removing its gate branch turns posts==0 red.
• The CLI hint never prints hyperframes open.
• The route is registered only in the CLI preview server, so the button stays hidden anywhere else.
• The hint goes to stdout, and only in human modes. render --quiet, batch --json and every preview --json branch skip it.

What I ran at 58934a34

• desktopApp.test.ts: 14/14.
• cli.commands.test.ts: 12/12. It has no assertion for open.
• OpenInDesktopButton + StudioHeader dom tests: 12 pass, 2 skipped by HANDOFF_READY.
• I didn't run anything on macOS. The "app ignores the folder" point comes from reading the desktop app's current main branch, which has no open-file handler. I didn't run it.

— Rames

[jerrai-bot-heygen]

Re-reviewed the delta 58934a3...e1016df. Every item from my changes-requested review is fixed:

• POST guard. sameOriginPost (desktopRoutes.ts:6) reuses identityAllowed for Host. When present, Sec-Fetch-Site must be same-origin and Origin must be http://<host>, so a cross-site or rebound-host POST gets 403 and open is never called (tested). A headerless loopback request such as curl is still accepted. That matches what identityAllowed is for (stopping a web page that reaches localhost by rebinding a domain name), so it is fine.
• One gate. HANDOFF_READY now exists only in desktopApp.ts. openInDesktop returns handoff-unavailable before it spawns anything or calls leaveHandoff, which is the only writer of agent-handoff.json. The route checks ready before open, GET reports handoff, and the button never POSTs while gated (asserted).
• Nits. Fixed: the exit code, JSON for a bad directory, not-installed vs open-failed, the read-only project case and the draft/batch hint tests. Windows paths, the smoke mock and the comment ratio are fixed too.

Still open, all small:

• The Studio and player captures check is red until the Before/After images are in the body.
• Windows engine-cli/studio-2 were still running at review time.
• open.ts itself has no test. The exit code and the --json bad-directory path are untested.
• expect(HANDOFF_READY).toBe(false) means the PR that flips the gate must edit that test.

— Jerrai

[jrusso1020]

Approve. This replaces my changes-requested review. Both of my points are fixed at e1016df4.

• hyperframes open is gated. openInDesktop returns handoff-unavailable before it spawns open or writes agent-handoff.json, and the command prints the download line. So no hand-off file can be written now and picked up by a later release. The POST route answers the same way while gated, and the button reads handoff from the GET, so there is one gate.
• The POST guard holds. sameOriginPost needs a loopback (or bound) Host, Sec-Fetch-Site same-origin when it is sent, and an Origin equal to http://<host>. A cross-site page, another localhost port, and a rebound host name all get 403.
• Nits fixed: open exits 1 when nothing opened, --json answers in JSON for a bad directory, and the draft and batch hint skips have a test.

Mutations, each one restored:

• ready check removed from openInDesktop: red, 2 fails.
• Origin check removed: red.
• Host check removed: red.
• Route gate removed: red.
• Button gate removed: red.

Tests at this head: desktopRoutes + desktopApp + render/execute 23/23. OpenInDesktopButton + StudioHeader dom tests 14/14.

CI: every required check is green except Studio and player captures, which waits on the Before/After in the body. A body edit isn't a push, so this approval still counts afterwards.

Nit, not blocking: three new comments point at a private repository's PR number and package paths (desktopApp.ts:12, FrameyGlyph.tsx:3, theme.css:439). A reader of this public repo can't follow them. Describing the behavior instead would read better.

I didn't run anything on macOS.

— Rames

[jrusso1020]

Re-approving at e09b7de2. My last approval was at e1016df4, and only two commits have landed since:

• 13cb249b, merge of main (32d2bc6f). No conflicts were resolved by hand. git merge-tree --write-tree e1016df4 32d2bc6f gives tree 5548c5de, which is exactly the merge commit's tree.
• e09b7de2. OpenInDesktopButton.tsx now uses studioApiFetch for both the GET and the POST to /api/open-in-desktop. This is what main's new oxlint rule requires. studioApiFetch only adds credentials (omit on loopback). The POST guard (sameOriginPost) checks Host, Origin and Sec-Fetch-Site, not cookies, so leaving cookies off doesn't change whether the guard accepts the request. Test mocks of globalThis.fetch still catch the call.

CI at this head: 66 pass, 0 failing. That includes regression, preview-regression, the timeline viewport gate, CodeQL and Windows render verification. The 20 edit-accuracy shards were still queued when I posted. Branch protection still gates the merge on them, and this delta doesn't touch editing.

— Rames