@testspectra/cli 1.0.70 → 1.1.0-rc.1

package/dist/utils/api-server.js

@@ -0,0 +1,179 @@
+import http from 'http';
+/** Port the self-hosted demo API server listens on (separate from the demo web app's 5173). */
+export const DEMO_API_PORT = 5200;
+// Self-hosted dummy REST data for the demo app's API sections — keeps the ApiInterception and
+// ApiSeeding suites fully offline/deterministic instead of depending on an external service
+// (jsonplaceholder.typicode.com) whose reachability and latency were themselves a source of
+// flakiness. Mocked requests never reach these handlers (CDP/proxy intercepts them first); they
+// back the genuine passthrough cases (real network call recording, seed/cleanup hooks).
+const API_POSTS = [
+    {
+        userId: 1,
+        id: 1,
+        title: 'TestSpectra demo post one',
+        body: 'Self-hosted demo data served by the built-in TestSpectra API server.',
+    },
+    {
+        userId: 1,
+        id: 2,
+        title: 'TestSpectra demo post two',
+        body: 'No external network required — deterministic for CI and offline runs.',
+    },
+    {
+        userId: 2,
+        id: 3,
+        title: 'TestSpectra demo post three',
+        body: 'Intercept it with Spectra.intercept() or let it pass through untouched.',
+    },
+    {
+        userId: 2,
+        id: 4,
+        title: 'TestSpectra demo post four',
+        body: 'Served independently of the demo web app so either can run without the other.',
+    },
+];
+const API_USERS = [
+    { id: 1, name: 'Ada Lovelace', username: 'ada', email: 'ada@testspectra.dev' },
+    { id: 2, name: 'Alan Turing', username: 'alan', email: 'alan@testspectra.dev' },
+    { id: 3, name: 'Grace Hopper', username: 'grace', email: 'grace@testspectra.dev' },
+];
+const API_TODOS = [{ userId: 1, id: 1, title: 'Verify the self-hosted demo API responds', completed: false }];
+/** Fixed demo credentials — this is a deterministic offline sandbox, not a real auth system. */
+const DEMO_ACCOUNT = { email: 'demo@testspectra.dev', password: 'demo-password' };
+/**
+ * Issued session tokens, in-memory only (reset on server restart) — backs both `/api/login`'s
+ * `Set-Cookie` (web, read via `Spectra.browser.setCookies()`) and its JSON `token` field
+ * (Android, read by the app's own deep-link-triggered login and stored via its own secure
+ * storage — see docs/v2/features/authentication-and-session-seeding.md). `/api/me` looks a
+ * caller's cookie *or* `Authorization: Bearer <token>` up in this same map.
+ */
+const issuedSessions = new Map();
+/**
+ * Standalone self-hosted REST API server for the demo apps, kept separate from `DemoServer` (the
+ * static web app) so the API can run independently and either server can be swapped for a real
+ * backend in a project. Mirrors the small subset of jsonplaceholder.typicode.com shapes the demo's
+ * API sections exercise.
+ */
+export class DemoApiServer {
+    server = null;
+    port;
+    constructor(port = DEMO_API_PORT) {
+        this.port = port;
+    }
+    async start() {
+        return new Promise((resolve, reject) => {
+            this.server = http.createServer((req, res) => {
+                this.handleApi(req, res, req.url ? req.url.split('?')[0] : '/');
+            });
+            this.server.on('error', (err) => {
+                if (err.code === 'EADDRINUSE') {
+                    // Port already in use (e.g. user already running the API server)
+                    resolve({ url: `http://localhost:${this.port}`, port: this.port });
+                }
+                else {
+                    reject(err);
+                }
+            });
+            this.server.listen(this.port, '0.0.0.0', () => {
+                const addr = this.server?.address();
+                const actualPort = typeof addr === 'object' && addr !== null ? addr.port : this.port;
+                resolve({ url: `http://localhost:${actualPort}`, port: actualPort });
+            });
+        });
+    }
+    handleApi(req, res, pathname) {
+        // The demo web app (port 5173) calls this server (port 5200) cross-origin. A wildcard origin
+        // can't be combined with credentialed requests (Access-Control-Allow-Credentials), which
+        // /api/me below needs to receive the session cookie seeded via Spectra.browser.setCookies() —
+        // reflect the actual request Origin instead so both credentialed and simple requests work.
+        res.setHeader('Access-Control-Allow-Origin', req.headers.origin || '*');
+        res.setHeader('Access-Control-Allow-Credentials', 'true');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', '*');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        const sendJson = (status, payload) => {
+            // no-store: the demo app fetches these without a cache-buster, so a cached body would be
+            // served for later, differently-mocked requests to the same URL instead of reaching the
+            // mock proxy.
+            res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
+            res.end(JSON.stringify(payload));
+        };
+        if (pathname === '/api/login' && req.method === 'POST') {
+            const chunks = [];
+            req.on('data', (chunk) => chunks.push(chunk));
+            req.on('end', () => {
+                let payload = {};
+                try {
+                    payload = JSON.parse(Buffer.concat(chunks).toString('utf-8') || '{}');
+                }
+                catch { }
+                if (payload.email !== DEMO_ACCOUNT.email || payload.password !== DEMO_ACCOUNT.password) {
+                    sendJson(401, { error: 'Invalid credentials' });
+                    return;
+                }
+                const token = `demo-session-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+                issuedSessions.set(token, { email: DEMO_ACCOUNT.email });
+                // HttpOnly: JS on the page can't read this — only the browser's own network layer (and
+                // Spectra.browser.setCookies(), which operates at that same layer) can set/send it.
+                res.setHeader('Set-Cookie', `demo_session=${token}; Path=/; HttpOnly; SameSite=Lax`);
+                sendJson(200, { token, user: { email: DEMO_ACCOUNT.email } });
+            });
+            return;
+        }
+        if (pathname === '/api/me' && req.method === 'GET') {
+            const cookieHeader = req.headers.cookie || '';
+            const cookieToken = /(?:^|;\s*)demo_session=([^;]+)/.exec(cookieHeader)?.[1];
+            const bearerToken = /^Bearer\s+(.+)$/.exec(req.headers.authorization || '')?.[1];
+            const session = issuedSessions.get(cookieToken || '') || issuedSessions.get(bearerToken || '');
+            sendJson(200, session ? { authenticated: true, user: session } : { authenticated: false });
+            return;
+        }
+        if (pathname === '/api/posts' && req.method === 'GET') {
+            sendJson(200, API_POSTS);
+            return;
+        }
+        if (pathname === '/api/users' && req.method === 'GET') {
+            sendJson(200, API_USERS);
+            return;
+        }
+        if (pathname === '/api/todos/1' && req.method === 'GET') {
+            sendJson(200, API_TODOS[0]);
+            return;
+        }
+        if (pathname === '/api/posts' && req.method === 'POST') {
+            const chunks = [];
+            req.on('data', (chunk) => chunks.push(chunk));
+            req.on('end', () => {
+                let payload = {};
+                try {
+                    payload = JSON.parse(Buffer.concat(chunks).toString('utf-8') || '{}');
+                }
+                catch { }
+                sendJson(201, { ...payload, id: Date.now() });
+            });
+            return;
+        }
+        if (pathname.startsWith('/api/posts/') && req.method === 'DELETE') {
+            sendJson(200, {});
+            return;
+        }
+        sendJson(404, { error: 'Not Found' });
+    }
+    async stop() {
+        if (this.server) {
+            if (typeof this.server.closeAllConnections === 'function') {
+                this.server.closeAllConnections();
+            }
+            return new Promise((resolve) => {
+                this.server?.close(() => {
+                    this.server = null;
+                    resolve();
+                });
+            });
+        }
+    }
+}

package/dist/utils/demo-server.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Static file server for the demo web app bundle. Serves ONLY the web app — the self-hosted demo
+ * REST API lives in a separate `DemoApiServer` (`cli/src/utils/api-server.ts`, port 5200) so the
+ * two can run and be swapped independently.
+ */
 export declare class DemoServer {
     private server;
     private port;

package/dist/utils/demo-server.js

@@ -1,21 +1,26 @@
-import http from "http";
-import fs from "fs";
-import path from "path";
-import { fileURLToPath } from "url";
+import http from 'http';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
 const MIME_TYPES = {
-    ".html": "text/html",
-    ".js": "application/javascript",
-    ".css": "text/css",
-    ".json": "application/json",
-    ".png": "image/png",
-    ".jpg": "image/jpeg",
-    ".gif": "image/gif",
-    ".svg": "image/svg+xml",
-    ".ico": "image/x-icon",
-    ".woff": "font/woff",
-    ".woff2": "font/woff2",
-    ".ttf": "font/ttf",
+    '.html': 'text/html',
+    '.js': 'application/javascript',
+    '.css': 'text/css',
+    '.json': 'application/json',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
 };
+/**
+ * Static file server for the demo web app bundle. Serves ONLY the web app — the self-hosted demo
+ * REST API lives in a separate `DemoApiServer` (`cli/src/utils/api-server.ts`, port 5200) so the
+ * two can run and be swapped independently.
+ */
 export class DemoServer {
     server = null;
     port;
@@ -26,14 +31,14 @@ export class DemoServer {
         const __filename = fileURLToPath(import.meta.url);
         const __dirname = path.dirname(__filename);
         const candidates = [
-            path.resolve(__dirname, "../../demo-app"),
-            path.resolve(__dirname, "../demo-app"),
-            path.resolve(__dirname, "../../../demo-app"),
-            path.resolve(__dirname, "../../../apps/demo-web-app/dist"),
-            path.resolve(__dirname, "../../../../apps/demo-web-app/dist"),
+            path.resolve(__dirname, '../../demo-app'),
+            path.resolve(__dirname, '../demo-app'),
+            path.resolve(__dirname, '../../../demo-app'),
+            path.resolve(__dirname, '../../../apps/demo-web-app/dist'),
+            path.resolve(__dirname, '../../../../apps/demo-web-app/dist'),
         ];
         for (const cand of candidates) {
-            if (fs.existsSync(cand) && fs.existsSync(path.join(cand, "index.html"))) {
+            if (fs.existsSync(cand) && fs.existsSync(path.join(cand, 'index.html'))) {
                 return cand;
             }
         }
@@ -46,32 +51,32 @@ export class DemoServer {
         }
         return new Promise((resolve, reject) => {
             this.server = http.createServer((req, res) => {
-                const reqUrl = req.url ? req.url.split("?")[0] : "/";
-                let safePath = path.normalize(reqUrl).replace(/^(\.\.[\/\\])+/, "");
-                if (safePath === "/" || safePath === "\\")
-                    safePath = "/index.html";
+                const reqUrl = req.url ? req.url.split('?')[0] : '/';
+                let safePath = path.normalize(reqUrl).replace(/^(\.\.[/\\])+/, '');
+                if (safePath === '/' || safePath === '\\')
+                    safePath = '/index.html';
                 let filePath = path.join(demoDir, safePath);
                 // Fallback to index.html for SPA routes
                 if (!fs.existsSync(filePath) || fs.statSync(filePath).isDirectory()) {
-                    filePath = path.join(demoDir, "index.html");
+                    filePath = path.join(demoDir, 'index.html');
                 }
                 const ext = path.extname(filePath).toLowerCase();
-                const contentType = MIME_TYPES[ext] || "application/octet-stream";
+                const contentType = MIME_TYPES[ext] || 'application/octet-stream';
                 try {
                     const content = fs.readFileSync(filePath);
                     res.writeHead(200, {
-                        "Content-Type": contentType,
-                        "Access-Control-Allow-Origin": "*",
+                        'Content-Type': contentType,
+                        'Access-Control-Allow-Origin': '*',
                     });
                     res.end(content);
                 }
                 catch {
-                    res.writeHead(404, { "Content-Type": "text/plain" });
-                    res.end("Not Found");
+                    res.writeHead(404, { 'Content-Type': 'text/plain' });
+                    res.end('Not Found');
                 }
             });
-            this.server.on("error", (err) => {
-                if (err.code === "EADDRINUSE") {
+            this.server.on('error', (err) => {
+                if (err.code === 'EADDRINUSE') {
                     // Port already in use (e.g. user already running server)
                     resolve({ url: `http://localhost:${this.port}`, port: this.port });
                 }
@@ -79,13 +84,18 @@ export class DemoServer {
                     reject(err);
                 }
             });
-            this.server.listen(this.port, "0.0.0.0", () => {
-                resolve({ url: `http://localhost:${this.port}`, port: this.port });
+            this.server.listen(this.port, '0.0.0.0', () => {
+                const addr = this.server?.address();
+                const actualPort = typeof addr === 'object' && addr !== null ? addr.port : this.port;
+                resolve({ url: `http://localhost:${actualPort}`, port: actualPort });
             });
         });
     }
     async stop() {
         if (this.server) {
+            if (typeof this.server.closeAllConnections === 'function') {
+                this.server.closeAllConnections();
+            }
             return new Promise((resolve) => {
                 this.server?.close(() => {
                     this.server = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/cli",
-  "version": "1.0.70",
+  "version": "1.1.0-rc.1",
   "description": "TestSpectra Zero-Config Cross-Platform Test Runner CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,8 +17,12 @@
     "testspectra": "./bin/spectra.js"
   },
   "scripts": {
+    "build:rust": "node scripts/ensure-runner-binary.js",
+    "prebuild": "node scripts/ensure-runner-binary.js",
     "build": "tsc && node scripts/copy-demo.js",
     "watch": "tsc -w",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "files": [
@@ -26,22 +30,30 @@
     "bin",
     "templates",
     "demo-app",
-    "README.md"
+    "README.md",
+    "LICENSE.md"
   ],
   "dependencies": {
-    "@clack/prompts": "^1.7.0",
-    "@testspectra/matchers": "^1.0.70",
-    "chalk": "^5.3.0",
-    "commander": "^12.1.0",
-    "dotenv": "^16.4.5",
-    "ora": "^8.0.1",
-    "zod": "^3.23.8"
+    "@clack/prompts": "catalog:",
+    "@testspectra/matchers": "^1.1.0-rc.1",
+    "@testspectra/react": "workspace:*",
+    "@testspectra/skills": "^1.1.0-rc.1",
+    "chalk": "catalog:",
+    "commander": "catalog:",
+    "dotenv": "catalog:",
+    "ora": "catalog:",
+    "typescript": "catalog:",
+    "yaml": "catalog:",
+    "zod": "catalog:"
   },
   "devDependencies": {
-    "@types/node": "^20.14.0",
-    "esbuild": "^0.28.2",
-    "typescript": "^5.4.5"
+    "@types/node": "catalog:",
+    "@wdio/globals": "catalog:",
+    "@wdio/mocha-framework": "catalog:",
+    "@wdio/types": "catalog:",
+    "esbuild": "catalog:",
+    "vitest": "catalog:"
   },
   "type": "module",
-  "license": "MIT"
+  "license": "SEE LICENSE IN LICENSE.md"
 }

package/templates/default/CLAUDE.md

@@ -1,9 +1,16 @@
 # CLAUDE.md - TestSpectra Framework Conventions
 
 ## Commands
-- Run all Web tests: `pnpm spectra run -t web`
-- Run specific spec: `pnpm spectra run "specs/Playground/TC-0001-form-controls/web.test.ts" -t web`
-- Run Mobile tests: `pnpm spectra run --target android` or `pnpm spectra run --target ios`
+- Run all Web tests: `pnpm test:web` (or `spectra run -t web`)
+- Run all Mobile tests: `pnpm test:mobile` (or `spectra run -t mobile`)
+- Run Android tests: `pnpm test:android` (or `spectra run -t android`)
+- Run iOS tests: `pnpm test:ios` (or `spectra run -t ios`)
+- Run specific spec: `spectra run "specs/Playground/TC-0001-form-controls/mobile.test.ts" -t mobile`
 - Type checking: `pnpm type-check` (or `tsc -b`)
-- Preflight doctor: `pnpm spectra doctor`
-- List devices: `pnpm spectra devices`
+- Preflight doctor: `pnpm doctor` (or `spectra doctor`)
+- Sync ambient types: `pnpm sync-types`
+
+## Element Selectors
+- `~name` → **accessibility id** (Android `content-desc`, RN `accessibilityLabel`, web `aria-label`) — the portable default.
+- `#name` → **native id** (Android `resource-id`, RN `testID`, web CSS `id`).
+- Each prefix maps to exactly one attribute (no silent cross-matching). Prefer `~` for user-perceivable elements, `#` for stable test ids. See `docs/v2/cli/selectors.md`.

package/templates/default/fixtures/apiData.json

@@ -0,0 +1,24 @@
+{
+  "mockPosts": [
+    {
+      "id": 1,
+      "title": "Mocked Post 1 - TestSpectra Matchers",
+      "body": "First mocked post body for verifying GET API interception in TestSpectra."
+    },
+    {
+      "id": 2,
+      "title": "Mocked Post 2 - Cross-Platform Automation",
+      "body": "Second mocked post body for verifying collection and item assertions."
+    }
+  ],
+  "mockNewPost": {
+    "title": "TestSpectra Automated Post",
+    "body": "End-to-End API mock verification with browser.intercept command."
+  },
+  "mockPostResponse": {
+    "id": 101,
+    "title": "TestSpectra Automated Post",
+    "body": "End-to-End API mock verification with browser.intercept command.",
+    "userId": 1
+  }
+}

package/templates/default/package.json

@@ -5,11 +5,20 @@
   "type": "module",
   "scripts": {
     "test": "spectra run",
-    "type-check": "tsc -b"
+    "test:web": "spectra run -t web",
+    "test:mobile": "spectra run -t mobile",
+    "test:android": "spectra run -t android",
+    "test:ios": "spectra run -t ios",
+    "spectra": "spectra",
+    "doctor": "spectra doctor",
+    "watch": "spectra watch",
+    "type-check": "tsc -b",
+    "sync-types": "spectra sync-types",
+    "postinstall": "spectra sync-types"
   },
   "devDependencies": {
-    "@testspectra/cli": "^1.0.70",
-    "@testspectra/matchers": "^1.0.70",
+    "@testspectra/cli": "^1.1.0-rc.1",
+    "@testspectra/matchers": "^1.1.0-rc.1",
     "@types/node": "^20.14.0",
     "@wdio/cli": "^9.2.8",
     "@wdio/local-runner": "^9.2.8",

package/templates/default/page-objects/AuthPage/mobile.ts

@@ -0,0 +1,5 @@
+class AuthPage {
+  get statusBadge() { return Spectra.get("~auth-status-badge"); }
+}
+
+export default new AuthPage();

package/templates/default/page-objects/AuthPage/web.ts

@@ -0,0 +1,10 @@
+class AuthPage {
+  get checkStatusButton() { return Spectra.get("#check-auth-status-btn"); }
+  get statusBadge() { return Spectra.get("#auth-status-badge"); }
+
+  async open() {
+    await Spectra.navigate("/#auth");
+  }
+}
+
+export default new AuthPage();

package/templates/default/page-objects/MatchersPage/mobile.ts

@@ -1,21 +1,70 @@
-export class MatchersPage {
-  get visibleElement() { return Spectra.get("~visible_element"); }
-  get hiddenElement() { return Spectra.get("~hidden_element"); }
-  get existingElement() { return Spectra.get("~existing_element"); }
-  get submitButton() { return Spectra.get("~submit_button"); }
-  get disabledButton() { return Spectra.get("~disabled_button"); }
-  get checkbox() { return Spectra.get("~checkbox"); }
-  get radio() { return Spectra.get("~radio"); }
-  get emailInput() { return Spectra.get("~email_input"); }
-  get tokenInput() { return Spectra.get("~token_input"); }
-  get exactText() { return Spectra.get("~exact_text"); }
-  get partialText() { return Spectra.get("~partial_text"); }
-  get activeTab() { return Spectra.get("~active_tab"); }
-  get navLink() { return Spectra.get("~nav_link"); }
-  get productCards() { return Spectra.getAll("~product_card"); }
-  get emptyList() { return Spectra.getAll("~empty_list"); }
+class MatchersPage {
+  get visibleElement() { return Spectra.get("~visible-element"); }
+  get hiddenElement() { return Spectra.get("~hidden-element"); }
+  get existingElement() { return Spectra.get("~existing-element"); }
+  get removableElement() { return Spectra.get("~removable-element"); }
+  get submitButton() { return Spectra.get("~submit-button"); }
+  get disabledButton() { return Spectra.get("~disabled-button"); }
+  get checkbox() { return Spectra.get("~terms-checkbox"); }
+  get radio() { return Spectra.get("~mode-radio"); }
+  get emailInput() { return Spectra.get("~email-input"); }
+  get tokenInput() { return Spectra.get("~token-input"); }
+  get exactText() { return Spectra.get("~exact-text"); }
+  get partialText() { return Spectra.get("~partial-text"); }
+  // `#` = native id (RN testID → resource-id). Its accessibility label deliberately reads
+  // "active-tab is-active" (RN exposes no CSS classes, so the class is carried in the a11y label
+  // for `shouldHaveClass`), so it isn't addressable by the a11y-id form `~active-tab`.
+  get activeTab() { return Spectra.get("#active-tab"); }
+  get navLink() { return Spectra.get("~nav-link"); }
+  get styledElement() { return Spectra.get("~styled-element"); }
+  get focusInput() { return Spectra.get("~focus-input"); }
+  get productCards() { return Spectra.getAll("~product-item-1, ~product-item-2, ~product-item-3, ~product-item-4"); }
+  get emptyList() { return Spectra.getAll("~empty-list-item"); }
+  get overviewSection() { return Spectra.get("#overview-section"); }
+  // Scoped lookups via element.get() — resolved within overview-section's own bounds (Android
+  // has no ancestor API, so this is a bounds-containment lookup), not screen-wide.
+  overviewSubtitle() { return this.overviewSection.get("#demo-page-subtitle"); }
+  overviewOutsideElement() { return this.overviewSection.get("~submit-button"); }
 
-  async open(_section = "") {}
+  // API Demo elements
+  get fetchApiButton() { return Spectra.get("~fetch-api-btn"); }
+  get fetchStatusBadge() { return Spectra.get("~fetch-status-badge"); }
+  get fetchedItems() { return Spectra.getAll("~api-post-item"); }
+  get fetchLoadingIndicator() { return Spectra.get("~fetch-loading-indicator"); }
+  get fetchCustomUrlInput() { return Spectra.get("~fetch-custom-url"); }
+  get postTitleInput() { return Spectra.get("~post-title-input"); }
+  get postBodyInput() { return Spectra.get("~post-body-input"); }
+  get submitPostButton() { return Spectra.get("~submit-post-btn"); }
+  get postStatusBadge() { return Spectra.get("~post-status-badge"); }
+  get postSuccessBanner() { return Spectra.get("~post-success-banner"); }
+  get postResponseJson() { return Spectra.get("~post-response-json"); }
+
+  async open(section = "") {
+    try {
+      // A fresh app process (relaunched by the orchestrator's bootstrap before every suite) has to
+      // fetch, parse, and execute the RN JS bundle from Metro before anything is on screen — on a
+      // cold start this can take well past a normal action's poll budget. Wait for the home screen
+      // itself first so that timing doesn't silently swallow the sidebar click below and leave the
+      // real failure to surface confusingly on whatever element the test touches next.
+      await Spectra.get("~toggle-sidebar-btn").waitForElement(30000);
+
+      const isDrawerOpen = await Spectra.get("~close-sidebar-btn").isDisplayed().catch(() => false);
+      if (!isDrawerOpen) {
+        await Spectra.get("~toggle-sidebar-btn").click();
+        // The mobile drawer is a React Native `<Modal>` — a separate OS-level window with its own
+        // slide-in animation, not a plain re-rendered View — so its content (including every
+        // nav-item below) isn't in the accessibility tree at all until Android actually finishes
+        // creating that window, which is async and occasionally slow under load. Without this
+        // wait, clicking a nav item right after the toggle relies entirely on click()'s own
+        // poll-retry to bridge that gap, which can eat most of the ~10s implicit-wait budget when
+        // the Modal is slow to materialize.
+        await Spectra.get("~close-sidebar-btn").waitForElement(10000);
+      }
+      if (section) {
+        await Spectra.get(`~nav-item-${section}`).click();
+      }
+    } catch {}
+  }
 }
 
 export default new MatchersPage();

package/templates/default/page-objects/MatchersPage/web.ts

@@ -1,4 +1,4 @@
-export class MatchersPage {
+class MatchersPage {
   get visibleElement() { return Spectra.get("#demo-visible-el"); }
   get hiddenElement() { return Spectra.get("#demo-hidden-el"); }
   get existingElement() { return Spectra.get("#demo-existing-el"); }
@@ -12,11 +12,31 @@ export class MatchersPage {
   get partialText() { return Spectra.get("#demo-partial-text"); }
   get activeTab() { return Spectra.get("#demo-active-tab"); }
   get navLink() { return Spectra.get("#demo-nav-link"); }
+  get styledElement() { return Spectra.get("#demo-styled-el"); }
+  get focusInput() { return Spectra.get("#demo-focus-input"); }
   get productCards() { return Spectra.getAll(".demo-product-card"); }
   get emptyList() { return Spectra.getAll("#demo-empty-list > *"); }
+  get overviewSection() { return Spectra.get("#overview"); }
+  // Scoped lookups via element.get() — resolved within overview-section's own subtree, not
+  // document-wide.
+  overviewSubtitle() { return this.overviewSection.get("#demo-page-subtitle"); }
+  overviewOutsideElement() { return this.overviewSection.get("#demo-submit-btn"); }
+
+  // API Interception & Mocking elements
+  get fetchApiButton() { return Spectra.get("#fetch-api-btn"); }
+  get fetchStatusBadge() { return Spectra.get("#fetch-status-badge"); }
+  get fetchedItems() { return Spectra.getAll(".api-fetched-item"); }
+  get fetchLoadingIndicator() { return Spectra.get("#fetch-loading-indicator"); }
+  get fetchCustomUrlInput() { return Spectra.get("#fetch-custom-url-input"); }
+  get postTitleInput() { return Spectra.get("#post-input-title"); }
+  get postBodyInput() { return Spectra.get("#post-input-body"); }
+  get submitPostButton() { return Spectra.get("#submit-post-btn"); }
+  get postStatusBadge() { return Spectra.get("#post-status-badge"); }
+  get postSuccessBanner() { return Spectra.get("#post-success-banner"); }
+  get postResponseJson() { return Spectra.get("#post-response-json"); }
 
   async open(section = "") {
-    await browser.url("/" + (section ? "#" + section : ""));
+    await Spectra.navigate("/" + (section ? "#" + section : ""));
   }
 }
 

package/templates/default/page-objects/NavigationPage/mobile.ts

@@ -1,5 +1,14 @@
-export class NavigationPage {
-  get sidebarLinks() { return Spectra.getAll("~sidebar_link"); }
+class NavigationPage {
+  get sidebarLinks() {
+    return Spectra.getAll(
+      "~nav-item-overview, ~nav-item-element-matchers, ~nav-item-visibility, ~nav-item-existence, ~nav-item-state, ~nav-item-value, ~nav-item-text, ~nav-item-class-attr, ~nav-item-browser-matchers, ~nav-item-url, ~nav-item-title, ~nav-item-collection-matchers, ~nav-item-length, ~nav-item-api-matchers, ~nav-item-api-fetch, ~nav-item-api-post, ~nav-item-playground"
+    );
+  }
+  get toggleSidebarButton() { return Spectra.get("~toggle-sidebar-btn"); }
+  get closeSidebarButton() { return Spectra.get("~close-sidebar-btn"); }
+  get overviewLink() { return Spectra.get("~nav-item-overview"); }
+  get visibilityLink() { return Spectra.get("~nav-item-visibility"); }
+  get playgroundLink() { return Spectra.get("~nav-item-playground"); }
 }
 
 export default new NavigationPage();

package/templates/default/page-objects/NavigationPage/web.ts

@@ -1,4 +1,4 @@
-export class NavigationPage {
+class NavigationPage {
   get sidebarLinks() { return Spectra.getAll("aside a"); }
   get overviewLink() { return Spectra.get("aside a[href='#overview']"); }
   get visibilityLink() { return Spectra.get("aside a[href='#visibility']"); }