@hyperframes/studio 0.6.0-alpha.1 → 0.6.0-alpha.11

package/src/components/editor/domEditing.test.ts

@@ -9,7 +9,9 @@ import {
   findElementForTimelineElement,
   getDomEditNonEditableReason,
   getDomEditTargetKey,
+  isLargeRasterDomEditSelection,
   isTextEditableSelection,
+  resolveVisualDomEditSelectionTarget,
   serializeDomEditTextFields,
   type DomEditSelection,
   resolveDomEditCapabilities,
@@ -23,6 +25,30 @@ function createDocument(markup: string): Document {
   return window.document;
 }
 
+function setElementRect(
+  element: HTMLElement,
+  rect: Partial<Pick<DOMRect, "left" | "top" | "width" | "height">>,
+) {
+  const left = rect.left ?? 0;
+  const top = rect.top ?? 0;
+  const width = rect.width ?? 100;
+  const height = rect.height ?? 40;
+  Object.defineProperty(element, "getBoundingClientRect", {
+    configurable: true,
+    value: () => ({
+      x: left,
+      y: top,
+      left,
+      top,
+      width,
+      height,
+      right: left + width,
+      bottom: top + height,
+      toJSON: () => null,
+    }),
+  });
+}
+
 describe("resolveDomEditCapabilities", () => {
   it("marks absolute px-positioned layers as movable and resizable", () => {
     expect(
@@ -199,6 +225,154 @@ describe("resolveDomEditCapabilities", () => {
   });
 });
 
+describe("resolveVisualDomEditSelectionTarget", () => {
+  it("prefers the visible leaf under the pointer over an oversized container", () => {
+    const document = createDocument(`
+      <section id="container" class="hero-shell">
+        <span id="headline" class="headline">Launch faster</span>
+      </section>
+    `);
+    const container = document.getElementById("container") as HTMLElement;
+    const headline = document.getElementById("headline") as HTMLElement;
+    setElementRect(container, { width: 900, height: 520 });
+    setElementRect(headline, { left: 240, top: 160, width: 180, height: 36 });
+
+    expect(
+      resolveVisualDomEditSelectionTarget([container, headline], {
+        activeCompositionPath: "index.html",
+      }),
+    ).toBe(headline);
+  });
+
+  it("skips hidden and zero-size elements before picking a rendered candidate", () => {
+    const document = createDocument(`
+      <div id="hidden" style="display: none">Hidden</div>
+      <div id="empty">Empty</div>
+      <div id="visible">Visible</div>
+    `);
+    const hidden = document.getElementById("hidden") as HTMLElement;
+    const empty = document.getElementById("empty") as HTMLElement;
+    const visible = document.getElementById("visible") as HTMLElement;
+    setElementRect(hidden, { width: 120, height: 32 });
+    setElementRect(empty, { width: 0, height: 0 });
+    setElementRect(visible, { width: 120, height: 32 });
+
+    expect(
+      resolveVisualDomEditSelectionTarget([hidden, empty, visible], {
+        activeCompositionPath: "index.html",
+      }),
+    ).toBe(visible);
+  });
+
+  it("skips transparent elements that still report a box", () => {
+    const document = createDocument(`
+      <button id="transparent" style="opacity: 0">Transparent</button>
+      <button id="visible">Visible</button>
+    `);
+    const transparent = document.getElementById("transparent") as HTMLElement;
+    const visible = document.getElementById("visible") as HTMLElement;
+    setElementRect(transparent, { width: 120, height: 32 });
+    setElementRect(visible, { width: 120, height: 32 });
+
+    expect(
+      resolveVisualDomEditSelectionTarget([transparent, visible], {
+        activeCompositionPath: "index.html",
+      }),
+    ).toBe(visible);
+  });
+
+  it("falls back to the nearest stable editable ancestor when a visual child has no target", () => {
+    const document = createDocument(`
+      <section id="card">
+        <span>Unlabeled copy</span>
+      </section>
+    `);
+    const card = document.getElementById("card") as HTMLElement;
+    const span = card.querySelector("span") as HTMLElement;
+    setElementRect(card, { width: 400, height: 200 });
+    setElementRect(span, { left: 40, top: 40, width: 140, height: 28 });
+
+    expect(
+      resolveVisualDomEditSelectionTarget([span, card], {
+        activeCompositionPath: "index.html",
+      }),
+    ).toBe(card);
+  });
+
+  it("keeps explicit layer selection able to target containers", () => {
+    const document = createDocument(`
+      <section id="container" class="hero-shell">
+        <span id="headline" class="headline">Launch faster</span>
+      </section>
+    `);
+    const container = document.getElementById("container") as HTMLElement;
+    const headline = document.getElementById("headline") as HTMLElement;
+    setElementRect(container, { width: 900, height: 520 });
+    setElementRect(headline, { left: 240, top: 160, width: 180, height: 36 });
+
+    const visualTarget = resolveVisualDomEditSelectionTarget([container, headline], {
+      activeCompositionPath: "index.html",
+    });
+    const explicitSelection = resolveDomEditSelection(container, {
+      activeCompositionPath: "index.html",
+      isMasterView: false,
+    });
+
+    expect(visualTarget).toBe(headline);
+    expect(explicitSelection?.id).toBe("container");
+  });
+});
+
+describe("isLargeRasterDomEditSelection", () => {
+  it("flags large image and background targets for raster click fallback", () => {
+    expect(
+      isLargeRasterDomEditSelection(
+        {
+          tagName: "img",
+          boundingBox: { x: 0, y: 0, width: 1920, height: 1080 },
+          computedStyles: {},
+        },
+        { width: 1920, height: 1080 },
+      ),
+    ).toBe(true);
+
+    expect(
+      isLargeRasterDomEditSelection(
+        {
+          tagName: "div",
+          boundingBox: { x: 0, y: 0, width: 1280, height: 720 },
+          computedStyles: { "background-image": 'url("hero.png")' },
+        },
+        { width: 1920, height: 1080 },
+      ),
+    ).toBe(true);
+  });
+
+  it("does not flag small media or text selections", () => {
+    expect(
+      isLargeRasterDomEditSelection(
+        {
+          tagName: "img",
+          boundingBox: { x: 80, y: 80, width: 96, height: 96 },
+          computedStyles: {},
+        },
+        { width: 1920, height: 1080 },
+      ),
+    ).toBe(false);
+
+    expect(
+      isLargeRasterDomEditSelection(
+        {
+          tagName: "h1",
+          boundingBox: { x: 0, y: 0, width: 1600, height: 300 },
+          computedStyles: {},
+        },
+        { width: 1920, height: 1080 },
+      ),
+    ).toBe(false);
+  });
+});
+
 describe("resolveDomEditSelection", () => {
   it("keeps composition host transforms disabled in master view", () => {
     expect(
@@ -643,6 +817,36 @@ describe("resolveDomEditSelection", () => {
     ).toBe(root);
   });
 
+  it("normalizes preview URLs when resolving master timeline composition clips", () => {
+    const document = createDocument(`
+      <div data-composition-id="main">
+        <div
+          id="slide-1"
+          data-composition-id="slide-core-conviction"
+          data-composition-src="compositions/slide-01-core-conviction.html"
+        >
+          <h1>Core Conviction</h1>
+        </div>
+      </div>
+    `);
+    const slide = document.getElementById("slide-1") as HTMLElement;
+
+    expect(
+      findElementForTimelineElement(
+        document,
+        {
+          id: "slide-1",
+          compositionSrc:
+            "http://127.0.0.1:5176/api/projects/apple-presentation-download/preview/compositions/slide-01-core-conviction.html",
+        },
+        {
+          activeCompositionPath: null,
+          isMasterView: true,
+        },
+      ),
+    ).toBe(slide);
+  });
+
   it("does not fall back to the root composition when an explicit timeline selector misses", () => {
     const document = createDocument(`
       <div data-composition-id="hook">
@@ -783,6 +987,50 @@ describe("patch builders and prompt builder", () => {
     expect(prompt).not.toContain("Source file: index.html");
   });
 
+  it("includes raster click context in copied agent prompts", () => {
+    const selection = {
+      element: {} as HTMLElement,
+      id: undefined,
+      selector: ".hero-bg",
+      selectorIndex: undefined,
+      sourceFile: "index.html",
+      compositionPath: "index.html",
+      compositionSrc: undefined,
+      isCompositionHost: false,
+      label: "Hero Bg",
+      tagName: "img",
+      boundingBox: { x: 0, y: 0, width: 1920, height: 1080 },
+      textContent: null,
+      dataAttributes: {},
+      inlineStyles: {},
+      computedStyles: {},
+      textFields: [],
+      capabilities: {
+        canSelect: true,
+        canEditStyles: true,
+        canMove: true,
+        canResize: true,
+        canApplyManualOffset: true,
+        canApplyManualSize: true,
+        canApplyManualRotation: true,
+      },
+    } satisfies DomEditSelection;
+
+    const prompt = buildElementAgentPrompt({
+      selection,
+      currentTime: 3,
+      selectionContext:
+        "The user clicked visible text that is baked into the selected image/background.",
+      userInstruction: "Change the title copy.",
+    });
+
+    expect(prompt).toContain("Selection context:");
+    expect(prompt).toContain(
+      "The user clicked visible text that is baked into the selected image/background.",
+    );
+    expect(prompt).toContain("Change the title copy.");
+  });
+
   it("serializes child text fields back into HTML", () => {
     expect(
       serializeDomEditTextFields([

package/src/components/editor/domEditing.ts

@@ -105,6 +105,11 @@ export interface DomEditContextOptions {
   preferClipAncestor?: boolean;
 }
 
+export interface DomEditViewport {
+  width: number;
+  height: number;
+}
+
 export interface TimelineElementDomTarget {
   id?: string;
   domId?: string;
@@ -291,6 +296,27 @@ function escapeCssString(value: string): string {
     .replace(/\f/g, "\\c ");
 }
 
+function normalizeTimelineCompositionSource(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+
+  let pathname = trimmed;
+  try {
+    pathname = new URL(trimmed, "http://studio.local").pathname;
+  } catch {
+    pathname = trimmed;
+  }
+
+  for (const marker of ["/preview/comp/", "/preview/"]) {
+    const markerIndex = pathname.indexOf(marker);
+    if (markerIndex < 0) continue;
+    const sourcePath = pathname.slice(markerIndex + marker.length).replace(/^\/+/, "");
+    return sourcePath || trimmed;
+  }
+
+  return trimmed;
+}
+
 function querySelectorAllSafely(doc: Document, selector: string): Element[] {
   try {
     return Array.from(doc.querySelectorAll(selector));
@@ -372,6 +398,7 @@ function buildElementLabel(el: HTMLElement): string {
 const DOM_LAYER_IGNORED_TAGS = new Set([
   "base",
   "br",
+  "canvas",
   "link",
   "meta",
   "script",
@@ -416,6 +443,91 @@ function getDomLayerPatchTarget(
   };
 }
 
+function getElementDepth(el: HTMLElement): number {
+  let depth = 0;
+  let current = el.parentElement;
+  while (current) {
+    depth += 1;
+    current = current.parentElement;
+  }
+  return depth;
+}
+
+function hasRenderedBox(el: HTMLElement): boolean {
+  const rect = el.getBoundingClientRect();
+  if (rect.width <= 1 || rect.height <= 1) return false;
+
+  const computed = el.ownerDocument.defaultView?.getComputedStyle(el);
+  if (!computed) return true;
+  if (computed.display === "none" || computed.visibility === "hidden") return false;
+
+  const opacity = Number.parseFloat(computed.opacity);
+  if (Number.isFinite(opacity) && opacity <= 0.01) return false;
+
+  return true;
+}
+
+function getVisualElementScore(el: HTMLElement, pointerStackIndex: number): number {
+  const tagName = el.tagName.toLowerCase();
+  const rect = el.getBoundingClientRect();
+  const area = Math.max(1, rect.width * rect.height);
+  const smallerElementBonus = Math.max(0, 1_000_000 - Math.min(area, 1_000_000)) / 1_000;
+  const visualLeafBonus =
+    isEditableTextLeaf(el) || ["img", "video", "canvas", "svg"].includes(tagName) ? 2_000 : 0;
+
+  return getElementDepth(el) * 10_000 + visualLeafBonus + smallerElementBonus - pointerStackIndex;
+}
+
+export function resolveVisualDomEditSelectionTarget(
+  elementsFromPoint: Iterable<Element | null | undefined>,
+  options: Pick<DomEditContextOptions, "activeCompositionPath">,
+): HTMLElement | null {
+  let best: { element: HTMLElement; score: number } | null = null;
+  let pointerStackIndex = 0;
+
+  for (const entry of elementsFromPoint) {
+    if (!isHtmlElement(entry)) {
+      pointerStackIndex += 1;
+      continue;
+    }
+
+    if (hasRenderedBox(entry) && getDomLayerPatchTarget(entry, options.activeCompositionPath)) {
+      const score = getVisualElementScore(entry, pointerStackIndex);
+      if (!best || score > best.score) {
+        best = { element: entry, score };
+      }
+    }
+    pointerStackIndex += 1;
+  }
+
+  return best?.element ?? null;
+}
+
+function hasRasterBackground(selection: Pick<DomEditSelection, "computedStyles">): boolean {
+  const backgroundImage = selection.computedStyles["background-image"]?.trim();
+  return Boolean(backgroundImage && backgroundImage !== "none");
+}
+
+export function isLargeRasterDomEditSelection(
+  selection: Pick<DomEditSelection, "boundingBox" | "computedStyles" | "tagName">,
+  viewport?: DomEditViewport | null,
+): boolean {
+  const tagName = selection.tagName.toLowerCase();
+  const isRasterLike = tagName === "img" || hasRasterBackground(selection);
+  if (!isRasterLike) return false;
+
+  const { width, height } = selection.boundingBox;
+  if (width <= 1 || height <= 1) return false;
+  if (!viewport || viewport.width <= 1 || viewport.height <= 1) {
+    return width >= 960 && height >= 540;
+  }
+
+  const areaRatio = (width * height) / (viewport.width * viewport.height);
+  const widthRatio = width / viewport.width;
+  const heightRatio = height / viewport.height;
+  return areaRatio >= 0.4 || (widthRatio >= 0.7 && heightRatio >= 0.5);
+}
+
 function getDirectLayerChildren(el: HTMLElement, options: DomEditContextOptions): HTMLElement[] {
   return Array.from(el.children).filter(
     (child): child is HTMLElement =>
@@ -848,9 +960,14 @@ export function findElementForTimelineElement(
   options: TimelineElementDomTargetOptions,
 ): HTMLElement | null {
   const elementId = typeof element.id === "string" ? element.id : "";
-  const compositionSource = element.compositionSrc ?? options.compIdToSrc?.get(elementId);
+  const compositionSource =
+    normalizeTimelineCompositionSource(element.compositionSrc) ??
+    options.compIdToSrc?.get(elementId);
   const sourceFile =
-    compositionSource ?? element.sourceFile ?? options.activeCompositionPath ?? "index.html";
+    compositionSource ??
+    normalizeTimelineCompositionSource(element.sourceFile) ??
+    options.activeCompositionPath ??
+    "index.html";
   const escapedElementId = escapeCssString(elementId);
   const escapedCompositionSource = compositionSource ? escapeCssString(compositionSource) : null;
   const selector =
@@ -927,12 +1044,14 @@ export function buildElementAgentPrompt({
   selection,
   currentTime,
   tagSnippet,
+  selectionContext,
   userInstruction,
   sourceFilePath,
 }: {
   selection: DomEditSelection;
   currentTime: number;
   tagSnippet?: string;
+  selectionContext?: string;
   userInstruction?: string;
   sourceFilePath?: string;
 }): string {
@@ -957,6 +1076,11 @@ export function buildElementAgentPrompt({
     lines.push(`Text: ${selection.textContent}`);
   }
 
+  const trimmedSelectionContext = selectionContext?.trim();
+  if (trimmedSelectionContext) {
+    lines.push("", "Selection context:", trimmedSelectionContext);
+  }
+
   const textFieldsBlock = formatTextFields(selection.textFields);
   if (textFieldsBlock) {
     lines.push("", "Text fields:", textFieldsBlock);

package/src/components/editor/manualEditingAvailability.test.ts

@@ -16,16 +16,17 @@ describe("manual editing availability", () => {
     vi.resetModules();
   });
 
-  it("keeps alpha inspector and manual editing surfaces disabled by default", async () => {
+  it("enables inspector selection by default while motion and manual dragging stay opt-in", async () => {
     const availability = await loadAvailabilityWithEnv({});
 
     expect(availability.STUDIO_PREVIEW_MANUAL_EDITING_ENABLED).toBe(false);
-    expect(availability.STUDIO_INSPECTOR_PANELS_ENABLED).toBe(false);
+    expect(availability.STUDIO_PREVIEW_SELECTION_ENABLED).toBe(true);
+    expect(availability.STUDIO_INSPECTOR_PANELS_ENABLED).toBe(true);
     expect(availability.STUDIO_MOTION_PANEL_ENABLED).toBe(false);
-    expect(availability.STUDIO_TIMELINE_LAYER_INSPECTOR_ENABLED).toBe(false);
+    expect(availability.STUDIO_TIMELINE_LAYER_INSPECTOR_ENABLED).toBe(true);
   });
 
-  it("enables inspector layers only through explicit opt-in flags", async () => {
+  it("keeps explicit truthy inspector env flags enabled", async () => {
     const availability = await loadAvailabilityWithEnv({
       VITE_STUDIO_ENABLE_INSPECTOR_PANELS: "1",
       VITE_STUDIO_ENABLE_TIMELINE_LAYER_INSPECTOR: "true",
@@ -35,6 +36,15 @@ describe("manual editing availability", () => {
     expect(availability.STUDIO_TIMELINE_LAYER_INSPECTOR_ENABLED).toBe(true);
   });
 
+  it("allows explicit env flags to disable default-on inspector layers", async () => {
+    const availability = await loadAvailabilityWithEnv({
+      VITE_STUDIO_ENABLE_TIMELINE_LAYER_INSPECTOR: "off",
+    });
+
+    expect(availability.STUDIO_INSPECTOR_PANELS_ENABLED).toBe(true);
+    expect(availability.STUDIO_TIMELINE_LAYER_INSPECTOR_ENABLED).toBe(false);
+  });
+
   it("keeps timeline layer inspection off when the parent inspector flag is off", async () => {
     const availability = await loadAvailabilityWithEnv({
       VITE_STUDIO_ENABLE_INSPECTOR_PANELS: "0",
@@ -42,6 +52,7 @@ describe("manual editing availability", () => {
     });
 
     expect(availability.STUDIO_INSPECTOR_PANELS_ENABLED).toBe(false);
+    expect(availability.STUDIO_PREVIEW_SELECTION_ENABLED).toBe(false);
     expect(availability.STUDIO_TIMELINE_LAYER_INSPECTOR_ENABLED).toBe(false);
   });
 

package/src/components/editor/manualEditingAvailability.ts

@@ -38,7 +38,7 @@ export const STUDIO_PREVIEW_MANUAL_EDITING_ENABLED = resolveStudioBooleanEnvFlag
 export const STUDIO_INSPECTOR_PANELS_ENABLED = resolveStudioBooleanEnvFlag(
   env,
   [STUDIO_INSPECTOR_PANELS_ENV, "VITE_STUDIO_INSPECTOR_PANELS_ENABLED"],
-  false,
+  true,
 );
 
 export const STUDIO_MOTION_PANEL_ENABLED = resolveStudioBooleanEnvFlag(
@@ -52,9 +52,11 @@ export const STUDIO_TIMELINE_LAYER_INSPECTOR_ENABLED =
   resolveStudioBooleanEnvFlag(
     env,
     [STUDIO_TIMELINE_LAYER_INSPECTOR_ENV, "VITE_STUDIO_TIMELINE_LAYER_INSPECTOR_ENABLED"],
-    false,
+    true,
   );
 
+export const STUDIO_PREVIEW_SELECTION_ENABLED = STUDIO_INSPECTOR_PANELS_ENABLED;
+
 export const STUDIO_MANUAL_EDITING_ENABLED = STUDIO_PREVIEW_MANUAL_EDITING_ENABLED;
 
 export const STUDIO_MANUAL_EDITING_DISABLED_TITLE = "Manual editing is temporarily disabled";

package/src/components/editor/manualEdits.ts

@@ -1053,7 +1053,11 @@ function wrapSeekReapplyFunction(
     return result;
   };
   markWrapped(wrappedSeek);
-  owner[key] = wrappedSeek;
+  try {
+    owner[key] = wrappedSeek;
+  } catch {
+    return false;
+  }
   return true;
 }
 
@@ -1161,7 +1165,11 @@ function wrapPlayReapplyFunction(
     return result;
   };
   markWrapped(wrappedPlay);
-  owner[key] = wrappedPlay;
+  try {
+    owner[key] = wrappedPlay;
+  } catch {
+    return false;
+  }
   return true;
 }
 
@@ -1181,7 +1189,11 @@ function wrapApplyAfterFunction(
     return result;
   };
   markWrapped(wrappedApplyAfter);
-  owner[key] = wrappedApplyAfter;
+  try {
+    owner[key] = wrappedApplyAfter;
+  } catch {
+    return false;
+  }
   return true;
 }
 

package/src/components/nle/NLELayout.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import { shouldDisableTimelineWhileCompositionLoading } from "./NLELayout";
+
+describe("timeline loading disable state", () => {
+  it("disables the timeline while the composition loading overlay is visible", () => {
+    expect(shouldDisableTimelineWhileCompositionLoading(true)).toBe(true);
+  });
+
+  it("reenables the timeline after composition loading finishes", () => {
+    expect(shouldDisableTimelineWhileCompositionLoading(false)).toBe(false);
+  });
+});