@qontinui/ui-bridge-native 0.6.11 → 0.6.13

package/dist/core/index.mjs

@@ -1,3 +1,465 @@
+// 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/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/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/vision-fields.ts
 var INTERACTIVE_HANDLER_NAMES = /* @__PURE__ */ new Set([
   "onPress",
@@ -171,7 +633,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");
@@ -180,6 +677,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;
@@ -199,8 +712,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":
@@ -272,6 +835,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
@@ -309,6 +884,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 (error) {
+        if (this.config.verbose) {
+          console.warn(`[ui-bridge-native] routeProvider getActiveTab threw:`, error);
+        }
+        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
@@ -324,6 +923,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 (error) {
+      if (this.config.verbose) {
+        console.warn(`[ui-bridge-native] viewportProvider threw:`, error);
+      }
+      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
   // ============================================================================
@@ -367,16 +1016,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) {
@@ -419,6 +1069,7 @@ var NativeUIBridgeRegistry = class {
       registeredAt: Date.now(),
       mounted: true,
       registrationRoute: registrationRoute ?? null,
+      scrollAncestorId,
       flatStyle,
       stateStyles
     };
@@ -549,6 +1200,103 @@ var NativeUIBridgeRegistry = class {
       console.log(`[ui-bridge-native] Marked ${cleared} elements offscreen for route: ${route}`);
     }
   }
+  /**
+   * Re-measure every mounted-visible element's geometry via its stored React
+   * ref and write the fresh coordinates into the registry ("measure-on-
+   * snapshot").
+   *
+   * Why: element geometry is otherwise captured ONCE at mount time
+   * (`onLayout` + `measureInWindow` in `useUIElement`) and RN never re-fires
+   * `onLayout` on pure translation — scrolling a virtualized list
+   * (FlashList), recycling a cell, a keyboard shift or an orientation change
+   * all move elements WITHOUT updating the stored `state.layout`. Snapshot
+   * consumers (vision analyzers hit-testing `bbox`, coord-based tap) then
+   * operate on stale positions. Re-measuring at READ time is correct
+   * regardless of what moved the element and needs zero per-consumer wiring:
+   * every registry entry already stores its ref (see `registerElement`).
+   *
+   * Per-element outcomes:
+   *   - non-zero dims → write a fresh full layout (same state shape as the
+   *     mount-time measure loop in `useUIElement`); counted as `measured`.
+   *   - zero dims AND the element previously had a non-null `state.layout` →
+   *     the view collapsed / left the screen; clear to
+   *     `{ visible: false, layout: null }` (same shape `markRouteOffscreen`
+   *     writes); counted as `cleared`.
+   *   - zero dims and it never had a layout → leave state untouched (element
+   *     in the mount→first-onLayout gap; don't demote `likely-visible`);
+   *     counted as `skipped`.
+   *   - no ref / no callable `measureInWindow` (test fixtures, web) → leave
+   *     untouched; counted as `skipped`.
+   *
+   * The whole sweep races an overall timeout (default 250 ms) so a dead ref
+   * whose `measureInWindow` never calls back can never hang a snapshot: the
+   * returned promise resolves at the deadline with whatever counts have
+   * accumulated. Late callbacks may still write state afterwards — harmless,
+   * freshest data wins. Never throws.
+   *
+   * Non-React core module on purpose — `measureInWindow` is duck-typed off
+   * the stored ref rather than imported from `react-native` (see the
+   * `projectBbox` doc comment for why this file must not import RN).
+   */
+  async refreshMeasurements(options) {
+    const timeoutMs = typeof options?.timeoutMs === "number" && Number.isFinite(options.timeoutMs) && options.timeoutMs > 0 ? options.timeoutMs : 250;
+    const counts = { measured: 0, cleared: 0, skipped: 0 };
+    const pending = [];
+    for (const element of this.getMountedVisibleElements()) {
+      const node = element.ref?.current;
+      if (!node || typeof node.measureInWindow !== "function") {
+        counts.skipped++;
+        continue;
+      }
+      const id = element.id;
+      pending.push(
+        new Promise((resolve) => {
+          let settled = false;
+          try {
+            node.measureInWindow((pageX, pageY, w, h) => {
+              if (settled) return;
+              settled = true;
+              try {
+                if (w > 0 && h > 0) {
+                  this.updateElementState(id, {
+                    mounted: true,
+                    visible: true,
+                    enabled: true,
+                    focused: false,
+                    layout: { x: pageX, y: pageY, width: w, height: h, pageX, pageY }
+                  });
+                  counts.measured++;
+                } else if (this.elements.get(id)?.getState().layout != null) {
+                  this.updateElementState(id, { visible: false, layout: null });
+                  counts.cleared++;
+                } else {
+                  counts.skipped++;
+                }
+              } finally {
+                resolve();
+              }
+            });
+          } catch {
+            if (!settled) {
+              settled = true;
+              counts.skipped++;
+              resolve();
+            }
+          }
+        })
+      );
+    }
+    if (pending.length > 0) {
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, timeoutMs);
+        void Promise.all(pending).then(() => {
+          clearTimeout(timer);
+          resolve();
+        });
+      });
+    }
+    return counts;
+  }
   /**
    * Update element state
    */
@@ -698,12 +1446,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
@@ -715,6 +1459,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
    */
@@ -828,41 +1621,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 (error) {
           if (this.config.verbose) {
             console.warn(`[ui-bridge-native] routeProvider getCurrentRoute threw:`, error);
           }
-          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,
@@ -882,10 +1693,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
         };
@@ -905,6 +1717,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) {
@@ -1102,6 +1921,6 @@ function matchesIdentifier(identifier, criteria) {
   return true;
 }
 
-export { NativeUIBridgeRegistry, buildTreePath, createNativeElementIdentifier, extractHandlerNames, findAllByPattern, findElementByIdentifier, getGlobalRegistry, matchesCurrentRoute, matchesIdentifier, parseTreePath, projectBbox, resetGlobalRegistry, setGlobalRegistry };
+export { DEFAULT_PARAM_VALIDATION_MODE, MAX_ACTION_TIMEOUT_MS, NATIVE_STANDARD_ACTION_EFFECTS, NativeUIBridgeRegistry, buildTreePath, computeVisibility, createNativeElementIdentifier, deriveActiveTabFromSegments, extractHandlerNames, findAllByPattern, findElementByIdentifier, formatParamValidationFailure, getDefaultParamValidationMode, getGlobalRegistry, inertAbortSignal, intersectRects, isEmptyRect, matchesCurrentRoute, matchesIdentifier, nativeStandardActionEffect, normalizeActionTimeoutMs, pageRectOf, parseTreePath, projectBbox, resetDefaultParamValidationMode, resetGlobalRegistry, resolveActionEffect, runAbortable, serializeElementCustomActions, setDefaultParamValidationMode, setGlobalRegistry, validateActionParams };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map