@qontinui/ui-bridge-native 0.6.16 → 0.7.0

package/dist/observation/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The Observation envelope, vendored from `@qontinui/ui-bridge`.
+ *
+ * `./observation.ts` is a GENERATED copy of the canonical
+ * `packages/ui-bridge/src/observation/observation.ts` (see
+ * `scripts/sync-observation.mjs`); CI fails if the two drift. This package
+ * imports it by relative path so it takes no runtime dependency on
+ * `@qontinui/ui-bridge` (an optional peer here) and needs no package-`exports`
+ * support from Metro.
+ */
+export { Observation, ObservationError, UNKNOWN_CODES, isUnknownCode, type UnknownCode, type ObservationStatus, type ObservationProducer, type ObservationCoverage, type UnmeasuredDimension, type ObservationCache, type ObservationProvenance, type ObservationProvenanceInit, type ObservationUnknown, type ObservationTime, type MeasuredObservation, type AbsentObservation, type UnknownObservation, } from './observation';
+//# sourceMappingURL=index.d.ts.map

package/dist/observation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACxB,MAAM,eAAe,CAAC"}

package/dist/observation/observation.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Observation envelope — the shape every UI Bridge observation surface answers
+ * in: WHAT was seen (`measured`), that nothing was there (`absent`), or that the
+ * producer could not look (`unknown`) — and, in every case, where the answer
+ * came from (`provenance`).
+ *
+ * Why it exists: an empty findings list used to mean either "the page has
+ * nothing there" or "the producer never looked", byte-identically, and only the
+ * first is a statement about the page. `page-health` rendered a missing
+ * `elements` key as a CRITICAL blank page; an agent reading that went looking
+ * for a bug no evidence pointed at.
+ *
+ * This is the TypeScript twin of the canonical Rust type
+ * `qontinui-schemas/rust-vision-core/src/observation.rs`. `@qontinui/ui-bridge`
+ * is a standalone package and takes no dependency on qontinui-schemas; it is
+ * held to the Rust canon by SDK-captured fixtures the schemas crate parses
+ * strictly (plan 2026-09-20-ui-bridge-observations-…, D2). The two MUST stay
+ * structurally identical on the wire:
+ *
+ * ```jsonc
+ * {
+ *   "status": "measured" | "absent" | "unknown",       // always present
+ *   "value": <T>,                                       // present iff measured
+ *   "unknown": { "code": <UnknownCode>, "detail": "…" }, // present iff unknown
+ *   "provenance": {                                     // always present, EVERY key always present
+ *     "producer": { "id": "…", "version": "…" },
+ *     "observedAt": "<RFC3339>" | null,
+ *     "evaluatedAt": "<RFC3339>",
+ *     "coverage": { "considered": n, "measured": n,
+ *                   "unmeasured": [{ "dimension": "…", "count": n, "code": <UnknownCode> }] },
+ *     "confidence": <0..1> | null,
+ *     "cache": { "hit": bool, "storedAt": "<RFC3339>" | null, "keyInputs": ["…"] } | null,
+ *     "source": { … } | null
+ *   }
+ * }
+ * ```
+ *
+ * `null` in `provenance` is a STATEMENT, never an omission: `confidence: null`
+ * says "a deduction, not an estimate", `cache: null` says "this producer has no
+ * cache", `observedAt: null` says "no sample was taken". A key is therefore
+ * never left out, and the constructors below are the only way to build one.
+ *
+ * The envelope adds no score and no verdict — `healthy`/`unhealthy` never
+ * appears in it.
+ */
+/**
+ * Why a producer could not answer. A CLOSED set: every `unknown` observation
+ * carries exactly one of these, so an agent branches on the code rather than
+ * parsing English out of `detail`.
+ */
+export type UnknownCode = 
+/** The bridge/app could not be reached. */
+'app_unreachable'
+/** The running build does not serve this capability (e.g. an SDK route that needs a runner). */
+ | 'capability_unavailable_in_build'
+/** The producer ran and errored (transport, HTTP status, timeout, thrown exception). */
+ | 'producer_failed'
+/** The producer did not run — e.g. zero registered components, nothing to look at yet. */
+ | 'producer_not_run'
+/** A required input was absent (no `elements` key, no bbox, no frame). */
+ | 'input_missing'
+/** Observations existed but all fell under the caller's confidence floor. */
+ | 'below_confidence_floor'
+/** A model reply could not be parsed/validated. */
+ | 'model_reply_unparseable'
+/** The question needs more than one frame (e.g. `animation_settled`). */
+ | 'needs_multi_frame_input'
+/** The input is known to be stale. */
+ | 'stale_input';
+/** Every {@link UnknownCode}, in the canonical (wire-contract) order. */
+export declare const UNKNOWN_CODES: readonly UnknownCode[];
+/** Type guard: is `value` one of the closed {@link UnknownCode} members? */
+export declare function isUnknownCode(value: unknown): value is UnknownCode;
+/** Which producer answered, and at what version. */
+export interface ObservationProducer {
+    /** e.g. `sdk/page-health`, `runner/vision-extract`, `vision-core/layout`. */
+    id: string;
+    /** The producing package's or crate's version. */
+    version: string;
+}
+/** One dimension the producer could NOT measure, how many items it affected, and why. */
+export interface UnmeasuredDimension {
+    /** What went unmeasured, e.g. `geometry`, `text`. */
+    dimension: string;
+    /** How many considered items lacked it. */
+    count: number;
+    code: UnknownCode;
+}
+/**
+ * How much of what the producer looked at it could actually measure. A
+ * non-empty `unmeasured` makes a `measured` observation DEGRADED (legal) and an
+ * `absent` one ILLEGAL; so does `considered === 0` for `absent`.
+ */
+export interface ObservationCoverage {
+    /** Items the producer considered. */
+    considered: number;
+    /** Items it could measure in full. */
+    measured: number;
+    /** Named dimensions it could not measure. Always present — `[]` is the statement "full coverage". */
+    unmeasured: UnmeasuredDimension[];
+}
+/** Provenance of a cached answer. Every key always present. */
+export interface ObservationCache {
+    /** Whether this answer was served from the cache. */
+    hit: boolean;
+    /** When the served entry was stored. `null` on a miss or when the cache keeps no timestamp. */
+    storedAt: string | null;
+    /** The inputs the cache key was derived from, so a reader can judge what a hit is keyed on. */
+    keyInputs: string[];
+}
+/** Where an {@link Observation} came from. EVERY key is always present. */
+export interface ObservationProvenance {
+    producer: ObservationProducer;
+    /** When the underlying state was sampled (snapshot time / frame capture). `null` = no sample was taken. */
+    observedAt: string | null;
+    /** When the producer ran. Never null. */
+    evaluatedAt: string;
+    coverage: ObservationCoverage;
+    /** Finite, in `[0, 1]`, or `null` = "a deduction, not an estimate". */
+    confidence: number | null;
+    /** `null` = this producer has no cache. */
+    cache: ObservationCache | null;
+    /** Source attribution as a JSON object, or `null` = the producer has none to give. */
+    source: Record<string, unknown> | null;
+}
+/** Why a producer could not answer. */
+export interface ObservationUnknown {
+    code: UnknownCode;
+    /** Human prose. Never the only carrier of the reason — `code` is. */
+    detail: string;
+}
+/** The three answers, as the `status` tag spells them on the wire. */
+export type ObservationStatus = 'measured' | 'absent' | 'unknown';
+/** The producer looked and saw `value`. */
+export interface MeasuredObservation<T> {
+    status: 'measured';
+    value: T;
+    provenance: ObservationProvenance;
+}
+/** The producer looked with FULL coverage and found nothing. */
+export interface AbsentObservation {
+    status: 'absent';
+    provenance: ObservationProvenance;
+}
+/** The producer could not look. Carries no `value`. */
+export interface UnknownObservation {
+    status: 'unknown';
+    unknown: ObservationUnknown;
+    provenance: ObservationProvenance;
+}
+/**
+ * The envelope. A discriminated union on `status`, so there is no `measured`
+ * without a `value`, no `unknown` without a `code`, and no `value` beside an
+ * `absent` — at compile time. The one invariant spanning the state AND the
+ * provenance (`absent` only over full coverage of at least one considered
+ * item) is enforced by
+ * {@link Observation.absent}.
+ */
+export type Observation<T> = MeasuredObservation<T> | AbsentObservation | UnknownObservation;
+/** Thrown when a constructor is asked for an illegal envelope. */
+export declare class ObservationError extends Error {
+    constructor(message: string);
+}
+/** A timestamp in any of the forms producers hold one in. */
+export type ObservationTime = string | number | Date;
+/** Inputs for {@link Observation.provenance}. Omitted optional keys become the explicit `null` statements. */
+export interface ObservationProvenanceInit {
+    producer: ObservationProducer;
+    /** When the underlying state was sampled. Omitted / `null` = no sample was taken. */
+    observedAt?: ObservationTime | null;
+    /** When the producer ran. Defaults to now. */
+    evaluatedAt?: ObservationTime;
+    /** Defaults to `{ considered: 0, measured: 0, unmeasured: [] }`. */
+    coverage?: ObservationCoverage;
+    /** Omitted / `null` / non-finite = a deduction, not an estimate. */
+    confidence?: number | null;
+    /** Omitted / `null` = this producer has no cache. */
+    cache?: {
+        hit: boolean;
+        storedAt: ObservationTime | null;
+        keyInputs: string[];
+    } | null;
+    /** Omitted / `null` = no source attribution. */
+    source?: Record<string, unknown> | null;
+}
+/** Full coverage of `n` considered items. */
+declare function fullCoverage(n: number): ObservationCoverage;
+declare function provenance(init: ObservationProvenanceInit): ObservationProvenance;
+/**
+ * The producer looked and saw `value`. THROWS {@link ObservationError} on
+ * `undefined`: a measured observation whose `value` key would vanish from
+ * the wire is exactly the missing-key shape the Rust canon refuses.
+ */
+declare function measured<T>(value: T, prov: ObservationProvenance): Observation<T>;
+/**
+ * The producer looked and found nothing. "absent" means the producer
+ * considered at least one item, measured every one of them, and found
+ * nothing. THROWS {@link ObservationError}, checked in the Rust canon's order:
+ *
+ * 1. `coverage.unmeasured` is non-empty — never asserted over a region the
+ *    producer did not measure;
+ * 2. `coverage.considered` is 0 — never asserted over nothing looked at (a
+ *    producer with nothing to consider answers `unknown`, e.g.
+ *    `producer_not_run` / `input_missing`);
+ * 3. `coverage.measured !== coverage.considered` — a partial look is
+ *    `measured` with its gaps in `coverage.unmeasured`, never `absent`.
+ */
+declare function absent<T = never>(prov: ObservationProvenance): Observation<T>;
+declare function unknown<T = never>(code: UnknownCode, detail: string, prov: ObservationProvenance): Observation<T>;
+/**
+ * Constructors for the envelope. `Observation.measured` / `.absent` /
+ * `.unknown` are the ONLY way to build one; `.provenance` builds the block
+ * with every nullable key stated explicitly.
+ *
+ * @example
+ * ```ts
+ * // `Observation` is exported by the package that ships this module.
+ * const prov = Observation.provenance({
+ *   producer: { id: 'sdk/page-health', version: '0.29.0' },
+ *   observedAt: Date.now(),
+ * });
+ * const obs = Observation.unknown('input_missing', 'no elements key', prov);
+ * ```
+ */
+export declare const Observation: {
+    readonly provenance: typeof provenance;
+    readonly fullCoverage: typeof fullCoverage;
+    readonly measured: typeof measured;
+    readonly absent: typeof absent;
+    readonly unknown: typeof unknown;
+};
+export {};
+//# sourceMappingURL=observation.d.ts.map

package/dist/observation/observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation.d.ts","sourceRoot":"","sources":["../../src/observation/observation.ts"],"names":[],"mappings":"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"}

package/dist/react/index.js

@@ -2381,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(() => {
@@ -2418,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 };
   }
   /**
@@ -3161,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"]);
@@ -3230,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)
@@ -3391,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
@@ -3845,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 () => {
@@ -4355,7 +4641,7 @@ function createServerHandlers(registry, executor, config) {
       };
       if (config?.appInfo) {
         response.uiBridge = {
-          version: "0.6.16",
+          version: "0.7.0",
           ...config.appInfo,
           capabilities: ["elements", "components", "actions", "design"],
           elementCount: stats.elements,