@qontinui/ui-bridge-native 0.5.1 → 0.6.2

package/dist/react/useUIElement.d.ts

@@ -4,14 +4,33 @@
  * Register a native element with UI Bridge for control and observation.
  */
 import type { NativeElementType, NativeStandardAction, NativeCustomAction, NativeElementState, NativeElementIdentifier, RegisteredNativeElement, NativeElementRef } from '../core/types';
+type AnyHandler = (...args: any[]) => any;
 /**
- * useUIElement options
+ * A press handler for `button`/`pressable` types. Matches the loose RN
+ * `Pressable` `onPress` shape (no required argument), so consumers can pass
+ * either a no-arg callback or one that consumes the gesture event.
  */
-export interface UseUIElementOptions {
+export type PressHandler = (event?: unknown) => void;
+/**
+ * Element types that require a press handler at registration. The TS
+ * signature on `useUIElement` rejects these types unless `handlers.onPress`
+ * is provided in options.
+ *
+ * Picked from the action-executor in `control/action-executor.ts` — the
+ * `press` action looks up `props.onPress` (or `onPressIn` /
+ * `onResponderRelease`); registering a button without one is a guaranteed
+ * dead-button per the 2026-05-20 manual-test session.
+ */
+export type PressNeedingNativeElementType = 'button' | 'pressable';
+/**
+ * Base options for `useUIElement`. The discriminated union below layers
+ * `handlers` requirements on top of this — see {@link UseUIElementOptions}.
+ */
+export interface UseUIElementOptionsBase<T extends NativeElementType = NativeElementType> {
     /** Unique identifier for the element */
     id: string;
     /** Element type (defaults to 'custom') */
-    type?: NativeElementType;
+    type?: T;
     /** Human-readable label */
     label?: string;
     /** Override available actions */
@@ -32,10 +51,24 @@ export interface UseUIElementOptions {
         focused?: unknown;
         disabled?: unknown;
     };
+}
+/**
+ * Options shape for press-needing types — `handlers.onPress` is REQUIRED.
+ * Registering a `button`/`pressable` without an `onPress` produces a
+ * "No press handler found on element" error when the bridge fires
+ * `POST /control/element/:id/action {"action":"press"}`. Phase 1 of plan
+ * `2026-05-20-manual-test-remediation` makes that a compile-time error.
+ *
+ * Consumers that wire `onPress` lazily (e.g. computed from props during
+ * render) should use {@link useUIElementWithProps} + `captureProps({ onPress })`
+ * instead. The runtime guard in this hook also warns once per id when
+ * `onPress` never reaches the registry.
+ */
+export interface UseUIElementOptionsHandlersRequired<T extends PressNeedingNativeElementType = PressNeedingNativeElementType> extends UseUIElementOptionsBase<T> {
     /**
      * Handler props to auto-register with the bridge for action execution.
-     * When provided, the bridge can invoke these handlers via press/type/toggle actions
-     * without the component needing a separate useEffect + updateElementProps call.
+     * For `button`/`pressable`, `onPress` is required — UI Bridge invokes it
+     * when a `press` action is dispatched.
      *
      * @example
      * ```tsx
@@ -46,8 +79,32 @@ export interface UseUIElementOptions {
      * });
      * ```
      */
-    handlers?: Record<string, ((...args: any[]) => any) | undefined>;
+    handlers: {
+        /** Required — UI Bridge invokes this on `press`/`click` actions. */
+        onPress: PressHandler;
+        /** Additional handlers (`onLongPress`, `onPressIn`, etc.) */
+        [key: string]: AnyHandler | undefined;
+    };
+}
+/**
+ * Options shape for non-press-needing types — `handlers` is optional.
+ * Applies to `input`, `text`, `view`, `list`, etc. — anything where a
+ * missing `onPress` doesn't indicate a dead button.
+ */
+export interface UseUIElementOptionsHandlersOptional<T extends NativeElementType = NativeElementType> extends UseUIElementOptionsBase<T> {
+    /**
+     * Handler props to auto-register with the bridge for action execution.
+     * Optional for non-press-needing types.
+     */
+    handlers?: Record<string, AnyHandler | undefined>;
 }
+/**
+ * useUIElement options — discriminated union over element type.
+ *
+ * For `type: 'button' | 'pressable'`, `handlers.onPress` is required.
+ * For all other types, `handlers` is optional.
+ */
+export type UseUIElementOptions<T extends NativeElementType = NativeElementType> = T extends PressNeedingNativeElementType ? UseUIElementOptionsHandlersRequired<T> : UseUIElementOptionsHandlersOptional<T>;
 /**
  * Bridge props to spread onto the component
  */
@@ -96,35 +153,27 @@ export interface UseUIElementReturn {
         focused?: unknown;
         disabled?: unknown;
     }) => void;
+    /**
+     * Re-publish the element's label (and the mirrored `accessibilityLabel` /
+     * `testId` so spec-check and a11y stay in sync). Idempotent — no-op when
+     * the new label equals the current registered value.
+     *
+     * Labels passed via `useUIElement({ id, label })` are captured ONCE at
+     * registration; if the source state changes (e.g. a tab's active suffix,
+     * or a list's "N events" count), the registry would otherwise hold the
+     * mount-time label forever. Call `updateLabel(...)` from a `useEffect`
+     * (or directly from a handler) to keep the registry in sync.
+     *
+     * @example
+     * ```tsx
+     * const label = `${events.length} events`;
+     * const { updateLabel } = useUIElement({ id: 'events-list', label, type: 'list' });
+     * useEffect(() => { updateLabel(label); }, [label, updateLabel]);
+     * ```
+     */
+    updateLabel: (newLabel: string) => void;
 }
-/**
- * useUIElement hook for React Native
- *
- * Registers a native element with UI Bridge for programmatic control.
- *
- * @example
- * ```tsx
- * function SubmitButton() {
- *   const { ref, onLayout, bridgeProps, trigger } = useUIElement({
- *     id: 'submit-btn',
- *     type: 'button',
- *     label: 'Submit Form',
- *   });
- *
- *   return (
- *     <Pressable
- *       ref={ref}
- *       onLayout={onLayout}
- *       {...bridgeProps}
- *       onPress={() => handleSubmit()}
- *     >
- *       <Text>Submit</Text>
- *     </Pressable>
- *   );
- * }
- * ```
- */
-export declare function useUIElement(options: UseUIElementOptions): UseUIElementReturn;
+export declare function useUIElement<T extends NativeElementType = NativeElementType>(options: UseUIElementOptions<T>): UseUIElementReturn;
 /**
  * useUIElementWithProps hook
  *
@@ -158,5 +207,13 @@ export interface UseUIElementWithPropsReturn extends UseUIElementReturn {
     /** Capture props for action execution */
     captureProps: (props: Record<string, unknown>) => void;
 }
-export declare function useUIElementWithProps(options: UseUIElementOptions): UseUIElementWithPropsReturn;
+/**
+ * Loose options for `useUIElementWithProps` — `handlers` is optional for ALL
+ * element types because the consumer will later call `captureProps({ onPress,
+ * ... })` from the render body. The runtime warning in {@link useUIElement}
+ * still backstops the "captured but never called with onPress" case.
+ */
+export type UseUIElementWithPropsOptions<T extends NativeElementType = NativeElementType> = UseUIElementOptionsHandlersOptional<T>;
+export declare function useUIElementWithProps<T extends NativeElementType = NativeElementType>(options: UseUIElementWithPropsOptions<T>): UseUIElementWithPropsReturn;
+export {};
 //# sourceMappingURL=useUIElement.d.ts.map

package/dist/react/useUIElement.d.ts.map

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

package/dist/server/handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/server/handlers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,sBAAsB,EAAuB,MAAM,kBAAkB,CAAC;AAQpF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,KAAK,EAQV,oBAAoB,EAKrB,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AA+PhF;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,sBAAsB,EAChC,QAAQ,EAAE,oBAAoB,EAC9B,MAAM,CAAC,EAAE;IACP,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAClF,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,iFAAiF;IACjF,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;CAC7C,GACA,oBAAoB,CA8vBtB"}
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/server/handlers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,sBAAsB,EAAuB,MAAM,kBAAkB,CAAC;AAQpF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,KAAK,EAQV,oBAAoB,EAKrB,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AA+PhF;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,sBAAsB,EAChC,QAAQ,EAAE,oBAAoB,EAC9B,MAAM,CAAC,EAAE;IACP,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAClF,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,iFAAiF;IACjF,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;CAC7C,GACA,oBAAoB,CAkzBtB"}

package/dist/server/http-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../../src/server/http-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,oBAAoB,EAA0B,MAAM,kBAAkB,CAAC;AACrF,OAAO,KAAK,EACV,kBAAkB,EAElB,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EAGlB,MAAM,SAAS,CAAC;AAIjB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAiTlE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAE7E;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,uBAAuB;IACvB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,sBAAsB;IACtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,iCAAiC;IACjC,SAAS,IAAI,OAAO,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAuB,SAAQ,aAAa;IAC3D,mGAAmG;IACnG,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACjF,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,sDAAsD;IACtD,qBAAqB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,wDAAwD;IACxD,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D,kDAAkD;IAClD,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AAED;;GAEG;AACH,qBAAa,oBAAoB;IAuB7B,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,QAAQ;IAvBlB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,OAAO,CAAC,CAAgB;IAChC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,iBAAiB,CAAC,CAAoB;IAC9C;;;;OAIG;IACH,OAAO,CAAC,cAAc,CAAsC;IAE5D;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,oBAAoB,CAAuB;gBAGzC,QAAQ,EAAE,sBAAsB,EAChC,QAAQ,EAAE,oBAAoB,EACtC,MAAM,GAAE,kBAAuB;IA6CjC;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAIxC;;;OAGG;IACH,qBAAqB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI;IAiGzD;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IAsC/C;;;OAGG;IACH,qBAAqB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI;IA6BzD;;;;OAIG;IACH,oBAAoB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IA4BvD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAyB5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAe3B;;OAEG;IACH,SAAS,IAAI,OAAO;IAMpB,OAAO,CAAC,WAAW,CAAC,CAAuB;IAE3C;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI;IAIlD;;;;OAIG;IACG,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA4IxF;;OAEG;IACG,kBAAkB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAwB7E;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAetB;;;;OAIG;IACH,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAa/C;;;OAGG;YACW,oBAAoB;IAwHlC;;;;;;;;;;;OAWG;YACW,sBAAsB;IAmJpC;;;OAGG;YACW,cAAc;IA6E5B;;;;;;;;;;;OAWG;YACW,oBAAoB;IAgClC;;;;;OAKG;IACG,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAuDhE;;;;;;;;;;;OAWG;YACW,YAAY;CAuE3B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,sBAAsB,EAChC,QAAQ,EAAE,oBAAoB,EAC9B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,oBAAoB,CAEtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG"}
+{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../../src/server/http-server.ts"],"names":[],"mappings":"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"}

package/dist/server/index.js

@@ -141,6 +141,31 @@ var UI_BRIDGE_NATIVE_ROUTES = {
     path: "/ui-bridge/ai/fill-form",
     description: "Fill multiple input elements in a single call"
   },
+  // AI helpers (NOT_SUPPORTED stubs) — these endpoints exist on the runner-side
+  // UI Bridge surface but have no analog on mobile React Native. The mobile
+  // bridge registers explicit stubs so callers get a structured NOT_SUPPORTED
+  // envelope instead of a confusing HTTP 404. The mobile bridge's snapshot +
+  // `/control/find` already cover what an operator would reach for these for.
+  AI_FORMS: {
+    method: "GET",
+    path: "/ui-bridge/ai/forms",
+    description: "Discover forms (runner-only; mobile returns NOT_SUPPORTED)"
+  },
+  AI_IDLE_STATUS: {
+    method: "GET",
+    path: "/ui-bridge/ai/idle-status",
+    description: "Get page-idle signal (runner-only; mobile returns NOT_SUPPORTED)"
+  },
+  AI_CHANGE_BUFFER_ENABLE: {
+    method: "POST",
+    path: "/ui-bridge/ai/change-buffer/enable",
+    description: "Enable DOM change buffer (runner-only; mobile returns NOT_SUPPORTED)"
+  },
+  AI_WAIT_FOR_ELEMENT: {
+    method: "POST",
+    path: "/ui-bridge/ai/wait-for-element",
+    description: "Wait for element predicate via HTTP (runner-only; mobile returns NOT_SUPPORTED \u2014 use WS waitForElement instead)"
+  },
   // Test hooks — drive ModalDetector state from outside the React tree
   // (gated by `features.testHooks`). Mirrors `pushModal` / `dismissModal`
   // calls that components normally make in-process.
@@ -847,22 +872,25 @@ function createServerHandlers(registry, executor, config) {
     getElements: async (ctx) => {
       const visibleOnly = ctx.query?.visibleOnly === "true" || ctx.body?.visibleOnly === true;
       const forRoute = ctx.query?.route || ctx.body?.route;
-      let allElements = visibleOnly ? registry.getVisibleElements() : registry.getAllElements();
+      let allElements = visibleOnly ? registry.getMountedVisibleElements() : registry.getAllElements();
       if (forRoute) {
         allElements = allElements.filter((e) => e.registrationRoute === forRoute);
       }
       const elements = allElements.map((e) => {
         const handlers = extractHandlerNames(e.props);
+        const state = e.getState();
+        const visibility = !state.visible ? "hidden" : state.layout !== null ? "visible" : "likely-visible";
         return {
           id: e.id,
           type: e.type,
           label: e.label,
           identifier: e.getIdentifier(),
-          state: e.getState(),
+          state,
           actions: e.actions,
           customActions: e.customActions ? Object.keys(e.customActions) : void 0,
           registeredHandlers: handlers.length > 0 ? handlers : void 0,
-          registrationRoute: e.registrationRoute
+          registrationRoute: e.registrationRoute,
+          visibility
         };
       });
       return success2({ elements });
@@ -1125,6 +1153,37 @@ function createServerHandlers(registry, executor, config) {
         "NOT_SUPPORTED"
       );
     },
+    // AI helpers — runner-only endpoints that have no React Native analog.
+    //
+    // The mobile bridge mounts explicit NOT_SUPPORTED stubs at the runner's
+    // cheatsheet paths so callers (and the /manual-test skill in particular)
+    // get a structured envelope explaining the gap rather than a confusing
+    // HTTP 404. Each error message names an in-tree mobile replacement so
+    // operators aren't left guessing what to use instead.
+    aiForms: async () => {
+      return error2(
+        'ai/forms (form discovery) is runner-only; mobile React Native has no DOM to walk. Use GET /ui-bridge/control/snapshot and filter for type === "input" instead.',
+        "NOT_SUPPORTED"
+      );
+    },
+    aiIdleStatus: async () => {
+      return error2(
+        'ai/idle-status (page-idle signal) is runner-only; mobile React Native has no DOM-mutation / network-idle signals. Use the registry event stream (WS subscribe to "element:registered"/"element:stateChanged") or poll /control/snapshot for stability.',
+        "NOT_SUPPORTED"
+      );
+    },
+    aiChangeBufferEnable: async () => {
+      return error2(
+        'ai/change-buffer (DOM mutation diff buffer) is runner-only; mobile React Native has no DOM. Use the WS event bridge (subscribe to "element:registered"/"element:unregistered"/"element:stateChanged") for change notifications.',
+        "NOT_SUPPORTED"
+      );
+    },
+    aiWaitForElement: async () => {
+      return error2(
+        'POST /ai/wait-for-element is runner-only on mobile. Use the WS "waitForElement" JSON-RPC method or "waitForCondition" instead \u2014 same semantics, no HTTP polling overhead.',
+        "NOT_SUPPORTED"
+      );
+    },
     // Meta / Introspection (stub — server constructor overrides with real route table)
     getMethods: async () => {
       return error2("Methods introspection not configured", "NOT_SUPPORTED");
@@ -1780,6 +1839,24 @@ var WS_ROUTES = [
   { pattern: "meta/methods", handler: "getMethods", httpMethods: ["GET"] },
   // AI helpers — mobile parity with the runner's `/ui-bridge/ai/*` family.
   { pattern: "ai/fill-form", handler: "fillForm", httpMethods: ["POST"] },
+  // AI helpers — NOT_SUPPORTED stubs. These endpoints exist on the runner-side
+  // UI Bridge surface (and the /manual-test skill's cheatsheet documents them
+  // as if they're universally available). Mobile React Native has no DOM, so
+  // the mobile bridge mounts explicit stubs so callers get a structured
+  // NOT_SUPPORTED envelope (with a hint pointing at the mobile-native
+  // replacement) instead of a confusing HTTP 404.
+  { pattern: "ai/forms", handler: "aiForms", httpMethods: ["GET"] },
+  { pattern: "ai/idle-status", handler: "aiIdleStatus", httpMethods: ["GET"] },
+  {
+    pattern: "ai/change-buffer/enable",
+    handler: "aiChangeBufferEnable",
+    httpMethods: ["POST"]
+  },
+  {
+    pattern: "ai/wait-for-element",
+    handler: "aiWaitForElement",
+    httpMethods: ["POST"]
+  },
   // Coord-based tap — synthesizes a press at the given screen coords by
   // matching against registered elements' layout rects.
   { pattern: "control/tap", handler: "tapAt", httpMethods: ["POST"] },
@@ -1852,6 +1929,10 @@ var HANDLER_DESCRIPTIONS = {
   diffBaseline: "Diff current UI against a saved baseline",
   getMethods: "List every handler name (legacy introspection)",
   fillForm: "Fill multiple inputs in one call: body { fields: [{elementId, value}] } \u2014 each field dispatches `type` + `clear:true`",
+  aiForms: 'STUB \u2014 runner-only; mobile returns NOT_SUPPORTED. Use /control/snapshot + filter type==="input" instead.',
+  aiIdleStatus: "STUB \u2014 runner-only; mobile returns NOT_SUPPORTED. Subscribe to registry events over WS for change signals.",
+  aiChangeBufferEnable: "STUB \u2014 runner-only; mobile returns NOT_SUPPORTED. Use WS event subscriptions for change notifications.",
+  aiWaitForElement: "STUB \u2014 runner-only; mobile returns NOT_SUPPORTED. Use the WS waitForElement / waitForCondition JSON-RPC methods.",
   tapAt: "Synthesize a press at given screen coords by matching registered element layout rects: body { x, y, action? }",
   getConsoleErrors: "TEST HOOK \u2014 last-N console.error/console.warn entries; ?since=<ms>&limit=<n>",
   getNetworkRequests: "TEST HOOK \u2014 last-N fetch/XHR entries with status + duration; ?since=<ms>&limit=<n>",