upwwwards 0.1.6-beta.1 → 0.1.8-beta.1

package/dist/{Thread-Cvf__-O4.d.ts → Thread-5NGNyOJb.d.ts}

@@ -8,13 +8,14 @@ declare namespace CallStack {
     type CALLBACK = (...args: any) => void;
 }
 /**
-    * Callstack: an ordered list of synchronous callbacks that are invoked together, in insertion order,
-    * with the same arguments (similar to a lightweight event emitter for a single event).
+    * Ordered list of synchronous callbacks invoked together, in insertion order, with the same arguments
+    * (a lightweight single-event emitter).
     *
-    * Callbacks run either all at once with `loop`, or one at a time with `gen`, which returns a generator
-    * that pauses after each callback (used by the frame scheduler `Thread` to spread work across frames).
-    * Callbacks may be added or removed while the stack is being iterated: removals are applied immediately
-    * without skipping the next callback, and additions only run from the next iteration.
+    * Run them all at once with {@link CallStack.loop}, or one-by-one with {@link CallStack.gen} (yields after each
+    * callback so a caller such as `Up.Thread` can spread work across frames).
+    * You may {@link CallStack.add}, {@link CallStack.remove}, or {@link CallStack.clear} while an iteration is running:
+    * removals apply immediately without skipping the next callback, additions run from the next iteration,
+    * and `clear` skips any callback that has not run yet.
     *
     * If a callback throws, the error is logged with `Logs.error` and the remaining callbacks of that
     * iteration are skipped; the error is not rethrown.
@@ -93,6 +94,12 @@ declare class CallStack<T extends CallStack.CALLBACK> {
         * ```
     */
     gen(...args: Parameters<T>): Thread.GENERATOR;
+    /**
+        * Removes every callback and resets iteration counters (`length` becomes `0`).
+        * Safe to call during {@link CallStack.loop} / {@link CallStack.gen}: callbacks that have not run yet are skipped.
+        * When no iteration is in progress, any outstanding generator created by {@link CallStack.gen} is closed.
+    */
+    clear(): void;
 }
 
 declare namespace Arrays {
@@ -294,16 +301,6 @@ declare const
     * Key of the method returning the active cache (browser map or request-scoped server map).
 */
 getCache: unique symbol;
-declare const /**
-    * Key of the modifier refreshing viewport metrics.
-    * @internal
-*/
-updateScreenVars: unique symbol;
-declare const /**
-    * Key of the modifier refreshing scroll metrics.
-    * @internal
-*/
-updateScrollVars: unique symbol;
 declare namespace App {
     /**
         * Operating system / device family detected from `navigator.userAgent`.
@@ -332,8 +329,9 @@ declare namespace App {
 /**
     * Application runtime: device and browser detection, viewport and scroll metrics, an application cache,
     * and a wait queue that delays the `LOAD` event (see {@link Event}).
-    * @note Metrics are client-only. They are read once by `Up.set`, then refreshed by Thread modifiers before
-    * `resize` (flag `8`) and `scroll` (flag `32`) tasks run.
+    * @note Metrics are client-only. They are read once by `Up.set`, then refreshed by Thread modifiers on
+    * `resize` (flag `8`) and `scroll` (flag `32`) when those flags are armed ({@link Thread.sub} / {@link Thread.arm}).
+    * With the Scroll plugin, Lenis arms the scroll flag after writing `window.scrollY`.
 */
 declare abstract class App {
     #private;
@@ -489,15 +487,16 @@ declare abstract class App {
     */
     static remove(key: App.CACHE_KEY): boolean;
     /**
-        * Thread modifier refreshing viewport metrics (`w`, `cw`, `sw`, `lw`, `h`, `ch`, `sh`, `lh`).
-        * @internal
+        * Refreshes viewport metrics (`w`, `cw`, `sw`, `lw`, `h`, `ch`, `sh`, `lh`).
+        * Registered as a Thread modifier on {@link Thread.RESIZE_FLAG}; call it yourself only if you need an immediate read outside that phase.
     */
-    static [updateScreenVars](): void;
+    static updateScreenVars(): void;
     /**
-        * Thread modifier refreshing scroll metrics (`y`, `dY`, `downwards`).
-        * @internal
+        * Refreshes scroll metrics (`y`, `dY`, `downwards`) from `window.scrollY`.
+        * Registered as a Thread modifier on {@link Thread.RESIZE_FLAG} and {@link Thread.SCROLL_FLAG}; no-op when `y` is unchanged.
+        * Prefer letting Thread arm those flags (or the Scroll plugin) rather than calling this every frame by hand.
     */
-    static [updateScrollVars](): void;
+    static updateScrollVars(): void;
     /**
         * Clears the application cache and pending wait queue. Called from `Up.destroy` in the browser.
         * @internal
@@ -518,15 +517,15 @@ declare namespace Thread {
         * Thread scheduler configuration, declared in `up.thread` of the Vite initializer.
     */
     type CONFIG = {
-        /**
-            * Soft time budget in ms per frame for flow (one-shot) tasks. Must be greater than `0`. Default: `8`.
-        */
-        flowBudget?: number;
         /**
             * Soft time budget in ms per frame for forever tasks. Must be greater than `0`. Default: `4`.
             * Forever tasks always run every frame; the budget only limits how long their generators may run.
         */
         foreverBudget?: number;
+        /**
+            * Soft time budget in ms per frame for flow (one-shot) tasks. Must be greater than `0`. Default: `8`.
+        */
+        flowBudget?: number;
     };
     /**
         * Flag of `EARTHQUAKE` event tasks (`2`).
@@ -553,10 +552,20 @@ declare namespace Thread {
     */
     type SYNTHRA_FLAG = 2_048;
     /**
-        * Priority flag of a task or modifier: a power of 2 from `1` to `4096`.
-        * Within a frame, lower flags run first; tasks sharing a flag run in insertion order.
+        * Default flag of {@link Thread.sub} when `flag` is omitted (`8192`).
+        * Runs before {@link Thread.MAX_FLAG} (end-of-frame work such as Anime `updateRoot`).
+    */
+    type DEFAULT_FLAG = 8_192;
+    /**
+        * Highest allowed priority flag (`32768`). Reserved for end-of-frame work (e.g. Anime advances GSAP here).
+        * Not the default of {@link Thread.sub} — see {@link Thread.DEFAULT_FLAG}.
     */
-    type FLAG = 1 | EARTHQUAKE_FLAG | 4 | RESIZE_FLAG | 16 | SCROLL_FLAG | 64 | EVENT_FLAG | 256 | OBSERVER_FLAG | 1_024 | SYNTHRA_FLAG | 4_096;
+    type MAX_FLAG = 32_768;
+    /**
+        * Priority flag of a task or modifier: a power of 2 from `1` to {@link Thread.MAX_FLAG} (`32768`).
+        * Within a frame, lower flags run first; for each flag, forever tasks run before flow tasks.
+    */
+    type FLAG = 1 | EARTHQUAKE_FLAG | 4 | RESIZE_FLAG | 16 | SCROLL_FLAG | 64 | EVENT_FLAG | 256 | OBSERVER_FLAG | 1_024 | SYNTHRA_FLAG | 4_096 | DEFAULT_FLAG | 16_384 | MAX_FLAG;
     /**
         * Modifier callback. It is called without arguments and its return value is ignored.
     */
@@ -602,10 +611,12 @@ declare namespace Thread {
     ];
 }
 /**
-    * Frame scheduler of the runtime. Each frame (`requestAnimationFrame`, or an external ticker such as GSAP) runs, in order:
-    * modifiers, then flow tasks (run once, then removed), then forever tasks (run every frame).
-    * Work is grouped by priority flags (see {@link Thread.FLAG}) and limited by a soft time budget ({@link Thread.CONFIG});
-    * flow tasks that do not fit are postponed to the next frame, and generator tasks are resumed across frames.
+    * Frame scheduler of the runtime (`Up.Thread`). Each frame (`requestAnimationFrame`, or an external ticker such as GSAP)
+    * runs, in order: **drivers** → **modifiers** → **tasks by ascending flag** (forever then flow for each flag).
+    * Drivers (see {@link Thread.addDriver}) write frame inputs early (e.g. Lenis `raf`). Modifiers refresh shared data
+    * before tasks; arm them with {@link Thread.sub} or {@link Thread.arm}. Soft budgets ({@link Thread.CONFIG}) apply
+    * separately to forever and flow. Prefer `Up.Event.sub(['TICK', …])` for simple per-frame work; use Thread for
+    * budgets, priorities, drivers, or end-of-frame forever tasks on {@link Thread.MAX_FLAG}.
     * @note Client-only: the frame loop starts with `Up.set`. The Thread is paused while the page is hidden.
 */
 declare abstract class Thread {
@@ -632,10 +643,15 @@ declare abstract class Thread {
     */
     static get App(): typeof App;
     /**
-        * Highest allowed flag, also the default flag of {@link Thread.sub}.
-        * @returns `4096`.
+        * Default priority flag of {@link Thread.sub} when `flag` is omitted (`8192`).
+        * @returns `8192`.
     */
-    static get MAX_FLAG(): Thread.FLAG;
+    static get DEFAULT_FLAG(): Thread.DEFAULT_FLAG;
+    /**
+        * Highest allowed priority flag (`32768`). Use for end-of-frame forever work (e.g. Anime `gsap.updateRoot`).
+        * @returns `32768`.
+    */
+    static get MAX_FLAG(): Thread.MAX_FLAG;
     /**
         * Timestamp (ms) of the last processed frame, in the clock of the frame driver:
         * `requestAnimationFrame` time by default, or the external ticker time when one is attached (e.g. GSAP ticker time × `1000`).
@@ -662,16 +678,32 @@ declare abstract class Thread {
     */
     static [set](): void;
     /**
-        * Registers a modifier: a lightweight hook that refreshes shared data before tasks use it.
-        * After {@link Thread.sub} is called with the same `flag`, the modifier runs once at the start of the next processed frame,
-        * before any task (at most once per frame). Modifiers run by ascending flag, then in registration order.
-        * Registering the same callback twice on the same flag logs a warning and does nothing.
+        * Registers a **driver**: a sync callback run at the **start** of every processed frame, before modifiers and tasks.
+        * Use it for external clocks that write frame inputs (e.g. Scroll registers Lenis `raf` here with `autoRaf: false`).
+        * Callbacks run in registration order with no arguments; prefer sync functions. The same reference can be
+        * registered only once (a duplicate logs a warning and is ignored).
+        * @param callback Function called at the start of the frame (reads {@link Thread.timestamp} if needed).
+        * @example
+        * ```ts
+        * const step = (): void => { lenis.raf(Up.Thread.timestamp) }
+        *
+        * Up.Thread.addDriver(step)
+        * // later
+        * Up.Thread.removeDriver(step)
+        * ```
+    */
+    static addDriver(callback: Thread.CALLBACK): void;
+    /**
+        * Registers a modifier: a lightweight hook that refreshes shared data before tasks of the same `flag`.
+        * After {@link Thread.sub} or {@link Thread.arm} with that flag, the modifier runs once in the modifiers phase
+        * of the next processed frame (at most once per frame), before forever/flow tasks. Modifiers run by ascending
+        * flag, then in registration order. Registering the same callback twice on the same flag logs a warning.
         * @note Keep modifiers cheap: they may run on many frames.
         * @note The `App` metric modifiers (on {@link Thread.RESIZE_FLAG} and {@link Thread.SCROLL_FLAG}) are registered first,
         * so they run before user modifiers of the same flag.
         * @param callback Function called without arguments.
-        * @param flag Priority flag, a power of 2 from `1` to `4096`.
-        * @throws If `flag` is not a power of 2 between `1` and `4096`.
+        * @param flag Priority flag, a power of 2 from `1` to {@link Thread.MAX_FLAG}.
+        * @throws If `flag` is not a power of 2 between `1` and {@link Thread.MAX_FLAG}.
         * @example
         * ```ts
         * let ratio = 1
@@ -680,15 +712,20 @@ declare abstract class Thread {
         * ```
     */
     static addModifier(callback: Thread.CALLBACK, flag: Thread.FLAG): void;
+    /**
+        * Unregisters a driver added with {@link Thread.addDriver}. Does nothing if it is not registered.
+        * @param callback The same function reference passed to `addDriver`.
+    */
+    static removeDriver(callback: Thread.CALLBACK): void;
     /**
         * Removes a modifier registered with {@link Thread.addModifier}. Does nothing if it is not registered on `flag`.
         * @param callback The same function reference passed to `addModifier`.
         * @param flag The flag used when adding the modifier.
-        * @throws If `flag` is not a power of 2 between `1` and `4096`.
+        * @throws If `flag` is not a power of 2 between `1` and {@link Thread.MAX_FLAG}.
     */
     static removeModifier(callback: Thread.CALLBACK, flag: Thread.FLAG): void;
     /**
-        * Clears all modifiers and tasks and stops the internal frame loop. Called from `Up.destroy` in the browser.
+        * Clears all modifiers, tasks, and drivers, and stops the internal frame loop. Called from `Up.destroy` in the browser.
         * @internal
     */
     static [destroy](): void;
@@ -722,9 +759,9 @@ declare abstract class Thread {
         * (the task stays scheduled until the promise settles).
         * @template T Task type, used to type `args`.
         * @param task The task function, identified by reference.
-        * @param flag Priority flag, a power of 2 from `1` to `4096`. Default: {@link Thread.MAX_FLAG} (`4096`).
+        * @param flag Priority flag, a power of 2 from `1` to {@link Thread.MAX_FLAG}. Default: {@link Thread.DEFAULT_FLAG} (`8192`).
         * @param args Arguments passed to the task when it runs (the latest call wins).
-        * @throws If `flag` is not a power of 2 between `1` and `4096`.
+        * @throws If `flag` is not a power of 2 between `1` and {@link Thread.MAX_FLAG} (`32768`).
         * @example
         * ```ts
         * function* build(items: HTMLElement[]): Generator<void, void, void>
@@ -747,6 +784,18 @@ declare abstract class Thread {
         * @param task The same function reference passed to {@link Thread.sub}.
     */
     static unsub(task: Thread.TASK): void;
+    /**
+        * Arms modifiers of `flag` for the next modifiers phase (same frame if called from a driver or before modifiers run).
+        * No-op when no modifiers are registered on `flag`. {@link Thread.sub} calls this automatically; call it yourself
+        * when an external writer updates shared state without scheduling a task (e.g. Scroll arms {@link Thread.SCROLL_FLAG}
+        * after Lenis writes `window.scrollY`, so `App.updateScrollVars` and ScrollTrigger modifiers run).
+        * @param flag Priority flag whose modifiers should run.
+        * @example
+        * ```ts
+        * lenis.on('scroll', () => Up.Thread.arm(32))
+        * ```
+    */
+    static arm(flag: Thread.FLAG): void;
     /**
         * Returns a promise that resolves when a scheduled task completes its next (or current) run, or when it is unsubscribed.
         * @param task The same function reference passed to {@link Thread.sub}.
@@ -781,4 +830,4 @@ declare abstract class Thread {
     static unmarkForever(task: Thread.TASK): void;
 }
 
-export { Arrays as A, CallStack as C, Thread as T, App as a, type AppCache as b, updateScrollVars as c, updateScreenVars as u };
+export { Arrays as A, CallStack as C, Thread as T, App as a, type AppCache as b };

package/dist/core/[1]/Event.js

@@ -298,8 +298,8 @@ class Event {
       if (config.enhance) Event.#constructData(config.enhance);
     }
     for (const [KEY, DATA] of Event.#DATA) {
-      const CALLSTACK = [], caller = Event.#caller.bind(null, CALLSTACK), callback = DATA.crushed ? caller : DATA.callback.bind(null, caller);
-      Event.#MANAGER.set(KEY, CALLSTACK);
+      const WRAPPERS = [], caller = Event.#caller.bind(null, WRAPPERS), callback = DATA.crushed ? caller : DATA.callback.bind(null, caller);
+      Event.#MANAGER.set(KEY, WRAPPERS);
       if (DATA.forever) {
         Event.Thread.markForever(callback);
         Event.#getThreadSubscription(KEY, callback, DATA.threadFlag)();
@@ -359,18 +359,26 @@ class Event {
   static #getWaiter(task, waitState) {
     return waitState > 0 ? Wait.debounce(task, waitState, false) : Wait.throttle(task, waitState * -1, true, false);
   }
+  static #getIndex(wrappers, callback) {
+    for (let i = 0, max = wrappers.length; i < max; i++) if (wrappers[i].original === callback) return i;
+    return -1;
+  }
   // ##ADD
   /**
       * Adds `callback` to the callstack of `key` (no duplicates), or calls it immediately (see {@link Event.sub}).
   */
-  static #add(key, callback) {
-    if (key === "LOAD" && Event.#status & Event.#PRE_LOAD) {
+  static #add(key, callback, options) {
+    const WRAPPERS = Event.#MANAGER.get(key);
+    if (!WRAPPERS || key === "LOAD" && Event.#status & Event.#PRE_LOAD) {
       callback();
       return;
-    }
-    const CALLSTACK = Event.#MANAGER.get(key);
-    if (!CALLSTACK) callback();
-    else if (!CALLSTACK.includes(callback)) CALLSTACK.push(callback);
+    } else if (~Event.#getIndex(WRAPPERS, callback)) return;
+    let original = callback;
+    if (options?.once) callback = (...args) => {
+      Event.#remove(key, original);
+      return original(...args);
+    };
+    WRAPPERS.push({ original, callback });
   }
   // ##REMOVE
   /**
@@ -378,10 +386,10 @@ class Event {
   */
   static #remove(key, callback) {
     Wait.cancel(callback);
-    const CALLSTACK = Event.#MANAGER.get(key);
-    if (!CALLSTACK) return;
-    const INDEX = CALLSTACK.indexOf(callback);
-    if (~INDEX) CALLSTACK.splice(INDEX, 1);
+    const WRAPPERS = Event.#MANAGER.get(key);
+    if (!WRAPPERS) return;
+    const INDEX = Event.#getIndex(WRAPPERS, callback);
+    if (~INDEX) WRAPPERS.splice(INDEX, 1);
   }
   // ##UPDATES
   /**
@@ -530,20 +538,28 @@ class Event {
   }
   // ##UTILS
   /**
-      * Subscribes one or several tickets.
-      * Without `subscriber`, each `[key, callback]` ticket ({@link Event.TICKET}) is added to the Event manager.
-      * Subscribing the same callback twice to the same key has no effect, and subscribers of an event run in reverse subscription order.
-      * With `subscriber`, each `[key, callback, options?]` ticket ({@link Event.TICKET_CUSTOM}) is passed to `subscriber.addEventListener`.
-      * @note Without `subscriber`, the callback is called once immediately, with no arguments, and is not stored when:
-      * the key is unknown or not registered (including on the server), or the key is `LOAD` and the current `LOAD` phase has already started.
+      * Subscribes one or several handlers.
+      *
+      * **Event manager** (no second argument) — pass {@link Event.TICKET} tuples:
+      * - `['LIFE', onLife]`
+      * - `['LOAD', onLoad, { once: true }]` — runs once for that key, then auto-unsubscribes
+      *
+      * Same handler twice on the same key is ignored. Handlers for a given key run in **reverse** subscription order.
+      *
+      * **DOM target** — pass a `subscriber` (`window`, `document`, an element, …) and {@link Event.TICKET_CUSTOM}
+      * tuples; the third field is native `AddEventListenerOptions` (`passive`, DOM `once`, …).
+      *
+      * @note Without a `subscriber`, the handler is called **immediately** (no args) and **not stored** when:
+      * the key is unknown / not registered (including on the server), or the key is `LOAD` and the current `LOAD`
+      * phase has already started.
       * @param pass A ticket or an array of tickets.
-      * @param subscriber Optional listener target (`window`, `document`, an `Element`, …).
+      * @param subscriber Optional listener target for DOM (or DOM-like) events.
       * @example
       * ```ts
       * const onResize = (): void => console.log(Up.App.w, Up.App.h)
       * const onClick  = (e: MouseEvent): void => console.log(e.clientX)
       *
-      * Up.Event.sub([['LOAD', () => console.log('Page ready')], ['resize', onResize]])
+      * Up.Event.sub([['LOAD', () => console.log('Page ready'), { once: true }], ['resize', onResize]])
       * Up.Event.sub(['click', onClick, Up.Event.PASSIVE], document.body)
       * ```
   */
@@ -554,8 +570,9 @@ class Event {
     );
   }
   /**
-      * Unsubscribes one or several tickets previously passed to {@link Event.sub}.
-      * Callbacks are matched by reference, so pass the same function (and the same `subscriber`) used to subscribe.
+      * Unsubscribes handlers previously passed to {@link Event.sub}.
+      * Match by **function reference** (and the same `subscriber` if you used one).
+      * For Event-manager tickets, pass the same handler you subscribed — including when it was registered with `{ once: true }`.
       * @param pass A ticket or an array of tickets.
       * @param subscriber The listener target used when subscribing, if any.
       * @example
@@ -572,11 +589,12 @@ class Event {
   }
   // ##GENERATORS
   /**
-      * Calls each subscriber of `callstack` with `args`, from last to first, yielding after each call.
+      * Invokes each subscriber with `args`, from last to first, yielding after each call.
+      * @internal
   */
-  static *#caller(callstack, ...args) {
-    for (let i = callstack.length - 1; i > -1; i--) {
-      callstack[i](...args);
+  static *#caller(wrappers, ...args) {
+    for (let i = wrappers.length - 1; i > -1; i--) {
+      wrappers[i].callback(...args);
       yield;
     }
   }