@surdeddd/bottom-sheet 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -22,6 +22,18 @@ var SheetStack = class {
     this.entries.splice(idx, 1);
     this.recompute();
   }
+  promote(id) {
+    const idx = this.entries.findIndex((e) => e.id === id);
+    if (idx === -1) return;
+    if (idx !== this.entries.length - 1) {
+      const [entry] = this.entries.splice(idx, 1);
+      this.entries.push(entry);
+    }
+    this.recompute();
+  }
+  update() {
+    this.recompute();
+  }
   size() {
     return this.entries.length;
   }
@@ -29,9 +41,24 @@ var SheetStack = class {
     this.entries = [];
   }
   recompute() {
+    let top = null;
+    const open = [];
+    for (const entry of this.entries) {
+      if (!entry.isOpen || entry.isOpen()) {
+        top = entry;
+        open.push(entry);
+      }
+    }
+    if (!top && this.entries.length > 0) {
+      top = this.entries[this.entries.length - 1];
+    }
     this.entries.forEach((entry, i) => {
       entry.setZIndex(BASE_Z + i * STEP);
-      entry.setIsTop(i === this.entries.length - 1);
+      entry.setIsTop(entry === top);
+      if (entry.setDepth) {
+        const openIdx = open.indexOf(entry);
+        entry.setDepth(openIdx === -1 ? 0 : open.length - 1 - openIdx);
+      }
     });
   }
 };
@@ -236,11 +263,6 @@ var SnapResolver = class {
     this.allowedIds = allowed ?? raw.map((p) => p.id);
     this.recompute();
   }
-  /**
-   * Re-resolve raw → resolved against the current viewport / fit-measure,
-   * recompute maxAxisSize, invalidate range cache, notify engine. Called on
-   * resize, orientationchange, visualViewport changes, and snap-list swaps.
-   */
   recompute() {
     this.resolved = resolveSnapList(this.raw, this.mode, this.measureFit);
     this.maxAxisSize = this.resolved.reduce(
@@ -250,15 +272,10 @@ var SnapResolver = class {
     this.rangeCache = null;
     this.onMaxAxisSizeChange?.(this.maxAxisSize);
   }
-  /** Replace the raw snap list and recompute. Engine calls on `setSnapPoints`. */
   setRaw(raw) {
     this.raw = raw;
     this.recompute();
   }
-  /**
-   * Replace the allow-list. Range cache depends on `(resolvedSnaps ×
-   * allowedIds)` so flipping ids alone invalidates without a full recompute.
-   */
   setAllowedIds(ids) {
     this.allowedIds = ids;
     this.rangeCache = null;
@@ -266,11 +283,6 @@ var SnapResolver = class {
   findById(id) {
     return findById(id, this.resolved);
   }
-  /**
-   * Pure drag-settle target resolution. Engine passes the gesture-specific
-   * fields (delta, velocity, pointerKind, flickVelocity, dragThreshold) plus
-   * `size`/`activeId` since those are still engine-owned.
-   */
   findDragSettleTarget(args) {
     return findDragSettleTarget({
       ...args,
@@ -279,18 +291,9 @@ var SnapResolver = class {
       maxAxisSize: this.maxAxisSize
     });
   }
-  /**
-   * Memoised allowed-range query. Twice-per-drag-frame (gesture onMove +
-   * applySize→computeProgress); cache collapses 2× iteration of resolvedSnaps
-   * to one recompute per geometry/allow-list change.
-   */
   getAllowedRange() {
     return this.rangeCache ?? (this.rangeCache = allowedRange(this.resolved, this.allowedIds));
   }
-  /**
-   * Read-only view of resolved snaps. Returned as `readonly` to discourage
-   * accidental mutation by feature install sites that close over this list.
-   */
   getResolvedSnaps() {
     return this.resolved;
   }
@@ -300,18 +303,6 @@ var SnapResolver = class {
   getMaxAxisSize() {
     return this.maxAxisSize;
   }
-  /**
-   * External clamp override. The resize-observer feature compares
-   * `getMaxAxisSize()` against the live viewport and shrinks if the largest
-   * resolved snap exceeds it (mobile address-bar collapse / soft-keyboard
-   * window resize). The next `recompute()` overwrites this clamp from the
-   * resolved-snap reduction.
-   *
-   * Does NOT invalidate the range cache — viewport clamping doesn't change
-   * `(resolvedSnaps × allowedIds) → range`. DOES fire `onMaxAxisSizeChange`
-   * so the resolver owns the layout-axis style write end-to-end (symmetric
-   * with `recompute()` — feature call sites no longer duplicate the write).
-   */
   setMaxAxisSize(n) {
     this.maxAxisSize = n;
     this.onMaxAxisSizeChange?.(n);
@@ -358,14 +349,17 @@ function installAutoCollapse(deps) {
   const fire = () => {
     if (deps.isDestroyed()) return;
     if (deps.isDragging()) return;
-    const allowed = deps.getAllowedIds();
-    const target = allowed.find((id) => {
+    const active = deps.resolveSnap(deps.getActiveId());
+    if (!active || active.size === 0) return;
+    let target = null;
+    for (const id of deps.getAllowedIds()) {
       const snap = deps.resolveSnap(id);
-      return snap !== null && snap.size > 0;
-    });
+      if (!snap || snap.size <= 0) continue;
+      if (!target || snap.size < target.size) target = snap;
+    }
     if (!target) return;
-    if (target === deps.getActiveId()) return;
-    deps.snapTo(target);
+    if (target.id === active.id || target.size >= active.size) return;
+    deps.snapTo(target.id);
   };
   const reset = () => {
     clearTimer();
@@ -376,6 +370,7 @@ function installAutoCollapse(deps) {
     }, ms);
   };
   const unsubscribe = deps.on("snap", () => reset());
+  if ((deps.resolveSnap(deps.getActiveId())?.size ?? 0) > 0) reset();
   return () => {
     clearTimer();
     unsubscribe();
@@ -388,6 +383,7 @@ function notifyLinkedSheets(sheets, self) {
   for (const linked of sheets) {
     if (linked === self) continue;
     try {
+      if (linked.state.size === 0) continue;
       const ids = linked.getAllowedIds();
       const target = ids.find((id) => id !== "closed");
       if (target && target !== linked.state.activeId) {
@@ -434,7 +430,7 @@ function installRoute(deps) {
       const onPop = (event) => {
         if (deps.isDestroyed()) return;
         const state = event.state;
-        if (state && state.__bsRouted === target && deps.getSize() > 0) {
+        if ((!state || state.__bsRouted !== target) && deps.getSize() > 0) {
           routePushed = false;
           void deps.close();
         }
@@ -588,13 +584,17 @@ function installResizeObserver(deps) {
     if (viewportSize2 > 0 && viewportSize2 < max) {
       deps.setMaxAxisSize(viewportSize2);
     }
+    const wasAnimating = deps.isAnimating?.() ?? false;
     deps.cancelInFlight();
     deps.newCycle();
     const current = deps.resolveActiveSnap();
     const newMax = deps.getMaxAxisSize();
     const targetSize = current ? Math.min(current.size, newMax) : Math.min(deps.getSize(), newMax);
     deps.setSize(targetSize);
-    if (current && !deps.isDragging()) deps.applySize(targetSize);
+    if (current && !deps.isDragging()) {
+      deps.applySize(targetSize);
+      if (wasAnimating) deps.resyncAfterCancel?.();
+    }
   };
   let resizeObserver = null;
   if (typeof ResizeObserver !== "undefined") {
@@ -686,73 +686,130 @@ var WriteSentinel = class {
   constructor() {
     __publicField(this, "last", -1);
   }
-  /**
-   * Returns `true` (and updates the cached value) if `next` differs from the
-   * cached `last` by more than `epsilon`. Returns `false` (and leaves the
-   * cache untouched) when the delta is within epsilon — caller skips the
-   * CSSOM write.
-   */
   shouldWrite(next, epsilon) {
     if (Math.abs(next - this.last) <= epsilon) return false;
     this.last = next;
     return true;
   }
-  /**
-   * Force the next `shouldWrite` to pass. Resets the cache to `-1` so any
-   * non-negative `next` exceeds the epsilon comparison. Called from setters
-   * that mutate state under the cache (range/mode/enabled flips that change
-   * the progress→opacity mapping but don't move `progress` itself).
-   */
   invalidate() {
     this.last = -1;
   }
-  /**
-   * Record `value` as the last-written without performing a write. Used
-   * when a setter writes a literal value through a different path (e.g.
-   * `setScrimMode("off")` writes `opacity: "0"` inline) and wants future
-   * `shouldWrite` calls to short-circuit against that known cached state.
-   */
   setLastWritten(value) {
     this.last = value;
   }
-  /** Read-only accessor for diagnostic / dedup-aware peek. */
   get value() {
     return this.last;
   }
 };
 
+// src/core/primitives/devWarn.ts
+function devWarn(...args) {
+  if (typeof process !== "undefined" && process.env && process.env.NODE_ENV !== "production" && typeof console !== "undefined") {
+    console.warn(...args);
+  }
+}
+
+// src/core/primitives/overlay-position.ts
+function resolveSheetAnchoredStyle(mode, position, inset) {
+  const sizeOffset = `calc(var(--bs-size, 0px) + ${inset})`;
+  switch (mode) {
+    case "bottom":
+      if (position === "sheet-top-left") return { bottom: sizeOffset, left: inset };
+      if (position === "sheet-top-right") return { bottom: sizeOffset, right: inset };
+      return { bottom: sizeOffset, left: "50%", transform: "translateX(-50%)" };
+    case "top":
+      if (position === "sheet-top-left") return { top: sizeOffset, left: inset };
+      if (position === "sheet-top-right") return { top: sizeOffset, right: inset };
+      return { top: sizeOffset, left: "50%", transform: "translateX(-50%)" };
+    case "left":
+      if (position === "sheet-top-left") return { left: sizeOffset, top: inset };
+      if (position === "sheet-top-right") return { left: sizeOffset, bottom: inset };
+      return { left: sizeOffset, top: "50%", transform: "translateY(-50%)" };
+    case "right":
+      if (position === "sheet-top-left") return { right: sizeOffset, top: inset };
+      if (position === "sheet-top-right") return { right: sizeOffset, bottom: inset };
+      return { right: sizeOffset, top: "50%", transform: "translateY(-50%)" };
+  }
+}
+function applyOverlayPosition(ws, mode, position, inset) {
+  switch (position) {
+    case "top-left":
+      ws.top = inset;
+      ws.left = inset;
+      break;
+    case "top-center":
+      ws.top = inset;
+      ws.left = "50%";
+      ws.transform = "translateX(-50%)";
+      break;
+    case "top-right":
+      ws.top = inset;
+      ws.right = inset;
+      break;
+    case "center-left":
+      ws.top = "50%";
+      ws.left = inset;
+      ws.transform = "translateY(-50%)";
+      break;
+    case "center":
+      ws.top = "50%";
+      ws.left = "50%";
+      ws.transform = "translate(-50%, -50%)";
+      break;
+    case "center-right":
+      ws.top = "50%";
+      ws.right = inset;
+      ws.transform = "translateY(-50%)";
+      break;
+    case "bottom-left":
+      ws.bottom = inset;
+      ws.left = inset;
+      break;
+    case "bottom-center":
+      ws.bottom = inset;
+      ws.left = "50%";
+      ws.transform = "translateX(-50%)";
+      break;
+    case "bottom-right":
+      ws.bottom = inset;
+      ws.right = inset;
+      break;
+    case "sheet-top-left":
+    case "sheet-top-center":
+    case "sheet-top-right": {
+      const style = resolveSheetAnchoredStyle(mode, position, inset);
+      if (style.top !== void 0) ws.top = style.top;
+      if (style.bottom !== void 0) ws.bottom = style.bottom;
+      if (style.left !== void 0) ws.left = style.left;
+      if (style.right !== void 0) ws.right = style.right;
+      if (style.transform !== void 0) ws.transform = style.transform;
+      break;
+    }
+  }
+}
+
 // src/core/controllers/scrim-controller.ts
+var VALID_CSS_LENGTH = /^-?\d+(?:\.\d+)?(?:px|em|rem|%)$/;
 var ScrimController = class {
   constructor(deps, opts) {
-    // ── DOM refs (mirror engine's; cached for hot path) ─────────────────
     __publicField(this, "screenComponent");
     __publicField(this, "backdrop");
     __publicField(this, "mode");
-    // ── Engine callbacks ────────────────────────────────────────────────
     __publicField(this, "isDestroyed");
     __publicField(this, "isTopSheet");
     __publicField(this, "getAllowedIds");
     __publicField(this, "getResolvedSnaps");
     __publicField(this, "snapToFn");
-    // ── Mode + state ────────────────────────────────────────────────────
+    __publicField(this, "closeFn");
+    __publicField(this, "scrimInteractive", false);
     __publicField(this, "scrimMode");
     __publicField(this, "backdropRange");
     __publicField(this, "screenRange");
-    // setScrimEnabled toggle — gated through `scrimEnabled` rather than nuking
-    // ranges so re-enable can restore prior values without a remount. Public
-    // so tests / introspection can read it without an `as any` cast.
     __publicField(this, "scrimEnabled", true);
     __publicField(this, "savedScrimRanges", null);
-    // ── Tap-to-close ────────────────────────────────────────────────────
     __publicField(this, "scrimTapToCloseEnabled", false);
     __publicField(this, "detachScrimTap", null);
-    // ── Scrim overlay slot (positioned floating element) ────────────────
     __publicField(this, "scrimOverlayTeardown", null);
-    // ── Hot-path opacity dedup caches (per-frame writes) ────────────────
-    // Numeric sentinels migrated to WriteSentinel primitive — single
-    // invalidation surface, shared with the engine's size/progress sentinels.
-    // The two string-typed sentinels (`Pointer`, `Display`) keep their inline
-    // pattern: equality on string union, no epsilon, different reset semantics.
     __publicField(this, "backdropOpacitySentinel", new WriteSentinel());
     __publicField(this, "screenOpacitySentinel", new WriteSentinel());
     __publicField(this, "lastBackdropPointer", "");
@@ -765,6 +822,7 @@ var ScrimController = class {
     this.getAllowedIds = deps.getAllowedIds;
     this.getResolvedSnaps = deps.getResolvedSnaps;
     this.snapToFn = deps.snapTo;
+    this.closeFn = deps.close;
     this.scrimMode = opts.scrimMode ?? "full";
     const preset = opts.scrimPreset ? SCRIM_PRESETS[opts.scrimPreset] : null;
     this.backdropRange = opts.backdropRange ?? preset?.range ?? [0, 1];
@@ -787,41 +845,15 @@ var ScrimController = class {
       }
     }
   }
-  /**
-   * Invalidate the opacity dedup caches. Called from any setter that mutates
-   * range/mode/enabled — opacity is a pure function of (progress, range,
-   * enabled), so a config change makes the cached values stale even if
-   * `progress` itself didn't move. Next `applyOpacity(progress, false)` call
-   * sees the -1 sentinel and re-runs the math instead of short-circuiting.
-   *
-   * Public for the engine: `setSnapPoints` mutates resolved geometry which
-   * shifts `progress→opacity` mapping under the cache; engine calls this to
-   * keep the next render frame correct on a static sheet.
-   * @internal
-   */
   invalidateOpacityCache() {
     this.backdropOpacitySentinel.invalidate();
     this.screenOpacitySentinel.invalidate();
   }
-  /** Engine calls this when its `attach()` runs — installs scrim-tap-click if requested. */
   attach() {
     if (this.scrimTapToCloseEnabled) {
       this.setScrimTapToClose(true);
     }
   }
-  // ── Hot-path: opacity computation called per-frame from engine.applySize ──
-  /**
-   * Per-frame opacity writer. Computes backdrop + screen opacity from the
-   * sheet's progress (0..1 within allowed range), gated by sub-pixel dedup
-   * caches so steady-state frames don't trigger style recalc.
-   *
-   * `progressChanged` is the engine's already-computed dedup gate — when
-   * `false`, opacity is by construction a pure function of `progress` so
-   * cached values are still valid; we short-circuit the Math.min/max +
-   * division work entirely. Setters that mutate ranges/mode/enabled
-   * invalidate the cache by writing -1 sentinels so the next call re-runs
-   * the math.
-   */
   applyOpacity(progress, progressChanged) {
     if (!progressChanged && this.backdropOpacitySentinel.value !== -1 && this.screenOpacitySentinel.value !== -1) {
       return;
@@ -867,80 +899,30 @@ var ScrimController = class {
       }
     }
   }
-  // ── Public setters (engine forwards these 1:1) ─────────────────────
-  /**
-   * Replace the [start, end] progress window in which the backdrop fades 0→1.
-   * @param range - Tuple of two progress values in 0..1 (start <= end).
-   * @param applySize - Engine-supplied recompute hook; runs one applyOpacity pass.
-   * @example
-   *   // Backdrop only starts darkening after the sheet crosses 30% open.
-   *   engine.setBackdropRange([0.3, 1]);
-   */
   setBackdropRange(range, applySize) {
     if (this.isDestroyed()) return;
     this.backdropRange = range;
     this.invalidateOpacityCache();
     applySize();
   }
-  /**
-   * Replace the [start, end] progress window in which the screen scrim fades 0→1.
-   * @param range - Tuple of two progress values in 0..1 (start <= end).
-   * @param applySize - Engine-supplied recompute hook; runs one applyOpacity pass.
-   * @example
-   *   // Scrim is fully opaque only when the sheet is past 50% — softer feel.
-   *   engine.setScreenRange([0, 0.5]);
-   */
   setScreenRange(range, applySize) {
     if (this.isDestroyed()) return;
     this.screenRange = range;
     this.invalidateOpacityCache();
     applySize();
   }
-  /**
-   * Set the scrim background color. Pass `null`/`undefined` to clear the
-   * inline write and let consumer CSS take over.
-   * @param color - Any valid CSS color string, or `null`/`undefined` to clear.
-   * @example
-   *   engine.setScrimColor("rgba(0, 0, 0, 0.6)");
-   *   engine.setScrimColor(null); // hand back to consumer CSS
-   */
   setScrimColor(color) {
     if (this.isDestroyed()) return;
     this.applyScrimStyles({ color: color === void 0 ? null : color });
   }
-  /**
-   * Set the scrim backdrop-filter blur radius. Pass `null`/`undefined` to clear.
-   * @param blur - CSS length (e.g. `"8px"`) consumed as `blur(<value>)`, or
-   *               `null`/`undefined` to remove the filter.
-   * @example
-   *   engine.setScrimBlur("12px"); // frosted-glass effect
-   *   engine.setScrimBlur(null);    // disable blur
-   */
   setScrimBlur(blur) {
     if (this.isDestroyed()) return;
     this.applyScrimStyles({ blur: blur === void 0 ? null : blur });
   }
-  /**
-   * Toggle whether the scrim layer captures pointer events.
-   * @param interactive - `true` → `pointer-events: auto`; `false` → `none`.
-   * @example
-   *   engine.setScrimInteractive(true);  // scrim swallows clicks
-   *   engine.setScrimInteractive(false); // clicks pass through to content below
-   */
   setScrimInteractive(interactive) {
     if (this.isDestroyed()) return;
     this.applyScrimStyles({ interactive });
   }
-  /**
-   * Switch scrim positioning at runtime.
-   * @param mode - `"full"` (consumer CSS), `"above-sheet"` (engine-pinned inset
-   *               so only the area NOT covered by the sheet is dimmed), or
-   *               `"off"` (display:none + opacity:0 — no remount needed).
-   * @param applySize - Engine-supplied recompute hook; runs one applyOpacity pass.
-   * @example
-   *   engine.setScrimMode("above-sheet"); // dim only the area above the sheet
-   *   engine.setScrimMode("off");          // disable scrim layer
-   */
   setScrimMode(mode, applySize) {
     if (this.isDestroyed()) return;
     if (mode === this.scrimMode) return;
@@ -970,15 +952,6 @@ var ScrimController = class {
     }
     applySize();
   }
-  /**
-   * Enable or disable click-on-scrim → snap to first non-zero allowed snap.
-   * Auto-promotes `pointer-events: auto` when scrim is non-interactive so the
-   * click listener actually fires.
-   * @param enabled - `true` installs the click listener; `false` removes it.
-   * @example
-   *   engine.setScrimTapToClose(true);  // tap outside sheet collapses it
-   *   engine.setScrimTapToClose(false); // require explicit close button
-   */
   setScrimTapToClose(enabled) {
     if (this.isDestroyed()) return;
     if (!this.screenComponent) return;
@@ -991,11 +964,15 @@ var ScrimController = class {
       }
       const onClick = () => {
         if (this.isDestroyed()) return;
+        if (this.closeFn) {
+          this.closeFn();
+          return;
+        }
         const allowed = this.getAllowedIds();
         const snaps = this.getResolvedSnaps();
         const fallback = allowed.find((id) => {
           const snap = findById(id, snaps);
-          return snap !== null && snap.size > 0;
+          return snap !== null && snap.size === 0;
         });
         if (fallback) this.snapToFn(fallback);
       };
@@ -1008,20 +985,11 @@ var ScrimController = class {
       this.scrimTapToCloseEnabled = false;
     }
   }
-  /**
-   * Toggle the scrim layer without remounting. Disabling stashes current
-   * `screenRange`/`backdropRange` and degenerates them to `[1, 1]` (opacity
-   * formula → 0 across the whole range); re-enabling restores the saved values.
-   * @param enabled - `false` hides scrim, `true` restores prior ranges.
-   * @param applySize - Engine-supplied recompute hook; runs one applyOpacity pass.
-   * @example
-   *   engine.setScrimEnabled(false); // hide scrim, ranges remembered
-   *   engine.setScrimEnabled(true);  // restore prior ranges (no remount)
-   */
   setScrimEnabled(enabled, applySize) {
     if (this.isDestroyed()) return;
     if (enabled === this.scrimEnabled) return;
     this.scrimEnabled = enabled;
+    this.invalidateOpacityCache();
     if (!enabled) {
       this.savedScrimRanges = {
         screen: this.screenRange,
@@ -1036,20 +1004,6 @@ var ScrimController = class {
     }
     applySize();
   }
-  /**
-   * Batch-update multiple scrim fields with a single applySize() at the end.
-   * If `preset` is set, it seeds color/blur/interactive/range first; explicit
-   * fields override.
-   * @param opts - Partial scrim config: preset, mode, enabled, tapToClose,
-   *               color, blur, interactive, range.
-   * @param applySize - Engine-supplied recompute hook; runs ONCE per call.
-   * @example
-   *   engine.setScrim({
-   *     preset: "frosted",
-   *     mode: "above-sheet",
-   *     tapToClose: true,
-   *   });
-   */
   setScrim(opts, applySize) {
     if (this.isDestroyed()) return;
     if (opts.preset) {
@@ -1059,7 +1013,12 @@ var ScrimController = class {
         blur: cfg.blur ?? null,
         interactive: cfg.interactive
       });
-      this.screenRange = cfg.range;
+      if (!this.scrimEnabled && this.savedScrimRanges) {
+        this.savedScrimRanges = { screen: cfg.range, backdrop: cfg.range };
+      } else {
+        this.screenRange = cfg.range;
+        this.backdropRange = cfg.range;
+      }
     }
     const noop = () => {
     };
@@ -1072,27 +1031,18 @@ var ScrimController = class {
       interactive: opts.interactive
     });
     if (opts.range !== void 0) {
-      this.screenRange = opts.range;
+      if (!this.scrimEnabled && this.savedScrimRanges) {
+        this.savedScrimRanges = {
+          screen: opts.range,
+          backdrop: this.savedScrimRanges.backdrop
+        };
+      } else {
+        this.screenRange = opts.range;
+      }
     }
     this.invalidateOpacityCache();
     applySize();
   }
-  /**
-   * Inject a positioned floating element into the scrim layer (e.g. a close
-   * button anchored top-right). Replaces any prior overlay so repeated calls
-   * (reactive effects re-running) don't accumulate wrappers.
-   * @param opts - Children element, optional `inset` (default `"16px"`),
-   *               `position` (9-way grid, default `"top-right"`), and
-   *               `interactive` flag (default `true`).
-   * @returns Teardown function that removes the wrapper from the DOM.
-   * @example
-   *   const teardown = engine.setScrimOverlay({
-   *     children: closeBtn,
-   *     position: "top-right",
-   *     inset: "20px",
-   *   });
-   *   // later: teardown(); // remove the floating button
-   */
   setScrimOverlay(opts) {
     if (this.isDestroyed()) return () => {
     };
@@ -1100,61 +1050,38 @@ var ScrimController = class {
     };
     this.scrimOverlayTeardown?.();
     const screen = this.screenComponent;
-    const inset = opts.inset ?? "16px";
+    const insetRaw = opts.inset ?? "16px";
+    const inset = VALID_CSS_LENGTH.test(insetRaw) ? insetRaw : "16px";
+    if (inset !== insetRaw) {
+      devWarn(
+        `[bottom-sheet] setScrimOverlay: invalid inset ${JSON.stringify(insetRaw)}; expected a CSS length like "16px" / "1rem" / "5%". Falling back to "16px".`
+      );
+    }
+    if (opts.children.ownerDocument && opts.children.ownerDocument !== screen.ownerDocument) {
+      devWarn(
+        "[bottom-sheet] setScrimOverlay: children belong to a different document than the scrim. Cross-document adoption can drop event listeners; construct children via the same document as the sheet root."
+      );
+    }
     const position = opts.position ?? "top-right";
     const interactive = opts.interactive ?? true;
     const wrapper = screen.ownerDocument.createElement("div");
     wrapper.className = "bs-scrim-overlay";
     const ws = wrapper.style;
     ws.position = "absolute";
-    switch (position) {
-      case "top-left":
-        ws.top = inset;
-        ws.left = inset;
-        break;
-      case "top-center":
-        ws.top = inset;
-        ws.left = "50%";
-        ws.transform = "translateX(-50%)";
-        break;
-      case "top-right":
-        ws.top = inset;
-        ws.right = inset;
-        break;
-      case "center-left":
-        ws.top = "50%";
-        ws.left = inset;
-        ws.transform = "translateY(-50%)";
-        break;
-      case "center":
-        ws.top = "50%";
-        ws.left = "50%";
-        ws.transform = "translate(-50%, -50%)";
-        break;
-      case "center-right":
-        ws.top = "50%";
-        ws.right = inset;
-        ws.transform = "translateY(-50%)";
-        break;
-      case "bottom-left":
-        ws.bottom = inset;
-        ws.left = inset;
-        break;
-      case "bottom-center":
-        ws.bottom = inset;
-        ws.left = "50%";
-        ws.transform = "translateX(-50%)";
-        break;
-      case "bottom-right":
-        ws.bottom = inset;
-        ws.right = inset;
-        break;
-    }
+    applyOverlayPosition(ws, this.mode, position, inset);
     if (interactive) {
       ws.pointerEvents = "auto";
     }
     wrapper.appendChild(opts.children);
-    screen.appendChild(wrapper);
+    const host = screen.parentElement;
+    if (!host) {
+      devWarn(
+        "[bottom-sheet] setScrimOverlay: scrim element has no parent, skipping overlay injection. Mount the sheet root before calling setScrimOverlay."
+      );
+      return () => {
+      };
+    }
+    host.appendChild(wrapper);
     const teardown = () => {
       if (wrapper.parentNode) wrapper.parentNode.removeChild(wrapper);
       if (this.scrimOverlayTeardown === teardown) {
@@ -1164,7 +1091,6 @@ var ScrimController = class {
     this.scrimOverlayTeardown = teardown;
     return teardown;
   }
-  /** Tear down toggle-state listeners + remove any injected overlay wrapper. */
   destroy() {
     this.detachScrimTap?.();
     this.detachScrimTap = null;
@@ -1183,8 +1109,6 @@ var ScrimController = class {
     this.lastBackdropPointer = "";
     this.lastScreenDisplay = "";
   }
-  // ── Private helpers ────────────────────────────────────────────────
-  /** Centralized scrim style writer — atomic 3-property write across all setters. */
   applyScrimStyles(opts) {
     if (!this.screenComponent) return;
     const s = this.screenComponent.style;
@@ -1203,10 +1127,10 @@ var ScrimController = class {
       }
     }
     if (opts.interactive !== void 0) {
+      this.scrimInteractive = opts.interactive;
       s.pointerEvents = opts.interactive ? "auto" : "none";
     }
   }
-  /** Pin the screen overlay to the area NOT occupied by the sheet. */
   applyAboveSheetInset() {
     if (!this.screenComponent) return;
     const insetByMode = {
@@ -1218,7 +1142,7 @@ var ScrimController = class {
     const s = this.screenComponent.style;
     s.position = "fixed";
     s.inset = insetByMode[this.mode];
-    s.pointerEvents = "none";
+    s.pointerEvents = this.scrimInteractive || this.scrimTapToCloseEnabled ? "auto" : "none";
   }
 };
 
@@ -1306,14 +1230,20 @@ var runSpring = ({
       if (cancelled) return;
       const dt = Math.min((now - lastTime) / 1e3, MAX_DT);
       lastTime = now;
-      const subDt = Math.min(dt, 1 / 240);
-      let stepsLeft = Math.max(1, Math.ceil(dt / subDt));
+      const steps = Math.max(1, Math.ceil(dt * 240));
+      const subDt = dt / steps;
+      let stepsLeft = steps;
       while (stepsLeft-- > 0) {
         const force = -cfg.stiffness * (x - to) - cfg.damping * v;
         const accel = force / cfg.mass;
         v += accel * subDt;
         x += v * subDt;
       }
+      if (!Number.isFinite(x) || !Number.isFinite(v)) {
+        onUpdate(to, 0);
+        resolve();
+        return;
+      }
       onUpdate(x, v);
       const isAtRest = Math.abs(to - x) < (cfg.restDelta ?? 0.5) && Math.abs(v) < (cfg.restSpeed ?? 0.5);
       if (isAtRest) {
@@ -1377,13 +1307,9 @@ var AnimationRunner = class {
     __publicField(this, "duration");
     __publicField(this, "easing");
     __publicField(this, "respectReducedMotion");
-    /** Live-tracked via mq listener so animateTo skips matchMedia per snap. */
     __publicField(this, "reducedMotion", false);
-    /** Disposes the matchMedia change listener — drained from destroy(). */
     __publicField(this, "detachReducedMotion", null);
-    /** Computed once — both inputs (option + API presence) stable for life. */
     __publicField(this, "viewTransitionsAvailable");
-    /** In-flight handles. Public for tests / debugging only — engine drives via cancel(). */
     __publicField(this, "currentTween", null);
     __publicField(this, "currentSpring", null);
     this.element = deps.element;
@@ -1414,26 +1340,13 @@ var AnimationRunner = class {
       }
     }
   }
-  /**
-   * Live derived flag — `true` whenever a spring/tween handle is in flight.
-   * Reading the canonical handles (instead of mirroring into a separate
-   * boolean) eliminates the reduced-motion early-return latent bug where
-   * the flag stayed true forever, and removes the cross-controller
-   * setIsAnimating callback.
-   */
   get isAnimating() {
     return this.currentTween !== null || this.currentSpring !== null;
   }
-  /** Cancel any in-flight tween/spring without touching engine state. */
   cancel() {
     this.currentTween?.cancel();
     this.currentSpring?.cancel();
   }
-  /**
-   * Animate from current size to `target`. Resolves when the animation
-   * completes; resolves early if cancelled mid-flight (caller checks an
-   * abort signal post-await for cycle-invariant correctness).
-   */
   async animateTo(target, velocityPxPerMs) {
     if (target === this.getSize()) return;
     this.currentTween?.cancel();
@@ -1474,7 +1387,6 @@ var AnimationRunner = class {
       if (!this.isDragging()) this.element.style.willChange = "auto";
     }
   }
-  /** Tear down the matchMedia listener. Engine calls from destroy(). */
   destroy() {
     this.detachReducedMotion?.();
     this.detachReducedMotion = null;
@@ -1506,9 +1418,13 @@ var isVisible = (el) => {
 var focusables = (root) => Array.from(root.querySelectorAll(FOCUSABLE)).filter(
   (el) => !el.hasAttribute("inert") && isVisible(el) && !el.matches("[aria-hidden='true']")
 );
+var trapStack = [];
 var installFocusTrap = (container, options = {}) => {
   if (typeof document === "undefined") return () => {
   };
+  const token = {};
+  trapStack.push(token);
+  const isActive = () => trapStack[trapStack.length - 1] === token;
   const previouslyFocused = document.activeElement;
   const focusInitial = () => {
     const initial = typeof options.initialFocus === "string" ? container.querySelector(options.initialFocus) : options.initialFocus ?? focusables(container)[0] ?? container;
@@ -1516,6 +1432,7 @@ var installFocusTrap = (container, options = {}) => {
   };
   focusInitial();
   const handleKey = (e) => {
+    if (!isActive()) return;
     if (e.key === "Escape" && options.onEscape) {
       options.onEscape();
       return;
@@ -1538,6 +1455,7 @@ var installFocusTrap = (container, options = {}) => {
     }
   };
   const handleFocusIn = (e) => {
+    if (!isActive()) return;
     const target = e.target;
     if (target && !container.contains(target)) {
       const list = focusables(container);
@@ -1550,6 +1468,8 @@ var installFocusTrap = (container, options = {}) => {
   return () => {
     if (released) return;
     released = true;
+    const idx = trapStack.indexOf(token);
+    if (idx !== -1) trapStack.splice(idx, 1);
     document.removeEventListener("keydown", handleKey, true);
     document.removeEventListener("focusin", handleFocusIn, true);
     if (previouslyFocused && document.contains(previouslyFocused)) {
@@ -1605,11 +1525,17 @@ function createInertSiblings(rootProvider) {
   return {
     apply() {
       if (typeof document === "undefined") return;
-      const root = rootProvider();
-      const parent = root.parentElement ?? document.body;
+      let top = rootProvider();
+      while (top.parentElement && top.parentElement !== document.body) {
+        top = top.parentElement;
+      }
+      const parent = top.parentElement ?? document.body;
       for (const child of Array.from(parent.children)) {
-        if (child === root) continue;
+        if (child === top) continue;
         if (child.hasAttribute("inert")) continue;
+        if (child.classList.contains("bs-backdrop") || child.classList.contains("bs-screen") || child.classList.contains("bs-root")) {
+          continue;
+        }
         child.setAttribute("inert", "");
         tracked.push(child);
       }
@@ -1625,7 +1551,6 @@ function createInertSiblings(rootProvider) {
 var LifecycleController = class {
   constructor(deps, opts) {
     __publicField(this, "element");
-    __publicField(this, "closeFn");
     __publicField(this, "focusTrapEnabled");
     __publicField(this, "initialFocus");
     __publicField(this, "closeOnEscape");
@@ -1634,16 +1559,11 @@ var LifecycleController = class {
     __publicField(this, "inertSiblings");
     __publicField(this, "shouldApplyInertSiblings");
     __publicField(this, "returnFocus");
-    /** Toggle-state teardowns — fire on close, NOT in destroy-only stack. */
     __publicField(this, "releaseFocusTrap", null);
     __publicField(this, "releaseScrollLock", null);
-    /** True between install() and release(). Guards release()/destroy() from
-     *  re-running side effects (notably `returnFocus.focus()`) on already-
-     *  released or never-installed instances. */
     __publicField(this, "installed", false);
     __publicField(this, "destroyed", false);
     this.element = deps.element;
-    this.closeFn = deps.close;
     this.focusTrapEnabled = opts.focusTrap ?? false;
     this.initialFocus = opts.initialFocus;
     this.closeOnEscape = opts.closeOnEscape ?? true;
@@ -1653,14 +1573,9 @@ var LifecycleController = class {
     this.returnFocus = opts.returnFocus;
     this.inertSiblings = createInertSiblings(() => this.element);
   }
-  /**
-   * Run the open-time install steps. Idempotent: each step checks its
-   * existing teardown ref so a re-open during a half-cancelled close
-   * doesn't double-install. Sets `installed=true` BEFORE the first side
-   * effect so a partial throw (detached / shadow-DOM target) leaves the
-   * caller's `release()` rollback path armed to undo whatever did succeed.
-   * No-op when destroyed.
-   */
+  get isInstalled() {
+    return this.installed;
+  }
   install() {
     if (this.destroyed) return;
     this.installed = true;
@@ -1669,30 +1584,17 @@ var LifecycleController = class {
     }
     if (this.focusTrapEnabled && !this.releaseFocusTrap) {
       this.releaseFocusTrap = installFocusTrap(this.element, {
-        initialFocus: this.initialFocus,
-        onEscape: this.closeOnEscape ? () => void this.closeFn() : void 0
+        initialFocus: this.initialFocus
       });
     }
     if (this.inertSiblingsEnabled && this.shouldApplyInertSiblings()) {
       this.inertSiblings.apply();
     }
   }
-  /**
-   * Update the post-release focus target. Overlay re-binds this when the
-   * consumer changes `returnFocus` after construction; the new value applies
-   * on the next `release()`. No-op when destroyed.
-   */
   setReturnFocus(target) {
     if (this.destroyed) return;
     this.returnFocus = target;
   }
-  /**
-   * Release all install-time teardowns. Short-circuits when not installed,
-   * so `close() → destroy()` (each routing through here) only restores
-   * focus once. The `installed` guard lets `inertSiblings.remove()` and
-   * the focus-trap/scroll-lock teardown nullings stay simple — they were
-   * already idempotent, but `returnFocus.focus()` was firing on every call.
-   */
   release() {
     if (!this.installed) return;
     this.installed = false;
@@ -1706,12 +1608,6 @@ var LifecycleController = class {
       target?.focus?.();
     }
   }
-  /**
-   * Final teardown — releases any still-installed listeners and seals the
-   * controller. After destroy(), install() is a no-op and setReturnFocus()
-   * is rejected, so post-destroy mutations can't queue up a stale focus
-   * restore.
-   */
   destroy() {
     this.release();
     this.destroyed = true;
@@ -1721,12 +1617,10 @@ var LifecycleController = class {
 // src/core/gestures.ts
 var isAxisVertical = (mode) => mode === "bottom" || mode === "top";
 var SampleRing = class {
-  // current count, ≤ capacity
   constructor(capacity) {
     __publicField(this, "slots");
     __publicField(this, "capacity");
     __publicField(this, "head", 0);
-    // next write index
     __publicField(this, "size", 0);
     this.capacity = capacity;
     this.slots = new Array(capacity);
@@ -1739,12 +1633,6 @@ var SampleRing = class {
     this.head = (this.head + 1) % this.capacity;
     if (this.size < this.capacity) this.size++;
   }
-  /**
-   * Drop oldest entries whose timestamp is below `cutoff`, but never shrink
-   * below `minKeep`. Mirrors the original
-   *   `while (samples.length > minKeep && samples[0].t < cutoff) samples.shift()`
-   * but without copying — just advances the logical tail.
-   */
   pruneBefore(cutoff, minKeep) {
     while (this.size > minKeep) {
       const oldestIdx = (this.head - this.size + this.capacity) % this.capacity;
@@ -1851,10 +1739,11 @@ var installGestures = (handle, mode, callbacks) => {
 var attachGestures = installGestures;
 
 // src/core/primitives/rubber-band.ts
-var RUBBER_BAND_FACTOR = 0.55;
 function rubberBand(overshoot, maxAxisSize) {
   const cap = Math.min(maxAxisSize * 0.15, 80);
-  return Math.sign(overshoot) * Math.pow(Math.abs(overshoot), RUBBER_BAND_FACTOR) * Math.min(6, cap / Math.max(Math.abs(overshoot), 1));
+  if (cap <= 0) return 0;
+  const abs = Math.abs(overshoot);
+  return Math.sign(overshoot) * (cap * abs / (abs + cap));
 }
 
 // src/core/features/soft-keyboard.ts
@@ -1881,28 +1770,14 @@ var GestureController = class {
     __publicField(this, "detach", null);
     __publicField(this, "isDragging_", false);
     __publicField(this, "dragStartSize", 0);
-    // Only "touch" gestures are eligible for soft-keyboard dismissal —
-    // mouse/trackpad users don't have a keyboard to dismiss.
     __publicField(this, "currentPointerKind", "touch");
-    // One blur per drag — flipping focus every move event races the keyboard's
-    // own animations on iOS and makes the page jitter.
     __publicField(this, "keyboardDismissed", false);
-    // Reused payload object for the "drag" event — mutated each onMove instead
-    // of allocating a fresh `{size, delta}` per frame. At 60-120Hz a long drag
-    // would otherwise churn tens of KB through the GC. Mirrors browser
-    // PointerEvent semantics: consumers must NOT retain the reference across
-    // frames (clone if needed). See SheetEventMap.drag JSDoc.
     __publicField(this, "dragPayload", { size: 0, delta: 0 });
     this.deps = deps;
   }
-  /** True between `dragstart` and `dragend`/`onCancel`. */
   get isDragging() {
     return this.isDragging_;
   }
-  /**
-   * Bind pointer listeners on the handle and return a teardown. Engine pushes
-   * the teardown into its TeardownStack so destroy() drains it once.
-   */
   install() {
     if (this.detach) return this.detach;
     this.detach = installGestures(this.deps.handle, this.deps.mode, {
@@ -1953,17 +1828,16 @@ var GestureController = class {
         this.isDragging_ = false;
         this.keyboardDismissed = false;
         this.deps.getRoot()?.removeAttribute("data-dragging");
+        this.deps.emit("dragend", {
+          size: this.deps.getDragContext().size,
+          velocity: 0
+        });
         const restoreTo = this.dragStartSize;
         void this.deps.animateTo(restoreTo, 0);
       }
     });
     return this.detach;
   }
-  /**
-   * Force-clear drag visual state. Engine calls from destroy() when destroyed
-   * mid-drag — gesture detach won't synthesize an onCancel, so we have to
-   * roll back the data-attribute + will-change ourselves.
-   */
   forceClearDragState() {
     if (!this.isDragging_) return;
     this.isDragging_ = false;
@@ -1982,11 +1856,6 @@ var AriaSliderWriter = class {
       mode === "bottom" || mode === "top" ? "vertical" : "horizontal"
     );
   }
-  /**
-   * Update slider position. `allowedIds` length determines `aria-valuemax`;
-   * `activeId` indexes into it for `aria-valuenow` + `aria-valuetext`.
-   * Empty list → strip every dynamic attr so AT skips the handle entirely.
-   */
   setValue(allowedIds, activeId) {
     if (allowedIds.length === 0) {
       this.handle.removeAttribute("aria-valuemin");
@@ -2036,6 +1905,287 @@ function createScrollCache(deps) {
   };
 }
 
+// src/core/primitives/anchor-animations.ts
+var DEFAULT_DURATION3 = 200;
+var DEFAULT_EASING = "cubic-bezier(0.22, 1, 0.36, 1)";
+var PRESET_FRAMES = {
+  fade: {
+    enter: [{ opacity: 0 }, { opacity: 1 }],
+    exit: [{ opacity: 1 }, { opacity: 0 }]
+  },
+  scale: {
+    enter: [
+      { opacity: 0, transform: "scale(0.85)" },
+      { opacity: 1, transform: "scale(1)" }
+    ],
+    exit: [
+      { opacity: 1, transform: "scale(1)" },
+      { opacity: 0, transform: "scale(0.85)" }
+    ]
+  },
+  slide: {
+    enter: [
+      { opacity: 0, transform: "translateY(10px)" },
+      { opacity: 1, transform: "translateY(0)" }
+    ],
+    exit: [
+      { opacity: 1, transform: "translateY(0)" },
+      { opacity: 0, transform: "translateY(10px)" }
+    ]
+  },
+  pop: {
+    enter: [
+      { opacity: 0, transform: "scale(0.6)", offset: 0 },
+      { opacity: 1, transform: "scale(1.06)", offset: 0.7 },
+      { opacity: 1, transform: "scale(1)", offset: 1 }
+    ],
+    exit: [
+      { opacity: 1, transform: "scale(1)" },
+      { opacity: 0, transform: "scale(0.6)" }
+    ]
+  }
+};
+var INSTANT = {
+  finished: Promise.resolve(),
+  cancel: () => {
+  }
+};
+function resolveTransitionFrames(spec, phase) {
+  const fallback = { frames: null, duration: 0, easing: DEFAULT_EASING };
+  if (spec === "none") return fallback;
+  if (spec === void 0 || typeof spec === "string") {
+    const preset2 = PRESET_FRAMES[spec ?? "fade"];
+    return {
+      frames: preset2[phase],
+      duration: DEFAULT_DURATION3,
+      easing: DEFAULT_EASING
+    };
+  }
+  const custom = phase === "enter" ? spec.enter : spec.exit;
+  if (custom) {
+    return {
+      frames: custom,
+      duration: spec.duration ?? DEFAULT_DURATION3,
+      easing: spec.easing ?? DEFAULT_EASING
+    };
+  }
+  if (spec.preset === "none") return fallback;
+  const preset = PRESET_FRAMES[spec.preset ?? "fade"];
+  return {
+    frames: preset[phase],
+    duration: spec.duration ?? DEFAULT_DURATION3,
+    easing: spec.easing ?? DEFAULT_EASING
+  };
+}
+function runAnchorTransition(el, spec, phase) {
+  const respectReduced = typeof spec === "object" ? spec.respectReducedMotion !== false : true;
+  if (respectReduced && prefersReducedMotion()) return INSTANT;
+  const { frames, duration, easing } = resolveTransitionFrames(spec, phase);
+  if (!frames || duration <= 0) return INSTANT;
+  if (typeof el.animate !== "function") return INSTANT;
+  const animation = el.animate(frames, {
+    duration,
+    easing,
+    fill: "both"
+  });
+  const finished = animation.finished.then(() => void 0).catch(() => void 0);
+  return {
+    finished,
+    cancel: () => {
+      try {
+        animation.cancel();
+      } catch {
+        return;
+      }
+    }
+  };
+}
+
+// src/core/features/sheet-anchors.ts
+function attachAnchor(deps, opts) {
+  const doc = deps.host.ownerDocument;
+  const wrapper = doc.createElement("div");
+  wrapper.className = "bs-anchor";
+  const interactive = opts.interactive ?? true;
+  const position = opts.position ?? "sheet-top-right";
+  const isDock = position === "dock-bottom" || position === "dock-top";
+  const ws = wrapper.style;
+  ws.position = "fixed";
+  if (isDock) {
+    ws.left = "0";
+    ws.right = "0";
+    if (position === "dock-bottom") {
+      ws.bottom = "0";
+    } else {
+      ws.top = "0";
+    }
+  } else {
+    applyOverlayPosition(ws, deps.mode, position, opts.inset ?? "16px");
+  }
+  if (opts.fadeRange) {
+    const [r0, r1] = opts.fadeRange;
+    const span = Math.max(r1 - r0, 1e-4);
+    ws.opacity = `clamp(0, calc((var(--bs-progress, 0) - ${r0}) / ${span}), 1)`;
+  }
+  wrapper.appendChild(opts.element);
+  deps.host.appendChild(wrapper);
+  let visible = null;
+  let inFlight = null;
+  const shouldShow = (state) => {
+    if (typeof opts.showOn === "function") return opts.showOn(state);
+    if (Array.isArray(opts.showOn)) return opts.showOn.includes(state.activeId);
+    return isDock || state.size > 0;
+  };
+  const applyVisibility = (next, animate) => {
+    if (next === visible) return;
+    visible = next;
+    inFlight?.cancel();
+    inFlight = null;
+    wrapper.style.pointerEvents = next && interactive ? "auto" : "none";
+    if (next) {
+      wrapper.style.visibility = "";
+      if (animate) {
+        inFlight = runAnchorTransition(opts.element, opts.animation, "enter");
+      }
+      return;
+    }
+    if (!animate) {
+      wrapper.style.visibility = "hidden";
+      return;
+    }
+    const handle = runAnchorTransition(opts.element, opts.animation, "exit");
+    inFlight = handle;
+    void handle.finished.then(() => {
+      if (inFlight === handle && visible === false) {
+        wrapper.style.visibility = "hidden";
+      }
+    });
+  };
+  const evaluate = (animate) => {
+    if (deps.isDestroyed()) return;
+    applyVisibility(shouldShow(deps.getState()), animate);
+  };
+  const offs = [
+    deps.on("snap", () => evaluate(true)),
+    deps.on("open", () => evaluate(true)),
+    deps.on("close", () => evaluate(true))
+  ];
+  evaluate(false);
+  return {
+    wrapper,
+    detach: () => {
+      offs.forEach((off) => off());
+      inFlight?.cancel();
+      inFlight = null;
+      if (wrapper.parentNode) wrapper.parentNode.removeChild(wrapper);
+    },
+    syncZ: (z) => {
+      wrapper.style.zIndex = String(z);
+    }
+  };
+}
+
+// src/core/features/scrim-stages.ts
+var matchesId = (def, activeId) => {
+  if (def.for === void 0) return false;
+  return Array.isArray(def.for) ? def.for.includes(activeId) : def.for === activeId;
+};
+var matchesRange = (def, progress) => {
+  if (!def.forRange) return false;
+  const [from, to] = def.forRange;
+  return progress >= from && progress <= to;
+};
+function installScrimStages(deps, opts) {
+  const doc = deps.host.ownerDocument;
+  const entries = opts.stages.map((def) => {
+    const wrapper = doc.createElement("div");
+    wrapper.className = "bs-scrim-stage";
+    const ws = wrapper.style;
+    ws.position = "absolute";
+    applyOverlayPosition(
+      ws,
+      deps.mode,
+      def.position ?? opts.position ?? "center",
+      def.inset ?? opts.inset ?? "16px"
+    );
+    ws.visibility = "hidden";
+    ws.pointerEvents = "none";
+    wrapper.appendChild(def.element);
+    deps.host.appendChild(wrapper);
+    return { def, wrapper, inFlight: null };
+  });
+  let active = null;
+  const resolveActive = () => {
+    const state = deps.getState();
+    if (state.size === 0) {
+      return entries.find((e) => matchesId(e.def, state.activeId)) ?? null;
+    }
+    return entries.find((e) => matchesId(e.def, state.activeId)) ?? entries.find((e) => matchesRange(e.def, state.progress)) ?? null;
+  };
+  const hide = (entry, animate) => {
+    entry.inFlight?.cancel();
+    entry.wrapper.style.pointerEvents = "none";
+    if (!animate) {
+      entry.inFlight = null;
+      entry.wrapper.style.visibility = "hidden";
+      return;
+    }
+    const handle = runAnchorTransition(
+      entry.def.element,
+      entry.def.animation ?? opts.animation,
+      "exit"
+    );
+    entry.inFlight = handle;
+    void handle.finished.then(() => {
+      if (entry.inFlight === handle && active !== entry) {
+        entry.wrapper.style.visibility = "hidden";
+      }
+    });
+  };
+  const show = (entry, animate) => {
+    entry.inFlight?.cancel();
+    entry.inFlight = null;
+    entry.wrapper.style.visibility = "";
+    entry.wrapper.style.pointerEvents = entry.def.interactive ?? opts.interactive ?? false ? "auto" : "none";
+    if (animate) {
+      entry.inFlight = runAnchorTransition(
+        entry.def.element,
+        entry.def.animation ?? opts.animation,
+        "enter"
+      );
+    }
+  };
+  const update = (animate) => {
+    if (deps.isDestroyed()) return;
+    const next = resolveActive();
+    if (next === active) return;
+    const prev = active;
+    active = next;
+    if (prev) hide(prev, animate);
+    if (next) show(next, animate);
+  };
+  const offs = [
+    deps.on("snap", () => update(true)),
+    deps.on("open", () => update(true)),
+    deps.on("close", () => update(true))
+  ];
+  if (entries.some((e) => e.def.forRange)) {
+    offs.push(deps.on("progress", () => update(true)));
+  }
+  update(false);
+  return () => {
+    offs.forEach((off) => off());
+    for (const entry of entries) {
+      entry.inFlight?.cancel();
+      entry.inFlight = null;
+      if (entry.wrapper.parentNode) {
+        entry.wrapper.parentNode.removeChild(entry.wrapper);
+      }
+    }
+    active = null;
+  };
+}
+
 // src/core/primitives/engine-options.ts
 var DEFAULT_FLICK_VELOCITY = 0.65;
 var DEFAULT_DRAG_THRESHOLD = 18;
@@ -2060,9 +2210,6 @@ function resolveEngineOptions(opts, extras) {
       scrimMode: opts.scrimMode,
       scrimColor: opts.scrimColor,
       scrimBlur: opts.scrimBlur,
-      // Auto-promote pointer-events when tap-to-close is on so the click
-      // listener actually receives events. Caller can still force `false`
-      // explicitly to opt out — `??` only kicks in for `undefined`.
       scrimInteractive: opts.scrimInteractive ?? (opts.scrimTapToClose ? true : void 0),
       scrimTapToClose: opts.scrimTapToClose,
       scrimPreset: opts.scrimPreset,
@@ -2083,10 +2230,6 @@ function resolveEngineOptions(opts, extras) {
       closeOnEscape: opts.closeOnEscape,
       lockBodyScroll: opts.lockBodyScroll,
       inertSiblings: opts.inertSiblings,
-      // Folded in from `extras` so the lifecycle bag is fully assembled at
-      // the call site — engine no longer needs a spread+override at
-      // controller construction. When `extras` is omitted, the field stays
-      // undefined and the controller uses its own default predicate.
       shouldApplyInertSiblings: extras?.shouldApplyInertSiblings
     }
   };
@@ -2121,6 +2264,7 @@ var BottomSheetEngine = class {
     __publicField(this, "scrollContainer");
     __publicField(this, "backdrop");
     __publicField(this, "screenComponent");
+    __publicField(this, "scrimParent", null);
     __publicField(this, "mode");
     __publicField(this, "flickVelocity");
     __publicField(this, "dragThreshold");
@@ -2131,40 +2275,22 @@ var BottomSheetEngine = class {
     __publicField(this, "lifecycle");
     __publicField(this, "closeOnBack");
     __publicField(this, "routedTo");
-    // Engine retains `snapPointsRaw` for the "find a closed-id" query in
-    // close() (raw input, not resolved geometry). Resolver owns geometry.
     __publicField(this, "snapPointsRaw");
     __publicField(this, "snaps");
     __publicField(this, "activeId");
     __publicField(this, "size", 0);
-    // Constructed in attach(); a plugin's install() could read `state` before
-    // attach completes if the constructor throws partway through. State getter
-    // null-guards via `this.gesture?.isDragging ?? false`.
     __publicField(this, "gesture");
     __publicField(this, "rootEl", null);
     __publicField(this, "destroyed", false);
-    // In-flight ViewTransition handle. A second snapTo while a VT is in flight
-    // would otherwise let Chromium reject the second's promise and flicker —
-    // newCycle() calls skipTransition() to abort cleanly.
     __publicField(this, "currentViewTransition", null);
-    // Each cycle captures the signal at entry; when a newer cycle aborts the
-    // controller, the captured signal flips to `aborted=true` and post-await
-    // guards short-circuit (prevents stale snap/open/close emits).
     __publicField(this, "currentAbort", new AbortController());
-    // Sub-pixel `--bs-size` deltas and <1% `--bs-progress` deltas are not
-    // visually distinguishable; gating CSSOM writes drops 30-50% of writes
-    // during the spring's settle tail.
     __publicField(this, "sizeWriteSentinel", new WriteSentinel());
     __publicField(this, "progressWriteSentinel", new WriteSentinel());
     __publicField(this, "isTopSheet", true);
-    // Pooled payload — identity documented in SheetEventMap.progress JSDoc;
-    // consumers must not retain across frames.
     __publicField(this, "progressPayload", {
       value: 0,
       size: 0
     });
-    // Pooled buffer for `getDragContext()` — onMove calls this 60-120×/s.
-    // Inner `range` object identity is also stable (mutated in place).
     __publicField(this, "dragContextBuf", {
       size: 0,
       maxAxisSize: 0,
@@ -2175,13 +2301,13 @@ var BottomSheetEngine = class {
     __publicField(this, "persistKey");
     __publicField(this, "linkedSheets", []);
     __publicField(this, "scrollCache");
-    // Single LIFO stack for ALL destroy-only teardowns. Plugins (added last)
-    // tear down first before the infrastructure they depend on. Toggle-semantic
-    // listeners (focus-trap / scroll-lock / scrim tap-to-close) stay as named
-    // fields on their controllers.
     __publicField(this, "teardowns", new TeardownStack());
-    // Pre-computed transform template — built once per engine since `mode` is
-    // fixed for its lifetime. Avoids the 4-arm switch at 60-120 Hz.
+    __publicField(this, "anchors", []);
+    __publicField(this, "anchorHost", null);
+    __publicField(this, "stackZ", 100);
+    __publicField(this, "detachScrimStages", null);
+    __publicField(this, "stackEffectEnabled", false);
+    __publicField(this, "stackEffectPrimed", false);
     __publicField(this, "transformTemplate");
     const resolved = resolveEngineOptions(opts, {
       shouldApplyInertSiblings: () => {
@@ -2196,7 +2322,8 @@ var BottomSheetEngine = class {
     this.handle = opts.handle ?? opts.element;
     this.scrollContainer = opts.scrollContainer;
     this.backdrop = opts.backdrop;
-    this.screenComponent = opts.screenComponent;
+    this.screenComponent = opts.scrim ?? opts.screenComponent;
+    this.scrimParent = this.screenComponent?.parentElement ?? null;
     this.mode = resolved.mode;
     this.transformTemplate = buildTransformTemplate(this.mode);
     this.aria = new AriaSliderWriter(this.handle, this.mode);
@@ -2214,6 +2341,9 @@ var BottomSheetEngine = class {
         getResolvedSnaps: () => this.snaps.getResolvedSnaps().slice(),
         snapTo: (id) => {
           void this.snapTo(id);
+        },
+        close: () => {
+          void this.close();
         }
       },
       resolved.scrim
@@ -2224,8 +2354,6 @@ var BottomSheetEngine = class {
         getRootEl: () => this.rootEl,
         applySize: (size) => this.applySize(size),
         getSize: () => this.size,
-        // Optional chain protects synthetic test paths that drive animateTo
-        // before attach() (gesture is constructed there).
         isDragging: () => this.gesture?.isDragging ?? false
       },
       resolved.animation
@@ -2239,6 +2367,7 @@ var BottomSheetEngine = class {
     );
     this.closeOnBack = resolved.closeOnBack;
     this.routedTo = opts.routedTo;
+    this.stackEffectEnabled = opts.stackEffect ?? false;
     this.snapPointsRaw = opts.snapPoints;
     this.persistKey = opts.persistKey;
     if (opts.linkedSheets) {
@@ -2251,7 +2380,7 @@ var BottomSheetEngine = class {
       this.snapPointsRaw,
       resolved.initialAllowed,
       this.mode,
-      () => this.handle.offsetHeight,
+      () => layoutAxis(this.mode) === "width" ? this.handle.offsetWidth : this.handle.offsetHeight,
       (maxAxisSize) => {
         this.element.style[layoutAxis(this.mode)] = `${maxAxisSize}px`;
       }
@@ -2330,21 +2459,6 @@ var BottomSheetEngine = class {
   on(event, fn) {
     return this.bus.on(event, fn);
   }
-  /**
-   * Register a plugin. `install` runs synchronously; if it returns a function,
-   * it's captured for teardown during `destroy()`. No-op if already destroyed
-   * — installing into a torn-down engine would leak listeners.
-   *
-   * Throws from `plugin.install` are caught and rethrown via `queueMicrotask`
-   * so a buggy plugin can't take the engine down with it: the engine stays
-   * usable, sibling plugins still install, and the error surfaces in dev tools
-   * on the next tick instead of being swallowed. Mirrors the per-fn isolation
-   * model used for teardowns.
-   *
-   * Plugins that accept the second `scope` argument get transactional cleanup:
-   * push partial-install cleanups via `scope.add(fn)` and the engine drains
-   * them on throw, OR merges them into destroy-time teardowns on success.
-   */
   use(plugin) {
     if (this.destroyed) {
       console.warn(
@@ -2354,9 +2468,6 @@ var BottomSheetEngine = class {
     }
     const scoped = [];
     const scope = {
-      // typeof check — not just truthiness — so a JS-only plugin pushing a
-      // bogus value is silently rejected instead of queueing a confusing
-      // TypeError on destroy() drain.
       add: (fn) => {
         if (typeof fn === "function") scoped.push(fn);
       }
@@ -2385,36 +2496,13 @@ var BottomSheetEngine = class {
     }
     return this;
   }
-  /**
-   * Replace the linked-sheets list at runtime. Use when peer engines aren't
-   * available at construction time (mounted later in the tree). The wiring
-   * to the `open` event is independent of this list — it reads `linkedSheets`
-   * lazily on emit, so this setter is a simple field swap.
-   */
   setLinkedSheets(sheets) {
     if (this.destroyed) return;
     this.linkedSheets = sheets;
   }
-  /** Read-only view of the current allow-list, for cross-sheet target negotiation. */
   getAllowedIds() {
     return this.snaps.getAllowedIds().slice();
   }
-  /**
-   * Animate to a snap point by id. Resolves when the animation completes.
-   *
-   * Two call shapes:
-   * ```ts
-   * engine.snapTo("full");                           // default velocity
-   * engine.snapTo("full", 0.5);                      // px/ms initial velocity
-   * engine.snapTo("full", { velocity: 0.5, signal }); // abortable
-   * ```
-   *
-   * When `opts.signal` is provided, calling `controller.abort()` cancels the
-   * in-flight tween/spring and the returned promise resolves without firing
-   * `snap`. The captured `AbortSignal` is checked after each await so external
-   * aborts ride the same cycle invariant as internal ones (resize, destroy,
-   * concurrent snapTo).
-   */
   async snapTo(id, velocityOrOpts = 0, _skipBeforeSnap = false) {
     if (this.destroyed) return;
     const opts = typeof velocityOrOpts === "object" ? velocityOrOpts : { velocity: velocityOrOpts };
@@ -2473,16 +2561,6 @@ var BottomSheetEngine = class {
       this.handleClose();
     }
   }
-  /**
-   * Drive the sheet to an arbitrary px size, bypassing snap matching.
-   * Useful for preview scrubs, animation chaining, or programmatic gestures.
-   * Animates with the configured spring/tween. Resolves when the animation
-   * completes. Does NOT update `activeId` — call `snapTo(id)` after to commit.
-   *
-   * Unlike `snapTo`, this does not fire `before-snap` (it isn't a snap commit)
-   * nor `snap` (the sheet isn't settling to a known snap). `progress` events
-   * still fire via applySize. Target is clamped to `[0, maxAxisSize]`.
-   */
   async dragTo(targetSize, velocityOrOpts = 0) {
     if (this.destroyed) return;
     const opts = typeof velocityOrOpts === "object" ? velocityOrOpts : { velocity: velocityOrOpts };
@@ -2512,28 +2590,13 @@ var BottomSheetEngine = class {
   }
   setAllowed(ids, snap) {
     if (this.destroyed) return;
-    const willSnap = snap !== void 0 && ids.includes(snap) || !ids.includes(this.activeId) && ids.length > 0;
-    if (!willSnap) {
-      this.animation.cancel();
-      this.newCycle();
-    }
     this.snaps.setAllowedIds(ids);
     this.updateAriaSlider();
     if (snap && ids.includes(snap)) {
-      void this.snapTo(
-        snap,
-        0,
-        /* internal */
-        true
-      );
+      void this.snapTo(snap, 0, true);
     } else if (!ids.includes(this.activeId)) {
       const fallback = ids[0];
-      if (fallback) void this.snapTo(
-        fallback,
-        0,
-        /* internal */
-        true
-      );
+      if (fallback) void this.snapTo(fallback, 0, true);
     }
   }
   setBackdropRange(range) {
@@ -2551,21 +2614,6 @@ var BottomSheetEngine = class {
   setScrimInteractive(interactive) {
     this.scrim.setScrimInteractive(interactive);
   }
-  /**
-   * Batch-update multiple scrim fields in one call. Apply order is:
-   *   1. `preset` — fills baseline color/blur/range/interactive.
-   *   2. `mode` — re-positions the scrim (fixed inset / clear / hide).
-   *   3. `enabled` — flips the opacity contribution on/off.
-   *   4. `tapToClose` — installs/tears the click listener.
-   *   5. `color` / `blur` / `interactive` / `range` — explicit overrides.
-   *   6. ONE `applySize` so the per-frame opacity stays consistent.
-   *
-   * Performance: collecting changes here (vs calling individual setters)
-   * avoids repeated `applySize` calls during a multi-field swap. Setters
-   * called here suppress their own internal `applySize` either by passing
-   * through fast-paths (mode/enabled no-op when value unchanged) or by
-   * being visual-only (color/blur/interactive don't influence opacity).
-   */
   setScrim(opts) {
     this.scrim.setScrim(opts, () => this.applySize(this.size));
   }
@@ -2581,11 +2629,79 @@ var BottomSheetEngine = class {
   setScrimOverlay(opts) {
     return this.scrim.setScrimOverlay(opts);
   }
-  /**
-   * Read-only snapshot of scrim state. Use the `setScrim*` setters to mutate.
-   * Stable public API — internals (e.g. cached opacity sentinels) are NOT
-   * exposed so consumers can't accidentally couple to ScrimController shape.
-   */
+  addAnchor(opts) {
+    if (this.destroyed || typeof document === "undefined") return () => {
+    };
+    if (!this.anchorHost) {
+      this.anchorHost = this.rootEl ?? this.element.parentElement ?? document.body;
+      this.anchorHost.style.setProperty("--bs-size", `${this.size}px`);
+      this.anchorHost.style.setProperty(
+        "--bs-progress",
+        String(this.computeProgress(this.size))
+      );
+    }
+    const handle = attachAnchor(
+      {
+        mode: this.mode,
+        host: this.anchorHost,
+        getState: () => ({
+          activeId: this.activeId,
+          size: this.size,
+          progress: this.computeProgress(this.size)
+        }),
+        on: (event, fn) => this.on(event, fn),
+        isDestroyed: () => this.destroyed
+      },
+      opts
+    );
+    handle.syncZ(this.stackZ + 1);
+    this.anchors.push(handle);
+    const detach = () => {
+      const idx = this.anchors.indexOf(handle);
+      if (idx === -1) return;
+      this.anchors.splice(idx, 1);
+      handle.detach();
+    };
+    this.teardowns.add(detach);
+    return detach;
+  }
+  setScrimStages(opts) {
+    if (this.destroyed || typeof document === "undefined") return () => {
+    };
+    this.detachScrimStages?.();
+    this.detachScrimStages = null;
+    if (!opts) return () => {
+    };
+    const host = this.screenComponent?.parentElement;
+    if (!host) {
+      console.warn(
+        "[BottomSheet] setScrimStages: no scrim element mounted \u2014 pass `scrim` to the engine first."
+      );
+      return () => {
+      };
+    }
+    const detachInstalled = installScrimStages(
+      {
+        mode: this.mode,
+        host,
+        getState: () => ({
+          activeId: this.activeId,
+          size: this.size,
+          progress: this.computeProgress(this.size)
+        }),
+        on: (event, fn) => this.on(event, fn),
+        isDestroyed: () => this.destroyed
+      },
+      opts
+    );
+    const detach = () => {
+      if (this.detachScrimStages === detach) this.detachScrimStages = null;
+      detachInstalled();
+    };
+    this.detachScrimStages = detach;
+    this.teardowns.add(() => this.detachScrimStages?.());
+    return detach;
+  }
   getScrimState() {
     return { mode: this.scrim.scrimMode, enabled: this.scrim.scrimEnabled };
   }
@@ -2631,24 +2747,11 @@ var BottomSheetEngine = class {
   emit(event, payload) {
     this.bus.emit(event, payload);
   }
-  /**
-   * Abort the current cycle's signal and replace the controller. Returns the
-   * fresh signal so the caller can capture it locally before any await — when
-   * a future newCycle() / destroy aborts our controller, the captured signal
-   * flips to aborted and post-await guards short-circuit.
-   */
   newCycle() {
     this.currentAbort.abort();
     this.currentAbort = new AbortController();
     return this.currentAbort.signal;
   }
-  /**
-   * Fire `before-snap` and report whether a listener cancelled it. The
-   * `cancel()` callback exposed to listeners is frozen after the synchronous
-   * emit phase so async callers can't silently miss — they get a console
-   * warning. Returns `true` when cancelled so callers can early-return /
-   * spring-back without re-implementing the cancel/frozen pattern.
-   */
   emitBeforeSnap(target, previousId) {
     let cancelled = false;
     let frozen = false;
@@ -2682,59 +2785,54 @@ var BottomSheetEngine = class {
     this.snaps.setRaw(this.snapPointsRaw);
     this.scrim.invalidateOpacityCache();
   }
-  /**
-   * Memoised `allowedRange()` — delegates to SnapResolver which owns the cache.
-   * Engine wrapper kept so existing call sites don't all need updating;
-   * resolver-level memoization survives across method invocations.
-   */
   getAllowedRange() {
     return this.snaps.getAllowedRange();
   }
-  /**
-   * Write ARIA slider value attributes onto the handle so the engine itself
-   * is the source of truth for screen-reader announcements. Called from the
-   * constructor and from every code path that mutates `activeId` /
-   * `allowedIds`. WAI-ARIA 1.2 requires `aria-valuenow` for `role="slider"` —
-   * without it screen readers can't announce drag/snap progress to keyboard
-   * + AT users (WCAG 4.1.2 Name, Role, Value).
-   *
-   * Engine does NOT set `role="slider"` itself — that's the adapter's or
-   * consumer markup's responsibility. We only decorate with dynamic values.
-   *
-   * Empty allowed-list is malformed input (settable via `setAllowed([])`);
-   * short-circuit to remove ARIA value attributes so screen readers see a
-   * no-value slider rather than a degenerate `min=max=now=0` (WAI-ARIA 1.2
-   * requires `valuemax > valuemin` for `role="slider"`).
-   */
+  allowedIdsBySize() {
+    return this.snaps.getAllowedIds().slice().sort(
+      (a, b) => (this.snaps.findById(a)?.size ?? 0) - (this.snaps.findById(b)?.size ?? 0)
+    );
+  }
   updateAriaSlider() {
-    this.aria.setValue(this.snaps.getAllowedIds(), this.activeId);
+    this.aria.setValue(this.allowedIdsBySize(), this.activeId);
   }
   registerInStack() {
     this.teardowns.add(sheetStack.push({
       id: this.id,
       setZIndex: (z) => {
+        this.stackZ = z;
         this.element.style.zIndex = String(z);
         if (this.backdrop) this.backdrop.style.zIndex = String(z - 1);
+        for (const anchor of this.anchors) anchor.syncZ(z + 1);
       },
       setIsTop: (isTop) => {
         this.isTopSheet = isTop;
         if (this.backdrop) {
           this.backdrop.style.display = isTop ? "" : "none";
         }
-      }
+      },
+      isOpen: () => this.size > 0,
+      setDepth: (depth) => this.applyStackDepth(depth)
     }));
   }
+  applyStackDepth(depth) {
+    if (!this.stackEffectEnabled) return;
+    this.element.setAttribute("data-stack-depth", String(depth));
+    if (!this.stackEffectPrimed) {
+      this.stackEffectPrimed = true;
+      const isVertical = this.mode === "bottom" || this.mode === "top";
+      this.element.style.transformOrigin = isVertical ? "50% 100%" : "0% 50%";
+      this.element.style.transition = "scale 320ms cubic-bezier(0.29, 1.04, 0.84, 0.99)";
+    }
+    const scale = Math.max(1 - depth * 0.04, 0.86);
+    this.element.style.scale = scale === 1 ? "" : String(scale);
+  }
   attach() {
     this.gesture = new GestureController({
       handle: this.handle,
       element: this.element,
       mode: this.mode,
       getRoot: () => this.rootEl,
-      // Single coalesced reader — narrows the DI surface and removes 3 getter
-      // dispatches per onMove frame at 60-120Hz. Returns a SHARED buffer
-      // (this.dragContextBuf) — see field JSDoc for the retention contract.
-      // Inner `range` object is mutated in place too so callers caching its
-      // identity between frames stay valid.
       getDragContext: () => {
         const buf = this.dragContextBuf;
         const r = this.getAllowedRange();
@@ -2788,7 +2886,7 @@ var BottomSheetEngine = class {
         container: this.scrollContainer,
         isDragging: () => this.gesture?.isDragging ?? false,
         isAnimating: () => this.animation.isAnimating,
-        getAllowedIds: () => this.snaps.getAllowedIds(),
+        getAllowedIds: () => this.allowedIdsBySize(),
         getActiveId: () => this.activeId,
         snapTo: (id) => {
           void this.snapTo(id);
@@ -2817,11 +2915,13 @@ var BottomSheetEngine = class {
         },
         newCycle: () => {
           this.newCycle();
-        }
+        },
+        isAnimating: () => this.animation.isAnimating,
+        resyncAfterCancel: () => this.resyncAfterResize()
       }));
       if (this.lifecycle.closeOnEscape) {
         const onKey = (e) => {
-          if (this.destroyed) return;
+          if (this.destroyed || e.defaultPrevented) return;
           if (e.key === "Escape" && this.isTopSheet && this.size > 0) {
             void this.close();
           }
@@ -2853,7 +2953,7 @@ var BottomSheetEngine = class {
       handle: this.handle,
       mode: this.mode,
       isDestroyed: () => this.destroyed,
-      getAllowedIds: () => this.snaps.getAllowedIds(),
+      getAllowedIds: () => this.allowedIdsBySize(),
       getActiveId: () => this.activeId,
       snapTo: (id) => {
         void this.snapTo(id);
@@ -2874,6 +2974,7 @@ var BottomSheetEngine = class {
     });
     if (!target) return;
     const previousId = this.activeId;
+    if (target.id === previousId && target.size === this.size) return;
     if (this.emitBeforeSnap(target, previousId)) {
       const restore = this.snaps.findById(previousId);
       if (restore) {
@@ -2882,6 +2983,7 @@ var BottomSheetEngine = class {
       return;
     }
     const previousSize = this.size;
+    const previousSnapSize = this.snaps.findById(previousId)?.size;
     this.scrollCache.cache(previousId, previousSize, target.size);
     this.activeId = target.id;
     void this.animation.animateTo(target.size, velocity).then(() => {
@@ -2890,9 +2992,10 @@ var BottomSheetEngine = class {
       this.updateAriaSlider();
       this.emit("snap", { id: target.id, size: target.size });
       this.haptic();
-      if (previousId === "closed" && target.size > 0) {
+      if (previousSnapSize === 0 && target.size > 0) {
         this.emit("open", { id: target.id });
         this.handleOpen();
+        notifyLinkedSheets(this.linkedSheets, this);
       }
       if (target.size === 0) {
         this.emit("close", void 0);
@@ -2900,7 +3003,6 @@ var BottomSheetEngine = class {
       }
     });
   }
-  /** Trigger a brief haptic tick (iOS Safari + Android Chrome support). */
   haptic() {
     if (typeof navigator !== "undefined" && "vibrate" in navigator) {
       try {
@@ -2916,6 +3018,12 @@ var BottomSheetEngine = class {
     style.transform = this.transformTemplate(offset);
     if (this.sizeWriteSentinel.shouldWrite(size, SIZE_WRITE_EPSILON)) {
       style.setProperty("--bs-size", `${size}px`);
+      if (this.scrimParent) {
+        this.scrimParent.style.setProperty("--bs-size", `${size}px`);
+      }
+      if (this.anchorHost && this.anchorHost !== this.scrimParent) {
+        this.anchorHost.style.setProperty("--bs-size", `${size}px`);
+      }
     }
     const progress = this.computeProgress(size);
     const progressChanged = this.progressWriteSentinel.shouldWrite(
@@ -2924,6 +3032,9 @@ var BottomSheetEngine = class {
     );
     if (progressChanged) {
       style.setProperty("--bs-progress", String(progress));
+      if (this.anchorHost) {
+        this.anchorHost.style.setProperty("--bs-progress", String(progress));
+      }
     }
     this.scrim.applyOpacity(progress, progressChanged);
     if (progressChanged && this.bus.listenerCount("progress") > 0) {
@@ -2938,6 +3049,7 @@ var BottomSheetEngine = class {
     return Math.min(Math.max((size - min) / (max - min), 0), 1);
   }
   handleOpen() {
+    sheetStack.promote(this.id);
     try {
       this.lifecycle.install();
     } catch (err) {
@@ -2951,8 +3063,24 @@ var BottomSheetEngine = class {
       });
     }
   }
+  resyncAfterResize() {
+    if (this.destroyed) return;
+    const target = this.snaps.findById(this.activeId);
+    if (!target) return;
+    this.updateAriaSlider();
+    this.emit("snap", { id: target.id, size: target.size });
+    if (target.size > 0 && !this.lifecycle.isInstalled) {
+      this.emit("open", { id: target.id });
+      this.handleOpen();
+      notifyLinkedSheets(this.linkedSheets, this);
+    } else if (target.size === 0 && this.lifecycle.isInstalled) {
+      this.emit("close", void 0);
+      this.handleClose();
+    }
+  }
   handleClose() {
     this.lifecycle.release();
+    sheetStack.update();
   }
 };
 
@@ -3047,8 +3175,6 @@ var OverlayEngine = class {
     __publicField(this, "exitEasing");
     __publicField(this, "backdropOpacity");
     __publicField(this, "backdropFilter");
-    // Definite-assignment: written via assignSwipeFromConfig in the
-    // constructor — TS can't follow the helper, mark the assertion explicit.
     __publicField(this, "swipeToCloseEnabled");
     __publicField(this, "swipeThreshold");
     __publicField(this, "swipeVelocityThreshold");
@@ -3063,18 +3189,16 @@ var OverlayEngine = class {
     __publicField(this, "closeOnOutsidePointerEnabled");
     __publicField(this, "detachOutsidePointer", null);
     __publicField(this, "detachSwipe", null);
+    __publicField(this, "respectReducedMotionEnabled");
+    __publicField(this, "isTop", true);
+    __publicField(this, "backPushed", false);
+    __publicField(this, "movedToTarget", false);
     __publicField(this, "onOpenCb");
     __publicField(this, "onCloseCb");
     __publicField(this, "isOpen_", false);
     __publicField(this, "isAnimating_", false);
     __publicField(this, "destroyed", false);
-    // Tracks whether setOverlayChildren ever populated the panel — lets
-    // clearOverlayChildren skip the DOM mutation when nothing was injected
-    // (so the field also acts as a zero-allocation feature flag).
     __publicField(this, "hasInjectedChildren", false);
-    // Bumped on every open/close. awaitTransition captures it and ignores
-    // transitionend/timeout fired by older cycles — prevents cross-cycle
-    // listener bleed during rapid toggling.
     __publicField(this, "cycleNonce", 0);
     __publicField(this, "bus", createEventBus());
     __publicField(this, "detachEscape", null);
@@ -3105,6 +3229,7 @@ var OverlayEngine = class {
     this.mountTarget = opts.mountTo;
     this.peekRaw = opts.peek;
     this.closeOnOutsidePointerEnabled = opts.closeOnOutsidePointer ?? false;
+    this.respectReducedMotionEnabled = opts.respectReducedMotion ?? true;
     this.onOpenCb = opts.onOpen;
     this.onCloseCb = opts.onClose;
     if (this.peekRaw !== void 0 && this.edge !== "bottom") {
@@ -3127,9 +3252,6 @@ var OverlayEngine = class {
         closeOnEscape: this.closeOnEscape,
         lockBodyScroll: this.bodyScrollLockEnabled,
         inertSiblings: this.inertSiblingsEnabled,
-        // Overlay-specific guard: only paint body siblings inert when the
-        // overlay element is actually a body descendant. Detached / shadow-
-        // DOM / portal overlays would otherwise lock unrelated trees.
         shouldApplyInertSiblings: () => {
           const bodyChildren = Array.from(document.body.children);
           return bodyChildren.some(
@@ -3155,15 +3277,17 @@ var OverlayEngine = class {
     this.emit("before-open", void 0);
     this.isOpen_ = true;
     this.isAnimating_ = true;
+    sheetStack.promote(this.id);
     this.element.removeAttribute("hidden");
     this.element.setAttribute("data-state", "entering");
     if (this.focusTrapEnabled) {
       this.element.setAttribute("aria-modal", "true");
     }
-    const transitionStr = `transform ${this.duration}ms ${this.enterEasing}, opacity ${this.duration}ms ease-out`;
+    const dur = this.effectiveDuration();
+    const transitionStr = `transform ${dur}ms ${this.enterEasing}, opacity ${dur}ms ease-out`;
     this.element.style.transition = transitionStr;
     if (this.backdrop) {
-      this.backdrop.style.transition = `opacity ${this.duration}ms ease-out`;
+      this.backdrop.style.transition = `opacity ${dur}ms ease-out`;
     }
     const cycle = ++this.cycleNonce;
     return new Promise((resolve) => {
@@ -3175,7 +3299,7 @@ var OverlayEngine = class {
           this.element.style.opacity = "1";
           if (this.backdrop) {
             this.backdrop.style.opacity = String(this.backdropOpacity);
-            this.backdrop.style.pointerEvents = "auto";
+            this.backdrop.style.pointerEvents = this.backdropOpacity > 0 ? "auto" : "none";
             if (this.backdropFilter) {
               this.backdrop.style.backdropFilter = this.backdropFilter;
               this.backdrop.style.webkitBackdropFilter = this.backdropFilter;
@@ -3211,7 +3335,10 @@ var OverlayEngine = class {
             });
             return resolve();
           }
-          this.awaitTransition(cycle).then(() => {
+          this.awaitTransition(
+            cycle,
+            this.enterAnimation === "fade" ? "opacity" : "transform"
+          ).then(() => {
             if (this.destroyed || cycle !== this.cycleNonce) return resolve();
             this.isAnimating_ = false;
             this.element.setAttribute("data-state", "open");
@@ -3228,11 +3355,14 @@ var OverlayEngine = class {
     this.emit("before-close", void 0);
     this.isOpen_ = false;
     this.isAnimating_ = true;
+    sheetStack.update();
+    this.popBackMarker(reason);
     this.element.setAttribute("data-state", "exiting");
-    const transitionStr = `transform ${this.duration}ms ${this.exitEasing}, opacity ${this.duration}ms ease-in`;
+    const dur = this.effectiveDuration();
+    const transitionStr = `transform ${dur}ms ${this.exitEasing}, opacity ${dur}ms ease-in`;
     this.element.style.transition = transitionStr;
     if (this.backdrop) {
-      this.backdrop.style.transition = `opacity ${this.duration}ms ease-in`;
+      this.backdrop.style.transition = `opacity ${dur}ms ease-in`;
     }
     const cycle = ++this.cycleNonce;
     return new Promise((resolve) => {
@@ -3243,7 +3373,7 @@ var OverlayEngine = class {
           this.exitAnimation,
           this.peekPx
         );
-        this.element.style.opacity = "0";
+        this.element.style.opacity = this.peekPx !== void 0 ? "1" : "0";
         if (this.backdrop) {
           this.backdrop.style.opacity = "0";
           this.backdrop.style.pointerEvents = "none";
@@ -3253,7 +3383,10 @@ var OverlayEngine = class {
           }
         }
         this.releaseInteractiveListeners();
-        this.awaitTransition(cycle).then(() => {
+        this.awaitTransition(
+          cycle,
+          this.exitAnimation === "fade" ? "opacity" : "transform"
+        ).then(() => {
           if (this.destroyed || cycle !== this.cycleNonce) return resolve();
           this.isAnimating_ = false;
           if (this.peekPx === void 0) {
@@ -3281,14 +3414,12 @@ var OverlayEngine = class {
     this.releaseInteractiveListeners();
     this.releaseStackEntry?.();
     this.releaseStackEntry = null;
+    const hadOriginalParent = this.originalParent !== null;
     this.restoreMount();
+    if (this.movedToTarget && !hadOriginalParent && this.element.parentNode) {
+      this.element.parentNode.removeChild(this.element);
+    }
   }
-  /**
-   * Runtime visual setter — opacity is applied immediately when open so a
-   * live-controls panel can preview the change without re-opening. When
-   * closed we only stash the field; next open() picks it up so we don't
-   * mutate hidden DOM (avoids paint thrash on detached panels).
-   */
   setBackdropOpacity(opacity) {
     if (this.destroyed) return;
     this.backdropOpacity = opacity;
@@ -3296,11 +3427,6 @@ var OverlayEngine = class {
       this.backdrop.style.opacity = String(opacity);
     }
   }
-  /**
-   * Runtime visual setter for `backdrop-filter`. `undefined` clears the
-   * filter (mirrors the close() behaviour). Defers to next open() when the
-   * overlay is currently closed.
-   */
   setBackdropFilter(filter) {
     if (this.destroyed) return;
     this.backdropFilter = filter;
@@ -3314,12 +3440,6 @@ var OverlayEngine = class {
       style.webkitBackdropFilter = "";
     }
   }
-  /**
-   * Toggle / reconfigure swipe-to-close at runtime. Re-resolves the flat
-   * threshold fields, then installs or tears down the pointer listener so
-   * the change applies to the CURRENT open cycle. Idempotent: safe to call
-   * with the same config repeatedly.
-   */
   setSwipeToClose(config) {
     if (this.destroyed) return;
     const wasEnabled = this.swipeToCloseEnabled;
@@ -3332,7 +3452,6 @@ var OverlayEngine = class {
       this.detachSwipe = null;
     }
   }
-  /** Animation setters only stage the field — applied on next open/close. */
   setEnterAnimation(animation) {
     if (this.destroyed) return;
     this.enterAnimation = animation;
@@ -3341,23 +3460,15 @@ var OverlayEngine = class {
     if (this.destroyed) return;
     this.exitAnimation = animation;
   }
-  /** Updates the field used at next close() — no immediate side effect. */
   setReturnFocus(target) {
     if (this.destroyed) return;
     this.lifecycle.setReturnFocus(target);
   }
-  /**
-   * Batch update — preset first, then individual overrides. Applied as a
-   * single DOM-write phase when open so live-controls don't trigger
-   * cascading reflows. Safe to call when closed (defers to next open).
-   */
   setOverlay(opts) {
     if (this.destroyed) return;
     const preset = opts.preset ? OVERLAY_PRESETS[opts.preset] : void 0;
     const merged = preset ? {
       backdropOpacity: preset.backdropOpacity,
-      // Preset's `undefined` filter means "no filter" — surface as null
-      // so the merged step clears the field instead of inheriting old.
       backdropFilter: preset.backdropFilter === void 0 ? null : preset.backdropFilter,
       swipeToClose: preset.swipeToClose,
       enterAnimation: preset.enterAnimation,
@@ -3408,6 +3519,36 @@ var OverlayEngine = class {
         }
       }
     }
+    if (opts.duration !== void 0) this.duration = opts.duration;
+    if (opts.enterEasing !== void 0) this.enterEasing = opts.enterEasing;
+    if (opts.exitEasing !== void 0) this.exitEasing = opts.exitEasing;
+    if (opts.closeOnEscape !== void 0) {
+      this.closeOnEscape = opts.closeOnEscape;
+      if (!opts.closeOnEscape) {
+        this.detachEscape?.();
+        this.detachEscape = null;
+      } else if (this.isOpen_) {
+        this.installInteractiveListeners();
+      }
+    }
+    if (opts.closeOnBackdrop !== void 0) {
+      this.closeOnBackdropEnabled = opts.closeOnBackdrop;
+      if (!opts.closeOnBackdrop) {
+        this.detachBackdrop?.();
+        this.detachBackdrop = null;
+      } else if (this.isOpen_) {
+        this.installInteractiveListeners();
+      }
+    }
+    if (opts.closeOnOutsidePointer !== void 0) {
+      this.closeOnOutsidePointerEnabled = opts.closeOnOutsidePointer;
+      if (!opts.closeOnOutsidePointer) {
+        this.detachOutsidePointer?.();
+        this.detachOutsidePointer = null;
+      } else if (this.isOpen_) {
+        this.installInteractiveListeners();
+      }
+    }
     if (opts.children !== void 0) {
       if (opts.children === null) {
         this.clearOverlayChildren();
@@ -3416,30 +3557,17 @@ var OverlayEngine = class {
       }
     }
   }
-  /**
-   * Runtime children injection — replace the panel's contents without
-   * unmounting the engine. `replaceChildren()` is a single atomic DOM op,
-   * so callers can swap content rapidly without intermediate flicker.
-   * Function form is resolved exactly ONCE per call (cheap lazy content).
-   */
   setOverlayChildren(children) {
     if (this.destroyed) return;
     const node = typeof children === "function" ? children() : children;
     this.element.replaceChildren(node);
     this.hasInjectedChildren = true;
   }
-  /**
-   * Clear injected children. No-op when nothing was injected so consumers
-   * who never used setOverlayChildren can call this defensively without
-   * paying for a DOM mutation.
-   */
   clearOverlayChildren() {
     if (this.destroyed || !this.hasInjectedChildren) return;
     this.element.replaceChildren();
     this.hasInjectedChildren = false;
   }
-  // Shared swipe-config normalizer — used by constructor, setSwipeToClose,
-  // and setOverlay so the union/object shape is decoded in exactly one place.
   assignSwipeFromConfig(swipe) {
     if (typeof swipe === "object" && swipe !== null) {
       this.swipeToCloseEnabled = swipe.enabled ?? true;
@@ -3454,6 +3582,22 @@ var OverlayEngine = class {
   emit(event, payload) {
     this.bus.emit(event, payload);
   }
+  effectiveDuration() {
+    return this.respectReducedMotionEnabled && prefersReducedMotion() ? 0 : this.duration;
+  }
+  popBackMarker(reason) {
+    if (!this.backPushed) return;
+    this.backPushed = false;
+    if (reason === "back") return;
+    const state = history.state;
+    if (state && state.__bsOverlay === this.id) {
+      try {
+        history.back();
+      } catch {
+        return;
+      }
+    }
+  }
   resolvePeekPx(raw) {
     if (typeof raw === "number") return Math.max(0, raw);
     try {
@@ -3475,6 +3619,7 @@ var OverlayEngine = class {
     this.originalParent = this.element.parentNode;
     this.originalNextSibling = this.element.nextSibling;
     target.appendChild(this.element);
+    this.movedToTarget = true;
     this.mounted = true;
   }
   restoreMount() {
@@ -3508,7 +3653,7 @@ var OverlayEngine = class {
       this.backdrop.style.willChange = "opacity";
     }
   }
-  awaitTransition(cycle) {
+  awaitTransition(cycle, property = "transform") {
     return new Promise((resolve) => {
       let done = false;
       const finish = () => {
@@ -3523,10 +3668,10 @@ var OverlayEngine = class {
           finish();
           return;
         }
-        if (e.propertyName === "transform") finish();
+        if (e.target === this.element && e.propertyName === property) finish();
       };
       this.element.addEventListener("transitionend", onEnd);
-      const timer = window.setTimeout(finish, this.duration + 50);
+      const timer = window.setTimeout(finish, this.effectiveDuration() + 50);
     });
   }
   installInteractiveListeners() {
@@ -3536,7 +3681,10 @@ var OverlayEngine = class {
     }
     if (this.closeOnEscape && !this.detachEscape) {
       const handler = (e) => {
-        if (e.key === "Escape" && this.isOpen_) void this.close("escape");
+        if (e.defaultPrevented) return;
+        if (e.key === "Escape" && this.isOpen_ && this.isTop) {
+          void this.close("escape");
+        }
       };
       document.addEventListener("keydown", handler);
       this.detachEscape = () => document.removeEventListener("keydown", handler);
@@ -3549,10 +3697,14 @@ var OverlayEngine = class {
     if (this.closeOnBackEnabled && typeof window !== "undefined" && !this.detachHardwareBack) {
       try {
         history.pushState({ __bsOverlay: this.id }, "");
+        this.backPushed = true;
       } catch {
       }
       const onPop = () => {
-        if (this.isOpen_) void this.close("back");
+        if (this.isOpen_ && this.isTop) {
+          this.backPushed = false;
+          void this.close("back");
+        }
       };
       window.addEventListener("popstate", onPop);
       this.detachHardwareBack = () => window.removeEventListener("popstate", onPop);
@@ -3583,55 +3735,57 @@ var OverlayEngine = class {
     this.detachOutsidePointer = null;
     this.lifecycle.release();
   }
-  /**
-   * Light pointer-driven dismiss. Tracks finger along the edge axis, follows
-   * with translate, dismisses if past `swipeThreshold` (fraction of panel
-   * size) or release velocity exceeds `swipeVelocityThreshold` (px/ms).
-   * Pure CSS-transform during drag — no rAF or physics required since the
-   * panel only moves one direction.
-   */
   installSwipeToClose() {
     const el = this.element;
     const edge = this.edge;
     const isVertical = edge === "bottom" || edge === "top";
     const sign = edge === "bottom" || edge === "right" ? 1 : -1;
-    const threshold = this.swipeThreshold;
-    const velocityThreshold = this.swipeVelocityThreshold;
+    const SLOP = 8;
     let startX = 0;
     let startY = 0;
     let startT = 0;
+    let tracking = false;
     let dragging = false;
     let pointerId = null;
+    const previousTouchAction = el.style.touchAction;
+    el.style.touchAction = isVertical ? "pan-x" : "pan-y";
     const onDown = (e) => {
       if (e.button !== void 0 && e.button !== 0) return;
       pointerId = e.pointerId;
       startX = e.clientX;
       startY = e.clientY;
       startT = performance.now();
-      dragging = true;
-      el.style.transition = "none";
-      try {
-        el.setPointerCapture(e.pointerId);
-      } catch {
-      }
+      tracking = true;
+      dragging = false;
     };
     const onMove = (e) => {
-      if (!dragging || e.pointerId !== pointerId) return;
+      if (!tracking || e.pointerId !== pointerId) return;
       const delta = isVertical ? e.clientY - startY : e.clientX - startX;
+      if (!dragging) {
+        if (Math.abs(delta) < SLOP) return;
+        dragging = true;
+        el.style.transition = "none";
+        try {
+          el.setPointerCapture(e.pointerId);
+        } catch {
+        }
+      }
       const offset = Math.max(0, sign * delta);
       el.style.transform = isVertical ? `translate3d(0, ${sign * offset}px, 0)` : `translate3d(${sign * offset}px, 0, 0)`;
     };
     const finish = (e) => {
-      if (!dragging || e.pointerId !== pointerId) return;
-      dragging = false;
+      if (!tracking || e.pointerId !== pointerId) return;
+      tracking = false;
       pointerId = null;
+      if (!dragging) return;
+      dragging = false;
       const dt = performance.now() - startT || 1;
       const delta = isVertical ? e.clientY - startY : e.clientX - startX;
       const offset = Math.max(0, sign * delta);
       const velocity = sign * delta / dt;
       const size = isVertical ? el.offsetHeight : el.offsetWidth;
-      const past = offset > size * threshold || velocity > velocityThreshold;
-      el.style.transition = `transform ${this.duration}ms ${this.exitEasing}`;
+      const past = offset > size * this.swipeThreshold || velocity > this.swipeVelocityThreshold;
+      el.style.transition = `transform ${this.effectiveDuration()}ms ${this.exitEasing}`;
       if (past) {
         void this.close("swipe");
       } else {
@@ -3643,6 +3797,7 @@ var OverlayEngine = class {
     el.addEventListener("pointerup", finish);
     el.addEventListener("pointercancel", finish);
     return () => {
+      el.style.touchAction = previousTouchAction;
       el.removeEventListener("pointerdown", onDown);
       el.removeEventListener("pointermove", onMove);
       el.removeEventListener("pointerup", finish);
@@ -3657,10 +3812,12 @@ var OverlayEngine = class {
         if (this.backdrop) this.backdrop.style.zIndex = String(z - 1);
       },
       setIsTop: (isTop) => {
+        this.isTop = isTop;
         if (this.backdrop) {
           this.backdrop.style.display = isTop ? "" : "none";
         }
-      }
+      },
+      isOpen: () => this.isOpen_
     });
   }
 };
@@ -3673,6 +3830,7 @@ exports.Overlay = OverlayEngine;
 exports.OverlayEngine = OverlayEngine;
 exports.SCRIM_PRESETS = SCRIM_PRESETS;
 exports.allowedRange = allowedRange;
+exports.applyOverlayPosition = applyOverlayPosition;
 exports.attachGestures = attachGestures;
 exports.createOverlay = createOverlay;
 exports.createSheetManager = createSheetManager;
@@ -3684,8 +3842,10 @@ exports.installFocusTrap = installFocusTrap;
 exports.installGestures = installGestures;
 exports.lockBodyScroll = lockBodyScroll;
 exports.prefersReducedMotion = prefersReducedMotion;
+exports.resolveSheetAnchoredStyle = resolveSheetAnchoredStyle;
 exports.resolveSnap = resolveSnap;
 exports.resolveSnapList = resolveSnapList;
+exports.runAnchorTransition = runAnchorTransition;
 exports.runSpring = runSpring;
 exports.sheetStack = sheetStack;
 exports.tween = tween;