@needle-tools/engine 5.1.0-alpha.8 → 5.1.0-beta

package/src/engine-components/web/ScrollFollow.ts

@@ -1,12 +1,43 @@
 // For firefox ViewTimeline support — dynamic import to avoid SSR crashes (polyfill accesses window at module level)
 if (typeof window !== "undefined") import("scroll-timeline-polyfill/dist/scroll-timeline.js");
 
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// NOTE / TODO — ScrollMarker tracking vs. the parent window (useTopWindowScroll)
+//
+// The ScrollMarker feature (see handleTimelineTarget) currently relies on `ViewTimeline` to know
+// how far a marker element has travelled through the viewport. This import polyfills `ViewTimeline`
+// on THIS window only — it never patches the parent/top window. So when `useTopWindowScroll` is on
+// and we resolve markers against the host page (top document), tracking only works if the *host*
+// window also has `ViewTimeline`:
+//   - Chromium host (native ViewTimeline) ............. works
+//   - Firefox/Safari host without the polyfill ........ does NOT work → falls back to linear scroll
+//   - cross-origin host ............................... impossible (no access to top.document at all)
+// We cannot reliably install the polyfill onto a (same-origin) parent from inside the iframe — it is
+// designed to patch its own realm at import time, and doing it cross-realm is fragile.
+//
+// POSSIBLE CHANGE: drop `ViewTimeline` entirely and compute the marker's viewport progress manually
+// with getBoundingClientRect, e.g. for the default "cover 0%→100%" range:
+//     const rect = el.getBoundingClientRect();
+//     const vh   = scroller.clientHeight;              // top's viewport when useTopWindowScroll
+//     const t01  = (vh - rect.top) / (vh + rect.height);
+// This is mathematically equivalent to the current ViewTimeline values (0 = entering from bottom,
+// 0.5 = centered, 1 = exited past top — matches the existing `1 - |t-0.5|*2` weighting).
+//   PROS: works with top/parent content in every browser (same-origin); removes the
+//         scroll-timeline-polyfill dependency and this SSR-risky top-level import; cheaper
+//         (no ViewTimeline objects / WeakMap per marker). `ViewTimeline` is used ONLY in this file.
+//   CONS: re-implements view-progress ourselves instead of leaning on the platform/polyfill, so any
+//         future spec range features (cover/contain/entry/exit, named ranges) would have to be
+//         reproduced by hand; needs careful re-testing against the existing scrollytelling demos.
+//   NOTE: cross-origin embeds still cannot work either way — that needs a postMessage scroll bridge.
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
 import { Box3, Object3D } from "three";
 
 import { isDevEnvironment } from "../../engine/debug/debug.js";
 import { Mathf } from "../../engine/engine_math.js";
 import { serializable } from "../../engine/engine_serialization.js";
 import { getBoundingBox, setVisibleInCustomShadowRendering } from "../../engine/engine_three_utils.js";
+import { validate } from "../../engine/engine_util_decorator.js";
 import { getParam } from "../../engine/engine_utils.js";
 import { Animation } from "../Animation.js";
 import { Animator } from "../Animator.js";
@@ -115,6 +146,25 @@ export class ScrollFollow extends Behaviour {
     @serializable()
     mode: "window" = "window";
 
+    /**
+     * Read the scroll position from the **top-level window** instead of the window Needle Engine
+     * runs in. This matters when the canvas is embedded in an iframe:
+     * - When the page is **not** embedded this has no effect — the top window *is* the current window.
+     * - When embedded in a **same-origin** iframe, the component follows the *host page's* scroll,
+     *   which is almost always the intent (an embedded iframe usually isn't scrollable itself).
+     *
+     * Set this to `false` to always follow the engine's own window scroll, e.g. when the iframe
+     * itself is scrollable and you want to follow its own scroll rather than the host's.
+     *
+     * If the top window is **cross-origin** (and therefore inaccessible), the component
+     * transparently falls back to the local window and logs a warning in development —
+     * cross-origin embeds would require a `postMessage` scroll bridge from the host page.
+     * @default true
+     */
+    @validate()
+    @serializable()
+    useTopWindowScroll: boolean = true;
+
     /**
      * Event fired when the scroll position changes
      */
@@ -134,6 +184,13 @@ export class ScrollFollow extends Behaviour {
     private _needsUpdate = false;
     private _firstUpdate = false;
 
+    /** The window whose scroll position currently drives this component (resolved from {@link useTopWindowScroll}). */
+    private _scrollWindow: Window | null = null;
+    /** The window the `wheel` listener is attached to — kept so we remove it from the same window. */
+    private _wheelTarget: Window | null = null;
+    private _crossOriginWarned = false;
+    private _viewTimelineWarned = false;
+
     awake() {
         this._firstUpdate = true;
     }
@@ -141,14 +198,70 @@ export class ScrollFollow extends Behaviour {
 
     /** @internal */
     onEnable() {
-        window.addEventListener("wheel", this.updateCurrentScrollValue, { passive: true });
+        this.rebindScrollListener();
         this._appliedValue = -1;
         this._needsUpdate = true;
     }
 
     /** @internal */
     onDisable() {
-        window.removeEventListener("wheel", this.updateCurrentScrollValue);
+        this._wheelTarget?.removeEventListener("wheel", this.updateCurrentScrollValue);
+        this._wheelTarget = null;
+    }
+
+    /** @internal */
+    onValidate(property?: string) {
+        // React to a runtime change of `useTopWindowScroll` while the component is active.
+        if (property === "useTopWindowScroll" && this._wheelTarget) {
+            this.rebindScrollListener();
+            this._needsUpdate = true;
+        }
+    }
+
+    /**
+     * Resolves which browsing context's scroll position should drive this component.
+     * Honors {@link useTopWindowScroll}. When the top window is requested but is cross-origin
+     * (and therefore inaccessible) it falls back to the local window and warns once —
+     * cross-origin embeds would need a `postMessage` scroll bridge from the host page.
+     */
+    private resolveScrollWindow(): Window {
+        if (!this.useTopWindowScroll) return window;
+        const top = window.top;
+        // Not embedded, or we already *are* the top window.
+        if (!top || top === window.self) return window;
+        try {
+            // Any property access on a cross-origin top window throws a SecurityError.
+            void top.document;
+            return top;
+        }
+        catch (_e) {
+            if (!this._crossOriginWarned) {
+                this._crossOriginWarned = true;
+                if (debug || isDevEnvironment()) {
+                    console.warn("[ScrollFollow] useTopWindowScroll is enabled but the top-level window is cross-origin and cannot be read. Falling back to the local window. Supporting cross-origin embeds requires a postMessage scroll bridge from the host page.");
+                }
+            }
+            return window;
+        }
+    }
+
+    /** (Re)resolves the scroll window and moves the `wheel` listener onto it. */
+    private rebindScrollListener() {
+        const next = this.resolveScrollWindow();
+        this._scrollWindow = next;
+        if (next === this._wheelTarget) return;
+        this._wheelTarget?.removeEventListener("wheel", this.updateCurrentScrollValue);
+        this._wheelTarget = next;
+        next.addEventListener("wheel", this.updateCurrentScrollValue, { passive: true });
+        // The selector cache may point into the previous document — invalidate it.
+        this._lastSelectorValue = null;
+        this._lastSelectorElement = null;
+        if(debug) {
+            console.debug(`[ScrollFollow] Scroll listener bound to ${next === window ? "local window" : "top-level window"}`, {
+                scrollWindow: this._scrollWindow,
+                isTopWindow: next === window,
+            });
+        }
     }
 
     /** @internal */
@@ -214,26 +327,34 @@ export class ScrollFollow extends Behaviour {
 
     private updateCurrentScrollValue = () => {
 
+        const win = this._scrollWindow ?? window;
+        const doc = win.document;
+        // The page's scrollable extent lives on the root scrolling element (documentElement in
+        // standards mode, body in quirks mode) — document.body.scrollHeight is unreliable and is
+        // often just the viewport height even when the page is scrolled. scrollingElement resolves
+        // to the correct one for the current document mode.
+        const scroller = doc.scrollingElement ?? doc.documentElement;
+
         switch (this.mode) {
             case "window":
                 if (this.htmlSelector?.length) {
                     if (this.htmlSelector !== this._lastSelectorValue) {
-                        this._lastSelectorElement = document.querySelector(this.htmlSelector);
+                        this._lastSelectorElement = doc.querySelector(this.htmlSelector);
                         this._lastSelectorValue = this.htmlSelector;
                     }
                     if (this._lastSelectorElement) {
                         const rect = this._lastSelectorElement.getBoundingClientRect();
-                        this._target_value = -rect.top / (rect.height - window.innerHeight);
+                        this._target_value = -rect.top / (rect.height - win.innerHeight);
                         break;
                     }
                 }
                 else {
-                    if (window.document.body.scrollHeight <= window.innerHeight) {
-                        // If the page is not scrollable we can still increment the scroll value to allow triggering timelines etc.
+                    const maxScroll = scroller.scrollHeight - scroller.clientHeight;
+                    if (maxScroll <= 0) {
+                        // Page is not scrollable — keep the current value (still allows triggering timelines etc.).
                     }
                     else {
-                        const diff = window.document.body.scrollHeight - window.innerHeight;
-                        this._target_value = window.scrollY / (diff || 1);
+                        this._target_value = scroller.scrollTop / maxScroll;
                     }
                 }
 
@@ -241,6 +362,10 @@ export class ScrollFollow extends Behaviour {
         }
 
         if (isNaN(this._target_value) || !isFinite(this._target_value)) this._target_value = -1;
+
+        if (debug) {
+            console.debug(`[ScrollFollow] Scroll value updated: ${this._target_value.toFixed(5)} (ScrollTop: ${scroller.scrollTop}, ScrollHeight: ${scroller.scrollHeight}, ClientHeight: ${scroller.clientHeight})`);
+        }
     }
 
 
@@ -295,6 +420,10 @@ export class ScrollFollow extends Behaviour {
 
     private handleTimelineTarget(director: PlayableDirector, value: number) {
 
+        // Resolve markers against the same browsing context we read scroll from (see useTopWindowScroll).
+        const scrollWin = this._scrollWindow ?? window;
+        const doc = scrollWin.document;
+
         const duration = director.duration;
         let markersArray = timelineMarkerArrays.get(director);
 
@@ -314,7 +443,7 @@ export class ScrollFollow extends Behaviour {
                     marker.needsUpdate = false;
                     try {
                         // TODO: with this it's currently not possible to remap markers from HTML. For example if I have two sections and I want to now use the marker["center"] multiple times to stay at that marker for a longer time
-                        marker.element = tryGetElementsForSelector(index) as HTMLElement | null;
+                        marker.element = tryGetElementsForSelector(index, doc) as HTMLElement | null;
                         if (debug) console.debug(`ScrollMarker #${index} (${marker.time.toFixed(2)}) found`, marker.element);
                         if (!marker.element) {
                             if (debug || isDevEnvironment()) console.warn(`No HTML element found for ScrollMarker: ${marker.name} (index ${index})`);
@@ -335,7 +464,7 @@ export class ScrollFollow extends Behaviour {
 
             // If the timeline has no markers defined we can use timeline-marker elements in the DOM. These must define times then
             if (markersArray.length <= 0) {
-                const markers = document.querySelectorAll(`[data-timeline-marker]`);
+                const markers = doc.querySelectorAll(`[data-timeline-marker]`);
                 markers.forEach((element) => {
                     const value = element.getAttribute("data-timeline-marker");
                     const time = parseFloat(value || ("NaN"));
@@ -351,15 +480,32 @@ export class ScrollFollow extends Behaviour {
                 });
             }
 
-            // Init ViewTimeline for markers
-            for (const marker of markersArray) {
-                if (marker.element) {
-                    // https://scroll-driven-animations.style/tools/view-timeline/ranges
-                    /** @ts-ignore */
-                    marker.timeline = new ViewTimeline({
-                        subject: marker.element,
-                        axis: 'block', // https://drafts.csswg.org/scroll-animations/#scroll-notation
-                    });
+            // Init ViewTimeline for markers. Use the constructor from the *owning* window so that
+            // markers living in a same-origin host page (useTopWindowScroll) are tracked in the
+            // correct realm rather than against the iframe's own (non-scrolling) document.
+            const ViewTimelineCtor = (scrollWin as unknown as { ViewTimeline?: new (opts: { subject: Element, axis: string }) => ViewTimeline }).ViewTimeline;
+            if (!ViewTimelineCtor) {
+                // ViewTimeline isn't available on the target window yet. This is expected transiently
+                // on the "self" path while the async scroll-timeline polyfill is still loading, and
+                // permanently when useTopWindowScroll targets a host page without ViewTimeline support.
+                // Don't persist the half-built marker set — drop the cache so it's rebuilt next frame
+                // (self-heals once the polyfill loads), and fall back to linear scrubbing for now.
+                if (!this._viewTimelineWarned && (debug || isDevEnvironment())) {
+                    this._viewTimelineWarned = true;
+                    console.warn("[ScrollFollow] ViewTimeline is not available on the target window — falling back to linear scroll. If this persists with useTopWindowScroll, the scroll-timeline polyfill must be present on the host page.");
+                }
+                timelineMarkerArrays.delete(director);
+                markersArray.length = 0;
+            }
+            else {
+                for (const marker of markersArray) {
+                    if (marker.element) {
+                        // https://scroll-driven-animations.style/tools/view-timeline/ranges
+                        marker.timeline = new ViewTimelineCtor({
+                            subject: marker.element,
+                            axis: 'block', // https://drafts.csswg.org/scroll-animations/#scroll-notation
+                        });
+                    }
                 }
             }
         }
@@ -473,7 +619,7 @@ const weightsArray: OverlapInfo[] = [];
 const needleScrollMarkerCache = new Array<Element>();
 let needsScrollMarkerRefresh = true;
 
-function tryGetElementsForSelector(index: number): Element | null {
+function tryGetElementsForSelector(index: number, doc: Document): Element | null {
 
     if (!needsScrollMarkerRefresh) {
         const element = needleScrollMarkerCache[index] || null;
@@ -481,12 +627,12 @@ function tryGetElementsForSelector(index: number): Element | null {
     }
     needsScrollMarkerRefresh = false;
     needleScrollMarkerCache.length = 0;
-    const markers = document.querySelectorAll(`[data-timeline-marker]`);
+    const markers = doc.querySelectorAll(`[data-timeline-marker]`);
     markers.forEach((m, i) => {
         needleScrollMarkerCache[i] = m;
     });
     needsScrollMarkerRefresh = false;
-    return tryGetElementsForSelector(index);
+    return tryGetElementsForSelector(index, doc);
 }