@supernal/interface 1.0.0

package/dist/esm/src/testing/BrowserStateInjection.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Browser State Injection - Test Utilities
+ *
+ * Provides mechanism for E2E tests to set and read component state
+ * in the browser context. Only active in test environments.
+ *
+ * @module BrowserStateInjection
+ */
+/**
+ * Global test state interface
+ * Exposed on window for Playwright tests to access
+ */
+export interface TestStateManager {
+    /**
+     * Set component state via custom event
+     * @param component - Component name (from @Component decorator)
+     * @param state - Partial state to merge
+     */
+    setState(component: string, state: any): void;
+    /**
+     * Get component state by reading data-state attribute
+     * @param component - Component name
+     * @returns Current component state or undefined
+     */
+    getState(component: string): any | undefined;
+    /**
+     * Wait for component to be ready (registered and rendered)
+     * @param component - Component name
+     * @param timeoutMs - Timeout in milliseconds (default: 5000)
+     */
+    waitForComponent(component: string, timeoutMs?: number): Promise<void>;
+    /**
+     * Reset component to initial state
+     * @param component - Component name
+     */
+    resetState(component: string): void;
+    /**
+     * Check if component is registered and available
+     * @param component - Component name
+     */
+    hasComponent(component: string): boolean;
+}
+/**
+ * Custom event detail for state updates
+ */
+export interface StateUpdateEvent {
+    component: string;
+    state: any;
+}
+/**
+ * Custom event detail for state reset
+ */
+export interface StateResetEvent {
+    component: string;
+}
+/**
+ * Initialize test state manager on window
+ * Only runs in test environment
+ */
+export declare function initializeTestStateManager(): void;
+/**
+ * Get test state manager from window
+ * Returns undefined if not in browser or not test environment
+ */
+export declare function getTestStateManager(): TestStateManager | undefined;
+/**
+ * Type augmentation for Window interface
+ */
+declare global {
+    interface Window {
+        __testState__?: TestStateManager;
+    }
+}
+//# sourceMappingURL=BrowserStateInjection.d.ts.map

package/dist/esm/src/testing/BrowserStateInjection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserStateInjection.d.ts","sourceRoot":"","sources":["../../../../src/testing/BrowserStateInjection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAAC;IAE9C;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,CAAC;IAE7C;;;;OAIG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvE;;;OAGG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEpC;;;OAGG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,GAAG,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAqGD;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAmBjD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,SAAS,CAMlE;AAOD;;GAEG;AACH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,aAAa,CAAC,EAAE,gBAAgB,CAAC;KAClC;CACF"}

package/dist/esm/src/testing/BrowserStateInjection.js

@@ -0,0 +1,126 @@
+/**
+ * Browser State Injection - Test Utilities
+ *
+ * Provides mechanism for E2E tests to set and read component state
+ * in the browser context. Only active in test environments.
+ *
+ * @module BrowserStateInjection
+ */
+/**
+ * Test state manager implementation
+ * Available as window.__testState__ in test environments
+ */
+class BrowserTestStateManager {
+    constructor() {
+        this.eventPrefix = 'test:';
+    }
+    setState(component, state) {
+        if (typeof window === 'undefined') {
+            throw new Error('setState can only be called in browser context');
+        }
+        const event = new CustomEvent(`${this.eventPrefix}setState`, {
+            detail: { component, state },
+            bubbles: false,
+            cancelable: false,
+        });
+        window.dispatchEvent(event);
+        // Also log for debugging
+        if (process.env.NODE_ENV === 'test') {
+            console.log(`[TEST] setState: ${component}`, state);
+        }
+    }
+    getState(component) {
+        if (typeof window === 'undefined') {
+            throw new Error('getState can only be called in browser context');
+        }
+        // Find element by component name
+        const element = document.querySelector(`[data-component="${component}"]`);
+        if (!element) {
+            return undefined;
+        }
+        // Read state from data-state attribute
+        const stateAttr = element.getAttribute('data-state');
+        if (!stateAttr) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(stateAttr);
+        }
+        catch (error) {
+            console.error(`[TEST] Failed to parse state for ${component}:`, error);
+            return undefined;
+        }
+    }
+    async waitForComponent(component, timeoutMs = 5000) {
+        if (typeof window === 'undefined') {
+            throw new Error('waitForComponent can only be called in browser context');
+        }
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeoutMs) {
+            const element = document.querySelector(`[data-component="${component}"]`);
+            if (element) {
+                // Component element exists, wait a bit for React to initialize
+                await new Promise(resolve => setTimeout(resolve, 100));
+                return;
+            }
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        throw new Error(`Component '${component}' not found after ${timeoutMs}ms`);
+    }
+    resetState(component) {
+        if (typeof window === 'undefined') {
+            throw new Error('resetState can only be called in browser context');
+        }
+        const event = new CustomEvent(`${this.eventPrefix}resetState`, {
+            detail: { component },
+            bubbles: false,
+            cancelable: false,
+        });
+        window.dispatchEvent(event);
+        if (process.env.NODE_ENV === 'test') {
+            console.log(`[TEST] resetState: ${component}`);
+        }
+    }
+    hasComponent(component) {
+        if (typeof window === 'undefined') {
+            return false;
+        }
+        const element = document.querySelector(`[data-component="${component}"]`);
+        return !!element;
+    }
+}
+/**
+ * Initialize test state manager on window
+ * Only runs in test environment
+ */
+export function initializeTestStateManager() {
+    if (typeof window === 'undefined') {
+        return;
+    }
+    // Only initialize in test environment
+    if (process.env.NODE_ENV !== 'test') {
+        return;
+    }
+    // Check if already initialized
+    if (window.__testState__) {
+        return;
+    }
+    // Create and expose test state manager
+    window.__testState__ = new BrowserTestStateManager();
+    console.log('[TEST] Browser state injection initialized');
+}
+/**
+ * Get test state manager from window
+ * Returns undefined if not in browser or not test environment
+ */
+export function getTestStateManager() {
+    if (typeof window === 'undefined') {
+        return undefined;
+    }
+    return window.__testState__;
+}
+// Auto-initialize in test environment
+if (typeof window !== 'undefined' && process.env.NODE_ENV === 'test') {
+    initializeTestStateManager();
+}
+//# sourceMappingURL=BrowserStateInjection.js.map

package/dist/esm/src/testing/BrowserStateInjection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserStateInjection.js","sourceRoot":"","sources":["../../../../src/testing/BrowserStateInjection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAwDH;;;GAGG;AACH,MAAM,uBAAuB;IAA7B;QACmB,gBAAW,GAAG,OAAO,CAAC;IA4FzC,CAAC;IA1FC,QAAQ,CAAC,SAAiB,EAAE,KAAU;QACpC,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,WAAW,CAAmB,GAAG,IAAI,CAAC,WAAW,UAAU,EAAE;YAC7E,MAAM,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE;YAC5B,OAAO,EAAE,KAAK;YACd,UAAU,EAAE,KAAK;SAClB,CAAC,CAAC;QAEH,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAE5B,yBAAyB;QACzB,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;YACpC,OAAO,CAAC,GAAG,CAAC,oBAAoB,SAAS,EAAE,EAAE,KAAK,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAED,QAAQ,CAAC,SAAiB;QACxB,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QAED,iCAAiC;QACjC,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,oBAAoB,SAAS,IAAI,CAAC,CAAC;QAC1E,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,uCAAuC;QACvC,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;QACrD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC/B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,oCAAoC,SAAS,GAAG,EAAE,KAAK,CAAC,CAAC;YACvE,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,SAAiB,EAAE,YAAoB,IAAI;QAChE,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAC5E,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,SAAS,EAAE,CAAC;YAC1C,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,oBAAoB,SAAS,IAAI,CAAC,CAAC;YAC1E,IAAI,OAAO,EAAE,CAAC;gBACZ,+DAA+D;gBAC/D,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;gBACvD,OAAO;YACT,CAAC;YACD,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;QACzD,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,cAAc,SAAS,qBAAqB,SAAS,IAAI,CAAC,CAAC;IAC7E,CAAC;IAED,UAAU,CAAC,SAAiB;QAC1B,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;QACtE,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,WAAW,CAAkB,GAAG,IAAI,CAAC,WAAW,YAAY,EAAE;YAC9E,MAAM,EAAE,EAAE,SAAS,EAAE;YACrB,OAAO,EAAE,KAAK;YACd,UAAU,EAAE,KAAK;SAClB,CAAC,CAAC;QAEH,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAE5B,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;YACpC,OAAO,CAAC,GAAG,CAAC,sBAAsB,SAAS,EAAE,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED,YAAY,CAAC,SAAiB;QAC5B,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,oBAAoB,SAAS,IAAI,CAAC,CAAC;QAC1E,OAAO,CAAC,CAAC,OAAO,CAAC;IACnB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B;IACxC,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO;IACT,CAAC;IAED,sCAAsC;IACtC,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;QACpC,OAAO;IACT,CAAC;IAED,+BAA+B;IAC/B,IAAK,MAAc,CAAC,aAAa,EAAE,CAAC;QAClC,OAAO;IACT,CAAC;IAED,uCAAuC;IACtC,MAAc,CAAC,aAAa,GAAG,IAAI,uBAAuB,EAAE,CAAC;IAE9D,OAAO,CAAC,GAAG,CAAC,4CAA4C,CAAC,CAAC;AAC5D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAQ,MAAc,CAAC,aAAa,CAAC;AACvC,CAAC;AAED,sCAAsC;AACtC,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;IACrE,0BAA0B,EAAE,CAAC;AAC/B,CAAC"}

package/dist/esm/src/testing/ComponentStateHelpers.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Generalized State-Based Test Helpers
+ *
+ * Utilities for testing ANY component using data contracts instead of UI text.
+ * These helpers provide a component-agnostic way to assert state.
+ *
+ * @module tests/generalized-state-helpers
+ */
+import { Page } from '@playwright/test';
+/**
+ * Get state from any component that exposes it
+ *
+ * @param page - Playwright page
+ * @param componentId - Component identifier (e.g., 'demo-widgets', 'chat', 'counter')
+ *
+ * @example
+ * ```typescript
+ * const state = await getComponentState(page, 'demo-widgets');
+ * ```
+ */
+export declare function getComponentState<TState = any>(page: Page, componentId: string): Promise<TState>;
+/**
+ * Assert component state matches expected values
+ *
+ * @param page - Playwright page
+ * @param componentId - Component identifier
+ * @param expected - Partial state to match
+ *
+ * @example
+ * ```typescript
+ * await assertComponentState(page, 'demo-widgets', { menuOpen: true });
+ * await assertComponentState(page, 'counter', { count: 5 });
+ * await assertComponentState(page, 'chat', { isMinimized: false });
+ * ```
+ */
+export declare function assertComponentState<TState = any>(page: Page, componentId: string, expected: Partial<TState>): Promise<void>;
+/**
+ * Set component state (if component supports it)
+ *
+ * @param page - Playwright page
+ * @param componentId - Component identifier
+ * @param updates - Partial state to set
+ *
+ * @example
+ * ```typescript
+ * await setComponentState(page, 'demo-widgets', { theme: 'dark' });
+ * ```
+ */
+export declare function setComponentState<TState = any>(page: Page, componentId: string, updates: Partial<TState>): Promise<void>;
+/**
+ * Wait for component state to match condition
+ *
+ * @param page - Playwright page
+ * @param componentId - Component identifier
+ * @param condition - Function that returns true when state is ready
+ * @param options - Timeout and polling options
+ *
+ * @example
+ * ```typescript
+ * await waitForComponentState(page, 'chat',
+ *   state => state.messages.length > 0
+ * );
+ * ```
+ */
+export declare function waitForComponentState<TState = any>(page: Page, componentId: string, condition: (state: TState) => boolean, options?: {
+    timeout?: number;
+    pollInterval?: number;
+}): Promise<void>;
+/**
+ * Assert state via data-state attributes (alternative approach)
+ * Useful when component doesn't expose JS state but adds data attributes
+ *
+ * @param page - Playwright page
+ * @param selector - CSS selector for component
+ * @param attribute - data-state-* attribute name
+ * @param expectedValue - Expected attribute value
+ *
+ * @example
+ * ```typescript
+ * await assertStateAttribute(page, '[data-testid="menu"]', 'data-state-open', 'true');
+ * ```
+ */
+export declare function assertStateAttribute(page: Page, selector: string, attribute: string, expectedValue: string): Promise<void>;
+/**
+ * Get all registered component state IDs
+ * Useful for debugging
+ *
+ * @param page - Playwright page
+ * @returns Array of component IDs that expose state
+ *
+ * @example
+ * ```typescript
+ * const components = await getRegisteredComponents(page);
+ * console.log('Available:', components); // ['demo-widgets', 'chat', 'counter']
+ * ```
+ */
+export declare function getRegisteredComponents(page: Page): Promise<string[]>;
+/**
+ * Debug helper: Print current state of a component
+ *
+ * @param page - Playwright page
+ * @param componentId - Component identifier
+ *
+ * @example
+ * ```typescript
+ * await debugComponentState(page, 'demo-widgets');
+ * ```
+ */
+export declare function debugComponentState(page: Page, componentId: string): Promise<void>;
+/**
+ * Debug helper: Print all component states
+ *
+ * @param page - Playwright page
+ *
+ * @example
+ * ```typescript
+ * await debugAllComponentStates(page);
+ * ```
+ */
+export declare function debugAllComponentStates(page: Page): Promise<void>;
+//# sourceMappingURL=ComponentStateHelpers.d.ts.map

package/dist/esm/src/testing/ComponentStateHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComponentStateHelpers.d.ts","sourceRoot":"","sources":["../../../../src/testing/ComponentStateHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,IAAI,EAAU,MAAM,kBAAkB,CAAC;AAWhD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,GAAG,GAAG,EAClD,IAAI,EAAE,IAAI,EACV,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,GAAG,GAAG,EACrD,IAAI,EAAE,IAAI,EACV,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,GACxB,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,GAAG,GAAG,EAClD,IAAI,EAAE,IAAI,EACV,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,GACvB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,GAAG,GAAG,EACtD,IAAI,EAAE,IAAI,EACV,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,EACrC,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GACxD,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAI3E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,IAAI,EACV,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAKf;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAevE"}

package/dist/esm/src/testing/ComponentStateHelpers.js

@@ -0,0 +1,190 @@
+/**
+ * Generalized State-Based Test Helpers
+ *
+ * Utilities for testing ANY component using data contracts instead of UI text.
+ * These helpers provide a component-agnostic way to assert state.
+ *
+ * @module tests/generalized-state-helpers
+ */
+import { expect } from '@playwright/test';
+/**
+ * Get state from any component that exposes it
+ *
+ * @param page - Playwright page
+ * @param componentId - Component identifier (e.g., 'demo-widgets', 'chat', 'counter')
+ *
+ * @example
+ * ```typescript
+ * const state = await getComponentState(page, 'demo-widgets');
+ * ```
+ */
+export async function getComponentState(page, componentId) {
+    return await page.evaluate((id) => {
+        if (window.__componentState__?.[id]) {
+            return window.__componentState__[id].get();
+        }
+        throw new Error(`Component state not exposed for: ${id}\n` +
+            `Available components: ${Object.keys(window.__componentState__ || {}).join(', ')}\n` +
+            `Make sure the component exposes state via window.__componentState__['${id}']`);
+    }, componentId);
+}
+/**
+ * Assert component state matches expected values
+ *
+ * @param page - Playwright page
+ * @param componentId - Component identifier
+ * @param expected - Partial state to match
+ *
+ * @example
+ * ```typescript
+ * await assertComponentState(page, 'demo-widgets', { menuOpen: true });
+ * await assertComponentState(page, 'counter', { count: 5 });
+ * await assertComponentState(page, 'chat', { isMinimized: false });
+ * ```
+ */
+export async function assertComponentState(page, componentId, expected) {
+    const actual = await getComponentState(page, componentId);
+    // Check each expected key matches
+    for (const key of Object.keys(expected)) {
+        const expectedValue = expected[key];
+        const actualValue = actual[key];
+        if (JSON.stringify(actualValue) !== JSON.stringify(expectedValue)) {
+            throw new Error(`State mismatch for component "${componentId}".\n` +
+                `Field: ${key}\n` +
+                `Expected: ${JSON.stringify(expectedValue)}\n` +
+                `Actual: ${JSON.stringify(actualValue)}\n` +
+                `Full state: ${JSON.stringify(actual, null, 2)}`);
+        }
+    }
+}
+/**
+ * Set component state (if component supports it)
+ *
+ * @param page - Playwright page
+ * @param componentId - Component identifier
+ * @param updates - Partial state to set
+ *
+ * @example
+ * ```typescript
+ * await setComponentState(page, 'demo-widgets', { theme: 'dark' });
+ * ```
+ */
+export async function setComponentState(page, componentId, updates) {
+    await page.evaluate(({ id, state }) => {
+        if (window.__componentState__?.[id]?.update) {
+            window.__componentState__[id].update(state);
+        }
+        else {
+            throw new Error(`Component ${id} does not support state updates or is not exposed`);
+        }
+    }, { id: componentId, state: updates });
+}
+/**
+ * Wait for component state to match condition
+ *
+ * @param page - Playwright page
+ * @param componentId - Component identifier
+ * @param condition - Function that returns true when state is ready
+ * @param options - Timeout and polling options
+ *
+ * @example
+ * ```typescript
+ * await waitForComponentState(page, 'chat',
+ *   state => state.messages.length > 0
+ * );
+ * ```
+ */
+export async function waitForComponentState(page, componentId, condition, options = {}) {
+    const { timeout = 5000, pollInterval = 100 } = options;
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+        const state = await getComponentState(page, componentId);
+        if (condition(state)) {
+            return;
+        }
+        await page.waitForTimeout(pollInterval);
+    }
+    const currentState = await getComponentState(page, componentId);
+    throw new Error(`Timeout waiting for component state condition after ${timeout}ms.\n` +
+        `Component: ${componentId}\n` +
+        `Current state: ${JSON.stringify(currentState, null, 2)}`);
+}
+/**
+ * Assert state via data-state attributes (alternative approach)
+ * Useful when component doesn't expose JS state but adds data attributes
+ *
+ * @param page - Playwright page
+ * @param selector - CSS selector for component
+ * @param attribute - data-state-* attribute name
+ * @param expectedValue - Expected attribute value
+ *
+ * @example
+ * ```typescript
+ * await assertStateAttribute(page, '[data-testid="menu"]', 'data-state-open', 'true');
+ * ```
+ */
+export async function assertStateAttribute(page, selector, attribute, expectedValue) {
+    const element = page.locator(selector);
+    await expect(element).toHaveAttribute(attribute, expectedValue);
+}
+/**
+ * Get all registered component state IDs
+ * Useful for debugging
+ *
+ * @param page - Playwright page
+ * @returns Array of component IDs that expose state
+ *
+ * @example
+ * ```typescript
+ * const components = await getRegisteredComponents(page);
+ * console.log('Available:', components); // ['demo-widgets', 'chat', 'counter']
+ * ```
+ */
+export async function getRegisteredComponents(page) {
+    return await page.evaluate(() => {
+        return Object.keys(window.__componentState__ || {});
+    });
+}
+/**
+ * Debug helper: Print current state of a component
+ *
+ * @param page - Playwright page
+ * @param componentId - Component identifier
+ *
+ * @example
+ * ```typescript
+ * await debugComponentState(page, 'demo-widgets');
+ * ```
+ */
+export async function debugComponentState(page, componentId) {
+    const state = await getComponentState(page, componentId);
+    console.log(`=== ${componentId} State ===`);
+    console.log(JSON.stringify(state, null, 2));
+    console.log('========================');
+}
+/**
+ * Debug helper: Print all component states
+ *
+ * @param page - Playwright page
+ *
+ * @example
+ * ```typescript
+ * await debugAllComponentStates(page);
+ * ```
+ */
+export async function debugAllComponentStates(page) {
+    const components = await getRegisteredComponents(page);
+    console.log(`\n=== All Component States (${components.length} found) ===`);
+    for (const id of components) {
+        try {
+            const state = await getComponentState(page, id);
+            console.log(`\n[${id}]:`);
+            console.log(JSON.stringify(state, null, 2));
+        }
+        catch (error) {
+            console.log(`\n[${id}]: Error - ${error}`);
+        }
+    }
+    console.log('\n========================================\n');
+}
+//# sourceMappingURL=ComponentStateHelpers.js.map

package/dist/esm/src/testing/ComponentStateHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComponentStateHelpers.js","sourceRoot":"","sources":["../../../../src/testing/ComponentStateHelpers.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/testing/GherkinParser.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Gherkin Parser
+ *
+ * Parses Gherkin .feature files and converts them to executable test scenarios.
+ * Basic open-source version (Story system is enterprise edition).
+ */
+export interface GherkinFeature {
+    name: string;
+    description?: string;
+    tags?: string[];
+    scenarios: GherkinScenario[];
+}
+export interface GherkinScenario {
+    name: string;
+    tags?: string[];
+    steps: GherkinStep[];
+}
+export interface GherkinStep {
+    keyword: 'Given' | 'When' | 'Then' | 'And' | 'But';
+    text: string;
+    toolId?: string;
+    params?: Record<string, any>;
+}
+export declare class GherkinParser {
+    /**
+     * Parse a Gherkin feature file content
+     */
+    static parseFeature(content: string): GherkinFeature;
+    /**
+     * Resolve tool IDs from step text using natural language matching
+     */
+    static resolveSteps(steps: GherkinStep[]): GherkinStep[];
+    /**
+     * Extract parameters from step text
+     */
+    private static extractParameters;
+    /**
+     * Convert Gherkin scenario to Story definition
+     *
+     * NOTE: Story system is part of @supernal/interface-enterprise
+     * This method is not available in the open source edition.
+     *
+     * For enterprise features including story system, visit:
+     * https://supernal.ai/enterprise
+     */
+    static scenarioToStory(scenario: GherkinScenario, featureName: string): any;
+    /**
+     * Convert entire feature to stories and register them
+     *
+     * NOTE: Story system is part of @supernal/interface-enterprise
+     * This method is not available in the open source edition.
+     */
+    static featureToStories(feature: GherkinFeature): any[];
+    /**
+     * Generate unique story ID from feature and scenario names
+     */
+    private static generateStoryId;
+    /**
+     * Generate Gherkin steps from tools
+     * Moved from ToolPromptGenerator for consolidation
+     */
+    static generateSteps(tools: any[]): string;
+    /**
+     * Generate complete Gherkin feature from tool metadata
+     * Consolidated from both ToolPromptGenerator and original generateFeature
+     */
+    static generateFeature(featureName: string, tools: any[], options?: {
+        description?: string;
+        tags?: string[];
+    }): string;
+    /**
+     * Generate Playwright test from Gherkin feature
+     */
+    static generatePlaywrightTest(feature: GherkinFeature): string;
+    /**
+     * Validate round-trip: Generate → Parse → Generate
+     * Ensures parsing and generation are consistent
+     */
+    static validateRoundTrip(tools: any[], featureName?: string): {
+        valid: boolean;
+        original: string;
+        parsed: GherkinFeature;
+        regenerated: string;
+        errors: string[];
+    };
+}
+//# sourceMappingURL=GherkinParser.d.ts.map

package/dist/esm/src/testing/GherkinParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GherkinParser.d.ts","sourceRoot":"","sources":["../../../../src/testing/GherkinParser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,eAAe,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B;AAED,qBAAa,aAAa;IACxB;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc;IAiEpD;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE;IA0BxD;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAkBhC;;;;;;;;OAQG;IACH,MAAM,CAAC,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,GAAG,GAAG;IAO3E;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,cAAc,GAAG,GAAG,EAAE;IAOvD;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAM9B;;;OAGG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,MAAM;IAW1C;;;OAGG;IACH,MAAM,CAAC,eAAe,CACpB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,GAAG,EAAE,EACZ,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;KACjB,GACA,MAAM;IAuBT;;OAEG;IACH,MAAM,CAAC,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM;IA4B9D;;;OAGG;IACH,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,WAAW,GAAE,MAAuB,GAAG;QAC5E,KAAK,EAAE,OAAO,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,cAAc,CAAC;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,EAAE,CAAC;KAClB;CAqDF"}