@qontinui/ui-bridge-native 0.6.16 → 0.7.1

package/dist/server/index.mjs

@@ -1064,7 +1064,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.1" 
+  };
+}
+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"]);
@@ -1094,14 +1306,7 @@ var LOADING_PHRASES = [
   "initializing",
   "fetching"
 ];
-var EMPTY_PHRASES = [
-  "no data",
-  "no results",
-  "nothing here",
-  "empty",
-  "no items",
-  "get started"
-];
+var EMPTY_PHRASES = ["no data", "no results", "nothing here", "empty", "no items", "get started"];
 function severityRank(s) {
   if (s === "CRITICAL") return 3;
   if (s === "WARNING") return 2;
@@ -1133,13 +1338,90 @@ 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 nothingOnScreenDetail(elements, visibleCount, visibilityUnstated) {
+  if (visibilityUnstated === 0 && visibleCount > 0) {
+    return `all ${visibleCount} visible element(s) have no measured layout yet, so spatial coverage, layout regions and visual anomalies cannot be measured`;
+  }
+  if (visibilityUnstated > 0) {
+    const geometry = visibleCount > 0 ? ` and none of the ${visibleCount} visible one(s) has a measured layout` : "";
+    return `${visibilityUnstated} of ${elements.length} element(s) carry no boolean \`state.visible\`${geometry}, so no element can be placed on screen; spatial coverage, layout regions and visual anomalies cannot be measured`;
+  }
+  const unmounted = elements.filter((el) => el.state?.mounted === false).length;
+  return `all ${elements.length} registered element(s) report visible: false (unmounted=${unmounted}, off-screen route or otherwise=${elements.length - unmounted}), so whatever is on screen is not a registered element and there is nothing on screen to measure; this says nothing about whether the screen is blank`;
+}
+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 onScreen = elements.filter((el) => el.state?.visible === true);
+  const visibilityUnstated = elements.filter(
+    (el) => typeof el.state?.visible !== "boolean"
+  ).length;
+  const visible = onScreen.flatMap((el) => {
+    const rect = normalizeRect(el.state, viewport);
+    return rect ? [{ el, rect }] : [];
+  });
+  const withoutGeometry = onScreen.length - visible.length;
+  const unmeasured = [];
+  if (withoutGeometry > 0) {
+    unmeasured.push({ dimension: "geometry", count: withoutGeometry, code: "input_missing" });
+  }
+  if (visibilityUnstated > 0) {
+    unmeasured.push({ dimension: "visibility", count: visibilityUnstated, code: "input_missing" });
+  }
+  const coverage = {
+    considered: onScreen.length + visibilityUnstated,
+    measured: visible.length,
+    unmeasured
+  };
+  if (elements.length > 0 && visible.length === 0) {
+    return Observation.unknown(
+      "input_missing",
+      nothingOnScreenDetail(elements, onScreen.length, visibilityUnstated),
+      Observation.provenance({ ...base, coverage })
+    );
+  }
   const grid = Array.from(
     { length: GRID_SIZE },
     () => Array.from({ length: GRID_SIZE }, () => false)
@@ -1226,7 +1508,7 @@ function diagnosePageHealth(elements, viewport) {
   for (const el of elements) {
     const elType = el.type ?? "";
     if (SKIP_TEXT_TYPES.has(elType)) continue;
-    const text = (el.state.textContent ?? "").toString();
+    const text = (el.state?.textContent ?? "").toString();
     if (!text) continue;
     const textLower = text.toLowerCase();
     for (const p of ERROR_PHRASES) {
@@ -1267,7 +1549,7 @@ function diagnosePageHealth(elements, viewport) {
   for (const el of elements) {
     if (!INTERACTIVE_TYPES2.has(el.type)) continue;
     interactiveTotal++;
-    if (el.state.enabled === false) interactiveDisabled++;
+    if (el.state?.enabled === false) interactiveDisabled++;
   }
   const interactiveSeverity = interactiveTotal > 0 && interactiveDisabled / interactiveTotal > 0.5 ? "WARNING" : "OK";
   findings.push({
@@ -1291,16 +1573,18 @@ function diagnosePageHealth(elements, viewport) {
     detail: `zero_size=${zeroSize}, outside_viewport=${outsideViewport} (horizontal-overflow only; below/above-fold scrollable content is not an anomaly)`,
     data: { zero_size: zeroSize, outside_viewport: outsideViewport }
   });
-  const heatmap = grid.map(
-    (row) => row.map((cell) => cell ? "#" : ".").join("")
+  const heatmap = grid.map((row) => row.map((cell) => cell ? "#" : ".").join(""));
+  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 })
   );
-  return {
-    summary: worstSeverity(findings),
-    findings,
-    heatmap,
-    element_count: elements.length,
-    visible_count: visible.length
-  };
 }
 
 // src/server/handlers.ts
@@ -1748,13 +2032,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 () => {
@@ -2258,7 +2559,7 @@ function createServerHandlers(registry, executor, config) {
       };
       if (config?.appInfo) {
         response.uiBridge = {
-          version: "0.6.16",
+          version: "0.7.1",
           ...config.appInfo,
           capabilities: ["elements", "components", "actions", "design"],
           elementCount: stats.elements,
@@ -4548,6 +4849,6 @@ async function bindWithRetry(attempt, options = {}) {
   }
 }
 
-export { ConsoleErrorBuffer, NativeUIBridgeServer, NetworkRequestBuffer, OPCODE_BINARY, OPCODE_CLOSE, OPCODE_CONTINUATION, OPCODE_PING, OPCODE_PONG, OPCODE_TEXT, UI_BRIDGE_NATIVE_ROUTES, WebSocketConnection, WebSocketEventBridge, bindWithRetry, buildUpgradeResponse, computeAcceptKey, createDesignHandlers, createNativeServer, createServerHandlers, decodeFrames, decodeTextPayload, encodeCloseFrame, encodePingFrame, encodePongFrame, encodeTextFrame, httpStatusForResponse, isAddrInUseError, isBatchRequest, isSubscribe, isUnsubscribe };
+export { ConsoleErrorBuffer, NATIVE_PAGE_HEALTH_PRODUCER_ID, NativeUIBridgeServer, NetworkRequestBuffer, OPCODE_BINARY, OPCODE_CLOSE, OPCODE_CONTINUATION, OPCODE_PING, OPCODE_PONG, OPCODE_TEXT, Observation, ObservationError, UI_BRIDGE_NATIVE_ROUTES, UNKNOWN_CODES, WebSocketConnection, WebSocketEventBridge, bindWithRetry, buildUpgradeResponse, computeAcceptKey, createDesignHandlers, createNativeServer, createServerHandlers, decodeFrames, decodeTextPayload, diagnosePageHealth, encodeCloseFrame, encodePingFrame, encodePongFrame, encodeTextFrame, httpStatusForResponse, isAddrInUseError, isBatchRequest, isSubscribe, isUnknownCode, isUnsubscribe, pageHealthUnknown };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map