feat(studio): instant, flicker-free manual editing (#1605)

* chore(producer): shim __filename/__dirname in the CJS banner

Bundled CJS deps like wawoff2 call __dirname; without the shim they throw
"__dirname is not defined in ES module" at render time. Also ignore .zed/.

* chore(producer): use a template literal for the CJS banner (review nit)

* feat(core): add GSAP keyframe + motion-path source mutations

Array-form keyframe removal in both the recast and acorn writers, plus
update/add/remove-motion-path-point and add-motion-path. Exclude _auto and
data from tween property-group classification.

* fix(core): address #1554 review — data-exclusion test, split-fix doc, motion-path sentinel, parity blocks

- Regression test for the `data` GSAP-key exclusion (parallel to _auto).
- splitAnimationsInScript: documented that .fromTo()/.to() correctly stay out of the
  from-branch (only .from() reverts) and the <= boundary; added mid-flight straddle tests.
- addMotionPathToScript failure path returns id: null (was empty-string sentinel); caller updated.
- Parity blocks for addKeyframeToScript array-form + updateKeyframeInScript (mirroring
  removeKeyframeFromScript). Surfaced a latent acorn array-form partial-props merge bug —
  documented as it.skip with a ready assertion (acorn cutover follow-up).

* feat(core): route motion-path mutations through studio-api + fix clip stamping

Wire the new mutations into the file save route. Only authored clips suppress
descendant stamping, so auto-stamped animated scenes can inline-expand.

Hide in-flow timed clips with `display:none` only when they are LEAF clips (no
nested timed clips). `display:none` on a container removes its whole subtree,
hiding descendants that are still inside their own visibility window — e.g. an
in-flow composition root whose effective window clamps to the timeline end would
black out a child video that should still show (the hdr-hlg regression).
Containers keep `visibility:hidden`, which a visible descendant can override; only
leaves leave the flow, which is all the split-overlap case needs.

* feat(core): strip legacy path-offset/rotation + drop obsolete studio lint rule

A position or rotation add/set mutation makes the GSAP timeline the single source of
truth for that channel, so any lingering --hf-studio-offset / --hf-studio-rotation CSS
var must be cleared to avoid double-applying. stripStudioEditsFromTarget now clears both
channels, and the add-strip fires for the position AND rotation property groups.

Also removes the obsolete `gsap_studio_edit_blocked` lint rule: it warned that Studio
cannot save drag/resize edits to elements in a registered timeline — the exact premise
the single-source work inverts (the timeline is now the edit target). Removed the rule,
its now-unused TIMELINE_REGISTRY_ASSIGN_PATTERN import, and its 5 tests.

* fix(core): address #1555 review — complete hold-sync, invalidate clip cache, strip rotation channel

- HOLD_SYNC_MUTATION_TYPES: add add-motion-path (load-bearing — addMotionPathToScript
  authors past t=0 → first-frame snap-to-(0,0) without the hold), update-meta,
  shift-positions, scale-positions, split-animations. (add stays out: flat tweens
  only, syncPositionHoldsBeforeKeyframes is a no-op for non-keyframed tweens.)
- init.ts: timedClip in-flow/leaf WeakMaps now invalidate on clipTreeSignature change;
  visible/hidden branches both go through isTimedClipInFlow (was .get() by accident).
- keyframesWriteRotation mirrors keyframesWritePosition so a rotation-only keyframe set
  strips the stale --hf-studio-rotation channel.

* feat(studio): GSAP runtime read layer + shared helpers

* fix(studio): address #1607 review — cold-parse vs fetch-error budgets, isZeroDurationSet, array-ease tests

- useGsapAnimationFetchFallback: discriminate resolved/fetch-error/cold; only the cold
  (warm-but-zero) race gets the full ~600ms retry budget — a hard fetch error retries once.
- Extract isZeroDurationSet (was !(duration>0) duplicated); rejects NaN, documents intent.
- parsePercentageKeyframes: cite GSAP even-index spread; tests that a per-entry/interior
  ease is stripped without shifting the other keyframes' percentages.

* feat(studio): GSAP drag/commit/bridge editing infra

* fix(studio): address #1608 review — facade awaits commit, strict stale-parse guard, clearProps restore

BLOCKER: useSafeGsapCommitMutation now RETURNS the (.catch-chained) commit promise and the
commitMutation facade awaits it — so await session.commitMutation(...) resolves AFTER the
server save, fixing both consumers (useEnableKeyframes + useGestureCommit's
showToast/requestSeek/idle, which were firing before the save landed). SafeGsapCommitMutation
return type widened void→Promise<void> (fire-and-forget consumers ignore it).
- stale-parse guard uses hasNonHoldTweenForElement (a leftover hold set no longer counts as live).
- commitFlatViaKeyframes snapshots dragged gsap values before clearProps + restores after seek,
  so a failed commit leaves the dropped pose, not a cleared element.

* feat(studio): motion-path geometry + commit helpers

* docs(studio): address #1609 review — document occlusion fade-in invariant, donut limit, nearestPointOnPath t-semantics

* feat(studio): on-canvas motion-path overlay

* fix(studio): address #1610 review — scope dblclick to pan-surface, kind-aware geometry guard, gate createMode, screen-space drag threshold

* feat(studio): keyframes flag, gesture recording + timeline/selection refinements

* fix(studio): address #1611 review — fetch-first keyframe path, gated hydration, dev-gated debug + gesture warn, per-group gesture tweens

- useEnableKeyframes: parse current source first (null-vs-[] distinction) so a delete-all's
  empty parse isn't overridden by a stale selectedGsapAnimations cache.
- useStudioUrlState: freeze the hydration effect's time dep once hydrated (was re-running every tick).
- useGestureRecording: dev-gated console.warn when the live-preview runtime throws (was silent).
- playerStore: gate window.__playerStore behind dev (guarded import.meta.env.DEV).
- useGestureCommit: partition recorded keyframes by property group → one add-with-keyframes per
  group, so a mixed gesture no longer yields an untagged legacy tween.

* feat(studio): single-source manual offset + rotation via the GSAP timeline

Dragging or rotating an element writes into the GSAP timeline (the single source of
truth) instead of a parallel --hf-studio-offset / --hf-studio-rotation CSS var: static
elements commit a tl.set (idempotent on re-edit), tweened elements edit keyframes, and
the live preview moves via gsap.set so what you see equals what is written and renders.
Removes the dual-channel CSS-var/transform reconciliation behind the
fling / disappear / runaway / double-stack / wrong-start bug class — for BOTH position
and rotation (gesture base read from the gsap transform, gsap.set live preview, tl.set/
keyframe commit, dropped the handleDom*Commit CSS fallbacks).

Subcompositions edit the same single-source way, which surfaced and fixes:
- resolve a subcomp element's source file via the composition-id map (the runtime drops
  the source linkage when inlining the subcomposition);
- a selected element's selection box AND motion path use basic visibility, not the
  occlusion heuristic (a backgroundless opacity-1 scene above it is not an opaque cover);
- soft reload rebuilds ONLY the committed composition's timeline, leaving other
  compositions' timelines intact (no cross-composition revert);
- read keyframes from the element's OWN composition timeline (scan all timelines, not
  the first unstable key);
- delete-all uses a soft reload too, so editing no longer hard-reloads the iframe.

* fix(studio): address #1567 review — drop drag-intercept flag, harden softReload onerror, tighten runtime ladder, per-group gestures

- DROP STUDIO_GSAP_DRAG_INTERCEPT_ENABLED: single-source GSAP intercept is the only
  position/rotation channel; the false branch silently killed drag+rotate (and let GSAP
  elements into the keyframe-corrupting CSS path). Removed flag + dead branch + env def + tests.
- gsapSoftReload: plugin onerror no longer fakes success — signals onAsyncFailure so the caller
  full-reloads; honors __hfMotionPathPluginLoading so a concurrent reload can't queue a dup script.
- gsapDragCommit: resolveDragRuntime narrows the as-any ladder; a mid-seek throw logs + drops
  partial reads (no phantom identity) and re-applies the drag override in finally.
- MotionPathOverlay: park-timer cleanup keyed on animId change.
- useGestureCommit: partitionKeyframesByGroup wraps the add-with-keyframes sites (per #1611 review).

* feat(studio): patchRuntimeTweenInPlace — update a tween's values in place

Defensive runtime helper: locate the element's tween in window.__timelines via the
shared resolveRuntimeTween scan, update its set/keyframe vars, invalidate, and re-seek
the playhead — without re-running the whole composition. Returns false (caller falls
back to soft reload) for any shape it can't safely patch (no tween, dynamic/computed
keyframes, motionPath arc, channel mismatch, or any error). Foundation for instant,
flicker-free manual edits.

* fix(studio): address #1612 review — channel-aware set resolution + decline dynamic-expression patches

- resolveRuntimeTween gains an optional channels[] hint; for kind:set it prefers the set whose
  vars carry one of the patched channels and never returns a disjoint-only set (e.g. won't write
  {x,y} into a co-located {rotation} set). patchRuntimeTweenInPlace derives channels from the props.
- patchSet declines (returns false → soft reload) when overwriting a string/dynamic vars[ch],
  instead of silently dropping the computed expression.

* feat(studio): instantPatch fast path in runCommit

A commit carrying an instantPatch option tries patchRuntimeTweenInPlace first; on
success the preview updates in place with NO reload (instant), on false it falls back
to the existing soft reload. Extracts the preview-sync tail into a testable
applyPreviewSync helper. No behavior change when instantPatch is absent.

* feat(studio): route static position/rotation set drags through instantPatch

Static-element position and rotation set commits now attach instantPatch{selector,
change:{kind:set}} so the drag updates in place with no reload. Structural ops (new
tween add, delete-all, convert/split/materialize) and keyframe edits deliberately omit
it and keep the soft reload — keyframe instant-patch needs object-form keyframe support
in patchRuntimeTweenInPlace (deferred).

* fix(studio): address #1613 review — derive instantPatch from the mutation, patch both coalesced commits, wire onAsyncFailure

- commitStaticGsapPosition/Rotation derive instantPatch.change.props from the actual
  update-property mutation(s) sent (one source of truth → findUnsafeMutationValues-validated
  values flow into the patch; can't drift).
- Coalesced x/y: the intermediate x commit also carries instantPatch{x}, the y commit {x,y},
  so a second-POST failure still leaves the preview patched for what persisted.
- applyPreviewSync passes reloadPreview as onAsyncFailure (plugin-CDN load error → full reload);
  per U4 the synchronous false still does NOT escalate.
- (channel disambiguation from #1612 verified end-to-end: {x,y}→position set, {rotation}→rotation set.)

* feat(studio): no full iframe remount for soft-reloadable edits

A softReload edit (and the SDK single-script refresh) no longer escalates to a full
reloadPreview() iframe remount when applySoftReload returns false — the live gsap.set
already shows the value, and a remount is the worst flash + re-inlines subcomps
(reverting their keyframes). verifyTimelinesPopulated now checks the expected target
keys the re-run registers, so a correct scoped re-run doesn't spuriously report empty.
Full reload stays only for the structural (no-softReload) and ambiguous-script paths.

* feat(studio): pre-load MotionPathPlugin so motion-path edits don't async-flash

ensureMotionPathPluginLoaded() runs once at the preview iframe-load seam (NLELayout
onIframeLoad), eagerly loading + registering MotionPathPlugin without killing the
timeline. So when a user adds a motion path to a composition that didn't originally
use one, the soft reload runs synchronously instead of taking the kill-then-await-CDN
async path (the flash). Idempotent + defensive; the existing async fallback stays for
genuine cold-start/CDN-failure.

* fix(studio): don't re-save + reload when source editor syncs externally

The SourceEditor's CodeMirror update listener fired onChange on ANY docChanged —
including the programmatic dispatch that syncs external content (e.g. a manual-edit
commit writing the source back into the open editor). That made the editor re-save the
file and bump refreshKey, fully reloading the preview iframe on every drag/keyframe
edit — defeating the in-place instant patch and causing the flash. Annotate the
programmatic sync (ExternalSync) and skip onChange for it, so only real keystrokes save.

* fix(core): inject MotionPathPlugin into preview when a composition uses motionPath

A studio-created motion path writes a gsap motionPath tween into the single-source
timeline, but the preview HTML only loaded gsap core — so the first render threw
"Invalid property motionPath ... Missing plugin?". Detect motionPath usage and inject
MotionPathPlugin right after the composition's gsap script, version-matched to it.

* fix(studio): dedup __hfMotionPathPluginLoading type decl (restack artifact)

* fix(studio): address #1605 review — distinguish soft-reload failure modes + observability, SourceEditor focus guard

BLOCKER: applySoftReload now returns SoftReloadResult ('applied' | 'verify-failed' |
'cannot-soft-reload') instead of a bare bool. applyPreviewSync + sdkRefresh escalate to a full
reloadPreview() on the PERMANENT 'cannot-soft-reload' (no gsap/rebind hook/scopable key/script,
or sync re-run threw) — fixing the silent-stale-preview U4 dropped — but still suppress the
TRANSIENT 'verify-failed' (live gsap.set is correct). Telemetry: gsap_soft_reload_outcome
(origin/result/escalated) + gsap_instant_patch_fallback, so the U4 invariant is enforced, not asserted.
- SourceEditor: skip the programmatic external-sync replace while the editor is focused, so an
  in-flight commit doesn't clobber the user's uncommitted keystrokes (ExternalSync kept for unfocused).
- Verified ensureMotionPathPluginLoaded already guards __hfMotionPathPluginLoading (no double-append).

* fix(core): align __clipTree and __clipManifest ids via stableClipId

Timeline inline expansion was dead for nested children inside index.html:
the tree keyed id-less elements by a synthetic __clip-N while the manifest
keyed them null, so parent<->child never joined. Both now resolve identity
through stableClipId (id || data-hf-id), which every generated element has.

* fix(core): strip baked runtime + tag comp root in preview assembly

Comps that ship a baked inline runtime were double-loaded (preview injects
its own) and the baked copy failed to parse inline (Unexpected token '<').
Strip it in buildSubCompositionHtml + the disk-fallback preview path. Also
tag the comp root with data-composition-file so the studio resolves a comp's
top-level elements to the right source file instead of defaulting to
index.html (which made the GSAP panel parse the wrong, multi-timeline file).

* feat(studio): set motion-path destination from a toolbar toggle

Replaces the double-click-on-canvas UX (which painted text over the preview)
with a 'Set motion destination' toggle next to Snap/Grid, shown only when the
selected element can take a path. While armed, one canvas press places the
destination. Also removes the dead TimelinePropertyRows component.

* fix(studio): center timeline keyframe diamonds on their percentage

Dropped clampDiamondLeft, which forced boundary keyframes fully inside the
clip so a 0% diamond sat half a diamond right of the 0% point. Each diamond's
midpoint now sits exactly on its % (the clip is overflow-visible).

* fix(studio): resize static elements via tl.set, not a single-stop keyframes tween

Resizing an element with no size animation wrote keyframes:{ <playhead%>:
{width,height} } — one mid-point stop GSAP can't interpolate, so it rendered
NaN/0 dimensions at every other frame and the element vanished (worst off 0%).
Added commitStaticGsapSize (mirrors commitStaticGsapPosition): a static resize
now writes tl.set({width,height}), held at all frames; re-resizing updates it
in place.

* fix(studio): negative-cache failed media probes

Only successful probes were cached, so CORS/404 cross-origin media was
re-probed every rAF-driven timeline re-derive, flooding the console. Remember
failed URLs and skip them.

* fix(studio): type window.setTimeout handle as number

ReturnType<typeof window.setTimeout> infers NodeJS.Timeout when @types/node is
present and clashes with the DOM number the call returns. Type it number.

* fix(studio): drag/resize disappearance, stale-ID duplicates, soft-reload clearProps

- Fix soft-reload clearProps destroying element inline styles — save cssText,
  clear, restore, strip only transform
- Fix resize no-op on re-resize: delete+add instead of two update-property
- Route set tweens through static resize path (convertToKeyframes skips sets)
- Re-fetch animation ID before drag commit to prevent stale-ID duplicates
- Guard editDebugLog for Node test environments
- Fix NLELayout setState-during-render (move reset to useEffect)
- Stop SnapToolbar pointer events propagating to canvas deselect handler
- Enable click-to-add waypoints on cubic motion paths
- Add whole-path drag offset (Alt+drag shifts all keyframes together)
- Add Canvas shortcuts section to ShortcutsPanel
- Extract useMotionPathData + commitGsapPositionFromDrag (filesize compliance)
- Delete dead code (getElementDepth, isElementVisibleInPreview, unused exports)

packages/studio/src/utils/gsapSoftReload.test.ts

@@ -1,7 +1,7 @@
 // @vitest-environment happy-dom
 
 import { describe, it, expect, vi } from "vitest";
-import { applySoftReload } from "./gsapSoftReload";
+import { applySoftReload, ensureMotionPathPluginLoaded } from "./gsapSoftReload";
 
 const SCRIPT_TEXT = `
 window.__timelines = window.__timelines || {};
@@ -10,6 +10,13 @@ tl.to("#box", { opacity: 0.8 });
 window.__timelines["root"] = tl;
 `;
 
+const MOTION_PATH_SCRIPT_TEXT = `
+window.__timelines = window.__timelines || {};
+const tl = gsap.timeline({ paused: true });
+tl.to("#box", { motionPath: { path: [{ x: 0, y: 0 }, { x: 100, y: 50 }] } });
+window.__timelines["root"] = tl;
+`;
+
 function buildMockIframe(overrides: Record<string, unknown> = {}) {
   const scriptEl = document.createElement("script");
   scriptEl.textContent =
@@ -58,29 +65,35 @@ function buildMockIframe(overrides: Record<string, unknown> = {}) {
 }
 
 describe("applySoftReload", () => {
-  it("returns false when iframe is null", () => {
-    expect(applySoftReload(null, SCRIPT_TEXT)).toBe(false);
+  it('returns "cannot-soft-reload" when iframe is null', () => {
+    expect(applySoftReload(null, SCRIPT_TEXT)).toBe("cannot-soft-reload");
   });
 
-  it("returns false when scriptText is empty", () => {
+  it('returns "cannot-soft-reload" when scriptText is empty', () => {
     const { iframe } = buildMockIframe();
-    expect(applySoftReload(iframe, "")).toBe(false);
+    expect(applySoftReload(iframe, "")).toBe("cannot-soft-reload");
   });
 
-  it("returns false when gsap is not on iframe window", () => {
+  it('returns "cannot-soft-reload" when gsap is not on iframe window', () => {
     const { iframe } = buildMockIframe({ gsap: undefined });
-    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe(false);
+    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe("cannot-soft-reload");
   });
 
-  it("returns false when __hfForceTimelineRebind is missing", () => {
+  it('returns "cannot-soft-reload" when __hfForceTimelineRebind is missing', () => {
     const { iframe } = buildMockIframe({ __hfForceTimelineRebind: undefined });
-    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe(false);
+    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe("cannot-soft-reload");
+  });
+
+  it('returns "cannot-soft-reload" when the script registers no scopable key', () => {
+    // No __timelines["key"] pattern → targetKeys is empty → can't scope safely.
+    const { iframe } = buildMockIframe();
+    expect(applySoftReload(iframe, 'gsap.to("#box", { x: 1 });')).toBe("cannot-soft-reload");
   });
 
   it("kills existing timelines, rebinds, and re-seeks on success", () => {
     const { iframe, contentWindow, mockTimeline } = buildMockIframe();
     const result = applySoftReload(iframe, SCRIPT_TEXT);
-    expect(result).toBe(true);
+    expect(result).toBe("applied");
     expect(mockTimeline.kill).toHaveBeenCalled();
     expect(contentWindow.__hfForceTimelineRebind).toHaveBeenCalled();
     expect(contentWindow.__player.seek).toHaveBeenCalledWith(2.0);
@@ -96,11 +109,119 @@ describe("applySoftReload", () => {
       },
     });
     const result = applySoftReload(iframe, SCRIPT_TEXT);
-    expect(result).toBe(true);
+    expect(result).toBe("applied");
     expect(suppressionCalled).toBe(true);
   });
 
-  it("returns false when multiple GSAP scripts exist (ambiguous)", () => {
+  it('returns "applied" when the re-run re-registers the script\'s expected key', () => {
+    // SCRIPT_TEXT registers __timelines["root"]; buildMockIframe's appendChild
+    // shim repopulates `root` on execution. The hardened verify checks the
+    // expected target key is present (not merely "some key"), so a correct re-run
+    // reliably reports "applied" — it doesn't spuriously hit the transient window.
+    const { iframe, contentWindow } = buildMockIframe();
+    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe("applied");
+    expect(contentWindow.__timelines.root).toBeDefined();
+  });
+
+  it('returns "verify-failed" (transient) when the re-run leaves the key empty', () => {
+    // No appendChild shim repopulation: the body container has no shim, so the
+    // re-run kills __timelines["root"] and the new script doesn't re-register it.
+    // That is the TRANSIENT post-run window — surfaced as "verify-failed" so
+    // callers know NOT to escalate (the live gsap.set already shows the value).
+    const scriptEl = document.createElement("script");
+    scriptEl.textContent = 'window.__timelines["root"] = gsap.timeline();';
+    const container = document.createElement("div"); // no appendChild shim
+    container.appendChild(scriptEl);
+    const { iframe } = buildMockIframe();
+    (iframe as unknown as { contentDocument: unknown }).contentDocument = {
+      querySelectorAll: (sel: string) => (sel === "script:not([src])" ? [scriptEl] : []),
+      createElement: (tag: string) => document.createElement(tag),
+      body: container,
+      head: document.createElement("div"),
+    };
+    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe("verify-failed");
+  });
+
+  it("editing composition A leaves composition B's timeline intact (scoped kill)", () => {
+    // Two comps live side by side; the soft reload only re-runs comp "root".
+    // Comp "subscene" must survive untouched — the regression the full remount
+    // (re-inline) used to cause.
+    const subsceneTimeline = { kill: vi.fn(), pause: vi.fn() };
+    const { iframe, contentWindow, mockTimeline } = buildMockIframe({
+      __timelines: {
+        root: { kill: vi.fn(), pause: vi.fn() },
+        subscene: subsceneTimeline,
+      } as Record<string, { kill: ReturnType<typeof vi.fn>; pause: ReturnType<typeof vi.fn> }>,
+    });
+    void mockTimeline;
+
+    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe("applied");
+    // Comp B was never killed and is still registered.
+    expect(subsceneTimeline.kill).not.toHaveBeenCalled();
+    expect(contentWindow.__timelines.subscene).toBe(subsceneTimeline);
+  });
+
+  it("runs synchronously (no async plugin load) when MotionPathPlugin is already present", () => {
+    // The preview bootstrap pre-loads MotionPathPlugin, so win.MotionPathPlugin
+    // is set before any motion-path edit. The soft reload must then execute the
+    // script inline — no CDN <script> appended to <head>, the timeline is
+    // repopulated synchronously, and verifyTimelinesPopulated reports the real
+    // result (not the optimistic-true async path).
+    const headAppends: Node[] = [];
+    const head = document.createElement("div");
+    const realHeadAppend = head.appendChild.bind(head);
+    head.appendChild = <T extends Node>(node: T): T => {
+      headAppends.push(node);
+      return realHeadAppend(node);
+    };
+    const { iframe, contentWindow } = buildMockIframe({ MotionPathPlugin: {} });
+    (iframe.contentDocument as unknown as { head: unknown }).head = head;
+
+    const result = applySoftReload(iframe, MOTION_PATH_SCRIPT_TEXT);
+
+    expect(result).toBe("applied");
+    // No CDN plugin <script> was appended to <head> — ran inline.
+    expect(headAppends.filter((n) => n instanceof HTMLScriptElement)).toHaveLength(0);
+    expect(contentWindow.__hfForceTimelineRebind).toHaveBeenCalled();
+    expect(contentWindow.__player.seek).toHaveBeenCalledWith(2.0);
+    expect(contentWindow.__timelines.root).toBeDefined();
+  });
+
+  it("falls back to the async plugin load when MotionPathPlugin is genuinely absent", () => {
+    const head = document.createElement("div");
+    const appendedScripts: HTMLScriptElement[] = [];
+    const realHeadAppend = head.appendChild.bind(head);
+    head.appendChild = <T extends Node>(node: T): T => {
+      if (node instanceof HTMLScriptElement) appendedScripts.push(node);
+      return realHeadAppend(node);
+    };
+    // gsap present but MotionPathPlugin unset → async load path.
+    const { iframe, contentWindow } = buildMockIframe({
+      MotionPathPlugin: undefined,
+      gsap: { timeline: vi.fn(), registerPlugin: vi.fn() },
+    });
+    (iframe.contentDocument as unknown as { head: unknown }).head = head;
+
+    const onAsyncFailure = vi.fn();
+    const result = applySoftReload(iframe, MOTION_PATH_SCRIPT_TEXT, onAsyncFailure);
+
+    // Optimistically "applied" (script will run once the plugin loads) — and the
+    // script has NOT executed yet, so the timeline isn't rebound synchronously.
+    expect(result).toBe("applied");
+    expect(appendedScripts).toHaveLength(1);
+    expect(appendedScripts[0]!.src).toContain("MotionPathPlugin");
+    expect(contentWindow.__hfForceTimelineRebind).not.toHaveBeenCalled();
+
+    // onerror must NOT run the script (that would reference a missing plugin) —
+    // it escalates via onAsyncFailure so the caller can full-reload to recover,
+    // and clears the in-flight loading flag.
+    appendedScripts[0]!.onerror?.(new Event("error"));
+    expect(onAsyncFailure).toHaveBeenCalledTimes(1);
+    expect(contentWindow.__hfForceTimelineRebind).not.toHaveBeenCalled();
+    expect(contentWindow.__hfMotionPathPluginLoading).toBe(false);
+  });
+
+  it('returns "cannot-soft-reload" when multiple GSAP scripts exist (ambiguous)', () => {
     const script1 = document.createElement("script");
     script1.textContent = "const tl = gsap.timeline({ paused: true });";
     const script2 = document.createElement("script");
@@ -115,6 +236,89 @@ describe("applySoftReload", () => {
       createElement: (tag: string) => document.createElement(tag),
       body: container,
     };
-    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe(false);
+    // Multiple scripts, none registering "root" → can't identify what to replace
+    // → structural failure that genuinely needs a full reload.
+    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe("cannot-soft-reload");
+  });
+});
+
+function buildBootstrapIframe(overrides: Record<string, unknown> = {}) {
+  const head = document.createElement("div");
+  const appendedScripts: HTMLScriptElement[] = [];
+  const realHeadAppend = head.appendChild.bind(head);
+  head.appendChild = <T extends Node>(node: T): T => {
+    if (node instanceof HTMLScriptElement) appendedScripts.push(node);
+    return realHeadAppend(node);
+  };
+
+  const registerPlugin = vi.fn();
+  const contentWindow = {
+    gsap: { registerPlugin } as Record<string, unknown> | undefined,
+    MotionPathPlugin: undefined as unknown,
+    __hfMotionPathPluginLoading: undefined as boolean | undefined,
+    ...overrides,
+  };
+  const contentDocument = {
+    createElement: (tag: string) => document.createElement(tag),
+    head,
+  };
+  return {
+    iframe: { contentWindow, contentDocument } as unknown as HTMLIFrameElement,
+    contentWindow,
+    appendedScripts,
+    registerPlugin,
+  };
+}
+
+describe("ensureMotionPathPluginLoaded", () => {
+  it("no-ops when the iframe is null", () => {
+    expect(() => ensureMotionPathPluginLoaded(null)).not.toThrow();
+  });
+
+  it("no-ops when gsap is unavailable", () => {
+    const { iframe, appendedScripts } = buildBootstrapIframe({ gsap: undefined });
+    ensureMotionPathPluginLoaded(iframe);
+    expect(appendedScripts).toHaveLength(0);
+  });
+
+  it("appends the plugin script once and registers it on load", () => {
+    const { iframe, contentWindow, appendedScripts, registerPlugin } = buildBootstrapIframe();
+    ensureMotionPathPluginLoaded(iframe);
+    expect(appendedScripts).toHaveLength(1);
+    expect(appendedScripts[0]!.src).toContain("MotionPathPlugin");
+    expect(contentWindow.__hfMotionPathPluginLoading).toBe(true);
+
+    // Simulate the CDN load completing; the plugin is now present.
+    contentWindow.MotionPathPlugin = {};
+    appendedScripts[0]!.onload?.(new Event("load"));
+    expect(registerPlugin).toHaveBeenCalledWith(contentWindow.MotionPathPlugin);
+    expect(contentWindow.__hfMotionPathPluginLoading).toBe(false);
+  });
+
+  it("is idempotent: a second call while loading does not append a second script", () => {
+    const { iframe, appendedScripts } = buildBootstrapIframe();
+    ensureMotionPathPluginLoaded(iframe);
+    ensureMotionPathPluginLoaded(iframe);
+    expect(appendedScripts).toHaveLength(1);
+  });
+
+  it("registers an already-present plugin without appending a script", () => {
+    const plugin = {};
+    const { iframe, appendedScripts, registerPlugin } = buildBootstrapIframe({
+      MotionPathPlugin: plugin,
+    });
+    ensureMotionPathPluginLoaded(iframe);
+    expect(appendedScripts).toHaveLength(0);
+    expect(registerPlugin).toHaveBeenCalledWith(plugin);
+  });
+
+  it("clears the loading flag and still resolves when the CDN load errors", () => {
+    const { iframe, contentWindow, appendedScripts } = buildBootstrapIframe();
+    ensureMotionPathPluginLoaded(iframe);
+    appendedScripts[0]!.onerror?.(new Event("error"));
+    expect(contentWindow.__hfMotionPathPluginLoading).toBe(false);
+    // A subsequent call can retry (plugin still absent, flag cleared).
+    ensureMotionPathPluginLoaded(iframe);
+    expect(appendedScripts).toHaveLength(2);
   });
 });