@hyperframes/studio 0.7.61 → 0.7.63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.61",
+  "version": "0.7.63",
   "description": "",
   "repository": {
     "type": "git",
@@ -46,11 +46,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.7.61",
-    "@hyperframes/parsers": "0.7.61",
-    "@hyperframes/player": "0.7.61",
-    "@hyperframes/sdk": "0.7.61",
-    "@hyperframes/studio-server": "0.7.61"
+    "@hyperframes/core": "0.7.63",
+    "@hyperframes/parsers": "0.7.63",
+    "@hyperframes/player": "0.7.63",
+    "@hyperframes/studio-server": "0.7.63",
+    "@hyperframes/sdk": "0.7.63"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -65,7 +65,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.7.61"
+    "@hyperframes/producer": "0.7.63"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -23,7 +23,6 @@ import { useDomEditSession } from "./hooks/useDomEditSession";
 import { useSdkSelectionSync } from "./hooks/useSdkSelectionSync";
 import { useStudioSdkSessions } from "./hooks/useStudioSdkSessions";
 import { useBlockHandlers } from "./hooks/useBlockHandlers";
-import { useAddAssetAtPlayhead } from "./hooks/useAddAssetAtPlayhead";
 import { useAppHotkeys } from "./hooks/useAppHotkeys";
 import { useClipboard } from "./hooks/useClipboard";
 import { deleteSelectedKeyframes } from "./hooks/timelineEditingHelpers";
@@ -58,6 +57,7 @@ import { FileManagerProvider } from "./contexts/FileManagerContext";
 import { DomEditProvider } from "./contexts/DomEditContext";
 import { StudioSplash } from "./components/StudioSplash";
 import { useServerConnection } from "./hooks/useServerConnection";
+import { useTimelineAddAtPlayhead } from "./hooks/useTimelineAddAtPlayhead";
 import {
   normalizeStudioCompositionPath,
   readStudioUrlStateFromWindow,
@@ -65,7 +65,6 @@ import {
 } from "./utils/studioUrlState";
 import { trackStudioSessionStart } from "./telemetry/events";
 import { hasFiredSessionStart, markSessionStartFired } from "./telemetry/config";
-type CanvasRect = { left: number; top: number; width: number; height: number };
 // fallow-ignore-next-line complexity
 export function StudioApp() {
   const { projectId, resolving, waitingForServer } = useServerConnection();
@@ -100,9 +99,6 @@ export function StudioApp() {
   const timelineDuration = usePlayerStore((s) => s.duration);
   const isPlaying = usePlayerStore((s) => s.isPlaying);
   const isMasterView = !activeCompPath || activeCompPath === "index.html";
-  const activePreviewUrl = activeCompPath
-    ? `/api/projects/${projectId}/preview/comp/${activeCompPath}`
-    : null;
   const effectiveTimelineDuration = useMemo(() => {
     const maxEnd =
       timelineElements.length > 0
@@ -196,7 +192,13 @@ export function StudioApp() {
     },
     [timelineEditing.handleTimelineGroupMove],
   );
-  const handleAddAssetAtPlayhead = useAddAssetAtPlayhead(timelineEditing.handleTimelineAssetDrop);
+  const {
+    addAssetAtPlayhead: handleAddAssetAtPlayhead,
+    addCompositionAtPlayhead: handleAddCompositionAtPlayhead,
+  } = useTimelineAddAtPlayhead(
+    timelineEditing.handleTimelineAssetDrop,
+    timelineEditing.handleTimelineCompositionDrop,
+  );
   const {
     activeBlockParams,
     setActiveBlockParams,
@@ -338,7 +340,9 @@ export function StudioApp() {
   const renderClipContent = useRenderClipContent({
     projectIdRef: fileManager.projectIdRef,
     compIdToSrc,
-    activePreviewUrl,
+    activePreviewUrl: activeCompPath
+      ? `/api/projects/${projectId}/preview/comp/${activeCompPath}`
+      : null,
     effectiveTimelineDuration,
   });
   const compositionDimensions = useCompositionDimensions();
@@ -369,14 +373,13 @@ export function StudioApp() {
   });
   handleToggleRecordingRef.current = handleToggleRecording;
   const recordingToggle = STUDIO_KEYFRAMES_ENABLED ? handleToggleRecording : undefined;
-  const canvasRectRef = useRef<CanvasRect | null>(null);
+  const canvasRectRef = useRef<DOMRect | null>(null);
   useLayoutEffect(() => {
     if (gestureState !== "recording" || !previewIframe) {
       canvasRectRef.current = null;
       return;
     }
-    const r = previewIframe.getBoundingClientRect();
-    canvasRectRef.current = { left: r.left, top: r.top, width: r.width, height: r.height };
+    canvasRectRef.current = previewIframe.getBoundingClientRect();
   }, [gestureState, previewIframe]);
   const handlePreviewIframeRef = useCallback(
     (iframe: HTMLIFrameElement | null) => {
@@ -511,6 +514,7 @@ export function StudioApp() {
                         lintFindingCount={lintModal?.length ?? findingsByFile.size}
                         lintFindingsByFile={findingsByFile}
                         onAddAssetToTimeline={handleAddAssetAtPlayhead}
+                        onAddCompositionToTimeline={handleAddCompositionAtPlayhead}
                       />
                     }
                     right={
@@ -540,6 +544,7 @@ export function StudioApp() {
                     handleTimelineElementDelete={timelineEditing.handleTimelineElementDelete}
                     handleTimelineAssetDrop={timelineEditing.handleTimelineAssetDrop}
                     handleTimelineBlockDrop={handleTimelineBlockDrop}
+                    handleTimelineCompositionDrop={timelineEditing.handleTimelineCompositionDrop}
                     handlePreviewBlockDrop={handlePreviewBlockDrop}
                     handleTimelineFileDrop={timelineEditing.handleTimelineFileDrop}
                     handleTimelineElementMove={timelineEditing.handleTimelineElementMove}

package/src/components/EditorShell.tsx

@@ -42,6 +42,10 @@ export interface EditorShellProps extends TimelineEditCallbackDeps {
     blockName: string,
     placement: TimelineDropPlacement,
   ) => Promise<void> | void;
+  handleTimelineCompositionDrop?: (
+    sourcePath: string,
+    placement: TimelineDropPlacement,
+  ) => Promise<void> | void;
   handlePreviewBlockDrop?: (
     blockName: string,
     position: { left: number; top: number },
@@ -72,6 +76,7 @@ export function EditorShell({
   handleTimelineElementDelete,
   handleTimelineAssetDrop,
   handleTimelineBlockDrop,
+  handleTimelineCompositionDrop,
   handlePreviewBlockDrop,
   handleTimelineFileDrop,
   handleTimelineElementMove,
@@ -140,6 +145,7 @@ export function EditorShell({
             onFileDrop={handleTimelineFileDrop}
             onAssetDrop={handleTimelineAssetDrop}
             onBlockDrop={handleTimelineBlockDrop}
+            onCompositionDrop={handleTimelineCompositionDrop}
             onDeleteElement={handleTimelineElementDelete}
             previewOverlay={
               <PreviewOverlays
@@ -174,6 +180,10 @@ interface EditorShellBodyProps {
   onFileDrop: (files: File[], placement?: TimelineDropPlacement) => Promise<void> | void;
   onAssetDrop: (assetPath: string, placement: TimelineDropPlacement) => Promise<void> | void;
   onBlockDrop?: (blockName: string, placement: TimelineDropPlacement) => Promise<void> | void;
+  onCompositionDrop?: (
+    sourcePath: string,
+    placement: TimelineDropPlacement,
+  ) => Promise<void> | void;
   onDeleteElement: (element: TimelineElement) => Promise<void> | void;
 }
 
@@ -189,6 +199,7 @@ function EditorShellBody({
   onFileDrop,
   onAssetDrop,
   onBlockDrop,
+  onCompositionDrop,
   onDeleteElement,
 }: EditorShellBodyProps) {
   const { compositionStack, updateCompositionStack, containerRef } = useNLEContext();
@@ -233,6 +244,7 @@ function EditorShellBody({
         onFileDrop={onFileDrop}
         onAssetDrop={onAssetDrop}
         onBlockDrop={onBlockDrop}
+        onCompositionDrop={onCompositionDrop}
         onDeleteElement={onDeleteElement}
         onSelectTimelineElement={onSelectTimelineElement}
         timelineFooter={

package/src/components/StudioLeftSidebar.tsx

@@ -19,6 +19,7 @@ export interface StudioLeftSidebarProps {
   lintFindingCount?: number;
   lintFindingsByFile?: Map<string, { count: number; messages: string[] }>;
   onAddAssetToTimeline?: (path: string) => void;
+  onAddCompositionToTimeline?: (path: string) => void;
 }
 
 // fallow-ignore-next-line complexity
@@ -32,6 +33,7 @@ export function StudioLeftSidebar({
   lintFindingCount,
   lintFindingsByFile,
   onAddAssetToTimeline,
+  onAddCompositionToTimeline,
 }: StudioLeftSidebarProps) {
   const {
     leftCollapsed,
@@ -150,6 +152,7 @@ export function StudioLeftSidebar({
         onAddBlock={onAddBlock}
         onPreviewBlock={onPreviewBlock}
         onAddAssetToTimeline={onAddAssetToTimeline}
+        onAddCompositionToTimeline={onAddCompositionToTimeline}
       />
       {/* Vertical resize divider: 3px visible seam, 8px pointer-capture zone via
           the absolutely-positioned inner hit area. The outer element is w-[3px] so

package/src/components/editor/DomEditSelectionChrome.test.tsx

@@ -9,6 +9,57 @@ import { DomEditSelectionChrome } from "./DomEditSelectionChrome";
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
 describe("DomEditSelectionChrome crop composition", () => {
+  it("renders overlay-only transparent chrome at headline geometry without changing composition bytes", () => {
+    const composition = document.implementation.createHTMLDocument();
+    composition.body.innerHTML = `
+      <section class="hl-block"><div class="hl-mask" style="overflow:hidden;background:transparent">
+        <h1 class="hl-text">Launch title</h1>
+      </div></section>
+    `;
+    const headline = composition.querySelector<HTMLElement>(".hl-text")!;
+    const before = composition.documentElement.outerHTML;
+    const selection = {
+      element: headline,
+      selector: ".hl-text",
+      capabilities: {
+        canCrop: false,
+        canApplyManualOffset: false,
+        canApplyManualSize: false,
+        canApplyManualRotation: false,
+      },
+    } as unknown as DomEditSelection;
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    act(() => {
+      root.render(
+        <DomEditSelectionChrome
+          selection={selection}
+          overlayRect={{ left: 44, top: 52, width: 220, height: 48, editScaleX: 1, editScaleY: 1 }}
+          allowCanvasMovement={false}
+          boxRef={createRef()}
+          boxChromeClass="border border-studio-accent/80"
+          boxClipPath={undefined}
+          selectionKey="headline"
+          groupSelectionCount={0}
+          blockedMoveRef={createRef()}
+          gestures={{ startGesture: vi.fn() } as never}
+          onStyleCommit={vi.fn()}
+          onBoxMouseDown={vi.fn()}
+          onBoxClick={vi.fn()}
+        />,
+      );
+    });
+    const chrome = host.querySelector<HTMLElement>('[data-dom-edit-selection-box="true"]')!;
+    expect(chrome.style.cssText).toContain("left: 44px");
+    expect(chrome.style.cssText).toContain("width: 220px");
+    expect(chrome.style.background).toBe("");
+    expect(chrome.className).not.toMatch(/bg-/);
+    expect(composition.documentElement.outerHTML).toBe(before);
+    act(() => root.unmount());
+    host.remove();
+  });
+
   it("places rotated crop UI in exactly one oriented coordinate plane", () => {
     const element = document.createElement("div");
     element.id = "clip";

package/src/components/editor/PropertyPanelFlat.tsx

@@ -78,6 +78,7 @@ export function PropertyPanelFlat({
   onClearSelection,
   onUngroup,
   onSetStyle,
+  onPreviewStyle,
   onSetAttribute,
   onSetAttributes,
   onSetAttributeLive,
@@ -86,6 +87,7 @@ export function PropertyPanelFlat({
   onRemoveBackground,
   onSetText,
   onSetTextFieldStyle,
+  onPreviewTextFieldStyle,
   onAddTextField,
   onRemoveTextField,
   onAskAgent,
@@ -147,6 +149,7 @@ export function PropertyPanelFlat({
   | "onClearSelection"
   | "onUngroup"
   | "onSetStyle"
+  | "onPreviewStyle"
   | "onSetAttribute"
   | "onSetAttributes"
   | "onSetAttributeLive"
@@ -155,6 +158,7 @@ export function PropertyPanelFlat({
   | "onRemoveBackground"
   | "onSetText"
   | "onSetTextFieldStyle"
+  | "onPreviewTextFieldStyle"
   | "onAddTextField"
   | "onRemoveTextField"
   | "onAskAgent"
@@ -360,6 +364,7 @@ export function PropertyPanelFlat({
           onImportFonts={onImportFonts}
           onSetText={onSetText}
           onSetTextFieldStyle={onSetTextFieldStyle}
+          onPreviewTextFieldStyle={onPreviewTextFieldStyle}
           onAddTextField={onAddTextField}
           onRemoveTextField={onRemoveTextField}
         />
@@ -382,6 +387,7 @@ export function PropertyPanelFlat({
           styles={styles}
           assets={assets}
           onSetStyle={onSetStyle}
+          onPreviewStyle={onPreviewStyle}
           onImportAssets={onImportAssets}
           gsapBorderRadius={gsapBorderRadius}
         />

package/src/components/editor/compositionReliabilityFixture.integration.test.ts

@@ -0,0 +1,105 @@
+// @vitest-environment jsdom
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { patchElementInHtml } from "@hyperframes/studio-server/source-mutation";
+import { describe, expect, it } from "vitest";
+import { buildDomEditStylePatchOperation } from "./domEditing";
+
+const fixtureDir = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../tests/e2e/fixtures/composition-reliability",
+);
+
+function fixture(path: string): string {
+  return readFileSync(join(fixtureDir, path), "utf8");
+}
+
+function parse(html: string): Document {
+  return new DOMParser().parseFromString(html, "text/html");
+}
+
+function inTemplate(document: Document, selector: string): Element | null {
+  for (const template of Array.from(document.querySelectorAll("template"))) {
+    const match = template.content.querySelector(selector);
+    if (match) return match;
+  }
+  return null;
+}
+
+describe("composition reliability acceptance fixture", () => {
+  const indexSource = fixture("index.html");
+  const titleSource = fixture("compositions/title-card.html");
+  const nestedSource = fixture("compositions/nested-shell.html");
+
+  it("owns repeated root hosts, a nested host, transparent headline topology, and collisions", () => {
+    const index = parse(indexSource);
+    const repeated = Array.from(
+      index.querySelectorAll('[data-composition-src="compositions/title-card.html"]'),
+    );
+    expect(repeated).toHaveLength(2);
+    expect(repeated.map((host) => host.getAttribute("data-start"))).toEqual(["0", "4"]);
+    expect(
+      index.querySelector('[data-composition-src="compositions/nested-shell.html"]'),
+    ).toBeTruthy();
+
+    const nested = parse(nestedSource);
+    const nestedHost = inTemplate(nested, '[data-composition-src="title-card.html"]');
+    expect(nestedHost).toBeTruthy();
+    const nestedDependency = nestedHost?.getAttribute("data-composition-src");
+    expect(
+      nestedDependency ? existsSync(resolve(fixtureDir, "compositions", nestedDependency)) : false,
+    ).toBe(true);
+
+    const title = parse(titleSource);
+    const mask = inTemplate(title, ".hl-mask");
+    const headline = inTemplate(title, ".hl-mask > .hl-text");
+    expect(mask?.textContent).toContain("Reliable compositions");
+    expect(inTemplate(title, "style")?.textContent).toMatch(
+      /\.hl-mask\s*\{[^}]*overflow:\s*hidden;[^}]*background:\s*transparent;/,
+    );
+    expect(headline?.tagName).toBe("H1");
+
+    const collisionA = index.querySelector('[data-hf-id="collision-a"]')!;
+    const collisionB = index.querySelector('[data-hf-id="collision-b"]')!;
+    const layered = index.querySelector('[data-hf-id="layer-overlap"]')!;
+    expect(collisionA.getAttribute("data-track-index")).toBe(
+      collisionB.getAttribute("data-track-index"),
+    );
+    expect(
+      Number(collisionA.getAttribute("data-start")) +
+        Number(collisionA.getAttribute("data-duration")),
+    ).toBe(Number(collisionB.getAttribute("data-start")));
+    expect(layered.getAttribute("data-start")).toBe(collisionB.getAttribute("data-start"));
+    expect(layered.getAttribute("data-track-index")).not.toBe(
+      collisionB.getAttribute("data-track-index"),
+    );
+  });
+
+  it("keeps timeline host edits in the root source and headline color in the template source", () => {
+    const moved = patchElementInHtml(indexSource, { hfId: "title-host-a" }, [
+      { type: "attribute", property: "start", value: "5" },
+      { type: "attribute", property: "duration", value: "2" },
+    ]);
+    expect(moved.matched).toBe(true);
+    expect(moved.html).toContain('data-hf-id="title-host-a"');
+    expect(moved.html).toContain('data-start="5"');
+    expect(moved.html).toContain('data-duration="2"');
+    expect(moved.html).not.toContain('data-hf-id="title-text"');
+    expect(titleSource).not.toContain("#12b886");
+
+    const recolored = patchElementInHtml(titleSource, { hfId: "title-text" }, [
+      buildDomEditStylePatchOperation("color", "#12b886"),
+    ]);
+    expect(recolored.matched).toBe(true);
+    const recoloredDocument = parse(recolored.html);
+    expect(
+      inTemplate(recoloredDocument, '[data-hf-id="title-text"]')?.getAttribute("style"),
+    ).toContain("color: #12b886");
+    expect(
+      inTemplate(recoloredDocument, '[data-hf-id="title-mask"]')?.getAttribute("style"),
+    ).toBeNull();
+    expect(recolored.html).not.toContain('data-hf-id="title-host-a"');
+    expect(indexSource).not.toContain("#12b886");
+  });
+});

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

@@ -739,6 +739,40 @@ describe("resolveDomEditSelection", () => {
     expect(selection?.selector).toBe("#copy");
   });
 
+  it("keeps a transparent overflow mask structural when directly selecting its headline", async () => {
+    const document = createDocument(`
+      <template id="source-template"></template>
+      <section class="hl-block">
+        <div class="hl-mask" style="overflow: hidden; background: transparent">
+          <h1 class="hl-text">Launch title</h1>
+        </div>
+      </section>
+    `);
+    const headline = document.querySelector<HTMLElement>(".hl-text")!;
+    setElementRect(headline, { left: 44, top: 52, width: 220, height: 48 });
+    const selection = await resolveDomEditSelection(headline, {
+      activeCompositionPath: "index.html",
+      isMasterView: false,
+      preferClipAncestor: false,
+    });
+
+    expect(selection?.element).toBe(headline);
+    expect(selection?.selector).toBe(".hl-text");
+    expect(selection?.textFields).toMatchObject([{ source: "self", tagName: "h1" }]);
+    expect(selection?.boundingBox).toEqual({ x: 44, y: 52, width: 220, height: 48 });
+    // Explicit layer navigation remains free to resolve the structural mask.
+    const mask = document.querySelector<HTMLElement>(".hl-mask")!;
+    expect(
+      (
+        await resolveDomEditSelection(mask, {
+          activeCompositionPath: "index.html",
+          isMasterView: false,
+          preferClipAncestor: false,
+        })
+      )?.element,
+    ).toBe(mask);
+  });
+
   // fallow-ignore-next-line code-duplication
   it("collects simple child text blocks as separate editable fields", async () => {
     const document = createDocument(`

package/src/components/editor/propertyPanelColor.test.tsx

@@ -11,6 +11,15 @@ afterEach(() => {
   document.body.innerHTML = "";
 });
 
+function renderColorField(onCommit: (value: string) => void): void {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  act(() => {
+    root.render(<ColorField flat label="Color" value="rgb(255, 176, 32)" onCommit={onCommit} />);
+  });
+}
+
 describe("ColorField flat trigger", () => {
   it("renders label and value inline with a small swatch, no boxed border", () => {
     const host = document.createElement("div");
@@ -25,4 +34,26 @@ describe("ColorField flat trigger", () => {
     expect(host.textContent).toContain("Color");
     act(() => root.unmount());
   });
+
+  it("persists one keyboard slider gesture on keyup", () => {
+    const onCommit = vi.fn();
+    renderColorField(onCommit);
+    const trigger = document.querySelector<HTMLButtonElement>('[data-flat-color-trigger="true"]');
+    if (!trigger) throw new Error("Color trigger was not rendered");
+    act(() => {
+      trigger.click();
+    });
+    const hue = document.querySelector<HTMLElement>('[role="slider"][aria-label="Hue"]');
+    if (!hue) throw new Error("Hue slider was not rendered");
+
+    act(() => {
+      hue.dispatchEvent(new KeyboardEvent("keydown", { bubbles: true, key: "ArrowRight" }));
+    });
+    expect(onCommit).not.toHaveBeenCalled();
+    act(() => {
+      hue.dispatchEvent(new KeyboardEvent("keyup", { bubbles: true, key: "ArrowRight" }));
+    });
+
+    expect(onCommit).toHaveBeenCalledOnce();
+  });
 });