modal_stack 0.3.0 → 0.4.1

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

@@ -4,6 +4,8 @@ import {
   createStack,
   handlePopstate,
   ModalStackDepthError,
+  pathBack,
+  pathTo,
   pop,
   push,
   replaceTop,
@@ -80,12 +82,21 @@ describe("push", () => {
       {
         type: "pushHistory",
         url: "/projects/42/edit",
-        historyState: { stackId: STACK_ID, layerId: "L1", depth: 1 },
+        historyState: { stackId: STACK_ID, layerId: "L1", depth: 1, frameIndex: 0 },
       },
       { type: "persistSnapshot" },
     ]);
   });
 
+  test("first layer carries a single-frame array", () => {
+    const { state } = pushed(freshStack());
+    expect(state.layers[0].frames).toEqual([
+      { url: "/projects/42/edit", stale: false },
+    ]);
+    expect(Object.isFrozen(state.layers[0].frames)).toBe(true);
+    expect(Object.isFrozen(state.layers[0].frames[0])).toBe(true);
+  });
+
   test("preserves side and size for drawer layers", () => {
     const { state, commands } = push(freshStack(), {
       id: "L1",
@@ -270,7 +281,7 @@ describe("push", () => {
     expect(commands).toContainEqual({
       type: "pushHistory",
       url: "/clients/new",
-      historyState: { stackId: STACK_ID, layerId: "L2", depth: 2 },
+      historyState: { stackId: STACK_ID, layerId: "L2", depth: 2, frameIndex: 0 },
     });
   });
 
@@ -296,6 +307,181 @@ describe("push", () => {
   });
 });
 
+describe("pathTo", () => {
+  test("throws on empty stack", () => {
+    expect(() => pathTo(freshStack(), { url: "/x" })).toThrow(/at least one layer/);
+  });
+
+  test("requires a frame.url", () => {
+    const s = pushed(freshStack()).state;
+    expect(() => pathTo(s, {})).toThrow(/frame\.url/);
+    expect(() => pathTo(s, { url: "" })).toThrow(/frame\.url/);
+  });
+
+  test("appends a frame to the top layer and emits mountFrame + pushHistory", () => {
+    const s = pushed(freshStack()).state;
+    const { state, commands } = pathTo(s, { url: "/projects/42/edit/step2" });
+
+    expect(state.layers).toHaveLength(1);
+    expect(state.layers[0].id).toBe("L1");
+    expect(state.layers[0].url).toBe("/projects/42/edit/step2");
+    expect(state.layers[0].frames).toEqual([
+      { url: "/projects/42/edit", stale: false },
+      { url: "/projects/42/edit/step2", stale: false },
+    ]);
+
+    expect(commands).toEqual([
+      {
+        type: "mountFrame",
+        layerId: "L1",
+        fromFrameIndex: 0,
+        toFrameIndex: 1,
+        url: "/projects/42/edit/step2",
+        stale: false,
+      },
+      {
+        type: "pushHistory",
+        url: "/projects/42/edit/step2",
+        historyState: { stackId: STACK_ID, layerId: "L1", depth: 1, frameIndex: 1 },
+      },
+      { type: "persistSnapshot" },
+    ]);
+  });
+
+  test("propagates stale flag and transition option", () => {
+    const s = pushed(freshStack()).state;
+    const { state, commands } = pathTo(
+      s,
+      { url: "/projects/42/edit/step2", stale: true },
+      { transition: "fade" },
+    );
+    expect(state.layers[0].frames[1].stale).toBe(true);
+    expect(commands[0]).toMatchObject({
+      type: "mountFrame",
+      stale: true,
+      transition: "fade",
+    });
+  });
+
+  test("rejects unknown transition", () => {
+    const s = pushed(freshStack()).state;
+    expect(() => pathTo(s, { url: "/x" }, { transition: "warp" })).toThrow(
+      /unknown transition/,
+    );
+  });
+
+  test("targets the top layer when several layers are stacked", () => {
+    let s = pushed(freshStack()).state;
+    s = push(s, { id: "L2", url: "/clients/new" }).state;
+    const { state, commands } = pathTo(s, { url: "/clients/new/contact" });
+    expect(state.layers[0].frames).toEqual([
+      { url: "/projects/42/edit", stale: false },
+    ]);
+    expect(state.layers[1].frames).toEqual([
+      { url: "/clients/new", stale: false },
+      { url: "/clients/new/contact", stale: false },
+    ]);
+    expect(commands[0]).toMatchObject({ layerId: "L2", toFrameIndex: 1 });
+  });
+});
+
+describe("pathBack", () => {
+  test("throws on empty stack", () => {
+    expect(() => pathBack(freshStack())).toThrow(/at least one layer/);
+  });
+
+  test("rejects non-positive steps", () => {
+    const s = pushed(freshStack()).state;
+    expect(() => pathBack(s, { steps: 0 })).toThrow(/positive integer/);
+    expect(() => pathBack(s, { steps: -1 })).toThrow(/positive integer/);
+    expect(() => pathBack(s, { steps: NaN })).toThrow(/positive integer/);
+  });
+
+  test("on a single-frame layer is a noop (does not close the layer)", () => {
+    const s = pushed(freshStack()).state;
+    const result = pathBack(s);
+    expect(result.state).toBe(s);
+    expect(result.commands).toEqual([]);
+  });
+
+  test("steps back one frame by default and emits unmountFrame + historyBack", () => {
+    let s = pushed(freshStack()).state;
+    s = pathTo(s, { url: "/projects/42/edit/step2" }).state;
+
+    const { state, commands } = pathBack(s);
+    expect(state.layers[0].frames).toEqual([
+      { url: "/projects/42/edit", stale: false },
+    ]);
+    expect(state.layers[0].url).toBe("/projects/42/edit");
+
+    expect(commands).toEqual([
+      {
+        type: "unmountFrame",
+        layerId: "L1",
+        fromFrameIndex: 1,
+        toFrameIndex: 0,
+        url: "/projects/42/edit",
+        stale: false,
+      },
+      { type: "historyBack", n: 1 },
+      { type: "persistSnapshot" },
+    ]);
+  });
+
+  test("steps back N frames in one shot", () => {
+    let s = pushed(freshStack()).state;
+    s = pathTo(s, { url: "/projects/42/edit/step2" }).state;
+    s = pathTo(s, { url: "/projects/42/edit/step3" }).state;
+
+    const { state, commands } = pathBack(s, { steps: 2 });
+    expect(state.layers[0].frames).toHaveLength(1);
+    expect(state.layers[0].url).toBe("/projects/42/edit");
+    expect(commands).toEqual([
+      {
+        type: "unmountFrame",
+        layerId: "L1",
+        fromFrameIndex: 2,
+        toFrameIndex: 0,
+        url: "/projects/42/edit",
+        stale: false,
+      },
+      { type: "historyBack", n: 2 },
+      { type: "persistSnapshot" },
+    ]);
+  });
+
+  test("clamps steps to keep at least the first frame", () => {
+    let s = pushed(freshStack()).state;
+    s = pathTo(s, { url: "/projects/42/edit/step2" }).state;
+    s = pathTo(s, { url: "/projects/42/edit/step3" }).state;
+
+    const { state, commands } = pathBack(s, { steps: 99 });
+    expect(state.layers[0].frames).toHaveLength(1);
+    expect(commands.find((c) => c.type === "historyBack")).toEqual({
+      type: "historyBack",
+      n: 2,
+    });
+  });
+
+  test("preserves the stale flag of the destination frame", () => {
+    let s = pushed(freshStack()).state;
+    s = pathTo(s, { url: "/step2", stale: true }).state;
+    s = pathTo(s, { url: "/step3" }).state;
+    const { commands } = pathBack(s);
+    expect(commands[0]).toMatchObject({
+      type: "unmountFrame",
+      stale: true,
+      url: "/step2",
+    });
+  });
+
+  test("rejects unknown transition", () => {
+    let s = pushed(freshStack()).state;
+    s = pathTo(s, { url: "/step2" }).state;
+    expect(() => pathBack(s, { transition: "warp" })).toThrow(/unknown transition/);
+  });
+});
+
 describe("pop", () => {
   test("noop on empty stack", () => {
     const s = freshStack();
@@ -311,6 +497,7 @@ describe("pop", () => {
     expect(commands).toEqual([
       { type: "closeDialog" },
       { type: "unmountTopLayer" },
+      { type: "clearFrameCache", layerId: "L1" },
       { type: "historyBack", n: 1 },
       { type: "unlockScroll" },
       { type: "clearSnapshot" },
@@ -324,11 +511,28 @@ describe("pop", () => {
     expect(state.layers).toHaveLength(1);
     expect(commands).toEqual([
       { type: "unmountTopLayer" },
+      { type: "clearFrameCache", layerId: "L2" },
       { type: "historyBack", n: 1 },
       { type: "inertLayer", layerId: "L1", value: false },
       { type: "persistSnapshot" },
     ]);
   });
+
+  test("popping a layer with a path walks history back across all its frames", () => {
+    let s = pushed(freshStack()).state;
+    s = pathTo(s, { url: "/projects/42/edit/step2" }).state;
+    s = pathTo(s, { url: "/projects/42/edit/step3" }).state;
+    const { state, commands } = pop(s);
+    expect(state.layers).toEqual([]);
+    expect(commands).toEqual([
+      { type: "closeDialog" },
+      { type: "unmountTopLayer" },
+      { type: "clearFrameCache", layerId: "L1" },
+      { type: "historyBack", n: 3 },
+      { type: "unlockScroll" },
+      { type: "clearSnapshot" },
+    ]);
+  });
 });
 
 describe("replaceTop", () => {
@@ -355,7 +559,7 @@ describe("replaceTop", () => {
       {
         type: "replaceHistory",
         url: "/projects/42/edit/billing",
-        historyState: { stackId: STACK_ID, layerId: "L1", depth: 1 },
+        historyState: { stackId: STACK_ID, layerId: "L1", depth: 1, frameIndex: 0 },
       },
       { type: "persistSnapshot" },
     ]);
@@ -400,10 +604,38 @@ describe("replaceTop", () => {
     expect(commands[1]).toEqual({
       type: "pushHistory",
       url: "/onboarding/step2",
-      historyState: { stackId: STACK_ID, layerId: "L1b", depth: 1 },
+      historyState: { stackId: STACK_ID, layerId: "L1b", depth: 1, frameIndex: 0 },
     });
   });
 
+  test("collapses path frames and walks history back the surplus", () => {
+    let s = pushed(freshStack()).state;
+    s = pathTo(s, { url: "/projects/42/edit/step2" }).state;
+    s = pathTo(s, { url: "/projects/42/edit/step3" }).state;
+    const { state, commands } = replaceTop(s, { url: "/projects/42/edit/billing" });
+    expect(state.layers[0].frames).toEqual([
+      { url: "/projects/42/edit/billing", stale: false },
+    ]);
+    expect(commands).toEqual([
+      { type: "clearFrameCache", layerId: "L1" },
+      { type: "historyBack", n: 2 },
+      {
+        type: "morphTopLayer",
+        layerId: "L1",
+        url: "/projects/42/edit/billing",
+        depth: 1,
+        variant: "modal",
+        dismissible: true,
+      },
+      {
+        type: "replaceHistory",
+        url: "/projects/42/edit/billing",
+        historyState: { stackId: STACK_ID, layerId: "L1", depth: 1, frameIndex: 0 },
+      },
+      { type: "persistSnapshot" },
+    ]);
+  });
+
   test("rejects unknown historyMode", () => {
     const s = pushed(freshStack()).state;
     expect(() => replaceTop(s, { url: "/x" }, { historyMode: "wat" })).toThrow(
@@ -427,11 +659,23 @@ describe("closeAll", () => {
     expect(commands).toEqual([
       { type: "closeDialog" },
       { type: "unmountAllLayers" },
+      { type: "clearFrameCache", layerId: "L1" },
+      { type: "clearFrameCache", layerId: "L2" },
+      { type: "clearFrameCache", layerId: "L3" },
       { type: "unlockScroll" },
       { type: "historyBack", n: 3 },
       { type: "clearSnapshot" },
     ]);
   });
+
+  test("counts every frame across every layer when walking history back", () => {
+    let s = pushed(freshStack()).state;
+    s = pathTo(s, { url: "/projects/42/edit/step2" }).state;
+    s = push(s, { id: "L2", url: "/clients/new" }).state;
+    s = pathTo(s, { url: "/clients/new/contact" }).state;
+    const { commands } = closeAll(s);
+    expect(commands).toContainEqual({ type: "historyBack", n: 4 });
+  });
 });
 
 describe("handlePopstate", () => {
@@ -451,6 +695,8 @@ describe("handlePopstate", () => {
     expect(commands).toEqual([
       { type: "closeDialog" },
       { type: "unmountAllLayers" },
+      { type: "clearFrameCache", layerId: "L1" },
+      { type: "clearFrameCache", layerId: "L2" },
       { type: "unlockScroll" },
       { type: "clearSnapshot" },
     ]);
@@ -467,12 +713,13 @@ describe("handlePopstate", () => {
   test("back: targetDepth < current pops layers and un-inerts new top (no historyBack)", () => {
     const s = buildTwoLayer();
     const { state, commands } = handlePopstate(s, {
-      historyState: { stackId: STACK_ID, layerId: "L1", depth: 1 },
+      historyState: { stackId: STACK_ID, layerId: "L1", depth: 1, frameIndex: 0 },
       locationHref: "/projects/42/edit",
     });
     expect(state.layers.map((l) => l.id)).toEqual(["L1"]);
     expect(commands).toEqual([
       { type: "unmountTopLayer" },
+      { type: "clearFrameCache", layerId: "L2" },
       { type: "inertLayer", layerId: "L1", value: false },
       { type: "persistSnapshot" },
     ]);
@@ -490,6 +737,8 @@ describe("handlePopstate", () => {
       { type: "closeDialog" },
       { type: "unmountTopLayer" },
       { type: "unmountTopLayer" },
+      { type: "clearFrameCache", layerId: "L1" },
+      { type: "clearFrameCache", layerId: "L2" },
       { type: "unlockScroll" },
       { type: "clearSnapshot" },
     ]);
@@ -514,7 +763,7 @@ describe("handlePopstate", () => {
       { historyMode: "push" },
     ).state;
     const { state, commands } = handlePopstate(after, {
-      historyState: { stackId: STACK_ID, layerId: "L1", depth: 1 },
+      historyState: { stackId: STACK_ID, layerId: "L1", depth: 1, frameIndex: 0 },
       locationHref: "/onboarding/step1",
     });
     expect(state.layers[0]).toMatchObject({
@@ -522,6 +771,7 @@ describe("handlePopstate", () => {
       url: "/onboarding/step1",
     });
     expect(commands).toEqual([
+      { type: "clearFrameCache", layerId: "L1b" },
       {
         type: "morphTopLayer",
         layerId: "L1",
@@ -537,12 +787,56 @@ describe("handlePopstate", () => {
   test("same depth, same layerId is a noop", () => {
     const s = pushed(freshStack()).state;
     const { state, commands } = handlePopstate(s, {
-      historyState: { stackId: STACK_ID, layerId: "L1", depth: 1 },
+      historyState: { stackId: STACK_ID, layerId: "L1", depth: 1, frameIndex: 0 },
       locationHref: "/projects/42/edit",
     });
     expect(state).toEqual(s);
     expect(commands).toEqual([]);
   });
+
+  test("back through frames: same layer, lower frameIndex steps back in path", () => {
+    let s = pushed(freshStack()).state;
+    s = pathTo(s, { url: "/projects/42/edit/step2" }).state;
+    s = pathTo(s, { url: "/projects/42/edit/step3" }).state;
+
+    const { state, commands } = handlePopstate(s, {
+      historyState: { stackId: STACK_ID, layerId: "L1", depth: 1, frameIndex: 1 },
+      locationHref: "/projects/42/edit/step2",
+    });
+
+    expect(state.layers[0].frames).toEqual([
+      { url: "/projects/42/edit", stale: false },
+      { url: "/projects/42/edit/step2", stale: false },
+    ]);
+    expect(state.layers[0].url).toBe("/projects/42/edit/step2");
+    expect(commands).toEqual([
+      {
+        type: "unmountFrame",
+        layerId: "L1",
+        fromFrameIndex: 2,
+        toFrameIndex: 1,
+        url: "/projects/42/edit/step2",
+        stale: false,
+      },
+      { type: "persistSnapshot" },
+    ]);
+  });
+
+  test("forward popstate to a frame we no longer track defers to snapshot rebuild", () => {
+    let s = pushed(freshStack()).state;
+    s = pathTo(s, { url: "/projects/42/edit/step2" }).state;
+    // user pressed back, dropping the step2 frame from state
+    s = pathBack(s).state;
+
+    const { state, commands } = handlePopstate(s, {
+      historyState: { stackId: STACK_ID, layerId: "L1", depth: 1, frameIndex: 1 },
+      locationHref: "/projects/42/edit/step2",
+    });
+    expect(state).toEqual(s);
+    expect(commands).toEqual([
+      { type: "rebuildFromSnapshot", targetDepth: 1, targetLayerId: "L1" },
+    ]);
+  });
 });
 
 describe("snapshot / restore", () => {
@@ -575,13 +869,13 @@ describe("snapshot / restore", () => {
     expect(restore("not-json", { stackId: STACK_ID })).toBeNull();
     expect(restore("", { stackId: STACK_ID })).toBeNull();
     expect(restore(null, { stackId: STACK_ID })).toBeNull();
-    expect(restore('{"v":2}', { stackId: STACK_ID })).toBeNull();
+    expect(restore('{"v":3}', { stackId: STACK_ID })).toBeNull();
     expect(restore('{"v":1}', { stackId: STACK_ID })).toBeNull();
   });
 
   test("returns null when a layer has unknown variant", () => {
     const malicious = JSON.stringify({
-      v: 1,
+      v: 2,
       stackId: STACK_ID,
       baseUrl: "/",
       layers: [{ id: "L1", url: "/", variant: "popover", dismissible: true }],
@@ -589,4 +883,95 @@ describe("snapshot / restore", () => {
     });
     expect(restore(malicious, { stackId: STACK_ID })).toBeNull();
   });
+
+  test("serializes frames as { url, stale } only", () => {
+    let s = pushed(freshStack()).state;
+    s = pathTo(s, { url: "/projects/42/edit/step2", stale: true }).state;
+    const parsed = JSON.parse(snapshot(s));
+    expect(parsed.v).toBe(2);
+    expect(parsed.layers[0].frames).toEqual([
+      { url: "/projects/42/edit", stale: false },
+      { url: "/projects/42/edit/step2", stale: true },
+    ]);
+  });
+
+  test("round-trips a layer with multiple frames", () => {
+    let s = pushed(freshStack()).state;
+    s = pathTo(s, { url: "/projects/42/edit/step2" }).state;
+    s = pathTo(s, { url: "/projects/42/edit/step3", stale: true }).state;
+    const restored = restore(snapshot(s), { stackId: STACK_ID });
+    expect(restored).toEqual(s);
+    expect(restored.layers[0].frames).toHaveLength(3);
+    expect(restored.layers[0].frames[2].stale).toBe(true);
+  });
+
+  test("accepts a v1 snapshot and synthesizes single-frame arrays", () => {
+    const v1 = JSON.stringify({
+      v: 1,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+      layers: [
+        {
+          id: "L1",
+          url: "/projects/42/edit",
+          variant: "modal",
+          dismissible: true,
+          size: null,
+          side: null,
+          width: null,
+          height: null,
+        },
+      ],
+      savedAt: Date.now(),
+    });
+    const restored = restore(v1, { stackId: STACK_ID });
+    expect(restored).not.toBeNull();
+    expect(restored.layers[0].frames).toEqual([
+      { url: "/projects/42/edit", stale: false },
+    ]);
+  });
+
+  test("returns null when a v2 layer has malformed frames", () => {
+    const malicious = JSON.stringify({
+      v: 2,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+      layers: [
+        {
+          id: "L1",
+          url: "/x",
+          variant: "modal",
+          dismissible: true,
+          size: null,
+          side: null,
+          width: null,
+          height: null,
+          frames: [{ stale: false }],
+        },
+      ],
+      savedAt: Date.now(),
+    });
+    expect(restore(malicious, { stackId: STACK_ID })).toBeNull();
+
+    const emptyFrames = JSON.stringify({
+      v: 2,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+      layers: [
+        {
+          id: "L1",
+          url: "/x",
+          variant: "modal",
+          dismissible: true,
+          size: null,
+          side: null,
+          width: null,
+          height: null,
+          frames: [],
+        },
+      ],
+      savedAt: Date.now(),
+    });
+    expect(restore(emptyFrames, { stackId: STACK_ID })).toBeNull();
+  });
 });

data/app/views/modal_stack/_dialog.html.erb

@@ -0,0 +1 @@
+<%= content_tag(:dialog, dialog_attrs) do %><% end %>

data/app/views/modal_stack/_panel.html.erb

@@ -0,0 +1,4 @@
+<%= content_tag(:div, wrapper_attrs) do %>
+  <%= back_button %>
+  <%= content %>
+<% end %>

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

@@ -56,6 +56,15 @@ ModalStack.configure do |config|
   #   :silent — drop the push, no warning
   config.max_depth_strategy = :warn
 
+  # Default transition between frames in a modal path (the wizard-style
+  # `modal_path_to` / `modal_path_back` flow). Override per call with
+  # `transition:` on the stream action when a specific step needs a
+  # different feel.
+  #   :slide — directional, current frame slides out, next slides in
+  #   :fade  — cross-fade, no direction
+  #   :none  — instantaneous swap
+  config.default_path_transition = :slide
+
   # Replace `data-turbo-confirm` window.confirm with a modal_stack
   # confirmation layer (cf. RFC §15.Q7). Off by default — opt-in.
   config.replace_turbo_confirm = false

data/lib/generators/modal_stack/views/templates/_dialog.html.erb

@@ -0,0 +1,9 @@
+<%# modal_stack dialog template — override this file to customise the HTML
+    structure of the singleton <dialog> element that acts as the modal root.
+    Available locals:
+      dialog_attrs — Hash { id:, data: { controller: "modal-stack", ... }, ...extras }
+                     Must stay on the <dialog> element — the JS Stimulus controller
+                     and layer injection depend on these attributes.
+    Note: the JS runtime appends panel layers as direct children of <dialog> via
+    appendChild. Static children you add here will be siblings of those layers. %>
+<%= content_tag(:dialog, dialog_attrs) do %><% end %>

data/lib/generators/modal_stack/views/templates/_panel.html.erb

@@ -0,0 +1,18 @@
+<%# modal_stack panel template — override this file to customise the HTML
+    structure that wraps every modal/drawer/bottom-sheet/confirmation panel.
+    Available locals:
+      content       — SafeBuffer, the yielded view content
+      back_button   — SafeBuffer | nil, pre-rendered back button (nil when back: false)
+      wrapper_attrs — Hash { class:, data:, ...extras } — must stay on the root element
+                      so the JS runtime can read its data attributes
+      size          — Symbol  :sm | :md | :lg | :xl
+      variant       — Symbol  :modal | :drawer | :bottom_sheet | :confirmation
+      dismissible   — Boolean
+      side          — Symbol | nil  :left | :right | :top | :bottom
+      width         — String | nil  CSS value (e.g. "42rem")
+      height        — String | nil  CSS value
+      transition    — Symbol | nil  :slide | :fade | :none %>
+<%= content_tag(:div, wrapper_attrs) do %>
+  <%= back_button %>
+  <%= content %>
+<% end %>

data/lib/generators/modal_stack/views/views_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/base"
+
+module ModalStack
+  module Generators
+    class ViewsGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :panel, type: :boolean, default: false,
+                           desc: "Copy only the panel partial"
+      class_option :dialog, type: :boolean, default: false,
+                            desc: "Copy only the dialog partial"
+
+      def copy_views
+        if options[:panel]
+          copy_panel
+        elsif options[:dialog]
+          copy_dialog
+        else
+          copy_panel
+          copy_dialog
+        end
+      end
+
+      def show_readme
+        say <<~TXT, :green
+
+          modal_stack views ejected to app/views/modal_stack/.
+
+          Edit the copied partials to override the default HTML structure.
+          The `wrapper_attrs` / `dialog_attrs` locals carry the required
+          data attributes — keep them on the root element so the JS runtime
+          continues to work.
+        TXT
+      end
+
+      private
+
+      def copy_panel
+        copy_file "_panel.html.erb", "app/views/modal_stack/_panel.html.erb"
+      end
+
+      def copy_dialog
+        copy_file "_dialog.html.erb", "app/views/modal_stack/_dialog.html.erb"
+      end
+    end
+  end
+end

data/lib/modal_stack/capybara.rb

@@ -14,6 +14,7 @@ module ModalStack
   module Capybara
     DIALOG_SELECTOR = "#modal-stack-root"
     LAYER_SELECTOR = '[data-modal-stack-target="layer"]:not([data-leaving])'
+    FRAME_SELECTOR = "[data-modal-stack-frame]:not([data-leaving])"
 
     # Scope Capybara matchers to a specific layer of the stack.
     #
@@ -81,5 +82,25 @@ module ModalStack
     def modal_stack_depth
       ::Capybara.current_session.all(:css, LAYER_SELECTOR, wait: 0).size
     end
+
+    # Capybara matcher: assert the top layer's path frame depth.
+    #
+    #   expect(page).to have_modal_frames(2)
+    #
+    # Layers without a path read as a single frame.
+    def have_modal_frames(count, **)
+      have_css("#{LAYER_SELECTOR}[data-frame-depth=\"#{count}\"]", **)
+    end
+
+    # Scope Capybara to the *current* frame inside the top (or specified)
+    # layer — i.e. the frame that's not animating out.
+    def within_modal_frame(depth: nil, **, &)
+      layers = ::Capybara.current_session.all(:css, LAYER_SELECTOR, minimum: 1, **)
+      layer = depth ? layers[depth - 1] : layers.last
+      raise ::Capybara::ElementNotFound, "no modal_stack layer at depth #{depth}" unless layer
+
+      frame = layer.first(:css, FRAME_SELECTOR, minimum: 1, **)
+      ::Capybara.current_session.within(frame, &)
+    end
   end
 end