RubyGems - modal_stack - Versions diffs - 0.4.1 → 0.4.2 - Mend

modal_stack 0.4.1 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +15 -0
data/README.md +75 -5
data/app/assets/javascripts/modal_stack.js +205 -23
data/app/javascript/modal_stack/controllers/modal_stack_controller.js +111 -8
data/app/javascript/modal_stack/orchestrator.js +17 -3
data/app/javascript/modal_stack/orchestrator.test.js +2 -2
data/app/javascript/modal_stack/runtime.js +149 -4
data/app/javascript/modal_stack/runtime.test.js +7 -6
data/app/javascript/modal_stack/state.js +24 -11
data/app/javascript/modal_stack/state.test.js +11 -9
data/lib/modal_stack/helpers/modal_stack_assets_helper.rb +6 -0
data/lib/modal_stack/version.rb +1 -1
metadata +1 -1

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6457e6ddbb7a769783e711fd3956cbefc390ec9ada62daa6aa4d5d8a2bb7896
-  data.tar.gz: bb59d60f0eea1bbfd57506b98eff623ed1cbea3f9cb2002406d32e0a6c22df36
+  metadata.gz: 1ef421729ab66f062b0cd608549828f9cec8dd70a8854ad48b94baf2932c70b0
+  data.tar.gz: 3de87974331a9634bc32baba6563f20b34da3121594a32627335bfc13b13d8df
 SHA512:
-  metadata.gz: 69bdbb2322e3dad7984544f33b823a1ca62eb83993f51a8942a9321bfa7387978df9cc3c4ba3ee56dbfe49dd484a7a5b09f78fe811c7ebc636b8e51dd16e1e2a
-  data.tar.gz: b7c29d6355f7fb8f6fd15971037798eb22236c05bf19078d9a0cc7c58e080c09c30c0031ce98942b03fa183e8adcc301ac5f36186c77fa86443b63eafd417763
+  metadata.gz: 3c217b0849b43aece36f81f333cd78169db098009f4f04cab70ab79f5788949cf4f3c0e99a6aa658ea35e5700d120477e98a8903ead7ca1481f63063068d4abd
+  data.tar.gz: 4897264315c5f453abc0302b2f1b436db73ba38f5724c79c568631489d0efdb5b90fa653137ddcdc60326fac0461c3fe0d1dfc20762151c199748454fcb26d33

data/CHANGELOG.md CHANGED Viewed

@@ -6,6 +6,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
+## [0.4.2] - 2026-05-15
+### Added
+- **URL never changes** — the browser address bar stays on the originating URL when modals open. Each modal/frame still pushes a phantom `history.pushState` entry so the back button closes layers one by one, but the URL itself does not change.
+- **Reload restoration** — the current modal stack (layers + active wizard step) is persisted to `sessionStorage` and fully restored on page reload. Single-step modals restore via a GET re-fetch; POST-only wizard steps are restored from their cached HTML so they never 404.
+- **`modal_stack:frame-leave` / `modal_stack:frame-enter` custom events** — fired on the `<dialog>` (bubbles to `document`) when a path frame transitions in or out. Detail: `{ layerId, frameIndex, direction: "forward" | "back" }`. Use these to save and restore form field values across wizard steps without gem involvement (see README for example Stimulus controller).
+- **`data-turbo-permanent`** on the dialog element by default — prevents Turbo Drive from destroying and recreating the controller on page-restoration renders, eliminating a class of double-listener bugs and mid-animation state loss.
+### Fixed
+- **No Turbo page-restoration on modal close** — our `popstate` listener is now registered in capture phase and calls `event.stopImmediatePropagation()` for popstates we triggered ourselves. Turbo's bubble-phase handler never sees them, so no restoration visit, no loading bar, and no body replacement on close.
+- **Scroll lock survives Turbo renders** — `turbo:before-cache` strips `data-modal-stack-locked` from `<body>` before Turbo caches a snapshot; `turbo:render` handler in the controller calls `unlockScroll()` when `depth === 0`, neutralising any cached-snapshot restoration that re-applies the attribute.
+- **Double-pop on concurrent close handlers** — `_onCancel` and `_onBackdropClick` now return early if `!this.element.open`, preventing a second `pop()` call when Stimulus double-connects the controller (which registers two listeners on the same dialog).
+- **Multiple queued `historyBack` calls** — replaced the boolean suppress flag with a counter (`#suppressTurboVisitCount`) so N back-steps each cancel their own Turbo restoration visit independently, with a 1-second safety-valve reset.
+- **`turbo:before-cache` cleanup** — `--modal-stack-scrollbar-width` CSS variable is also stripped before caching so Turbo snapshots are always taken in the unlocked baseline state.
 ## [0.4.1] - 2026-05-14
 ### Added

data/README.md CHANGED Viewed

@@ -409,6 +409,8 @@ stale), either pass `stale: true` to `modal_path_to` or set the
 `X-Modal-Stack-Stale: true` header on the response. The runtime will
 refetch the URL instead of restoring from cache.
+> **Persisting form data between steps:** form field values are *not* automatically saved — see [`modal_stack:frame-leave` / `modal_stack:frame-enter`](#persisting-form-data-across-wizard-steps) for the recommended pattern.
 > ⚠️ **`replaceTop` collapses path frames.** When the top layer has a
 > path and you call `turbo_stream.modal_replace`, the path is forgotten:
 > the layer is morphed back to a single frame and the surplus history
@@ -609,12 +611,14 @@ per command name.
 #### Custom events
-The `<dialog>` emits two `CustomEvent`s that bubble to `document`:
+The `<dialog>` emits `CustomEvent`s that bubble to `document`:
-| Event                  | `detail`                                    | Fired when |
-| ---------------------- | ------------------------------------------- | ---------- |
-| `modal_stack:ready`    | `{ stackId }`                               | The Stimulus controller has connected and the orchestrator is ready. |
-| `modal_stack:error`    | `{ action, error }`                         | A Turbo Stream action (`modal_push`/`modal_pop`/`modal_replace`/`modal_close_all`/`modal_path_to`/`modal_path_back`) threw or rejected. The page is not crashed; surface UI feedback in the listener. |
+| Event                       | `detail`                                            | Fired when |
+| --------------------------- | --------------------------------------------------- | ---------- |
+| `modal_stack:ready`         | `{ stackId }`                                       | The Stimulus controller has connected and the orchestrator is ready. |
+| `modal_stack:error`         | `{ action, error }`                                 | A Turbo Stream action threw or rejected. The page is not crashed; surface UI feedback in the listener. |
+| `modal_stack:frame-leave`   | `{ layerId, frameIndex, direction }`                | A path frame is about to be swapped out (user going forward or back). Fired while the leaving frame is still in the DOM — listeners can read current form field values. |
+| `modal_stack:frame-enter`   | `{ layerId, frameIndex, direction }`                | A path frame has been mounted (user arrived at a step, restored from cache, or restored after page reload). Fired after the new frame is in the DOM — listeners can populate form fields. `direction` is `"forward"` or `"back"`. |
 ```js
 document.addEventListener("modal_stack:error", (event) => {
@@ -623,6 +627,72 @@ document.addEventListener("modal_stack:error", (event) => {
 });
 ```
+##### Persisting form data across wizard steps
+Form field values typed by the user are **not** automatically preserved by modal_stack — that is the responsibility of the host application. Use `modal_stack:frame-leave` and `modal_stack:frame-enter` to save and restore data.
+Example with a Stimulus controller added to each wizard step view:
+```js
+// app/javascript/controllers/wizard_step_controller.js
+import { Controller } from "@hotwired/stimulus"
+export default class extends Controller {
+  static values = { key: String }
+  connect() {
+    // Listen on the dialog so events from any nested frame reach us.
+    this._leave = (e) => {
+      if (this.#isMyFrame(e)) this.#save()
+    }
+    this._enter = (e) => {
+      if (this.#isMyFrame(e)) this.#restore()
+    }
+    document.addEventListener("modal_stack:frame-leave", this._leave)
+    document.addEventListener("modal_stack:frame-enter", this._enter)
+  }
+  disconnect() {
+    document.removeEventListener("modal_stack:frame-leave", this._leave)
+    document.removeEventListener("modal_stack:frame-enter", this._enter)
+  }
+  #isMyFrame(event) {
+    // The controller's element lives inside the frame — check ancestry.
+    return event.target.contains(this.element)
+  }
+  #save() {
+    const data = {}
+    for (const el of this.element.querySelectorAll("input, textarea, select")) {
+      if (el.name) data[el.name] = el.value
+    }
+    sessionStorage.setItem(this.keyValue, JSON.stringify(data))
+  }
+  #restore() {
+    const raw = sessionStorage.getItem(this.keyValue)
+    if (!raw) return
+    const data = JSON.parse(raw)
+    for (const [name, value] of Object.entries(data)) {
+      const el = this.element.querySelector(`[name="${name}"]`)
+      if (el) el.value = value
+    }
+  }
+}
+```
+Then attach it to the step partial:
+```erb
+<%# app/views/wizard/_step1.html.erb %>
+<div data-controller="wizard-step" data-wizard-step-key-value="wizard-step-1">
+  <%# form fields … %>
+</div>
+```
+> **Why not auto-persist?** The gem cannot know the shape of your data, applicable validations, or where you want it stored (session, server-side draft, etc.). Keeping this boundary explicit also means you can encrypt, debounce, or sync to a server-side draft without fighting the gem.
 #### Scrollbar-width compensation
 When the first layer is pushed, `BrowserRuntime#lockScroll` measures

data/app/assets/javascripts/modal_stack.js CHANGED Viewed

@@ -289,18 +289,18 @@ function pop(state) {
   const newTop = newLayers[newLayers.length - 1] ?? null;
   const commands = [];
   if (newTop) {
+    commands.push({ type: "persistSnapshot" });
     commands.push({ type: "unmountTopLayer" });
     commands.push({ type: "clearFrameCache", layerId: popped.id });
     commands.push({ type: "historyBack", n: framesToWalkBack });
     commands.push({ type: "inertLayer", layerId: newTop.id, value: false });
-    commands.push({ type: "persistSnapshot" });
   } else {
     commands.push({ type: "closeDialog" });
+    commands.push({ type: "clearSnapshot" });
     commands.push({ type: "unmountTopLayer" });
     commands.push({ type: "clearFrameCache", layerId: popped.id });
     commands.push({ type: "historyBack", n: framesToWalkBack });
     commands.push({ type: "unlockScroll" });
-    commands.push({ type: "clearSnapshot" });
   }
   return { state: { ...state, layers: newLayers }, commands };
 }
@@ -369,11 +369,11 @@ function closeAll(state) {
     state: { ...state, layers: Object.freeze([]) },
     commands: [
       { type: "closeDialog" },
+      { type: "clearSnapshot" },
       { type: "unmountAllLayers" },
       ...cacheClears,
       { type: "unlockScroll" },
-      { type: "historyBack", n },
-      { type: "clearSnapshot" }
+      { type: "historyBack", n }
     ]
   };
 }
@@ -390,10 +390,10 @@ function handlePopstate(state, { historyState, locationHref }) {
       state: { ...state, layers: Object.freeze([]) },
       commands: [
         { type: "closeDialog" },
+        { type: "clearSnapshot" },
         { type: "unmountAllLayers" },
         ...cacheClears,
-        { type: "unlockScroll" },
-        { type: "clearSnapshot" }
+        { type: "unlockScroll" }
       ]
     };
   }
@@ -406,8 +406,12 @@ 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)
+    if (newTop) {
+      commands.push({ type: "persistSnapshot" });
+    } else {
       commands.push({ type: "closeDialog" });
+      commands.push({ type: "clearSnapshot" });
+    }
     for (let i = 0;i < droppedLayers.length; i++) {
       commands.push({ type: "unmountTopLayer" });
     }
@@ -416,10 +420,8 @@ function handlePopstate(state, { historyState, locationHref }) {
     }
     if (newTop) {
       commands.push({ type: "inertLayer", layerId: newTop.id, value: false });
-      commands.push({ type: "persistSnapshot" });
     } else {
       commands.push({ type: "unlockScroll" });
-      commands.push({ type: "clearSnapshot" });
     }
     return { state: { ...state, layers: newLayers }, commands };
   }
@@ -615,6 +617,9 @@ class Orchestrator {
   get depth() {
     return this.state.layers.length;
   }
+  get expectedPopstates() {
+    return this.#expectedPopstates;
+  }
   async push(layer, { html = null, fragment = null } = {}) {
     const transition = push(this.state, layer, {
       maxDepth: this.maxDepth,
@@ -689,6 +694,15 @@ class Orchestrator {
     this.#inflight.clear();
     this.#fragmentCache.clear();
   }
+  setFragmentCache(url, fragment) {
+    if (!url || !fragment)
+      return;
+    this.#fragmentCache.set(url, {
+      fragment: cloneFragment(fragment),
+      stale: false,
+      ts: Date.now()
+    });
+  }
   prefetch(url) {
     if (!url || typeof this.runtime.fetchFragment !== "function") {
       return Promise.resolve(null);
@@ -749,6 +763,7 @@ function supportsAbort() {
 // app/javascript/modal_stack/runtime.js
 var SNAPSHOT_KEY = "modalStackSnapshot";
+var FRAME_HTML_KEY = "modalStackFrameHtml";
 var FRAGMENT_HEADER = "X-Modal-Stack-Request";
 var STALE_HEADER = "X-Modal-Stack-Stale";
 var SCROLLBAR_WIDTH_VAR = "--modal-stack-scrollbar-width";
@@ -759,10 +774,13 @@ var LEAVE_TIMEOUT_FLOOR_MS = 300;
 var LEAVE_TIMEOUT_FALLBACK_MS = 600;
 class BrowserRuntime {
+  #suppressTurboVisitCount = 0;
+  #suppressTurboVisitTimer = null;
   constructor({
     dialog,
     body = globalThis.document?.body,
     history = globalThis.history,
+    location = globalThis.location,
     fetcher = globalThis.fetch?.bind(globalThis),
     store = globalThis.sessionStorage,
     documentRef = globalThis.document
@@ -776,10 +794,34 @@ class BrowserRuntime {
     this.dialog = dialog;
     this.body = body;
     this.history = history;
+    this.location = location;
     this.fetcher = fetcher;
     this.store = store;
     this.document = documentRef;
     this._frameCache = new Map;
+    this.#suppressTurboVisitCount = 0;
+    this._turboVisitGuard = (event) => {
+      if (this.#suppressTurboVisitCount <= 0)
+        return;
+      this.#suppressTurboVisitCount -= 1;
+      if (this.#suppressTurboVisitCount === 0)
+        clearTimeout(this.#suppressTurboVisitTimer);
+      event.preventDefault();
+    };
+    documentRef.addEventListener?.("turbo:before-visit", this._turboVisitGuard);
+    this._turboBeforeCache = () => {
+      if (!this.body)
+        return;
+      delete this.body.dataset.modalStackLocked;
+      const root = this.document?.documentElement;
+      if (root)
+        root.style.removeProperty(SCROLLBAR_WIDTH_VAR);
+    };
+    documentRef.addEventListener?.("turbo:before-cache", this._turboBeforeCache);
+  }
+  destroy() {
+    this.document?.removeEventListener?.("turbo:before-visit", this._turboVisitGuard);
+    this.document?.removeEventListener?.("turbo:before-cache", this._turboBeforeCache);
   }
   showDialog() {
     if (!this.dialog.open)
@@ -844,6 +886,11 @@ class BrowserRuntime {
     const frag = await this.#resolveFragment({ url, html, fragment });
     const oldFrame = this.#findFrame(layer, fromFrameIndex);
     if (oldFrame) {
+      this.#dispatchFrameEvent("modal_stack:frame-leave", {
+        layerId,
+        frameIndex: fromFrameIndex,
+        direction: "forward"
+      });
       const cached = this.document.createDocumentFragment();
       cached.append(...oldFrame.childNodes);
       this._frameCache.set(this.#frameKey(layerId, fromFrameIndex), cached);
@@ -852,8 +899,16 @@ class BrowserRuntime {
     newFrame.append(...frag.childNodes);
     layer.appendChild(newFrame);
     this.#applyFrameDepth(layer, toFrameIndex);
+    if (toFrameIndex > 0) {
+      this.#persistFrameHtml(layerId, toFrameIndex, newFrame.innerHTML);
+    }
     if (oldFrame)
       oldFrame.remove();
+    this.#dispatchFrameEvent("modal_stack:frame-enter", {
+      layerId,
+      frameIndex: toFrameIndex,
+      direction: "forward"
+    });
     if (transition)
       this.#cleanupFrameTransition(newFrame);
   }
@@ -861,6 +916,11 @@ class BrowserRuntime {
     const layer = this.#findLayer(layerId);
     if (!layer)
       return;
+    this.#dispatchFrameEvent("modal_stack:frame-leave", {
+      layerId,
+      frameIndex: fromFrameIndex,
+      direction: "back"
+    });
     const cacheKey = this.#frameKey(layerId, toFrameIndex);
     let restored = stale ? null : this._frameCache.get(cacheKey) ?? null;
     if (!restored) {
@@ -878,6 +938,11 @@ class BrowserRuntime {
     const oldFrame = this.#findFrame(layer, fromFrameIndex);
     if (oldFrame)
       oldFrame.remove();
+    this.#dispatchFrameEvent("modal_stack:frame-enter", {
+      layerId,
+      frameIndex: toFrameIndex,
+      direction: "back"
+    });
     if (transition)
       this.#cleanupFrameTransition(newFrame);
   }
@@ -887,6 +952,7 @@ class BrowserRuntime {
       if (key.startsWith(prefix))
         this._frameCache.delete(key);
     }
+    this.#removeFrameHtmlForLayer(layerId);
   }
   async unmountTopLayer() {
     const layer = this.#topLayer();
@@ -899,13 +965,18 @@ class BrowserRuntime {
     const timeout = this.#leaveTimeoutMs();
     await Promise.all(layers.map((l) => animateOut(l, timeout)));
   }
-  pushHistory({ url, historyState }) {
-    this.history.pushState(historyState, "", url);
+  pushHistory({ historyState }) {
+    this.history.pushState(historyState, "", this.location?.href ?? "");
   }
-  replaceHistory({ url, historyState }) {
-    this.history.replaceState(historyState, "", url);
+  replaceHistory({ historyState }) {
+    this.history.replaceState(historyState, "", this.location?.href ?? "");
   }
   historyBack({ n }) {
+    this.#suppressTurboVisitCount += 1;
+    clearTimeout(this.#suppressTurboVisitTimer);
+    this.#suppressTurboVisitTimer = setTimeout(() => {
+      this.#suppressTurboVisitCount = 0;
+    }, 1000);
     this.history.go(-n);
   }
   rebuildFromSnapshot() {
@@ -923,6 +994,7 @@ class BrowserRuntime {
       return;
     try {
       this.store.removeItem(SNAPSHOT_KEY);
+      this.store.removeItem(FRAME_HTML_KEY);
     } catch {}
   }
   readSnapshot() {
@@ -934,6 +1006,54 @@ class BrowserRuntime {
       return null;
     }
   }
+  restoreFrameCacheFromStorage() {
+    const map = this.#readFrameHtmlMap();
+    for (const [key, html] of Object.entries(map)) {
+      this._frameCache.set(key, parseFragment(html, this.document));
+    }
+  }
+  getFrameFragment(layerId, frameIndex) {
+    return this._frameCache.get(this.#frameKey(layerId, frameIndex)) ?? null;
+  }
+  #persistFrameHtml(layerId, frameIndex, html) {
+    if (!this.store)
+      return;
+    try {
+      const map = this.#readFrameHtmlMap();
+      map[`${layerId}#${frameIndex}`] = html;
+      this.store.setItem(FRAME_HTML_KEY, JSON.stringify(map));
+    } catch {}
+  }
+  #readFrameHtmlMap() {
+    try {
+      const raw = this.store?.getItem(FRAME_HTML_KEY);
+      return raw ? JSON.parse(raw) : {};
+    } catch {
+      return {};
+    }
+  }
+  #removeFrameHtmlForLayer(layerId) {
+    if (!this.store)
+      return;
+    try {
+      const map = this.#readFrameHtmlMap();
+      const prefix = `${layerId}#`;
+      let changed = false;
+      for (const key of Object.keys(map)) {
+        if (key.startsWith(prefix)) {
+          delete map[key];
+          changed = true;
+        }
+      }
+      if (!changed)
+        return;
+      if (Object.keys(map).length === 0) {
+        this.store.removeItem(FRAME_HTML_KEY);
+      } else {
+        this.store.setItem(FRAME_HTML_KEY, JSON.stringify(map));
+      }
+    } catch {}
+  }
   #leaveTimeoutMs() {
     if (this._cachedLeaveTimeoutMs != null)
       return this._cachedLeaveTimeoutMs;
@@ -959,6 +1079,9 @@ class BrowserRuntime {
   #frameKey(layerId, frameIndex) {
     return `${layerId}#${frameIndex}`;
   }
+  #dispatchFrameEvent(name, detail) {
+    this.dialog.dispatchEvent(new CustomEvent(name, { bubbles: true, detail }));
+  }
   #purgeFrameCacheAbove(layerId, frameIndex) {
     const prefix = `${layerId}#`;
     for (const key of [...this._frameCache.keys()]) {
@@ -1122,26 +1245,38 @@ class ModalStackController extends Controller2 {
     maxDepth: { type: Number, default: 0 },
     maxDepthStrategy: { type: String, default: "warn" }
   };
+  #restoring = false;
   connect() {
-    const stackId = this.stackIdValue || generateLayerId();
     const baseUrl = this.baseUrlValue || window.location.href;
     this.runtime = new BrowserRuntime({ dialog: this.element });
-    const snapshot2 = this.runtime.readSnapshot();
+    this.runtime.restoreFrameCacheFromStorage();
+    const savedSnapshot = this.runtime.readSnapshot();
+    const snapshotState = savedSnapshot ? restore(savedSnapshot) : null;
+    const stackId = this.stackIdValue || snapshotState?.stackId || generateLayerId();
     this.orchestrator = new Orchestrator({
       runtime: this.runtime,
       stackId,
       baseUrl,
-      restoreFrom: snapshot2,
+      restoreFrom: null,
       maxDepth: this.maxDepthValue > 0 ? this.maxDepthValue : null,
       maxDepthStrategy: this.maxDepthStrategyValue || "warn"
     });
-    this._onPopstate = (event) => this.orchestrator.onPopstate({
-      historyState: event.state,
-      locationHref: window.location.href
-    });
-    window.addEventListener("popstate", this._onPopstate);
+    this._onPopstate = (event) => {
+      const isOwn = this.orchestrator.expectedPopstates > 0;
+      this.orchestrator.onPopstate({
+        historyState: event.state,
+        locationHref: window.location.href
+      });
+      if (isOwn)
+        event.stopImmediatePropagation();
+    };
+    window.addEventListener("popstate", this._onPopstate, true);
     this._onCancel = (event) => {
       event.preventDefault();
+      if (!this.element.open)
+        return;
+      if (this.#restoring)
+        return;
       const top = this.#topLayer();
       if (!top || top.dismissible === false)
         return;
@@ -1151,19 +1286,66 @@ class ModalStackController extends Controller2 {
     this._onBackdropClick = (event) => {
       if (event.target !== this.element)
         return;
+      if (!this.element.open)
+        return;
+      if (this.#restoring)
+        return;
       const top = this.#topLayer();
       if (!top || top.dismissible === false)
         return;
       this.orchestrator.pop();
     };
     this.element.addEventListener("click", this._onBackdropClick);
+    this._onTurboRender = () => {
+      if (this.orchestrator.depth === 0)
+        this.runtime.unlockScroll();
+    };
+    document.addEventListener("turbo:render", this._onTurboRender);
     this.#registerStreamActions();
-    this.element.dispatchEvent(new CustomEvent("modal_stack:ready", { bubbles: true, detail: { stackId } }));
+    if (snapshotState?.layers?.length > 0) {
+      this.#restoring = true;
+      this.#restoreSnapshot(snapshotState.layers).catch((err) => console.warn("[modal_stack] snapshot restore failed:", err)).finally(() => {
+        this.#restoring = false;
+      });
+    }
+    this.element.dispatchEvent(new CustomEvent("modal_stack:ready", {
+      bubbles: true,
+      detail: { stackId }
+    }));
+  }
+  async#restoreSnapshot(layers) {
+    const baseUrls = layers.map((l) => l.frames?.[0]?.url ?? l.url);
+    const baseFragments = await Promise.all(baseUrls.map((url) => this.orchestrator.prefetch(url).catch(() => null)));
+    for (let i = 0;i < layers.length; i++) {
+      const layer = layers[i];
+      await this.orchestrator.push({
+        id: layer.id,
+        url: baseUrls[i],
+        variant: layer.variant,
+        dismissible: layer.dismissible,
+        size: layer.size,
+        side: layer.side,
+        width: layer.width,
+        height: layer.height
+      }, { fragment: baseFragments[i] });
+      const extraFrames = (layer.frames ?? []).slice(1);
+      for (let fi = 0;fi < extraFrames.length; fi++) {
+        const frame = extraFrames[fi];
+        const frameIndex = fi + 1;
+        const cached = this.runtime.getFrameFragment(layer.id, frameIndex);
+        if (!cached)
+          break;
+        this.orchestrator.setFragmentCache(frame.url, cached.cloneNode(true));
+        await this.orchestrator.pathTo({ url: frame.url, stale: frame.stale }, { fragment: cached.cloneNode(true) });
+      }
+    }
   }
   disconnect() {
-    window.removeEventListener("popstate", this._onPopstate);
+    window.removeEventListener("popstate", this._onPopstate, true);
     this.element.removeEventListener("cancel", this._onCancel);
     this.element.removeEventListener("click", this._onBackdropClick);
+    document.removeEventListener("turbo:render", this._onTurboRender);
+    this.runtime.destroy?.();
   }
   push(layer, opts) {
     return this.orchestrator.push(layer, opts);

data/app/javascript/modal_stack/controllers/modal_stack_controller.js CHANGED Viewed

@@ -1,6 +1,7 @@
 import { Controller } from "@hotwired/stimulus";
 import { Orchestrator } from "../orchestrator.js";
 import { BrowserRuntime } from "../runtime.js";
+import { restore } from "../state.js";
 export class ModalStackController extends Controller {
   static values = {
@@ -10,33 +11,56 @@ export class ModalStackController extends Controller {
     maxDepthStrategy: { type: String, default: "warn" },
   };
+  #restoring = false;
   connect() {
-    const stackId = this.stackIdValue || generateLayerId();
     const baseUrl = this.baseUrlValue || window.location.href;
     this.runtime = new BrowserRuntime({ dialog: this.element });
-    const snapshot = this.runtime.readSnapshot();
+    // Restore frame HTML cache before reading snapshot so wizard frames
+    // saved in sessionStorage are available during #restoreSnapshot.
+    this.runtime.restoreFrameCacheFromStorage();
+    const savedSnapshot = this.runtime.readSnapshot();
+    // Peek at the snapshot (without stackId filter) to reuse the saved
+    // stackId across page reloads — otherwise a randomly generated stackId
+    // would never match the one saved in sessionStorage.
+    const snapshotState = savedSnapshot ? restore(savedSnapshot) : null;
+    const stackId =
+      this.stackIdValue || snapshotState?.stackId || generateLayerId();
     this.orchestrator = new Orchestrator({
       runtime: this.runtime,
       stackId,
       baseUrl,
-      restoreFrom: snapshot,
+      // Restoration is handled below via push() so each layer gets a
+      // phantom history entry and the back button closes them one by one.
+      restoreFrom: null,
       // Stimulus Number values default to 0, but state.js treats null as
       // "no cap" — so map 0/missing to null here.
       maxDepth: this.maxDepthValue > 0 ? this.maxDepthValue : null,
       maxDepthStrategy: this.maxDepthStrategyValue || "warn",
     });
-    this._onPopstate = (event) =>
+    this._onPopstate = (event) => {
+      // Run in capture phase so we fire before Turbo's bubble-phase popstate
+      // handler. When the popstate was triggered by our own historyBack
+      // (expectedPopstates > 0), stop propagation immediately after processing
+      // so Turbo never sees the event and cannot start a restoration visit
+      // (which shows the loading bar and replaces the body).
+      const isOwn = this.orchestrator.expectedPopstates > 0;
       this.orchestrator.onPopstate({
         historyState: event.state,
         locationHref: window.location.href,
       });
-    window.addEventListener("popstate", this._onPopstate);
+      if (isOwn) event.stopImmediatePropagation();
+    };
+    window.addEventListener("popstate", this._onPopstate, true);
     this._onCancel = (event) => {
       event.preventDefault();
+      if (!this.element.open) return;
+      if (this.#restoring) return;
       const top = this.#topLayer();
       if (!top || top.dismissible === false) return;
       this.orchestrator.pop();
@@ -45,22 +69,98 @@ export class ModalStackController extends Controller {
     this._onBackdropClick = (event) => {
       if (event.target !== this.element) return;
+      if (!this.element.open) return;
+      if (this.#restoring) return;
       const top = this.#topLayer();
       if (!top || top.dismissible === false) return;
       this.orchestrator.pop();
     };
     this.element.addEventListener("click", this._onBackdropClick);
+    // After any Turbo render (restoration, morph, stream-driven page update),
+    // re-check scroll lock. A snapshot cached while a modal was open can
+    // restore data-modal-stack-locked on body even after the modal has closed.
+    // turbo:before-cache strips the attribute before caching; this is the
+    // safety net for renders that fire from an already-stale cache.
+    this._onTurboRender = () => {
+      if (this.orchestrator.depth === 0) this.runtime.unlockScroll();
+    };
+    document.addEventListener("turbo:render", this._onTurboRender);
     this.#registerStreamActions();
+    if (snapshotState?.layers?.length > 0) {
+      this.#restoring = true;
+      this.#restoreSnapshot(snapshotState.layers)
+        .catch((err) =>
+          console.warn("[modal_stack] snapshot restore failed:", err),
+        )
+        .finally(() => {
+          this.#restoring = false;
+        });
+    }
     this.element.dispatchEvent(
-      new CustomEvent("modal_stack:ready", { bubbles: true, detail: { stackId } }),
+      new CustomEvent("modal_stack:ready", {
+        bubbles: true,
+        detail: { stackId },
+      }),
     );
   }
+  async #restoreSnapshot(layers) {
+    // Always open each layer from its first frame URL (accessible via GET).
+    const baseUrls = layers.map((l) => l.frames?.[0]?.url ?? l.url);
+    // Pre-fetch base frames in parallel so the push loop runs without any
+    // network await between iterations, eliminating the race window where
+    // Escape fires while this.state lags behind (only partial stack).
+    const baseFragments = await Promise.all(
+      baseUrls.map((url) => this.orchestrator.prefetch(url).catch(() => null)),
+    );
+    for (let i = 0; i < layers.length; i++) {
+      const layer = layers[i];
+      await this.orchestrator.push(
+        {
+          id: layer.id,
+          url: baseUrls[i],
+          variant: layer.variant,
+          dismissible: layer.dismissible,
+          size: layer.size,
+          side: layer.side,
+          width: layer.width,
+          height: layer.height,
+        },
+        { fragment: baseFragments[i] },
+      );
+      // Restore additional wizard frames using HTML saved to sessionStorage
+      // on the previous visit. Each frame may be a POST-only step that 404s
+      // on a direct GET — we use the cached HTML instead of re-fetching.
+      const extraFrames = (layer.frames ?? []).slice(1);
+      for (let fi = 0; fi < extraFrames.length; fi++) {
+        const frame = extraFrames[fi];
+        const frameIndex = fi + 1;
+        const cached = this.runtime.getFrameFragment(layer.id, frameIndex);
+        if (!cached) break; // Can't restore beyond this frame — stop here
+        // Warm the orchestrator's fragment cache so forward re-navigation
+        // after a back doesn't attempt a failing GET for this URL.
+        this.orchestrator.setFragmentCache(frame.url, cached.cloneNode(true));
+        await this.orchestrator.pathTo(
+          { url: frame.url, stale: frame.stale },
+          { fragment: cached.cloneNode(true) },
+        );
+      }
+    }
+  }
   disconnect() {
-    window.removeEventListener("popstate", this._onPopstate);
+    window.removeEventListener("popstate", this._onPopstate, true);
     this.element.removeEventListener("cancel", this._onCancel);
     this.element.removeEventListener("click", this._onBackdropClick);
+    document.removeEventListener("turbo:render", this._onTurboRender);
+    this.runtime.destroy?.();
   }
   push(layer, opts) {
@@ -207,7 +307,10 @@ function layerPatchFromStreamElement(el) {
 }
 function generateLayerId() {
-  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+  if (
+    typeof crypto !== "undefined" &&
+    typeof crypto.randomUUID === "function"
+  ) {
     return crypto.randomUUID();
   }
   return `ms-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;

data/app/javascript/modal_stack/orchestrator.js CHANGED Viewed

@@ -71,6 +71,10 @@ export class Orchestrator {
     return this.state.layers.length;
   }
+  get expectedPopstates() {
+    return this.#expectedPopstates;
+  }
   /**
    * Push a layer. When `html`/`fragment` are absent, the orchestrator
    * pre-fetches the URL so `mountLayer` is a sync DOM append (no flash).
@@ -194,6 +198,18 @@ export class Orchestrator {
     this.#fragmentCache.clear();
   }
+  // Seed the fragment cache with a known fragment for a URL. Used during
+  // snapshot restore to ensure forward re-navigation to a POST-only wizard
+  // step reuses the cached HTML rather than attempting a failing GET fetch.
+  setFragmentCache(url, fragment) {
+    if (!url || !fragment) return;
+    this.#fragmentCache.set(url, {
+      fragment: cloneFragment(fragment),
+      stale: false,
+      ts: Date.now(),
+    });
+  }
   // Warm the prefetch cache for `url` without mutating the stack. Safe
   // to call repeatedly for the same URL (deduped via #inflight) and from
   // hover/focus handlers; failures are swallowed since this is best-effort.
@@ -217,9 +233,7 @@ export class Orchestrator {
     // A popstate arriving while we have prefetches in flight means the
     // user navigated away from any URL we were preloading; drop them.
     this.#invalidatePrefetch();
-    return this.#dispatch(
-      handlePopstate(this.state, { historyState, locationHref }),
-    );
+    return this.#dispatch(handlePopstate(this.state, { historyState, locationHref }));
   }
   async #dispatch({ state, commands }, payload = {}) {

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

@@ -299,12 +299,12 @@ describe("closeAll", () => {
     const types = runtime._calls.map((c) => c.type);
     expect(types).toEqual([
       "closeDialog",
+      "clearSnapshot",
       "unmountAllLayers",
       "clearFrameCache",
       "clearFrameCache",
       "unlockScroll",
       "historyBack",
-      "clearSnapshot",
     ]);
     runtime._calls.length = 0;
@@ -561,10 +561,10 @@ describe("onPopstate", () => {
     const types = runtime._calls.map((c) => c.type);
     expect(types).toEqual([
       "closeDialog",
+      "clearSnapshot",
       "unmountAllLayers",
       "clearFrameCache",
       "unlockScroll",
-      "clearSnapshot",
     ]);
     expect(types).not.toContain("historyBack");
   });

data/app/javascript/modal_stack/runtime.js CHANGED Viewed

@@ -1,4 +1,5 @@
 export const SNAPSHOT_KEY = "modalStackSnapshot";
+export const FRAME_HTML_KEY = "modalStackFrameHtml";
 export const FRAGMENT_HEADER = "X-Modal-Stack-Request";
 // Server response header that flags the just-rendered frame as stale —
 // the runtime will refetch instead of restoring from the in-memory cache
@@ -27,11 +28,17 @@ const LEAVE_TIMEOUT_FALLBACK_MS = 600;
  * `orchestrator.test.js` for an in-memory fake).
  */
 export class BrowserRuntime {
+  // Counter: incremented per historyBack call, decremented per Turbo visit
+  // cancelled. Guards every popstate that lands on a Turbo-owned entry.
+  #suppressTurboVisitCount = 0;
+  #suppressTurboVisitTimer = null;
   /**
    * @param {Object} options
    * @param {HTMLDialogElement} options.dialog
    * @param {HTMLElement} [options.body]
    * @param {History} [options.history]
+   * @param {Location} [options.location]
    * @param {typeof fetch} [options.fetcher]
    * @param {Storage} [options.store]
    * @param {Document} [options.documentRef]
@@ -40,6 +47,7 @@ export class BrowserRuntime {
     dialog,
     body = globalThis.document?.body,
     history = globalThis.history,
+    location = globalThis.location,
     fetcher = globalThis.fetch?.bind(globalThis),
     store = globalThis.sessionStorage,
     documentRef = globalThis.document,
@@ -50,6 +58,7 @@ export class BrowserRuntime {
     this.dialog = dialog;
     this.body = body;
     this.history = history;
+    this.location = location;
     this.fetcher = fetcher;
     this.store = store;
     this.document = documentRef;
@@ -57,6 +66,44 @@ export class BrowserRuntime {
     // Populated by mountFrame on the way forward, drained by unmountFrame on
     // the way back, purged on layer teardown via clearFrameCache.
     this._frameCache = new Map();
+    // When our historyBack() navigates back to the original page-load history
+    // entry, that entry carries Turbo's restorationIdentifier. Turbo sees it on
+    // popstate and starts a restoration visit which replaces the body — including
+    // restoring a cached snapshot that had data-modal-stack-locked baked in,
+    // leaving the page scroll-locked after the modal closes.
+    //
+    // We intercept turbo:before-visit and cancel the *one* restoration triggered
+    // by our own historyBack. The flag is armed in historyBack and consumed (or
+    // timed out) immediately so it cannot suppress a user-initiated navigation.
+    this.#suppressTurboVisitCount = 0;
+    this._turboVisitGuard = (event) => {
+      if (this.#suppressTurboVisitCount <= 0) return;
+      this.#suppressTurboVisitCount -= 1;
+      if (this.#suppressTurboVisitCount === 0) clearTimeout(this.#suppressTurboVisitTimer);
+      event.preventDefault();
+    };
+    documentRef.addEventListener?.("turbo:before-visit", this._turboVisitGuard);
+    // Turbo caches a page snapshot before navigating away. If the modal is
+    // open at cache time, data-modal-stack-locked is baked into the snapshot.
+    // When Turbo later restores or morphs from that snapshot, the attribute
+    // is re-applied to body, leaving the page scroll-locked even though no
+    // modal is open. Stripping the lock before cache keeps snapshots clean.
+    this._turboBeforeCache = () => {
+      if (!this.body) return;
+      delete this.body.dataset.modalStackLocked;
+      const root = this.document?.documentElement;
+      if (root) root.style.removeProperty(SCROLLBAR_WIDTH_VAR);
+    };
+    documentRef.addEventListener?.("turbo:before-cache", this._turboBeforeCache);
+  }
+  // Called by the Stimulus controller on disconnect so the global listener
+  // is cleaned up if the element leaves the DOM (e.g. full page navigation).
+  destroy() {
+    this.document?.removeEventListener?.("turbo:before-visit", this._turboVisitGuard);
+    this.document?.removeEventListener?.("turbo:before-cache", this._turboBeforeCache);
   }
   showDialog() {
@@ -130,6 +177,10 @@ export class BrowserRuntime {
     // animateOut below operates on the wrapper, which we'll throw away.
     const oldFrame = this.#findFrame(layer, fromFrameIndex);
     if (oldFrame) {
+      // Fire before detach so listeners can still read live form values.
+      this.#dispatchFrameEvent("modal_stack:frame-leave", {
+        layerId, frameIndex: fromFrameIndex, direction: "forward",
+      });
       const cached = this.document.createDocumentFragment();
       cached.append(...oldFrame.childNodes);
       this._frameCache.set(this.#frameKey(layerId, fromFrameIndex), cached);
@@ -140,6 +191,13 @@ export class BrowserRuntime {
     layer.appendChild(newFrame);
     this.#applyFrameDepth(layer, toFrameIndex);
+    // Persist the incoming frame's HTML so it can be restored across page
+    // reloads. Frame 0 is always the layer's initial mount (accessible via
+    // GET); frames 1+ may be POST-only wizard steps that 404 on direct fetch.
+    if (toFrameIndex > 0) {
+      this.#persistFrameHtml(layerId, toFrameIndex, newFrame.innerHTML);
+    }
     // Old frame is removed synchronously. Entering frames carry
     // data-transition + data-direction so host CSS can drive the *enter*
     // animation via @starting-style; the leaving frame would need its own
@@ -147,6 +205,11 @@ export class BrowserRuntime {
     // which we leave to the host CSS preset.
     if (oldFrame) oldFrame.remove();
+    // Fire after mount so listeners can read/populate the new frame's DOM.
+    this.#dispatchFrameEvent("modal_stack:frame-enter", {
+      layerId, frameIndex: toFrameIndex, direction: "forward",
+    });
     // Remove transition attrs once the animation completes so the :has()
     // rule that clips overflow doesn't persist indefinitely.
     if (transition) this.#cleanupFrameTransition(newFrame);
@@ -156,6 +219,11 @@ export class BrowserRuntime {
     const layer = this.#findLayer(layerId);
     if (!layer) return;
+    // Fire before detach so listeners can still read live form values.
+    this.#dispatchFrameEvent("modal_stack:frame-leave", {
+      layerId, frameIndex: fromFrameIndex, direction: "back",
+    });
     const cacheKey = this.#frameKey(layerId, toFrameIndex);
     let restored = stale ? null : this._frameCache.get(cacheKey) ?? null;
     if (!restored) {
@@ -181,6 +249,11 @@ export class BrowserRuntime {
     const oldFrame = this.#findFrame(layer, fromFrameIndex);
     if (oldFrame) oldFrame.remove();
+    // Fire after mount so listeners can restore data into the returned frame.
+    this.#dispatchFrameEvent("modal_stack:frame-enter", {
+      layerId, frameIndex: toFrameIndex, direction: "back",
+    });
     if (transition) this.#cleanupFrameTransition(newFrame);
   }
@@ -189,6 +262,7 @@ export class BrowserRuntime {
     for (const key of [...this._frameCache.keys()]) {
       if (key.startsWith(prefix)) this._frameCache.delete(key);
     }
+    this.#removeFrameHtmlForLayer(layerId);
   }
   async unmountTopLayer() {
@@ -203,15 +277,25 @@ export class BrowserRuntime {
     await Promise.all(layers.map((l) => animateOut(l, timeout)));
   }
-  pushHistory({ url, historyState }) {
-    this.history.pushState(historyState, "", url);
+  pushHistory({ historyState }) {
+    this.history.pushState(historyState, "", this.location?.href ?? "");
   }
-  replaceHistory({ url, historyState }) {
-    this.history.replaceState(historyState, "", url);
+  replaceHistory({ historyState }) {
+    this.history.replaceState(historyState, "", this.location?.href ?? "");
   }
   historyBack({ n }) {
+    // Arm the guard before calling history.go so turbo:before-visit (which
+    // fires synchronously inside Turbo's popstate handler) can cancel the
+    // restoration visit. A safety timeout clears the flag if the popstate
+    // never triggers a Turbo visit (i.e. we landed on one of our own phantom
+    // entries that lack Turbo's restorationIdentifier).
+    this.#suppressTurboVisitCount += 1;
+    clearTimeout(this.#suppressTurboVisitTimer);
+    this.#suppressTurboVisitTimer = setTimeout(() => {
+      this.#suppressTurboVisitCount = 0;
+    }, 1000);
     this.history.go(-n);
   }
@@ -235,6 +319,7 @@ export class BrowserRuntime {
     if (!this.store) return;
     try {
       this.store.removeItem(SNAPSHOT_KEY);
+      this.store.removeItem(FRAME_HTML_KEY);
     } catch {
       // ignore
     }
@@ -249,6 +334,60 @@ export class BrowserRuntime {
     }
   }
+  // Preloads _frameCache from sessionStorage so wizard frames saved across
+  // reloads can be restored via pathTo without re-fetching their URLs.
+  restoreFrameCacheFromStorage() {
+    const map = this.#readFrameHtmlMap();
+    for (const [key, html] of Object.entries(map)) {
+      this._frameCache.set(key, parseFragment(html, this.document));
+    }
+  }
+  // Returns the cached fragment for a specific frame (used during restoration).
+  getFrameFragment(layerId, frameIndex) {
+    return this._frameCache.get(this.#frameKey(layerId, frameIndex)) ?? null;
+  }
+  #persistFrameHtml(layerId, frameIndex, html) {
+    if (!this.store) return;
+    try {
+      const map = this.#readFrameHtmlMap();
+      map[`${layerId}#${frameIndex}`] = html;
+      this.store.setItem(FRAME_HTML_KEY, JSON.stringify(map));
+    } catch {
+      // sessionStorage full or unavailable — best effort
+    }
+  }
+  #readFrameHtmlMap() {
+    try {
+      const raw = this.store?.getItem(FRAME_HTML_KEY);
+      return raw ? JSON.parse(raw) : {};
+    } catch {
+      return {};
+    }
+  }
+  #removeFrameHtmlForLayer(layerId) {
+    if (!this.store) return;
+    try {
+      const map = this.#readFrameHtmlMap();
+      const prefix = `${layerId}#`;
+      let changed = false;
+      for (const key of Object.keys(map)) {
+        if (key.startsWith(prefix)) { delete map[key]; changed = true; }
+      }
+      if (!changed) return;
+      if (Object.keys(map).length === 0) {
+        this.store.removeItem(FRAME_HTML_KEY);
+      } else {
+        this.store.setItem(FRAME_HTML_KEY, JSON.stringify(map));
+      }
+    } catch {
+      // ignore
+    }
+  }
   // 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
@@ -293,6 +432,12 @@ export class BrowserRuntime {
     return `${layerId}#${frameIndex}`;
   }
+  #dispatchFrameEvent(name, detail) {
+    this.dialog.dispatchEvent(
+      new CustomEvent(name, { bubbles: true, detail }),
+    );
+  }
   #purgeFrameCacheAbove(layerId, frameIndex) {
     const prefix = `${layerId}#`;
     for (const key of [...this._frameCache.keys()]) {

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

@@ -97,20 +97,21 @@ describe("snapshot storage", () => {
 });
 describe("history wiring", () => {
-  test("pushHistory / replaceHistory / historyBack delegate to history", () => {
+  test("pushHistory / replaceHistory always use current location.href, ignoring the modal url", () => {
     const calls = [];
     const history = {
       pushState: (s, t, u) => calls.push(["push", s, t, u]),
       replaceState: (s, t, u) => calls.push(["replace", s, t, u]),
       go: (n) => calls.push(["go", n]),
     };
-    const rt = new BrowserRuntime(noopRuntimeArgs({ history }));
-    rt.pushHistory({ url: "/a", historyState: { x: 1 } });
-    rt.replaceHistory({ url: "/b", historyState: { y: 2 } });
+    const location = { href: "http://example.com/origin" };
+    const rt = new BrowserRuntime(noopRuntimeArgs({ history, location }));
+    rt.pushHistory({ url: "/modal-a", historyState: { x: 1 } });
+    rt.replaceHistory({ url: "/modal-b", historyState: { y: 2 } });
     rt.historyBack({ n: 3 });
     expect(calls).toEqual([
-      ["push", { x: 1 }, "", "/a"],
-      ["replace", { y: 2 }, "", "/b"],
+      ["push", { x: 1 }, "", "http://example.com/origin"],
+      ["replace", { y: 2 }, "", "http://example.com/origin"],
       ["go", -3],
     ]);
   });

data/app/javascript/modal_stack/state.js CHANGED Viewed

@@ -371,11 +371,13 @@ export function pop(state) {
   const newTop = newLayers[newLayers.length - 1] ?? null;
   const commands = [];
   if (newTop) {
+    // Persist early so a page reload during the animation restores the
+    // correct (already-popped) stack rather than the stale one.
+    commands.push({ type: "persistSnapshot" });
     commands.push({ type: "unmountTopLayer" });
     commands.push({ type: "clearFrameCache", layerId: popped.id });
     commands.push({ type: "historyBack", n: framesToWalkBack });
     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
@@ -385,11 +387,13 @@ export function pop(state) {
     // fade kicks in for *another* 220ms — visually the backdrop fades
     // after the modal is gone.
     commands.push({ type: "closeDialog" });
+    // Clear early so a page reload during the animation does not restore
+    // the modal that is already being dismissed.
+    commands.push({ type: "clearSnapshot" });
     commands.push({ type: "unmountTopLayer" });
     commands.push({ type: "clearFrameCache", layerId: popped.id });
     commands.push({ type: "historyBack", n: framesToWalkBack });
     commands.push({ type: "unlockScroll" });
-    commands.push({ type: "clearSnapshot" });
   }
   return { state: { ...state, layers: newLayers }, commands };
 }
@@ -480,13 +484,15 @@ export function closeAll(state) {
     state: { ...state, layers: Object.freeze([]) },
     // closeDialog first so the dialog's exit transition runs in
     // parallel with the layers' [data-leaving] transitions.
+    // clearSnapshot comes before unmountAllLayers so a reload during
+    // the animation does not restore a stack that is already closing.
     commands: [
       { type: "closeDialog" },
+      { type: "clearSnapshot" },
       { type: "unmountAllLayers" },
       ...cacheClears,
       { type: "unlockScroll" },
       { type: "historyBack", n },
-      { type: "clearSnapshot" },
     ],
   };
 }
@@ -511,13 +517,13 @@ export function handlePopstate(state, { historyState, locationHref }) {
     }));
     return {
       state: { ...state, layers: Object.freeze([]) },
-      // closeDialog first — see closeAll() for rationale.
+      // closeDialog and clearSnapshot first — see closeAll() for rationale.
       commands: [
         { type: "closeDialog" },
+        { type: "clearSnapshot" },
         { type: "unmountAllLayers" },
         ...cacheClears,
         { type: "unlockScroll" },
-        { type: "clearSnapshot" },
       ],
     };
   }
@@ -532,10 +538,19 @@ 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" });
+    if (newTop) {
+      // Persist before animation so a reload during the transition
+      // restores the correct remaining stack.
+      commands.push({ type: "persistSnapshot" });
+    } else {
+      // When popping back to the root via popstate, fire closeDialog
+      // first so the dialog's exit transition runs alongside the
+      // sequential unmountTopLayer cascade.
+      commands.push({ type: "closeDialog" });
+      // Clear before animation so a reload during the transition does
+      // not restore the stack that is already being dismissed.
+      commands.push({ type: "clearSnapshot" });
+    }
     for (let i = 0; i < droppedLayers.length; i++) {
       commands.push({ type: "unmountTopLayer" });
     }
@@ -544,10 +559,8 @@ export function handlePopstate(state, { historyState, locationHref }) {
     }
     if (newTop) {
       commands.push({ type: "inertLayer", layerId: newTop.id, value: false });
-      commands.push({ type: "persistSnapshot" });
     } else {
       commands.push({ type: "unlockScroll" });
-      commands.push({ type: "clearSnapshot" });
     }
     return { state: { ...state, layers: newLayers }, commands };
   }

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

@@ -492,15 +492,15 @@ 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.
+    // closeDialog and clearSnapshot come first so a reload during the
+    // exit animation does not restore the modal that is already closing.
     expect(commands).toEqual([
       { type: "closeDialog" },
+      { type: "clearSnapshot" },
       { type: "unmountTopLayer" },
       { type: "clearFrameCache", layerId: "L1" },
       { type: "historyBack", n: 1 },
       { type: "unlockScroll" },
-      { type: "clearSnapshot" },
     ]);
   });
@@ -509,12 +509,14 @@ describe("pop", () => {
     s = push(s, { id: "L2", url: "/clients/new" }).state;
     const { state, commands } = pop(s);
     expect(state.layers).toHaveLength(1);
+    // persistSnapshot comes first so a reload during the animation
+    // restores the correct remaining stack (without the popped layer).
     expect(commands).toEqual([
+      { type: "persistSnapshot" },
       { type: "unmountTopLayer" },
       { type: "clearFrameCache", layerId: "L2" },
       { type: "historyBack", n: 1 },
       { type: "inertLayer", layerId: "L1", value: false },
-      { type: "persistSnapshot" },
     ]);
   });
@@ -526,11 +528,11 @@ describe("pop", () => {
     expect(state.layers).toEqual([]);
     expect(commands).toEqual([
       { type: "closeDialog" },
+      { type: "clearSnapshot" },
       { type: "unmountTopLayer" },
       { type: "clearFrameCache", layerId: "L1" },
       { type: "historyBack", n: 3 },
       { type: "unlockScroll" },
-      { type: "clearSnapshot" },
     ]);
   });
 });
@@ -658,13 +660,13 @@ describe("closeAll", () => {
     expect(state.layers).toEqual([]);
     expect(commands).toEqual([
       { type: "closeDialog" },
+      { type: "clearSnapshot" },
       { type: "unmountAllLayers" },
       { type: "clearFrameCache", layerId: "L1" },
       { type: "clearFrameCache", layerId: "L2" },
       { type: "clearFrameCache", layerId: "L3" },
       { type: "unlockScroll" },
       { type: "historyBack", n: 3 },
-      { type: "clearSnapshot" },
     ]);
   });
@@ -694,11 +696,11 @@ describe("handlePopstate", () => {
     expect(state.layers).toEqual([]);
     expect(commands).toEqual([
       { type: "closeDialog" },
+      { type: "clearSnapshot" },
       { type: "unmountAllLayers" },
       { type: "clearFrameCache", layerId: "L1" },
       { type: "clearFrameCache", layerId: "L2" },
       { type: "unlockScroll" },
-      { type: "clearSnapshot" },
     ]);
   });
@@ -718,10 +720,10 @@ describe("handlePopstate", () => {
     });
     expect(state.layers.map((l) => l.id)).toEqual(["L1"]);
     expect(commands).toEqual([
+      { type: "persistSnapshot" },
       { type: "unmountTopLayer" },
       { type: "clearFrameCache", layerId: "L2" },
       { type: "inertLayer", layerId: "L1", value: false },
-      { type: "persistSnapshot" },
     ]);
     expect(commands).not.toContainEqual({ type: "historyBack", n: 1 });
   });
@@ -735,12 +737,12 @@ describe("handlePopstate", () => {
     expect(state.layers).toEqual([]);
     expect(commands).toEqual([
       { type: "closeDialog" },
+      { type: "clearSnapshot" },
       { type: "unmountTopLayer" },
       { type: "unmountTopLayer" },
       { type: "clearFrameCache", layerId: "L1" },
       { type: "clearFrameCache", layerId: "L2" },
       { type: "unlockScroll" },
-      { type: "clearSnapshot" },
     ]);
   });

data/lib/modal_stack/helpers/modal_stack_assets_helper.rb CHANGED Viewed

@@ -39,6 +39,12 @@ module ModalStack
         data = existing.merge(controller: controllers)
         data[:modal_stack_max_depth_value] ||= config.max_depth if config.max_depth
         data[:modal_stack_max_depth_strategy_value] ||= config.max_depth_strategy.to_s
+        # Preserve dialog across Turbo Drive page-restores (which fire on
+        # popstate when the destination history entry was set by Turbo). Without
+        # this, the Stimulus controller disconnects mid-close, the runtime is
+        # rebuilt from scratch, and any in-flight state (animations, focused
+        # element, click-event propagation) is lost.
+        data[:turbo_permanent] = "" unless data.key?(:turbo_permanent)
         data
       end

data/lib/modal_stack/version.rb CHANGED Viewed

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

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: modal_stack
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Florian Gagnaire