@hyperframes/studio 0.5.7 → 0.6.0-alpha.10

package/src/player/components/TimelineClip.tsx

@@ -17,15 +17,67 @@ interface TimelineClipProps {
   theme?: TimelineTheme;
   trackStyle: TimelineTrackStyle;
   isComposition: boolean;
+  isInspectorActive?: boolean;
+  isThumbnailActive?: boolean;
+  thumbnailLabel?: string;
+  childCount?: number;
   onHoverStart: () => void;
   onHoverEnd: () => void;
   onPointerDown?: (e: React.PointerEvent) => void;
   onResizeStart?: (edge: "start" | "end", e: React.PointerEvent) => void;
+  onInspectorClick?: (e: React.MouseEvent) => void;
+  onThumbnailClick?: (e: React.MouseEvent) => void;
   onClick: (e: React.MouseEvent) => void;
   onDoubleClick: (e: React.MouseEvent) => void;
   children?: ReactNode;
 }
 
+export const TIMELINE_CLIP_CONTROL_Z_INDEX = 20;
+
+const COMPACT_CLIP_CONTROL_WIDTH = 112;
+
+interface TimelineClipControlPresentationInput {
+  widthPx: number;
+  isSelected: boolean;
+  isHovered: boolean;
+  isInspectorActive: boolean;
+  isThumbnailActive: boolean;
+  isDragging: boolean;
+}
+
+export interface TimelineClipControlPresentation {
+  compact: boolean;
+  showControls: boolean;
+  containerClassName: string;
+  buttonClassName: string;
+  iconSize: number;
+}
+
+export function getTimelineClipControlPresentation({
+  widthPx,
+  isSelected,
+  isHovered,
+  isInspectorActive,
+  isThumbnailActive,
+  isDragging,
+}: TimelineClipControlPresentationInput): TimelineClipControlPresentation {
+  const compact = widthPx < COMPACT_CLIP_CONTROL_WIDTH;
+  const isInteractive = isHovered || isSelected || isInspectorActive || isThumbnailActive;
+  const showControls = !isDragging && (!compact || isInteractive);
+
+  return {
+    compact,
+    showControls,
+    containerClassName: compact
+      ? "absolute right-1 top-1 flex items-center gap-1"
+      : "absolute right-2 top-2 flex items-center gap-1",
+    buttonClassName: compact
+      ? "flex h-5 w-5 items-center justify-center rounded-[7px]"
+      : "flex h-6 w-6 items-center justify-center rounded-md",
+    iconSize: compact ? 12 : 14,
+  };
+}
+
 export const TimelineClip = memo(function TimelineClip({
   el,
   pps,
@@ -37,10 +89,16 @@ export const TimelineClip = memo(function TimelineClip({
   theme = defaultTimelineTheme,
   trackStyle,
   isComposition,
+  isInspectorActive = false,
+  isThumbnailActive = false,
+  thumbnailLabel = "thumbnail",
+  childCount = 0,
   onHoverStart,
   onHoverEnd,
   onPointerDown,
   onResizeStart,
+  onInspectorClick,
+  onThumbnailClick,
   onClick,
   onDoubleClick,
   children,
@@ -62,7 +120,38 @@ export const TimelineClip = memo(function TimelineClip({
         : theme.clipShadow;
   const capabilities = getTimelineEditCapabilities(el);
   const displayLabel = el.label || el.id || el.tag;
+  const inspectorLabel =
+    childCount > 0
+      ? `${childCount} nested selectable layer${childCount === 1 ? "" : "s"}`
+      : "Inspect clip layer";
   const showHandles = handleOpacity > 0.01;
+  const baseBackgroundImage = isSelected ? theme.clipBackgroundActive : theme.clipBackground;
+  const controlPresentation = getTimelineClipControlPresentation({
+    widthPx,
+    isSelected,
+    isHovered,
+    isInspectorActive,
+    isThumbnailActive,
+    isDragging,
+  });
+  const glossBackgroundImage = isSelected
+    ? "linear-gradient(180deg, rgba(255,255,255,0.03), rgba(255,255,255,0))"
+    : "linear-gradient(180deg, rgba(255,255,255,0.02), rgba(255,255,255,0))";
+  const accentBackgroundImage = `linear-gradient(120deg, ${trackStyle.accent}${
+    isSelected ? "22" : "1e"
+  }, transparent 28%)`;
+  const compositionStripeBackgroundImage =
+    isComposition && !hasCustomContent
+      ? "repeating-linear-gradient(135deg, transparent, transparent 3px, rgba(255,255,255,0.05) 3px, rgba(255,255,255,0.05) 6px)"
+      : undefined;
+  const clipBackgroundImage = [
+    compositionStripeBackgroundImage,
+    glossBackgroundImage,
+    accentBackgroundImage,
+    baseBackgroundImage,
+  ]
+    .filter(Boolean)
+    .join(", ");
 
   return (
     <div
@@ -76,13 +165,7 @@ export const TimelineClip = memo(function TimelineClip({
         top: clipY,
         bottom: clipY,
         borderRadius: theme.clipRadius,
-        background: isSelected
-          ? `linear-gradient(180deg, rgba(255,255,255,0.03), rgba(255,255,255,0)), linear-gradient(120deg, ${trackStyle.accent}22, transparent 28%), ${theme.clipBackgroundActive}`
-          : `linear-gradient(180deg, rgba(255,255,255,0.02), rgba(255,255,255,0)), linear-gradient(120deg, ${trackStyle.accent}1e, transparent 28%), ${theme.clipBackground}`,
-        backgroundImage:
-          isComposition && !hasCustomContent
-            ? `repeating-linear-gradient(135deg, transparent, transparent 3px, rgba(255,255,255,0.05) 3px, rgba(255,255,255,0.05) 6px)`
-            : undefined,
+        backgroundImage: clipBackgroundImage,
         border: `1px solid ${borderColor}`,
         boxShadow,
         transition:
@@ -102,6 +185,157 @@ export const TimelineClip = memo(function TimelineClip({
       onClick={onClick}
       onDoubleClick={onDoubleClick}
     >
+      {childCount > 0 && controlPresentation.showControls && (
+        <button
+          type="button"
+          className={`absolute flex items-center gap-1 rounded-md border border-studio-accent/30 bg-neutral-950/75 text-[10px] font-semibold tabular-nums text-studio-accent shadow-lg shadow-black/25 backdrop-blur transition-colors hover:border-studio-accent/60 hover:bg-studio-accent/15 ${
+            controlPresentation.compact ? "left-1 top-1 h-5 px-1" : "left-2 top-2 h-6 px-1.5"
+          }`}
+          style={{ zIndex: TIMELINE_CLIP_CONTROL_Z_INDEX }}
+          title={inspectorLabel}
+          aria-label={inspectorLabel}
+          onPointerDown={(event) => {
+            event.stopPropagation();
+          }}
+          onClick={(event) => {
+            event.stopPropagation();
+            onInspectorClick?.(event);
+          }}
+        >
+          <svg
+            width={controlPresentation.compact ? "11" : "13"}
+            height={controlPresentation.compact ? "11" : "13"}
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="1.8"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            aria-hidden="true"
+          >
+            <rect x="4" y="4" width="6" height="6" rx="1" />
+            <rect x="14" y="4" width="6" height="6" rx="1" />
+            <rect x="4" y="14" width="6" height="6" rx="1" />
+            <path d="M14 17h6" />
+          </svg>
+          {childCount}
+        </button>
+      )}
+      {onInspectorClick &&
+        controlPresentation.compact &&
+        !controlPresentation.showControls &&
+        !isDragging && (
+          <button
+            type="button"
+            className="group/clip-inspect absolute right-1 top-1/2 flex h-7 w-2 -translate-y-1/2 items-center justify-center rounded-full border border-white/15 bg-neutral-950/70 text-neutral-300 shadow-lg shadow-black/25 backdrop-blur transition-all hover:w-5 hover:border-white/30 hover:bg-neutral-950/90 focus:w-5 focus:border-studio-accent/60 focus:bg-studio-accent/15 focus:outline-none"
+            style={{ zIndex: TIMELINE_CLIP_CONTROL_Z_INDEX }}
+            title={inspectorLabel}
+            aria-label={inspectorLabel}
+            onPointerDown={(event) => {
+              event.stopPropagation();
+            }}
+            onClick={(event) => {
+              event.stopPropagation();
+              onInspectorClick(event);
+            }}
+          >
+            <svg
+              className="opacity-0 transition-opacity group-hover/clip-inspect:opacity-100 group-focus/clip-inspect:opacity-100"
+              width="12"
+              height="12"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="1.8"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              aria-hidden="true"
+            >
+              <path d="M2 12s3.5-6 10-6 10 6 10 6-3.5 6-10 6S2 12 2 12Z" />
+              <circle cx="12" cy="12" r="3" />
+            </svg>
+          </button>
+        )}
+      {(onThumbnailClick || onInspectorClick) && controlPresentation.showControls && (
+        <div
+          className={controlPresentation.containerClassName}
+          style={{ zIndex: TIMELINE_CLIP_CONTROL_Z_INDEX }}
+        >
+          {onThumbnailClick && (
+            <button
+              type="button"
+              className={`${controlPresentation.buttonClassName} border shadow-lg shadow-black/25 backdrop-blur transition-colors ${
+                isThumbnailActive
+                  ? "border-studio-accent/60 bg-studio-accent/18 text-studio-accent"
+                  : "border-white/12 bg-neutral-950/70 text-neutral-400 hover:border-white/24 hover:text-neutral-100"
+              }`}
+              title={
+                isThumbnailActive ? `Hide clip ${thumbnailLabel}` : `Show clip ${thumbnailLabel}`
+              }
+              aria-label={
+                isThumbnailActive ? `Hide clip ${thumbnailLabel}` : `Show clip ${thumbnailLabel}`
+              }
+              onPointerDown={(event) => {
+                event.stopPropagation();
+              }}
+              onClick={(event) => {
+                event.stopPropagation();
+                onThumbnailClick(event);
+              }}
+            >
+              <svg
+                width={controlPresentation.iconSize}
+                height={controlPresentation.iconSize}
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="1.8"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                aria-hidden="true"
+              >
+                <rect x="3" y="5" width="18" height="14" rx="2" />
+                <circle cx="8" cy="10" r="1.5" />
+                <path d="m4 17 5-5 4 4 2-2 5 5" />
+              </svg>
+            </button>
+          )}
+          {onInspectorClick && (
+            <button
+              type="button"
+              className={`${controlPresentation.buttonClassName} border shadow-lg shadow-black/25 backdrop-blur transition-colors ${
+                isInspectorActive
+                  ? "border-studio-accent/60 bg-studio-accent/18 text-studio-accent"
+                  : "border-white/12 bg-neutral-950/70 text-neutral-400 hover:border-white/24 hover:text-neutral-100"
+              }`}
+              title={inspectorLabel}
+              aria-label={inspectorLabel}
+              onPointerDown={(event) => {
+                event.stopPropagation();
+              }}
+              onClick={(event) => {
+                event.stopPropagation();
+                onInspectorClick(event);
+              }}
+            >
+              <svg
+                width={controlPresentation.iconSize}
+                height={controlPresentation.iconSize}
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="1.8"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                aria-hidden="true"
+              >
+                <path d="M2 12s3.5-6 10-6 10 6 10 6-3.5 6-10 6S2 12 2 12Z" />
+                <circle cx="12" cy="12" r="3" />
+              </svg>
+            </button>
+          )}
+        </div>
+      )}
       <div
         aria-hidden="true"
         role="presentation"

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

@@ -248,13 +248,28 @@ describe("getTimelineEditCapabilities", () => {
     });
   });
 
-  it("disables move and trims for generic motion clips even when patchable", () => {
+  it("allows moving generic motion clips while keeping trims blocked", () => {
     expect(
       getTimelineEditCapabilities({
         tag: "section",
         duration: 2,
         selector: ".feature-card",
       }),
+    ).toEqual({
+      canMove: true,
+      canTrimStart: false,
+      canTrimEnd: false,
+    });
+  });
+
+  it("keeps implicit layout layers selectable but not timeline-editable", () => {
+    expect(
+      getTimelineEditCapabilities({
+        duration: 8,
+        selector: ".scene-shell",
+        tag: "div",
+        timingSource: "implicit",
+      }),
     ).toEqual({
       canMove: false,
       canTrimStart: false,
@@ -428,7 +443,6 @@ describe("buildClipRangeSelection", () => {
     });
   });
 });
-
 describe("resolveTimelineAutoScroll", () => {
   it("does not scroll when the pointer stays away from the edges", () => {
     expect(
@@ -512,7 +526,6 @@ describe("buildTimelineElementAgentPrompt", () => {
     ).toContain("If this clip is animated with GSAP");
   });
 });
-
 describe("resolveTimelineResize", () => {
   it("shrinks clip duration from the right edge", () => {
     expect(

package/src/player/components/timelineEditing.ts

@@ -228,12 +228,21 @@ export function getTimelineEditCapabilities(input: {
   playbackStart?: number;
   playbackStartAttr?: "media-start" | "playback-start";
   sourceDuration?: number;
+  timingSource?: "authored" | "implicit";
 }): TimelineEditCapabilities {
+  if (input.timingSource === "implicit") {
+    return {
+      canMove: false,
+      canTrimStart: false,
+      canTrimEnd: false,
+    };
+  }
+
   const canPatch = hasPatchableTimelineTarget(input);
   const hasFiniteDuration = Number.isFinite(input.duration) && input.duration > 0;
   const hasDeterministicWindow = isDeterministicTimelineWindow(input);
   return {
-    canMove: canPatch && hasDeterministicWindow,
+    canMove: canPatch && (hasDeterministicWindow || hasFiniteDuration),
     canTrimEnd: canPatch && hasFiniteDuration && hasDeterministicWindow,
     canTrimStart: canPatch && hasFiniteDuration && canOffsetTrimClipStart(input),
   };
@@ -273,7 +282,6 @@ export function buildClipRangeSelection(
     anchorY: anchor.anchorY,
   };
 }
-
 export function buildTimelineAgentPrompt({
   rangeStart,
   rangeEnd,
@@ -347,7 +355,6 @@ export function buildTimelineElementAgentPrompt(element: {
 
   return lines.join("\n");
 }
-
 export function formatTimelineAttributeNumber(value: number): string {
   return Number(roundToCentiseconds(value).toFixed(2)).toString();
 }

package/src/player/hooks/useTimelinePlayer.test.ts

@@ -2,10 +2,12 @@ import { describe, expect, it } from "vitest";
 import { Window } from "happy-dom";
 import {
   buildStandaloneRootTimelineElement,
+  createStaticSeekPlaybackAdapter,
   createTimelineElementFromManifestClip,
   findTimelineDomNodeForClip,
   getTimelineElementSelector,
   parseTimelineFromDOM,
+  readTimelineDurationFromDocument,
   type ClipManifestClip,
   mergeTimelineElementsPreservingDowngrades,
   resolveStandaloneRootCompositionSrc,
@@ -13,6 +15,30 @@ import {
   shouldIgnorePlaybackShortcutTarget,
 } from "./useTimelinePlayer";
 
+function createDocument(markup: string): Document {
+  const window = new Window();
+  Object.assign(window, { SyntaxError });
+  window.document.body.innerHTML = markup;
+  return window.document;
+}
+
+function createClip(overrides: Partial<ClipManifestClip>): ClipManifestClip {
+  return {
+    id: null,
+    label: "",
+    start: 0,
+    duration: 4,
+    track: 0,
+    kind: "element",
+    tagName: "div",
+    compositionId: null,
+    parentCompositionId: null,
+    compositionSrc: null,
+    assetUrl: null,
+    ...overrides,
+  };
+}
+
 function mockTargetMatching(selectorNeedle: string): EventTarget {
   return {
     closest: (selector: string) => (selector.includes(selectorNeedle) ? ({} as Element) : null),
@@ -33,29 +59,102 @@ function mockKeyboardEvent(
   };
 }
 
-function createDocument(markup: string): Document {
-  const window = new Window();
-  window.document.body.innerHTML = markup;
-  return window.document;
-}
-
-function createClip(overrides: Partial<ClipManifestClip>): ClipManifestClip {
+function createManualAnimationClock() {
+  let now = 0;
+  let nextId = 0;
+  const callbacks = new Map<number, FrameRequestCallback>();
   return {
-    id: null,
-    label: "Element",
-    start: 0,
-    duration: 4,
-    track: 0,
-    kind: "element",
-    tagName: "div",
-    compositionId: null,
-    parentCompositionId: null,
-    compositionSrc: null,
-    assetUrl: null,
-    ...overrides,
+    now: () => now,
+    requestAnimationFrame: (callback: FrameRequestCallback) => {
+      nextId += 1;
+      callbacks.set(nextId, callback);
+      return nextId;
+    },
+    cancelAnimationFrame: (id: number) => {
+      callbacks.delete(id);
+    },
+    step: (milliseconds: number) => {
+      now += milliseconds;
+      const pending = Array.from(callbacks.entries());
+      callbacks.clear();
+      for (const [, callback] of pending) {
+        callback(now);
+      }
+    },
+    scheduledCount: () => callbacks.size,
   };
 }
 
+describe("readTimelineDurationFromDocument", () => {
+  it("prefers the root composition duration", () => {
+    const doc = createDocument(`
+      <div data-composition-id="main" data-duration="3">
+        <section data-start="0" data-duration="8"></section>
+      </div>
+    `);
+
+    expect(readTimelineDurationFromDocument(doc)).toBe(3);
+  });
+
+  it("falls back to the maximum child end time", () => {
+    const doc = createDocument(`
+      <div data-composition-id="main">
+        <section data-start="1" data-duration="2"></section>
+        <section data-start="4" data-duration="1.5"></section>
+      </div>
+    `);
+
+    expect(readTimelineDurationFromDocument(doc)).toBe(5.5);
+  });
+});
+
+describe("createStaticSeekPlaybackAdapter", () => {
+  it("drives renderSeek while playing a duration-only composition", () => {
+    const clock = createManualAnimationClock();
+    const renderedTimes: number[] = [];
+    const adapter = createStaticSeekPlaybackAdapter(
+      {
+        getTime: () => 0,
+        renderSeek: (time: number) => {
+          renderedTimes.push(time);
+        },
+      },
+      3,
+      clock,
+    );
+
+    adapter.seek(1);
+    adapter.play();
+    clock.step(500);
+    clock.step(2_000);
+
+    expect(renderedTimes).toEqual([1, 1.5, 3]);
+    expect(adapter.getTime()).toBe(3);
+    expect(adapter.isPlaying()).toBe(false);
+    expect(clock.scheduledCount()).toBe(0);
+  });
+
+  it("clamps explicit seeks to the fallback duration", () => {
+    const clock = createManualAnimationClock();
+    const renderedTimes: number[] = [];
+    const adapter = createStaticSeekPlaybackAdapter(
+      {
+        getTime: () => 0,
+        renderSeek: (time: number) => {
+          renderedTimes.push(time);
+        },
+      },
+      2,
+      clock,
+    );
+
+    adapter.seek(9);
+
+    expect(renderedTimes).toEqual([2]);
+    expect(adapter.getTime()).toBe(2);
+  });
+});
+
 describe("buildStandaloneRootTimelineElement", () => {
   it("includes selector and source metadata for standalone composition fallback clips", () => {
     expect(
@@ -150,6 +249,36 @@ describe("findTimelineDomNodeForClip", () => {
 });
 
 describe("anonymous timeline identity", () => {
+  it("adds root-level untimed DOM layers as implicit full-duration layers", () => {
+    const doc = createDocument(`
+      <div data-composition-id="compare" data-start="0" data-duration="18">
+        <link rel="stylesheet" href="styles.css" />
+        <div class="scene-shell">
+          <div class="topline">Title</div>
+        </div>
+        <video id="main-video" class="clip main-video" data-start="0" data-duration="18" data-track-index="1"></video>
+        <script></script>
+      </div>
+    `);
+
+    const elements = parseTimelineFromDOM(doc, 18);
+
+    expect(elements).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          duration: 18,
+          label: "Scene Shell",
+          selector: ".scene-shell",
+          start: 0,
+          tag: "div",
+          timingSource: "implicit",
+        }),
+      ]),
+    );
+    expect(elements.find((element) => element.tag === "link")).toBeUndefined();
+    expect(elements.find((element) => element.tag === "script")).toBeUndefined();
+  });
+
   it("keeps fallback-parsed anonymous clips distinct when labels match", () => {
     const doc = createDocument(`
       <div data-composition-id="main" data-start="0" data-duration="8">