Skip to content

Commit 58934a3

Browse files
feat(studio,cli): add an Edit with Framey button and hyperframes open for HyperFrames Studio
Point people from the CLI and the Studio preview to HyperFrames Studio, the desktop app. - Studio header: an "Edit with Framey" button with Framey, the app's cursor mascot (the eye follows the pointer, a wiggle on hover, honours reduced motion). Until the app opens handed-over projects (HANDOFF_READY), a press shows a "Meet Framey" card with the download. The button shows only where the preview server answers GET /api/open-in-desktop on macOS, so the desktop app's own embedded Studio never shows it. - `hyperframes open [dir]`: hands the project folder to the app with `open -b` (released app, then Canary) and points to the download when neither is installed. When run by Claude Code or Codex it leaves .hyperframes/agent-handoff.json (CLAUDE_CODE_SESSION_ID / CODEX_THREAD_ID) so the app's first chat can pick up that conversation. - render and preview print one line about the app: the download until HANDOFF_READY, then `hyperframes open` when the app is installed. Nothing for a draft render, a batch row, or a run inside the app (HYPERFRAMES_DESKTOP_PROJECT).
1 parent ce08f20 commit 58934a3

16 files changed

Lines changed: 722 additions & 5 deletions

‎packages/cli/src/cli.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,7 @@ const commandLoaders = {
152152
preview: () =>
153153
assertStudioWorkspaceBuilt().then(() => import("./commands/preview.js").then((m) => m.default)),
154154
publish: () => import("./commands/publish.js").then((m) => m.default),
155+
open: () => import("./commands/open.js").then((m) => m.default),
155156
render: () => import("./commands/render.js").then((m) => m.default),
156157
lint: () => import("./commands/lint.js").then((m) => m.default),
157158
check: () => import("./commands/check.js").then((m) => m.default),

‎packages/cli/src/commands/open.ts‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
import { defineCommand } from "citty";
2+
import type { Example } from "./_examples.js";
3+
import { c } from "../ui/colors.js";
4+
import { openInDesktop } from "../utils/desktopApp.js";
5+
import { resolveProject } from "../utils/project.js";
6+
7+
export const examples: Example[] = [
8+
["Open this project in HyperFrames Studio", "hyperframes open"],
9+
["Open another project", "hyperframes open ./my-video"],
10+
["For agents", "hyperframes open --json"],
11+
];
12+
13+
export default defineCommand({
14+
meta: { name: "open", description: "Open a project in HyperFrames Studio, the desktop app" },
15+
args: {
16+
dir: {
17+
type: "positional",
18+
description: "Project directory (default: current)",
19+
required: false,
20+
},
21+
json: { type: "boolean", description: "Output as JSON", default: false },
22+
},
23+
run({ args }) {
24+
const project = resolveProject(args.dir);
25+
const result = openInDesktop(project.dir);
26+
if (args.json) {
27+
console.log(JSON.stringify({ project: project.dir, ...result }, null, 2));
28+
return;
29+
}
30+
if (result.opened) {
31+
console.log(`${c.success("◇")} Opening ${c.accent(project.name)} in HyperFrames Studio`);
32+
if (result.handedOver) {
33+
const agent = result.handedOver.engine === "claude" ? "Claude Code" : "Codex";
34+
console.log(` ${c.dim(`Its chat picks up this ${agent} conversation.`)}`);
35+
}
36+
return;
37+
}
38+
console.log(
39+
result.reason === "not-installed"
40+
? `${c.warn("◇")} HyperFrames Studio isn't installed on this Mac.`
41+
: `${c.warn("◇")} Opening a project from the CLI works on macOS only for now.`,
42+
);
43+
console.log(` Download it: ${c.accent(result.downloadUrl)}`);
44+
},
45+
});

‎packages/cli/src/commands/preview.ts‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ import { fileURLToPath } from "node:url";
3939
import { createRequire } from "node:module";
4040
import * as clack from "@clack/prompts";
4141
import { c } from "../ui/colors.js";
42+
import { desktopHint } from "../utils/desktopApp.js";
4243
import { isDevMode } from "../utils/env.js";
4344
import { normalizeErrorMessage as errorMessage } from "../utils/errorMessage.js";
4445
import { buildNpxCommand } from "../utils/npxCommand.js";
@@ -365,7 +366,7 @@ export default defineCommand({
365366
);
366367
return;
367368
}
368-
printStudioSummary(project.name, previewBaseUrl(status.port), {
369+
printStudioSummary(project.name, previewBaseUrl(status.port), project.dir, {
369370
details: [`Background preview running (PID ${status.pid}).`, `Log: ${status.logPath}`],
370371
});
371372
return;
@@ -539,7 +540,7 @@ export default defineCommand({
539540
);
540541
} else {
541542
clack.intro(c.bold("hyperframes preview"));
542-
printStudioSummary(projectName, url, {
543+
printStudioSummary(projectName, url, dir, {
543544
details: [
544545
background.type === "reused"
545546
? "Reusing the background server already running for this project."
@@ -1282,13 +1283,16 @@ function openStudioBrowser(url: string, projectName: string, options?: BrowserLa
12821283
function printStudioSummary(
12831284
projectName: string,
12841285
serverUrl: string,
1286+
projectDir: string,
12851287
opts: { details?: string[]; footer?: string } = {},
12861288
): void {
12871289
const urls = studioSummaryUrls(projectName, serverUrl);
12881290
console.log();
12891291
console.log(` ${c.dim("Project")} ${c.accent(projectName)}`);
12901292
console.log(` ${c.dim("Studio")} ${c.accent(urls.studioUrl)}`);
12911293
console.log(` ${c.dim("Server")} ${c.accent(urls.serverUrl)}`);
1294+
const hint = desktopHint(projectDir);
1295+
if (hint) console.log(` ${c.dim("Desktop")} ${hint}`);
12921296
console.log();
12931297
for (const detail of opts.details ?? []) {
12941298
console.log(` ${c.dim(detail)}`);
@@ -1395,7 +1399,7 @@ function attachStudioReadyHandler(
13951399
);
13961400
} else {
13971401
spinner.stop(c.success("Studio running"));
1398-
printStudioSummary(projectName, url, {
1402+
printStudioSummary(projectName, url, projectDir, {
13991403
footer: "Press Ctrl+C to stop",
14001404
});
14011405
}
@@ -1629,7 +1633,7 @@ async function runEmbeddedMode(
16291633
);
16301634
} else {
16311635
s.stop(c.success("Already running"));
1632-
printStudioSummary(pName, url, {
1636+
printStudioSummary(pName, url, dir, {
16331637
details: ["Reusing existing server. Use --force-new to start a fresh instance."],
16341638
});
16351639
}
@@ -1647,7 +1651,7 @@ async function runEmbeddedMode(
16471651
console.log(` ${c.warn(`Port ${startPort} is in use, using ${result.port} instead`)}`);
16481652
console.log();
16491653
}
1650-
printStudioSummary(pName, url, {
1654+
printStudioSummary(pName, url, dir, {
16511655
details: [
16521656
"Edit with your AI agent — it has HyperFrames skills installed.",
16531657
"Changes reload automatically in the studio.",

‎packages/cli/src/commands/render.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ import { resolve, dirname, join, basename } from "node:path";
6262
import { execFileSync, spawn } from "node:child_process";
6363
import { loadProducer } from "../utils/producer.js";
6464
import { c } from "../ui/colors.js";
65+
import { desktopHint } from "../utils/desktopApp.js";
6566
import {
6667
formatBytes,
6768
formatRenderSummaryDetail,
@@ -524,6 +525,8 @@ export interface RenderOptions {
524525
throwOnError?: boolean;
525526
/** Skip the interactive feedback prompt after a successful render. */
526527
skipFeedback?: boolean;
528+
/** False for a batch row: one line about the desktop app per batch is noise, not a pointer. */
529+
desktopHint?: boolean;
527530
/**
528531
* OPT IN to managing the DE parallel-router circuit breaker
529532
* (`applyDeParallelRouterCircuitBreaker`) for this render. Default OFF —
@@ -886,6 +889,8 @@ async function renderDocker(
886889
runPostRenderStep("printRenderComplete", () =>
887890
printRenderComplete({
888891
outputPath,
892+
projectDir,
893+
desktopHint: options.desktopHint !== false && options.quality !== "draft",
889894
elapsedMs: elapsed,
890895
quiet: options.quiet,
891896
format: options.format,
@@ -1138,6 +1143,8 @@ async function executeLocalRender(
11381143
runPostRenderStep("printRenderComplete", () =>
11391144
printRenderComplete({
11401145
outputPath,
1146+
projectDir,
1147+
desktopHint: options.desktopHint !== false && options.quality !== "draft",
11411148
elapsedMs: elapsed,
11421149
quiet: options.quiet,
11431150
format: options.format,
@@ -1900,6 +1907,9 @@ function readOutputFootprint(outputPath: string): { fileSize: string; isDirector
19001907

19011908
function printRenderComplete(input: {
19021909
outputPath: string;
1910+
projectDir: string;
1911+
/** Print the desktop-app line: a delivered render, never a draft or a batch row. */
1912+
desktopHint: boolean;
19031913
elapsedMs: number;
19041914
quiet: boolean;
19051915
format: RenderFormat;
@@ -1920,6 +1930,8 @@ function printRenderComplete(input: {
19201930
console.log(c.success("\u25C7") + " " + c.accent(outputPath));
19211931
console.log(" " + c.bold(fileSize) + c.dim(" \u00B7 " + detail));
19221932
if (perf) printRenderPipeline(perf, input.requestedGpuMode);
1933+
const hint = input.desktopHint ? desktopHint(input.projectDir) : null;
1934+
if (hint) console.log(" " + c.dim(hint));
19231935
}
19241936

19251937
function printRenderPipeline(

‎packages/cli/src/commands/render/execute.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -365,6 +365,7 @@ async function executeBatchRender(
365365
exitAfterComplete: false,
366366
throwOnError: true,
367367
skipFeedback: true,
368+
desktopHint: false,
368369
manageDeParallelRouterBreaker: plan.batchConcurrency <= 1,
369370
};
370371
const manifest = await batchModule.runBatchRender({

‎packages/cli/src/help.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ const GROUPS: Group[] = [
2727
["present", "Open a slideshow deck in presenter mode (with audience sync)"],
2828
["publish", "Upload a project to a stable URL (private by default)"],
2929
["render", "Render a composition to MP4 or WebM"],
30+
["open", "Open a project in HyperFrames Studio, the desktop app"],
3031
],
3132
},
3233
{

‎packages/cli/src/server/studioServer.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -966,6 +966,15 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
966966
});
967967
});
968968

969+
// HyperFrames Studio, the desktop app: the header's "Open in app" asks this server, which runs on the person's Mac,
970+
// to hand the project folder over (`hyperframes open`'s `open -b`). The desktop's own Studio has no such route, so
971+
// the button stays hidden there.
972+
app.get("/api/open-in-desktop", (c) => c.json({ available: process.platform === "darwin" }));
973+
app.post("/api/open-in-desktop", async (c) => {
974+
const { openInDesktop } = await import("../utils/desktopApp.js");
975+
return c.json(openInDesktop(projectDir));
976+
});
977+
969978
// ── Pre-flight checks for render ────────────────────────────────────────
970979
// Intercept render requests before they reach the shared API so we can
971980
// fail fast with an actionable hint instead of burning through the entire
Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
2+
import { tmpdir } from "node:os";
3+
import { join } from "node:path";
4+
import { afterEach, describe, expect, it } from "vitest";
5+
import {
6+
AGENT_HANDOFF_FILE,
7+
DESKTOP_DOWNLOAD_URL,
8+
HANDOFF_READY,
9+
agentSession,
10+
desktopHint,
11+
desktopInstalled,
12+
openCommandFor,
13+
openInDesktop,
14+
} from "./desktopApp.js";
15+
16+
const NO_AGENT = {};
17+
18+
describe("openInDesktop", () => {
19+
it("hands the folder to the released app when it is installed", () => {
20+
const asked: string[] = [];
21+
const result = openInDesktop("/films/a", {
22+
platform: "darwin",
23+
open: (id, dir) => (asked.push(`${id} ${dir}`), true),
24+
env: NO_AGENT,
25+
});
26+
expect(result).toEqual({ opened: true, bundleId: "dev.hyperframes.desktop", handedOver: null });
27+
expect(asked).toEqual(["dev.hyperframes.desktop /films/a"]);
28+
});
29+
30+
it("falls back to Canary when only Canary is installed", () => {
31+
const result = openInDesktop("/films/a", {
32+
platform: "darwin",
33+
open: (id) => id.endsWith(".canary"),
34+
env: NO_AGENT,
35+
});
36+
expect(result).toMatchObject({ opened: true, bundleId: "dev.hyperframes.desktop.canary" });
37+
});
38+
39+
it("points to the download when no app is installed", () => {
40+
const result = openInDesktop("/films/a", { platform: "darwin", open: () => false });
41+
expect(result).toEqual({
42+
opened: false,
43+
reason: "not-installed",
44+
downloadUrl: DESKTOP_DOWNLOAD_URL,
45+
});
46+
});
47+
48+
it("never runs `open` off macOS", () => {
49+
const result = openInDesktop("C:\\films\\a", {
50+
platform: "win32",
51+
open: () => {
52+
throw new Error("must not run");
53+
},
54+
});
55+
expect(result).toMatchObject({ opened: false, reason: "unsupported-platform" });
56+
});
57+
});
58+
59+
describe("agent hand-off", () => {
60+
let dir: string | undefined;
61+
afterEach(() => dir && rmSync(dir, { recursive: true, force: true }));
62+
const handoff = () => join(dir!, AGENT_HANDOFF_FILE);
63+
64+
it("names the conversation the command runs in, Claude Code first", () => {
65+
expect(agentSession({ CLAUDE_CODE_SESSION_ID: "c-1", CODEX_THREAD_ID: "x-1" })).toEqual({
66+
engine: "claude",
67+
sessionId: "c-1",
68+
});
69+
expect(agentSession({ CODEX_THREAD_ID: "x-1" })).toEqual({ engine: "codex", sessionId: "x-1" });
70+
expect(agentSession({})).toBeNull();
71+
});
72+
73+
it("leaves the app the conversation once it has the folder", () => {
74+
dir = mkdtempSync(join(tmpdir(), "hf-handoff-"));
75+
const result = openInDesktop(dir, {
76+
platform: "darwin",
77+
open: () => true,
78+
env: { CLAUDE_CODE_SESSION_ID: "0a8eed95-0869-45bf-83ec-5d71fcc5236c" },
79+
});
80+
expect(result).toMatchObject({ opened: true, handedOver: { engine: "claude" } });
81+
expect(JSON.parse(readFileSync(handoff(), "utf8"))).toEqual({
82+
engine: "claude",
83+
sessionId: "0a8eed95-0869-45bf-83ec-5d71fcc5236c",
84+
});
85+
});
86+
87+
it("writes nothing when no app took the folder, or no agent runs the command", () => {
88+
dir = mkdtempSync(join(tmpdir(), "hf-handoff-"));
89+
openInDesktop(dir, { platform: "darwin", open: () => false, env: { CODEX_THREAD_ID: "x-1" } });
90+
openInDesktop(dir, { platform: "darwin", open: () => true, env: {} });
91+
expect(existsSync(handoff())).toBe(false);
92+
});
93+
});
94+
95+
describe("openCommandFor", () => {
96+
it("names the project relative to where the person is", () => {
97+
expect(openCommandFor("/work/films/a", "/work/films/a")).toBe("hyperframes open .");
98+
expect(openCommandFor("/work/films/a", "/work")).toBe("hyperframes open films/a");
99+
expect(openCommandFor("/work/my film", "/work")).toBe('hyperframes open "my film"');
100+
});
101+
});
102+
103+
describe("desktopInstalled", () => {
104+
const nothing = {
105+
platform: "darwin",
106+
home: "/Users/a",
107+
exists: () => false,
108+
spotlight: () => false,
109+
};
110+
111+
it("finds the app where the DMG and the installer put it, Canary included", () => {
112+
expect(
113+
desktopInstalled({
114+
...nothing,
115+
exists: (p: string) => p === "/Applications/HyperFrames Canary.app",
116+
}),
117+
).toBe(true);
118+
expect(
119+
desktopInstalled({
120+
...nothing,
121+
exists: (p: string) => p === "/Users/a/Applications/HyperFrames.app",
122+
}),
123+
).toBe(true);
124+
});
125+
126+
it("asks Spotlight for one installed anywhere else", () => {
127+
expect(
128+
desktopInstalled({ ...nothing, spotlight: (id: string) => id === "dev.hyperframes.desktop" }),
129+
).toBe(true);
130+
expect(desktopInstalled(nothing)).toBe(false);
131+
});
132+
133+
it("is never there off macOS", () => {
134+
expect(desktopInstalled({ ...nothing, platform: "linux", exists: () => true })).toBe(false);
135+
});
136+
});
137+
138+
describe("desktopHint", () => {
139+
const OUTSIDE = {};
140+
const download = `Edit it by chatting with Framey in HyperFrames Studio → ${DESKTOP_DOWNLOAD_URL}`;
141+
142+
it("points to the download when the app is missing", () => {
143+
expect(desktopHint(process.cwd(), { env: OUTSIDE, installed: false })).toBe(download);
144+
});
145+
146+
it("points an installed app to `hyperframes open` once the app opens handed-over projects", () => {
147+
expect(desktopHint(process.cwd(), { env: OUTSIDE, installed: true })).toBe(
148+
HANDOFF_READY ? "Edit it with Framey: hyperframes open ." : download,
149+
);
150+
});
151+
152+
it("says nothing inside the app, whose runs carry HYPERFRAMES_DESKTOP_PROJECT", () => {
153+
expect(
154+
desktopHint(process.cwd(), { env: { HYPERFRAMES_DESKTOP_PROJECT: "/p" }, installed: true }),
155+
).toBeNull();
156+
});
157+
});

0 commit comments

Comments
 (0)