@hyperframes/studio 0.6.0-alpha.8 → 0.6.0

package/src/player/hooks/useTimelinePlayer.ts

@@ -906,6 +906,7 @@ export function useTimelinePlayer() {
   const iframeShortcutCleanupRef = useRef<(() => void) | null>(null);
   const playbackKeyDownRef = useRef<(e: KeyboardEvent) => void>(() => {});
   const playbackKeyUpRef = useRef<(e: KeyboardEvent) => void>(() => {});
+  const lastTimelineMessageRef = useRef<number>(0);
   const staticSeekAdapterRef = useRef<{
     player: RuntimePlaybackAdapter;
     duration: number;
@@ -920,17 +921,40 @@ export function useTimelinePlayer() {
   const syncTimelineElements = useCallback(
     (elements: TimelineElement[], nextDuration?: number) => {
       const state = usePlayerStore.getState();
+      const resolvedDuration = nextDuration ?? state.duration;
       const mergedElements = mergeTimelineElementsPreservingDowngrades(
         state.elements,
         elements,
         state.duration,
-        nextDuration ?? state.duration,
+        resolvedDuration,
       );
-      setElements(mergedElements);
-      if (Number.isFinite(nextDuration) && (nextDuration ?? 0) > 0) {
+
+      const elementsChanged =
+        mergedElements.length !== state.elements.length ||
+        mergedElements.some((el, i) => {
+          const prev = state.elements[i];
+          return (
+            !prev ||
+            el.id !== prev.id ||
+            el.start !== prev.start ||
+            el.duration !== prev.duration ||
+            el.track !== prev.track
+          );
+        });
+
+      if (elementsChanged) {
+        setElements(mergedElements);
+      }
+      if (
+        Number.isFinite(nextDuration) &&
+        (nextDuration ?? 0) > 0 &&
+        nextDuration !== state.duration
+      ) {
         setDuration(nextDuration ?? 0);
       }
-      setTimelineReady(true);
+      if (!state.timelineReady) {
+        setTimelineReady(true);
+      }
     },
     [setElements, setTimelineReady, setDuration],
   );
@@ -1501,102 +1525,70 @@ export function useTimelinePlayer() {
     }
   }, [syncTimelineElements]);
 
-  const onIframeLoad = useCallback(() => {
-    unmutePreviewMedia(iframeRef.current);
-
-    let attempts = 0;
-    const maxAttempts = 25;
-
-    if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
-
-    probeIntervalRef.current = setInterval(() => {
-      attempts++;
-      const adapter = getAdapter();
-      if (adapter && adapter.getDuration() > 0) {
-        clearInterval(probeIntervalRef.current);
-        adapter.pause();
-
-        const seekTo = pendingSeekRef.current;
-        pendingSeekRef.current = null;
-        const startTime = seekTo != null ? Math.min(seekTo, adapter.getDuration()) : 0;
-
-        adapter.seek(startTime);
-        const adapterDur = adapter.getDuration();
-        // Cap at 7200s (2h) to guard against loop-inflated GSAP timelines
-        if (Number.isFinite(adapterDur) && adapterDur > 0 && adapterDur < 7200)
-          setDuration(adapterDur);
-        setCurrentTime(startTime);
-        if (!isRefreshingRef.current) {
-          setTimelineReady(true);
-        }
-        isRefreshingRef.current = false;
-        setIsPlaying(false);
+  const initializeAdapter = useCallback(() => {
+    const adapter = getAdapter();
+    if (!adapter || adapter.getDuration() <= 0) return false;
 
-        try {
-          const iframe = iframeRef.current;
-          const doc = iframe?.contentDocument;
-          const iframeWin = iframe?.contentWindow as IframeWindow | null;
-          if (doc && iframeWin) {
-            normalizePreviewViewport(doc, iframeWin);
-            autoHealMissingCompositionIds(doc);
-            attachIframeShortcutListeners();
-          }
+    adapter.pause();
+    const seekTo = pendingSeekRef.current;
+    pendingSeekRef.current = null;
+    const startTime = seekTo != null ? Math.min(seekTo, adapter.getDuration()) : 0;
+
+    adapter.seek(startTime);
+    const adapterDur = adapter.getDuration();
+    if (
+      Number.isFinite(adapterDur) &&
+      adapterDur > 0 &&
+      adapterDur < 7200 &&
+      adapterDur !== usePlayerStore.getState().duration
+    ) {
+      setDuration(adapterDur);
+    }
+    setCurrentTime(startTime);
+    if (!isRefreshingRef.current) {
+      setTimelineReady(true);
+    }
+    isRefreshingRef.current = false;
+    setIsPlaying(false);
 
-          // Try reading __clipManifest if already available (fast path)
-          const manifest = iframeWin?.__clipManifest;
-          if (manifest && manifest.clips.length > 0) {
-            processTimelineMessage(manifest);
-          }
-          // Enrich: fill in composition hosts the manifest missed
-          enrichMissingCompositions();
-
-          // Run DOM fallback if still no elements were populated
-          // (manifest may exist but all clips filtered out by parentCompositionId logic)
-          if (usePlayerStore.getState().elements.length === 0 && doc) {
-            // Fallback: parse data-start elements directly from DOM (raw HTML without runtime)
-            const els = parseTimelineFromDOM(doc, adapter.getDuration());
-            if (els.length > 0) {
-              syncTimelineElements(els);
-            }
-          }
+    try {
+      const iframe = iframeRef.current;
+      const doc = iframe?.contentDocument;
+      const iframeWin = iframe?.contentWindow as IframeWindow | null;
+      if (doc && iframeWin) {
+        normalizePreviewViewport(doc, iframeWin);
+        autoHealMissingCompositionIds(doc);
+        attachIframeShortcutListeners();
+      }
 
-          // Final fallback for standalone composition previews: if still no
-          // elements, build timeline entries from the DOM inside the root
-          // composition. This ensures the timeline always shows content when
-          // viewing a single composition (where elements lack data-start).
-          if (usePlayerStore.getState().elements.length === 0 && doc) {
-            const rootComp = doc.querySelector("[data-composition-id]");
-            const rootDuration = adapter.getDuration();
-            if (rootComp && rootDuration > 0) {
-              const fallbackElement = buildStandaloneRootTimelineElement({
-                compositionId: rootComp.getAttribute("data-composition-id") || "composition",
-                tagName: (rootComp as HTMLElement).tagName || "div",
-                rootDuration,
-                iframeSrc: iframe?.src || "",
-                selector: getTimelineElementSelector(rootComp),
-              });
-              if (fallbackElement) {
-                // Always show the root composition as a single clip — guarantees
-                // the timeline is never empty when a valid composition is loaded.
-                syncTimelineElements([fallbackElement]);
-              }
-            }
-          }
-          // The runtime will also postMessage the full timeline after all compositions load.
-          // That message is handled by the window listener below, which will update elements
-          // with the complete data (including async-loaded compositions).
-        } catch (err) {
-          console.warn("[useTimelinePlayer] Could not read timeline elements from iframe", err);
-        }
+      const manifest = iframeWin?.__clipManifest;
+      if (manifest && manifest.clips.length > 0) {
+        processTimelineMessage(manifest);
+      }
+      enrichMissingCompositions();
 
-        return;
+      if (usePlayerStore.getState().elements.length === 0 && doc) {
+        const els = parseTimelineFromDOM(doc, adapter.getDuration());
+        if (els.length > 0) syncTimelineElements(els);
       }
-      if (attempts >= maxAttempts) {
-        clearInterval(probeIntervalRef.current);
-        console.warn("Could not find __player, __timeline, or __timelines on iframe after 5s");
+      if (usePlayerStore.getState().elements.length === 0 && doc) {
+        const rootComp = doc.querySelector("[data-composition-id]");
+        const rootDuration = adapter.getDuration();
+        if (rootComp && rootDuration > 0) {
+          const fallbackElement = buildStandaloneRootTimelineElement({
+            compositionId: rootComp.getAttribute("data-composition-id") || "composition",
+            tagName: (rootComp as HTMLElement).tagName || "div",
+            rootDuration,
+            iframeSrc: iframe?.src || "",
+            selector: getTimelineElementSelector(rootComp),
+          });
+          if (fallbackElement) syncTimelineElements([fallbackElement]);
+        }
       }
-    }, 200);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
+    } catch (err) {
+      console.warn("[useTimelinePlayer] Could not read timeline elements from iframe", err);
+    }
+    return true;
   }, [
     getAdapter,
     setDuration,
@@ -1609,6 +1601,50 @@ export function useTimelinePlayer() {
     attachIframeShortcutListeners,
   ]);
 
+  const onIframeLoad = useCallback(() => {
+    unmutePreviewMedia(iframeRef.current);
+    if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+
+    // Fast path: adapter already available (in-place reloads, cached compositions)
+    if (initializeAdapter()) return;
+
+    // The runtime posts "state" or "timeline" messages once ready.
+    // Listen for those instead of polling. Use a short-lived message
+    // listener that fires initializeAdapter on the first signal.
+    const iframe = iframeRef.current;
+    let settled = false;
+
+    const trySettle = () => {
+      if (settled) return;
+      if (initializeAdapter()) {
+        settled = true;
+        window.removeEventListener("message", onMessage);
+        if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+      }
+    };
+
+    const onMessage = (e: MessageEvent) => {
+      if (e.source && iframe && e.source !== iframe.contentWindow) return;
+      const data = e.data;
+      if (data?.source === "hf-preview" && (data?.type === "state" || data?.type === "timeline")) {
+        trySettle();
+      }
+    };
+    window.addEventListener("message", onMessage);
+
+    // Safety net: if no message arrives within 5s, try one last time then give up.
+    // This replaces the old 25×200ms polling loop with a single delayed check.
+    probeIntervalRef.current = setTimeout(() => {
+      if (!settled) {
+        trySettle();
+        if (!settled) {
+          console.warn("[useTimelinePlayer] Runtime did not signal readiness within 5s");
+        }
+      }
+      window.removeEventListener("message", onMessage);
+    }, 5000) as unknown as ReturnType<typeof setInterval>;
+  }, [initializeAdapter]);
+
   /** Save the current playback time so the next onIframeLoad restores it. */
   const saveSeekPosition = useCallback(() => {
     const adapter = getAdapter();
@@ -1668,23 +1704,24 @@ export function useTimelinePlayer() {
               processTimelineMessageRef.current(manifest);
             }
           }
-          // Always try to enrich — timelines may have registered since the last check
-          enrichMissingCompositionsRef.current();
+          // Enrich only when the timeline has settled — skip during the window
+          // right after a "timeline" message to avoid the enrichment adding
+          // elements that fight with the manifest's authoritative element list,
+          // causing duration oscillation (the merge function alternates between
+          // REPLACE and PRESERVE when element counts fluctuate).
+          const msSinceTimeline = Date.now() - lastTimelineMessageRef.current;
+          if (msSinceTimeline > 500) {
+            enrichMissingCompositionsRef.current();
+          }
         } catch (err) {
           console.warn("[useTimelinePlayer] Could not read clip manifest from iframe", err);
         }
       }
       if (data?.source === "hf-preview" && data?.type === "timeline" && Array.isArray(data.clips)) {
+        lastTimelineMessageRef.current = Date.now();
         processTimelineMessageRef.current(data);
         // Fill in composition hosts the manifest missed (element-reference starts)
         enrichMissingCompositionsRef.current();
-        if (data.durationInFrames > 0 && Number.isFinite(data.durationInFrames)) {
-          const fps = 30;
-          const dur = data.durationInFrames / fps;
-          if (dur > 0 && dur < 7200) {
-            usePlayerStore.getState().setDuration(dur);
-          }
-        }
         // If manifest produced 0 elements after filtering, try DOM fallback
         if (usePlayerStore.getState().elements.length === 0) {
           try {

package/src/utils/domEditHelpers.ts

@@ -0,0 +1,50 @@
+import type { DomEditSelection } from "../components/editor/domEditing";
+import { getDomEditTargetKey } from "../components/editor/domEditing";
+
+export function domEditSelectionsTargetSame(
+  a: DomEditSelection | null,
+  b: DomEditSelection | null,
+): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return getDomEditTargetKey(a) === getDomEditTargetKey(b);
+}
+
+export function domEditSelectionInGroup(
+  group: DomEditSelection[],
+  selection: DomEditSelection | null,
+): boolean {
+  if (!selection) return false;
+  return group.some((entry) => domEditSelectionsTargetSame(entry, selection));
+}
+
+export function toggleDomEditGroupSelection(
+  group: DomEditSelection[],
+  selection: DomEditSelection,
+): DomEditSelection[] {
+  if (domEditSelectionInGroup(group, selection)) {
+    return group.filter((entry) => !domEditSelectionsTargetSame(entry, selection));
+  }
+  return [...group, selection];
+}
+
+export function replaceDomEditGroupSelection(
+  group: DomEditSelection[],
+  selection: DomEditSelection,
+): DomEditSelection[] {
+  let replaced = false;
+  const nextGroup = group.map((entry) => {
+    if (!domEditSelectionsTargetSame(entry, selection)) return entry;
+    replaced = true;
+    return selection;
+  });
+  return replaced ? nextGroup : [...group, selection];
+}
+
+export function seedDomEditGroupWithSelection(
+  group: DomEditSelection[],
+  selection: DomEditSelection | null,
+): DomEditSelection[] {
+  if (!selection || domEditSelectionInGroup(group, selection)) return group;
+  return [selection, ...group];
+}

package/src/utils/studioFontHelpers.ts

@@ -0,0 +1,83 @@
+import { googleFontStylesheetUrl } from "../components/editor/fontCatalog";
+import { importedFontFaceCss, type ImportedFontAsset } from "../components/editor/fontAssets";
+import { toRelativeProjectAssetPath } from "./studioHelpers";
+
+const GENERIC_FONT_FAMILIES = new Set([
+  "inherit",
+  "initial",
+  "revert",
+  "revert-layer",
+  "serif",
+  "sans-serif",
+  "monospace",
+  "cursive",
+  "fantasy",
+  "system-ui",
+  "ui-sans-serif",
+  "ui-serif",
+  "ui-monospace",
+  "ui-rounded",
+  "emoji",
+  "math",
+  "fangsong",
+]);
+
+export function primaryFontFamilyFromCss(value: string): string {
+  const first = value.split(",")[0] ?? "";
+  return first.trim().replace(/^["']|["']$/g, "");
+}
+
+export function primaryFontFamilyValue(value: string): string {
+  return (
+    value
+      .split(",")[0]
+      ?.trim()
+      .replace(/^["']|["']$/g, "")
+      .trim() ?? ""
+  );
+}
+
+export function injectPreviewGoogleFont(doc: Document, fontFamilyValue: string): void {
+  const family = primaryFontFamilyFromCss(fontFamilyValue);
+  if (!family || GENERIC_FONT_FAMILIES.has(family.toLowerCase())) return;
+
+  const id = `studio-preview-google-font-${family.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
+  if (doc.getElementById(id)) return;
+
+  const link = doc.createElement("link");
+  link.id = id;
+  link.rel = "stylesheet";
+  link.href = googleFontStylesheetUrl(family);
+  doc.head.appendChild(link);
+}
+
+export function injectPreviewImportedFont(doc: Document, asset: ImportedFontAsset): void {
+  const id = `studio-imported-font-${asset.family.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
+  if (doc.getElementById(id)) return;
+  const style = doc.createElement("style");
+  style.id = id;
+  style.textContent = importedFontFaceCss(asset);
+  doc.head.appendChild(style);
+}
+
+export function ensureImportedFontFace(
+  html: string,
+  asset: ImportedFontAsset,
+  sourceFile: string,
+): string {
+  const css = importedFontFaceCss(asset, toRelativeProjectAssetPath(sourceFile, asset.path));
+  if (html.includes(css)) return html;
+
+  const styleRe = /<style\b[^>]*data-hf-studio-fonts=(["'])true\1[^>]*>([\s\S]*?)<\/style>/i;
+  const styleMatch = styleRe.exec(html);
+  if (styleMatch) {
+    const nextCss = `${styleMatch[2].trim()}\n${css}`.trim();
+    return html.replace(styleMatch[0], `<style data-hf-studio-fonts="true">\n${nextCss}\n</style>`);
+  }
+
+  const styleTag = `<style data-hf-studio-fonts="true">\n${css}\n</style>`;
+  if (/<\/head>/i.test(html)) {
+    return html.replace(/<\/head>/i, `  ${styleTag}\n  </head>`);
+  }
+  return `${styleTag}\n${html}`;
+}

package/src/utils/studioHelpers.ts

@@ -0,0 +1,214 @@
+import type { TimelineElement } from "../player";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import type { TimelineAssetKind } from "./timelineAssetDrop";
+
+export interface EditingFile {
+  path: string;
+  content: string | null;
+}
+
+export interface AppToast {
+  message: string;
+  tone: "error" | "info";
+}
+
+export type RightPanelTab = "design" | "motion" | "renders";
+
+export interface AgentModalAnchorPoint {
+  x: number;
+  y: number;
+}
+
+export function getTimelineElementLabel(element: TimelineElement): string {
+  return element.label || element.id || element.tag;
+}
+
+export function confirmElementDelete(label: string, kind: "timeline clip" | "element"): boolean {
+  return window.confirm(
+    `Delete ${kind} "${label}"?\n\nThis removes it from the project source. You can use Undo to restore it.`,
+  );
+}
+
+export function normalizeProjectAssetPath(value: string): string {
+  const trimmed = value.trim();
+  const maybeUrl = /^[a-z]+:\/\//i.test(trimmed) ? new URL(trimmed).pathname : trimmed;
+  return decodeURIComponent(maybeUrl)
+    .replace(/\\/g, "/")
+    .replace(/^\.?\//, "");
+}
+
+export function toRelativeProjectAssetPath(sourceFile: string, assetPath: string): string {
+  const fromParts = normalizeProjectAssetPath(sourceFile).split("/").filter(Boolean);
+  const targetParts = normalizeProjectAssetPath(assetPath).split("/").filter(Boolean);
+
+  fromParts.pop();
+
+  while (fromParts.length > 0 && targetParts.length > 0 && fromParts[0] === targetParts[0]) {
+    fromParts.shift();
+    targetParts.shift();
+  }
+
+  return [...fromParts.map(() => ".."), ...targetParts].join("/") || assetPath;
+}
+
+export function isAbsoluteFilePath(value: string): boolean {
+  return /^(?:\/|[A-Za-z]:[\\/]|\\\\)/.test(value);
+}
+
+export function toProjectAbsolutePath(
+  projectDir: string | null,
+  sourceFile: string,
+): string | undefined {
+  const trimmedSource = sourceFile.trim();
+  if (!trimmedSource) return undefined;
+
+  const normalizedSource = trimmedSource.replace(/\\/g, "/");
+  if (isAbsoluteFilePath(normalizedSource)) return normalizedSource;
+
+  const normalizedRoot = projectDir?.trim().replace(/\\/g, "/").replace(/\/+$/, "");
+  if (!normalizedRoot) return undefined;
+
+  return `${normalizedRoot}/${normalizedSource.replace(/^\.?\//, "")}`;
+}
+
+export function normalizeDomEditStyleValue(property: string, value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) return trimmed;
+
+  if (
+    ["border-radius", "border-width", "font-size", "letter-spacing"].includes(property) &&
+    /^-?\d+(\.\d+)?$/.test(trimmed)
+  ) {
+    return `${trimmed}px`;
+  }
+
+  return trimmed;
+}
+
+export function isImageBackgroundValue(value: string): boolean {
+  return /^url\(/i.test(value.trim());
+}
+
+export function isManualGeometryStyleProperty(property: string): boolean {
+  return property === "left" || property === "top" || property === "width" || property === "height";
+}
+
+export function getEventTargetElement(target: EventTarget | null): HTMLElement | null {
+  if (!target || typeof target !== "object") return null;
+  const maybeNode = target as {
+    nodeType?: number;
+    parentElement?: Element | null;
+  };
+  if (maybeNode.nodeType === 1) return target as HTMLElement;
+  if (maybeNode.nodeType === 3 && maybeNode.parentElement) {
+    return maybeNode.parentElement as HTMLElement;
+  }
+  return null;
+}
+
+export function shouldIgnoreHistoryShortcut(target: EventTarget | null): boolean {
+  const el = getEventTargetElement(target);
+  if (!el) return false;
+  return Boolean(
+    el.closest("input, textarea, select, [contenteditable='true'], [role='textbox'], .cm-editor"),
+  );
+}
+
+export function getHistoryShortcutLabel(action: "undo" | "redo"): string {
+  const isMac =
+    typeof navigator !== "undefined" && /Mac|iPhone|iPad|iPod/i.test(navigator.platform);
+  const modifier = isMac ? "Cmd" : "Ctrl";
+  return action === "undo" ? `${modifier}+Z` : `${modifier}+Shift+Z`;
+}
+
+export function findMatchingTimelineElementId(
+  selection: Pick<
+    DomEditSelection,
+    "id" | "selector" | "selectorIndex" | "sourceFile" | "compositionSrc" | "isCompositionHost"
+  >,
+  elements: TimelineElement[],
+): string | null {
+  const selectionSourceFile = selection.sourceFile || "index.html";
+  for (const element of elements) {
+    const elementSourceFile = element.sourceFile || "index.html";
+    if (
+      selection.id &&
+      element.domId === selection.id &&
+      elementSourceFile === selectionSourceFile
+    ) {
+      return element.key ?? element.id;
+    }
+    if (
+      selection.isCompositionHost &&
+      selection.compositionSrc &&
+      element.compositionSrc === selection.compositionSrc
+    ) {
+      return element.key ?? element.id;
+    }
+    if (
+      selection.selector &&
+      element.selector === selection.selector &&
+      (element.selectorIndex ?? 0) === (selection.selectorIndex ?? 0) &&
+      (element.sourceFile ?? "index.html") === selection.sourceFile
+    ) {
+      return element.key ?? element.id;
+    }
+  }
+
+  return null;
+}
+
+export function clampNumber(value: number, min: number, max: number): number {
+  if (max < min) return min;
+  return Math.min(Math.max(value, min), max);
+}
+
+export function collectHtmlIds(source: string): string[] {
+  return Array.from(source.matchAll(/\bid="([^"]+)"/g), (match) => match[1] ?? "");
+}
+
+export const DEFAULT_TIMELINE_ASSET_DURATION: Record<TimelineAssetKind, number> = {
+  image: 3,
+  video: 5,
+  audio: 5,
+};
+
+export async function resolveDroppedAssetDuration(
+  projectId: string,
+  assetPath: string,
+  kind: TimelineAssetKind,
+): Promise<number> {
+  if (kind === "image") return DEFAULT_TIMELINE_ASSET_DURATION.image;
+
+  const media = document.createElement(kind === "video" ? "video" : "audio");
+  media.preload = "metadata";
+  media.src = `/api/projects/${projectId}/preview/${assetPath}`;
+
+  const duration = await new Promise<number>((resolve) => {
+    const timeout = window.setTimeout(() => resolve(DEFAULT_TIMELINE_ASSET_DURATION[kind]), 3000);
+    const finalize = (value: number) => {
+      window.clearTimeout(timeout);
+      resolve(value);
+    };
+
+    media.addEventListener(
+      "loadedmetadata",
+      () => {
+        const raw = Number(media.duration);
+        finalize(
+          Number.isFinite(raw) && raw > 0
+            ? Math.round(raw * 100) / 100
+            : DEFAULT_TIMELINE_ASSET_DURATION[kind],
+        );
+      },
+      { once: true },
+    );
+    media.addEventListener("error", () => finalize(DEFAULT_TIMELINE_ASSET_DURATION[kind]), {
+      once: true,
+    });
+  });
+
+  media.src = "";
+  media.load();
+  return duration;
+}