@hyperframes/studio 0.7.61 → 0.7.63

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

@@ -2,6 +2,8 @@
 
 import React, { act, useState } from "react";
 import { createRoot } from "react-dom/client";
+import postcss from "postcss";
+import tailwindcss from "tailwindcss";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { FlatTextLayerList, FlatTextSection } from "./propertyPanelFlatTextSection";
 import type { DomEditSelection, DomEditTextField } from "./domEditingTypes";
@@ -256,8 +258,9 @@ describe("FlatTextFieldEditor controls", () => {
     act(() => root.unmount());
   });
 
-  it("live-commits the Size field on input, without requiring blur/Enter", async () => {
+  it("previews Size input immediately and persists once on blur", () => {
     const onSetTextFieldStyle = vi.fn();
+    const onPreviewTextFieldStyle = vi.fn();
     const { host, root } = renderInto(
       <FlatTextSection
         element={makeSingleFieldElement()}
@@ -265,6 +268,7 @@ describe("FlatTextFieldEditor controls", () => {
         fontAssets={[]}
         onSetText={vi.fn()}
         onSetTextFieldStyle={onSetTextFieldStyle}
+        onPreviewTextFieldStyle={onPreviewTextFieldStyle}
         onAddTextField={vi.fn()}
         onRemoveTextField={vi.fn()}
       />,
@@ -275,6 +279,7 @@ describe("FlatTextFieldEditor controls", () => {
     const input = sizeLabel?.parentElement?.querySelector<HTMLInputElement>("input");
     if (!input) throw new Error("expected the Size row's input");
     act(() => {
+      input.focus();
       const nativeInputValueSetter = Object.getOwnPropertyDescriptor(
         window.HTMLInputElement.prototype,
         "value",
@@ -282,9 +287,10 @@ describe("FlatTextFieldEditor controls", () => {
       nativeInputValueSetter?.call(input, "24px");
       input.dispatchEvent(new Event("input", { bubbles: true }));
     });
-    // liveCommit debounces on a 120ms timer — no blur/Enter dispatched here.
-    await act(async () => {
-      await new Promise((resolve) => setTimeout(resolve, 160));
+    expect(onPreviewTextFieldStyle).toHaveBeenCalledWith("a", "font-size", "24px");
+    expect(onSetTextFieldStyle).not.toHaveBeenCalled();
+    act(() => {
+      input.blur();
     });
     expect(onSetTextFieldStyle).toHaveBeenCalledWith("a", "font-size", "24px");
     act(() => root.unmount());
@@ -462,4 +468,41 @@ describe("FlatTextSection — multi-field", () => {
 
     act(() => root.unmount());
   });
+
+  it("keeps Content expandable and grows it with multiline text", async () => {
+    const element = makeMultiFieldElement();
+    element.textFields[0].value = "First line\nSecond line\nThird line";
+
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    act(() => {
+      root.render(
+        <FlatTextSection
+          element={element}
+          styles={{}}
+          fontAssets={[]}
+          onSetText={vi.fn()}
+          onSetTextFieldStyle={vi.fn()}
+          onAddTextField={vi.fn()}
+          onRemoveTextField={vi.fn()}
+        />,
+      );
+    });
+
+    const contentTextarea = host.querySelector<HTMLTextAreaElement>("textarea");
+    expect(contentTextarea?.value).toBe("First line\nSecond line\nThird line");
+    expect(contentTextarea?.classList).toContain("resize-y");
+    expect(contentTextarea?.classList).toContain("overflow-y-auto");
+
+    const compiled = await postcss([
+      tailwindcss({
+        content: [{ raw: host.innerHTML, extension: "html" }],
+        corePlugins: { preflight: false },
+      }),
+    ]).process("@tailwind utilities;", { from: undefined });
+    expect(compiled.css).toContain("field-sizing: content");
+
+    act(() => root.unmount());
+  });
 });

package/src/components/editor/propertyPanelFlatTextSection.tsx

@@ -47,6 +47,7 @@ function FlatTextFieldEditor({
   onImportFonts,
   onSetText,
   onSetTextFieldStyle,
+  onPreviewTextFieldStyle,
   autoFocus = false,
 }: {
   field: DomEditSelection["textFields"][number];
@@ -55,6 +56,7 @@ function FlatTextFieldEditor({
   onImportFonts?: (files: FileList | File[]) => Promise<ImportedFontAsset[]>;
   onSetText: (value: string, fieldKey?: string) => void;
   onSetTextFieldStyle: (fieldKey: string, property: string, value: string) => void;
+  onPreviewTextFieldStyle?: (fieldKey: string, property: string, value: string) => void;
   autoFocus?: boolean;
 }) {
   const track = useTrackDesignInput();
@@ -100,6 +102,7 @@ function FlatTextFieldEditor({
         value={field.computedStyles["font-size"] || styles["font-size"] || "16px"}
         tier={resolveValueTier(field.inlineStyles["font-size"], styles["font-size"] || "16px")}
         liveCommit
+        onPreview={(next) => onPreviewTextFieldStyle?.(field.key, "font-size", next)}
         onCommit={(next) => onSetTextFieldStyle(field.key, "font-size", next)}
       />
       <div className="flex min-h-[30px] items-center justify-between">
@@ -220,6 +223,7 @@ function FlatTextFieldEditor({
             flat
             label="Color"
             value={value ?? getTextFieldColor(field, styles)}
+            onPreview={(next) => onPreviewTextFieldStyle?.(field.key, "color", next)}
             onCommit={onCommit ?? ((next) => onSetTextFieldStyle(field.key, "color", next))}
           />
         )}
@@ -235,6 +239,7 @@ export function FlatTextSection({
   onImportFonts,
   onSetText,
   onSetTextFieldStyle,
+  onPreviewTextFieldStyle,
   onAddTextField,
   onRemoveTextField,
 }: {
@@ -244,6 +249,7 @@ export function FlatTextSection({
   onImportFonts?: (files: FileList | File[]) => Promise<ImportedFontAsset[]>;
   onSetText: (value: string, fieldKey?: string) => void;
   onSetTextFieldStyle: (fieldKey: string, property: string, value: string) => void;
+  onPreviewTextFieldStyle?: (fieldKey: string, property: string, value: string) => void;
   onAddTextField: (afterFieldKey?: string) => string | Promise<string | null> | null;
   onRemoveTextField: (fieldKey: string) => void;
 }) {
@@ -288,6 +294,7 @@ export function FlatTextSection({
           onImportFonts={onImportFonts}
           onSetText={onSetText}
           onSetTextFieldStyle={onSetTextFieldStyle}
+          onPreviewTextFieldStyle={onPreviewTextFieldStyle}
           autoFocus
         />
       </div>
@@ -303,6 +310,7 @@ export function FlatTextSection({
         onImportFonts={onImportFonts}
         onSetText={onSetText}
         onSetTextFieldStyle={onSetTextFieldStyle}
+        onPreviewTextFieldStyle={onPreviewTextFieldStyle}
       />
       <button
         type="button"

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

@@ -356,7 +356,10 @@ describe.each(["classic", "flat"] as const)("shared %s input telemetry", (ui) =>
       (input) => input.value === "#FF0000",
     );
     if (!hex) throw new Error("expected color hex input");
-    act(() => changeInput(hex, "#00FF00"));
+    act(() => {
+      changeInput(hex, "#00FF00");
+      blurInput(hex);
+    });
 
     expect(trackStudioEvent).toHaveBeenCalledTimes(1);
     expect(trackStudioEvent).toHaveBeenLastCalledWith("design_input", {

package/src/components/editor/propertyPanelPrimitives.tsx

@@ -3,107 +3,10 @@ import {
   DesignPanelInputProvider,
   useTrackDesignInput,
 } from "../../contexts/DesignPanelInputContext";
-import { adjustNumericToken, FIELD, LABEL, parseNumericToken } from "./propertyPanelHelpers";
+import { FIELD, LABEL } from "./propertyPanelHelpers";
+import { CommitField } from "./propertyPanelCommitField";
 
-export function CommitField({
-  value,
-  disabled,
-  liveCommit,
-  align = "left",
-  onCommit,
-}: {
-  value: string;
-  disabled?: boolean;
-  liveCommit?: boolean;
-  /** The legacy panel lays out label-then-value inline (left reads naturally);
-   *  the flat inspector lays out label…value across a `justify-between` row,
-   *  where a left-aligned value looks stranded at the edge of its own
-   *  right-hand box instead of lining up with every other row's value. */
-  align?: "left" | "right";
-  onCommit: (nextValue: string) => void;
-}) {
-  const [draft, setDraft] = useState(value);
-  const commitTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const valueRef = useRef(value);
-  const draftRef = useRef(draft);
-  const inputRef = useRef<HTMLInputElement>(null);
-
-  valueRef.current = value;
-  draftRef.current = draft;
-
-  useEffect(() => {
-    setDraft(value);
-  }, [value]);
-
-  useEffect(() => {
-    const el = inputRef.current;
-    if (!el) return;
-    const handler = (e: WheelEvent) => {
-      if (disabled || document.activeElement !== el) return;
-      const delta = e.deltaY === 0 ? e.deltaX : e.deltaY;
-      if (delta === 0) return;
-      const nextDraft = adjustNumericToken(draftRef.current, delta < 0 ? 1 : -1, e);
-      if (!nextDraft) return;
-      e.preventDefault();
-      e.stopPropagation();
-      setDraft(nextDraft);
-      scheduleCommitRef.current(nextDraft);
-    };
-    el.addEventListener("wheel", handler, { passive: false });
-    return () => el.removeEventListener("wheel", handler);
-  }, [disabled]);
-
-  useEffect(
-    () => () => {
-      if (commitTimerRef.current) clearTimeout(commitTimerRef.current);
-    },
-    [],
-  );
-
-  const commitDraft = (nextDraft: string) => {
-    if (commitTimerRef.current) clearTimeout(commitTimerRef.current);
-    if (nextDraft !== valueRef.current) onCommit(nextDraft);
-  };
-
-  const scheduleCommit = (nextDraft: string) => {
-    if (commitTimerRef.current) clearTimeout(commitTimerRef.current);
-    commitTimerRef.current = setTimeout(() => {
-      if (nextDraft !== valueRef.current) onCommit(nextDraft);
-    }, 120);
-  };
-  const scheduleCommitRef = useRef(scheduleCommit);
-  scheduleCommitRef.current = scheduleCommit;
-
-  return (
-    <input
-      ref={inputRef}
-      type="text"
-      value={draft}
-      disabled={disabled}
-      onChange={(e) => {
-        setDraft(e.target.value);
-        if (liveCommit) scheduleCommit(e.target.value);
-      }}
-      onBlur={() => commitDraft(draft)}
-      onKeyDown={(e) => {
-        if (e.key === "Enter") {
-          (e.target as HTMLInputElement).blur();
-          return;
-        }
-        if (e.key !== "ArrowUp" && e.key !== "ArrowDown") return;
-        const nextDraft = adjustNumericToken(draft, e.key === "ArrowUp" ? 1 : -1, e);
-        if (!nextDraft) return;
-        e.preventDefault();
-        setDraft(nextDraft);
-        scheduleCommit(nextDraft);
-      }}
-      title={parseNumericToken(value) ? "Scroll or use Arrow keys to adjust" : undefined}
-      className={`min-w-0 w-full bg-transparent text-[11px] font-medium text-neutral-100 outline-none disabled:cursor-not-allowed disabled:text-neutral-600 ${
-        align === "right" ? "text-right" : "text-left"
-      }`}
-    />
-  );
-}
+export { CommitField } from "./propertyPanelCommitField";
 
 /* ------------------------------------------------------------------ */
 /*  MetricField                                                        */

package/src/components/editor/propertyPanelSections.tsx

@@ -147,7 +147,7 @@ export function TextAreaField({
           onFocus={handleFocus}
           onChange={handleChange}
           onBlur={handleBlur}
-          className="w-full resize-none bg-transparent font-mono text-[11px] leading-normal text-panel-text-0 outline-none disabled:cursor-not-allowed disabled:text-panel-text-4"
+          className="[field-sizing:content] max-h-[40vh] min-h-12 w-full resize-y overflow-x-hidden overflow-y-auto bg-transparent font-mono text-[11px] leading-normal text-panel-text-0 outline-none disabled:cursor-not-allowed disabled:text-panel-text-4"
         />
       </div>
     );
@@ -165,7 +165,7 @@ export function TextAreaField({
           onFocus={handleFocus}
           onChange={handleChange}
           onBlur={handleBlur}
-          className="w-full resize-none bg-transparent text-[11px] font-medium text-neutral-100 outline-none disabled:cursor-not-allowed disabled:text-neutral-600"
+          className="[field-sizing:content] max-h-[40vh] min-h-20 w-full resize-y overflow-x-hidden overflow-y-auto bg-transparent text-[11px] font-medium text-neutral-100 outline-none disabled:cursor-not-allowed disabled:text-neutral-600"
         />
       </div>
     </label>

package/src/components/editor/propertyPanelTypes.ts

@@ -32,6 +32,7 @@ export interface PropertyPanelProps {
   onClearSelection: () => void;
   onUngroup?: () => void;
   onSetStyle: (prop: string, value: string) => void | Promise<void>;
+  onPreviewStyle?: (prop: string, value: string) => void;
   onSetAttribute: (attr: string, value: string) => void | Promise<void>;
   /** Commits several data-* attributes on the SAME element in ONE atomic
    *  persist call — e.g. a pinned timing range's start+duration together, so
@@ -62,6 +63,7 @@ export interface PropertyPanelProps {
   onSetManualRotation: (element: DomEditSelection, next: { angle: number }) => void;
   onSetText: (value: string, fieldKey?: string) => void;
   onSetTextFieldStyle: (fieldKey: string, property: string, value: string) => void;
+  onPreviewTextFieldStyle?: (fieldKey: string, property: string, value: string) => void;
   onAddTextField: (afterFieldKey?: string) => string | Promise<string | null> | null;
   onRemoveTextField: (fieldKey: string) => void;
   onAskAgent: () => void;

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

@@ -0,0 +1,37 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+import { useInspectorGestureTransaction } from "./useInspectorGestureTransaction";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+describe("useInspectorGestureTransaction", () => {
+  it("keeps a new gesture active when the prior async commit is acknowledged", () => {
+    const host = document.createElement("div");
+    const root = createRoot(host);
+    const onPreview = vi.fn();
+    const onCommit = vi.fn();
+    let gesture: ReturnType<typeof useInspectorGestureTransaction<number>> | null = null;
+
+    function Probe({ sourceValue }: { sourceValue: number }) {
+      gesture = useInspectorGestureTransaction({ sourceValue, onPreview, onCommit });
+      return null;
+    }
+
+    act(() => root.render(<Probe sourceValue={10} />));
+    act(() => {
+      gesture?.preview(20);
+      gesture?.settle();
+      gesture?.preview(30);
+    });
+    act(() => root.render(<Probe sourceValue={20} />));
+
+    expect(onPreview).toHaveBeenLastCalledWith(30);
+    act(() => gesture?.settle());
+    expect(onCommit.mock.calls.map(([value]) => value)).toEqual([20, 30]);
+
+    act(() => root.unmount());
+  });
+});

package/src/components/editor/useInspectorGestureTransaction.ts

@@ -0,0 +1,60 @@
+import { useCallback, useEffect, useRef } from "react";
+
+/** One owner for continuous inspector edits: preview freely, persist once. */
+export function useInspectorGestureTransaction<T>({
+  sourceValue,
+  onPreview,
+  onCommit,
+}: {
+  sourceValue: T;
+  onPreview: (value: T) => void;
+  onCommit: (value: T) => void;
+}) {
+  const sourceRef = useRef(sourceValue);
+  const activeRef = useRef<{ before: T; latest: T } | null>(null);
+  const previewRef = useRef(onPreview);
+  const commitRef = useRef(onCommit);
+  if (!activeRef.current) sourceRef.current = sourceValue;
+  previewRef.current = onPreview;
+  commitRef.current = onCommit;
+
+  const begin = useCallback(() => {
+    if (!activeRef.current) {
+      activeRef.current = { before: sourceRef.current, latest: sourceRef.current };
+    }
+  }, []);
+
+  const preview = useCallback((value: T) => {
+    if (!activeRef.current) {
+      activeRef.current = { before: sourceRef.current, latest: sourceRef.current };
+    }
+    activeRef.current.latest = value;
+    previewRef.current(value);
+  }, []);
+
+  const settle = useCallback(() => {
+    const active = activeRef.current;
+    activeRef.current = null;
+    if (active && !Object.is(active.before, active.latest)) {
+      sourceRef.current = active.latest;
+      // Restore the captured baseline before the persistent commit captures
+      // rollback state. The commit reapplies `latest` synchronously, so this
+      // is not visible but a failed save can now correctly restore `before`.
+      previewRef.current(active.before);
+      commitRef.current(active.latest);
+    }
+  }, []);
+
+  const cancel = useCallback(() => {
+    const active = activeRef.current;
+    activeRef.current = null;
+    if (active && !Object.is(active.before, active.latest)) {
+      sourceRef.current = active.before;
+      previewRef.current(active.before);
+    }
+  }, []);
+
+  useEffect(() => cancel, [cancel]);
+
+  return { begin, preview, settle, cancel, activeRef };
+}

package/src/components/nle/TimelinePane.tsx

@@ -96,6 +96,10 @@ export interface TimelinePaneProps {
     blockName: string,
     placement: Pick<TimelineElement, "start" | "track">,
   ) => Promise<void> | void;
+  onCompositionDrop?: (
+    sourcePath: string,
+    placement: Pick<TimelineElement, "start" | "track">,
+  ) => Promise<void> | void;
   onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
   onSelectTimelineElement?: (element: TimelineElement | null) => void;
 }
@@ -109,6 +113,7 @@ export function TimelinePane({
   onDeleteElement,
   onAssetDrop,
   onBlockDrop,
+  onCompositionDrop,
   onBlockedEditAttempt,
   onSelectTimelineElement,
 }: TimelinePaneProps) {
@@ -273,6 +278,7 @@ export function TimelinePane({
             onDeleteElement={handleDeleteElement}
             onAssetDrop={onAssetDrop}
             onBlockDrop={onBlockDrop}
+            onCompositionDrop={onCompositionDrop}
             onMoveElement={handleMoveElement}
             onMoveElements={handleMoveElements}
             onResizeElement={handleResizeElement}

package/src/components/sidebar/CompositionsTab.drag.test.tsx

@@ -0,0 +1,87 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TIMELINE_COMPOSITION_MIME } from "../../utils/timelineCompositionDrop";
+import { CompositionsTab } from "./CompositionsTab";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+(
+  window as unknown as { happyDOM: { settings: { disableIframePageLoading: boolean } } }
+).happyDOM.settings.disableIframePageLoading = true;
+
+let root: Root | null = null;
+
+afterEach(() => {
+  if (root) act(() => root?.unmount());
+  root = null;
+  document.body.innerHTML = "";
+});
+
+function mount(onSelect = vi.fn(), onAddToTimeline = vi.fn()) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  act(() => {
+    root?.render(
+      <CompositionsTab
+        projectId="demo"
+        compositions={["compositions/headline.html"]}
+        activeComposition={null}
+        onSelect={onSelect}
+        onAddToTimeline={onAddToTimeline}
+      />,
+    );
+  });
+  const card = host.querySelector<HTMLElement>('[draggable="true"]');
+  if (!card) throw new Error("composition card did not render");
+  return { host, card, onSelect, onAddToTimeline };
+}
+
+describe("composition card drag", () => {
+  it("keeps ordinary click navigation", () => {
+    const { card, onSelect } = mount();
+    act(() => card.click());
+    expect(onSelect).toHaveBeenCalledWith("compositions/headline.html");
+  });
+
+  it("emits only source identity and suppresses the click following a drag", () => {
+    const { card, onSelect } = mount();
+    const data = new Map<string, string>();
+    const event = new Event("dragstart", { bubbles: true });
+    Object.defineProperty(event, "dataTransfer", {
+      value: {
+        effectAllowed: "none",
+        setData: (type: string, value: string) => data.set(type, value),
+      },
+    });
+    act(() => {
+      card.dispatchEvent(event);
+      card.click();
+    });
+
+    expect(JSON.parse(data.get(TIMELINE_COMPOSITION_MIME) ?? "null")).toEqual({
+      sourcePath: "compositions/headline.html",
+    });
+    expect(card.className).toContain("select-none");
+    expect(onSelect).not.toHaveBeenCalled();
+  });
+
+  it("offers pointer and keyboard add-at-playhead actions without opening the card", () => {
+    const { host, onSelect, onAddToTimeline } = mount();
+    const add = host.querySelector<HTMLButtonElement>(
+      '[aria-label="Add headline to timeline at playhead"]',
+    );
+    if (!add) throw new Error("add action did not render");
+    act(() => {
+      add.click();
+      add.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true }));
+      add.click();
+    });
+
+    expect(onAddToTimeline).toHaveBeenCalledTimes(2);
+    expect(onAddToTimeline).toHaveBeenLastCalledWith("compositions/headline.html");
+    expect(onSelect).not.toHaveBeenCalled();
+  });
+});

package/src/components/sidebar/CompositionsTab.tsx

@@ -1,5 +1,6 @@
 import { memo, useCallback, useEffect, useRef, useState } from "react";
 import { setPreviewMediaMuted } from "../../player/lib/timelineIframeHelpers";
+import { TIMELINE_COMPOSITION_MIME } from "../../utils/timelineCompositionDrop";
 
 interface CompositionsTabProps {
   projectId: string;
@@ -7,6 +8,7 @@ interface CompositionsTabProps {
   activeComposition: string | null;
   onSelect: (comp: string) => void;
   onRenderComposition?: (comp: string) => void;
+  onAddToTimeline?: (comp: string) => void;
   isRendering?: boolean;
   lintFindingsByFile?: Map<string, { count: number; messages: string[] }>;
 }
@@ -115,6 +117,7 @@ function CompCard({
   onRender,
   isRendering,
   lintInfo,
+  onAddToTimeline,
 }: {
   projectId: string;
   comp: string;
@@ -123,12 +126,14 @@ function CompCard({
   onRender?: () => void;
   isRendering?: boolean;
   lintInfo?: { count: number; messages: string[] };
+  onAddToTimeline?: () => void;
 }) {
   const [hovered, setHovered] = useState(false);
   const [stageSize, setStageSize] = useState(DEFAULT_PREVIEW_STAGE);
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
   const hoverTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
   const syncTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const draggedRef = useRef(false);
 
   const requestIframePlaybackSync = useCallback((shouldPlay: boolean) => {
     if (syncTimer.current) {
@@ -179,10 +184,32 @@ function CompCard({
 
   return (
     <div
-      onClick={onSelect}
+      role="button"
+      tabIndex={0}
+      draggable
+      onDragStart={(event) => {
+        draggedRef.current = true;
+        event.dataTransfer.effectAllowed = "copy";
+        event.dataTransfer.setData(TIMELINE_COMPOSITION_MIME, JSON.stringify({ sourcePath: comp }));
+      }}
+      onDragEnd={() => {
+        window.setTimeout(() => {
+          draggedRef.current = false;
+        }, 0);
+      }}
+      onClick={() => {
+        if (!draggedRef.current) onSelect();
+      }}
+      onKeyDown={(event) => {
+        if (event.target !== event.currentTarget) return;
+        if (event.key === "Enter" || event.key === " ") {
+          event.preventDefault();
+          onSelect();
+        }
+      }}
       onPointerEnter={handleEnter}
       onPointerLeave={handleLeave}
-      className={`group/card w-full text-left px-2 py-1.5 flex items-center gap-2.5 transition-colors cursor-pointer ${
+      className={`group/card w-full select-none text-left px-2 py-1.5 flex items-center gap-2.5 transition-colors cursor-grab active:cursor-grabbing ${
         isActive
           ? "bg-studio-accent/10 border-l-2 border-studio-accent"
           : "border-l-2 border-transparent hover:bg-neutral-800/50"
@@ -232,6 +259,20 @@ function CompCard({
         </div>
         <span className="text-[9px] text-neutral-600 truncate block">{comp}</span>
       </div>
+      {onAddToTimeline && (
+        <button
+          type="button"
+          title={`Add ${name} to timeline at playhead`}
+          aria-label={`Add ${name} to timeline at playhead`}
+          onClick={(event) => {
+            event.stopPropagation();
+            onAddToTimeline();
+          }}
+          className="flex h-8 w-8 flex-shrink-0 items-center justify-center rounded text-neutral-600 opacity-0 transition-[color,background-color,opacity] hover:bg-neutral-800 hover:text-studio-accent group-hover/card:opacity-100 group-focus-within/card:opacity-100 focus:opacity-100"
+        >
+          <span aria-hidden="true">+</span>
+        </button>
+      )}
       {onRender && (
         <button
           type="button"
@@ -274,6 +315,7 @@ export const CompositionsTab = memo(function CompositionsTab({
   activeComposition,
   onSelect,
   onRenderComposition,
+  onAddToTimeline,
   isRendering,
   lintFindingsByFile,
 }: CompositionsTabProps) {
@@ -295,6 +337,7 @@ export const CompositionsTab = memo(function CompositionsTab({
           isActive={activeComposition === comp}
           onSelect={() => onSelect(comp)}
           onRender={onRenderComposition ? () => onRenderComposition(comp) : undefined}
+          onAddToTimeline={onAddToTimeline ? () => onAddToTimeline(comp) : undefined}
           isRendering={isRendering}
           lintInfo={lintFindingsByFile?.get(comp)}
         />

package/src/components/sidebar/LeftSidebar.tsx

@@ -61,6 +61,7 @@ interface LeftSidebarProps {
   onPreviewBlock?: (preview: BlockPreviewInfo | null) => void;
   takeoverContent?: ReactNode;
   onAddAssetToTimeline?: (path: string) => void;
+  onAddCompositionToTimeline?: (path: string) => void;
 }
 
 export const LeftSidebar = memo(
@@ -94,6 +95,7 @@ export const LeftSidebar = memo(
       onPreviewBlock,
       takeoverContent,
       onAddAssetToTimeline,
+      onAddCompositionToTimeline,
     },
     ref,
   ) {
@@ -220,6 +222,7 @@ export const LeftSidebar = memo(
                 compositions={compositions}
                 activeComposition={activeComposition}
                 onSelect={onSelectComposition}
+                onAddToTimeline={onAddCompositionToTimeline}
                 onRenderComposition={onRenderComposition}
                 isRendering={isRendering}
                 lintFindingsByFile={lintFindingsByFile}

package/src/contexts/StudioContext.tsx

@@ -69,6 +69,10 @@ export function useStudioPlaybackContext(): StudioPlaybackValue {
   return ctx;
 }
 
+export function useStudioPlaybackContextOptional(): StudioPlaybackValue | null {
+  return useContext(StudioPlaybackContext);
+}
+
 /** @deprecated Use useStudioShellContext and/or useStudioPlaybackContext instead. */
 // fallow-ignore-next-line unused-export
 export function useStudioContext(): StudioContextValue {