Skip to content

Write HTML. Render video. Built for agents.

feat(studio): the desktop-app button says Install the desktop app and never dead-ends (#5854)

Miguel Ángel5975dd7579bf
diff --git a/packages/cli/src/server/desktopRoutes.test.ts b/packages/cli/src/server/desktopRoutes.test.ts
index 986ca3cd5a..c583de0aac 100644
--- a/packages/cli/src/server/desktopRoutes.test.ts
+++ b/packages/cli/src/server/desktopRoutes.test.ts
@@ -19,10 +19,14 @@ function server(
place: { platform?: NodeJS.Platform; installed?: () => boolean } = {},
) {
const app = new Hono();
- const open = vi.fn((_dir: string): DesktopOpenResult => OPENED);
+ const open = vi.fn((_dir: string, _cta?: string): DesktopOpenResult => OPENED);
mountDesktopRoutes(app, "/films/a", { ready, open, ...place });
- const post = (headers: Record<string, string>) =>
- app.request("/api/open-in-desktop", { method: "POST", headers });
+ const post = (headers: Record<string, string>, body?: unknown) =>
+ app.request("/api/open-in-desktop", {
+ method: "POST",
+ headers: body === undefined ? headers : { ...headers, "content-type": "application/json" },
+ body: body === undefined ? undefined : JSON.stringify(body),
+ });
return { app, open, post };
}
@@ -32,7 +36,13 @@ describe("open-in-desktop routes", () => {
await server(false, { installed: () => false }).app.request("/api/open-in-desktop")
).json();
const downloadUrl = desktopDownloadUrl();
- expect(body).toEqual({ available: downloadUrl !== null, handoff: false, downloadUrl });
+ expect(body).toEqual({
+ available: downloadUrl !== null,
+ handoff: false,
+ downloadUrl,
+ os: process.platform,
+ installed: false,
+ });
});
it("shows the button where the app is installed even without a download (Windows)", async () => {
@@ -42,10 +52,33 @@ describe("open-in-desktop routes", () => {
"/api/open-in-desktop",
)
).json();
- expect(await get(true)).toEqual({ available: true, handoff: true, downloadUrl: null });
+ expect(await get(true)).toEqual({
+ available: true,
+ handoff: true,
+ downloadUrl: null,
+ os: "win32",
+ installed: true,
+ });
expect(await get(false)).toMatchObject({ available: false });
});
+ it("offers the hand-off only where the app is installed, so a press without it goes to the download", async () => {
+ const get = async (installed: boolean) =>
+ (
+ await server(true, { platform: "darwin", installed: () => installed }).app.request(
+ "/api/open-in-desktop",
+ )
+ ).json();
+ expect(await get(true)).toMatchObject({ available: true, handoff: true });
+ expect(await get(false)).toEqual({
+ available: true,
+ handoff: false,
+ downloadUrl: desktopDownloadUrl("darwin"),
+ os: "darwin",
+ installed: false,
+ });
+ });
+
it("refuses a POST from another site, or through a rebound host name", async () => {
const { open, post } = server(true);
const crossSite = { ...STUDIO, origin: "https://evil.example", "sec-fetch-site": "cross-site" };
@@ -67,7 +100,20 @@ describe("open-in-desktop routes", () => {
it("once live, opens this server's project for Studio's own POST", async () => {
const { open, post } = server(true);
expect(await (await post(STUDIO)).json()).toEqual(OPENED);
- expect(open).toHaveBeenCalledWith("/films/a");
+ expect(open).toHaveBeenCalledWith("/films/a", undefined);
+ });
+
+ it("passes the press's page id on to the hand-off, and drops anything that is not one", async () => {
+ const { open, post } = server(true);
+ const id = "3f2b8c1e-9a4d-4e7b-8c21-5d6e7f8a9b0c";
+ await post(STUDIO, { cta: id });
+ await post(STUDIO, { cta: "../../etc/passwd" });
+ await post(STUDIO, { cta: 42 });
+ expect(open.mock.calls).toEqual([
+ ["/films/a", id],
+ ["/films/a", undefined],
+ ["/films/a", undefined],
+ ]);
});
});
diff --git a/packages/cli/src/server/desktopRoutes.ts b/packages/cli/src/server/desktopRoutes.ts
index 3aa88df89f..54fc22023e 100644
--- a/packages/cli/src/server/desktopRoutes.ts
+++ b/packages/cli/src/server/desktopRoutes.ts
@@ -7,6 +7,8 @@ import {
} from "../utils/desktopApp.js";
import { identityAllowed } from "./telemetryIdentity.js";
+const CTA_ID = /^[A-Za-z0-9-]{1,64}$/;
+
/** A bodiless POST is a simple request, so any page can send one to localhost: it has to come from this Studio. */
export function sameOriginPost(headers: {
host?: string;
@@ -19,22 +21,29 @@ export function sameOriginPost(headers: {
return origin === undefined || origin === `http://${host}`;
}
-/** Edit with Framey's route: whether to show it, where to download, and whether the app takes the project. */
+/** The desktop-app button's route: show it or not, the download, and whether the app here takes the project. */
export function mountDesktopRoutes(
app: Hono,
projectDir: string,
{
ready = HANDOFF_READY,
- open = openInDesktop,
+ open = (dir: string, cta?: string) => openInDesktop(dir, { cta }),
platform = process.platform,
installed = () => desktopInstalled({ platform }),
} = {},
): void {
const downloadUrl = desktopDownloadUrl(platform);
- app.get("/api/open-in-desktop", (c) =>
- c.json({ available: downloadUrl !== null || installed(), handoff: ready, downloadUrl }),
- );
- app.post("/api/open-in-desktop", (c) => {
+ app.get("/api/open-in-desktop", (c) => {
+ const here = installed();
+ return c.json({
+ available: downloadUrl !== null || here,
+ handoff: ready && here,
+ downloadUrl,
+ os: platform,
+ installed: here,
+ });
+ });
+ app.post("/api/open-in-desktop", async (c) => {
const allowed = sameOriginPost({
host: c.req.header("host"),
origin: c.req.header("origin"),
@@ -47,6 +56,8 @@ export function mountDesktopRoutes(
reason: "handoff-unavailable",
downloadUrl,
});
- return c.json(open(projectDir));
+ const body: unknown = await c.req.json().catch(() => null);
+ const cta = (body as { cta?: unknown } | null)?.cta;
+ return c.json(open(projectDir, typeof cta === "string" && CTA_ID.test(cta) ? cta : undefined));
});
}
diff --git a/packages/cli/src/utils/desktopApp.test.ts b/packages/cli/src/utils/desktopApp.test.ts
index f68639df85..038a6de2be 100644
--- a/packages/cli/src/utils/desktopApp.test.ts
+++ b/packages/cli/src/utils/desktopApp.test.ts
@@ -1,6 +1,15 @@
-import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+ chmodSync,
+ existsSync,
+ mkdtempSync,
+ readdirSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from "node:fs";
import { tmpdir } from "node:os";
import { join, resolve, win32 } from "node:path";
+import { isHyperframesProject } from "@hyperframes/core";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { readSeen } from "./appHistory.js";
import {
@@ -43,6 +52,48 @@ describe("openInDesktop", () => {
expect(asked).toEqual([`dev.hyperframes.desktop ${FILM}`]);
});
+ it("hands over a folder preview serves from a bare index.html as a project the app accepts", () => {
+ const dir = mkdtempSync(join(tmpdir(), "hf-bare-"));
+ try {
+ writeFileSync(join(dir, "index.html"), "<html></html>");
+ let marked: boolean | null = null;
+ const result = openInDesktop(dir, {
+ ...LIVE,
+ open: (_id, folder) => ((marked = isHyperframesProject(readdirSync(folder))), true),
+ });
+ expect(result).toMatchObject({ opened: true });
+ expect(marked).toBe(true);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ it("leaves the press's page id for the app only when the app took the folder", () => {
+ const dir = mkdtempSync(join(tmpdir(), "hf-cta-"));
+ const record = join(dir, ".hyperframes", "desktop-cta.json");
+ try {
+ writeFileSync(join(dir, "index.html"), "<html></html>");
+ openInDesktop(dir, { ...LIVE, cta: "page-1", open: () => false, installed: () => false });
+ expect(existsSync(record)).toBe(false);
+ openInDesktop(dir, { ...LIVE, cta: "page-1", open: () => true });
+ expect(JSON.parse(readFileSync(record, "utf8"))).toMatchObject({ cta: "page-1" });
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ it("leaves a project's own marker file alone", () => {
+ const dir = mkdtempSync(join(tmpdir(), "hf-marked-"));
+ try {
+ writeFileSync(join(dir, "index.html"), "<html></html>");
+ writeFileSync(join(dir, "meta.json"), "{}");
+ openInDesktop(dir, { ...LIVE, open: () => true });
+ expect(existsSync(join(dir, "hyperframes.json"))).toBe(false);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
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, app: "HyperFrames Canary" });
diff --git a/packages/cli/src/utils/desktopApp.ts b/packages/cli/src/utils/desktopApp.ts
index 75d7d49eba..36753756b3 100644
--- a/packages/cli/src/utils/desktopApp.ts
+++ b/packages/cli/src/utils/desktopApp.ts
@@ -1,8 +1,10 @@
import { spawn, spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
import { homedir } from "node:os";
import { basename, isAbsolute, join, relative, win32 } from "node:path";
+import { isHyperframesProject } from "@hyperframes/core";
import { addCatchUpNote, markSeen, readSeen } from "./appHistory.js";
+import { createProjectConfig } from "./projectConfig.js";
import { writeRecord } from "./projectRecords.js";
// The HyperFrames desktop app (not "Studio"): `open -b` on macOS, its executable elsewhere; released, then Canary.
@@ -32,6 +34,8 @@ export interface AgentSession {
}
export const AGENT_HANDOFF_FILE = join(".hyperframes", "agent-handoff.json");
+/** The Studio page's telemetry `tab_id`, left for the app to report its first open and export against. */
+const DESKTOP_CTA_RECORD = "desktop-cta.json";
// ponytail: Claude Code, then Codex, then Grok; an agent started inside another's shell carries both, unsorted.
export function agentSession(env: NodeJS.ProcessEnv = process.env): AgentSession | null {
@@ -131,6 +135,17 @@ function leaveHandoff(dir: string, session: AgentSession | null): AgentSession |
return session;
}
+function markBareIndexAsProject(dir: string): void {
+ try {
+ if (existsSync(join(dir, "index.html")) && !isHyperframesProject(readdirSync(dir)))
+ createProjectConfig(dir);
+ } catch (error) {
+ console.warn(
+ `◇ Couldn't add hyperframes.json to ${dir}, so the app may not open it: ${error}`,
+ );
+ }
+}
+
// 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(
@@ -142,8 +157,10 @@ export function openInDesktop(
launch = launchApp,
installed = () => desktopInstalled({ platform }),
env = process.env,
+ cta,
...where
}: AppLookup & {
+ cta?: string;
ready?: boolean;
open?: (bundleId: string, dir: string) => boolean;
launch?: (executable: string, dir: string) => boolean;
@@ -157,12 +174,16 @@ export function openInDesktop(
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)),
- });
+ const opened = (canary: boolean): DesktopOpenResult => {
+ if (cta) writeRecord(dir, DESKTOP_CTA_RECORD, JSON.stringify({ cta, at: Date.now() }));
+ return {
+ opened: true,
+ app: canary ? "HyperFrames Canary" : "the HyperFrames desktop app",
+ handedOver: leaveHandoff(dir, agentSession(env)),
+ };
+ };
if (!ready) return notOpened("handoff-unavailable");
+ markBareIndexAsProject(dir);
if (platform === "darwin") {
const bundleId = DESKTOP_BUNDLE_IDS.find((id) => open(id, dir));
if (!bundleId) return notOpened(installed() ? "open-failed" : "not-installed");
diff --git a/packages/studio/src/components/DesktopGuideCard.tsx b/packages/studio/src/components/DesktopGuideCard.tsx
new file mode 100644
index 0000000000..cc5c76dfde
--- /dev/null
+++ b/packages/studio/src/components/DesktopGuideCard.tsx
@@ -0,0 +1,292 @@
+import { ArrowSquareOut, Check, Copy } from "@phosphor-icons/react";
+import { useEffect, useState, type ReactNode } from "react";
+import { copyTextToClipboard } from "../utils/clipboard";
+import { FrameyGlyph, type FrameyMood } from "./FrameyGlyph";
+import { Button, cn } from "./ui";
+
+// The desktop-app guide card under OpenInDesktopButton: Framey and three steps (download, install, open), all drawn
+// from one `Progress`.
+
+export type DesktopRoute = {
+ handoff: boolean;
+ downloadUrl: string | null;
+ context: { os: string; app_installed: boolean; download_available: boolean };
+};
+
+/** The OS for the download, and what "this …" calls the machine. */
+const platformName = (os: string): string =>
+ os === "darwin" ? "Mac" : os === "linux" ? "Linux" : "your computer";
+const deviceName = (os: string): string => (os === "darwin" ? "Mac" : "computer");
+
+const NOTE = "mt-0.5 text-step-12 text-text-2 text-pretty";
+
+/** Re-keys on `value`, so text that changes settles in rather than snapping. */
+export function Swap({ value, children }: { value: string; children: ReactNode }) {
+ return (
+ <span key={value} className="hf-guide-swap inline-block">
+ {children}
+ </span>
+ );
+}
+
+type StepState = "todo" | "now" | "done" | "bad";
+const TODO: StepState = "todo";
+const NOW: StepState = "now";
+const DONE: StepState = "done";
+const BAD: StepState = "bad";
+
+function Step({
+ n,
+ state,
+ title,
+ children,
+}: {
+ n: number;
+ state: StepState;
+ title: string;
+ children: ReactNode;
+}) {
+ return (
+ <li
+ className="grid grid-cols-[22px_minmax(0,1fr)] gap-2.5 border-border py-2 not-first:border-t"
+ data-step={n}
+ data-state={state}
+ >
+ <span
+ className={cn(
+ "grid size-[22px] place-items-center rounded-full text-step-11 font-bold tabular-nums",
+ state === "now" && "bg-accent text-on-accent shadow-[0_0_0_3px_var(--color-on)]",
+ state === "done" && "bg-on text-accent-ink",
+ state === "bad" && "bg-danger/15 text-danger-ink",
+ state === "todo" && "bg-hover text-text-2",
+ )}
+ >
+ {state === "done" ? <Check size={12} weight="bold" className="hf-guide-tick" /> : n}
+ </span>
+ <div className="min-w-0">
+ <b
+ title={title}
+ className={cn(
+ "block truncate text-step-13 font-semibold",
+ state === "todo" ? "text-text-muted" : "text-text-0",
+ )}
+ >
+ {title}
+ </b>
+ {children}
+ </div>
+ </li>
+ );
+}
+
+function Spinner() {
+ return (
+ <span
+ aria-hidden="true"
+ className="size-3 shrink-0 animate-spin rounded-full border-2 border-on-hover border-t-accent motion-reduce:animate-none"
+ />
+ );
+}
+
+/** The project folder, with a copy control that confirms for a moment. */
+function FolderPath({ dir }: { dir: string }) {
+ const [copied, setCopied] = useState(false);
+ useEffect(() => {
+ if (!copied) return;
+ const timer = setTimeout(() => setCopied(false), 1500);
+ return () => clearTimeout(timer);
+ }, [copied]);
+ return (
+ <div className="mt-1.5 flex min-w-0 items-center gap-1.5">
+ <span
+ title={dir}
+ data-testid="desktop-guide-folder"
+ className="min-w-0 flex-1 truncate rounded-md border border-border bg-bg-0 px-2 py-1.5 font-mono text-step-11 text-text-0"
+ >
+ {dir}
+ </span>
+ <Button
+ variant="secondary"
+ aria-label={copied ? "Copied" : "Copy folder path"}
+ className="w-ctl px-0"
+ onClick={() => void copyTextToClipboard(dir).then((ok) => ok && setCopied(true))}
+ >
+ {copied ? <Check size={14} className="hf-guide-tick" /> : <Copy size={14} />}
+ </Button>
+ </div>
+ );
+}
+
+/** Where the person is: what the button says, how Framey looks, and each step's state all derive from this. */
+export type Progress = {
+ route: DesktopRoute;
+ opening: boolean;
+ failed: boolean;
+ downloaded: boolean;
+ slow: boolean;
+ /** The app turned up on this page (not already there): Framey hops once. */
+ arrived: boolean;
+};
+
+const isInstalled = (p: Progress) => p.route.context.app_installed;
+export const isWaiting = (p: Progress) => p.downloaded && !isInstalled(p);
+
+export function moodOf(p: Progress): FrameyMood {
+ if (p.opening) return "opening";
+ if (p.failed) return "error";
+ if (isWaiting(p)) return "thinking";
+ return p.arrived ? "found" : "idle";
+}
+
+export function labelOf(p: Progress): string {
+ if (p.opening) return "Opening in the app…";
+ if (p.failed) return "Couldn't open";
+ if (p.route.handoff) return "Open in desktop app";
+ return isWaiting(p) ? "Finish installing" : "Install the desktop app";
+}
+
+function subtitleOf(p: Progress): string {
+ if (p.failed) return "Almost there: the last step needs another try.";
+ if (!isInstalled(p))
+ return "Watch it, click a frame, tell Framey what to change. Three steps, about two minutes.";
+ return p.route.handoff
+ ? "Everything is ready. One press and you're in."
+ : "Almost there: one last step.";
+}
+
+type CardProps = {
+ progress: Progress;
+ projectDir: string | null;
+ onDownload: () => void;
+ onOpen: () => void;
+};
+
+function DownloadStep({ progress, onDownload }: CardProps) {
+ const { context, downloadUrl } = progress.route;
+ const where = platformName(context.os);
+ const installed = isInstalled(progress);
+ if (!progress.downloaded && !installed)
+ return (
+ <Step n={1} state={NOW} title={`Download HyperFrames for ${where}`}>
+ <p className={NOTE}>Free. Opens hyperframes.dev in a new tab.</p>
+ <Button
+ variant="primary"
+ className="mt-2"
+ icon={<ArrowSquareOut size={14} />}
+ onClick={onDownload}
+ >
+ Download for {where}
+ </Button>
+ </Step>
+ );
+ return (
+ <Step n={1} state={DONE} title={`Download HyperFrames for ${where}`}>
+ <p className={NOTE}>
+ {installed ? `Already on this ${deviceName(context.os)}.` : "Started in your browser."}
+ {!installed && downloadUrl && (
+ <button
+ type="button"
+ className="ml-1.5 cursor-pointer font-medium text-accent-ink hover:underline"
+ onClick={onDownload}
+ >
+ Download again
+ </button>
+ )}
+ </p>
+ </Step>
+ );
+}
+
+function InstallStep({ progress }: CardProps) {
+ const { os } = progress.route.context;
+ if (isInstalled(progress))
+ return (
+ <Step n={2} state={DONE} title="Install it">
+ <p className={NOTE}>
+ <Swap value="found">Found HyperFrames on this {deviceName(os)}.</Swap>
+ </p>
+ </Step>
+ );
+ return (
+ <Step n={2} state={progress.downloaded ? NOW : TODO} title="Install it">
+ <p className={NOTE}>
+ {os === "darwin"
+ ? "Open the download and drag HyperFrames into Applications."
+ : "Open the download to install HyperFrames."}
+ </p>
+ {progress.downloaded && (
+ <p className="mt-1.5 flex items-center gap-2 text-step-12 text-text-2" role="status">
+ <Spinner />
+ <Swap value={String(progress.slow)}>
+ {progress.slow ? "Still looking. Did the download finish?" : "Looking for the app…"}
+ </Swap>
+ </p>
+ )}
+ </Step>
+ );
+}
+
+function OpenStep({ progress, projectDir, onOpen }: CardProps) {
+ const title = `Open ${projectDir?.split(/[\\/]/).filter(Boolean).pop() ?? "this project"}`;
+ const folder = projectDir && <FolderPath dir={projectDir} />;
+ if (progress.failed)
+ return (
+ <Step n={3} state={BAD} title={title}>
+ <p className={NOTE}>
+ The app didn't start. Try again, or open HyperFrames and drop this folder in:
+ </p>
+ {folder}
+ <Button variant="primary" className="mt-2" loading={progress.opening} onClick={onOpen}>
+ Try again
+ </Button>
+ </Step>
+ );
+ const installed = isInstalled(progress);
+ // Installed, but this platform's app cannot take a handed-over project yet: the folder is the way in.
+ if (installed && !progress.route.handoff)
+ return (
+ <Step n={3} state={NOW} title={title}>
+ <p className={NOTE}>Open HyperFrames and drop this folder in:</p>
+ {folder}
+ </Step>
+ );
+ return (
+ <Step n={3} state={installed ? NOW : TODO} title={title}>
+ <p className={NOTE}>Same project, same files, in the desktop app.</p>
+ <Button
+ variant="primary"
+ className="mt-2"
+ disabled={!progress.route.handoff}
+ loading={progress.opening}
+ onClick={onOpen}
+ >
+ Open in desktop app
+ </Button>
+ </Step>
+ );
+}
+
+export function GuideCard(props: CardProps) {
+ const { progress } = props;
+ const subtitle = subtitleOf(progress);
+ return (
+ <div data-testid="desktop-guide">
+ <div className="grid grid-cols-[auto_minmax(0,1fr)] items-center gap-3 bg-linear-to-b from-accent/8 to-transparent px-4 pt-4 pb-3">
+ <FrameyGlyph size={46} mood={moodOf(progress)} />
+ <div className="min-w-0">
+ <p className="text-step-14 font-semibold text-balance text-text-0">
+ Edit this video in the desktop app
+ </p>
+ <p className={NOTE}>
+ <Swap value={subtitle}>{subtitle}</Swap>
+ </p>
+ </div>
+ </div>
+ <ol className="m-0 grid list-none px-4 pt-1 pb-4">
+ <DownloadStep {...props} />
+ <InstallStep {...props} />
+ <OpenStep {...props} />
+ </ol>
+ </div>
+ );
+}
diff --git a/packages/studio/src/components/FrameyGlyph.tsx b/packages/studio/src/components/FrameyGlyph.tsx
index abcde5f219..f11cad15e6 100644
--- a/packages/studio/src/components/FrameyGlyph.tsx
+++ b/packages/studio/src/components/FrameyGlyph.tsx
@@ -1,51 +1,101 @@
import type { Ref } from "react";
+import { cn } from "./ui";
-// Framey, the desktop app's cursor mascot, as hyperframes-internal packages/nib draws it: a rounded triangle with a
-// white rim and one eye. The viewBox frames the body with its rim; the tip points up and left like a cursor.
+// Framey, the desktop app's cursor mascot, as the app draws it: a rounded triangle with a white rim and one eye,
+// framed square around the body and rim.
const BODY = "M77.55 48.44 L122.77 65.85 L99.3 89.41 Z";
const EYE = { cx: 111.6, cy: 68.2, r: 11.5 };
+const RIM = 24;
+const VIEW_BOX = "65.55 34.315 69.22 69.22";
-/** `eyeRef` moves the pupils (a translate of a few px) without re-rendering. */
+/** The app's moods: what Framey's eye and body do (styles in components.css, `.hf-framey-mood`). */
+export type FrameyMood = "idle" | "thinking" | "found" | "opening" | "error";
+
+const INK = "var(--color-framey-ink)";
+
+function Pupils({ mood }: { mood?: FrameyMood }) {
+ const { cx, cy } = EYE;
+ if (mood === "found")
+ return (
+ <g transform={`translate(${cx + 1.7} ${cy - 2.3})`}>
+ <circle r={4.6} fill={INK} />
+ <circle cx={1.4} cy={-1.6} r={1.3} fill="var(--color-white)" />
+ </g>
+ );
+ if (mood === "thinking")
+ return (
+ <g transform={`translate(${cx} ${cy})`}>
+ <g className="hf-framey-orbit">
+ <circle cx={-2.8} r={1.9} fill={INK} />
+ <circle cx={2.8} r={1.9} fill={INK} />
+ </g>
+ </g>
+ );
+ if (mood === "error")
+ return (
+ <path
+ transform={`translate(${cx} ${cy})`}
+ d="M-5 -2 L-1.4 1.6 M-1.4 -2 L-5 1.6 M1.4 -2 L5 1.6 M5 -2 L1.4 1.6"
+ stroke={INK}
+ strokeWidth={1.7}
+ strokeLinecap="round"
+ />
+ );
+ return (
+ <path
+ d={`M${cx - 2.6} ${cy - 2.4} V${cy + 2.4} M${cx + 2.6} ${cy - 2.4} V${cy + 2.4}`}
+ stroke={INK}
+ strokeWidth={2.4}
+ strokeLinecap="round"
+ />
+ );
+}
+
+/** `eyeRef` moves the pupils (a translate of a few px) without re-rendering. Without `mood` Framey holds still. */
export function FrameyGlyph({
size,
className,
eyeRef,
+ mood,
}: {
size: number;
className?: string;
eyeRef?: Ref<SVGGElement>;
+ mood?: FrameyMood;
}) {
return (
<svg
width={size}
height={size}
- viewBox="58 30 82 76"
+ viewBox={VIEW_BOX}
aria-hidden="true"
- className={className}
overflow="visible"
+ className={cn(mood && "hf-framey-mood", className)}
+ data-mood={mood}
>
- <path
- d={BODY}
- fill="var(--color-white)"
- stroke="var(--color-white)"
- strokeWidth={24}
- strokeLinejoin="round"
- />
- <path
- d={BODY}
- fill="var(--color-framey)"
- stroke="var(--color-framey)"
- strokeWidth={19}
- strokeLinejoin="round"
- />
- <circle cx={EYE.cx} cy={EYE.cy} r={EYE.r} fill="var(--color-white)" />
- <g ref={eyeRef} className="hf-framey-eye">
- <path
- d={`M${EYE.cx - 2.6} ${EYE.cy - 2} V${EYE.cy + 2} M${EYE.cx + 2.6} ${EYE.cy - 2} V${EYE.cy + 2}`}
- stroke="var(--color-framey-ink)"
- strokeWidth={2.4}
- strokeLinecap="round"
- />
+ <g className="hf-framey-whole">
+ <g className="hf-framey-body">
+ <path
+ d={BODY}
+ fill="var(--color-white)"
+ stroke="var(--color-white)"
+ strokeWidth={RIM}
+ strokeLinejoin="round"
+ />
+ <path
+ d={BODY}
+ fill="var(--color-framey)"
+ stroke="var(--color-framey)"
+ strokeWidth={19}
+ strokeLinejoin="round"
+ />
+ <g className="hf-framey-lid">
+ <circle cx={EYE.cx} cy={EYE.cy} r={EYE.r} fill="var(--color-white)" />
+ <g ref={eyeRef} className="hf-framey-eye">
+ <Pupils mood={mood} />
+ </g>
+ </g>
+ </g>
</g>
</svg>
);
diff --git a/packages/studio/src/components/OpenInDesktopButton.dom.test.tsx b/packages/studio/src/components/OpenInDesktopButton.dom.test.tsx
index 9dc4fae2f3..7dfc264655 100644
--- a/packages/studio/src/components/OpenInDesktopButton.dom.test.tsx
+++ b/packages/studio/src/components/OpenInDesktopButton.dom.test.tsx
@@ -1,8 +1,8 @@
// @vitest-environment happy-dom
/**
- * "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.
+ * "Install the desktop app": shown where the preview server has the app or its download to offer. With the app ready a
+ * press opens the project in it; otherwise it opens the guide card (download, install, open).
*/
import React, { act } from "react";
import { createRoot, type Root } from "react-dom/client";
@@ -12,21 +12,39 @@ import { afterEach, beforeEach, expect, it, vi } from "vitest";
const showToast = vi.fn();
vi.mock("../contexts/StudioContext", () => ({ useStudioShellContext: () => ({ showToast }) }));
-vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+const track = vi.fn();
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: track }));
+const FOLDER = "/work/launch-teaser";
+vi.mock("../contexts/FileManagerContext", () => ({
+ useFileManagerContextOptional: () => ({ projectDir: FOLDER }),
+}));
+const copied: string[] = [];
+vi.mock("../utils/clipboard", () => ({
+ copyTextToClipboard: async (text: string) => (copied.push(text), true),
+}));
const { OpenInDesktopButton } = await import("./OpenInDesktopButton");
+const { resolveTabId } = await import("../telemetry/tabId");
+const tagged = (url: string) => {
+ const withId = new URL(url);
+ withId.searchParams.set("hf_cta", resolveTabId());
+ return withId.toString();
+};
const DOWNLOAD = "https://hyperframes.dev/studio/download";
let mounted: { root: Root; host: HTMLElement } | null = null;
let posts: number;
+let postBodies: unknown[];
function serve(get: Response | null, post?: unknown) {
posts = 0;
+ postBodies = [];
vi.stubGlobal(
"fetch",
vi.fn(async (_url: string, init?: RequestInit) => {
if (init?.method === "POST") {
posts += 1;
+ postBodies.push(JSON.parse(String(init.body ?? "null")));
return Response.json(post);
}
return get ?? new Response("Not found", { status: 404 });
@@ -43,15 +61,32 @@ async function mount(): Promise<HTMLElement> {
return host;
}
-const downloadHref = () =>
- [...document.querySelectorAll("a")]
- .find((a) => a.textContent?.includes("Get the desktop app"))
- ?.getAttribute("href");
-
const button = () =>
document.querySelector<HTMLButtonElement>('[data-testid="header-open-in-desktop"]');
-beforeEach(() => showToast.mockReset());
+let reveal: (() => void) | null = null;
+
+beforeEach(() => {
+ showToast.mockReset();
+ track.mockReset();
+ reveal = null;
+ vi.stubGlobal(
+ "IntersectionObserver",
+ class {
+ constructor(private readonly onChange: (entries: { isIntersecting: boolean }[]) => void) {}
+ observe() {
+ reveal = () => this.onChange([{ isIntersecting: true }]);
+ }
+ disconnect() {
+ reveal = null;
+ }
+ },
+ );
+});
+
+const events = (name: string) =>
+ track.mock.calls.filter(([event]) => event === name).map(([, props]) => props);
+const MAC = { os: "darwin", app_installed: true, download_available: true };
afterEach(() => {
vi.unstubAllGlobals();
@@ -90,16 +125,186 @@ it("opens the project in an installed app that has no download (Windows)", async
expect(posts).toBe(1);
});
-it("while the app cannot take a project yet, introduces Framey with the download and opens nothing", async () => {
- const linux = `${DOWNLOAD}?os=linux`;
- serve(Response.json({ available: true, handoff: false, downloadUrl: linux }), { opened: true });
+/** Runs `body` with the poll and slow-download timers under test control. */
+async function withFakeTimers(body: () => Promise<void>) {
+ vi.useFakeTimers({ toFake: ["setInterval", "clearInterval", "setTimeout", "clearTimeout"] });
+ try {
+ await body();
+ } finally {
+ vi.useRealTimers();
+ }
+}
+
+const guide = () => document.querySelector<HTMLElement>('[data-testid="desktop-guide"]');
+const stepState = (n: number) =>
+ guide()?.querySelector<HTMLElement>(`[data-step="${n}"]`)?.dataset.state ?? null;
+const cardButton = (text: string) =>
+ [...(guide()?.querySelectorAll("button") ?? [])].find((b) => b.textContent === text) ?? null;
+const noApp = { os: "darwin", app_installed: false, download_available: true };
+const routeBody = (over: Record<string, unknown> = {}) => ({
+ ...noApp,
+ available: true,
+ handoff: false,
+ downloadUrl: DOWNLOAD,
+ installed: false,
+ ...over,
+});
+
+it("reads 'Install the desktop app' beside Framey, and 'Open in desktop app' once the app takes projects", async () => {
+ serve(Response.json(routeBody()));
+ await mount();
+ expect(button()!.textContent).toBe("Install the desktop app");
+ expect(button()!.querySelector("svg .hf-framey-eye")).not.toBeNull();
+ act(() => mounted!.root.unmount());
+ mounted = null;
+
+ serve(Response.json(routeBody({ handoff: true, installed: true, app_installed: true })));
+ await mount();
+ expect(button()!.textContent).toBe("Open in desktop app");
+});
+
+it("without the app, a press opens the guide at step 1 and hands nothing over", async () => {
+ serve(Response.json(routeBody()), { opened: true });
await mount();
await act(async () => button()!.click());
+ expect(guide()).not.toBeNull();
+ expect([stepState(1), stepState(2), stepState(3)]).toEqual(["now", "todo", "todo"]);
+ expect(cardButton("Open in desktop app")!.disabled).toBe(true);
expect(posts).toBe(0);
- expect(document.body.textContent).toContain("Meet Framey");
- expect(downloadHref()).toBe(linux);
+ expect(events("desktop_cta_guide")).toEqual([{ step: "opened", ...noApp }]);
+});
+
+it("step 1 opens the tagged download in a new tab, then the button says what is left", async () => {
+ const opened: string[] = [];
+ const tab = { opener: {} as unknown };
+ vi.stubGlobal("open", (url: string) => (opened.push(url), tab));
+ serve(Response.json(routeBody()));
+ await mount();
+ await act(async () => button()!.click());
+ await act(async () => cardButton("Download for Mac")!.click());
+ expect(opened).toEqual([tagged(DOWNLOAD)]);
+ expect(tab.opener).toBeNull();
+ expect([stepState(1), stepState(2)]).toEqual(["done", "now"]);
+ expect(guide()!.textContent).toContain("Looking for the app…");
+ expect(button()!.textContent).toBe("Finish installing2 of 3");
+ expect(events("desktop_cta_outcome")).toEqual([{ outcome: "sent_to_download", ...noApp }]);
+ expect(events("desktop_cta_guide").map((e) => (e as { step: string }).step)).toEqual([
+ "opened",
+ "download_opened",
+ ]);
+});
+
+it("names the download when the browser blocks the new tab, and leaves step 1 to do", async () => {
+ vi.stubGlobal("open", () => null);
+ serve(Response.json(routeBody()));
+ await mount();
+ await act(async () => button()!.click());
+ await act(async () => cardButton("Download for Mac")!.click());
+ expect(showToast).toHaveBeenCalledWith(`Get the HyperFrames desktop app at ${DOWNLOAD}`, "info");
+ expect(stepState(1)).toBe("now");
+ expect(events("desktop_cta_outcome")).toEqual([
+ { outcome: "failed", reason: "download_tab_blocked", ...noApp },
+ ]);
});
+it("finds the install only from the preview server, asking only while the card is open", () =>
+ withFakeTimers(async () => {
+ let answer = routeBody();
+ let gets = 0;
+ vi.stubGlobal(
+ "fetch",
+ vi.fn(async (_url: string, init?: RequestInit) => {
+ if (init?.method === "POST") return Response.json({ opened: true });
+ gets += 1;
+ return Response.json(answer);
+ }),
+ );
+ vi.stubGlobal("open", () => ({ opener: null }));
+ await mount();
+ expect(gets).toBe(1);
+ await act(async () => vi.advanceTimersByTime(10_000));
+ expect(gets).toBe(1);
+
+ await act(async () => button()!.click());
+ await act(async () => cardButton("Download for Mac")!.click());
+ await act(async () => vi.advanceTimersByTime(2000));
+ const asked = gets;
+ expect(asked).toBeGreaterThan(1);
+ expect(events("desktop_cta_guide").map((e) => (e as { step: string }).step)).not.toContain(
+ "install_detected",
+ );
+
+ answer = routeBody({ handoff: true, installed: true });
+ await act(async () => vi.advanceTimersByTime(2000));
+ expect([stepState(2), stepState(3)]).toEqual(["done", "now"]);
+ expect(cardButton("Open in desktop app")!.disabled).toBe(false);
+ expect(button()!.textContent).toBe("Open in desktop app");
+ expect(guide()!.querySelector('svg[data-mood="found"]')).not.toBeNull();
+ const detected = events("desktop_cta_guide").filter(
+ (e) => (e as { step: string }).step === "install_detected",
+ );
+ expect(detected).toEqual([
+ { step: "install_detected", os: "darwin", app_installed: true, download_available: true },
+ ]);
+ const settled = gets;
+ await act(async () => vi.advanceTimersByTime(10_000));
+ expect(gets).toBe(settled);
+ }));
+
+it("records the install once per page, even when the app goes and comes back", () =>
+ withFakeTimers(async () => {
+ let answer = routeBody();
+ vi.stubGlobal(
+ "fetch",
+ vi.fn(async (_url: string, init?: RequestInit) => {
+ if (init?.method === "POST")
+ return Response.json({ opened: false, reason: "not-installed", downloadUrl: DOWNLOAD });
+ return Response.json(answer);
+ }),
+ );
+ await mount();
+ await act(async () => button()!.click());
+ answer = routeBody({ handoff: true, installed: true });
+ await act(async () => vi.advanceTimersByTime(2000));
+ expect(stepState(2)).toBe("done");
+
+ // The app is removed: the hand-off finds it gone, and the server stops reporting it.
+ answer = routeBody();
+ await act(async () => cardButton("Open in desktop app")!.click());
+ expect(stepState(2)).toBe("todo");
+ // Installed again: the card finds it a second time.
+ answer = routeBody({ handoff: true, installed: true });
+ await act(async () => vi.advanceTimersByTime(2000));
+ expect(stepState(2)).toBe("done");
+
+ const detected = events("desktop_cta_guide").filter(
+ (e) => (e as { step: string }).step === "install_detected",
+ );
+ expect(detected).toHaveLength(1);
+ }));
+
+it("stops asking the preview server when the card closes", () =>
+ withFakeTimers(async () => {
+ let gets = 0;
+ vi.stubGlobal(
+ "fetch",
+ vi.fn(async () => ((gets += 1), Response.json(routeBody()))),
+ );
+ await mount();
+ await act(async () => button()!.click());
+ await act(async () => vi.advanceTimersByTime(4000));
+ expect(gets).toBeGreaterThan(2);
+ await act(async () => button()!.click());
+ expect(guide()).toBeNull();
+ const closedAt = gets;
+ await act(async () => vi.advanceTimersByTime(10_000));
+ expect(gets).toBe(closedAt);
+ expect(events("desktop_cta_guide").map((e) => (e as { step: string }).step)).toEqual([
+ "opened",
+ "closed",
+ ]);
+ }));
+
it("opens the project in the app and says so", async () => {
serve(Response.json({ available: true, handoff: true, downloadUrl: DOWNLOAD }), {
opened: true,
@@ -108,23 +313,200 @@ it("opens the project in the app and says so", async () => {
await mount();
await act(async () => button()!.click());
expect(posts).toBe(1);
+ expect(postBodies).toEqual([{ cta: resolveTabId() }]);
+ expect(guide()).toBeNull();
expect(showToast).toHaveBeenCalledWith(
- "Framey is opening this project in the HyperFrames desktop app",
+ "Opening this project in the HyperFrames desktop app",
"info",
);
expect(button()!.dataset.opening).toBe("true");
- expect(document.body.textContent).not.toContain("Meet Framey");
});
-it("introduces Framey and offers the download when the app is missing", async () => {
- serve(Response.json({ available: true, handoff: true, downloadUrl: DOWNLOAD }), {
+it("a failed hand-off opens the card at step 3 with the folder to copy and Try again", async () => {
+ const opened: string[] = [];
+ vi.stubGlobal("open", (url: string) => (opened.push(url), {}));
+ copied.length = 0;
+ serve(Response.json(routeBody({ handoff: true, installed: true })), {
+ opened: false,
+ reason: "open-failed",
+ downloadUrl: DOWNLOAD,
+ });
+ await mount();
+ await act(async () => button()!.click());
+ expect(opened).toEqual([]);
+ expect(button()!.textContent).toBe("Couldn't open");
+ expect(stepState(3)).toBe("bad");
+ expect(guide()!.textContent).toContain("Almost there: the last step needs another try.");
+ expect(guide()!.textContent).not.toContain("Everything is ready");
+ expect(guide()!.querySelector('[data-testid="desktop-guide-folder"]')!.textContent).toBe(FOLDER);
+ await act(async () =>
+ guide()!.querySelector<HTMLButtonElement>('[aria-label="Copy folder path"]')!.click(),
+ );
+ expect(copied).toEqual([FOLDER]);
+ await act(async () => cardButton("Try again")!.click());
+ expect(posts).toBe(2);
+});
+
+it("a hand-off that finds the app gone goes back to the download step", async () => {
+ serve(Response.json(routeBody({ handoff: true, installed: true })), {
opened: false,
reason: "not-installed",
downloadUrl: DOWNLOAD,
});
await mount();
await act(async () => button()!.click());
- expect(showToast).not.toHaveBeenCalled();
- expect(document.body.textContent).toContain("Meet Framey");
- expect(downloadHref()).toBe(DOWNLOAD);
+ expect([stepState(1), stepState(3)]).toEqual(["now", "todo"]);
+ expect(button()!.textContent).toBe("Install the desktop app");
+});
+
+it("where the app is installed but cannot take a project (Linux), step 3 shows the folder to drop in", async () => {
+ const linux = { os: "linux", app_installed: true, download_available: true };
+ serve(
+ Response.json({
+ ...linux,
+ available: true,
+ handoff: false,
+ downloadUrl: `${DOWNLOAD}?os=linux`,
+ installed: true,
+ }),
+ { opened: true },
+ );
+ await mount();
+ await act(async () => button()!.click());
+ expect([stepState(1), stepState(2), stepState(3)]).toEqual(["done", "done", "now"]);
+ expect(guide()!.textContent).toContain("Found HyperFrames on this computer.");
+ expect(guide()!.textContent).toContain("Open HyperFrames and drop this folder in:");
+ expect(guide()!.querySelector('[data-testid="desktop-guide-folder"]')!.textContent).toBe(FOLDER);
+ expect(cardButton("Open in desktop app")).toBeNull();
+ expect(posts).toBe(0);
+});
+
+it("counts where the button can show, the app here, and platforms with no app", async () => {
+ serve(
+ Response.json({
+ ...MAC,
+ available: true,
+ handoff: true,
+ downloadUrl: DOWNLOAD,
+ installed: true,
+ }),
+ );
+ await mount();
+ expect(events("desktop_cta_eligibility")).toEqual([{ eligibility: "open_in_app", ...MAC }]);
+ act(() => mounted!.root.unmount());
+ mounted = null;
+
+ track.mockReset();
+ serve(
+ Response.json({
+ available: false,
+ handoff: false,
+ downloadUrl: null,
+ os: "win32",
+ installed: false,
+ }),
+ );
+ await mount();
+ expect(button()).toBeNull();
+ expect(events("desktop_cta_eligibility")).toEqual([
+ {
+ eligibility: "no_app_for_platform",
+ os: "win32",
+ app_installed: false,
+ download_available: false,
+ },
+ ]);
+ expect(events("desktop_cta_impression")).toEqual([]);
+});
+
+it("records one impression, only once the button is on screen", async () => {
+ serve(
+ Response.json({
+ ...MAC,
+ available: true,
+ handoff: true,
+ downloadUrl: DOWNLOAD,
+ installed: true,
+ }),
+ );
+ await mount();
+ expect(events("desktop_cta_impression")).toEqual([]);
+ act(() => reveal!());
+ expect(events("desktop_cta_impression")).toEqual([{ eligibility: "open_in_app", ...MAC }]);
+ expect(reveal).toBeNull();
+});
+
+it("records the click and its outcome for each way a hand-off ends", async () => {
+ const outcomes = async (post: unknown) => {
+ track.mockReset();
+ serve(
+ Response.json({
+ ...MAC,
+ available: true,
+ handoff: true,
+ downloadUrl: DOWNLOAD,
+ installed: true,
+ }),
+ post,
+ );
+ await mount();
+ await act(async () => button()!.click());
+ const result = { clicks: events("toolbar_action"), outcomes: events("desktop_cta_outcome") };
+ act(() => mounted!.root.unmount());
+ mounted = null;
+ return result;
+ };
+ expect(await outcomes({ opened: true })).toEqual({
+ clicks: [{ action: "open_in_desktop", ...MAC }],
+ outcomes: [{ outcome: "opened", ...MAC }],
+ });
+ expect(
+ (await outcomes({ opened: false, reason: "open-failed", downloadUrl: DOWNLOAD })).outcomes,
+ ).toEqual([{ outcome: "failed", reason: "open-failed", ...MAC }]);
+ expect(
+ (await outcomes({ opened: false, reason: "not-installed", downloadUrl: DOWNLOAD })).outcomes,
+ ).toEqual([{ outcome: "failed", reason: "not-installed", ...MAC }]);
+});
+
+it("records a press the preview server never answered as failed", async () => {
+ vi.stubGlobal(
+ "fetch",
+ vi.fn(async (_url: string, init?: RequestInit) => {
+ if (init?.method === "POST") throw new TypeError("network");
+ return Response.json({
+ ...MAC,
+ available: true,
+ handoff: true,
+ downloadUrl: DOWNLOAD,
+ installed: true,
+ });
+ }),
+ );
+ await mount();
+ await act(async () => button()!.click());
+ expect(events("desktop_cta_outcome")).toEqual([
+ { outcome: "failed", reason: "preview_server_unreachable", ...MAC },
+ ]);
+});
+
+it("records the download press as sent to the download, never as an install", async () => {
+ const linux = { os: "linux", app_installed: false, download_available: true };
+ vi.stubGlobal("open", () => ({ opener: null }));
+ serve(
+ Response.json({
+ ...linux,
+ available: true,
+ handoff: false,
+ downloadUrl: `${DOWNLOAD}?os=linux`,
+ installed: false,
+ }),
+ );
+ await mount();
+ await act(async () => button()!.click());
+ await act(async () => cardButton("Download for Linux")!.click());
+ expect(events("toolbar_action")).toEqual([{ action: "get_desktop_app", ...linux }]);
+ expect(events("desktop_cta_outcome")).toEqual([{ outcome: "sent_to_download", ...linux }]);
+ const sent = JSON.stringify(track.mock.calls);
+ expect(sent).not.toMatch(/"(outcome|step)":"[a-z_]*install/);
+ expect(sent).not.toContain("/");
});
diff --git a/packages/studio/src/components/OpenInDesktopButton.tsx b/packages/studio/src/components/OpenInDesktopButton.tsx
index 22d2f32411..37a4aa874e 100644
--- a/packages/studio/src/components/OpenInDesktopButton.tsx
+++ b/packages/studio/src/components/OpenInDesktopButton.tsx
@@ -1,41 +1,121 @@
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
import { useStudioShellContext } from "../contexts/StudioContext";
+import { useFileManagerContextOptional } from "../contexts/FileManagerContext";
+import { resolveTabId } from "../telemetry/tabId";
import { studioApiFetch } from "../utils/studioApiFetch";
import { trackStudioEvent } from "../utils/studioTelemetry";
+import {
+ GuideCard,
+ Swap,
+ isWaiting,
+ labelOf,
+ moodOf,
+ type DesktopRoute,
+ type Progress,
+} from "./DesktopGuideCard";
import { FrameyGlyph } from "./FrameyGlyph";
-import { Button, buttonBase, buttonSizes, buttonVariants, cn, Popover } from "./ui";
+import { Button, Popover, cn } from "./ui";
-// "Edit with Framey": the preview server (`/api/open-in-desktop`) says whether to show it and whether the app can
-// take the project yet (its gate is the CLI's HANDOFF_READY); until then a press introduces Framey with the download.
+// "Install the desktop app": the preview server (`/api/open-in-desktop`) says whether to show it, whether the app is
+// here and whether it takes the project. With the app ready a press opens the project in it; otherwise the press
+// opens a card where Framey walks through download, install and open.
const ROUTE = "/api/open-in-desktop";
/** How far the pupils travel towards the pointer, in the glyph's own units. */
const GAZE = 2.2;
/** Long enough for the flight to finish before the label comes back. */
const OPENING_MS = 1600;
+/** While the card is open and the app is not here yet, how often to ask the preview server again. */
+const POLL_MS = 2000;
+/** After this long without the app turning up, the card asks whether the download finished. */
+const SLOW_MS = 60_000;
type OpenResult = { opened: true } | { opened: false; reason: string; downloadUrl: string };
-type DesktopRoute = { handoff: boolean; downloadUrl: string | null };
+type Eligibility = "open_in_app" | "download" | "no_app_for_platform";
-/** Null hides the button: no route (the app's own Studio), or nothing here to open or download. */
-function useDesktopRoute(): DesktopRoute | null {
+/** Every Guide step change, for the funnel: never a download counted as an install. */
+type GuideStep = "opened" | "closed" | "download_opened" | "install_detected";
+
+/** The download, tagged with this page's telemetry `tab_id` so a later install can be matched to the press. */
+const withCta = (url: string): string => {
+ const tagged = new URL(url);
+ tagged.searchParams.set("hf_cta", resolveTabId());
+ return tagged.toString();
+};
+
+const eligibilityOf = (route: DesktopRoute): Eligibility =>
+ route.handoff ? "open_in_app" : route.downloadUrl ? "download" : "no_app_for_platform";
+
+/** The preview server's answer, or null when there is none (the desktop's own Studio, or no server). */
+async function readRoute(): Promise<DesktopRoute | null> {
+ const res = await studioApiFetch(ROUTE);
+ if (!res.ok) return null;
+ const body = (await res.json()) as {
+ available?: unknown;
+ handoff?: unknown;
+ downloadUrl?: unknown;
+ os?: unknown;
+ installed?: unknown;
+ } | null;
+ if (!body) return null;
+ const downloadUrl = typeof body.downloadUrl === "string" ? body.downloadUrl : null;
+ return {
+ handoff: body.available === true && body.handoff === true,
+ downloadUrl: body.available === true ? downloadUrl : null,
+ context: {
+ os: typeof body.os === "string" ? body.os : "unknown",
+ app_installed: body.installed === true,
+ download_available: downloadUrl !== null,
+ },
+ };
+}
+
+/** Null hides the button: no route, or nothing here to open or download. `setRoute` takes a fresher answer. */
+function useDesktopRoute() {
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; 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 });
+ readRoute()
+ .then((answered) => {
+ if (!live || !answered) return;
+ trackStudioEvent("desktop_cta_eligibility", {
+ eligibility: eligibilityOf(answered),
+ ...answered.context,
+ });
+ if (answered.handoff || answered.downloadUrl) setRoute(answered);
})
.catch(() => {});
return () => {
live = false;
};
}, []);
- return route;
+ return [route, setRoute] as const;
+}
+
+/** One impression per page, once the button is on screen. */
+function useImpression(anchor: React.RefObject<HTMLElement | null>, route: DesktopRoute | null) {
+ const shown = route !== null;
+ const routeRef = useRef(route);
+ routeRef.current = route;
+ useEffect(() => {
+ const el = anchor.current;
+ if (!shown || !el) return;
+ const record = () => {
+ const now = routeRef.current!;
+ trackStudioEvent("desktop_cta_impression", {
+ eligibility: eligibilityOf(now),
+ ...now.context,
+ });
+ };
+ if (typeof IntersectionObserver === "undefined") return record();
+ const seen = new IntersectionObserver((entries) => {
+ if (!entries.some((entry) => entry.isIntersecting)) return;
+ seen.disconnect();
+ record();
+ });
+ seen.observe(el);
+ return () => seen.disconnect();
+ }, [anchor, shown]);
}
/** Framey looks at the pointer: one listener, one write per frame, no re-render. */
@@ -64,97 +144,190 @@ function useGaze(
}, [anchor, eye]);
}
-export function OpenInDesktopButton() {
+/** While the card is open and the app is not here, ask the preview server again; stops on close or once found. */
+function useInstallWatch(watching: boolean, onAnswer: (route: DesktopRoute) => void): void {
+ useEffect(() => {
+ if (!watching) return;
+ let live = true;
+ const ask = () =>
+ readRoute()
+ .then((answered) => live && answered && onAnswer(answered))
+ .catch(() => {});
+ void ask();
+ const timer = setInterval(ask, POLL_MS);
+ return () => {
+ live = false;
+ clearInterval(timer);
+ };
+ }, [watching, onAnswer]);
+}
+
+const LOOK =
+ "hf-framey-trigger gap-1.5 border border-accent/40 bg-accent/10 pl-1 font-semibold text-text-0 enabled:hover:bg-accent/20 hover:bg-accent/20";
+const LOOK_FAILED = "border-danger/45 bg-danger/8 text-danger-ink enabled:hover:bg-danger/14";
+
+/** The guide's state and the two actions that move it: the download and the hand-off. */
+function useGuide(route: DesktopRoute | null, setRoute: (route: DesktopRoute) => void) {
const { showToast } = useStudioShellContext();
- const route = useDesktopRoute();
+ const [cardOpen, setCardOpen] = useState(false);
const [opening, setOpening] = useState(false);
- // The card under the button, introducing Framey with the app's download.
- const [downloadUrl, setDownloadUrl] = useState<string | null>(null);
- const trigger = useRef<HTMLButtonElement>(null);
- const eye = useRef<SVGGElement>(null);
- useGaze(trigger, eye);
+ const [failed, setFailed] = useState(false);
+ const [downloaded, setDownloaded] = useState(false);
+ const [slow, setSlow] = useState(false);
+ const [arrived, setArrived] = useState(false);
+ const installed = route?.context.app_installed === true;
+ // The funnel counts one install per page, even if the app is removed and found again.
+ const installCounted = useRef(false);
+
+ const onAnswer = useCallback(
+ (answered: DesktopRoute) => {
+ if (!answered.context.app_installed) return;
+ setRoute(answered);
+ setArrived(true);
+ if (installCounted.current) return;
+ installCounted.current = true;
+ trackStudioEvent("desktop_cta_guide", { step: "install_detected", ...answered.context });
+ },
+ [setRoute],
+ );
+ useInstallWatch(cardOpen && route !== null && !installed, onAnswer);
+
+ useEffect(() => {
+ if (!downloaded || installed) return;
+ setSlow(false);
+ const timer = setTimeout(() => setSlow(true), SLOW_MS);
+ return () => clearTimeout(timer);
+ }, [downloaded, installed]);
+
if (!route) return null;
+ const context = route.context;
+ const guideStep = (step: GuideStep) =>
+ trackStudioEvent("desktop_cta_guide", { step, ...context });
+ const outcome = (result: "opened" | "sent_to_download" | "failed", reason?: string) =>
+ trackStudioEvent("desktop_cta_outcome", {
+ outcome: result,
+ ...(reason ? { reason } : {}),
+ ...context,
+ });
- const open = async () => {
- if (!route.handoff) {
- trackStudioEvent("toolbar_action", { action: "open_in_desktop" });
- setDownloadUrl(route.downloadUrl);
+ const showCard = (next: boolean) => {
+ if (next === cardOpen) return;
+ setCardOpen(next);
+ guideStep(next ? "opened" : "closed");
+ };
+
+ const download = () => {
+ if (!route.downloadUrl) return;
+ trackStudioEvent("toolbar_action", { action: "get_desktop_app", ...context });
+ const tab = window.open(withCta(route.downloadUrl), "_blank");
+ if (!tab) {
+ showToast(`Get the HyperFrames desktop app at ${route.downloadUrl}`, "info");
+ outcome("failed", "download_tab_blocked");
+ return;
+ }
+ tab.opener = null;
+ setDownloaded(true);
+ outcome("sent_to_download");
+ guideStep("download_opened");
+ };
+
+ const landed = async (result: OpenResult) => {
+ if (result.opened) {
+ outcome("opened");
+ showCard(false);
+ showToast("Opening this project in the HyperFrames desktop app", "info");
+ await new Promise((done) => setTimeout(done, OPENING_MS));
return;
}
+ outcome("failed", result.reason);
+ // The app is gone: back to the download. Anything else: say so where the person is, with a way through.
+ if (result.reason === "not-installed")
+ setRoute({ ...route, handoff: false, context: { ...context, app_installed: false } });
+ else setFailed(true);
+ showCard(true);
+ };
+
+ const open = async () => {
if (opening) return;
setOpening(true);
- trackStudioEvent("toolbar_action", { action: "open_in_desktop" });
+ setFailed(false);
+ trackStudioEvent("toolbar_action", { action: "open_in_desktop", ...context });
try {
- const res = await studioApiFetch(ROUTE, { method: "POST" });
- const result = (await res.json()) as OpenResult;
- if (result.opened) {
- showToast("Framey is opening this project in the HyperFrames desktop app", "info");
- await new Promise((done) => setTimeout(done, OPENING_MS));
- } else setDownloadUrl(result.downloadUrl);
+ const res = await studioApiFetch(ROUTE, {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify({ cta: resolveTabId() }),
+ });
+ await landed((await res.json()) as OpenResult);
} catch {
+ outcome("failed", "preview_server_unreachable");
showToast("Couldn't reach the preview server to open the app", "error");
} finally {
setOpening(false);
}
};
+ const progress: Progress = { route, opening, failed, downloaded, slow, arrived };
+ return { progress, cardOpen, showCard, download, open };
+}
+
+export function OpenInDesktopButton() {
+ const projectDir = useFileManagerContextOptional()?.projectDir ?? null;
+ const [route, setRoute] = useDesktopRoute();
+ const trigger = useRef<HTMLButtonElement>(null);
+ const eye = useRef<SVGGElement>(null);
+ useGaze(trigger, eye);
+ useImpression(trigger, route);
+ const guide = useGuide(route, setRoute);
+ if (!guide) return null;
+ const { progress, cardOpen, showCard, download, open } = guide;
+ const label = labelOf(progress);
+ const waiting = isWaiting(progress);
+
return (
<Popover
- open={downloadUrl !== null}
- // The popover owns the trigger's press: a press runs the hand-off, and the card shows only when there is
- // something to say (the download). A second handler on the button raced this one.
+ open={cardOpen}
+ // With the app ready the press is the hand-off itself; everything else opens the card.
onOpenChange={(next) => {
- if (next) void open();
- else setDownloadUrl(null);
+ if (next && progress.route.handoff && !progress.failed) return void open();
+ showCard(next);
}}
side="bottom"
align="end"
- arrow
- aria-label="Meet Framey"
- className="w-72"
+ aria-label="Get the desktop app"
+ className="w-[360px] overflow-hidden p-0"
trigger={
<Button
ref={trigger}
variant="ghost"
data-testid="header-open-in-desktop"
- data-opening={opening || undefined}
- title="Open this project in the HyperFrames desktop app and edit it with Framey"
- className="hf-framey-trigger gap-1.5 border border-accent/40 bg-accent/10 pl-1 font-semibold text-text-0 enabled:hover:bg-accent/20"
- icon={<FrameyGlyph size={24} className="hf-framey" eyeRef={eye} />}
+ data-opening={progress.opening || undefined}
+ aria-busy={progress.opening || waiting || undefined}
+ title={
+ progress.route.handoff
+ ? "Open this project in the HyperFrames desktop app"
+ : "Get the free HyperFrames desktop app"
+ }
+ className={cn(LOOK, progress.failed && LOOK_FAILED)}
+ icon={
+ <FrameyGlyph size={24} className="hf-framey" eyeRef={eye} mood={moodOf(progress)} />
+ }
>
- {opening ? "Opening in the app…" : "Edit with Framey"}
- {!opening && (
- <span className="rounded-full bg-accent px-1.5 text-[10px] leading-4 font-bold text-on-accent">
- New
+ <Swap value={label}>{label}</Swap>
+ {waiting && (
+ <span className="rounded-full bg-on px-1.5 text-[10px] leading-4 font-bold text-accent-ink tabular-nums">
+ 2 of 3
</span>
)}
</Button>
}
>
- <div className="flex items-center gap-2.5">
- <FrameyGlyph size={36} />
- <p className="text-step-12 font-medium text-text-0">Meet Framey</p>
- </div>
- <p className="mt-2 text-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>
- <li>Watch me act out each edit</li>
- </ul>
- <div className="mt-3 flex items-center justify-end gap-2 whitespace-nowrap">
- <Button variant="ghost" onClick={() => setDownloadUrl(null)}>
- Not now
- </Button>
- <a
- href={downloadUrl ?? undefined}
- target="_blank"
- rel="noopener noreferrer"
- className={cn(buttonBase, buttonVariants.primary, buttonSizes.md)}
- onClick={() => trackStudioEvent("toolbar_action", { action: "get_desktop_app" })}
- >
- Get the desktop app
- </a>
- </div>
+ <GuideCard
+ progress={progress}
+ projectDir={projectDir}
+ onDownload={download}
+ onOpen={() => void open()}
+ />
</Popover>
);
}
diff --git a/packages/studio/src/styles/components.css b/packages/studio/src/styles/components.css
index 1ef5398b40..ae76e180bc 100644
--- a/packages/studio/src/styles/components.css
+++ b/packages/studio/src/styles/components.css
@@ -956,7 +956,7 @@
}
}
-/* Framey on the header's "Edit with Framey" (OpenInDesktopButton.tsx): a pulse as the page opens, a wiggle
+/* Framey on the header's "Install the desktop app" (OpenInDesktopButton.tsx): a pulse as the page opens, a wiggle
* on hover, a flight towards the app while it opens. The eye follows the pointer from script. */
@keyframes hf-framey-wiggle {
0%,
@@ -1020,3 +1020,163 @@
transition: none;
}
}
+
+/* Framey's moods, timed as the desktop app times them: it breathes and blinks, its eyes circle while it waits,
+ * it hops once when the app turns up, flies while a project hands over, and shakes when that fails. */
+.hf-framey-mood .hf-framey-body {
+ transform-box: fill-box;
+ transform-origin: 50% 60%;
+ animation: hf-framey-breath 3.27s ease-in-out infinite;
+}
+
+.hf-framey-mood .hf-framey-lid,
+.hf-framey-mood .hf-framey-whole {
+ transform-box: fill-box;
+ transform-origin: 50% 50%;
+}
+
+.hf-framey-mood .hf-framey-whole {
+ transform-origin: 50% 100%;
+}
+
+.hf-framey-mood:is([data-mood="idle"], [data-mood="found"]) .hf-framey-lid {
+ animation: hf-framey-blink 4.6s infinite;
+}
+
+.hf-framey-mood[data-mood="found"] .hf-framey-whole {
+ animation: hf-framey-hop 1.8s cubic-bezier(0.2, 0.8, 0.2, 1) 2;
+}
+
+.hf-framey-mood[data-mood="opening"] .hf-framey-whole {
+ animation: hf-framey-handoff 2.4s cubic-bezier(0.2, 0.8, 0.2, 1) infinite;
+}
+
+.hf-framey-mood[data-mood="error"] .hf-framey-whole {
+ animation: hf-framey-shake 0.6s ease-in-out 1;
+}
+
+.hf-framey-orbit {
+ animation: hf-framey-orbit 1.4s linear infinite;
+}
+
+@keyframes hf-framey-breath {
+ 50% {
+ transform: scale(1.018);
+ }
+}
+
+@keyframes hf-framey-blink {
+ 0%,
+ 93%,
+ 100% {
+ transform: scaleY(1);
+ }
+ 95.5% {
+ transform: scaleY(0.12);
+ }
+}
+
+@keyframes hf-framey-hop {
+ 0%,
+ 40%,
+ 100% {
+ transform: translateY(0);
+ }
+ 20% {
+ transform: translateY(-7px);
+ }
+}
+
+@keyframes hf-framey-orbit {
+ 0%,
+ 100% {
+ transform: translate(3px, 0);
+ }
+ 25% {
+ transform: translate(0, 3px);
+ }
+ 50% {
+ transform: translate(-3px, 0);
+ }
+ 75% {
+ transform: translate(0, -3px);
+ }
+}
+
+@keyframes hf-framey-handoff {
+ 0% {
+ transform: none;
+ }
+ 45%,
+ 60% {
+ transform: translate(14px, -4px) rotate(10deg);
+ opacity: 1;
+ }
+ 80% {
+ transform: translate(30px, -8px) rotate(12deg);
+ opacity: 0;
+ }
+ 81% {
+ transform: translate(-10px, 0);
+ opacity: 0;
+ }
+ 100% {
+ transform: none;
+ opacity: 1;
+ }
+}
+
+@keyframes hf-framey-shake {
+ 0%,
+ 100% {
+ transform: translateX(0);
+ }
+ 20% {
+ transform: translateX(-3px);
+ }
+ 40% {
+ transform: translateX(3px);
+ }
+ 60% {
+ transform: translateX(-2px);
+ }
+ 80% {
+ transform: translateX(2px);
+ }
+}
+
+/* The desktop-app guide card: a label or step that changes settles in; a finished step's tick pops in. */
+.hf-guide-swap {
+ animation: hf-guide-swap 180ms var(--ease-out-quint);
+}
+
+.hf-guide-tick {
+ animation: hf-guide-tick 300ms var(--ease-out-quint);
+}
+
+@keyframes hf-guide-swap {
+ from {
+ opacity: 0;
+ transform: translateY(3px);
+ filter: blur(2px);
+ }
+}
+
+@keyframes hf-guide-tick {
+ from {
+ opacity: 0;
+ transform: scale(0.3);
+ filter: blur(3px);
+ }
+}
+
+@media (prefers-reduced-motion: reduce) {
+ .hf-framey-mood .hf-framey-body,
+ .hf-framey-mood .hf-framey-lid,
+ .hf-framey-mood .hf-framey-whole,
+ .hf-framey-orbit,
+ .hf-guide-swap,
+ .hf-guide-tick {
+ animation: none;
+ }
+}
diff --git a/scripts/studio-runtime-smoke.mjs b/scripts/studio-runtime-smoke.mjs
index 379f93cd21..4d2843042a 100644
--- a/scripts/studio-runtime-smoke.mjs
+++ b/scripts/studio-runtime-smoke.mjs
@@ -52,7 +52,7 @@ const GET_RESPONSES = new Map([
// interesting assertion is that the shell mounts clean, not that a blocking
// notice renders. The notice has its own tests.
["/api/environment/ffmpeg", json({ ok: true })],
- // The header's Edit with Framey asks this on load; shown, so the shell mounts with it.
+ // The header's "Install the desktop app" asks this on load; shown, so the shell mounts with it.
[
"/api/open-in-desktop",
json({