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

modal_stack 0.4.1 → 0.4.3

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 (20) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +23 -0
data/README.md +98 -7
data/app/assets/javascripts/modal_stack.js +205 -23
data/app/assets/stylesheets/modal_stack/bootstrap.css +35 -0
data/app/assets/stylesheets/modal_stack/tailwind_v3.css +35 -0
data/app/assets/stylesheets/modal_stack/tailwind_v4.css +35 -0
data/app/assets/stylesheets/modal_stack/vanilla.css +35 -0
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/app/views/modal_stack/_panel.html.erb +13 -0
data/lib/modal_stack/helpers/modal_stack_assets_helper.rb +6 -0
data/lib/modal_stack/helpers/modal_stack_container_helper.rb +4 -1
data/lib/modal_stack/version.rb +1 -1
metadata +2 -2

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6457e6ddbb7a769783e711fd3956cbefc390ec9ada62daa6aa4d5d8a2bb7896
-  data.tar.gz: bb59d60f0eea1bbfd57506b98eff623ed1cbea3f9cb2002406d32e0a6c22df36
+  metadata.gz: 992372f08bce8ea31105e8cba05c60035014852c197c38b325648eaebf154820
+  data.tar.gz: 70db58c91eda0101149fde86cec748812c7b8aff3f3908a30d6178538000c98f
 SHA512:
-  metadata.gz: 69bdbb2322e3dad7984544f33b823a1ca62eb83993f51a8942a9321bfa7387978df9cc3c4ba3ee56dbfe49dd484a7a5b09f78fe811c7ebc636b8e51dd16e1e2a
-  data.tar.gz: b7c29d6355f7fb8f6fd15971037798eb22236c05bf19078d9a0cc7c58e080c09c30c0031ce98942b03fa183e8adcc301ac5f36186c77fa86443b63eafd417763
+  metadata.gz: 98043c481ff734f042b88f2117b766fb1dc2110dfdacbad71d66de39471999d15e1dfb368e9466964d1127b809ed4bb3a8aea4fb83847aba6163d717f75eb4bf
+  data.tar.gz: 46b3b5491dd13836ee207e62b42d2a3023ee1b65ac75da634d40a944608822b2a40e102ef39861f0208ab47a17afb4dbe0d529341c8d9611adce2ef9ba600ab5

data/CHANGELOG.md CHANGED Viewed

@@ -6,6 +6,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
+## [0.4.3] - 2026-05-25
+### Added
+- **`title:` option on `modal_stack_container`** — renders a `<header class="modal-stack__panel-header">` containing an `<h2 class="modal-stack__panel-title">` above the panel content. No output when omitted, so existing panels are unaffected.
+- **`close_button:` option on `modal_stack_container`** — renders a `×` button (`<button class="modal-stack__panel-close">`) wired to `modal-stack#pop`. Defaults to the `dismissible:` value, so dismissible layers get a close button for free and locked layers (`dismissible: false`) get none by default. Pass `close_button: false` to suppress it explicitly on a dismissible layer.
+- **CSS** for the new header slot in all four presets (`tailwind_v4`, `tailwind_v3`, `bootstrap`, `vanilla`): `.modal-stack__panel-header` (flexbox row), `.modal-stack__panel-title` (flex-1), `.modal-stack__panel-close` (transparent button, opacity hover, focus-visible ring).
+- `title` and `show_close` passed as **separate partial locals** to `_panel.html.erb` so host apps overriding the partial can consume them individually rather than receiving a pre-rendered HTML blob.
+## [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

@@ -279,9 +279,30 @@ options at the call site:
 ```
 `modal_stack_container` accepts `size:`, `variant:`, `side:`, `width:`,
-`height:`, `dismissible:`, and an `html: { class:, data:, ... }` Hash for
+`height:`, `dismissible:`, `title:`, `close_button:`, and an `html: { class:, data:, ... }` Hash for
 extra attributes on the wrapping `<div>`.
+Pass `title:` to render a `<header>` with an `<h2>` above the panel content.
+`close_button:` (default: inherits `dismissible:`) renders a `×` button wired to
+`modal-stack#pop` — locked layers (`dismissible: false`) get no close button by default:
+```erb
+<%# Dismissible — title + auto close button %>
+<%= modal_stack_container title: "Edit project", size: :md do %>
+  <%= render "form", project: @project %>
+<% end %>
+<%# Locked — title only, no × (close_button: defaults to false) %>
+<%= modal_stack_container title: "Are you sure?",
+                           variant: :confirmation,
+                           dismissible: false do %>
+  <button data-action="click->modal-stack#pop">Confirm</button>
+<% end %>
+<%# Explicit override %>
+<%= modal_stack_container title: "Info", close_button: false do %>…<% end %>
+```
 ### Stack-aware controllers
 `modal_stack_layout` switches the controller's layout to `modal` **only**
@@ -409,6 +430,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
@@ -482,7 +505,7 @@ Injected into `ActionView::Base` by the engine — available in every view.
 | Helper                                            | Description |
 | ------------------------------------------------- | ----------- |
 | `modal_link_to(name, options, html_options)`      | Renders a `link_to` wired to push a layer when clicked. Accepts the modal options (`as:`, `side:`, `size:`, `width:`, `height:`, `dismissible:`) on top of standard `link_to` arguments. Falls back to plain `link_to` for Hotwire Native requests. |
-| `modal_stack_container(size:, variant:, side:, width:, height:, dismissible:, back:, transition:, html: {}) { ... }` | Wraps a panel view with the markup the JS runtime expects. `back: true` injects a back-button slot wired to `modal-stack#pathBack` (hidden by CSS at the first frame); `transition:` writes `data-modal-stack-transition` for host CSS hooks. |
+| `modal_stack_container(size:, variant:, side:, width:, height:, dismissible:, back:, transition:, title:, close_button:, html: {}) { ... }` | Wraps a panel view with the markup the JS runtime expects. `back: true` injects a back-button slot wired to `modal-stack#pathBack` (hidden by CSS at the first frame); `transition:` writes `data-modal-stack-transition` for host CSS hooks. `title:` renders a `<header>` with `<h2>`; `close_button:` (default: `dismissible:` value) renders a `×` close button. |
 | `modal_back_link(name = nil, **opts) { ... }`     | Renders a `<button>` wired to the `modal-stack-back-link` Stimulus controller. Pass `steps:` (default `1`) to walk back multiple frames in a single click — clamped at the first frame, never closes the layer. Block form supported for custom markup (e.g. `<%= modal_back_link(class: "btn") { "← Back" } %>`). |
 | `modal_stack_stylesheet_link_tag(**options)`      | Emits `<link rel="stylesheet">` for the configured preset (`modal_stack/tailwind_v4.css`, etc.). Returns an empty SafeBuffer when `css_provider = :none`. |
 | `modal_stack_dialog_tag(**html_options)`          | Emits the singleton `<dialog id="modal-stack-root" data-controller="modal-stack">`. Drop just before `</body>`. |
@@ -609,12 +632,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 +648,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/assets/stylesheets/modal_stack/bootstrap.css CHANGED Viewed

@@ -331,6 +331,41 @@ body[data-modal-stack-locked] {
   display: none;
 }
+/* --- Header slot ------------------------------------------------- */
+.modal-stack__panel-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+}
+.modal-stack__panel-title {
+  margin: 0;
+  flex: 1;
+  min-width: 0;
+}
+.modal-stack__panel-close {
+  font: inherit;
+  background: transparent;
+  border: 0;
+  padding: 0.25rem;
+  cursor: pointer;
+  color: inherit;
+  opacity: 0.55;
+  line-height: 1;
+  font-size: 1.4em;
+  flex-shrink: 0;
+  transition: opacity 150ms ease;
+}
+.modal-stack__panel-close:hover { opacity: 1; }
+.modal-stack__panel-close:focus-visible {
+  outline: 2px solid currentColor;
+  outline-offset: 2px;
+  border-radius: 2px;
+}
 @media (prefers-reduced-motion: reduce) {
   #modal-stack-root,
   #modal-stack-root::backdrop,