fix(studio): playhead keyframe edits keep their ease, undo names its edit and never waits on videos

.github/workflows/ci.yml

@@ -850,6 +850,8 @@ jobs:
             packages/studio/data/projects/fade-handles
           cp -R packages/studio/tests/e2e/fixtures/inline-text-caret \
             packages/studio/data/projects/inline-text-caret
+          cp -R packages/studio/tests/e2e/fixtures/undo-socket-pool \
+            packages/studio/data/projects/undo-socket-pool
       - name: Read the base branch's work-count ceilings
         # A ceiling may not disappear, or rise without a new reason, against the branch this PR merges into.
         if: github.event_name == 'pull_request'
@@ -1000,6 +1002,28 @@ jobs:
           STUDIO_URL="http://localhost:5317/#project/inline-text-caret" \
             EVIDENCE_DIR=/tmp/inline-text-caret \
             node packages/studio/tests/e2e/inline-text-caret.mjs
+      - name: Install ffmpeg for the paused-video fixture
+        if: success() || failure()
+        uses: ./.github/actions/install-ffmpeg-linux
+      - name: Undo while paused videos hold the preview's sockets
+        # Counts the undo's wait for a socket, not its total time: unpinned it is 0 ms.
+        if: success() || failure()
+        run: |
+          set -euo pipefail
+          NODE_ENV=production bun run --cwd packages/studio dev -- --port 5318 --strictPort &
+          SERVER_PID=$!
+          trap 'kill "$SERVER_PID" 2>/dev/null || true' EXIT
+          for i in $(seq 1 60); do
+            if curl -sf "http://localhost:5318/" >/dev/null 2>&1; then break; fi
+            sleep 1
+          done
+          if ! curl -sf "http://localhost:5318/" >/dev/null 2>&1; then
+            echo "FAIL: studio dev server did not start on port 5318"
+            exit 1
+          fi
+          STUDIO_URL="http://localhost:5318/#project/undo-socket-pool" \
+            STUDIO_PROJECT_DIR="$PWD/packages/studio/data/projects/undo-socket-pool" \
+            node packages/studio/tests/e2e/undo-socket-pool.mjs | tee /tmp/undo-socket-pool.json
       - name: Upload gate evidence
         # The gate's whole output is machine-readable evidence, and a red run is
         # exactly when someone needs to read it. Keep it on failure too.
@@ -1011,6 +1035,7 @@ jobs:
             /tmp/timeline-gate-*.json
             /tmp/studio-open-counts.json
             /tmp/inline-text-caret/*.png
+            /tmp/undo-socket-pool.json
           if-no-files-found: error
 
   # Manual editing accuracy in the built Studio, gated against the base branch's baseline.json.

.oxlintrc.json

@@ -45,6 +45,45 @@
         "react-hooks/rules-of-hooks": "error",
         "react-hooks/exhaustive-deps": "warn"
       }
+    },
+    {
+      "files": ["packages/studio/src/**/*.ts", "packages/studio/src/**/*.tsx"],
+      "excludeFiles": [
+        "**/*.test.ts",
+        "**/*.test.tsx",
+        "**/*TestUtils.ts",
+        "**/*TestUtils.tsx",
+        "**/*TestHarness.ts",
+        "**/*TestHarness.tsx",
+        "packages/studio/src/utils/studioApiFetch.ts"
+      ],
+      "rules": {
+        "no-restricted-globals": [
+          "error",
+          {
+            "name": "fetch",
+            "message": "Use studioApiFetch (utils/studioApiFetch.ts): it keeps Studio's requests off the preview media's sockets."
+          }
+        ],
+        "no-restricted-properties": [
+          "error",
+          {
+            "object": "window",
+            "property": "fetch",
+            "message": "Use studioApiFetch (utils/studioApiFetch.ts): it keeps Studio's requests off the preview media's sockets."
+          },
+          {
+            "object": "globalThis",
+            "property": "fetch",
+            "message": "Use studioApiFetch (utils/studioApiFetch.ts): it keeps Studio's requests off the preview media's sockets."
+          },
+          {
+            "object": "self",
+            "property": "fetch",
+            "message": "Use studioApiFetch (utils/studioApiFetch.ts): it keeps Studio's requests off the preview media's sockets."
+          }
+        ]
+      }
     }
   ]
 }

docs/packages/studio-server.mdx

@@ -35,6 +35,18 @@ export function mountStudioApi(
 }
 ```
 
+When it is served from loopback (`localhost`, `127.0.0.1` or `[::1]`), Studio
+sends its API requests without cookies, so they don't queue behind the
+preview's media. On any other origin it sends them as usual, so remote and
+proxied setups (Codespaces, tunnels, an access proxy) keep their cookies by
+default. A loopback host that authenticates its mounted API with same-origin
+cookies sets `VITE_STUDIO_API_SAME_ORIGIN_CREDENTIALS=true`, at build time or at
+runtime in `window.__HF_STUDIO_ENV__`; it costs that host the connection
+speedup.
+Studio reads the flag once, when its modules load, so set
+`window.__HF_STUDIO_ENV__` before loading Studio; the CLI injects it, but a host
+that mounts the API itself must inject it too.
+
 A `StudioApiAdapter` supplies:
 
 - project listing and resolution;

packages/parsers/src/gsapParserAcorn.ts

@@ -1903,7 +1903,7 @@ export function parseGsapScriptAcornForWrite(script: string): ParsedGsapAcornFor
       tweenCallToAnimation(call, scope, script, identifierBindings),
     );
     applyTimelineDefaults(rawAnims, detection.defaults);
-    resolveTimelinePositions(rawAnims);
+    resolveTimelinePositions(rawAnims, collectAddLabelDefs(ast, ref, scope, calls));
     const animations = assignStableIds(rawAnims);
     const located = calls.map((call, i) => ({
       id: animations[i]!.id,

packages/parsers/src/gsapWriter.acorn.test.ts

@@ -13,6 +13,7 @@ import {
   copyAnimationsInScript,
   removeAnimationFromScript,
   removeKeyframeFromScript,
+  replaceTweenWithKeyframesInScript,
   updateAnimationInScript,
   updateKeyframeInScript,
 } from "./gsapWriterAcorn.js";
@@ -535,3 +536,60 @@ tl.from("#goodbye", { opacity: 0 }, 1);`;
     expect(copyAnimationsInScript(script, "#tag", "#tag-2", 3)).toBe(script);
   });
 });
+
+describe("replaceTweenWithKeyframesInScript", () => {
+  const script = `var tl = gsap.timeline({ paused: true });
+tl.fromTo("#a", { x: 0 }, { x: 100, duration: 1, delay: 0.5, onStart: go }, 1);
+tl.set("#b", { x: 5 }, 0);`;
+  const tweenOn = (selector: string) =>
+    parseGsapScriptAcorn(script).animations.find((a) => a.targetSelector === selector)!;
+  const edit = (position: number, extra = {}) => ({
+    targetSelector: "#a",
+    position,
+    duration: 2,
+    keyframes: [
+      { percentage: 100, properties: { x: 100 } },
+      { percentage: 0, properties: { x: 0 } },
+    ],
+    ...extra,
+  });
+  const rewritten = (out: string | null) => out?.split("\n")[1];
+
+  it("leaves a tween it cannot find, or a set(), to the caller", () => {
+    expect(replaceTweenWithKeyframesInScript(script, "#missing", edit(1))).toBeNull();
+    expect(replaceTweenWithKeyframesInScript(script, tweenOn("#b").id, edit(0))).toBeNull();
+  });
+
+  it("rewrites a tween that stays put as to(), keeping its position, delay and callbacks", () => {
+    const { id, resolvedStart } = tweenOn("#a");
+    expect(rewritten(replaceTweenWithKeyframesInScript(script, id, edit(resolvedStart!)))).toBe(
+      'tl.to("#a", { keyframes: { "0%": { x: 0 }, "100%": { x: 100 } }, delay: 0.5, onStart: go, duration: 2 }, 1);',
+    );
+  });
+
+  it("moves a retargeted tween to the new position without its delay, with the edit's ease", () => {
+    const out = replaceTweenWithKeyframesInScript(
+      script,
+      tweenOn("#a").id,
+      edit(3, { targetSelector: "#c", ease: "none", easeEach: "power1.in" }),
+    );
+    expect(rewritten(out)).toBe(
+      'tl.to("#c", { keyframes: { "0%": { x: 0 }, "100%": { x: 100 }, easeEach: "power1.in" }, onStart: go, duration: 2, ease: "none" }, 3);',
+    );
+  });
+});
+
+describe("position argument", () => {
+  it("is added after the last argument, so a call with a trailing comma stays valid", () => {
+    const script = `var tl = gsap.timeline({ paused: true });
+tl.to(
+  "#a",
+  { x: 100, duration: 1 },
+);
+window.__timelines["t"] = tl;`;
+    const id = parseGsapScriptAcorn(script).animations[0]!.id;
+    const result = updateAnimationInScript(script, id, { position: 0.5 });
+    expect(() => new Function("gsap", "window", result)).not.toThrow();
+    expect(parseGsapScriptAcorn(result).animations[0]!.position).toBe(0.5);
+  });
+});

packages/parsers/src/gsapWriterAcorn.ts

@@ -443,7 +443,8 @@ function overwritePosition(ms: MagicString, call: TweenCallInfo, position: numbe
   if (call.positionArg) {
     ms.overwrite(call.positionArg.start, call.positionArg.end, valueToCode(position));
   } else {
-    ms.appendLeft(call.node.end - 1, `, ${valueToCode(position)}`);
+    const last = call.node.arguments.at(-1);
+    ms.appendLeft(last ? last.end : call.node.end - 1, `, ${valueToCode(position)}`);
   }
 }
 
@@ -1790,6 +1791,54 @@ export function materializeKeyframesFromScript(
   return ms.toString();
 }
 
+/**
+ * Rewrites a tween as `to()` with these keyframes where it stands: the call keeps its place in the
+ * script and its position argument, so a tween placed after it ('>', '<', '+=', none) stays put.
+ */
+export function replaceTweenWithKeyframesInScript(
+  script: string,
+  animationId: string,
+  edit: {
+    targetSelector: string;
+    position: number;
+    duration: number;
+    keyframes: Array<{
+      percentage: number;
+      properties: Record<string, number | string>;
+      ease?: string;
+      auto?: boolean;
+    }>;
+    ease?: string;
+    easeEach?: string;
+  },
+): string | null {
+  const parsed = parseGsapScriptAcornForWrite(script);
+  const target = parsed?.located.find((l) => l.id === animationId);
+  const call = target?.call;
+  if (!target || call?.varsArg?.type !== "ObjectExpression") return null;
+  const { animation } = target;
+  if (animation.method !== "to" && animation.method !== "from" && animation.method !== "fromTo")
+    return null;
+  const ms = new MagicString(script);
+  const start = animation.resolvedStart ?? animation.position;
+  const moved = typeof start !== "number" || Math.abs(start - edit.position) > 5e-4;
+  const kept = preservedVarsEntries(call.varsArg, script).filter(
+    (e) => !/^\s*duration\s*:/.test(e) && !(moved && /^\s*delay\s*:/.test(e)),
+  );
+  const sorted = [...edit.keyframes].sort((a, b) => a.percentage - b.percentage);
+  const parts = [`keyframes: ${buildKeyframeObjectCode(sorted, edit.easeEach)}`, ...kept];
+  parts.push(`duration: ${valueToCode(edit.duration)}`);
+  if (edit.ease) parts.push(`ease: ${JSON.stringify(edit.ease)}`);
+  if (animation.hasUnresolvedSelector || animation.targetSelector !== edit.targetSelector) {
+    const selectorArg = call.node.arguments[0];
+    ms.overwrite(selectorArg.start, selectorArg.end, JSON.stringify(edit.targetSelector));
+  }
+  convertMethodToTo(ms, animation, call, call.varsArg);
+  overwriteVarsArg(ms, call, `{ ${parts.join(", ")} }`);
+  if (moved) overwritePosition(ms, call, edit.position);
+  return ms.toString();
+}
+
 // ── Add animation with keyframes ──────────────────────────────────────────────
 
 /** Insert a new keyframed `to()` call and return the new animation ID. */

packages/studio-server/src/routes/files.patchRace.test.ts

@@ -14,6 +14,7 @@ import { Hono } from "hono";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { fileContentVersion, identifyFileWrite } from "../helpers/fileVersion";
 import { registerFileRoutes } from "./files";
+import { stubAdapter } from "./stubAdapter.test-helpers";
 
 const hooks = vi.hoisted(() => ({
   transforming: undefined as (() => void) | undefined,
@@ -76,15 +77,7 @@ function project() {
   const path = join(dir, "index.html");
   writeFileSync(path, ORIGINAL);
   const app = new Hono();
-  registerFileRoutes(app, {
-    listProjects: () => [],
-    resolveProject: async (id: string) => ({ id, dir }),
-    bundle: async () => null,
-    lint: async () => ({ findings: [] }),
-    runtimeUrl: "/api/runtime.js",
-    rendersDir: () => "/tmp/renders",
-    startRender: () => ({ id: "job", status: "rendering", progress: 0, outputPath: "/tmp/o.mp4" }),
-  });
+  registerFileRoutes(app, stubAdapter(dir));
   const post = (route: string, body: unknown) =>
     app.request(`http://localhost/projects/demo/file-mutations/${route}`, {
       method: "POST",