@hyperframes/studio 0.8.80 → 0.8.81

package/package.json

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

package/src/App.tsx

@@ -344,8 +344,7 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: St
     effectiveTimelineDuration,
   });
   const compositionDimensions = useCompositionDimensions(previewIframeRef);
-  const { lintModal, linting, handleLint, closeLintModal, findingsByFile, hasLintError } =
-    useLintModal(projectId, refreshKey);
+  const lint = useLintModal(projectId, refreshKey);
   const frameCapture = useFrameCapture({
     projectId,
     activeCompPath,
@@ -500,11 +499,11 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: St
                         onSelectComposition={handleSelectComposition}
                         onAddBlock={handleAddBlock}
                         onPreviewBlock={setBlockPreview}
-                        onLint={handleLint}
-                        linting={linting}
-                        lintFindingCount={lintModal?.length ?? findingsByFile.size}
-                        lintFindingsByFile={findingsByFile}
-                        lintHasError={hasLintError}
+                        onLint={lint.handleLint}
+                        linting={lint.linting}
+                        lintFindingCount={lint.lintFindingCount}
+                        lintFindingsByFile={lint.findingsByFile}
+                        lintHasError={lint.hasLintError}
                         onAddAssetToTimeline={handleAddAssetAtPlayhead}
                         onAddCompositionToTimeline={handleAddCompositionAtPlayhead}
                       />
@@ -577,8 +576,8 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: St
                 <StudioOverlays
                   projectId={projectId}
                   projectDir={fileManager.projectDir}
-                  lintModal={lintModal}
-                  closeLintModal={closeLintModal}
+                  lintModal={lint.lintModal}
+                  closeLintModal={lint.closeLintModal}
                   consoleErrors={consoleErrors}
                   clearConsoleErrors={() => setConsoleErrors(null)}
                   domEditSession={domEditSession}

package/src/components/StudioRightPanels.tsx

@@ -23,14 +23,10 @@ import { useStudioPlaybackContext, useStudioShellContext } from "../contexts/Stu
 import { useFileManagerContext } from "../contexts/FileManagerContext";
 import { useDomEditContext } from "../contexts/DomEditContext";
 import { usePlayerStore } from "../player";
-import {
-  applyColorGradingScopeUpdate,
-  EMPTY_COLOR_GRADING_SCOPE_RESULT,
-  type ColorGradingScope,
-} from "./studioColorGradingScope";
 import { timelineKeysForSelections } from "../utils/studioHelpers";
 import { canHideSelections } from "../utils/timelineInspector";
 import { useRemoveBackground } from "../hooks/useRemoveBackground";
+import { useApplyColorGradingScope } from "../hooks/useApplyColorGradingScope";
 
 // fallow-ignore-next-line complexity
 export function StudioRightPanels({
@@ -49,14 +45,8 @@ export function StudioRightPanels({
   onAutoGroupCarveSources,
   onAddMediaOverlay,
 }: StudioRightPanelsProps) {
-  const {
-    previewIframeRef,
-    projectId,
-    activeCompPath,
-    showToast,
-    waitForPendingDomEditSaves,
-    renderQueue,
-  } = useStudioShellContext();
+  const { previewIframeRef, projectId, activeCompPath, showToast, renderQueue } =
+    useStudioShellContext();
   const { captionEditMode, refreshKey } = useStudioPlaybackContext();
 
   const {
@@ -114,7 +104,6 @@ export function StudioRightPanels({
     refreshFileTree,
     readProjectFile,
     writeProjectFile,
-    fileTree,
     editingFile,
   } = useFileManagerContext();
 
@@ -158,40 +147,7 @@ export function StudioRightPanels({
   });
   useCaptionDesignFocus(captionEditMode);
 
-  const handleApplyColorGradingScope = useCallback(
-    async (scope: ColorGradingScope, value: string | null) =>
-      applyColorGradingScopeUpdate({
-        scope,
-        value,
-        selectedSourceFile: domEditSelection?.sourceFile || activeCompPath || "index.html",
-        fileTree,
-        projectId,
-        waitForPendingDomEditSaves,
-        readProjectFile,
-        writeProjectFile,
-        recordEdit,
-        reloadPreview,
-        showToast,
-      }).catch((error) => {
-        showToast(
-          `Couldn't apply color grading: ${error instanceof Error ? error.message : String(error)}`,
-          "error",
-        );
-        return EMPTY_COLOR_GRADING_SCOPE_RESULT;
-      }),
-    [
-      activeCompPath,
-      domEditSelection?.sourceFile,
-      fileTree,
-      projectId,
-      readProjectFile,
-      recordEdit,
-      reloadPreview,
-      showToast,
-      waitForPendingDomEditSaves,
-      writeProjectFile,
-    ],
-  );
+  const handleApplyColorGradingScope = useApplyColorGradingScope(recordEdit, reloadPreview);
 
   const handleRemoveBackground = useRemoveBackground(projectId, refreshFileTree, showToast);
 

package/src/components/panels/VariablesOtherCompositions.tsx

@@ -85,7 +85,7 @@ function CompositionSection({
 }
 
 export function VariablesOtherCompositions({
-  fileTree,
+  compositionPaths,
   excludePath,
   refreshKey,
   readProjectFile,
@@ -93,8 +93,8 @@ export function VariablesOtherCompositions({
   recordEdit,
   reloadPreview,
 }: {
-  fileTree: string[];
-  excludePath: string;
+  compositionPaths: string[];
+  excludePath: string | null;
   refreshKey: unknown;
   readProjectFile: (path: string) => Promise<string>;
   writeProjectFile: (path: string, content: string) => Promise<void>;
@@ -103,7 +103,7 @@ export function VariablesOtherCompositions({
 }) {
   const [selfRefresh, setSelfRefresh] = useState(0);
   const groups = useProjectCompositionVariables(
-    fileTree,
+    compositionPaths,
     excludePath,
     readProjectFile,
     `${refreshKey}:${selfRefresh}`,

package/src/components/panels/VariablesPanel.test.tsx

@@ -0,0 +1,86 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { openComposition } from "@hyperframes/sdk";
+import { VariablesPanel } from "./VariablesPanel";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const withTitle = (id: string, label: string) => `<!DOCTYPE html>
+<html data-composition-variables='[{"id":"title","type":"string","label":"${label}","default":"Hello"}]'>
+<body><div data-composition-id="${id}" data-hf-id="hf-stage" data-hf-root data-duration="5"></div></body>
+</html>`;
+
+const files: Record<string, string> = {
+  "index.html":
+    '<html><body><div data-hf-id="hf-stage" data-hf-root data-duration="5"></div></body></html>',
+  "main.html": withTitle("main", "Main title"),
+  "scene.html": withTitle("scene", "Scene title"),
+  ".hyperframes/preview/4884df6e.html": withTitle("root", "Generated title"),
+};
+const shell = {
+  activeCompPath: "index.html" as string | null,
+  compositions: ["index.html", "scene.html"],
+};
+
+vi.mock("../../contexts/StudioContext", () => ({
+  useStudioShellContext: () => ({ activeCompPath: shell.activeCompPath, showToast: vi.fn() }),
+  useStudioPlaybackContext: () => ({ refreshKey: 0 }),
+}));
+vi.mock("../../contexts/DomEditContext", () => ({
+  useDomEditContext: () => ({ domEditSelection: null }),
+}));
+vi.mock("../../contexts/FileManagerContext", () => ({
+  useFileManagerContext: () => ({
+    readProjectFile: async (path: string) => files[path] ?? "",
+    writeProjectFile: vi.fn(),
+    fileTree: Object.keys(files),
+    compositions: shell.compositions,
+  }),
+}));
+
+let root: Root | null = null;
+
+afterEach(() => {
+  act(() => root?.unmount());
+  root = null;
+  document.body.innerHTML = "";
+});
+
+async function renderOtherCompositions(sessionPath: string): Promise<string> {
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  const session = await openComposition(files[sessionPath]!, { history: false });
+  await act(async () => {
+    root?.render(
+      <VariablesPanel
+        sdkSession={session}
+        publishSdkSession={vi.fn()}
+        reloadPreview={vi.fn()}
+        recordEdit={vi.fn(async () => {})}
+      />,
+    );
+  });
+  const other = () =>
+    [...host.querySelectorAll("p")].find((p) => p.textContent === "Other compositions")
+      ?.parentElement?.textContent ?? "";
+  await vi.waitFor(() => expect(other()).toContain("scene.html"));
+  return other();
+}
+
+describe("VariablesPanel other compositions", () => {
+  it("lists the project's compositions, not Studio's generated preview documents", async () => {
+    shell.activeCompPath = "index.html";
+    shell.compositions = ["index.html", "scene.html"];
+    expect(await renderOtherCompositions("index.html")).not.toContain(".hyperframes/preview");
+  });
+
+  it("leaves out the main composition in the master view when it is not index.html", async () => {
+    shell.activeCompPath = null;
+    shell.compositions = ["main.html", "scene.html"];
+    expect(await renderOtherCompositions("main.html")).not.toContain("main.html");
+  });
+});

package/src/components/panels/VariablesPanel.tsx

@@ -254,7 +254,7 @@ export const VariablesPanel = memo(function VariablesPanel({
 }: VariablesPanelProps) {
   const { activeCompPath, showToast } = useStudioShellContext();
   const { refreshKey } = useStudioPlaybackContext();
-  const { readProjectFile, writeProjectFile, fileTree, compositions } = useFileManagerContext();
+  const { readProjectFile, writeProjectFile, compositions } = useFileManagerContext();
   const { domEditSelection } = useDomEditContext();
   // Master view (no activeCompPath) targets the real main composition, not a
   // hardcoded index.html — used for both the persist write target and the
@@ -537,8 +537,8 @@ export const VariablesPanel = memo(function VariablesPanel({
           </button>
         )}
         <VariablesOtherCompositions
-          fileTree={fileTree}
-          excludePath={activeCompPath ?? "index.html"}
+          compositionPaths={compositions}
+          excludePath={effectiveCompPath}
           refreshKey={`${refreshKey}:${revision}`}
           readProjectFile={readProjectFile}
           writeProjectFile={writeProjectFile}

package/src/components/sidebar/SidebarLintButton.test.tsx

@@ -44,6 +44,35 @@ describe("SidebarLintButton badge", () => {
     expect(badge?.textContent).toContain("including errors");
   });
 
+  it("pulses a few times and then holds still, so an idle Studio paints nothing", () => {
+    const badge = renderBadge(true);
+    expect(badge?.style.animationIterationCount).toBe("3");
+  });
+
+  it("pulses again when the finding count changes", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    root = createRoot(host);
+    const render = (findingCount: number) =>
+      act(() => {
+        root?.render(
+          <SidebarLintButton
+            onLint={vi.fn()}
+            linting={false}
+            findingCount={findingCount}
+            hasError
+          />,
+        );
+      });
+    render(2);
+    const first = host.querySelector("[data-lint-badge]");
+    render(2);
+    expect(host.querySelector("[data-lint-badge]")).toBe(first);
+    render(3);
+    // A new element restarts its CSS animation; a text change on the old one would not.
+    expect(host.querySelector("[data-lint-badge]")).not.toBe(first);
+  });
+
   it("stays still when the findings are warnings only", () => {
     const badge = renderBadge(false);
     expect(badge?.dataset.lintBadge).toBe("warning");

package/src/components/sidebar/SidebarLintButton.tsx

@@ -1,3 +1,5 @@
+const ERROR_PULSES_BEFORE_IDLE = 3;
+
 export function SidebarLintButton({
   onLint,
   linting,
@@ -31,7 +33,9 @@ export function SidebarLintButton({
         {linting ? "Linting…" : "Lint"}
         {!linting && findingCount != null && findingCount > 0 && (
           <span
+            key={findingCount}
             data-lint-badge={hasError ? "error" : "warning"}
+            style={hasError ? { animationIterationCount: ERROR_PULSES_BEFORE_IDLE } : undefined}
             className={
               hasError
                 ? "ml-1 min-w-[16px] rounded-full bg-panel-danger/25 px-1 text-[9px] font-bold text-panel-danger animate-pulse motion-reduce:animate-none"

package/src/components/studioColorGradingScope.ts

@@ -22,7 +22,7 @@ interface ApplyColorGradingScopeOptions {
   scope: ColorGradingScope;
   value: string | null;
   selectedSourceFile: string;
-  fileTree: string[];
+  compositionPaths: string[];
   projectId: string;
   waitForPendingDomEditSaves: () => Promise<void>;
   readProjectFile: ProjectFileReader;
@@ -35,11 +35,9 @@ interface ApplyColorGradingScopeOptions {
 function colorGradingScopePaths(
   scope: ColorGradingScope,
   selectedSourceFile: string,
-  fileTree: string[],
+  compositionPaths: string[],
 ): string[] {
-  return scope === "source-file"
-    ? [selectedSourceFile]
-    : fileTree.filter((path) => /\.html?$/i.test(path));
+  return scope === "source-file" ? [selectedSourceFile] : compositionPaths;
 }
 
 async function patchColorGradingScopeFiles(
@@ -72,7 +70,7 @@ export async function applyColorGradingScopeUpdate({
   scope,
   value,
   selectedSourceFile,
-  fileTree,
+  compositionPaths,
   projectId,
   waitForPendingDomEditSaves,
   readProjectFile,
@@ -91,7 +89,7 @@ export async function applyColorGradingScopeUpdate({
   }
 
   const { files, changedElements } = await patchColorGradingScopeFiles(
-    colorGradingScopePaths(scope, selectedSourceFile, fileTree),
+    colorGradingScopePaths(scope, selectedSourceFile, compositionPaths),
     value,
     readProjectFile,
   );

package/src/hooks/useApplyColorGradingScope.test.tsx

@@ -0,0 +1,53 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it, vi } from "vitest";
+import { useApplyColorGradingScope } from "./useApplyColorGradingScope";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const readProjectFile = vi.fn(async (_path: string) => "<html><body></body></html>");
+
+vi.mock("../contexts/StudioContext", () => ({
+  useStudioShellContext: () => ({
+    projectId: "demo",
+    activeCompPath: "index.html",
+    showToast: vi.fn(),
+    waitForPendingDomEditSaves: async () => {},
+  }),
+}));
+vi.mock("../contexts/DomEditContext", () => ({
+  useDomEditContext: () => ({ domEditSelection: null }),
+}));
+vi.mock("../contexts/FileManagerContext", () => ({
+  useFileManagerContext: () => ({
+    readProjectFile,
+    writeProjectFile: vi.fn(),
+    fileTree: ["index.html", "scene.html", ".hyperframes/preview/4884df6e.html"],
+    compositions: ["index.html", "scene.html"],
+  }),
+}));
+
+it("grades the project's compositions, not Studio's generated preview documents", async () => {
+  let apply: ReturnType<typeof useApplyColorGradingScope> | null = null;
+  function Probe() {
+    apply = useApplyColorGradingScope(
+      vi.fn(async () => {}),
+      vi.fn(),
+    );
+    return null;
+  }
+  const root = createRoot(document.createElement("div"));
+  act(() => root.render(<Probe />));
+
+  await act(async () => {
+    await apply!("project", null);
+  });
+
+  expect(readProjectFile.mock.calls.map(([path]) => path).sort()).toEqual([
+    "index.html",
+    "scene.html",
+  ]);
+  act(() => root.unmount());
+});

package/src/hooks/useApplyColorGradingScope.ts

@@ -0,0 +1,54 @@
+import { useCallback } from "react";
+import { useStudioShellContext } from "../contexts/StudioContext";
+import { useDomEditContext } from "../contexts/DomEditContext";
+import { useFileManagerContext } from "../contexts/FileManagerContext";
+import {
+  applyColorGradingScopeUpdate,
+  EMPTY_COLOR_GRADING_SCOPE_RESULT,
+  type ColorGradingScope,
+} from "../components/studioColorGradingScope";
+import type { StudioRightPanelsProps } from "../components/StudioRightPanels.types";
+
+export function useApplyColorGradingScope(
+  recordEdit: StudioRightPanelsProps["recordEdit"],
+  reloadPreview: StudioRightPanelsProps["reloadPreview"],
+) {
+  const { projectId, activeCompPath, showToast, waitForPendingDomEditSaves } =
+    useStudioShellContext();
+  const { domEditSelection } = useDomEditContext();
+  const { readProjectFile, writeProjectFile, compositions } = useFileManagerContext();
+  return useCallback(
+    async (scope: ColorGradingScope, value: string | null) =>
+      applyColorGradingScopeUpdate({
+        scope,
+        value,
+        selectedSourceFile: domEditSelection?.sourceFile || activeCompPath || "index.html",
+        compositionPaths: compositions,
+        projectId,
+        waitForPendingDomEditSaves,
+        readProjectFile,
+        writeProjectFile,
+        recordEdit,
+        reloadPreview,
+        showToast,
+      }).catch((error) => {
+        showToast(
+          `Couldn't apply color grading: ${error instanceof Error ? error.message : String(error)}`,
+          "error",
+        );
+        return EMPTY_COLOR_GRADING_SCOPE_RESULT;
+      }),
+    [
+      activeCompPath,
+      compositions,
+      domEditSelection?.sourceFile,
+      projectId,
+      readProjectFile,
+      recordEdit,
+      reloadPreview,
+      showToast,
+      waitForPendingDomEditSaves,
+      writeProjectFile,
+    ],
+  );
+}

package/src/hooks/useLintModal.test.tsx

@@ -69,6 +69,21 @@ describe("useLintModal hasLintError", () => {
   });
 });
 
+describe("useLintModal lintFindingCount", () => {
+  it("counts findings, not files, with the result open and after it closes", async () => {
+    const findings = ["a", "b", "c"].map((message) => ({
+      severity: "warning",
+      message,
+      file: "index.html",
+    }));
+    await mountWithLint(async () => ({ json: async () => ({ findings }) }));
+    expect(latest?.lintFindingCount).toBe(3);
+    act(() => latest?.closeLintModal());
+    expect(latest?.findingsByFile.size).toBe(1);
+    expect(latest?.lintFindingCount).toBe(3);
+  });
+});
+
 describe("useLintModal background lint", () => {
   it("waits for the live preview to boot before asking the server to lint", async () => {
     usePlayerStore.setState({ previewBooted: false });

package/src/hooks/useLintModal.ts

@@ -98,8 +98,10 @@ export function useLintModal(projectId: string | null, refreshKey?: number) {
 
   const findingsByElement = useMemo(() => groupFindings((f) => f.elementId), [groupFindings]);
   const findingsByFile = useMemo(() => groupFindings((f) => f.file), [groupFindings]);
-  // Reads the list the badge count reads: the manual result when present, else the background one.
-  const hasLintError = (lintModal ?? backgroundFindings).some((f) => f.severity === "error");
+  // The badge counts findings, not files: the manual result when present, else the background one.
+  const badgeFindings = lintModal ?? backgroundFindings;
+  const lintFindingCount = badgeFindings.length;
+  const hasLintError = badgeFindings.some((f) => f.severity === "error");
 
   // Sync lint findings directly to the player store — eliminates the
   // mirroring useEffect that was previously in App.tsx.
@@ -115,6 +117,7 @@ export function useLintModal(projectId: string | null, refreshKey?: number) {
     backgroundFindings,
     findingsByElement,
     findingsByFile,
+    lintFindingCount,
     hasLintError,
   };
 }

package/src/hooks/useProjectCompositionVariables.ts

@@ -51,7 +51,7 @@ async function readGroup(
  * full parse, so large projects don't pay N openComposition calls.
  */
 export function useProjectCompositionVariables(
-  fileTree: string[],
+  compositionPaths: string[],
   excludePath: string | null,
   readProjectFile: (path: string) => Promise<string>,
   refreshKey: unknown,
@@ -60,7 +60,7 @@ export function useProjectCompositionVariables(
 
   useEffect(() => {
     let cancelled = false;
-    const htmlFiles = fileTree.filter((p) => p.endsWith(".html") && p !== excludePath);
+    const htmlFiles = compositionPaths.filter((p) => p !== excludePath);
 
     void (async () => {
       const out: CompositionVariableGroup[] = [];
@@ -75,7 +75,7 @@ export function useProjectCompositionVariables(
       cancelled = true;
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [fileTree, excludePath, readProjectFile, refreshKey]);
+  }, [compositionPaths, excludePath, readProjectFile, refreshKey]);
 
   return groups;
 }