Skip to content

Commit 5975dd7

Browse files
feat(studio): the desktop-app button says Install the desktop app and never dead-ends (#5854)
* feat(studio): the header's desktop-app button says Install the desktop app and never dead-ends The button now reads "Install the desktop app" beside Framey drawn as the app draws it. Where the app is installed, a press opens this project in it; a folder preview serves from a bare index.html gets its hyperframes.json first, so the app no longer refuses it. Without the app, the button links straight to hyperframes.dev's download, and a failed open lands there too. Platforms with no build of the app show no button. Telemetry now records eligibility, one impression, the click and the press outcome, with OS, app installed and download available. * feat(studio): the desktop-app button records eligibility, impression, click and outcome * feat(studio): a desktop-app press carries its page id to the download and the app hand-off * chore(studio): describe Framey's drawing without internal names * feat(studio): the desktop-app button opens a guide that walks download, install and open Without the app, the header button opens a card where Framey walks three steps: the download opens in a new tab, the install is found by asking the preview server while the card is open, and the project opens through the existing hand-off. A failed hand-off shows the folder to copy and Try again. With the app ready the press opens the project directly. Each step change is recorded through trackStudioEvent; a download is never counted as an install. * fix(studio): the desktop-app guide counts one install per page The app removed and found again on the same page recorded install_detected twice; a page latch keeps it to one, as the telemetry contract says.
1 parent b46ebed commit 5975dd7

10 files changed

Lines changed: 1329 additions & 143 deletions

File tree

‎packages/cli/src/server/desktopRoutes.test.ts‎

Lines changed: 52 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,14 @@ function server(
1919
place: { platform?: NodeJS.Platform; installed?: () => boolean } = {},
2020
) {
2121
const app = new Hono();
22-
const open = vi.fn((_dir: string): DesktopOpenResult => OPENED);
22+
const open = vi.fn((_dir: string, _cta?: string): DesktopOpenResult => OPENED);
2323
mountDesktopRoutes(app, "/films/a", { ready, open, ...place });
24-
const post = (headers: Record<string, string>) =>
25-
app.request("/api/open-in-desktop", { method: "POST", headers });
24+
const post = (headers: Record<string, string>, body?: unknown) =>
25+
app.request("/api/open-in-desktop", {
26+
method: "POST",
27+
headers: body === undefined ? headers : { ...headers, "content-type": "application/json" },
28+
body: body === undefined ? undefined : JSON.stringify(body),
29+
});
2630
return { app, open, post };
2731
}
2832

@@ -32,7 +36,13 @@ describe("open-in-desktop routes", () => {
3236
await server(false, { installed: () => false }).app.request("/api/open-in-desktop")
3337
).json();
3438
const downloadUrl = desktopDownloadUrl();
35-
expect(body).toEqual({ available: downloadUrl !== null, handoff: false, downloadUrl });
39+
expect(body).toEqual({
40+
available: downloadUrl !== null,
41+
handoff: false,
42+
downloadUrl,
43+
os: process.platform,
44+
installed: false,
45+
});
3646
});
3747

3848
it("shows the button where the app is installed even without a download (Windows)", async () => {
@@ -42,10 +52,33 @@ describe("open-in-desktop routes", () => {
4252
"/api/open-in-desktop",
4353
)
4454
).json();
45-
expect(await get(true)).toEqual({ available: true, handoff: true, downloadUrl: null });
55+
expect(await get(true)).toEqual({
56+
available: true,
57+
handoff: true,
58+
downloadUrl: null,
59+
os: "win32",
60+
installed: true,
61+
});
4662
expect(await get(false)).toMatchObject({ available: false });
4763
});
4864

65+
it("offers the hand-off only where the app is installed, so a press without it goes to the download", async () => {
66+
const get = async (installed: boolean) =>
67+
(
68+
await server(true, { platform: "darwin", installed: () => installed }).app.request(
69+
"/api/open-in-desktop",
70+
)
71+
).json();
72+
expect(await get(true)).toMatchObject({ available: true, handoff: true });
73+
expect(await get(false)).toEqual({
74+
available: true,
75+
handoff: false,
76+
downloadUrl: desktopDownloadUrl("darwin"),
77+
os: "darwin",
78+
installed: false,
79+
});
80+
});
81+
4982
it("refuses a POST from another site, or through a rebound host name", async () => {
5083
const { open, post } = server(true);
5184
const crossSite = { ...STUDIO, origin: "https://evil.example", "sec-fetch-site": "cross-site" };
@@ -67,7 +100,20 @@ describe("open-in-desktop routes", () => {
67100
it("once live, opens this server's project for Studio's own POST", async () => {
68101
const { open, post } = server(true);
69102
expect(await (await post(STUDIO)).json()).toEqual(OPENED);
70-
expect(open).toHaveBeenCalledWith("/films/a");
103+
expect(open).toHaveBeenCalledWith("/films/a", undefined);
104+
});
105+
106+
it("passes the press's page id on to the hand-off, and drops anything that is not one", async () => {
107+
const { open, post } = server(true);
108+
const id = "3f2b8c1e-9a4d-4e7b-8c21-5d6e7f8a9b0c";
109+
await post(STUDIO, { cta: id });
110+
await post(STUDIO, { cta: "../../etc/passwd" });
111+
await post(STUDIO, { cta: 42 });
112+
expect(open.mock.calls).toEqual([
113+
["/films/a", id],
114+
["/films/a", undefined],
115+
["/films/a", undefined],
116+
]);
71117
});
72118
});
73119

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

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ import {
77
} from "../utils/desktopApp.js";
88
import { identityAllowed } from "./telemetryIdentity.js";
99

10+
const CTA_ID = /^[A-Za-z0-9-]{1,64}$/;
11+
1012
/** A bodiless POST is a simple request, so any page can send one to localhost: it has to come from this Studio. */
1113
export function sameOriginPost(headers: {
1214
host?: string;
@@ -19,22 +21,29 @@ export function sameOriginPost(headers: {
1921
return origin === undefined || origin === `http://${host}`;
2022
}
2123

22-
/** Edit with Framey's route: whether to show it, where to download, and whether the app takes the project. */
24+
/** The desktop-app button's route: show it or not, the download, and whether the app here takes the project. */
2325
export function mountDesktopRoutes(
2426
app: Hono,
2527
projectDir: string,
2628
{
2729
ready = HANDOFF_READY,
28-
open = openInDesktop,
30+
open = (dir: string, cta?: string) => openInDesktop(dir, { cta }),
2931
platform = process.platform,
3032
installed = () => desktopInstalled({ platform }),
3133
} = {},
3234
): void {
3335
const downloadUrl = desktopDownloadUrl(platform);
34-
app.get("/api/open-in-desktop", (c) =>
35-
c.json({ available: downloadUrl !== null || installed(), handoff: ready, downloadUrl }),
36-
);
37-
app.post("/api/open-in-desktop", (c) => {
36+
app.get("/api/open-in-desktop", (c) => {
37+
const here = installed();
38+
return c.json({
39+
available: downloadUrl !== null || here,
40+
handoff: ready && here,
41+
downloadUrl,
42+
os: platform,
43+
installed: here,
44+
});
45+
});
46+
app.post("/api/open-in-desktop", async (c) => {
3847
const allowed = sameOriginPost({
3948
host: c.req.header("host"),
4049
origin: c.req.header("origin"),
@@ -47,6 +56,8 @@ export function mountDesktopRoutes(
4756
reason: "handoff-unavailable",
4857
downloadUrl,
4958
});
50-
return c.json(open(projectDir));
59+
const body: unknown = await c.req.json().catch(() => null);
60+
const cta = (body as { cta?: unknown } | null)?.cta;
61+
return c.json(open(projectDir, typeof cta === "string" && CTA_ID.test(cta) ? cta : undefined));
5162
});
5263
}

‎packages/cli/src/utils/desktopApp.test.ts‎

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,15 @@
1-
import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
1+
import {
2+
chmodSync,
3+
existsSync,
4+
mkdtempSync,
5+
readdirSync,
6+
readFileSync,
7+
rmSync,
8+
writeFileSync,
9+
} from "node:fs";
210
import { tmpdir } from "node:os";
311
import { join, resolve, win32 } from "node:path";
12+
import { isHyperframesProject } from "@hyperframes/core";
413
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
514
import { readSeen } from "./appHistory.js";
615
import {
@@ -43,6 +52,48 @@ describe("openInDesktop", () => {
4352
expect(asked).toEqual([`dev.hyperframes.desktop ${FILM}`]);
4453
});
4554

55+
it("hands over a folder preview serves from a bare index.html as a project the app accepts", () => {
56+
const dir = mkdtempSync(join(tmpdir(), "hf-bare-"));
57+
try {
58+
writeFileSync(join(dir, "index.html"), "<html></html>");
59+
let marked: boolean | null = null;
60+
const result = openInDesktop(dir, {
61+
...LIVE,
62+
open: (_id, folder) => ((marked = isHyperframesProject(readdirSync(folder))), true),
63+
});
64+
expect(result).toMatchObject({ opened: true });
65+
expect(marked).toBe(true);
66+
} finally {
67+
rmSync(dir, { recursive: true, force: true });
68+
}
69+
});
70+
71+
it("leaves the press's page id for the app only when the app took the folder", () => {
72+
const dir = mkdtempSync(join(tmpdir(), "hf-cta-"));
73+
const record = join(dir, ".hyperframes", "desktop-cta.json");
74+
try {
75+
writeFileSync(join(dir, "index.html"), "<html></html>");
76+
openInDesktop(dir, { ...LIVE, cta: "page-1", open: () => false, installed: () => false });
77+
expect(existsSync(record)).toBe(false);
78+
openInDesktop(dir, { ...LIVE, cta: "page-1", open: () => true });
79+
expect(JSON.parse(readFileSync(record, "utf8"))).toMatchObject({ cta: "page-1" });
80+
} finally {
81+
rmSync(dir, { recursive: true, force: true });
82+
}
83+
});
84+
85+
it("leaves a project's own marker file alone", () => {
86+
const dir = mkdtempSync(join(tmpdir(), "hf-marked-"));
87+
try {
88+
writeFileSync(join(dir, "index.html"), "<html></html>");
89+
writeFileSync(join(dir, "meta.json"), "{}");
90+
openInDesktop(dir, { ...LIVE, open: () => true });
91+
expect(existsSync(join(dir, "hyperframes.json"))).toBe(false);
92+
} finally {
93+
rmSync(dir, { recursive: true, force: true });
94+
}
95+
});
96+
4697
it("falls back to Canary when only Canary is installed", () => {
4798
const result = openInDesktop(FILM, { ...LIVE, open: (id) => id.endsWith(".canary") });
4899
expect(result).toMatchObject({ opened: true, app: "HyperFrames Canary" });

‎packages/cli/src/utils/desktopApp.ts‎

Lines changed: 27 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
import { spawn, spawnSync } from "node:child_process";
2-
import { existsSync, readFileSync } from "node:fs";
2+
import { existsSync, readdirSync, readFileSync } from "node:fs";
33
import { homedir } from "node:os";
44
import { basename, isAbsolute, join, relative, win32 } from "node:path";
5+
import { isHyperframesProject } from "@hyperframes/core";
56
import { addCatchUpNote, markSeen, readSeen } from "./appHistory.js";
7+
import { createProjectConfig } from "./projectConfig.js";
68
import { writeRecord } from "./projectRecords.js";
79

810
// The HyperFrames desktop app (not "Studio"): `open -b` on macOS, its executable elsewhere; released, then Canary.
@@ -32,6 +34,8 @@ export interface AgentSession {
3234
}
3335

3436
export const AGENT_HANDOFF_FILE = join(".hyperframes", "agent-handoff.json");
37+
/** The Studio page's telemetry `tab_id`, left for the app to report its first open and export against. */
38+
const DESKTOP_CTA_RECORD = "desktop-cta.json";
3539

3640
// ponytail: Claude Code, then Codex, then Grok; an agent started inside another's shell carries both, unsorted.
3741
export function agentSession(env: NodeJS.ProcessEnv = process.env): AgentSession | null {
@@ -131,6 +135,17 @@ function leaveHandoff(dir: string, session: AgentSession | null): AgentSession |
131135
return session;
132136
}
133137

138+
function markBareIndexAsProject(dir: string): void {
139+
try {
140+
if (existsSync(join(dir, "index.html")) && !isHyperframesProject(readdirSync(dir)))
141+
createProjectConfig(dir);
142+
} catch (error) {
143+
console.warn(
144+
`◇ Couldn't add hyperframes.json to ${dir}, so the app may not open it: ${error}`,
145+
);
146+
}
147+
}
148+
134149
// ponytail: success on Windows and Linux means the spawn started, not that the app took the folder; wait for the
135150
// app's own acknowledgement if a broken install ever needs reporting.
136151
export function openInDesktop(
@@ -142,8 +157,10 @@ export function openInDesktop(
142157
launch = launchApp,
143158
installed = () => desktopInstalled({ platform }),
144159
env = process.env,
160+
cta,
145161
...where
146162
}: AppLookup & {
163+
cta?: string;
147164
ready?: boolean;
148165
open?: (bundleId: string, dir: string) => boolean;
149166
launch?: (executable: string, dir: string) => boolean;
@@ -157,12 +174,16 @@ export function openInDesktop(
157174
reason,
158175
downloadUrl: desktopDownloadUrl(platform) ?? STUDIO_PAGE,
159176
});
160-
const opened = (canary: boolean): DesktopOpenResult => ({
161-
opened: true,
162-
app: canary ? "HyperFrames Canary" : "the HyperFrames desktop app",
163-
handedOver: leaveHandoff(dir, agentSession(env)),
164-
});
177+
const opened = (canary: boolean): DesktopOpenResult => {
178+
if (cta) writeRecord(dir, DESKTOP_CTA_RECORD, JSON.stringify({ cta, at: Date.now() }));
179+
return {
180+
opened: true,
181+
app: canary ? "HyperFrames Canary" : "the HyperFrames desktop app",
182+
handedOver: leaveHandoff(dir, agentSession(env)),
183+
};
184+
};
165185
if (!ready) return notOpened("handoff-unavailable");
186+
markBareIndexAsProject(dir);
166187
if (platform === "darwin") {
167188
const bundleId = DESKTOP_BUNDLE_IDS.find((id) => open(id, dir));
168189
if (!bundleId) return notOpened(installed() ? "open-failed" : "not-installed");

0 commit comments

Comments
 (0)