@qontinui/ui-bridge-native 0.6.15 → 0.7.0

package/dist/react/index.js

@@ -313,6 +313,13 @@ function computeVisibility(state, clip) {
   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 copyRouteInfo(info) {
+  const copy = { ...info };
+  if (info.params) copy.params = { ...info.params };
+  if (info.queryParams) copy.queryParams = { ...info.queryParams };
+  if (info.routeStack) copy.routeStack = [...info.routeStack];
+  return copy;
+}
 function inferActions(type, scrollAncestorId) {
   const baseActions = scrollAncestorId ? ["focus", "blur", "scrollIntoView"] : ["focus", "blur"];
   switch (type) {
@@ -377,6 +384,16 @@ var NativeUIBridgeRegistry = class {
      * already installs.
      */
     this.routeProvider = null;
+    /**
+     * The route TEMPLATE the app last reported through `useRouteAwareness`
+     * (via {@link setRouteInfo}), emitted on every snapshot as `page.route`.
+     *
+     * Deliberately NOT named `routeInfo`: `createSnapshot`'s parameter of that
+     * name is the CONCRETE `{currentRoute, segments, activeTab}` read from the
+     * route provider. The two must never be confused — the concrete path is
+     * user input, and this slot is the router-asserted template.
+     */
+    this.reportedRoute = void 0;
     /**
      * Device pixel ratio used to project `state.layout` (logical dp) into the
      * physical-pixel `bbox` emitted on each snapshot element. Defaults to `1`
@@ -435,6 +452,22 @@ var NativeUIBridgeRegistry = class {
   getRouteProvider() {
     return this.routeProvider;
   }
+  /**
+   * Set the route info emitted as `page.route` on every snapshot — the
+   * router-asserted TEMPLATE, normally reported by `useRouteAwareness`.
+   * Pass `undefined` to clear it (the hook does so on unmount), after which
+   * snapshots omit `page` again.
+   *
+   * The value is copied, so a later mutation by the caller cannot alter what
+   * is stored or what an already-emitted snapshot holds.
+   */
+  setRouteInfo(info) {
+    this.reportedRoute = info ? copyRouteInfo(info) : void 0;
+  }
+  /** Read-only accessor for the reported route info, if any (a copy). */
+  getRouteInfo() {
+    return this.reportedRoute ? copyRouteInfo(this.reportedRoute) : void 0;
+  }
   /**
    * Resolve the snapshot's `activeTab`: an explicit `getActiveTab()` on the
    * route provider wins, otherwise derive it from the Expo Router segments the
@@ -1275,6 +1308,12 @@ var NativeUIBridgeRegistry = class {
       // hosts that wire no route provider.
       ...resolvedRoute.currentRoute ? { route: resolvedRoute.currentRoute } : {},
       ...resolvedRoute.activeTab ? { activeTab: resolvedRoute.activeTab } : {},
+      // The router-asserted route TEMPLATE, spelled as the web SDK's
+      // `snapshot.page.route`. Emitted on the ONE assembly point both route
+      // branches above share (the explicit-`routeInfo` branch the server's
+      // `getSnapshot` override uses, and the provider fallback). Omitted, not
+      // nulled, when unset — the same convention as the aliases above.
+      ...this.reportedRoute ? { page: { route: copyRouteInfo(this.reportedRoute) } } : {},
       registration: this.getRegistrationCoverage()
     };
     if (this.appInfo) {
@@ -1321,6 +1360,9 @@ var NativeUIBridgeRegistry = class {
           }
         }
       }
+      if (this.reportedRoute) {
+        snapshot.page = { route: copyRouteInfo(this.reportedRoute) };
+      }
     }
     return snapshot;
   }
@@ -2339,7 +2381,7 @@ var DefaultNativeActionExecutor = class {
     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(
+    const measured2 = await new Promise(
       (resolve, reject) => {
         let settled = false;
         const timer = setTimeout(() => {
@@ -2376,13 +2418,13 @@ var DefaultNativeActionExecutor = class {
         }
       }
     );
-    if (ancestorRect && Number.isFinite(measured.x) && Number.isFinite(measured.width) && measured.x + measured.width > ancestorRect.right - ancestorRect.left + 1) {
+    if (ancestorRect && Number.isFinite(measured2.x) && Number.isFinite(measured2.width) && measured2.x + measured2.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 });
+    container.scrollTo({ y: Math.max(0, measured2.y - padding), animated: false });
     return { alreadyVisible: false, scrolled: true };
   }
   /**
@@ -3119,7 +3161,219 @@ function createDesignHandlers(registry, viewportProvider) {
   };
 }
 
+// src/observation/observation.ts
+var UNKNOWN_CODES = [
+  "app_unreachable",
+  "capability_unavailable_in_build",
+  "producer_failed",
+  "producer_not_run",
+  "input_missing",
+  "below_confidence_floor",
+  "model_reply_unparseable",
+  "needs_multi_frame_input",
+  "stale_input"
+];
+function isUnknownCode(value) {
+  return typeof value === "string" && UNKNOWN_CODES.includes(value);
+}
+var ObservationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ObservationError";
+  }
+};
+function toRfc3339(t) {
+  const d = t instanceof Date ? t : new Date(t);
+  if (Number.isNaN(d.getTime())) {
+    throw new ObservationError(`not a valid timestamp: ${String(t)}`);
+  }
+  return d.toISOString();
+}
+function normalizeConfidence(c) {
+  if (c === null || c === void 0 || !Number.isFinite(c)) return null;
+  return Math.min(1, Math.max(0, c));
+}
+function fullCoverage(n) {
+  return { considered: n, measured: n, unmeasured: [] };
+}
+function assertCount(value, what) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new ObservationError(`${what} must be a non-negative integer, got ${String(value)}`);
+  }
+}
+function assertCoverage(coverage) {
+  if (!coverage || typeof coverage !== "object") {
+    throw new ObservationError("coverage must be an object");
+  }
+  assertCount(coverage.considered, "coverage.considered");
+  assertCount(coverage.measured, "coverage.measured");
+  if (!Array.isArray(coverage.unmeasured)) {
+    throw new ObservationError("coverage.unmeasured must be an array");
+  }
+  coverage.unmeasured.forEach((u, i) => {
+    if (!u || typeof u.dimension !== "string") {
+      throw new ObservationError(`coverage.unmeasured[${i}].dimension must be a string`);
+    }
+    assertCount(u.count, `coverage.unmeasured[${i}].count`);
+    if (!isUnknownCode(u.code)) {
+      throw new ObservationError(
+        `coverage.unmeasured[${i}].code is not an UnknownCode: ${String(u.code)}`
+      );
+    }
+  });
+}
+function assertSource(source) {
+  if (source === null) return;
+  if (typeof source !== "object" || Array.isArray(source)) {
+    throw new ObservationError("source must be a JSON object or null");
+  }
+}
+var RFC3339 = /^(\d{4})-(\d{2})-(\d{2})[Tt ](\d{2}):(\d{2}):(\d{2})(\.\d+)?([Zz]|[+-](\d{2}):(\d{2}))$/;
+function isRfc3339(value) {
+  if (typeof value !== "string") return false;
+  const m = RFC3339.exec(value);
+  if (!m) return false;
+  const [y, mo, d, h, mi, s] = [m[1], m[2], m[3], m[4], m[5], m[6]].map(Number);
+  if (mo < 1 || mo > 12 || d < 1 || h > 23 || mi > 59 || s > 60) return false;
+  const leap = y % 4 === 0 && y % 100 !== 0 || y % 400 === 0;
+  const daysInMonth = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][mo - 1];
+  if (d > daysInMonth) return false;
+  if (m[9] !== void 0 && (Number(m[9]) > 23 || Number(m[10]) > 59)) return false;
+  return true;
+}
+function assertProvenance(prov) {
+  if (!prov || typeof prov !== "object") throw new ObservationError("provenance is required");
+  if (!prov.producer || typeof prov.producer.id !== "string" || typeof prov.producer.version !== "string") {
+    throw new ObservationError("producer must carry a string id and version");
+  }
+  if (!isRfc3339(prov.evaluatedAt)) {
+    throw new ObservationError(
+      `evaluatedAt must be an RFC3339 date-time, got ${String(prov.evaluatedAt)}`
+    );
+  }
+  if (prov.observedAt !== null && !isRfc3339(prov.observedAt)) {
+    throw new ObservationError(
+      `observedAt must be an RFC3339 date-time or null, got ${String(prov.observedAt)}`
+    );
+  }
+  assertCoverage(prov.coverage);
+  if (prov.confidence !== null && (typeof prov.confidence !== "number" || !Number.isFinite(prov.confidence) || prov.confidence < 0 || prov.confidence > 1)) {
+    throw new ObservationError(
+      `confidence must be in [0, 1] or null, got ${String(prov.confidence)}`
+    );
+  }
+  if (prov.cache !== null) {
+    if (typeof prov.cache !== "object" || typeof prov.cache.hit !== "boolean" || !Array.isArray(prov.cache.keyInputs) || !prov.cache.keyInputs.every((k) => typeof k === "string")) {
+      throw new ObservationError(
+        "cache must be { hit: boolean, storedAt, keyInputs: string[] } or null"
+      );
+    }
+    if (prov.cache.storedAt !== null && !isRfc3339(prov.cache.storedAt)) {
+      throw new ObservationError(
+        `cache.storedAt must be an RFC3339 date-time or null, got ${String(prov.cache.storedAt)}`
+      );
+    }
+  }
+  assertSource(prov.source);
+}
+function provenance(init) {
+  if (!init.producer || typeof init.producer.id !== "string" || typeof init.producer.version !== "string") {
+    throw new ObservationError("producer must carry a string id and version");
+  }
+  const coverage = init.coverage ?? fullCoverage(0);
+  assertCoverage(coverage);
+  const source = init.source ?? null;
+  assertSource(source);
+  const built = {
+    producer: { id: init.producer.id, version: init.producer.version },
+    observedAt: init.observedAt === void 0 || init.observedAt === null ? null : toRfc3339(init.observedAt),
+    evaluatedAt: toRfc3339(init.evaluatedAt ?? /* @__PURE__ */ new Date()),
+    coverage: {
+      considered: coverage.considered,
+      measured: coverage.measured,
+      unmeasured: coverage.unmeasured.map((u) => ({
+        dimension: u.dimension,
+        count: u.count,
+        code: u.code
+      }))
+    },
+    confidence: normalizeConfidence(init.confidence),
+    cache: init.cache ? {
+      hit: init.cache.hit,
+      storedAt: init.cache.storedAt === null ? null : toRfc3339(init.cache.storedAt),
+      keyInputs: [...init.cache.keyInputs]
+    } : null,
+    source
+  };
+  assertProvenance(built);
+  return built;
+}
+function measured(value, prov) {
+  if (value === void 0) {
+    throw new ObservationError(
+      'measured requires a value; report "nothing there" as absent and "could not look" as unknown'
+    );
+  }
+  assertProvenance(prov);
+  return { status: "measured", value, provenance: prov };
+}
+function absent(prov) {
+  assertProvenance(prov);
+  const { considered, measured: measured2, unmeasured } = prov.coverage;
+  if (unmeasured.length > 0) {
+    const dims = unmeasured.map((u) => `${u.dimension} x${u.count} (${u.code})`).join(", ");
+    throw new ObservationError(
+      `cannot assert absent over unmeasured coverage: ${dims}. Report the observation as measured (degraded) or unknown instead.`
+    );
+  }
+  if (considered === 0) {
+    throw new ObservationError(
+      "cannot assert absent over zero considered items: the producer looked at nothing. Report the observation as unknown instead."
+    );
+  }
+  if (measured2 !== considered) {
+    throw new ObservationError(
+      `an \`absent\` observation must have measured every considered item (measured ${measured2} of ${considered}); a partial look is \`measured\` with its gaps in \`coverage.unmeasured\`, never \`absent\``
+    );
+  }
+  return { status: "absent", provenance: prov };
+}
+function unknown(code, detail, prov) {
+  if (!isUnknownCode(code)) {
+    throw new ObservationError(`not an UnknownCode: ${String(code)}`);
+  }
+  if (typeof detail !== "string") {
+    throw new ObservationError("unknown requires a string detail");
+  }
+  assertProvenance(prov);
+  return { status: "unknown", unknown: { code, detail }, provenance: prov };
+}
+var Observation = {
+  provenance,
+  fullCoverage,
+  measured,
+  absent,
+  unknown
+};
+
 // src/server/page-health.ts
+var NATIVE_PAGE_HEALTH_PRODUCER_ID = "sdk-native/page-health";
+function defaultProducer() {
+  return {
+    id: NATIVE_PAGE_HEALTH_PRODUCER_ID,
+    version: "0.7.0" 
+  };
+}
+function pageHealthUnknown(code, detail, options = {}) {
+  return Observation.unknown(
+    code,
+    detail,
+    Observation.provenance({
+      producer: options.producer ?? defaultProducer(),
+      evaluatedAt: options.evaluatedAt
+    })
+  );
+}
 var GRID_SIZE = 20;
 var NAV_TYPES = /* @__PURE__ */ new Set(["button", "heading", "badge", "status-message"]);
 var SKIP_TEXT_TYPES = /* @__PURE__ */ new Set(["button", "link", "tab", "menuitem"]);
@@ -3188,13 +3442,66 @@ function normalizeRect(state, viewport) {
     height: layout.height / viewport.height
   };
 }
-function diagnosePageHealth(elements, viewport) {
+function diagnosePageHealth(input, options = {}) {
+  const producer = options.producer ?? defaultProducer();
+  try {
+    return observe(input, producer, options.evaluatedAt);
+  } catch (err) {
+    return Observation.unknown(
+      "producer_failed",
+      `page-health producer threw: ${err instanceof Error ? err.message : String(err)}`,
+      Observation.provenance({ producer })
+    );
+  }
+}
+function observe(input, producer, evaluatedAt) {
+  const base = {
+    producer,
+    observedAt: input.observedAt,
+    evaluatedAt
+  };
+  if (!Array.isArray(input.elements)) {
+    return Observation.unknown(
+      "input_missing",
+      "the registry handed over no `elements` array, so there was nothing to analyze; this says nothing about the screen itself",
+      Observation.provenance({ ...base, observedAt: null })
+    );
+  }
+  const elements = input.elements;
+  const viewport = input.viewport;
+  if (!viewport || !(viewport.width > 0) || !(viewport.height > 0)) {
+    return Observation.unknown(
+      "input_missing",
+      viewport ? `the device viewport is degenerate (${viewport.width}x${viewport.height}), so no element can be placed on screen \u2014 pass \`body.viewport\` or wire \`viewportProvider\`` : "the device viewport is unknown, so no element can be placed on screen \u2014 pass `body.viewport` or wire `viewportProvider`",
+      Observation.provenance(base)
+    );
+  }
+  if (elements.length === 0 && (input.registeredComponents ?? 0) === 0) {
+    return Observation.unknown(
+      "producer_not_run",
+      "the registry reports zero elements and zero components \u2014 nothing has registered yet, so there was nothing to look at",
+      Observation.provenance(base)
+    );
+  }
+  return analyze(elements, viewport, base);
+}
+function analyze(elements, viewport, base) {
   const findings = [];
-  const projected = elements.map((el) => ({
-    el,
-    rect: el.state.visible ? normalizeRect(el.state, viewport) : null
-  }));
-  const visible = projected.filter((p) => p.rect !== null);
+  const considered = elements.filter((el) => el.state.visible);
+  const visible = considered.flatMap((el) => {
+    const rect = normalizeRect(el.state, viewport);
+    return rect ? [{ el, rect }] : [];
+  });
+  const withoutGeometry = considered.length - visible.length;
+  const unmeasured = withoutGeometry > 0 ? [{ dimension: "geometry", count: withoutGeometry, code: "input_missing" }] : [];
+  const coverage = { considered: considered.length, measured: visible.length, unmeasured };
+  if (considered.length > 0 && visible.length === 0) {
+    return Observation.unknown(
+      "input_missing",
+      `all ${considered.length} visible element(s) have no measured layout yet, so spatial coverage, layout regions and visual anomalies cannot be measured`,
+      Observation.provenance({ ...base, coverage })
+    );
+  }
   const grid = Array.from(
     { length: GRID_SIZE },
     () => Array.from({ length: GRID_SIZE }, () => false)
@@ -3349,13 +3656,17 @@ function diagnosePageHealth(elements, viewport) {
   const heatmap = grid.map(
     (row) => row.map((cell) => cell ? "#" : ".").join("")
   );
-  return {
-    summary: worstSeverity(findings),
-    findings,
-    heatmap,
-    element_count: elements.length,
-    visible_count: visible.length
-  };
+  return Observation.measured(
+    {
+      summary: worstSeverity(findings),
+      findings,
+      heatmap,
+      element_count: elements.length,
+      visible_count: visible.length
+    },
+    // A deduction over the registry, not an estimate.
+    Observation.provenance({ ...base, coverage })
+  );
 }
 
 // src/server/handlers.ts
@@ -3803,13 +4114,30 @@ function createServerHandlers(registry, executor, config) {
     },
     getPageHealth: async (ctx) => {
       const bodyViewport = ctx.body?.viewport;
-      const viewport = bodyViewport ?? config?.viewportProvider?.() ?? { width: 0, height: 0 };
-      const elements = registry.getAllElements().map((e) => ({
-        type: e.type,
-        state: e.getState()
-      }));
-      const report = diagnosePageHealth(elements, viewport);
-      return success2(report);
+      let viewport;
+      try {
+        viewport = bodyViewport ?? config?.viewportProvider?.() ?? null;
+      } catch {
+        viewport = null;
+      }
+      const observedAt = Date.now();
+      let elements;
+      let registeredComponents;
+      try {
+        elements = registry.getAllElements().map((e) => ({
+          type: e.type,
+          state: e.getState()
+        }));
+        registeredComponents = registry.getAllComponents().length;
+      } catch (err) {
+        return success2(
+          pageHealthUnknown(
+            "producer_failed",
+            `could not read the registry: ${err instanceof Error ? err.message : String(err)}`
+          )
+        );
+      }
+      return success2(diagnosePageHealth({ elements, registeredComponents, viewport, observedAt }));
     },
     // Workflows
     getWorkflows: async () => {
@@ -4313,7 +4641,7 @@ function createServerHandlers(registry, executor, config) {
       };
       if (config?.appInfo) {
         response.uiBridge = {
-          version: "0.6.15",
+          version: "0.7.0",
           ...config.appInfo,
           capabilities: ["elements", "components", "actions", "design"],
           elementCount: stats.elements,
@@ -7875,11 +8203,84 @@ function State(props) {
 function TransitionTo(props) {
   return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: props.children });
 }
+function effectiveInfo(info, unmatched) {
+  return unmatched ? { ...info, pattern: null, params: void 0 } : info;
+}
+function useRouteAwareness(info, options = {}) {
+  const bridge = useUIBridgeNativeOptional();
+  const unmatched = options.unmatched === true;
+  const infoRef = react.useRef(info);
+  infoRef.current = info;
+  const pattern = info.pattern;
+  const patternSource = info.patternSource;
+  const paramsKey = info.params ? JSON.stringify(info.params) : "";
+  const queryParamsKey = info.queryParams ? JSON.stringify(info.queryParams) : "";
+  const routeStackKey = info.routeStack?.join(",");
+  react.useEffect(() => {
+    if (!bridge) return;
+    const registry = bridge.registry;
+    registry.setRouteInfo(effectiveInfo(infoRef.current, unmatched));
+    return () => {
+      registry.setRouteInfo(void 0);
+    };
+  }, [bridge, unmatched, pattern, patternSource, paramsKey, queryParamsKey, routeStackKey]);
+}
+
+// src/react/routePattern.ts
+function focusedIndex(state, routeCount) {
+  if (state.index !== void 0) return state.index;
+  return typeof state.type === "string" && state.type !== "stack" ? 0 : routeCount - 1;
+}
+function isRouteIdentifier(value) {
+  return typeof value === "string" && value.length > 0 && !value.includes("/") && !value.includes("?") && !value.includes("#");
+}
+function isExpoRouterUnmatched(segments) {
+  return segments.some((s) => typeof s === "string" && s.startsWith("+"));
+}
+function expoRouterPattern(segments) {
+  if (!Array.isArray(segments)) return null;
+  for (const segment of segments) {
+    if (!isRouteIdentifier(segment)) return null;
+    if (segment.startsWith("+")) return null;
+  }
+  return "/" + segments.join("/");
+}
+function expoRouterRouteStack(segments) {
+  if (expoRouterPattern(segments) === null) return void 0;
+  const stack = ["/"];
+  for (let depth = 1; depth <= segments.length; depth++) {
+    stack.push("/" + segments.slice(0, depth).join("/"));
+  }
+  return stack;
+}
+function reactNavigationPattern(state, options = {}) {
+  const names = [];
+  let level = state ?? void 0;
+  while (level) {
+    const routes = level.routes;
+    if (!Array.isArray(routes) || routes.length === 0) return null;
+    const index = focusedIndex(level, routes.length);
+    if (!Number.isInteger(index) || index < 0 || index >= routes.length) return null;
+    const route = routes[index];
+    if (!route || !isRouteIdentifier(route.name)) return null;
+    names.push(route.name);
+    level = route.state;
+  }
+  if (names.length === 0) return null;
+  const leaf = names[names.length - 1];
+  if (options.notFoundRouteNames?.includes(leaf)) return null;
+  return "/" + names.join("/");
+}
 
 exports.State = State;
 exports.TransitionTo = TransitionTo;
 exports.UIBridgeNativeProvider = UIBridgeNativeProvider;
+exports.expoRouterPattern = expoRouterPattern;
+exports.expoRouterRouteStack = expoRouterRouteStack;
+exports.isExpoRouterUnmatched = isExpoRouterUnmatched;
+exports.reactNavigationPattern = reactNavigationPattern;
 exports.useAutoRegister = useAutoRegister;
+exports.useRouteAwareness = useRouteAwareness;
 exports.useToastRecorder = useToastRecorder;
 exports.useUIBridge = useUIBridge;
 exports.useUIBridgeModal = useUIBridgeModal;