modal_stack 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d872f05608ece432767e38bbe58ec38bf97c60a0cd90ccf1afd37f41f7f6192
-  data.tar.gz: 3da69811422baf2e1e7927bae0dbe46cf75311b5214e34e90e0a04e8aa691250
+  metadata.gz: a4ea30705b3d178cd2be1ad1a3b0a7b5487b40490b327d0e727b29e9e644f06f
+  data.tar.gz: '049b2eafb22af9cffd3ec3d454a23550dff04273cb23e4b96146a3716a62a383'
 SHA512:
-  metadata.gz: 3d9470889c9fa8b2d967174818eb813a90657baac94a70edadf3f7a416400e364cc5e15ed9b7274544b138f8b5647189e21143b14aa27d67cac79ae711822d20
-  data.tar.gz: 5dcdab2a2dca8c1b57b67e62f1daff68cc3b04395e5e66d9a3da933de02caef78460116c4b097fb040fa33011a83eb79f0645d6e273e91ad21ec552a27023d1b
+  metadata.gz: da14584321b5c28cd93ecbc9dd260865313c5ccd62e17d7846a734c3da47b54e3f0ac20b703542cb14d8cc93fe3611c5de0d7e17c06900ecab92c554ae5c806f
+  data.tar.gz: 111ac685cf469d968fb71288cc13822d059e97212a01b098d3766ce0136990ac1b0db4384777a86245fb6923cb225fc62c23543979d79fe18efbc1d2b1e8dbfe

data/CHANGELOG.md

@@ -12,6 +12,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+## [0.3.0] - 2026-05-03
+
+### Added
+- **Prefetch cache + dedupe** in `Orchestrator`: fragments fetched for `push` / `replaceTop` are cached per URL (TTL 30 s) and concurrent prefetches for the same URL share a single in-flight request. Aborts pending requests on `closeAll` and on stack-mismatching `popstate`.
+- **Hover/focus prefetch** on `modal-stack-link`: links warm the cache on `pointerenter` / `focus` so the modal opens with no network latency on click. Opt out with `data-modal-stack-link-prefetch="false"`.
+- **`Orchestrator#prefetch(url)`** public method (and matching `ModalStackController#prefetch`) for warming the cache from app code.
+- **Request-scoped configuration** via `controller.modal_stack_config` (helper-method exposed). Rendering helpers now read configuration once per request instead of once per call.
+- **`:tailwind_v4` CSS preset** that chains on Tailwind v4 `@theme` tokens (`--color-*`, `--radius-*`, `--shadow-*`, `--ease-*`, `--container-*`), so the modal stack inherits the host project's Tailwind theme automatically. Fallbacks match the Tailwind v4 defaults so the preset still renders correctly when `@theme` isn't redefined (or when Tailwind v4 isn't installed).
+- **`:tailwind_v3` CSS preset** — the previous `:tailwind` preset, renamed for clarity. Static values aligned with Tailwind v3 defaults (Tailwind v3 doesn't expose tokens as CSS variables).
+- `Configuration::CSS_PROVIDER_ALIASES` constant for legacy `:tailwind` → `:tailwind_v3` normalization.
+- New tests: prefetch dedupe / cache hit / TTL / abort-on-closeAll / `prefetch` API; CSS-derived leave timeout; `:tailwind` alias normalization; generator default + alias mapping.
+
+### Changed
+- **Animation safety timeout** is now derived from the `--modal-stack-duration` CSS variable on the `<dialog>` (1.5× the declared duration, floored at 300 ms). Falls back to 600 ms when the variable is unset, so existing host CSS keeps working.
+- `BrowserRuntime#fetchFragment` accepts an `{ signal }` option to support `AbortController` cancellation.
+- **CSS preset perf overhaul**: removed animated blur from all four presets — animating `backdrop-filter: blur(2px)` on a fullscreen surface costs ~190 ms/frame on Hi-DPI displays (Retina, 4K), which collapsed modal animations to ~5 fps.
+  - The old `--modal-stack-backdrop-blur` variable (radius only) is replaced with `--modal-stack-backdrop-filter` (full filter expression). Default is `none`, which lets Chrome skip the filter pass entirely — `backdrop-filter: blur(0)` still allocated a filter layer, so a `0` radius wasn't actually free. Apps that want a blurred backdrop now opt in with `:root { --modal-stack-backdrop-filter: blur(8px); }` (any filter expression accepted, not just `blur()`).
+  - `backdrop-filter` is no longer in the backdrop's `transition` list — when the user opts in, the filter is applied statically when the dialog opens, so the cost is paid once and the per-frame compositor work disappears.
+  - `filter: blur(0.5px)` on inert (underlying) layers has been dropped — only `opacity: 0.5` remains. The blur was visually negligible on screen but forced an extra GPU layer per stacked modal.
+  - The `filter` property has been removed from the layer's `transition` list since nothing animates it any more.
+- **Backdrop fade now runs in parallel with the layer's leave animation** when closing the last modal (or `closeAll`). Previously the reducer emitted `[unmountTopLayer, …, closeDialog, …]` and the orchestrator awaited each command sequentially — `closeDialog` only fired after the layer's 220 ms `transitionend`, so the backdrop fade-out was perceived *after* the modal was gone (effective close time ≈ 440 ms). The reducer now emits `closeDialog` first; it's synchronous on the runtime, so the dialog's exit transition (opacity, backdrop background, `display`/`overlay` `allow-discrete`) starts immediately and runs alongside the layer's `[data-leaving]` transition. Total close time is now ≈ 220 ms. Fix applied to `pop`, `closeAll`, and the two `handlePopstate` branches that close the dialog.
+- **`config.css_provider` default** is now `:tailwind_v3` (was `:tailwind`). Existing apps with `config.css_provider = :tailwind` keep working — the alias is normalized to `:tailwind_v3` on assignment, with no rendered CSS change.
+- **Generator default `--css-provider`** is now `tailwind_v4` for new installs (was `tailwind`). Run `bin/rails g modal_stack:install --css-provider=tailwind_v3` to opt back in to the v3 preset, or pass the legacy `tailwind` flag — it's normalized to `tailwind_v3` in the generated initializer.
+- The `app/assets/stylesheets/modal_stack/tailwind.css` file has been renamed to `tailwind_v3.css`. Sprockets manifests written by previous installs that contain `//= link modal_stack/tailwind.css` need the line updated to `tailwind_v3.css` (or `tailwind_v4.css`). Importmap / jsbundling installs aren't affected — they don't reference the stylesheet by filename.
+- `INITIALIZER_VERSION` bumped to `0.3.0` because the generator template documents the new providers.
+
 ## [0.2.0] - 2026-05-03
 
 ### Added

data/README.md

@@ -9,9 +9,10 @@ browser back/forward support, and drive everything from imperative Turbo
 Stream actions (`modal_push`, `modal_pop`, `modal_replace`, `modal_close_all`).
 
 [![CI](https://github.com/Metalzoid/modal_stack/actions/workflows/main.yml/badge.svg)](https://github.com/Metalzoid/modal_stack/actions)
-[![Gem Version](https://badge.fury.io/rb/modal_stack.svg)](https://rubygems.org/gems/modal_stack)
-[![Ruby](https://img.shields.io/gem/ruby-version/modal_stack?label=ruby)](https://www.ruby-lang.org/)
-[![Rails](https://img.shields.io/gem/dv/modal_stack/railties?label=rails)](https://rubyonrails.org/)
+[![Gem Version](https://img.shields.io/gem/v/modal_stack.svg?label=gem)](https://rubygems.org/gems/modal_stack)
+[![Downloads](https://img.shields.io/gem/dt/modal_stack?label=downloads)](https://rubygems.org/gems/modal_stack)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
+[![Rails](https://img.shields.io/badge/rails-7.2%20%7C%208.0%20%7C%208.1-CC0000?logo=rubyonrails&logoColor=white)](https://rubyonrails.org/)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE.txt)
 
 </div>
@@ -140,10 +141,11 @@ $ bin/rails g modal_stack:install --mode=sprockets   # legacy apps
 Pick the CSS preset that matches your stack:
 
 ```bash
-$ bin/rails g modal_stack:install --css-provider=tailwind   # default
-$ bin/rails g modal_stack:install --css-provider=bootstrap  # picks up Bootstrap 5 vars
-$ bin/rails g modal_stack:install --css-provider=vanilla    # framework-free
-$ bin/rails g modal_stack:install --css-provider=none       # bring your own CSS
+$ bin/rails g modal_stack:install --css-provider=tailwind_v4 # default — chains on Tailwind v4 @theme tokens
+$ bin/rails g modal_stack:install --css-provider=tailwind_v3 # static values aligned with Tailwind v3
+$ bin/rails g modal_stack:install --css-provider=bootstrap   # picks up Bootstrap 5 vars
+$ bin/rails g modal_stack:install --css-provider=vanilla     # framework-free
+$ bin/rails g modal_stack:install --css-provider=none        # bring your own CSS
 ```
 
 ### What the generator does
@@ -204,7 +206,7 @@ Everything lives in `config/initializers/modal_stack.rb`:
 ```ruby
 ModalStack.configure do |config|
   # ─── Presentation ─────────────────────────────────────────────────
-  config.css_provider     = :tailwind   # :tailwind | :bootstrap | :vanilla | :none
+  config.css_provider     = :tailwind_v4 # :tailwind_v3 | :tailwind_v4 | :bootstrap | :vanilla | :none
   config.default_variant  = :modal      # :modal | :drawer | :bottom_sheet | :confirmation
   config.default_size     = :md         # :sm | :md | :lg | :xl
   config.default_dismissible = true     # ESC + backdrop click close the layer
@@ -420,7 +422,7 @@ ModalStack.reset_configuration!         # test-fixture helper
 
 | Attribute                    | Type    | Default                  | Description |
 | ---------------------------- | ------- | ------------------------ | ----------- |
-| `css_provider`               | Symbol  | `:tailwind`              | One of `:tailwind`, `:bootstrap`, `:vanilla`, `:none`. Determines which stylesheet `modal_stack_stylesheet_link_tag` resolves to. Validated. |
+| `css_provider`               | Symbol  | `:tailwind_v3`           | One of `:tailwind_v3`, `:tailwind_v4`, `:bootstrap`, `:vanilla`, `:none`. Determines which stylesheet `modal_stack_stylesheet_link_tag` resolves to. The legacy `:tailwind` is accepted and normalized to `:tailwind_v3`. New installs default to `:tailwind_v4`. Validated. |
 | `assets_mode`                | Symbol  | `:auto`                  | One of `:importmap`, `:jsbundling`, `:sprockets`, `:auto`. Used by the generator. Validated. |
 | `default_variant`            | Symbol  | `:modal`                 | `:modal`, `:drawer`, `:bottom_sheet`, or `:confirmation`. Validated. |
 | `default_size`               | Symbol  | `:md`                    | `:sm`, `:md`, `:lg`, `:xl`. Validated. |
@@ -445,7 +447,7 @@ Injected into `ActionView::Base` by the engine — available in every view.
 | ------------------------------------------------- | ----------- |
 | `modal_link_to(name, options, html_options)`      | Renders a `link_to` wired to push a layer when clicked. Accepts the modal options (`as:`, `side:`, `size:`, `width:`, `height:`, `dismissible:`) on top of standard `link_to` arguments. Falls back to plain `link_to` for Hotwire Native requests. |
 | `modal_stack_container(size:, variant:, side:, width:, height:, dismissible:, html: {}) { ... }` | Wraps a panel view with the markup the JS runtime expects. Renders a `<div>` carrying the size/variant/dismissible/dimension data attributes. |
-| `modal_stack_stylesheet_link_tag(**options)`      | Emits `<link rel="stylesheet">` for the configured preset (`modal_stack/tailwind.css`, etc.). Returns an empty SafeBuffer when `css_provider = :none`. |
+| `modal_stack_stylesheet_link_tag(**options)`      | Emits `<link rel="stylesheet">` for the configured preset (`modal_stack/tailwind_v4.css`, etc.). Returns an empty SafeBuffer when `css_provider = :none`. |
 | `modal_stack_dialog_tag(**html_options)`          | Emits the singleton `<dialog id="modal-stack-root" data-controller="modal-stack">`. Drop just before `</body>`. |
 | `modal_stack_javascript_tag`                      | Reserved hook for layouts; currently a no-op (JS is loaded via your bundler / importmap). |
 
@@ -594,7 +596,7 @@ $ bin/rails g modal_stack:install [flags]
 | Flag                  | Type    | Default     | Values |
 | --------------------- | ------- | ----------- | ------ |
 | `--mode`              | String  | `auto`      | `auto`, `importmap`, `jsbundling`, `sprockets` |
-| `--css-provider`      | String  | `tailwind`  | `tailwind`, `bootstrap`, `vanilla`, `none` |
+| `--css-provider`      | String  | `tailwind_v4` | `tailwind_v3`, `tailwind_v4`, `bootstrap`, `vanilla`, `none` (legacy `tailwind` accepted, normalized to `tailwind_v3`) |
 | `--skip-layout`       | Boolean | `false`     | When set, doesn't inject the stylesheet/dialog helpers into `application.html.erb` |
 | `--skip-js`           | Boolean | `false`     | When set, skips the Importmap pin / package install / Stimulus install wiring |
 | `--skip-initializer`  | Boolean | `false`     | When set, doesn't generate `config/initializers/modal_stack.rb` |
@@ -613,17 +615,18 @@ safe.
 
 ## 🎨 CSS presets & theming
 
-Three opinionated stylesheets ship with the gem. Pick one with
+Four opinionated stylesheets ship with the gem. Pick one with
 `config.css_provider`:
 
-| Preset       | File                                       | Best for |
-| ------------ | ------------------------------------------ | -------- |
-| `:tailwind`  | `app/assets/stylesheets/modal_stack/tailwind.css`  | Tailwind apps — uses Tailwind tokens by default but overridable |
-| `:bootstrap` | `app/assets/stylesheets/modal_stack/bootstrap.css` | Picks up Bootstrap 5 CSS variables |
-| `:vanilla`   | `app/assets/stylesheets/modal_stack/vanilla.css`   | Framework-free, neutral defaults |
-| `:none`      | —                                          | Bring your own CSS |
+| Preset          | File                                                  | Best for |
+| --------------- | ----------------------------------------------------- | -------- |
+| `:tailwind_v4`  | `app/assets/stylesheets/modal_stack/tailwind_v4.css`  | Tailwind v4 apps — chains on `@theme` tokens (`--color-*`, `--radius-*`, `--shadow-*`, `--container-*`) so the modal picks up your theme automatically. Falls back to Tailwind defaults when `@theme` isn't redefined. |
+| `:tailwind_v3`  | `app/assets/stylesheets/modal_stack/tailwind_v3.css`  | Tailwind v3 apps — static values aligned with Tailwind v3 defaults (v3 doesn't expose tokens as CSS variables). Legacy `:tailwind` is accepted as an alias. |
+| `:bootstrap`    | `app/assets/stylesheets/modal_stack/bootstrap.css`    | Picks up Bootstrap 5 CSS variables |
+| `:vanilla`      | `app/assets/stylesheets/modal_stack/vanilla.css`      | Framework-free, neutral defaults |
+| `:none`         | —                                                     | Bring your own CSS |
 
-All three presets are driven by the same `--modal-stack-*` CSS variables.
+All presets are driven by the same `--modal-stack-*` CSS variables.
 Override on `:root` to retheme without touching the gem:
 
 ```css
@@ -720,7 +723,7 @@ modal_stack/
 ├── app/
 │   ├── assets/
 │   │   ├── javascripts/modal_stack.js  # pre-built importmap bundle (committed)
-│   │   └── stylesheets/modal_stack/    # tailwind / bootstrap / vanilla presets
+│   │   └── stylesheets/modal_stack/    # tailwind_v3 / tailwind_v4 / bootstrap / vanilla presets
 │   ├── javascript/modal_stack/         # ES module sources + bun tests
 │   │   ├── state.js                    # pure reducer (100% coverage)
 │   │   ├── orchestrator.js             # state → command translator

data/app/assets/javascripts/modal_stack.js

@@ -126,15 +126,16 @@ function pop(state) {
     return { state, commands: [] };
   const newLayers = Object.freeze(state.layers.slice(0, -1));
   const newTop = newLayers[newLayers.length - 1] ?? null;
-  const commands = [
-    { type: "unmountTopLayer" },
-    { type: "historyBack", n: 1 }
-  ];
+  const commands = [];
   if (newTop) {
+    commands.push({ type: "unmountTopLayer" });
+    commands.push({ type: "historyBack", n: 1 });
     commands.push({ type: "inertLayer", layerId: newTop.id, value: false });
     commands.push({ type: "persistSnapshot" });
   } else {
     commands.push({ type: "closeDialog" });
+    commands.push({ type: "unmountTopLayer" });
+    commands.push({ type: "historyBack", n: 1 });
     commands.push({ type: "unlockScroll" });
     commands.push({ type: "clearSnapshot" });
   }
@@ -192,8 +193,8 @@ function closeAll(state) {
   return {
     state: { ...state, layers: Object.freeze([]) },
     commands: [
-      { type: "unmountAllLayers" },
       { type: "closeDialog" },
+      { type: "unmountAllLayers" },
       { type: "unlockScroll" },
       { type: "historyBack", n },
       { type: "clearSnapshot" }
@@ -208,8 +209,8 @@ function handlePopstate(state, { historyState, locationHref }) {
     return {
       state: { ...state, layers: Object.freeze([]) },
       commands: [
-        { type: "unmountAllLayers" },
         { type: "closeDialog" },
+        { type: "unmountAllLayers" },
         { type: "unlockScroll" },
         { type: "clearSnapshot" }
       ]
@@ -222,6 +223,8 @@ function handlePopstate(state, { historyState, locationHref }) {
     const newLayers = Object.freeze(state.layers.slice(0, targetDepth));
     const newTop = newLayers[newLayers.length - 1] ?? null;
     const commands = [];
+    if (!newTop)
+      commands.push({ type: "closeDialog" });
     for (let i = 0;i < currentDepth - targetDepth; i++) {
       commands.push({ type: "unmountTopLayer" });
     }
@@ -229,7 +232,6 @@ function handlePopstate(state, { historyState, locationHref }) {
       commands.push({ type: "inertLayer", layerId: newTop.id, value: false });
       commands.push({ type: "persistSnapshot" });
     } else {
-      commands.push({ type: "closeDialog" });
       commands.push({ type: "unlockScroll" });
       commands.push({ type: "clearSnapshot" });
     }
@@ -326,21 +328,27 @@ function restore(serialized, { stackId, maxAgeMs = DEFAULT_MAX_AGE_MS, now = Dat
 }
 
 // app/javascript/modal_stack/orchestrator.js
+var PREFETCH_TTL_MS = 30000;
+
 class Orchestrator {
   #expectedPopstates = 0;
+  #fragmentCache = new Map;
+  #inflight = new Map;
   constructor({
     runtime,
     stackId,
     baseUrl,
     restoreFrom = null,
     maxDepth = null,
-    maxDepthStrategy = "warn"
+    maxDepthStrategy = "warn",
+    prefetchTtlMs = PREFETCH_TTL_MS
   }) {
     if (!runtime)
       throw new Error("runtime required");
     this.runtime = runtime;
     this.maxDepth = maxDepth;
     this.maxDepthStrategy = maxDepthStrategy;
+    this.prefetchTtlMs = prefetchTtlMs;
     this.state = createStack({ stackId, baseUrl });
     if (restoreFrom) {
       const restored = restore(restoreFrom, { stackId });
@@ -378,9 +386,44 @@ class Orchestrator {
   async#prefetch(url) {
     if (typeof this.runtime.fetchFragment !== "function")
       return null;
-    return this.runtime.fetchFragment(url);
+    const cached = this.#fragmentCache.get(url);
+    if (cached && Date.now() - cached.ts < this.prefetchTtlMs) {
+      return cloneFragment(cached.fragment);
+    }
+    const existing = this.#inflight.get(url);
+    if (existing) {
+      const entry2 = await existing.promise;
+      return cloneFragment(entry2.fragment);
+    }
+    const controller = supportsAbort() ? new AbortController : null;
+    const fetchPromise = this.runtime.fetchFragment(url, controller ? { signal: controller.signal } : undefined).then((fragment) => {
+      const entry2 = { fragment, ts: Date.now() };
+      this.#fragmentCache.set(url, entry2);
+      return entry2;
+    }).finally(() => {
+      this.#inflight.delete(url);
+    });
+    this.#inflight.set(url, { controller, promise: fetchPromise });
+    const entry = await fetchPromise;
+    return cloneFragment(entry.fragment);
+  }
+  #invalidatePrefetch() {
+    for (const { controller } of this.#inflight.values()) {
+      try {
+        controller?.abort();
+      } catch {}
+    }
+    this.#inflight.clear();
+    this.#fragmentCache.clear();
+  }
+  prefetch(url) {
+    if (!url || typeof this.runtime.fetchFragment !== "function") {
+      return Promise.resolve(null);
+    }
+    return this.#prefetch(url).catch(() => null);
   }
   closeAll() {
+    this.#invalidatePrefetch();
     return this.#dispatch(closeAll(this.state));
   }
   onPopstate({ historyState, locationHref }) {
@@ -388,6 +431,7 @@ class Orchestrator {
       this.#expectedPopstates -= 1;
       return Promise.resolve();
     }
+    this.#invalidatePrefetch();
     return this.#dispatch(handlePopstate(this.state, { historyState, locationHref }));
   }
   async#dispatch({ state, commands }, payload = {}) {
@@ -418,13 +462,26 @@ class Orchestrator {
     await handler.call(this.runtime, cmd);
   }
 }
+function cloneFragment(fragment) {
+  if (!fragment)
+    return fragment;
+  if (typeof fragment.cloneNode === "function") {
+    return fragment.cloneNode(true);
+  }
+  return fragment;
+}
+function supportsAbort() {
+  return typeof globalThis.AbortController === "function";
+}
 
 // app/javascript/modal_stack/runtime.js
 var SNAPSHOT_KEY = "modalStackSnapshot";
 var FRAGMENT_HEADER = "X-Modal-Stack-Request";
 var SCROLLBAR_WIDTH_VAR = "--modal-stack-scrollbar-width";
 var LAYER_SELECTOR = '[data-modal-stack-target="layer"]';
-var LEAVE_TIMEOUT_MS = 600;
+var DURATION_CSS_VAR = "--modal-stack-duration";
+var LEAVE_TIMEOUT_FLOOR_MS = 300;
+var LEAVE_TIMEOUT_FALLBACK_MS = 600;
 
 class BrowserRuntime {
   constructor({
@@ -502,11 +559,12 @@ class BrowserRuntime {
     const layer = this.#topLayer();
     if (!layer)
       return;
-    await animateOut(layer);
+    await animateOut(layer, this.#leaveTimeoutMs());
   }
   async unmountAllLayers() {
     const layers = [...this.dialog.querySelectorAll(LAYER_SELECTOR)];
-    await Promise.all(layers.map(animateOut));
+    const timeout = this.#leaveTimeoutMs();
+    await Promise.all(layers.map((l) => animateOut(l, timeout)));
   }
   pushHistory({ url, historyState }) {
     this.history.pushState(historyState, "", url);
@@ -543,6 +601,22 @@ class BrowserRuntime {
       return null;
     }
   }
+  #leaveTimeoutMs() {
+    if (this._cachedLeaveTimeoutMs != null)
+      return this._cachedLeaveTimeoutMs;
+    const get = globalThis.getComputedStyle;
+    if (typeof get !== "function" || !this.dialog?.ownerDocument) {
+      return LEAVE_TIMEOUT_FALLBACK_MS;
+    }
+    let parsed = NaN;
+    try {
+      const raw = get(this.dialog).getPropertyValue(DURATION_CSS_VAR);
+      parsed = parseDurationMs(raw);
+    } catch {}
+    const ms = Number.isFinite(parsed) ? Math.max(Math.ceil(parsed * 1.5), LEAVE_TIMEOUT_FLOOR_MS) : LEAVE_TIMEOUT_FALLBACK_MS;
+    this._cachedLeaveTimeoutMs = ms;
+    return ms;
+  }
   #findLayer(layerId) {
     return this.dialog.querySelector(`${LAYER_SELECTOR}[data-layer-id="${escapeAttr(layerId)}"]`);
   }
@@ -579,13 +653,14 @@ class BrowserRuntime {
       layer.style.removeProperty("height");
     }
   }
-  async fetchFragment(url) {
+  async fetchFragment(url, { signal } = {}) {
     const resp = await this.fetcher(url, {
       headers: {
         Accept: "text/html, text/vnd.turbo-stream.html",
         [FRAGMENT_HEADER]: "1"
       },
-      credentials: "same-origin"
+      credentials: "same-origin",
+      signal
     });
     if (!resp.ok) {
       throw new Error(`modal_stack: fetch ${url} → ${resp.status}`);
@@ -608,7 +683,7 @@ function parseFragment(html, doc) {
   fragment.append(...parsed.body.childNodes);
   return fragment;
 }
-function animateOut(layer) {
+function animateOut(layer, timeoutMs = LEAVE_TIMEOUT_FALLBACK_MS) {
   return new Promise((resolve) => {
     let done = false;
     const finish = () => {
@@ -621,9 +696,20 @@ function animateOut(layer) {
     };
     layer.addEventListener("transitionend", finish, { once: true });
     layer.dataset.leaving = "";
-    setTimeout(finish, LEAVE_TIMEOUT_MS);
+    setTimeout(finish, timeoutMs);
   });
 }
+function parseDurationMs(raw) {
+  if (typeof raw !== "string")
+    return NaN;
+  const value = raw.trim();
+  if (!value)
+    return NaN;
+  const num = parseFloat(value);
+  if (!Number.isFinite(num))
+    return NaN;
+  return /m?s$/i.test(value) && !/ms$/i.test(value) ? num * 1000 : num;
+}
 function escapeAttr(value) {
   if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
     return CSS.escape(value);
@@ -694,6 +780,9 @@ class ModalStackController extends Controller {
   closeAll() {
     return this.orchestrator.closeAll();
   }
+  prefetch(url) {
+    return this.orchestrator.prefetch(url);
+  }
   #topLayer() {
     const layers = this.orchestrator.layers;
     return layers[layers.length - 1] ?? null;
@@ -790,11 +879,21 @@ function generateLayerId() {
 import { Controller as Controller2 } from "@hotwired/stimulus";
 
 class ModalStackLinkController extends Controller2 {
-  open(event) {
-    const stack = document.querySelector('[data-controller~="modal-stack"]');
-    if (!stack)
+  connect() {
+    if (this.element.dataset.modalStackLinkPrefetch === "false")
+      return;
+    this._onIntent = () => this.#warm();
+    this.element.addEventListener("pointerenter", this._onIntent);
+    this.element.addEventListener("focus", this._onIntent);
+  }
+  disconnect() {
+    if (!this._onIntent)
       return;
-    const controller = this.application.getControllerForElementAndIdentifier(stack, "modal-stack");
+    this.element.removeEventListener("pointerenter", this._onIntent);
+    this.element.removeEventListener("focus", this._onIntent);
+  }
+  open(event) {
+    const controller = this.#stackController();
     if (!controller)
       return;
     event.preventDefault();
@@ -810,6 +909,18 @@ class ModalStackLinkController extends Controller2 {
       dismissible: ds.modalStackLinkDismissible !== "false"
     });
   }
+  #warm() {
+    const controller = this.#stackController();
+    if (!controller || typeof controller.prefetch !== "function")
+      return;
+    controller.prefetch(this.element.href);
+  }
+  #stackController() {
+    const stack = document.querySelector('[data-controller~="modal-stack"]');
+    if (!stack)
+      return null;
+    return this.application.getControllerForElementAndIdentifier(stack, "modal-stack");
+  }
 }
 function generateLayerId2() {
   if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {

data/app/assets/stylesheets/modal_stack/bootstrap.css

@@ -23,7 +23,9 @@
   --modal-stack-fg: var(--bs-body-color, #212529);
   --modal-stack-shadow: var(--bs-box-shadow-lg, 0 1rem 3rem rgba(0, 0, 0, 0.175));
   --modal-stack-backdrop: rgba(var(--bs-backdrop-color, 0, 0, 0), var(--bs-backdrop-opacity, 0.5));
-  --modal-stack-backdrop-blur: 0;
+  /* Default `none` so Chrome skips the filter pass. Opt in with
+   * `:root { --modal-stack-backdrop-filter: blur(8px); }`. */
+  --modal-stack-backdrop-filter: none;
   --modal-stack-panel-padding: var(--bs-modal-padding, 1rem);
   --modal-stack-size-sm: 300px;
   --modal-stack-size-md: 500px;
@@ -65,23 +67,22 @@ body[data-modal-stack-locked] {
 
 #modal-stack-root::backdrop {
   background: rgba(0, 0, 0, 0);
-  backdrop-filter: blur(0);
   transition:
     background var(--modal-stack-duration) var(--modal-stack-ease),
-    backdrop-filter var(--modal-stack-duration) var(--modal-stack-ease),
     overlay var(--modal-stack-duration) var(--modal-stack-ease) allow-discrete,
     display var(--modal-stack-duration) var(--modal-stack-ease) allow-discrete;
 }
 
 #modal-stack-root[open]::backdrop {
   background: var(--modal-stack-backdrop);
-  backdrop-filter: blur(var(--modal-stack-backdrop-blur));
+  /* Static. Default is `none` (no filter pass). Opt in with
+   * --modal-stack-backdrop-filter on :root. */
+  backdrop-filter: var(--modal-stack-backdrop-filter);
 }
 
 @starting-style {
   #modal-stack-root[open]::backdrop {
     background: rgba(0, 0, 0, 0);
-    backdrop-filter: blur(0);
   }
 }
 
@@ -101,8 +102,7 @@ body[data-modal-stack-locked] {
   transform: translate(-50%, -50%);
   transition:
     transform var(--modal-stack-duration) var(--modal-stack-ease),
-    opacity var(--modal-stack-duration) var(--modal-stack-ease),
-    filter var(--modal-stack-duration) var(--modal-stack-ease);
+    opacity var(--modal-stack-duration) var(--modal-stack-ease);
 }
 
 @starting-style {
@@ -120,7 +120,6 @@ body[data-modal-stack-locked] {
 
 [data-modal-stack-target="layer"][inert] {
   opacity: 0.5;
-  filter: blur(0.5px);
 }
 
 [data-modal-stack-target="layer"][data-modal-stack-size="sm"] { width: var(--modal-stack-size-sm); }

data/app/assets/stylesheets/modal_stack/{tailwind.css → tailwind_v3.css}

@@ -1,11 +1,14 @@
 /*
- * modal_stack — Tailwind preset
+ * modal_stack — Tailwind v3 preset
+ *
+ * Tailwind v3 doesn't expose its design tokens as native CSS variables,
+ * so this preset ships static values aligned with the Tailwind defaults
+ * (slate text, white surface, rounded-2xl-ish radius, container sizes).
+ * Override the `--modal-stack-*` tokens on `:root` to retheme without
+ * touching the gem.
  *
  * Structural CSS for the <dialog id="modal-stack-root"> + layered
  * `[data-modal-stack-target="layer"]` setup driven by the JS runtime.
- * Visual tokens are exposed as CSS custom properties on `:root` so they
- * can be overridden globally, per scope, or via Tailwind's
- * `:root { --modal-stack-* }` declaration.
  *
  * Variants:    [data-variant="modal" | "drawer" | "bottom_sheet" | "confirmation"]
  * Drawer side: [data-side="left" | "right" | "top" | "bottom"]
@@ -27,7 +30,13 @@
   --modal-stack-fg: #0f172a;
   --modal-stack-shadow: 0 30px 60px -20px rgba(15, 23, 42, 0.35);
   --modal-stack-backdrop: rgba(15, 23, 42, 0.55);
-  --modal-stack-backdrop-blur: 2px;
+  /* `none` by default — `backdrop-filter: blur()` even at radius 0
+   * still allocates a filter layer on the compositor, and animating
+   * a non-zero radius costs ~190ms/frame on Hi-DPI displays. Opt in
+   * with `:root { --modal-stack-backdrop-filter: blur(8px); }` —
+   * the filter is applied statically when the dialog opens (no
+   * per-frame compositor cost). */
+  --modal-stack-backdrop-filter: none;
   --modal-stack-panel-padding: 24px;
   --modal-stack-size-sm: 24rem;   /* 384px */
   --modal-stack-size-md: 34rem;   /* 544px */
@@ -79,23 +88,23 @@ body[data-modal-stack-locked] {
 
 #modal-stack-root::backdrop {
   background: rgba(15, 23, 42, 0);
-  backdrop-filter: blur(0);
   transition:
     background var(--modal-stack-duration) var(--modal-stack-ease),
-    backdrop-filter var(--modal-stack-duration) var(--modal-stack-ease),
     overlay var(--modal-stack-duration) var(--modal-stack-ease) allow-discrete,
     display var(--modal-stack-duration) var(--modal-stack-ease) allow-discrete;
 }
 
 #modal-stack-root[open]::backdrop {
   background: var(--modal-stack-backdrop);
-  backdrop-filter: blur(var(--modal-stack-backdrop-blur));
+  /* Static (not in the transition list above). Default is `none` so
+   * Chrome skips the filter pass entirely. Override --modal-stack-
+   * backdrop-filter to opt in. */
+  backdrop-filter: var(--modal-stack-backdrop-filter);
 }
 
 @starting-style {
   #modal-stack-root[open]::backdrop {
     background: rgba(15, 23, 42, 0);
-    backdrop-filter: blur(0);
   }
 }
 
@@ -117,8 +126,7 @@ body[data-modal-stack-locked] {
   transform: translate(-50%, -50%);
   transition:
     transform var(--modal-stack-duration) var(--modal-stack-ease),
-    opacity var(--modal-stack-duration) var(--modal-stack-ease),
-    filter var(--modal-stack-duration) var(--modal-stack-ease);
+    opacity var(--modal-stack-duration) var(--modal-stack-ease);
 }
 
 @starting-style {
@@ -136,7 +144,6 @@ body[data-modal-stack-locked] {
 
 [data-modal-stack-target="layer"][inert] {
   opacity: 0.5;
-  filter: blur(0.5px);
 }
 
 /* --- Sizes via [data-modal-stack-size] ----------------------------- */