@jay-framework/runtime-automation 0.11.0

package/dist/index.d.ts

@@ -0,0 +1,137 @@
+import * as _jay_framework_runtime from '@jay-framework/runtime';
+import { JayComponent } from '@jay-framework/runtime';
+import { TrackByMap } from '@jay-framework/view-state-merge';
+
+/**
+ * Coordinate path identifying an element.
+ * For forEach items: ['trackByValue', 'refName']
+ * For nested: ['parentTrackBy', 'childTrackBy', 'refName']
+ */
+type Coordinate = string[];
+/**
+ * Represents an interactive element on the page.
+ */
+interface Interaction {
+    /** Ref name from jay-html */
+    refName: string;
+    /** Full coordinate path (for forEach items) */
+    coordinate: Coordinate;
+    /** The actual DOM element - can be used to read/set values or call click() */
+    element: HTMLElement;
+    /** HTML element type (e.g., "HTMLButtonElement") */
+    elementType: string;
+    /** Events this element can handle (e.g., ["click", "input"]) */
+    supportedEvents: string[];
+    /** For collection items: the item's ViewState */
+    itemContext?: object;
+    /** Human-readable description (from contract if available) */
+    description?: string;
+}
+/**
+ * Current page state exposed for automation.
+ */
+interface PageState {
+    /** Current ViewState of the component (includes headless component data under their keys) */
+    viewState: object;
+    /** All available interactions with their DOM elements */
+    interactions: Interaction[];
+    /** Custom events the component can emit */
+    customEvents: Array<{
+        name: string;
+    }>;
+}
+/**
+ * Automation API attached to wrapped components.
+ */
+interface AutomationAPI {
+    /** Get current page state and available interactions */
+    getPageState(): PageState;
+    /** Trigger an event on an element by coordinate */
+    triggerEvent(eventType: string, coordinate: Coordinate, eventData?: object): void;
+    /** Subscribe to ViewState changes - called on every ViewState update */
+    onStateChange(callback: (state: PageState) => void): () => void;
+    /** Get a specific interaction by coordinate */
+    getInteraction(coordinate: Coordinate): Interaction | undefined;
+    /** Get list of custom events the component emits */
+    getCustomEvents(): Array<{
+        name: string;
+    }>;
+    /** Subscribe to a custom component event (e.g., 'AddToCart') */
+    onComponentEvent(eventName: string, callback: (eventData: any) => void): () => void;
+    /** Cleanup - call when component is unmounted */
+    dispose(): void;
+}
+/** @deprecated Use Interaction instead */
+type AIInteraction = Interaction;
+/** @deprecated Use PageState instead */
+type AIPageState = PageState;
+/** @deprecated Use AutomationAPI instead */
+type AIAgentAPI = AutomationAPI;
+
+/**
+ * Options for creating an AutomationAgent with slow ViewState support.
+ */
+interface AutomationAgentOptions {
+    /** The initial merged slow+fast ViewState */
+    initialViewState: object;
+    /** TrackByMap for deep merging arrays by their track-by keys */
+    trackByMap: TrackByMap;
+}
+/** Wrapper type that adds automation capabilities to a component */
+type AutomationWrappedComponent<T> = T & {
+    automation: AutomationAPI;
+};
+/**
+ * Wraps a Jay component with automation capabilities.
+ * Uses addEventListener('viewStateChange', ...) to capture all state changes.
+ *
+ * @param component - The Jay component to wrap
+ * @param options - Optional options for slow rendering support:
+ *   - initialViewState: Full ViewState (slow+fast merged)
+ *   - trackByMap: Map of array paths to their track-by keys for deep merging
+ *
+ * @example
+ * ```typescript
+ * const instance = MyComponent(props);
+ * const wrapped = wrapWithAutomation(instance);
+ *
+ * // Access automation API
+ * const state = wrapped.automation.getPageState();
+ * wrapped.automation.triggerEvent('click', ['button-ref']);
+ * ```
+ *
+ * @example With slow rendering
+ * ```typescript
+ * const instance = MyComponent(fastViewState);
+ * const fullViewState = deepMergeViewStates(slowViewState, fastViewState, trackByMap);
+ * const wrapped = wrapWithAutomation(instance, { initialViewState: fullViewState, trackByMap });
+ * ```
+ */
+declare function wrapWithAutomation<T extends JayComponent<any, any, any>>(component: T, options?: AutomationAgentOptions): AutomationWrappedComponent<T>;
+
+/**
+ * Global context for accessing the automation API.
+ * Available in dev mode when automation is enabled.
+ *
+ * @example
+ * ```typescript
+ * import { useContext } from '@jay-framework/runtime';
+ * import { AUTOMATION_CONTEXT } from '@jay-framework/runtime-automation';
+ *
+ * function MyComponent(props, refs, automation: AutomationAPI) {
+ *     const state = automation.getPageState();
+ *     // ...
+ * }
+ *
+ * export const MyComp = makeJayComponent(render, MyComponent, AUTOMATION_CONTEXT);
+ * ```
+ */
+declare const AUTOMATION_CONTEXT: _jay_framework_runtime.ContextMarker<AutomationAPI>;
+
+/**
+ * Collects all interactive elements from a component's refs.
+ * Handles nested refs (e.g., headless components) by recursively traversing the refs tree.
+ */
+declare function collectInteractions(refs: any): Interaction[];
+
+export { type AIAgentAPI, type AIInteraction, type AIPageState, AUTOMATION_CONTEXT, type AutomationAPI, type AutomationAgentOptions, type AutomationWrappedComponent, type Coordinate, type Interaction, type PageState, collectInteractions, wrapWithAutomation };

package/dist/index.js

@@ -0,0 +1,261 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+import { createJayContext } from "@jay-framework/runtime";
+function deepMergeViewStates(base, overlay, trackByMap, path = "") {
+  if (!base && !overlay)
+    return {};
+  if (!base)
+    return overlay || {};
+  if (!overlay)
+    return base || {};
+  const result = {};
+  const allKeys = /* @__PURE__ */ new Set([...Object.keys(base), ...Object.keys(overlay)]);
+  for (const key of allKeys) {
+    const baseValue = base[key];
+    const overlayValue = overlay[key];
+    const currentPath = path ? `${path}.${key}` : key;
+    if (overlayValue === void 0) {
+      result[key] = baseValue;
+    } else if (baseValue === void 0) {
+      result[key] = overlayValue;
+    } else if (Array.isArray(baseValue) && Array.isArray(overlayValue)) {
+      const trackByField = trackByMap[currentPath];
+      if (trackByField) {
+        result[key] = mergeArraysByTrackBy(
+          baseValue,
+          overlayValue,
+          trackByField,
+          trackByMap,
+          currentPath
+        );
+      } else {
+        result[key] = overlayValue;
+      }
+    } else if (typeof baseValue === "object" && baseValue !== null && typeof overlayValue === "object" && overlayValue !== null && !Array.isArray(baseValue) && !Array.isArray(overlayValue)) {
+      result[key] = deepMergeViewStates(baseValue, overlayValue, trackByMap, currentPath);
+    } else {
+      result[key] = overlayValue;
+    }
+  }
+  return result;
+}
+function mergeArraysByTrackBy(baseArray, overlayArray, trackByField, trackByMap, arrayPath) {
+  const baseByKey = /* @__PURE__ */ new Map();
+  for (const item of baseArray) {
+    const key = item[trackByField];
+    if (key !== void 0 && key !== null) {
+      if (baseByKey.has(key)) {
+        console.warn(
+          `Duplicate trackBy key [${key}] in base array at path [${arrayPath}]. This may cause incorrect merging.`
+        );
+      }
+      baseByKey.set(key, item);
+    }
+  }
+  const overlayByKey = /* @__PURE__ */ new Map();
+  for (const item of overlayArray) {
+    const key = item[trackByField];
+    if (key !== void 0 && key !== null) {
+      overlayByKey.set(key, item);
+    }
+  }
+  return baseArray.map((baseItem) => {
+    const key = baseItem[trackByField];
+    if (key === void 0 || key === null) {
+      return baseItem;
+    }
+    const overlayItem = overlayByKey.get(key);
+    if (overlayItem) {
+      return deepMergeViewStates(baseItem, overlayItem, trackByMap, arrayPath);
+    } else {
+      return baseItem;
+    }
+  });
+}
+function collectInteractions(refs) {
+  const interactions = [];
+  if (!refs)
+    return interactions;
+  collectInteractionsRecursive(refs, interactions);
+  return interactions;
+}
+function collectInteractionsRecursive(refs, interactions) {
+  if (!refs)
+    return;
+  for (const [refName, refImpl] of Object.entries(refs)) {
+    if (!refImpl)
+      continue;
+    if (refImpl.elements && refImpl.elements instanceof Set) {
+      for (const elem of refImpl.elements) {
+        if (elem.element) {
+          interactions.push({
+            refName,
+            coordinate: elem.coordinate || [refName],
+            element: elem.element,
+            elementType: getElementType(elem.element),
+            supportedEvents: getSupportedEvents(elem.element),
+            itemContext: elem.viewState
+          });
+        }
+      }
+    } else if (isNestedRefsObject(refImpl)) {
+      collectInteractionsRecursive(refImpl, interactions);
+    }
+  }
+}
+function isNestedRefsObject(obj) {
+  if (!obj || typeof obj !== "object")
+    return false;
+  if (obj.elements instanceof Set)
+    return false;
+  const proto = Object.getPrototypeOf(obj);
+  if (proto !== Object.prototype && proto !== null)
+    return false;
+  return true;
+}
+function getElementType(element) {
+  return element.constructor.name;
+}
+function getSupportedEvents(element) {
+  const base = ["click", "focus", "blur"];
+  if (element instanceof HTMLInputElement) {
+    return [...base, "input", "change"];
+  }
+  if (element instanceof HTMLButtonElement) {
+    return ["click", "focus", "blur"];
+  }
+  if (element instanceof HTMLSelectElement) {
+    return [...base, "change"];
+  }
+  if (element instanceof HTMLTextAreaElement) {
+    return [...base, "input", "change"];
+  }
+  if (element instanceof HTMLAnchorElement) {
+    return ["click"];
+  }
+  if (element instanceof HTMLFormElement) {
+    return ["submit", "reset"];
+  }
+  return base;
+}
+const VIEW_STATE_CHANGE = "viewStateChange";
+class AutomationAgent {
+  constructor(component, options) {
+    __publicField(this, "stateListeners", /* @__PURE__ */ new Set());
+    __publicField(this, "cachedInteractions", null);
+    __publicField(this, "viewStateHandler", null);
+    /**
+     * When slow rendering is used, this holds the merged slow+fast ViewState.
+     * Updated on each viewStateChange event with the new fast state merged in.
+     */
+    __publicField(this, "mergedViewState");
+    __publicField(this, "initialSlowViewState");
+    __publicField(this, "trackByMap");
+    this.component = component;
+    if (options) {
+      this.initialSlowViewState = options.initialViewState;
+      this.trackByMap = options.trackByMap;
+      this.mergedViewState = deepMergeViewStates(
+        options.initialViewState,
+        this.component.viewState || {},
+        options.trackByMap
+      );
+    }
+    this.subscribeToUpdates();
+  }
+  subscribeToUpdates() {
+    this.viewStateHandler = () => {
+      this.cachedInteractions = null;
+      if (this.initialSlowViewState && this.trackByMap) {
+        this.mergedViewState = deepMergeViewStates(
+          this.initialSlowViewState,
+          this.component.viewState || {},
+          this.trackByMap
+        );
+      }
+      this.notifyListeners();
+    };
+    this.component.addEventListener(VIEW_STATE_CHANGE, this.viewStateHandler);
+  }
+  notifyListeners() {
+    if (this.stateListeners.size === 0)
+      return;
+    const state = this.getPageState();
+    this.stateListeners.forEach((callback) => callback(state));
+  }
+  getPageState() {
+    if (!this.cachedInteractions) {
+      this.cachedInteractions = collectInteractions(this.component.element?.refs);
+    }
+    return {
+      // Use merged state if available (slow+fast), otherwise component's viewState
+      viewState: this.mergedViewState || this.component.viewState,
+      interactions: this.cachedInteractions,
+      customEvents: this.getCustomEvents()
+    };
+  }
+  triggerEvent(eventType, coordinate, eventData) {
+    const interaction = this.getInteraction(coordinate);
+    if (!interaction) {
+      throw new Error(`No element found at coordinate: ${coordinate.join("/")}`);
+    }
+    const event = new Event(eventType, { bubbles: true });
+    if (eventData) {
+      Object.assign(event, eventData);
+    }
+    interaction.element.dispatchEvent(event);
+  }
+  getInteraction(coordinate) {
+    const state = this.getPageState();
+    return state.interactions.find(
+      (i) => i.coordinate.length === coordinate.length && i.coordinate.every((c, idx) => c === coordinate[idx])
+    );
+  }
+  onStateChange(callback) {
+    this.stateListeners.add(callback);
+    return () => this.stateListeners.delete(callback);
+  }
+  getCustomEvents() {
+    const events = [];
+    const component = this.component;
+    for (const key in component) {
+      if (component[key]?.emit && typeof component[key].emit === "function") {
+        const name = key.startsWith("on") ? key.slice(2) : key;
+        events.push({ name });
+      }
+    }
+    return events;
+  }
+  onComponentEvent(eventName, callback) {
+    const component = this.component;
+    const handlerKey = eventName.startsWith("on") ? eventName : `on${eventName}`;
+    const handler = component[handlerKey];
+    if (!handler || typeof handler !== "function") {
+      throw new Error(`Unknown component event: ${eventName}`);
+    }
+    handler(({ event }) => callback(event));
+    return () => handler(void 0);
+  }
+  dispose() {
+    if (this.viewStateHandler) {
+      this.component.removeEventListener(VIEW_STATE_CHANGE, this.viewStateHandler);
+      this.viewStateHandler = null;
+    }
+    this.stateListeners.clear();
+    this.cachedInteractions = null;
+  }
+}
+function wrapWithAutomation(component, options) {
+  const agent = new AutomationAgent(component, options);
+  return Object.assign(component, { automation: agent });
+}
+const AUTOMATION_CONTEXT = createJayContext();
+export {
+  AUTOMATION_CONTEXT,
+  collectInteractions,
+  wrapWithAutomation
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@jay-framework/runtime-automation",
+  "version": "0.11.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "Automation API for Jay components - enables programmatic state inspection and interaction triggering",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "readme.md"
+  ],
+  "scripts": {
+    "build": "npm run build:js && npm run build:types",
+    "build:watch": "npm run build:js -- --watch & npm run build:types -- --watch",
+    "build:js": "vite build",
+    "build:types": "tsup lib/index.ts --dts-only --format esm",
+    "build:check-types": "tsc",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build && npm run build:check-types && npm run test",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@jay-framework/runtime": "^0.11.0",
+    "@jay-framework/view-state-merge": "^0.11.0"
+  },
+  "devDependencies": {
+    "@jay-framework/component": "^0.11.0",
+    "@jay-framework/dev-environment": "^0.11.0",
+    "@types/node": "^20.11.5",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.11",
+    "vitest": "^1.2.1"
+  }
+}

package/readme.md

@@ -0,0 +1,74 @@
+# @jay-framework/runtime-automation
+
+Automation API for Jay components. Enables programmatic automation to:
+
+- Read current page state (ViewState)
+- Discover available interactions (refs with coordinates)
+- Trigger events on elements
+- Subscribe to state changes
+- Listen to custom component events
+
+**Use cases**: AI agents, test automation, accessibility tools, E2E testing.
+
+## Installation
+
+```bash
+npm install @jay-framework/runtime-automation
+```
+
+## Usage
+
+```typescript
+import { wrapWithAutomation } from '@jay-framework/runtime-automation';
+
+// Wrap your component with automation capabilities
+const instance = MyComponent(props);
+const wrapped = wrapWithAutomation(instance);
+
+// Mount as usual
+target.appendChild(wrapped.element.dom);
+
+// Automation API is available on the instance
+const state = wrapped.automation.getPageState();
+console.log(state.viewState); // Current data
+console.log(state.interactions); // Available actions
+
+// Trigger events
+wrapped.automation.triggerEvent('click', ['product-123', 'remove']);
+
+// Subscribe to state changes
+const unsubscribe = wrapped.automation.onStateChange((newState) => {
+  console.log('State updated:', newState.viewState);
+});
+```
+
+## Browser Console Usage
+
+```javascript
+// Expose to window for console access
+window.app = wrapped;
+
+// Then from console:
+app.automation.getPageState();
+app.automation.triggerEvent('click', ['item-1', 'removeBtn']);
+```
+
+## API
+
+### `wrapWithAutomation(component)`
+
+Wraps a Jay component with automation capabilities.
+
+### `AutomationAPI`
+
+- `getPageState()` - Get current ViewState and available interactions
+- `triggerEvent(type, coordinate, data?)` - Trigger an event on an element
+- `getInteraction(coordinate)` - Get a specific interaction by coordinate
+- `onStateChange(callback)` - Subscribe to ViewState changes
+- `getCustomEvents()` - List custom events the component emits
+- `onComponentEvent(name, callback)` - Subscribe to a custom component event
+- `dispose()` - Clean up listeners
+
+## Design
+
+See [Design Log #76 - AI Agent Integration](../../../design-log/76%20-%20AI%20Agent%20Integration.md) for full design documentation.