@testspectra/cli 1.1.14 → 1.2.1

package/dist/commands/run.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { ConfigLoader } from '../config/loader.js';
+import { resolvePluginSpecifiers } from '../plugins/resolver.js';
 import { RustCoreBridge } from '../runner/bridge.js';
 import { Reporter } from '../runner/reporter.js';
 import { TypeGenerator } from '../types/generator.js';
@@ -137,6 +138,7 @@ export async function runCommand(specPaths, options = {}) {
     // Ensure latest ambient types are up-to-date
     TypeGenerator.writeDeclarationFiles(cwd);
     await TypeGenerator.syncEnvDeclaration(cwd);
+    await TypeGenerator.syncPluginDeclarations(cwd);
     const home = process.env.HOME || process.env.USERPROFILE || '';
     const globalAppDataPath = path.join(home, '.testspectra');
     const appDataPath = options.workdir ? path.resolve(options.workdir) : globalAppDataPath;
@@ -168,6 +170,9 @@ export async function runCommand(specPaths, options = {}) {
         }
     }
     const config = await ConfigLoader.loadConfig(cwd);
+    if (config.executionConfig) {
+        config.executionConfig.plugins = resolvePluginSpecifiers(cwd, config.executionConfig.plugins);
+    }
     if (options.baseUrl) {
         config.webConfig.baseUrl = options.baseUrl;
     }

package/dist/commands/sync-types.js

@@ -6,6 +6,7 @@ export async function syncTypesCommand(options = {}) {
     try {
         TypeGenerator.generateAll(cwd);
         await TypeGenerator.syncEnvDeclaration(cwd);
+        await TypeGenerator.syncPluginDeclarations(cwd);
         console.log(chalk.green('✔ Successfully synchronized TestSpectra ambient type declarations in .testspectra/types/'));
     }
     catch (err) {

package/dist/commands/test.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import chalk from 'chalk';
 import * as p from '@clack/prompts';
 import { ConfigLoader } from '../config/loader.js';
+import { resolvePluginSpecifiers } from '../plugins/resolver.js';
 import { renderSummaryView } from '../reporter/summary-view.js';
 import { Reporter } from '../runner/reporter.js';
 import { RustCoreBridge } from '../runner/bridge.js';
@@ -94,6 +95,7 @@ export async function testCommand(options = {}) {
         headless = options.headless;
     }
     // Fallback to spectra.config.ts if options were not explicitly provided on CLI
+    let pluginSpecifiers = [];
     try {
         const config = await ConfigLoader.loadConfig(cwd);
         if (stepDelayMs === undefined && config?.webConfig?.stepDelay !== undefined) {
@@ -104,6 +106,7 @@ export async function testCommand(options = {}) {
         if (!options.headed && options.headless === undefined && config?.webConfig?.headless !== undefined) {
             headless = String(config.webConfig.headless) !== 'false' && Boolean(config.webConfig.headless);
         }
+        pluginSpecifiers = resolvePluginSpecifiers(cwd, config?.executionConfig?.plugins);
     }
     catch {
         /* ignore config load failures */
@@ -120,6 +123,7 @@ export async function testCommand(options = {}) {
     const bundleServer = await reactPkg.startBundleServer({
         testRoot: cwd,
         stepDelayMs: stepDelayMs ?? 0,
+        plugins: pluginSpecifiers,
     });
     let ok = false;
     try {

package/dist/commands/watch.js

@@ -11,6 +11,9 @@ export function startWatcher(cwd, debounceMs = 60) {
     TypeGenerator.syncEnvDeclaration(cwd).catch((err) => {
         console.error(chalk.red(`✖ Error generating initial env.d.ts: ${err?.message}`));
     });
+    TypeGenerator.syncPluginDeclarations(cwd).catch((err) => {
+        console.error(chalk.red(`✖ Error generating initial plugin declarations: ${err?.message}`));
+    });
     let debounceTimer = null;
     const triggerRegen = (filePath, eventType) => {
         if (debounceTimer)
@@ -19,6 +22,7 @@ export function startWatcher(cwd, debounceMs = 60) {
             try {
                 TypeGenerator.generateAll(cwd);
                 await TypeGenerator.syncEnvDeclaration(cwd);
+                await TypeGenerator.syncPluginDeclarations(cwd);
                 const time = new Date().toLocaleTimeString();
                 const rel = path.relative(cwd, filePath) || filePath;
                 console.log(chalk.gray(`[${time}] `) + chalk.cyan(`✨ Updated ambient types `) + chalk.gray(`(${eventType}: ${rel})`));

package/dist/config/loader.js

@@ -117,6 +117,10 @@ export class ConfigLoader {
                     loaded.executionConfig?.environmentVariables ??
                     DEFAULT_CONFIG_DATA.executionConfig?.environmentVariables ??
                     {},
+                plugins: overrides?.executionConfig?.plugins ??
+                    loaded.executionConfig?.plugins ??
+                    DEFAULT_CONFIG_DATA.executionConfig?.plugins ??
+                    [],
             },
         };
     }

package/dist/config/schema.d.ts

@@ -373,6 +373,16 @@ export interface ExecutionConfig {
      * (e.g. `{ API_SECRET_KEY: "..." }`).
      */
     environmentVariables?: Record<string, string>;
+    /**
+     * TestSpectra plugins to load before tests run. Each entry is a module specifier — a package
+     * name (e.g. `"@myorg/spectra-button-plugin"`) or a path relative to the project root — whose
+     * default export is a `SpectraPlugin` (`{ name, setup }`) or a bare `(spectra) => void` install
+     * function. Plugins extend the `Spectra` DSL via `Spectra.registerCommand()`.
+     *
+     * Consumer projects must also wire the plugin's ambient types themselves (via TypeScript module
+     * augmentation of `SpectraStatic`); the type generator does not discover external plugins.
+     */
+    plugins?: string[];
 }
 /**
  * Root configuration data structure matching TestSpectra project schema.

package/dist/generator/tsconfig-generator.js

@@ -50,6 +50,7 @@ export class TsConfigGenerator {
             },
             include: [
                 '../types/web.d.ts',
+                '../types/plugins/web.d.ts',
                 '../types/fixtures.d.ts',
                 '../../**/specs/**/*.ts',
                 '../../**/specs/**/*.tsx',
@@ -90,6 +91,7 @@ export class TsConfigGenerator {
             },
             include: [
                 '../types/mobile.d.ts',
+                '../types/plugins/mobile.d.ts',
                 '../types/fixtures.d.ts',
                 '../../**/specs/**/*.ts',
                 '../../**/specs/**/*.tsx',
@@ -130,6 +132,7 @@ export class TsConfigGenerator {
             },
             include: [
                 '../types/android.d.ts',
+                '../types/plugins/android.d.ts',
                 '../types/fixtures.d.ts',
                 '../../**/specs/**/*.ts',
                 '../../**/specs/**/*.tsx',
@@ -170,6 +173,7 @@ export class TsConfigGenerator {
             },
             include: [
                 '../types/ios.d.ts',
+                '../types/plugins/ios.d.ts',
                 '../types/fixtures.d.ts',
                 '../../**/specs/**/*.ts',
                 '../../**/specs/**/*.tsx',
@@ -210,6 +214,7 @@ export class TsConfigGenerator {
             },
             include: [
                 '../types/common.d.ts',
+                '../types/plugins/common.d.ts',
                 '../types/fixtures.d.ts',
                 '../../**/page-objects/**/common.ts',
                 '../../**/page-objects/**/common.tsx',
@@ -244,8 +249,21 @@ export class TsConfigGenerator {
         const relRuns = path.relative(subConfigDir, path.join(options.cwd, '.testspectra', 'runs')).replace(/\\/g, '/');
         const relCache = path.relative(subConfigDir, path.join(options.cwd, '.testspectra', 'cache')).replace(/\\/g, '/');
         const platformDts = `${relTypesDir}/${platform}.d.ts`;
+        // Plugin declarations are workspace-wide and live only at the root types dir
+        // (`.testspectra/types/plugins/<platform>.d.ts`), unlike scoped fixtures/platform files —
+        // so reference them relative to the root, not to this scope's own types dir.
+        const pluginDts = path
+            .relative(subConfigDir, path.join(options.cwd, '.testspectra', 'types', 'plugins', `${platform}.d.ts`))
+            .replace(/\\/g, '/');
         const fixturesDts = `${relTypesDir}/fixtures.d.ts`;
-        const include = [platformDts, fixturesDts, `${relScope}/**/*.ts`, `${relScope}/**/*.tsx`, relSpectraConfig];
+        const include = [
+            platformDts,
+            pluginDts,
+            fixturesDts,
+            `${relScope}/**/*.ts`,
+            `${relScope}/**/*.tsx`,
+            relSpectraConfig,
+        ];
         const baseExcludes = [relNodeModules, relDist, relReports, relRuns, relCache];
         const stemMap = {
             web: ['android', 'ios', 'mobile'],

package/dist/generator/type-generator.d.ts

@@ -38,6 +38,18 @@ export declare class TypeGenerator {
      * (which must stay synchronous) because reading the config file is unavoidably async.
      */
     static syncEnvDeclaration(cwd: string): Promise<void>;
+    /**
+     * Reloads `spectra.config.ts` and refreshes `.testspectra/types/plugins/<platform>.d.ts` with the
+     * platform-appropriate plugin type entries. Mirrors `syncEnvDeclaration` (async, config-driven):
+     * each configured plugin package exposes platform-stem subpath exports (`./web`, `./android`,
+     * `./ios`, `./mobile`, `./common`) containing `SpectraStatic` module augmentations, and this
+     * method emits, per platform, imports for the stems in that platform's hierarchy.
+     *
+     * A plugin with no platform-stem subpaths is treated as `common` (applies to every platform).
+     * These files are referenced from each generated `<platform>.d.ts` (see
+     * `generateDeclarationsForScope`); `writeDeclarationFiles` guarantees they exist first.
+     */
+    static syncPluginDeclarations(cwd: string): Promise<void>;
     /**
      * Discovers all feature directories and shared library directories.
      * Returns a map of scope -> base directory

package/dist/generator/type-generator.js

@@ -1,5 +1,6 @@
 import fs from 'fs';
 import path from 'path';
+import { createRequire } from 'node:module';
 import { ConfigLoader } from '../config/loader.js';
 import { TsConfigGenerator } from './tsconfig-generator.js';
 export const PLATFORM_HIERARCHY = {
@@ -194,6 +195,75 @@ export function isComponentTestingProject(cwd) {
         return false;
     }
 }
+/** Platform stems a plugin may expose as `exports` subpaths. */
+const PLUGIN_STEMS = ['web', 'android', 'ios', 'mobile', 'common'];
+/**
+ * Reads the platform stems a plugin package exposes as subpath exports (`./web`, `./android`,
+ * `./ios`, `./mobile`, `./common`). A plugin with no such subpaths returns `[]` and is treated as
+ * a root-only (`common`) plugin by the caller.
+ */
+function detectPluginStems(exportsField) {
+    if (!exportsField || typeof exportsField !== 'object')
+        return [];
+    const keys = Object.keys(exportsField);
+    return PLUGIN_STEMS.filter((stem) => keys.includes(`./${stem}`));
+}
+function walkUpToPackageJson(filePath) {
+    let dir = path.dirname(filePath);
+    while (dir !== path.dirname(dir)) {
+        const candidate = path.join(dir, 'package.json');
+        if (fs.existsSync(candidate))
+            return candidate;
+        dir = path.dirname(dir);
+    }
+    return null;
+}
+/**
+ * Resolves a plugin specifier to its `package.json` path, so the generator can read the package
+ * name and its platform-stem `exports`. Handles absolute/relative paths and bare package
+ * specifiers (via Node resolution, with a `node_modules/<spec>` fallback for ESM-only packages
+ * whose root export has no `require`/`default` condition).
+ */
+function resolvePluginPackageJson(cwd, specifier) {
+    if (path.isAbsolute(specifier) || specifier.startsWith('.')) {
+        const resolved = path.resolve(cwd, specifier);
+        if (fs.existsSync(resolved)) {
+            if (fs.statSync(resolved).isDirectory()) {
+                const pkg = path.join(resolved, 'package.json');
+                return fs.existsSync(pkg) ? pkg : null;
+            }
+            return walkUpToPackageJson(resolved);
+        }
+        return null;
+    }
+    try {
+        const req = createRequire(path.join(cwd, 'package.json'));
+        return walkUpToPackageJson(req.resolve(specifier));
+    }
+    catch {
+        const fallback = path.join(cwd, 'node_modules', specifier, 'package.json');
+        return fs.existsSync(fallback) ? fallback : null;
+    }
+}
+/**
+ * Resolves each configured plugin to its package name + available platform stems.
+ * Unresolvable plugins are skipped (the runtime loader reports them separately).
+ */
+function resolvePluginStems(cwd, plugins) {
+    const infos = [];
+    for (const specifier of plugins) {
+        const pkgPath = resolvePluginPackageJson(cwd, specifier);
+        if (!pkgPath)
+            continue;
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+            const name = typeof pkg.name === 'string' && pkg.name ? pkg.name : specifier;
+            infos.push({ name, stems: detectPluginStems(pkg.exports) });
+        }
+        catch { }
+    }
+    return infos;
+}
 export class TypeGenerator {
     /**
      * Main entry point to generate all ambient type declarations.
@@ -220,6 +290,49 @@ export class TypeGenerator {
         catch { }
         fs.writeFileSync(path.join(rootTypesDir, 'env.d.ts'), this.generateEnvDeclaration(environmentVariables), 'utf-8');
     }
+    /**
+     * Reloads `spectra.config.ts` and refreshes `.testspectra/types/plugins/<platform>.d.ts` with the
+     * platform-appropriate plugin type entries. Mirrors `syncEnvDeclaration` (async, config-driven):
+     * each configured plugin package exposes platform-stem subpath exports (`./web`, `./android`,
+     * `./ios`, `./mobile`, `./common`) containing `SpectraStatic` module augmentations, and this
+     * method emits, per platform, imports for the stems in that platform's hierarchy.
+     *
+     * A plugin with no platform-stem subpaths is treated as `common` (applies to every platform).
+     * These files are referenced from each generated `<platform>.d.ts` (see
+     * `generateDeclarationsForScope`); `writeDeclarationFiles` guarantees they exist first.
+     */
+    static async syncPluginDeclarations(cwd) {
+        const rootTypesDir = path.join(cwd, '.testspectra', 'types');
+        const pluginsDir = path.join(rootTypesDir, 'plugins');
+        fs.mkdirSync(pluginsDir, { recursive: true });
+        let plugins = [];
+        try {
+            const config = await ConfigLoader.loadConfig(cwd);
+            plugins = config.executionConfig?.plugins ?? [];
+        }
+        catch { }
+        const infos = resolvePluginStems(cwd, plugins);
+        const platforms = ['web', 'android', 'ios', 'mobile', 'common'];
+        for (const platform of platforms) {
+            const hierarchy = PLATFORM_HIERARCHY[platform];
+            const specifiers = new Set();
+            for (const info of infos) {
+                if (info.stems.length === 0) {
+                    // Root-only plugin: treated as `common`, so it applies to every platform.
+                    specifiers.add(info.name);
+                    continue;
+                }
+                for (const stem of hierarchy) {
+                    if (info.stems.includes(stem))
+                        specifiers.add(`${info.name}/${stem}`);
+                }
+            }
+            const content = specifiers.size > 0
+                ? `${[...specifiers].map((s) => `import '${s}';`).join('\n')}\n\nexport {};\n`
+                : `// No TestSpectra plugin augmentations for the ${platform} platform.\nexport {};\n`;
+            fs.writeFileSync(path.join(pluginsDir, `${platform}.d.ts`), content, 'utf-8');
+        }
+    }
     /**
      * Discovers all feature directories and shared library directories.
      * Returns a map of scope -> base directory
@@ -643,6 +756,19 @@ export class TypeGenerator {
         if (!fs.existsSync(envDtsPath)) {
             fs.writeFileSync(envDtsPath, this.generateEnvDeclaration({}), 'utf-8');
         }
+        // Plugin declaration files are filled in asynchronously by `syncPluginDeclarations` (reading
+        // `spectra.config.ts` is async), but the generated `<platform>.d.ts` files reference them via
+        // `/// <reference path>`. Guarantee they exist so a reference never points at a missing file.
+        const pluginsDir = path.join(rootTypesDir, 'plugins');
+        if (!fs.existsSync(pluginsDir)) {
+            fs.mkdirSync(pluginsDir, { recursive: true });
+        }
+        for (const platform of ['web', 'android', 'ios', 'mobile', 'common']) {
+            const pluginDts = path.join(pluginsDir, `${platform}.d.ts`);
+            if (!fs.existsSync(pluginDts)) {
+                fs.writeFileSync(pluginDts, `// No TestSpectra plugin augmentations for the ${platform} platform.\nexport {};\n`, 'utf-8');
+            }
+        }
         const scopes = this.getEntityScopes(cwd);
         const sharedScope = scopes.find((s) => s.isShared);
         const featureScopes = scopes.filter((s) => !s.isShared);

package/dist/plugins/resolver.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolves `executionConfig.plugins` module specifiers to absolute file paths so the worker
+ * runtime (Bun E2E worker or browser bundle server) can import them regardless of its own
+ * resolution root.
+ *
+ * - Absolute paths are passed through unchanged.
+ * - Relative paths are resolved against the project root.
+ * - Bare package specifiers are resolved through Node's resolver rooted at the project; if that
+ *   fails (e.g. an ESM-only package with no `require`/`default` export condition), the original
+ *   specifier is kept so the runtime can still attempt its own bare-specifier resolution.
+ */
+export declare function resolvePluginSpecifiers(cwd: string, plugins?: string[]): string[];

package/dist/plugins/resolver.js

@@ -0,0 +1,48 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+/**
+ * Resolves `executionConfig.plugins` module specifiers to absolute file paths so the worker
+ * runtime (Bun E2E worker or browser bundle server) can import them regardless of its own
+ * resolution root.
+ *
+ * - Absolute paths are passed through unchanged.
+ * - Relative paths are resolved against the project root.
+ * - Bare package specifiers are resolved through Node's resolver rooted at the project; if that
+ *   fails (e.g. an ESM-only package with no `require`/`default` export condition), the original
+ *   specifier is kept so the runtime can still attempt its own bare-specifier resolution.
+ */
+export function resolvePluginSpecifiers(cwd, plugins) {
+    if (!plugins || plugins.length === 0)
+        return [];
+    let projectRequire;
+    try {
+        projectRequire = createRequire(path.join(cwd, 'package.json'));
+    }
+    catch {
+        projectRequire = undefined;
+    }
+    const resolved = [];
+    for (const specifier of plugins) {
+        if (typeof specifier !== 'string' || specifier.length === 0)
+            continue;
+        if (path.isAbsolute(specifier)) {
+            resolved.push(specifier);
+            continue;
+        }
+        if (specifier.startsWith('.')) {
+            resolved.push(path.resolve(cwd, specifier));
+            continue;
+        }
+        let found;
+        if (projectRequire) {
+            try {
+                found = projectRequire.resolve(specifier);
+            }
+            catch {
+                found = undefined;
+            }
+        }
+        resolved.push(found ?? specifier);
+    }
+    return resolved;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/cli",
-  "version": "1.1.14",
+  "version": "1.2.1",
   "description": "TestSpectra Cross-Platform Test Runner CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,10 +25,10 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@testspectra/matchers": "^1.1.14",
-    "@testspectra/react": "^1.1.14",
-    "@testspectra/reporter": "^1.1.14",
-    "@testspectra/skills": "^1.1.14",
+    "@testspectra/matchers": "^1.2.1",
+    "@testspectra/react": "^1.2.1",
+    "@testspectra/reporter": "^1.2.1",
+    "@testspectra/skills": "^1.2.1",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "cross-spawn": "^7.0.6",
@@ -39,9 +39,9 @@
     "zod": "^3.23.8"
   },
   "optionalDependencies": {
-    "@testspectra/cli-darwin-arm64": "1.1.14",
-    "@testspectra/cli-linux-x64": "1.1.14",
-    "@testspectra/cli-win32-x64": "1.1.14"
+    "@testspectra/cli-darwin-arm64": "1.2.1",
+    "@testspectra/cli-linux-x64": "1.2.1",
+    "@testspectra/cli-win32-x64": "1.2.1"
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6",

package/templates/default/package.json

@@ -17,8 +17,9 @@
     "postinstall": "spectra sync-types"
   },
   "devDependencies": {
-    "@testspectra/cli": "^1.1.14",
-    "@testspectra/matchers": "^1.1.14",
+    "@testspectra/cli": "^1.2.1",
+    "@testspectra/matchers": "^1.2.1",
+    "@testspectra/plugin-demo": "^1.2.1",
     "@types/node": "^20.14.0",
     "@wdio/cli": "^9.2.8",
     "@wdio/local-runner": "^9.2.8",

package/templates/default/specs/ElementMatchers/TC-0004-states-and-attributes/mobile.test.ts

@@ -12,10 +12,17 @@ it("Verify button state, checkbox, radio and attributes", async () => {
   await MatchersPage.checkbox.shouldNotBeChecked();
   await MatchersPage.radio.shouldBeChecked();
 
-  // Focus states
+  // Focus & blur states (element API). On mobile `focus()` clicks the field and `blur()` is a
+  // no-op (native apps have no DOM focus concept), so we only assert the focused transition.
   await MatchersPage.focusInput.shouldNotBeFocused();
-  await MatchersPage.focusInput.click();
+  await MatchersPage.focusInput.focus();
   await MatchersPage.focusInput.shouldBeFocused();
+  await MatchersPage.focusInput.blur();
+
+  // Focus states (static Spectra API) mirror the element API on mobile.
+  await Spectra.focus(MatchersPage.focusInput);
+  await MatchersPage.focusInput.shouldBeFocused();
+  await Spectra.blur(MatchersPage.focusInput);
 
   // Class, Attribute, and CSS assertions
   await MatchersPage.activeTab.shouldHaveClass("is-active");

package/templates/default/specs/ElementMatchers/TC-0004-states-and-attributes/spec.md

@@ -17,3 +17,4 @@ coverage:
 3. Assert terms checkbox is not checked
 4. Assert active tab has is-active class
 5. Assert navigation link has correct href attribute
+6. Focus and blur the focus input and assert focus state transitions

package/templates/default/specs/ElementMatchers/TC-0004-states-and-attributes/web.test.ts

@@ -12,10 +12,18 @@ it("Verify button state, checkbox, radio and attributes", async () => {
   await MatchersPage.checkbox.shouldNotBeChecked();
   await MatchersPage.radio.shouldBeChecked();
 
-  // Focus states
+  // Focus & blur states (element API)
   await MatchersPage.focusInput.shouldNotBeFocused();
-  await MatchersPage.focusInput.click();
+  await MatchersPage.focusInput.focus();
   await MatchersPage.focusInput.shouldBeFocused();
+  await MatchersPage.focusInput.blur();
+  await MatchersPage.focusInput.shouldNotBeFocused();
+
+  // Focus & blur states (static Spectra API)
+  await Spectra.focus(MatchersPage.focusInput);
+  await MatchersPage.focusInput.shouldBeFocused();
+  await Spectra.blur(MatchersPage.focusInput);
+  await MatchersPage.focusInput.shouldNotBeFocused();
 
   // Class, Attribute, and CSS assertions
   await MatchersPage.activeTab.shouldHaveClass("is-active");

package/templates/default/specs/PluginDemo/TC-0001-plugin-commands/spec.md

@@ -0,0 +1,16 @@
+---
+id: TC-0001-plugin-commands
+title: Verify plugin-registered custom Spectra commands
+priority: Medium
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+---
+
+# Verify plugin-registered custom Spectra commands
+
+## Test Steps
+1. Navigate to the playground section
+2. Invoke the plugin-registered findButton command and assert its label
+3. Invoke the plugin-registered findComponent command and assert existence

package/templates/default/specs/PluginDemo/TC-0001-plugin-commands/web.test.ts

@@ -0,0 +1,15 @@
+it("Verify plugin-registered custom Spectra commands", async () => {
+  await Spectra.navigate("/#playground");
+
+  // Button-specific command registered by @testspectra/plugin-demo (common platform stem).
+  const enabledButton = Spectra.findButton("#demo-enabled-btn");
+  await enabledButton.shouldBeVisible();
+  await enabledButton.assertLabel("Enabled Button");
+  await enabledButton.press();
+
+  // Universal component command registered by the same plugin (common platform stem).
+  await Spectra.findComponent("#demo-email-input-pg").shouldExist();
+
+  // Web-only command registered by the plugin (web platform stem).
+  await Spectra.findByCss("#demo-email-input-pg").shouldExist();
+});

package/templates/default/specs/PluginDemo/suite.md

@@ -0,0 +1,9 @@
+---
+id: suite-plugin-demo
+name: PluginDemo
+description: Custom Spectra commands registered by an external TestSpectra plugin
+executionOrder: 1.5
+parallel: true
+---
+
+# Suite: PluginDemo

package/templates/default/spectra.config.ts

@@ -52,5 +52,7 @@ export default defineConfig({
     normalResponseTime: "1000",
     monitoredDomains: [],
     environmentVariables: { DEMO_API_MODE: "sandbox" },
+    // Demo plugin: registers Spectra.findComponent() / Spectra.findButton() commands.
+    plugins: ["@testspectra/plugin-demo"],
   },
 });

package/templates/nx/package.json

@@ -12,8 +12,8 @@
     "postinstall": "spectra sync-types"
   },
   "devDependencies": {
-    "@testspectra/cli": "^1.1.14",
-    "@testspectra/matchers": "^1.1.14",
+    "@testspectra/cli": "^1.2.1",
+    "@testspectra/matchers": "^1.2.1",
     "@types/node": "^20.14.0",
     "@wdio/cli": "^9.2.8",
     "@wdio/local-runner": "^9.2.8",
@@ -23,6 +23,7 @@
     "@wdio/mocha-framework": "^9.2.8",
     "nx": "^20.8.4",
     "typescript": "^5.4.5",
-    "webdriverio": "^9.2.8"
+    "webdriverio": "^9.2.8",
+    "@testspectra/plugin-demo": "^1.2.1"
   }
 }

package/templates/react-component/package.json

@@ -14,9 +14,9 @@
     "postinstall": "spectra sync-types"
   },
   "devDependencies": {
-    "@testspectra/cli": "^1.1.14",
-    "@testspectra/matchers": "^1.1.14",
-    "@testspectra/react": "^1.1.14",
+    "@testspectra/cli": "^1.2.1",
+    "@testspectra/matchers": "^1.2.1",
+    "@testspectra/react": "^1.2.1",
     "@types/node": "^20.14.0",
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",

package/templates/react-component/specs/ButtonComponent/TC-0006-button-bounds-and-parent/spec.md

@@ -0,0 +1,21 @@
+---
+id: TC-0006
+title: Verify button bounds and parent element access
+priority: Medium
+caseType: Positive
+status: automated
+coverage:
+  web: automated
+---
+
+# TC-0006: Button Bounds and Parent Access
+
+Verify that `Spectra.get()` exposes element bounds (position + size), can navigate up the DOM tree via `parent()`, and can locate an ancestor via `closest()`.
+
+## Test Steps
+
+1. Mount `<div><Button label="Bounds Test" /></div>`.
+2. Get the button via `Spectra.get('~button')` and read its bounds.
+3. Verify `bounds.width` and `bounds.height` are greater than 0, and `bounds.x` / `bounds.y` are numbers.
+4. Call `parent()` and verify the parent element is visible.
+5. Call `closest('div')` and verify a matching ancestor is returned.

package/templates/react-component/specs/ButtonComponent/TC-0006-button-bounds-and-parent/web.test.tsx

@@ -0,0 +1,25 @@
+import { Button } from '../../../src/components/Button/Button.js';
+import { withProviders } from '../../../src/test-utils.js';
+
+it('Verify button bounds and parent element access', async () => {
+  await Spectra.mount(withProviders(
+    <div><Button label="Bounds Test" /></div>,
+  ));
+
+  const button = Spectra.get('~button');
+
+  // getBounds returns position + size
+  const bounds = await button.getBounds();
+  expect(bounds.width).toBeGreaterThan(0);
+  expect(bounds.height).toBeGreaterThan(0);
+  expect(typeof bounds.x).toBe('number');
+  expect(typeof bounds.y).toBe('number');
+
+  // parent() navigates up the DOM tree
+  const parent = button.parent();
+  await parent.shouldBeVisible();
+
+  // closest() finds matching ancestor
+  const wrapper = await button.closest('div');
+  expect(wrapper).not.toBeNull();
+});

package/templates/react-component/specs/ButtonComponent/TC-0007-button-wait-and-remove/spec.md

@@ -0,0 +1,20 @@
+---
+id: TC-0007
+title: Verify button wait states and element removal detection
+priority: Medium
+caseType: Positive
+status: automated
+coverage:
+  web: automated
+---
+
+# TC-0007: Button Wait States
+
+Verify that a mounted button satisfies explicit wait conditions such as `waitForClickable()` before asserting visibility.
+
+## Test Steps
+
+1. Mount `<div><Button label="Wait Test" /></div>`.
+2. Get the button via `Spectra.get('~button')`.
+3. Call `waitForClickable({ timeout: 3000 })` and verify it resolves to `true`.
+4. Verify the button is visible.

package/templates/react-component/specs/ButtonComponent/TC-0007-button-wait-and-remove/web.test.tsx

@@ -0,0 +1,18 @@
+import { Button } from '../../../src/components/Button/Button.js';
+import { withProviders } from '../../../src/test-utils.js';
+
+it('Verify button wait states and element removal detection', async () => {
+  await Spectra.mount(withProviders(
+    <div><Button label="Wait Test" /></div>,
+  ));
+
+  const button = Spectra.get('~button');
+
+  // waitForClickable — button should be clickable
+  const clickable = await button.waitForClickable({ timeout: 3000 });
+  expect(clickable).toBe(true);
+
+  // waitForUndisplayed on hidden element
+  // waitForElementRemoved would need a dynamically removed element — skip for static mount
+  await button.shouldBeVisible();
+});

package/templates/react-component/specs/InputComponent/TC-0009-input-bounds/spec.md

@@ -0,0 +1,20 @@
+---
+id: TC-0009
+title: Verify input bounds and closest ancestor
+priority: Medium
+caseType: Positive
+status: automated
+coverage:
+  web: automated
+---
+
+# TC-0009: Input Bounds and Closest Ancestor
+
+Verify that `Spectra.get('input')` exposes element bounds (position + size) and can locate a matching ancestor via `closest()`.
+
+## Test Steps
+
+1. Mount `<Input placeholder="Bounds check" />`.
+2. Get the input via `Spectra.get('input')` and read its bounds.
+3. Verify `bounds.width` and `bounds.height` are greater than 0.
+4. Call `closest('div')` and verify a matching ancestor is returned.

package/templates/react-component/specs/InputComponent/TC-0009-input-bounds/web.test.tsx

@@ -0,0 +1,15 @@
+import { Input } from '../../../src/components/Input/Input.js';
+import { withProviders } from '../../../src/test-utils.js';
+
+it('Verify input bounds and closest ancestor', async () => {
+  await Spectra.mount(withProviders(<Input placeholder="Bounds check" />));
+
+  const input = Spectra.get('input');
+
+  const bounds = await input.getBounds();
+  expect(bounds.width).toBeGreaterThan(0);
+  expect(bounds.height).toBeGreaterThan(0);
+
+  const closest = await input.closest('div');
+  expect(closest).not.toBeNull();
+});