Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
feat(cli,studio): hand off on macOS now, and open the app on Windows and Linux (#4999)
WaterrrForever6a27a34f21ef
diff --git a/packages/cli/src/commands/open.ts b/packages/cli/src/commands/open.tsindex db60152319..9c1a97e68d 100644--- a/packages/cli/src/commands/open.ts+++ b/packages/cli/src/commands/open.ts@@ -2,25 +2,25 @@ 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 { downloadHint, 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 this project in the HyperFrames desktop app", "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.",+ "unsupported-platform": "Opening a project from the CLI works on macOS, Windows and Linux only.",+ "not-installed": "The HyperFrames desktop app isn't installed on this computer.",+ "open-failed": "The HyperFrames desktop app couldn't be started.",};function printResult(project: ProjectDir, result: DesktopOpenResult): void {if (result.opened) {- console.log(`${c.success("◇")} Opening ${c.accent(project.name)} in HyperFrames Studio`);+ console.log(`${c.success("◇")} Opening ${c.accent(project.name)} in ${result.app}`);if (result.handedOver) {const agent = result.handedOver.engine === "claude" ? "Claude Code" : "Codex";console.log(` ${c.dim(`Its chat picks up this ${agent} conversation.`)}`);@@ -28,7 +28,7 @@ function printResult(project: ProjectDir, result: DesktopOpenResult): void {return;}const why = WHY_NOT[result.reason];- if (!why) return console.log(`${c.warn("◇")} ${DOWNLOAD_HINT}`);+ if (!why) return console.log(`${c.warn("◇")} ${downloadHint(result.downloadUrl)}`);console.log(`${c.warn("◇")} ${why}`);console.log(` Download it: ${c.accent(result.downloadUrl)}`);}@@ -46,7 +46,7 @@ function projectForJson(dir: string | undefined): ProjectDir | null {}export default defineCommand({- meta: { name: "open", description: "Open a project in HyperFrames Studio, the desktop app" },+ meta: { name: "open", description: "Open a project in the HyperFrames desktop app" },args: {dir: {type: "positional",diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.tsindex e6fed5043c..46dab62817 100644--- a/packages/cli/src/commands/render.ts+++ b/packages/cli/src/commands/render.ts@@ -1905,9 +1905,9 @@ 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";+/** A render points to the desktop app; a batch row does not. Drafts do too: music-to-video delivers one. */+export function wantsDesktopHint(options: Pick<RenderOptions, "desktopHint">): boolean {+ return options.desktopHint !== false;}function printRenderComplete(input: {diff --git a/packages/cli/src/commands/render/execute.test.ts b/packages/cli/src/commands/render/execute.test.tsindex 075c3f79a7..f67b3e7e69 100644--- a/packages/cli/src/commands/render/execute.test.ts+++ b/packages/cli/src/commands/render/execute.test.ts@@ -43,10 +43,9 @@ describe("renderOptionsFromPlan", () => {});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);+ it("comes after every render but a batch row", () => {+ expect(wantsDesktopHint({})).toBe(true);+ expect(wantsDesktopHint({ desktopHint: false })).toBe(false);const projectDir = mkdtempSync(join(tmpdir(), "hf-render-batch-"));try {writeFileSync(join(projectDir, "index.html"), '<main data-composition-id="main"></main>');diff --git a/packages/cli/src/help.ts b/packages/cli/src/help.tsindex 34769aa7a8..3fb2182d6f 100644--- a/packages/cli/src/help.ts+++ b/packages/cli/src/help.ts@@ -27,7 +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"],+ ["open", "Open a project in the HyperFrames desktop app"],],},{diff --git a/packages/cli/src/server/desktopRoutes.test.ts b/packages/cli/src/server/desktopRoutes.test.tsindex 1fce187970..986ca3cd5a 100644--- a/packages/cli/src/server/desktopRoutes.test.ts+++ b/packages/cli/src/server/desktopRoutes.test.ts@@ -1,6 +1,6 @@import { Hono } from "hono";import { describe, expect, it, vi } from "vitest";-import type { DesktopOpenResult } from "../utils/desktopApp.js";+import { desktopDownloadUrl, type DesktopOpenResult } from "../utils/desktopApp.js";import { mountDesktopRoutes, sameOriginPost } from "./desktopRoutes.js";const STUDIO = {@@ -10,14 +10,17 @@ const STUDIO = {};const OPENED: DesktopOpenResult = {opened: true,- bundleId: "dev.hyperframes.desktop",+ app: "the HyperFrames desktop app",handedOver: null,};-function server(ready: boolean) {+function server(+ ready: boolean,+ place: { platform?: NodeJS.Platform; installed?: () => boolean } = {},+) {const app = new Hono();const open = vi.fn((_dir: string): DesktopOpenResult => OPENED);- mountDesktopRoutes(app, "/films/a", { ready, open });+ mountDesktopRoutes(app, "/films/a", { ready, open, ...place });const post = (headers: Record<string, string>) =>app.request("/api/open-in-desktop", { method: "POST", headers });return { app, open, post };@@ -25,8 +28,22 @@ function server(ready: boolean) {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 });+ const body = await (+ await server(false, { installed: () => false }).app.request("/api/open-in-desktop")+ ).json();+ const downloadUrl = desktopDownloadUrl();+ expect(body).toEqual({ available: downloadUrl !== null, handoff: false, downloadUrl });+ });++ it("shows the button where the app is installed even without a download (Windows)", async () => {+ const get = async (installed: boolean) =>+ (+ await server(true, { platform: "win32", installed: () => installed }).app.request(+ "/api/open-in-desktop",+ )+ ).json();+ expect(await get(true)).toEqual({ available: true, handoff: true, downloadUrl: null });+ expect(await get(false)).toMatchObject({ available: false });});it("refuses a POST from another site, or through a rebound host name", async () => {diff --git a/packages/cli/src/server/desktopRoutes.ts b/packages/cli/src/server/desktopRoutes.tsindex 43a16ebe08..3aa88df89f 100644--- a/packages/cli/src/server/desktopRoutes.ts+++ b/packages/cli/src/server/desktopRoutes.ts@@ -1,5 +1,10 @@import type { Hono } from "hono";-import { DESKTOP_DOWNLOAD_URL, HANDOFF_READY, openInDesktop } from "../utils/desktopApp.js";+import {+ HANDOFF_READY,+ desktopDownloadUrl,+ desktopInstalled,+ 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. */@@ -14,14 +19,20 @@ export function sameOriginPost(headers: {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. */+/** Edit with Framey's route: whether to show it, where to download, and whether the app takes the project. */export function mountDesktopRoutes(app: Hono,projectDir: string,- { ready = HANDOFF_READY, open = openInDesktop } = {},+ {+ ready = HANDOFF_READY,+ open = openInDesktop,+ platform = process.platform,+ installed = () => desktopInstalled({ platform }),+ } = {},): void {+ const downloadUrl = desktopDownloadUrl(platform);app.get("/api/open-in-desktop", (c) =>- c.json({ available: process.platform === "darwin", handoff: ready }),+ c.json({ available: downloadUrl !== null || installed(), handoff: ready, downloadUrl }),);app.post("/api/open-in-desktop", (c) => {const allowed = sameOriginPost({@@ -34,7 +45,7 @@ export function mountDesktopRoutes(return c.json({opened: false,reason: "handoff-unavailable",- downloadUrl: DESKTOP_DOWNLOAD_URL,+ downloadUrl,});return c.json(open(projectDir));});diff --git a/packages/cli/src/utils/desktopApp.test.ts b/packages/cli/src/utils/desktopApp.test.tsindex 346c4a5973..e4b6db983d 100644--- a/packages/cli/src/utils/desktopApp.test.ts+++ b/packages/cli/src/utils/desktopApp.test.ts@@ -1,11 +1,9 @@import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";import { tmpdir } from "node:os";-import { join, resolve } from "node:path";+import { join, resolve, win32 } from "node:path";import { afterEach, describe, expect, it } from "vitest";import {AGENT_HANDOFF_FILE,- DESKTOP_DOWNLOAD_URL,- DOWNLOAD_HINT,HANDOFF_READY,agentSession,desktopHint,@@ -15,7 +13,9 @@ import {} 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 LIVE = { ready: true, platform: "darwin" as const, env: {}, installed: () => true };+const MAC_DOWNLOAD = "https://hyperframes.dev/studio/download";+const MAC_HINT = `Keep editing by chatting with Framey in the HyperFrames desktop app → ${MAC_DOWNLOAD}`;const FILM = resolve("films", "a");const never = () => {throw new Error("must not run");@@ -23,11 +23,12 @@ const never = () => {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({+ // Only the Mac app reads a handed-over folder in a released build so far.+ expect(HANDOFF_READY).toBe(process.platform === "darwin");+ expect(openInDesktop(FILM, { ready: false, platform: "darwin", open: never })).toEqual({opened: false,reason: "handoff-unavailable",- downloadUrl: DESKTOP_DOWNLOAD_URL,+ downloadUrl: MAC_DOWNLOAD,});});@@ -37,13 +38,13 @@ describe("openInDesktop", () => {...LIVE,open: (id, dir) => (asked.push(`${id} ${dir}`), true),});- expect(result).toEqual({ opened: true, bundleId: "dev.hyperframes.desktop", handedOver: null });+ expect(result).toEqual({ opened: true, app: "the HyperFrames desktop app", 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" });+ expect(result).toMatchObject({ opened: true, app: "HyperFrames Canary" });});it("tells a missing app from one macOS could not open", () => {@@ -53,9 +54,92 @@ describe("openInDesktop", () => {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" });+ it("opens nothing where the app has no build, and offers the app's page", () => {+ expect(+ openInDesktop(FILM, { ...LIVE, platform: "freebsd", open: never, launch: never }),+ ).toEqual({+ opened: false,+ reason: "unsupported-platform",+ downloadUrl: "https://hyperframes.dev/studio",+ });+ });+});++describe("openInDesktop on Windows", () => {+ const local = win32.join("C:", "Users", "a", "AppData", "Local");+ const exe = (name: string) => win32.join(local, "Programs", name, `${name}.exe`);+ const WIN = { ...LIVE, platform: "win32" as const, env: { LOCALAPPDATA: local }, open: never };++ it("starts the installed app with the folder, released build first", () => {+ const started: string[] = [];+ const launch = (executable: string, dir: string) => (+ started.push(`${executable} ${dir}`), true+ );+ const result = openInDesktop(FILM, { ...WIN, exists: () => true, launch });+ expect(result).toEqual({ opened: true, app: "the HyperFrames desktop app", handedOver: null });+ expect(started).toEqual([`${exe("HyperFrames")} ${FILM}`]);+ });++ it("falls back to Canary when only Canary is installed", () => {+ const canary = exe("HyperFrames Canary");+ const result = openInDesktop(FILM, { ...WIN, exists: (p) => p === canary, launch: () => true });+ expect(result).toMatchObject({ opened: true, app: "HyperFrames Canary" });+ });++ it("tells a missing app from one that would not start, and offers the app's page", () => {+ const missing = openInDesktop(FILM, { ...WIN, exists: () => false, launch: never });+ expect(missing).toEqual({+ opened: false,+ reason: "not-installed",+ downloadUrl: "https://hyperframes.dev/studio",+ });+ const failed = openInDesktop(FILM, { ...WIN, exists: () => true, launch: () => false });+ expect(failed).toMatchObject({ opened: false, reason: "open-failed" });+ });+});++describe("openInDesktop on Linux", () => {+ const home = resolve("home", "a");+ const appImage = resolve("opt", "HyperFrames-x86_64.AppImage");+ const launcher = (name: string) => join(home, ".config", name, "launcher.json");+ const LINUX = { ...LIVE, platform: "linux" as const, home, open: never, exists: () => true };++ it("starts the AppImage the app last recorded in its launcher.json", () => {+ const files = { [launcher("HyperFrames Canary")]: JSON.stringify({ appImage }) };+ const started: string[] = [];+ const result = openInDesktop(FILM, {+ ...LINUX,+ read: (p) => files[p] ?? null,+ launch: (executable, dir) => (started.push(`${executable} ${dir}`), true),+ });+ expect(result).toMatchObject({ opened: true, app: "HyperFrames Canary" });+ expect(started).toEqual([`${appImage} ${FILM}`]);+ });++ it("reads launcher.json under XDG_CONFIG_HOME when it is set", () => {+ const config = resolve("xdg");+ const read = (p: string) =>+ p === join(config, "HyperFrames", "launcher.json") ? JSON.stringify({ appImage }) : null;+ const env = { XDG_CONFIG_HOME: config };+ expect(openInDesktop(FILM, { ...LINUX, env, read, launch: () => true })).toMatchObject({+ opened: true,+ app: "the HyperFrames desktop app",+ });+ });++ it("ignores a relative, moved, or unreadable AppImage path", () => {+ const relativeFile = { [launcher("HyperFrames")]: JSON.stringify({ appImage: "HF.AppImage" }) };+ const relativePath = { ...LINUX, read: (p: string) => relativeFile[p] ?? null, launch: never };+ expect(openInDesktop(FILM, relativePath)).toMatchObject({ reason: "not-installed" });+ const moved = { [launcher("HyperFrames")]: JSON.stringify({ appImage }) };+ const gone = { ...LINUX, read: (p: string) => moved[p] ?? null, exists: () => false };+ expect(openInDesktop(FILM, { ...gone, launch: never })).toMatchObject({+ reason: "not-installed",+ downloadUrl: `${MAC_DOWNLOAD}?os=linux`,+ });+ expect(openInDesktop(FILM, { ...LINUX, read: () => "{", launch: never })).toMatchObject({+ reason: "not-installed",+ });});});@@ -130,7 +214,12 @@ describe("openCommandFor", () => {describe("desktopInstalled", () => {const home = resolve("Users", "a");- const nothing = { platform: "darwin", home, exists: () => false, spotlight: () => false };+ const nothing = {+ platform: "darwin" as const,+ 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");@@ -146,27 +235,57 @@ describe("desktopInstalled", () => {expect(desktopInstalled(nothing)).toBe(false);});- it("is never there off macOS", () => {- expect(desktopInstalled({ ...nothing, platform: "linux", exists: () => true })).toBe(false);+ it("finds the Windows app where its installer puts it, and nothing where there is no build", () => {+ const local = win32.join("C:", "Users", "a", "AppData", "Local");+ const canary = win32.join(local, "Programs", "HyperFrames Canary", "HyperFrames Canary.exe");+ const windows = { ...nothing, platform: "win32" as const, env: { LOCALAPPDATA: local } };+ expect(desktopInstalled({ ...windows, exists: (p: string) => p === canary })).toBe(true);+ expect(desktopInstalled(windows)).toBe(false);+ expect(desktopInstalled({ ...nothing, platform: "freebsd", exists: () => true })).toBe(false);+ });++ it("finds no Linux app that never recorded its AppImage", () => {+ const linux = { ...nothing, platform: "linux" as const, exists: () => true, read: () => null };+ expect(desktopInstalled(linux)).toBe(false);});});describe("desktopHint", () => {+ const mac = { env: {}, platform: "darwin" as const };+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,+ expect(desktopHint(process.cwd(), { ...mac, ready: false, installed: true })).toBe(MAC_HINT);+ expect(desktopHint(process.cwd(), { ...mac, ready: true, installed: false })).toBe(MAC_HINT);+ });++ it("offers the Linux build on Linux, and nothing on Windows without the app", () => {+ expect(desktopHint(process.cwd(), { env: {}, platform: "linux", installed: false })).toBe(+ `Keep editing by chatting with Framey in the HyperFrames desktop app → ${MAC_DOWNLOAD}?os=linux`,+ );+ expect(desktopHint(process.cwd(), { env: {}, platform: "win32", installed: false })).toBeNull();+ expect(desktopHint(process.cwd(), { env: {}, platform: "win32", ready: true })).toBeNull();+ });++ it("points an installed Windows app to `hyperframes open`", () => {+ const windows = { env: {}, platform: "win32" as const, ready: true, installed: true };+ expect(desktopHint(process.cwd(), windows)).toBe(+ "Keep editing by chatting with Framey in the desktop app: hyperframes open .",);});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 .",+ expect(desktopHint(process.cwd(), { ...mac, ready: true, installed: true })).toBe(+ "Keep editing by chatting with Framey in the desktop app: 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 };+ const inApp = {+ ...mac,+ 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.tsindex cb6c0d2f97..c5996559ac 100644--- a/packages/cli/src/utils/desktopApp.ts+++ b/packages/cli/src/utils/desktopApp.ts@@ -1,17 +1,28 @@-import { spawnSync } from "node:child_process";-import { existsSync, mkdirSync, writeFileSync } from "node:fs";+import { spawn, spawnSync } from "node:child_process";+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";import { homedir } from "node:os";-import { basename, join, relative } from "node:path";+import { basename, isAbsolute, join, relative, win32 } from "node:path";-// HyperFrames Studio, the desktop app; macOS hands it a folder through `open -b`. Released app first, then Canary.+// The HyperFrames desktop app (not "Studio"): `open -b` on macOS, its executable elsewhere; released, 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}`;+const APP_NAMES = ["HyperFrames", "HyperFrames Canary"] as const;+const STUDIO_PAGE = "https://hyperframes.dev/studio";+const DOWNLOADS: Partial<Record<NodeJS.Platform, string>> = {+ darwin: `${STUDIO_PAGE}/download`,+ linux: `${STUDIO_PAGE}/download?os=linux`,+};-// 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;+/** This machine's build of the app; null where there is none yet (Windows). */+export const desktopDownloadUrl = (platform = process.platform): string | null =>+ DOWNLOADS[platform] ?? null;++export const downloadHint = (url: string): string =>+ `Keep editing by chatting with Framey in the HyperFrames desktop app → ${url}`;++// ponytail: the Mac app takes a handed-over folder since b254 (hyperframes-internal#2601); Windows and Linux join+// once its folder-argv change ships. Until then every surface offers the download and writes no hand-off.+export const HANDOFF_READY = process.platform === "darwin";export interface AgentSession {engine: "claude" | "codex";@@ -28,8 +39,10 @@ export function agentSession(env: NodeJS.ProcessEnv = process.env): AgentSessionreturn null;}+type AppName = "the HyperFrames desktop app" | "HyperFrames Canary";+export type DesktopOpenResult =- | { opened: true; bundleId: string; handedOver: AgentSession | null }+ | { opened: true; app: AppName; handedOver: AgentSession | null }| {opened: false;reason: "handoff-unavailable" | "unsupported-platform" | "not-installed" | "open-failed";@@ -39,6 +52,72 @@ export type DesktopOpenResult =const openWithBundle = (bundleId: string, dir: string): boolean =>spawnSync("open", ["-b", bundleId, dir], { stdio: "ignore" }).status === 0;+/** Single-instance app: a running copy is forwarded the folder. Only a refused spawn counts as failed. */+function launchApp(executable: string, dir: string): boolean {+ try {+ const child = spawn(executable, [dir], { detached: true, stdio: "ignore" });+ child.on("error", () => {});+ child.unref();+ return true;+ } catch {+ return false;+ }+}++const readText = (path: string): string | null => {+ try {+ return readFileSync(path, "utf8");+ } catch {+ return null;+ }+};++function launcherAppImage(text: string | null): string | null {+ try {+ const launcher: unknown = JSON.parse(text ?? "null");+ return typeof launcher === "object" &&+ launcher !== null &&+ "appImage" in launcher &&+ typeof launcher.appImage === "string"+ ? launcher.appImage+ : null;+ } catch {+ return null;+ }+}++interface AppLookup {+ platform?: NodeJS.Platform;+ env?: NodeJS.ProcessEnv;+ home?: string;+ exists?: (path: string) => boolean;+ read?: (path: string) => string | null;+}++/** Released then Canary: the Windows install path, or the AppImage Linux records in launcher.json; null on macOS. */+function desktopApps({+ platform = process.platform,+ env = process.env,+ home = homedir(),+ exists = existsSync,+ read = readText,+}: AppLookup = {}): { executable: string; canary: boolean }[] | null {+ if (platform !== "win32" && platform !== "linux") return null;+ const config = env.XDG_CONFIG_HOME || join(home, ".config");+ const where = (name: string): string | null => {+ if (platform === "win32")+ return env.LOCALAPPDATA+ ? win32.join(env.LOCALAPPDATA, "Programs", name, `${name}.exe`)+ : null;+ const appImage = launcherAppImage(read(join(config, name, "launcher.json")));+ return appImage && isAbsolute(appImage) ? appImage : null;+ };+ return APP_NAMES.flatMap((name, i) => {+ const executable = where(name);+ return executable && exists(executable) ? [{ executable, canary: i === 1 }] : [];+ });+}+/** 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;@@ -51,31 +130,48 @@ function leaveHandoff(dir: string, session: AgentSession | null): AgentSession |}}-// ponytail: macOS only; the Windows app needs its own hand-off (argv on second-instance) before this grows a branch.+// ponytail: success on Windows and Linux means the spawn started, not that the app took the folder; wait for the+// app's own acknowledgement if a broken install ever needs reporting.export function openInDesktop(dir: string,{ready = HANDOFF_READY,platform = process.platform,open = openWithBundle,+ launch = launchApp,installed = () => desktopInstalled({ platform }),env = process.env,- }: {+ ...where+ }: AppLookup & {ready?: boolean;- platform?: string;open?: (bundleId: string, dir: string) => boolean;+ launch?: (executable: 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 });+ ): DesktopOpenResult => ({+ opened: false,+ reason,+ downloadUrl: desktopDownloadUrl(platform) ?? STUDIO_PAGE,+ });+ const opened = (canary: boolean): DesktopOpenResult => ({+ opened: true,+ app: canary ? "HyperFrames Canary" : "the HyperFrames desktop app",+ handedOver: leaveHandoff(dir, agentSession(env)),+ });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)) };+ if (platform === "darwin") {+ const bundleId = DESKTOP_BUNDLE_IDS.find((id) => open(id, dir));+ if (!bundleId) return notOpened(installed() ? "open-failed" : "not-installed");+ return opened(bundleId.endsWith(".canary"));+ }+ const apps = desktopApps({ platform, env, ...where });+ if (!apps) return notOpened("unsupported-platform");+ if (!apps.length) return notOpened("not-installed");+ const app = apps.find(({ executable }) => launch(executable, dir));+ return app ? opened(app.canary) : notOpened("open-failed");}/** The `hyperframes open` line for a project, relative to where the person is. */@@ -90,36 +186,37 @@ const spotlightFinds = (bundleId: string): boolean =>.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. */+/** Whether this machine has the app, without launching it (on a Mac: install folders, then 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;+ ...where+}: AppLookup & { spotlight?: (bundleId: string) => boolean } = {}): boolean {+ const { platform = process.platform, home = homedir(), exists = existsSync } = where;+ if (platform !== "darwin") return (desktopApps(where)?.length ?? 0) > 0;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). */+/** The app line render and preview print; null inside the app, or with nothing here to open or download. */export function desktopHint(dir: string,{env = process.env,ready = HANDOFF_READY,installed,- }: { env?: NodeJS.ProcessEnv; ready?: boolean; installed?: boolean } = {},+ platform = process.platform,+ }: {+ env?: NodeJS.ProcessEnv;+ ready?: boolean;+ installed?: boolean;+ platform?: NodeJS.Platform;+ } = {},): string | null {if (env.HYPERFRAMES_DESKTOP_PROJECT) return null;- return ready && (installed ?? desktopInstalled())- ? `Edit it with Framey: ${openCommandFor(dir)}`- : DOWNLOAD_HINT;+ if (ready && (installed ?? desktopInstalled({ platform, env })))+ return `Keep editing by chatting with Framey in the desktop app: ${openCommandFor(dir)}`;+ const url = desktopDownloadUrl(platform);+ return url ? downloadHint(url) : null;}diff --git a/packages/studio/src/components/OpenInDesktopButton.dom.test.tsx b/packages/studio/src/components/OpenInDesktopButton.dom.test.tsxindex 92a154c0d9..9dc4fae2f3 100644--- a/packages/studio/src/components/OpenInDesktopButton.dom.test.tsx+++ b/packages/studio/src/components/OpenInDesktopButton.dom.test.tsx@@ -1,7 +1,7 @@// @vitest-environment happy-dom/**- * "Edit with Framey": shown only where the preview server answers on macOS; a press opens the project in the app,+ * "Edit with Framey": shown where the preview server has the app or its download to offer; 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";@@ -45,7 +45,7 @@ async function mount(): Promise<HTMLElement> {const downloadHref = () =>[...document.querySelectorAll("a")]- .find((a) => a.textContent?.includes("Get HyperFrames Studio"))+ .find((a) => a.textContent?.includes("Get the desktop app"))?.getAttribute("href");const button = () =>@@ -68,31 +68,48 @@ it("stays hidden where the server has no hand-off (the desktop's own Studio)", aexpect(button()).toBeNull();});-it("stays hidden when the server says it cannot open the app (not macOS)", async () => {- serve(Response.json({ available: false }));+it("stays hidden when the app has no build for this machine (Windows)", async () => {+ serve(Response.json({ available: false, handoff: true, downloadUrl: null }));await mount();expect(button()).toBeNull();});+it("with the app installed but no download (Windows), shows only once the app can take the project", async () => {+ serve(Response.json({ available: true, handoff: false, downloadUrl: null }));+ await mount();+ expect(button()).toBeNull();+});++it("opens the project in an installed app that has no download (Windows)", async () => {+ serve(Response.json({ available: true, handoff: true, downloadUrl: null }), {+ opened: true,+ app: "the HyperFrames desktop app",+ });+ await mount();+ await act(async () => button()!.click());+ expect(posts).toBe(1);+});+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 });+ const linux = `${DOWNLOAD}?os=linux`;+ serve(Response.json({ available: true, handoff: false, downloadUrl: linux }), { opened: true });await mount();await act(async () => button()!.click());expect(posts).toBe(0);expect(document.body.textContent).toContain("Meet Framey");- expect(downloadHref()).toBe(DOWNLOAD);+ expect(downloadHref()).toBe(linux);});it("opens the project in the app and says so", async () => {- serve(Response.json({ available: true, handoff: true }), {+ serve(Response.json({ available: true, handoff: true, downloadUrl: DOWNLOAD }), {opened: true,- bundleId: "dev.hyperframes.desktop",+ app: "the HyperFrames desktop app",});await mount();await act(async () => button()!.click());expect(posts).toBe(1);expect(showToast).toHaveBeenCalledWith(- "Framey is opening this project in HyperFrames Studio",+ "Framey is opening this project in the HyperFrames desktop app","info",);expect(button()!.dataset.opening).toBe("true");@@ -100,7 +117,7 @@ it("opens the project in the app and says so", async () => {});it("introduces Framey and offers the download when the app is missing", async () => {- serve(Response.json({ available: true, handoff: true }), {+ serve(Response.json({ available: true, handoff: true, downloadUrl: DOWNLOAD }), {opened: false,reason: "not-installed",downloadUrl: DOWNLOAD,diff --git a/packages/studio/src/components/OpenInDesktopButton.tsx b/packages/studio/src/components/OpenInDesktopButton.tsxindex 78b2d1cd3c..a5e5698c40 100644--- a/packages/studio/src/components/OpenInDesktopButton.tsx+++ b/packages/studio/src/components/OpenInDesktopButton.tsx@@ -8,7 +8,6 @@ import { Button, buttonBase, buttonSizes, buttonVariants, cn, Popover } from "./// "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. */@@ -16,15 +15,20 @@ 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);+type DesktopRoute = { handoff: boolean; downloadUrl: string | null };++/** Null hides the button: no route (the app's own Studio), or nothing here to open or download. */+function useDesktopRoute(): DesktopRoute | null {+ const [route, setRoute] = useState<DesktopRoute | 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 });+ .then((body: { available?: unknown; handoff?: unknown; downloadUrl?: unknown } | null) => {+ if (!live || body?.available !== true) return;+ const handoff = body.handoff === true;+ const downloadUrl = typeof body.downloadUrl === "string" ? body.downloadUrl : null;+ if (handoff || downloadUrl) setRoute({ handoff, downloadUrl });}).catch(() => {});return () => {@@ -74,7 +78,7 @@ export function OpenInDesktopButton() {const open = async () => {if (!route.handoff) {trackStudioEvent("toolbar_action", { action: "open_in_desktop" });- setDownloadUrl(DOWNLOAD_URL);+ setDownloadUrl(route.downloadUrl);return;}if (opening) return;@@ -84,7 +88,7 @@ export function OpenInDesktopButton() {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");+ showToast("Framey is opening this project in the HyperFrames desktop app", "info");await new Promise((done) => setTimeout(done, OPENING_MS));} else setDownloadUrl(result.downloadUrl);} catch {@@ -114,7 +118,7 @@ export function OpenInDesktopButton() {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"+ title="Open this project in the HyperFrames 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} />}>@@ -126,9 +130,7 @@ export function OpenInDesktopButton() {<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>+ <p className="mt-2 text-balance text-text-3">I live in the free HyperFrames desktop app:</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>@@ -145,7 +147,7 @@ export function OpenInDesktopButton() {className={cn(buttonBase, buttonVariants.primary, buttonSizes.md)}onClick={() => trackStudioEvent("toolbar_action", { action: "get_desktop_app" })}>- Get HyperFrames Studio+ Get the desktop app</a></div></Popover>diff --git a/scripts/studio-runtime-smoke.mjs b/scripts/studio-runtime-smoke.mjsindex e53bf2a6ee..379f93cd21 100644--- a/scripts/studio-runtime-smoke.mjs+++ b/scripts/studio-runtime-smoke.mjs@@ -53,7 +53,14 @@ const GET_RESPONSES = new Map([// 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 })],+ [+ "/api/open-in-desktop",+ json({+ available: true,+ handoff: false,+ downloadUrl: "https://hyperframes.dev/studio/download",+ }),+ ],]);const MUTATION_RESPONSES = new Map([[`${PROJECT_PATH}/selection`, json({ ok: true, selection: null, updatedAt: null })],