@hyperframes/studio 0.8.172 → 0.8.174

package/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>
   );
 }

package/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;
+  }
+}