@hyperframes/studio 0.5.5 → 0.6.0-alpha.2

package/src/utils/studioFileHistory.ts

@@ -0,0 +1,61 @@
+import type { EditHistoryKind } from "./editHistory";
+
+interface SaveProjectFilesWithHistoryInput {
+  projectId: string;
+  label: string;
+  kind: EditHistoryKind;
+  coalesceKey?: string;
+  files: Record<string, string>;
+  readFile: (path: string) => Promise<string>;
+  writeFile: (path: string, content: string) => Promise<void>;
+  recordEdit: (entry: {
+    label: string;
+    kind: EditHistoryKind;
+    coalesceKey?: string;
+    files: Record<string, { before: string; after: string }>;
+  }) => Promise<void>;
+}
+
+export async function saveProjectFilesWithHistory({
+  label,
+  kind,
+  coalesceKey,
+  files,
+  readFile,
+  writeFile,
+  recordEdit,
+}: SaveProjectFilesWithHistoryInput): Promise<string[]> {
+  const snapshots: Record<string, { before: string; after: string }> = {};
+  for (const [path, after] of Object.entries(files)) {
+    const before = await readFile(path);
+    if (before !== after) {
+      snapshots[path] = { before, after };
+    }
+  }
+
+  const changedPaths = Object.keys(snapshots);
+  if (changedPaths.length === 0) return [];
+
+  const writtenPaths: string[] = [];
+  try {
+    for (const path of changedPaths) {
+      await writeFile(path, snapshots[path].after);
+      writtenPaths.push(path);
+    }
+
+    await recordEdit({ label, kind, coalesceKey, files: snapshots });
+  } catch (error) {
+    try {
+      for (const path of writtenPaths.reverse()) {
+        await writeFile(path, snapshots[path].before);
+      }
+    } catch (rollbackError) {
+      throw new AggregateError(
+        [error, rollbackError],
+        "Failed to save project files and rollback did not complete",
+      );
+    }
+    throw error;
+  }
+  return changedPaths;
+}

package/src/utils/timelineAssetDrop.test.ts

@@ -4,6 +4,7 @@ import {
   buildTimelineAssetInsertHtml,
   getTimelineAssetKind,
   insertTimelineAssetIntoSource,
+  resolveTimelineAssetInitialGeometry,
   resolveTimelineAssetSrc,
 } from "./timelineAssetDrop";
 
@@ -19,17 +20,21 @@ describe("getTimelineAssetKind", () => {
 
 describe("buildTimelineAssetInsertHtml", () => {
   it("builds an image clip with explicit timing and track", () => {
-    expect(
-      buildTimelineAssetInsertHtml({
-        id: "photo_asset",
-        assetPath: "assets/photo.png",
-        kind: "image",
-        start: 1.25,
-        duration: 3,
-        track: 2,
-        zIndex: 4,
-      }),
-    ).toContain('img id="photo_asset"');
+    const html = buildTimelineAssetInsertHtml({
+      id: "photo_asset",
+      assetPath: "assets/photo.png",
+      kind: "image",
+      start: 1.25,
+      duration: 3,
+      track: 2,
+      zIndex: 4,
+      geometry: { left: 0, top: 0, width: 1280, height: 720 },
+    });
+
+    expect(html).toContain('img id="photo_asset"');
+    expect(html).toContain("left: 0px");
+    expect(html).toContain("width: 1280px");
+    expect(html).not.toContain("inset:");
   });
 
   it("builds an audio clip without visual layout styles", () => {
@@ -47,6 +52,21 @@ describe("buildTimelineAssetInsertHtml", () => {
   });
 });
 
+describe("resolveTimelineAssetInitialGeometry", () => {
+  it("uses the target composition dimensions for visual media", () => {
+    expect(
+      resolveTimelineAssetInitialGeometry(
+        `<div data-composition-id="main" data-width="330" data-height="228"></div>`,
+      ),
+    ).toEqual({
+      left: 0,
+      top: 0,
+      width: 330,
+      height: 228,
+    });
+  });
+});
+
 describe("resolveTimelineAssetSrc", () => {
   it("keeps project-root asset paths for index.html", () => {
     expect(resolveTimelineAssetSrc("index.html", "assets/photo.png")).toBe("assets/photo.png");

package/src/utils/timelineAssetDrop.ts

@@ -76,6 +76,23 @@ export function buildTimelineFileDropPlacements(
   });
 }
 
+export function resolveTimelineAssetInitialGeometry(source: string): {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+} {
+  const width = Number.parseFloat(source.match(/\bdata-width=(["'])([^"']+)\1/i)?.[2] ?? "");
+  const height = Number.parseFloat(source.match(/\bdata-height=(["'])([^"']+)\1/i)?.[2] ?? "");
+
+  return {
+    left: 0,
+    top: 0,
+    width: Number.isFinite(width) && width > 0 ? Math.round(width) : 640,
+    height: Number.isFinite(height) && height > 0 ? Math.round(height) : 360,
+  };
+}
+
 export function buildTimelineAssetInsertHtml(input: {
   id: string;
   assetPath: string;
@@ -84,15 +101,18 @@ export function buildTimelineAssetInsertHtml(input: {
   duration: number;
   track: number;
   zIndex: number;
+  geometry?: { left: number; top: number; width: number; height: number };
 }): string {
   const sharedAttrs = `id="${input.id}" class="clip" src="${input.assetPath}" data-start="${input.start}" data-duration="${input.duration}" data-track-index="${input.track}"`;
+  const geometry = input.geometry ?? { left: 0, top: 0, width: 640, height: 360 };
+  const visualStyles = `position: absolute; left: ${geometry.left}px; top: ${geometry.top}px; width: ${geometry.width}px; height: ${geometry.height}px; object-fit: contain; z-index: ${input.zIndex}`;
 
   if (input.kind === "image") {
-    return `<img ${sharedAttrs} style="position: absolute; inset: 0; width: 100%; height: 100%; object-fit: contain; z-index: ${input.zIndex}" />`;
+    return `<img ${sharedAttrs} style="${visualStyles}" />`;
   }
 
   if (input.kind === "video") {
-    return `<video ${sharedAttrs} muted playsinline style="position: absolute; inset: 0; width: 100%; height: 100%; object-fit: contain; z-index: ${input.zIndex}"></video>`;
+    return `<video ${sharedAttrs} muted playsinline style="${visualStyles}"></video>`;
   }
 
   return `<audio ${sharedAttrs} style="z-index: ${input.zIndex}"></audio>`;

package/src/utils/timelineInspector.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import { Window } from "happy-dom";
+import {
+  canInspectTimelineElement,
+  getTimelineLayerVisibilityInPreview,
+  getTimelineElementKey,
+  isAudioTimelineElement,
+  isTimelineElementActiveAtTime,
+  isTimelineLayerVisibleInPreview,
+  shouldShowTimelineInspectorBounds,
+} from "./timelineInspector";
+
+function createDocument(markup: string): Document {
+  const window = new Window();
+  window.document.body.innerHTML = markup;
+  return window.document;
+}
+
+function attachVisibleBox(element: HTMLElement) {
+  Object.defineProperty(element, "getBoundingClientRect", {
+    configurable: true,
+    value: () => ({
+      bottom: 34,
+      height: 24,
+      left: 10,
+      right: 90,
+      top: 10,
+      width: 80,
+      x: 10,
+      y: 10,
+      toJSON: () => ({}),
+    }),
+  });
+}
+
+describe("timeline inspector", () => {
+  it("keeps visual clips inspectable and audio-only clips out of the visual panel", () => {
+    expect(canInspectTimelineElement({ tag: "section" })).toBe(true);
+    expect(canInspectTimelineElement({ tag: "video", src: "assets/demo.mp4" })).toBe(true);
+    expect(canInspectTimelineElement({ tag: "audio" })).toBe(false);
+    expect(canInspectTimelineElement({ tag: "div", src: "assets/narration.mp3" })).toBe(false);
+    expect(isAudioTimelineElement({ tag: "sfx" })).toBe(true);
+  });
+
+  it("uses stable timeline keys and only shows bounds at clip edges", () => {
+    expect(getTimelineElementKey({ id: "card", key: "index.html#card" })).toBe("index.html#card");
+    expect(shouldShowTimelineInspectorBounds(2, { start: 2, duration: 4 })).toBe(true);
+    expect(shouldShowTimelineInspectorBounds(6, { start: 2, duration: 4 })).toBe(true);
+    expect(shouldShowTimelineInspectorBounds(4, { start: 2, duration: 4 })).toBe(false);
+  });
+
+  it("keeps selected layer bounds visible only while the clip is active", () => {
+    expect(isTimelineElementActiveAtTime(1.99, { start: 2, duration: 4 }, 0)).toBe(false);
+    expect(isTimelineElementActiveAtTime(2, { start: 2, duration: 4 }, 0)).toBe(true);
+    expect(isTimelineElementActiveAtTime(4, { start: 2, duration: 4 }, 0)).toBe(true);
+    expect(isTimelineElementActiveAtTime(6, { start: 2, duration: 4 }, 0)).toBe(true);
+    expect(isTimelineElementActiveAtTime(6.01, { start: 2, duration: 4 }, 0)).toBe(false);
+  });
+
+  it("uses composite visibility for nested layers", () => {
+    const hiddenDoc = createDocument(`<div style="opacity: 0"><span id="label">Label</span></div>`);
+    const hiddenLabel = hiddenDoc.getElementById("label") as HTMLElement;
+    attachVisibleBox(hiddenLabel);
+    expect(isTimelineLayerVisibleInPreview(hiddenLabel)).toBe(false);
+
+    const visibleDoc = createDocument(
+      `<div style="opacity: 1"><span id="label">Label</span></div>`,
+    );
+    const visibleLabel = visibleDoc.getElementById("label") as HTMLElement;
+    attachVisibleBox(visibleLabel);
+    expect(isTimelineLayerVisibleInPreview(visibleLabel)).toBe(true);
+    expect(getTimelineLayerVisibilityInPreview(visibleLabel)).toMatchObject({
+      compositeOpacity: 1,
+      hasBox: true,
+      inViewport: true,
+      visible: true,
+    });
+  });
+});

package/src/utils/timelineInspector.ts

@@ -0,0 +1,116 @@
+import type { TimelineElement } from "../player";
+
+export const TIMELINE_INSPECTOR_BOUNDARY_EPSILON_SECONDS = 0.08;
+
+const AUDIO_TIMELINE_TAGS = new Set(["audio", "music", "sfx", "sound", "narration"]);
+const AUDIO_SOURCE_EXT_RE = /\.(aac|flac|m4a|mp3|ogg|opus|wav)(?:[?#].*)?$/i;
+
+export function getTimelineElementKey(
+  element: Pick<TimelineElement, "id" | "key"> | null | undefined,
+): string | null {
+  if (!element) return null;
+  return element.key ?? element.id;
+}
+
+export function isAudioTimelineElement(
+  element: Pick<TimelineElement, "tag" | "src"> | null | undefined,
+): boolean {
+  if (!element) return false;
+  const tag = element.tag.trim().toLowerCase();
+  if (AUDIO_TIMELINE_TAGS.has(tag)) return true;
+  return Boolean(element.src && AUDIO_SOURCE_EXT_RE.test(element.src));
+}
+
+export function canInspectTimelineElement(
+  element: Pick<TimelineElement, "tag" | "src"> | null | undefined,
+): boolean {
+  return !isAudioTimelineElement(element);
+}
+
+export function shouldShowTimelineInspectorBounds(
+  currentTime: number,
+  element: Pick<TimelineElement, "start" | "duration"> | null | undefined,
+  epsilonSeconds = TIMELINE_INSPECTOR_BOUNDARY_EPSILON_SECONDS,
+): boolean {
+  if (!element) return false;
+  if (!Number.isFinite(currentTime)) return false;
+  if (!Number.isFinite(element.start) || !Number.isFinite(element.duration)) return false;
+  const start = Math.max(0, element.start);
+  const end = Math.max(start, start + Math.max(0, element.duration));
+  const epsilon = Math.max(0, epsilonSeconds);
+  return Math.abs(currentTime - start) <= epsilon || Math.abs(currentTime - end) <= epsilon;
+}
+
+export function isTimelineElementActiveAtTime(
+  currentTime: number,
+  element: Pick<TimelineElement, "start" | "duration"> | null | undefined,
+  epsilonSeconds = TIMELINE_INSPECTOR_BOUNDARY_EPSILON_SECONDS,
+): boolean {
+  if (!element) return false;
+  if (!Number.isFinite(currentTime)) return false;
+  if (!Number.isFinite(element.start) || !Number.isFinite(element.duration)) return false;
+  const start = Math.max(0, element.start);
+  const end = Math.max(start, start + Math.max(0, element.duration));
+  const epsilon = Math.max(0, epsilonSeconds);
+  return currentTime >= start - epsilon && currentTime <= end + epsilon;
+}
+
+export interface TimelineLayerVisibility {
+  visible: boolean;
+  compositeOpacity: number;
+  hasBox: boolean;
+  inViewport: boolean;
+}
+
+export function getTimelineLayerVisibilityInPreview(
+  element: HTMLElement,
+  options: { minCompositeOpacity?: number } = {},
+): TimelineLayerVisibility {
+  const hidden: TimelineLayerVisibility = {
+    visible: false,
+    compositeOpacity: 0,
+    hasBox: false,
+    inViewport: false,
+  };
+  if (!element.isConnected) return hidden;
+  const doc = element.ownerDocument;
+  const win = doc.defaultView;
+  if (!win) return hidden;
+
+  const minCompositeOpacity = options.minCompositeOpacity ?? 0.01;
+  let compositeOpacity = 1;
+  let current: HTMLElement | null = element;
+  while (current && current !== doc.body && current !== doc.documentElement) {
+    const style = win.getComputedStyle(current);
+    if (style.display === "none" || style.visibility === "hidden") {
+      return { ...hidden, compositeOpacity };
+    }
+    compositeOpacity *= Number.parseFloat(style.opacity || "1");
+    if (compositeOpacity <= minCompositeOpacity) {
+      return { ...hidden, compositeOpacity };
+    }
+    current = current.parentElement;
+  }
+
+  const rect = element.getBoundingClientRect();
+  const hasBox = rect.width > 0.5 && rect.height > 0.5;
+  if (!hasBox) return { visible: false, compositeOpacity, hasBox, inViewport: false };
+
+  const viewportWidth = win.innerWidth || doc.documentElement.clientWidth;
+  const viewportHeight = win.innerHeight || doc.documentElement.clientHeight;
+  const inViewport =
+    rect.right > 0 && rect.bottom > 0 && rect.left < viewportWidth && rect.top < viewportHeight;
+  return {
+    visible: inViewport,
+    compositeOpacity,
+    hasBox,
+    inViewport,
+  };
+}
+
+export function isTimelineLayerVisibleInPreview(
+  element: HTMLElement,
+  options: { minCompositeOpacity?: number } = {},
+): boolean {
+  return getTimelineLayerVisibilityInPreview(element, options).visible;
+}