Skip to content

Write HTML. Render video. Built for agents.

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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): AgentSession
return 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.tsx
index 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)", a
expect(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.tsx
index 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.mjs
index 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 })],