modal_stack 0.2.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d872f05608ece432767e38bbe58ec38bf97c60a0cd90ccf1afd37f41f7f6192
-  data.tar.gz: 3da69811422baf2e1e7927bae0dbe46cf75311b5214e34e90e0a04e8aa691250
+  metadata.gz: c6457e6ddbb7a769783e711fd3956cbefc390ec9ada62daa6aa4d5d8a2bb7896
+  data.tar.gz: bb59d60f0eea1bbfd57506b98eff623ed1cbea3f9cb2002406d32e0a6c22df36
 SHA512:
-  metadata.gz: 3d9470889c9fa8b2d967174818eb813a90657baac94a70edadf3f7a416400e364cc5e15ed9b7274544b138f8b5647189e21143b14aa27d67cac79ae711822d20
-  data.tar.gz: 5dcdab2a2dca8c1b57b67e62f1daff68cc3b04395e5e66d9a3da933de02caef78460116c4b097fb040fa33011a83eb79f0645d6e273e91ad21ec552a27023d1b
+  metadata.gz: 69bdbb2322e3dad7984544f33b823a1ca62eb83993f51a8942a9321bfa7387978df9cc3c4ba3ee56dbfe49dd484a7a5b09f78fe811c7ebc636b8e51dd16e1e2a
+  data.tar.gz: b7c29d6355f7fb8f6fd15971037798eb22236c05bf19078d9a0cc7c58e080c09c30c0031ce98942b03fa183e8adcc301ac5f36186c77fa86443b63eafd417763

data/CHANGELOG.md

@@ -6,11 +6,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-05-14
+
 ### Added
+- **Frame transition CSS** fully implemented in all four presets (`tailwind_v4`, `tailwind_v3`, `bootstrap`, `vanilla`): `[data-transition="slide"]` animates the entering frame with `@starting-style translate` (slides in from the right on forward, from the left on back); `[data-transition="fade"]` cross-fades via `opacity`. The layer clips off-screen frames via a `:has([data-transition])` → `overflow: hidden` rule during animation, then the runtime removes `[data-transition]` / `[data-direction]` on `transitionend` (safety fallback: `#leaveTimeoutMs`-based timeout) so `overflow-y: auto` is fully restored afterward.
+- **`top` / `bottom` drawer sides** in the `vanilla` and `bootstrap` presets (parity with `tailwind_v3` / `tailwind_v4`). Both presets gain the `--modal-stack-drawer-height` CSS token (default `22rem`), entry/exit `@starting-style` translate animations, `[data-leaving]` exit rules, and updated header comments.
+- **`overscroll-behavior: contain`** on `[data-modal-stack-target="layer"]` in all four presets — prevents scroll chaining (Android pull-to-refresh, iOS bounce scrolling propagating to the page) when a modal's content is scrolled to its top or bottom boundary.
+- **Safe-area inset** support: `padding-bottom: env(safe-area-inset-bottom, 0)` on `bottom_sheet` and `drawer[data-side="bottom"]` layers in all four presets — panel content is no longer obscured by the iOS home indicator.
+- **`:focus-visible` ring** on `.modal-stack__panel-back` in all four presets — the back button now renders a keyboard-focus outline (`2px solid currentColor, offset 4px`) in full compliance with WCAG 2.4.7.
 
 ### Changed
+- `modal_stack_container` helper: extracted `build_panel_attrs` private method — eliminates the `Metrics/MethodLength` RuboCop offense introduced by the `back:` / `transition:` parameters added in 0.4.0.
 
 ### Fixed
+- `escapeAttr` fallback (used when `CSS.escape` is unavailable) now escapes `[` and `]` in addition to `"` and `\`. An unescaped `]` in a layer ID would prematurely close a CSS attribute selector such as `[data-layer-id="…"]`, producing either a silent no-op or a selector error depending on the browser.
+
+## [0.4.0] - 2026-05-08
+
+### Added
+- **Path navigation inside a single layer** — `turbo_stream.modal_path_to(...)` appends a frame to the top layer's path; `turbo_stream.modal_path_back(steps: N)` walks back. Each forward step pushes a real history entry, so browser-back walks frames one by one before closing the layer. `modal_pop` / X / ESC still close the whole layer at once and collapse all of its frames from history in a single jump.
+- **`Layer.frames` in the reducer**: every layer now carries an immutable `frames: [{ url, stale }]` array. Layers without a path read as a single-frame array, so existing `push` / `pop` / `replaceTop` behavior is unchanged.
+- **In-memory frame cache** in `BrowserRuntime`: forward frames cache their HTML so back-navigation is instant — no network round-trip. The cache is purged when the layer closes; `purgeFrameCacheAbove` evicts entries when the user steps back.
+- **`X-Modal-Stack-Stale` response header**: controllers can mark a frame stale at render time (or pass `stale: true` on the stream action) so the runtime refetches instead of restoring from cache when the user steps back to it.
+- **`modal_back_link` view helper**: renders a button wired to the new `modal-stack-back-link` Stimulus controller. Accepts `steps:` (default 1) to collapse multiple frames in a single click. Pairs with the new `back: true` option on `modal_stack_container`, which injects a back-button slot — hidden by CSS when the layer is on its first frame (`[data-frame-depth="1"]`).
+- **`config.default_path_transition`** (default `:slide`, also `:fade` / `:none`): read by `modal_path_to` / `modal_path_back` when no per-call `transition:` is given.
+- **New Capybara matchers**: `have_modal_frames(count)` and `within_modal_frame(depth: nil)` for testing path-based wizards.
+- **`modal-stack#pathBack` Stimulus action** for direct wiring on custom UI (`data-action="click->modal-stack#pathBack"`, optional `data-modal-stack-steps-param`).
+- **CSS preset hooks**: every preset (`tailwind_v3`, `tailwind_v4`, `bootstrap`, `vanilla`) gains `[data-modal-stack-frame] { display: contents }` so the runtime's frame wrapper is layout-invisible, plus a `.modal-stack__panel-back` reset.
+- **`Orchestrator#pathTo` / `pathBack`** public methods, `pathTo` / `pathBack` reducer functions, `mountFrame` / `unmountFrame` / `clearFrameCache` runtime commands.
+- New tests: 38 added across `state.test.js`, `orchestrator.test.js`, `runtime.test.js`, plus Ruby specs for the new helpers / config / stream actions and a 4-example system spec covering forward, back via helper, multi-step back, browser back through frames, and ESC mid-path.
+
+### Changed
+- **Snapshot format bumped to v2** to carry the new `frames` array. v1 snapshots from existing tabs are restored gracefully — each v1 layer is rehydrated with a synthesised single-frame array, so an in-flight upgrade doesn't break sessions.
+- **Layer DOM contract**: each layer's content is now wrapped in `<div data-modal-stack-frame data-frame-index="N">`. With `display: contents`, host CSS is unaffected. The layer carries `data-frame-depth="N"` and `data-frame-index="N"` for matchers and CSS hooks (e.g. hide the back button at depth 1).
+- **`replaceTop` collapses path frames**: when the top layer has multiple frames, `replaceTop` walks history back over the surplus, evicts the cache, and morphs to a single-frame layer. Documented as a deliberate trade-off.
+- **`pop` / `closeAll`** walk history back across every frame of every popped layer in a single jump, so the back button doesn't land on stale frame entries pointing at a closed layer.
+- **`handlePopstate`** routes on `frameIndex` as well as depth: lower frame-index in the same layer steps back via `unmountFrame`; forward to a frame the state no longer tracks (e.g. after a back) defers to `rebuildFromSnapshot`.
+- **`fetchFragment` returns `{ fragment, stale }`**: the runtime surfaces the `X-Modal-Stack-Stale` header to the orchestrator. The orchestrator's prefetch accepts both the new shape and the legacy bare-fragment return for back-compat with custom test runtimes.
+- `INITIALIZER_VERSION` bumped to `0.4.0`; the install template documents `default_path_transition`.
+
+## [0.3.0] - 2026-05-03
+
+### Added
+- **Prefetch cache + dedupe** in `Orchestrator`: fragments fetched for `push` / `replaceTop` are cached per URL (TTL 30 s) and concurrent prefetches for the same URL share a single in-flight request. Aborts pending requests on `closeAll` and on stack-mismatching `popstate`.
+- **Hover/focus prefetch** on `modal-stack-link`: links warm the cache on `pointerenter` / `focus` so the modal opens with no network latency on click. Opt out with `data-modal-stack-link-prefetch="false"`.
+- **`Orchestrator#prefetch(url)`** public method (and matching `ModalStackController#prefetch`) for warming the cache from app code.
+- **Request-scoped configuration** via `controller.modal_stack_config` (helper-method exposed). Rendering helpers now read configuration once per request instead of once per call.
+- **`:tailwind_v4` CSS preset** that chains on Tailwind v4 `@theme` tokens (`--color-*`, `--radius-*`, `--shadow-*`, `--ease-*`, `--container-*`), so the modal stack inherits the host project's Tailwind theme automatically. Fallbacks match the Tailwind v4 defaults so the preset still renders correctly when `@theme` isn't redefined (or when Tailwind v4 isn't installed).
+- **`:tailwind_v3` CSS preset** — the previous `:tailwind` preset, renamed for clarity. Static values aligned with Tailwind v3 defaults (Tailwind v3 doesn't expose tokens as CSS variables).
+- `Configuration::CSS_PROVIDER_ALIASES` constant for legacy `:tailwind` → `:tailwind_v3` normalization.
+- New tests: prefetch dedupe / cache hit / TTL / abort-on-closeAll / `prefetch` API; CSS-derived leave timeout; `:tailwind` alias normalization; generator default + alias mapping.
+
+### Changed
+- **Animation safety timeout** is now derived from the `--modal-stack-duration` CSS variable on the `<dialog>` (1.5× the declared duration, floored at 300 ms). Falls back to 600 ms when the variable is unset, so existing host CSS keeps working.
+- `BrowserRuntime#fetchFragment` accepts an `{ signal }` option to support `AbortController` cancellation.
+- **CSS preset perf overhaul**: removed animated blur from all four presets — animating `backdrop-filter: blur(2px)` on a fullscreen surface costs ~190 ms/frame on Hi-DPI displays (Retina, 4K), which collapsed modal animations to ~5 fps.
+  - The old `--modal-stack-backdrop-blur` variable (radius only) is replaced with `--modal-stack-backdrop-filter` (full filter expression). Default is `none`, which lets Chrome skip the filter pass entirely — `backdrop-filter: blur(0)` still allocated a filter layer, so a `0` radius wasn't actually free. Apps that want a blurred backdrop now opt in with `:root { --modal-stack-backdrop-filter: blur(8px); }` (any filter expression accepted, not just `blur()`).
+  - `backdrop-filter` is no longer in the backdrop's `transition` list — when the user opts in, the filter is applied statically when the dialog opens, so the cost is paid once and the per-frame compositor work disappears.
+  - `filter: blur(0.5px)` on inert (underlying) layers has been dropped — only `opacity: 0.5` remains. The blur was visually negligible on screen but forced an extra GPU layer per stacked modal.
+  - The `filter` property has been removed from the layer's `transition` list since nothing animates it any more.
+- **Backdrop fade now runs in parallel with the layer's leave animation** when closing the last modal (or `closeAll`). Previously the reducer emitted `[unmountTopLayer, …, closeDialog, …]` and the orchestrator awaited each command sequentially — `closeDialog` only fired after the layer's 220 ms `transitionend`, so the backdrop fade-out was perceived *after* the modal was gone (effective close time ≈ 440 ms). The reducer now emits `closeDialog` first; it's synchronous on the runtime, so the dialog's exit transition (opacity, backdrop background, `display`/`overlay` `allow-discrete`) starts immediately and runs alongside the layer's `[data-leaving]` transition. Total close time is now ≈ 220 ms. Fix applied to `pop`, `closeAll`, and the two `handlePopstate` branches that close the dialog.
+- **`config.css_provider` default** is now `:tailwind_v3` (was `:tailwind`). Existing apps with `config.css_provider = :tailwind` keep working — the alias is normalized to `:tailwind_v3` on assignment, with no rendered CSS change.
+- **Generator default `--css-provider`** is now `tailwind_v4` for new installs (was `tailwind`). Run `bin/rails g modal_stack:install --css-provider=tailwind_v3` to opt back in to the v3 preset, or pass the legacy `tailwind` flag — it's normalized to `tailwind_v3` in the generated initializer.
+- The `app/assets/stylesheets/modal_stack/tailwind.css` file has been renamed to `tailwind_v3.css`. Sprockets manifests written by previous installs that contain `//= link modal_stack/tailwind.css` need the line updated to `tailwind_v3.css` (or `tailwind_v4.css`). Importmap / jsbundling installs aren't affected — they don't reference the stylesheet by filename.
+- `INITIALIZER_VERSION` bumped to `0.3.0` because the generator template documents the new providers.
 
 ## [0.2.0] - 2026-05-03
 

data/README.md

@@ -9,9 +9,10 @@ browser back/forward support, and drive everything from imperative Turbo
 Stream actions (`modal_push`, `modal_pop`, `modal_replace`, `modal_close_all`).
 
 [![CI](https://github.com/Metalzoid/modal_stack/actions/workflows/main.yml/badge.svg)](https://github.com/Metalzoid/modal_stack/actions)
-[![Gem Version](https://badge.fury.io/rb/modal_stack.svg)](https://rubygems.org/gems/modal_stack)
-[![Ruby](https://img.shields.io/gem/ruby-version/modal_stack?label=ruby)](https://www.ruby-lang.org/)
-[![Rails](https://img.shields.io/gem/dv/modal_stack/railties?label=rails)](https://rubyonrails.org/)
+[![Gem Version](https://img.shields.io/gem/v/modal_stack.svg?label=gem)](https://rubygems.org/gems/modal_stack)
+[![Downloads](https://img.shields.io/gem/dt/modal_stack?label=downloads)](https://rubygems.org/gems/modal_stack)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
+[![Rails](https://img.shields.io/badge/rails-7.2%20%7C%208.0%20%7C%208.1-CC0000?logo=rubyonrails&logoColor=white)](https://rubyonrails.org/)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE.txt)
 
 </div>
@@ -81,16 +82,17 @@ browser-`back`-ing through nested confirmation steps — they break down.
 ## ✨ Features
 
 - 🪜 **Stack of N layers** — push modals on top of modals; the underlying ones become `inert` automatically.
+- 🛤️ **Path inside a layer** — `modal_path_to` / `modal_path_back` for wizards & flows: each step gets its own URL and history entry, browser-back walks frames one by one, the X button collapses the whole path in a single jump.
 - 🪟 **Native `<dialog>`** — focus trap, ESC, accessible roles for free.
 - 🔗 **Deep-linking** — the top of the stack lives in `window.location`. Bookmark it, share it, refresh it.
-- ↩️ **Browser back = pop** — one history entry per layer; `cmd`+`←` does what users expect.
-- 🎮 **Imperative Turbo Stream actions** — `turbo_stream.modal_push / modal_pop / modal_replace / modal_close_all` from anywhere.
-- 🎨 **Three CSS presets** — Tailwind, Bootstrap, vanilla. All driven by `--modal-stack-*` CSS variables for easy retheming.
-- 🪞 **Four variants** — `modal`, `drawer` (with side), `bottom_sheet`, `confirmation`.
+- ↩️ **Browser back = pop or step-back** — frame paths collapse to single history jumps when the layer closes.
+- 🎮 **Imperative Turbo Stream actions** — `turbo_stream.modal_push / modal_pop / modal_replace / modal_close_all / modal_path_to / modal_path_back` from anywhere.
+- 🎨 **Four CSS presets** — Tailwind v4, Tailwind v3, Bootstrap, vanilla. All driven by `--modal-stack-*` CSS variables for easy retheming. Frame transitions (`slide`, `fade`) are fully implemented in every preset via `@starting-style`.
+- 🪞 **Four variants** — `modal`, `drawer` (left/right/top/bottom), `bottom_sheet`, `confirmation`.
 - 📏 **Sizes & custom dimensions** — `:sm` / `:md` / `:lg` / `:xl`, or pass `width:` / `height:` strings (`"42rem"`, `"min(90vw, 56rem)"`).
 - 🔒 **Dismissible flag** — `dismissible: false` for confirmations users must answer.
 - ♿ **`prefers-reduced-motion`** — animations collapse to 1ms when the OS asks.
-- 🧪 **Capybara matchers** — `within_modal`, `have_modal_open`, `have_modal_stack(depth: 2)`, `close_modal`, `close_all_modals`.
+- 🧪 **Capybara matchers** — `within_modal`, `within_modal_frame`, `have_modal_open`, `have_modal_stack(depth: 2)`, `have_modal_frames(2)`, `close_modal`, `close_all_modals`.
 - ⚡ **Three asset pipelines** — Importmap (default), jsbundling, Sprockets.
 - 🧱 **Engine-based** — zero monkey-patching, pure Rails Engine + Stimulus + Turbo.
 
@@ -140,10 +142,11 @@ $ bin/rails g modal_stack:install --mode=sprockets   # legacy apps
 Pick the CSS preset that matches your stack:
 
 ```bash
-$ bin/rails g modal_stack:install --css-provider=tailwind   # default
-$ bin/rails g modal_stack:install --css-provider=bootstrap  # picks up Bootstrap 5 vars
-$ bin/rails g modal_stack:install --css-provider=vanilla    # framework-free
-$ bin/rails g modal_stack:install --css-provider=none       # bring your own CSS
+$ bin/rails g modal_stack:install --css-provider=tailwind_v4 # default — chains on Tailwind v4 @theme tokens
+$ bin/rails g modal_stack:install --css-provider=tailwind_v3 # static values aligned with Tailwind v3
+$ bin/rails g modal_stack:install --css-provider=bootstrap   # picks up Bootstrap 5 vars
+$ bin/rails g modal_stack:install --css-provider=vanilla     # framework-free
+$ bin/rails g modal_stack:install --css-provider=none        # bring your own CSS
 ```
 
 ### What the generator does
@@ -204,16 +207,17 @@ Everything lives in `config/initializers/modal_stack.rb`:
 ```ruby
 ModalStack.configure do |config|
   # ─── Presentation ─────────────────────────────────────────────────
-  config.css_provider     = :tailwind   # :tailwind | :bootstrap | :vanilla | :none
+  config.css_provider     = :tailwind_v4 # :tailwind_v3 | :tailwind_v4 | :bootstrap | :vanilla | :none
   config.default_variant  = :modal      # :modal | :drawer | :bottom_sheet | :confirmation
   config.default_size     = :md         # :sm | :md | :lg | :xl
   config.default_dismissible = true     # ESC + backdrop click close the layer
 
   # ─── Behavior ─────────────────────────────────────────────────────
-  config.max_depth              = 5     # hard cap on nested layers (nil to disable)
-  config.max_depth_strategy     = :warn # :warn | :raise | :silent
-  config.respect_reduced_motion = true  # honor prefers-reduced-motion
-  config.replace_turbo_confirm  = false # use modal_stack confirmations for data-turbo-confirm
+  config.max_depth              = 5      # hard cap on nested layers (nil to disable)
+  config.max_depth_strategy     = :warn  # :warn | :raise | :silent
+  config.default_path_transition = :slide # :slide | :fade | :none
+  config.respect_reduced_motion = true   # honor prefers-reduced-motion
+  config.replace_turbo_confirm  = false  # use modal_stack confirmations for data-turbo-confirm
 
   # ─── Wiring (rarely changed) ──────────────────────────────────────
   config.dialog_id                 = "modal-stack-root"
@@ -359,10 +363,12 @@ strings — they're applied as inline styles, taking precedence over `size:`:
 ### Wizards & multi-step flows
 
 For step-by-step flows inside a single layer (onboarding, multi-step forms),
-combine `modal_push` (for the initial open) with `modal_replace` carrying
-`history: :push` between steps. Each step gets its own URL and a real
-history entry, so browser-back returns to the previous step (not the page
-behind the wizard):
+use `modal_path_to` to advance and `modal_path_back` (or the
+`modal_back_link` helper) to step back. The current frame's HTML is cached
+in memory, so back-navigation is instant — no network round-trip — and
+each forward step pushes a real history entry, so browser-back walks the
+frames one by one. When the user closes the layer (X / ESC / backdrop /
+`modal_pop`), every frame's history entry collapses in a single jump.
 
 ```ruby
 class WizardController < ApplicationController
@@ -372,10 +378,11 @@ class WizardController < ApplicationController
     respond_to do |format|
       format.html # full-page render for deep-links
       format.turbo_stream do
-        render turbo_stream: turbo_stream.modal_replace(
+        render turbo_stream: turbo_stream.modal_path_to(
           template: "wizard/step_2",
-          history: :push,
           url: wizard_step_2_path
+          # transition: :fade        # :slide (default from config) | :fade | :none
+          # stale: true              # force a refetch when the user steps back here
         )
       end
     end
@@ -383,6 +390,36 @@ class WizardController < ApplicationController
 end
 ```
 
+```erb
+<%# wizard/step_2.html.erb %>
+<%= modal_stack_container(back: true) do %>
+  <h2>Step 2</h2>
+  <%# … form … %>
+
+  <%= modal_back_link "Back" %>
+  <%# or modal_back_link "Restart", steps: 99    # clamped at the first frame %>
+<% end %>
+```
+
+`back: true` on `modal_stack_container` injects a back-button slot —
+hidden by CSS at `[data-frame-depth="1"]`, visible from frame 2 onward.
+
+To force a refresh when the user steps back to a frame (e.g. its data is
+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.
+
+> ⚠️ **`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
+> entries are walked back. Use `modal_path_back` if you want to step
+> back, `modal_replace` if you want to swap the entire layer.
+
+If you'd rather not keep a back-history (e.g. each step replaces the
+previous and there's no going back), use the older `modal_replace`
+mechanism with `history: :push` instead — the URL still changes per
+step, but no in-memory cache is kept and `replaceTop` is the right tool.
+
 ### Stack depth & inertness
 
 When a layer is pushed on top of another, the bottom layer automatically
@@ -420,7 +457,7 @@ ModalStack.reset_configuration!         # test-fixture helper
 
 | Attribute                    | Type    | Default                  | Description |
 | ---------------------------- | ------- | ------------------------ | ----------- |
-| `css_provider`               | Symbol  | `:tailwind`              | One of `:tailwind`, `:bootstrap`, `:vanilla`, `:none`. Determines which stylesheet `modal_stack_stylesheet_link_tag` resolves to. Validated. |
+| `css_provider`               | Symbol  | `:tailwind_v3`           | One of `:tailwind_v3`, `:tailwind_v4`, `:bootstrap`, `:vanilla`, `:none`. Determines which stylesheet `modal_stack_stylesheet_link_tag` resolves to. The legacy `:tailwind` is accepted and normalized to `:tailwind_v3`. New installs default to `:tailwind_v4`. Validated. |
 | `assets_mode`                | Symbol  | `:auto`                  | One of `:importmap`, `:jsbundling`, `:sprockets`, `:auto`. Used by the generator. Validated. |
 | `default_variant`            | Symbol  | `:modal`                 | `:modal`, `:drawer`, `:bottom_sheet`, or `:confirmation`. Validated. |
 | `default_size`               | Symbol  | `:md`                    | `:sm`, `:md`, `:lg`, `:xl`. Validated. |
@@ -428,6 +465,7 @@ ModalStack.reset_configuration!         # test-fixture helper
 | `default_classes`            | Hash    | `{ ... }`                | Hash of extra CSS class strings keyed by `:modal_panel`, `:drawer_panel`, `:bottom_sheet_panel`, `:confirmation_panel`. Useful for adding utility classes on top of the chosen preset. |
 | `max_depth`                  | Integer | `5`                      | Hard cap on stack depth. Coerced from strings; set to `nil` to disable. Validated. |
 | `max_depth_strategy`         | Symbol  | `:warn`                  | One of `:warn`, `:raise`, `:silent`. See [Stack depth & inertness](#stack-depth--inertness). Validated. |
+| `default_path_transition`    | Symbol  | `:slide`                 | Default transition for `modal_path_to` / `modal_path_back` when no per-call `transition:` is given. One of `:slide`, `:fade`, `:none`. Validated. |
 | `request_header`             | String  | `"X-Modal-Stack-Request"` | HTTP header used by the JS runtime to signal stack-originated fetches. Read by `modal_stack_request?`. |
 | `dialog_id`                  | String  | `"modal-stack-root"`     | The id of the singleton `<dialog>`. Override only on name collision. |
 | `stack_root_data_attribute`  | String  | `"modal-stack"`          | The Stimulus `data-controller` value attached to the `<dialog>`. |
@@ -444,8 +482,9 @@ 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:, html: {}) { ... }` | Wraps a panel view with the markup the JS runtime expects. Renders a `<div>` carrying the size/variant/dismissible/dimension data attributes. |
-| `modal_stack_stylesheet_link_tag(**options)`      | Emits `<link rel="stylesheet">` for the configured preset (`modal_stack/tailwind.css`, etc.). Returns an empty SafeBuffer when `css_provider = :none`. |
+| `modal_stack_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_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>`. |
 | `modal_stack_javascript_tag`                      | Reserved hook for layouts; currently a no-op (JS is loaded via your bundler / importmap). |
 
@@ -470,11 +509,21 @@ options as Turbo's built-in stream actions (`partial:`, `template:`,
 | ----------------------------------------------------------- | ------- |
 | `modal_push(content = nil, **opts, &block)`                 | `variant:`, `dismissible:`, `url:`, `side:`, `size:`, `width:`, `height:`, plus any rendering options |
 | `modal_pop`                                                 | — |
-| `modal_replace(content = nil, **opts, &block)`              | All `modal_push` options plus `history:` (`:replace` *(default)* or `:push`) and `layer_id:` |
+| `modal_replace(content = nil, **opts, &block)`              | All `modal_push` options plus `history:` (`:replace` *(default)* or `:push`) and `layer_id:`. **Resets the path to a single frame** when the top layer has multiple frames. |
 | `modal_close_all`                                           | — |
+| `modal_path_to(content = nil, **opts, &block)`              | `url:`, `transition:` (`:slide` *(default from config)* / `:fade` / `:none`), `stale:` (when true, runtime refetches on back), `layer_id:`, plus any rendering options. |
+| `modal_path_back(steps: 1, transition: nil)`                | `steps:` (positive integer, clamped at the first frame), `transition:` override. |
 
 `history: :push` raises `ArgumentError` if given any value other than
-`:push` or `:replace`.
+`:push` or `:replace`. Unknown transitions on `modal_path_to` /
+`modal_path_back` raise `ArgumentError` as well.
+
+> 💡 **Stale frames.** When you want a frame to refetch on back instead
+> of restoring from the in-memory cache, either pass `stale: true` to
+> `modal_path_to` or set the `X-Modal-Stack-Stale: true` header on the
+> response. Useful when the frame's data is expected to change between
+> the forward visit and the back visit (e.g. a list that the user
+> mutated downstream).
 
 ### Layer DOM contract
 
@@ -487,24 +536,42 @@ Each pushed layer is a `<div>` inside the dialog with:
      data-variant="drawer"
      data-side="right"
      data-dismissible="true"
+     data-frame-index="1"
+     data-frame-depth="2"
      data-modal-stack-size="lg"
      data-modal-stack-width="42rem"  style="width: 42rem;">
-  <!-- panel content -->
+  <div data-modal-stack-frame
+       data-frame-index="1"
+       data-transition="slide"
+       data-direction="forward">
+    <!-- panel content -->
+  </div>
 </div>
 ```
 
+The frame wrapper sits between the layer and the panel content. It
+defaults to `display: contents` so it is invisible to host CSS. When a
+transition is requested, the runtime sets `[data-transition]` and
+`[data-direction]` on the entering frame — the shipped presets pick
+these up via `@starting-style` rules (`slide`: translate from right/left,
+`fade`: opacity 0→1) and restore `overflow-y: auto` on the layer once
+`transitionend` fires. `data-frame-depth="N"` on the layer reflects the
+current path length — `1` for layers without a path, `N` for layers `N`
+frames deep.
+
 Underlying layers receive `inert`. A layer being unmounted gets
 `data-leaving=""` for the duration of the exit transition (capped at
 600ms even if the host CSS forgets to define one).
 
 ### Stimulus controllers
 
-Both controllers are registered via `installModalStack(application)`.
+All three controllers are registered via `installModalStack(application)`.
 
 | Identifier             | Role |
 | ---------------------- | ---- |
-| `modal-stack`          | Bound to the singleton `<dialog>`. Wires popstate / cancel / backdrop-click listeners, registers the `Turbo.StreamActions`, hosts the Orchestrator. |
+| `modal-stack`          | Bound to the singleton `<dialog>`. Wires popstate / cancel / backdrop-click listeners, registers the `Turbo.StreamActions`, hosts the Orchestrator. Also exposes a public `pathBack` action — wire it on any element via `data-action="click->modal-stack#pathBack"` (with optional `data-modal-stack-steps-param="2"`). |
 | `modal-stack-link`     | Attached to elements rendered by `modal_link_to`. On `click`, finds the `modal-stack` controller and calls `push({ url, variant, … })` from the element's data attributes. |
+| `modal-stack-back-link`| Attached to elements rendered by `modal_back_link`. On `click`, calls `orchestrator.pathBack({ steps })` — never closes the layer; clamps at the first frame. |
 
 ### JS runtime
 
@@ -514,11 +581,13 @@ The package exports a small functional core + a browser adapter:
 import {
   // pure reducer — no IO, no DOM
   createStack, push, pop, replaceTop, closeAll, handlePopstate,
-  snapshot, restore, topLayer, VARIANTS, ModalStackDepthError,
+  pathTo, pathBack,
+  snapshot, restore, topLayer, VARIANTS, TRANSITIONS,
+  ModalStackDepthError,
 
   // orchestrator + browser runtime
   Orchestrator, BrowserRuntime,
-  FRAGMENT_HEADER, SNAPSHOT_KEY, SCROLLBAR_WIDTH_VAR,
+  FRAGMENT_HEADER, STALE_HEADER, SNAPSHOT_KEY, SCROLLBAR_WIDTH_VAR,
 } from "modal_stack"
 
 import { install } from "modal_stack/install"
@@ -530,12 +599,13 @@ side-effect-free and 100% covered; the browser adapter is the only
 file that touches `<dialog>`, `history`, `fetch`, and `sessionStorage`.
 
 The reducer's command type vocabulary (`mountLayer`, `morphTopLayer`,
-`unmountTopLayer`, `unmountAllLayers`, `showDialog`, `closeDialog`,
-`lockScroll`, `unlockScroll`, `inertLayer`, `pushHistory`,
-`replaceHistory`, `historyBack`, `rebuildFromSnapshot`, `persistSnapshot`,
-`clearSnapshot`) forms the contract between `state.js` and any runtime —
-swap in a custom adapter (e.g. for Hotwire Native) by implementing one
-method per command name.
+`unmountTopLayer`, `unmountAllLayers`, `mountFrame`, `unmountFrame`,
+`clearFrameCache`, `showDialog`, `closeDialog`, `lockScroll`,
+`unlockScroll`, `inertLayer`, `pushHistory`, `replaceHistory`,
+`historyBack`, `rebuildFromSnapshot`, `persistSnapshot`, `clearSnapshot`)
+forms the contract between `state.js` and any runtime — swap in a
+custom adapter (e.g. for Hotwire Native) by implementing one method
+per command name.
 
 #### Custom events
 
@@ -544,7 +614,7 @@ The `<dialog>` emits two `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`) threw or rejected. The page is not crashed; surface UI feedback in the listener. |
+| `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. |
 
 ```js
 document.addEventListener("modal_stack:error", (event) => {
@@ -577,10 +647,12 @@ specs. For Minitest, `require "modal_stack/capybara/minitest"`.
 | Helper / matcher                  | Description |
 | --------------------------------- | ----------- |
 | `within_modal(depth: nil) { ... }`| Scopes Capybara matchers to a layer. Defaults to the topmost; `depth: 1` is the bottom. Raises `Capybara::ElementNotFound` when no such layer exists. |
+| `within_modal_frame(depth: nil) { ... }` | Scopes Capybara matchers to the **current** frame inside a layer (the one that's not animating out). Useful when a path is in flight. |
 | `have_modal_open`                 | Matcher: passes when the dialog has `[open]`. |
 | `have_no_modal_open`              | Negation. |
 | `have_modal_stack(depth: nil)`    | Matcher: asserts the live (non-leaving) layer count. |
 | `have_no_modal_stack`             | Negation. |
+| `have_modal_frames(count)`        | Matcher: asserts the top layer's path has `count` frames. Layers without a path read as `1`. |
 | `close_modal`                     | Sends `ESC` to the dialog. Honors `dismissible: false` (the layer stays). |
 | `close_all_modals(max: 16)`       | Pops every layer by sending `ESC` repeatedly. |
 | `modal_stack_depth`               | Reads the current depth from the live DOM. |
@@ -594,7 +666,7 @@ $ bin/rails g modal_stack:install [flags]
 | Flag                  | Type    | Default     | Values |
 | --------------------- | ------- | ----------- | ------ |
 | `--mode`              | String  | `auto`      | `auto`, `importmap`, `jsbundling`, `sprockets` |
-| `--css-provider`      | String  | `tailwind`  | `tailwind`, `bootstrap`, `vanilla`, `none` |
+| `--css-provider`      | String  | `tailwind_v4` | `tailwind_v3`, `tailwind_v4`, `bootstrap`, `vanilla`, `none` (legacy `tailwind` accepted, normalized to `tailwind_v3`) |
 | `--skip-layout`       | Boolean | `false`     | When set, doesn't inject the stylesheet/dialog helpers into `application.html.erb` |
 | `--skip-js`           | Boolean | `false`     | When set, skips the Importmap pin / package install / Stimulus install wiring |
 | `--skip-initializer`  | Boolean | `false`     | When set, doesn't generate `config/initializers/modal_stack.rb` |
@@ -613,17 +685,27 @@ safe.
 
 ## 🎨 CSS presets & theming
 
-Three opinionated stylesheets ship with the gem. Pick one with
+Four opinionated stylesheets ship with the gem. Pick one with
 `config.css_provider`:
 
-| Preset       | File                                       | Best for |
-| ------------ | ------------------------------------------ | -------- |
-| `:tailwind`  | `app/assets/stylesheets/modal_stack/tailwind.css`  | Tailwind apps — uses Tailwind tokens by default but overridable |
-| `:bootstrap` | `app/assets/stylesheets/modal_stack/bootstrap.css` | Picks up Bootstrap 5 CSS variables |
-| `:vanilla`   | `app/assets/stylesheets/modal_stack/vanilla.css`   | Framework-free, neutral defaults |
-| `:none`      | —                                          | Bring your own CSS |
+| Preset          | File                                                  | Best for |
+| --------------- | ----------------------------------------------------- | -------- |
+| `:tailwind_v4`  | `app/assets/stylesheets/modal_stack/tailwind_v4.css`  | Tailwind v4 apps — chains on `@theme` tokens (`--color-*`, `--radius-*`, `--shadow-*`, `--container-*`) so the modal picks up your theme automatically. Falls back to Tailwind defaults when `@theme` isn't redefined. |
+| `:tailwind_v3`  | `app/assets/stylesheets/modal_stack/tailwind_v3.css`  | Tailwind v3 apps — static values aligned with Tailwind v3 defaults (v3 doesn't expose tokens as CSS variables). Legacy `:tailwind` is accepted as an alias. |
+| `:bootstrap`    | `app/assets/stylesheets/modal_stack/bootstrap.css`    | Picks up Bootstrap 5 CSS variables |
+| `:vanilla`      | `app/assets/stylesheets/modal_stack/vanilla.css`      | Framework-free, neutral defaults |
+| `:none`         | —                                                     | Bring your own CSS |
+
+All four presets share the following capabilities:
+
+- **Frame transitions** — `slide` (horizontal translate via `@starting-style`) and `fade` (opacity) are both fully implemented. The entering frame animates in; the layer clips off-screen frames with `overflow: hidden` for the duration, then restores `overflow-y: auto`.
+- **All four drawer sides** — `left`, `right`, `top`, `bottom` with matching entry/exit animations.
+- **Mobile scroll containment** — `overscroll-behavior: contain` prevents scroll chaining when modal content reaches its boundary.
+- **Safe-area inset** — `bottom_sheet` and `drawer[data-side="bottom"]` apply `env(safe-area-inset-bottom)` padding.
+- **Keyboard focus ring** — `.modal-stack__panel-back` has a `:focus-visible` outline.
+- **Reduced-motion** — frame transition durations collapse to `1ms` alongside layer transitions.
 
-All three presets are driven by the same `--modal-stack-*` CSS variables.
+All presets are driven by the same `--modal-stack-*` CSS variables.
 Override on `:root` to retheme without touching the gem:
 
 ```css
@@ -681,9 +763,11 @@ provided by the host app).
 
 - **Native `<dialog>`** — modern browsers handle focus trap, ESC, and `aria-modal` for free.
 - **Inertness** — underlying layers in a stack receive `inert`, so screen-readers and keyboard navigation skip them.
-- **Reduced motion** — when `prefers-reduced-motion: reduce` is set, presets collapse transitions to 1ms.
+- **Reduced motion** — when `prefers-reduced-motion: reduce` is set, presets collapse all transitions (layer and frame) to 1 ms.
 - **Focus restoration** — when a layer is popped, focus returns to the trigger element (per `<dialog>` semantics).
-- **Body scroll lock** — `<body data-modal-stack-locked>` prevents background scroll while the dialog is open.
+- **Back-button focus ring** — `.modal-stack__panel-back` renders a `:focus-visible` outline on keyboard focus in every preset.
+- **Body scroll lock** — `<body data-modal-stack-locked>` prevents background scroll while the dialog is open; `overscroll-behavior: contain` on layers additionally blocks scroll chaining (pull-to-refresh, iOS bounce) when modal content is scrolled to its boundary.
+- **Safe-area padding** — `bottom_sheet` and bottom drawers apply `env(safe-area-inset-bottom)` so content is never hidden under the iOS home indicator.
 
 ---
 
@@ -720,7 +804,7 @@ modal_stack/
 ├── app/
 │   ├── assets/
 │   │   ├── javascripts/modal_stack.js  # pre-built importmap bundle (committed)
-│   │   └── stylesheets/modal_stack/    # tailwind / bootstrap / vanilla presets
+│   │   └── stylesheets/modal_stack/    # tailwind_v3 / tailwind_v4 / bootstrap / vanilla presets
 │   ├── javascript/modal_stack/         # ES module sources + bun tests
 │   │   ├── state.js                    # pure reducer (100% coverage)
 │   │   ├── orchestrator.js             # state → command translator