@termwright/protocol 0.2.0 → 0.3.0

package/dist/contract-CH9gmj2Y.d.ts

@@ -0,0 +1,746 @@
+import { SessionCapabilityId, ProbeCapability, EvidenceProviderCapability } from './capability-graph.js';
+
+/**
+ * Semantic roles for the current protocol. ARIA-aligned; closed set. Unknown roles must be rejected
+ * during validation — they never silently acquire behavior.
+ */
+declare const SEMANTIC_ROLES: readonly ["application", "region", "dialog", "alert", "status", "list", "listitem", "menu", "menuitem", "button", "checkbox", "radio", "tab", "textbox", "heading", "text", "progressbar", "separator", "scrollbar", "table", "row", "cell", "generic"];
+type SemanticRole = (typeof SEMANTIC_ROLES)[number];
+/** Descriptive action capabilities. Diagnostic/strategy hints, never callback endpoints. */
+declare const SEMANTIC_ACTIONS: readonly ["focus", "activate", "toggle", "setValue", "scroll", "select", "expand"];
+type SemanticAction = (typeof SEMANTIC_ACTIONS)[number];
+declare const PHYSICAL_INPUT_RECIPE_ACTIONS: readonly ["focus", "activate", "toggle", "setValue"];
+type PhysicalInputRecipeAction = (typeof PHYSICAL_INPUT_RECIPE_ACTIONS)[number];
+/** Data-only physical input recipe; integrations never receive an execution callback. */
+type PhysicalInputRecipeStep = {
+    readonly kind: 'press';
+    readonly key: string;
+} | {
+    readonly kind: 'insert-action-value';
+};
+interface PhysicalInputRecipe {
+    readonly action: PhysicalInputRecipeAction;
+    readonly requiresFocus: boolean;
+    readonly steps: readonly PhysicalInputRecipeStep[];
+}
+
+/**
+ * Why a fact is temporarily unsettled.
+ *
+ * Every value names a revision-domain retry boundary. Permanent inability to
+ * observe a fact is `unsupported`, never `unknown`.
+ */
+type ObservationUnknownReason = 'awaiting-revision-pair' | 'provider-refresh' | 'stale-revision';
+type ObservationAbsentReason = 'detached' | 'not-displayed' | 'not-laid-out';
+type ObservationUnsupportedReason = 'capability' | 'framework-unobservable' | 'not-negotiated';
+type ObservationEvidence = EvidenceProvenance;
+type AuthoritativeObservationEvidence = ObservationEvidence & {
+    readonly strength: 'authoritative';
+};
+/**
+ * A fact with its epistemic state preserved.
+ *
+ * Consumers must never coerce `unknown`/`unsupported` to false, nor absence to
+ * an empty value. That rule prevents assertions from passing because a probe
+ * simply could not observe the requested property.
+ */
+type Observation<T> = {
+    readonly status: 'known';
+    readonly value: T;
+    readonly evidence: ObservationEvidence;
+} | {
+    readonly status: 'absent';
+    readonly reason: ObservationAbsentReason;
+    readonly evidence: AuthoritativeObservationEvidence;
+} | {
+    readonly status: 'unknown';
+    readonly reason: ObservationUnknownReason;
+} | {
+    readonly status: 'unsupported';
+    readonly capability: string;
+    readonly reason: ObservationUnsupportedReason;
+};
+type SemanticValueAbsentReason = ObservationAbsentReason | 'no-value';
+type SemanticValueWithheldReason = 'sensitive' | 'artifact-policy' | 'provider-policy';
+/** A semantic value never collapses absence, uncertainty, support or confidentiality. */
+type SemanticValueObservation = {
+    readonly status: 'known';
+    readonly value: string;
+    readonly sensitivity: 'public' | 'sensitive';
+    readonly evidence: ObservationEvidence;
+} | {
+    readonly status: 'absent';
+    readonly reason: SemanticValueAbsentReason;
+    readonly evidence: AuthoritativeObservationEvidence;
+} | {
+    readonly status: 'unknown';
+    readonly reason: ObservationUnknownReason;
+} | {
+    readonly status: 'unsupported';
+    readonly capability: 'semantic-value';
+    readonly reason: ObservationUnsupportedReason;
+} | {
+    readonly status: 'withheld';
+    readonly reason: SemanticValueWithheldReason;
+    readonly sensitivity: 'public' | 'sensitive';
+};
+/** Atomic identity of the screen/tree pair used for an observation. */
+interface ObservationStamp {
+    readonly sessionId: string;
+    readonly contractId: string;
+    readonly epoch: number;
+    /** Monotonic publication order across both screen and semantic revisions. */
+    readonly sequence: number;
+    readonly screenRevision: number;
+    readonly semanticRevision: number | null;
+    /** Screen revision paired to semanticRevision, or null when no pair exists. */
+    readonly pairedScreenRevision: number | null;
+}
+type CoordinateSpace = 'viewport-cells' | 'framework-local-cells';
+interface LocatorGeometry {
+    readonly stamp: ObservationStamp;
+    readonly coordinateSpace: Observation<CoordinateSpace>;
+    readonly intendedRect: Observation<Rect>;
+    readonly visibleRect: Observation<Rect>;
+}
+interface ViewportIntersection {
+    /** Half-open intersection in viewport cell coordinates. */
+    readonly rect: Rect;
+    /** Intersection area / intended area. Zero-area intended rect has ratio 0. */
+    readonly ratio: number;
+    readonly fullyInside: boolean;
+}
+interface LocatorVisibility {
+    readonly stamp: ObservationStamp;
+    readonly attached: Observation<boolean>;
+    readonly displayed: Observation<boolean>;
+    readonly viewport: Observation<ViewportIntersection>;
+    readonly offscreen: Observation<boolean>;
+}
+interface CellPoint {
+    readonly row: number;
+    readonly column: number;
+}
+interface PointerHitTest {
+    readonly stamp: ObservationStamp;
+    readonly point: Observation<CellPoint>;
+    readonly receivesEvents: Observation<boolean>;
+    /** Ref of the actual recipient, when the producer can identify it. */
+    readonly recipient: Observation<string>;
+}
+type SpatialRelation = 'contains' | 'inside' | 'overlaps' | 'left-of' | 'right-of' | 'above' | 'below' | 'aligned-left' | 'aligned-right' | 'aligned-top' | 'aligned-bottom' | 'adjacent-horizontal' | 'adjacent-vertical';
+/** Correct half-open rectangle intersection. Touching edges do not overlap. */
+declare function intersectRects(a: Rect, b: Rect): Rect;
+declare function rectArea(rect: Rect): number;
+declare function viewportIntersection(rect: Rect, columns: number, rows: number): ViewportIntersection;
+declare function spatialRelation(a: Rect, relation: SpatialRelation, b: Rect): boolean;
+
+/** Zero-based viewport cell coordinates. */
+interface Rect {
+    readonly row: number;
+    readonly column: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** Closed state set. No arbitrary records. */
+interface SemanticState {
+    readonly disabled?: boolean;
+    readonly focused?: boolean;
+    readonly selected?: boolean;
+    readonly checked?: boolean | 'mixed';
+    readonly expanded?: boolean;
+    readonly modal?: boolean;
+    readonly busy?: boolean;
+    readonly hidden?: boolean;
+    /**
+     * The node exists in the layout, but every one of its cells falls outside the
+     * visible area — it is scrolled out, and scrolling can bring it back.
+     *
+     * Named for the claim a test author makes ("this row is off screen"), not for
+     * the mechanism that produced it. Clipping is how it happens; being off
+     * screen is what it means.
+     *
+     * **Absent means "not claiming"**, not "on screen". A producer that cannot
+     * observe clipping simply omits it. Evidence-qualified geometry remains the
+     * authoritative source for viewport and visibility assertions.
+     *
+     * Implies {@link SemanticState.hidden}: if every cell is outside the visible
+     * area then the node is not visible, and validation refuses the pair
+     * `offscreen: true` without `hidden: true`.
+     */
+    readonly offscreen?: boolean;
+    readonly readonly?: boolean;
+    readonly multiline?: boolean;
+    readonly required?: boolean;
+    readonly multiselectable?: boolean;
+    readonly orientation?: 'horizontal' | 'vertical';
+    readonly level?: number;
+    readonly positionInSet?: number;
+    readonly setSize?: number;
+}
+/** Authoritative application viewport state in production-defined logical units. */
+interface SemanticScrollState {
+    readonly axis: 'vertical' | 'horizontal';
+    /** Logical distance from the start of the scrollable content. */
+    readonly offset: number;
+    /** Logical size of the visible application viewport. */
+    readonly viewport: number;
+    /** Logical size of the complete scrollable content. */
+    readonly extent: number;
+}
+/** Exact viewport cells painted by one semantic recipient for a committed frame. */
+interface SemanticPaintedRegion {
+    /** Bounding box of the painted cells; this is not intended layout geometry. */
+    readonly regionBounds: Rect;
+    /** Canonical, non-overlapping half-open row runs. */
+    readonly spans: readonly {
+        readonly row: number;
+        readonly from: number;
+        readonly to: number;
+    }[];
+}
+/** Maps grapheme offsets of a node's text to cell coordinates (optional capability). */
+interface SemanticTextRange {
+    readonly startOffset: number;
+    readonly endOffset: number;
+    readonly rect: Rect;
+}
+/**
+ * Deterministic JSON data owned by the application domain, not by the portable
+ * semantic vocabulary. Containers are allowed, but runtime objects/functions
+ * are not; validation applies the protocol's normal depth, byte and collection
+ * ceilings recursively.
+ */
+interface SemanticExtendedArray extends ReadonlyArray<SemanticExtendedValue> {
+}
+interface SemanticExtendedObject {
+    readonly [key: string]: SemanticExtendedValue;
+}
+type SemanticExtendedValue = null | boolean | number | string | SemanticExtendedArray | SemanticExtendedObject;
+/** Application-defined state, deliberately separate from {@link SemanticState}. */
+type SemanticExtendedState = SemanticExtendedObject;
+interface SemanticNode {
+    readonly id: string;
+    readonly parentId?: string;
+    readonly role: SemanticRole;
+    readonly name: string;
+    readonly description?: string;
+    readonly value?: SemanticValueObservation;
+    readonly state?: SemanticState;
+    /** Application-specific, serializable state; never promoted to portable flags. */
+    readonly extended?: SemanticExtendedState;
+    readonly actions?: readonly SemanticAction[];
+    /** Authoritative recipe executed only through Termwright's real input devices. */
+    readonly inputRecipes?: readonly PhysicalInputRecipe[];
+    readonly labelledBy?: readonly string[];
+    readonly describedBy?: readonly string[];
+    readonly textRanges?: readonly SemanticTextRange[];
+    /** Author-supplied test id (getByTestId). */
+    readonly testId?: string;
+    /**
+     * The framework's own name for this widget — a class name, a constructor
+     * name, a widget type.
+     *
+     * **Required when `role` is `generic`.** An unrecognised widget must survive
+     * as a generic node keeping its geometry, text and children, instead of being
+     * dropped with its children reparented. `frameworkType` is what makes such a
+     * node identifiable: without it a generic node says only "something was
+     * here", which is barely better than the drop it replaced.
+     */
+    readonly frameworkType?: string;
+    /** True when this node may own children the framework probe cannot enumerate. */
+    readonly opaqueChildren?: boolean;
+    /**
+     * Provenance: where this node's facts came from.
+     *
+     * One source for the whole node, because node facts overwhelmingly share
+     * one. Exceptions go in {@link SemanticNode.px}, so a mixed node pays only
+     * for the fields that actually differ. Descriptive per-property strings were
+     * ruled out by arithmetic — they cost about +91 % against a budget that is
+     * already tight.
+     */
+    readonly p?: ProvenanceSource;
+    /** Per-field provenance, for fields whose source differs from `p`. */
+    readonly px?: Readonly<Record<string, ProvenanceSource>>;
+    /** Evidence-qualified layout facts for this committed observation. */
+    readonly geometry: NodeGeometryObservations;
+    /** Application scroll state; distinct from the terminal emulator's scrollback. */
+    readonly scroll?: Observation<SemanticScrollState>;
+    /** Authoritative paint provenance; distinct from layout, clipping and pointer routing. */
+    readonly paintedRegion?: Observation<SemanticPaintedRegion>;
+}
+/** Layout facts reported independently so absence never masquerades as false. */
+interface NodeGeometryObservations {
+    readonly displayed: Observation<boolean>;
+    readonly intendedRect: Observation<Rect>;
+    readonly visibleRect: Observation<Rect>;
+}
+/** One half-open run of cells with an exact pointer recipient. */
+interface PointerHitRegion {
+    /** Canonical non-empty row run: `height` is always 1. */
+    readonly rect: Rect;
+    readonly recipientId: string;
+}
+/** A complete point-ownership map for a committed frame. */
+interface PointerHitGrid {
+    readonly regions: readonly PointerHitRegion[];
+}
+/** One provider-owned target region for a committed application revision. */
+interface ProviderPointerRegion {
+    readonly recipientId: string;
+    /** Bounding box of the pointer-receiving cells; not layout geometry. */
+    readonly regionBounds: Rect;
+    /** Canonical non-overlapping visible cell runs owned by the target. */
+    readonly spans: readonly {
+        readonly row: number;
+        readonly from: number;
+        readonly to: number;
+    }[];
+}
+/** Revision-bound application strategy recipes for one semantic recipient. */
+interface ProviderActionRecipes {
+    readonly recipientId: string;
+    readonly recipes: readonly PhysicalInputRecipe[];
+}
+/** Revision-bound application viewport state for one semantic recipient. */
+interface ProviderScrollState extends SemanticScrollState {
+    readonly recipientId: string;
+}
+/** Revision-bound application paint provenance for one semantic recipient. */
+interface ProviderPaintedRegion extends SemanticPaintedRegion {
+    readonly recipientId: string;
+}
+/** Production parser configuration hidden by the terminal transport. */
+interface ProviderTerminalInputModes {
+    readonly mouseTracking: 'none' | 'x10' | 'vt200' | 'drag' | 'any';
+    readonly mouseEncoding: 'default' | 'sgr' | 'urxvt' | 'utf8';
+    readonly focusReporting: 'on' | 'off';
+}
+/** Exact production focus-manager result for one committed revision. */
+type ProviderFocusState = {
+    readonly status: 'focused';
+    readonly recipientId: string;
+} | {
+    readonly status: 'none';
+};
+/**
+ * Application evidence bound to the same revision as its containing snapshot.
+ * A provider announced in hello must contribute exactly one entry per frame.
+ */
+type ProviderRevisionEvidence = {
+    readonly providerId: string;
+    readonly sessionId: string;
+    readonly revision: number;
+    readonly status: 'available';
+    readonly evidence: EvidenceProvenance;
+    readonly pointerRegions: readonly ProviderPointerRegion[];
+    /** Exact production focus-manager result when `focus-state` was announced. */
+    readonly focusState?: ProviderFocusState;
+    /** Production keybinding recipes when `action-recipes` was announced. */
+    readonly actionRecipes?: readonly ProviderActionRecipes[];
+    /** Complete application viewport facts when `scroll-state` was announced. */
+    readonly scrollStates?: readonly ProviderScrollState[];
+    /** Complete paint attribution when `painted-regions` was announced. */
+    readonly paintedRegions?: readonly ProviderPaintedRegion[];
+    /** Production parser configuration when `terminal-input-modes` was announced. */
+    readonly inputModes?: ProviderTerminalInputModes;
+    /** Complete production-router ownership map when `hit-test` was announced. */
+    readonly hitGrid?: PointerHitGrid;
+} | {
+    readonly providerId: string;
+    readonly sessionId: string;
+    readonly revision: number;
+    readonly status: 'lost';
+    readonly reason: string;
+} | {
+    readonly providerId: string;
+    readonly sessionId: string;
+    readonly revision: number;
+    readonly status: 'violation';
+    readonly reason: string;
+};
+interface CursorInfo {
+    readonly row: number;
+    readonly column: number;
+    readonly visible: boolean;
+    readonly shape?: 'block' | 'underline' | 'bar';
+}
+interface SemanticSnapshot {
+    readonly v: 2;
+    readonly sessionId: string;
+    /** Positive, strictly increasing within a semantic session. */
+    readonly revision: number;
+    readonly columns: number;
+    readonly rows: number;
+    readonly cursor?: CursorInfo;
+    readonly rootIds: readonly string[];
+    readonly nodes: readonly SemanticNode[];
+    /** Coordinate system used by every physical observation in this snapshot. */
+    readonly coordinateSpace: Observation<CoordinateSpace>;
+    /**
+     * Required by v2. `known` means a complete map, not a sample or paint-order
+     * approximation. Cells absent from a known map have no semantic recipient.
+     */
+    readonly hitGrid: Observation<PointerHitGrid>;
+    /** Present only when application evidence providers were negotiated in hello. */
+    readonly providerEvidence?: readonly ProviderRevisionEvidence[];
+}
+
+/**
+ * Probe IR — what an instrumented process **observed**, not what it means.
+ *
+ * A probe reports facts; a recognizer turns them into the semantic tree. The
+ * split exists because the six frameworks disagree about what is even knowable,
+ * and collapsing that disagreement early is how a tree ends up asserting things
+ * no framework ever said.
+ *
+ * Three rules shape every type here, each forced by the Phase 0 audits:
+ *
+ * 1. **Never fabricate identity.** Immediate-mode frameworks have none, and a
+ *    synthesised ordinal presented as a handle is worse than no handle: a test
+ *    written against it fails later and looks flaky rather than wrong. Identity
+ *    is therefore a typed capability with `frame-local` as a first-class value.
+ * 2. **Intent is not ownership.** The rectangle a widget was drawn *into* is not
+ *    the cells it ended up owning; later writes win and no framework records
+ *    who painted what. The two are separate fields, and only one framework
+ *    computes the second.
+ * 3. **Absent and unobservable are different facts.** A state a framework does
+ *    not expose is not a state that is off. The IR says which is which, rather
+ *    than letting `undefined` mean both.
+ *
+ * Naming note: the words `region` and `area` are avoided throughout. Each
+ * carries at least three conflicting meanings across the audited frameworks,
+ * and an IR that reuses them inherits every one of those ambiguities.
+ */
+/**
+ * How an object's identity behaves across frames.
+ *
+ * `frame-local` is a legitimate answer, not a degraded one: in immediate mode
+ * the widget is consumed by the render and nothing upstream survives to be
+ * named again. A consumer must not correlate `frame-local` values between
+ * frames.
+ */
+type ProbeIdentityKind = 'stable' | 'frame-local';
+/** An object's identity, tagged with what it is worth. */
+interface ProbeIdentity {
+    readonly kind: ProbeIdentityKind;
+    /** Unique within its frame; unique across the session only when `stable`. */
+    readonly value: string;
+}
+/**
+ * A rectangle in terminal cells.
+ *
+ * Deliberately not called a region or an area: `row`/`column` are absolute
+ * cell coordinates, and negative origins are legal because a widget may be
+ * partly scrolled off.
+ */
+interface ProbeRect {
+    readonly row: number;
+    readonly column: number;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Where an object was drawn.
+ *
+ * `intendedRect` is where it *asked* to draw. It is a statement of intent, not
+ * a claim on cells: frameworks do not clip it, do not validate it against the
+ * viewport, and a later write silently wins. For overlapping UIs — popups,
+ * modals, shadows — it is not where the object ended up.
+ *
+ * `visibleRect` is the intersection with the clip imposed by ancestors, which
+ * is the closest any framework gets to "what the user can see". Only one of
+ * the six computes it; everywhere else it is absent, and inferring it from
+ * `intendedRect` would be inventing a fact.
+ */
+interface ProbeGeometry {
+    readonly intendedRect?: ProbeRect;
+    readonly visibleRect?: ProbeRect;
+}
+/** Scroll position, in cells, of a scrollable object's viewport. */
+interface ProbeScroll {
+    readonly row: number;
+    readonly column: number;
+}
+/** Total scrollable extent, in cells. Absent where a framework cannot report it. */
+interface ProbeExtent {
+    readonly rows: number;
+    readonly columns: number;
+}
+/**
+ * State a probe read directly from the framework.
+ *
+ * Every field is optional, and absence means "not reported by this probe".
+ * A field the framework is *known* not to expose belongs in
+ * {@link ProbeObject.unobservable} instead, so a consumer can tell "off" from
+ * "unknowable".
+ *
+ * The three selection facts have separate names on purpose. An accessibility
+ * `selected` flag, a highlighted collection index and a selected text range
+ * are not interchangeable, even though frameworks often call all three
+ * "selection".
+ */
+interface ProbeObservedState {
+    readonly focused?: boolean;
+    readonly disabled?: boolean;
+    readonly checked?: boolean | 'mixed';
+    readonly expanded?: boolean;
+    readonly readonly?: boolean;
+    readonly selected?: boolean;
+    readonly busy?: boolean;
+    readonly multiline?: boolean;
+    readonly required?: boolean;
+    readonly multiselectable?: boolean;
+    /**
+     * Whether the framework's own display flag is on. Distinct from being
+     * scrolled out of view, which shows up as an empty `visibleRect`.
+     */
+    readonly displayed?: boolean;
+    /** Contents of a value-bearing widget. `''` means empty, not absent. */
+    readonly value?: string;
+    /** Explicit confidentiality classification. Omitted values default sensitive. */
+    readonly valueSensitivity?: 'public' | 'sensitive';
+    /** Highlighted item in a collection, by index. Not a text selection. */
+    readonly selectedIndex?: number;
+    /** Selected text range within this object. Not an item selection. */
+    readonly textSelection?: {
+        readonly start: number;
+        readonly end: number;
+    };
+    readonly scroll?: ProbeScroll;
+    readonly scrollExtent?: ProbeExtent;
+}
+/** Field names a probe can declare unobservable. */
+declare const PROBE_UNOBSERVABLE_FIELDS: readonly ["focused", "disabled", "checked", "expanded", "readonly", "selected", "busy", "multiline", "required", "multiselectable", "displayed", "value", "selectedIndex", "textSelection", "scroll", "scrollExtent", "intendedRect", "visibleRect", "paintOrder", "text", "parent"];
+type ProbeUnobservableField = (typeof PROBE_UNOBSERVABLE_FIELDS)[number];
+/**
+ * Author-supplied annotations carried verbatim.
+ *
+ * The probe does not interpret these — a recognizer does, at the top of the
+ * merge precedence. `role` is deliberately a free string here: it is whatever
+ * the author wrote, and validating it against the closed role set is the
+ * recognizer's job, which can then report a bad annotation instead of silently
+ * dropping it.
+ */
+interface ProbeAccessibilityHints {
+    /** Framework-native accessibility role, in the framework's vocabulary. */
+    readonly role?: string;
+    readonly name?: string;
+    readonly description?: string;
+}
+interface ProbeAnnotations {
+    readonly role?: string;
+    readonly name?: string;
+    readonly testId?: string;
+    readonly description?: string;
+    /** Application-domain JSON state, kept outside the portable state flags. */
+    readonly extended?: SemanticExtendedState;
+    /** Descriptive action intent; never callbacks or a second input channel. */
+    readonly actions?: readonly SemanticAction[];
+    /** Production key bindings represented as data, never framework callbacks. */
+    readonly inputRecipes?: readonly PhysicalInputRecipe[];
+    /** Probe identity values of author-declared labelling relationships. */
+    readonly labelledBy?: readonly string[];
+    /** Probe identity values of author-declared description relationships. */
+    readonly describedBy?: readonly string[];
+}
+/**
+ * One object a probe observed in a frame.
+ *
+ * `frameworkType` is required. It is the framework's own name for the thing —
+ * a class name, a constructor name, a widget type — and it is what keeps an
+ * unrecognised widget alive as a `generic` node instead of being dropped. Its
+ * quality varies enormously (Textual gives a full class ancestry; Ink gives one
+ * of four host-element names), so a recognizer must treat it as a hint, not a
+ * classification.
+ */
+interface ProbeObject {
+    readonly identity: ProbeIdentity;
+    readonly frameworkType: string;
+    /** Parent's identity value; absent for a root. */
+    readonly parent?: string;
+    readonly geometry?: ProbeGeometry;
+    readonly state?: ProbeObservedState;
+    /** Text the object itself carries, not its descendants'. */
+    readonly text?: string;
+    /** Accessibility metadata retained by the framework itself, not author SDK data. */
+    readonly accessibility?: ProbeAccessibilityHints;
+    readonly annotations?: ProbeAnnotations;
+    /**
+     * Where this object sits in paint order: higher was painted later, and
+     * therefore on top.
+     *
+     * Available in three of the six frameworks (a compositor hit-test, a z-order
+     * child list, a paint-order key) and absent in the rest. It is the only fact
+     * that makes "is my target actually the thing at this cell" answerable
+     * without inventing cell ownership, which no framework records.
+     */
+    readonly paintOrder?: number;
+    /**
+     * Facts this framework cannot report for this object. Distinct from a field
+     * simply being absent, which means the probe did not report it this time.
+     */
+    readonly unobservable?: readonly ProbeUnobservableField[];
+}
+/**
+ * A render or layout call the probe intercepted.
+ *
+ * Only some frameworks expose a call stream, and in immediate mode it is the
+ * *only* structure that exists — there is no tree to walk, just an ordered list
+ * of "this type was drawn into this rectangle". `ordinal` is the position in
+ * that stream and is meaningful only within its frame.
+ */
+interface ProbeOperation {
+    readonly kind: 'render' | 'layout';
+    readonly ordinal: number;
+    /** Identity of the object this call concerned, when the probe can attribute it. */
+    readonly target?: ProbeIdentity;
+    readonly frameworkType?: string;
+    readonly intendedRect?: ProbeRect;
+}
+/**
+ * One observed frame.
+ *
+ * `objects` may be empty and `operations` may carry everything: that is what an
+ * immediate-mode frame looks like, and a flat op list is a legal degenerate
+ * tree rather than an error.
+ */
+interface ProbeFrame {
+    /** Monotonic within the session. Every framework has exactly one of these. */
+    readonly frame: number;
+    readonly objects: readonly ProbeObject[];
+    readonly operations?: readonly ProbeOperation[];
+}
+
+/** Injection tiers used by the semantic-probe attachment doctrine. */
+declare const PROBE_INJECTION_TIERS: readonly ["T0", "T1", "T2", "T3"];
+type ProbeInjectionTier = (typeof PROBE_INJECTION_TIERS)[number];
+/** Semantic class A has geometry; class B deliberately publishes a tree without it. */
+declare const PROBE_SEMANTIC_CLASSES: readonly ["A", "B"];
+type ProbeSemanticClass = (typeof PROBE_SEMANTIC_CLASSES)[number];
+/**
+ * Named reductions a probe can report even when the broader session
+ * capability remains useful. These are deliberately more precise than the
+ * capability graph: omitting inactive screens must not disable the live
+ * semantic tree, and an opaque custom container must not disable known
+ * framework children.
+ */
+declare const PROBE_DEGRADED_CAPABILITIES: readonly ["semantic-tree", "stable-identity", "intended-geometry", "clipped-geometry", "painted-region", "pointer-geometry", "pointer-hit-testing", "focus", "scroll", "render-order", "action-strategies", "keyboard-input", "pointer-input", "focus-input", "paired-revisions", "inactive-screen-tree", "custom-container-enumeration"];
+type ProbeDegradedCapabilityId = SessionCapabilityId | 'inactive-screen-tree' | 'custom-container-enumeration';
+/** Runtime record of the strongest attachment mechanism that actually engaged. */
+interface ProbeInstrumentation {
+    readonly highestTier: ProbeInjectionTier;
+    readonly semanticClass: ProbeSemanticClass;
+    readonly degradedCapabilities: readonly ProbeDegradedCapabilityId[];
+}
+/**
+ * What a probe says about itself when it attaches.
+ *
+ * @remarks
+ * `frame-begin` is optional for a reason that is easy to get wrong. No audited
+ * framework offers a hook guaranteed to fire before every frame: one lets a
+ * pre-draw hook veto the frame entirely (so the post-draw hook never runs), one
+ * exposes only a post-frame hook, and one decouples submission from the flush
+ * with a ticker. A consumer must therefore never read "no frame-begin" as "no
+ * frame in progress" — doing so turns four of the six frameworks into a hang
+ * rather than an error.
+ */
+interface ProbeInfo {
+    /** Framework name, e.g. `ink`, `textual`, `ratatui`. */
+    readonly framework: string;
+    readonly frameworkVersion?: string;
+    /** Version of the probe itself, so a mismatch is diagnosable. */
+    readonly probeVersion: string;
+    /** The best identity this probe can offer for any object. */
+    readonly identityKind: ProbeIdentityKind;
+    readonly capabilities: readonly ProbeCapability[];
+    /**
+     * How this concrete run attached and what it could not observe.
+     * Optional on the wire so existing protocol-v2/custom adapters remain valid.
+     */
+    readonly instrumentation?: ProbeInstrumentation;
+}
+/**
+ * Where a semantic fact came from.
+ *
+ * Ranked: an annotation is what the author said, a recognizer is what our rules
+ * concluded, `framework` is what the framework itself reported, `correlation`
+ * is what matching across sources implied, and `heuristic` is a guess that
+ * happened to be useful. The merge precedence follows this order, except that
+ * physical facts — bounds, focus, visibility, cells — are never casually
+ * overridden by an annotation: an author may name a thing, but may not declare
+ * where it is on screen.
+ */
+declare const PROVENANCE_SOURCES: readonly ["annotation", "recognizer", "framework", "application", "correlation", "heuristic"];
+type ProvenanceSource = (typeof PROVENANCE_SOURCES)[number];
+
+/**
+ * Stable application provider identity announced in the adapter hello.
+ *
+ * Providers are collected before hello is sent. The declaration is therefore
+ * part of the same immutable negotiation as framework and terminal evidence;
+ * there is no late-registration message and no mutable side channel.
+ */
+interface EvidenceProviderRegistration {
+    readonly id: string;
+    readonly version: string;
+    readonly capabilities: readonly EvidenceProviderCapability[];
+    /** How the application obtains its authoritative production-router facts. */
+    readonly method: 'native' | 'declared';
+}
+/** Where a fact originated, how it was obtained, and what consumers may infer. */
+interface EvidenceProvenance {
+    readonly source: 'framework' | 'application' | 'terminal' | 'recognizer' | 'driver';
+    readonly method: 'native' | 'instrumented' | 'declared' | 'correlated' | 'measured' | 'derived' | 'heuristic';
+    readonly strength: 'authoritative' | 'diagnostic';
+    /** Stable identity of the producer, never a display label. */
+    readonly providerId: string;
+}
+declare function evidence(source: EvidenceProvenance['source'], method: EvidenceProvenance['method'], strength: EvidenceProvenance['strength'], providerId: string): EvidenceProvenance;
+type SessionCapabilityAvailability = {
+    readonly status: 'supported';
+    readonly evidence: EvidenceProvenance;
+} | {
+    readonly status: 'unsupported';
+    readonly reason: 'not-negotiated' | 'framework-unobservable' | 'terminal-unobservable' | 'provider-required';
+};
+type ContractProvider = {
+    readonly id: string;
+    readonly kind: 'framework' | 'terminal';
+    readonly version: string;
+} | {
+    readonly id: string;
+    readonly kind: 'application';
+    readonly version: string;
+    readonly method: 'native' | 'declared';
+    readonly capabilities: readonly EvidenceProviderCapability[];
+};
+/**
+ * Immutable public contract negotiated once for one session epoch.
+ *
+ * Runtime state (disabled nodes, clipping, terminal modes currently off) is
+ * intentionally absent. Those are actionability observations, not capability.
+ */
+interface EffectiveSessionContract {
+    readonly contractId: string;
+    readonly sessionId: string;
+    readonly epoch: number;
+    readonly protocol: 'termwright/2';
+    readonly framework: {
+        readonly name: string;
+        readonly version: string;
+        readonly adapterVersion: string;
+        readonly certificationId: string;
+        /** Runtime attachment facts declared by a framework probe, when available. */
+        readonly instrumentation?: ProbeInstrumentation;
+    } | null;
+    readonly providers: readonly ContractProvider[];
+    readonly capabilities: Readonly<Record<SessionCapabilityId, SessionCapabilityAvailability>>;
+    readonly terminal: {
+        readonly profile: string;
+        readonly platform: string;
+        readonly mouseModesObservable: boolean;
+    };
+}
+
+export { type ProviderActionRecipes as $, type AuthoritativeObservationEvidence as A, type PointerHitRegion as B, type CellPoint as C, type PointerHitTest as D, type EvidenceProviderRegistration as E, type ProbeAccessibilityHints as F, type ProbeDegradedCapabilityId as G, type ProbeExtent as H, type ProbeGeometry as I, type ProbeIdentity as J, type ProbeIdentityKind as K, type LocatorGeometry as L, type ProbeInjectionTier as M, type NodeGeometryObservations as N, type Observation as O, type ProbeAnnotations as P, type ProbeInstrumentation as Q, type Rect as R, type SemanticNode as S, type ProbeObject as T, type ProbeObservedState as U, type ProbeOperation as V, type ProbeRect as W, type ProbeScroll as X, type ProbeSemanticClass as Y, type ProbeUnobservableField as Z, type ProvenanceSource as _, type SemanticState as a, type ProviderFocusState as a0, type ProviderPaintedRegion as a1, type ProviderPointerRegion as a2, type ProviderRevisionEvidence as a3, type ProviderScrollState as a4, type ProviderTerminalInputModes as a5, SEMANTIC_ACTIONS as a6, SEMANTIC_ROLES as a7, type SemanticAction as a8, type SemanticExtendedArray as a9, type SemanticExtendedObject as aa, type SemanticExtendedState as ab, type SemanticExtendedValue as ac, type SemanticPaintedRegion as ad, type SemanticScrollState as ae, type SemanticTextRange as af, type SemanticValueAbsentReason as ag, type SemanticValueObservation as ah, type SemanticValueWithheldReason as ai, type SessionCapabilityAvailability as aj, type SpatialRelation as ak, type ViewportIntersection as al, evidence as am, intersectRects as an, rectArea as ao, spatialRelation as ap, viewportIntersection as aq, type SemanticSnapshot as b, type SemanticRole as c, type ProbeFrame as d, type ProbeInfo as e, type ContractProvider as f, type CoordinateSpace as g, type CursorInfo as h, type EffectiveSessionContract as i, type EvidenceProvenance as j, type LocatorVisibility as k, type ObservationAbsentReason as l, type ObservationEvidence as m, type ObservationStamp as n, type ObservationUnknownReason as o, type ObservationUnsupportedReason as p, PHYSICAL_INPUT_RECIPE_ACTIONS as q, PROBE_DEGRADED_CAPABILITIES as r, PROBE_INJECTION_TIERS as s, PROBE_SEMANTIC_CLASSES as t, PROBE_UNOBSERVABLE_FIELDS as u, PROVENANCE_SOURCES as v, type PhysicalInputRecipe as w, type PhysicalInputRecipeAction as x, type PhysicalInputRecipeStep as y, type PointerHitGrid as z };