@qontinui/ui-bridge-native 0.6.12 → 0.6.14

package/dist/core/param-schema.d.ts

@@ -0,0 +1,282 @@
+/**
+ * Parameter-schema validation for component actions.
+ *
+ * Plan `2026-08-20-ui-bridge-action-declaration-shape`, Phase 2.
+ *
+ * `ComponentAction.paramSchema` is **published to agents** — it is spread onto
+ * `/control/components` and `/control/component/:id` by
+ * `server/handlers.ts` `annotateComponentWithInvocationPaths`, and four live
+ * runner consumers read it off the wire. Until Phase 2 nothing enforced it, so
+ * an agent that read the schema and sent conforming params had no guarantee
+ * the handler agreed. That is worse than publishing nothing: it invites trust
+ * it cannot honour. This module is what makes the declaration enforceable.
+ *
+ * ---------------------------------------------------------------------------
+ * THE SUPPORTED SUBSET — this is a CROSS-REPO CONTRACT
+ * ---------------------------------------------------------------------------
+ *
+ * `qontinui-runner` reads these same schemas
+ * (`workflow_generation/wrapper_manifest.rs`, `commands/command_interpreter.rs`,
+ * `bin/wrappers_mcp.rs`), and `command_interpreter.rs` feeds one to an LLM and
+ * asks it to produce conforming args. So the grammar below is not a private
+ * implementation detail — changing it changes what those consumers may emit.
+ *
+ * **No dependency.** `@qontinui/ui-bridge` ships to browsers and has exactly
+ * one runtime dependency (`dom-accessibility-api`). A full JSON Schema
+ * validator (`ajv` and friends) would be the SDK's first heavyweight runtime
+ * dep, which the plan rejected on bundle size. Hence a hand-implemented subset,
+ * documented here rather than inferred from the code.
+ *
+ * **Two accepted top-level shapes**, because `useUIComponent`'s own author-
+ * facing doc has always sanctioned both:
+ *
+ * 1. **Object-schema form** — the shape `paramSchemaOf()`
+ *    (`@qontinui/ui-bridge-wrapper`) emits:
+ *
+ *    ```jsonc
+ *    { "type": "object",
+ *      "properties": { "username": { "type": "string" },
+ *                      "remember": { "type": "boolean" } },
+ *      "required": ["username"],
+ *      "additionalProperties": false }
+ *    ```
+ *
+ * 2. **Map form** — the lightweight shorthand the doc describes as
+ *    "a map of `{ paramName: "string" | "number" | ... }`":
+ *
+ *    ```jsonc
+ *    { "username": "string", "count": { "type": "integer", "minimum": 1 } }
+ *    ```
+ *
+ * **Disambiguation rule** (deterministic, no heuristics). The schema is read as
+ * form 1 **iff** either:
+ *
+ * - it carries a `properties` object; or
+ * - `type === "object"` **and every other top-level key is a JSON Schema
+ *   object-applicable keyword** ({@link OBJECT_SCHEMA_KEYWORDS}).
+ *
+ * Everything else is form 2. So `{ "type": "string" }` is a map declaring one
+ * param named `type` of type `string`, not a top-level string schema — a
+ * params bag is always an object, so a non-object top-level `type` cannot be
+ * describing the bag.
+ *
+ * ⚠️ **The second clause is load-bearing, and a naive `type === "object"` test
+ * is a silent-validation-loss bug.** Consider the map form
+ * `{ "type": "object", "id": "string" }` — an action taking a param literally
+ * named `type` whose hint is `"object"`, plus an `id`. Reading that as form 1
+ * would find no `properties`, express no constraint, and **silently drop every
+ * sibling declaration in the map**: `validateActionParams(schema, { id: 12345 })`
+ * would answer `{ valid: true }` for a schema that plainly says `id` is a
+ * string. `id` is not an object keyword, so the keyword test sends it to form 2
+ * and both params validate. A param named `type` is not exotic — it is one of
+ * the most common names there is.
+ *
+ * The one genuinely ambiguous input is a bare `{ "type": "object" }`: it is
+ * both an empty object schema and a one-entry map declaring a param named
+ * `type` of type `object`. It is read as form 1 (the empty object schema),
+ * which constrains nothing either way, so the choice is unobservable except in
+ * combination with `additionalProperties: false` — where form 1 is clearly the
+ * intended reading.
+ *
+ * ### Map form is a TYPE hint, never a REQUIREDNESS hint
+ *
+ * A bare string value in map form is read as a type name **only when it is one
+ * of the seven JSON Schema primitive names** — `string`, `number`, `integer`,
+ * `boolean`, `object`, `array`, `null` — which is exactly `paramSchemaOf`'s
+ * own `PRIMITIVE_TYPES` set. **Any other string is prose and constrains
+ * nothing.**
+ *
+ * That is not defensive coding, it is the corpus: a census of every literal
+ * `paramSchema` in the fleet (2026-08-22) found ~50 map-form declarations in
+ * `qontinui-runner` alone whose values are human-readable hints, not types —
+ * `{ count: "number (>= 1, defaults to 1)", account: "string — either a Claude
+ * account label … or the literal \"best\"" }`. Reading `"number (>= 1,
+ * defaults to 1)"` as a type name would make every one of them unvalidatable
+ * noise. The file that declares them says so itself: *"loose `Record<string,
+ * unknown>` with hint strings, no runtime validation"*.
+ *
+ * For the same reason, **map form never marks anything required.** It has no
+ * `required` array and no other way to express optionality, and most of those
+ * ~50 real declarations describe params that are explicitly optional in their
+ * own prose ("defaults to 1", "optional initial prompt"). Requiring by default
+ * would report a violation on nearly every real call. An author who needs
+ * required params writes form 1, which has a keyword for it.
+ *
+ * **Optionality in form 1** is exactly `required`: a property is required iff
+ * listed there. Note `paramSchemaOf` **omits `required` entirely** when every
+ * field is optional, so its absence means "nothing required", never "malformed".
+ *
+ * `optional: true` is not a JSON Schema keyword — it is this monorepo's
+ * convention on `paramSchemaOf`'s *input* descriptors, and `paramSchemaOf`
+ * strips it before the schema reaches the wire. It is honoured here (form 2
+ * only) purely so an unstripped input-shaped object is read the same way.
+ *
+ * **Recognised property keywords** — everything else is IGNORED:
+ *
+ * | Keyword | Applies to | Meaning |
+ * |---|---|---|
+ * | `type` | any | `"string" \| "number" \| "integer" \| "boolean" \| "object" \| "array" \| "null"`, or an array of those (union — a value matching any member passes). Any OTHER type name constrains nothing (`paramSchemaOf` passes unknown names through verbatim, so they do occur) |
+ * | `enum` | any | value must equal one of the listed JSON values |
+ * | `const` | any | value must equal this JSON value |
+ * | `properties` | objects | per-key sub-schemas, applied recursively |
+ * | `required` | objects | array of key names that must be present |
+ * | `additionalProperties` | objects | when exactly `false`, keys absent from `properties` are rejected — **including when the schema declares no `properties` at all**, which is the natural spelling of "takes no params". Any other value is ignored |
+ * | `items` | arrays | one sub-schema applied to every element, recursively |
+ * | `minimum` / `maximum` | numbers | inclusive bounds |
+ * | `minLength` / `maxLength` | strings | inclusive bounds on `.length` |
+ * | `pattern` | strings | ECMAScript regex, unanchored. An uncompilable **or catastrophically-backtracking** pattern is ignored, never a failure — see {@link MAX_PATTERN_LENGTH} |
+ *
+ * **⚠ Anything outside this table is IGNORED, never rejected.** `description`,
+ * `default`, `title`, `format`, `examples`, `$schema`, `$ref`, `oneOf`,
+ * `anyOf`, `allOf`, `not`, `patternProperties`, `minItems`, `exclusiveMinimum`
+ * … all pass silently. This is deliberate and load-bearing: a schema outside
+ * this subset is still *valid JSON Schema*, and rejecting an unrecognised
+ * keyword would convert a documentation nicety into a hard invocation failure
+ * for every author who wrote a richer schema than this validator reads. An
+ * unreadable schema means "no constraint expressed here", not "invalid".
+ * The same rule applies one level up: a `paramSchema` that is not a plain
+ * object at all (`null`, an array, a string) expresses no constraint and
+ * validates everything.
+ *
+ * **No coercion.** `"5"` does not satisfy `{"type":"number"}`. The runner's
+ * LLM router is already instructed to "coerce numeric tokens to numbers"
+ * (`command_interpreter.rs`), so coercing here would hide that contract rather
+ * than enforce it.
+ *
+ * ### A validator must return a verdict, never throw
+ *
+ * {@link validateActionParams} is called at an invocation seam whose only
+ * generic failure label is `UB-ACTION-FAILED` — "the handler failed". A
+ * validator that throws would therefore be reported as a *handler* fault, and
+ * the author would go debug code that never ran. Two inputs could do it, and
+ * both are **author-supplied schema data**, not caller params:
+ *
+ * - **A self-referential schema.** `const s = { type: 'object', properties: {} };
+ *   s.properties.self = s;` recurses until `RangeError: Maximum call stack size
+ *   exceeded`. Bounded by {@link MAX_SCHEMA_DEPTH}: past that depth the walk
+ *   stops and expresses no further constraint (the ignore-don't-reject rule,
+ *   applied to depth).
+ * - **A catastrophically-backtracking `pattern`.** This one does not throw at
+ *   all — it *hangs*, which no `try`/`catch` can rescue. Guarded before
+ *   compilation by {@link MAX_PATTERN_LENGTH} and a nested-quantifier test,
+ *   the same pair `control/action-executor.ts` already applies to a
+ *   caller-supplied `srcPattern`.
+ *
+ * The seams wrap the call anyway (belt and braces) and report a validator
+ * fault distinguishably from a handler fault — see the executors.
+ *
+ * ---------------------------------------------------------------------------
+ * DUPLICATE — deliberately not an import
+ * ---------------------------------------------------------------------------
+ *
+ * DUPLICATE OF `@qontinui/ui-bridge` `src/core/param-schema.ts` — DELIBERATELY
+ * NOT AN IMPORT, for the same reason as `core/abortable.ts` beside it:
+ * `@qontinui/ui-bridge` is an OPTIONAL peerDependency of this package and is
+ * absent from `dependencies`, so a consumer may install
+ * `@qontinui/ui-bridge-native` alone; importing from it would resolve inside
+ * this monorepo and then fail for that consumer.
+ *
+ * KEEP IN SYNC with `@qontinui/ui-bridge` `src/core/param-schema.ts`. The
+ * module has no imports and touches no DOM or Node API — only `RegExp`,
+ * `JSON`, `Set` and `Number`, all present in React Native. The documented
+ * subset above is a cross-repo contract, so the two copies drifting is a
+ * contract break, not a style nit.
+ */
+/** Which rule rejected a value. Machine-readable; pairs with `message`. */
+export type ParamSchemaKeyword = 'required' | 'type' | 'enum' | 'const' | 'additionalProperties' | 'minimum' | 'maximum' | 'minLength' | 'maxLength' | 'pattern';
+/**
+ * One rejected parameter. `path` is the whole point — an agent told only
+ * "invalid params" cannot fix anything, so every issue names the param it is
+ * about.
+ */
+export interface ParamSchemaIssue {
+    /**
+     * Location of the offending value, in dotted/bracketed form relative to the
+     * params object: `"username"`, `"filter.status"`, `"ids[2]"`. Empty string
+     * means the params object itself.
+     */
+    path: string;
+    /** Which rule rejected it. */
+    keyword: ParamSchemaKeyword;
+    /** What the schema demanded, rendered for a human/agent reader. */
+    expected: string;
+    /** What was actually supplied, rendered compactly. Absent for `required`. */
+    received?: string;
+    /** One-line explanation naming both the param and the reason. */
+    message: string;
+}
+/** Outcome of {@link validateActionParams}. */
+export interface ParamValidationResult {
+    valid: boolean;
+    /** Empty iff `valid`. */
+    issues: ParamSchemaIssue[];
+}
+/**
+ * What the executor does with a schema violation.
+ *
+ * - `'enforce'` — reject the invocation before the handler runs, with
+ *   `errorCode: 'UB-ACTION-REJECTED'` and the issue list attached.
+ * - `'warn'` — log the violation and invoke the handler anyway.
+ * - `'off'` — skip validation entirely (no schema walk, no allocation).
+ */
+export type ParamValidationMode = 'enforce' | 'warn' | 'off';
+/**
+ * **`'warn'`.** Decided on the plan's priority order — *powerful features →
+ * scalability → robustness → clean code* — not on backward compatibility,
+ * which is explicitly not a factor on this project.
+ *
+ * The feature Phase 2 delivers is *an enforceable declaration*, and warn mode
+ * delivers all of it except the refusal: the schema is walked, the violating
+ * param is named, and the violation is reported. Enforcement is one call to
+ * {@link setDefaultParamValidationMode} away, per deployment.
+ *
+ * What arming `'enforce'` by default would buy is the refusal — and the
+ * population it would refuse first is not attackers, it is the fleet's own
+ * schemas. Nothing has ever validated these declarations, so on the balance of
+ * evidence some existing `paramSchema` values are wrong about their own
+ * handlers rather than the callers being wrong about the schema; a validator
+ * armed on day one reports that as the caller's failure. Worse, the largest
+ * live producer of action params is a *model*:
+ * `qontinui-runner/src-tauri/src/commands/command_interpreter.rs` asks an LLM
+ * for "args whose keys match the chosen action's `paramSchema`", and that
+ * failure surfaces to a user running a slash command. Defaulting to enforce
+ * would convert a documentation defect into a user-visible outage on a
+ * population that was never measured.
+ *
+ * Robustness — third in the order, and the tiebreaker here — argues the same
+ * way: the robust move is to collect violations from a validator that has
+ * never seen production traffic before letting it refuse anything. A default
+ * that fails open and is *observable* beats a default that fails closed and is
+ * *unmeasured*.
+ */
+export declare const DEFAULT_PARAM_VALIDATION_MODE: ParamValidationMode;
+/**
+ * Arm or disarm validation process-wide. Call once at app boot; each
+ * invocation may still override it via `executeComponentAction`'s
+ * `{ paramValidation }` option.
+ */
+export declare function setDefaultParamValidationMode(mode: ParamValidationMode): void;
+/** The mode an invocation gets when it does not pass one. */
+export declare function getDefaultParamValidationMode(): ParamValidationMode;
+/** Test/teardown helper: restore {@link DEFAULT_PARAM_VALIDATION_MODE}. */
+export declare function resetDefaultParamValidationMode(): void;
+/**
+ * Validate `params` against an action's `paramSchema`.
+ *
+ * Returns `{ valid: true, issues: [] }` for anything the documented subset
+ * cannot read — that is the ignore-don't-reject rule, and it is why a schema
+ * this validator does not understand can never fail an invocation.
+ *
+ * @param schema the action's declared `paramSchema` (any shape; unreadable
+ *   shapes constrain nothing)
+ * @param params the params the caller supplied. `undefined` is treated as an
+ *   empty object, so a schema with required properties still reports them.
+ */
+export declare function validateActionParams(schema: unknown, params: unknown): ParamValidationResult;
+/**
+ * One-line summary of a violation set, naming the action and every offending
+ * param. Used as the `error` / `message` string at every invocation seam so
+ * the three trees phrase the rejection identically.
+ */
+export declare function formatParamValidationFailure(componentId: string, actionId: string, issues: ParamSchemaIssue[]): string;
+//# sourceMappingURL=param-schema.d.ts.map

package/dist/core/param-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"param-schema.d.ts","sourceRoot":"","sources":["../../src/core/param-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuLG;AAEH,2EAA2E;AAC3E,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,MAAM,GACN,MAAM,GACN,OAAO,GACP,sBAAsB,GACtB,SAAS,GACT,SAAS,GACT,WAAW,GACX,WAAW,GACX,SAAS,CAAC;AAEd;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,+CAA+C;AAC/C,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,OAAO,CAAC;IACf,yBAAyB;IACzB,MAAM,EAAE,gBAAgB,EAAE,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,MAAM,GAAG,KAAK,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,6BAA6B,EAAE,mBAA4B,CAAC;AAIzE;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAE7E;AAED,6DAA6D;AAC7D,wBAAgB,6BAA6B,IAAI,mBAAmB,CAEnE;AAED,2EAA2E;AAC3E,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD;AA6hBD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,OAAO,GACd,qBAAqB,CA0CvB;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,gBAAgB,EAAE,GACzB,MAAM,CAGR"}

package/dist/core/registry.d.ts

@@ -4,7 +4,7 @@
  * Central registry for all UI elements and components registered with UI Bridge Native.
  * Adapted from ui-bridge for React Native environments.
  */
-import type { RegisteredNativeElement, RegisteredNativeComponent, NativeElementState, NativeElementType, NativeStandardAction, NativeCustomAction, NativeAppInfo, NativeBridgeSnapshot, NativeElementBbox, NativeElementRef, NativeRegistrationCoverage, NativeRouteProviderLike, NativeSnapshotEnrichers, NativeSnapshotEnricher, Workflow, BridgeEventType, BridgeEventListener } from './types';
+import type { RegisteredNativeElement, RegisteredNativeComponent, NativeElementState, NativeElementType, NativeStandardAction, NativeCustomAction, NativeAppInfo, NativeBridgeSnapshot, NativeElementBbox, NativeElementRef, NativeRegistrationCoverage, NativeRouteProviderLike, NativeSnapshotEnrichers, NativeSnapshotEnricher, Workflow, BridgeEventType, BridgeEventListener, IREffect } from './types';
 /**
  * Options for registering an element
  */
@@ -19,6 +19,24 @@ export interface RegisterElementOptions {
     accessibilityLabel?: string;
     /** Route path where the element was registered (for page-scoped filtering) */
     registrationRoute?: string | null;
+    /**
+     * Id of the registered scrollable container this element lives inside.
+     *
+     * When set, {@link computeVisibility} clips the element against that
+     * container's measured frame as well as the window, so a row scrolled out of
+     * its `ScrollView` / `FlatList` stops reporting `visibility: 'visible'`.
+     *
+     * DECLARED, not inferred, and that is deliberate. React Native gives the
+     * registry no parent chain — `useUIElement` is a hook, so it never wraps its
+     * element's children and cannot publish itself as their ancestor. Guessing
+     * the ancestor geometrically is worse than not clipping: a full-width scroll
+     * container horizontally contains the tab bar and the header too, and
+     * clipping those against it would report on-screen chrome as off-screen.
+     * A wrong `hidden` is a worse answer than a coarse `visible`.
+     *
+     * Unset (the default) leaves the window as the only clip region.
+     */
+    scrollAncestorId?: string;
     /** Flattened RN style (from StyleSheet.flatten) for design review */
     flatStyle?: Record<string, unknown>;
     /** State-specific style overrides for design review */
@@ -38,10 +56,49 @@ export interface RegisterComponentOptions {
         id: string;
         label?: string;
         description?: string;
-        handler: (params?: unknown) => unknown | Promise<unknown>;
+        /**
+         * Phase 2 (same plan): the action's published parameter schema. It was
+         * ABSENT here and dropped by the object literal in `registerComponent`
+         * below, so the field `ComponentAction` declares could never reach a
+         * registered native component and the native invocation seam had nothing
+         * to validate against. That is the silent-drop trap the plan warns about,
+         * already realised.
+         */
+        paramSchema?: Record<string, unknown>;
+        /**
+         * Phase 4 (same plan): the safety annotation. Absent here, an author's
+         * `effect: 'destructive'` would die at this hop exactly the way
+         * `paramSchema` did before Phase 2 — the literal in `registerComponent`
+         * has a closed field list and nothing type-checks the omission.
+         */
+        effect?: IREffect;
+        /**
+         * Phase 3 (plan 2026-08-20-ui-bridge-action-declaration-shape): the second
+         * argument is the `ActionHandlerOptions` bag carrying the cancellation
+         * signal. A 1-arity handler stays assignable.
+         */
+        handler: (params?: unknown, options?: {
+            signal?: AbortSignal;
+        }) => unknown | Promise<unknown>;
     }>;
     elementIds?: string[];
 }
+/**
+ * Options for {@link NativeUIBridgeRegistry.updateComponentMeta}.
+ *
+ * Every field is optional and `undefined` means "leave the registered value
+ * alone" — the same partial-update semantics {@link RegisterComponentOptions}'s
+ * sister {@link NativeUIBridgeRegistry.updateElementMeta} uses. A consequence
+ * worth stating: a `description` cannot be CLEARED through this door, only
+ * replaced. Pass `actions: []` to publish an empty action list; that is
+ * distinguishable from omitting the field.
+ */
+export interface UpdateComponentMetaOptions {
+    name?: string;
+    description?: string;
+    actions?: RegisterComponentOptions['actions'];
+    elementIds?: string[];
+}
 /**
  * Registry configuration
  */
@@ -78,6 +135,29 @@ export declare function extractHandlerNames(props?: Record<string, unknown>): st
  * at the root, because tab elements had `registrationRoute: null`.
  */
 export declare function matchesCurrentRoute(registrationRoute: string | null | undefined, currentRoute: string): boolean;
+/**
+ * Derive the snapshot's `activeTab` from an Expo Router segment list.
+ *
+ * Expo Router spells a layout group as a parenthesised segment and a dynamic
+ * route as a bracketed one, so `usePathname()`/`useSegments()` on the "runs"
+ * tab of a `(tabs)` layout yield `"/(tabs)/runs"` and `["(tabs)", "runs"]`
+ * (the shape the `RouteProvider` doc comment already documents). The tab a user
+ * is looking at is therefore the segment immediately following the INNERMOST
+ * group.
+ *
+ * Rules, all deliberately conservative — an unknown tab is reported as absent
+ * rather than guessed:
+ *
+ *   - `["(tabs)", "runs"]`        → `"runs"`
+ *   - `["(tabs)", "runs", "[id]"]`→ `"runs"`  (a detail screen is still *on* a tab)
+ *   - `["(tabs)"]`                → `"index"` (the group's own index route)
+ *   - `["(tabs)", "[id]"]`        → `undefined` (dynamic route, not a tab)
+ *   - `["settings"]`              → `undefined` (no group layout ⇒ no tabs)
+ *   - `[]` / `undefined`          → `undefined`
+ *
+ * Exported so the rules are unit-testable without standing up a registry.
+ */
+export declare function deriveActiveTabFromSegments(segments?: string[]): string | undefined;
 /**
  * Project an element's runtime state into a runner-native pixel-space `bbox`.
  *
@@ -105,6 +185,104 @@ export declare function matchesCurrentRoute(registrationRoute: string | null | u
  * (rare; keeps a best-effort box rather than dropping the element).
  */
 export declare function projectBbox(state: NativeElementState, visibility: 'visible' | 'likely-visible' | 'hidden', pixelRatio?: number): NativeElementBbox | undefined;
+/**
+ * A rectangle in window (page) coordinates, logical dp — the same space
+ * `measureInWindow` reports `pageX`/`pageY` in.
+ */
+export interface NativePageRect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/**
+ * Why an element is not plainly visible.
+ *
+ * DUPLICATE of `@qontinui/ui-bridge` `VisibilityReason`
+ * (`src/core/types.ts` — `'hidden' | 'off-screen' | 'occluded' | 'no-layout'`),
+ * for the same reason the action types above are duplicated: `@qontinui/ui-bridge`
+ * is an OPTIONAL peer of this package, so this module must not import from it.
+ * KEEP IN SYNC — one vocabulary across both SDKs is the point; do not coin
+ * native-only spellings.
+ *
+ * `'occluded'` is declared but never produced here: React Native gives the
+ * registry no hit-test equivalent of `document.elementFromPoint`, so this SDK
+ * cannot honestly claim occlusion. It stays in the union so a native reason
+ * string is always a valid web reason string.
+ */
+export type NativeVisibilityReason = 'hidden' | 'off-screen' | 'occluded' | 'no-layout';
+/** The three-value verdict carried on every snapshot element. */
+export type NativeVisibility = 'visible' | 'likely-visible' | 'hidden';
+/**
+ * Convert an element's measured layout into a page-space rect, or `null` when
+ * it has no TRUSTWORTHY page-space origin.
+ *
+ * STRICTER THAN {@link projectBbox} ON PURPOSE. `projectBbox` falls back to the
+ * parent-relative `x`/`y` when `pageX`/`pageY` weren't measured, because a
+ * slightly-wrong box is still a usable box. Clipping cannot take that trade: a
+ * parent-relative origin compared against window coordinates silently mixes two
+ * coordinate spaces and yields a wrong `hidden` verdict — the outcome
+ * `RegisterElementOptions.scrollAncestorId` calls worse than a coarse
+ * `visible`. So a layout flagged `pageOriginUnmeasured` returns `null` here,
+ * and {@link computeVisibility} declines to clip rather than guess.
+ */
+export declare function pageRectOf(state: NativeElementState): NativePageRect | null;
+/**
+ * Is this rect empty — nothing can overlap it?
+ *
+ * {@link intersectRects} returns an INVERTED rect (`right < left`) when the two
+ * inputs are disjoint, which is the honest answer for "the reachable region",
+ * but `spansOverlap`'s `aMin < bMax && aMax > bMin` reads an inverted span as
+ * overlapping. Every consumer of an intersection must ask this first.
+ */
+export declare function isEmptyRect(rect: NativePageRect): boolean;
+/**
+ * Intersect two page rects, or `null` when either is absent (`null` means
+ * UNKNOWN, so it never narrows the other side).
+ *
+ * The result may be EMPTY — check {@link isEmptyRect}. That happens whenever
+ * the two rects are disjoint, e.g. a scroll container that has itself been
+ * scrolled out of the window: nothing inside it can be on screen, and an empty
+ * clip is exactly how that is expressed.
+ */
+export declare function intersectRects(a: NativePageRect | null, b: NativePageRect | null): NativePageRect | null;
+/**
+ * Decide what a snapshot should say about an element being on screen.
+ *
+ * THE DEFECT THIS CLOSES: visibility used to be derived from mount + `measure()`
+ * alone — `state.visible ? (state.layout ? 'visible' : 'likely-visible') : 'hidden'`
+ * — with no comparison against any bounds at all. Every mounted, measured
+ * element reported `visible`, including rows scrolled far past the fold, so a
+ * snapshot claimed things were on screen that were not.
+ *
+ * SCOPE — read this before citing it. This is a PURE PROJECTION: it reads
+ * `state.visible` and never writes it. An off-screen element still carries
+ * `state.visible === true`; only the snapshot's `visibility` /
+ * `visibilityReason` change. That is a deliberate divergence from the web SDK,
+ * which folds off-screen INTO the boolean (`@qontinui/ui-bridge`
+ * `src/core/registry.ts` — `if (!inViewport) return { visible: false, reason:
+ * 'off-screen' }`), and it means any consumer asserting on `state.visible`
+ * alone — `/manual-test`'s "PRESENT IS NOT VISIBLE" gate among them — sees no
+ * change on mobile and stays as vacuous as it was. Closing that needs either a
+ * matching demotion of `state.visible` here or a consumer that reads
+ * `visibility`; both are contract decisions beyond this projection, and
+ * neither is done. The strings are shared with the web SDK; the SHAPE is not.
+ *
+ * `clip` is the region the element must reach to count as on screen — the
+ * window, intersected with the measured frame of a declared
+ * `scrollAncestorId`. **A `null`/absent clip means the bounds are UNKNOWN, and
+ * an unknown never demotes**: with no viewport injected (every non-RN caller,
+ * including this package's own suite) the answer is exactly what it was before.
+ * Absence of evidence is not evidence of off-screen.
+ *
+ * Any overlap at all counts as visible. A half-scrolled row IS on screen, and
+ * a ratio threshold would be a second, unshared policy knob for callers to
+ * disagree about.
+ */
+export declare function computeVisibility(state: NativeElementState, clip?: NativePageRect | null): {
+    visibility: NativeVisibility;
+    visibilityReason?: NativeVisibilityReason;
+};
 /**
  * Native UI Bridge Registry
  *
@@ -150,6 +328,18 @@ export declare class NativeUIBridgeRegistry {
      * the `projectBbox` doc comment for why we don't import `react-native` here.
      */
     private pixelRatio;
+    /**
+     * 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.
+     */
+    private viewportProvider;
     /**
      * Sticky flag: flips `true` the first time any element is registered and
      * stays `true` even after elements are unregistered. Lets agents distinguish
@@ -175,6 +365,16 @@ export declare class NativeUIBridgeRegistry {
     setRouteProvider(provider: NativeRouteProviderLike | null | undefined): void;
     /** Read-only accessor for the registered route provider, if any. */
     getRouteProvider(): NativeRouteProviderLike | null;
+    /**
+     * 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.
+     */
+    private resolveActiveTab;
     /**
      * Set the device pixel ratio used to project per-element `bbox` geometry
      * into physical pixels. The React provider passes `PixelRatio.get()` here
@@ -184,6 +384,34 @@ export declare class NativeUIBridgeRegistry {
     setPixelRatio(ratio: number): void;
     /** Read-only accessor for the device pixel ratio used for bbox projection. */
     getPixelRatio(): number;
+    /**
+     * 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: (() => {
+        width: number;
+        height: number;
+    }) | null | undefined): void;
+    /**
+     * 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(): NativePageRect | null;
+    /**
+     * 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: RegisteredNativeElement, viewport?: NativePageRect | null): NativePageRect | null;
     /**
      * Register/replace canonical enrichers (modal/toast/undo). HMR-safe — calling
      * with a partial set merges into existing slots instead of clobbering them.
@@ -381,6 +609,33 @@ export declare class NativeUIBridgeRegistry {
      * Register a component
      */
     registerComponent(id: string, options: RegisterComponentOptions): RegisteredNativeComponent;
+    /**
+     * 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: string, meta: UpdateComponentMetaOptions): boolean;
     /**
      * Unregister a component
      */
@@ -430,10 +685,25 @@ export declare class NativeUIBridgeRegistry {
      * 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?: {
         currentRoute?: string | null;
         segments?: string[];
+        /**
+         * Explicit active tab for callers that own the answer outright. Omit to
+         * let the registered `routeProvider` / the segment derivation resolve it.
+         */
+        activeTab?: string | null;
     }, options?: {
         visibleOnly?: boolean;
         currentRouteOnly?: boolean;