From aa5f12b1dfeaa98002c087975df7c588e725ea4c Mon Sep 17 00:00:00 2001
From: Wilmer Arambula <terabytesoftw@gmail.com>
Date: Sat, 26 Sep 2026 10:24:43 -0300
Subject: [PATCH] fix(a11y): make the JSON snapshot fallback payload
 keyboard-focusable and run the history and Mail chip e2e specs against Yii3.

---
 e2e/smoke.spec.js               |  2 +-
 e2e/support/environment.js      |  3 ++-
 e2e/toolbar-mail.spec.js        |  8 ++-----
 resources/views/snapshot.php    |  2 ++
 tests/View/SnapshotViewTest.php | 40 +++++++++++++++++++++++++++++++++
 5 files changed, 47 insertions(+), 8 deletions(-)
 create mode 100644 tests/View/SnapshotViewTest.php

diff --git a/e2e/smoke.spec.js b/e2e/smoke.spec.js
index 030916e..b32b5f3 100644
--- a/e2e/smoke.spec.js
+++ b/e2e/smoke.spec.js
@@ -226,7 +226,7 @@ for (const [appIndex, app] of debugApps().entries()) {
           await expectDebuggerLayout(page, entry, "light");
 
           if (entry.kind === "history") {
-            await expect(page.locator("tr[data-key]")).toHaveCount(2);
+            await expect(page.locator("tr[data-yii-debug-tag]")).toHaveCount(2);
           }
 
           await expectNoRuntimeDiagnostics(
diff --git a/e2e/support/environment.js b/e2e/support/environment.js
index 5c6b7f5..07127f9 100644
--- a/e2e/support/environment.js
+++ b/e2e/support/environment.js
@@ -109,7 +109,8 @@ export function debugPageURL(app, entry, options = {}) {
   let path;
 
   if (entry.kind === "history") {
-    path = "/debug/index";
+    // Yii2 resolves the module default action at `/debug`; Yii3 serves the history only there.
+    path = "/debug";
   } else if (entry.kind === "compare") {
     path = "/debug/compare";
   } else if (entry.kind === "phpinfo") {
diff --git a/e2e/toolbar-mail.spec.js b/e2e/toolbar-mail.spec.js
index 1ea250d..9df80ef 100644
--- a/e2e/toolbar-mail.spec.js
+++ b/e2e/toolbar-mail.spec.js
@@ -16,16 +16,12 @@ for (const app of debugApps()) {
   test(`${app.name} Mail chip label opens the capture that sent the mail`, async ({
     page,
   }) => {
-    test.skip(
-      app.id === "yii3",
-      "Yii3 has no Mail panel until the Phase 5 port.",
-    );
-
     const diagnostics = collectRuntimeDiagnostics(page);
 
     // Serve the page toolbar from the seeded GET that follows the mail-sending POST; later AJAX loads are untouched.
+    // Yii2 serves the payload at `toolbar-data`, Yii3 at `toolbar`.
     await page.route(
-      /toolbar-data/,
+      /toolbar(?:-data)?[?&]/,
       (route) => {
         const url = new URL(route.request().url());
 
diff --git a/resources/views/snapshot.php b/resources/views/snapshot.php
index a3d0f38..bcbddfe 100644
--- a/resources/views/snapshot.php
+++ b/resources/views/snapshot.php
@@ -54,8 +54,10 @@
                 ->content('JSON snapshot'),
         )
         ->render();
+// The payload scrolls horizontally on narrow viewports, so it takes keyboard focus to stay reachable.
 $panelBody = $panelContent ?? Pre::tag()
     ->class('yii-debug-panel-payload')
+    ->addAttribute('tabindex', '0')
     ->html(Code::tag()->content($payload))
     ->render();
 ?>
diff --git a/tests/View/SnapshotViewTest.php b/tests/View/SnapshotViewTest.php
new file mode 100644
index 0000000..6ae7b3f
--- /dev/null
+++ b/tests/View/SnapshotViewTest.php
@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Debug\Tests\View;
+
+use PHPUnit\Framework\Attributes\Group;
+use PHPUnit\Framework\TestCase;
+
+use function dirname;
+use function ob_get_clean;
+use function ob_start;
+
+/**
+ * Unit tests for the JSON fallback of the shared `snapshot.php` panel view.
+ */
+#[Group('view')]
+final class SnapshotViewTest extends TestCase
+{
+    public function testJsonFallbackPayloadIsKeyboardFocusable(): void
+    {
+        $failure = null;
+        $method = 'GET';
+        $panelContent = null;
+        $panelLabel = 'router';
+        $payload = '{&quot;routes&quot;: []}';
+        $renderError = null;
+        $url = 'https://example.test/';
+
+        ob_start();
+        require dirname(__DIR__, 2) . '/resources/views/snapshot.php';
+        $html = (string) ob_get_clean();
+
+        self::assertMatchesRegularExpression(
+            '~<pre\b(?=[^>]*\bclass="yii-debug-panel-payload")(?=[^>]*\btabindex="0")[^>]*>~',
+            $html,
+            'The scrollable payload must be reachable by keyboard.',
+        );
+    }
+}