@hyperframes/studio 0.8.122 → 0.8.123

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.122",
+  "version": "0.8.123",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,12 +60,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/parsers": "0.8.122",
-    "@hyperframes/sdk": "0.8.122",
-    "@hyperframes/core": "0.8.122",
-    "@hyperframes/shader-transitions": "0.8.122",
-    "@hyperframes/studio-server": "0.8.122",
-    "@hyperframes/player": "0.8.122"
+    "@hyperframes/core": "0.8.123",
+    "@hyperframes/parsers": "0.8.123",
+    "@hyperframes/player": "0.8.123",
+    "@hyperframes/sdk": "0.8.123",
+    "@hyperframes/shader-transitions": "0.8.123",
+    "@hyperframes/studio-server": "0.8.123"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -81,7 +81,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.122"
+    "@hyperframes/producer": "0.8.123"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/FrameyGlyph.tsx

@@ -0,0 +1,52 @@
+import type { Ref } from "react";
+
+// 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.
+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 };
+
+/** `eyeRef` moves the pupils (a translate of a few px) without re-rendering. */
+export function FrameyGlyph({
+  size,
+  className,
+  eyeRef,
+}: {
+  size: number;
+  className?: string;
+  eyeRef?: Ref<SVGGElement>;
+}) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="58 30 82 76"
+      aria-hidden="true"
+      className={className}
+      overflow="visible"
+    >
+      <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>
+    </svg>
+  );
+}

package/src/components/OpenInDesktopButton.dom.test.tsx

@@ -0,0 +1,113 @@
+// @vitest-environment happy-dom
+
+/**
+ * "Edit with Framey": shown only where the preview server answers on macOS; a press opens the project in the app,
+ * or introduces Framey with the download while the app cannot take it or is missing.
+ */
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const showToast = vi.fn();
+vi.mock("../contexts/StudioContext", () => ({ useStudioShellContext: () => ({ showToast }) }));
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
+const { OpenInDesktopButton } = await import("./OpenInDesktopButton");
+
+const DOWNLOAD = "https://hyperframes.dev/studio/download";
+let mounted: { root: Root; host: HTMLElement } | null = null;
+let posts: number;
+
+function serve(get: Response | null, post?: unknown) {
+  posts = 0;
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (_url: string, init?: RequestInit) => {
+      if (init?.method === "POST") {
+        posts += 1;
+        return Response.json(post);
+      }
+      return get ?? new Response("Not found", { status: 404 });
+    }),
+  );
+}
+
+async function mount(): Promise<HTMLElement> {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  mounted = { root, host };
+  await act(async () => root.render(<OpenInDesktopButton />));
+  return host;
+}
+
+const downloadHref = () =>
+  [...document.querySelectorAll("a")]
+    .find((a) => a.textContent?.includes("Get HyperFrames Studio"))
+    ?.getAttribute("href");
+
+const button = () =>
+  document.querySelector<HTMLButtonElement>('[data-testid="header-open-in-desktop"]');
+
+beforeEach(() => showToast.mockReset());
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  if (!mounted) return;
+  const { root, host } = mounted;
+  mounted = null;
+  act(() => root.unmount());
+  host.remove();
+});
+
+it("stays hidden where the server has no hand-off (the desktop's own Studio)", async () => {
+  serve(null);
+  await mount();
+  expect(button()).toBeNull();
+});
+
+it("stays hidden when the server says it cannot open the app (not macOS)", async () => {
+  serve(Response.json({ available: false }));
+  await mount();
+  expect(button()).toBeNull();
+});
+
+it("while the app cannot take a project yet, introduces Framey with the download and opens nothing", async () => {
+  serve(Response.json({ available: true, handoff: false }), { opened: true });
+  await mount();
+  await act(async () => button()!.click());
+  expect(posts).toBe(0);
+  expect(document.body.textContent).toContain("Meet Framey");
+  expect(downloadHref()).toBe(DOWNLOAD);
+});
+
+it("opens the project in the app and says so", async () => {
+  serve(Response.json({ available: true, handoff: true }), {
+    opened: true,
+    bundleId: "dev.hyperframes.desktop",
+  });
+  await mount();
+  await act(async () => button()!.click());
+  expect(posts).toBe(1);
+  expect(showToast).toHaveBeenCalledWith(
+    "Framey is opening this project in HyperFrames Studio",
+    "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 }), {
+    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);
+});

package/src/components/OpenInDesktopButton.tsx

@@ -0,0 +1,153 @@
+import { useEffect, useRef, useState } from "react";
+import { useStudioShellContext } from "../contexts/StudioContext";
+import { studioApiFetch } from "../utils/studioApiFetch";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+import { FrameyGlyph } from "./FrameyGlyph";
+import { Button, buttonBase, buttonSizes, buttonVariants, cn, Popover } 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.
+const ROUTE = "/api/open-in-desktop";
+const DOWNLOAD_URL = "https://hyperframes.dev/studio/download";
+/** How far the pupils travel towards the pointer, in the glyph's own units. */
+const GAZE = 2.2;
+/** Long enough for the flight to finish before the label comes back. */
+const OPENING_MS = 1600;
+
+type OpenResult = { opened: true } | { opened: false; reason: string; downloadUrl: string };
+
+/** Null hides the button: no such route (the app's own Studio), or not macOS. */
+function useDesktopRoute(): { handoff: boolean } | null {
+  const [route, setRoute] = useState<{ handoff: boolean } | null>(null);
+  useEffect(() => {
+    let live = true;
+    studioApiFetch(ROUTE)
+      .then((res) => (res.ok ? res.json() : null))
+      .then((body: { available?: unknown; handoff?: unknown } | null) => {
+        if (live && body?.available === true) setRoute({ handoff: body.handoff === true });
+      })
+      .catch(() => {});
+    return () => {
+      live = false;
+    };
+  }, []);
+  return route;
+}
+
+/** Framey looks at the pointer: one listener, one write per frame, no re-render. */
+function useGaze(
+  anchor: React.RefObject<HTMLElement | null>,
+  eye: React.RefObject<SVGGElement | null>,
+) {
+  useEffect(() => {
+    let frame = 0;
+    const look = (event: PointerEvent) => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(() => {
+        const box = anchor.current?.getBoundingClientRect();
+        if (!box || !eye.current) return;
+        const dx = event.clientX - (box.left + box.height / 2);
+        const dy = event.clientY - (box.top + box.height / 2);
+        const distance = Math.hypot(dx, dy) || 1;
+        eye.current.style.transform = `translate(${(dx / distance) * GAZE}px, ${(dy / distance) * GAZE}px)`;
+      });
+    };
+    window.addEventListener("pointermove", look);
+    return () => {
+      cancelAnimationFrame(frame);
+      window.removeEventListener("pointermove", look);
+    };
+  }, [anchor, eye]);
+}
+
+export function OpenInDesktopButton() {
+  const { showToast } = useStudioShellContext();
+  const route = useDesktopRoute();
+  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);
+  if (!route) return null;
+
+  const open = async () => {
+    if (!route.handoff) {
+      trackStudioEvent("toolbar_action", { action: "open_in_desktop" });
+      setDownloadUrl(DOWNLOAD_URL);
+      return;
+    }
+    if (opening) return;
+    setOpening(true);
+    trackStudioEvent("toolbar_action", { action: "open_in_desktop" });
+    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 HyperFrames Studio", "info");
+        await new Promise((done) => setTimeout(done, OPENING_MS));
+      } else setDownloadUrl(result.downloadUrl);
+    } catch {
+      showToast("Couldn't reach the preview server to open the app", "error");
+    } finally {
+      setOpening(false);
+    }
+  };
+
+  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.
+      onOpenChange={(next) => {
+        if (next) void open();
+        else setDownloadUrl(null);
+      }}
+      side="bottom"
+      align="end"
+      arrow
+      aria-label="Meet Framey"
+      className="w-72"
+      trigger={
+        <Button
+          ref={trigger}
+          variant="ghost"
+          data-testid="header-open-in-desktop"
+          data-opening={opening || undefined}
+          title="Open this project in HyperFrames Studio, the desktop app, and edit it with Framey"
+          className="hf-framey-trigger gap-1.5 pl-1.5"
+          icon={<FrameyGlyph size={20} className="hf-framey" eyeRef={eye} />}
+        >
+          {opening ? "Opening in the app…" : "Edit with Framey"}
+        </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-text-3">
+        I live in HyperFrames Studio, the free desktop app for macOS:
+      </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 HyperFrames Studio
+        </a>
+      </div>
+    </Popover>
+  );
+}

package/src/components/StudioHeader.dom.test.tsx

@@ -40,6 +40,8 @@ vi.mock("../contexts/PanelLayoutContext", () => ({
 }));
 
 vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+// Probes the preview server on mount; covered in OpenInDesktopButton.dom.test.tsx.
+vi.mock("./OpenInDesktopButton", () => ({ OpenInDesktopButton: () => null }));
 
 const { StudioHeader } = await import("./StudioHeader");
 const { ShowThemeToggle } = await import("./ThemeToggle");

package/src/components/StudioHeader.tsx

@@ -6,6 +6,7 @@ import { trackStudioEvent } from "../utils/studioTelemetry";
 import { Button, buttonBase, buttonSizes, buttonVariants, cn, Tooltip } from "./ui";
 import { Dock } from "./dock/Dock";
 import { InspectorIcon } from "./icons/InspectorIcon";
+import { OpenInDesktopButton } from "./OpenInDesktopButton";
 import { HyperframesLogo } from "./ui/HyperframesLogo";
 import { ShowThemeToggle, ThemeToggle } from "./ThemeToggle";
 
@@ -151,6 +152,7 @@ export const StudioHeader = memo(function StudioHeader({
         </div>
         {showThemeToggle && <ThemeToggle />}
         <Dock.WindowMenu />
+        <OpenInDesktopButton />
         <Tooltip
           label={
             ffmpegMissing

package/src/styles/components.css

@@ -935,3 +935,54 @@
     transform: scaleY(1);
   }
 }
+
+/* Framey on the header's "Edit with Framey" (OpenInDesktopButton.tsx): a wiggle on hover, a flight towards
+ * the app while it opens. The eye follows the pointer from script. */
+@keyframes hf-framey-wiggle {
+  0%,
+  100% {
+    transform: rotate(0deg);
+  }
+  25% {
+    transform: rotate(-14deg);
+  }
+  60% {
+    transform: rotate(10deg);
+  }
+}
+
+@keyframes hf-framey-fly {
+  70% {
+    opacity: 1;
+  }
+  100% {
+    transform: translate(48px, -28px) rotate(25deg) scale(0.6);
+    opacity: 0;
+  }
+}
+
+.hf-framey {
+  transform-origin: 30% 30%;
+}
+
+.hf-framey-eye {
+  transition: transform 80ms linear;
+}
+
+.hf-framey-trigger:hover .hf-framey {
+  animation: hf-framey-wiggle 0.5s ease-in-out;
+}
+
+.hf-framey-trigger[data-opening] .hf-framey {
+  animation: hf-framey-fly 0.9s ease-in forwards;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hf-framey-trigger:hover .hf-framey,
+  .hf-framey-trigger[data-opening] .hf-framey {
+    animation: none;
+  }
+  .hf-framey-eye {
+    transition: none;
+  }
+}

package/src/styles/theme.css

@@ -436,6 +436,9 @@
   --color-violet-400: oklch(70.2% 0.183 293.541);
   --color-violet-500: oklch(60.6% 0.25 292.717);
   --color-white: #fff;
+  /* Framey, the desktop app's cursor mascot (hyperframes-internal packages/nib): the same in both themes. */
+  --color-framey: #3ce6ac;
+  --color-framey-ink: #16121a;
 }
 
 /* The colour-scheme picks each token's light or dark half: dark unless the document element