@hyperframes/studio 0.5.5 → 0.6.0-alpha.1

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">

package/src/player/hooks/useTimelinePlayer.ts

@@ -4,7 +4,7 @@ import { useMountEffect } from "../../hooks/useMountEffect";
 import { stepFrameTime, STUDIO_PREVIEW_FPS } from "../lib/time";
 import { useCaptionStore } from "../../captions/store";
 
-interface PlaybackAdapter {
+export interface PlaybackAdapter {
   play: () => void;
   pause: () => void;
   seek: (time: number) => void;
@@ -13,6 +13,16 @@ interface PlaybackAdapter {
   isPlaying: () => boolean;
 }
 
+type RuntimePlaybackAdapter = PlaybackAdapter & {
+  renderSeek?: (time: number) => void;
+};
+
+interface StaticSeekPlaybackClock {
+  now: () => number;
+  requestAnimationFrame: (callback: FrameRequestCallback) => number;
+  cancelAnimationFrame: (handle: number) => void;
+}
+
 interface TimelineLike {
   play: () => void;
   pause: () => void;
@@ -22,7 +32,7 @@ interface TimelineLike {
   isActive: () => boolean;
 }
 
-interface ClipManifestClip {
+export interface ClipManifestClip {
   id: string | null;
   label: string;
   start: number;
@@ -43,12 +53,133 @@ interface ClipManifest {
 }
 
 type IframeWindow = Window & {
-  __player?: PlaybackAdapter;
+  __player?: RuntimePlaybackAdapter;
   __timeline?: TimelineLike;
   __timelines?: Record<string, TimelineLike>;
   __clipManifest?: ClipManifest;
 };
 
+function isFinitePositive(value: number): boolean {
+  return Number.isFinite(value) && value > 0;
+}
+
+function clampTime(time: number, duration: number): number {
+  const safeDuration = Math.max(0, Number.isFinite(duration) ? duration : 0);
+  const safeTime = Math.max(0, Number.isFinite(time) ? time : 0);
+  return safeDuration > 0 ? Math.min(safeTime, safeDuration) : safeTime;
+}
+
+function readDurationAttribute(el: Element | null | undefined): number {
+  if (!el) return 0;
+  const duration =
+    Number.parseFloat(el.getAttribute("data-duration") ?? "") ||
+    Number.parseFloat(el.getAttribute("data-hf-authored-duration") ?? "");
+  return isFinitePositive(duration) ? duration : 0;
+}
+
+export function readTimelineDurationFromDocument(doc: Document | null | undefined): number {
+  if (!doc) return 0;
+  const rootDuration = readDurationAttribute(doc.querySelector("[data-composition-id]"));
+  if (rootDuration > 0) return rootDuration;
+
+  let maxEnd = 0;
+  for (const node of Array.from(doc.querySelectorAll("[data-start]"))) {
+    const start = Number.parseFloat(node.getAttribute("data-start") ?? "");
+    const duration = readDurationAttribute(node);
+    if (!Number.isFinite(start) || start < 0 || duration <= 0) continue;
+    maxEnd = Math.max(maxEnd, start + duration);
+  }
+  return maxEnd;
+}
+
+function getAdapterDuration(adapter: PlaybackAdapter | null | undefined): number {
+  if (!adapter) return 0;
+  try {
+    const duration = Number(adapter.getDuration());
+    return isFinitePositive(duration) ? duration : 0;
+  } catch {
+    return 0;
+  }
+}
+
+function getDefaultStaticSeekPlaybackClock(win: Window): StaticSeekPlaybackClock {
+  return {
+    now: () => win.performance.now(),
+    requestAnimationFrame: (callback) => win.requestAnimationFrame(callback),
+    cancelAnimationFrame: (handle) => win.cancelAnimationFrame(handle),
+  };
+}
+
+export function createStaticSeekPlaybackAdapter(
+  player: Pick<RuntimePlaybackAdapter, "getTime"> &
+    Partial<Pick<RuntimePlaybackAdapter, "renderSeek" | "seek">>,
+  duration: number,
+  clock: StaticSeekPlaybackClock,
+  getPlaybackRate: () => number = () => 1,
+): PlaybackAdapter {
+  const safeDuration = Math.max(0, Number.isFinite(duration) ? duration : 0);
+  let currentTime = clampTime(Number(player.getTime?.() ?? 0), safeDuration);
+  let playing = false;
+  let rafId = 0;
+  let playStartTime = currentTime;
+  let playStartNow = clock.now();
+
+  const renderSeek = (time: number) => {
+    currentTime = clampTime(time, safeDuration);
+    if (typeof player.renderSeek === "function") {
+      player.renderSeek(currentTime);
+      return;
+    }
+    player.seek?.(currentTime);
+  };
+
+  const stopTicker = () => {
+    if (rafId) {
+      clock.cancelAnimationFrame(rafId);
+      rafId = 0;
+    }
+  };
+
+  const tick: FrameRequestCallback = (now) => {
+    if (!playing) return;
+    const playbackRate = Math.max(0.1, Number(getPlaybackRate()) || 1);
+    const elapsed = ((now - playStartNow) / 1000) * playbackRate;
+    renderSeek(playStartTime + elapsed);
+    if (currentTime >= safeDuration) {
+      playing = false;
+      rafId = 0;
+      return;
+    }
+    rafId = clock.requestAnimationFrame(tick);
+  };
+
+  return {
+    play: () => {
+      if (playing || safeDuration <= 0) return;
+      if (currentTime >= safeDuration) renderSeek(0);
+      playing = true;
+      playStartTime = currentTime;
+      playStartNow = clock.now();
+      stopTicker();
+      rafId = clock.requestAnimationFrame(tick);
+    },
+    pause: () => {
+      playing = false;
+      stopTicker();
+    },
+    seek: (time) => {
+      renderSeek(time);
+      if (playing) {
+        playStartTime = currentTime;
+        playStartNow = clock.now();
+      }
+    },
+    getTime: () => currentTime,
+    getDuration: () => safeDuration,
+    isPlaying: () => playing,
+  };
+}
+
 function wrapTimeline(tl: TimelineLike): PlaybackAdapter {
   return {
     play: () => tl.play(),
@@ -183,6 +314,100 @@ function getTimelineElementDisplayLabel(input: {
   return tag ? `${tag} clip` : "Timeline clip";
 }
 
+const IMPLICIT_TIMELINE_LAYER_SKIP_TAGS = new Set([
+  "base",
+  "link",
+  "meta",
+  "noscript",
+  "script",
+  "style",
+  "template",
+]);
+
+function humanizeTimelineIdentifier(value: string): string {
+  return value
+    .trim()
+    .replace(/[_-]+/g, " ")
+    .replace(/\s+/g, " ")
+    .replace(/\b\w/g, (match) => match.toUpperCase());
+}
+
+function getImplicitTimelineLayerLabel(el: HTMLElement): string {
+  const explicitLabel =
+    el.getAttribute("data-timeline-label") ??
+    el.getAttribute("data-label") ??
+    el.getAttribute("aria-label");
+  if (explicitLabel?.trim()) return explicitLabel.trim();
+  if (el.id.trim()) return humanizeTimelineIdentifier(el.id);
+  const classes = el.className.split(/\s+/).filter(Boolean);
+  const className = classes.find((value) => value !== "clip") ?? classes[0];
+  if (className) return humanizeTimelineIdentifier(className);
+  return getTimelineElementDisplayLabel({ tag: el.tagName });
+}
+
+function isImplicitTimelineLayerCandidate(root: Element, el: Element): el is HTMLElement {
+  if (!isHtmlElement(el)) return false;
+  if (el.parentElement !== root) return false;
+  const tagName = el.tagName.toLowerCase();
+  if (IMPLICIT_TIMELINE_LAYER_SKIP_TAGS.has(tagName)) return false;
+  if (el.hasAttribute("data-start") || el.hasAttribute("data-track-index")) return false;
+  return Boolean(getTimelineElementSelector(el));
+}
+
+export function createImplicitTimelineLayersFromDOM(
+  doc: Document,
+  rootDuration: number,
+  existingElements: readonly TimelineElement[] = [],
+): TimelineElement[] {
+  if (!Number.isFinite(rootDuration) || rootDuration <= 0) return [];
+  const rootComp = doc.querySelector("[data-composition-id]");
+  if (!rootComp) return [];
+
+  const existingKeys = new Set(existingElements.map(getTimelineElementIdentity));
+  const maxTrack = existingElements.reduce(
+    (max, element) => Math.max(max, Number.isFinite(element.track) ? element.track : 0),
+    -1,
+  );
+  const layers: TimelineElement[] = [];
+
+  for (const child of Array.from(rootComp.children)) {
+    if (!isImplicitTimelineLayerCandidate(rootComp, child)) continue;
+
+    const selector = getTimelineElementSelector(child);
+    if (!selector) continue;
+    const selectorIndex = getTimelineElementSelectorIndex(doc, child, selector);
+    const sourceFile = getTimelineElementSourceFile(child);
+    const label = getImplicitTimelineLayerLabel(child);
+    const identity = buildTimelineElementIdentity({
+      preferredId: child.id || null,
+      label,
+      fallbackIndex: existingElements.length + layers.length,
+      domId: child.id || undefined,
+      selector,
+      selectorIndex,
+      sourceFile,
+    });
+    if (existingKeys.has(identity.key) || existingKeys.has(identity.id)) continue;
+
+    layers.push({
+      domId: child.id || undefined,
+      duration: rootDuration,
+      id: identity.id,
+      key: identity.key,
+      label,
+      selector,
+      selectorIndex,
+      sourceFile,
+      start: 0,
+      tag: child.tagName.toLowerCase(),
+      timingSource: "implicit",
+      track: maxTrack + 1 + layers.length,
+    });
+  }
+
+  return layers;
+}
+
 /**
  * Parse [data-start] elements from a Document into TimelineElement[].
  * Shared helper — used by onIframeLoad fallback, handleMessage, and enrichMissingCompositions.
@@ -244,6 +469,7 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
       selector,
       selectorIndex,
       sourceFile,
+      timingSource: "authored",
     };
 
     const mediaEl = resolveMediaElement(el);
@@ -275,7 +501,7 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
     els.push(entry);
   });
 
-  return els;
+  return [...els, ...createImplicitTimelineLayersFromDOM(doc, rootDuration, els)];
 }
 
 function isHtmlElement(el: Element): el is HTMLElement {
@@ -335,7 +561,6 @@ function buildTimelineElementKey(params: {
   if (params.selector) return `${scope}:${params.selector}:${params.selectorIndex ?? 0}`;
   return `${scope}:${params.id}:${params.fallbackIndex}`;
 }
-
 function buildTimelineElementIdentity(params: {
   preferredId?: string | null;
   label: string;
@@ -557,7 +782,6 @@ export function buildStandaloneRootTimelineElement(params: {
     sourceFile: compositionSrc,
   };
 }
-
 function normalizePreviewViewport(doc: Document, win: Window): void {
   if (doc.documentElement) {
     doc.documentElement.style.overflow = "hidden";
@@ -682,6 +906,11 @@ export function useTimelinePlayer() {
   const iframeShortcutCleanupRef = useRef<(() => void) | null>(null);
   const playbackKeyDownRef = useRef<(e: KeyboardEvent) => void>(() => {});
   const playbackKeyUpRef = useRef<(e: KeyboardEvent) => void>(() => {});
+  const staticSeekAdapterRef = useRef<{
+    player: RuntimePlaybackAdapter;
+    duration: number;
+    adapter: PlaybackAdapter;
+  } | null>(null);
 
   // ZERO store subscriptions — this hook never causes re-renders.
   // All reads use getState() (point-in-time), all writes use the stable setters.
@@ -710,13 +939,18 @@ export function useTimelinePlayer() {
     try {
       const iframe = iframeRef.current;
       const win = iframe?.contentWindow as IframeWindow | null;
-      if (!win) return null;
+      if (!iframe || !win) return null;
 
-      if (win.__player && typeof win.__player.play === "function") {
-        return win.__player;
+      const playerAdapter =
+        win.__player && typeof win.__player.play === "function" ? win.__player : null;
+      if (getAdapterDuration(playerAdapter) > 0) {
+        return playerAdapter;
       }
 
-      if (win.__timeline) return wrapTimeline(win.__timeline);
+      if (win.__timeline) {
+        const adapter = wrapTimeline(win.__timeline);
+        if (getAdapterDuration(adapter) > 0) return adapter;
+      }
 
       if (win.__timelines) {
         const keys = Object.keys(win.__timelines);
@@ -729,11 +963,40 @@ export function useTimelinePlayer() {
             ?.querySelector("[data-composition-id]")
             ?.getAttribute("data-composition-id");
           const key = rootId && rootId in win.__timelines ? rootId : keys[keys.length - 1];
-          return wrapTimeline(win.__timelines[key]);
+          const adapter = wrapTimeline(win.__timelines[key]);
+          if (getAdapterDuration(adapter) > 0) return adapter;
         }
       }
 
-      return null;
+      const fallbackDuration = Math.max(
+        usePlayerStore.getState().duration,
+        readTimelineDurationFromDocument(iframe.contentDocument),
+      );
+      if (
+        playerAdapter &&
+        fallbackDuration > 0 &&
+        (typeof playerAdapter.renderSeek === "function" || typeof playerAdapter.seek === "function")
+      ) {
+        const cached = staticSeekAdapterRef.current;
+        if (cached?.player === playerAdapter && cached.duration === fallbackDuration) {
+          return cached.adapter;
+        }
+        cached?.adapter.pause();
+        const adapter = createStaticSeekPlaybackAdapter(
+          playerAdapter,
+          fallbackDuration,
+          getDefaultStaticSeekPlaybackClock(win),
+          () => usePlayerStore.getState().playbackRate,
+        );
+        staticSeekAdapterRef.current = {
+          player: playerAdapter,
+          duration: fallbackDuration,
+          adapter,
+        };
+        return adapter;
+      }
+
+      return playerAdapter;
     } catch (err) {
       console.warn("[useTimelinePlayer] Could not get playback adapter (cross-origin)", err);
       return null;
@@ -1066,8 +1329,15 @@ export function useTimelinePlayer() {
               }))
               .filter((element) => element.duration > 0)
           : els;
-      if (clampedEls.length > 0) {
-        syncTimelineElements(clampedEls, newDuration > 0 ? newDuration : undefined);
+      const timelineEls =
+        iframeDoc && effectiveDuration > 0
+          ? [
+              ...clampedEls,
+              ...createImplicitTimelineLayersFromDOM(iframeDoc, effectiveDuration, clampedEls),
+            ]
+          : clampedEls;
+      if (timelineEls.length > 0) {
+        syncTimelineElements(timelineEls, newDuration > 0 ? newDuration : undefined);
       }
     },
     [syncTimelineElements],
@@ -1351,6 +1621,9 @@ export function useTimelinePlayer() {
     setIsPlaying(false);
   }, [getAdapter, stopRAFLoop, setIsPlaying, stopReverseLoop]);
 
+  const togglePlayRef = useRef(togglePlay);
+  togglePlayRef.current = togglePlay;
+
   const refreshPlayer = useCallback(() => {
     const iframe = iframeRef.current;
     if (!iframe) return;
@@ -1459,8 +1732,6 @@ export function useTimelinePlayer() {
       stopRAFLoop();
       stopReverseLoop();
       if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
-      // Don't reset() on cleanup — preserve timeline elements across iframe refreshes
-      // to prevent blink. New data will replace old when the iframe reloads.
     };
   });
 

package/src/player/store/playerStore.ts

@@ -23,6 +23,8 @@ export interface TimelineElement {
   volume?: number;
   /** Path from data-composition-src — identifies sub-composition elements */
   compositionSrc?: string;
+  /** Whether this row came from authored clip timing or Studio's full-duration layer fallback. */
+  timingSource?: "authored" | "implicit";
 }
 
 export type ZoomMode = "fit" | "manual";