@jay-framework/stack-client-runtime 0.10.0 → 0.12.0

package/dist/index.cjs

@@ -7,7 +7,8 @@ var __publicField = (obj, key, value) => {
 };
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const component = require("@jay-framework/component");
-function deepMergeViewStates(base, overlay, trackByMap, path = "") {
+const runtime = require("@jay-framework/runtime");
+function deepMergeViewStates$1(base, overlay, trackByMap, path = "") {
   if (!base && !overlay)
     return {};
   if (!base)
@@ -27,7 +28,7 @@ function deepMergeViewStates(base, overlay, trackByMap, path = "") {
     } else if (Array.isArray(baseValue) && Array.isArray(overlayValue)) {
       const trackByField = trackByMap[currentPath];
       if (trackByField) {
-        result[key] = mergeArraysByTrackBy(
+        result[key] = mergeArraysByTrackBy$1(
           baseValue,
           overlayValue,
           trackByField,
@@ -38,14 +39,14 @@ function deepMergeViewStates(base, overlay, trackByMap, path = "") {
         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);
+      result[key] = deepMergeViewStates$1(baseValue, overlayValue, trackByMap, currentPath);
     } else {
       result[key] = overlayValue;
     }
   }
   return result;
 }
-function mergeArraysByTrackBy(baseArray, overlayArray, trackByField, trackByMap, arrayPath) {
+function mergeArraysByTrackBy$1(baseArray, overlayArray, trackByField, trackByMap, arrayPath) {
   const baseByKey = /* @__PURE__ */ new Map();
   for (const item of baseArray) {
     const key = item[trackByField];
@@ -72,12 +73,29 @@ function mergeArraysByTrackBy(baseArray, overlayArray, trackByField, trackByMap,
     }
     const overlayItem = overlayByKey.get(key);
     if (overlayItem) {
-      return deepMergeViewStates(baseItem, overlayItem, trackByMap, arrayPath);
+      return deepMergeViewStates$1(baseItem, overlayItem, trackByMap, arrayPath);
     } else {
       return baseItem;
     }
   });
 }
+const HEADLESS_INSTANCES = runtime.createJayContext();
+function makeSignals$1(obj) {
+  return Object.keys(obj).reduce((signals, key) => {
+    signals[key] = component.createSignal(obj[key]);
+    return signals;
+  }, {});
+}
+function makeHeadlessInstanceComponent(preRender, interactiveConstructor, coordinateKey, pluginContexts = []) {
+  const wrappedConstructor = (props, refs, ...pluginResolvedContexts) => {
+    const instanceData = runtime.useContext(HEADLESS_INSTANCES);
+    const fastVS = instanceData?.viewStates?.[coordinateKey];
+    const cf = instanceData?.carryForwards?.[coordinateKey] || {};
+    const signalVS = fastVS ? makeSignals$1(fastVS) : void 0;
+    return interactiveConstructor(props, refs, signalVS, cf, ...pluginResolvedContexts);
+  };
+  return component.makeJayComponent(preRender, wrappedConstructor, ...pluginContexts);
+}
 function makeSignals(obj) {
   return Object.keys(obj).reduce((signals, key) => {
     signals[key] = component.createSignal(obj[key]);
@@ -85,39 +103,56 @@ function makeSignals(obj) {
   }, {});
 }
 function makeCompositeJayComponent(preRender, defaultViewState, fastCarryForward, parts, trackByMap = {}) {
+  const interactiveParts = parts.filter((part) => part.comp !== void 0);
   const hasFastRendering = defaultViewState !== null && defaultViewState !== void 0;
+  const headlessInstanceViewStates = defaultViewState?.__headlessInstances;
+  const headlessInstanceCarryForwards = fastCarryForward?.__headlessInstances;
+  if (headlessInstanceViewStates)
+    delete defaultViewState.__headlessInstances;
+  if (headlessInstanceCarryForwards)
+    delete fastCarryForward.__headlessInstances;
   const comp = (props, refs, ...contexts) => {
-    const instances = parts.map((part) => {
-      const partRefs = part.key ? refs[part.key] : refs;
-      let partContexts;
-      if (hasFastRendering) {
-        const partViewState = part.key ? defaultViewState?.[part.key] : defaultViewState;
-        const partFastViewState = partViewState ? makeSignals(partViewState) : void 0;
-        const partCarryForward = part.key ? fastCarryForward?.[part.key] : fastCarryForward;
-        partContexts = [
-          partFastViewState,
-          partCarryForward,
-          ...contexts.splice(0, part.contextMarkers.length)
-        ];
-      } else {
-        partContexts = [...contexts.splice(0, part.contextMarkers.length)];
+    if (headlessInstanceViewStates || headlessInstanceCarryForwards) {
+      const componentContext = runtime.useContext(component.COMPONENT_CONTEXT);
+      const instancesData = {
+        viewStates: headlessInstanceViewStates || {},
+        carryForwards: headlessInstanceCarryForwards || {}
+      };
+      componentContext.provideContexts.push([HEADLESS_INSTANCES, instancesData]);
+    }
+    const instances = interactiveParts.map(
+      (part) => {
+        const partRefs = part.key ? refs[part.key] : refs;
+        let partContexts;
+        if (hasFastRendering) {
+          const partViewState = part.key ? defaultViewState?.[part.key] : defaultViewState;
+          const partFastViewState = partViewState ? makeSignals(partViewState) : void 0;
+          const partCarryForward = part.key ? fastCarryForward?.[part.key] : fastCarryForward;
+          partContexts = [
+            partFastViewState,
+            partCarryForward,
+            ...contexts.splice(0, part.contextMarkers.length)
+          ];
+        } else {
+          partContexts = [...contexts.splice(0, part.contextMarkers.length)];
+        }
+        return [part.key, part.comp(props, partRefs, ...partContexts)];
       }
-      return [part.key, part.comp(props, partRefs, ...partContexts)];
-    });
+    );
     return {
       render: () => {
         let viewState = defaultViewState;
         instances.forEach(([key, instance]) => {
           const rendered = component.materializeViewState(instance.render());
           if (key) {
-            viewState[key] = deepMergeViewStates(
+            viewState[key] = deepMergeViewStates$1(
               defaultViewState[key],
               rendered,
               trackByMap,
               key
             );
           } else {
-            viewState = deepMergeViewStates(
+            viewState = deepMergeViewStates$1(
               viewState,
               rendered,
               trackByMap
@@ -128,7 +163,7 @@ function makeCompositeJayComponent(preRender, defaultViewState, fastCarryForward
       }
     };
   };
-  const contextMarkers = parts.reduce((cm, part) => {
+  const contextMarkers = interactiveParts.reduce((cm, part) => {
     return [...cm, ...part.contextMarkers];
   }, []);
   return component.makeJayComponent(
@@ -230,7 +265,262 @@ function isSimpleObject(obj) {
   }
   return true;
 }
+var __defProp2 = Object.defineProperty;
+var __defNormalProp2 = (obj, key, value) => key in obj ? __defProp2(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField2 = (obj, key, value) => {
+  __defNormalProp2(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+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(component2, options) {
+    __publicField2(this, "stateListeners", /* @__PURE__ */ new Set());
+    __publicField2(this, "cachedInteractions", null);
+    __publicField2(this, "viewStateHandler", null);
+    __publicField2(this, "mergedViewState");
+    __publicField2(this, "initialSlowViewState");
+    __publicField2(this, "trackByMap");
+    this.component = component2;
+    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 component2 = this.component;
+    for (const key in component2) {
+      if (component2[key]?.emit && typeof component2[key].emit === "function") {
+        const name = key.startsWith("on") ? key.slice(2) : key;
+        events.push({ name });
+      }
+    }
+    return events;
+  }
+  onComponentEvent(eventName, callback) {
+    const component2 = this.component;
+    const handlerKey = eventName.startsWith("on") ? eventName : `on${eventName}`;
+    const handler = component2[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(component2, options) {
+  const agent = new AutomationAgent(component2, options);
+  return Object.assign(component2, { automation: agent });
+}
+const AUTOMATION_CONTEXT = runtime.createJayContext();
+exports.AUTOMATION_CONTEXT = AUTOMATION_CONTEXT;
 exports.ActionError = ActionError;
+exports.HEADLESS_INSTANCES = HEADLESS_INSTANCES;
 exports.createActionCaller = createActionCaller;
 exports.makeCompositeJayComponent = makeCompositeJayComponent;
+exports.makeHeadlessInstanceComponent = makeHeadlessInstanceComponent;
 exports.setActionCallerOptions = setActionCallerOptions;
+exports.wrapWithAutomation = wrapWithAutomation;

package/dist/index.d.ts

@@ -1,16 +1,63 @@
 import * as _jay_framework_component from '@jay-framework/component';
 import { ComponentConstructor, ContextMarkers, JayComponentCore } from '@jay-framework/component';
-import { JayElement, PreRenderElement } from '@jay-framework/runtime';
+import { JayElement, PreRenderElement, ContextMarker } from '@jay-framework/runtime';
 import { TrackByMap } from '@jay-framework/view-state-merge';
+export { AUTOMATION_CONTEXT, AutomationAPI, AutomationWrappedComponent, Coordinate, Interaction, PageState, wrapWithAutomation } from '@jay-framework/runtime-automation';
 
 interface CompositePart {
-    comp: ComponentConstructor<any, any, any, any, any>;
+    /**
+     * The interactive component constructor.
+     * May be undefined if the component has no interactive phase (only slow/fast phases).
+     * See Design Log #72.
+     */
+    comp?: ComponentConstructor<any, any, any, any, any>;
     contextMarkers: ContextMarkers<any>;
     key?: string;
 }
 
 declare function makeCompositeJayComponent<PropsT extends object, ViewState extends object, Refs extends object, JayElementT extends JayElement<ViewState, Refs>, CompCore extends JayComponentCore<PropsT, ViewState>>(preRender: PreRenderElement<ViewState, Refs, JayElementT>, defaultViewState: ViewState, fastCarryForward: object, parts: Array<CompositePart>, trackByMap?: TrackByMap): (props: PropsT) => _jay_framework_component.ConcreteJayComponent<PropsT, ViewState, Refs, CompCore, JayElementT>;
 
+/**
+ * Client-side context and helpers for headless component instances.
+ *
+ * Provides the mechanism to deliver server-produced fast ViewState and carryForward
+ * to headless component instances on the client.
+ *
+ * Flow:
+ * 1. makeCompositeJayComponent extracts __headlessInstances from ViewState/carryForward
+ * 2. Registers HEADLESS_INSTANCES context during component construction
+ * 3. makeHeadlessInstanceComponent creates instance components that resolve their data
+ *    from this context by coordinate key
+ */
+
+/**
+ * Data structure for headless instance ViewStates and carryForwards.
+ * Keyed by coordinate path (e.g., "product-card:0", "p1/product-card:0").
+ */
+interface HeadlessInstancesData {
+    viewStates: Record<string, object>;
+    carryForwards: Record<string, object>;
+}
+/**
+ * Context marker for headless instance data.
+ * Provided by makeCompositeJayComponent, consumed by makeHeadlessInstanceComponent.
+ */
+declare const HEADLESS_INSTANCES: ContextMarker<HeadlessInstancesData>;
+/**
+ * Create a headless instance component that receives its fast ViewState from the
+ * HEADLESS_INSTANCES context, matched by coordinate key.
+ *
+ * This replaces makeJayComponent for headless instances. It wraps the plugin's
+ * interactive constructor to inject the instance's fast ViewState signals and
+ * carryForward before any plugin-defined context markers.
+ *
+ * @param preRender - The inline template's render function
+ * @param interactiveConstructor - The plugin's interactive constructor
+ * @param coordinateKey - The coordinate key for this instance (e.g., "product-card:0")
+ * @param pluginContexts - Additional context markers from the plugin (if any)
+ */
+declare function makeHeadlessInstanceComponent<PropsT extends object, ViewState extends object, Refs extends object, JayElementT extends JayElement<ViewState, Refs>, CompCore extends JayComponentCore<PropsT, ViewState>>(preRender: PreRenderElement<ViewState, Refs, JayElementT>, interactiveConstructor: ComponentConstructor<PropsT, Refs, ViewState, any, CompCore>, coordinateKey: string, pluginContexts?: ContextMarkers<any>): any;
+
 /**
  * Client-side action caller for Jay Stack.
  *
@@ -76,4 +123,4 @@ declare function setActionCallerOptions(options: ActionCallerOptions): void;
  */
 declare function createActionCaller<Input, Output>(actionName: string, method?: HttpMethod): (input: Input) => Promise<Output>;
 
-export { type ActionCallerOptions, ActionError, type CompositePart, type HttpMethod, createActionCaller, makeCompositeJayComponent, setActionCallerOptions };
+export { type ActionCallerOptions, ActionError, type CompositePart, HEADLESS_INSTANCES, type HeadlessInstancesData, type HttpMethod, createActionCaller, makeCompositeJayComponent, makeHeadlessInstanceComponent, setActionCallerOptions };

package/dist/index.js

@@ -4,8 +4,9 @@ var __publicField = (obj, key, value) => {
   __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
 };
-import { makeJayComponent, materializeViewState, createSignal } from "@jay-framework/component";
-function deepMergeViewStates(base, overlay, trackByMap, path = "") {
+import { makeJayComponent, createSignal, COMPONENT_CONTEXT, materializeViewState } from "@jay-framework/component";
+import { createJayContext, useContext } from "@jay-framework/runtime";
+function deepMergeViewStates$1(base, overlay, trackByMap, path = "") {
   if (!base && !overlay)
     return {};
   if (!base)
@@ -25,7 +26,7 @@ function deepMergeViewStates(base, overlay, trackByMap, path = "") {
     } else if (Array.isArray(baseValue) && Array.isArray(overlayValue)) {
       const trackByField = trackByMap[currentPath];
       if (trackByField) {
-        result[key] = mergeArraysByTrackBy(
+        result[key] = mergeArraysByTrackBy$1(
           baseValue,
           overlayValue,
           trackByField,
@@ -36,14 +37,14 @@ function deepMergeViewStates(base, overlay, trackByMap, path = "") {
         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);
+      result[key] = deepMergeViewStates$1(baseValue, overlayValue, trackByMap, currentPath);
     } else {
       result[key] = overlayValue;
     }
   }
   return result;
 }
-function mergeArraysByTrackBy(baseArray, overlayArray, trackByField, trackByMap, arrayPath) {
+function mergeArraysByTrackBy$1(baseArray, overlayArray, trackByField, trackByMap, arrayPath) {
   const baseByKey = /* @__PURE__ */ new Map();
   for (const item of baseArray) {
     const key = item[trackByField];
@@ -70,12 +71,29 @@ function mergeArraysByTrackBy(baseArray, overlayArray, trackByField, trackByMap,
     }
     const overlayItem = overlayByKey.get(key);
     if (overlayItem) {
-      return deepMergeViewStates(baseItem, overlayItem, trackByMap, arrayPath);
+      return deepMergeViewStates$1(baseItem, overlayItem, trackByMap, arrayPath);
     } else {
       return baseItem;
     }
   });
 }
+const HEADLESS_INSTANCES = createJayContext();
+function makeSignals$1(obj) {
+  return Object.keys(obj).reduce((signals, key) => {
+    signals[key] = createSignal(obj[key]);
+    return signals;
+  }, {});
+}
+function makeHeadlessInstanceComponent(preRender, interactiveConstructor, coordinateKey, pluginContexts = []) {
+  const wrappedConstructor = (props, refs, ...pluginResolvedContexts) => {
+    const instanceData = useContext(HEADLESS_INSTANCES);
+    const fastVS = instanceData?.viewStates?.[coordinateKey];
+    const cf = instanceData?.carryForwards?.[coordinateKey] || {};
+    const signalVS = fastVS ? makeSignals$1(fastVS) : void 0;
+    return interactiveConstructor(props, refs, signalVS, cf, ...pluginResolvedContexts);
+  };
+  return makeJayComponent(preRender, wrappedConstructor, ...pluginContexts);
+}
 function makeSignals(obj) {
   return Object.keys(obj).reduce((signals, key) => {
     signals[key] = createSignal(obj[key]);
@@ -83,39 +101,56 @@ function makeSignals(obj) {
   }, {});
 }
 function makeCompositeJayComponent(preRender, defaultViewState, fastCarryForward, parts, trackByMap = {}) {
+  const interactiveParts = parts.filter((part) => part.comp !== void 0);
   const hasFastRendering = defaultViewState !== null && defaultViewState !== void 0;
+  const headlessInstanceViewStates = defaultViewState?.__headlessInstances;
+  const headlessInstanceCarryForwards = fastCarryForward?.__headlessInstances;
+  if (headlessInstanceViewStates)
+    delete defaultViewState.__headlessInstances;
+  if (headlessInstanceCarryForwards)
+    delete fastCarryForward.__headlessInstances;
   const comp = (props, refs, ...contexts) => {
-    const instances = parts.map((part) => {
-      const partRefs = part.key ? refs[part.key] : refs;
-      let partContexts;
-      if (hasFastRendering) {
-        const partViewState = part.key ? defaultViewState?.[part.key] : defaultViewState;
-        const partFastViewState = partViewState ? makeSignals(partViewState) : void 0;
-        const partCarryForward = part.key ? fastCarryForward?.[part.key] : fastCarryForward;
-        partContexts = [
-          partFastViewState,
-          partCarryForward,
-          ...contexts.splice(0, part.contextMarkers.length)
-        ];
-      } else {
-        partContexts = [...contexts.splice(0, part.contextMarkers.length)];
+    if (headlessInstanceViewStates || headlessInstanceCarryForwards) {
+      const componentContext = useContext(COMPONENT_CONTEXT);
+      const instancesData = {
+        viewStates: headlessInstanceViewStates || {},
+        carryForwards: headlessInstanceCarryForwards || {}
+      };
+      componentContext.provideContexts.push([HEADLESS_INSTANCES, instancesData]);
+    }
+    const instances = interactiveParts.map(
+      (part) => {
+        const partRefs = part.key ? refs[part.key] : refs;
+        let partContexts;
+        if (hasFastRendering) {
+          const partViewState = part.key ? defaultViewState?.[part.key] : defaultViewState;
+          const partFastViewState = partViewState ? makeSignals(partViewState) : void 0;
+          const partCarryForward = part.key ? fastCarryForward?.[part.key] : fastCarryForward;
+          partContexts = [
+            partFastViewState,
+            partCarryForward,
+            ...contexts.splice(0, part.contextMarkers.length)
+          ];
+        } else {
+          partContexts = [...contexts.splice(0, part.contextMarkers.length)];
+        }
+        return [part.key, part.comp(props, partRefs, ...partContexts)];
       }
-      return [part.key, part.comp(props, partRefs, ...partContexts)];
-    });
+    );
     return {
       render: () => {
         let viewState = defaultViewState;
         instances.forEach(([key, instance]) => {
           const rendered = materializeViewState(instance.render());
           if (key) {
-            viewState[key] = deepMergeViewStates(
+            viewState[key] = deepMergeViewStates$1(
               defaultViewState[key],
               rendered,
               trackByMap,
               key
             );
           } else {
-            viewState = deepMergeViewStates(
+            viewState = deepMergeViewStates$1(
               viewState,
               rendered,
               trackByMap
@@ -126,7 +161,7 @@ function makeCompositeJayComponent(preRender, defaultViewState, fastCarryForward
       }
     };
   };
-  const contextMarkers = parts.reduce((cm, part) => {
+  const contextMarkers = interactiveParts.reduce((cm, part) => {
     return [...cm, ...part.contextMarkers];
   }, []);
   return makeJayComponent(
@@ -228,9 +263,264 @@ function isSimpleObject(obj) {
   }
   return true;
 }
+var __defProp2 = Object.defineProperty;
+var __defNormalProp2 = (obj, key, value) => key in obj ? __defProp2(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField2 = (obj, key, value) => {
+  __defNormalProp2(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+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) {
+    __publicField2(this, "stateListeners", /* @__PURE__ */ new Set());
+    __publicField2(this, "cachedInteractions", null);
+    __publicField2(this, "viewStateHandler", null);
+    __publicField2(this, "mergedViewState");
+    __publicField2(this, "initialSlowViewState");
+    __publicField2(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,
   ActionError,
+  HEADLESS_INSTANCES,
   createActionCaller,
   makeCompositeJayComponent,
-  setActionCallerOptions
+  makeHeadlessInstanceComponent,
+  setActionCallerOptions,
+  wrapWithAutomation
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/stack-client-runtime",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
   "license": "Apache-2.0",
   "main": "dist/index.js",
@@ -27,14 +27,15 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/component": "^0.10.0",
-    "@jay-framework/fullstack-component": "^0.10.0",
-    "@jay-framework/runtime": "^0.10.0",
-    "@jay-framework/view-state-merge": "^0.10.0"
+    "@jay-framework/component": "^0.12.0",
+    "@jay-framework/fullstack-component": "^0.12.0",
+    "@jay-framework/runtime": "^0.12.0",
+    "@jay-framework/runtime-automation": "^0.12.0",
+    "@jay-framework/view-state-merge": "^0.12.0"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.10.0",
-    "@jay-framework/jay-cli": "^0.10.0",
+    "@jay-framework/dev-environment": "^0.12.0",
+    "@jay-framework/jay-cli": "^0.12.0",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",