@qontinui/ui-bridge-native 0.6.12 → 0.6.13

package/dist/index.mjs

@@ -182,7 +182,42 @@ 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 toRegisteredComponentActions(actions) {
+  return actions.map((a) => ({
+    id: a.id,
+    label: a.label,
+    description: a.description,
+    paramSchema: a.paramSchema,
+    effect: a.effect,
+    handler: a.handler
+  }));
+}
+function publishedActionSignature(actions) {
+  return JSON.stringify(
+    actions.map((a) => [a.id, a.label, a.description, a.paramSchema, a.effect])
+  );
+}
+function sameElementIds(a, b) {
+  if (a === b) return true;
+  if (a === void 0 || b === void 0) return false;
+  return a.length === b.length && a.every((id, i) => id === b[i]);
+}
 function extractHandlerNames(props) {
   if (!props) return [];
   return Object.keys(props).filter((k) => typeof props[k] === "function");
@@ -191,6 +226,22 @@ function matchesCurrentRoute(registrationRoute, currentRoute) {
   if (registrationRoute == null || registrationRoute === "") return true;
   return registrationRoute === currentRoute;
 }
+function deriveActiveTabFromSegments(segments) {
+  if (!segments || segments.length === 0) return void 0;
+  let innermostGroup = -1;
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    if (typeof segment === "string" && segment.startsWith("(") && segment.endsWith(")")) {
+      innermostGroup = i;
+    }
+  }
+  if (innermostGroup === -1) return void 0;
+  const next = segments[innermostGroup + 1];
+  if (next === void 0) return "index";
+  if (typeof next !== "string" || next.length === 0) return void 0;
+  if (next.startsWith("[") && next.endsWith("]")) return void 0;
+  return next;
+}
 function projectBbox(state, visibility, pixelRatio = 1) {
   if (visibility !== "visible") return void 0;
   const layout = state.layout;
@@ -210,8 +261,58 @@ function projectBbox(state, visibility, pixelRatio = 1) {
     h: toPx(layout.height)
   };
 }
-function inferActions(type) {
-  const baseActions = ["focus", "blur"];
+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 intersectRects(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  return {
+    left: Math.max(a.left, b.left),
+    top: Math.max(a.top, b.top),
+    right: Math.min(a.right, b.right),
+    bottom: Math.min(a.bottom, b.bottom)
+  };
+}
+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" };
+}
+function inferActions(type, scrollAncestorId) {
+  const baseActions = scrollAncestorId ? ["focus", "blur", "scrollIntoView"] : ["focus", "blur"];
   switch (type) {
     case "button":
     case "touchable":
@@ -283,6 +384,18 @@ var NativeUIBridgeRegistry = class {
      * the `projectBbox` doc comment for why we don't import `react-native` here.
      */
     this.pixelRatio = 1;
+    /**
+     * Injected getter for the device window size in logical dp, used to clip
+     * reported visibility. Injected rather than read here for exactly the reason
+     * `pixelRatio` is: a static `import { Dimensions } from 'react-native'` in
+     * this non-React core module breaks the vitest suite and risks the
+     * Metro/Hermes `unknownModuleError`. It is a PROVIDER, not a value, so a
+     * rotation is picked up on the next snapshot with nothing to keep in sync.
+     *
+     * `null` means the window bounds are UNKNOWN, and {@link computeVisibility}
+     * treats unknown bounds as "cannot demote" — never as an empty viewport.
+     */
+    this.viewportProvider = null;
     /**
      * Sticky flag: flips `true` the first time any element is registered and
      * stays `true` even after elements are unregistered. Lets agents distinguish
@@ -320,6 +433,30 @@ var NativeUIBridgeRegistry = class {
   getRouteProvider() {
     return this.routeProvider;
   }
+  /**
+   * Resolve the snapshot's `activeTab`: an explicit `getActiveTab()` on the
+   * route provider wins, otherwise derive it from the Expo Router segments the
+   * provider already exposes.
+   *
+   * A throwing or empty-string provider degrades to the derivation rather than
+   * to `undefined` — the host's opt-in extra should never be able to make the
+   * snapshot WORSE than it was without it. A blank derivation stays blank.
+   */
+  resolveActiveTab(segments) {
+    const explicit = (() => {
+      if (!this.routeProvider?.getActiveTab) return void 0;
+      try {
+        const value = this.routeProvider.getActiveTab();
+        return typeof value === "string" && value.length > 0 ? value : void 0;
+      } catch (error3) {
+        if (this.config.verbose) {
+          console.warn(`[ui-bridge-native] routeProvider getActiveTab threw:`, error3);
+        }
+        return void 0;
+      }
+    })();
+    return explicit ?? deriveActiveTabFromSegments(segments);
+  }
   /**
    * Set the device pixel ratio used to project per-element `bbox` geometry
    * into physical pixels. The React provider passes `PixelRatio.get()` here
@@ -335,6 +472,56 @@ var NativeUIBridgeRegistry = class {
   getPixelRatio() {
     return this.pixelRatio;
   }
+  /**
+   * Set the getter for the device window size (logical dp) that reported
+   * visibility is clipped against. The React provider passes
+   * `() => Dimensions.get('window')` here at construction.
+   *
+   * Pass `null` to detach. While detached the window bounds are UNKNOWN and no
+   * element is ever demoted for being outside them.
+   */
+  setViewportProvider(provider) {
+    this.viewportProvider = provider ?? null;
+  }
+  /**
+   * The window as a page-space rect, or `null` when it is unknown or the
+   * provider returned something unusable (it throws in some RN teardown
+   * paths, and a zero-size window would silently hide the entire screen).
+   */
+  getViewportRect() {
+    if (!this.viewportProvider) return null;
+    let size;
+    try {
+      size = this.viewportProvider();
+    } catch (error3) {
+      if (this.config.verbose) {
+        console.warn(`[ui-bridge-native] viewportProvider threw:`, error3);
+      }
+      return null;
+    }
+    const { width, height } = size ?? {};
+    if (typeof width !== "number" || typeof height !== "number" || !Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+      return null;
+    }
+    return { left: 0, top: 0, right: width, bottom: height };
+  }
+  /**
+   * The region `element` must reach to count as on screen: the window,
+   * intersected with the measured frame of its declared `scrollAncestorId`.
+   *
+   * Returns `null` when neither bound is known — see {@link computeVisibility}
+   * for why that means "do not demote" rather than "nothing is visible".
+   * An ancestor that is not registered, or registered but not yet measured,
+   * contributes nothing rather than hiding its subtree.
+   */
+  getClipRectFor(element, viewport) {
+    const bounds = viewport === void 0 ? this.getViewportRect() : viewport;
+    const ancestorId = element.scrollAncestorId;
+    if (!ancestorId) return bounds;
+    const ancestor = this.elements.get(ancestorId);
+    if (!ancestor || ancestorId === element.id) return bounds;
+    return intersectRects(bounds, pageRectOf(ancestor.getState()));
+  }
   // ============================================================================
   // Snapshot Enricher Slots
   // ============================================================================
@@ -378,16 +565,17 @@ var NativeUIBridgeRegistry = class {
     const {
       type = "custom",
       label,
-      actions = inferActions(type),
       customActions,
       props,
       treePath = id,
       testId,
       accessibilityLabel,
       registrationRoute,
+      scrollAncestorId,
       flatStyle,
       stateStyles
     } = options;
+    const actions = options.actions ?? inferActions(type, scrollAncestorId);
     const getState = () => {
       const element = ref.current;
       if (!element) {
@@ -430,6 +618,7 @@ var NativeUIBridgeRegistry = class {
       registeredAt: Date.now(),
       mounted: true,
       registrationRoute: registrationRoute ?? null,
+      scrollAncestorId,
       flatStyle,
       stateStyles
     };
@@ -806,12 +995,8 @@ var NativeUIBridgeRegistry = class {
       id,
       name,
       description,
-      actions: actions.map((a) => ({
-        id: a.id,
-        label: a.label,
-        description: a.description,
-        handler: a.handler
-      })),
+      // Closed field list, applied once — see `toRegisteredComponentActions`.
+      actions: toRegisteredComponentActions(actions),
       elementIds,
       registeredAt: Date.now(),
       mounted: true
@@ -823,6 +1008,55 @@ var NativeUIBridgeRegistry = class {
     }
     return registered;
   }
+  /**
+   * Update a registered component's declaration in place — name, description,
+   * actions, elementIds.
+   *
+   * Sister to {@link updateElementMeta}, and it exists for the same reason one
+   * level up. `registerComponent` publishes the declaration exactly once, and
+   * `useUIComponent` registers on mount and never again, so an action whose
+   * `label` carries a count, an action that only exists while a row is
+   * selected, a `paramSchema` that widens once options load, or an `elementIds`
+   * list that grows after mount, all published their mount-time shape to
+   * `/control/components` forever. PR #176 closed that hole for an ELEMENT's
+   * label; this closes it for a COMPONENT's declaration.
+   *
+   * **Idempotent by VALUE over the PUBLISHED shape.** `handler` identity is
+   * excluded from the comparison — call sites pass inline closures that are
+   * freshly allocated every render, so including it would report a change on
+   * every call and make the door useless for a render-path publisher. The
+   * newest handlers are still STORED whenever `actions` is supplied, which is
+   * the other half of the same defect: without it the registry keeps the
+   * closure from the render that registered the component, so a handler reading
+   * component state read the state as it was at mount.
+   *
+   * Returns `true` when the published shape changed and an event was emitted,
+   * `false` otherwise — the same contract as `updateElementMeta`, so a caller
+   * can gate a warning or a state write on a real change.
+   */
+  updateComponentMeta(id, meta) {
+    const component = this.components.get(id);
+    if (!component) return false;
+    const nextName = meta.name !== void 0 ? meta.name : component.name;
+    const nextDescription = meta.description !== void 0 ? meta.description : component.description;
+    const nextActions = meta.actions !== void 0 ? toRegisteredComponentActions(meta.actions) : component.actions;
+    const nextElementIds = meta.elementIds !== void 0 ? meta.elementIds : component.elementIds;
+    const changed = nextName !== component.name || nextDescription !== component.description || !sameElementIds(nextElementIds, component.elementIds) || publishedActionSignature(nextActions) !== publishedActionSignature(component.actions);
+    if (!changed && meta.actions === void 0) return false;
+    this.components.set(id, {
+      ...component,
+      name: nextName,
+      description: nextDescription,
+      actions: nextActions,
+      elementIds: nextElementIds
+    });
+    if (!changed) return false;
+    this.emit("component:registered", { id, name: nextName });
+    if (this.config.verbose) {
+      console.log(`[ui-bridge-native] Updated component: ${id} (${nextName})`);
+    }
+    return true;
+  }
   /**
    * Unregister a component
    */
@@ -936,41 +1170,59 @@ var NativeUIBridgeRegistry = class {
    * server-level override (the bare-server / cloud-relay path) still get a
    * populated `currentRoute` field as long as `setRouteProvider` was called
    * on the registry.
+   *
+   * `activeTab` resolves through {@link resolveActiveTab} on BOTH branches. An
+   * explicit `routeInfo.activeTab` wins outright; otherwise a registered
+   * provider's `getActiveTab()` answers and the Expo Router derivation is the
+   * fallback. Deriving straight from `routeInfo.segments` here instead — which
+   * is what this branch did when `activeTab` was introduced — silently ignored
+   * `RouteProvider.getActiveTab` on the ONLY path that serves
+   * `control/snapshot` once `setRouteProvider` is wired (the server installs a
+   * `getSnapshot` override that passes `routeInfo`), so the opt-in hook for an
+   * app whose visible pane is decoupled from the router reached no consumer.
    */
   createSnapshot(routeInfo, options) {
     const resolvedRoute = (() => {
       if (routeInfo !== void 0) {
+        const explicit = typeof routeInfo.activeTab === "string" && routeInfo.activeTab.length > 0 ? routeInfo.activeTab : void 0;
         return {
           currentRoute: routeInfo.currentRoute ?? null,
-          segments: routeInfo.segments
+          segments: routeInfo.segments,
+          activeTab: explicit ?? this.resolveActiveTab(routeInfo.segments)
         };
       }
       if (this.routeProvider) {
         try {
+          const segments = this.routeProvider.getSegments?.();
           return {
             currentRoute: this.routeProvider.getCurrentRoute() ?? null,
-            segments: this.routeProvider.getSegments?.()
+            segments,
+            activeTab: this.resolveActiveTab(segments)
           };
         } 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, activeTab: void 0 };
         }
       }
-      return { currentRoute: null, segments: void 0 };
+      return { currentRoute: null, segments: void 0, activeTab: void 0 };
     })();
     let elements = options?.visibleOnly ? this.getMountedVisibleElements() : this.getAllElements();
     if (options?.currentRouteOnly && resolvedRoute.currentRoute) {
       const currentRoute = resolvedRoute.currentRoute;
       elements = elements.filter((e) => matchesCurrentRoute(e.registrationRoute, currentRoute));
     }
+    const viewport = this.getViewportRect();
     const snapshot = {
       timestamp: Date.now(),
       elements: elements.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,
+          this.getClipRectFor(e, viewport)
+        );
         const bbox = projectBbox(state, visibility, this.pixelRatio);
         const vision = projectVisionFields({
           type: e.type,
@@ -990,10 +1242,11 @@ var NativeUIBridgeRegistry = class {
           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
         };
@@ -1013,6 +1266,13 @@ var NativeUIBridgeRegistry = class {
       })),
       currentRoute: resolvedRoute.currentRoute,
       segments: resolvedRoute.segments,
+      // Canonical aliases, spelled the way the web SDK's `BridgeSnapshot`
+      // spells them so a cross-platform consumer reads one field name on both
+      // platforms. Omitted rather than nulled when unknown — same convention
+      // as the web fields, and it keeps the emitted shape byte-identical for
+      // hosts that wire no route provider.
+      ...resolvedRoute.currentRoute ? { route: resolvedRoute.currentRoute } : {},
+      ...resolvedRoute.activeTab ? { activeTab: resolvedRoute.activeTab } : {},
       registration: this.getRegistrationCoverage()
     };
     if (this.appInfo) {
@@ -1115,6 +1375,468 @@ function resetGlobalRegistry() {
   globalRegistry = null;
 }
 
+// src/core/action-effect.ts
+var NATIVE_STANDARD_ACTION_EFFECTS = {
+  // --- Reads ---------------------------------------------------------------
+  focus: "read",
+  blur: "read",
+  scroll: "read",
+  scrollIntoView: "read",
+  longPress: "read",
+  // --- Writes --------------------------------------------------------------
+  press: "write",
+  click: "write",
+  doubleTap: "write",
+  type: "write",
+  setValue: "write",
+  clear: "write",
+  swipe: "write",
+  toggle: "write"
+};
+function nativeStandardActionEffect(actionId) {
+  return Object.prototype.hasOwnProperty.call(NATIVE_STANDARD_ACTION_EFFECTS, actionId) ? NATIVE_STANDARD_ACTION_EFFECTS[actionId] : void 0;
+}
+function resolveActionEffect(action) {
+  return action.effect ?? nativeStandardActionEffect(action.id);
+}
+
+// src/core/param-schema.ts
+var DEFAULT_PARAM_VALIDATION_MODE = "warn";
+var currentDefaultMode = DEFAULT_PARAM_VALIDATION_MODE;
+function setDefaultParamValidationMode(mode) {
+  currentDefaultMode = mode;
+}
+function getDefaultParamValidationMode() {
+  return currentDefaultMode;
+}
+function resetDefaultParamValidationMode() {
+  currentDefaultMode = DEFAULT_PARAM_VALIDATION_MODE;
+}
+var PRIMITIVE_TYPE_NAMES = /* @__PURE__ */ new Set([
+  "string",
+  "number",
+  "integer",
+  "boolean",
+  "object",
+  "array",
+  "null"
+]);
+var OBJECT_SCHEMA_KEYWORDS = /* @__PURE__ */ new Set([
+  "type",
+  "properties",
+  "required",
+  "additionalProperties",
+  "patternProperties",
+  "propertyNames",
+  "minProperties",
+  "maxProperties",
+  "dependentRequired",
+  "dependentSchemas",
+  "unevaluatedProperties",
+  "allOf",
+  "anyOf",
+  "oneOf",
+  "not",
+  "if",
+  "then",
+  "else",
+  "enum",
+  "const",
+  "default",
+  "examples",
+  "title",
+  "description",
+  "deprecated",
+  "readOnly",
+  "writeOnly",
+  "$schema",
+  "$id",
+  "$ref",
+  "$comment",
+  "$defs",
+  "definitions"
+]);
+var MAX_SCHEMA_DEPTH = 32;
+var MAX_PATTERN_LENGTH = 200;
+function hasNestedQuantifiers(pattern) {
+  return /(\((?:[^()]*[+*}])[^()]*\))[+*?]|\(\?:[^()]*[+*}][^()]*\)[+*?]/.test(pattern);
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var hasOwnProperty = Object.prototype.hasOwnProperty;
+function hasOwn(value, key) {
+  return hasOwnProperty.call(value, key);
+}
+function render(value) {
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  if (Array.isArray(value)) return `array(${value.length})`;
+  const t = typeof value;
+  if (t === "string") return JSON.stringify(value);
+  if (t === "number" || t === "boolean") return String(value);
+  if (t === "object") return "object";
+  return t;
+}
+var MAX_RENDERED_JSON_LENGTH = 120;
+function renderJson(value) {
+  if (value === void 0) return "undefined";
+  let text;
+  try {
+    text = JSON.stringify(value) ?? String(value);
+  } catch {
+    return render(value);
+  }
+  return text.length > MAX_RENDERED_JSON_LENGTH ? `${text.slice(0, MAX_RENDERED_JSON_LENGTH)}\u2026` : text;
+}
+function jsonTypeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  const t = typeof value;
+  if (t === "number") return Number.isInteger(value) ? "integer" : "number";
+  if (t === "string" || t === "boolean" || t === "object") return t;
+  return t;
+}
+function matchesType(value, typeName) {
+  switch (typeName) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "null":
+      return value === null;
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return isPlainObject(value);
+    default:
+      return true;
+  }
+}
+function jsonEquals(a, b, depth = 0) {
+  if (a === b) return true;
+  if (depth > MAX_SCHEMA_DEPTH) return false;
+  if (a === null || b === null || a === void 0 || b === void 0) return false;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== "object") return false;
+  const aIsArray = Array.isArray(a);
+  if (aIsArray !== Array.isArray(b)) return false;
+  if (aIsArray) {
+    const bArr = b;
+    const aArr = a;
+    if (aArr.length !== bArr.length) return false;
+    return aArr.every((item, i) => jsonEquals(item, bArr[i], depth + 1));
+  }
+  const aObj = a;
+  const bObj = b;
+  const aKeys = Object.keys(aObj);
+  const bKeys = Object.keys(bObj);
+  if (aKeys.length !== bKeys.length) return false;
+  return aKeys.every((key) => hasOwn(bObj, key) && jsonEquals(aObj[key], bObj[key], depth + 1));
+}
+function joinPath(base, key) {
+  return base === "" ? key : `${base}.${key}`;
+}
+function readTypes(schema) {
+  const raw = schema["type"];
+  if (typeof raw === "string") return [raw];
+  if (Array.isArray(raw)) {
+    const names = raw.filter((t) => typeof t === "string");
+    return names.length > 0 ? names : null;
+  }
+  return null;
+}
+function validateValue(value, schema, path, issues, depth) {
+  if (depth > MAX_SCHEMA_DEPTH) return;
+  if (typeof schema === "string") {
+    if (PRIMITIVE_TYPE_NAMES.has(schema) && !matchesType(value, schema)) {
+      issues.push({
+        path,
+        keyword: "type",
+        expected: schema,
+        received: render(value),
+        message: `Parameter "${path}" must be of type ${schema}, received ${jsonTypeOf(value)} (${render(value)}).`
+      });
+    }
+    return;
+  }
+  if (!isPlainObject(schema)) return;
+  const types = readTypes(schema);
+  if (types !== null && !types.some((t) => matchesType(value, t))) {
+    const expected = types.join(" | ");
+    issues.push({
+      path,
+      keyword: "type",
+      expected,
+      received: render(value),
+      message: `Parameter "${path}" must be of type ${expected}, received ${jsonTypeOf(value)} (${render(value)}).`
+    });
+    return;
+  }
+  if (hasOwn(schema, "const") && !jsonEquals(value, schema["const"])) {
+    const expected = renderJson(schema["const"]);
+    const received = renderJson(value);
+    issues.push({
+      path,
+      keyword: "const",
+      expected,
+      received,
+      message: `Parameter "${path}" must equal ${expected}, received ${received}.`
+    });
+    return;
+  }
+  const enumValues = schema["enum"];
+  if (Array.isArray(enumValues) && !enumValues.some((allowed) => jsonEquals(value, allowed))) {
+    const expected = enumValues.map((v) => renderJson(v)).join(", ");
+    const received = renderJson(value);
+    issues.push({
+      path,
+      keyword: "enum",
+      expected,
+      received,
+      message: `Parameter "${path}" must be one of [${expected}], received ${received}.`
+    });
+    return;
+  }
+  if (typeof value === "number") {
+    const min = schema["minimum"];
+    if (typeof min === "number" && value < min) {
+      issues.push({
+        path,
+        keyword: "minimum",
+        expected: `>= ${min}`,
+        received: render(value),
+        message: `Parameter "${path}" must be >= ${min}, received ${value}.`
+      });
+    }
+    const max = schema["maximum"];
+    if (typeof max === "number" && value > max) {
+      issues.push({
+        path,
+        keyword: "maximum",
+        expected: `<= ${max}`,
+        received: render(value),
+        message: `Parameter "${path}" must be <= ${max}, received ${value}.`
+      });
+    }
+  }
+  if (typeof value === "string") {
+    const minLength = schema["minLength"];
+    if (typeof minLength === "number" && value.length < minLength) {
+      issues.push({
+        path,
+        keyword: "minLength",
+        expected: `length >= ${minLength}`,
+        received: `length ${value.length}`,
+        message: `Parameter "${path}" must be at least ${minLength} characters, received ${value.length}.`
+      });
+    }
+    const maxLength = schema["maxLength"];
+    if (typeof maxLength === "number" && value.length > maxLength) {
+      issues.push({
+        path,
+        keyword: "maxLength",
+        expected: `length <= ${maxLength}`,
+        received: `length ${value.length}`,
+        message: `Parameter "${path}" must be at most ${maxLength} characters, received ${value.length}.`
+      });
+    }
+    const pattern = schema["pattern"];
+    if (typeof pattern === "string" && pattern.length <= MAX_PATTERN_LENGTH && !hasNestedQuantifiers(pattern)) {
+      let re;
+      try {
+        re = new RegExp(pattern);
+      } catch {
+        re = null;
+      }
+      if (re !== null && !re.test(value)) {
+        issues.push({
+          path,
+          keyword: "pattern",
+          expected: `match /${pattern}/`,
+          received: render(value),
+          message: `Parameter "${path}" must match /${pattern}/, received ${render(value)}.`
+        });
+      }
+    }
+  }
+  if (Array.isArray(value) && hasOwn(schema, "items")) {
+    const items = schema["items"];
+    value.forEach((element, index) => {
+      validateValue(element, items, `${path}[${index}]`, issues, depth + 1);
+    });
+  }
+  if (isPlainObject(value) && (isPlainObject(schema["properties"]) || hasOwn(schema, "required") || schema["additionalProperties"] === false)) {
+    validateObject(value, schema, path, issues, depth);
+  }
+}
+function validateObject(value, schema, basePath, issues, depth) {
+  if (depth > MAX_SCHEMA_DEPTH) return;
+  const properties = isPlainObject(schema["properties"]) ? schema["properties"] : {};
+  const requiredRaw = schema["required"];
+  const required = Array.isArray(requiredRaw) ? requiredRaw.filter((k) => typeof k === "string") : [];
+  for (const key of required) {
+    if (!hasOwn(value, key) || value[key] === void 0) {
+      const at = joinPath(basePath, key);
+      issues.push({
+        path: at,
+        keyword: "required",
+        expected: "present",
+        message: `Required parameter "${at}" is missing.`
+      });
+    }
+  }
+  if (schema["additionalProperties"] === false) {
+    const declared = new Set(Object.keys(properties));
+    const expected = declared.size === 0 ? "no parameters" : `one of [${[...declared].join(", ")}]`;
+    for (const key of Object.keys(value)) {
+      if (!declared.has(key)) {
+        const at = joinPath(basePath, key);
+        issues.push({
+          path: at,
+          keyword: "additionalProperties",
+          expected,
+          received: render(value[key]),
+          message: `Parameter "${at}" is not declared by the schema, which sets additionalProperties: false.`
+        });
+      }
+    }
+  }
+  for (const [key, propSchema] of Object.entries(properties)) {
+    if (!hasOwn(value, key) || value[key] === void 0) continue;
+    validateValue(value[key], propSchema, joinPath(basePath, key), issues, depth + 1);
+  }
+}
+function isObjectSchemaForm(schema) {
+  if (isPlainObject(schema["properties"])) return true;
+  if (schema["type"] !== "object") return false;
+  return Object.keys(schema).every((key) => OBJECT_SCHEMA_KEYWORDS.has(key));
+}
+function normalizeMapForm(schema) {
+  if (isObjectSchemaForm(schema)) return null;
+  const properties = {};
+  for (const [key, raw] of Object.entries(schema)) {
+    if (raw === null || raw === void 0) continue;
+    if (typeof raw === "string") {
+      properties[key] = PRIMITIVE_TYPE_NAMES.has(raw) ? { type: raw } : {};
+      continue;
+    }
+    if (isPlainObject(raw)) {
+      const { optional: _optional, ...rest } = raw;
+      properties[key] = rest;
+      continue;
+    }
+  }
+  return { type: "object", properties };
+}
+function validateActionParams(schema, params) {
+  if (!isPlainObject(schema)) return { valid: true, issues: [] };
+  const normalized = normalizeMapForm(schema) ?? schema;
+  const hasProperties = isPlainObject(normalized["properties"]);
+  const hasRequired = Array.isArray(normalized["required"]);
+  const forbidsExtras = normalized["additionalProperties"] === false;
+  if (!hasProperties && !hasRequired && !forbidsExtras) {
+    return { valid: true, issues: [] };
+  }
+  const issues = [];
+  if (params === void 0 || params === null) {
+    validateObject({}, normalized, "", issues, 0);
+    return { valid: issues.length === 0, issues };
+  }
+  if (!isPlainObject(params)) {
+    issues.push({
+      path: "",
+      keyword: "type",
+      expected: "object",
+      received: render(params),
+      message: `Action params must be an object, received ${jsonTypeOf(params)} (${render(params)}).`
+    });
+    return { valid: false, issues };
+  }
+  validateObject(params, normalized, "", issues, 0);
+  return { valid: issues.length === 0, issues };
+}
+function formatParamValidationFailure(componentId, actionId, issues) {
+  const detail = issues.map((i) => i.message).join(" ");
+  return `Action "${actionId}" on component "${componentId}" was rejected: params do not match the action's declared paramSchema. ${detail}`;
+}
+
+// src/core/abortable.ts
+var MAX_ACTION_TIMEOUT_MS = 864e5;
+function normalizeActionTimeoutMs(raw) {
+  if (raw === void 0 || raw === null) {
+    return { ok: true, timeoutMs: void 0, clamped: false };
+  }
+  if (typeof raw !== "number") {
+    return {
+      ok: false,
+      reason: `timeoutMs must be a number of milliseconds, received ${typeof raw === "string" ? JSON.stringify(raw) : typeof raw}`
+    };
+  }
+  if (!Number.isFinite(raw)) {
+    return {
+      ok: false,
+      reason: `timeoutMs must be a finite number of milliseconds, received ${String(raw)}`
+    };
+  }
+  if (raw < 0) {
+    return {
+      ok: false,
+      reason: `timeoutMs must not be negative, received ${String(raw)}`
+    };
+  }
+  if (raw > MAX_ACTION_TIMEOUT_MS) {
+    return { ok: true, timeoutMs: MAX_ACTION_TIMEOUT_MS, clamped: true };
+  }
+  return { ok: true, timeoutMs: Math.floor(raw), clamped: false };
+}
+function inertAbortSignal() {
+  return new AbortController().signal;
+}
+async function runAbortable(invoke, options = {}) {
+  const callerSignal = options.signal;
+  const timeoutMs = options.timeoutMs;
+  if (callerSignal?.aborted) {
+    return { aborted: true, reason: "signal" };
+  }
+  const controller = new AbortController();
+  let reason = "signal";
+  let timer;
+  const onCallerAbort = () => {
+    reason = "signal";
+    controller.abort();
+  };
+  callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
+  if (typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs >= 0) {
+    timer = setTimeout(
+      () => {
+        reason = "timeout";
+        controller.abort();
+      },
+      Math.min(timeoutMs, MAX_ACTION_TIMEOUT_MS)
+    );
+  }
+  try {
+    const abandoned = new Promise((resolve) => {
+      controller.signal.addEventListener("abort", () => resolve({ aborted: true, reason }), {
+        once: true
+      });
+    });
+    const completed = (async () => ({
+      aborted: false,
+      result: await invoke(controller.signal)
+    }))();
+    return await Promise.race([completed, abandoned]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+    callerSignal?.removeEventListener("abort", onCallerAbort);
+  }
+}
+
 // src/core/element-identifier.ts
 function createNativeElementIdentifier(id, options = {}) {
   return {
@@ -1219,6 +1941,68 @@ var DEFAULT_WAIT_OPTIONS = {
   timeout: 1e4,
   interval: 100
 };
+var NativeActionError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "NativeActionError";
+  }
+};
+var DEFAULT_SCROLL_INTO_VIEW_PADDING = 16;
+var SCROLL_INTO_VIEW_MEASURE_TIMEOUT_MS = 1e3;
+var SCROLL_INTO_VIEW_WINDOW_MEASURE_TIMEOUT_MS = 250;
+function measurePageRectNow(element, preferred) {
+  const preferredNode = preferred;
+  const node = preferredNode && typeof preferredNode.measureInWindow === "function" ? preferredNode : element.ref.current;
+  if (!node || typeof node.measureInWindow !== "function") {
+    const state = element.getState();
+    return Promise.resolve(state.visible ? pageRectOf(state) : null);
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (rect) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(rect);
+    };
+    const timer = setTimeout(() => done(null), SCROLL_INTO_VIEW_WINDOW_MEASURE_TIMEOUT_MS);
+    try {
+      node.measureInWindow(
+        (x, y, w, h) => done(
+          [x, y, w, h].every(Number.isFinite) && w > 0 && h > 0 ? { left: x, top: y, right: x + w, bottom: y + h } : null
+        )
+      );
+    } catch {
+      done(null);
+    }
+  });
+}
+function resolveScrollView(current) {
+  const c = current;
+  if (!c) return null;
+  if (typeof c.scrollTo === "function")
+    return c;
+  for (const unwrap of [c.getNativeScrollRef, c.getScrollResponder]) {
+    if (typeof unwrap !== "function") continue;
+    let inner;
+    try {
+      inner = unwrap.call(c);
+    } catch {
+      inner = null;
+    }
+    if (inner && typeof inner.scrollTo === "function")
+      return inner;
+  }
+  return null;
+}
+function isDeclaredHorizontal(registeredProps, ...refs) {
+  if (registeredProps?.horizontal === true) return true;
+  return refs.some((r) => {
+    const props = r?.props;
+    return props !== null && typeof props === "object" && props.horizontal === true;
+  });
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1338,6 +2122,7 @@ var DefaultNativeActionExecutor = class {
       return {
         success: false,
         error: errorMsg,
+        ...error3 instanceof NativeActionError ? { code: error3.code } : {},
         stack: error3 instanceof Error ? error3.stack : void 0,
         durationMs: failTime - startTime,
         timestamp: failTime,
@@ -1355,7 +2140,7 @@ var DefaultNativeActionExecutor = class {
     }
     const props = element.props || {};
     if (element.customActions && action in element.customActions) {
-      return element.customActions[action].handler(params);
+      return element.customActions[action].handler(params, { signal: inertAbortSignal() });
     }
     switch (action) {
       case "click":
@@ -1378,6 +2163,11 @@ var DefaultNativeActionExecutor = class {
         return this.performBlur(element);
       case "scroll":
         return this.performScroll(props, params);
+      case "scrollIntoView":
+        return this.performScrollIntoView(
+          element,
+          params
+        );
       case "swipe":
         return this.performSwipe(props, params);
       case "toggle":
@@ -1544,6 +2334,138 @@ var DefaultNativeActionExecutor = class {
       props.onScroll(event);
     }
   }
+  /**
+   * Perform scrollIntoView: scroll the element's DECLARED scroll container so
+   * the element sits `padding` dp below the top of its viewport.
+   *
+   * The container comes from `scrollAncestorId` and nowhere else — the
+   * registry keeps no parent chain (`RegisterElementOptions.scrollAncestorId`),
+   * so there is no "nearest ScrollView" to find. Nothing here tracks a
+   * ScrollView's content offset either (`performScroll` only fakes an
+   * `onScroll` event), so the target is measured CONTENT-relative with
+   * `measureLayout` against the container's inner content view: stateless,
+   * and immune to a stale-offset race.
+   *
+   * Result shape mirrors the web executor's `scrollIntoView`
+   * (`@qontinui/ui-bridge` `control/action-executor.ts`):
+   * `{ alreadyVisible, scrolled }`, short-circuiting when the element is
+   * already fully inside its clip region. "Fully visible" is only claimed when
+   * it is MEASURED — a page-space rect for the element and a known,
+   * non-empty clip (window ∩ declared container), both measured at call
+   * time. Anything unknown scrolls.
+   *
+   * Containers: a ScrollView, or a VirtualizedList (FlatList / SectionList)
+   * unwrapped through `getNativeScrollRef()` / `getScrollResponder()`.
+   * Vertical only — a `horizontal` container is NOT_SUPPORTED. The action
+   * returns once `scrollTo` is dispatched; positions settle on the next frame.
+   *
+   * Prerequisites are checked BEFORE the visibility short-circuit, so whether
+   * the element supports the action does not depend on where it happens to be
+   * on screen. Each missing prerequisite is a `NOT_SUPPORTED` failure.
+   */
+  async performScrollIntoView(element, params) {
+    const padding = params?.padding ?? DEFAULT_SCROLL_INTO_VIEW_PADDING;
+    if (typeof padding !== "number" || !Number.isFinite(padding) || padding < 0) {
+      throw new Error('scrollIntoView "padding" must be a finite, non-negative number');
+    }
+    const ancestorId = element.scrollAncestorId;
+    if (!ancestorId) {
+      throw new NativeActionError(
+        `scrollIntoView is not supported on element "${element.id}": it declares no scrollAncestorId, and the registry keeps no parent chain to find its scroll container from`,
+        "NOT_SUPPORTED"
+      );
+    }
+    const ancestor = ancestorId === element.id ? void 0 : this.registry.getElement(ancestorId);
+    if (!ancestor) {
+      throw new NativeActionError(
+        `scrollIntoView is not supported on element "${element.id}": its declared scrollAncestorId "${ancestorId}" is not a registered element`,
+        "NOT_SUPPORTED"
+      );
+    }
+    const container = resolveScrollView(ancestor.ref.current);
+    if (!container) {
+      throw new NativeActionError(
+        `scrollIntoView is not supported on element "${element.id}": its scroll ancestor "${ancestorId}" has no scrollTo (not a mounted ScrollView, and no getNativeScrollRef/getScrollResponder yielding one)`,
+        "NOT_SUPPORTED"
+      );
+    }
+    if (isDeclaredHorizontal(ancestor.props, ancestor.ref.current, container)) {
+      throw new NativeActionError(
+        `scrollIntoView is not supported on element "${element.id}": its scroll ancestor "${ancestorId}" is horizontal (only vertical containers are supported)`,
+        "NOT_SUPPORTED"
+      );
+    }
+    const innerViewRef = container.getInnerViewRef?.();
+    const innerView = innerViewRef ?? container.getInnerViewNode?.();
+    const innerViewIsTag = innerViewRef == null && typeof innerView === "number";
+    if (innerView === void 0 || innerView === null) {
+      throw new NativeActionError(
+        `scrollIntoView is not supported on element "${element.id}": its scroll ancestor "${ancestorId}" exposes no inner content view to measure against`,
+        "NOT_SUPPORTED"
+      );
+    }
+    const target = element.ref.current;
+    if (!target || typeof target.measureLayout !== "function") {
+      throw new NativeActionError(
+        `scrollIntoView is not supported on element "${element.id}": its ref has no measureLayout (not a mounted host view)`,
+        "NOT_SUPPORTED"
+      );
+    }
+    const [rect, ancestorRect] = await Promise.all([
+      measurePageRectNow(element),
+      measurePageRectNow(ancestor, container)
+    ]);
+    const viewport = this.registry.getViewportRect();
+    const clip = ancestorRect ? intersectRects(viewport, ancestorRect) : null;
+    if (rect && clip && !isEmptyRect(clip) && rect.right > rect.left && rect.bottom > rect.top && rect.top >= clip.top && rect.left >= clip.left && rect.bottom <= clip.bottom && rect.right <= clip.right) {
+      return { alreadyVisible: true, scrolled: false };
+    }
+    const measured = await new Promise(
+      (resolve, reject) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+          if (settled) return;
+          settled = true;
+          reject(
+            new Error(
+              `scrollIntoView: measureLayout did not call back within ${SCROLL_INTO_VIEW_MEASURE_TIMEOUT_MS}ms` + (innerViewIsTag ? " (measured against a numeric inner-view tag from getInnerViewNode, which the new architecture does not support)" : "")
+            )
+          );
+        }, SCROLL_INTO_VIEW_MEASURE_TIMEOUT_MS);
+        const finish = (fn) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          fn();
+        };
+        try {
+          target.measureLayout(
+            innerView,
+            (x, y, width) => finish(
+              () => Number.isFinite(y) ? resolve({ x, y, width }) : reject(new Error("scrollIntoView: measureLayout returned a non-finite y"))
+            ),
+            () => finish(
+              () => reject(
+                new Error(
+                  `scrollIntoView: measureLayout failed for "${element.id}" relative to "${ancestorId}"`
+                )
+              )
+            )
+          );
+        } catch (error3) {
+          finish(() => reject(error3));
+        }
+      }
+    );
+    if (ancestorRect && Number.isFinite(measured.x) && Number.isFinite(measured.width) && measured.x + measured.width > ancestorRect.right - ancestorRect.left + 1) {
+      throw new NativeActionError(
+        `scrollIntoView is not supported on element "${element.id}": it is laid out beyond the horizontal extent of its scroll ancestor "${ancestorId}" (sideways overflow, a horizontal container, or a nested horizontal container \u2014 declare that inner container as its scrollAncestorId); only vertical scrolling is supported`,
+        "NOT_SUPPORTED"
+      );
+    }
+    container.scrollTo({ y: Math.max(0, measured.y - padding), animated: false });
+    return { alreadyVisible: false, scrolled: true };
+  }
   /**
    * Perform swipe action
    */
@@ -1598,7 +2520,7 @@ var DefaultNativeActionExecutor = class {
   /**
    * Execute a component action
    */
-  async executeComponentAction(componentId, request) {
+  async executeComponentAction(componentId, request, options = {}) {
     const startTime = Date.now();
     try {
       const component = this.registry.getComponent(componentId);
@@ -1621,10 +2543,71 @@ var DefaultNativeActionExecutor = class {
           requestId: request.requestId
         };
       }
-      const result = await action.handler(request.params);
+      const timeout = normalizeActionTimeoutMs(request.timeoutMs);
+      if (!timeout.ok) {
+        return {
+          success: false,
+          error: `Action "${request.action}" on component "${componentId}" was rejected: ${timeout.reason}.`,
+          durationMs: Date.now() - startTime,
+          timestamp: Date.now(),
+          requestId: request.requestId
+        };
+      }
+      const timeoutMs = timeout.timeoutMs;
+      const validationMode = options.paramValidation ?? getDefaultParamValidationMode();
+      if (validationMode !== "off" && action.paramSchema !== void 0) {
+        let validation;
+        try {
+          validation = validateActionParams(action.paramSchema, request.params);
+        } catch (validatorFault) {
+          const detail = validatorFault instanceof Error ? validatorFault.message : String(validatorFault);
+          const faultMessage = `Action "${request.action}" on component "${componentId}": its declared paramSchema could not be evaluated (${detail}).`;
+          if (validationMode === "enforce") {
+            return {
+              success: false,
+              error: faultMessage,
+              durationMs: Date.now() - startTime,
+              timestamp: Date.now(),
+              requestId: request.requestId
+            };
+          }
+          console.warn(`[ui-bridge-native] ${faultMessage}`);
+          validation = { valid: true, issues: [] };
+        }
+        if (!validation.valid) {
+          const message = formatParamValidationFailure(
+            componentId,
+            request.action,
+            validation.issues
+          );
+          if (validationMode === "enforce") {
+            return {
+              success: false,
+              error: message,
+              durationMs: Date.now() - startTime,
+              timestamp: Date.now(),
+              requestId: request.requestId
+            };
+          }
+          console.warn(`[ui-bridge-native] ${message}`);
+        }
+      }
+      const outcome = await runAbortable((signal) => action.handler(request.params, { signal }), {
+        signal: options.signal,
+        timeoutMs
+      });
+      if (outcome.aborted) {
+        return {
+          success: false,
+          error: outcome.reason === "timeout" ? `Action "${request.action}" on component "${componentId}" was abandoned after its ${timeoutMs}ms timeout elapsed.` : `Action "${request.action}" on component "${componentId}" was cancelled by the caller's abort signal.`,
+          durationMs: Date.now() - startTime,
+          timestamp: Date.now(),
+          requestId: request.requestId
+        };
+      }
       return {
         success: true,
-        result,
+        result: outcome.result,
         durationMs: Date.now() - startTime,
         timestamp: Date.now(),
         requestId: request.requestId
@@ -2698,10 +3681,14 @@ function createServerHandlers(registry, executor, config) {
       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,
@@ -2719,10 +3706,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
         };
@@ -2744,7 +3732,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
         }
@@ -2765,13 +3753,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);
     },
@@ -2781,7 +3765,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 });
@@ -2800,7 +3788,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
         }
@@ -2811,7 +3801,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");
@@ -3003,9 +3994,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.',
@@ -3332,18 +4326,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;
@@ -3376,10 +4364,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) {
@@ -3409,7 +4394,7 @@ function createServerHandlers(registry, executor, config) {
       };
       if (config?.appInfo) {
         response.uiBridge = {
-          version: "0.6.12",
+          version: "0.6.13",
           ...config.appInfo,
           capabilities: ["elements", "components", "actions", "design"],
           elementCount: stats.elements,
@@ -3557,8 +4542,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;
@@ -3566,12 +4591,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,
@@ -3601,10 +4634,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,
@@ -3614,6 +4651,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 ?? "";
@@ -3693,6 +4733,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("/");
@@ -3855,6 +4905,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",
@@ -3917,6 +4984,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" }
 ];
@@ -4114,7 +5185,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
@@ -4129,7 +5202,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 };
         }
@@ -4139,11 +5217,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() };
@@ -4809,8 +5902,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)
       };
@@ -4867,7 +5967,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;
@@ -4884,9 +5984,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()
     };
@@ -5190,6 +6291,31 @@ function createTransportLogger() {
 }
 var transportLogger = createTransportLogger();
 
+// src/transport/relay-logging.ts
+var CREDENTIAL_PARAMS = ["token", "access_token", "auth", "authorization", "key", "sig"];
+var CREDENTIAL_PARAM_RE = new RegExp(`([?&](?:${CREDENTIAL_PARAMS.join("|")})=)[^&#]*`, "gi");
+var USERINFO_RE = /^([a-z][a-z0-9+.-]*:\/\/)[^/?#@]*@/i;
+function redactRelayUrl(url) {
+  return url.replace(USERINFO_RE, "$1<redacted>@").replace(CREDENTIAL_PARAM_RE, "$1<redacted>");
+}
+function describeCloseEvent(event) {
+  const e = event ?? {};
+  const code = typeof e.code === "number" ? String(e.code) : "unknown";
+  const reason = typeof e.reason === "string" && e.reason.length > 0 ? e.reason : "(none)";
+  const wasClean = typeof e.wasClean === "boolean" ? String(e.wasClean) : "unknown";
+  return `code=${code} reason=${reason} wasClean=${wasClean}`;
+}
+function describeErrorEvent(event) {
+  const e = event ?? {};
+  const parts = [];
+  if (typeof e.message === "string" && e.message.length > 0) parts.push(`message=${e.message}`);
+  if (e.error instanceof Error) parts.push(`error=${e.error.message}`);
+  else if (typeof e.error === "string" && e.error.length > 0) parts.push(`error=${e.error}`);
+  if (typeof e.code === "number") parts.push(`code=${e.code}`);
+  if (parts.length === 0) parts.push("message=(none reported by the transport)");
+  return parts.join(" ");
+}
+
 // src/transport/DeviceAnnouncer.ts
 var DEFAULT_PORT = 8087;
 var RECONNECT_INITIAL_DELAY_MS = 2e3;
@@ -5259,7 +6385,8 @@ var DeviceAnnouncer = class {
     }
     if (this.stopped) return;
     const url = `${this.config.cloudRelayUrl}?token=${encodeURIComponent(this.config.cloudToken)}`;
-    transportLogger.log("[DeviceAnnouncer] Cloud relay: connecting to", url);
+    const safeUrl = redactRelayUrl(url);
+    transportLogger.log("[DeviceAnnouncer] Cloud relay: connecting to", safeUrl);
     const ws = new WebSocket(url);
     this.cloudWs = ws;
     ws.onopen = () => {
@@ -5288,14 +6415,22 @@ var DeviceAnnouncer = class {
       } catch {
       }
     };
-    ws.onclose = () => {
+    ws.onclose = (event) => {
       this.state = { ...this.state, cloudConnected: false };
-      if (!this.stopped) {
+      const detail = describeCloseEvent(event);
+      if (this.stopped) {
+        transportLogger.log(`[DeviceAnnouncer] Cloud relay closed ${detail} url=${safeUrl}`);
+      } else {
+        transportLogger.warn(
+          `[DeviceAnnouncer] Cloud relay closed unexpectedly ${detail} url=${safeUrl}`
+        );
         this.scheduleReconnect();
       }
     };
     ws.onerror = (err) => {
-      transportLogger.warn("[DeviceAnnouncer] Cloud relay error:", err);
+      transportLogger.warn(
+        `[DeviceAnnouncer] Cloud relay error: ${describeErrorEvent(err)} url=${safeUrl}`
+      );
     };
   }
   // ── Lifecycle ─────────────────────────────────────────────────────────────
@@ -5392,7 +6527,8 @@ var CloudRelayClient = class {
   connect() {
     if (this.stopped) return;
     const url = `${this.config.relayUrl}?token=${encodeURIComponent(this.config.authToken)}`;
-    transportLogger.log("[CloudRelayClient] Connecting to", url);
+    const safeUrl = redactRelayUrl(url);
+    transportLogger.log("[CloudRelayClient] Connecting to", safeUrl);
     const ws = new WebSocket(url);
     this.ws = ws;
     ws.onopen = () => {
@@ -5413,14 +6549,22 @@ var CloudRelayClient = class {
     ws.onmessage = (event) => {
       void this.onMessage(event.data);
     };
-    ws.onclose = () => {
+    ws.onclose = (event) => {
       this._isConnected = false;
-      if (!this.stopped) {
+      const detail = describeCloseEvent(event);
+      if (this.stopped) {
+        transportLogger.log(`[CloudRelayClient] WebSocket closed ${detail} url=${safeUrl}`);
+      } else {
+        transportLogger.warn(
+          `[CloudRelayClient] WebSocket closed unexpectedly ${detail} url=${safeUrl}`
+        );
         this.scheduleReconnect();
       }
     };
     ws.onerror = (err) => {
-      transportLogger.warn("[CloudRelayClient] WebSocket error:", err);
+      transportLogger.warn(
+        `[CloudRelayClient] WebSocket error: ${describeErrorEvent(err)} url=${safeUrl}`
+      );
     };
   }
   async onMessage(raw) {
@@ -5699,10 +6843,20 @@ var UndoTracker = class {
   }
 };
 var UIBridgeNativeContext = createContext(null);
+var EMPTY_FEATURES = {};
+var EMPTY_CONFIG = {};
+function useValueStable(value) {
+  const signature = JSON.stringify(value);
+  return useMemo(() => value, [signature]);
+}
+function readWindowViewport() {
+  const win = Dimensions.get("window");
+  return { width: win.width, height: win.height };
+}
 function UIBridgeNativeProvider({
   children,
-  features = {},
-  config = {},
+  features: featuresProp = EMPTY_FEATURES,
+  config: configProp = EMPTY_CONFIG,
   onEvent,
   serverAdapter,
   navigationProvider,
@@ -5713,6 +6867,8 @@ function UIBridgeNativeProvider({
   enableMdnsAnnounce,
   deviceId
 }) {
+  const features = useValueStable(featuresProp);
+  const config = useValueStable(configProp);
   const registryRef = useRef(null);
   const executorRef = useRef(null);
   const modalDetectorRef = useRef(null);
@@ -5725,6 +6881,7 @@ function UIBridgeNativeProvider({
       onEvent
     });
     registryRef.current.setPixelRatio(PixelRatio.get());
+    registryRef.current.setViewportProvider(readWindowViewport);
     setGlobalRegistry(registryRef.current);
   }
   const registry = registryRef.current;
@@ -5759,16 +6916,10 @@ function UIBridgeNativeProvider({
       // the `testHooks` value when undefined, so passing it through verbatim
       // keeps existing consumers unchanged.
       observability: features.observability,
-      // Injected device-viewport getter for POST /control/page-health. The
-      // server doesn't import `react-native` itself — the require/import
-      // pattern there crashed the host RN app in 0.6.3/0.6.4 (Metro/Hermes
-      // raised `unknownModuleError` past every try/catch). This provider
-      // already has a live react-native import, so it's the safe injection
-      // point. See feedback_metro_require_gotcha for the full incident.
-      viewportProvider: () => {
-        const win = Dimensions.get("window");
-        return { width: win.width, height: win.height };
-      }
+      // Injected device-viewport getter for POST /control/page-health and the
+      // design handlers. Same source as the registry's clipping bounds — see
+      // `readWindowViewport`.
+      viewportProvider: readWindowViewport
     });
     server.setAdapter(serverAdapter);
     if (navigationProvider) {
@@ -5866,10 +7017,7 @@ function UIBridgeNativeProvider({
             appInfo: config.appInfo,
             testHooks: features.testHooks === true,
             observability: features.observability,
-            viewportProvider: () => {
-              const win = Dimensions.get("window");
-              return { width: win.width, height: win.height };
-            }
+            viewportProvider: readWindowViewport
           });
           if (navigationProvider) bareServer.setNavigationProvider(navigationProvider);
           if (screenshotProvider) bareServer.setScreenshotProvider(screenshotProvider);
@@ -6074,6 +7222,7 @@ function useUIElement(options) {
   const propsRef = useRef({});
   const registeredRef = useRef(false);
   const registeredIdRef = useRef(null);
+  const autoPublishedLabelRef = useRef(void 0);
   const bridgeRef = useRef(bridge);
   bridgeRef.current = bridge;
   const nodeRef = useRef(null);
@@ -6113,6 +7262,7 @@ function useUIElement(options) {
     autoRegister = true,
     onStateChange,
     parentPath,
+    scrollAncestorId,
     style,
     stateStyles: stateStylesProp,
     handlers: handlersProp,
@@ -6137,22 +7287,38 @@ function useUIElement(options) {
       testId: id,
       accessibilityLabel: label,
       registrationRoute: bridge.getCurrentRoute(),
+      scrollAncestorId,
       flatStyle: flattenStyle(style),
       stateStyles: flattenStateStyles(stateStylesProp)
     });
     registeredRef.current = true;
     registeredIdRef.current = id;
+    autoPublishedLabelRef.current = typeof label === "string" ? label : void 0;
     if (typeof valueProp === "string") {
       bridge.registry.updateElementState(id, { value: valueProp });
     }
     setRegistered(true);
     scheduleDeadButtonWarning(bridge, id, type);
-  }, [bridge, id, type, label, actions, customActions, treePath, style, stateStylesProp, valueProp, ref]);
+  }, [
+    bridge,
+    id,
+    type,
+    label,
+    actions,
+    customActions,
+    treePath,
+    scrollAncestorId,
+    style,
+    stateStylesProp,
+    valueProp,
+    ref
+  ]);
   const unregister = useCallback(() => {
     if (!bridge || !registeredRef.current) return;
     bridge.registry.unregisterElement(registeredIdRef.current ?? id);
     registeredRef.current = false;
     registeredIdRef.current = null;
+    autoPublishedLabelRef.current = void 0;
     setRegistered(false);
   }, [bridge, id]);
   const onStateChangeRef = useRef(onStateChange);
@@ -6180,7 +7346,7 @@ function useUIElement(options) {
           writeLayout({ x, y, width, height, pageX, pageY });
         });
       } else {
-        writeLayout({ x, y, width, height, pageX: x, pageY: y });
+        writeLayout({ x, y, width, height, pageX: x, pageY: y, pageOriginUnmeasured: true });
       }
     },
     // `ref` is the once-per-hook interceptor object — identity-stable.
@@ -6292,6 +7458,16 @@ function useUIElement(options) {
     if (current === valueProp) return;
     bridge.registry.updateElementState(id, { value: valueProp });
   }, [bridge, registered, id, valueProp]);
+  useEffect(() => {
+    if (!bridge || !registered) return;
+    if (typeof label !== "string") return;
+    autoPublishedLabelRef.current = label;
+    bridge.registry.updateElementMeta(id, {
+      label,
+      accessibilityLabel: label,
+      testId: id
+    });
+  }, [bridge, registered, id, label]);
   useCallback(
     (props) => {
       propsRef.current = { ...propsRef.current, ...props };
@@ -6334,7 +7510,8 @@ function useUIElement(options) {
         accessibilityLabel: newLabel,
         testId: id
       });
-      if (!changed && !warnedRedundantUpdateLabelIds.has(id)) {
+      const alreadyPublishedBySdk = newLabel === autoPublishedLabelRef.current;
+      if (!changed && !alreadyPublishedBySdk && !warnedRedundantUpdateLabelIds.has(id)) {
         warnedRedundantUpdateLabelIds.add(id);
         console.warn(
           `[UI Bridge] updateLabel("${newLabel}") on element "${id}" was a no-op (label unchanged). Gate the call behind a useEffect with [label] deps to avoid redundant publishes.`
@@ -6390,36 +7567,56 @@ function useUIElementWithProps(options) {
 }
 function useUIComponent(options) {
   const bridge = useUIBridgeNativeOptional();
+  const [registered, setRegistered] = useState(false);
+  const [publishVersion, setPublishVersion] = useState(0);
+  const publishedIdRef = useRef(null);
   const registeredRef = useRef(false);
   const registeredIdRef = useRef(null);
   const actionsRef = useRef(options.actions || []);
   const elementIdsRef = useRef(options.elementIds || []);
   const { id, name, description, autoRegister = true } = options;
+  const actionsSignature = JSON.stringify(
+    (options.actions ?? []).map((a) => [a.id, a.label, a.description, a.paramSchema, a.effect])
+  );
+  const elementIdsSignature = JSON.stringify(options.elementIds ?? []);
   useEffect(() => {
-    actionsRef.current = options.actions || [];
-    elementIdsRef.current = options.elementIds || [];
-  }, [options.actions, options.elementIds]);
+    if (options.actions !== void 0) actionsRef.current = options.actions;
+  }, [options.actions]);
+  useEffect(() => {
+    if (options.elementIds !== void 0) elementIdsRef.current = options.elementIds;
+  }, [elementIdsSignature]);
+  const toRegistryActions = useCallback(
+    () => actionsRef.current.map(({ handler: declaredHandler, ...rest }) => ({
+      ...rest,
+      handler: (params, handlerOptions) => {
+        const latest = actionsRef.current.find((a) => a.id === rest.id);
+        return (latest?.handler ?? declaredHandler)(params, handlerOptions);
+      }
+    })),
+    []
+  );
   const register = useCallback(() => {
     if (!bridge || registeredRef.current) return;
     bridge.registry.registerComponent(id, {
       name,
       description,
-      actions: actionsRef.current.map((a) => ({
-        id: a.id,
-        label: a.label,
-        description: a.description,
-        handler: a.handler
-      })),
+      actions: toRegistryActions(),
       elementIds: elementIdsRef.current
     });
     registeredRef.current = true;
     registeredIdRef.current = id;
-  }, [bridge, id, name, description]);
+    setRegistered(true);
+    if (publishedIdRef.current !== id) {
+      publishedIdRef.current = id;
+      setPublishVersion((v) => v + 1);
+    }
+  }, [bridge, id, name, description, toRegistryActions]);
   const unregister = useCallback(() => {
     if (!bridge || !registeredRef.current) return;
     bridge.registry.unregisterComponent(registeredIdRef.current ?? id);
     registeredRef.current = false;
     registeredIdRef.current = null;
+    setRegistered(false);
   }, [bridge, id]);
   const executeAction = useCallback(
     async (actionId, params) => {
@@ -6437,25 +7634,47 @@ function useUIComponent(options) {
     },
     [bridge, id]
   );
+  const publishElementIds = useCallback(() => {
+    if (!registeredRef.current || !bridge) return;
+    const changed = bridge.registry.updateComponentMeta(registeredIdRef.current ?? id, {
+      elementIds: elementIdsRef.current
+    });
+    if (changed) {
+      setPublishVersion((v) => v + 1);
+    }
+  }, [bridge, id]);
   const updateActions = useCallback(
     (actions) => {
       actionsRef.current = actions;
       if (registeredRef.current && bridge) {
-        bridge.registry.unregisterComponent(id);
-        registeredRef.current = false;
-        register();
+        const targetId = registeredIdRef.current ?? id;
+        const changed = bridge.registry.updateComponentMeta(targetId, {
+          actions: toRegistryActions()
+        });
+        if (changed) {
+          setPublishVersion((v) => v + 1);
+        }
       }
     },
-    [bridge, id, register]
+    [bridge, id, toRegistryActions]
+  );
+  const addElement = useCallback(
+    (elementId) => {
+      if (!elementIdsRef.current.includes(elementId)) {
+        elementIdsRef.current = [...elementIdsRef.current, elementId];
+        publishElementIds();
+      }
+    },
+    [publishElementIds]
+  );
+  const removeElement = useCallback(
+    (elementId) => {
+      if (!elementIdsRef.current.includes(elementId)) return;
+      elementIdsRef.current = elementIdsRef.current.filter((eid) => eid !== elementId);
+      publishElementIds();
+    },
+    [publishElementIds]
   );
-  const addElement = useCallback((elementId) => {
-    if (!elementIdsRef.current.includes(elementId)) {
-      elementIdsRef.current = [...elementIdsRef.current, elementId];
-    }
-  }, []);
-  const removeElement = useCallback((elementId) => {
-    elementIdsRef.current = elementIdsRef.current.filter((eid) => eid !== elementId);
-  }, []);
   const registerRef = useRef(register);
   const unregisterRef = useRef(unregister);
   useEffect(() => {
@@ -6471,13 +7690,32 @@ function useUIComponent(options) {
         unregisterRef.current();
       }
     };
-  }, [autoRegister, bridge]);
-  const registeredComponent = useMemo(() => {
-    if (!bridge) return null;
-    return bridge.registry.getComponent(id) || null;
-  }, [bridge, id]);
+  }, [autoRegister, bridge, id]);
+  useEffect(() => {
+    if (!bridge || !registered) return;
+    const targetId = registeredIdRef.current ?? id;
+    const changed = bridge.registry.updateComponentMeta(targetId, {
+      name,
+      description,
+      ...options.actions !== void 0 ? { actions: toRegistryActions() } : {},
+      ...options.elementIds !== void 0 ? { elementIds: elementIdsRef.current } : {}
+    });
+    if (changed) {
+      setPublishVersion((v) => v + 1);
+    }
+  }, [
+    bridge,
+    registered,
+    id,
+    name,
+    description,
+    actionsSignature,
+    elementIdsSignature,
+    toRegistryActions
+  ]);
+  const registeredComponent = registered && bridge ? bridge.registry.getComponent(id) ?? null : null;
   return {
-    registered: registeredRef.current,
+    registered,
     executeAction,
     register,
     unregister,
@@ -6635,12 +7873,31 @@ function TransitionTo(props) {
 
 // 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",
@@ -6678,6 +7935,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",
@@ -6688,11 +7950,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",
@@ -6771,6 +8100,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",
@@ -6802,18 +8152,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).
@@ -7639,6 +9005,6 @@ var styles = StyleSheet.create({
   }
 });
 
-export { CloudRelayClient, DefaultNativeActionExecutor, DeviceAnnouncer, ModalDetector, NativeUIBridgeRegistry, NativeUIBridgeServer, State, ToastCapture, TransitionTo, UIBridgeInspector, UIBridgeNativeProvider, UI_BRIDGE_NATIVE_ROUTES, UndoTracker, WebSocketConnection, WebSocketEventBridge, bindWithRetry, buildTreePath, buildUpgradeResponse, captureNativeResponsiveSnapshot, captureNativeStateVariations, computeAcceptKey, createDesignHandlers, createNativeActionExecutor, createNativeElementIdentifier, createNativeServer, createServerHandlers, deriveInteractable, deriveText, extractHandlerNames, findAllByPattern, findElementByIdentifier, getGlobalRegistry, getNativeElementDesignData, isAddrInUseError, mapNativeStyleToExtended, matchesIdentifier, parseColorToRgb, parseFontSizePx, parseTreePath, projectVisionFields, resetGlobalRegistry, roleForType, setGlobalRegistry, useToastRecorder, useUIBridge, useUIBridgeModal, useUIBridgeNative, useUIBridgeNativeOptional, useUIBridgeNativeRequired, useUIBridgeRequired, useUIBridgeToast, useUIComponent, useUIComponentAction, useUIElement, useUIElementWithProps };
+export { CloudRelayClient, DEFAULT_PARAM_VALIDATION_MODE, DefaultNativeActionExecutor, DeviceAnnouncer, MAX_ACTION_TIMEOUT_MS, ModalDetector, NATIVE_STANDARD_ACTION_EFFECTS, NativeActionError, NativeUIBridgeRegistry, NativeUIBridgeServer, State, ToastCapture, TransitionTo, UIBridgeInspector, UIBridgeNativeProvider, UI_BRIDGE_NATIVE_ROUTES, UndoTracker, WebSocketConnection, WebSocketEventBridge, bindWithRetry, buildTreePath, buildUpgradeResponse, captureNativeResponsiveSnapshot, captureNativeStateVariations, computeAcceptKey, computeVisibility, createDesignHandlers, createNativeActionExecutor, createNativeElementIdentifier, createNativeServer, createServerHandlers, deriveInteractable, deriveText, extractHandlerNames, findAllByPattern, findElementByIdentifier, formatParamValidationFailure, getDefaultParamValidationMode, getGlobalRegistry, getNativeElementDesignData, httpStatusForResponse, inertAbortSignal, intersectRects, isAddrInUseError, isEmptyRect, mapNativeStyleToExtended, matchesIdentifier, nativeStandardActionEffect, normalizeActionTimeoutMs, pageRectOf, parseColorToRgb, parseFontSizePx, parseTreePath, projectVisionFields, resetDefaultParamValidationMode, resetGlobalRegistry, resolveActionEffect, roleForType, runAbortable, setDefaultParamValidationMode, setGlobalRegistry, useToastRecorder, useUIBridge, useUIBridgeModal, useUIBridgeNative, useUIBridgeNativeOptional, useUIBridgeNativeRequired, useUIBridgeRequired, useUIBridgeToast, useUIComponent, useUIComponentAction, useUIElement, useUIElementWithProps, validateActionParams };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map