@hyperframes/studio 0.8.171 → 0.8.173

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.171",
+  "version": "0.8.173",
   "description": "",
   "repository": {
     "type": "git",
@@ -59,12 +59,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.171",
-    "@hyperframes/player": "0.8.171",
-    "@hyperframes/sdk": "0.8.171",
-    "@hyperframes/shader-transitions": "0.8.171",
-    "@hyperframes/studio-server": "0.8.171",
-    "@hyperframes/parsers": "0.8.171"
+    "@hyperframes/core": "0.8.173",
+    "@hyperframes/parsers": "0.8.173",
+    "@hyperframes/player": "0.8.173",
+    "@hyperframes/sdk": "0.8.173",
+    "@hyperframes/shader-transitions": "0.8.173",
+    "@hyperframes/studio-server": "0.8.173"
   },
   "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.171"
+    "@hyperframes/producer": "0.8.173"
   },
   "peerDependencies": {
     "react": "19",

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

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