@unseenco/theatre-core 0.4.2 → 0.5.0

package/dist/index.mjs

@@ -239,16 +239,44 @@ var require_propose = __commonJS({
 // core/src/coreExports.ts
 var coreExports_exports = {};
 __export(coreExports_exports, {
+  PAGE_MODE_SEQUENCE_LENGTH: () => PAGE_MODE_SEQUENCE_LENGTH,
+  PAGE_MODE_SUB_UNITS_PER_UNIT: () => PAGE_MODE_SUB_UNITS_PER_UNIT,
+  attachGsapSequenceBridge: () => attachGsapSequenceBridge,
+  attachSheetScrollDriver: () => attachSheetScrollDriver,
+  attachTheatrePageScroll: () => attachTheatrePageScroll,
+  configureTheatrePageScroll: () => configureTheatrePageScroll,
+  createDefaultPageScrollDriver: () => createDefaultPageScrollDriver,
+  createElementHorizontalScrollDriver: () => createElementHorizontalScrollDriver,
+  createElementScrollDriver: () => createElementScrollDriver,
+  createNativeDocumentHorizontalScrollDriver: () => createNativeDocumentHorizontalScrollDriver,
+  createNativeDocumentScrollDriver: () => createNativeDocumentScrollDriver,
   createRafDriver: () => createRafDriver,
+  defaultPageScrollContext: () => defaultPageScrollContext,
+  getActivePageScrollContext: () => getActivePageScrollContext,
   getProject: () => getProject,
+  getSheetScrollDriver: () => getSheetScrollDriver,
+  getTheatreCoreRafDriver: () => getTheatreCoreRafDriver,
+  getTheatrePageScrollConfig: () => getTheatrePageScrollConfig,
+  getTheatrePageScrollContext: () => getTheatrePageScrollContext,
+  isNativeDocumentScroller: () => isNativeDocumentScroller,
+  isPageScrollTrigger: () => isPageScrollTrigger,
   isRemoteEditorWindow: () => isRemoteEditorWindow,
+  isVerticalPageScrollTrigger: () => isVerticalPageScrollTrigger,
   notify: () => notify,
   onChange: () => onChange,
+  pageScrollProgressFromSequence: () => pageScrollProgressFromSequence,
+  pageScrollScrollersMatch: () => pageScrollScrollersMatch,
   privateAPI: () => privateAPI,
+  resolvePageScrollAxis: () => resolvePageScrollAxis,
+  resolvePageScrollScroller: () => resolvePageScrollScroller,
+  setActivePageScrollContext: () => setActivePageScrollContext,
   setCoreRafDriver: () => setCoreRafDriver,
+  setPageScrollProgress: () => setPageScrollProgress,
   setPrivateAPI: () => setPrivateAPI,
+  syncNativeDocumentScrollToSequencePosition: () => syncNativeDocumentScrollToSequencePosition,
+  syncPageScrollToSequencePosition: () => syncPageScrollToSequencePosition,
   types: () => propTypes_exports,
-  val: () => val10
+  val: () => val12
 });
 
 // core/src/projects/projectsSingleton.ts
@@ -273,6 +301,82 @@ var ProjectsSingleton = class {
 var singleton = new ProjectsSingleton();
 var projectsSingleton_default = singleton;
 
+// core/src/rafDrivers.ts
+import { Ticker } from "@unseenco/theatre-dataverse";
+var lastDriverId = 0;
+function createRafDriver(conf) {
+  const tick = (time) => {
+    ticker.tick(time);
+  };
+  const ticker = new Ticker({
+    onActive() {
+      conf?.start?.();
+    },
+    onDormant() {
+      conf?.stop?.();
+    }
+  });
+  const driverPublicApi = {
+    tick,
+    id: lastDriverId++,
+    name: conf?.name ?? "CustomRafDriver-".concat(lastDriverId),
+    type: "Theatre_RafDriver_PublicAPI"
+  };
+  const driverPrivateApi = {
+    type: "Theatre_RafDriver_PrivateAPI",
+    publicApi: driverPublicApi,
+    ticker,
+    start: conf?.start,
+    stop: conf?.stop
+  };
+  setPrivateAPI(driverPublicApi, driverPrivateApi);
+  return driverPublicApi;
+}
+
+// core/src/coreTicker.ts
+function createBasicRafDriver() {
+  let rafId = null;
+  const start = () => {
+    if (typeof window !== "undefined") {
+      const onAnimationFrame = (t2) => {
+        driver.tick(t2);
+        rafId = window.requestAnimationFrame(onAnimationFrame);
+      };
+      rafId = window.requestAnimationFrame(onAnimationFrame);
+    } else {
+      driver.tick(0);
+      setTimeout(() => driver.tick(1), 0);
+    }
+  };
+  const stop = () => {
+    if (typeof window !== "undefined") {
+      if (rafId !== null) {
+        window.cancelAnimationFrame(rafId);
+      }
+    } else {
+    }
+  };
+  const driver = createRafDriver({ name: "DefaultCoreRafDriver", start, stop });
+  return driver;
+}
+var coreRafDriver;
+function getCoreRafDriver() {
+  if (!coreRafDriver) {
+    setCoreRafDriver(createBasicRafDriver());
+  }
+  return coreRafDriver;
+}
+function getCoreTicker() {
+  return getCoreRafDriver().ticker;
+}
+function setCoreRafDriver(driver) {
+  if (coreRafDriver) {
+    throw new Error("`setCoreRafDriver()` is already called.");
+  }
+  const driverPrivateApi = privateAPI(driver);
+  coreRafDriver = driverPrivateApi;
+}
+
 // core/src/privateAPIs.ts
 var publicAPIToPrivateAPIMap = /* @__PURE__ */ new WeakMap();
 function privateAPI(pub) {
@@ -281,6 +385,23 @@ function privateAPI(pub) {
 function setPrivateAPI(pub, priv) {
   publicAPIToPrivateAPIMap.set(pub, priv);
 }
+function getTheatreCoreRafDriver() {
+  return getCoreRafDriver().publicApi;
+}
+
+// core/src/sheets/applySheetRuntimeOptions.ts
+function applySheetRuntimeOptions(sheet, opts) {
+  if (!opts) return;
+  if (opts.sequenceMode !== void 0) {
+    sheet.setSequenceMode(opts.sequenceMode);
+  }
+  if (opts.scrollDriver !== void 0) {
+    sheet.setPageScrollDriver(opts.scrollDriver);
+  }
+  if (opts.gsap === true) {
+    sheet.enableGsapSequenceBridge();
+  }
+}
 
 // shared/src/utils/index.ts
 var emptyArray = [];
@@ -3222,11 +3343,11 @@ function sanitizeCompoundProps(props) {
         );
       }
     }
-    const val11 = props[key];
-    if (isLonghandPropType(val11)) {
-      sanitizedProps[key] = val11;
+    const val13 = props[key];
+    if (isLonghandPropType(val13)) {
+      sanitizedProps[key] = val13;
     } else {
-      sanitizedProps[key] = toLonghandProp(val11);
+      sanitizedProps[key] = toLonghandProp(val13);
     }
   }
   return sanitizedProps;
@@ -3324,15 +3445,15 @@ var file = (defaultValue, opts = {}) => {
     deserializeAndSanitize: _ensureFile
   };
 };
-var _ensureFile = (val11) => {
-  if (!val11) return void 0;
+var _ensureFile = (val13) => {
+  if (!val13) return void 0;
   let valid = true;
-  if (typeof val11.id !== "string" && ![null, void 0].includes(val11.id)) {
+  if (typeof val13.id !== "string" && ![null, void 0].includes(val13.id)) {
     valid = false;
   }
-  if (val11.type !== "file") valid = false;
+  if (val13.type !== "file") valid = false;
   if (!valid) return void 0;
-  return val11;
+  return val13;
 };
 var image = (defaultValue, opts = {}) => {
   if (process.env.NODE_ENV !== "production") {
@@ -3356,15 +3477,15 @@ var image = (defaultValue, opts = {}) => {
     deserializeAndSanitize: _ensureImage
   };
 };
-var _ensureImage = (val11) => {
-  if (!val11) return void 0;
+var _ensureImage = (val13) => {
+  if (!val13) return void 0;
   let valid = true;
-  if (typeof val11.id !== "string" && ![null, void 0].includes(val11.id)) {
+  if (typeof val13.id !== "string" && ![null, void 0].includes(val13.id)) {
     valid = false;
   }
-  if (val11.type !== "image") valid = false;
+  if (val13.type !== "image") valid = false;
   if (!valid) return void 0;
-  return val11;
+  return val13;
 };
 var number = (defaultValue, opts = {}) => {
   if (process.env.NODE_ENV !== "production") {
@@ -3487,11 +3608,11 @@ var rgba = (defaultValue = { r: 0, g: 0, b: 0, a: 1 }, opts = {}) => {
     deserializeAndSanitize: _sanitizeRgba
   };
 };
-var _sanitizeRgba = (val11) => {
-  if (!val11) return void 0;
+var _sanitizeRgba = (val13) => {
+  if (!val13) return void 0;
   let valid = true;
   for (const c2 of ["r", "g", "b", "a"]) {
-    if (!Object.prototype.hasOwnProperty.call(val11, c2) || typeof val11[c2] !== "number") {
+    if (!Object.prototype.hasOwnProperty.call(val13, c2) || typeof val13[c2] !== "number") {
       valid = false;
     }
   }
@@ -3500,7 +3621,7 @@ var _sanitizeRgba = (val11) => {
   for (const c2 of ["r", "g", "b", "a"]) {
     ;
     sanitized[c2] = Math.min(
-      Math.max(val11[c2], 0),
+      Math.max(val13[c2], 0),
       1
     );
   }
@@ -3539,8 +3660,8 @@ var boolean = (defaultValue, opts = {}) => {
     deserializeAndSanitize: _ensureBoolean
   };
 };
-var _ensureBoolean = (val11) => {
-  return typeof val11 === "boolean" ? val11 : void 0;
+var _ensureBoolean = (val13) => {
+  return typeof val13 === "boolean" ? val13 : void 0;
 };
 function leftInterpolate(left) {
   return left;
@@ -3747,8 +3868,8 @@ var TheatreSheetObject = class {
     }
     return der.getValue();
   }
-  set initialValue(val11) {
-    privateAPI(this).setInitialValue(val11);
+  set initialValue(val13) {
+    privateAPI(this).setInitialValue(val13);
   }
   showPropsOf(objects) {
     const host = privateAPI(this);
@@ -4516,9 +4637,9 @@ var SheetObject = class {
   }
   validateValue(pointer3, value) {
   }
-  setInitialValue(val11) {
-    this.validateValue(this.propsP, val11);
-    this._initialValue.set(val11);
+  setInitialValue(val13) {
+    this.validateValue(this.propsP, val13);
+    this._initialValue.set(val13);
   }
   setSessionOverride(path, value) {
     const propConfig = getPropConfigByPath(this.template.staticConfig, path);
@@ -4538,8 +4659,8 @@ var SheetObject = class {
    * Internal: called by `RemoteSync` when a value update for this object
    * arrives from a remote editor window. Not exposed on the public API.
    */
-  setRemoteOverride(val11) {
-    this._remoteOverride.set(val11);
+  setRemoteOverride(val13) {
+    this._remoteOverride.set(val13);
   }
   /**
    * Internal: used by `RemoteSync` to subscribe to this object's fully
@@ -5519,7 +5640,7 @@ function parsePathToProp(pathToPropInString) {
 }
 
 // core/src/sheets/SheetTemplate.ts
-import { Atom as Atom9 } from "@unseenco/theatre-dataverse";
+import { Atom as Atom10 } from "@unseenco/theatre-dataverse";
 
 // shared/src/utils/didYouMean.ts
 var import_propose = __toESM(require_propose());
@@ -5536,7 +5657,7 @@ function didYouMean(str, dictionary, prepend = "Did you mean ", append = "?") {
 
 // core/src/sequences/Sequence.ts
 import { getPointerParts as getPointerParts3 } from "@unseenco/theatre-dataverse";
-import { Atom as Atom7 } from "@unseenco/theatre-dataverse";
+import { Atom as Atom8 } from "@unseenco/theatre-dataverse";
 import { pointer as pointer2 } from "@unseenco/theatre-dataverse";
 import { prism as prism6, val as val6 } from "@unseenco/theatre-dataverse";
 
@@ -5917,11 +6038,11 @@ var AudioPlaybackController = class {
         "The sequence will still play, but only 1000 times. The `iterationCount: ".concat(iterationCount, "` provided to `sequence.play()`\nis too high for a sequence with audio.\n\nTo fix this, either set `iterationCount` to a lower value, or remove the audio from the sequence."),
         [
           {
-            url: "https://www.theatrejs.com/docs/latest/manual/audio",
+            url: "https://unseen-theatre.netlify.app/docs/guide/manual/audio",
             title: "Using Audio"
           },
           {
-            url: "https://www.theatrejs.com/docs/latest/api/core#sequence.attachaudio",
+            url: "https://unseen-theatre.netlify.app/docs/api/theatre-core#sequence.attachaudio",
             title: "Audio API"
           }
         ]
@@ -5974,82 +6095,6 @@ var AudioPlaybackController = class {
   }
 };
 
-// core/src/rafDrivers.ts
-import { Ticker } from "@unseenco/theatre-dataverse";
-var lastDriverId = 0;
-function createRafDriver(conf) {
-  const tick = (time) => {
-    ticker.tick(time);
-  };
-  const ticker = new Ticker({
-    onActive() {
-      conf?.start?.();
-    },
-    onDormant() {
-      conf?.stop?.();
-    }
-  });
-  const driverPublicApi = {
-    tick,
-    id: lastDriverId++,
-    name: conf?.name ?? "CustomRafDriver-".concat(lastDriverId),
-    type: "Theatre_RafDriver_PublicAPI"
-  };
-  const driverPrivateApi = {
-    type: "Theatre_RafDriver_PrivateAPI",
-    publicApi: driverPublicApi,
-    ticker,
-    start: conf?.start,
-    stop: conf?.stop
-  };
-  setPrivateAPI(driverPublicApi, driverPrivateApi);
-  return driverPublicApi;
-}
-
-// core/src/coreTicker.ts
-function createBasicRafDriver() {
-  let rafId = null;
-  const start = () => {
-    if (typeof window !== "undefined") {
-      const onAnimationFrame = (t2) => {
-        driver.tick(t2);
-        rafId = window.requestAnimationFrame(onAnimationFrame);
-      };
-      rafId = window.requestAnimationFrame(onAnimationFrame);
-    } else {
-      driver.tick(0);
-      setTimeout(() => driver.tick(1), 0);
-    }
-  };
-  const stop = () => {
-    if (typeof window !== "undefined") {
-      if (rafId !== null) {
-        window.cancelAnimationFrame(rafId);
-      }
-    } else {
-    }
-  };
-  const driver = createRafDriver({ name: "DefaultCoreRafDriver", start, stop });
-  return driver;
-}
-var coreRafDriver;
-function getCoreRafDriver() {
-  if (!coreRafDriver) {
-    setCoreRafDriver(createBasicRafDriver());
-  }
-  return coreRafDriver;
-}
-function getCoreTicker() {
-  return getCoreRafDriver().ticker;
-}
-function setCoreRafDriver(driver) {
-  if (coreRafDriver) {
-    throw new Error("`setCoreRafDriver()` is already called.");
-  }
-  const driverPrivateApi = privateAPI(driver);
-  coreRafDriver = driverPrivateApi;
-}
-
 // core/src/sequences/TheatreSequence.ts
 var TheatreSequence = class {
   get type() {
@@ -6073,7 +6118,7 @@ var TheatreSequence = class {
           "You seem to have called `sequence.play()` before the project has finished loading.\n\nThis would **not** a problem in production when using `@unseenco/theatre-core`, since Theatre.js loads instantly in core mode. However, when using `@unseenco/theatre-studio`, it takes a few milliseconds for it to load your project's state, before which your sequences cannot start playing.\n\nTo fix this, simply defer calling `sequence.play()` until after the project is loaded, like this:\n\n```\nproject.ready.then(() => {\n  sequence.play()\n})\n```",
           [
             {
-              url: "https://www.theatrejs.com/docs/0.5/api/core#project.ready",
+              url: "https://unseen-theatre.netlify.app/docs/api/theatre-core#project.ready",
               title: "Project.ready"
             }
           ]
@@ -6099,14 +6144,27 @@ var TheatreSequence = class {
   __experimental_getGsapClips() {
     return privateAPI(this).getGsapClips();
   }
+  __experimental_getGsapScrollTriggers() {
+    return privateAPI(this).getGsapScrollTriggers();
+  }
   async attachAudio(args) {
+    const priv = privateAPI(this);
+    if (priv._sheet.getSequenceMode() === "page") {
+      notify.warning(
+        "Audio is not supported in page mode",
+        "Sequence audio expects time in seconds. Use time mode for attachAudio(), or scrub scroll-driven animation without audio."
+      );
+      return Promise.reject(
+        new Error("sequence.attachAudio() is not supported in page mode")
+      );
+    }
     const { audioContext, destinationNode, decodedBuffer, gainNode } = await resolveAudioBuffer(args);
     const playbackController = new AudioPlaybackController(
       decodedBuffer,
       audioContext,
       gainNode
     );
-    privateAPI(this).replacePlaybackController(playbackController);
+    priv.replacePlaybackController(playbackController);
     return { audioContext, destinationNode, decodedBuffer, gainNode };
   }
   get pointer() {
@@ -6204,6 +6262,31 @@ async function resolveAudioBuffer(args) {
   };
 }
 
+// shared/src/gsap/gsapStudioRegistryRevision.ts
+import { Atom as Atom7 } from "@unseenco/theatre-dataverse";
+var revisionAtom = new Atom7(0);
+var gsapStudioRegistryRevisionPointer = revisionAtom.pointer;
+
+// shared/src/gsap/scrollTriggerRegistry.ts
+var DEFAULT_SHEET_INSTANCE_ID = "default";
+var REGISTRY_KEY = "__unseenco_theatre_gsap_scrollTriggerRegistry__";
+function sheetAddressKey(address) {
+  const sheetInstanceId = address.sheetInstanceId ?? DEFAULT_SHEET_INSTANCE_ID;
+  return "".concat(address.projectId, "|").concat(address.sheetId, "|").concat(sheetInstanceId);
+}
+function getStore() {
+  const g2 = globalThis;
+  if (!g2[REGISTRY_KEY]) {
+    g2[REGISTRY_KEY] = { bySheetAddress: /* @__PURE__ */ new Map() };
+  }
+  return g2[REGISTRY_KEY];
+}
+function listScrollTriggerEntriesForSheet(sheetKey) {
+  const map = getStore().bySheetAddress.get(sheetKey);
+  if (!map) return [];
+  return [...map.values()].sort((a2, b2) => a2.layout.start - b2.layout.start);
+}
+
 // shared/src/sequence/trackData.ts
 function isBasicKeyframedTrack(track) {
   return track.type === "BasicKeyframedTrack";
@@ -6211,6 +6294,19 @@ function isBasicKeyframedTrack(track) {
 function isGsapClipTrack(track) {
   return track.type === "GsapClipTrack";
 }
+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;
+}
 
 // core/src/sequences/Sequence.ts
 var possibleDirections = [
@@ -6246,7 +6342,7 @@ var Sequence = class {
     this._logger = _project._logger.named("Sheet", _sheet.address.sheetId).named("Instance", _sheet.address.sheetInstanceId).named("Variant", _sequenceVariant);
     this.address = { ...this._sheet.address, sequenceName: _sequenceVariant };
     this.publicApi = new TheatreSequence(this);
-    this._playbackControllerBox = new Atom7(
+    this._playbackControllerBox = new Atom8(
       playbackController ?? new DefaultPlaybackController()
     );
     this._prismOfStatePointer = prism6(
@@ -6258,6 +6354,9 @@ var Sequence = class {
     });
     this._positionFormatterD = prism6(() => {
       const subUnitsPerUnit = val6(this._subUnitsPerUnitD);
+      if (this._sheet.getSequenceMode() === "page") {
+        return new PercentBasedPositionFormatter(subUnitsPerUnit);
+      }
       return new TimeBasedPositionFormatter(subUnitsPerUnit);
     });
   }
@@ -6363,6 +6462,21 @@ var Sequence = class {
     }
     return result.sort((a2, b2) => a2.clip.start - b2.clip.start);
   }
+  getGsapScrollTriggers() {
+    if (this._sheet.getSequenceMode() !== "page") {
+      return [];
+    }
+    const key = sheetAddressKey(this._sheet.address);
+    return listScrollTriggerEntriesForSheet(key).filter((entry) => entry.sheetObject != null).map((entry) => ({
+      objectKey: entry.sheetObject.address.objectKey,
+      scrollTriggerId: entry.id,
+      label: entry.label,
+      layout: entry.layout,
+      kind: entry.kind,
+      animationSpanSeconds: entry.animationSpanSeconds,
+      timelineChildren: entry.timelineChildren
+    }));
+  }
   get positionFormatter() {
     return this._positionFormatterD.getValue();
   }
@@ -6433,6 +6547,13 @@ var Sequence = class {
     return this._playbackControllerBox.get().playDynamicRange(rangeD, ticker);
   }
   async play(conf, ticker) {
+    if (this._sheet.getSequenceMode() === "page") {
+      notify.warning(
+        "Playback is disabled in page mode",
+        "The sequence is driven by page scroll. Scrub the playhead or scroll the page instead of calling sequence.play()."
+      );
+      return false;
+    }
     const sequenceDuration = this.length;
     const range = conf && conf.range ? conf.range : [0, sequenceDuration];
     if (process.env.NODE_ENV !== "production") {
@@ -6465,11 +6586,11 @@ var Sequence = class {
           ), "s) is longer than the duration of the sequence (").concat(sequenceDuration, "s).\n\nTo fix this, either set `conf.range[1]` to be less the duration of the sequence, or adjust the sequence duration in the UI."),
           [
             {
-              url: "https://www.theatrejs.com/docs/latest/manual/sequences",
+              url: "https://unseen-theatre.netlify.app/docs/guide/manual/sequences",
               title: "Sequences"
             },
             {
-              url: "https://www.theatrejs.com/docs/latest/manual/sequences",
+              url: "https://unseen-theatre.netlify.app/docs/guide/manual/sequences",
               title: "Playback API"
             }
           ]
@@ -6623,6 +6744,33 @@ var TimeBasedPositionFormatter = class {
     return posInUnitSpace.toFixed(2) + "s";
   }
 };
+var PercentBasedPositionFormatter = class {
+  constructor(_subUnitsPerUnit) {
+    this._subUnitsPerUnit = _subUnitsPerUnit;
+  }
+  formatSubUnitForGrid(posInUnitSpace) {
+    const subUnitSize = 1 / this._subUnitsPerUnit;
+    const withinUnit = posInUnitSpace % 1;
+    const tenths = Math.round(withinUnit / subUnitSize);
+    return tenths + "t";
+  }
+  formatFullUnitForGrid(posInUnitSpace) {
+    return Math.round(posInUnitSpace) + "%";
+  }
+  formatForPlayhead(posInUnitSpace) {
+    const whole = Math.floor(posInUnitSpace);
+    const subUnitSize = 1 / this._subUnitsPerUnit;
+    const withinUnit = posInUnitSpace - whole;
+    const tenths = Math.round(withinUnit / subUnitSize);
+    if (tenths <= 0) {
+      return whole + "%";
+    }
+    return whole + "." + tenths + "%";
+  }
+  formatBasic(posInUnitSpace) {
+    return posInUnitSpace.toFixed(1) + "%";
+  }
+};
 var second = 1;
 var minute = second * 60;
 var hour = minute * 60;
@@ -6657,11 +6805,11 @@ function validateAndSanitiseSlashedPathOrThrow(unsanitisedPath, fnName) {
       "The path in `".concat(fnName, '("').concat(unsanitisedPath, '")` was sanitized to `"').concat(sanitisedPath, '"`.\n\n') + "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"
         }
       ]
@@ -6876,6 +7024,15 @@ var TheatreSheet = class {
   getActiveSequenceVariant() {
     return privateAPI(this).getActiveSequenceVariant();
   }
+  getSequenceMode() {
+    return privateAPI(this).getSequenceMode();
+  }
+  setSequenceMode(mode) {
+    privateAPI(this).setSequenceMode(mode);
+  }
+  setPageScrollDriver(driver) {
+    privateAPI(this).setPageScrollDriver(driver);
+  }
   get project() {
     return privateAPI(this).project.publicApi;
   }
@@ -6933,14 +7090,373 @@ var TheatreSheet = class {
 };
 
 // core/src/sheets/Sheet.ts
-import { Atom as Atom8, prism as prism7, val as val7 } from "@unseenco/theatre-dataverse";
+import { Atom as Atom9, prism as prism8, val as val9 } from "@unseenco/theatre-dataverse";
+
+// core/src/sheets/sheetSequenceMode.ts
+var PAGE_MODE_SEQUENCE_LENGTH = 100;
+var PAGE_MODE_SUB_UNITS_PER_UNIT = 10;
+
+// 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 t2 = tween;
+      if (typeof t2.startTime === "function") {
+        t2.startTime(childState.localStart);
+      }
+      if (typeof t2.duration === "function") {
+        t2.duration(childState.localDuration);
+      }
+    } catch {
+      ok = false;
+    }
+  }
+  return ok;
+}
+
+// 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((a2, b2) => a2.start - b2.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 t2 = progress * Math.max(span, 0.01);
+        if (typeof animation.time === "function") {
+          animation.time(t2, true);
+        } else {
+          animation.progress?.(progress, true);
+        }
+      } else {
+        animation.progress?.(progress, true);
+      }
+    }
+  }
+}
+function readGsapTweenTimelineDuration(animation) {
+  const tween = animation;
+  const total = tween.totalDuration?.();
+  if (typeof total === "number" && total > 0) return total;
+  const d2 = tween.duration();
+  return d2 > 0 ? d2 : 1;
+}
+
+// shared/src/gsap/gsapAnimationRegistry.ts
+var DEFAULT_SHEET_INSTANCE_ID2 = "default";
+var REGISTRY_KEY2 = "__unseenco_theatre_gsap_animationRegistry__";
+function sheetObjectAddressKeyFromParts(address) {
+  const sheetInstanceId = address.sheetInstanceId ?? DEFAULT_SHEET_INSTANCE_ID2;
+  return "".concat(address.projectId, "|").concat(address.sheetId, "|").concat(sheetInstanceId, "|").concat(address.objectKey);
+}
+function getStore2() {
+  const g2 = globalThis;
+  if (!g2[REGISTRY_KEY2]) {
+    g2[REGISTRY_KEY2] = {
+      bySheetAddress: /* @__PURE__ */ new Map()
+    };
+  }
+  return g2[REGISTRY_KEY2];
+}
+function getAnimationEntryBySheetAddressKey(sheetObjectAddressKey, animationId) {
+  return getStore2().bySheetAddress.get(sheetObjectAddressKey)?.get(animationId);
+}
+
+// shared/src/gsap/subscribeGsapClipSyncAtPlayhead.ts
+import { pointerToPrism, prism as prism7, val as val7 } from "@unseenco/theatre-dataverse";
+
+// shared/src/gsap/syncGsapClipsAtSequencePosition.ts
+function syncGsapClipsAtSequencePosition(position, clips) {
+  syncRegisteredGsapAnimationsForClips(
+    position,
+    clips
+  );
+}
+
+// shared/src/gsap/subscribeGsapClipSyncAtPlayhead.ts
+function subscribeGsapClipSyncAtPlayhead(source) {
+  const positionPointer = source.pointer.position;
+  const positionPrism = pointerToPrism(positionPointer);
+  const clipsPrism = prism7(() => source.getGsapClipTimings());
+  const syncNow = () => {
+    const clips = clipsPrism.getValue();
+    if (clips.length === 0) return;
+    syncGsapClipsAtSequencePosition(val7(positionPointer), clips);
+  };
+  const untapPosition = positionPrism.onStale(syncNow);
+  const untapClips = clipsPrism.onStale(syncNow);
+  syncNow();
+  return () => {
+    untapPosition();
+    untapClips();
+  };
+}
+
+// core/src/gsap/attachGsapSequenceBridge.ts
+function attachGsapSequenceBridge(sheet) {
+  const sequence = sheet.sequence;
+  const sheetAddress = privateAPI(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
+    }))
+  });
+}
+
+// core/src/sheets/attachSheetScrollDriver.ts
+import { val as val8 } from "@unseenco/theatre-dataverse";
+var sheetScrollDrivers = /* @__PURE__ */ new WeakMap();
+var pageScrollDrivenSequencePositionListeners = /* @__PURE__ */ new Set();
+function onPageScrollDrivenSequencePosition(listener) {
+  pageScrollDrivenSequencePositionListeners.add(listener);
+  return () => {
+    pageScrollDrivenSequencePositionListeners.delete(listener);
+  };
+}
+function notifyPageScrollDrivenSequencePosition(sheet, position) {
+  for (const listener of pageScrollDrivenSequencePositionListeners) {
+    listener(sheet, position);
+  }
+}
+function getSheetScrollDriver(sheet) {
+  return sheetScrollDrivers.get(sheet);
+}
+function rememberSheetScrollDriver(sheet, driver) {
+  sheetScrollDrivers.set(sheet, driver);
+}
+function progressFromScrollPosition(position, max) {
+  if (max <= 0) return 0;
+  if (position <= 0) return 0;
+  if (position >= max - 1) return 1;
+  return position / max;
+}
+function getNativeDocumentScrollingElement() {
+  return document.scrollingElement ?? document.documentElement;
+}
+function addNativeDocumentScrollListener(handler) {
+  document.addEventListener("scroll", handler, { passive: true, capture: true });
+  return () => document.removeEventListener("scroll", handler, { capture: true });
+}
+function createScrollDriverFromElement(getMaxScroll, getScrollPos, setScrollPos, addScrollListener) {
+  let suppressScrollEvents = false;
+  let suppressGeneration = 0;
+  const getProgress = () => {
+    const max = getMaxScroll();
+    return progressFromScrollPosition(getScrollPos(), max);
+  };
+  const setProgress = (progress) => {
+    const max = getMaxScroll();
+    const clamped = Math.max(0, Math.min(1, progress));
+    const gen = ++suppressGeneration;
+    suppressScrollEvents = true;
+    setScrollPos(clamped * max);
+    const release = () => {
+      if (gen === suppressGeneration) {
+        suppressScrollEvents = false;
+      }
+    };
+    requestAnimationFrame(() => requestAnimationFrame(release));
+  };
+  return {
+    getProgress,
+    setProgress,
+    subscribe(onProgressChange) {
+      let rafId = 0;
+      const flush = () => {
+        rafId = 0;
+        if (suppressScrollEvents) return;
+        onProgressChange(getProgress());
+      };
+      const scheduleFlush = () => {
+        if (rafId !== 0) return;
+        rafId = requestAnimationFrame(flush);
+      };
+      const handler = () => scheduleFlush();
+      const removeScroll = addScrollListener(handler);
+      const onResize = () => scheduleFlush();
+      window.addEventListener("resize", onResize);
+      return () => {
+        removeScroll();
+        window.removeEventListener("resize", onResize);
+        if (rafId !== 0) cancelAnimationFrame(rafId);
+      };
+    }
+  };
+}
+function createNativeDocumentScrollDriver() {
+  const getMaxScroll = () => {
+    const el = document.documentElement;
+    return Math.max(0, el.scrollHeight - window.innerHeight);
+  };
+  return createScrollDriverFromElement(
+    getMaxScroll,
+    () => window.scrollY,
+    (y2) => window.scrollTo({ top: y2, behavior: "instant" }),
+    addNativeDocumentScrollListener
+  );
+}
+function createNativeDocumentHorizontalScrollDriver() {
+  const getMaxScroll = () => {
+    const el = getNativeDocumentScrollingElement();
+    return Math.max(0, el.scrollWidth - el.clientWidth);
+  };
+  const getScrollLeft = () => {
+    const el = getNativeDocumentScrollingElement();
+    return el.scrollLeft;
+  };
+  return createScrollDriverFromElement(
+    getMaxScroll,
+    getScrollLeft,
+    (x2) => {
+      getNativeDocumentScrollingElement().scrollLeft = x2;
+    },
+    addNativeDocumentScrollListener
+  );
+}
+function createElementScrollDriver(element) {
+  const getMaxScroll = () => Math.max(0, element.scrollHeight - element.clientHeight);
+  return createScrollDriverFromElement(
+    getMaxScroll,
+    () => element.scrollTop,
+    (y2) => {
+      element.scrollTop = y2;
+    },
+    (handler) => {
+      element.addEventListener("scroll", handler, { passive: true });
+      return () => element.removeEventListener("scroll", handler);
+    }
+  );
+}
+function createElementHorizontalScrollDriver(element) {
+  const getMaxScroll = () => Math.max(0, element.scrollWidth - element.clientWidth);
+  return createScrollDriverFromElement(
+    getMaxScroll,
+    () => element.scrollLeft,
+    (x2) => {
+      element.scrollLeft = x2;
+    },
+    (handler) => {
+      element.addEventListener("scroll", handler, { passive: true });
+      return () => element.removeEventListener("scroll", handler);
+    }
+  );
+}
+function attachSheetScrollDriver(sheet, driver = createNativeDocumentScrollDriver()) {
+  rememberSheetScrollDriver(sheet, driver);
+  const sequence = sheet.sequence;
+  const syncPositionFromScroll = (progress) => {
+    const length = val8(sequence.pointer.length);
+    if (length <= 0) return;
+    sequence.position = progress * length;
+  };
+  const untapScroll = driver.subscribe((progress) => {
+    syncPositionFromScroll(progress);
+    notifyPageScrollDrivenSequencePosition(sheet, sequence.position);
+  });
+  syncPositionFromScroll(driver.getProgress());
+  return () => {
+    untapScroll();
+  };
+}
+function pageScrollProgressFromSequence(sheet) {
+  const length = val8(sheet.sequence.pointer.length);
+  if (length <= 0) return 0;
+  return sheet.sequence.position / length;
+}
+function setPageScrollProgress(sheet, progress) {
+  const length = val8(sheet.sequence.pointer.length);
+  if (length <= 0) return;
+  const clamped = Math.max(0, Math.min(1, progress));
+  sheet.sequence.position = clamped * length;
+}
+function syncPageScrollToSequencePosition(sheet, driver = getSheetScrollDriver(sheet) ?? createNativeDocumentScrollDriver()) {
+  const progress = pageScrollProgressFromSequence(sheet);
+  driver.setProgress(progress);
+}
+function syncNativeDocumentScrollToSequencePosition(sheet) {
+  syncPageScrollToSequencePosition(sheet, createNativeDocumentScrollDriver());
+}
+
+// core/src/sheets/Sheet.ts
 var Sheet = class {
   constructor(template, instanceId) {
     this.template = template;
     this.instanceId = instanceId;
-    __publicField(this, "_objects", new Atom8({}));
+    __publicField(this, "_objects", new Atom9({}));
     __publicField(this, "_sequences", {});
-    __publicField(this, "_activeSequenceVariant", new Atom8(
+    __publicField(this, "_activeSequenceVariant", new Atom9(
       DEFAULT_SEQUENCE_VARIANT
     ));
     /**
@@ -6948,7 +7464,12 @@ var Sheet = class {
      * value resolution (preview). User code can still update `_activeSequenceVariant`
      * via `setActiveSequenceVariant()` without affecting the Studio preview.
      */
-    __publicField(this, "_studioPreviewVariantOverride", new Atom8(void 0));
+    __publicField(this, "_studioPreviewVariantOverride", new Atom9(void 0));
+    __publicField(this, "_sequenceMode", new Atom9("time"));
+    __publicField(this, "sequenceModeP", this._sequenceMode.pointer);
+    __publicField(this, "_pageScrollDisposer");
+    __publicField(this, "_customPageScrollDriver");
+    __publicField(this, "_gsapBridgeDisposer");
     __publicField(this, "activeSequenceVariantP", this._activeSequenceVariant.pointer);
     __publicField(this, "effectiveActiveSequenceVariantD");
     __publicField(this, "address");
@@ -6965,12 +7486,12 @@ var Sheet = class {
       sheetInstanceId: this.instanceId
     };
     this.publicApi = new TheatreSheet(this);
-    this.effectiveActiveSequenceVariantD = prism7(() => {
-      const studioOverride = val7(this._studioPreviewVariantOverride.pointer);
+    this.effectiveActiveSequenceVariantD = prism8(() => {
+      const studioOverride = val9(this._studioPreviewVariantOverride.pointer);
       if (studioOverride !== void 0) {
         return studioOverride;
       }
-      return val7(this._activeSequenceVariant.pointer);
+      return val9(this._activeSequenceVariant.pointer);
     });
   }
   /**
@@ -7021,6 +7542,7 @@ var Sheet = class {
    * this sheet instance from the project. Persisted state is kept.
    */
   unload() {
+    this.disposeRuntimeIntegrations();
     for (const sequence of Object.values(this._sequences)) {
       sequence.pause();
     }
@@ -7032,10 +7554,13 @@ var Sheet = class {
     this.project._unloadSheetInstance(this);
   }
   getSequence(variant) {
-    const variantId = variant ?? val7(this._activeSequenceVariant.pointer);
+    const variantId = variant ?? val9(this._activeSequenceVariant.pointer);
     if (!this._sequences[variantId]) {
-      const lengthD = prism7(() => {
-        const sheetState = val7(
+      const lengthD = prism8(() => {
+        if (val9(this._sequenceMode.pointer) === "page") {
+          return PAGE_MODE_SEQUENCE_LENGTH;
+        }
+        const sheetState = val9(
           this.project.pointers.historic.sheetsById[this.address.sheetId]
         );
         const unsanitized = getSequenceStateFromSheet(
@@ -7044,8 +7569,11 @@ var Sheet = class {
         )?.length;
         return sanitizeSequenceLength(unsanitized);
       });
-      const subUnitsPerUnitD = prism7(() => {
-        const sheetState = val7(
+      const subUnitsPerUnitD = prism8(() => {
+        if (val9(this._sequenceMode.pointer) === "page") {
+          return PAGE_MODE_SUB_UNITS_PER_UNIT;
+        }
+        const sheetState = val9(
           this.project.pointers.historic.sheetsById[this.address.sheetId]
         );
         const unsanitized = getSequenceStateFromSheet(
@@ -7097,6 +7625,44 @@ var Sheet = class {
     }
     this._studioPreviewVariantOverride.set(variantId);
   }
+  getSequenceMode() {
+    return this._sequenceMode.get();
+  }
+  setSequenceMode(mode) {
+    if (this._sequenceMode.get() === mode) return;
+    this._sequenceMode.set(mode);
+    this.syncPageScrollDriver();
+    if (this._gsapBridgeDisposer) {
+      this._gsapBridgeDisposer();
+      this._gsapBridgeDisposer = attachGsapSequenceBridge(this.publicApi);
+    }
+  }
+  enableGsapSequenceBridge() {
+    if (this._gsapBridgeDisposer) return;
+    this._gsapBridgeDisposer = attachGsapSequenceBridge(this.publicApi);
+    this.syncPageScrollDriver();
+  }
+  disposeRuntimeIntegrations() {
+    this._pageScrollDisposer?.();
+    this._pageScrollDisposer = void 0;
+    this._gsapBridgeDisposer?.();
+    this._gsapBridgeDisposer = void 0;
+  }
+  syncPageScrollDriver() {
+    this._pageScrollDisposer?.();
+    this._pageScrollDisposer = void 0;
+    if (this.getSequenceMode() === "page") {
+      const driver = this._customPageScrollDriver ?? createNativeDocumentScrollDriver();
+      this._pageScrollDisposer = attachSheetScrollDriver(this.publicApi, driver);
+    }
+  }
+  setPageScrollDriver(driver) {
+    this._customPageScrollDriver = driver;
+    this.syncPageScrollDriver();
+  }
+  getPageScrollDriver() {
+    return this._customPageScrollDriver;
+  }
 };
 var sanitizeSequenceLength = (len) => typeof len === "number" && isFinite(len) && len > 0 ? len : 10;
 var sanitizeSequenceSubUnitsPerUnit = (subs) => typeof subs === "number" && isInteger_default(subs) && subs >= 1 && subs <= 1e3 ? subs : 30;
@@ -7107,13 +7673,13 @@ var SheetTemplate = class {
     this.project = project;
     __publicField(this, "type", "Theatre_SheetTemplate");
     __publicField(this, "address");
-    __publicField(this, "_instances", new Atom9({}));
+    __publicField(this, "_instances", new Atom10({}));
     __publicField(this, "instancesP", this._instances.pointer);
-    __publicField(this, "_objectTemplates", new Atom9({}));
+    __publicField(this, "_objectTemplates", new Atom10({}));
     __publicField(this, "objectTemplatesP", this._objectTemplates.pointer);
     __publicField(this, "_pendingOutlineNamespaces", {});
     __publicField(this, "_sequenceVariants", [DEFAULT_SEQUENCE_VARIANT]);
-    __publicField(this, "_visibleInOutline", new Atom9(true));
+    __publicField(this, "_visibleInOutline", new Atom10(true));
     __publicField(this, "visibleInOutlineP", this._visibleInOutline.pointer);
     this.address = { ...project.address, sheetId };
   }
@@ -7196,7 +7762,7 @@ var SheetTemplate = class {
 
 // core/src/projects/Project.ts
 import { PointerProxy } from "@unseenco/theatre-dataverse";
-import { Atom as Atom10 } from "@unseenco/theatre-dataverse";
+import { Atom as Atom11 } from "@unseenco/theatre-dataverse";
 
 // shared/src/utils/delay.ts
 var delay = (dur) => new Promise((resolve) => setTimeout(resolve, dur));
@@ -7634,8 +8200,165 @@ async function initialiseProjectState(studio, project, onDiskState) {
   });
 }
 
+// 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 getActivePageScrollContext() {
+  return activePageScrollContext;
+}
+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(a2, b2) {
+  if (a2 === b2) return true;
+  if (isNativeDocumentScroller(a2) && isNativeDocumentScroller(b2)) 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);
+}
+function isVerticalPageScrollTrigger(st, context = defaultPageScrollContext) {
+  return isPageScrollTrigger(st, {
+    scroller: context.scroller,
+    axis: "vertical"
+  });
+}
+
+// shared/src/gsap/scrollTriggerLayout.ts
+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);
+}
+
+// shared/src/gsap/domElementHighlightTarget.ts
+function resolveDomElementHighlightTarget(target) {
+  if (typeof document === "undefined") {
+    return null;
+  }
+  if (target.type === "id") {
+    return document.getElementById(target.id);
+  }
+  try {
+    const match = document.querySelector(target.selector);
+    return match instanceof Element ? match : null;
+  } catch {
+    return null;
+  }
+}
+
+// shared/src/sheets/remoteDomElementHighlight.ts
+var listeners = /* @__PURE__ */ new Set();
+function setRemoteDomElementHighlight(element) {
+  for (const listener of listeners) {
+    listener(element);
+  }
+}
+
+// shared/src/sheets/remotePageScrollMetrics.ts
+var remoteMetrics;
+var listeners2 = /* @__PURE__ */ new Set();
+function setRemotePageScrollMetrics(metrics) {
+  const prev = remoteMetrics;
+  remoteMetrics = metrics;
+  if (prev?.maxScroll !== metrics?.maxScroll || prev?.axis !== metrics?.axis) {
+    for (const listener of listeners2) {
+      listener();
+    }
+  }
+}
+
 // core/src/internal/RemoteSync.ts
-import { val as val8 } from "@unseenco/theatre-dataverse";
+import { pointerToPrism as pointerToPrism2, val as val10 } from "@unseenco/theatre-dataverse";
+
+// core/src/internal/createDebouncedCallback.ts
+function createDebouncedCallback(fn2, delayMs) {
+  let timeoutId;
+  const clearPending = () => {
+    if (timeoutId !== void 0) {
+      clearTimeout(timeoutId);
+      timeoutId = void 0;
+    }
+  };
+  return {
+    schedule() {
+      clearPending();
+      timeoutId = setTimeout(() => {
+        timeoutId = void 0;
+        fn2();
+      }, delayMs);
+    },
+    flush() {
+      if (timeoutId === void 0) return;
+      clearPending();
+      fn2();
+    },
+    cancel() {
+      clearPending();
+    }
+  };
+}
 
 // core/src/internal/remoteEditor.ts
 function isRemoteEditorWindow() {
@@ -7643,6 +8366,10 @@ function isRemoteEditorWindow() {
 }
 
 // core/src/internal/RemoteSync.ts
+var REMOTE_HISTORIC_SYNC_DEBOUNCE_MS = 100;
+function shouldSyncPageScrollWhenApplyingTimelineUpdate(isEditor, sequenceMode) {
+  return !isEditor && sequenceMode === "page";
+}
 var RemoteSync = class {
   constructor(project) {
     this.project = project;
@@ -7653,34 +8380,37 @@ var RemoteSync = class {
     __publicField(this, "objectUnsubs", /* @__PURE__ */ new Map());
     __publicField(this, "studio");
     __publicField(this, "activeSheet");
+    __publicField(this, "historicSyncDebounce");
+    __publicField(this, "lastBroadcastHistoricFingerprint");
+    __publicField(this, "historicSyncUnsubs", []);
+    __publicField(this, "remoteEditorActive", false);
+    __publicField(this, "suppressTimelineBroadcast", false);
+    __publicField(this, "listenerTimelineUnsub");
+    __publicField(this, "listenerMetricsUnsubs", []);
+    __publicField(this, "broadcastPageScrollMetrics");
     if (typeof BroadcastChannel === "undefined") return;
     this.channel = new BroadcastChannel(
       "theatre-remote:".concat(project.address.projectId)
     );
+    this.channel.onmessage = (event) => {
+      this._handleIncoming(event.data);
+    };
     if (!this.isEditor) {
-      this.channel.onmessage = (event) => {
-        this._handleIncoming(event.data);
-      };
+      this.listenerTimelineUnsub = onPageScrollDrivenSequencePosition(
+        (sheet, position) => {
+          this._broadcastTimelineFromListener(sheet, position);
+        }
+      );
     } else {
       const channel = this.channel;
       window.addEventListener("pagehide", () => {
-        const data = {};
-        if (this.studio) {
-          const projectId = this.project.address.projectId;
-          const historic = val8(
-            this.studio.atomP.historic.coreByProject[projectId]
-          );
-          const ahistoric = val8(
-            this.studio.atomP.ahistoric.coreByProject[projectId]
-          );
-          if (historic) {
-            data.historic = JSON.parse(JSON.stringify(historic));
-            if (ahistoric) {
-              data.ahistoric = JSON.parse(JSON.stringify(ahistoric));
-            }
-          }
+        this.historicSyncDebounce?.flush();
+        const data = this._readHistoricSnapshotFromStudio();
+        if (data && this.lastBroadcastHistoricFingerprint === fingerprintHistoricSnapshot(data)) {
+          channel.postMessage({ event: "disconnect", data: {} });
+          return;
         }
-        channel.postMessage({ event: "disconnect", data });
+        channel.postMessage({ event: "disconnect", data: data ?? {} });
       });
     }
   }
@@ -7731,8 +8461,13 @@ var RemoteSync = class {
   }
   attachStudio(studio) {
     this.studio = studio;
-    if (!this.isEditor || !this.channel) return;
+    if (!this.channel) return;
+    if (!this.isEditor) {
+      this._attachListenerPageScrollMetricsBroadcast();
+      return;
+    }
     const channel = this.channel;
+    channel.postMessage({ event: "editorHello", data: {} });
     const projectId = this.project.address.projectId;
     studio.publicApi.onSelectionChange((selection) => {
       for (const item of selection) {
@@ -7757,7 +8492,7 @@ var RemoteSync = class {
     let lastPosition;
     const ticker = getCoreTicker();
     const pollTimelinePosition = () => {
-      if (this.activeSheet) {
+      if (this.activeSheet && !this.suppressTimelineBroadcast) {
         const position = this.activeSheet.publicApi.sequence.position;
         if (position !== lastPosition) {
           lastPosition = position;
@@ -7771,9 +8506,117 @@ var RemoteSync = class {
       ticker.onNextTick(pollTimelinePosition);
     };
     ticker.onNextTick(pollTimelinePosition);
+    this.historicSyncDebounce = createDebouncedCallback(() => {
+      this._broadcastHistoricSnapshot();
+    }, REMOTE_HISTORIC_SYNC_DEBOUNCE_MS);
+    const scheduleHistoricSync = () => {
+      this.historicSyncDebounce?.schedule();
+    };
+    void studio.initialized.then(() => {
+      this.historicSyncUnsubs.push(
+        pointerToPrism2(studio.atomP.historic.coreByProject[projectId]).onChange(
+          studio.ticker,
+          scheduleHistoricSync,
+          true
+        ),
+        pointerToPrism2(
+          studio.atomP.ahistoric.coreByProject[projectId]
+        ).onChange(studio.ticker, scheduleHistoricSync, true)
+      );
+    });
+  }
+  _readHistoricSnapshotFromStudio() {
+    if (!this.studio) return void 0;
+    const projectId = this.project.address.projectId;
+    const historic = val10(
+      this.studio.atomP.historic.coreByProject[projectId]
+    );
+    if (!historic) return void 0;
+    const data = {
+      historic: JSON.parse(JSON.stringify(historic))
+    };
+    const ahistoric = val10(
+      this.studio.atomP.ahistoric.coreByProject[projectId]
+    );
+    if (ahistoric) {
+      data.ahistoric = JSON.parse(JSON.stringify(ahistoric));
+    }
+    return data;
+  }
+  _broadcastHistoricSnapshot(options) {
+    if (!this.channel) return;
+    const data = this._readHistoricSnapshotFromStudio();
+    if (!data) return;
+    const fingerprint = fingerprintHistoricSnapshot(data);
+    if (!options?.force && fingerprint === this.lastBroadcastHistoricFingerprint) {
+      return;
+    }
+    this.lastBroadcastHistoricFingerprint = fingerprint;
+    const message = { event: "updateHistoric", data };
+    this.channel.postMessage(message);
+  }
+  _applyHistoricSnapshot(historic, ahistoric) {
+    if (!this.studio) return;
+    const projectId = this.project.address.projectId;
+    this.studio.transaction(({ drafts }) => {
+      drafts.historic.coreByProject[projectId] = historic;
+      if (ahistoric) {
+        drafts.ahistoric.coreByProject[projectId] = ahistoric;
+      }
+      drafts.ephemeral.coreByProject[projectId].loadingState = {
+        type: "loaded"
+      };
+    });
+  }
+  _broadcastTimelineFromListener(sheet, position) {
+    if (this.isEditor || !this.channel || !this.remoteEditorActive || this.suppressTimelineBroadcast) {
+      return;
+    }
+    const registered = this.sheets.get(sheet.address.sheetId);
+    if (!registered || registered.getSequenceMode() !== "page") return;
+    const message = {
+      event: "updateTimeline",
+      data: { sheet: sheet.address.sheetId, position }
+    };
+    this.channel.postMessage(message);
+  }
+  _postPageScrollMetrics() {
+    if (!this.remoteEditorActive || !this.channel) return;
+    const ctx = getActivePageScrollContext();
+    const axis = resolvePageScrollAxis(ctx);
+    const maxScroll = getMaxScrollForPageScrollContext(ctx.scroller, axis);
+    const message = {
+      event: "pageScrollMetrics",
+      data: { maxScroll, axis }
+    };
+    this.channel.postMessage(message);
+  }
+  _attachListenerPageScrollMetricsBroadcast() {
+    if (this.isEditor || !this.channel) return;
+    const broadcast = () => this._postPageScrollMetrics();
+    this.broadcastPageScrollMetrics = broadcast;
+    const onScroll = () => broadcast();
+    document.addEventListener("scroll", onScroll, { passive: true, capture: true });
+    const onResize = () => broadcast();
+    window.addEventListener("resize", onResize);
+    const ScrollTrigger = globalThis.ScrollTrigger;
+    ScrollTrigger?.addEventListener?.("refresh", broadcast);
+    broadcast();
+    this.listenerMetricsUnsubs.push(() => {
+      document.removeEventListener("scroll", onScroll, { capture: true });
+      window.removeEventListener("resize", onResize);
+      ScrollTrigger?.removeEventListener?.("refresh", broadcast);
+    });
   }
   _handleIncoming(msg) {
     switch (msg.event) {
+      case "editorHello": {
+        if (this.isEditor) break;
+        this.remoteEditorActive = true;
+        this.broadcastPageScrollMetrics?.();
+        this._broadcastHistoricSnapshot({ force: true });
+        break;
+      }
       case "setSheet": {
         const sheet = this.sheets.get(msg.data.sheet);
         if (sheet && this.studio) {
@@ -7798,32 +8641,67 @@ var RemoteSync = class {
         const sheet = this.sheets.get(msg.data.sheet);
         if (sheet) {
           this.activeSheet = sheet;
+          this.suppressTimelineBroadcast = true;
           sheet.publicApi.sequence.position = msg.data.position;
+          if (shouldSyncPageScrollWhenApplyingTimelineUpdate(
+            this.isEditor,
+            sheet.getSequenceMode()
+          )) {
+            syncPageScrollToSequencePosition(sheet.publicApi);
+          }
+          requestAnimationFrame(() => {
+            this.suppressTimelineBroadcast = false;
+          });
+        }
+        break;
+      }
+      case "pageScrollMetrics": {
+        if (!this.isEditor) break;
+        const { maxScroll, axis } = msg.data;
+        setRemotePageScrollMetrics({ maxScroll, axis });
+        break;
+      }
+      case "highlightDomTarget": {
+        if (this.isEditor || !this.remoteEditorActive) break;
+        const target = msg.data.target;
+        const element = resolveDomElementHighlightTarget(target);
+        setRemoteDomElementHighlight(element);
+        break;
+      }
+      case "clearDomHighlight": {
+        if (this.isEditor || !this.remoteEditorActive) break;
+        setRemoteDomElementHighlight(null);
+        break;
+      }
+      case "updateHistoric": {
+        const { historic, ahistoric } = msg.data;
+        if (historic) {
+          this._applyHistoricSnapshot(historic, ahistoric);
         }
         break;
       }
       case "disconnect": {
         const { historic, ahistoric } = msg.data;
-        if (historic && this.studio) {
-          const projectId = this.project.address.projectId;
-          this.studio.transaction(({ drafts }) => {
-            drafts.historic.coreByProject[projectId] = historic;
-            if (ahistoric) {
-              drafts.ahistoric.coreByProject[projectId] = ahistoric;
-            }
-            drafts.ephemeral.coreByProject[projectId].loadingState = {
-              type: "loaded"
-            };
-          });
+        if (historic) {
+          this._applyHistoricSnapshot(historic, ahistoric);
         }
         for (const obj of this.objects.values()) {
           obj.setRemoteOverride({});
         }
+        if (!this.isEditor) {
+          this.remoteEditorActive = false;
+          setRemoteDomElementHighlight(null);
+        } else {
+          setRemotePageScrollMetrics(void 0);
+        }
         break;
       }
     }
   }
 };
+function fingerprintHistoricSnapshot(data) {
+  return JSON.stringify(data);
+}
 
 // core/src/_coreLogger.ts
 function noop2() {
@@ -7850,7 +8728,7 @@ function _coreLogger(config) {
 }
 
 // shared/src/utils/assets.ts
-import { val as val9 } from "@unseenco/theatre-dataverse";
+import { val as val11 } from "@unseenco/theatre-dataverse";
 
 // shared/src/utils/forEachDeep.ts
 function forEachPropDeep(m, fn2, startingPath = []) {
@@ -7920,7 +8798,7 @@ var Project = class {
     __publicField(this, "_studioReadyDeferred");
     __publicField(this, "_assetStorageReadyDeferred");
     __publicField(this, "_readyPromise");
-    __publicField(this, "_sheetTemplates", new Atom10({}));
+    __publicField(this, "_sheetTemplates", new Atom11({}));
     __publicField(this, "sheetTemplatesP", this._sheetTemplates.pointer);
     __publicField(this, "_studio");
     __publicField(this, "_onDiskStateAtom");
@@ -7933,7 +8811,7 @@ var Project = class {
     this._logger.traceDev("creating project");
     this.address = { projectId: id };
     this._remoteSync = new RemoteSync(this);
-    const onDiskStateAtom = new Atom10({
+    const onDiskStateAtom = new Atom11({
       ahistoric: {
         ahistoricStuff: ""
       },
@@ -7988,14 +8866,14 @@ var Project = class {
       if (typeof window === "undefined") {
         if (process.env.NODE_ENV === "production") {
           console.error(
-            'Argument config.state in Theatre.getProject("'.concat(id, '", config) is empty. ') + "You can safely ignore this message if you're developing a Next.js/Remix project in development mode. But if you are shipping to your end-users, then you need to set config.state, otherwise your project's state will be empty and nothing will animate. Learn more at https://www.theatrejs.com/docs/latest/manual/projects#state"
+            'Argument config.state in Theatre.getProject("'.concat(id, '", config) is empty. ') + "You can safely ignore this message if you're developing a Next.js/Remix project in development mode. But if you are shipping to your end-users, then you need to set config.state, otherwise your project's state will be empty and nothing will animate. Learn more at https://unseen-theatre.netlify.app/docs/guide/manual/projects#state"
           );
         }
       } else {
         setTimeout(() => {
           if (!this._studio) {
             throw new Error(
-              'Argument config.state in Theatre.getProject("'.concat(id, '", config) is empty. This is fine ') + "while you are using @unseenco/theatre-core along with @unseenco/theatre-studio. But since @unseenco/theatre-studio " + 'is not loaded, the state of project "'.concat(id, '" will be empty.\n\n') + "To fix this, you need to add @unseenco/theatre-studio into the bundle and export the project's state. Learn how to do that at https://www.theatrejs.com/docs/latest/manual/projects#state\n"
+              'Argument config.state in Theatre.getProject("'.concat(id, '", config) is empty. This is fine ') + "while you are using @unseenco/theatre-core along with @unseenco/theatre-studio. But since @unseenco/theatre-studio " + 'is not loaded, the state of project "'.concat(id, '" will be empty.\n\n') + "To fix this, you need to add @unseenco/theatre-studio into the bundle and export the project's state. Learn how to do that at https://unseen-theatre.netlify.app/docs/guide/manual/projects#state\n"
             );
           }
         }, 1e3);
@@ -8059,6 +8937,7 @@ var Project = class {
       template.setVisibleInOutline(opts.visible);
     }
     const sheet = template.getInstance(instanceId);
+    applySheetRuntimeOptions(sheet, opts);
     this._remoteSync.registerSheet(sheet);
     return sheet;
   }
@@ -8339,13 +9218,13 @@ var Project = class {
 };
 
 // shared/src/utils/sanitizers.ts
-var _validateSym = (val11, thingy, range) => {
-  if (typeof val11 !== "string") {
-    return "".concat(thingy, " must be a string. ").concat(userReadableTypeOfValue_default(val11), " given.");
-  } else if (val11.trim().length !== val11.length) {
-    return "".concat(thingy, " must not have leading or trailing spaces. '").concat(val11, "' given.");
-  } else if (val11.length < range[0] || val11.length > range[1]) {
-    return "".concat(thingy, " must have between ").concat(range[0], " and ").concat(range[1], " characters. '").concat(val11, "' given.");
+var _validateSym = (val13, thingy, range) => {
+  if (typeof val13 !== "string") {
+    return "".concat(thingy, " must be a string. ").concat(userReadableTypeOfValue_default(val13), " given.");
+  } else if (val13.trim().length !== val13.length) {
+    return "".concat(thingy, " must not have leading or trailing spaces. '").concat(val13, "' given.");
+  } else if (val13.length < range[0] || val13.length > range[1]) {
+    return "".concat(thingy, " must have between ").concat(range[0], " and ").concat(range[1], " characters. '").concat(val13, "' given.");
   }
 };
 var validateName = (name, thingy, shouldThrow = false) => {
@@ -8462,7 +9341,61 @@ var TheatreProject = class {
 // core/src/coreExports.ts
 var import_fast_deep_equal3 = __toESM(require_fast_deep_equal());
 import { isPointer } from "@unseenco/theatre-dataverse";
-import { isPrism, pointerToPrism } from "@unseenco/theatre-dataverse";
+import { isPrism, pointerToPrism as pointerToPrism3 } from "@unseenco/theatre-dataverse";
+
+// core/src/sheets/theatrePageScroll.ts
+var pageScrollConfig = {};
+function buildPageScrollContextFromConfig() {
+  return {
+    scroller: pageScrollConfig.scroller ?? defaultPageScrollContext.scroller,
+    axis: pageScrollConfig.axis ?? defaultPageScrollContext.axis
+  };
+}
+function configureTheatrePageScroll(config) {
+  const prev = pageScrollConfig;
+  pageScrollConfig = {
+    scroller: config.scroller ?? prev.scroller,
+    axis: config.axis ?? prev.axis
+  };
+  if (config.scroller !== void 0 || config.axis !== void 0) {
+    setActivePageScrollContext(buildPageScrollContextFromConfig());
+  }
+  return {
+    reset() {
+      pageScrollConfig = prev;
+      setActivePageScrollContext(
+        prev.scroller !== void 0 || prev.axis !== void 0 ? {
+          scroller: prev.scroller ?? defaultPageScrollContext.scroller,
+          axis: prev.axis ?? defaultPageScrollContext.axis
+        } : defaultPageScrollContext
+      );
+    }
+  };
+}
+function getTheatrePageScrollConfig() {
+  return pageScrollConfig;
+}
+function getTheatrePageScrollContext() {
+  const ctx = buildPageScrollContextFromConfig();
+  setActivePageScrollContext(ctx);
+  return ctx;
+}
+function createDefaultPageScrollDriver(scroller = getTheatrePageScrollContext().scroller, axis = resolvePageScrollAxis(getTheatrePageScrollContext())) {
+  if (typeof document !== "undefined" && scroller != null && !isNativeDocumentScroller(scroller) && scroller instanceof HTMLElement) {
+    return axis === "horizontal" ? createElementHorizontalScrollDriver(scroller) : createElementScrollDriver(scroller);
+  }
+  return axis === "horizontal" ? createNativeDocumentHorizontalScrollDriver() : createNativeDocumentScrollDriver();
+}
+function attachTheatrePageScroll(sheet, options = {}) {
+  const ctx = getTheatrePageScrollContext();
+  const driver = options.driver ?? createDefaultPageScrollDriver(ctx.scroller, resolvePageScrollAxis(ctx));
+  sheet.setPageScrollDriver(driver);
+  return () => {
+    sheet.setPageScrollDriver(void 0);
+  };
+}
+
+// core/src/coreExports.ts
 function getProject(id, config = {}) {
   const existingProject = projectsSingleton_default.get(id);
   if (existingProject) {
@@ -8503,7 +9436,7 @@ var shallowValidateOnDiskState = (projectId, s2) => {
     throw new InvalidArgumentError(
       "Error validating conf.state in Theatre.getProject(".concat(JSON.stringify(
         projectId
-      ), ", conf). The state seems to be formatted in a way that is unreadable to Theatre.js. Read more at https://www.theatrejs.com/docs/latest/manual/projects#state")
+      ), ", conf). The state seems to be formatted in a way that is unreadable to Theatre.js. Read more at https://unseen-theatre.netlify.app/docs/guide/manual/projects#state")
     );
   }
 };
@@ -8543,7 +9476,7 @@ var validateProjectIdOrThrow = (value) => {
 function onChange(pointer3, callback, rafDriver) {
   const ticker = rafDriver ? privateAPI(rafDriver).ticker : getCoreTicker();
   if (isPointer(pointer3)) {
-    const pr = pointerToPrism(pointer3);
+    const pr = pointerToPrism3(pointer3);
     return pr.onChange(ticker, callback, true);
   } else if (isPrism(pointer3)) {
     return pointer3.onChange(ticker, callback, true);
@@ -8553,9 +9486,9 @@ function onChange(pointer3, callback, rafDriver) {
     );
   }
 }
-function val10(pointer3) {
+function val12(pointer3) {
   if (isPointer(pointer3)) {
-    return pointerToPrism(pointer3).getValue();
+    return pointerToPrism3(pointer3).getValue();
   } else {
     throw new Error("Called val(p) where p is not a pointer.");
   }
@@ -8570,7 +9503,7 @@ var CoreBundle = class {
     return "Theatre_CoreBundle";
   }
   get version() {
-    return "0.4.2";
+    return "0.5.0";
   }
   getBitsForStudio(studio, callback) {
     if (this._studio) {
@@ -8619,16 +9552,44 @@ function registerCoreBundle() {
   }
 }
 export {
+  PAGE_MODE_SEQUENCE_LENGTH,
+  PAGE_MODE_SUB_UNITS_PER_UNIT,
+  attachGsapSequenceBridge,
+  attachSheetScrollDriver,
+  attachTheatrePageScroll,
+  configureTheatrePageScroll,
+  createDefaultPageScrollDriver,
+  createElementHorizontalScrollDriver,
+  createElementScrollDriver,
+  createNativeDocumentHorizontalScrollDriver,
+  createNativeDocumentScrollDriver,
   createRafDriver,
+  defaultPageScrollContext,
+  getActivePageScrollContext,
   getProject,
+  getSheetScrollDriver,
+  getTheatreCoreRafDriver,
+  getTheatrePageScrollConfig,
+  getTheatrePageScrollContext,
+  isNativeDocumentScroller,
+  isPageScrollTrigger,
   isRemoteEditorWindow,
+  isVerticalPageScrollTrigger,
   notify,
   onChange,
+  pageScrollProgressFromSequence,
+  pageScrollScrollersMatch,
   privateAPI,
+  resolvePageScrollAxis,
+  resolvePageScrollScroller,
+  setActivePageScrollContext,
   setCoreRafDriver,
+  setPageScrollProgress,
   setPrivateAPI,
+  syncNativeDocumentScrollToSequencePosition,
+  syncPageScrollToSequencePosition,
   propTypes_exports as types,
-  val10 as val
+  val12 as val
 };
 /*! Bundled license information: