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

package/src/captions/components/CaptionOverlay.tsx

@@ -1,6 +1,7 @@
 import { memo, useState, useCallback, useRef } from "react";
 import { useCaptionStore } from "../store";
 import { useMountEffect } from "../../hooks/useMountEffect";
+import { shouldHandleCaptionNudgeKey } from "../keyboard";
 
 interface CaptionOverlayProps {
   iframeRef: React.RefObject<HTMLIFrameElement | null>;
@@ -329,7 +330,7 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
       const { selectedSegmentIds: sel, model: m } = useCaptionStore.getState();
       if (sel.size === 0 || !m) return;
       const arrow = e.key;
-      if (!["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"].includes(arrow)) return;
+      if (!shouldHandleCaptionNudgeKey(e)) return;
 
       e.preventDefault();
       const step = e.shiftKey ? 10 : 1;

package/src/captions/keyboard.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { shouldHandleCaptionNudgeKey } from "./keyboard";
+
+function mockKeyboardEvent(
+  key: string,
+  overrides: Partial<Pick<KeyboardEvent, "altKey" | "ctrlKey" | "metaKey">> = {},
+): Pick<KeyboardEvent, "altKey" | "ctrlKey" | "metaKey" | "key"> {
+  return {
+    altKey: false,
+    ctrlKey: false,
+    metaKey: false,
+    key,
+    ...overrides,
+  };
+}
+
+describe("shouldHandleCaptionNudgeKey", () => {
+  it("handles plain and Shift-modified arrow keys for caption nudging", () => {
+    expect(shouldHandleCaptionNudgeKey(mockKeyboardEvent("ArrowLeft"))).toBe(true);
+    expect(shouldHandleCaptionNudgeKey(mockKeyboardEvent("ArrowRight"))).toBe(true);
+  });
+
+  it("ignores browser and app shortcut chords", () => {
+    expect(shouldHandleCaptionNudgeKey(mockKeyboardEvent("ArrowLeft", { altKey: true }))).toBe(
+      false,
+    );
+    expect(shouldHandleCaptionNudgeKey(mockKeyboardEvent("ArrowRight", { ctrlKey: true }))).toBe(
+      false,
+    );
+    expect(shouldHandleCaptionNudgeKey(mockKeyboardEvent("ArrowRight", { metaKey: true }))).toBe(
+      false,
+    );
+  });
+
+  it("ignores non-arrow keys", () => {
+    expect(shouldHandleCaptionNudgeKey(mockKeyboardEvent("KeyL"))).toBe(false);
+  });
+});

package/src/captions/keyboard.ts

@@ -0,0 +1,8 @@
+const CAPTION_NUDGE_KEYS = new Set(["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"]);
+
+type CaptionNudgeKeyEvent = Pick<KeyboardEvent, "altKey" | "ctrlKey" | "metaKey" | "key">;
+
+export function shouldHandleCaptionNudgeKey(event: CaptionNudgeKeyEvent): boolean {
+  if (event.metaKey || event.ctrlKey || event.altKey) return false;
+  return CAPTION_NUDGE_KEYS.has(event.key);
+}

package/src/components/LintModal.tsx

@@ -1,5 +1,6 @@
 import { useState } from "react";
 import { XIcon, WarningIcon, CheckCircleIcon, CaretRightIcon } from "@phosphor-icons/react";
+import { copyTextToClipboard } from "../utils/clipboard";
 
 export interface LintFinding {
   severity: "error" | "warning";
@@ -30,12 +31,10 @@ export function LintModal({
       return line;
     });
     const text = `Fix these HyperFrames lint issues for project "${projectId}":\n\nProject path: ${window.location.href}\n\n${lines.join("\n\n")}`;
-    try {
-      await navigator.clipboard.writeText(text);
+    const copiedText = await copyTextToClipboard(text);
+    if (copiedText) {
       setCopied(true);
       setTimeout(() => setCopied(false), 2000);
-    } catch {
-      // ignore
     }
   };
 

package/src/components/editor/DomEditOverlay.tsx

@@ -14,7 +14,11 @@ interface OverlayRect {
 interface DomEditOverlayProps {
   iframeRef: RefObject<HTMLIFrameElement | null>;
   selection: DomEditSelection | null;
-  onCanvasMouseDown: (event: React.MouseEvent<HTMLDivElement>) => void;
+  allowCanvasMovement?: boolean;
+  onCanvasMouseDown: (
+    event: React.MouseEvent<HTMLDivElement>,
+    options?: { preferClipAncestor?: boolean },
+  ) => void;
   onCanvasDoubleClick: (event: React.MouseEvent<HTMLDivElement>) => void;
   onSelectedDoubleClick: () => void;
   onBlockedMove: (selection: DomEditSelection) => void;
@@ -85,10 +89,21 @@ function selectionCacheKey(
   ].join("|");
 }
 
+function restoreInlineStyle(
+  element: HTMLElement,
+  property: "left" | "top" | "width" | "height",
+  value: string,
+) {
+  if (value) element.style.setProperty(property, value);
+  else element.style.removeProperty(property);
+}
+
 interface GestureState {
   kind: GestureKind;
   startX: number;
   startY: number;
+  initialStyleLeft: string;
+  initialStyleTop: string;
   originLeft: number;
   originTop: number;
   originWidth: number;
@@ -111,6 +126,7 @@ interface BlockedMoveState {
 export const DomEditOverlay = memo(function DomEditOverlay({
   iframeRef,
   selection,
+  allowCanvasMovement = true,
   onCanvasMouseDown,
   onCanvasDoubleClick,
   onSelectedDoubleClick,
@@ -226,6 +242,8 @@ export const DomEditOverlay = memo(function DomEditOverlay({
       kind,
       startX: e.clientX,
       startY: e.clientY,
+      initialStyleLeft: sel.element.style.left,
+      initialStyleTop: sel.element.style.top,
       originLeft: rect.left,
       originTop: rect.top,
       originWidth: rect.width,
@@ -277,9 +295,10 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     }
   };
 
-  const onPointerUp = () => {
+  const onPointerUp = (e: React.PointerEvent<HTMLDivElement>) => {
     const g = gestureRef.current;
     const sel = selectionRef.current;
+    const box = boxRef.current;
     blockedMoveRef.current = null;
     if (!g || !sel) {
       gestureRef.current = null;
@@ -290,6 +309,21 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     gestureRef.current = null;
     rafPausedRef.current = false;
 
+    const movedDistance = Math.hypot(e.clientX - g.startX, e.clientY - g.startY);
+    if (g.kind === "drag" && movedDistance < BLOCKED_MOVE_THRESHOLD_PX) {
+      restoreInlineStyle(sel.element, "left", g.initialStyleLeft);
+      restoreInlineStyle(sel.element, "top", g.initialStyleTop);
+      if (box) {
+        box.style.left = `${g.originLeft}px`;
+        box.style.top = `${g.originTop}px`;
+      }
+      suppressNextBoxClickRef.current = true;
+      onCanvasMouseDown(e as unknown as React.MouseEvent<HTMLDivElement>, {
+        preferClipAncestor: false,
+      });
+      return;
+    }
+
     if (g.kind === "drag") {
       const finalLeft = Number.parseFloat(sel.element.style.left) || g.actualLeft;
       const finalTop = Number.parseFloat(sel.element.style.top) || g.actualTop;
@@ -320,7 +354,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   const handleOverlayMouseDown = (event: React.MouseEvent<HTMLDivElement>) => {
     const target = event.target as HTMLElement | null;
     if (target?.closest('[data-dom-edit-selection-box="true"]')) return;
-    onCanvasMouseDown(event);
+    onCanvasMouseDown(event, { preferClipAncestor: false });
   };
 
   const handleOverlayDoubleClick = (event: React.MouseEvent<HTMLDivElement>) => {
@@ -339,7 +373,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
       event.stopPropagation();
       return;
     }
-    onCanvasMouseDown(event);
+    onCanvasMouseDown(event, { preferClipAncestor: false });
   };
 
   const clearPointerState = () => {
@@ -371,9 +405,10 @@ export const DomEditOverlay = memo(function DomEditOverlay({
               top: overlayRect.top,
               width: overlayRect.width,
               height: overlayRect.height,
-              cursor: selection.capabilities.canMove ? "move" : "default",
+              cursor: allowCanvasMovement && selection.capabilities.canMove ? "move" : "default",
             }}
             onPointerDown={(e) => {
+              if (!allowCanvasMovement) return;
               if (selection.capabilities.canMove) {
                 startGesture("drag", e);
                 return;
@@ -392,7 +427,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
             onDoubleClick={onSelectedDoubleClick}
           >
             {/* Resize handle — bottom-right corner */}
-            {selection.capabilities.canResize && (
+            {allowCanvasMovement && selection.capabilities.canResize && (
               <div
                 className="absolute -right-1.5 -bottom-1.5 w-3 h-3 rounded-sm bg-studio-accent border border-studio-accent/60"
                 style={{ cursor: "se-resize", touchAction: "none" }}

package/src/components/editor/PropertyPanel.tsx

@@ -64,6 +64,7 @@ interface PropertyPanelProps {
   onImportAssets?: (files: FileList) => Promise<string[]>;
   fontAssets?: ImportedFontAsset[];
   onImportFonts?: (files: FileList | File[]) => Promise<ImportedFontAsset[]>;
+  allowLayoutDetach?: boolean;
 }
 
 const FIELD =
@@ -1984,6 +1985,7 @@ export const PropertyPanel = memo(function PropertyPanel({
   onImportAssets,
   fontAssets = [],
   onImportFonts,
+  allowLayoutDetach = true,
 }: PropertyPanelProps) {
   const styles = element?.computedStyles ?? EMPTY_STYLES;
   const selectionColors = useMemo(() => collectSelectionColors(styles), [styles]);
@@ -2020,7 +2022,7 @@ export const PropertyPanel = memo(function PropertyPanel({
         <p className="text-sm font-medium text-neutral-200">Select an element in the preview.</p>
         <p className="mt-2 max-w-[260px] text-xs leading-5 text-neutral-500">
           The inspector is tuned for direct DOM edits with safer geometry controls, color picking,
-          and cleaner Paper-style grouping.
+          and cleaner grouped layer controls.
         </p>
       </div>
     );
@@ -2036,7 +2038,9 @@ export const PropertyPanel = memo(function PropertyPanel({
   const sourceLabel = element.id ? `#${element.id}` : element.selector;
   const showEditableSections = element.capabilities.canEditStyles;
   const disabledMoveReason =
-    element.capabilities.reasonIfDisabled && !element.capabilities.canDetachFromLayout
+    allowLayoutDetach &&
+    element.capabilities.reasonIfDisabled &&
+    !element.capabilities.canDetachFromLayout
       ? element.capabilities.reasonIfDisabled
       : null;
 
@@ -2131,7 +2135,7 @@ export const PropertyPanel = memo(function PropertyPanel({
               </button>
             </div>
           )}
-          {element.capabilities.canDetachFromLayout && (
+          {allowLayoutDetach && element.capabilities.canDetachFromLayout && (
             <div className="mt-4 flex min-w-0 flex-wrap items-center justify-between gap-3 border-l border-amber-500/40 pl-3">
               <div className="min-w-0 text-[11px] leading-5 text-neutral-400">
                 <div className="font-medium text-neutral-200">

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/NLELayout.tsx

@@ -5,6 +5,10 @@ import type { TimelineElement } from "../../player";
 import type { BlockedTimelineEditIntent } from "../../player/components/timelineEditing";
 import { NLEPreview } from "./NLEPreview";
 import { CompositionBreadcrumb, type CompositionLevel } from "./CompositionBreadcrumb";
+import {
+  TIMELINE_TOGGLE_SHORTCUT_LABEL,
+  getTimelineToggleTitle,
+} from "../../utils/timelineDiscovery";
 
 interface NLELayoutProps {
   projectId: string;
@@ -198,6 +202,7 @@ export const NLELayout = memo(function NLELayout({
 
   // Resizable timeline height
   const [timelineH, setTimelineH] = useState(DEFAULT_TIMELINE_H);
+  const isTimelineVisible = timelineVisible ?? true;
   const isDragging = useRef(false);
   const containerRef = useRef<HTMLDivElement>(null);
 
@@ -371,16 +376,11 @@ export const NLELayout = memo(function NLELayout({
               onNavigate={handleNavigateComposition}
             />
           )}
-          <PlayerControls
-            onTogglePlay={togglePlay}
-            onSeek={seek}
-            timelineVisible={timelineVisible ?? true}
-            onToggleTimeline={onToggleTimeline}
-          />
+          <PlayerControls onTogglePlay={togglePlay} onSeek={seek} />
         </div>
       </div>
 
-      {(timelineVisible ?? true) && (
+      {isTimelineVisible ? (
         <>
           {/* Resize divider */}
           <div
@@ -422,7 +422,42 @@ export const NLELayout = memo(function NLELayout({
             {timelineFooter && <div className="flex-shrink-0">{timelineFooter}</div>}
           </div>
         </>
-      )}
+      ) : onToggleTimeline ? (
+        <div className="flex-shrink-0 border-t border-neutral-800/50 bg-neutral-950/96">
+          <div className="flex h-10 items-center justify-between px-3">
+            <div className="text-[10px] font-medium uppercase tracking-[0.16em] text-neutral-500">
+              Timeline
+            </div>
+            <button
+              type="button"
+              onClick={onToggleTimeline}
+              className="flex h-7 items-center gap-1.5 rounded-md border border-neutral-800 px-2.5 text-[11px] font-medium text-neutral-300 transition-colors hover:border-neutral-700 hover:bg-neutral-900 hover:text-neutral-100"
+              title={getTimelineToggleTitle(false)}
+              aria-label="Show timeline editor"
+            >
+              <svg
+                width="13"
+                height="13"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="1.7"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                aria-hidden="true"
+              >
+                <rect x="3" y="13" width="18" height="8" rx="1" />
+                <path d="M7 9h10" />
+                <path d="M8 5h8" />
+              </svg>
+              <span>Show</span>
+              <span className="hidden rounded bg-white/5 px-1 py-0.5 font-mono text-[9px] text-neutral-500 sm:inline">
+                {TIMELINE_TOGGLE_SHORTCUT_LABEL}
+              </span>
+            </button>
+          </div>
+        </div>
+      ) : null}
     </div>
   );
 });

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
     }
   }, []);