modal_stack 0.2.0 → 0.3.0

data/app/javascript/modal_stack/orchestrator.test.js

@@ -208,8 +208,8 @@ describe("closeAll", () => {
     expect(orchestrator.depth).toBe(0);
     const types = runtime._calls.map((c) => c.type);
     expect(types).toEqual([
-      "unmountAllLayers",
       "closeDialog",
+      "unmountAllLayers",
       "unlockScroll",
       "historyBack",
       "clearSnapshot",
@@ -224,6 +224,172 @@ describe("closeAll", () => {
   });
 });
 
+describe("prefetch cache + abort", () => {
+  // Each fakeFragment supports cloneNode so the orchestrator can hand out
+  // independent copies without exhausting the cached entry.
+  function fakeFragment(label) {
+    return {
+      label,
+      consumed: false,
+      cloneNode() {
+        return fakeFragment(label);
+      },
+    };
+  }
+
+  function fetchingRuntime({ delayMs = 0, fail = false } = {}) {
+    const calls = [];
+    const aborts = [];
+    const handlerNames = [
+      "showDialog",
+      "lockScroll",
+      "inertLayer",
+      "mountLayer",
+      "morphTopLayer",
+      "unmountTopLayer",
+      "unmountAllLayers",
+      "closeDialog",
+      "unlockScroll",
+      "pushHistory",
+      "replaceHistory",
+      "historyBack",
+      "rebuildFromSnapshot",
+      "persistSnapshot",
+      "clearSnapshot",
+    ];
+    const runtime = { _calls: calls, _fetches: [], _aborts: aborts };
+    for (const name of handlerNames) {
+      runtime[name] = (cmd) => {
+        calls.push({ type: name, ...cmd });
+      };
+    }
+    runtime.fetchFragment = (url, { signal } = {}) => {
+      runtime._fetches.push(url);
+      return new Promise((resolve, reject) => {
+        const t = setTimeout(() => {
+          if (fail) reject(new Error("boom"));
+          else resolve(fakeFragment(`frag:${url}`));
+        }, delayMs);
+        if (signal) {
+          signal.addEventListener("abort", () => {
+            clearTimeout(t);
+            aborts.push(url);
+            const err = new Error("aborted");
+            err.name = "AbortError";
+            reject(err);
+          });
+        }
+      });
+    };
+    return runtime;
+  }
+
+  test("dedupes concurrent prefetches for the same url", async () => {
+    const rt = fetchingRuntime({ delayMs: 5 });
+    const orch = new Orchestrator({
+      runtime: rt,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+    });
+    await Promise.all([
+      orch.push({ id: "L1", url: "/x" }),
+      orch.push({ id: "L2", url: "/x" }),
+    ]);
+    expect(rt._fetches).toEqual(["/x"]);
+  });
+
+  test("hits the cache on a second push to the same url", async () => {
+    const rt = fetchingRuntime();
+    const orch = new Orchestrator({
+      runtime: rt,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+    });
+    await orch.push({ id: "L1", url: "/x" });
+    await orch.pop();
+    await orch.push({ id: "L2", url: "/x" });
+    expect(rt._fetches).toEqual(["/x"]);
+  });
+
+  test("returns a fresh clone per consumer (cache survives consumption)", async () => {
+    const rt = fetchingRuntime();
+    const orch = new Orchestrator({
+      runtime: rt,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+    });
+    const seenFragments = [];
+    rt.mountLayer = (cmd) => {
+      seenFragments.push(cmd.fragment);
+    };
+    await orch.push({ id: "L1", url: "/x" });
+    await orch.pop();
+    await orch.push({ id: "L2", url: "/x" });
+    expect(seenFragments).toHaveLength(2);
+    expect(seenFragments[0]).not.toBe(seenFragments[1]);
+  });
+
+  test("TTL expires the cache and triggers a refetch", async () => {
+    const rt = fetchingRuntime();
+    const orch = new Orchestrator({
+      runtime: rt,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+      prefetchTtlMs: 1,
+    });
+    await orch.push({ id: "L1", url: "/x" });
+    await orch.pop();
+    await new Promise((r) => setTimeout(r, 5));
+    await orch.push({ id: "L2", url: "/x" });
+    expect(rt._fetches).toEqual(["/x", "/x"]);
+  });
+
+  test("prefetch warms the cache without dispatching commands", async () => {
+    const rt = fetchingRuntime();
+    const orch = new Orchestrator({
+      runtime: rt,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+    });
+    await orch.prefetch("/x");
+    expect(rt._fetches).toEqual(["/x"]);
+    expect(rt._calls).toEqual([]);
+    // Subsequent push consumes the cache, no second fetch.
+    await orch.push({ id: "L1", url: "/x" });
+    expect(rt._fetches).toEqual(["/x"]);
+  });
+
+  test("prefetch swallows errors (best-effort)", async () => {
+    const rt = fetchingRuntime({ fail: true });
+    const orch = new Orchestrator({
+      runtime: rt,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+    });
+    await expect(orch.prefetch("/boom")).resolves.toBeNull();
+  });
+
+  test("closeAll aborts in-flight prefetches and clears the cache", async () => {
+    const rt = fetchingRuntime({ delayMs: 50 });
+    const orch = new Orchestrator({
+      runtime: rt,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+    });
+    // First push completes so the cache has /x.
+    await orch.push({ id: "L1", url: "/x" });
+    // Second push starts fetching /y and stays in flight.
+    const inflight = orch.push({ id: "L2", url: "/y" });
+    await new Promise((r) => setTimeout(r, 5));
+    await orch.closeAll();
+    await expect(inflight).rejects.toThrow(/aborted/);
+    expect(rt._aborts).toContain("/y");
+    // Cache has been cleared too: re-push of /x must refetch.
+    await orch.push({ id: "L3", url: "/x" });
+    expect(rt._fetches.filter((u) => u === "/x")).toHaveLength(2);
+  });
+});
+
 describe("onPopstate", () => {
   test("forward navigation requests rebuild from snapshot", async () => {
     await orchestrator.push({ id: "L1", url: "/x" });
@@ -299,8 +465,8 @@ describe("onPopstate", () => {
 
     const types = runtime._calls.map((c) => c.type);
     expect(types).toEqual([
-      "unmountAllLayers",
       "closeDialog",
+      "unmountAllLayers",
       "unlockScroll",
       "clearSnapshot",
     ]);

data/app/javascript/modal_stack/runtime.js

@@ -3,9 +3,15 @@ export const FRAGMENT_HEADER = "X-Modal-Stack-Request";
 export const SCROLLBAR_WIDTH_VAR = "--modal-stack-scrollbar-width";
 
 const LAYER_SELECTOR = '[data-modal-stack-target="layer"]';
-// Hard cap: never wait longer than this for an exit transition to fire,
-// even if the host CSS forgot to transition the leaving state.
-const LEAVE_TIMEOUT_MS = 600;
+// CSS variable host stylesheets set to declare their leave-transition
+// duration (e.g. "220ms"). When present, the runtime sizes its safety
+// timeout from this value; otherwise it falls back to a conservative cap.
+const DURATION_CSS_VAR = "--modal-stack-duration";
+// Floor for the safety timeout — even very short CSS transitions need
+// enough headroom for transitionend to fire on slow devices.
+const LEAVE_TIMEOUT_FLOOR_MS = 300;
+// Used when no CSS variable is exposed (host CSS missing, JSDOM tests).
+const LEAVE_TIMEOUT_FALLBACK_MS = 600;
 
 /**
  * The only file that touches `<dialog>`, `history`, `fetch`, and
@@ -102,12 +108,13 @@ export class BrowserRuntime {
   async unmountTopLayer() {
     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 }) {
@@ -156,6 +163,34 @@ export class BrowserRuntime {
     }
   }
 
+  // Reads --modal-stack-duration from the dialog's computed style and
+  // returns 1.5× that as the safety timeout (in ms). Cached after the
+  // first successful read since the variable is host-CSS-defined and
+  // shouldn't change at runtime. Returns LEAVE_TIMEOUT_FALLBACK_MS when
+  // getComputedStyle is unavailable (tests) or the variable is missing.
+  #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 {
+      // getComputedStyle can throw in detached/foreign documents.
+    }
+
+    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)}"]`,
@@ -193,13 +228,14 @@ export class BrowserRuntime {
     }
   }
 
-  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",
+      signal,
     });
     if (!resp.ok) {
       throw new Error(`modal_stack: fetch ${url} → ${resp.status}`);
@@ -227,7 +263,7 @@ function parseFragment(html, doc) {
 // out, then awaits transitionend (with a hard timeout) before removing
 // the element from the DOM.  If the host CSS doesn't define an exit
 // transition, the timeout still fires and the layer is removed cleanly.
-function animateOut(layer) {
+function animateOut(layer, timeoutMs = LEAVE_TIMEOUT_FALLBACK_MS) {
   return new Promise((resolve) => {
     let done = false;
     const finish = () => {
@@ -239,10 +275,21 @@ function animateOut(layer) {
     };
     layer.addEventListener("transitionend", finish, { once: true });
     layer.dataset.leaving = "";
-    setTimeout(finish, LEAVE_TIMEOUT_MS);
+    setTimeout(finish, timeoutMs);
   });
 }
 
+// Parses a CSS time token ("220ms", "0.22s", "  220 ms ") to milliseconds.
+// Returns NaN when the input is empty or unparseable so callers can fall back.
+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);

data/app/javascript/modal_stack/runtime.test.js

@@ -179,6 +179,74 @@ describe("scroll lock", () => {
   });
 });
 
+describe("leave timeout from CSS variable", () => {
+  function rtWithDuration(raw) {
+    const ownerDocument = {};
+    const dialog = {
+      ownerDocument,
+      querySelectorAll: () => [],
+    };
+    const documentRef = { documentElement: {}, body: {} };
+    const original = globalThis.getComputedStyle;
+    globalThis.getComputedStyle = () => ({
+      getPropertyValue: (name) =>
+        name === "--modal-stack-duration" ? raw : "",
+    });
+    const rt = new BrowserRuntime(
+      noopRuntimeArgs({ dialog, documentRef }),
+    );
+    return { rt, restore: () => (globalThis.getComputedStyle = original) };
+  }
+
+  async function trigger(rt) {
+    // unmountAllLayers reads the timeout once (querying [] layers, so it
+    // resolves immediately) and stashes the result on _cachedLeaveTimeoutMs.
+    await rt.unmountAllLayers();
+  }
+
+  test("derives 1.5x of the CSS variable, with a 300ms floor", async () => {
+    const { rt, restore } = rtWithDuration("220ms");
+    try {
+      await trigger(rt);
+      // 220ms × 1.5 = 330ms
+      expect(rt._cachedLeaveTimeoutMs).toBe(330);
+    } finally {
+      restore();
+    }
+  });
+
+  test("floors the timeout at 300ms for very fast transitions", async () => {
+    const { rt, restore } = rtWithDuration("100ms");
+    try {
+      await trigger(rt);
+      expect(rt._cachedLeaveTimeoutMs).toBe(300);
+    } finally {
+      restore();
+    }
+  });
+
+  test("falls back to 600 when the variable is empty", async () => {
+    const { rt, restore } = rtWithDuration("");
+    try {
+      await trigger(rt);
+      expect(rt._cachedLeaveTimeoutMs).toBe(600);
+    } finally {
+      restore();
+    }
+  });
+
+  test("supports seconds units (e.g. 0.4s)", async () => {
+    const { rt, restore } = rtWithDuration("0.4s");
+    try {
+      await trigger(rt);
+      // 400ms × 1.5 = 600ms
+      expect(rt._cachedLeaveTimeoutMs).toBe(600);
+    } finally {
+      restore();
+    }
+  });
+});
+
 describe("fetch headers", () => {
   test("sends Accept and X-Modal-Stack-Request headers", async () => {
     let captured = null;

data/app/javascript/modal_stack/state.js

@@ -195,15 +195,23 @@ export function pop(state) {
 
   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 {
+    // closeDialog first so the dialog's exit transition (opacity +
+    // backdrop background + display/overlay allow-discrete) starts
+    // immediately and runs in parallel with the layer's [data-leaving]
+    // transition. Without this order, the orchestrator awaits 220ms
+    // on unmountTopLayer before closing the dialog, then the backdrop
+    // fade kicks in for *another* 220ms — visually the backdrop fades
+    // after the modal is gone.
     commands.push({ type: "closeDialog" });
+    commands.push({ type: "unmountTopLayer" });
+    commands.push({ type: "historyBack", n: 1 });
     commands.push({ type: "unlockScroll" });
     commands.push({ type: "clearSnapshot" });
   }
@@ -276,9 +284,11 @@ export function closeAll(state) {
   const n = state.layers.length;
   return {
     state: { ...state, layers: Object.freeze([]) },
+    // closeDialog first so the dialog's exit transition runs in
+    // parallel with the layers' [data-leaving] transitions.
     commands: [
-      { type: "unmountAllLayers" },
       { type: "closeDialog" },
+      { type: "unmountAllLayers" },
       { type: "unlockScroll" },
       { type: "historyBack", n },
       { type: "clearSnapshot" },
@@ -301,9 +311,10 @@ export function handlePopstate(state, { historyState, locationHref }) {
     if (state.layers.length === 0) return { state, commands: [] };
     return {
       state: { ...state, layers: Object.freeze([]) },
+      // closeDialog first — see closeAll() for rationale.
       commands: [
-        { type: "unmountAllLayers" },
         { type: "closeDialog" },
+        { type: "unmountAllLayers" },
         { type: "unlockScroll" },
         { type: "clearSnapshot" },
       ],
@@ -318,6 +329,10 @@ export function handlePopstate(state, { historyState, locationHref }) {
     const newLayers = Object.freeze(state.layers.slice(0, targetDepth));
     const newTop = newLayers[newLayers.length - 1] ?? null;
     const commands = [];
+    // When popping back to the root via popstate, fire closeDialog
+    // first so the dialog's exit transition runs alongside the
+    // sequential unmountTopLayer cascade.
+    if (!newTop) commands.push({ type: "closeDialog" });
     for (let i = 0; i < currentDepth - targetDepth; i++) {
       commands.push({ type: "unmountTopLayer" });
     }
@@ -325,7 +340,6 @@ export 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" });
     }

data/app/javascript/modal_stack/state.test.js

@@ -306,10 +306,12 @@ describe("pop", () => {
     const first = pushed(freshStack()).state;
     const { state, commands } = pop(first);
     expect(state.layers).toEqual([]);
+    // closeDialog comes first so its exit transition runs in parallel
+    // with the layer's [data-leaving] transition.
     expect(commands).toEqual([
+      { type: "closeDialog" },
       { type: "unmountTopLayer" },
       { type: "historyBack", n: 1 },
-      { type: "closeDialog" },
       { type: "unlockScroll" },
       { type: "clearSnapshot" },
     ]);
@@ -423,8 +425,8 @@ describe("closeAll", () => {
     const { state, commands } = closeAll(s);
     expect(state.layers).toEqual([]);
     expect(commands).toEqual([
-      { type: "unmountAllLayers" },
       { type: "closeDialog" },
+      { type: "unmountAllLayers" },
       { type: "unlockScroll" },
       { type: "historyBack", n: 3 },
       { type: "clearSnapshot" },
@@ -447,8 +449,8 @@ describe("handlePopstate", () => {
     });
     expect(state.layers).toEqual([]);
     expect(commands).toEqual([
-      { type: "unmountAllLayers" },
       { type: "closeDialog" },
+      { type: "unmountAllLayers" },
       { type: "unlockScroll" },
       { type: "clearSnapshot" },
     ]);
@@ -485,9 +487,9 @@ describe("handlePopstate", () => {
     });
     expect(state.layers).toEqual([]);
     expect(commands).toEqual([
+      { type: "closeDialog" },
       { type: "unmountTopLayer" },
       { type: "unmountTopLayer" },
-      { type: "closeDialog" },
       { type: "unlockScroll" },
       { type: "clearSnapshot" },
     ]);

data/lib/generators/modal_stack/install/install_generator.rb

@@ -9,11 +9,16 @@ module ModalStack
       source_root File.expand_path("templates", __dir__)
 
       ASSETS_MODES = ModalStack::Configuration::ASSETS_MODES.map(&:to_s).freeze
-      CSS_PROVIDERS = ModalStack::Configuration::CSS_PROVIDERS.map(&:to_s).freeze
+      # The CLI accepts the canonical providers plus the legacy `tailwind`
+      # alias (normalized to `tailwind_v3` by Configuration). New installs
+      # default to `tailwind_v4` — Tailwind v4 is the modern default and
+      # the preset's fallbacks make it safe even without v4 installed.
+      CSS_PROVIDERS = (ModalStack::Configuration::CSS_PROVIDERS +
+                       ModalStack::Configuration::CSS_PROVIDER_ALIASES.keys).map(&:to_s).freeze
 
       class_option :mode, type: :string, default: "auto", enum: ASSETS_MODES,
                           desc: "JS asset strategy"
-      class_option :css_provider, type: :string, default: "tailwind",
+      class_option :css_provider, type: :string, default: "tailwind_v4",
                                   enum: CSS_PROVIDERS,
                                   desc: "CSS preset bundled with the install"
       class_option :skip_layout, type: :boolean, default: false,
@@ -55,7 +60,7 @@ module ModalStack
           modal_stack installed.
 
           Mode:          #{resolved_mode}
-          CSS provider:  #{options[:css_provider]}
+          CSS provider:  #{resolved_css_provider}
 
           Next steps:
             1. Confirm config/initializers/modal_stack.rb matches your needs.
@@ -82,6 +87,15 @@ module ModalStack
         @resolved_mode ||= detect_mode
       end
 
+      # Normalize the legacy `tailwind` alias to the canonical `tailwind_v3`
+      # string so the initializer file and sprockets manifest line both
+      # reference a stylesheet that actually exists in the gem.
+      def resolved_css_provider
+        provider = options[:css_provider].to_s
+        aliased = ModalStack::Configuration::CSS_PROVIDER_ALIASES[provider.to_sym]
+        aliased ? aliased.to_s : provider
+      end
+
       def detect_mode
         mode = options[:mode].to_s
         return mode unless mode == "auto"
@@ -146,7 +160,7 @@ module ModalStack
         manifest = "app/assets/config/manifest.js"
         if file_exists?(manifest)
           append_unique manifest, "//= link modal_stack.js"
-          append_unique manifest, "//= link modal_stack/#{options[:css_provider]}.css" unless options[:css_provider] == "none"
+          append_unique manifest, "//= link modal_stack/#{resolved_css_provider}.css" unless resolved_css_provider == "none"
         else
           say_status :warn, "#{manifest} not found; add `//= link modal_stack.js` manually", :yellow
         end

data/lib/generators/modal_stack/install/templates/initializer.rb

@@ -11,11 +11,18 @@ ModalStack.configure do |config|
   # CSS provider. Determines which stylesheet
   # `modal_stack_stylesheet_link_tag` resolves to.
   #
-  #   :tailwind   — Tailwind-aligned tokens (default)
-  #   :bootstrap  — picks up Bootstrap 5 CSS variables
-  #   :vanilla    — neutral defaults, framework-free
-  #   :none       — emit no <link>; provide your own CSS
-  config.css_provider = :<%= options[:css_provider] %>
+  #   :tailwind_v4 — Chains on Tailwind v4 @theme tokens (--color-*,
+  #                  --radius-*, --shadow-*, --container-*). Default for
+  #                  new installs. Falls back to Tailwind defaults when
+  #                  @theme isn't redefined, so it's safe even without v4.
+  #   :tailwind_v3 — Static values aligned with Tailwind v3 defaults
+  #                  (Tailwind v3 doesn't expose tokens as CSS variables).
+  #                  `:tailwind` is accepted as an alias for backwards
+  #                  compatibility.
+  #   :bootstrap   — Picks up Bootstrap 5 CSS variables.
+  #   :vanilla     — Neutral defaults, framework-free.
+  #   :none        — Emit no <link>; provide your own CSS.
+  config.css_provider = :<%= resolved_css_provider %>
 
   # JS asset strategy used by the install generator and by the
   # `modal_stack_javascript_tag` helper.

data/lib/modal_stack/configuration.rb

@@ -11,7 +11,11 @@ module ModalStack
   #   end
   #
   class Configuration
-    CSS_PROVIDERS = %i[tailwind bootstrap vanilla none].freeze
+    CSS_PROVIDERS = %i[tailwind_v3 tailwind_v4 bootstrap vanilla none].freeze
+    # Aliases accepted on input, normalized to a canonical CSS_PROVIDERS value.
+    # `:tailwind` predates the v3/v4 split — keep it working, map to v3 (no change
+    # in rendered CSS for existing apps).
+    CSS_PROVIDER_ALIASES = { tailwind: :tailwind_v3 }.freeze
     ASSETS_MODES = %i[importmap jsbundling sprockets auto].freeze
     VARIANTS = %i[modal drawer bottom_sheet confirmation].freeze
     SIZES = %i[sm md lg xl].freeze
@@ -36,7 +40,7 @@ module ModalStack
                 :max_depth_strategy
 
     def initialize
-      @css_provider = :tailwind
+      @css_provider = :tailwind_v3
       @assets_mode = :auto
       @default_variant = :modal
       @default_size = :md
@@ -56,6 +60,7 @@ module ModalStack
 
     def css_provider=(value)
       value = value.to_sym
+      value = CSS_PROVIDER_ALIASES.fetch(value, value)
       raise ArgumentError, "css_provider must be one of #{CSS_PROVIDERS.inspect}, got #{value.inspect}" unless CSS_PROVIDERS.include?(value)
 
       @css_provider = value

data/lib/modal_stack/controller_extensions.rb

@@ -5,7 +5,7 @@ module ModalStack
     extend ActiveSupport::Concern
 
     included do
-      helper_method :modal_stack_request?
+      helper_method :modal_stack_request?, :modal_stack_config
     end
 
     class_methods do
@@ -39,6 +39,13 @@ module ModalStack
       end
     end
 
+    # Request-scoped accessor for `ModalStack.configuration`. Memoized so
+    # helpers that read several config values per render hit the global
+    # singleton once instead of N times.
+    def modal_stack_config
+      @modal_stack_config ||= ModalStack.configuration
+    end
+
     # True when the current request was issued by the modal_stack JS runtime
     # (signaled by the X-Modal-Stack-Request header on the fetch).
     def modal_stack_request?

data/lib/modal_stack/helpers/modal_stack_assets_helper.rb

@@ -11,7 +11,7 @@ module ModalStack
       # Returns an empty SafeBuffer when `config.css_provider = :none`,
       # so apps can call this unconditionally.
       def modal_stack_stylesheet_link_tag(**)
-        provider = ModalStack.configuration.css_provider
+        provider = _modal_stack_config.css_provider
         return ActiveSupport::SafeBuffer.new if provider == :none
 
         stylesheet_link_tag("modal_stack/#{provider}", **)
@@ -23,7 +23,7 @@ module ModalStack
       #   <%= modal_stack_dialog_tag %>
       #
       def modal_stack_dialog_tag(**html_options)
-        config = ModalStack.configuration
+        config = _modal_stack_config
         attrs = html_options.dup
         attrs[:id] ||= config.dialog_id
         attrs[:data] = build_dialog_data(attrs[:data], config)
@@ -48,6 +48,18 @@ module ModalStack
       def modal_stack_javascript_tag(**)
         ActiveSupport::SafeBuffer.new
       end
+
+      private
+
+      # Prefers the request-scoped accessor injected by ControllerExtensions
+      # so we hit `ModalStack.configuration` once per request, not per call.
+      # Falls back to the global singleton for non-controller render contexts
+      # (mailers, ActionCable, isolated view tests).
+      def _modal_stack_config
+        return modal_stack_config if respond_to?(:modal_stack_config, true)
+
+        ModalStack.configuration
+      end
     end
   end
 end

data/lib/modal_stack/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ModalStack
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end