@unseenco/theatre-gsap 0.4.2 → 0.5.0

package/dist/index.mjs

@@ -522,11 +522,11 @@ function validateAndSanitiseSlashedPathOrThrow(unsanitisedPath, fnName) {
 Please replace the path with the sanitized one, otherwise it will likely break in the future.`,
       [
         {
-          url: "https://www.theatrejs.com/docs/latest/manual/objects#creating-sheet-objects",
+          url: "https://unseen-theatre.netlify.app/docs/guide/manual/objects#creating-objects",
           title: "Sheet Objects"
         },
         {
-          url: "https://www.theatrejs.com/docs/latest/api/core#sheet.object",
+          url: "https://unseen-theatre.netlify.app/docs/api/theatre-core#sheet.object",
           title: "API"
         }
       ]
@@ -595,6 +595,21 @@ function linkGsapTimelineChildAnimations(animation) {
   return map;
 }
 
+// ../../theatre/shared/src/gsap/gsapAnimationLabel.ts
+function readGsapAnimationVarsId(animation) {
+  const id = animation.vars?.id;
+  if (typeof id === "string" && id.trim().length > 0) {
+    return id.trim();
+  }
+  return void 0;
+}
+function resolveGsapAnimationRegistrationLabel(animation, optionsLabel, fallback = "GSAP animation") {
+  if (typeof optionsLabel === "string" && optionsLabel.length > 0) {
+    return optionsLabel;
+  }
+  return readGsapAnimationVarsId(animation) ?? fallback;
+}
+
 // ../../theatre/shared/src/gsap/gsapSheetObjectKey.ts
 var GSAP_NAMESPACE_STORE_KEY = "__unseenco_theatre_gsap_configuredNamespace__";
 function setConfiguredGsapSheetObjectNamespace(namespace) {
@@ -602,129 +617,7 @@ function setConfiguredGsapSheetObjectNamespace(namespace) {
   g[GSAP_NAMESPACE_STORE_KEY] = namespace.trim();
 }
 
-// ../../theatre/shared/src/sequence/trackData.ts
-function gsapClipEndTime(clip) {
-  return clip.start + clip.duration;
-}
-function gsapClipSyncProgress(sequencePosition, clip) {
-  if (clip.duration <= 0)
-    return 0;
-  if (sequencePosition < clip.start)
-    return 0;
-  const clipEnd = gsapClipEndTime(clip);
-  if (sequencePosition >= clipEnd - 1e-5)
-    return 1;
-  const raw = (sequencePosition - clip.start) / clip.duration;
-  if (raw <= 0)
-    return 0;
-  if (raw >= 1)
-    return 1;
-  return raw;
-}
-
-// ../../theatre/shared/src/gsap/applyTimelineChildTiming.ts
-function applyTimelineChildTimingToGsap(rootAnimation, timelineChildren, childById, onRebuild) {
-  if (!timelineChildren.length)
-    return true;
-  let ok = applyTimelineChildTimingToGsapInner(
-    rootAnimation,
-    timelineChildren,
-    childById
-  );
-  if (!ok && onRebuild) {
-    const rebuilt = onRebuild();
-    if (rebuilt) {
-      ok = applyTimelineChildTimingToGsapInner(
-        rebuilt,
-        timelineChildren,
-        childById
-      );
-    }
-  }
-  return ok;
-}
-function applyTimelineChildTimingToGsapInner(rootAnimation, timelineChildren, childById) {
-  if (!childById || timelineChildren.length === 0)
-    return true;
-  let ok = true;
-  for (const childState of timelineChildren) {
-    const tween = childById.get(childState.childId);
-    if (!tween)
-      continue;
-    try {
-      const t = tween;
-      if (typeof t.startTime === "function") {
-        t.startTime(childState.localStart);
-      }
-      if (typeof t.duration === "function") {
-        t.duration(childState.localDuration);
-      }
-    } catch {
-      ok = false;
-    }
-  }
-  return ok;
-}
-
 // ../../theatre/shared/src/gsap/syncGsapClipProgress.ts
-function getGsapAnimationTargetKey(animation, fallbackAnimationId) {
-  const tween = animation;
-  const targets = tween.targets?.();
-  if (targets && targets.length > 0) {
-    return targets[0];
-  }
-  return fallbackAnimationId;
-}
-function syncRegisteredGsapAnimationsForClips(sequencePosition, clips) {
-  const enriched = [];
-  for (const clip of clips) {
-    const entry = getAnimationEntryBySheetAddressKey(
-      clip.sheetObjectAddressKey,
-      clip.gsapAnimationId
-    );
-    if (!entry?.animation)
-      continue;
-    enriched.push({
-      ...clip,
-      entry,
-      targetKey: getGsapAnimationTargetKey(
-        entry.animation,
-        clip.gsapAnimationId
-      )
-    });
-  }
-  const byTarget = /* @__PURE__ */ new Map();
-  for (const item of enriched) {
-    const list = byTarget.get(item.targetKey) ?? [];
-    list.push(item);
-    byTarget.set(item.targetKey, list);
-  }
-  for (const group of byTarget.values()) {
-    const sorted = [...group].sort((a, b) => a.start - b.start);
-    for (const clip of sorted) {
-      const progress = gsapClipSyncProgress(sequencePosition, clip);
-      const entry = clip.entry;
-      const animation = entry.animation;
-      if (entry.kind === "timeline" && clip.timelineChildren && clip.timelineChildren.length > 0) {
-        applyTimelineChildTimingToGsap(
-          entry.animation,
-          clip.timelineChildren,
-          entry.timelineChildById,
-          entry.onRebuildTimeline
-        );
-        const span = clip.timelineSpan ?? readGsapTweenTimelineDuration(entry.animation);
-        const t = progress * Math.max(span, 0.01);
-        if (typeof animation.time === "function") {
-          animation.time(t, true);
-        } else {
-          animation.progress?.(progress, true);
-        }
-      } else {
-        animation.progress?.(progress, true);
-      }
-    }
-  }
-}
 function readGsapTweenTimelineDuration(animation) {
   const tween = animation;
   const total = tween.totalDuration?.();
@@ -1431,11 +1324,6 @@ var Stack = class {
   }
 };
 
-// ../dataverse/src/prism/Interface.ts
-function isPrism(d) {
-  return !!(d && d.isPrism && d.isPrism === true);
-}
-
 // ../dataverse/src/prism/discoveryMechanism.ts
 function createMechanism() {
   const noop = () => {
@@ -1777,14 +1665,14 @@ var PrismInstance = class {
   getValue() {
     reportResolutionStart(this);
     const state2 = this._state;
-    let val2;
+    let val;
     if (state2.hot) {
-      val2 = state2.handle.getValue();
+      val = state2.handle.getValue();
     } else {
-      val2 = calculateColdPrism(this._fn);
+      val = calculateColdPrism(this._fn);
     }
     reportResolutionEnd(this);
-    return val2;
+    return val;
   }
 };
 var HotScope = class _HotScope {
@@ -2187,8 +2075,8 @@ var Atom = class {
    * atom.setByPointer((p) => p.a.b, 2) // atom.get().a.b === 2
    * ```
    */
-  setByPointer(pointerOrFn, val2) {
-    this.reduceByPointer(pointerOrFn, () => val2);
+  setByPointer(pointerOrFn, val) {
+    this.reduceByPointer(pointerOrFn, () => val);
   }
   _checkUpdates(scope2, oldState, newState) {
     if (oldState === newState)
@@ -2235,38 +2123,6 @@ var Atom = class {
   }
 };
 
-// ../dataverse/src/pointerToPrism.ts
-var identifyPrismWeakMap = /* @__PURE__ */ new WeakMap();
-function isPointerToPrismProvider(val2) {
-  return typeof val2 === "object" && val2 !== null && val2["$$isPointerToPrismProvider"] === true;
-}
-var pointerToPrism = (pointer2) => {
-  const meta = getPointerMeta(pointer2);
-  let prismInstance = identifyPrismWeakMap.get(meta);
-  if (!prismInstance) {
-    const root2 = meta.root;
-    if (!isPointerToPrismProvider(root2)) {
-      throw new Error(
-        `Cannot run pointerToPrism() on a pointer whose root is not an PointerToPrismProvider`
-      );
-    }
-    prismInstance = root2.pointerToPrism(pointer2);
-    identifyPrismWeakMap.set(meta, prismInstance);
-  }
-  return prismInstance;
-};
-
-// ../dataverse/src/val.ts
-var val = (input) => {
-  if (isPointer(input)) {
-    return pointerToPrism(input).getValue();
-  } else if (isPrism(input)) {
-    return input.getValue();
-  } else {
-    return input;
-  }
-};
-
 // ../../theatre/shared/src/gsap/gsapStudioRegistryRevision.ts
 var revisionAtom = new Atom(0);
 function bumpGsapStudioRegistryRevision() {
@@ -2344,9 +2200,6 @@ function getAnimationEntry(sheetObject, animationId) {
 function getAnimationEntryForSheetObject(sheetObject) {
   return getAnimationEntry(sheetObject);
 }
-function getAnimationEntryBySheetAddressKey(sheetObjectAddressKey2, animationId) {
-  return getStore2().bySheetAddress.get(sheetObjectAddressKey2)?.get(animationId);
-}
 function listAnimationEntries() {
   const entries = [];
   for (const byAnim of getStore2().bySheetAddress.values()) {
@@ -2355,22 +2208,136 @@ function listAnimationEntries() {
   return entries;
 }
 
+// ../../theatre/shared/src/sheets/pageScrollContext.ts
+var defaultPageScrollContext = {
+  scroller: null,
+  axis: "vertical"
+};
+var activePageScrollContext = defaultPageScrollContext;
+function setActivePageScrollContext(context) {
+  activePageScrollContext = {
+    scroller: context.scroller,
+    axis: context.axis ?? "vertical"
+  };
+}
+function resolvePageScrollAxis(context = defaultPageScrollContext) {
+  return context.axis ?? "vertical";
+}
+function resolvePageScrollScroller(st, defaultsScroller) {
+  const surface = st;
+  const fromSt = surface.scroller ?? surface.vars?.scroller;
+  if (fromSt != null) {
+    return fromSt;
+  }
+  if (defaultsScroller !== void 0) {
+    return defaultsScroller;
+  }
+  return null;
+}
+function isWindowLike(value) {
+  return typeof Window !== "undefined" && (value === window || value instanceof Window);
+}
+function isNativeDocumentScroller(scroller) {
+  if (scroller == null)
+    return true;
+  if (isWindowLike(scroller))
+    return true;
+  if (typeof document === "undefined")
+    return false;
+  return scroller === document.documentElement || scroller === document.body;
+}
+function pageScrollScrollersMatch(a, b) {
+  if (a === b)
+    return true;
+  if (isNativeDocumentScroller(a) && isNativeDocumentScroller(b))
+    return true;
+  return false;
+}
+function isScrollTriggerHorizontal(st) {
+  const surface = st;
+  return surface.horizontal === true || surface.vars?.horizontal === true;
+}
+function isPageScrollTrigger(st, context = defaultPageScrollContext) {
+  const axis = resolvePageScrollAxis(context);
+  const stHorizontal = isScrollTriggerHorizontal(st);
+  if (stHorizontal !== (axis === "horizontal")) {
+    return false;
+  }
+  const stScroller = resolvePageScrollScroller(st, context.scroller);
+  return pageScrollScrollersMatch(stScroller, context.scroller);
+}
+
+// src/gsapScrollTriggerPlugin.ts
+import { ScrollTrigger as scrollTriggerFromGsap } from "gsap/ScrollTrigger";
+var boundScrollTrigger;
+function bindGsapScrollTriggerPlugin(scrollTrigger) {
+  boundScrollTrigger = scrollTrigger;
+}
+function getGsapScrollTriggerPlugin() {
+  if (boundScrollTrigger) {
+    return boundScrollTrigger;
+  }
+  const g = globalThis;
+  return g.ScrollTrigger ?? scrollTriggerFromGsap;
+}
+function requireGsapScrollTriggerPlugin() {
+  const plugin = getGsapScrollTriggerPlugin();
+  if (!plugin) {
+    throw new Error(
+      'ScrollTrigger is not available. Import ScrollTrigger from "gsap/ScrollTrigger", call gsap.registerPlugin(ScrollTrigger), and optionally bindGsapScrollTriggerPlugin(ScrollTrigger) before registering scroll triggers with Theatre.'
+    );
+  }
+  return plugin;
+}
+function refreshGsapScrollTriggers() {
+  getGsapScrollTriggerPlugin()?.refresh();
+}
+
 // src/config.ts
 var activeConfig = {
   namespace: "GSAP",
   outlineNamespace: { defaultCollapsed: false }
 };
 setConfiguredGsapSheetObjectNamespace(activeConfig.namespace);
+function pageScrollContextFromConfig(pageScroll) {
+  return {
+    scroller: pageScroll.scroller ?? defaultPageScrollContext.scroller,
+    axis: pageScroll.axis ?? defaultPageScrollContext.axis ?? "vertical"
+  };
+}
+function applyScrollTriggerDefaultsForPageScroll(pageScroll) {
+  const ScrollTrigger = getGsapScrollTriggerPlugin();
+  const { scroller, axis } = pageScrollContextFromConfig(pageScroll);
+  ScrollTrigger?.defaults?.({
+    scroller: scroller ?? void 0,
+    ...axis === "horizontal" ? { horizontal: true } : {}
+  });
+}
 function configureTheatreGsap(config) {
   const prev = activeConfig;
   activeConfig = {
     namespace: config.namespace ?? prev.namespace ?? "GSAP",
-    outlineNamespace: config.outlineNamespace ?? prev.outlineNamespace
+    outlineNamespace: config.outlineNamespace ?? prev.outlineNamespace,
+    suppressGsapTickerRafWarning: config.suppressGsapTickerRafWarning ?? prev.suppressGsapTickerRafWarning,
+    pageScroll: config.pageScroll ?? prev.pageScroll
   };
   setConfiguredGsapSheetObjectNamespace(activeConfig.namespace ?? "GSAP");
+  if (config.pageScroll !== void 0) {
+    const ctx = pageScrollContextFromConfig(config.pageScroll);
+    setActivePageScrollContext(ctx);
+    applyScrollTriggerDefaultsForPageScroll(config.pageScroll);
+  }
   return {
     reset() {
       activeConfig = prev;
+      setConfiguredGsapSheetObjectNamespace(prev.namespace ?? "GSAP");
+      if (prev.pageScroll !== void 0) {
+        const ctx = pageScrollContextFromConfig(prev.pageScroll);
+        setActivePageScrollContext(ctx);
+        applyScrollTriggerDefaultsForPageScroll(prev.pageScroll);
+      } else {
+        setActivePageScrollContext(defaultPageScrollContext);
+      }
     }
   };
 }
@@ -2427,11 +2394,56 @@ function formatOutlineNamespacePathKey(pathSegments) {
   return pathSegments.join(" / ");
 }
 
+// src/gsapTickerRafBridge.ts
+import { getTheatreCoreRafDriver } from "@unseenco/theatre-core/privateAPIs";
+var gsapTickerDrivenDriverIds = /* @__PURE__ */ new Set();
+function bindGsapTickerToRafDriver(rafDriver, gsap) {
+  const onTick = (time) => {
+    rafDriver.tick(time * 1e3);
+  };
+  gsapTickerDrivenDriverIds.add(rafDriver.id);
+  gsap.ticker.add(onTick);
+  return () => {
+    gsap.ticker.remove(onTick);
+    gsapTickerDrivenDriverIds.delete(rafDriver.id);
+  };
+}
+function isRafDriverDrivenByGsapTicker(rafDriver) {
+  return gsapTickerDrivenDriverIds.has(rafDriver.id);
+}
+var hasWarnedGsapTickerRaf = false;
+var gsapTickerRafWarningMicrotaskQueued = false;
+function scheduleGsapTickerRafWarningCheck() {
+  if (gsapTickerRafWarningMicrotaskQueued)
+    return;
+  gsapTickerRafWarningMicrotaskQueued = true;
+  queueMicrotask(() => {
+    gsapTickerRafWarningMicrotaskQueued = false;
+    warnIfGsapTickerNotDrivingTheatreRaf();
+  });
+}
+function warnIfGsapTickerNotDrivingTheatreRaf() {
+  if (typeof window === "undefined")
+    return;
+  if (getTheatreGsapConfig().suppressGsapTickerRafWarning)
+    return;
+  if (hasWarnedGsapTickerRaf)
+    return;
+  const coreDriver = getTheatreCoreRafDriver();
+  if (!isRafDriverDrivenByGsapTicker(coreDriver)) {
+    hasWarnedGsapTickerRaf = true;
+    console.warn(
+      "[theatre-gsap] Theatre is not driven by gsap.ticker. After setCoreRafDriver(), call bindGsapTickerToRafDriver(rafDriver, gsap) so GSAP and Theatre share one clock. See the GSAP extension guide."
+    );
+  }
+}
+
 // src/registerGsapAnimation.ts
 function registerGsapAnimation(animation, sheet, options) {
   const config = getTheatreGsapConfig();
   const namespace = options.namespace ?? config.namespace ?? "GSAP";
-  const objectKey = buildGsapSheetObjectKey(namespace, options.label);
+  const label = resolveGsapAnimationRegistrationLabel(animation, options.label);
+  const objectKey = buildGsapSheetObjectKey(namespace, label);
   const id = options.id ?? objectKey;
   animation.pause();
   const sheetObjectPublic = sheet.object(objectKey, {}, { reconfigure: false });
@@ -2445,75 +2457,441 @@ function registerGsapAnimation(animation, sheet, options) {
   }
   registerAnimationInRegistry2({
     id,
-    label: options.label,
+    label,
     animation,
     sheetObject: sheetObjectInternal,
-    defaultDuration: options.defaultDuration,
+    defaultDuration: options.defaultDuration ?? (sheet.getSequenceMode() === "page" ? 10 : void 0),
     onRebuildTimeline: options.onRebuildTimeline
   });
+  scheduleGsapTickerRafWarningCheck();
   return { id, sheetObject: sheetObjectPublic };
 }
 
-// src/attachGsapSequenceBridge.ts
+// src/registerGsapScrollTrigger.ts
 import { privateAPI as privateAPI2 } from "@unseenco/theatre-core/privateAPIs";
 
-// ../../theatre/shared/src/gsap/syncGsapClipsAtSequencePosition.ts
-function syncGsapClipsAtSequencePosition(position, clips) {
-  syncRegisteredGsapAnimationsForClips(
-    position,
-    clips
-  );
+// ../../theatre/shared/src/gsap/scrollTriggerGuards.ts
+function resolveScrollTriggerAnimation(st) {
+  const surface = st;
+  if (surface.animation != null)
+    return surface.animation;
+  if (surface.vars?.animation != null)
+    return surface.vars.animation;
+  return void 0;
+}
+function defaultScrollTriggerLabel(st, fallbackIndex) {
+  const surface = st;
+  const id = surface.vars?.id;
+  if (typeof id === "string" && id.length > 0)
+    return id;
+  const trigger = surface.trigger;
+  if (trigger && typeof trigger === "object" && "id" in trigger) {
+    const elementId = trigger.id;
+    if (typeof elementId === "string" && elementId.length > 0) {
+      return elementId;
+    }
+  }
+  return `ScrollTrigger ${fallbackIndex + 1}`;
+}
+function readAnimationSpanSeconds(animation) {
+  return Math.max(readGsapTweenTimelineDuration(animation), MIN_ANIMATION_SPAN);
 }
+var MIN_ANIMATION_SPAN = 0.01;
 
-// ../../theatre/shared/src/gsap/subscribeGsapClipSyncAtPlayhead.ts
-function subscribeGsapClipSyncAtPlayhead(source2) {
-  const positionPointer = source2.pointer.position;
-  const positionPrism = pointerToPrism(positionPointer);
-  const clipsPrism = prism_default(() => source2.getGsapClipTimings());
-  const syncNow = () => {
-    const clips = clipsPrism.getValue();
-    if (clips.length === 0)
-      return;
-    syncGsapClipsAtSequencePosition(val(positionPointer), clips);
+// ../../theatre/shared/src/gsap/scrollTriggerLayout.ts
+var MIN_SEQUENCE_DURATION = 0.01;
+function scrollPixelsToPageUnits(startPx, endPx, maxScrollPx, sequenceLength) {
+  const length = Math.max(sequenceLength, MIN_SEQUENCE_DURATION);
+  if (maxScrollPx <= 0) {
+    return { start: 0, duration: length };
+  }
+  const startProgress = Math.max(0, Math.min(1, startPx / maxScrollPx));
+  const endProgress = Math.max(0, Math.min(1, endPx / maxScrollPx));
+  const lo = Math.min(startProgress, endProgress);
+  const hi = Math.max(startProgress, endProgress);
+  let start = lo * length;
+  let duration = Math.max((hi - lo) * length, MIN_SEQUENCE_DURATION);
+  if (start + duration > length) {
+    start = Math.max(0, length - duration);
+  }
+  if (start < 0)
+    start = 0;
+  return { start, duration };
+}
+function getNativeDocumentMaxScroll(axis = "vertical") {
+  if (typeof document === "undefined" || typeof window === "undefined") {
+    return 0;
+  }
+  const el = document.documentElement;
+  if (axis === "horizontal") {
+    const scrolling = document.scrollingElement ?? el;
+    return Math.max(0, scrolling.scrollWidth - scrolling.clientWidth);
+  }
+  return Math.max(0, el.scrollHeight - window.innerHeight);
+}
+function getMaxScrollForScroller(scroller, axis = "vertical") {
+  if (typeof document === "undefined" || typeof window === "undefined") {
+    return 0;
+  }
+  if (isNativeDocumentScroller(scroller)) {
+    return getNativeDocumentMaxScroll(axis);
+  }
+  const el = scroller;
+  if (axis === "horizontal") {
+    return Math.max(0, el.scrollWidth - el.clientWidth);
+  }
+  return Math.max(0, el.scrollHeight - el.clientHeight);
+}
+function getMaxScrollForPageScrollContext(scroller, axis = "vertical") {
+  return getMaxScrollForScroller(scroller, axis);
+}
+
+// ../../theatre/shared/src/sheets/remotePageScrollMetrics.ts
+var remoteMetrics;
+function resolveMaxScrollPxForPageLayout(localMaxScrollPx, axis) {
+  if (localMaxScrollPx > 0) {
+    return localMaxScrollPx;
+  }
+  const remote = remoteMetrics;
+  if (remote && remote.axis === axis && remote.maxScroll > 0) {
+    return remote.maxScroll;
+  }
+  return localMaxScrollPx;
+}
+
+// ../../theatre/shared/src/gsap/extractScrollTriggerLayout.ts
+function extractScrollTriggerLayout(st, options) {
+  const pageScrollContext = options.pageScrollContext ?? defaultPageScrollContext;
+  if (!isPageScrollTrigger(st, pageScrollContext)) {
+    return { ok: false, reason: "unsupported_scroller" };
+  }
+  const surface = st;
+  const animation = resolveScrollTriggerAnimation(st);
+  if (!animation) {
+    return { ok: false, reason: "missing_animation" };
+  }
+  const axis = resolvePageScrollAxis(pageScrollContext);
+  const localMaxScroll = getMaxScrollForPageScrollContext(
+    pageScrollContext.scroller,
+    axis
+  );
+  const maxScroll = resolveMaxScrollPxForPageLayout(localMaxScroll, axis);
+  const layout = scrollPixelsToPageUnits(
+    surface.start,
+    surface.end,
+    maxScroll,
+    options.sequenceLength
+  );
+  const fallbackIndex = options.fallbackIndex ?? 0;
+  const label = options.label ?? defaultScrollTriggerLabel(st, fallbackIndex);
+  const id = options.id ?? (typeof surface.vars?.id === "string" && surface.vars.id.length > 0 ? surface.vars.id : `st_${label.replace(/\s+/g, "_")}_${fallbackIndex}`);
+  const kind = isGsapTimeline(animation) ? "timeline" : "tween";
+  const animationSpanSeconds = readAnimationSpanSeconds(animation);
+  const timelineChildren = kind === "timeline" ? introspectGsapTimelineChildren(animation) : [];
+  return {
+    ok: true,
+    value: {
+      id,
+      label,
+      layout,
+      kind,
+      animationSpanSeconds,
+      timelineChildren
+    }
   };
-  const untapPosition = positionPrism.onStale(syncNow);
-  const untapClips = clipsPrism.onStale(syncNow);
-  syncNow();
-  return () => {
-    untapPosition();
-    untapClips();
+}
+
+// ../../theatre/shared/src/gsap/scrollTriggerRegistry.ts
+var DEFAULT_SHEET_INSTANCE_ID2 = "default";
+var REGISTRY_KEY2 = "__unseenco_theatre_gsap_scrollTriggerRegistry__";
+function sheetAddressKey(address) {
+  const sheetInstanceId = address.sheetInstanceId ?? DEFAULT_SHEET_INSTANCE_ID2;
+  return `${address.projectId}|${address.sheetId}|${sheetInstanceId}`;
+}
+function getStore3() {
+  const g = globalThis;
+  if (!g[REGISTRY_KEY2]) {
+    g[REGISTRY_KEY2] = { bySheetAddress: /* @__PURE__ */ new Map() };
+  }
+  return g[REGISTRY_KEY2];
+}
+function getSheetMap(key) {
+  const store = getStore3();
+  let map = store.bySheetAddress.get(key);
+  if (!map) {
+    map = /* @__PURE__ */ new Map();
+    store.bySheetAddress.set(key, map);
+  }
+  return map;
+}
+function registerScrollTriggerInRegistry(sheetKey, entry) {
+  const map = getSheetMap(sheetKey);
+  for (const existing of map.values()) {
+    if (existing.scrollTrigger === entry.scrollTrigger) {
+      return "duplicate";
+    }
+    if (existing.id === entry.id) {
+      return "duplicate";
+    }
+  }
+  map.set(entry.id, entry);
+  bumpGsapStudioRegistryRevision();
+  return "registered";
+}
+function findScrollTriggerEntryByInstance(sheetKey, scrollTrigger) {
+  const map = getStore3().bySheetAddress.get(sheetKey);
+  if (!map)
+    return void 0;
+  for (const entry of map.values()) {
+    if (entry.scrollTrigger === scrollTrigger) {
+      return entry;
+    }
+  }
+  return void 0;
+}
+function updateScrollTriggerLayoutInRegistry(sheetKey, id, patch) {
+  const existing = getSheetMap(sheetKey).get(id);
+  if (!existing)
+    return;
+  getSheetMap(sheetKey).set(id, { ...existing, ...patch });
+  bumpGsapStudioRegistryRevision();
+}
+function listScrollTriggerEntriesForSheet(sheetKey) {
+  const map = getStore3().bySheetAddress.get(sheetKey);
+  if (!map)
+    return [];
+  return [...map.values()].sort((a, b) => a.layout.start - b.layout.start);
+}
+
+// src/attachTheatrePageScroll.ts
+import {
+  attachTheatrePageScroll as attachTheatrePageScrollCore,
+  createDefaultPageScrollDriver as createDefaultPageScrollDriverCore,
+  getTheatrePageScrollContext as getTheatrePageScrollContextCore
+} from "@unseenco/theatre-core";
+function applyScrollTriggerDefaultsFromGsapConfig() {
+  const { pageScroll } = getTheatreGsapConfig();
+  if (!pageScroll)
+    return;
+  const ScrollTrigger = getGsapScrollTriggerPlugin();
+  if (!ScrollTrigger?.defaults)
+    return;
+  const axis = pageScroll.axis ?? defaultPageScrollContext.axis ?? "vertical";
+  ScrollTrigger.defaults({
+    scroller: pageScroll.scroller ?? void 0,
+    ...axis === "horizontal" ? { horizontal: true } : {}
+  });
+}
+function getTheatrePageScrollContext() {
+  applyScrollTriggerDefaultsFromGsapConfig();
+  const pageScroll = getTheatreGsapConfig().pageScroll;
+  if (pageScroll) {
+    const ctx = {
+      scroller: pageScroll.scroller ?? defaultPageScrollContext.scroller,
+      axis: pageScroll.axis ?? defaultPageScrollContext.axis
+    };
+    setActivePageScrollContext(ctx);
+    return ctx;
+  }
+  return getTheatrePageScrollContextCore();
+}
+function createDefaultPageScrollDriver(scroller = getTheatrePageScrollContext().scroller) {
+  const ctx = getTheatrePageScrollContext();
+  return createDefaultPageScrollDriverCore(scroller, resolvePageScrollAxis(ctx));
+}
+function attachTheatrePageScroll(sheet, options = {}) {
+  applyScrollTriggerDefaultsFromGsapConfig();
+  return attachTheatrePageScrollCore(sheet, options);
+}
+
+// ../../theatre/shared/src/gsap/scrollTriggerGlobal.ts
+function refreshGsapScrollTriggersFromGlobal() {
+  const ScrollTrigger = globalThis.ScrollTrigger;
+  ScrollTrigger?.refresh?.();
+}
+
+// ../../theatre/shared/src/gsap/refreshScrollTriggerLayoutsForSheet.ts
+function refreshScrollTriggerLayoutsForSheet(sheetKey, sequenceLength, pageScrollContext = defaultPageScrollContext) {
+  refreshGsapScrollTriggersFromGlobal();
+  for (const entry of listScrollTriggerEntriesForSheet(sheetKey)) {
+    const extracted = extractScrollTriggerLayout(entry.scrollTrigger, {
+      sequenceLength,
+      id: entry.id,
+      label: entry.label,
+      pageScrollContext
+    });
+    if (!extracted.ok)
+      continue;
+    updateScrollTriggerLayoutInRegistry(sheetKey, entry.id, {
+      layout: extracted.value.layout,
+      kind: extracted.value.kind,
+      animationSpanSeconds: extracted.value.animationSpanSeconds,
+      timelineChildren: extracted.value.timelineChildren
+    });
+  }
+}
+
+// src/registerGsapScrollTrigger.ts
+function assertPageMode(sheet) {
+  if (sheet.getSequenceMode() !== "page") {
+    throw new Error(
+      'registerGsapScrollTrigger() requires the sheet to use sequenceMode "page".'
+    );
+  }
+}
+function sequenceLengthForSheet(sheet) {
+  return privateAPI2(sheet).getSequence().length;
+}
+function scrollTriggerObjectKey(namespace, label) {
+  return buildGsapSheetObjectKey(namespace, `ScrollTriggers / ${label}`);
+}
+function registerOneGsapScrollTriggerOnSheet(sheet, st, options, fallbackIndex) {
+  const config = getTheatreGsapConfig();
+  const namespace = options.namespace ?? config.namespace ?? "GSAP";
+  const sheetInternal = privateAPI2(sheet);
+  const sheetKey = sheetAddressKey(sheetInternal.address);
+  const sequenceLength = sequenceLengthForSheet(sheet);
+  const existingByInstance = findScrollTriggerEntryByInstance(sheetKey, st);
+  if (existingByInstance?.sheetObject) {
+    console.warn(
+      `[theatre-gsap] ScrollTrigger "${options.label}" is already registered for this sheet (id "${existingByInstance.id}"). Skipping duplicate registration.`
+    );
+    return {
+      id: existingByInstance.id,
+      sheetObject: existingByInstance.sheetObject.publicApi
+    };
+  }
+  refreshGsapScrollTriggers();
+  const pageScrollContext = getTheatrePageScrollContext();
+  const extracted = extractScrollTriggerLayout(st, {
+    sequenceLength,
+    id: options.id,
+    label: options.label,
+    fallbackIndex,
+    pageScrollContext
+  });
+  if (!extracted.ok) {
+    if (extracted.reason === "unsupported_scroller") {
+      console.warn(
+        `[theatre-gsap] Skipped ScrollTrigger "${options.label}": scroller or scroll axis does not match configured page scroll (see configureTheatreGsap pageScroll scroller and axis).`
+      );
+    } else {
+      console.warn(
+        `[theatre-gsap] Skipped ScrollTrigger "${options.label}": no linked tween or timeline found.`
+      );
+    }
+    return null;
+  }
+  const { value } = extracted;
+  const objectKey = scrollTriggerObjectKey(namespace, value.label);
+  const id = options.id ?? value.id;
+  const sheetObjectPublic = sheet.object(objectKey, {}, { reconfigure: false });
+  const sheetObjectInternal = privateAPI2(sheetObjectPublic);
+  if (config.outlineNamespace) {
+    privateAPI2(sheet).template.setOutlineNamespaceConfig(
+      formatOutlineNamespacePathKey([namespace]),
+      config.outlineNamespace
+    );
+  }
+  const entry = {
+    id,
+    label: value.label,
+    scrollTrigger: st,
+    sheetObject: sheetObjectInternal,
+    layout: value.layout,
+    kind: value.kind,
+    animationSpanSeconds: value.animationSpanSeconds,
+    timelineChildren: value.timelineChildren
   };
+  registerScrollTriggerInRegistry(sheetKey, entry);
+  return { id, sheetObject: sheetObjectPublic };
+}
+function registerGsapScrollTrigger(scrollTrigger, sheet, options) {
+  assertPageMode(sheet);
+  requireGsapScrollTriggerPlugin();
+  const result = registerOneGsapScrollTriggerOnSheet(
+    sheet,
+    scrollTrigger,
+    options,
+    0
+  );
+  if (!result) {
+    throw new Error(
+      `Could not register ScrollTrigger "${options.label}". See console warnings for details.`
+    );
+  }
+  scheduleGsapTickerRafWarningCheck();
+  return result;
+}
+function refreshRegisteredGsapScrollTriggerLayouts(sheet) {
+  if (sheet.getSequenceMode() !== "page")
+    return;
+  const sheetInternal = privateAPI2(sheet);
+  const sheetKey = sheetAddressKey(sheetInternal.address);
+  refreshScrollTriggerLayoutsForSheet(
+    sheetKey,
+    sequenceLengthForSheet(sheet),
+    getTheatrePageScrollContext()
+  );
 }
 
-// src/attachGsapSequenceBridge.ts
-function attachGsapSequenceBridge(sheet) {
-  const sequence = sheet.sequence;
-  const sheetAddress = privateAPI2(sheet).address;
-  return subscribeGsapClipSyncAtPlayhead({
-    pointer: sequence.pointer,
-    getGsapClipTimings: () => sequence.__experimental_getGsapClips().map(({ objectKey, clip }) => ({
-      sheetObjectAddressKey: sheetObjectAddressKeyFromParts({
-        projectId: sheetAddress.projectId,
-        sheetId: sheetAddress.sheetId,
-        sheetInstanceId: sheetAddress.sheetInstanceId,
-        objectKey
-      }),
-      gsapAnimationId: clip.gsapAnimationId,
-      start: clip.start,
-      duration: clip.duration,
-      timelineChildren: clip.timelineChildren,
-      timelineSpan: clip.timelineSpan
-    }))
+// src/registerAllGsapScrollTriggers.ts
+import { privateAPI as privateAPI3 } from "@unseenco/theatre-core/privateAPIs";
+function registerAllGsapScrollTriggers(sheet) {
+  if (sheet.getSequenceMode() !== "page") {
+    throw new Error(
+      'registerAllGsapScrollTriggers() requires the sheet to use sequenceMode "page".'
+    );
+  }
+  const ScrollTrigger = requireGsapScrollTriggerPlugin();
+  refreshGsapScrollTriggers();
+  const all = ScrollTrigger.getAll();
+  const sheetKey = sheetAddressKey(privateAPI3(sheet).address);
+  const registered = [];
+  let skipped = 0;
+  all.forEach((st, index) => {
+    const already = findScrollTriggerEntryByInstance(sheetKey, st);
+    const label = defaultScrollTriggerLabel(st, index);
+    const id = typeof st.vars?.id === "string" && st.vars.id.length > 0 ? st.vars.id : void 0;
+    const result = registerOneGsapScrollTriggerOnSheet(
+      sheet,
+      st,
+      { label, id },
+      index
+    );
+    if (!result) {
+      skipped += 1;
+    } else if (already) {
+      skipped += 1;
+    } else {
+      registered.push(result);
+    }
   });
+  scheduleGsapTickerRafWarningCheck();
+  return { registered, skipped };
 }
+
+// src/attachGsapSequenceBridge.ts
+import { attachGsapSequenceBridge } from "@unseenco/theatre-core";
 export {
   attachGsapSequenceBridge,
+  attachTheatrePageScroll,
+  bindGsapScrollTriggerPlugin,
+  bindGsapTickerToRafDriver,
   configureTheatreGsap,
+  createDefaultPageScrollDriver,
   getAnimationEntry2 as getAnimationEntry,
   getAnimationEntryById,
   getAnimationEntryForSheetObject2 as getAnimationEntryForSheetObject,
   getTheatreGsapConfig,
+  getTheatrePageScrollContext,
+  isRafDriverDrivenByGsapTicker,
   listAnimationEntries2 as listAnimationEntries,
-  registerGsapAnimation
+  refreshRegisteredGsapScrollTriggerLayouts,
+  registerAllGsapScrollTriggers,
+  registerGsapAnimation,
+  registerGsapScrollTrigger,
+  scheduleGsapTickerRafWarningCheck,
+  warnIfGsapTickerNotDrivingTheatreRaf
 };
 //# sourceMappingURL=index.mjs.map