@codyswann/lisa 4.66.0 → 4.66.1

package/plugins/lisa-expo-copilot/skills/playwright-selectors/SKILL.md

@@ -394,6 +394,31 @@ Components from third-party libraries (e.g., `react-native-bouncy-checkbox`, `re
 
 ---
 
+## Reveal-on-Focus Assertions
+
+`toBeVisible()` proves the element exists and is not hidden — it does NOT
+prove the element crossed onto the screen. A focused element scrolled off-view
+still reports visible. For any "focus reveals the element" behavior (skip
+links, focus-trapped modals, scroll-into-view containers), assert on layout,
+not just visibility:
+
+```typescript
+// Rejects when the element has no box at all (display: none, detached).
+const box = await page.getByTestId("dialog:panel").boundingBox();
+expect(box).not.toBeNull();
+
+// Then prove it is actually inside the viewport — the part toBeVisible()
+// cannot say.
+await expect(page.getByTestId("dialog:panel")).toBeInViewport();
+```
+
+Pair them: `boundingBox()` answers "is there a box" (null means never laid
+out), `toBeInViewport()` answers "did it cross onto the screen". An assertion
+that skips the null check reads a missing layout as a viewport miss, which is
+a different bug.
+
+---
+
 ## Implementation Checklist
 
 When adding E2E test coverage to a component:

package/plugins/lisa-expo-copilot/skills/testing-library/references/mocking-patterns.md

@@ -588,3 +588,25 @@ afterAll(() => {
   console.error = originalError;
 });
 ```
+
+## Migrating jest.mock Usage
+
+When moving a test file onto the managed setup, scope the migration to the
+file under your hand — a suite-wide mock sweep is where subtle behavior
+changes hide.
+
+- **Prefer renderer-compatible mocks.** A mock that works in the Node
+  environment but reads `window`, native modules, or ESM-only entry points
+  fails under the jsdom/renderer the Expo preset provides. Mock the seam your
+  component actually imports (`jest.mock("nativewind", ...)`,
+  `jest.mock("@/lib/env", ...)`) — never reach around it to mock a transitive
+  dependency.
+- **Keep factories stable and hoisted.** Jest hoists `jest.mock` calls above
+  imports, so a factory cannot close over outer variables. Everything the
+  factory needs must come from `jest.requireActual`, `jest.requireMock`, or a
+  `mock`-prefixed name. A factory that silently returns a different shape per
+  run is the migration failure that surfaces as unrelated flakes.
+- **Check version compatibility, not history.** A pinned workaround for an
+  old jest-expo/Expo SDK issue is not a permanent blocker — verify whether the
+  current versions still need it before carrying it forward. Historical Expo
+  issues expire; copy them forward only when they reproduce.

package/plugins/lisa-expo-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo-cursor/skills/expo-router-best-practices/SKILL.md

@@ -426,6 +426,7 @@ const { width } = useWindowDimensions();
 For detailed documentation on specific topics, refer to:
 
 - `references/official-docs.md` - Condensed official Expo Router documentation
+- `references/static-export-verification.md` - Asserting enumerated routes, per-route titles, and initial HTML after `expo export`
 - `scripts/generate-route.py` - Route scaffolding script
 
 Official Documentation: https://docs.expo.dev/router/introduction/

package/plugins/lisa-expo-cursor/skills/expo-router-best-practices/references/static-export-verification.md

@@ -0,0 +1,54 @@
+# Static Export Verification
+
+When `expo export` runs with static output (`output: "static"` in app.json),
+every route must produce an HTML file with the right title and the expected
+initial markup. `expo export` succeeding only proves the bundle built — a
+missing route, a wrong title, or an empty shell all ship green unless the
+exported output itself is checked.
+
+## Enumerate the dynamic routes
+
+Static export prerenders each route it can enumerate. Dynamic segments need
+`generateStaticParams` — an unenumerated `[id]` route produces no page at all.
+After export, enumerate the routes the app *declares* and assert each one has
+a file under `dist/`:
+
+```typescript
+import { existsSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+const DIST = path.resolve("dist");
+
+// The routes the app owns — keep this in sync with app/, or derive it from
+// the route manifest expo-router emits.
+const EXPECTED_ROUTES = ["index", "settings", "players/[id]"];
+
+for (const route of EXPECTED_ROUTES) {
+  const html = path.join(DIST, `${route}.html`);
+  expect(existsSync(html)).toBe(true);
+}
+```
+
+## Per-route titles
+
+`<Stack.Screen options={{ title: "..." }}>` sets the native header title; the
+web `<title>` comes from `Head` (`expo-router/head`). Assert the title the
+exported HTML actually carries:
+
+```typescript
+const html = readFileSync(path.join(DIST, "settings.html"), "utf8");
+expect(html).toMatch(/<title>[^<]*Settings[^<]*<\/title>/);
+```
+
+## Expected initial content
+
+The exported page should ship its prerendered content, not a bare shell —
+that is what makes static export worth shipping at all. Assert a stable marker
+of the route's expected first paint:
+
+```typescript
+expect(html).toContain("Sign in to continue");
+```
+
+Keep the marker to content that exists in the static HTML, never something
+hydration adds later.

package/plugins/lisa-expo-cursor/skills/expo-tailwind-setup/SKILL.md

@@ -478,3 +478,10 @@ Add className to component props:
 ```tsx
 type Props = React.ComponentProps<typeof RNView> & { className?: string };
 ```
+
+The same rule applies at every styling API boundary — `useCssElement`,
+`cssInterop`, or `styled()`: type the wrapped component's props explicitly
+(`React.ComponentProps<typeof X> & { className?: string }`) and pass props
+through, rather than casting to a wider type. A cast compiles over a
+prop-shape drift that an explicit type would refuse — the boundary is where
+the drift is cheapest to catch.

package/plugins/lisa-expo-cursor/skills/playwright-selectors/SKILL.md

@@ -394,6 +394,31 @@ Components from third-party libraries (e.g., `react-native-bouncy-checkbox`, `re
 
 ---
 
+## Reveal-on-Focus Assertions
+
+`toBeVisible()` proves the element exists and is not hidden — it does NOT
+prove the element crossed onto the screen. A focused element scrolled off-view
+still reports visible. For any "focus reveals the element" behavior (skip
+links, focus-trapped modals, scroll-into-view containers), assert on layout,
+not just visibility:
+
+```typescript
+// Rejects when the element has no box at all (display: none, detached).
+const box = await page.getByTestId("dialog:panel").boundingBox();
+expect(box).not.toBeNull();
+
+// Then prove it is actually inside the viewport — the part toBeVisible()
+// cannot say.
+await expect(page.getByTestId("dialog:panel")).toBeInViewport();
+```
+
+Pair them: `boundingBox()` answers "is there a box" (null means never laid
+out), `toBeInViewport()` answers "did it cross onto the screen". An assertion
+that skips the null check reads a missing layout as a viewport miss, which is
+a different bug.
+
+---
+
 ## Implementation Checklist
 
 When adding E2E test coverage to a component:

package/plugins/lisa-expo-cursor/skills/testing-library/references/mocking-patterns.md

@@ -588,3 +588,25 @@ afterAll(() => {
   console.error = originalError;
 });
 ```
+
+## Migrating jest.mock Usage
+
+When moving a test file onto the managed setup, scope the migration to the
+file under your hand — a suite-wide mock sweep is where subtle behavior
+changes hide.
+
+- **Prefer renderer-compatible mocks.** A mock that works in the Node
+  environment but reads `window`, native modules, or ESM-only entry points
+  fails under the jsdom/renderer the Expo preset provides. Mock the seam your
+  component actually imports (`jest.mock("nativewind", ...)`,
+  `jest.mock("@/lib/env", ...)`) — never reach around it to mock a transitive
+  dependency.
+- **Keep factories stable and hoisted.** Jest hoists `jest.mock` calls above
+  imports, so a factory cannot close over outer variables. Everything the
+  factory needs must come from `jest.requireActual`, `jest.requireMock`, or a
+  `mock`-prefixed name. A factory that silently returns a different shape per
+  run is the migration failure that surfaces as unrelated flakes.
+- **Check version compatibility, not history.** A pinned workaround for an
+  old jest-expo/Expo SDK issue is not a permanent blocker — verify whether the
+  current versions still need it before carrying it forward. Historical Expo
+  issues expire; copy them forward only when they reproduce.

package/plugins/lisa-harper-fabric/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Harper/Fabric-specific Lisa rules for TypeScript component apps.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "NestJS-specific skills and migration write-protection hooks.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Ruby on Rails-specific skills and hooks for RuboCop and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "TypeScript-specific hooks for formatting, linting, and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "Distributable LLM Wiki kernel — ingest, query, lint, and maintain a git-native markdown knowledge base across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.66.0",
+  "version": "4.66.1",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/src/expo/skills/expo-router-best-practices/SKILL.md

@@ -426,6 +426,7 @@ const { width } = useWindowDimensions();
 For detailed documentation on specific topics, refer to:
 
 - `references/official-docs.md` - Condensed official Expo Router documentation
+- `references/static-export-verification.md` - Asserting enumerated routes, per-route titles, and initial HTML after `expo export`
 - `scripts/generate-route.py` - Route scaffolding script
 
 Official Documentation: https://docs.expo.dev/router/introduction/

package/plugins/src/expo/skills/expo-router-best-practices/references/static-export-verification.md

@@ -0,0 +1,54 @@
+# Static Export Verification
+
+When `expo export` runs with static output (`output: "static"` in app.json),
+every route must produce an HTML file with the right title and the expected
+initial markup. `expo export` succeeding only proves the bundle built — a
+missing route, a wrong title, or an empty shell all ship green unless the
+exported output itself is checked.
+
+## Enumerate the dynamic routes
+
+Static export prerenders each route it can enumerate. Dynamic segments need
+`generateStaticParams` — an unenumerated `[id]` route produces no page at all.
+After export, enumerate the routes the app *declares* and assert each one has
+a file under `dist/`:
+
+```typescript
+import { existsSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+const DIST = path.resolve("dist");
+
+// The routes the app owns — keep this in sync with app/, or derive it from
+// the route manifest expo-router emits.
+const EXPECTED_ROUTES = ["index", "settings", "players/[id]"];
+
+for (const route of EXPECTED_ROUTES) {
+  const html = path.join(DIST, `${route}.html`);
+  expect(existsSync(html)).toBe(true);
+}
+```
+
+## Per-route titles
+
+`<Stack.Screen options={{ title: "..." }}>` sets the native header title; the
+web `<title>` comes from `Head` (`expo-router/head`). Assert the title the
+exported HTML actually carries:
+
+```typescript
+const html = readFileSync(path.join(DIST, "settings.html"), "utf8");
+expect(html).toMatch(/<title>[^<]*Settings[^<]*<\/title>/);
+```
+
+## Expected initial content
+
+The exported page should ship its prerendered content, not a bare shell —
+that is what makes static export worth shipping at all. Assert a stable marker
+of the route's expected first paint:
+
+```typescript
+expect(html).toContain("Sign in to continue");
+```
+
+Keep the marker to content that exists in the static HTML, never something
+hydration adds later.

package/plugins/src/expo/skills/expo-tailwind-setup/SKILL.md

@@ -478,3 +478,10 @@ Add className to component props:
 ```tsx
 type Props = React.ComponentProps<typeof RNView> & { className?: string };
 ```
+
+The same rule applies at every styling API boundary — `useCssElement`,
+`cssInterop`, or `styled()`: type the wrapped component's props explicitly
+(`React.ComponentProps<typeof X> & { className?: string }`) and pass props
+through, rather than casting to a wider type. A cast compiles over a
+prop-shape drift that an explicit type would refuse — the boundary is where
+the drift is cheapest to catch.

package/plugins/src/expo/skills/playwright-selectors/SKILL.md

@@ -394,6 +394,31 @@ Components from third-party libraries (e.g., `react-native-bouncy-checkbox`, `re
 
 ---
 
+## Reveal-on-Focus Assertions
+
+`toBeVisible()` proves the element exists and is not hidden — it does NOT
+prove the element crossed onto the screen. A focused element scrolled off-view
+still reports visible. For any "focus reveals the element" behavior (skip
+links, focus-trapped modals, scroll-into-view containers), assert on layout,
+not just visibility:
+
+```typescript
+// Rejects when the element has no box at all (display: none, detached).
+const box = await page.getByTestId("dialog:panel").boundingBox();
+expect(box).not.toBeNull();
+
+// Then prove it is actually inside the viewport — the part toBeVisible()
+// cannot say.
+await expect(page.getByTestId("dialog:panel")).toBeInViewport();
+```
+
+Pair them: `boundingBox()` answers "is there a box" (null means never laid
+out), `toBeInViewport()` answers "did it cross onto the screen". An assertion
+that skips the null check reads a missing layout as a viewport miss, which is
+a different bug.
+
+---
+
 ## Implementation Checklist
 
 When adding E2E test coverage to a component: