fix(studio): gsap panel bug bash — clamping, overlay, click cycling, visibility toggle (#1126)

* fix(studio): gsap panel bug bash — clamping, overlay, click cycling, visibility toggle

- opacity/autoAlpha clamped to [0,1] (display 0–100%) — eliminates -30%/190% edits
- `visibility` renders as a boolean toggle; only available to add in `set` tweens
- ease curve section: use aspect-ratio container so control circles are not oval
- MetricField scroll only fires when the input is focused (was triggering on scroll-over)
- preview overlay clipped to its container (overflow-hidden) — no bleed into panels
- `fromTo` method label updated to "From → To" (was "Animate", same as `to`)
- repeated click at same position cycles through stacked/overlapping elements (#1124, #1125)
  resolveAllVisualDomEditTargets returns the full z-stack; subsequent same-spot clicks
  advance through all selectable layers at that coordinate
- fallow-ignore-next-line complexity on pre-existing complex functions surfaced by
  branching from fix/gsap-fromto-panel rather than main

Closes #1124, #1125

* fix(studio): address Vai+Rames follow-up notes on hf#1122

- extract buildTweenSummary to gsapAnimationHelpers.ts (now testable)
- add tests for all buildTweenSummary branches including fromTo
- extract requireAnimation/requireFromToAnimation helpers in files.ts,
  eliminating the parse→find→guard pattern repeated across three switch
  cases and removing the fallow-ignore-next-line complexity bypass
- add 400 guard: add mutation with fromProperties on non-fromTo method
  now returns 400 instead of silently dropping fromProperties
- add test for the 400 guard

* fix(studio): buildTweenSummary formats percent props as 0-100% not 0-1

* fix(studio): show all .html files as compositions in sidebar

The Comps sidebar only listed index.html and files under a compositions/
subdirectory. Any other .html file in the project root was invisible and
could not be loaded as a composition preview.

Broadened the filter in useFileManager and the activeCompPath guard in
App.tsx to treat every .html file as a selectable composition.

Also excluded App.tsx from the filesize pre-commit check — the file is
already 652 lines (decomposition tracked in PR #724).

* fix(studio): detect compositions by data-composition-id, not path convention

The previous approach filtered compositions by path convention (index.html
or compositions/ subdirectory). Any .html file outside that convention was
invisible in the Comps sidebar.

The server now scans each .html file for data-composition-id and returns
a compositions[] field in the project API response. The client uses this
server-provided list instead of filtering locally. This means any .html
file that is a real HyperFrames composition shows up regardless of where
it lives in the project tree.

* fix(studio): rename Ask agent to Copy prompt to AI agent, show context preview

Updated the property panel button label from "Ask agent" to "Copy prompt
to AI agent". Updated the modal title to match. Added a collapsible
"Context included in prompt" details section to the modal that shows the
element metadata that will be included when copying.

* fix(studio): wire contextPreview to agent modal

Passes composition path, source file, selector, tag, and text content
to the AskAgentModal so the context preview section is visible.

* fix(core): seek timeline to current time after initial bind

When bindRootTimelineIfAvailable captured a GSAP timeline for the first
time, it paused it but never seeked to state.currentTime. This left
fromTo tweens stuck at their immediateRender "from" state (e.g. opacity 0)
even after the user scrubbed past the tween's end. The polling rebind
path already seeked to previousTime — the initial bind was the only path
that skipped it.

* feat(core): add gsap_timeline_not_registered lint rule

Warns when a composition creates gsap.timeline() but never registers it
in window.__timelines. Without registration, the runtime cannot discover
the timeline, and animations will not play during preview or render.

Skips the warning for sub-compositions (template-based) which inherit
the parent's timeline context.

* fix(studio): address hf#1126 review feedback

- Extract buildAgentContextPreview into domEditingAgentPrompt.ts and
  import it in App.tsx, removing the inline computation that pushed
  App.tsx past the 600-line CI gate
- Switch isCompositionFile from sync readFileSync to async readFile with
  Promise.all, and use a regex test instead of string includes
- Move PERCENT_PROPS from AnimationCard.tsx and gsapAnimationHelpers.ts
  into gsapAnimationConstants.ts (single source of truth)
- Add regression test for the totalTime initial-bind seek fix in
  init.test.ts — verifies the captured timeline receives a totalTime
  call on initial bind

* refactor(studio): extract App.tsx below 600 LOC, remove lefthook exemption

Extracted inspector state, studio context construction, and drag overlay
into useStudioContextValue.ts. Deduplicated block handler args via a
shared blockCtx memo. App.tsx drops from 657 to 588 lines.

Removed the App.tsx exemption from lefthook.yml — the file now passes
the 600-line gate without special-casing. Added domEditing.ts barrel to
fallowrc ignoreExports (re-exports not traceable by static analysis).

Author: miguel-heygen

.fallowrc.jsonc

@@ -79,6 +79,12 @@
         "refreshDomEditSelection",
       ],
     },
+    // domEditing barrel: re-exports consumed throughout the studio but
+    // fallow's static analyzer can't trace re-exports through barrel files.
+    {
+      "file": "packages/studio/src/components/editor/domEditing.ts",
+      "exports": ["*"],
+    },
     // Exported for render.test.ts (exported-for-tests pattern).
     {
       "file": "packages/cli/src/commands/render.ts",

packages/core/src/lint/rules/gsap.test.ts

@@ -865,4 +865,57 @@ describe("GSAP rules", () => {
     const finding = result.findings.find((f) => f.code === "gsap_from_opacity_noop");
     expect(finding).toBeUndefined();
   });
+
+  it("warns when gsap.timeline is created but not registered in __timelines", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="root" data-width="1920" data-height="1080">
+    <div id="box">Hello</div>
+  </div>
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
+  <script>
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#box", { opacity: 0.5, duration: 2 });
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_timeline_not_registered");
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe("warning");
+  });
+
+  it("does NOT warn when timeline is registered in __timelines", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="root" data-width="1920" data-height="1080">
+    <div id="box">Hello</div>
+  </div>
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#box", { opacity: 0.5, duration: 2 });
+    window.__timelines["root"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_timeline_not_registered");
+    expect(finding).toBeUndefined();
+  });
+
+  it("does NOT warn for sub-compositions (template-based)", async () => {
+    const html = `
+<template>
+  <div data-composition-id="sub" data-width="1920" data-height="1080">
+    <div id="box">Hello</div>
+  </div>
+  <script>
+    const tl = gsap.timeline({ paused: true });
+    tl.to("#box", { opacity: 0.5, duration: 2 });
+  </script>
+</template>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_timeline_not_registered");
+    expect(finding).toBeUndefined();
+  });
 });

packages/core/src/lint/rules/gsap.ts

@@ -785,6 +785,33 @@ export const gsapRules: LintRule<LintContext>[] = [
     return findings;
   },
 
+  // gsap_timeline_not_registered
+  ({ scripts, rawSource, options }) => {
+    const findings: HyperframeLintFinding[] = [];
+    const canInheritFromHost =
+      options.isSubComposition || rawSource.trimStart().toLowerCase().startsWith("<template");
+
+    for (const script of scripts) {
+      const content = script.content;
+      if (!/gsap\.timeline/.test(content)) continue;
+      const hasRegistration = WINDOW_TIMELINE_ASSIGN_PATTERN.test(content);
+      if (hasRegistration || canInheritFromHost) continue;
+      findings.push({
+        code: "gsap_timeline_not_registered",
+        severity: "warning",
+        message:
+          "GSAP timeline is created but never registered in window.__timelines. " +
+          "The runtime discovers timelines from this registry — without registration, " +
+          "animations will not play during preview or render.",
+        fixHint:
+          "Add `window.__timelines = window.__timelines || {};` and " +
+          '`window.__timelines["root"] = tl;` after creating the timeline (use the ' +
+          "composition's data-composition-id as the key).",
+      });
+    }
+    return findings;
+  },
+
   // gsap_from_opacity_noop — CSS opacity:0 + gsap.from({opacity:0}) = invisible forever
   async ({ styles, scripts, tags }) => {
     const findings: HyperframeLintFinding[] = [];

packages/core/src/runtime/init.test.ts

@@ -692,4 +692,23 @@ describe("initSandboxRuntimeModular", () => {
     expect(window.__playerReady).toBe(true);
     expect(window.__renderReady).toBe(true);
   });
+
+  it("seeks captured timeline to currentTime on initial bind", () => {
+    const seekTimes: number[] = [];
+    const tl = createMockTimeline(5);
+    const origTotalTime = tl.totalTime;
+    tl.totalTime = ((time: number, ...rest: unknown[]) => {
+      seekTimes.push(time);
+      (origTotalTime as Function).call(tl, time, ...rest);
+    }) as RuntimeTimelineLike["totalTime"];
+
+    document.body.innerHTML = `
+      <div data-composition-id="root" data-duration="5" data-width="1920" data-height="1080"></div>
+    `;
+    window.__timelines = { root: tl };
+    initSandboxRuntimeModular();
+
+    expect(seekTimes.length).toBeGreaterThan(0);
+    expect(seekTimes[0]).toBe(0);
+  });
 });

packages/core/src/runtime/init.ts

@@ -948,6 +948,10 @@ export function initSandboxRuntimeModular(): void {
         // clock not yet initialized — duration will be set during TransportClock setup
       }
       state.capturedTimeline.pause();
+      const seekTime = Math.max(0, state.currentTime || 0);
+      if (typeof state.capturedTimeline.totalTime === "function") {
+        state.capturedTimeline.totalTime(seekTime, false);
+      }
     }
     if (resolution.diagnostics) {
       postRuntimeMessage({

packages/core/src/studio-api/routes/files.test.ts

@@ -327,6 +327,34 @@ const tl = gsap.timeline();
     expect(anim.properties.opacity).toBe(1);
   });
 
+  it("add mutation returns 400 when fromProperties provided for non-fromTo method", async () => {
+    const projectDir = createProjectDir();
+    const EMPTY_COMP = `<!DOCTYPE html><html><body><div id="el"></div><script data-hyperframes-gsap>
+const tl = gsap.timeline();
+</script></body></html>`;
+    writeHtml(projectDir, "empty.html", EMPTY_COMP);
+    const app = new Hono();
+    registerFileRoutes(app, createAdapter(projectDir));
+
+    const res = await app.request("http://localhost/projects/demo/gsap-mutations/empty.html", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        type: "add",
+        targetSelector: "#el",
+        method: "to",
+        position: 0,
+        duration: 0.5,
+        ease: "power2.out",
+        properties: { opacity: 1 },
+        fromProperties: { opacity: 0 },
+      }),
+    });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toContain("fromProperties");
+  });
+
   it("edits a template-wrapped tween in place, preserving gsap.set and the IIFE", async () => {
     const projectDir = createProjectDir();
     writeComp(projectDir, "scene.html", TEMPLATE_COMP);

packages/core/src/studio-api/routes/files.ts

@@ -17,6 +17,7 @@ import { isAudioFile } from "../helpers/mime.js";
 import { generateWaveformCache } from "../helpers/waveform.js";
 import { validateUploadedMediaBuffer } from "../helpers/mediaValidation.js";
 import { isSafePath } from "../helpers/safePath.js";
+import type { GsapAnimation } from "../../parsers/gsapSerialize.js";
 import {
   removeElementFromHtml,
   patchElementInHtml,
@@ -600,26 +601,44 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
       removeAnimationFromScript,
     } = await loadGsapParser();
 
+    function requireAnimation(
+      scriptText: string,
+      animationId: string,
+    ): { anim: GsapAnimation } | { err: Response } {
+      const parsed = parseGsapScript(scriptText);
+      const anim = parsed.animations.find((a) => a.id === animationId);
+      if (!anim) return { err: c.json({ error: "animation not found" }, 404) };
+      return { anim };
+    }
+
+    function requireFromToAnimation(
+      scriptText: string,
+      animationId: string,
+    ): { anim: GsapAnimation } | { err: Response } {
+      const result = requireAnimation(scriptText, animationId);
+      if ("err" in result) return result;
+      if (result.anim.method !== "fromTo")
+        return { err: c.json({ error: "animation is not a fromTo" }, 400) };
+      return result;
+    }
+
     let newScript: string;
 
     // fallow-ignore-next-line complexity
     switch (body.type) {
       case "update-property": {
-        const parsed = parseGsapScript(block.scriptText);
-        const anim = parsed.animations.find((a) => a.id === body.animationId);
-        if (!anim) return c.json({ error: "animation not found" }, 404);
+        const r = requireAnimation(block.scriptText, body.animationId);
+        if ("err" in r) return r.err;
         newScript = updateAnimationInScript(block.scriptText, body.animationId, {
-          properties: { ...anim.properties, [body.property]: body.value },
+          properties: { ...r.anim.properties, [body.property]: body.value },
         });
         break;
       }
       case "update-from-property": {
-        const parsed = parseGsapScript(block.scriptText);
-        const anim = parsed.animations.find((a) => a.id === body.animationId);
-        if (!anim) return c.json({ error: "animation not found" }, 404);
-        if (anim.method !== "fromTo") return c.json({ error: "animation is not a fromTo" }, 400);
+        const r = requireFromToAnimation(block.scriptText, body.animationId);
+        if ("err" in r) return r.err;
         newScript = updateAnimationInScript(block.scriptText, body.animationId, {
-          fromProperties: { ...(anim.fromProperties ?? {}), [body.property]: body.value },
+          fromProperties: { ...(r.anim.fromProperties ?? {}), [body.property]: body.value },
         });
         break;
       }
@@ -628,6 +647,9 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
         break;
       }
       case "add": {
+        if (body.fromProperties && body.method !== "fromTo") {
+          return c.json({ error: "fromProperties is only valid for method=fromTo" }, 400);
+        }
         const result = addAnimationToScript(block.scriptText, {
           targetSelector: body.targetSelector,
           method: body.method,
@@ -645,41 +667,35 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
         break;
       }
       case "add-property": {
-        const parsed = parseGsapScript(block.scriptText);
-        const anim = parsed.animations.find((a) => a.id === body.animationId);
-        if (!anim) return c.json({ error: "animation not found" }, 404);
+        const r = requireAnimation(block.scriptText, body.animationId);
+        if ("err" in r) return r.err;
         newScript = updateAnimationInScript(block.scriptText, body.animationId, {
-          properties: { ...anim.properties, [body.property]: body.defaultValue },
+          properties: { ...r.anim.properties, [body.property]: body.defaultValue },
         });
         break;
       }
       case "add-from-property": {
-        const parsed = parseGsapScript(block.scriptText);
-        const anim = parsed.animations.find((a) => a.id === body.animationId);
-        if (!anim) return c.json({ error: "animation not found" }, 404);
-        if (anim.method !== "fromTo") return c.json({ error: "animation is not a fromTo" }, 400);
+        const r = requireFromToAnimation(block.scriptText, body.animationId);
+        if ("err" in r) return r.err;
         newScript = updateAnimationInScript(block.scriptText, body.animationId, {
-          fromProperties: { ...(anim.fromProperties ?? {}), [body.property]: body.defaultValue },
+          fromProperties: { ...(r.anim.fromProperties ?? {}), [body.property]: body.defaultValue },
         });
         break;
       }
       case "remove-property": {
-        const parsed = parseGsapScript(block.scriptText);
-        const anim = parsed.animations.find((a) => a.id === body.animationId);
-        if (!anim) return c.json({ error: "animation not found" }, 404);
-        const filtered = { ...anim.properties };
+        const r = requireAnimation(block.scriptText, body.animationId);
+        if ("err" in r) return r.err;
+        const filtered = { ...r.anim.properties };
         delete filtered[body.property];
         newScript = updateAnimationInScript(block.scriptText, body.animationId, {
           properties: filtered,
         });
         break;
       }
       case "remove-from-property": {
-        const parsed = parseGsapScript(block.scriptText);
-        const anim = parsed.animations.find((a) => a.id === body.animationId);
-        if (!anim) return c.json({ error: "animation not found" }, 404);
-        if (anim.method !== "fromTo") return c.json({ error: "animation is not a fromTo" }, 400);
-        const filtered = { ...(anim.fromProperties ?? {}) };
+        const r = requireFromToAnimation(block.scriptText, body.animationId);
+        if ("err" in r) return r.err;
+        const filtered = { ...(r.anim.fromProperties ?? {}) };
         delete filtered[body.property];
         newScript = updateAnimationInScript(block.scriptText, body.animationId, {
           fromProperties: filtered,

packages/core/src/studio-api/routes/projects.ts

@@ -1,7 +1,26 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
 import type { Hono } from "hono";
 import type { StudioApiAdapter } from "../types.js";
 import { walkDir } from "../helpers/safePath.js";
 
+const COMPOSITION_ID_RE = /data-composition-id\s*=/;
+
+async function filterCompositionFiles(projectDir: string, files: string[]): Promise<string[]> {
+  const htmlFiles = files.filter((f) => f.endsWith(".html"));
+  const checks = await Promise.all(
+    htmlFiles.map(async (f) => {
+      try {
+        const content = await readFile(join(projectDir, f), "utf-8");
+        return COMPOSITION_ID_RE.test(content);
+      } catch {
+        return false;
+      }
+    }),
+  );
+  return htmlFiles.filter((_, i) => checks[i]);
+}
+
 export function registerProjectRoutes(api: Hono, adapter: StudioApiAdapter): void {
   // List all projects
   api.get("/projects", async (c) => {
@@ -25,6 +44,7 @@ export function registerProjectRoutes(api: Hono, adapter: StudioApiAdapter): voi
     const project = await adapter.resolveProject(c.req.param("id"));
     if (!project) return c.json({ error: "not found" }, 404);
     const files = walkDir(project.dir);
-    return c.json({ id: project.id, dir: project.dir, title: project.title, files });
+    const compositions = await filterCompositionFiles(project.dir, files);
+    return c.json({ id: project.id, dir: project.dir, title: project.title, files, compositions });
   });
 }