modal_stack 0.1.1 → 0.3.0

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

@@ -1,5 +1,10 @@
 import { describe, expect, test } from "bun:test";
-import { BrowserRuntime, FRAGMENT_HEADER, SNAPSHOT_KEY } from "./runtime.js";
+import {
+  BrowserRuntime,
+  FRAGMENT_HEADER,
+  SCROLLBAR_WIDTH_VAR,
+  SNAPSHOT_KEY,
+} from "./runtime.js";
 
 function fakeStore() {
   const map = new Map();
@@ -110,6 +115,138 @@ describe("history wiring", () => {
   });
 });
 
+describe("scroll lock", () => {
+  function fakeStyle() {
+    const props = new Map();
+    return {
+      props,
+      setProperty: (k, v) => props.set(k, v),
+      removeProperty: (k) => props.delete(k),
+    };
+  }
+
+  function fakeRoot({ clientWidth = 1000 } = {}) {
+    return { clientWidth, style: fakeStyle() };
+  }
+
+  test("lockScroll sets scrollbar-width var from window/root delta", () => {
+    const root = fakeRoot({ clientWidth: 985 });
+    const body = { dataset: {} };
+    const documentRef = { documentElement: root, body };
+    const rt = new BrowserRuntime(
+      noopRuntimeArgs({ documentRef, body }),
+    );
+    // Bun's globalThis.innerWidth is 0 by default — set it for the duration.
+    const original = globalThis.innerWidth;
+    globalThis.innerWidth = 1000;
+    try {
+      rt.lockScroll();
+    } finally {
+      globalThis.innerWidth = original;
+    }
+    expect(root.style.props.get(SCROLLBAR_WIDTH_VAR)).toBe("15px");
+    expect("modalStackLocked" in body.dataset).toBe(true);
+  });
+
+  test("unlockScroll clears the css variable", () => {
+    const root = fakeRoot();
+    root.style.props.set(SCROLLBAR_WIDTH_VAR, "15px");
+    const body = { dataset: { modalStackLocked: "" } };
+    const documentRef = { documentElement: root, body };
+    const rt = new BrowserRuntime(
+      noopRuntimeArgs({ documentRef, body }),
+    );
+    rt.unlockScroll();
+    expect(root.style.props.has(SCROLLBAR_WIDTH_VAR)).toBe(false);
+    expect("modalStackLocked" in body.dataset).toBe(false);
+  });
+
+  test("lockScroll never goes negative when there's no scrollbar", () => {
+    const root = fakeRoot({ clientWidth: 1000 });
+    const body = { dataset: {} };
+    const documentRef = { documentElement: root, body };
+    const rt = new BrowserRuntime(
+      noopRuntimeArgs({ documentRef, body }),
+    );
+    const original = globalThis.innerWidth;
+    globalThis.innerWidth = 800; // narrower than clientWidth
+    try {
+      rt.lockScroll();
+    } finally {
+      globalThis.innerWidth = original;
+    }
+    expect(root.style.props.get(SCROLLBAR_WIDTH_VAR)).toBe("0px");
+  });
+});
+
+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

@@ -1,3 +1,27 @@
+/**
+ * @typedef {"modal" | "drawer" | "bottom_sheet" | "confirmation"} Variant
+ * @typedef {"left" | "right" | "top" | "bottom"} DrawerSide
+ * @typedef {"sm" | "md" | "lg" | "xl"} Size
+ *
+ * @typedef {Object} Layer
+ * @property {string} id        Stable layer identifier (used for inertness + DOM lookup)
+ * @property {string} url       Layer URL — also written to history
+ * @property {Variant} variant
+ * @property {boolean} dismissible
+ * @property {Size|null} size
+ * @property {DrawerSide|null} side  Required for drawers; null otherwise
+ * @property {string|null} width    Free-form CSS width (e.g. "42rem")
+ * @property {string|null} height
+ *
+ * @typedef {Object} Stack
+ * @property {string} stackId
+ * @property {string} baseUrl
+ * @property {readonly Layer[]} layers
+ *
+ * @typedef {{ type: string } & Record<string, unknown>} Command
+ * @typedef {{ state: Stack, commands: readonly Command[] }} Transition
+ */
+
 export const VARIANTS = Object.freeze([
   "modal",
   "drawer",
@@ -8,6 +32,25 @@ export const VARIANTS = Object.freeze([
 const SNAPSHOT_VERSION = 1;
 const DEFAULT_MAX_AGE_MS = 30 * 60 * 1000;
 const DRAWER_SIDES = Object.freeze(["left", "right", "top", "bottom"]);
+const MAX_DEPTH_STRATEGIES = Object.freeze(["raise", "warn", "silent"]);
+
+/**
+ * Thrown by `push()` when `maxDepth` is exceeded under the `"raise"` strategy.
+ * Caught upstream by the orchestrator's stream-action error boundary so the
+ * page doesn't blow up — but applications can also catch it directly when
+ * calling `orchestrator.push()` programmatically.
+ */
+export class ModalStackDepthError extends Error {
+  constructor({ maxDepth, attemptedDepth }) {
+    super(
+      `modal_stack: cannot push past max_depth=${maxDepth} ` +
+        `(attempted depth=${attemptedDepth})`,
+    );
+    this.name = "ModalStackDepthError";
+    this.maxDepth = maxDepth;
+    this.attemptedDepth = attemptedDepth;
+  }
+}
 
 function normalizeLayerOptions({ variant, size, side, width, height }) {
   // A drawer must always carry a side so CSS can position it.
@@ -37,17 +80,34 @@ function freezeLayer({ id, url, variant, dismissible, size, side, width, height
   });
 }
 
+/**
+ * Build an empty, frozen stack.
+ * @param {{ stackId: string, baseUrl: string }} options
+ * @returns {Stack}
+ */
 export function createStack({ stackId, baseUrl }) {
   if (!stackId) throw new Error("stackId required");
   if (!baseUrl) throw new Error("baseUrl required");
   return Object.freeze({ stackId, baseUrl, layers: Object.freeze([]) });
 }
 
+/**
+ * @param {Stack} state
+ * @returns {Layer|null}
+ */
 export function topLayer(state) {
   return state.layers[state.layers.length - 1] ?? null;
 }
 
-export function push(state, layer) {
+/**
+ * Push a new layer on top of the stack.
+ *
+ * @param {Stack} state
+ * @param {Partial<Layer> & { id: string, url: string }} layer
+ * @param {{ maxDepth?: number|null, maxDepthStrategy?: "raise"|"warn"|"silent" }} [options]
+ * @returns {Transition}
+ */
+export function push(state, layer, options = {}) {
   if (!layer?.id) throw new Error("layer.id required");
   if (!layer?.url) throw new Error("layer.url required");
   const variant = layer.variant ?? "modal";
@@ -55,6 +115,29 @@ export function push(state, layer) {
     throw new Error(`unknown variant: ${variant}`);
   }
 
+  const { maxDepth = null, maxDepthStrategy = "warn" } = options;
+  if (maxDepth != null && state.layers.length >= maxDepth) {
+    if (!MAX_DEPTH_STRATEGIES.includes(maxDepthStrategy)) {
+      throw new Error(
+        `unknown maxDepthStrategy: ${maxDepthStrategy} (expected one of ${MAX_DEPTH_STRATEGIES.join(", ")})`,
+      );
+    }
+    if (maxDepthStrategy === "raise") {
+      throw new ModalStackDepthError({
+        maxDepth,
+        attemptedDepth: state.layers.length + 1,
+      });
+    }
+    if (maxDepthStrategy === "warn" && typeof console !== "undefined") {
+      console.warn(
+        `[modal_stack] push ignored: stack is at max_depth=${maxDepth}. ` +
+          `Set ModalStack.configuration.max_depth higher, or use ` +
+          `max_depth_strategy = :silent to suppress this warning.`,
+      );
+    }
+    return { state, commands: [] };
+  }
+
   const newLayer = freezeLayer({
     id: layer.id,
     url: layer.url,
@@ -102,26 +185,46 @@ export function push(state, layer) {
   return { state: { ...state, layers }, commands };
 }
 
+/**
+ * Pop the top layer. No-op when the stack is empty.
+ * @param {Stack} state
+ * @returns {Transition}
+ */
 export function pop(state) {
   if (state.layers.length === 0) 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 {
+    // 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" });
   }
   return { state: { ...state, layers: newLayers }, commands };
 }
 
+/**
+ * Replace (morph) the top layer in-place.
+ * @param {Stack} state
+ * @param {Partial<Layer>} patch
+ * @param {{ historyMode?: "push"|"replace" }} [options]
+ * @returns {Transition}
+ */
 export function replaceTop(state, patch, { historyMode = "replace" } = {}) {
   if (state.layers.length === 0) {
     throw new Error("replaceTop requires at least one layer");
@@ -171,14 +274,21 @@ export function replaceTop(state, patch, { historyMode = "replace" } = {}) {
   };
 }
 
+/**
+ * Close every layer at once.
+ * @param {Stack} state
+ * @returns {Transition}
+ */
 export function closeAll(state) {
   if (state.layers.length === 0) return { state, commands: [] };
   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" },
@@ -186,6 +296,13 @@ export function closeAll(state) {
   };
 }
 
+/**
+ * Reduce a browser `popstate` into a transition: pop layers, morph the top,
+ * or request a rebuild from snapshot for forward navigation.
+ * @param {Stack} state
+ * @param {{ historyState: any, locationHref: string }} options
+ * @returns {Transition}
+ */
 export function handlePopstate(state, { historyState, locationHref }) {
   const isOurs =
     historyState && historyState.stackId === state.stackId;
@@ -194,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" },
       ],
@@ -211,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" });
     }
@@ -218,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" });
     }
@@ -273,6 +394,12 @@ export function handlePopstate(state, { historyState, locationHref }) {
   return { state, commands: [] };
 }
 
+/**
+ * Serialize the stack for sessionStorage. Versioned + timestamped.
+ * @param {Stack} state
+ * @param {{ now?: () => number }} [options]
+ * @returns {string}
+ */
 export function snapshot(state, { now = Date.now } = {}) {
   return JSON.stringify({
     v: SNAPSHOT_VERSION,
@@ -283,6 +410,13 @@ export function snapshot(state, { now = Date.now } = {}) {
   });
 }
 
+/**
+ * Restore a stack from a serialized snapshot. Returns null on any validation
+ * failure (wrong stackId, expired, malformed JSON, etc.).
+ * @param {string} serialized
+ * @param {{ stackId?: string, maxAgeMs?: number, now?: () => number }} [options]
+ * @returns {Stack|null}
+ */
 export function restore(
   serialized,
   { stackId, maxAgeMs = DEFAULT_MAX_AGE_MS, now = Date.now } = {},

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

@@ -1,8 +1,9 @@
-import { describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import {
   closeAll,
   createStack,
   handlePopstate,
+  ModalStackDepthError,
   pop,
   push,
   replaceTop,
@@ -156,6 +157,87 @@ describe("push", () => {
     ).toThrow(/unknown drawer side/);
   });
 
+  describe("max_depth", () => {
+    let warnings = [];
+    const originalWarn = console.warn;
+
+    beforeEach(() => {
+      warnings = [];
+      console.warn = (...args) => warnings.push(args.join(" "));
+    });
+
+    afterEach(() => {
+      console.warn = originalWarn;
+    });
+
+    function stackOfDepth(n) {
+      let s = freshStack();
+      for (let i = 0; i < n; i++) {
+        s = push(s, { id: `L${i}`, url: `/p/${i}`, variant: "modal" }).state;
+      }
+      return s;
+    }
+
+    test("no cap when maxDepth is null (default)", () => {
+      const s = stackOfDepth(10);
+      const { state, commands } = push(s, { id: "L10", url: "/p/10", variant: "modal" });
+      expect(state.layers).toHaveLength(11);
+      expect(commands.length).toBeGreaterThan(0);
+    });
+
+    test("strategy 'warn' drops the push and logs", () => {
+      const s = stackOfDepth(3);
+      const { state, commands } = push(
+        s,
+        { id: "Lx", url: "/x", variant: "modal" },
+        { maxDepth: 3, maxDepthStrategy: "warn" },
+      );
+      expect(state).toBe(s);
+      expect(commands).toEqual([]);
+      expect(warnings.join("\n")).toMatch(/max_depth=3/);
+    });
+
+    test("strategy 'silent' drops the push without warning", () => {
+      const s = stackOfDepth(3);
+      const { state, commands } = push(
+        s,
+        { id: "Lx", url: "/x", variant: "modal" },
+        { maxDepth: 3, maxDepthStrategy: "silent" },
+      );
+      expect(state).toBe(s);
+      expect(commands).toEqual([]);
+      expect(warnings).toEqual([]);
+    });
+
+    test("strategy 'raise' throws ModalStackDepthError", () => {
+      const s = stackOfDepth(3);
+      let caught = null;
+      try {
+        push(
+          s,
+          { id: "Lx", url: "/x", variant: "modal" },
+          { maxDepth: 3, maxDepthStrategy: "raise" },
+        );
+      } catch (e) {
+        caught = e;
+      }
+      expect(caught).toBeInstanceOf(ModalStackDepthError);
+      expect(caught.maxDepth).toBe(3);
+      expect(caught.attemptedDepth).toBe(4);
+    });
+
+    test("rejects unknown strategy", () => {
+      const s = stackOfDepth(3);
+      expect(() =>
+        push(
+          s,
+          { id: "Lx", url: "/x", variant: "modal" },
+          { maxDepth: 3, maxDepthStrategy: "explode" },
+        ),
+      ).toThrow(/unknown maxDepthStrategy/);
+    });
+  });
+
   test("passes custom width and height to mount command", () => {
     const { state, commands } = push(freshStack(), {
       id: "L1",
@@ -224,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" },
     ]);
@@ -341,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" },
@@ -365,8 +449,8 @@ describe("handlePopstate", () => {
     });
     expect(state.layers).toEqual([]);
     expect(commands).toEqual([
-      { type: "unmountAllLayers" },
       { type: "closeDialog" },
+      { type: "unmountAllLayers" },
       { type: "unlockScroll" },
       { type: "clearSnapshot" },
     ]);
@@ -403,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.
@@ -40,9 +47,15 @@ ModalStack.configure do |config|
   # layout to "modal" — read by `modal_stack_request?`.
   config.request_header = "X-Modal-Stack-Request"
 
-  # Hard cap on stack depth (push past this is a runtime error).
+  # Hard cap on stack depth. Set to `nil` to disable.
   config.max_depth = 5
 
+  # What to do when a push would exceed `max_depth`:
+  #   :warn   — log a console warning, drop the push (default)
+  #   :raise  — throw `ModalStackDepthError` from the JS runtime
+  #   :silent — drop the push, no warning
+  config.max_depth_strategy = :warn
+
   # Replace `data-turbo-confirm` window.confirm with a modal_stack
   # confirmation layer (cf. RFC §15.Q7). Off by default — opt-in.
   config.replace_turbo_confirm = false