test: align narration and keyboard focus expectations

Author: hhkaos

CHANGELOG.md

@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+### Fixed
+
+- E2E narration expectations include the nested-list fixture content, and the keyboard focus-ring test accounts for the explanations toggle revealed when the splitter receives focus.
+
 ## [0.2.0-beta.11] - 2026-10-18
 
 ### Added

docs/dev/PROJECT.md

@@ -355,6 +355,8 @@ The page structure is our own CSS grid (`div.layout` > `div.docs-column` (`main.
 
 | Feature | Context A | Context B | Notes |
 |---|---|---|---|
+| Keyboard focus reveals new Tab stops | Shift+Tab from a file tab reaches the explanations splitter while its toggle is hidden | The splitter's `:focus-within` reveals Hide explanations, so the next Tab reaches that button before returning to the file tab | Forward and backward Tab navigation are not symmetric when focus changes visibility. `e2e/tutorial-page.spec.ts` checks splitter → toggle → selected file tab before checking the keyboard focus ring. |
+| Shared fixture prose and narration assertions | Adding list examples to a closed disclosure preserves its initial layout | Narration with collapsed sections enabled reads that new content, including when explanations are hidden | Search `e2e/speech.spec.ts` for exact spoken-text expectations whenever editing `fixtures/framework-fixture/tutorial/tutorial.mdx`; list layout and narration tests share this fixture. |
 | Hidden explanations and scroll events | A pointer selection marks the docs scroller as user-controlled | Hiding its ancestor reports `scrollTop = 0` and can deliver scroll callbacks, which previously activated the intro or first step | Both scroll-driven step activation paths ignore a docs panel with zero `clientHeight`; keyboard navigation still works while it is hidden. Regression: `e2e/presentation.spec.ts` (select, hide, navigate, show). |
 | Starlight locals in website overrides | Starlight sets `Astro.locals.starlightRoute` at runtime | `astro check` in `site/` does not load Starlight's global types merely because the integration is configured in `.mjs` | `site/src/env.d.ts` references `@astrojs/starlight`, whose entry point imports the global declarations. Keep it when adding overrides that read route data (the Markdown source link, 2026-10-17). |
 | Astro glob loader metadata | Unchanged Markdown keeps its content digest and cached parsed data | Changing only `parseData` helpers does not invalidate that digest, so newly added metadata may be absent in an existing dev server or cached build | The website source link derives its URL from the stable content ID through `docsSourceUrl()` instead of relying on new cached metadata fields. Check both dev and preview after changing content metadata. |
@@ -398,6 +400,7 @@ The page structure is our own CSS grid (`div.layout` > `div.docs-column` (`main.
 | `JSON.parse` error position (Node/V8) | "Expected …" / "Unterminated string" messages include `position N (line L column C)` | "Unexpected token …" messages have no position | `readErrorRule()` reports those at line 1; do not rely on the message for exact positions |
 | Response headers in the runner | Same-origin or CORS-safelisted headers (`Content-Type`, `Content-Length`…): readable | Other headers of a cross-origin response: hidden unless listed in `Access-Control-Expose-Headers` | The Headers tab lists `response.headers` as the browser exposes them (lowercase names) and says so |
 | npm trusted publishing provenance | Missing or mismatched package `repository.url` | URL matching the GitHub provenance repository | Publish can fail with E422; npm may normalize the URL to `git+https://github.com/<owner>/<repo>.git` |
+| npm publish acceptance vs install availability | `npm publish` and GitHub Actions succeed, with a notice that the package is being processed | The registry can still return 404 for the version and retain the previous `latest`; pnpm reports `ERR_PNPM_NO_MATCHING_VERSION` | npm scans new versions before making them installable, typically around five minutes, sometimes 15 minutes or more (not guaranteed). Seen for core beta.11 while the scaffolder was already available. Check `npm view interactive-code-scroll@0.2.0-beta.11 version --prefer-online` before retrying the install; do not assume a pnpm cache problem or republish just because the workflow succeeded. [Official explanation](https://github.blog/changelog/2026-07-28-npm-publish-time-malware-scanning-and-dual-use-metadata/). |
 | npm publish `E404 Not Found` on `PUT` | Trusted publishing configured and valid: publishes | Expired trusted publishing setup on npmjs.com (seen for `create-interactive-code-scroll`, 0.2.0-beta.1) | The 404 hides an auth failure. Renew it in the package's Settings → Trusted publishing (GitHub Actions, `hhkaos/interactive-code-scroll`, `publish-npm.yml`, environment `npm-publish`, "Allow npm publish"), then re-run the workflow: versions already on npm are skipped. Older `gh` has no `rerun --failed`; `gh run rerun <id>` is safe |
 | Shiki line layout | `.line` as `inline-block` inside `<pre>` | `.line` as `block` inside `<pre>` | Block line spans can make Shiki's inter-line text nodes render as extra vertical spacing; keep lines inline-level and assert adjacent line spacing in E2E |
 | MDX frontmatter in Sätteri plugins | `ctx.source` has the frontmatter blanked out (lines kept) | Astro parses it first and seeds `ctx.data.astro.frontmatter` | Read the parsed object from `ctx.data`; get key line numbers from the file on disk (`frontmatterKeyLines`) |

docs/dev/documentation-review.json

@@ -1,5 +1,9 @@
 {
   "changes": [
+    {
+      "change": "E2E narration expectations include the nested-list fixture content, and the keyboard focus-ring test accounts for the explanations toggle revealed when the splitter receives focus.",
+      "reason": "Test-only corrections for existing fixture content and focus-dependent toggle visibility; no runtime behavior, public API or authoring instructions changed."
+    },
     {
       "change": "Tutorial lists use consistent item spacing, preserve paragraph separation within items and remove the extra bottom gap after nested lists.",
       "docs": [
@@ -159,7 +163,7 @@
     }
   ],
   "sourceDigest": "5f6dad69036a3198ff1e1f2a88cde05fa5872f8ee4ce1cde51d6d347976742ca",
-  "changelogDigest": "b81895ee638f56634b870a13ea1598b235c70a12db606e9e0523dabd0fdbcf67",
+  "changelogDigest": "e46aedccc1f4b2eb48f941d2bc9b099ac3472ca55f9fc9491f5c27de68ab4c86",
   "documents": {
     "README.md": "05032d254b5a82cdead0bf6d7d724d4bbe9ff162cfc9bf99d985622f7325abc8",
     "docs/authoring.md": "8018da431067f9505299368487323fe67dd25bb45f015429571306a60dbfe91f",

e2e/speech.spec.ts

@@ -170,6 +170,21 @@ test("starting with hidden explanations reads prose, hints and collapsed section
     "See the example docs.",
     "Why register more than one behavior?",
     "registerOAuthInfos() accepts an array so one app can register more than one configuration.",
+    "Review the project and its files before changing the configuration.",
+    "This longer item wraps in a narrow explanations panel.",
+    "Configure the project with these nested actions:",
+    "Set the project name.",
+    "Choose the output folder.",
+    "Keep generated files together.",
+    "Keep source files separate.",
+    "Run the project after reviewing the configuration.",
+    "The next list uses paragraphs inside its items.",
+    "Review the settings.",
+    "Include a second paragraph when the item needs more explanation.",
+    "Check the defaults.",
+    "Save the changes.",
+    "Continue with the tutorial.",
+    "The lists keep their normal separation from surrounding prose.",
     "Use registered behaviors to respond to changes.",
     "About registered behaviors: Callbacks registered for the fixture’s interactions.",
   ];

e2e/tutorial-page.spec.ts

@@ -340,6 +340,10 @@ test("shows the file tab focus ring for keyboard focus only", async ({ page }) =
   await expect(page.locator('calcite-tab-title[data-file="main.js"]')).toBeFocused();
   expect(await ring("main.js")).toBe("rgba(0, 0, 0, 0)");
   await page.keyboard.press("Shift+Tab");
+  await expect(page.locator('.splitter[aria-orientation="vertical"]')).toBeFocused();
+  // Focusing the splitter reveals its Hide explanations control, adding a Tab stop.
+  await page.keyboard.press("Tab");
+  await expect(page.locator("#docs-toggle")).toBeFocused();
   await page.keyboard.press("Tab");
   await expect(page.locator('calcite-tab-title[data-file="main.js"]')).toBeFocused();
   // Calcite fades the ring in (outline-color transition, 0.15s): right after Tab it may still be transparent.