tera-system-ui 0.2.1 → 0.2.3

package/dist/components/bottom-sheet/BottomSheet.svelte

@@ -1,3 +1,44 @@
+<script module lang="ts">"use strict";
+// ============================================
+// PAGE-ROOT OVERSCROLL GUARD (native pull-to-refresh)
+// ============================================
+// The two-phase drag doesn't preventDefault() until a gesture commits past the ~10px
+// activation threshold, so a SLOW downward pull that STARTS on an interactive element
+// (button / input / link / [tabindex]) leaves a window where the browser can claim the
+// gesture as native pull-to-refresh / overscroll-reload before the sheet does — which is
+// why only a *slow* pull triggers it (a quick flick clears the threshold on the first
+// touchmove and preventDefault()s first). `overscroll-behavior-y: contain` on the document
+// root closes that window for the sheet's whole open lifetime WITHOUT touching the gesture
+// logic. Shared + reference-counted across every mounted sheet so stacked sheets apply it
+// once and the page's original inline value is restored only when the last sheet releases.
+let overscrollGuardCount = 0;
+let savedRootOverscrollY = '';
+let savedBodyOverscrollY = '';
+function acquireOverscrollGuard() {
+    if (typeof document === 'undefined')
+        return;
+    if (overscrollGuardCount === 0) {
+        const root = document.documentElement;
+        const { body } = document;
+        savedRootOverscrollY = root.style.overscrollBehaviorY;
+        savedBodyOverscrollY = body.style.overscrollBehaviorY;
+        // Set both: browsers disagree on whether html or body is the root scroller.
+        root.style.overscrollBehaviorY = 'contain';
+        body.style.overscrollBehaviorY = 'contain';
+    }
+    overscrollGuardCount++;
+}
+function releaseOverscrollGuard() {
+    if (typeof document === 'undefined' || overscrollGuardCount === 0)
+        return;
+    overscrollGuardCount--;
+    if (overscrollGuardCount === 0) {
+        document.documentElement.style.overscrollBehaviorY = savedRootOverscrollY;
+        document.body.style.overscrollBehaviorY = savedBodyOverscrollY;
+    }
+}
+</script>
+
 <script lang="ts">import { onDestroy, onMount } from 'svelte';
 import { bottomSheetStore } from './bottomSheetStore.svelte.js';
 import { bottomSheetRecipe } from './BottomSheet.recipe';
@@ -18,23 +59,31 @@ const CONFIG = {
     backdrop: {
         maxOpacity: 0.5 // Maximum opacity when fully open
     },
-    // Animation timing
+    // Spring physics for open / close / settle, PLAYED ON THE COMPOSITOR via the Web
+    // Animations API (see animateTo) so motion holds the display's native refresh rate
+    // (e.g. 120Hz) even under main-thread load. `response` is the approximate settle
+    // time (s); `damping` is the damping ratio (1 = critical/no bounce, <1 adds a little
+    // life). The spring is simulated ONCE per gesture — seeded with the finger's release
+    // velocity so motion continues instead of restarting — and emitted as compositor
+    // keyframes; there is no per-frame JavaScript. `close` finalizes the instant it
+    // reaches offscreen (simulateSpring hideOnArrival) so there is no lingering tail.
     animation: {
-        defaultDuration: 0.35, // Default duration (seconds)
-        minDuration: 0.15, // Min duration for fast swipes
-        maxDuration: 0.4, // Max duration for slow gestures
-        easing: 'cubic-bezier(0.2, 0.9, 0.36, 1)' // iOS-style spring curve
+        open: { response: 0.4, damping: 0.86 }, // present — quick, no bounce
+        close: { response: 0.26, damping: 0.85 }, // dismiss — fast, finalizes on arrival
+        snap: { response: 0.32, damping: 0.84 }, // moving between snap points
+        restDistance: 0.5, // px from target at which the simulated spring is "settled"
+        restVelocity: 40 // px/s below which the simulated spring is "at rest"
     },
     // Gesture handling
     gesture: {
         velocityInfluence: 0.01, // How much velocity affects snap selection
-        overdragExponent: 0.55, // Overdrag resistance (lower = more resistance)
         closeVelocityThreshold: 0.35, // Velocity to trigger close (px/ms)
         closeProgressThreshold: 0.35, // Progress to trigger close (0-1)
         maxLockedDrag: 60, // Max drag when dragToClose disabled (px)
         lockedDragResistance: 0.3, // Resistance when dragToClose disabled
         // Two-phase gesture recognition for interactive elements (iOS-style)
         dragActivationThreshold: 10, // Vertical px to commit to drag from interactive element
+        pullClaimThreshold: 3, // Vertical px to CLAIM the gesture (preventDefault) BEFORE commit, so iOS Safari can't start pull-to-refresh during a slow pull. Below dragActivationThreshold; tune on-device.
         horizontalDeadZone: 1.2, // If abs(dx)/abs(dy) > this, abort drag (let native horizontal win)
         tapDistanceThreshold: 6 // Max total movement (px) to still count as a tap
     }
@@ -42,7 +91,7 @@ const CONFIG = {
 // ============================================
 // COMPONENT PROPS
 // ============================================
-let { id, open = $bindable(false), snapPoints = [0.9], defaultSnapPoint = 0, containerRef = null, scaleTargetRef = null, constrainToContainer = false, scaleBackground = true, dragToClose = true, closeOnBackdrop = true, showCloseButton = false, onClose, onOpenChange, children, header } = $props();
+let { id, open = $bindable(false), snapPoints = [0.9], defaultSnapPoint = 0, containerRef = null, scaleTargetRef = null, constrainToContainer = false, scaleBackground = true, dragToClose = true, closeOnBackdrop = true, showCloseButton = false, syncThemeColor = true, preventPullToRefresh = true, onClose, onOpenChange, children, header } = $props();
 // ============================================
 // INTERNAL STATE
 // ============================================
@@ -53,11 +102,32 @@ let backdropRef = $state(null);
 // Sheet state
 let isVisible = $state(false);
 let isClosing = $state(false);
-let isAnimating = $state(false);
 let isDragging = $state(false);
-let currentTranslateY = $state(0);
+// Plain (NOT $state): written on every drag move (can be ~120/s) but never read
+// reactively (no template / $derived / $effect depends on it). Keeping it out of the
+// reactivity graph avoids a signal write per pointer event on high-refresh displays.
+// During a compositor animation it holds the resting target; the true on-screen value
+// is read from the compositor when a gesture interrupts (readLiveTranslateY).
+let currentTranslateY = 0;
 let sheetHeight = $state(0);
-let transitionDuration = $state(`${CONFIG.animation.defaultDuration}s`);
+// Compositor spring engine — programmatic motion (open/close/snap/settle) plays as Web
+// Animations on the compositor thread (see animateTo). currentTranslateY holds the live
+// RESTING position; while an animation runs we read the true on-screen value straight
+// from the compositor (readLiveTranslateY), so grabbing the sheet mid-flight never jumps.
+let sheetAnim = null; // sheet translate
+let backdropAnim = null; // backdrop opacity (kept in sync)
+let scaleAnim = null; // scale-target scale/translate/radius (in sync)
+let scaleTargetPrimed = false; // static scale-target styles set once per open cycle
+// iOS Safari status-bar tint. The full-screen backdrop darkens the area behind the status
+// bar; with no page-level <meta name="theme-color"> Safari re-samples it and flips the bar
+// dark (losing the immersive look). When the page declares none we add one (= page
+// background) for the sheet's open lifetime and remove it on close; a page that sets its own
+// theme-color is left alone — Safari honors it, so the backdrop can't flip it.
+let themeColorMeta = null;
+// Whether THIS sheet currently holds the shared page-root overscroll guard (see the module
+// script). Kept per-instance so acquire/release stay balanced — restore is called from both
+// the close completion and onDestroy, and must be a no-op the second time.
+let heldOverscrollGuard = false;
 // Drag tracking
 let dragState = {
     startY: 0,
@@ -79,6 +149,11 @@ let dragState = {
 // Scroll state
 let scrollableElement = null;
 let isScrolledToTop = true;
+// Backdrop dismiss: the pointerId of a press that STARTED on the backdrop. A genuine
+// dismiss is a full press+release on the backdrop; tracking the origin lets us ignore
+// the stray pointerup that lands on a freshly-mounted backdrop when a press begun
+// elsewhere (e.g. a long-press on a button that opened the sheet) is released over it.
+let backdropPressPointerId = null;
 // Dimensions
 let windowHeight = $state(typeof window !== 'undefined' ? window.innerHeight : 800);
 let containerHeight = $state(0);
@@ -108,6 +183,19 @@ onMount(() => {
 });
 onDestroy(() => {
     containerResizeObserver?.disconnect();
+    cancelAnimations();
+    restoreThemeColor();
+    restoreOverscrollGuard();
+});
+// Motion is driven by direct writes (drag) and Web Animations (open/close/snap), so keep
+// the recipe's CSS `transition` OFF on these elements — otherwise the CSS transition would
+// fight each per-move drag write and smear it. (WAAPI animations are independent of the
+// `transition` property, so turning it off here does not affect them.)
+$effect(() => {
+    if (sheetRef)
+        sheetRef.style.transition = 'none';
+    if (backdropRef)
+        backdropRef.style.transition = 'none';
 });
 // Watch containerRef for constrained mode
 $effect(() => {
@@ -145,19 +233,11 @@ $effect(() => {
         doClose();
     }
 });
-// Setup scrollable element detection
-$effect(() => {
-    if (!contentRef || !isVisible)
-        return;
-    scrollableElement = contentRef.querySelector('[data-bottom-sheet-scroll]');
-    if (!scrollableElement)
-        return;
-    const handleScroll = () => {
-        isScrolledToTop = scrollableElement.scrollTop <= 1;
-    };
-    scrollableElement.addEventListener('scroll', handleScroll, { passive: true });
-    isScrolledToTop = scrollableElement.scrollTop <= 1;
-});
+// NOTE: The scrollable region ([data-bottom-sheet-scroll]) is resolved lazily
+// at gesture-start from the event target (see getScrollableFromTarget), NOT via
+// a one-shot querySelector here. A single querySelector at open-time cannot see
+// content that is mounted lazily AFTER the sheet opens (e.g. async-loaded lists),
+// which left scrollableElement null and broke drag/scroll arbitration inside it.
 // ============================================
 // CORE FUNCTIONS
 // ============================================
@@ -176,52 +256,256 @@ function recalculateDimensions() {
     if (sheetRef)
         sheetHeight = sheetRef.offsetHeight;
 }
+// ============================================
+// COMPOSITOR SPRING ENGINE (Web Animations API)
+// ============================================
+// Open / close / snap / settle play as Web Animations on the COMPOSITOR thread, so they
+// hold the display's native refresh rate (e.g. 120Hz) even when the main thread is busy —
+// the failure mode of a per-frame rAF loop, which must be scheduled on main every frame
+// and drops frames under contention. We simulate the damped spring ONCE per gesture
+// (seeded with the finger's release velocity) to get a position trajectory, then hand it
+// to the compositor as keyframes: NO per-frame JavaScript, store write, or layout during
+// the animation. Drag stays on direct per-input writes (renderPosition) — it must track
+// the finger 1:1, which no pre-baked animation can do.
+const prefersReducedMotion = () => typeof window !== 'undefined' &&
+    !!window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+/** Convert (response, dampingRatio) to spring stiffness/damping (unit mass). */
+function springConstants(response, damping) {
+    const omega = (2 * Math.PI) / response; // natural angular frequency
+    return { k: omega * omega, c: 2 * damping * omega };
+}
+// ── Position → visual mappings. Shared by immediate drag writes (renderPosition) and by
+//    keyframe generation, so a compositor animation and a live drag paint identically. ──
+function backdropOpacityFor(translateY) {
+    const progress = Math.max(0, Math.min(maxSnapPoint, (sheetHeight - translateY) / effectiveHeight));
+    return Math.max(0, Math.min(CONFIG.backdrop.maxOpacity, progress * CONFIG.backdrop.maxOpacity));
+}
+function scalePropsFor(translateY) {
+    const p = Math.max(0, Math.min(1, (sheetHeight - translateY) / effectiveHeight));
+    const { factor, borderRadius, translateY: ty } = CONFIG.scale;
+    return {
+        scale: String(1 - factor * p),
+        translate: `0 ${(ty * p).toFixed(2)}px`,
+        borderRadius: `${(borderRadius * p).toFixed(2)}px`
+    };
+}
+/** Set the scale target's static (non-animated) styles once per open cycle. */
+function primeScaleTarget() {
+    if (scaleTargetPrimed || !scaleTarget || !scaleBackground)
+        return;
+    scaleTarget.style.transition = 'none';
+    scaleTarget.style.transformOrigin = CONFIG.scale.origin;
+    scaleTarget.style.overflow = 'hidden';
+    scaleTarget.style.willChange = 'scale, translate, border-radius';
+    scaleTargetPrimed = true;
+}
+/** Write the whole visual state for a given translateY. Used by DRAG and immediate sets. */
+function renderPosition(translateY) {
+    if (sheetRef)
+        sheetRef.style.translate = `0 ${translateY}px`;
+    const rawProgress = (sheetHeight - translateY) / effectiveHeight;
+    const progress = Math.max(0, Math.min(maxSnapPoint, rawProgress));
+    updateBackdrop(progress);
+    updateScaleTarget(progress);
+    bottomSheetStore.updateProgress(id, Math.max(0, Math.min(1, rawProgress)));
+}
+/** Read the sheet's LIVE translateY — reflects a running compositor animation. */
+function readLiveTranslateY() {
+    if (!sheetRef)
+        return null;
+    const t = getComputedStyle(sheetRef).getPropertyValue('translate');
+    if (!t || t === 'none')
+        return null;
+    const parts = t.trim().split(/\s+/);
+    const y = parts.length > 1 ? parseFloat(parts[1]) : 0;
+    return Number.isFinite(y) ? y : null;
+}
+/** Cancel any in-flight compositor animations (sheet + backdrop + scale). */
+function cancelAnimations() {
+    sheetAnim?.cancel();
+    backdropAnim?.cancel();
+    scaleAnim?.cancel();
+    sheetAnim = backdropAnim = scaleAnim = null;
+}
+/**
+ * Freeze the sheet at its LIVE on-screen position and stop the animation, so a fresh
+ * gesture anchors to exactly what's rendered — no jump. Called when the user grabs the
+ * sheet mid-flight. (.cancel() reverts fill:none animations to their base, which is the
+ * settled target — so we pin the live value to inline styles FIRST, then cancel.)
+ */
+function interruptAnimation() {
+    if (sheetAnim || backdropAnim || scaleAnim) {
+        const liveY = readLiveTranslateY();
+        if (liveY !== null) {
+            currentTranslateY = liveY;
+            renderPosition(liveY); // pin translate + backdrop + scale to the live value
+        }
+        cancelAnimations();
+    }
+    isClosing = false;
+}
+/** Snap all visuals to a resting target — the base the fill:none animations settle onto. */
+function applyFinal(target) {
+    currentTranslateY = target;
+    renderPosition(target);
+}
+/**
+ * Simulate a damped spring from startY → targetY seeded with v0 (px/s), returning the
+ * position trajectory (evenly spaced in time) and its duration (ms). For close/hide we
+ * stop at the FIRST arrival at the target (on the way offscreen) so there is no tail.
+ */
+function simulateSpring(startY, targetY, v0, spring, hideOnArrival) {
+    const { restDistance, restVelocity } = CONFIG.animation;
+    const { k, c } = springConstants(spring.response, spring.damping);
+    const dt = 1 / 90; // keyframe sampling step; compositor interpolates between
+    const subSteps = 2; // physics sub-steps per sample (stability at high stiffness)
+    const h = dt / subSteps;
+    const maxSteps = Math.ceil(1.5 / dt); // safety cap (~1.5s)
+    let x = startY;
+    let v = v0;
+    const ys = [x];
+    for (let i = 0; i < maxSteps; i++) {
+        for (let s = 0; s < subSteps; s++) {
+            const a = -k * (x - targetY) - c * v;
+            v += a * h;
+            x += v * h;
+        }
+        if (hideOnArrival && x >= targetY) {
+            ys.push(targetY); // reached offscreen — stop before any rebound
+            break;
+        }
+        ys.push(x);
+        if (!hideOnArrival && Math.abs(x - targetY) < restDistance && Math.abs(v) < restVelocity) {
+            ys[ys.length - 1] = targetY;
+            break;
+        }
+    }
+    return { ys, duration: (ys.length - 1) * dt * 1000 };
+}
+/**
+ * Spring the sheet toward `target`, seeded with `initialVelocity` (px/s) so a flick
+ * continues seamlessly. Plays on the COMPOSITOR via the Web Animations API. If a spring
+ * is already in flight we read its LIVE position and re-simulate from there, so retargets
+ * (and mid-flight direction changes) never jump. The sheet's translate, the backdrop's
+ * opacity, and the scale target all animate from ONE simulation with identical timing, so
+ * they stay locked together on the compositor with zero per-frame JS.
+ */
+function animateTo(target, spring, initialVelocity = 0, onComplete, hideOnArrival = false) {
+    const running = !!(sheetAnim || backdropAnim || scaleAnim);
+    const start = running ? (readLiveTranslateY() ?? currentTranslateY) : currentTranslateY;
+    cancelAnimations();
+    // Reduced motion, or a move too small to be worth animating → jump straight there.
+    if (prefersReducedMotion()) {
+        applyFinal(target);
+        onComplete?.();
+        return;
+    }
+    const { ys, duration } = simulateSpring(start, target, initialVelocity, spring, hideOnArrival);
+    if (duration < 8 || ys.length < 2) {
+        applyFinal(target);
+        onComplete?.();
+        return;
+    }
+    if (scaleTarget && scaleBackground)
+        primeScaleTarget();
+    // Bases = final values, so when the fill:none animations end the elements hold `target`
+    // (no revert-to-start flash). The animations override this from t=0 with keyframe[0]=start.
+    applyFinal(target);
+    const N = ys.length;
+    const opts = { duration, easing: 'linear', fill: 'none' };
+    const sheetKf = ys.map((y, i) => ({ translate: `0 ${y.toFixed(2)}px`, offset: i / (N - 1) }));
+    sheetAnim = sheetRef ? sheetRef.animate(sheetKf, opts) : null;
+    if (backdropRef) {
+        const kf = ys.map((y, i) => ({ opacity: String(backdropOpacityFor(y)), offset: i / (N - 1) }));
+        backdropAnim = backdropRef.animate(kf, opts);
+    }
+    if (scaleTarget && scaleBackground) {
+        const kf = ys.map((y, i) => ({ ...scalePropsFor(y), offset: i / (N - 1) }));
+        scaleAnim = scaleTarget.animate(kf, opts);
+    }
+    // Finalize on natural completion only. .cancel() (retarget / grab) fires oncancel, not
+    // onfinish, so a superseded animation never runs the callback.
+    if (sheetAnim) {
+        sheetAnim.onfinish = () => {
+            sheetAnim = backdropAnim = scaleAnim = null;
+            onComplete?.();
+        };
+    }
+    else {
+        applyFinal(target);
+        onComplete?.();
+    }
+}
 function doOpen() {
+    // Refresh viewport/container dimensions BEFORE the sheet renders, so its
+    // height (maxSheetHeight) is derived from current values. While the sheet is
+    // closed, windowHeight is not tracked (handleWindowResize is gated on
+    // isVisible), so a resize between opens would otherwise leave the first
+    // render using a stale height — measured sheetHeight then mismatches the
+    // fresh effectiveHeight, shifting the sheet off the bottom edge until the
+    // next open. Doing this before isVisible keeps them in sync.
+    if (typeof window !== 'undefined')
+        windowHeight = window.innerHeight;
+    if (containerRef && constrainToContainer)
+        containerHeight = containerRef.clientHeight;
     isVisible = true;
     isClosing = false;
-    isAnimating = true;
+    backdropPressPointerId = null; // fresh open — ignore any stale backdrop press id
+    applyThemeColor(); // hold the iOS status bar at the page color before the backdrop darkens it
+    applyOverscrollGuard(); // stop the page pull-to-refresh from hijacking a slow drag off an interactive element
     bottomSheetStore.open(id);
     requestAnimationFrame(() => {
         // sheetRef is bound by this rAF tick.
         recalculateDimensions();
-        requestAnimationFrame(() => snapTo(currentSnapPoint, () => {
-            isAnimating = false;
-        }));
+        // Start fully hidden (matches the sheet's initial CSS translate of 100%),
+        // then spring up to the target snap point.
+        currentTranslateY = sheetHeight;
+        renderPosition(sheetHeight);
+        const target = sheetHeight - currentSnapPoint * effectiveHeight;
+        animateTo(target, CONFIG.animation.open, 0);
     });
 }
 function doClose() {
     if (isClosing)
         return;
+    animateSheetClose(0);
+}
+/** Spring the sheet fully down and finalize. `initialVelocity` (px/s) carries a flick-to-dismiss. */
+function animateSheetClose(initialVelocity) {
     isClosing = true;
-    isAnimating = true;
-    snapTo(0, () => {
+    animateTo(sheetHeight, CONFIG.animation.close, initialVelocity, () => {
         isVisible = false;
         isClosing = false;
-        isAnimating = false;
         bottomSheetStore.close(id);
         prevOpen = false;
         open = false;
         resetScaleTarget();
+        restoreThemeColor();
+        restoreOverscrollGuard();
         onClose?.();
         onOpenChange?.(false);
-    });
+    }, true); // hideOnArrival — finalize as soon as it's offscreen, no spring tail
 }
-function snapTo(progress, onComplete) {
-    transitionDuration = calcDynamicDuration();
-    // Calculate translateY: sheet height is maxSnapPoint * effectiveHeight
-    // When progress = maxSnapPoint, translateY = 0 (fully visible)
-    // When progress = 0, translateY = sheetHeight (hidden)
-    const targetTranslateY = sheetHeight - (progress * effectiveHeight);
-    currentTranslateY = targetTranslateY;
-    if (sheetRef) {
-        sheetRef.style.translate = `0 ${targetTranslateY}px`;
-    }
-    updateBackdrop(progress);
-    updateScaleTarget(progress);
-    bottomSheetStore.updateProgress(id, Math.max(0, Math.min(1, progress)));
-    if (onComplete) {
-        setTimeout(onComplete, parseFloat(transitionDuration) * 1000);
+/**
+ * Settle after a drag release: resolve the target snap point, then spring to it
+ * carrying the finger's release velocity so the hand-off is seamless.
+ */
+function settleFromRelease() {
+    const nearestSnap = determineSnapPoint();
+    const releaseVelocity = calculateVelocity() * 1000; // px/ms → px/s (down = positive)
+    if (nearestSnap === 0 && dragToClose) {
+        animateSheetClose(releaseVelocity);
+        return;
     }
+    const snap = nearestSnap > 0 ? nearestSnap : dragState.startSnapPoint;
+    const target = sheetHeight - snap * effectiveHeight;
+    animateTo(target, CONFIG.animation.snap, releaseVelocity, () => {
+        if (!open) {
+            prevOpen = true;
+            open = true;
+            onOpenChange?.(true);
+        }
+    });
 }
 // ============================================
 // VISUAL UPDATES
@@ -232,23 +516,23 @@ function updateBackdrop(progress) {
     const opacity = Math.max(0, Math.min(CONFIG.backdrop.maxOpacity, progress * CONFIG.backdrop.maxOpacity));
     backdropRef.style.opacity = String(opacity);
 }
-function updateScaleTarget(progress, withTransition = true) {
+function updateScaleTarget(progress) {
     if (!scaleTarget || !scaleBackground)
         return;
+    // Static props are set ONCE per open cycle (see primeScaleTarget) — re-writing
+    // transition / transform-origin / overflow / will-change every frame churns the
+    // compositor layer and blows the frame budget on 120Hz displays.
+    primeScaleTarget();
     const p = Math.max(0, Math.min(1, progress));
-    const { factor, borderRadius, translateY, origin } = CONFIG.scale;
+    const { factor, borderRadius, translateY } = CONFIG.scale;
+    // Per-frame: scale + translate are GPU-composited (cheap). Quantize border-radius to
+    // whole px so it only actually repaints ~a dozen times across the gesture, not 120×/s.
     scaleTarget.style.scale = String(1 - factor * p);
-    scaleTarget.style.translate = `0 ${translateY * p}px`;
-    scaleTarget.style.borderRadius = `${borderRadius * p}px`;
-    scaleTarget.style.transformOrigin = origin;
-    scaleTarget.style.overflow = 'hidden';
-    scaleTarget.style.willChange = 'scale, translate, border-radius';
-    if (withTransition) {
-        const { easing } = CONFIG.animation;
-        scaleTarget.style.transition = `scale ${transitionDuration} ${easing}, translate ${transitionDuration} ${easing}, border-radius ${transitionDuration} ${easing}`;
-    }
+    scaleTarget.style.translate = `0 ${(translateY * p).toFixed(2)}px`;
+    scaleTarget.style.borderRadius = `${Math.round(borderRadius * p)}px`;
 }
 function resetScaleTarget() {
+    scaleTargetPrimed = false;
     if (!scaleTarget || !scaleBackground)
         return;
     scaleTarget.style.scale = '';
@@ -260,6 +544,66 @@ function resetScaleTarget() {
     scaleTarget.style.willChange = '';
 }
 // ============================================
+// BROWSER CHROME (iOS status-bar tint)
+// ============================================
+function isTransparentColor(color) {
+    return !color || color === 'transparent' || color === 'rgba(0, 0, 0, 0)';
+}
+/** First opaque background up the page root — what iOS Safari samples for the status bar. */
+function resolvePageBackgroundColor() {
+    if (typeof document === 'undefined')
+        return '#ffffff';
+    for (const el of [document.body, document.documentElement]) {
+        if (!el)
+            continue;
+        const bg = getComputedStyle(el).backgroundColor;
+        if (!isTransparentColor(bg))
+            return bg;
+    }
+    return '#ffffff';
+}
+/**
+ * Keep the iOS Safari status bar immersive while the sheet is open. Acts ONLY when the page
+ * declares no <meta name="theme-color"> — the case Safari resolves by sampling the now-darkened
+ * backdrop and flipping the bar dark: we add one pinned to the page background (theme-aware,
+ * so it also tracks dark mode). A page that sets its own theme-color owns its status bar and
+ * is left untouched. restoreThemeColor removes ours on close.
+ */
+function applyThemeColor() {
+    if (!syncThemeColor || typeof document === 'undefined' || themeColorMeta)
+        return;
+    if (document.querySelector('meta[name="theme-color"]'))
+        return;
+    const meta = document.createElement('meta');
+    meta.name = 'theme-color';
+    meta.setAttribute('content', resolvePageBackgroundColor());
+    document.head.appendChild(meta);
+    themeColorMeta = meta;
+}
+/** Remove the theme-color tag we added on open (no-op if we never added one). */
+function restoreThemeColor() {
+    themeColorMeta?.remove();
+    themeColorMeta = null;
+}
+/**
+ * Guard the page against native pull-to-refresh while this sheet is open (see the module
+ * script). Balanced + idempotent per instance so the shared reference count stays correct
+ * even though restore fires from both the close completion and onDestroy.
+ */
+function applyOverscrollGuard() {
+    if (!preventPullToRefresh || heldOverscrollGuard)
+        return;
+    heldOverscrollGuard = true;
+    acquireOverscrollGuard();
+}
+/** Release this sheet's hold on the page overscroll guard (no-op if not held). */
+function restoreOverscrollGuard() {
+    if (!heldOverscrollGuard)
+        return;
+    heldOverscrollGuard = false;
+    releaseOverscrollGuard();
+}
+// ============================================
 // GESTURE UTILITIES
 // ============================================
 function pushHistory(y) {
@@ -282,23 +626,15 @@ function calculateVelocity() {
     const dt = last.time - first.time;
     return dt > 0 ? (last.y - first.y) / dt : 0;
 }
-function calcDynamicDuration() {
-    const now = performance.now();
-    const recent = dragState.history.filter(p => now - p.time <= 100);
-    if (recent.length < 2)
-        return `${CONFIG.animation.defaultDuration}s`;
-    const first = recent[0];
-    const last = recent[recent.length - 1];
-    if (!first || !last)
-        return `${CONFIG.animation.defaultDuration}s`;
-    const speed = Math.abs((last.y - first.y) / (last.time - first.time));
-    const { minDuration, maxDuration } = CONFIG.animation;
-    let duration = maxDuration - (speed / 2) * (maxDuration - minDuration);
-    duration = Math.max(minDuration, Math.min(maxDuration, duration));
-    return `${duration}s`;
-}
-function overdragResistance(value) {
-    return value < 0 ? -Math.pow(Math.abs(value), CONFIG.gesture.overdragExponent) : value;
+function clampAboveMaxSnap(translateY) {
+    // The sheet is only as tall as its MAX snap point, with its bottom pinned to the
+    // screen bottom (translateY 0 == fully open to max). Letting translateY go below
+    // that (negative) would lift the sheet's bottom edge off the screen and reveal the
+    // background in the gap beneath it — which looks broken. So pin it: you cannot drag
+    // the sheet frame above its largest detent. This is also what native iOS does — the
+    // frame is firm at the top detent; only inner scroll content overscrolls.
+    const topLimit = sheetHeight - maxSnapPoint * effectiveHeight;
+    return translateY < topLimit ? topLimit : translateY;
 }
 function applyLockedDragResistance(rawTranslateY) {
     // Base translateY when at start snap point: sheetHeight - (startSnapPoint * effectiveHeight)
@@ -365,6 +701,15 @@ function isInteractive(target) {
 function shouldIgnoreDrag(target) {
     return !!target.closest('[data-bottom-sheet-no-drag]');
 }
+/**
+ * Resolve the scrollable region ([data-bottom-sheet-scroll]) that contains the
+ * gesture target. Resolved per-gesture (not once at open-time) so that content
+ * mounted lazily after the sheet opened — and nested/multiple scroll regions —
+ * are detected correctly. Returns the nearest scrollable ancestor, or null.
+ */
+function getScrollableFromTarget(target) {
+    return target.closest('[data-bottom-sheet-scroll]');
+}
 /**
  * Install a one-shot capture-phase click listener to suppress the ghost click
  * that fires after a committed drag from an interactive element.
@@ -415,7 +760,7 @@ function commitToDrag(clientY) {
     dragState.currentY = currentTranslateY;
     clearHistory();
     pushHistory(clientY);
-    transitionDuration = '0s';
+    interruptAnimation();
     if (scaleTarget)
         scaleTarget.style.transition = 'none';
     isDragging = true;
@@ -458,7 +803,9 @@ function handleTouchStart(e) {
         return;
     const target = e.target;
     const inDraggableArea = isInDraggableArea(target);
-    const inScrollable = !!target.closest('[data-bottom-sheet-scroll]');
+    // Resolve scrollable region from the actual target so lazily-mounted content is detected.
+    scrollableElement = getScrollableFromTarget(target);
+    const inScrollable = !!scrollableElement;
     const isInteractiveTarget = isInteractive(target);
     // data-bottom-sheet-no-drag: treat as fully default element — no tracking at all
     if (shouldIgnoreDrag(target) && !inDraggableArea) {
@@ -484,8 +831,8 @@ function handleTouchStart(e) {
         dragState.committed = false;
         dragState.inScrollable = inScrollable;
         dragState.shouldPreventScroll = true; // Will be used if we commit
-        // Do NOT set isDragging, transitionDuration, or disable transitions
-        // Do NOT call e.preventDefault() — allow native touch behavior until committed
+        // Do NOT set isDragging or interrupt the animation yet — allow native
+        // touch behavior until the gesture commits, and don't call e.preventDefault().
         return;
     }
     // Non-interactive element: immediately commit to dragging (existing behavior)
@@ -493,7 +840,7 @@ function handleTouchStart(e) {
     dragState.isInteractiveStart = false;
     dragState.committed = true;
     dragState.shouldPreventScroll = !(inScrollable && isScrolledToTop && !inDraggableArea);
-    transitionDuration = '0s';
+    interruptAnimation();
     if (scaleTarget)
         scaleTarget.style.transition = 'none';
     isDragging = true;
@@ -525,7 +872,26 @@ function handleTouchMove(e) {
             dragState.isInteractiveStart = false;
             return;
         }
-        // Still pending — do nothing, let native behavior continue
+        // Still pending (under the commit threshold). Claim a downward, vertical-leaning pull
+        // NOW so iOS Safari can't start its native pull-to-refresh during this slow pre-commit
+        // window — overscroll-behavior does NOT stop Safari's UA refresh; only preventDefault
+        // does. Stay PENDING (the sheet doesn't start moving until the >=10px commit), but deny
+        // the browser the gesture. Skip when a scroll region under the finger should scroll
+        // instead (pulling down while not at its top), and skip horizontal-leaning moves so
+        // native sliders keep working. Touch-only: desktop has no pull-to-refresh.
+        const claimDx = Math.abs(clientX - dragState.startX);
+        const claimDy = Math.abs(clientY - dragState.startY);
+        if (clientY - dragState.startY > 0 && claimDy >= CONFIG.gesture.pullClaimThreshold && claimDy >= claimDx) {
+            let claimGesture = true;
+            if (dragState.inScrollable) {
+                if (scrollableElement)
+                    isScrolledToTop = scrollableElement.scrollTop <= 1;
+                if (!isScrolledToTop)
+                    claimGesture = false; // let the content scroll natively
+            }
+            if (claimGesture && e.cancelable)
+                e.preventDefault();
+        }
         return;
     }
     // ── Normal drag logic (committed) ──
@@ -541,18 +907,12 @@ function handleTouchMove(e) {
         return;
     e.preventDefault();
     let translateY = dragState.currentY + moveDelta;
-    if (translateY < 0)
-        translateY = overdragResistance(translateY);
+    translateY = clampAboveMaxSnap(translateY);
     if (!dragToClose)
         translateY = applyLockedDragResistance(translateY);
     translateY = Math.min(translateY, sheetHeight);
     currentTranslateY = translateY;
-    if (sheetRef)
-        sheetRef.style.translate = `0 ${translateY}px`;
-    const progress = Math.max(0, Math.min(maxSnapPoint, (sheetHeight - translateY) / effectiveHeight));
-    updateBackdrop(progress);
-    updateScaleTarget(progress, false);
-    bottomSheetStore.updateProgress(id, progress);
+    renderPosition(translateY);
 }
 function handleTouchEnd(e) {
     if (e.touches.length > 0 || !dragState.isTouchActive)
@@ -574,19 +934,7 @@ function handleTouchEnd(e) {
     }
     isDragging = false;
     dragState.shouldPreventScroll = false;
-    const nearestSnap = determineSnapPoint();
-    if (nearestSnap === 0 && dragToClose) {
-        doClose();
-    }
-    else {
-        snapTo(nearestSnap > 0 ? nearestSnap : dragState.startSnapPoint, () => {
-            if (!open) {
-                prevOpen = true;
-                open = true;
-                onOpenChange?.(true);
-            }
-        });
-    }
+    settleFromRelease();
 }
 // ============================================
 // POINTER EVENT HANDLERS (Desktop)
@@ -596,7 +944,9 @@ function handlePointerDown(e) {
         return;
     const target = e.target;
     const inDraggableArea = isInDraggableArea(target);
-    const inScrollable = !!target.closest('[data-bottom-sheet-scroll]');
+    // Resolve scrollable region from the actual target so lazily-mounted content is detected.
+    scrollableElement = getScrollableFromTarget(target);
+    const inScrollable = !!scrollableElement;
     const isInteractiveTarget = isInteractive(target);
     const shouldIgnoreDragTarget = shouldIgnoreDrag(target);
     // data-bottom-sheet-no-drag: treat as fully default element — no tracking at all
@@ -624,7 +974,7 @@ function handlePointerDown(e) {
     dragState.isPending = false;
     dragState.isInteractiveStart = false;
     dragState.committed = true;
-    transitionDuration = '0s';
+    interruptAnimation();
     if (scaleTarget)
         scaleTarget.style.transition = 'none';
     sheetRef?.setPointerCapture(e.pointerId);
@@ -665,18 +1015,12 @@ function handlePointerMove(e) {
     dragState.lastY = clientY;
     pushHistory(clientY);
     let translateY = dragState.currentY + clientY - dragState.startY;
-    if (translateY < 0)
-        translateY = overdragResistance(translateY);
+    translateY = clampAboveMaxSnap(translateY);
     if (!dragToClose)
         translateY = applyLockedDragResistance(translateY);
     translateY = Math.min(translateY, sheetHeight);
     currentTranslateY = translateY;
-    if (sheetRef)
-        sheetRef.style.translate = `0 ${translateY}px`;
-    const progress = Math.max(0, Math.min(maxSnapPoint, (sheetHeight - translateY) / effectiveHeight));
-    updateBackdrop(progress);
-    updateScaleTarget(progress, false);
-    bottomSheetStore.updateProgress(id, progress);
+    renderPosition(translateY);
     e.preventDefault();
 }
 function handlePointerUp(e) {
@@ -701,19 +1045,7 @@ function handlePointerUp(e) {
     if (!isDragging)
         return;
     isDragging = false;
-    const nearestSnap = determineSnapPoint();
-    if (nearestSnap === 0 && dragToClose) {
-        doClose();
-    }
-    else {
-        snapTo(nearestSnap > 0 ? nearestSnap : dragState.startSnapPoint, () => {
-            if (!open) {
-                prevOpen = true;
-                open = true;
-                onOpenChange?.(true);
-            }
-        });
-    }
+    settleFromRelease();
 }
 function handlePointerCancel(e) {
     if (e.pointerType === 'touch' || dragState.activePointerId !== e.pointerId)
@@ -733,14 +1065,28 @@ function handlePointerCancel(e) {
     if (!isDragging)
         return;
     isDragging = false;
-    snapTo(findNearestSnapPoint(currentTranslateY, 0));
+    // No velocity on cancel — settle to the nearest snap point at rest.
+    const target = sheetHeight - findNearestSnapPoint(currentTranslateY, 0) * effectiveHeight;
+    animateTo(target, CONFIG.animation.snap, 0);
 }
 function handleCloseButtonClick(e) {
     e.stopPropagation();
     doClose();
 }
+function handleBackdropPointerDown(e) {
+    // Record a press that begins ON the backdrop (and only the backdrop). Used to tell
+    // a deliberate backdrop tap apart from the ghost pointerup described below.
+    backdropPressPointerId = e.target === backdropRef ? e.pointerId : null;
+}
 function handleBackdropClick(e) {
-    if (!closeOnBackdrop || e.target !== backdropRef || isDragging || isAnimating)
+    // Dismiss only when THIS press both started and ended on the backdrop. Gating on the
+    // press origin (not an isAnimating timer) keeps a deliberate tap instant — even mid
+    // open-animation — while ignoring the stray release that fires when a press begun
+    // elsewhere lifts over a just-mounted backdrop (e.g. long-press a button to open the
+    // sheet, then release: that pointerup lands on the backdrop but never pressed it).
+    const startedOnBackdrop = backdropPressPointerId === e.pointerId;
+    backdropPressPointerId = null;
+    if (!closeOnBackdrop || e.target !== backdropRef || isDragging || !startedOnBackdrop)
         return;
     doClose();
 }
@@ -763,85 +1109,101 @@ function touchEvents(node) {
         }
     };
 }
-</script>
-
-<svelte:window onkeydown={handleKeydown}/>
-
-{#if isVisible}
-    <!-- Backdrop -->
-    <!-- svelte-ignore a11y_no_static_element_interactions -->
-    <div
-            bind:this={backdropRef}
-            class={r.backdrop()}
-            style:z-index={zIndex}
-            style:--transition-duration={transitionDuration}
-            onpointerup={handleBackdropClick}
-    ></div>
-
-    <!-- Sheet -->
-    <!-- svelte-ignore a11y_no_static_element_interactions -->
-    <div
-            bind:this={sheetRef}
-            class={r.sheet()}
-            style:z-index={zIndex + 1}
-            style:height="{maxSheetHeight}px"
-            style:--transition-duration={transitionDuration}
-            role="dialog"
-            aria-modal="true"
-            tabindex={-1}
-            use:touchEvents
-            onpointerdown={handlePointerDown}
-            onpointermove={handlePointerMove}
-            onpointerup={handlePointerUp}
-            onpointercancel={handlePointerCancel}
-    >
-        <!-- Drag Handle -->
-        <div class={r.handle()} data-bottom-sheet-handle>
-            <div class={r.handleBar()}></div>
-        </div>
-
-        <!-- Header -->
-        {#if header}
-            <div class={r.header()} data-bottom-sheet-header>
-                {@render header()}
-                {#if showCloseButton}
-                    <button
-                            class={r.closeButton()}
-                            data-bottom-sheet-close
-                            onclick={handleCloseButtonClick}
-                            aria-label="Close"
-                            type="button"
-                    >
-                        <IconX class="size-4"/>
-                    </button>
-                {/if}
-            </div>
-        {/if}
-
-        <!-- Content -->
-        <div bind:this={contentRef} class={r.content()} data-bottom-sheet-content>
-            {#if children}
-                {@render children()}
-            {/if}
-        </div>
-    </div>
-{/if}
-
-<style>
-    /* Consumer-marked scroll region inside the sheet body. */
-    [data-bottom-sheet-content] :global([data-bottom-sheet-scroll]) {
-        flex: 1;
-        overflow-y: auto;
-        overflow-x: hidden;
-        overscroll-behavior: contain;
-        -webkit-overflow-scrolling: touch;
-        min-height: 0;
-        touch-action: pan-y;
-    }
-
-    /* Suppress native gestures on header children so the drag is captured. */
-    [data-bottom-sheet-header] :global(*) {
-        touch-action: none;
-        user-select: none;
-    }
-</style>
+</script>
+
+<svelte:window onkeydown={handleKeydown}/>
+
+{#if isVisible}
+    <!-- Backdrop -->
+    <!-- svelte-ignore a11y_no_static_element_interactions -->
+    <div
+            bind:this={backdropRef}
+            class={r.backdrop()}
+            style:z-index={zIndex}
+            onpointerdown={handleBackdropPointerDown}
+            onpointerup={handleBackdropClick}
+    ></div>
+
+    <!-- Sheet -->
+    <!-- svelte-ignore a11y_no_static_element_interactions -->
+    <div
+            bind:this={sheetRef}
+            class={r.sheet()}
+            style:z-index={zIndex + 1}
+            style:height="{maxSheetHeight}px"
+            data-bottom-sheet-surface
+            role="dialog"
+            aria-modal="true"
+            tabindex={-1}
+            use:touchEvents
+            onpointerdown={handlePointerDown}
+            onpointermove={handlePointerMove}
+            onpointerup={handlePointerUp}
+            onpointercancel={handlePointerCancel}
+    >
+        <!-- Drag Handle -->
+        <div class={r.handle()} data-bottom-sheet-handle>
+            <div class={r.handleBar()}></div>
+        </div>
+
+        <!-- Header -->
+        {#if header}
+            <div class={r.header()} data-bottom-sheet-header>
+                {@render header()}
+                {#if showCloseButton}
+                    <button
+                            class={r.closeButton()}
+                            data-bottom-sheet-close
+                            onclick={handleCloseButtonClick}
+                            aria-label="Close"
+                            type="button"
+                    >
+                        <IconX class="size-4"/>
+                    </button>
+                {/if}
+            </div>
+        {/if}
+
+        <!-- Content -->
+        <div bind:this={contentRef} class={r.content()} data-bottom-sheet-content>
+            {#if children}
+                {@render children()}
+            {/if}
+        </div>
+    </div>
+{/if}
+
+<style>
+    /* Consumer-marked scroll region inside the sheet body. */
+    [data-bottom-sheet-content] :global([data-bottom-sheet-scroll]) {
+        flex: 1;
+        overflow-y: auto;
+        overflow-x: hidden;
+        overscroll-behavior: contain;
+        -webkit-overflow-scrolling: touch;
+        min-height: 0;
+        touch-action: pan-y;
+    }
+
+    /* Suppress native gestures on header children so the drag is captured. */
+    [data-bottom-sheet-header] :global(*) {
+        touch-action: none;
+        user-select: none;
+    }
+
+    /* Extend the sheet's own surface below its bottom edge. The sheet is only as tall as
+       its max snap point; if it ever sits a hair above the screen bottom — the open spring's
+       slight overshoot, or sub-pixel rounding — this keeps the sliver beneath it sheet-colored
+       instead of letting the background show through. The sheet is overflow-visible so this is
+       not clipped, and it rides along with the sheet's transform. */
+    :global([data-bottom-sheet-surface]::after) {
+        content: '';
+        position: absolute;
+        top: 100%;
+        left: 0;
+        right: 0;
+        height: 100%;
+        background-color: inherit;
+        pointer-events: none;
+    }
+</style>