@hyperframes/studio 0.7.37 → 0.7.39

package/src/components/renders/useRenderQueue.ts

@@ -36,23 +36,66 @@ export interface StartRenderOptions {
   composition?: string;
 }
 
+// "Hide" (formerly "Clear") is a view operation, not a delete: hidden ids are
+// remembered here so hidden renders don't resurrect from the on-disk history
+// on the next load. Per-project key so projects don't hide each other's rows.
+function hiddenIdsKey(projectId: string): string {
+  return `hf-studio-hidden-renders:${projectId}`;
+}
+
+function readHiddenIds(projectId: string): Set<string> {
+  try {
+    const raw = window.localStorage.getItem(hiddenIdsKey(projectId));
+    const parsed: unknown = raw ? JSON.parse(raw) : [];
+    return new Set(Array.isArray(parsed) ? parsed.filter((v) => typeof v === "string") : []);
+  } catch {
+    return new Set();
+  }
+}
+
+function writeHiddenIds(projectId: string, ids: Set<string>): void {
+  try {
+    // Cap the list so it doesn't grow unbounded across months of renders.
+    window.localStorage.setItem(hiddenIdsKey(projectId), JSON.stringify([...ids].slice(-200)));
+  } catch {
+    /* localStorage may be unavailable or full */
+  }
+}
+
 export function useRenderQueue(projectId: string | null) {
   const [jobs, setJobs] = useState<RenderJob[]>([]);
+  // History fetch failure — distinguished from "no renders yet" so the panel
+  // never shows a false empty state.
+  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);
   const eventSourceRef = useRef<EventSource | null>(null);
   const activeJobRef = useRef<string | null>(null);
 
+  const closeActiveEventSource = useCallback((jobId?: string) => {
+    if (jobId && activeJobRef.current !== jobId) return;
+    eventSourceRef.current?.close();
+    eventSourceRef.current = null;
+    activeJobRef.current = null;
+  }, []);
+
   // Load completed renders from the server
   const loadRenders = useCallback(async () => {
     if (!projectId) return;
     try {
       const res = await fetch(`/api/projects/${projectId}/renders`);
-      if (!res.ok) return;
+      if (!res.ok) {
+        setLoadError(`Couldn't load render history (server error ${res.status}).`);
+        return;
+      }
       const data = await res.json();
+      setLoadError(null);
       if (Array.isArray(data.renders)) {
+        const hidden = readHiddenIds(projectId);
         setJobs((prev) => {
           const existing = new Set(prev.map((j) => j.id));
           const fromServer: RenderJob[] = data.renders
-            .filter((r: { id: string }) => !existing.has(r.id))
+            .filter((r: { id: string }) => !existing.has(r.id) && !hidden.has(r.id))
             .map(
               (r: {
                 id: string;
@@ -74,7 +117,7 @@ export function useRenderQueue(projectId: string | null) {
         });
       }
     } catch {
-      // ignore
+      setLoadError("Couldn't load render history. Is the studio server running?");
     }
   }, [projectId]);
 
@@ -175,6 +218,8 @@ export function useRenderQueue(projectId: string | null) {
       es.addEventListener("progress", (event) => {
         try {
           const data = JSON.parse(event.data);
+          const terminal =
+            data.status === "complete" || data.status === "failed" || data.status === "cancelled";
           setJobs((prev) =>
             prev.map((j) =>
               j.id === jobId
@@ -182,21 +227,15 @@ export function useRenderQueue(projectId: string | null) {
                     ...j,
                     progress: data.progress ?? j.progress,
                     stage: data.stage ?? data.message ?? j.stage,
-                    status:
-                      data.status === "complete"
-                        ? "complete"
-                        : data.status === "failed"
-                          ? "failed"
-                          : j.status,
+                    status: terminal ? (data.status as RenderJob["status"]) : j.status,
                     durationMs: data.status === "complete" ? Date.now() - startTime : undefined,
                     error: data.error ?? j.error,
                   }
                 : j,
             ),
           );
-          if (data.status === "complete" || data.status === "failed") {
-            es.close();
-            activeJobRef.current = null;
+          if (terminal) {
+            closeActiveEventSource(jobId);
           }
         } catch {
           // ignore parse errors
@@ -221,21 +260,78 @@ export function useRenderQueue(projectId: string | null) {
 
       return jobId;
     },
-    [projectId],
+    [projectId, closeActiveEventSource],
   );
 
-  const deleteRender = useCallback(async (jobId: string) => {
-    try {
-      await fetch(`/api/render/${jobId}`, { method: "DELETE" });
-    } catch {
-      // ignore
-    }
-    setJobs((prev) => prev.filter((j) => j.id !== jobId));
-  }, []);
+  // Cancel an in-flight render. The job row stays (as "cancelled") so the
+  // user sees the outcome; the SSE stream is closed either way.
+  const cancelRender = useCallback(
+    async (jobId: string) => {
+      setActionError(null);
+      closeActiveEventSource(jobId);
+      setJobs((prev) =>
+        prev.map((j) =>
+          j.id === jobId && j.status === "rendering" ? { ...j, status: "cancelled" } : j,
+        ),
+      );
+      try {
+        const res = await fetch(`/api/render/${jobId}/cancel`, { method: "POST" });
+        if (!res.ok && res.status !== 404) {
+          setActionError("Couldn't cancel on the server — the render may still be running.");
+          return;
+        }
+        // Reconcile with the status the route reports: if the render actually
+        // finished (or failed) before the cancel landed, don't leave the row
+        // stuck on the optimistic "cancelled" — reload to pick up the real
+        // outcome (and the finished file's metadata).
+        if (res.ok) {
+          const body = (await res.json().catch(() => null)) as { status?: string } | null;
+          if (body?.status && body.status !== "cancelled") {
+            void loadRenders();
+          }
+        }
+      } catch {
+        setActionError("Couldn't reach the server to cancel — the render may still be running.");
+      }
+    },
+    [closeActiveEventSource, loadRenders],
+  );
 
+  const deleteRender = useCallback(
+    async (jobId: string) => {
+      setActionError(null);
+      closeActiveEventSource(jobId);
+      try {
+        const res = await fetch(`/api/render/${jobId}`, { method: "DELETE" });
+        if (!res.ok) {
+          setActionError("Couldn't delete the render — it's still on disk.");
+          return;
+        }
+      } catch {
+        setActionError("Couldn't reach the server to delete the render.");
+        return;
+      }
+      setJobs((prev) => prev.filter((j) => j.id !== jobId));
+    },
+    [closeActiveEventSource],
+  );
+
+  // Hide finished rows from the list (view-only — files stay on disk and can
+  // be recovered from the renders/ directory). Remembered per project so the
+  // rows don't resurrect from history on reload.
   const clearCompleted = useCallback(() => {
-    setJobs((prev) => prev.filter((j) => j.status === "rendering"));
-  }, []);
+    setJobs((prev) => {
+      const finished = prev.filter((j) => j.status !== "rendering");
+      if (projectId && finished.length > 0) {
+        const hidden = readHiddenIds(projectId);
+        for (const j of finished) hidden.add(j.id);
+        writeHiddenIds(projectId, hidden);
+      }
+      return prev.filter((j) => j.status === "rendering");
+    });
+  }, [projectId]);
+
+  const dismissActionError = useCallback(() => setActionError(null), []);
 
   // Clean up EventSource on unmount or projectId change
   useEffect(() => {
@@ -250,10 +346,26 @@ export function useRenderQueue(projectId: string | null) {
     () => ({
       jobs,
       isRendering,
+      loadError,
+      actionError,
+      dismissActionError,
+      reloadRenders: loadRenders,
       deleteRender,
+      cancelRender,
       clearCompleted,
       startRender: startRender as (options: unknown) => Promise<void>,
     }),
-    [jobs, isRendering, deleteRender, clearCompleted, startRender],
+    [
+      jobs,
+      isRendering,
+      loadError,
+      actionError,
+      dismissActionError,
+      loadRenders,
+      deleteRender,
+      cancelRender,
+      clearCompleted,
+      startRender,
+    ],
   );
 }

package/src/components/sidebar/AssetsTab.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { filterByUsage, countUsage, deriveUsedPaths } from "./AssetsTab";
+import { globalAssetRows } from "./GlobalAssetsView";
+
+const assets = ["bgm.mp3", "logo.png", "orphan.wav"];
+const used = new Set(["bgm.mp3", "logo.png"]);
+
+describe("filterByUsage", () => {
+  it("returns everything for 'all'", () => {
+    expect(filterByUsage(assets, used, "all")).toEqual(assets);
+  });
+
+  it("keeps only referenced assets for 'used'", () => {
+    expect(filterByUsage(assets, used, "used")).toEqual(["bgm.mp3", "logo.png"]);
+  });
+
+  it("keeps only unreferenced assets for 'unused'", () => {
+    expect(filterByUsage(assets, used, "unused")).toEqual(["orphan.wav"]);
+  });
+
+  it("treats everything as unused when nothing is referenced", () => {
+    expect(filterByUsage(assets, new Set(), "used")).toEqual([]);
+    expect(filterByUsage(assets, new Set(), "unused")).toEqual(assets);
+  });
+});
+
+describe("deriveUsedPaths", () => {
+  it("matches the asset-list format across every src shape", () => {
+    const used = deriveUsedPaths([
+      { src: "assets/logo.png" }, // raw authored relative path
+      { src: "/api/projects/demo/preview/assets/bgm.mp3" }, // served form
+      { src: "./assets/icon.svg" }, // ./-prefixed
+      { src: "assets/clip.mp4?v=2" }, // cache-busted
+      {}, // no src — skipped
+    ]);
+    expect(used.has("assets/logo.png")).toBe(true);
+    expect(used.has("assets/bgm.mp3")).toBe(true);
+    expect(used.has("assets/icon.svg")).toBe(true);
+    expect(used.has("assets/clip.mp4")).toBe(true);
+    expect(used.size).toBe(4);
+  });
+
+  it("an authored relative src lines up with the asset entry (the live bug class)", () => {
+    const used = deriveUsedPaths([{ src: "assets/logo.png" }]);
+    // asset-list entries are project-relative (see serveUrl = preview/${asset})
+    expect(filterByUsage(["assets/logo.png", "assets/orphan.wav"], used, "used")).toEqual([
+      "assets/logo.png",
+    ]);
+  });
+});
+
+describe("countUsage", () => {
+  it("counts used vs unused", () => {
+    expect(countUsage(assets, used)).toEqual({ used: 2, unused: 1 });
+  });
+
+  it("is all-unused with an empty used set", () => {
+    expect(countUsage(assets, new Set())).toEqual({ used: 0, unused: 3 });
+  });
+});
+
+describe("globalAssetRows", () => {
+  const recs = [
+    { id: "bgm_001", type: "bgm", description: "calm ambient" },
+    { id: "img_001", type: "image", entity: "Acme" },
+    { sha: "abc", type: "sfx" },
+  ];
+
+  it("maps records to display rows with a sensible label", () => {
+    const rows = globalAssetRows(recs);
+    expect(rows).toEqual([
+      { id: "bgm_001", type: "bgm", label: "calm ambient" },
+      { id: "img_001", type: "image", label: "Acme" },
+      { id: "abc", type: "sfx", label: "abc" },
+    ]);
+  });
+
+  it("filters by id / type / description / entity, case-insensitively", () => {
+    expect(globalAssetRows(recs, "ACME").map((r) => r.id)).toEqual(["img_001"]);
+    expect(globalAssetRows(recs, "bgm").map((r) => r.id)).toEqual(["bgm_001"]);
+    expect(globalAssetRows(recs, "ambient").map((r) => r.id)).toEqual(["bgm_001"]);
+  });
+
+  it("empty query returns all", () => {
+    expect(globalAssetRows(recs, "  ").length).toBe(3);
+  });
+});

package/src/components/sidebar/AssetsTab.tsx

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 import { memo, useState, useCallback, useRef, useMemo, useEffect } from "react";
 import { VideoFrameThumbnail } from "../ui/VideoFrameThumbnail";
 import { MEDIA_EXT, IMAGE_EXT, VIDEO_EXT, FONT_EXT } from "../../utils/mediaTypes";
@@ -14,6 +15,7 @@ import {
   FILTER_ORDER,
 } from "./assetHelpers";
 import { AudioRow } from "./AudioRow";
+import { GlobalAssetsView } from "./GlobalAssetsView";
 
 interface AssetsTabProps {
   projectId: string;
@@ -172,6 +174,51 @@ function ImageCard({
   );
 }
 
+export type UsageFilter = "all" | "used" | "unused";
+
+/** Filter assets by whether the composition references them. Pure — unit-tested. */
+export function filterByUsage(
+  assets: string[],
+  usedPaths: Set<string>,
+  usageFilter: UsageFilter,
+): string[] {
+  if (usageFilter === "used") return assets.filter((a) => usedPaths.has(a));
+  if (usageFilter === "unused") return assets.filter((a) => !usedPaths.has(a));
+  return assets;
+}
+
+/** Count used vs unused over a media set. Pure — unit-tested. */
+export function countUsage(
+  assets: string[],
+  usedPaths: Set<string>,
+): { used: number; unused: number } {
+  let used = 0;
+  for (const a of assets) if (usedPaths.has(a)) used++;
+  return { used, unused: assets.length - used };
+}
+
+/**
+ * Project-relative asset paths referenced by composition elements — the set the
+ * "in use" badge, used-first sort, and usage filter all key on. Element src is
+ * the raw authored value (timelineElementHelpers sets entry.src =
+ * getAttribute("src")), so it can be a relative path ("assets/x.png"), a
+ * "./"-prefixed path, the served "/api/projects/<id>/preview/assets/x.png" form,
+ * or carry a ?query — normalize all of them to the bare project path so they
+ * match the asset-list entries. Pure — unit-tested.
+ */
+export function deriveUsedPaths(elements: Array<{ src?: string }>): Set<string> {
+  const paths = new Set<string>();
+  for (const el of elements) {
+    if (!el.src) continue;
+    const s = el.src
+      .replace(/^\/api\/projects\/[^/]+\/preview\//, "") // strip the dev serve prefix
+      .replace(/^\.?\//, "") // strip leading ./ or /
+      .split(/[?#]/)[0]; // drop query / hash
+    if (s) paths.add(s);
+  }
+  return paths;
+}
+
 export const AssetsTab = memo(function AssetsTab({
   projectId,
   assets,
@@ -183,7 +230,11 @@ export const AssetsTab = memo(function AssetsTab({
   const [dragOver, setDragOver] = useState(false);
   const [copiedPath, setCopiedPath] = useState<string | null>(null);
   const [activeFilter, setActiveFilter] = useState<MediaCategory | "all">("all");
+  const [usageFilter, setUsageFilter] = useState<"all" | "used" | "unused">("all");
   const [searchQuery, setSearchQuery] = useState("");
+  // Cross-project view: the global media-use cache (~/.media). The view itself
+  // (GlobalAssetsView) owns its fetch — AssetsTab only tracks which scope is active.
+  const [viewMode, setViewMode] = useState<"local" | "global">("local");
   const [manifest, setManifest] = useState<
     Map<string, { description?: string; duration?: number; width?: number; height?: number }>
   >(new Map());
@@ -246,19 +297,11 @@ export const AssetsTab = memo(function AssetsTab({
   }, []);
 
   const elements = usePlayerStore((s) => s.elements);
-  const usedPaths = useMemo(() => {
-    const paths = new Set<string>();
-    for (const el of elements) {
-      if (el.src) {
-        const src = el.src.replace(/^\/api\/projects\/[^/]+\/preview\//, "");
-        paths.add(src);
-      }
-    }
-    return paths;
-  }, [elements]);
+  const usedPaths = useMemo(() => deriveUsedPaths(elements), [elements]);
 
   const mediaAssets = useMemo(() => {
-    const all = assets.filter((a) => MEDIA_EXT.test(a) || FONT_EXT.test(a));
+    const media = assets.filter((a) => MEDIA_EXT.test(a) || FONT_EXT.test(a));
+    const all = filterByUsage(media, usedPaths, usageFilter);
     if (!searchQuery) return all;
     const q = searchQuery.toLowerCase();
     return all.filter((a) => {
@@ -266,7 +309,7 @@ export const AssetsTab = memo(function AssetsTab({
       const rec = manifest.get(a);
       return rec?.description?.toLowerCase().includes(q);
     });
-  }, [assets, searchQuery, manifest]);
+  }, [assets, searchQuery, manifest, usageFilter, usedPaths]);
 
   const categorized = useMemo(() => {
     const groups: Record<MediaCategory, string[]> = { audio: [], images: [], video: [], fonts: [] };
@@ -291,6 +334,17 @@ export const AssetsTab = memo(function AssetsTab({
     return c;
   }, [mediaAssets, categorized]);
 
+  // Usage counts over the full media set (independent of the active usage filter,
+  // so the chips don't show their own filtered totals).
+  const usageCounts = useMemo(
+    () =>
+      countUsage(
+        assets.filter((a) => MEDIA_EXT.test(a) || FONT_EXT.test(a)),
+        usedPaths,
+      ),
+    [assets, usedPaths],
+  );
+
   const visibleCategories =
     activeFilter === "all"
       ? FILTER_ORDER.filter((c) => categorized[c].length > 0)
@@ -308,6 +362,22 @@ export const AssetsTab = memo(function AssetsTab({
     >
       {/* Header — matches design panel Section pattern */}
       <div className="px-4 pt-2.5 pb-1.5 flex-shrink-0">
+        {/* Scope toggle — this project's assets vs the global media-use cache */}
+        <div className="flex gap-1 mb-2.5 p-0.5 rounded-md bg-panel-input">
+          {(["local", "global"] as const).map((m) => (
+            <button
+              key={m}
+              onClick={() => setViewMode(m)}
+              className={`flex-1 px-2 py-1 text-[11px] font-medium rounded transition-colors ${
+                viewMode === m
+                  ? "bg-panel-accent/15 text-panel-accent"
+                  : "text-panel-text-3 hover:text-panel-text-1"
+              }`}
+            >
+              {m === "local" ? "This project" : "All projects"}
+            </button>
+          ))}
+        </div>
         {/* Import */}
         {onImport && (
           <>
@@ -377,8 +447,8 @@ export const AssetsTab = memo(function AssetsTab({
           </div>
         )}
 
-        {/* Filter chips — panel-input style */}
-        {mediaAssets.length > 0 && (
+        {/* Filter chips — panel-input style (local view only) */}
+        {viewMode === "local" && mediaAssets.length > 0 && (
           <div className="flex gap-1.5 flex-wrap">
             <button
               onClick={() => setActiveFilter("all")}
@@ -405,13 +475,41 @@ export const AssetsTab = memo(function AssetsTab({
                 </button>
               ) : null,
             )}
+            {/* Usage filter — show only assets the composition references, or only the unused ones */}
+            {usageCounts.used > 0 && usageCounts.unused > 0 && (
+              <>
+                <span className="w-px self-stretch bg-panel-input mx-0.5" aria-hidden="true" />
+                <button
+                  onClick={() => setUsageFilter(usageFilter === "used" ? "all" : "used")}
+                  className={`px-2.5 py-1 text-[11px] font-medium rounded-md transition-colors ${
+                    usageFilter === "used"
+                      ? "bg-panel-accent/15 text-panel-accent"
+                      : "bg-panel-input text-panel-text-3 hover:text-panel-text-1"
+                  }`}
+                >
+                  In use {usageCounts.used}
+                </button>
+                <button
+                  onClick={() => setUsageFilter(usageFilter === "unused" ? "all" : "unused")}
+                  className={`px-2.5 py-1 text-[11px] font-medium rounded-md transition-colors ${
+                    usageFilter === "unused"
+                      ? "bg-panel-accent/15 text-panel-accent"
+                      : "bg-panel-input text-panel-text-3 hover:text-panel-text-1"
+                  }`}
+                >
+                  Unused {usageCounts.unused}
+                </button>
+              </>
+            )}
           </div>
         )}
       </div>
 
       {/* Asset list */}
       <div className="flex-1 overflow-y-auto mt-1">
-        {mediaAssets.length === 0 ? (
+        {viewMode === "global" ? (
+          <GlobalAssetsView searchQuery={searchQuery} />
+        ) : mediaAssets.length === 0 ? (
           <div className="flex flex-col items-center justify-center h-full px-4 gap-2">
             <svg
               width="24"

package/src/components/sidebar/BlocksTab.tsx

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 import { memo, useState, useCallback, useRef, useEffect } from "react";
 import { createPortal } from "react-dom";
 import { useBlockCatalog } from "../../hooks/useBlockCatalog";
@@ -234,7 +235,7 @@ function buildAgentPrompt(
     captions: [
       `Using /hyperframes, add the "${title}" caption style (registry: ${name}) to my composition.`,
       `${description}`,
-      `Transcribe the audio with /hyperframes-media, then wire the transcript into this caption component. Match the font colors and animation timing to my composition's design tokens. Place it as an overlay above the main content with the highest z-index.`,
+      `Transcribe the audio with /media-use, then wire the transcript into this caption component. Match the font colors and animation timing to my composition's design tokens. Place it as an overlay above the main content with the highest z-index.`,
     ].join("\n\n"),
     vfx: [
       `Using /hyperframes, add the "${title}" VFX (registry: ${name}) as a full-screen overlay on my composition.`,

package/src/components/sidebar/GlobalAssetsView.tsx

@@ -0,0 +1,91 @@
+import { useEffect, useMemo, useState } from "react";
+
+// Cross-project asset view — the global media-use cache (~/.media), fetched from
+// /api/assets/global. Self-contained (owns its fetch + state) so AssetsTab stays
+// focused on the local view.
+
+export interface GlobalAssetRecord {
+  id?: string;
+  type?: string;
+  description?: string;
+  entity?: string;
+  sha?: string;
+}
+
+export interface GlobalAssetRow {
+  id: string;
+  type: string;
+  label: string;
+}
+
+/**
+ * Normalize global records into display rows, filtered by an optional query
+ * (id / type / description / entity). Pure — unit-tested.
+ */
+export function globalAssetRows(records: GlobalAssetRecord[], query = ""): GlobalAssetRow[] {
+  const q = query.trim().toLowerCase();
+  return records
+    .filter((r) =>
+      !q
+        ? true
+        : [r.id, r.type, r.description, r.entity].some(
+            (f) => f && String(f).toLowerCase().includes(q),
+          ),
+    )
+    .map((r) => ({
+      id: r.id ?? r.sha ?? "asset",
+      type: r.type ?? "asset",
+      label: r.description || r.entity || r.id || r.sha || "asset",
+    }));
+}
+
+export function GlobalAssetsView({ searchQuery }: { searchQuery: string }) {
+  const [records, setRecords] = useState<GlobalAssetRecord[] | null>(null);
+  useEffect(() => {
+    let cancelled = false;
+    fetch("/api/assets/global")
+      .then((r) => (r.ok ? r.json() : { assets: [] }))
+      .then((d) => {
+        if (!cancelled) setRecords(Array.isArray(d.assets) ? d.assets : []);
+      })
+      .catch(() => {
+        if (!cancelled) setRecords([]);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const rows = useMemo(() => globalAssetRows(records ?? [], searchQuery), [records, searchQuery]);
+
+  if (records === null) {
+    return <p className="px-4 py-3 text-[11px] text-panel-text-5">Loading global assets…</p>;
+  }
+  if (rows.length === 0) {
+    return (
+      <p className="px-4 py-3 text-[11px] text-panel-text-5">
+        No assets in the global cache yet. Resolved media is promoted to <code>~/.media</code> and
+        becomes reusable across projects.
+      </p>
+    );
+  }
+  return (
+    <div>
+      <div className="px-4 py-2 border-t border-panel-border text-[11px] text-panel-text-5">
+        {rows.length} reusable across all projects
+      </div>
+      {rows.map((row) => (
+        <div
+          key={row.id}
+          className="px-4 py-1.5 flex items-center gap-2.5 border-l-2 border-transparent hover:bg-neutral-800/50"
+          title={`${row.id} · ${row.type}`}
+        >
+          <span className="text-[9px] font-medium text-neutral-600 uppercase w-10 flex-shrink-0">
+            {row.type}
+          </span>
+          <span className="text-xs text-panel-text-1 truncate">{row.label}</span>
+        </div>
+      ))}
+    </div>
+  );
+}