@oxyhq/bloom 0.89.0 → 1.0.1

package/lib/module/scroll/index.web.js

@@ -1,326 +1,5 @@
 "use strict";
 
-/**
- * Web variant of the scroll-restoration primitive.
- *
- * Mirrors the proven Bluesky pattern (manual `history.scrollRestoration` plus
- * an in-memory `Map<key, offset>`) with three deliberate differences forced by
- * Oxy's layouts and by the behaviour of the (expo-router-wrapped) React
- * Navigation web stack:
- *
- *  1. Bluesky restores the WINDOW scroller, whereas Oxy apps keep multi-column
- *     layouts whose feed scrolls an INNER container. So we restore the offset
- *     of a caller-registered scrollable (a ref to an element / RN scroll
- *     component, or the `'window'` sentinel).
- *
- *  2. The web stack HIDES the background screen on push. While hidden, the
- *     previous screen's scroll container collapses (`scrollHeight ===
- *     clientHeight`) and the navigator forces its `scrollTop` to 0. The screen
- *     is NOT unmounted, so a virtualized list (e.g. FlashList) keeps its rows
- *     but re-lays them out over SEVERAL frames once the screen is re-shown. Two
- *     problems follow, both handled here:
- *
- *       (a) A blur-time read of `scrollTop` returns the navigator's forced 0,
- *           not the user's real offset — saving it would clobber the good
- *           value. We therefore persist the last offset OBSERVED by the live
- *           scroll listener, never a fresh read taken at blur time.
- *
- *       (b) A single-frame restore writes `scrollTop` while the list is still
- *           collapsed; the write is clamped to 0 and never re-applied once the
- *           content grows. We therefore re-apply the target offset across a
- *           bounded run of animation frames, stopping as soon as the write
- *           sticks (the content has grown tall enough) or a small frame cap is
- *           reached.
- *
- *  3. A document-scrolled app (one window scroller shared by every route) has
- *     no per-screen container to reset, so an unrecognised key MUST be written
- *     to 0 explicitly. Doing nothing leaves the previous screen's offset in
- *     place and the new screen opens mid-page.
- *
- * Native bundlers use `./index.ts`; web bundlers select this file via the
- * `"browser"` export condition in `package.json`.
- */
-import { useCallback, useRef } from 'react';
-import { useScrollRestorationContext } from "./context.js";
-import { createScroller } from "./scrollable.web.js";
-import { deriveScrollKey } from "./store.js";
 export { ScrollRestorationProvider } from "./context.js";
-/**
- * Maximum number of animation frames the restore will re-apply the saved offset
- * before giving up. A virtualized list re-lays out its rows over a handful of
- * frames after its screen is re-shown; ~30 frames (≈0.5s at 60fps) is
- * comfortably longer than any observed relayout while staying short enough that
- * the loop never lingers as a perceptible cost. The loop normally exits far
- * earlier — as soon as the write sticks.
- */
-const RESTORE_FRAME_CAP = 30;
-
-/**
- * Tolerance (in CSS pixels) for considering a restore "stuck". After writing
- * `element.scrollTop = target`, the browser may clamp it to the current
- * `scrollHeight - clientHeight`; if the resulting offset is within this many
- * pixels of the target we treat the restore as complete. Sub-pixel rounding and
- * fractional device-pixel ratios make an exact equality check unreliable.
- */
-const RESTORE_STICK_TOLERANCE_PX = 2;
-
-/**
- * The web binding is a constant: this platform observes offsets by subscribing
- * to the resolved DOM node's own `scroll` event, so it needs nothing from the
- * caller. It is still returned — and still safe to spread onto a list — so a
- * call site is written once and runs on both platforms.
- */
-const WEB_BINDING = {
-  onScroll: () => undefined
-};
-
-/**
- * Events that mean the USER has taken over the scroller, and the restore must
- * stop trying to put them back.
- *
- * The browser's own restoration is specified the same way: HTML §7.4.6.5 has
- * the UA re-attempt the saved position and "may continue to attempt to do so
- * periodically, until document's has been scrolled by the user becomes true".
- * Without this the loop fights anyone who starts scrolling inside the frame
- * budget, yanking them back once per frame for up to {@link RESTORE_FRAME_CAP}
- * frames.
- *
- * Two designs were rejected, and the reasons are the point:
- *
- *  - **"Any `scroll` event aborts"** — the obvious version, and it aborts on the
- *    FIRST frame every time: `setOffset` is itself a scroll, so the loop would
- *    cancel on the event its own write produced and no restore would ever
- *    complete.
- *  - **"Abort on an offset we did not write"** — tempting because it needs no
- *    listeners, but a virtualized list inserting rows ABOVE the viewport makes
- *    the browser's scroll anchoring move `scrollTop` on its own. That is
- *    precisely the situation the loop exists for, so the unexplained-delta test
- *    would abort exactly when it must not.
- *
- * What is being detected is user INPUT, so this detects user input. `pointerdown`
- * covers a scrollbar drag and a touch-less press; `keydown` covers arrow/page
- * keys, and reaches us whenever focus is inside the scroller it would scroll.
- */
-const USER_TAKEOVER_EVENTS = ['wheel', 'touchstart', 'pointerdown', 'keydown'];
-
-/**
- * Preserve and restore the scroll offset of `target` across navigation, keyed
- * by the content its screen is showing plus an optional `options.key`.
- *
- * Behaviour (web):
- * - On every scroll while the screen is focused, the current offset is recorded
- *   under the key that was live when the listener was attached. This stream of
- *   saves is the source of truth.
- * - On focus — and again whenever the key changes while the screen STAYS
- *   focused, which is how an in-screen tab or folder swap is seen at all — the
- *   offset saved for the new key is re-applied across a bounded run of
- *   animation frames, stopping as soon as the write sticks or
- *   {@link RESTORE_FRAME_CAP} is reached. Content never seen this session is
- *   written to 0 once instead; a write to 0 always sticks, so it needs no loop.
- * - On blur (and on a key change), the LAST OBSERVED offset is persisted under
- *   the OUTGOING key as a final safety net — not a fresh `scrollTop` read,
- *   which the navigator may already have forced to 0 while collapsing the
- *   hidden screen.
- */
-export function useScrollRestoration(target, options) {
-  const {
-    store,
-    adapter
-  } = useScrollRestorationContext();
-  const contentId = adapter.useScreenContentId();
-  const enabled = options?.enabled ?? true;
-  const scrollKey = deriveScrollKey(contentId, options?.key);
-
-  // The key this hook instance has already sent to the top. Writing 0 is a
-  // one-time ARRIVAL action: a later re-run for the SAME key (`enabled` turning
-  // on once the rows exist, a screen regaining focus) must not repeat it,
-  // because by then the user may have scrolled somewhere the hook never got to
-  // record. Restoring twice is harmless; resetting twice is data loss.
-  const resetKeyRef = useRef(null);
-  adapter.useScreenFocusEffect(
-  // Every varying input is a dependency rather than a ref read, so the
-  // session below CLOSES OVER the key it belongs to. That is what makes a
-  // key change mid-focus correct in both directions: the outgoing session's
-  // cleanup persists to the old key, and the incoming one restores the new.
-  useCallback(() => {
-    if (!enabled || scrollKey === null) return undefined;
-    const scroller = createScroller(target);
-    const element = target === 'window' ? typeof window === 'undefined' ? null : window : resolveScrollEventTarget(target);
-
-    // The last offset the live scroll listener observed for this session.
-    // This — not a cleanup-time `getOffset()` — is what we persist at the
-    // end, because by then the navigator may have collapsed the hidden
-    // screen and forced its `scrollTop` to 0 (problem A). `null` means the
-    // user never scrolled this session, so there is nothing newer to persist
-    // than what the scroll listener already saved live.
-    let lastObservedOffset = null;
-
-    // The offset WE last wrote, which a real browser dispatches back as a
-    // `scroll` event (jsdom does not, so the tests for this emit it
-    // explicitly). Both writers arm it: the reset, and every frame of the
-    // restore loop. Persisting either records an offset the user never
-    // chose — the reset's 0 under a key another LIVE screen may share (the
-    // two-live-entries trade content keying makes, see `deriveScrollKey`),
-    // and the loop's intermediate value as a PARTIAL that outlives an
-    // interrupted restore.
-    //
-    // A `restoring` FLAG covering the loop's duration is the obvious
-    // alternative and is wrong. It could only be cleared by a takeover
-    // event, so a session whose scroll came from a source that fires none —
-    // `scrollIntoView` from another component, a focus-driven scroll — would
-    // suppress saves indefinitely and never record the user's position at
-    // all: an unbounded corruption traded for a bounded one. Arming a VALUE
-    // is bounded to one event per write and covers every way the loop can
-    // end (stuck, capped, aborted), because each frame re-arms.
-    let echoOffset = null;
-
-    // The largest offset reachable when we last PERSISTED one. A browser
-    // clamp is recognised against this rather than against the previous
-    // OBSERVATION, and that distinction is the whole mechanism: Chrome
-    // dispatches TWO `scroll` events for one clamp, so an
-    // observation-relative test sees the shrink on the first and nothing on
-    // the second, which then saves the clamped value anyway. Measured.
-    let maxOffsetAtLastSave = scroller.getMaxOffset();
-    const save = () => {
-      const offset = scroller.getOffset();
-      const maxOffset = scroller.getMaxOffset();
-      // Ignore a spurious 0 produced by the navigator collapsing a hidden
-      // background screen: while collapsed the container cannot scroll, so
-      // its `scrollTop` is forced to 0. Persisting it would clobber the good
-      // offset recorded by earlier live saves (problem A). A genuine
-      // scroll-to-top keeps the container scrollable and is saved normally.
-      if (offset === 0 && maxOffset <= 0) return;
-      // A partial clamp: the reachable range SHRANK and the offset is sitting
-      // exactly at the new bottom. That is what the browser does to a tab
-      // whose document has been taken over by a shorter sibling — the two
-      // together are a signature a genuine scroll does not have, because
-      // reaching the bottom on your own does not shrink the page in the same
-      // breath. Suppressing keeps the pre-clamp offset, which on return
-      // simply clamps to the same place if the content really did shrink.
-      if (maxOffset < maxOffsetAtLastSave && Math.abs(offset - maxOffset) <= RESTORE_STICK_TOLERANCE_PX) {
-        return;
-      }
-      if (offset === echoOffset) {
-        // Our own write coming back. Consume the arming so a real scroll to
-        // the same offset later is saved normally.
-        echoOffset = null;
-        return;
-      }
-      echoOffset = null;
-      lastObservedOffset = offset;
-      maxOffsetAtLastSave = maxOffset;
-      store.save(scrollKey, offset);
-    };
-
-    // Restore and reset are ONE write. A miss reads 0, and 0 is exactly what
-    // an unseen screen must be written to — left alone it would show the
-    // previous screen's offset, since a document-scrolled app shares one
-    // scroller across every route.
-    const targetOffset = store.read(scrollKey);
-
-    // They remain two DECISIONS, though, and `read` cannot tell them apart:
-    // a key never seen and a key deliberately saved at the top both read 0.
-    // Only the first is a RESET, and a reset is a one-time ARRIVAL action
-    // gated on `resetKeyRef` — repeating it on a later re-run for the same
-    // key would send a user who has since scrolled back to the top, and the
-    // hook was inert while they did it so there is nothing to restore them
-    // to afterwards. A 0 the user deliberately saved is theirs, and always
-    // re-applies. `has` is the only thing that answers this.
-    const isReset = !store.has(scrollKey);
-    const alreadyReset = isReset && resetKeyRef.current === scrollKey;
-    if (isReset) resetKeyRef.current = scrollKey;
-    let rafId = null;
-    const stopRestore = () => {
-      if (rafId === null) return;
-      cancelAnimationFrame(rafId);
-      rafId = null;
-    };
-    if (alreadyReset) {
-      // Nothing to write: this content has already been sent to the top once
-      // and the user is wherever they have moved to since.
-    } else if (targetOffset === 0) {
-      // A write to 0 is never clamped away, so it needs no re-apply loop.
-      echoOffset = 0;
-      scroller.setOffset(0);
-    } else if (typeof requestAnimationFrame !== 'undefined') {
-      // Re-apply across a bounded run of frames. A freshly re-shown
-      // virtualized list re-lays out its rows over several frames, so a
-      // single write while it is still collapsed would be clamped to 0 and
-      // never re-applied (problem B).
-      //
-      // Every write the loop makes is suppressed from the save path (see
-      // `echoOffset` below), so an interrupted restore leaves the ORIGINAL
-      // target stored rather than a partial. Nothing is lost on the success
-      // path: `targetOffset` came out of the store, so persisting it again
-      // would write back the same number.
-      let framesLeft = RESTORE_FRAME_CAP;
-      const applyOffset = () => {
-        rafId = null;
-        scroller.setOffset(targetOffset);
-        framesLeft -= 1;
-        // `getOffset` re-reads the value the browser actually took, which is
-        // clamped to the content height it has reached so far. Arm it as the
-        // echo to swallow: this write is about to come back as a `scroll`
-        // event, and persisting a PARTIAL offset we wrote ourselves is how a
-        // restore that is aborted or capped corrupts the stored position.
-        const landed = scroller.getOffset();
-        echoOffset = landed;
-        // Stop once the write took effect (content grew tall enough) or we
-        // exhaust the frame budget.
-        const reached = Math.abs(landed - targetOffset) <= RESTORE_STICK_TOLERANCE_PX;
-        if (!reached && framesLeft > 0) {
-          rafId = requestAnimationFrame(applyOffset);
-        }
-      };
-      rafId = requestAnimationFrame(applyOffset);
-      // Only while a loop is actually in flight — the reset path has nothing
-      // to abort, and the listeners would be idle on every screen.
-      for (const type of USER_TAKEOVER_EVENTS) {
-        element?.addEventListener(type, stopRestore, {
-          passive: true
-        });
-      }
-    }
-    element?.addEventListener('scroll', save, {
-      passive: true
-    });
-    return () => {
-      stopRestore();
-      element?.removeEventListener('scroll', save);
-      // Removing a listener that was never added is a no-op, so this needs no
-      // flag tracking whether the loop branch ran.
-      for (const type of USER_TAKEOVER_EVENTS) {
-        element?.removeEventListener(type, stopRestore);
-      }
-      // Final capture: persist the last offset the scroll listener OBSERVED,
-      // never a fresh read (which the navigator may have forced to 0 while
-      // collapsing the hidden screen). When the user never scrolled this
-      // session there is nothing newer than the live saves already recorded.
-      if (lastObservedOffset !== null) {
-        store.save(scrollKey, lastObservedOffset);
-      }
-    };
-  }, [store, scrollKey, enabled, target]));
-  return WEB_BINDING;
-}
-
-/**
- * Resolve the EventTarget to listen for `scroll` on. RNW scroll components
- * expose `getScrollableNode()`; raw refs may hold the DOM node directly.
- */
-function resolveScrollEventTarget(target) {
-  const current = target.current;
-  if (current == null) return null;
-  if (typeof EventTarget !== 'undefined' && current instanceof EventTarget) {
-    return current;
-  }
-  const handle = current;
-  if (typeof handle.getScrollableNode === 'function') {
-    const node = handle.getScrollableNode();
-    if (typeof EventTarget !== 'undefined' && node instanceof EventTarget) {
-      return node;
-    }
-  }
-  return null;
-}
+export { useScrollRestoration } from "./use-scroll-restoration.web.js";
 //# sourceMappingURL=index.web.js.map

package/lib/module/scroll/index.web.js.map

@@ -1 +1 @@
-{"version":3,"names":["useCallback","useRef","useScrollRestorationContext","createScroller","deriveScrollKey","ScrollRestorationProvider","RESTORE_FRAME_CAP","RESTORE_STICK_TOLERANCE_PX","WEB_BINDING","onScroll","undefined","USER_TAKEOVER_EVENTS","useScrollRestoration","target","options","store","adapter","contentId","useScreenContentId","enabled","scrollKey","key","resetKeyRef","useScreenFocusEffect","scroller","element","window","resolveScrollEventTarget","lastObservedOffset","echoOffset","maxOffsetAtLastSave","getMaxOffset","save","offset","getOffset","maxOffset","Math","abs","targetOffset","read","isReset","has","alreadyReset","current","rafId","stopRestore","cancelAnimationFrame","setOffset","requestAnimationFrame","framesLeft","applyOffset","landed","reached","type","addEventListener","passive","removeEventListener","EventTarget","handle","getScrollableNode","node"],"sourceRoot":"../../../src","sources":["scroll/index.web.tsx"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASA,WAAW,EAAEC,MAAM,QAAQ,OAAO;AAE3C,SAASC,2BAA2B,QAAQ,cAAW;AACvD,SAASC,cAAc,QAAQ,qBAAkB;AACjD,SAASC,eAAe,QAAQ,YAAS;AAOzC,SAASC,yBAAyB,QAAQ,cAAW;AAYrD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMC,iBAAiB,GAAG,EAAE;;AAE5B;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMC,0BAA0B,GAAG,CAAC;;AAEpC;AACA;AACA;AACA;AACA;AACA;AACA,MAAMC,WAAqC,GAAG;EAAEC,QAAQ,EAAEA,CAAA,KAAMC;AAAU,CAAC;;AAE3E;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMC,oBAAoB,GAAG,CAAC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,CAAC;;AAE9E;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,oBAAoBA,CAClCC,MAA+B,EAC/BC,OAAqC,EACX;EAC1B,MAAM;IAAEC,KAAK;IAAEC;EAAQ,CAAC,GAAGd,2BAA2B,CAAC,CAAC;EACxD,MAAMe,SAAS,GAAGD,OAAO,CAACE,kBAAkB,CAAC,CAAC;EAC9C,MAAMC,OAAO,GAAGL,OAAO,EAAEK,OAAO,IAAI,IAAI;EACxC,MAAMC,SAAS,GAAGhB,eAAe,CAACa,SAAS,EAAEH,OAAO,EAAEO,GAAG,CAAC;;EAE1D;EACA;EACA;EACA;EACA;EACA,MAAM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","ignoreList":[]}
+{"version":3,"names":["ScrollRestorationProvider","useScrollRestoration"],"sourceRoot":"../../../src","sources":["scroll/index.web.ts"],"mappings":";;AAAA,SAASA,yBAAyB,QAAQ,cAAW;AACrD,SAASC,oBAAoB,QAAQ,iCAA8B","ignoreList":[]}

package/lib/module/scroll/use-scroll-restoration.js

@@ -0,0 +1,106 @@
+"use strict";
+
+/**
+ * Native variant of the scroll-restoration primitive.
+ *
+ * React Navigation's native-stack keeps every screen MOUNTED while it is in the
+ * stack, so a list's scroll position survives a push/pop for free — this file
+ * must not interfere with that, and does not: nothing here runs on focus.
+ *
+ * What native does not survive is a KEY CHANGE: an in-screen tab or folder swap
+ * that re-keys a list, and a screen that genuinely unmounts and remounts. The
+ * effect below is therefore keyed on the storage key (plus `enabled`) rather
+ * than on focus, which draws exactly that line with no bookkeeping: React
+ * re-runs it when the key changes and leaves it alone when a push/pop merely
+ * re-focuses the same screen showing the same content.
+ *
+ * Web bundlers select `./index.web` via the `"browser"` export condition in
+ * `package.json`; native bundlers fall through to this file.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useScrollRestorationContext } from "./context.js";
+import { createScroller } from "./scrollable.native.js";
+import { deriveScrollKey } from "./store.js";
+/**
+ * Preserve and restore the scroll offset of `target` across content changes,
+ * keyed by the content its screen is showing plus an optional `options.key`.
+ *
+ * Behaviour (native):
+ * - Offsets are recorded from the returned `onScroll` binding, which the caller
+ *   wires onto the list. There is no other way to observe a list's offset.
+ * - When the storage key changes — a re-keyed list, a remount, or `enabled`
+ *   turning on — the saved offset is applied, or 0 when the key was never seen.
+ * - A push/pop that re-focuses the same screen scrolls nothing. The navigator
+ *   already preserved the position, and re-applying it would at best be a
+ *   no-op and at worst fight a list that has legitimately moved on.
+ */
+export function useScrollRestoration(target, options) {
+  const {
+    store,
+    adapter
+  } = useScrollRestorationContext();
+  const contentId = adapter.useScreenContentId();
+  const enabled = options?.enabled ?? true;
+  const scrollKey = deriveScrollKey(contentId, options?.key);
+
+  // The key the live `onScroll` binding is allowed to record against. It is
+  // assigned by the effect below only AFTER that effect's own write has landed,
+  // and cleared by its cleanup — so the relayout the outgoing content emits
+  // while a new key is already rendered is never attributed to the new key.
+  const recordingKeyRef = useRef(null);
+
+  // Native's write is ALWAYS deferred a frame (see below), restore and reset
+  // alike, so this is pending whenever the effect below has work to do. Seeded
+  // on the first render rather than defaulting to false, because the effect is
+  // a passive one: a caller hiding its list until the offset lands would
+  // otherwise get one painted frame at the wrong position.
+  const [restorePending, setRestorePending] = useState(() => enabled && scrollKey !== null);
+  useEffect(() => {
+    if (!enabled || scrollKey === null) {
+      setRestorePending(false);
+      return undefined;
+    }
+    const scroller = createScroller(target);
+    let frame = null;
+
+    // Restore and reset are ONE write: a miss reads 0, and 0 is exactly what a
+    // list showing content never seen this session must be sent to rather than
+    // left at the offset its predecessor had.
+    setRestorePending(true);
+    const apply = () => {
+      frame = null;
+      scroller.setOffset(store.read(scrollKey));
+      recordingKeyRef.current = scrollKey;
+      setRestorePending(false);
+    };
+
+    // Defer one frame. This effect fires in the same commit that rendered the
+    // incoming rows, and a list cannot honour an offset before it has laid them
+    // out — the write would be clamped to whatever height it has reached so
+    // far, with no second chance (unlike web, native gets no scroll event to
+    // re-apply from). One frame is all that is needed because `enabled` has
+    // already guaranteed the rows are there; what remains is the layout pass.
+    if (typeof requestAnimationFrame === 'function') {
+      frame = requestAnimationFrame(apply);
+    } else {
+      // No frame scheduler (SSR, or a bare Node import of this barrel).
+      // Applying immediately is still the correct write; only the wait is lost.
+      apply();
+    }
+    return () => {
+      if (frame !== null) cancelAnimationFrame(frame);
+      recordingKeyRef.current = null;
+      setRestorePending(false);
+    };
+  }, [store, scrollKey, enabled, target]);
+  const onScroll = useCallback(event => {
+    const key = recordingKeyRef.current;
+    if (key === null) return;
+    store.save(key, event.nativeEvent.contentOffset.y);
+  }, [store]);
+  return useMemo(() => ({
+    onScroll,
+    restorePending
+  }), [onScroll, restorePending]);
+}
+//# sourceMappingURL=use-scroll-restoration.js.map

package/lib/module/scroll/use-scroll-restoration.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useCallback","useEffect","useMemo","useRef","useState","useScrollRestorationContext","createScroller","deriveScrollKey","useScrollRestoration","target","options","store","adapter","contentId","useScreenContentId","enabled","scrollKey","key","recordingKeyRef","restorePending","setRestorePending","undefined","scroller","frame","apply","setOffset","read","current","requestAnimationFrame","cancelAnimationFrame","onScroll","event","save","nativeEvent","contentOffset","y"],"sourceRoot":"../../../src","sources":["scroll/use-scroll-restoration.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASA,WAAW,EAAEC,SAAS,EAAEC,OAAO,EAAEC,MAAM,EAAEC,QAAQ,QAAQ,OAAO;AAEzE,SAASC,2BAA2B,QAAQ,cAAW;AACvD,SAASC,cAAc,QAAQ,wBAAqB;AACpD,SAASC,eAAe,QAAQ,YAAS;AAOzC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,oBAAoBA,CAClCC,MAA+B,EAC/BC,OAAqC,EACX;EAC1B,MAAM;IAAEC,KAAK;IAAEC;EAAQ,CAAC,GAAGP,2BAA2B,CAAC,CAAC;EACxD,MAAMQ,SAAS,GAAGD,OAAO,CAACE,kBAAkB,CAAC,CAAC;EAC9C,MAAMC,OAAO,GAAGL,OAAO,EAAEK,OAAO,IAAI,IAAI;EACxC,MAAMC,SAAS,GAAGT,eAAe,CAACM,SAAS,EAAEH,OAAO,EAAEO,GAAG,CAAC;;EAE1D;EACA;EACA;EACA;EACA,MAAMC,eAAe,GAAGf,MAAM,CAAgB,IAAI,CAAC;;EAEnD;EACA;EACA;EACA;EACA;EACA,MAAM,CAACgB,cAAc,EAAEC,iBAAiB,CAAC,GAAGhB,QAAQ,CAClD,MAAMW,OAAO,IAAIC,SAAS,KAAK,IACjC,CAAC;EAEDf,SAAS,CAAC,MAAM;IACd,IAAI,CAACc,OAAO,IAAIC,SAAS,KAAK,IAAI,EAAE;MAClCI,iBAAiB,CAAC,KAAK,CAAC;MACxB,OAAOC,SAAS;IAClB;IAEA,MAAMC,QAAQ,GAAGhB,cAAc,CAACG,MAAM,CAAC;IACvC,IAAIc,KAAoB,GAAG,IAAI;;IAE/B;IACA;IACA;IACAH,iBAAiB,CAAC,IAAI,CAAC;IACvB,MAAMI,KAAK,GAAGA,CAAA,KAAY;MACxBD,KAAK,GAAG,IAAI;MACZD,QAAQ,CAACG,SAAS,CAACd,KAAK,CAACe,IAAI,CAACV,SAAS,CAAC,CAAC;MACzCE,eAAe,CAACS,OAAO,GAAGX,SAAS;MACnCI,iBAAiB,CAAC,KAAK,CAAC;IAC1B,CAAC;;IAED;IACA;IACA;IACA;IACA;IACA;IACA,IAAI,OAAOQ,qBAAqB,KAAK,UAAU,EAAE;MAC/CL,KAAK,GAAGK,qBAAqB,CAACJ,KAAK,CAAC;IACtC,CAAC,MAAM;MACL;MACA;MACAA,KAAK,CAAC,CAAC;IACT;IAEA,OAAO,MAAM;MACX,IAAID,KAAK,KAAK,IAAI,EAAEM,oBAAoB,CAACN,KAAK,CAAC;MAC/CL,eAAe,CAACS,OAAO,GAAG,IAAI;MAC9BP,iBAAiB,CAAC,KAAK,CAAC;IAC1B,CAAC;EACH,CAAC,EAAE,CAACT,KAAK,EAAEK,SAAS,EAAED,OAAO,EAAEN,MAAM,CAAC,CAAC;EAEvC,MAAMqB,QAAQ,GAAG9B,WAAW,CACzB+B,KAAK,IAAK;IACT,MAAMd,GAAG,GAAGC,eAAe,CAACS,OAAO;IACnC,IAAIV,GAAG,KAAK,IAAI,EAAE;IAClBN,KAAK,CAACqB,IAAI,CAACf,GAAG,EAAEc,KAAK,CAACE,WAAW,CAACC,aAAa,CAACC,CAAC,CAAC;EACpD,CAAC,EACD,CAACxB,KAAK,CACR,CAAC;EAED,OAAOT,OAAO,CACZ,OAAO;IAAE4B,QAAQ;IAAEX;EAAe,CAAC,CAAC,EACpC,CAACW,QAAQ,EAAEX,cAAc,CAC3B,CAAC;AACH","ignoreList":[]}