Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
feat(studio,cli): add an Edit with Framey button and `hyperframes open` for HyperFrames Studio (#4951)
WaterrrForeverbd0dc8c3aeb0
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.tsindex 00a6c4bb0b..75e7886369 100644--- a/packages/cli/src/cli.ts+++ b/packages/cli/src/cli.ts@@ -129,6 +129,7 @@ const commandLoaders = {preview: () =>assertStudioWorkspaceBuilt().then(() => import("./commands/preview.js").then((m) => m.default)),publish: () => import("./commands/publish.js").then((m) => m.default),+ open: () => import("./commands/open.js").then((m) => m.default),render: () => import("./commands/render.js").then((m) => m.default),lint: () => import("./commands/lint.js").then((m) => m.default),check: () => import("./commands/check.js").then((m) => m.default),diff --git a/packages/cli/src/commands/open.ts b/packages/cli/src/commands/open.tsnew file mode 100644index 0000000000..db60152319--- /dev/null+++ b/packages/cli/src/commands/open.ts@@ -0,0 +1,66 @@+import { defineCommand } from "citty";+import type { Example } from "./_examples.js";+import { c } from "../ui/colors.js";+import { setCommandExitCode } from "../utils/commandResult.js";+import { DOWNLOAD_HINT, openInDesktop, type DesktopOpenResult } from "../utils/desktopApp.js";+import { resolveProject, resolveProjectOrThrow, type ProjectDir } from "../utils/project.js";++export const examples: Example[] = [+ ["Open this project in HyperFrames Studio", "hyperframes open"],+ ["Open another project", "hyperframes open ./my-video"],+ ["For agents", "hyperframes open --json"],+];++const WHY_NOT: Record<Extract<DesktopOpenResult, { opened: false }>["reason"], string | null> = {+ "handoff-unavailable": null,+ "unsupported-platform": "Opening a project from the CLI works on macOS only.",+ "not-installed": "HyperFrames Studio isn't installed on this Mac.",+ "open-failed": "macOS couldn't open HyperFrames Studio.",+};++function printResult(project: ProjectDir, result: DesktopOpenResult): void {+ if (result.opened) {+ console.log(`${c.success("◇")} Opening ${c.accent(project.name)} in HyperFrames Studio`);+ if (result.handedOver) {+ const agent = result.handedOver.engine === "claude" ? "Claude Code" : "Codex";+ console.log(` ${c.dim(`Its chat picks up this ${agent} conversation.`)}`);+ }+ return;+ }+ const why = WHY_NOT[result.reason];+ if (!why) return console.log(`${c.warn("◇")} ${DOWNLOAD_HINT}`);+ console.log(`${c.warn("◇")} ${why}`);+ console.log(` Download it: ${c.accent(result.downloadUrl)}`);+}++/** Under --json a bad directory answers in JSON too, not with the human error box. */+function projectForJson(dir: string | undefined): ProjectDir | null {+ try {+ return resolveProjectOrThrow(dir);+ } catch (error) {+ const message = error instanceof Error ? error.message : String(error);+ console.log(JSON.stringify({ ok: false, error: { code: "invalid-project", message } }));+ setCommandExitCode(1);+ return null;+ }+}++export default defineCommand({+ meta: { name: "open", description: "Open a project in HyperFrames Studio, the desktop app" },+ args: {+ dir: {+ type: "positional",+ description: "Project directory (default: current)",+ required: false,+ },+ json: { type: "boolean", description: "Output as JSON", default: false },+ },+ run({ args }) {+ const project = args.json ? projectForJson(args.dir) : resolveProject(args.dir);+ if (!project) return;+ const result = openInDesktop(project.dir);+ if (!result.opened) setCommandExitCode(1);+ if (args.json) console.log(JSON.stringify({ project: project.dir, ...result }, null, 2));+ else printResult(project, result);+ },+});diff --git a/packages/cli/src/commands/preview.ts b/packages/cli/src/commands/preview.tsindex a134b2615a..4e29f45d10 100644--- a/packages/cli/src/commands/preview.ts+++ b/packages/cli/src/commands/preview.ts@@ -39,6 +39,7 @@ import { fileURLToPath } from "node:url";import { createRequire } from "node:module";import * as clack from "@clack/prompts";import { c } from "../ui/colors.js";+import { desktopHint } from "../utils/desktopApp.js";import { isDevMode } from "../utils/env.js";import { normalizeErrorMessage as errorMessage } from "../utils/errorMessage.js";import { buildNpxCommand } from "../utils/npxCommand.js";@@ -365,7 +366,7 @@ export default defineCommand({);return;}- printStudioSummary(project.name, previewBaseUrl(status.port), {+ printStudioSummary(project.name, previewBaseUrl(status.port), project.dir, {details: [`Background preview running (PID ${status.pid}).`, `Log: ${status.logPath}`],});return;@@ -539,7 +540,7 @@ export default defineCommand({);} else {clack.intro(c.bold("hyperframes preview"));- printStudioSummary(projectName, url, {+ printStudioSummary(projectName, url, dir, {details: [background.type === "reused"? "Reusing the background server already running for this project."@@ -1282,6 +1283,7 @@ function openStudioBrowser(url: string, projectName: string, options?: BrowserLafunction printStudioSummary(projectName: string,serverUrl: string,+ projectDir: string,opts: { details?: string[]; footer?: string } = {},): void {const urls = studioSummaryUrls(projectName, serverUrl);@@ -1289,6 +1291,8 @@ function printStudioSummary(console.log(` ${c.dim("Project")} ${c.accent(projectName)}`);console.log(` ${c.dim("Studio")} ${c.accent(urls.studioUrl)}`);console.log(` ${c.dim("Server")} ${c.accent(urls.serverUrl)}`);+ const hint = desktopHint(projectDir);+ if (hint) console.log(` ${c.dim("Desktop")} ${hint}`);console.log();for (const detail of opts.details ?? []) {console.log(` ${c.dim(detail)}`);@@ -1395,7 +1399,7 @@ function attachStudioReadyHandler();} else {spinner.stop(c.success("Studio running"));- printStudioSummary(projectName, url, {+ printStudioSummary(projectName, url, projectDir, {footer: "Press Ctrl+C to stop",});}@@ -1629,7 +1633,7 @@ async function runEmbeddedMode();} else {s.stop(c.success("Already running"));- printStudioSummary(pName, url, {+ printStudioSummary(pName, url, dir, {details: ["Reusing existing server. Use --force-new to start a fresh instance."],});}@@ -1647,7 +1651,7 @@ async function runEmbeddedMode(console.log(` ${c.warn(`Port ${startPort} is in use, using ${result.port} instead`)}`);console.log();}- printStudioSummary(pName, url, {+ printStudioSummary(pName, url, dir, {details: ["Edit with your AI agent — it has HyperFrames skills installed.","Changes reload automatically in the studio.",diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.tsindex df47984c8a..e6fed5043c 100644--- a/packages/cli/src/commands/render.ts+++ b/packages/cli/src/commands/render.ts@@ -62,6 +62,7 @@ import { resolve, dirname, join, basename } from "node:path";import { execFileSync, spawn } from "node:child_process";import { loadProducer } from "../utils/producer.js";import { c } from "../ui/colors.js";+import { desktopHint } from "../utils/desktopApp.js";import {formatBytes,formatRenderSummaryDetail,@@ -524,6 +525,8 @@ export interface RenderOptions {throwOnError?: boolean;/** Skip the interactive feedback prompt after a successful render. */skipFeedback?: boolean;+ /** False for a batch row: one line about the desktop app per batch is noise, not a pointer. */+ desktopHint?: boolean;/*** OPT IN to managing the DE parallel-router circuit breaker* (`applyDeParallelRouterCircuitBreaker`) for this render. Default OFF —@@ -886,6 +889,8 @@ async function renderDocker(runPostRenderStep("printRenderComplete", () =>printRenderComplete({outputPath,+ projectDir,+ desktopHint: wantsDesktopHint(options),elapsedMs: elapsed,quiet: options.quiet,format: options.format,@@ -1138,6 +1143,8 @@ async function executeLocalRender(runPostRenderStep("printRenderComplete", () =>printRenderComplete({outputPath,+ projectDir,+ desktopHint: wantsDesktopHint(options),elapsedMs: elapsed,quiet: options.quiet,format: options.format,@@ -1898,8 +1905,16 @@ function readOutputFootprint(outputPath: string): { fileSize: string; isDirector}}+/** A delivered render points to the desktop app; a draft or a batch row does not. */+export function wantsDesktopHint(options: Pick<RenderOptions, "desktopHint" | "quality">): boolean {+ return options.desktopHint !== false && options.quality !== "draft";+}+function printRenderComplete(input: {outputPath: string;+ projectDir: string;+ /** Print the desktop-app line: a delivered render, never a draft or a batch row. */+ desktopHint: boolean;elapsedMs: number;quiet: boolean;format: RenderFormat;@@ -1920,6 +1935,8 @@ function printRenderComplete(input: {console.log(c.success("\u25C7") + " " + c.accent(outputPath));console.log(" " + c.bold(fileSize) + c.dim(" \u00B7 " + detail));if (perf) printRenderPipeline(perf, input.requestedGpuMode);+ const hint = input.desktopHint ? desktopHint(input.projectDir) : null;+ if (hint) console.log(" " + c.dim(hint));}function printRenderPipeline(diff --git a/packages/cli/src/commands/render/execute.test.ts b/packages/cli/src/commands/render/execute.test.tsindex 82a94bb492..075c3f79a7 100644--- a/packages/cli/src/commands/render/execute.test.ts+++ b/packages/cli/src/commands/render/execute.test.ts@@ -3,7 +3,8 @@ import { tmpdir } from "node:os";import { join } from "node:path";import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import { createRenderPlan } from "./plan.js";-import { renderOptionsFromPlan } from "./execute.js";+import { batchRowRenderOptions, renderOptionsFromPlan } from "./execute.js";+import { wantsDesktopHint } from "../render.js";describe("renderOptionsFromPlan", () => {let projectDir: string;@@ -40,3 +41,19 @@ describe("renderOptionsFromPlan", () => {expect(on.variables).toEqual({ title: "x" });});});++describe("the desktop-app line after a render", () => {+ it("comes after a delivered render, never after a draft or a batch row", () => {+ expect(wantsDesktopHint({ quality: "high" })).toBe(true);+ expect(wantsDesktopHint({ quality: "draft" })).toBe(false);+ expect(wantsDesktopHint({ quality: "high", desktopHint: false })).toBe(false);+ const projectDir = mkdtempSync(join(tmpdir(), "hf-render-batch-"));+ try {+ writeFileSync(join(projectDir, "index.html"), '<main data-composition-id="main"></main>');+ const row = batchRowRenderOptions(createRenderPlan({ dir: projectDir }), undefined);+ expect(wantsDesktopHint(row)).toBe(false);+ } finally {+ rmSync(projectDir, { recursive: true, force: true });+ }+ });+});diff --git a/packages/cli/src/commands/render/execute.ts b/packages/cli/src/commands/render/execute.tsindex a929c16ca7..f85a55cbe5 100644--- a/packages/cli/src/commands/render/execute.ts+++ b/packages/cli/src/commands/render/execute.ts@@ -320,16 +320,12 @@ async function runResolutionPreflight(failCommand();}-async function executeBatchRender(+export function batchRowRenderOptions(plan: RenderPlan,browserPath: string | undefined,- batchModule: typeof import("../batchRender.js"),- preparedBatch: import("../batchRender.js").PreparedBatchRender,- dependencies: RenderExecutionDependencies,- cancellation?: RenderCancellationScope,-): Promise<void> {+): RenderOptions {const batchQuiet = plan.quiet || plan.batchJson;- const renderOptionsBase: RenderOptions = {+ return {fps: plan.fps,quality: plan.quality,authoringSkill: plan.authoringSkill,@@ -365,8 +361,21 @@ async function executeBatchRender(exitAfterComplete: false,throwOnError: true,skipFeedback: true,+ desktopHint: false,manageDeParallelRouterBreaker: plan.batchConcurrency <= 1,};+}++async function executeBatchRender(+ plan: RenderPlan,+ browserPath: string | undefined,+ batchModule: typeof import("../batchRender.js"),+ preparedBatch: import("../batchRender.js").PreparedBatchRender,+ dependencies: RenderExecutionDependencies,+ cancellation?: RenderCancellationScope,+): Promise<void> {+ const batchQuiet = plan.quiet || plan.batchJson;+ const renderOptionsBase = batchRowRenderOptions(plan, browserPath);const manifest = await batchModule.runBatchRender({prepared: preparedBatch,concurrency: plan.batchConcurrency,diff --git a/packages/cli/src/help.ts b/packages/cli/src/help.tsindex 236c919cd4..34769aa7a8 100644--- a/packages/cli/src/help.ts+++ b/packages/cli/src/help.ts@@ -27,6 +27,7 @@ const GROUPS: Group[] = [["present", "Open a slideshow deck in presenter mode (with audience sync)"],["publish", "Upload a project to a stable URL (private by default)"],["render", "Render a composition to MP4 or WebM"],+ ["open", "Open a project in HyperFrames Studio, the desktop app"],],},{diff --git a/packages/cli/src/server/desktopRoutes.test.ts b/packages/cli/src/server/desktopRoutes.test.tsnew file mode 100644index 0000000000..1fce187970--- /dev/null+++ b/packages/cli/src/server/desktopRoutes.test.ts@@ -0,0 +1,64 @@+import { Hono } from "hono";+import { describe, expect, it, vi } from "vitest";+import type { DesktopOpenResult } from "../utils/desktopApp.js";+import { mountDesktopRoutes, sameOriginPost } from "./desktopRoutes.js";++const STUDIO = {+ host: "localhost:3002",+ origin: "http://localhost:3002",+ "sec-fetch-site": "same-origin",+};+const OPENED: DesktopOpenResult = {+ opened: true,+ bundleId: "dev.hyperframes.desktop",+ handedOver: null,+};++function server(ready: boolean) {+ const app = new Hono();+ const open = vi.fn((_dir: string): DesktopOpenResult => OPENED);+ mountDesktopRoutes(app, "/films/a", { ready, open });+ const post = (headers: Record<string, string>) =>+ app.request("/api/open-in-desktop", { method: "POST", headers });+ return { app, open, post };+}++describe("open-in-desktop routes", () => {+ it("tells Studio whether to show the button and whether the app can take the project", async () => {+ const body = await (await server(false).app.request("/api/open-in-desktop")).json();+ expect(body).toEqual({ available: process.platform === "darwin", handoff: false });+ });++ it("refuses a POST from another site, or through a rebound host name", async () => {+ const { open, post } = server(true);+ const crossSite = { ...STUDIO, origin: "https://evil.example", "sec-fetch-site": "cross-site" };+ expect((await post(crossSite)).status).toBe(403);+ expect(+ (await post({ ...STUDIO, host: "evil.example:3002", origin: "http://evil.example:3002" }))+ .status,+ ).toBe(403);+ expect(open).not.toHaveBeenCalled();+ });++ it("while gated, answers Studio's own POST with the download and opens nothing", async () => {+ const { open, post } = server(false);+ const res = await post(STUDIO);+ expect(await res.json()).toMatchObject({ opened: false, reason: "handoff-unavailable" });+ expect(open).not.toHaveBeenCalled();+ });++ it("once live, opens this server's project for Studio's own POST", async () => {+ const { open, post } = server(true);+ expect(await (await post(STUDIO)).json()).toEqual(OPENED);+ expect(open).toHaveBeenCalledWith("/films/a");+ });+});++describe("sameOriginPost", () => {+ it("lets a local process without browser headers through, never a foreign origin", () => {+ expect(sameOriginPost({ host: "127.0.0.1:3002" })).toBe(true);+ expect(sameOriginPost({ host: "localhost:3002", origin: "http://localhost:3003" })).toBe(false);+ expect(sameOriginPost({ host: "localhost:3002", fetchSite: "same-site" })).toBe(false);+ expect(sameOriginPost({})).toBe(false);+ });+});diff --git a/packages/cli/src/server/desktopRoutes.ts b/packages/cli/src/server/desktopRoutes.tsnew file mode 100644index 0000000000..43a16ebe08--- /dev/null+++ b/packages/cli/src/server/desktopRoutes.ts@@ -0,0 +1,41 @@+import type { Hono } from "hono";+import { DESKTOP_DOWNLOAD_URL, HANDOFF_READY, openInDesktop } from "../utils/desktopApp.js";+import { identityAllowed } from "./telemetryIdentity.js";++/** A bodiless POST is a simple request, so any page can send one to localhost: it has to come from this Studio. */+export function sameOriginPost(headers: {+ host?: string;+ origin?: string;+ fetchSite?: string;+}): boolean {+ const { host, origin, fetchSite } = headers;+ if (!host || !identityAllowed(host)) return false;+ if (fetchSite && fetchSite !== "same-origin") return false;+ return origin === undefined || origin === `http://${host}`;+}++/** Studio's Edit with Framey: the GET says whether to show it (macOS) and whether the app can take the project. */+export function mountDesktopRoutes(+ app: Hono,+ projectDir: string,+ { ready = HANDOFF_READY, open = openInDesktop } = {},+): void {+ app.get("/api/open-in-desktop", (c) =>+ c.json({ available: process.platform === "darwin", handoff: ready }),+ );+ app.post("/api/open-in-desktop", (c) => {+ const allowed = sameOriginPost({+ host: c.req.header("host"),+ origin: c.req.header("origin"),+ fetchSite: c.req.header("sec-fetch-site"),+ });+ if (!allowed) return c.json({ error: "forbidden" }, 403);+ if (!ready)+ return c.json({+ opened: false,+ reason: "handoff-unavailable",+ downloadUrl: DESKTOP_DOWNLOAD_URL,+ });+ return c.json(open(projectDir));+ });+}diff --git a/packages/cli/src/server/studioServer.ts b/packages/cli/src/server/studioServer.tsindex 7a40bae3ac..e1acf8f2ec 100644--- a/packages/cli/src/server/studioServer.ts+++ b/packages/cli/src/server/studioServer.ts@@ -32,6 +32,7 @@ import {resolveCliTelemetryDistinctId,} from "./telemetryIdentity.js";import { emitStudioRenderComplete, emitStudioRenderError } from "./studioRenderTelemetry.js";+import { mountDesktopRoutes } from "./desktopRoutes.js";import { isDevMode } from "../utils/env.js";import { runRenderSetupWorker } from "../utils/cancellableProcess.js";import type { ProjectLintResult } from "@hyperframes/lint";@@ -966,6 +967,8 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {});});+ mountDesktopRoutes(app, projectDir);+// ── Pre-flight checks for render ────────────────────────────────────────// Intercept render requests before they reach the shared API so we can// fail fast with an actionable hint instead of burning through the entirediff --git a/packages/cli/src/utils/desktopApp.test.ts b/packages/cli/src/utils/desktopApp.test.tsnew file mode 100644index 0000000000..346c4a5973--- /dev/null+++ b/packages/cli/src/utils/desktopApp.test.ts@@ -0,0 +1,172 @@+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join, resolve } from "node:path";+import { afterEach, describe, expect, it } from "vitest";+import {+ AGENT_HANDOFF_FILE,+ DESKTOP_DOWNLOAD_URL,+ DOWNLOAD_HINT,+ HANDOFF_READY,+ agentSession,+ desktopHint,+ desktopInstalled,+ openCommandFor,+ openInDesktop,+} from "./desktopApp.js";++// The live path (ready) is what ships once the app takes handed-over folders; CI exercises it here.+const LIVE = { ready: true, platform: "darwin", env: {}, installed: () => true };+const FILM = resolve("films", "a");+const never = () => {+ throw new Error("must not run");+};++describe("openInDesktop", () => {+ it("opens and writes nothing while the app cannot take a project", () => {+ expect(HANDOFF_READY).toBe(false);+ expect(openInDesktop(FILM, { open: never })).toEqual({+ opened: false,+ reason: "handoff-unavailable",+ downloadUrl: DESKTOP_DOWNLOAD_URL,+ });+ });++ it("hands the folder to the released app when it is installed", () => {+ const asked: string[] = [];+ const result = openInDesktop(FILM, {+ ...LIVE,+ open: (id, dir) => (asked.push(`${id} ${dir}`), true),+ });+ expect(result).toEqual({ opened: true, bundleId: "dev.hyperframes.desktop", handedOver: null });+ expect(asked).toEqual([`dev.hyperframes.desktop ${FILM}`]);+ });++ it("falls back to Canary when only Canary is installed", () => {+ const result = openInDesktop(FILM, { ...LIVE, open: (id) => id.endsWith(".canary") });+ expect(result).toMatchObject({ opened: true, bundleId: "dev.hyperframes.desktop.canary" });+ });++ it("tells a missing app from one macOS could not open", () => {+ const missing = openInDesktop(FILM, { ...LIVE, open: () => false, installed: () => false });+ expect(missing).toMatchObject({ opened: false, reason: "not-installed" });+ const failed = openInDesktop(FILM, { ...LIVE, open: () => false, installed: () => true });+ expect(failed).toMatchObject({ opened: false, reason: "open-failed" });+ });++ it("never runs `open` off macOS", () => {+ const result = openInDesktop(FILM, { ...LIVE, platform: "win32", open: never });+ expect(result).toMatchObject({ opened: false, reason: "unsupported-platform" });+ });+});++describe("agent hand-off", () => {+ let dir: string | undefined;+ afterEach(() => {+ if (dir) chmodSync(dir, 0o755);+ if (dir) rmSync(dir, { recursive: true, force: true });+ });+ const handoff = () => join(dir!, AGENT_HANDOFF_FILE);++ it("names the conversation the command runs in, Claude Code first", () => {+ expect(agentSession({ CLAUDE_CODE_SESSION_ID: "c-1", CODEX_THREAD_ID: "x-1" })).toEqual({+ engine: "claude",+ sessionId: "c-1",+ });+ expect(agentSession({ CODEX_THREAD_ID: "x-1" })).toEqual({ engine: "codex", sessionId: "x-1" });+ expect(agentSession({})).toBeNull();+ });++ it("leaves the app the conversation once it has the folder", () => {+ dir = mkdtempSync(join(tmpdir(), "hf-handoff-"));+ const session = "0a8eed95-0869-45bf-83ec-5d71fcc5236c";+ const result = openInDesktop(dir, {+ ...LIVE,+ open: () => true,+ env: { CLAUDE_CODE_SESSION_ID: session },+ });+ expect(result).toMatchObject({ opened: true, handedOver: { engine: "claude" } });+ expect(JSON.parse(readFileSync(handoff(), "utf8"))).toEqual({+ engine: "claude",+ sessionId: session,+ });+ });++ it("writes nothing when gated, when no app took the folder, or when no agent runs the command", () => {+ dir = mkdtempSync(join(tmpdir(), "hf-handoff-"));+ const agent = { CODEX_THREAD_ID: "x-1" };+ openInDesktop(dir, { ready: false, platform: "darwin", open: never, env: agent });+ openInDesktop(dir, { ...LIVE, open: () => false, env: agent });+ openInDesktop(dir, { ...LIVE, open: () => true });+ expect(existsSync(handoff())).toBe(false);+ });++ it.skipIf(process.platform === "win32")(+ "still opens a project it cannot write to, with nothing handed over",+ () => {+ dir = mkdtempSync(join(tmpdir(), "hf-handoff-"));+ chmodSync(dir, 0o555);+ const result = openInDesktop(dir, {+ ...LIVE,+ open: () => true,+ env: { CODEX_THREAD_ID: "x-1" },+ });+ expect(result).toMatchObject({ opened: true, handedOver: null });+ },+ );+});++describe("openCommandFor", () => {+ it("names the project relative to where the person is", () => {+ const work = resolve("work");+ expect(openCommandFor(join(work, "films", "a"), join(work, "films", "a"))).toBe(+ "hyperframes open .",+ );+ expect(openCommandFor(join(work, "films", "a"), work)).toBe(+ `hyperframes open ${join("films", "a")}`,+ );+ expect(openCommandFor(join(work, "my film"), work)).toBe('hyperframes open "my film"');+ });+});++describe("desktopInstalled", () => {+ const home = resolve("Users", "a");+ const nothing = { platform: "darwin", home, exists: () => false, spotlight: () => false };++ it("finds the app where the DMG and the installer put it, Canary included", () => {+ const canary = join("/Applications", "HyperFrames Canary.app");+ expect(desktopInstalled({ ...nothing, exists: (p: string) => p === canary })).toBe(true);+ const mine = join(home, "Applications", "HyperFrames.app");+ expect(desktopInstalled({ ...nothing, exists: (p: string) => p === mine })).toBe(true);+ });++ it("asks Spotlight for one installed anywhere else", () => {+ expect(+ desktopInstalled({ ...nothing, spotlight: (id: string) => id === "dev.hyperframes.desktop" }),+ ).toBe(true);+ expect(desktopInstalled(nothing)).toBe(false);+ });++ it("is never there off macOS", () => {+ expect(desktopInstalled({ ...nothing, platform: "linux", exists: () => true })).toBe(false);+ });+});++describe("desktopHint", () => {+ it("points to the download while gated, and when the app is missing", () => {+ expect(desktopHint(process.cwd(), { env: {}, installed: true })).toBe(DOWNLOAD_HINT);+ expect(desktopHint(process.cwd(), { env: {}, ready: true, installed: false })).toBe(+ DOWNLOAD_HINT,+ );+ });++ it("points an installed app to `hyperframes open` once the app takes handed-over projects", () => {+ expect(desktopHint(process.cwd(), { env: {}, ready: true, installed: true })).toBe(+ "Edit it with Framey: hyperframes open .",+ );+ });++ it("says nothing inside the app, whose runs carry HYPERFRAMES_DESKTOP_PROJECT", () => {+ const inApp = { env: { HYPERFRAMES_DESKTOP_PROJECT: "/p" }, ready: true, installed: true };+ expect(desktopHint(process.cwd(), inApp)).toBeNull();+ });+});diff --git a/packages/cli/src/utils/desktopApp.ts b/packages/cli/src/utils/desktopApp.tsnew file mode 100644index 0000000000..cb6c0d2f97--- /dev/null+++ b/packages/cli/src/utils/desktopApp.ts@@ -0,0 +1,125 @@+import { spawnSync } from "node:child_process";+import { existsSync, mkdirSync, writeFileSync } from "node:fs";+import { homedir } from "node:os";+import { basename, join, relative } from "node:path";++// HyperFrames Studio, the desktop app; macOS hands it a folder through `open -b`. Released app first, then Canary.+const DESKTOP_BUNDLE_IDS = ["dev.hyperframes.desktop", "dev.hyperframes.desktop.canary"] as const;+const DESKTOP_APP_NAMES = ["HyperFrames.app", "HyperFrames Canary.app"];+export const DESKTOP_DOWNLOAD_URL = "https://hyperframes.dev/studio/download";+export const DOWNLOAD_HINT = `Edit it by chatting with Framey in HyperFrames Studio → ${DESKTOP_DOWNLOAD_URL}`;++// ponytail: released apps ignore a handed-over folder until hyperframes-internal#2601 ships. Until then nothing+// opens or writes a hand-off, and every surface (CLI, preview route, Studio's button) offers the download.+export const HANDOFF_READY = false;++export interface AgentSession {+ engine: "claude" | "codex";+ sessionId: string;+}++export const AGENT_HANDOFF_FILE = join(".hyperframes", "agent-handoff.json");++// ponytail: Claude Code first; a Codex started inside a Claude Code shell (or the reverse) carries both, unsorted.+export function agentSession(env: NodeJS.ProcessEnv = process.env): AgentSession | null {+ if (env.CLAUDE_CODE_SESSION_ID)+ return { engine: "claude", sessionId: env.CLAUDE_CODE_SESSION_ID };+ if (env.CODEX_THREAD_ID) return { engine: "codex", sessionId: env.CODEX_THREAD_ID };+ return null;+}++export type DesktopOpenResult =+ | { opened: true; bundleId: string; handedOver: AgentSession | null }+ | {+ opened: false;+ reason: "handoff-unavailable" | "unsupported-platform" | "not-installed" | "open-failed";+ downloadUrl: string;+ };++const openWithBundle = (bundleId: string, dir: string): boolean =>+ spawnSync("open", ["-b", bundleId, dir], { stdio: "ignore" }).status === 0;++/** The app reads the hand-off at its first chat send, so a project it cannot be written to just opens without it. */+function leaveHandoff(dir: string, session: AgentSession | null): AgentSession | null {+ if (!session) return null;+ try {+ mkdirSync(join(dir, ".hyperframes"), { recursive: true });+ writeFileSync(join(dir, AGENT_HANDOFF_FILE), JSON.stringify(session));+ return session;+ } catch {+ return null;+ }+}++// ponytail: macOS only; the Windows app needs its own hand-off (argv on second-instance) before this grows a branch.+export function openInDesktop(+ dir: string,+ {+ ready = HANDOFF_READY,+ platform = process.platform,+ open = openWithBundle,+ installed = () => desktopInstalled({ platform }),+ env = process.env,+ }: {+ ready?: boolean;+ platform?: string;+ open?: (bundleId: string, dir: string) => boolean;+ installed?: () => boolean;+ env?: NodeJS.ProcessEnv;+ } = {},+): DesktopOpenResult {+ const notOpened = (+ reason: Extract<DesktopOpenResult, { opened: false }>["reason"],+ ): DesktopOpenResult => ({ opened: false, reason, downloadUrl: DESKTOP_DOWNLOAD_URL });+ if (!ready) return notOpened("handoff-unavailable");+ if (platform !== "darwin") return notOpened("unsupported-platform");+ const bundleId = DESKTOP_BUNDLE_IDS.find((id) => open(id, dir));+ if (!bundleId) return notOpened(installed() ? "open-failed" : "not-installed");+ return { opened: true, bundleId, handedOver: leaveHandoff(dir, agentSession(env)) };+}++/** The `hyperframes open` line for a project, relative to where the person is. */+export function openCommandFor(dir: string, cwd = process.cwd()): string {+ const shown = relative(cwd, dir) || ".";+ return `hyperframes open ${/\s/.test(shown) ? JSON.stringify(shown) : shown}`;+}++/** Spotlight's copies of an app with this bundle id; an updater's hidden leftover (`.X.app.installing-…`) is none. */+const spotlightFinds = (bundleId: string): boolean =>+ spawnSync("mdfind", [`kMDItemCFBundleIdentifier == '${bundleId}'`], { encoding: "utf8" })+ .stdout?.split("\n")+ .some((path) => path.endsWith(".app") && !basename(path).startsWith(".")) ?? false;++/** Whether this Mac has the app, without launching it: where the DMG and the installer put it, else Spotlight. */+export function desktopInstalled({+ platform = process.platform,+ home = homedir(),+ exists = existsSync,+ spotlight = spotlightFinds,+}: {+ platform?: string;+ home?: string;+ exists?: (path: string) => boolean;+ spotlight?: (bundleId: string) => boolean;+} = {}): boolean {+ if (platform !== "darwin") return false;+ const folders = ["/Applications", join(home, "Applications")];+ if (folders.some((folder) => DESKTOP_APP_NAMES.some((name) => exists(join(folder, name)))))+ return true;+ return DESKTOP_BUNDLE_IDS.some(spotlight);+}++/** The line render and preview print about the app; null inside the app (its agent runs set the variable). */+export function desktopHint(+ dir: string,+ {+ env = process.env,+ ready = HANDOFF_READY,+ installed,+ }: { env?: NodeJS.ProcessEnv; ready?: boolean; installed?: boolean } = {},+): string | null {+ if (env.HYPERFRAMES_DESKTOP_PROJECT) return null;+ return ready && (installed ?? desktopInstalled())+ ? `Edit it with Framey: ${openCommandFor(dir)}`+ : DOWNLOAD_HINT;+}diff --git a/packages/studio/src/components/FrameyGlyph.tsx b/packages/studio/src/components/FrameyGlyph.tsxnew file mode 100644index 0000000000..abcde5f219--- /dev/null+++ b/packages/studio/src/components/FrameyGlyph.tsx@@ -0,0 +1,52 @@+import type { Ref } from "react";++// Framey, the desktop app's cursor mascot, as hyperframes-internal packages/nib draws it: a rounded triangle with a+// white rim and one eye. The viewBox frames the body with its rim; the tip points up and left like a cursor.+const BODY = "M77.55 48.44 L122.77 65.85 L99.3 89.41 Z";+const EYE = { cx: 111.6, cy: 68.2, r: 11.5 };++/** `eyeRef` moves the pupils (a translate of a few px) without re-rendering. */+export function FrameyGlyph({+ size,+ className,+ eyeRef,+}: {+ size: number;+ className?: string;+ eyeRef?: Ref<SVGGElement>;+}) {+ return (+ <svg+ width={size}+ height={size}+ viewBox="58 30 82 76"+ aria-hidden="true"+ className={className}+ overflow="visible"+ >+ <path+ d={BODY}+ fill="var(--color-white)"+ stroke="var(--color-white)"+ strokeWidth={24}+ strokeLinejoin="round"+ />+ <path+ d={BODY}+ fill="var(--color-framey)"+ stroke="var(--color-framey)"+ strokeWidth={19}+ strokeLinejoin="round"+ />+ <circle cx={EYE.cx} cy={EYE.cy} r={EYE.r} fill="var(--color-white)" />+ <g ref={eyeRef} className="hf-framey-eye">+ <path+ d={`M${EYE.cx - 2.6} ${EYE.cy - 2} V${EYE.cy + 2} M${EYE.cx + 2.6} ${EYE.cy - 2} V${EYE.cy + 2}`}+ stroke="var(--color-framey-ink)"+ strokeWidth={2.4}+ strokeLinecap="round"+ />+ </g>+ </svg>+ );+}diff --git a/packages/studio/src/components/OpenInDesktopButton.dom.test.tsx b/packages/studio/src/components/OpenInDesktopButton.dom.test.tsxnew file mode 100644index 0000000000..92a154c0d9--- /dev/null+++ b/packages/studio/src/components/OpenInDesktopButton.dom.test.tsx@@ -0,0 +1,113 @@+// @vitest-environment happy-dom++/**+ * "Edit with Framey": shown only where the preview server answers on macOS; a press opens the project in the app,+ * or introduces Framey with the download while the app cannot take it or is missing.+ */+import React, { act } from "react";+import { createRoot, type Root } from "react-dom/client";+import { afterEach, beforeEach, expect, it, vi } from "vitest";++(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;++const showToast = vi.fn();+vi.mock("../contexts/StudioContext", () => ({ useStudioShellContext: () => ({ showToast }) }));+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));++const { OpenInDesktopButton } = await import("./OpenInDesktopButton");++const DOWNLOAD = "https://hyperframes.dev/studio/download";+let mounted: { root: Root; host: HTMLElement } | null = null;+let posts: number;++function serve(get: Response | null, post?: unknown) {+ posts = 0;+ vi.stubGlobal(+ "fetch",+ vi.fn(async (_url: string, init?: RequestInit) => {+ if (init?.method === "POST") {+ posts += 1;+ return Response.json(post);+ }+ return get ?? new Response("Not found", { status: 404 });+ }),+ );+}++async function mount(): Promise<HTMLElement> {+ const host = document.createElement("div");+ document.body.append(host);+ const root = createRoot(host);+ mounted = { root, host };+ await act(async () => root.render(<OpenInDesktopButton />));+ return host;+}++const downloadHref = () =>+ [...document.querySelectorAll("a")]+ .find((a) => a.textContent?.includes("Get HyperFrames Studio"))+ ?.getAttribute("href");++const button = () =>+ document.querySelector<HTMLButtonElement>('[data-testid="header-open-in-desktop"]');++beforeEach(() => showToast.mockReset());++afterEach(() => {+ vi.unstubAllGlobals();+ if (!mounted) return;+ const { root, host } = mounted;+ mounted = null;+ act(() => root.unmount());+ host.remove();+});++it("stays hidden where the server has no hand-off (the desktop's own Studio)", async () => {+ serve(null);+ await mount();+ expect(button()).toBeNull();+});++it("stays hidden when the server says it cannot open the app (not macOS)", async () => {+ serve(Response.json({ available: false }));+ await mount();+ expect(button()).toBeNull();+});++it("while the app cannot take a project yet, introduces Framey with the download and opens nothing", async () => {+ serve(Response.json({ available: true, handoff: false }), { opened: true });+ await mount();+ await act(async () => button()!.click());+ expect(posts).toBe(0);+ expect(document.body.textContent).toContain("Meet Framey");+ expect(downloadHref()).toBe(DOWNLOAD);+});++it("opens the project in the app and says so", async () => {+ serve(Response.json({ available: true, handoff: true }), {+ opened: true,+ bundleId: "dev.hyperframes.desktop",+ });+ await mount();+ await act(async () => button()!.click());+ expect(posts).toBe(1);+ expect(showToast).toHaveBeenCalledWith(+ "Framey is opening this project in HyperFrames Studio",+ "info",+ );+ expect(button()!.dataset.opening).toBe("true");+ expect(document.body.textContent).not.toContain("Meet Framey");+});++it("introduces Framey and offers the download when the app is missing", async () => {+ serve(Response.json({ available: true, handoff: true }), {+ opened: false,+ reason: "not-installed",+ downloadUrl: DOWNLOAD,+ });+ await mount();+ await act(async () => button()!.click());+ expect(showToast).not.toHaveBeenCalled();+ expect(document.body.textContent).toContain("Meet Framey");+ expect(downloadHref()).toBe(DOWNLOAD);+});diff --git a/packages/studio/src/components/OpenInDesktopButton.tsx b/packages/studio/src/components/OpenInDesktopButton.tsxnew file mode 100644index 0000000000..78b2d1cd3c--- /dev/null+++ b/packages/studio/src/components/OpenInDesktopButton.tsx@@ -0,0 +1,153 @@+import { useEffect, useRef, useState } from "react";+import { useStudioShellContext } from "../contexts/StudioContext";+import { studioApiFetch } from "../utils/studioApiFetch";+import { trackStudioEvent } from "../utils/studioTelemetry";+import { FrameyGlyph } from "./FrameyGlyph";+import { Button, buttonBase, buttonSizes, buttonVariants, cn, Popover } from "./ui";++// "Edit with Framey": the preview server (`/api/open-in-desktop`) says whether to show it and whether the app can+// take the project yet (its gate is the CLI's HANDOFF_READY); until then a press introduces Framey with the download.+const ROUTE = "/api/open-in-desktop";+const DOWNLOAD_URL = "https://hyperframes.dev/studio/download";+/** How far the pupils travel towards the pointer, in the glyph's own units. */+const GAZE = 2.2;+/** Long enough for the flight to finish before the label comes back. */+const OPENING_MS = 1600;++type OpenResult = { opened: true } | { opened: false; reason: string; downloadUrl: string };++/** Null hides the button: no such route (the app's own Studio), or not macOS. */+function useDesktopRoute(): { handoff: boolean } | null {+ const [route, setRoute] = useState<{ handoff: boolean } | null>(null);+ useEffect(() => {+ let live = true;+ studioApiFetch(ROUTE)+ .then((res) => (res.ok ? res.json() : null))+ .then((body: { available?: unknown; handoff?: unknown } | null) => {+ if (live && body?.available === true) setRoute({ handoff: body.handoff === true });+ })+ .catch(() => {});+ return () => {+ live = false;+ };+ }, []);+ return route;+}++/** Framey looks at the pointer: one listener, one write per frame, no re-render. */+function useGaze(+ anchor: React.RefObject<HTMLElement | null>,+ eye: React.RefObject<SVGGElement | null>,+) {+ useEffect(() => {+ let frame = 0;+ const look = (event: PointerEvent) => {+ cancelAnimationFrame(frame);+ frame = requestAnimationFrame(() => {+ const box = anchor.current?.getBoundingClientRect();+ if (!box || !eye.current) return;+ const dx = event.clientX - (box.left + box.height / 2);+ const dy = event.clientY - (box.top + box.height / 2);+ const distance = Math.hypot(dx, dy) || 1;+ eye.current.style.transform = `translate(${(dx / distance) * GAZE}px, ${(dy / distance) * GAZE}px)`;+ });+ };+ window.addEventListener("pointermove", look);+ return () => {+ cancelAnimationFrame(frame);+ window.removeEventListener("pointermove", look);+ };+ }, [anchor, eye]);+}++export function OpenInDesktopButton() {+ const { showToast } = useStudioShellContext();+ const route = useDesktopRoute();+ const [opening, setOpening] = useState(false);+ // The card under the button, introducing Framey with the app's download.+ const [downloadUrl, setDownloadUrl] = useState<string | null>(null);+ const trigger = useRef<HTMLButtonElement>(null);+ const eye = useRef<SVGGElement>(null);+ useGaze(trigger, eye);+ if (!route) return null;++ const open = async () => {+ if (!route.handoff) {+ trackStudioEvent("toolbar_action", { action: "open_in_desktop" });+ setDownloadUrl(DOWNLOAD_URL);+ return;+ }+ if (opening) return;+ setOpening(true);+ trackStudioEvent("toolbar_action", { action: "open_in_desktop" });+ try {+ const res = await studioApiFetch(ROUTE, { method: "POST" });+ const result = (await res.json()) as OpenResult;+ if (result.opened) {+ showToast("Framey is opening this project in HyperFrames Studio", "info");+ await new Promise((done) => setTimeout(done, OPENING_MS));+ } else setDownloadUrl(result.downloadUrl);+ } catch {+ showToast("Couldn't reach the preview server to open the app", "error");+ } finally {+ setOpening(false);+ }+ };++ return (+ <Popover+ open={downloadUrl !== null}+ // The popover owns the trigger's press: a press runs the hand-off, and the card shows only when there is+ // something to say (the download). A second handler on the button raced this one.+ onOpenChange={(next) => {+ if (next) void open();+ else setDownloadUrl(null);+ }}+ side="bottom"+ align="end"+ arrow+ aria-label="Meet Framey"+ className="w-72"+ trigger={+ <Button+ ref={trigger}+ variant="ghost"+ data-testid="header-open-in-desktop"+ data-opening={opening || undefined}+ title="Open this project in HyperFrames Studio, the desktop app, and edit it with Framey"+ className="hf-framey-trigger gap-1.5 pl-1.5"+ icon={<FrameyGlyph size={20} className="hf-framey" eyeRef={eye} />}+ >+ {opening ? "Opening in the app…" : "Edit with Framey"}+ </Button>+ }+ >+ <div className="flex items-center gap-2.5">+ <FrameyGlyph size={36} />+ <p className="text-step-12 font-medium text-text-0">Meet Framey</p>+ </div>+ <p className="mt-2 text-text-3">+ I live in HyperFrames Studio, the free desktop app for macOS:+ </p>+ <ul className="mt-1.5 grid gap-1 text-text-1">+ <li>Chat to change anything in the video</li>+ <li>Draw on a frame to point at it</li>+ <li>Watch me act out each edit</li>+ </ul>+ <div className="mt-3 flex items-center justify-end gap-2 whitespace-nowrap">+ <Button variant="ghost" onClick={() => setDownloadUrl(null)}>+ Not now+ </Button>+ <a+ href={downloadUrl ?? undefined}+ target="_blank"+ rel="noopener noreferrer"+ className={cn(buttonBase, buttonVariants.primary, buttonSizes.md)}+ onClick={() => trackStudioEvent("toolbar_action", { action: "get_desktop_app" })}+ >+ Get HyperFrames Studio+ </a>+ </div>+ </Popover>+ );+}diff --git a/packages/studio/src/components/StudioHeader.dom.test.tsx b/packages/studio/src/components/StudioHeader.dom.test.tsxindex 263433c7a9..2052404c64 100644--- a/packages/studio/src/components/StudioHeader.dom.test.tsx+++ b/packages/studio/src/components/StudioHeader.dom.test.tsx@@ -40,6 +40,8 @@ vi.mock("../contexts/PanelLayoutContext", () => ({}));vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));+// Probes the preview server on mount; covered in OpenInDesktopButton.dom.test.tsx.+vi.mock("./OpenInDesktopButton", () => ({ OpenInDesktopButton: () => null }));const { StudioHeader } = await import("./StudioHeader");const { ShowThemeToggle } = await import("./ThemeToggle");diff --git a/packages/studio/src/components/StudioHeader.tsx b/packages/studio/src/components/StudioHeader.tsxindex f0e05f6b2b..b452e61780 100644--- a/packages/studio/src/components/StudioHeader.tsx+++ b/packages/studio/src/components/StudioHeader.tsx@@ -6,6 +6,7 @@ import { trackStudioEvent } from "../utils/studioTelemetry";import { Button, buttonBase, buttonSizes, buttonVariants, cn, Tooltip } from "./ui";import { Dock } from "./dock/Dock";import { InspectorIcon } from "./icons/InspectorIcon";+import { OpenInDesktopButton } from "./OpenInDesktopButton";import { HyperframesLogo } from "./ui/HyperframesLogo";import { ShowThemeToggle, ThemeToggle } from "./ThemeToggle";@@ -151,6 +152,7 @@ export const StudioHeader = memo(function StudioHeader({</div>{showThemeToggle && <ThemeToggle />}<Dock.WindowMenu />+ <OpenInDesktopButton /><Tooltiplabel={ffmpegMissingdiff --git a/packages/studio/src/styles/components.css b/packages/studio/src/styles/components.cssindex 159649110a..f1484f582a 100644--- a/packages/studio/src/styles/components.css+++ b/packages/studio/src/styles/components.css@@ -935,3 +935,54 @@transform: scaleY(1);}}++/* Framey on the header's "Edit with Framey" (OpenInDesktopButton.tsx): a wiggle on hover, a flight towards+ * the app while it opens. The eye follows the pointer from script. */+@keyframes hf-framey-wiggle {+ 0%,+ 100% {+ transform: rotate(0deg);+ }+ 25% {+ transform: rotate(-14deg);+ }+ 60% {+ transform: rotate(10deg);+ }+}++@keyframes hf-framey-fly {+ 70% {+ opacity: 1;+ }+ 100% {+ transform: translate(48px, -28px) rotate(25deg) scale(0.6);+ opacity: 0;+ }+}++.hf-framey {+ transform-origin: 30% 30%;+}++.hf-framey-eye {+ transition: transform 80ms linear;+}++.hf-framey-trigger:hover .hf-framey {+ animation: hf-framey-wiggle 0.5s ease-in-out;+}++.hf-framey-trigger[data-opening] .hf-framey {+ animation: hf-framey-fly 0.9s ease-in forwards;+}++@media (prefers-reduced-motion: reduce) {+ .hf-framey-trigger:hover .hf-framey,+ .hf-framey-trigger[data-opening] .hf-framey {+ animation: none;+ }+ .hf-framey-eye {+ transition: none;+ }+}diff --git a/packages/studio/src/styles/theme.css b/packages/studio/src/styles/theme.cssindex c568ab7295..849ccd1a5b 100644--- a/packages/studio/src/styles/theme.css+++ b/packages/studio/src/styles/theme.css@@ -436,6 +436,9 @@--color-violet-400: oklch(70.2% 0.183 293.541);--color-violet-500: oklch(60.6% 0.25 292.717);--color-white: #fff;+ /* Framey, the desktop app's cursor mascot (hyperframes-internal packages/nib): the same in both themes. */+ --color-framey: #3ce6ac;+ --color-framey-ink: #16121a;}/* The colour-scheme picks each token's light or dark half: dark unless the document elementdiff --git a/scripts/studio-runtime-smoke.mjs b/scripts/studio-runtime-smoke.mjsindex 1638ca943e..e53bf2a6ee 100644--- a/scripts/studio-runtime-smoke.mjs+++ b/scripts/studio-runtime-smoke.mjs@@ -52,6 +52,8 @@ const GET_RESPONSES = new Map([// interesting assertion is that the shell mounts clean, not that a blocking// notice renders. The notice has its own tests.["/api/environment/ffmpeg", json({ ok: true })],+ // The header's Edit with Framey asks this on load; shown, so the shell mounts with it.+ ["/api/open-in-desktop", json({ available: true, handoff: false })],]);const MUTATION_RESPONSES = new Map([[`${PROJECT_PATH}/selection`, json({ ok: true, selection: null, updatedAt: null })],