npm - @hyperframes/studio - Versions diffs - 0.8.0 → 0.8.1 - Mend

@hyperframes/studio 0.8.0 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (28) hide show

package/dist/assets/hyperframes-player-CZd-Aooq.js +459 -0
package/dist/assets/{index-CNMWti50.js → index-BUkSmrkr.js} +1 -1
package/dist/assets/{index-qKEWQDBH.js → index-CCc35ru7.js} +1 -1
package/dist/assets/{index-C8UQR5cB.js → index-CEuEI4NE.js} +180 -180
package/dist/assets/index-DcF4s1PG.css +1 -0
package/dist/index.html +2 -2
package/dist/index.js +1721 -1487
package/dist/index.js.map +1 -1
package/package.json +7 -7
package/src/components/StudioHeader.tsx +12 -1
package/src/components/StudioLeftSidebar.tsx +14 -1
package/src/components/StudioRightPanel.tsx +2 -33
package/src/components/renders/FfmpegRequiredNotice.test.tsx +105 -0
package/src/components/renders/FfmpegRequiredNotice.tsx +133 -0
package/src/components/renders/RenderQueue.test.tsx +83 -1
package/src/components/renders/RenderQueue.tsx +37 -1
package/src/components/renders/RenderQueuePanel.tsx +56 -0
package/src/components/renders/renderQueueTestHarness.tsx +74 -0
package/src/components/renders/serverError.test.ts +50 -0
package/src/components/renders/serverError.ts +21 -0
package/src/components/renders/useFfmpegStatus.ts +108 -0
package/src/components/renders/useRenderQueue.ts +42 -2
package/src/components/renders/useRenderQueueFfmpegGate.test.tsx +79 -0
package/src/components/renders/useRenderQueueTelemetry.test.tsx +8 -36
package/src/contexts/StudioContext.tsx +7 -0
package/src/hooks/useStudioContextValue.ts +4 -12
package/dist/assets/hyperframes-player-BShTvtlv.js +0 -459
package/dist/assets/index-8lDGbNjx.css +0 -1

package/src/components/renders/renderQueueTestHarness.tsx ADDED Viewed

@@ -0,0 +1,74 @@
+// Shared mounting/stubbing for the useRenderQueue test files. Both of them
+// need the same three things — a fetch that answers the render POST, an inert
+// EventSource, and a component that exposes the hook's value — and keeping two
+// copies in step is not worth the lines.
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { vi } from "vitest";
+import type { useRenderQueue } from "./useRenderQueue";
+export type RenderQueueApi = ReturnType<typeof useRenderQueue>;
+type UseRenderQueue = typeof useRenderQueue;
+// Part of the harness contract: importing it puts React in act() mode, so no
+// test file has to remember to.
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+/** Answers the render POST with a job id, and the history GET with nothing. */
+export function stubRenderFetch(): ReturnType<typeof vi.fn> {
+  const fetchMock = vi.fn(async () =>
+    Promise.resolve(
+      new Response(JSON.stringify({ jobId: "j1", status: "rendering" }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+    ),
+  );
+  vi.stubGlobal("fetch", fetchMock);
+  vi.stubGlobal(
+    "EventSource",
+    class {
+      close(): void {}
+      addEventListener(): void {}
+    },
+  );
+  return fetchMock;
+}
+/** Render POSTs only, so assertions ignore the history GET the hook makes. */
+export function renderPosts(fetchMock: ReturnType<typeof vi.fn>): unknown[] {
+  return fetchMock.mock.calls.filter(
+    ([, init]) => (init as RequestInit | undefined)?.method === "POST",
+  );
+}
+export interface MountedQueue {
+  /** The hook's current value. Throws if the harness never mounted. */
+  api: () => RenderQueueApi;
+  unmount: () => void;
+}
+export function mountRenderQueue(
+  useRenderQueueHook: UseRenderQueue,
+  projectId = "demo",
+): MountedQueue {
+  let current: RenderQueueApi | null = null;
+  function Harness(): null {
+    current = useRenderQueueHook(projectId);
+    return null;
+  }
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root: Root = createRoot(host);
+  act(() => {
+    root.render(<Harness />);
+  });
+  return {
+    api: () => {
+      if (!current) throw new Error("useRenderQueue harness did not mount");
+      return current;
+    },
+    unmount: () => act(() => root.unmount()),
+  };
+}

package/src/components/renders/serverError.test.ts ADDED Viewed

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { readServerError } from "./serverError";
+function jsonResponse(body: unknown, status: number): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+describe("readServerError", () => {
+  // The regression this whole file exists for: the render route's 503 carries
+  // "FFmpeg not found" plus the install command, and Studio used to show the
+  // user "Server error (503)" instead.
+  it("prefers the server's cause and remediation over the status code", async () => {
+    const res = jsonResponse({ error: "FFmpeg not found", hint: "brew install ffmpeg" }, 503);
+    await expect(readServerError(res)).resolves.toBe("FFmpeg not found. brew install ffmpeg");
+  });
+  it("uses the cause alone when the server sends no hint", async () => {
+    const res = jsonResponse({ error: "FFmpeg not found" }, 503);
+    await expect(readServerError(res)).resolves.toBe("FFmpeg not found");
+  });
+  it("falls back to the status code when the body is not JSON", async () => {
+    const res = new Response("<html>502 Bad Gateway</html>", { status: 502 });
+    await expect(readServerError(res)).resolves.toBe(
+      "Server error (502). Check the terminal for details.",
+    );
+  });
+  it("falls back to the status code when the JSON carries no error string", async () => {
+    const res = jsonResponse({ hint: "brew install ffmpeg" }, 500);
+    await expect(readServerError(res)).resolves.toBe(
+      "Server error (500). Check the terminal for details.",
+    );
+  });
+  it("ignores a non-string error rather than rendering it as an object", async () => {
+    const res = jsonResponse({ error: { code: 17 } }, 500);
+    await expect(readServerError(res)).resolves.toBe(
+      "Server error (500). Check the terminal for details.",
+    );
+  });
+});

package/src/components/renders/serverError.ts ADDED Viewed

@@ -0,0 +1,21 @@
+/**
+ * The render route answers a refusal with `{ error, hint }` naming the exact
+ * cause and how to fix it. Studio used to print the bare status code and drop
+ * that body, which is why the most common Studio export failure reached users
+ * as "Server error (503)" with no mention of the missing FFmpeg the server had
+ * already diagnosed. The status code is the fallback now, not the message.
+ */
+export async function readServerError(res: Response): Promise<string> {
+  try {
+    const body: unknown = await res.json();
+    if (typeof body === "object" && body !== null) {
+      const { error, hint } = body as { error?: unknown; hint?: unknown };
+      if (typeof error === "string" && error) {
+        return typeof hint === "string" && hint ? `${error}. ${hint}` : error;
+      }
+    }
+  } catch {
+    // Not JSON, or the body was already consumed — fall through to the status.
+  }
+  return `Server error (${res.status}). Check the terminal for details.`;
+}

package/src/components/renders/useFfmpegStatus.ts ADDED Viewed

@@ -0,0 +1,108 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+/**
+ * What the dev server knows about this machine's FFmpeg, as reported by
+ * `GET /api/environment/ffmpeg`. Studio asks when the Render panel opens so a
+ * missing encoder is a prompt with an install command, not a failed export an
+ * hour into the work.
+ */
+export interface FfmpegStatus {
+  ok: boolean;
+  /** Short headline, e.g. "FFmpeg not found". Absent when ok. */
+  title?: string;
+  /** Why it cannot run, in the server's words. Absent when ok. */
+  detail?: string;
+  /** Prose remediation, including the manual route where one exists. */
+  hint?: string;
+  /** A single pasteable install command, when this platform has one. */
+  command?: string;
+}
+/**
+ * `null` means "no answer", NOT "missing". An unreachable or older dev server
+ * is not evidence that FFmpeg is absent, and blocking Export on a failed probe
+ * would lock out people whose setup is fine. Unknown always fails open.
+ */
+type ProbeResult = FfmpegStatus | null;
+/**
+ * One line naming the problem and the fix, for the render row Studio writes
+ * when it refuses to start. Prefers the command over the prose hint: the row
+ * is narrow, and the command is the part the user acts on.
+ */
+export function ffmpegInstallMessage(status: FfmpegStatus | null): string {
+  const title = status?.title ?? "FFmpeg not found";
+  const remedy = status?.command ?? status?.hint;
+  return remedy ? `${title}. Install it with: ${remedy}` : `${title}. Install FFmpeg to export.`;
+}
+// The Render panel unmounts on every right-panel tab switch, and each miss
+// re-probes the filesystem server-side. Remember the answer for the tab's life.
+let cached: ProbeResult = null;
+const asText = (value: unknown): string | undefined =>
+  typeof value === "string" && value ? value : undefined;
+/** Parses the endpoint's answer, or `null` for anything that is not one. */
+function parseStatus(body: unknown): ProbeResult {
+  if (typeof body !== "object" || body === null) return null;
+  const { ok, title, detail, hint, command } = body as Record<string, unknown>;
+  if (typeof ok !== "boolean") return null;
+  return {
+    ok,
+    title: asText(title),
+    detail: asText(detail),
+    hint: asText(hint),
+    command: asText(command),
+  };
+}
+async function probe(): Promise<ProbeResult> {
+  try {
+    const res = await fetch("/api/environment/ffmpeg");
+    return res.ok ? parseStatus(await res.json()) : null;
+  } catch {
+    return null;
+  }
+}
+export function useFfmpegStatus(): {
+  status: ProbeResult;
+  checking: boolean;
+  recheck: () => void;
+} {
+  const [status, setStatus] = useState<ProbeResult>(cached);
+  const [checking, setChecking] = useState(cached === null);
+  const mounted = useRef(true);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+  const run = useCallback(async () => {
+    setChecking(true);
+    const next = await probe();
+    cached = next;
+    if (!mounted.current) return;
+    setStatus(next);
+    setChecking(false);
+  }, []);
+  useEffect(() => {
+    if (cached !== null) return;
+    void run();
+  }, [run]);
+  // Someone who just installed FFmpeg should not have to restart Studio to
+  // prove it. Drops the cache so the server re-probes rather than replaying
+  // the stale "not found" it already cached against.
+  const recheck = useCallback(() => {
+    cached = null;
+    void run();
+  }, [run]);
+  return { status, checking, recheck };
+}

package/src/components/renders/useRenderQueue.ts CHANGED Viewed

@@ -4,6 +4,8 @@ import { trackStudioRenderStart } from "../../telemetry/events";
 import { getAnonymousId } from "../../telemetry/config";
 import { browserTelemetryAllowed } from "../../telemetry/policy";
 import { generateId } from "../../utils/generateId";
+import { readServerError } from "./serverError";
+import { ffmpegInstallMessage, useFfmpegStatus } from "./useFfmpegStatus";
 import { requestStudioFeedback, type FeedbackContext } from "../feedback/feedbackTrigger";
 export interface RenderJob {
@@ -71,6 +73,17 @@ export function useRenderQueue(projectId: string | null) {
   const [loadError, setLoadError] = useState<string | null>(null);
   // Failure of a user action (delete/cancel), surfaced inline in the panel.
   const [actionError, setActionError] = useState<string | null>(null);
+  // Owned here rather than in the panel: Studio renders from three places —
+  // the panel's Export button, the header's, and each composition card in the
+  // left sidebar — and a check living in one of them leaves the rest free to
+  // start a render this machine cannot finish. Every caller routes through
+  // `startRender`, so that is where the refusal belongs. Call sites still
+  // read `ffmpegMissing` to put the prompt on screen, because a refusal the
+  // user cannot see reads as a broken button.
+  const { status: ffmpeg, checking: ffmpegChecking, recheck: recheckFfmpeg } = useFfmpegStatus();
+  // A null status means the probe gave no answer (older server, failed
+  // request), which is not evidence of a missing encoder. Unknown fails open.
+  const ffmpegMissing = ffmpeg !== null && !ffmpeg.ok;
   const eventSourceRef = useRef<EventSource | null>(null);
   const activeJobRef = useRef<string | null>(null);
   // Renders started in THIS tab, mapped to the settings they ran with.
@@ -150,6 +163,23 @@ export function useRenderQueue(projectId: string | null) {
     // fallow-ignore-next-line complexity
     async (opts: StartRenderOptions = {}) => {
       if (!projectId) return;
+      // The server would answer this with a 503 anyway. Refusing here keeps
+      // the reason and the fix in the message, and keeps a control that
+      // forgot to disable itself from producing a mystery failure.
+      if (ffmpegMissing) {
+        addSessionJob(
+          {
+            id: generateId(),
+            status: "failed",
+            progress: 0,
+            error: ffmpegInstallMessage(ffmpeg),
+            filename: "Export blocked",
+            createdAt: Date.now(),
+          },
+          {},
+        );
+        return;
+      }
       const fps = opts.fps ?? 30;
       const quality = opts.quality ?? "standard";
@@ -237,7 +267,7 @@ export function useRenderQueue(projectId: string | null) {
           id: generateId(),
           status: "failed",
           progress: 0,
-          error: `Server error (${res.status}). Check the terminal for details.`,
+          error: await readServerError(res),
           filename: "Export failed",
           createdAt: startTime,
         };
@@ -307,7 +337,7 @@ export function useRenderQueue(projectId: string | null) {
       return jobId;
     },
-    [projectId, closeActiveEventSource, addSessionJob],
+    [projectId, closeActiveEventSource, addSessionJob, ffmpeg, ffmpegMissing],
   );
   // Cancel an in-flight render. The job row stays (as "cancelled") so the
@@ -431,6 +461,12 @@ export function useRenderQueue(projectId: string | null) {
       cancelRender,
       clearCompleted,
       startRender: startRender as (options: unknown) => Promise<void>,
+      // Every Export control reads these, so no caller has to decide for
+      // itself whether this machine can encode.
+      ffmpeg,
+      ffmpegMissing,
+      ffmpegChecking,
+      recheckFfmpeg,
     }),
     [
       jobs,
@@ -443,6 +479,10 @@ export function useRenderQueue(projectId: string | null) {
       cancelRender,
       clearCompleted,
       startRender,
+      ffmpeg,
+      ffmpegMissing,
+      ffmpegChecking,
+      recheckFfmpeg,
     ],
   );
 }

package/src/components/renders/useRenderQueueFfmpegGate.test.tsx ADDED Viewed

@@ -0,0 +1,79 @@
+// @vitest-environment happy-dom
+// Studio has three render entry points: the Renders panel's Export button, the
+// header's, and the Render control on every composition card in the left
+// sidebar. The last two call startRender directly. A check that lives in one
+// button leaves every other caller free to queue a render this machine cannot
+// finish, so the refusal lives in startRender, which all of them route through
+// — including any fourth caller nobody has written yet.
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { FfmpegStatus } from "./useFfmpegStatus";
+import { mountRenderQueue, renderPosts, stubRenderFetch } from "./renderQueueTestHarness";
+let ffmpegStatus: FfmpegStatus | null = { ok: true };
+vi.mock("./useFfmpegStatus", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./useFfmpegStatus")>()),
+  useFfmpegStatus: () => ({ status: ffmpegStatus, checking: false, recheck: vi.fn() }),
+}));
+// Only the analytics call is stubbed. The identity and policy modules read
+// localStorage, which happy-dom provides, so faking them would only be faking.
+vi.mock("../../telemetry/events", () => ({ trackStudioRenderStart: vi.fn() }));
+const { useRenderQueue } = await import("./useRenderQueue");
+let queue: ReturnType<typeof mountRenderQueue> | null = null;
+let fetchMock: ReturnType<typeof stubRenderFetch>;
+beforeEach(() => {
+  ffmpegStatus = { ok: true };
+  fetchMock = stubRenderFetch();
+});
+afterEach(() => {
+  queue?.unmount();
+  queue = null;
+  document.body.innerHTML = "";
+  vi.unstubAllGlobals();
+});
+async function start(): Promise<ReturnType<typeof mountRenderQueue>> {
+  queue = mountRenderQueue(useRenderQueue);
+  const { act } = await import("react");
+  await act(async () => {
+    await queue?.api().startRender({});
+  });
+  return queue;
+}
+describe("useRenderQueue FFmpeg gate", () => {
+  it("refuses to start a render, from any caller, when FFmpeg is missing", async () => {
+    ffmpegStatus = { ok: false, title: "FFmpeg not found", command: "brew install ffmpeg" };
+    const mounted = await start();
+    expect(renderPosts(fetchMock)).toHaveLength(0);
+    const job = mounted.api().jobs.at(-1);
+    expect(job?.status).toBe("failed");
+    // The point of refusing here rather than letting the server 503: the row
+    // carries the fix, not a status code.
+    expect(job?.error).toBe("FFmpeg not found. Install it with: brew install ffmpeg");
+  });
+  it("starts the render when FFmpeg is present", async () => {
+    await start();
+    expect(renderPosts(fetchMock)).toHaveLength(1);
+  });
+  it("starts the render when the probe gave no answer", async () => {
+    // An unreachable or older dev server must not block a working setup.
+    ffmpegStatus = null;
+    const mounted = await start();
+    expect(renderPosts(fetchMock)).toHaveLength(1);
+    expect(mounted.api().ffmpegMissing).toBe(false);
+  });
+});

package/src/components/renders/useRenderQueueTelemetry.test.tsx CHANGED Viewed

@@ -8,8 +8,8 @@
 // correctly.
 import { act } from "react";
-import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mountRenderQueue, renderPosts, stubRenderFetch } from "./renderQueueTestHarness";
 const policyState = { allowed: true };
 const mintCalls = vi.fn(() => "browser-user-123");
@@ -26,45 +26,17 @@ vi.mock("../../telemetry/events", () => ({
 const { useRenderQueue } = await import("./useRenderQueue");
-Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
-let root: Root | null = null;
+let queue: ReturnType<typeof mountRenderQueue> | null = null;
 /** Body of the POST the hook makes when a render is started. */
 async function startRenderBody(): Promise<Record<string, unknown>> {
-  const fetchMock = vi.fn(async (_url: string, _init?: RequestInit) =>
-    Promise.resolve(
-      new Response(JSON.stringify({ jobId: "j1", status: "rendering" }), {
-        status: 200,
-        headers: { "content-type": "application/json" },
-      }),
-    ),
-  );
-  vi.stubGlobal("fetch", fetchMock);
-  vi.stubGlobal(
-    "EventSource",
-    class {
-      close(): void {}
-      addEventListener(): void {}
-    },
-  );
-  let api: ReturnType<typeof useRenderQueue> | null = null;
-  function Harness(): null {
-    api = useRenderQueue("demo");
-    return null;
-  }
-  const host = document.createElement("div");
-  document.body.append(host);
-  root = createRoot(host);
-  act(() => {
-    root?.render(<Harness />);
-  });
+  const fetchMock = stubRenderFetch();
+  queue = mountRenderQueue(useRenderQueue);
   await act(async () => {
-    await api?.startRender({ fps: 30, quality: "standard", format: "mp4" });
+    await queue?.api().startRender({ fps: 30, quality: "standard", format: "mp4" });
   });
-  const post = fetchMock.mock.calls.find(([, init]) => init?.method === "POST");
+  const [post] = renderPosts(fetchMock) as [undefined | [string, RequestInit]];
   const body = post?.[1]?.body;
   if (body === undefined || body === null) throw new Error("hook made no POST with a body");
   return JSON.parse(String(body)) as Record<string, unknown>;
@@ -76,8 +48,8 @@ beforeEach(() => {
 });
 afterEach(() => {
-  if (root) act(() => root?.unmount());
-  root = null;
+  queue?.unmount();
+  queue = null;
   document.body.innerHTML = "";
   vi.unstubAllGlobals();
 });

package/src/contexts/StudioContext.tsx CHANGED Viewed

@@ -1,6 +1,7 @@
 import { createContext, useContext, useMemo, type ReactNode } from "react";
 import type { TimelineElement } from "../player";
 import type { CompositionDimensions } from "../components/renders/RenderQueue";
+import type { FfmpegStatus } from "../components/renders/useFfmpegStatus";
 export interface StudioShellValue {
   projectId: string;
@@ -27,6 +28,12 @@ export interface StudioShellValue {
     cancelRender: (jobId: string) => void;
     clearCompleted: () => void;
     startRender: (options: unknown) => Promise<void>;
+    /** Encoder availability. `null` means "no answer", not "missing". */
+    ffmpeg: FfmpegStatus | null;
+    /** True only when the server positively reported no usable FFmpeg. */
+    ffmpegMissing: boolean;
+    ffmpegChecking: boolean;
+    recheckFfmpeg: () => void;
   };
   compositionDimensions: CompositionDimensions | null;
   waitForPendingDomEditSaves: () => Promise<void>;

package/src/hooks/useStudioContextValue.ts CHANGED Viewed

@@ -20,18 +20,10 @@ interface StudioContextInput {
   editHistory: { canUndo: boolean; canRedo: boolean; undoLabel: string; redoLabel: string };
   handleUndo: StudioContextValue["handleUndo"];
   handleRedo: StudioContextValue["handleRedo"];
-  renderQueue: {
-    jobs: unknown[];
-    isRendering: boolean;
-    loadError: string | null;
-    actionError: string | null;
-    dismissActionError: () => void;
-    reloadRenders: () => void;
-    deleteRender: (id: string) => void;
-    cancelRender: (id: string) => void;
-    clearCompleted: () => void;
-    startRender: (options: unknown) => Promise<void>;
-  };
+  // Was a second copy of the same shape, which meant every field added to the
+  // context had to be added here too or the build broke. Same idiom as the
+  // fields around it: the context type owns it.
+  renderQueue: StudioContextValue["renderQueue"];
   compositionDimensions: { width: number; height: number } | null;
   waitForPendingDomEditSaves: () => Promise<void>;
   handlePreviewIframeRef: (iframe: HTMLIFrameElement | null) => void;