@unseenco/theatre-core 0.4.3 → 0.5.0

package/dist/index.d.ts

@@ -782,6 +782,40 @@ type TransientPropPath = string | readonly (string | number)[];
 /** Same path format as {@link TransientPropPath}. */
 type StaticPropPath = TransientPropPath;
 
+/** How the sheet sequence maps to the sequencer UI and playback driver. */
+type SheetSequenceMode = 'time' | 'page';
+/** Fixed sequence length in page mode (= 100% scroll range). */
+declare const PAGE_MODE_SEQUENCE_LENGTH = 100;
+/** Sub-units per unit in page mode: 10 → 0.1% snap steps. */
+declare const PAGE_MODE_SUB_UNITS_PER_UNIT = 10;
+
+/** Maps page scroll progress (0–1) to sequence position and back. */
+type ScrollDriver = {
+    getProgress(): number;
+    setProgress(progress: number): void;
+    subscribe(onChange: (progress: number) => void): () => void;
+};
+declare function getSheetScrollDriver(sheet: ISheet): ScrollDriver | undefined;
+/** Native `window` / `documentElement` vertical scroll. */
+declare function createNativeDocumentScrollDriver(): ScrollDriver;
+/** Native `window` / `documentElement` horizontal scroll. */
+declare function createNativeDocumentHorizontalScrollDriver(): ScrollDriver;
+/** Vertical scroll on a custom overflow element. */
+declare function createElementScrollDriver(element: HTMLElement): ScrollDriver;
+/** Horizontal scroll on a custom overflow element. */
+declare function createElementHorizontalScrollDriver(element: HTMLElement): ScrollDriver;
+/**
+ * Keeps `sheet.sequence.position` aligned with scroll progress in page mode.
+ * Progress maps to `[0, sequence.length]` (length is 100 in page mode).
+ */
+declare function attachSheetScrollDriver(sheet: ISheet, driver?: ScrollDriver): () => void;
+declare function pageScrollProgressFromSequence(sheet: ISheet): number;
+declare function setPageScrollProgress(sheet: ISheet, progress: number): void;
+/** Scroll to match the current sequence playhead using the sheet's active driver. */
+declare function syncPageScrollToSequencePosition(sheet: ISheet, driver?: ScrollDriver): void;
+/** Scroll the native document to match the current sequence playhead (page mode UI). */
+declare function syncNativeDocumentScrollToSequencePosition(sheet: ISheet): void;
+
 /** Public API for a custom requestAnimationFrame driver that advances Theatre's core ticker. */
 interface IRafDriver {
     /**
@@ -950,7 +984,7 @@ interface ISheetObject<Props extends UnknownShorthandCompoundProps = UnknownShor
      * Calls `fn` every time the value of the props change.
      *
      * @param fn - The callback is called every time the value of the props change, plus once at the beginning.
-     * @param rafDriver - (optional) The `rafDriver` to use. Learn how to use `rafDriver`s [from the docs](https://www.theatrejs.com/docs/latest/manual/advanced#rafdrivers).
+     * @param rafDriver - (optional) The `rafDriver` to use. Learn how to use `rafDriver`s [from the docs](https://unseen-theatre.netlify.app/docs/guide/manual/advanced#rafdrivers).
      * @returns an Unsubscribe function
      *
      * @example
@@ -1130,7 +1164,7 @@ interface ISequence {
         /**
          * Optionally provide a rafDriver to use for the playback. It'll default to
          * the core driver if not provided, which is a `requestAnimationFrame()` driver.
-         * Learn how to use `rafDriver`s [from the docs](https://www.theatrejs.com/docs/latest/manual/advanced#rafdrivers).
+         * Learn how to use `rafDriver`s [from the docs](https://unseen-theatre.netlify.app/docs/guide/manual/advanced#rafdrivers).
          */
         rafDriver?: IRafDriver;
     }): Promise<boolean>;
@@ -1200,13 +1234,30 @@ interface ISequence {
         trackId: SequenceTrackId;
         clip: GsapClipTrack;
     }>;
+    /**
+     * Runtime ScrollTrigger registrations for page-mode visualization (read-only in Studio).
+     *
+     * @experimental
+     */
+    __experimental_getGsapScrollTriggers(): Array<{
+        objectKey: string;
+        scrollTriggerId: string;
+        label: string;
+        layout: {
+            start: number;
+            duration: number;
+        };
+        kind: 'tween' | 'timeline';
+        animationSpanSeconds: number;
+        timelineChildren: GsapTimelineChildClip[];
+    }>;
     /**
      * Attaches an audio source to the sequence. Playing the sequence automatically
      * plays the audio source and their times are kept in sync.
      *
      * @returns A promise that resolves once the audio source is loaded and decoded
      *
-     * Learn more [here](https://www.theatrejs.com/docs/latest/manual/audio).
+     * Learn more [here](https://unseen-theatre.netlify.app/docs/guide/manual/audio).
      *
      * @example
      * Usage:
@@ -1346,7 +1397,7 @@ interface ISheet {
     /**
      * Creates a child object for the sheet
      *
-     * **Docs: https://www.theatrejs.com/docs/latest/manual/objects**
+     * **Docs: https://unseen-theatre.netlify.app/docs/guide/manual/objects**
      *
      * @param key - Each object is identified by a key, which is a non-empty string
      * @param props - The props of the object. See examples
@@ -1517,6 +1568,21 @@ interface ISheet {
      * Returns the currently active sequence variant name.
      */
     getActiveSequenceVariant(): SequenceVariantId;
+    /**
+     * Whether the sequence uses wall-clock time (default) or page-scroll percent units.
+     * Page mode is runtime-only and not persisted in project state.
+     */
+    getSequenceMode(): 'time' | 'page';
+    /**
+     * Switches sequence units: `time` (seconds) or `page` (0–100 = scroll percent).
+     * In page mode, length is fixed at 100 and snap grid uses 0.1% steps.
+     */
+    setSequenceMode(mode: 'time' | 'page'): void;
+    /**
+     * Overrides the scroll driver used in page mode (e.g. Lenis). Pass `undefined` to
+     * restore native document scroll. Re-attaches the scroll → playhead listener.
+     */
+    setPageScrollDriver(driver: ScrollDriver | undefined): void;
 }
 
 /**
@@ -1527,11 +1593,28 @@ type ISheetOptions = {
      * Whether the sheet appears in the Studio outline panel. Defaults to `true`.
      */
     visible?: boolean;
+    /**
+     * How the sheet sequence maps to the sequencer UI and playback driver.
+     * In **`page`** mode the sequence length is fixed at **100** (percent scroll) with **0.1%** snap steps;
+     * native document scroll keeps the playhead in sync.
+     *
+     * @defaultValue `'time'`
+     */
+    sequenceMode?: SheetSequenceMode;
+    /**
+     * When `true`, enables the GSAP sequence bridge for this sheet (required for `@unseenco/theatre-gsap`).
+     */
+    gsap?: boolean;
+    /**
+     * Custom scroll driver for **`page`** mode (Lenis, overflow element, etc.).
+     * When omitted in page mode, native document scroll is used.
+     */
+    scrollDriver?: ScrollDriver;
 };
 /** Options passed to {@link getProject} when creating or attaching to a project. */
 type IProjectConfig = {
     /**
-     * The state of the project, as [exported](https://www.theatrejs.com/docs/latest/manual/projects#state) by the studio.
+     * The state of the project, as [exported](https://unseen-theatre.netlify.app/docs/guide/manual/projects#state) by the studio.
      */
     state?: $IntentionalAny;
     assets?: {
@@ -1571,11 +1654,11 @@ interface IProject {
     /**
      * Creates a Sheet under the project
      * @param sheetId - Sheets are identified by their `sheetId`, which must be a string longer than 3 characters
-     * @param instanceIdOrOpts - Optionally provide an `instanceId` if you want to create multiple instances of the same Sheet, or pass `{ visible: false }` to hide the sheet from the Studio outline panel
-     * @param opts - Optionally provide `{ visible: false }` to hide the sheet from the Studio outline panel
+     * @param instanceIdOrOpts - Optionally provide an `instanceId`, or pass sheet options (e.g. `{ sequenceMode: 'page', gsap: true }`)
+     * @param opts - Sheet options such as `{ visible: false }`, `sequenceMode`, or `gsap`
      * @returns The newly created Sheet
      *
-     * **Docs: https://www.theatrejs.com/docs/latest/manual/sheets**
+     * **Docs: https://unseen-theatre.netlify.app/docs/guide/manual/sheets**
      */
     sheet(sheetId: string, instanceIdOrOpts?: string | ISheetOptions): ISheet;
     /**
@@ -1583,7 +1666,7 @@ interface IProject {
      *
      * @param sheetId - Sheets are identified by their `sheetId`, which must be a string longer than 3 characters
      * @param instanceId - Instance id when creating multiple instances of the same sheet
-     * @param opts - Optionally provide `{ visible: false }` to hide the sheet from the Studio outline panel
+     * @param opts - Sheet options such as `{ visible: false }`, `sequenceMode`, or `gsap`
      * @returns The newly created Sheet
      */
     sheet(sheetId: string, instanceId: string, opts?: ISheetOptions): ISheet;
@@ -1712,13 +1795,57 @@ declare function isRemoteEditorWindow(): boolean;
  */
 declare function attachGsapSequenceBridge(sheet: ISheet): () => void;
 
+/** `null` = native document scroll (window / documentElement). */
+type PageScrollScroller = Window | Element | null;
+type PageScrollAxis = 'vertical' | 'horizontal';
+type PageScrollContext = {
+    scroller: PageScrollScroller;
+    /** Scroll axis for page mode and ScrollTrigger registration (default vertical). */
+    axis?: PageScrollAxis;
+};
+declare const defaultPageScrollContext: PageScrollContext;
+declare function setActivePageScrollContext(context: PageScrollContext): void;
+declare function getActivePageScrollContext(): PageScrollContext;
+declare function resolvePageScrollAxis(context?: PageScrollContext): PageScrollAxis;
+declare function resolvePageScrollScroller(st: unknown, defaultsScroller?: PageScrollScroller): PageScrollScroller;
+declare function isNativeDocumentScroller(scroller: PageScrollScroller): boolean;
+/** Same scroller target for page-mode scroll registration (reference equality or both native doc). */
+declare function pageScrollScrollersMatch(a: PageScrollScroller, b: PageScrollScroller): boolean;
+/**
+ * True when ST scroller and horizontal flag match the configured page scroll context.
+ */
+declare function isPageScrollTrigger(st: unknown, context?: PageScrollContext): boolean;
+declare function isVerticalPageScrollTrigger(st: unknown, context?: PageScrollContext): boolean;
+
+type TheatrePageScrollConfig = {
+    /** Default scroller for page-mode layout helpers; `null` = native document. */
+    scroller?: PageScrollScroller;
+    /** Scroll axis (default vertical). */
+    axis?: PageScrollAxis;
+};
+declare function configureTheatrePageScroll(config: TheatrePageScrollConfig): {
+    reset: () => void;
+};
+declare function getTheatrePageScrollConfig(): TheatrePageScrollConfig;
+/** Active page scroll context from {@link configureTheatrePageScroll}. */
+declare function getTheatrePageScrollContext(): PageScrollContext;
+declare function createDefaultPageScrollDriver(scroller?: PageScrollScroller, axis?: PageScrollAxis): ScrollDriver;
+type AttachTheatrePageScrollOptions = {
+    driver?: ScrollDriver;
+};
+/**
+ * Wires page-mode scroll → sequence sync using {@link configureTheatrePageScroll}
+ * or an explicit driver (Lenis, overflow containers, etc.).
+ */
+declare function attachTheatrePageScroll(sheet: ISheet, options?: AttachTheatrePageScrollOptions): () => void;
+
 /**
  * Returns a project of the given id, or creates one if it doesn't already exist.
  *
  * @remarks
  * If \@unseenco/theatre-studio is also loaded, then the state of the project will be managed by the studio.
  *
- * [Learn more about exporting](https://www.theatrejs.com/docs/latest/manual/projects#state)
+ * [Learn more about exporting](https://unseen-theatre.netlify.app/docs/guide/manual/projects#state)
  *
  * @example
  * Usage:
@@ -1743,7 +1870,7 @@ declare function getProject(id: string, config?: IProjectConfig): IProject;
  *
  * @param pointer - A Pointer (like `object.props.x`)
  * @param callback - The callback is called every time the value of pointer changes
- * @param rafDriver - (optional) The `rafDriver` to use. Learn how to use `rafDriver`s [from the docs](https://www.theatrejs.com/docs/latest/manual/advanced#rafdrivers).
+ * @param rafDriver - (optional) The `rafDriver` to use. Learn how to use `rafDriver`s [from the docs](https://unseen-theatre.netlify.app/docs/guide/manual/advanced#rafdrivers).
  * @returns An unsubscribe function
  *
  * @example
@@ -1797,4 +1924,4 @@ declare function val<T>(pointer: PointerType<T>): T;
  */
 type __UNSTABLE_Project_OnDiskState = OnDiskState;
 
-export { IProject, IProjectConfig, IRafDriver, ISequence, ISheet, ISheetObject, ISheetObjectOptions, ISheetOptions, UnknownShorthandCompoundProps, __UNSTABLE_Project_OnDiskState, attachGsapSequenceBridge, createRafDriver, getProject, isRemoteEditorWindow, notify, onChange, setCoreRafDriver, index_d as types, val };
+export { AttachTheatrePageScrollOptions, IProject, IProjectConfig, IRafDriver, ISequence, ISheet, ISheetObject, ISheetObjectOptions, ISheetOptions, PAGE_MODE_SEQUENCE_LENGTH, PAGE_MODE_SUB_UNITS_PER_UNIT, PageScrollAxis, PageScrollContext, PageScrollScroller, ScrollDriver, SheetSequenceMode, TheatrePageScrollConfig, UnknownShorthandCompoundProps, __UNSTABLE_Project_OnDiskState, attachGsapSequenceBridge, attachSheetScrollDriver, attachTheatrePageScroll, configureTheatrePageScroll, createDefaultPageScrollDriver, createElementHorizontalScrollDriver, createElementScrollDriver, createNativeDocumentHorizontalScrollDriver, createNativeDocumentScrollDriver, createRafDriver, defaultPageScrollContext, getActivePageScrollContext, getProject, getSheetScrollDriver, getTheatrePageScrollConfig, getTheatrePageScrollContext, isNativeDocumentScroller, isPageScrollTrigger, isRemoteEditorWindow, isVerticalPageScrollTrigger, notify, onChange, pageScrollProgressFromSequence, pageScrollScrollersMatch, resolvePageScrollAxis, resolvePageScrollScroller, setActivePageScrollContext, setCoreRafDriver, setPageScrollProgress, syncNativeDocumentScrollToSequencePosition, syncPageScrollToSequencePosition, index_d as types, val };