@hyperframes/studio 0.6.0-alpha.9 → 0.6.1

package/src/player/lib/timelineIframeHelpers.ts

@@ -0,0 +1,269 @@
+/**
+ * Runtime iframe integration utilities.
+ *
+ * Handles the boundary between the studio host page and the preview iframe:
+ * - Viewport normalisation on load
+ * - Auto-healing missing data-composition-id attributes
+ * - Unmuting media via postMessage
+ * - Resolving the underlying <iframe> from any wrapper element
+ * - Scanning the DOM for composition hosts the manifest missed
+ *   (element-reference starts that the CDN runtime fails to resolve)
+ */
+
+import type { TimelineElement } from "../store/playerStore";
+import type { IframeWindow } from "./playbackTypes";
+import {
+  getTimelineElementSelector,
+  getTimelineElementSourceFile,
+  getTimelineElementSelectorIndex,
+  getTimelineElementDisplayLabel,
+  buildTimelineElementIdentity,
+} from "./timelineElementHelpers";
+
+// ---------------------------------------------------------------------------
+// Viewport / DOM normalisation
+// ---------------------------------------------------------------------------
+
+export function normalizePreviewViewport(doc: Document, win: Window): void {
+  if (doc.documentElement) {
+    doc.documentElement.style.overflow = "hidden";
+    doc.documentElement.style.margin = "0";
+  }
+  if (doc.body) {
+    doc.body.style.overflow = "hidden";
+    doc.body.style.margin = "0";
+  }
+  win.scrollTo({ top: 0, left: 0, behavior: "auto" });
+}
+
+export function autoHealMissingCompositionIds(doc: Document): void {
+  const compositionIdRe = /data-composition-id=["']([^"']+)["']/gi;
+  const referencedIds = new Set<string>();
+  const scopedNodes = Array.from(doc.querySelectorAll("style, script"));
+  for (const node of scopedNodes) {
+    const text = node.textContent || "";
+    if (!text) continue;
+    let match: RegExpExecArray | null;
+    while ((match = compositionIdRe.exec(text)) !== null) {
+      const id = (match[1] || "").trim();
+      if (id) referencedIds.add(id);
+    }
+  }
+
+  if (referencedIds.size === 0) return;
+
+  const existingIds = new Set<string>();
+  const existingNodes = Array.from(doc.querySelectorAll<HTMLElement>("[data-composition-id]"));
+  for (const node of existingNodes) {
+    const id = node.getAttribute("data-composition-id");
+    if (id) existingIds.add(id);
+  }
+
+  for (const compId of referencedIds) {
+    if (compId === "root" || existingIds.has(compId)) continue;
+    const host =
+      doc.getElementById(`${compId}-layer`) ||
+      doc.getElementById(`${compId}-comp`) ||
+      doc.getElementById(compId);
+    if (!host) continue;
+    if (!host.getAttribute("data-composition-id")) {
+      host.setAttribute("data-composition-id", compId);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Muting / iframe resolution
+// ---------------------------------------------------------------------------
+
+export function unmutePreviewMedia(iframe: HTMLIFrameElement | null): void {
+  if (!iframe) return;
+  try {
+    iframe.contentWindow?.postMessage(
+      { source: "hf-parent", type: "control", action: "set-muted", muted: false },
+      "*",
+    );
+  } catch (err) {
+    console.warn("[useTimelinePlayer] Failed to unmute preview media", err);
+  }
+}
+
+/**
+ * Resolve the underlying iframe from any host element. Supports:
+ * - Direct `<iframe>` element (most common — studio's own `Player.tsx`)
+ * - Custom elements (e.g. `<hyperframes-player>`) whose shadow DOM contains an iframe
+ * - Wrapper elements whose light DOM contains a descendant iframe
+ *
+ * Exported so web-component consumers can pre-resolve the iframe before
+ * assigning it to `iframeRef` returned by `useTimelinePlayer`. Returns `null`
+ * when the element has no associated iframe yet.
+ *
+ * @example
+ * ```tsx
+ * const { iframeRef } = useTimelinePlayer();
+ * const playerElRef = useRef<HyperframesPlayer>(null);
+ *
+ * useEffect(() => {
+ *   iframeRef.current = resolveIframe(playerElRef.current);
+ * }, [iframeRef]);
+ * ```
+ */
+export function resolveIframe(el: Element | null): HTMLIFrameElement | null {
+  if (!el) return null;
+  if (el instanceof HTMLIFrameElement) return el;
+  return el.shadowRoot?.querySelector("iframe") ?? el.querySelector("iframe") ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Enrich missing compositions from DOM
+// ---------------------------------------------------------------------------
+
+/**
+ * Scan the iframe DOM for composition hosts missing from the current
+ * timeline elements and add them.  The CDN runtime often fails to resolve
+ * element-reference starts (`data-start="intro"`) so composition hosts
+ * are silently dropped from `__clipManifest`.  This pass reads the DOM +
+ * GSAP timeline registry directly to fill the gaps.
+ */
+export function buildMissingCompositionElements(
+  doc: Document,
+  iframeWin: IframeWindow,
+  currentEls: readonly TimelineElement[],
+  rootDuration: number,
+): { missing: TimelineElement[]; updatedEls: TimelineElement[]; patched: boolean } {
+  const existingIds = new Set(currentEls.map((e) => e.id));
+  const rootComp = doc.querySelector("[data-composition-id]");
+  const rootCompId = rootComp?.getAttribute("data-composition-id");
+  // Use [data-composition-id][data-start] — the composition loader strips
+  // data-composition-src after loading, so we can't rely on it.
+  const hosts = doc.querySelectorAll("[data-composition-id][data-start]");
+  const missing: TimelineElement[] = [];
+
+  hosts.forEach((host) => {
+    const el = host as HTMLElement;
+    const compId = el.getAttribute("data-composition-id");
+    if (!compId || compId === rootCompId) return;
+    if (existingIds.has(el.id) || existingIds.has(compId)) return;
+
+    // Resolve start: numeric or element-reference
+    const startAttr = el.getAttribute("data-start") ?? "0";
+    let start = parseFloat(startAttr);
+    if (isNaN(start)) {
+      const ref =
+        doc.getElementById(startAttr) || doc.querySelector(`[data-composition-id="${startAttr}"]`);
+      if (ref) {
+        const refStartAttr = ref.getAttribute("data-start") ?? "0";
+        let refStart = parseFloat(refStartAttr);
+        // Recursively resolve one level of reference for the ref's own start
+        if (isNaN(refStart)) {
+          const refRef =
+            doc.getElementById(refStartAttr) ||
+            doc.querySelector(`[data-composition-id="${refStartAttr}"]`);
+          const rrStart = parseFloat(refRef?.getAttribute("data-start") ?? "0") || 0;
+          const rrCompId = refRef?.getAttribute("data-composition-id");
+          const rrDur =
+            parseFloat(refRef?.getAttribute("data-duration") ?? "") ||
+            (rrCompId
+              ? ((
+                  iframeWin.__timelines?.[rrCompId] as { duration?: () => number } | undefined
+                )?.duration?.() ?? 0)
+              : 0);
+          refStart = rrStart + rrDur;
+        }
+        const refCompId = ref.getAttribute("data-composition-id");
+        const refDur =
+          parseFloat(ref.getAttribute("data-duration") ?? "") ||
+          (refCompId
+            ? ((
+                iframeWin.__timelines?.[refCompId] as { duration?: () => number } | undefined
+              )?.duration?.() ?? 0)
+            : 0);
+        start = refStart + refDur;
+      } else {
+        start = 0;
+      }
+    }
+
+    // Resolve duration from data-duration or GSAP timeline
+    let dur = parseFloat(el.getAttribute("data-duration") ?? "");
+    if (isNaN(dur) || dur <= 0) {
+      dur =
+        (
+          iframeWin.__timelines?.[compId] as { duration?: () => number } | undefined
+        )?.duration?.() ?? 0;
+    }
+    if (!Number.isFinite(dur) || dur <= 0) return;
+    if (!Number.isFinite(start)) start = 0;
+    if (Number.isFinite(rootDuration) && rootDuration > 0) {
+      if (start >= rootDuration) return;
+      dur = Math.min(dur, Math.max(0, rootDuration - start));
+      if (dur <= 0) return;
+    }
+
+    const trackStr = el.getAttribute("data-track-index");
+    const track = trackStr != null ? parseInt(trackStr, 10) : 0;
+    const compSrc =
+      el.getAttribute("data-composition-src") || el.getAttribute("data-composition-file");
+    const selector = getTimelineElementSelector(el);
+    const sourceFile = getTimelineElementSourceFile(el);
+    const selectorIndex = getTimelineElementSelectorIndex(doc, el, selector);
+    const label = getTimelineElementDisplayLabel({
+      id: el.id || compId || null,
+      label: el.getAttribute("data-timeline-label") ?? el.getAttribute("data-label"),
+      tag: el.tagName,
+    });
+    const identity = buildTimelineElementIdentity({
+      preferredId: el.id || compId || null,
+      label,
+      fallbackIndex: missing.length,
+      domId: el.id || undefined,
+      selector,
+      selectorIndex,
+      sourceFile,
+    });
+    const entry: TimelineElement = {
+      id: identity.id,
+      label,
+      key: identity.key,
+      tag: el.tagName.toLowerCase(),
+      start,
+      duration: dur,
+      track: isNaN(track) ? 0 : track,
+      domId: el.id || undefined,
+      selector,
+      selectorIndex,
+      sourceFile,
+    };
+    if (compSrc) {
+      entry.compositionSrc = compSrc;
+    } else {
+      // Inline composition — expose inner video for thumbnails
+      const innerVideo = el.querySelector("video[src]");
+      if (innerVideo) {
+        entry.src = innerVideo.getAttribute("src") || undefined;
+        entry.tag = "video";
+      }
+    }
+    missing.push(entry);
+  });
+
+  // Patch existing elements that are missing compositionSrc
+  let patched = false;
+  const updatedEls = (currentEls as TimelineElement[]).map((existing) => {
+    if (existing.compositionSrc) return existing;
+    // Find the matching DOM host by element id or composition id
+    const host =
+      doc.getElementById(existing.id) ??
+      doc.querySelector(`[data-composition-id="${existing.id}"]`);
+    if (!host) return existing;
+    const compSrc =
+      host.getAttribute("data-composition-src") || host.getAttribute("data-composition-file");
+    if (compSrc) {
+      patched = true;
+      return { ...existing, compositionSrc: compSrc };
+    }
+    return existing;
+  });
+
+  return { missing, updatedEls, patched };
+}

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;
+}