@qontinui/ui-bridge-native 0.3.0 → 0.3.1

package/dist/index.mjs

@@ -55,6 +55,29 @@ var NativeUIBridgeRegistry = class {
     this.eventListeners = /* @__PURE__ */ new Map();
     this.enrichers = {};
     this.snapshotExtras = /* @__PURE__ */ new Map();
+    /**
+     * App identification metadata (appId/appName/appType/framework). Set via
+     * `setAppInfo` — typically wired in the server constructor from the
+     * `NativeUIBridgeConfig` the host passes to `UIBridgeNativeProvider`.
+     *
+     * When set, `createSnapshot` includes it on the resulting snapshot so
+     * agents can identify the app from snapshot bytes alone (parity with the
+     * `uiBridge` block on the `health` response). Snapshots created before
+     * this is wired simply omit the field.
+     */
+    this.appInfo = null;
+    /**
+     * Optional route provider. When set, `createSnapshot` reads
+     * `currentRoute`/`segments` from it whenever the caller does not pass an
+     * explicit `routeInfo` argument. This lets the default `getSnapshot` HTTP
+     * handler — which has no direct reference to the `NativeUIBridgeServer`
+     * instance — still emit a populated `currentRoute` field.
+     *
+     * Wired by `NativeUIBridgeServer.setRouteProvider`, which forwards the
+     * provider into the registry alongside the per-handler overrides it
+     * already installs.
+     */
+    this.routeProvider = null;
     /**
      * Sticky flag: flips `true` the first time any element is registered and
      * stays `true` even after elements are unregistered. Lets agents distinguish
@@ -65,6 +88,34 @@ var NativeUIBridgeRegistry = class {
     this.config = config;
   }
   // ============================================================================
+  // App Info & Route Provider
+  // ============================================================================
+  /**
+   * Set the app identification metadata returned alongside snapshots.
+   * Idempotent — re-calling with the same shape is a no-op.
+   * Pass `null` (or omit a previous call) to clear.
+   */
+  setAppInfo(info) {
+    this.appInfo = info ?? null;
+  }
+  /** Read-only accessor for the registered app info, if any. */
+  getAppInfo() {
+    return this.appInfo;
+  }
+  /**
+   * Set a route provider whose `getCurrentRoute`/`getSegments` are read by
+   * `createSnapshot` when no explicit `routeInfo` argument is supplied.
+   *
+   * Call with `null` to detach (e.g. when the host swaps providers on HMR).
+   */
+  setRouteProvider(provider) {
+    this.routeProvider = provider ?? null;
+  }
+  /** Read-only accessor for the registered route provider, if any. */
+  getRouteProvider() {
+    return this.routeProvider;
+  }
+  // ============================================================================
   // Snapshot Enricher Slots
   // ============================================================================
   /**
@@ -453,12 +504,41 @@ var NativeUIBridgeRegistry = class {
   // Snapshots
   // ============================================================================
   /**
-   * Create a snapshot of the current state
+   * Create a snapshot of the current state.
+   *
+   * Route resolution: `routeInfo` wins when provided. Otherwise — and this
+   * is the path the default `getSnapshot` HTTP handler takes — we fall back
+   * to the registered `routeProvider`. This means callers that never wire a
+   * server-level override (the bare-server / cloud-relay path) still get a
+   * populated `currentRoute` field as long as `setRouteProvider` was called
+   * on the registry.
    */
   createSnapshot(routeInfo, options) {
+    const resolvedRoute = (() => {
+      if (routeInfo !== void 0) {
+        return {
+          currentRoute: routeInfo.currentRoute ?? null,
+          segments: routeInfo.segments
+        };
+      }
+      if (this.routeProvider) {
+        try {
+          return {
+            currentRoute: this.routeProvider.getCurrentRoute() ?? null,
+            segments: this.routeProvider.getSegments?.()
+          };
+        } catch (error3) {
+          if (this.config.verbose) {
+            console.warn(`[ui-bridge-native] routeProvider getCurrentRoute threw:`, error3);
+          }
+          return { currentRoute: null, segments: void 0 };
+        }
+      }
+      return { currentRoute: null, segments: void 0 };
+    })();
     let elements = options?.visibleOnly ? this.getVisibleElements() : this.getAllElements();
-    if (options?.currentRouteOnly && routeInfo?.currentRoute) {
-      const currentRoute = routeInfo.currentRoute;
+    if (options?.currentRouteOnly && resolvedRoute.currentRoute) {
+      const currentRoute = resolvedRoute.currentRoute;
       elements = elements.filter((e) => e.registrationRoute === currentRoute);
     }
     const snapshot = {
@@ -490,10 +570,13 @@ var NativeUIBridgeRegistry = class {
         description: w.description,
         stepCount: w.steps.length
       })),
-      currentRoute: routeInfo?.currentRoute ?? null,
-      segments: routeInfo?.segments,
+      currentRoute: resolvedRoute.currentRoute,
+      segments: resolvedRoute.segments,
       registration: this.getRegistrationCoverage()
     };
+    if (this.appInfo) {
+      snapshot.appInfo = this.appInfo;
+    }
     if (this.enrichers.modalDetector) {
       try {
         snapshot.modalStack = this.enrichers.modalDetector.getSnapshotModalContext();
@@ -522,7 +605,7 @@ var NativeUIBridgeRegistry = class {
       }
     }
     if (this.snapshotExtras.size > 0) {
-      const ctx = { elements, currentRoute: routeInfo?.currentRoute ?? null };
+      const ctx = { elements, currentRoute: resolvedRoute.currentRoute };
       for (const [name, fn] of this.snapshotExtras) {
         try {
           const extra = fn(ctx);
@@ -2041,7 +2124,8 @@ function createServerHandlers(registry, executor, config) {
     },
     getSnapshot: async (ctx) => {
       const visibleOnly = ctx.query?.visibleOnly === "true" || ctx.body?.visibleOnly === true;
-      const snapshot = registry.createSnapshot(void 0, { visibleOnly });
+      const currentRouteOnly = ctx.query?.currentRouteOnly === "true" || ctx.body?.currentRouteOnly === true;
+      const snapshot = registry.createSnapshot(void 0, { visibleOnly, currentRouteOnly });
       return success2(snapshot);
     },
     // Workflows
@@ -2208,6 +2292,134 @@ function createServerHandlers(registry, executor, config) {
       const failedCount = results.length - succeededCount;
       return success2({ results, succeededCount, failedCount });
     },
+    // Coord-based tap
+    //
+    // Synthesizes a press at the given screen coordinates by scanning the
+    // registered elements' layout rects for a containing match. We prefer the
+    // *topmost* match (smallest area = innermost child) since native UIs
+    // generally render parents before children, and the user's tap should
+    // logically hit the leaf-most interactive element.
+    //
+    // Coords are interpreted in the absolute (screen) space published by
+    // `measureInWindow`; we compare against `pageX/pageY` when available and
+    // fall back to the layout's relative `x/y` so this works in test fixtures
+    // that don't measure (the fallback only matches single-rooted screens but
+    // is good enough for the unit suite).
+    tapAt: async (ctx) => {
+      const body = ctx.body;
+      const x = body?.x;
+      const y = body?.y;
+      if (typeof x !== "number" || !Number.isFinite(x)) {
+        return error2('"x" must be a finite number', "INVALID_REQUEST");
+      }
+      if (typeof y !== "number" || !Number.isFinite(y)) {
+        return error2('"y" must be a finite number', "INVALID_REQUEST");
+      }
+      const action = body?.action ?? "press";
+      const allowedActions = [
+        "press",
+        "longPress",
+        "doubleTap"
+      ];
+      if (!allowedActions.includes(action)) {
+        return error2(
+          `"action" must be one of: ${allowedActions.join(", ")}`,
+          "INVALID_REQUEST"
+        );
+      }
+      const candidates = [];
+      for (const el of registry.getAllElements()) {
+        const state = el.getState();
+        const layout = state?.layout;
+        if (!layout) continue;
+        if (typeof layout.width !== "number" || typeof layout.height !== "number" || layout.width <= 0 || layout.height <= 0) {
+          continue;
+        }
+        const hasPage = typeof layout.pageX === "number" && typeof layout.pageY === "number" && Number.isFinite(layout.pageX) && Number.isFinite(layout.pageY);
+        const left = hasPage ? layout.pageX : layout.x;
+        const top = hasPage ? layout.pageY : layout.y;
+        if (x >= left && x <= left + layout.width && y >= top && y <= top + layout.height) {
+          candidates.push({
+            elementId: el.id,
+            layout,
+            area: layout.width * layout.height
+          });
+        }
+      }
+      if (candidates.length === 0) {
+        return error2(
+          `No element registered at (${x}, ${y})`,
+          "no_element_at_coords"
+        );
+      }
+      candidates.sort((a, b) => a.area - b.area);
+      const target = candidates[0];
+      const response = await executor.executeAction(target.elementId, { action });
+      if (!response.success) {
+        return error2(response.error || "Action failed", "ACTION_FAILED");
+      }
+      return success2({
+        elementId: target.elementId,
+        action,
+        layout: {
+          x: target.layout.x,
+          y: target.layout.y,
+          width: target.layout.width,
+          height: target.layout.height,
+          pageX: target.layout.pageX,
+          pageY: target.layout.pageY
+        }
+      });
+    },
+    // Observability — console error / network request ring buffers.
+    //
+    // The buffers are owned by NativeUIBridgeServer and patched onto the
+    // globals on `start()` (gated behind `features.testHooks`). When no
+    // buffer is provided (no testHooks, or a stripped-down server fixture),
+    // these handlers gracefully return empty arrays so callers can probe
+    // without 500ing.
+    getConsoleErrors: async (ctx) => {
+      const buf = config?.consoleErrorBuffer;
+      const since = ctx.query?.since !== void 0 ? Number(ctx.query.since) : void 0;
+      const limit = ctx.query?.limit !== void 0 ? Number(ctx.query.limit) : void 0;
+      if (!buf) {
+        return success2({
+          entries: [],
+          count: 0,
+          bufferSize: 0
+        });
+      }
+      const entries = buf.entries({
+        since: typeof since === "number" && Number.isFinite(since) ? since : void 0,
+        limit: typeof limit === "number" && Number.isFinite(limit) ? limit : void 0
+      });
+      return success2({
+        entries,
+        count: entries.length,
+        bufferSize: buf.size()
+      });
+    },
+    getNetworkRequests: async (ctx) => {
+      const buf = config?.networkRequestBuffer;
+      const since = ctx.query?.since !== void 0 ? Number(ctx.query.since) : void 0;
+      const limit = ctx.query?.limit !== void 0 ? Number(ctx.query.limit) : void 0;
+      if (!buf) {
+        return success2({
+          entries: [],
+          count: 0,
+          bufferSize: 0
+        });
+      }
+      const entries = buf.entries({
+        since: typeof since === "number" && Number.isFinite(since) ? since : void 0,
+        limit: typeof limit === "number" && Number.isFinite(limit) ? limit : void 0
+      });
+      return success2({
+        entries,
+        count: entries.length,
+        bufferSize: buf.size()
+      });
+    },
     // Test hooks — modal stack manipulation
     //
     // These two endpoints exist so external automation runners can drive
@@ -2309,6 +2521,266 @@ function createServerHandlers(registry, executor, config) {
   };
 }
 
+// src/server/observability.ts
+var RingBuffer = class {
+  constructor(capacity) {
+    this.capacity = capacity;
+    this.items = [];
+  }
+  push(entry) {
+    this.items.push(entry);
+    if (this.items.length > this.capacity) {
+      this.items.splice(0, this.items.length - this.capacity);
+    }
+  }
+  /**
+   * Return entries optionally filtered by `since` (timestamp ms) and capped
+   * at `limit`. Newest-end is preserved when `limit` would otherwise truncate.
+   */
+  entries(opts = {}) {
+    const { since, limit } = opts;
+    let filtered = this.items;
+    if (typeof since === "number") {
+      filtered = filtered.filter((e) => e.timestamp >= since);
+    }
+    if (typeof limit === "number" && limit >= 0 && filtered.length > limit) {
+      filtered = filtered.slice(filtered.length - limit);
+    }
+    return filtered.slice();
+  }
+  size() {
+    return this.items.length;
+  }
+  clear() {
+    this.items.length = 0;
+  }
+};
+function formatConsoleArgs(args) {
+  return args.map((a) => {
+    if (a instanceof Error) return a.message;
+    if (typeof a === "string") return a;
+    try {
+      return JSON.stringify(a);
+    } catch {
+      return String(a);
+    }
+  }).join(" ");
+}
+function extractStack(args) {
+  for (const a of args) {
+    if (a instanceof Error && a.stack) return a.stack;
+  }
+  return void 0;
+}
+var ConsoleErrorBuffer = class {
+  constructor(capacity = 100) {
+    this.installed = false;
+    this.buffer = new RingBuffer(capacity);
+  }
+  install() {
+    if (this.installed) return;
+    if (typeof console === "undefined") return;
+    this.originalError = console.error;
+    this.originalWarn = console.warn;
+    const buffer = this.buffer;
+    const origError = this.originalError;
+    const origWarn = this.originalWarn;
+    console.error = (...args) => {
+      try {
+        buffer.push({
+          timestamp: Date.now(),
+          level: "error",
+          message: formatConsoleArgs(args),
+          stack: extractStack(args)
+        });
+      } catch {
+      }
+      origError.apply(console, args);
+    };
+    console.warn = (...args) => {
+      try {
+        buffer.push({
+          timestamp: Date.now(),
+          level: "warn",
+          message: formatConsoleArgs(args),
+          stack: extractStack(args)
+        });
+      } catch {
+      }
+      origWarn.apply(console, args);
+    };
+    this.installed = true;
+  }
+  uninstall() {
+    if (!this.installed) return;
+    if (typeof console === "undefined") return;
+    if (this.originalError) console.error = this.originalError;
+    if (this.originalWarn) console.warn = this.originalWarn;
+    this.originalError = void 0;
+    this.originalWarn = void 0;
+    this.installed = false;
+  }
+  entries(opts = {}) {
+    return this.buffer.entries(opts);
+  }
+  size() {
+    return this.buffer.size();
+  }
+  clear() {
+    this.buffer.clear();
+  }
+  isInstalled() {
+    return this.installed;
+  }
+};
+function extractUrl(input) {
+  if (typeof input === "string") return input;
+  if (input && typeof input === "object") {
+    const obj = input;
+    if (typeof obj.url === "string") return obj.url;
+    try {
+      return String(input);
+    } catch {
+      return "";
+    }
+  }
+  return "";
+}
+function extractMethod(input, init) {
+  if (init && typeof init.method === "string") return init.method.toUpperCase();
+  if (input && typeof input === "object") {
+    const obj = input;
+    if (typeof obj.method === "string") return obj.method.toUpperCase();
+  }
+  return "GET";
+}
+var NetworkRequestBuffer = class {
+  constructor(capacity = 100) {
+    this.installed = false;
+    this.buffer = new RingBuffer(capacity);
+  }
+  install() {
+    if (this.installed) return;
+    const g = globalThis;
+    if (typeof g.fetch === "function") {
+      this.originalFetch = g.fetch;
+      const buffer = this.buffer;
+      const original = this.originalFetch;
+      const patched = async (input, init) => {
+        const start = Date.now();
+        const url = extractUrl(input);
+        const method = extractMethod(input, init);
+        try {
+          const res = await original.call(globalThis, input, init);
+          buffer.push({
+            timestamp: start,
+            method,
+            url,
+            status: res.status,
+            durationMs: Date.now() - start,
+            ok: res.ok
+          });
+          return res;
+        } catch (err) {
+          buffer.push({
+            timestamp: start,
+            method,
+            url,
+            status: 0,
+            durationMs: Date.now() - start,
+            ok: false,
+            error: err instanceof Error ? err.message : String(err)
+          });
+          throw err;
+        }
+      };
+      g.fetch = patched;
+    }
+    if (typeof g.XMLHttpRequest === "function") {
+      const Xhr = g.XMLHttpRequest;
+      this.originalXhrOpen = Xhr.prototype.open;
+      this.originalXhrSend = Xhr.prototype.send;
+      const buffer = this.buffer;
+      const origOpen = this.originalXhrOpen;
+      Xhr.prototype.open = function(method, url, ...rest) {
+        this.__uiBridgeMethod = method.toUpperCase();
+        this.__uiBridgeUrl = typeof url === "string" ? url : String(url);
+        return origOpen.call(
+          this,
+          method,
+          url,
+          ...rest
+        );
+      };
+      const origSend = this.originalXhrSend;
+      Xhr.prototype.send = function(body) {
+        const start = Date.now();
+        const method = this.__uiBridgeMethod ?? "GET";
+        const url = this.__uiBridgeUrl ?? "";
+        const finalize = (status, ok, error3) => {
+          buffer.push({
+            timestamp: start,
+            method,
+            url,
+            status,
+            durationMs: Date.now() - start,
+            ok,
+            error: error3
+          });
+        };
+        const onLoadEnd = () => {
+          this.removeEventListener("loadend", onLoadEnd);
+          this.removeEventListener("error", onError);
+          finalize(this.status, this.status >= 200 && this.status < 300);
+        };
+        const onError = () => {
+          this.removeEventListener("loadend", onLoadEnd);
+          this.removeEventListener("error", onError);
+          finalize(0, false, "XMLHttpRequest error");
+        };
+        this.addEventListener("loadend", onLoadEnd);
+        this.addEventListener("error", onError);
+        return origSend.call(
+          this,
+          body
+        );
+      };
+    }
+    this.installed = true;
+  }
+  uninstall() {
+    if (!this.installed) return;
+    const g = globalThis;
+    if (this.originalFetch) {
+      g.fetch = this.originalFetch;
+      this.originalFetch = void 0;
+    }
+    if (typeof g.XMLHttpRequest === "function") {
+      if (this.originalXhrOpen) {
+        g.XMLHttpRequest.prototype.open = this.originalXhrOpen;
+      }
+      if (this.originalXhrSend) {
+        g.XMLHttpRequest.prototype.send = this.originalXhrSend;
+      }
+    }
+    this.originalXhrOpen = void 0;
+    this.originalXhrSend = void 0;
+    this.installed = false;
+  }
+  entries(opts = {}) {
+    return this.buffer.entries(opts);
+  }
+  size() {
+    return this.buffer.size();
+  }
+  clear() {
+    this.buffer.clear();
+  }
+  isInstalled() {
+    return this.installed;
+  }
+};
+
 // src/server/ws-types.ts
 function isBatchRequest(msg) {
   return typeof msg === "object" && msg !== null && "batch" in msg && Array.isArray(msg.batch);
@@ -2359,6 +2831,10 @@ var WS_ROUTES = [
   },
   // Discovery
   { pattern: "control/find", handler: "find", httpMethods: ["POST"] },
+  // Runner-parity alias for `control/find`; the runner exposes its
+  // AI-powered element search at `/ui-bridge/ai/find`, so mobile mounts the
+  // same handler at both paths to keep agents portable across platforms.
+  { pattern: "ai/find", handler: "find", httpMethods: ["POST"] },
   { pattern: "control/snapshot", handler: "getSnapshot", httpMethods: ["GET"] },
   { pattern: "control/discover", handler: "getSnapshot" },
   // Workflows
@@ -2397,6 +2873,9 @@ 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"] },
+  // 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"] },
   // Test hooks — gated behind `features.testHooks`. Let external runners
   // drive the ModalDetector over HTTP so tests can flip `snapshot.modalStack`
   // without mounting React components.
@@ -2411,6 +2890,20 @@ var WS_ROUTES = [
     handler: "dismissModal",
     httpMethods: ["POST"],
     requiresTestHooks: true
+  },
+  // Observability — last-N console errors + network requests. testHooks-gated
+  // because patching `console.error` / `fetch` is invasive in production.
+  {
+    pattern: "control/console-errors",
+    handler: "getConsoleErrors",
+    httpMethods: ["GET"],
+    requiresTestHooks: true
+  },
+  {
+    pattern: "sdk/network-requests",
+    handler: "getNetworkRequests",
+    httpMethods: ["GET"],
+    requiresTestHooks: true
   }
 ];
 var HANDLER_DESCRIPTIONS = {
@@ -2446,6 +2939,9 @@ 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`",
+  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>",
   pushModal: "TEST HOOK \u2014 push a modal onto the snapshot.modalStack via the registry ModalDetector",
   dismissModal: "TEST HOOK \u2014 dismiss a modal by id from the snapshot.modalStack via the registry ModalDetector"
 };
@@ -2514,8 +3010,15 @@ var NativeUIBridgeServer = class {
       cors: true,
       ...config
     };
+    this.consoleErrorBuffer = new ConsoleErrorBuffer();
+    this.networkRequestBuffer = new NetworkRequestBuffer();
+    if (this.config.appInfo) {
+      this.registry.setAppInfo(this.config.appInfo);
+    }
     this.handlers = createServerHandlers(registry, executor, {
-      appInfo: this.config.appInfo
+      appInfo: this.config.appInfo,
+      consoleErrorBuffer: this.consoleErrorBuffer,
+      networkRequestBuffer: this.networkRequestBuffer
     });
     this.handlers.getMethods = async () => {
       const testHooks = this.config.testHooks === true;
@@ -2643,8 +3146,16 @@ var NativeUIBridgeServer = class {
   /**
    * Set a route provider for reporting the current navigation route.
    * When set, `control/snapshot` responses include `currentRoute` and `segments`.
+   *
+   * Also forwards the provider into the registry so the *default*
+   * `getSnapshot` handler (and any other call site of
+   * `registry.createSnapshot`) reads the route too — without this the
+   * cloud-relay/bare-server path returned `currentRoute: null` even when
+   * a `RouteTracker` was wired, because that path never installed the
+   * server-level handler override below.
    */
   setRouteProvider(provider) {
+    this.registry.setRouteProvider(provider);
     const baseGetElements = this.handlers.getElements;
     this.handlers.getElements = async (ctx) => {
       const currentRouteOnly = ctx.query?.currentRouteOnly === "true" || ctx.body?.currentRouteOnly === true;
@@ -2713,6 +3224,10 @@ var NativeUIBridgeServer = class {
       console.warn("[ui-bridge-native] See documentation for supported adapters.");
       return;
     }
+    if (this.config.testHooks === true) {
+      this.consoleErrorBuffer.install();
+      this.networkRequestBuffer.install();
+    }
     await this.adapter.start(this.config.serverPort, this.handleRequest.bind(this));
     this.running = true;
     console.log(`[ui-bridge-native] HTTP server started on port ${this.config.serverPort}`);
@@ -2726,6 +3241,8 @@ var NativeUIBridgeServer = class {
     }
     await this.adapter.stop();
     this.running = false;
+    this.consoleErrorBuffer.uninstall();
+    this.networkRequestBuffer.uninstall();
     console.log("[ui-bridge-native] HTTP server stopped");
   }
   /**
@@ -4554,56 +5071,35 @@ function useUIElement(options) {
     registeredIdRef.current = null;
     setRegistered(false);
   }, [bridge, id]);
+  const onStateChangeRef = useRef(onStateChange);
+  useEffect(() => {
+    onStateChangeRef.current = onStateChange;
+  }, [onStateChange]);
   const onLayout = useCallback(
     (event) => {
       const { x, y, width, height } = event.nativeEvent.layout;
+      const writeLayout = (newLayout) => {
+        setLayout(newLayout);
+        if (!bridge) return;
+        const newState = {
+          mounted: true,
+          visible: width > 0 && height > 0,
+          enabled: true,
+          focused: false,
+          layout: newLayout
+        };
+        bridge.registry.updateElementState(id, newState);
+        onStateChangeRef.current?.(newState);
+      };
       if (ref.current && "measureInWindow" in ref.current) {
         ref.current.measureInWindow((pageX, pageY) => {
-          const newLayout = {
-            x,
-            y,
-            width,
-            height,
-            pageX,
-            pageY
-          };
-          setLayout(newLayout);
-          if (bridge && registered) {
-            const newState = {
-              mounted: true,
-              visible: width > 0 && height > 0,
-              enabled: true,
-              focused: false,
-              layout: newLayout
-            };
-            bridge.registry.updateElementState(id, newState);
-            onStateChange?.(newState);
-          }
+          writeLayout({ x, y, width, height, pageX, pageY });
         });
       } else {
-        const newLayout = {
-          x,
-          y,
-          width,
-          height,
-          pageX: x,
-          pageY: y
-        };
-        setLayout(newLayout);
-        if (bridge && registered) {
-          const newState = {
-            mounted: true,
-            visible: width > 0 && height > 0,
-            enabled: true,
-            focused: false,
-            layout: newLayout
-          };
-          bridge.registry.updateElementState(id, newState);
-          onStateChange?.(newState);
-        }
+        writeLayout({ x, y, width, height, pageX: x, pageY: y });
       }
     },
-    [bridge, registered, id, onStateChange]
+    [bridge, id]
   );
   const registerRef = useRef(register);
   const unregisterRef = useRef(unregister);
@@ -4621,6 +5117,37 @@ function useUIElement(options) {
       }
     };
   }, [autoRegister, bridge]);
+  useEffect(() => {
+    if (!bridge || !registered) return;
+    const node = ref.current;
+    if (!node || typeof node.measureInWindow !== "function") return;
+    let cancelled = false;
+    node.measureInWindow((pageX, pageY, w, h) => {
+      if (cancelled) return;
+      if (w <= 0 || h <= 0) return;
+      const newLayout = {
+        x: pageX,
+        y: pageY,
+        width: w,
+        height: h,
+        pageX,
+        pageY
+      };
+      setLayout(newLayout);
+      const newState = {
+        mounted: true,
+        visible: true,
+        enabled: true,
+        focused: false,
+        layout: newLayout
+      };
+      bridge.registry.updateElementState(id, newState);
+      onStateChangeRef.current?.(newState);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [bridge, registered, id]);
   const registeredHandlerKeysRef = useRef([]);
   useEffect(() => {
     if (!bridge || !registered || !handlersProp) return;