@qontinui/ui-bridge-native 0.6.16 → 0.7.1

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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"}