@qontinui/ui-bridge-native 0.6.11 → 0.6.13

package/dist/server/index.mjs

@@ -7,12 +7,31 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 
 // src/server/types.ts
 var UI_BRIDGE_NATIVE_ROUTES = {
+  // Discovery / introspection — the two endpoints an agent hits first to learn
+  // the rest of this table without reading docs. Special-cased in
+  // `routeRequest` rather than living in `WS_ROUTES`, and appended by
+  // `buildRoutesPayload` so `_routes` describes itself.
+  HELP: {
+    method: "GET",
+    path: "/ui-bridge/_help",
+    description: "Route index + action reference + tips (rich discovery payload)"
+  },
+  ROUTES: {
+    method: "GET",
+    path: "/ui-bridge/_routes",
+    description: "Minimal {method, path} route list, matching the runner /_routes shape"
+  },
   // Control - Elements
   GET_ELEMENTS: {
     method: "GET",
     path: "/ui-bridge/control/elements",
     description: "List all registered elements"
   },
+  GET_ELEMENTS_FLAT: {
+    method: "GET",
+    path: "/ui-bridge/elements",
+    description: "List all registered elements (flat alias matching the runner path)"
+  },
   GET_ELEMENT: {
     method: "GET",
     path: "/ui-bridge/control/element/:id",
@@ -50,6 +69,11 @@ var UI_BRIDGE_NATIVE_ROUTES = {
     path: "/ui-bridge/control/find",
     description: "Find elements matching criteria"
   },
+  AI_FIND: {
+    method: "POST",
+    path: "/ui-bridge/ai/find",
+    description: "Find elements matching criteria (runner-parity alias for /control/find)"
+  },
   GET_SNAPSHOT: {
     method: "GET",
     path: "/ui-bridge/control/snapshot",
@@ -60,11 +84,78 @@ var UI_BRIDGE_NATIVE_ROUTES = {
     path: "/ui-bridge/control/discover",
     description: "Discover elements (alias for snapshot; web/runner parity)"
   },
+  DISCOVER_POST: {
+    method: "POST",
+    path: "/ui-bridge/control/discover",
+    description: "Discover elements over POST (same handler as the GET form; web/runner parity)"
+  },
   PAGE_HEALTH: {
     method: "POST",
     path: "/ui-bridge/control/page-health",
     description: "Holistic page health diagnostic: spatial coverage, layout regions, text signals, interactive readiness, anomalies + ASCII heatmap"
   },
+  PAGE_HEALTH_GET: {
+    method: "GET",
+    path: "/ui-bridge/control/page-health",
+    description: "Page health diagnostic over GET, for ad-hoc curls with no body"
+  },
+  // Screenshots — GET and POST both accepted so a curl works either way.
+  //
+  // Both keys carry an explicit verb suffix. The pre-existing multi-verb pairs
+  // do not agree on what an UNSUFFIXED key means — `DISCOVER` is the GET and
+  // `PAGE_HEALTH` is the POST — so a consumer reading `ROUTES.<NAME>.method`
+  // off a bare name gets opposite verbs from equally unmarked keys. Those two
+  // names are load-bearing for existing consumers and are left alone; new
+  // multi-verb entries name their verb rather than entrenching the ambiguity.
+  SCREENSHOT_GET: {
+    method: "GET",
+    path: "/ui-bridge/control/screenshot",
+    description: "PNG screenshot of the current screen"
+  },
+  SCREENSHOT_POST: {
+    method: "POST",
+    path: "/ui-bridge/control/screenshot",
+    description: "PNG screenshot of the current screen (POST form)"
+  },
+  // Coordinate-based interaction
+  CONTROL_TAP: {
+    method: "POST",
+    path: "/ui-bridge/control/tap",
+    description: "Synthesize a press at screen coords by matching registered element layout rects: body { x, y, action? }"
+  },
+  // App-agnostic interaction parity with the web/runner surface. The
+  // selector-based pair has no RN analog and answers NOT_SUPPORTED (501).
+  PAGE_CLICK_BY_TEXT: {
+    method: "POST",
+    path: "/ui-bridge/control/page/click-by-text",
+    description: "Press the first element matching free text: body { text, visibleOnly? }"
+  },
+  PAGE_CLICK_BY_SELECTOR: {
+    method: "POST",
+    path: "/ui-bridge/control/page/click-by-selector",
+    description: "Selector-based press (web-only; mobile returns NOT_SUPPORTED)"
+  },
+  PAGE_TYPE_INTO: {
+    method: "POST",
+    path: "/ui-bridge/control/page/type-into",
+    description: "Type into the input matching a label: body { label, text, clear?, visibleOnly? }"
+  },
+  PAGE_READ_VALUE: {
+    method: "POST",
+    path: "/ui-bridge/control/page/read-value",
+    description: "Selector-based value read (web-only; mobile returns NOT_SUPPORTED)"
+  },
+  PAGE_FIND_BY_TEXT: {
+    method: "POST",
+    path: "/ui-bridge/control/page/find-by-text",
+    description: "List elements matching free text without pressing: body { text, visibleOnly? }"
+  },
+  // Meta
+  META_METHODS: {
+    method: "GET",
+    path: "/ui-bridge/meta/methods",
+    description: "List every handler name (legacy introspection; prefer /_routes)"
+  },
   // Workflows
   GET_WORKFLOWS: {
     method: "GET",
@@ -143,6 +234,27 @@ var UI_BRIDGE_NATIVE_ROUTES = {
     path: "/ui-bridge/design/style-guide",
     description: "Clear loaded style guide"
   },
+  // Quality Evaluation
+  DESIGN_EVALUATE: {
+    method: "POST",
+    path: "/ui-bridge/design/evaluate",
+    description: "Score the current UI against a quality context"
+  },
+  DESIGN_EVALUATE_CONTEXTS: {
+    method: "GET",
+    path: "/ui-bridge/design/evaluate/contexts",
+    description: "List available quality evaluation contexts"
+  },
+  DESIGN_EVALUATE_BASELINE: {
+    method: "POST",
+    path: "/ui-bridge/design/evaluate/baseline",
+    description: "Save a quality baseline snapshot"
+  },
+  DESIGN_EVALUATE_DIFF: {
+    method: "POST",
+    path: "/ui-bridge/design/evaluate/diff",
+    description: "Diff the current UI against a saved baseline"
+  },
   // AI helpers
   AI_FILL_FORM: {
     method: "POST",
@@ -174,18 +286,34 @@ var UI_BRIDGE_NATIVE_ROUTES = {
     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.
+  // Test hooks — drive ModalDetector state and the screen lock from outside
+  // the React tree (gated by `features.testHooks`). Mirrors `pushModal` /
+  // `dismissModal` calls that components normally make in-process.
+  //
+  // These are LISTED unconditionally — this table is a static constant with no
+  // config to consult — but each carries `requiresTestHooks: true`, which is
+  // the machine-readable form of the `(testHooks)` in its description. With the
+  // flag off `routeRequest` and `buildRoutesPayload` both drop them and the
+  // route answers a bare 404. `route-table-parity.test.ts` compares the whole
+  // table against `_routes` at `testHooks: true`, and the flagged subset
+  // against `_routes` at `testHooks: false`, so both surfaces are pinned.
   PUSH_MODAL: {
     method: "POST",
     path: "/ui-bridge/control/modal/push",
-    description: "Push a modal onto the modal stack (testHooks)"
+    description: "Push a modal onto the modal stack (testHooks)",
+    requiresTestHooks: true
   },
   DISMISS_MODAL: {
     method: "POST",
     path: "/ui-bridge/control/modal/dismiss/:id",
-    description: "Dismiss a modal by id (testHooks)"
+    description: "Dismiss a modal by id (testHooks)",
+    requiresTestHooks: true
+  },
+  KEEP_AWAKE: {
+    method: "POST",
+    path: "/ui-bridge/control/keep-awake",
+    description: "Keep the device screen awake via the injected keepAwakeProvider: body { enabled, durationMs? } (testHooks)",
+    requiresTestHooks: true
   },
   // Observability — last-N ring buffers (always mounted; `installed:false`
   // when the console/network patches are off, i.e. no testHooks).
@@ -380,6 +508,21 @@ function projectVisionFields(args) {
   return fields;
 }
 
+// src/core/element-actions.ts
+function serializeElementCustomActions(customActions) {
+  if (!customActions) return void 0;
+  const out = [];
+  for (const [id, action] of Object.entries(customActions)) {
+    if (!action) continue;
+    const entry = { id };
+    if (action.label !== void 0) entry.label = action.label;
+    if (action.description !== void 0) entry.description = action.description;
+    if (action.effect !== void 0) entry.effect = action.effect;
+    out.push(entry);
+  }
+  return out;
+}
+
 // src/core/registry.ts
 function extractHandlerNames(props) {
   if (!props) return [];
@@ -408,6 +551,46 @@ function projectBbox(state, visibility, pixelRatio = 1) {
     h: toPx(layout.height)
   };
 }
+function pageRectOf(state) {
+  const layout = state.layout;
+  if (!layout) return null;
+  if (layout.pageOriginUnmeasured === true) return null;
+  const hasPage = typeof layout.pageX === "number" && typeof layout.pageY === "number" && Number.isFinite(layout.pageX) && Number.isFinite(layout.pageY);
+  if (!hasPage) return null;
+  const left = layout.pageX;
+  const top = layout.pageY;
+  if (typeof layout.width !== "number" || typeof layout.height !== "number" || !Number.isFinite(layout.width) || !Number.isFinite(layout.height)) {
+    return null;
+  }
+  return { left, top, right: left + layout.width, bottom: top + layout.height };
+}
+function spansOverlap(aMin, aMax, bMin, bMax) {
+  if (aMin === aMax) return aMin >= bMin && aMin <= bMax;
+  return aMin < bMax && aMax > bMin;
+}
+function isEmptyRect(rect) {
+  return rect.right <= rect.left || rect.bottom <= rect.top;
+}
+function computeVisibility(state, clip) {
+  if (!state.visible) {
+    return { visibility: "hidden", visibilityReason: "hidden" };
+  }
+  if (state.layout === null) {
+    return { visibility: "likely-visible", visibilityReason: "no-layout" };
+  }
+  if (!clip) {
+    return { visibility: "visible" };
+  }
+  const rect = pageRectOf(state);
+  if (!rect) {
+    return { visibility: "visible" };
+  }
+  if (isEmptyRect(clip)) {
+    return { visibility: "hidden", visibilityReason: "off-screen" };
+  }
+  const onScreen = spansOverlap(rect.left, rect.right, clip.left, clip.right) && spansOverlap(rect.top, rect.bottom, clip.top, clip.bottom);
+  return onScreen ? { visibility: "visible" } : { visibility: "hidden", visibilityReason: "off-screen" };
+}
 
 // src/design/design-inspector-native.ts
 function toCssValue(value) {
@@ -1355,16 +1538,21 @@ function createServerHandlers(registry, executor, config) {
   return {
     // Elements
     getElements: async (ctx) => {
+      await registry.refreshMeasurements();
       const visibleOnly = ctx.query?.visibleOnly === "true" || ctx.body?.visibleOnly === true;
       const forRoute = ctx.query?.route || ctx.body?.route;
       let allElements = visibleOnly ? registry.getMountedVisibleElements() : registry.getAllElements();
       if (forRoute) {
         allElements = allElements.filter((e) => matchesCurrentRoute(e.registrationRoute, forRoute));
       }
+      const viewport = registry.getViewportRect();
       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";
+        const { visibility, visibilityReason } = computeVisibility(
+          state,
+          registry.getClipRectFor(e, viewport)
+        );
         const bbox = projectBbox(state, visibility, registry.getPixelRatio());
         const vision = projectVisionFields({
           type: e.type,
@@ -1382,10 +1570,11 @@ function createServerHandlers(registry, executor, config) {
           identifier: e.getIdentifier(),
           state,
           actions: e.actions,
-          customActions: e.customActions ? Object.keys(e.customActions) : void 0,
+          customActions: serializeElementCustomActions(e.customActions),
           registeredHandlers: handlers.length > 0 ? handlers : void 0,
           registrationRoute: e.registrationRoute,
           visibility,
+          ...visibilityReason ? { visibilityReason } : {},
           ...bbox ? { bbox } : {},
           ...vision
         };
@@ -1407,7 +1596,7 @@ function createServerHandlers(registry, executor, config) {
           identifier: element.getIdentifier(),
           state: resolveElementState(element),
           actions: element.actions,
-          customActions: element.customActions ? Object.keys(element.customActions) : void 0,
+          customActions: serializeElementCustomActions(element.customActions),
           registeredHandlers: handlers.length > 0 ? handlers : void 0,
           registrationRoute: element.registrationRoute
         }
@@ -1428,13 +1617,9 @@ function createServerHandlers(registry, executor, config) {
       if (!envelope?.action) {
         return error2("Action is required", "INVALID_REQUEST");
       }
-      const response = await executor.executeAction(id, {
-        action: envelope.action,
-        params: envelope.params,
-        waitOptions: envelope.waitOptions
-      });
+      const response = await executor.executeAction(id, envelope);
       if (!response.success) {
-        return error2(response.error || "Action failed", "ACTION_FAILED");
+        return error2(response.error || "Action failed", response.code ?? "ACTION_FAILED");
       }
       return success2(response);
     },
@@ -1444,7 +1629,11 @@ function createServerHandlers(registry, executor, config) {
         id: c.id,
         name: c.name,
         description: c.description,
-        actions: c.actions.map((a) => ({ id: a.id, label: a.label })),
+        // Phase 4 (plan 2026-08-20-ui-bridge-action-declaration-shape):
+        // carry the safety annotation onto the native wire too — a walker
+        // driving a React Native app needs the same `destructive` exclusion
+        // the web channel gets.
+        actions: c.actions.map((a) => ({ id: a.id, label: a.label, effect: a.effect })),
         elementIds: c.elementIds
       }));
       return success2({ components });
@@ -1463,7 +1652,9 @@ function createServerHandlers(registry, executor, config) {
           actions: component.actions.map((a) => ({
             id: a.id,
             label: a.label,
-            description: a.description
+            description: a.description,
+            // Phase 4 — see the listing twin above.
+            effect: a.effect
           })),
           elementIds: component.elementIds
         }
@@ -1474,7 +1665,8 @@ function createServerHandlers(registry, executor, config) {
       const body = ctx.body;
       const response = await executor.executeComponentAction(id, {
         action: actionId,
-        params: body?.params
+        params: body?.params,
+        timeoutMs: body?.timeoutMs
       });
       if (!response.success) {
         return error2(response.error || "Action failed", "ACTION_FAILED");
@@ -1548,6 +1740,7 @@ function createServerHandlers(registry, executor, config) {
       });
     },
     getSnapshot: async (ctx) => {
+      await registry.refreshMeasurements();
       const visibleOnly = ctx.query?.visibleOnly === "true" || ctx.body?.visibleOnly === true;
       const currentRouteOnly = ctx.query?.currentRouteOnly === "true" || ctx.body?.currentRouteOnly === true;
       const snapshot = registry.createSnapshot(void 0, { visibleOnly, currentRouteOnly });
@@ -1665,9 +1858,12 @@ function createServerHandlers(registry, executor, config) {
     //
     // 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.
+    // get a structured envelope explaining the gap rather than a bare
+    // "no such route". These answer **HTTP 501** — `httpStatusForResponse` in
+    // server/http-server.ts maps NOT_SUPPORTED → 501, so the status line and
+    // the envelope agree; an unmounted path answers 404 instead. 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.',
@@ -1863,6 +2059,7 @@ function createServerHandlers(registry, executor, config) {
     // that don't measure (the fallback only matches single-rooted screens but
     // is good enough for the unit suite).
     tapAt: async (ctx) => {
+      await registry.refreshMeasurements();
       const body = ctx.body;
       const x = body?.x;
       const y = body?.y;
@@ -1993,18 +2190,12 @@ function createServerHandlers(registry, executor, config) {
     pushModal: async (ctx) => {
       const detector = registry.getEnrichers().modalDetector;
       if (!detector) {
-        return error2(
-          "modal detector not registered",
-          "ENRICHER_UNAVAILABLE"
-        );
+        return error2("modal detector not registered", "ENRICHER_UNAVAILABLE");
       }
       const body = ctx.body;
       const id = body?.id;
       if (typeof id !== "string" || id.length === 0) {
-        return error2(
-          'pushModal requires a non-empty "id"',
-          "INVALID_REQUEST"
-        );
+        return error2('pushModal requires a non-empty "id"', "INVALID_REQUEST");
       }
       const allowedTypes = ["modal", "sheet", "drawer", "popover", "alertdialog", "dialog"];
       const requestedType = body?.type;
@@ -2037,10 +2228,7 @@ function createServerHandlers(registry, executor, config) {
     dismissModal: async (ctx) => {
       const detector = registry.getEnrichers().modalDetector;
       if (!detector) {
-        return error2(
-          "modal detector not registered",
-          "ENRICHER_UNAVAILABLE"
-        );
+        return error2("modal detector not registered", "ENRICHER_UNAVAILABLE");
       }
       const { id } = ctx.params;
       if (typeof id !== "string" || id.length === 0) {
@@ -2070,7 +2258,7 @@ function createServerHandlers(registry, executor, config) {
       };
       if (config?.appInfo) {
         response.uiBridge = {
-          version: "0.6.11",
+          version: "0.6.13",
           ...config.appInfo,
           capabilities: ["elements", "components", "actions", "design"],
           elementCount: stats.elements,
@@ -2218,8 +2406,48 @@ function extractMethod(input, init) {
 var NetworkRequestBuffer = class {
   constructor(capacity = 100) {
     this.installed = false;
+    /**
+     * Synchronous re-entrancy depth: non-zero while the ORIGINAL `fetch` is
+     * executing, which is exactly the window in which React Native's whatwg-fetch
+     * polyfill constructs and opens its internal `XMLHttpRequest`.
+     *
+     * A counter rather than a boolean so a `fetch` called from inside a `fetch`
+     * (an interceptor, a retry wrapper) still unwinds to zero. Safe as a plain
+     * number: JS is single-threaded and the only writes are the paired
+     * increment/decrement around one synchronous call.
+     */
+    this.fetchDepth = { value: 0 };
     this.buffer = new RingBuffer(capacity);
   }
+  /**
+   * Patch `fetch` and `XMLHttpRequest` so `GET /sdk/network-requests` can
+   * report what the app talked to.
+   *
+   * ONE REQUEST MUST PRODUCE ONE ENTRY. React Native implements `fetch` **on
+   * top of** XHR (whatwg-fetch), so both patches observe the same request and
+   * the buffer used to carry every call twice — same url, timestamps ~1ms
+   * apart, and on failure one `"Network request failed"` beside one
+   * `"XMLHttpRequest error"`. A tester reads that as a double-fetch bug in the
+   * app and chases a defect that does not exist.
+   *
+   * The de-dup: `fetchDepth` is raised across the synchronous call into the
+   * original `fetch`, which is when the polyfill builds its XHR; `open` stamps
+   * any XHR created in that window with `__uiBridgeFromFetch`, and `send`
+   * skips recording those. The `fetch` patch keeps the entry, because it is
+   * the layer the app actually called and the only one that sees `Response.ok`.
+   *
+   * Uninstalling both patches together keeps this sound: an XHR can only be
+   * marked while the fetch patch is live.
+   *
+   * KNOWN LIMIT — it is coupled to the polyfill building its XHR SYNCHRONOUSLY,
+   * which whatwg-fetch does (its work happens in the Promise executor). If the
+   * host's `fetch` is wrapped by an interceptor that defers the real call to a
+   * microtask or `setTimeout`, the depth is back to 0 by the time `open` runs
+   * and every request duplicates again — the original symptom, with no signal
+   * that the mechanism disengaged. Duplicates in `/sdk/network-requests` are
+   * the thing to look for; they mean this assumption stopped holding, not that
+   * the app double-fetched.
+   */
   install() {
     if (this.installed) return;
     const g = globalThis;
@@ -2227,12 +2455,20 @@ var NetworkRequestBuffer = class {
       this.originalFetch = g.fetch;
       const buffer = this.buffer;
       const original = this.originalFetch;
+      const fetchDepth = this.fetchDepth;
       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);
+          let pending;
+          fetchDepth.value += 1;
+          try {
+            pending = original.call(globalThis, input, init);
+          } finally {
+            fetchDepth.value -= 1;
+          }
+          const res = await pending;
           buffer.push({
             timestamp: start,
             method,
@@ -2262,10 +2498,14 @@ var NetworkRequestBuffer = class {
       this.originalXhrOpen = Xhr.prototype.open;
       this.originalXhrSend = Xhr.prototype.send;
       const buffer = this.buffer;
+      const fetchDepth = this.fetchDepth;
       const origOpen = this.originalXhrOpen;
       Xhr.prototype.open = function(method, url, ...rest) {
         this.__uiBridgeMethod = method.toUpperCase();
         this.__uiBridgeUrl = typeof url === "string" ? url : String(url);
+        if (fetchDepth.value > 0) {
+          this.__uiBridgeFromFetch = true;
+        }
         return origOpen.call(
           this,
           method,
@@ -2275,6 +2515,9 @@ var NetworkRequestBuffer = class {
       };
       const origSend = this.originalXhrSend;
       Xhr.prototype.send = function(body) {
+        if (this.__uiBridgeFromFetch === true) {
+          return origSend.call(this, body);
+        }
         const start = Date.now();
         const method = this.__uiBridgeMethod ?? "GET";
         const url = this.__uiBridgeUrl ?? "";
@@ -2354,6 +2597,16 @@ function isUnsubscribe(msg) {
 }
 
 // src/server/http-server.ts
+var ERROR_CODE_HTTP_STATUS = /* @__PURE__ */ new Map([
+  ["NOT_SUPPORTED", 501],
+  ["NOT_FOUND", 404],
+  ["METHOD_NOT_ALLOWED", 405]
+]);
+function httpStatusForResponse(response) {
+  if (response.success) return 200;
+  const mapped = response.code ? ERROR_CODE_HTTP_STATUS.get(response.code) : void 0;
+  return mapped ?? 400;
+}
 function parsePath(pattern, actual) {
   const patternParts = pattern.split("/");
   const actualParts = actual.split("/");
@@ -2516,6 +2769,23 @@ var WS_ROUTES = [
     httpMethods: ["GET"]
   }
 ];
+var DISCOVERY_PATHS = /* @__PURE__ */ new Set(["_help", "_routes"]);
+function allowedMethodsForPath(path, testHooks) {
+  const PREFIX = "/ui-bridge/";
+  if (!path.startsWith(PREFIX)) return [];
+  const stripped = path.slice(PREFIX.length);
+  const methods = [];
+  if (DISCOVERY_PATHS.has(stripped)) methods.push("GET");
+  for (const route of WS_ROUTES) {
+    if (!route.httpMethods) continue;
+    if (route.requiresTestHooks && !testHooks) continue;
+    if (parsePath(route.pattern, stripped) === null) continue;
+    for (const verb of route.httpMethods) {
+      if (!methods.includes(verb)) methods.push(verb);
+    }
+  }
+  return methods;
+}
 var HANDLER_DESCRIPTIONS = {
   health: "Liveness probe; returns app metadata + element count",
   getElements: "Flat list of registered UI elements",
@@ -2578,6 +2848,10 @@ var ACTION_REFERENCE = [
   { name: "focus", params: "none" },
   { name: "blur", params: "none" },
   { name: "scroll", params: "ScrollActionParams { offset? {x,y}, to? }" },
+  {
+    name: "scrollIntoView",
+    params: "ScrollIntoViewActionParams { padding? (dp, default 16) } \u2014 scrolls the element's DECLARED scrollAncestorId ScrollView; returns { alreadyVisible, scrolled }; NOT_SUPPORTED (501) without a usable declared ancestor"
+  },
   { name: "swipe", params: "SwipeActionParams { direction, distance }" },
   { name: "toggle", params: "none \u2014 flips boolean controls" }
 ];
@@ -2775,7 +3049,9 @@ var NativeUIBridgeServer = class {
   }
   /**
    * Set a route provider for reporting the current navigation route.
-   * When set, `control/snapshot` responses include `currentRoute` and `segments`.
+   * When set, `control/snapshot` responses include `currentRoute` and
+   * `segments`, plus the canonical `route` / `activeTab` aliases the web SDK's
+   * `BridgeSnapshot` spells the same way.
    *
    * Also forwards the provider into the registry so the *default*
    * `getSnapshot` handler (and any other call site of
@@ -2790,7 +3066,12 @@ var NativeUIBridgeServer = class {
     this.handlers.getElements = async (ctx) => {
       const currentRouteOnly = ctx.query?.currentRouteOnly === "true" || ctx.body?.currentRouteOnly === true;
       if (currentRouteOnly && !ctx.query?.route && !ctx.body?.route) {
-        const currentRoute = provider.getCurrentRoute();
+        let currentRoute;
+        try {
+          currentRoute = provider.getCurrentRoute();
+        } catch {
+          currentRoute = null;
+        }
         if (currentRoute) {
           ctx.query = { ...ctx.query, route: currentRoute };
         }
@@ -2800,11 +3081,26 @@ var NativeUIBridgeServer = class {
     this.handlers.getSnapshot = async (ctx) => {
       const visibleOnly = ctx?.query?.visibleOnly === "true" || ctx?.body?.visibleOnly === true;
       const currentRouteOnly = ctx?.query?.currentRouteOnly === "true" || ctx?.body?.currentRouteOnly === true;
+      let currentRoute;
+      try {
+        currentRoute = provider.getCurrentRoute() ?? null;
+      } catch {
+        currentRoute = null;
+      }
+      let segments;
+      try {
+        segments = provider.getSegments?.();
+      } catch {
+        segments = void 0;
+      }
+      let activeTab;
+      try {
+        activeTab = provider.getActiveTab?.();
+      } catch {
+        activeTab = void 0;
+      }
       const snapshot = this.registry.createSnapshot(
-        {
-          currentRoute: provider.getCurrentRoute(),
-          segments: provider.getSegments?.()
-        },
+        { currentRoute, segments, activeTab },
         { visibleOnly, currentRouteOnly }
       );
       return { success: true, data: snapshot, timestamp: Date.now() };
@@ -3470,8 +3766,15 @@ var NativeUIBridgeServer = class {
     }
     try {
       const response = await this.routeRequest(request);
+      if (response.code === "METHOD_NOT_ALLOWED") {
+        const allow = allowedMethodsForPath(request.path, this.config.testHooks === true);
+        if (allow.length > 0) {
+          headers["Allow"] = allow.join(", ");
+          if (this.config.cors) headers["Access-Control-Expose-Headers"] = "Allow";
+        }
+      }
       return {
-        status: response.success ? 200 : 400,
+        status: httpStatusForResponse(response),
         headers,
         body: JSON.stringify(response)
       };
@@ -3528,7 +3831,7 @@ var NativeUIBridgeServer = class {
         timestamp: Date.now()
       };
     }
-    let patternMatchedButWrongVerb = false;
+    let patternMatchedButWrongVerb = DISCOVERY_PATHS.has(stripped);
     for (const route of WS_ROUTES) {
       const pathParams = parsePath(route.pattern, stripped);
       if (!pathParams) continue;
@@ -3545,9 +3848,10 @@ var NativeUIBridgeServer = class {
       const ctx = { params: pathParams, query, body };
       return this.handlers[route.handler](ctx);
     }
+    const allowed = patternMatchedButWrongVerb ? allowedMethodsForPath(path, testHooks) : [];
     return {
       success: false,
-      error: patternMatchedButWrongVerb ? `Method not allowed: ${method} ${path}` : `Route not found: ${method} ${path}`,
+      error: patternMatchedButWrongVerb ? `Method not allowed: ${method} ${path}${allowed.length > 0 ? ` (allowed: ${allowed.join(", ")})` : ""}` : `Route not found: ${method} ${path}`,
       code: patternMatchedButWrongVerb ? "METHOD_NOT_ALLOWED" : "NOT_FOUND",
       timestamp: Date.now()
     };
@@ -4244,6 +4548,6 @@ async function bindWithRetry(attempt, options = {}) {
   }
 }
 
-export { ConsoleErrorBuffer, NativeUIBridgeServer, NetworkRequestBuffer, OPCODE_BINARY, OPCODE_CLOSE, OPCODE_CONTINUATION, OPCODE_PING, OPCODE_PONG, OPCODE_TEXT, UI_BRIDGE_NATIVE_ROUTES, WebSocketConnection, WebSocketEventBridge, bindWithRetry, buildUpgradeResponse, computeAcceptKey, createDesignHandlers, createNativeServer, createServerHandlers, decodeFrames, decodeTextPayload, encodeCloseFrame, encodePingFrame, encodePongFrame, encodeTextFrame, isAddrInUseError, isBatchRequest, isSubscribe, isUnsubscribe };
+export { ConsoleErrorBuffer, NativeUIBridgeServer, NetworkRequestBuffer, OPCODE_BINARY, OPCODE_CLOSE, OPCODE_CONTINUATION, OPCODE_PING, OPCODE_PONG, OPCODE_TEXT, UI_BRIDGE_NATIVE_ROUTES, WebSocketConnection, WebSocketEventBridge, bindWithRetry, buildUpgradeResponse, computeAcceptKey, createDesignHandlers, createNativeServer, createServerHandlers, decodeFrames, decodeTextPayload, encodeCloseFrame, encodePingFrame, encodePongFrame, encodeTextFrame, httpStatusForResponse, isAddrInUseError, isBatchRequest, isSubscribe, isUnsubscribe };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map