@hyperframes/studio 0.5.0-alpha.1 → 0.5.0-alpha.10

package/src/components/editor/domEditing.test.ts

@@ -108,6 +108,61 @@ describe("resolveDomEditCapabilities", () => {
     });
   });
 
+  it("treats identity transforms left behind by animation libraries as movable", () => {
+    expect(
+      resolveDomEditCapabilities({
+        selector: "#card",
+        inlineStyles: {
+          left: "120px",
+          top: "80px",
+          width: "240px",
+          height: "140px",
+        },
+        computedStyles: {
+          position: "absolute",
+          left: "120px",
+          top: "80px",
+          width: "240px",
+          height: "140px",
+          transform: "matrix(1, 0, 0, 1, 0, 0)",
+        },
+        isCompositionHost: false,
+        isMasterView: false,
+      }),
+    ).toMatchObject({
+      canMove: true,
+      canResize: true,
+      canDetachFromLayout: false,
+    });
+  });
+
+  it("treats identity matrix3d transforms as movable", () => {
+    expect(
+      resolveDomEditCapabilities({
+        selector: "#card",
+        inlineStyles: {
+          left: "120px",
+          top: "80px",
+          width: "240px",
+          height: "140px",
+        },
+        computedStyles: {
+          position: "absolute",
+          left: "120px",
+          top: "80px",
+          width: "240px",
+          height: "140px",
+          transform: "matrix3d(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1)",
+        },
+        isCompositionHost: false,
+        isMasterView: false,
+      }),
+    ).toMatchObject({
+      canMove: true,
+      canResize: true,
+    });
+  });
+
   it("allows imported absolute media to resize from computed px geometry", () => {
     expect(
       resolveDomEditCapabilities({
@@ -228,6 +283,24 @@ describe("resolveDomEditSelection", () => {
     expect(selection?.selector).toBe("#card");
   });
 
+  it("can resolve the exact child when clip-ancestor preference is disabled", () => {
+    const document = createDocument(`
+      <section id="card" class="clip" style="left: 10px; top: 20px; width: 200px; height: 100px; position: absolute;">
+        <p id="copy">Hello</p>
+      </section>
+    `);
+
+    const child = document.getElementById("copy") as HTMLElement;
+    const selection = resolveDomEditSelection(child, {
+      activeCompositionPath: null,
+      isMasterView: false,
+      preferClipAncestor: false,
+    });
+
+    expect(selection?.id).toBe("copy");
+    expect(selection?.selector).toBe("#copy");
+  });
+
   it("collects simple child text blocks as separate editable fields", () => {
     const document = createDocument(`
       <section id="card" class="clip" style="left: 10px; top: 20px; width: 200px; height: 100px; position: absolute;">
@@ -394,6 +467,43 @@ describe("patch builders and prompt builder", () => {
     expect(prompt).toContain("Do not modify other elements' data-* attributes or positioning.");
   });
 
+  it("uses an absolute source path in copied agent prompts when provided", () => {
+    const selection = {
+      element: {} as HTMLElement,
+      id: "editable-card",
+      selector: "#editable-card",
+      selectorIndex: undefined,
+      sourceFile: "index.html",
+      compositionPath: "index.html",
+      compositionSrc: undefined,
+      isCompositionHost: false,
+      label: "Drag me first",
+      tagName: "div",
+      boundingBox: { x: 108, y: 112, width: 380, height: 196 },
+      textContent: "Drag me first",
+      dataAttributes: {},
+      inlineStyles: {},
+      computedStyles: {},
+      textFields: [],
+      capabilities: {
+        canSelect: true,
+        canEditStyles: true,
+        canMove: true,
+        canResize: true,
+        canDetachFromLayout: false,
+      },
+    } satisfies DomEditSelection;
+
+    const prompt = buildElementAgentPrompt({
+      selection,
+      currentTime: 1.25,
+      sourceFilePath: "/tmp/hf-studio-project/index.html",
+    });
+
+    expect(prompt).toContain("Source file: /tmp/hf-studio-project/index.html");
+    expect(prompt).not.toContain("Source file: index.html");
+  });
+
   it("serializes child text fields back into HTML", () => {
     expect(
       serializeDomEditTextFields([

package/src/components/editor/domEditing.ts

@@ -93,6 +93,32 @@ function parsePx(value: string | undefined): number | null {
   return Number.isFinite(parsed) ? parsed : null;
 }
 
+function isIdentityTransform(value: string | undefined): boolean {
+  const transform = (value ?? "none").trim();
+  if (!transform || transform === "none") return true;
+
+  const matrix = transform.match(/^matrix\(([^)]+)\)$/i);
+  if (matrix) {
+    const values = matrix[1].split(",").map((part) => Number.parseFloat(part.trim()));
+    if (values.length !== 6 || values.some((part) => !Number.isFinite(part))) return false;
+    return (
+      Math.abs(values[0] - 1) < 0.0001 &&
+      Math.abs(values[1]) < 0.0001 &&
+      Math.abs(values[2]) < 0.0001 &&
+      Math.abs(values[3] - 1) < 0.0001 &&
+      Math.abs(values[4]) < 0.0001 &&
+      Math.abs(values[5]) < 0.0001
+    );
+  }
+
+  const matrix3d = transform.match(/^matrix3d\(([^)]+)\)$/i);
+  if (!matrix3d) return false;
+  const values = matrix3d[1].split(",").map((part) => Number.parseFloat(part.trim()));
+  if (values.length !== 16 || values.some((part) => !Number.isFinite(part))) return false;
+  const identity = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+  return values.every((part, index) => Math.abs(part - identity[index]) < 0.0001);
+}
+
 function isClipClassName(className: string | undefined): boolean {
   return Boolean(className?.split(/\s+/).includes("clip"));
 }
@@ -426,13 +452,13 @@ export function resolveDomEditCapabilities(args: {
   const top = parsePx(args.inlineStyles.top) ?? parsePx(args.computedStyles.top);
   const width = parsePx(args.inlineStyles.width) ?? parsePx(args.computedStyles.width);
   const height = parsePx(args.inlineStyles.height) ?? parsePx(args.computedStyles.height);
-  const transform = (args.computedStyles.transform ?? "none").trim();
+  const hasTransformDrivenGeometry = !isIdentityTransform(args.computedStyles.transform);
 
   const canMove =
     (position === "absolute" || position === "fixed") &&
     left != null &&
     top != null &&
-    transform === "none";
+    !hasTransformDrivenGeometry;
 
   const canResize = canMove && (width != null || height != null);
   const isBlockishLayer =
@@ -442,7 +468,7 @@ export function resolveDomEditCapabilities(args: {
     isBlockishDisplay(args.computedStyles.display);
   const canDetachFromLayout =
     !canMove &&
-    transform === "none" &&
+    !hasTransformDrivenGeometry &&
     isBlockishLayer &&
     (!isInlineTextTag(args.tagName) || isClipClassName(args.className));
   const reasonIfDisabled = !canMove
@@ -671,12 +697,15 @@ export function buildElementAgentPrompt({
   currentTime,
   tagSnippet,
   userInstruction,
+  sourceFilePath,
 }: {
   selection: DomEditSelection;
   currentTime: number;
   tagSnippet?: string;
   userInstruction?: string;
+  sourceFilePath?: string;
 }): string {
+  const displayedSourceFile = sourceFilePath?.trim() || selection.sourceFile;
   const lines = [
     "## HyperFrames element edit request v1",
     "Schema version: 1",
@@ -685,7 +714,7 @@ export function buildElementAgentPrompt({
     "",
     `Composition: ${selection.compositionPath}`,
     `Playback time: ${formatTime(currentTime)}`,
-    `Source file: ${selection.sourceFile}`,
+    `Source file: ${displayedSourceFile}`,
     `DOM id: ${selection.id ?? "(none)"}`,
     `Selector: ${selection.selector ?? "(none)"}`,
     `Selector index: ${selection.selectorIndex ?? 0}`,

package/src/components/nle/NLEPreview.tsx

@@ -67,7 +67,11 @@ export const NLEPreview = memo(function NLEPreview({
 
   return (
     <div className="flex flex-col h-full min-h-0">
-      <div className="relative flex-1 flex items-center justify-center p-2 overflow-hidden min-h-0">
+      <div
+        className="relative flex-1 flex items-center justify-center p-2 overflow-hidden min-h-0 outline-none focus:ring-1 focus:ring-studio-accent/40"
+        tabIndex={0}
+        aria-label="Composition preview"
+      >
         {retiringKey && (
           <Player
             key={retiringKey}

package/src/components/sidebar/AssetsTab.tsx

@@ -2,6 +2,7 @@ import { memo, useState, useCallback, useRef } from "react";
 import { VideoFrameThumbnail } from "../ui/VideoFrameThumbnail";
 import { MEDIA_EXT, IMAGE_EXT, VIDEO_EXT, AUDIO_EXT } from "../../utils/mediaTypes";
 import { TIMELINE_ASSET_MIME } from "../../utils/timelineAssetDrop";
+import { copyTextToClipboard } from "../../utils/clipboard";
 
 interface AssetsTabProps {
   projectId: string;
@@ -298,12 +299,10 @@ export const AssetsTab = memo(function AssetsTab({
   );
 
   const handleCopyPath = useCallback(async (path: string) => {
-    try {
-      await navigator.clipboard.writeText(path);
+    const copied = await copyTextToClipboard(path);
+    if (copied) {
       setCopiedPath(path);
       setTimeout(() => setCopiedPath(null), 1500);
-    } catch {
-      // ignore
     }
   }, []);
 

package/src/player/components/AudioWaveform.tsx

@@ -2,6 +2,7 @@ import { memo, useRef, useState, useCallback, useEffect } from "react";
 
 interface AudioWaveformProps {
   audioUrl: string;
+  waveformUrl?: string;
   label: string;
   labelColor: string;
 }
@@ -49,6 +50,7 @@ function fakePeaks(url: string, count: number): number[] {
 
 // Module-level cache so decoded audio persists across re-renders and re-mounts
 const peaksCache = new Map<string, number[]>();
+const decodeInFlight = new Map<string, Promise<number[]>>();
 
 /**
  * Audio waveform rendered from real PCM data via Web Audio API.
@@ -57,43 +59,56 @@ const peaksCache = new Map<string, number[]>();
  */
 export const AudioWaveform = memo(function AudioWaveform({
   audioUrl,
+  waveformUrl,
   label,
   labelColor,
 }: AudioWaveformProps) {
   const containerRef = useRef<HTMLDivElement | null>(null);
   const barsRef = useRef<HTMLDivElement | null>(null);
   const roRef = useRef<ResizeObserver | null>(null);
-  const [peaks, setPeaks] = useState<number[] | null>(peaksCache.get(audioUrl) ?? null);
+  const cacheKey = waveformUrl ?? audioUrl;
+  const [peaks, setPeaks] = useState<number[] | null>(peaksCache.get(cacheKey) ?? null);
 
-  // Fetch + decode audio once
   useEffect(() => {
-    if (peaks || !audioUrl) return;
-
-    const ctrl = new AbortController();
-    fetch(audioUrl, { signal: ctrl.signal })
-      .then((r) => r.arrayBuffer())
-      .then((buf) => {
-        const ctx = new AudioContext();
-        return ctx.decodeAudioData(buf).finally(() => ctx.close());
-      })
-      .then((decoded) => {
-        if (ctrl.signal.aborted) return;
-        const channel = decoded.getChannelData(0);
-        // Extract enough peaks for wide clips (up to 4000 bars)
-        const p = extractPeaks(channel, 4000);
-        peaksCache.set(audioUrl, p);
-        setPeaks(p);
-      })
-      .catch(() => {
-        if (ctrl.signal.aborted) return;
-        // Fallback to fake waveform
-        const p = fakePeaks(audioUrl, 4000);
-        peaksCache.set(audioUrl, p);
-        setPeaks(p);
-      });
-
-    return () => ctrl.abort();
-  }, [audioUrl, peaks]);
+    if (peaks || !cacheKey) return;
+
+    let cancelled = false;
+
+    let promise = decodeInFlight.get(cacheKey);
+    if (!promise) {
+      promise = (
+        waveformUrl
+          ? fetch(waveformUrl)
+              .then((r) => r.json())
+              .then((d: { peaks?: number[] }) => {
+                if (!Array.isArray(d.peaks)) throw new Error("bad response");
+                return d.peaks;
+              })
+          : fetch(audioUrl)
+              .then((r) => r.arrayBuffer())
+              .then((buf) => {
+                const ctx = new AudioContext();
+                return ctx.decodeAudioData(buf).finally(() => ctx.close());
+              })
+              .then((decoded) => extractPeaks(decoded.getChannelData(0), 4000))
+      )
+        .catch(() => fakePeaks(cacheKey, 4000))
+        .then((p) => {
+          peaksCache.set(cacheKey, p);
+          return p;
+        })
+        .finally(() => decodeInFlight.delete(cacheKey));
+
+      decodeInFlight.set(cacheKey, promise);
+    }
+
+    promise.then((p) => {
+      if (!cancelled) setPeaks(p);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [audioUrl, waveformUrl, cacheKey, peaks]);
 
   // Draw bars into the container using innerHTML (fast, zoom-resilient)
   const draw = useCallback(() => {

package/src/player/components/CompositionThumbnail.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { buildCompositionThumbnailUrl } from "./CompositionThumbnail";
+
+describe("buildCompositionThumbnailUrl", () => {
+  it("includes selector and occurrence index for precise element thumbnails", () => {
+    expect(
+      buildCompositionThumbnailUrl({
+        previewUrl: "/api/projects/demo/preview",
+        seekTime: 1,
+        duration: 2,
+        selector: ".card",
+        selectorIndex: 2,
+        origin: "http://localhost:3000",
+      }),
+    ).toBe(
+      "http://localhost:3000/api/projects/demo/thumbnail/index.html?t=2.00&v=v2&selector=.card&selectorIndex=2",
+    );
+  });
+});

package/src/player/components/CompositionThumbnail.tsx

@@ -7,6 +7,7 @@ interface CompositionThumbnailProps {
   labelColor: string;
   accentColor?: string;
   selector?: string;
+  selectorIndex?: number;
   seekTime?: number;
   duration?: number;
   width?: number;
@@ -16,12 +17,44 @@ interface CompositionThumbnailProps {
 const CLIP_HEIGHT = 66;
 const THUMBNAIL_URL_VERSION = "v2";
 
+export function buildCompositionThumbnailUrl({
+  previewUrl,
+  seekTime = 2,
+  duration = 5,
+  selector,
+  selectorIndex,
+  origin,
+}: {
+  previewUrl: string;
+  seekTime?: number;
+  duration?: number;
+  selector?: string;
+  selectorIndex?: number;
+  origin: string;
+}): string {
+  const thumbnailBase = previewUrl
+    .replace("/preview/comp/", "/thumbnail/")
+    .replace(/\/preview$/, "/thumbnail/index.html");
+  const midTime = seekTime + duration / 2;
+  const thumbnailUrl = new URL(thumbnailBase, origin);
+  thumbnailUrl.searchParams.set("t", midTime.toFixed(2));
+  thumbnailUrl.searchParams.set("v", THUMBNAIL_URL_VERSION);
+  if (selector) {
+    thumbnailUrl.searchParams.set("selector", selector);
+    if (selectorIndex != null && selectorIndex > 0) {
+      thumbnailUrl.searchParams.set("selectorIndex", String(selectorIndex));
+    }
+  }
+  return thumbnailUrl.toString();
+}
+
 export const CompositionThumbnail = memo(function CompositionThumbnail({
   previewUrl,
   label,
   labelColor,
   accentColor = "#6B7280",
   selector,
+  selectorIndex,
   seekTime = 2,
   duration = 5,
 }: CompositionThumbnailProps) {
@@ -48,15 +81,14 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
     roRef.current?.disconnect();
   });
 
-  const thumbnailBase = previewUrl
-    .replace("/preview/comp/", "/thumbnail/")
-    .replace(/\/preview$/, "/thumbnail/index.html");
-  const midTime = seekTime + duration / 2;
-  const thumbnailUrl = new URL(thumbnailBase, window.location.origin);
-  thumbnailUrl.searchParams.set("t", midTime.toFixed(2));
-  thumbnailUrl.searchParams.set("v", THUMBNAIL_URL_VERSION);
-  if (selector) thumbnailUrl.searchParams.set("selector", selector);
-  const url = thumbnailUrl.toString();
+  const url = buildCompositionThumbnailUrl({
+    previewUrl,
+    seekTime,
+    duration,
+    selector,
+    selectorIndex,
+    origin: window.location.origin,
+  });
   const frameW = Math.max(48, Math.round(CLIP_HEIGHT * aspect));
   const frameCount = containerWidth > 0 ? Math.max(1, Math.ceil(containerWidth / frameW)) : 1;
 
@@ -66,7 +98,7 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
         src={url}
         alt=""
         draggable={false}
-        loading="lazy"
+        loading="eager"
         onLoad={(e) => {
           const img = e.currentTarget;
           if (img.naturalWidth > 0 && img.naturalHeight > 0) {

package/src/player/components/EditModal.tsx

@@ -3,6 +3,7 @@ import { useMountEffect } from "../../hooks/useMountEffect";
 import { usePlayerStore } from "../store/playerStore";
 import { formatTime } from "../lib/time";
 import { buildPromptCopyText, buildTimelineAgentPrompt } from "./timelineEditing";
+import { copyTextToClipboard } from "../../utils/clipboard";
 
 interface EditPopoverProps {
   rangeStart: number;
@@ -62,16 +63,8 @@ export function EditPopover({ rangeStart, rangeEnd, anchorX, anchorY, onClose }:
   }, [start, end, elementsInRange, prompt]);
 
   const handleCopy = useCallback(async () => {
-    try {
-      await navigator.clipboard.writeText(buildClipboardText());
-    } catch {
-      const ta = document.createElement("textarea");
-      ta.value = buildClipboardText();
-      document.body.appendChild(ta);
-      ta.select();
-      document.execCommand("copy");
-      document.body.removeChild(ta);
-    }
+    const copied = await copyTextToClipboard(buildClipboardText());
+    if (!copied) return;
     setCopiedAgentPrompt(true);
     setTimeout(() => {
       setCopiedAgentPrompt(false);
@@ -82,16 +75,8 @@ export function EditPopover({ rangeStart, rangeEnd, anchorX, anchorY, onClose }:
   const handleCopyPrompt = useCallback(async () => {
     const promptText = buildPromptCopyText(prompt);
     if (!promptText) return;
-    try {
-      await navigator.clipboard.writeText(promptText);
-    } catch {
-      const ta = document.createElement("textarea");
-      ta.value = promptText;
-      document.body.appendChild(ta);
-      ta.select();
-      document.execCommand("copy");
-      document.body.removeChild(ta);
-    }
+    const copied = await copyTextToClipboard(promptText);
+    if (!copied) return;
     setCopiedPromptOnly(true);
     setTimeout(() => {
       setCopiedPromptOnly(false);