@termwright/protocol 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,16 +1,20 @@
+import { S as SemanticNode, a as SemanticState, b as SemanticSnapshot, c as SemanticRole, R as Rect, P as ProbeAnnotations, d as ProbeFrame, e as ProbeInfo, E as EvidenceProviderRegistration } from './contract-CH9gmj2Y.js';
+export { A as AuthoritativeObservationEvidence, C as CellPoint, f as ContractProvider, g as CoordinateSpace, h as CursorInfo, i as EffectiveSessionContract, j as EvidenceProvenance, L as LocatorGeometry, k as LocatorVisibility, N as NodeGeometryObservations, O as Observation, l as ObservationAbsentReason, m as ObservationEvidence, n as ObservationStamp, o as ObservationUnknownReason, p as ObservationUnsupportedReason, q as PHYSICAL_INPUT_RECIPE_ACTIONS, r as PROBE_DEGRADED_CAPABILITIES, s as PROBE_INJECTION_TIERS, t as PROBE_SEMANTIC_CLASSES, u as PROBE_UNOBSERVABLE_FIELDS, v as PROVENANCE_SOURCES, w as PhysicalInputRecipe, x as PhysicalInputRecipeAction, y as PhysicalInputRecipeStep, z as PointerHitGrid, B as PointerHitRegion, D as PointerHitTest, F as ProbeAccessibilityHints, G as ProbeDegradedCapabilityId, H as ProbeExtent, I as ProbeGeometry, J as ProbeIdentity, K as ProbeIdentityKind, M as ProbeInjectionTier, Q as ProbeInstrumentation, T as ProbeObject, U as ProbeObservedState, V as ProbeOperation, W as ProbeRect, X as ProbeScroll, Y as ProbeSemanticClass, Z as ProbeUnobservableField, _ as ProvenanceSource, $ as ProviderActionRecipes, a0 as ProviderFocusState, a1 as ProviderPaintedRegion, a2 as ProviderPointerRegion, a3 as ProviderRevisionEvidence, a4 as ProviderScrollState, a5 as ProviderTerminalInputModes, a6 as SEMANTIC_ACTIONS, a7 as SEMANTIC_ROLES, a8 as SemanticAction, a9 as SemanticExtendedArray, aa as SemanticExtendedObject, ab as SemanticExtendedState, ac as SemanticExtendedValue, ad as SemanticPaintedRegion, ae as SemanticScrollState, af as SemanticTextRange, ag as SemanticValueAbsentReason, ah as SemanticValueObservation, ai as SemanticValueWithheldReason, aj as SessionCapabilityAvailability, ak as SpatialRelation, al as ViewportIntersection, am as evidence, an as intersectRects, ao as rectArea, ap as spatialRelation, aq as viewportIntersection } from './contract-CH9gmj2Y.js';
+import { AdapterCapability } from './capability-graph.js';
+export { ADAPTER_CAPABILITIES, CAPABILITY_CONFORMANCE_CLAIMS, CAPABILITY_EDGE_KINDS, CAPABILITY_GRAPH, CAPABILITY_GRAPH_VERSION, CAPABILITY_NODE_CATEGORIES, CAPABILITY_NODE_LAYERS, CONDITION_KINDS, CapabilityConformanceClaimId, CapabilityEdgeKind, CapabilityGraphEdge, CapabilityGraphNode, CapabilityGraphValidationResult, CapabilityNodeCategory, CapabilityNodeId, CapabilityNodeLayer, CapabilityRemediation, CapabilityResolution, ConditionKind, EVIDENCE_PROVIDER_CAPABILITIES, EVIDENCE_PROVIDER_TYPES, EvidenceProviderCapability, EvidenceProviderType, PROBE_CAPABILITIES, PUBLIC_CAPABILITY_CONSUMERS, ProbeCapability, PublicCapabilityConsumer, RUNTIME_PREREQUISITES, RuntimePrerequisiteId, SESSION_CAPABILITIES, SessionCapabilityId, capabilityNode, capabilityRemediation, resolveCapability, sessionCapabilitiesFromProducers, validateCapabilityGraph } from './capability-graph.js';
+export { A as ARTIFACT_VALUE_POLICIES, a as ActionIntent, b as ActionKind, c as ActionPlan, d as ActionReceipt, e as ActionabilityExplanation, f as ArtifactValuePolicy, C as Condition, g as ConditionResult, h as ConditionTextMatcher, D as DEFAULT_ARTIFACT_VALUE_POLICY, E as ExecutableActionPlan, i as ExecutableDeviceOperation, j as ExecutableValue, L as LocatorDomain, k as LocatorRef, P as PhysicalRegion, l as PublicValue, R as RecordedDeviceOperation, m as RecordedValue, S as ScreenCondition, n as ScreenLeafCondition, o as ScreenLocatorRef, p as SemanticLocatorRef, q as SensitiveValue, V as ValueSensitivity, r as executableText, s as projectActionReceiptForArtifact, t as projectSemanticSnapshotForArtifact, u as publicValue, v as recordActionPlan, w as recordDeviceOperation, x as recordValue, y as sensitive, z as valueSensitivity } from './action-model-BP9Znu6L.js';
+export { ActionId, AttemptId, CreateRunEventInput, DEFAULT_RUN_EVENT_LIMITS, ExecutionId, InvocationId, ProduceRunEventInput, ProjectId, RUN_EVENT_CLASSES, RUN_EVENT_VERSION, RUN_ID_KINDS, RunEvent, RunEventClass, RunEventId, RunEventIdentity, RunEventJson, RunEventLimits, RunEventProducer, RunEventProducerId, RunEventStreamValidator, RunEventValidationResult, RunEventViolationCode, RunId, RunIdByKind, RunIdFactory, RunIdKind, RunnerTaskId, SessionId, ShardId, SpecId, StepId, createRunEvent, createRunId, parseRunId, validateRunEvent } from './run-events.js';
+export { DEFAULT_RUN_EVENT_JOURNAL_LIMITS, RunEventFlushBarrier, RunEventJournal, RunEventJournalAppendResult, RunEventJournalLimits, RunEventJournalViolationCode } from './run-journal.js';
+export { RUN_STATES, RUN_STATE_TRANSITIONS, RunState, RunStateTransitionResult, TERMINAL_RUN_STATES, TerminalRunState, canTransitionRunState, isRunState, isTerminalRunState, validateRunStateTransition } from './run-state.js';
 import { z } from 'zod';
 
 /** Environment variable names injected by the driver before spawning the child. */
 declare const ENV_ENDPOINT = "TERMWRIGHT_ENDPOINT";
 declare const ENV_TOKEN = "TERMWRIGHT_TOKEN";
-declare const ENV_PROTOCOL = "TERMWRIGHT_PROTOCOL";
-/** Current protocol major version. */
-declare const PROTOCOL_VERSION: 1;
-declare const PROTOCOL_ID: "termwright/1";
-/** Qualified observation protocol. V1 remains exported for existing adapters. */
-declare const PROTOCOL_V2_ID: "termwright/2";
-type ProtocolId = typeof PROTOCOL_ID | typeof PROTOCOL_V2_ID;
-declare const SUPPORTED_PROTOCOL_IDS: readonly ProtocolId[];
+/** Current and only supported protocol major version. */
+declare const PROTOCOL_VERSION: 2;
+declare const PROTOCOL_ID: "termwright/2";
+type ProtocolId = typeof PROTOCOL_ID;
 /** Entropy behind a session token, in bytes (256 bits). */
 declare const TOKEN_BYTES = 32;
 /**
@@ -78,16 +82,6 @@ declare class ProtocolViolation extends Error {
     constructor(code: ProtocolViolationCode, message: string);
 }
 
-/**
- * v1 semantic roles. 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];
-
 /**
  * Conservative defaults and absolute maxima. Callers may tighten defaults but
  * can never widen the absolute maxima.
@@ -116,622 +110,8 @@ interface ProtocolLimits {
 }
 declare const DEFAULT_LIMITS: ProtocolLimits;
 declare const ABSOLUTE_LIMITS: ProtocolLimits;
-/** Default semantic negotiation window (ms) before a session settles as generic. */
-declare const DEFAULT_NEGOTIATION_MS = 250;
-
-/**
- * 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;
-    /**
-     * 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;
-    /** 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", "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[];
-    /** 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[];
-}
-/** Optional abilities a probe declares at handshake time. */
-declare const PROBE_CAPABILITIES: readonly ["stable-identity", "visible-rect", "operations", "annotations", "frame-begin", "paint-order"];
-type ProbeCapability = (typeof PROBE_CAPABILITIES)[number];
-/**
- * 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[];
-}
-/**
- * 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", "correlation", "heuristic"];
-type ProvenanceSource = (typeof PROVENANCE_SOURCES)[number];
-
-/**
- * Resolving IR geometry into the single rectangle a semantic node publishes.
- *
- * The IR keeps `intendedRect` and `visibleRect` apart because they are
- * different facts. `SemanticNode.bounds` is one rectangle, so somewhere the two
- * have to collapse — and that collapse is a decision, not a formatting step.
- *
- * The decision: **`bounds` is always the best known *visible* geometry.** A
- * consumer never has to ask which of the two it is holding, because the answer
- * is always the same one. Publishing both rectangles instead would push "which
- * of these did you mean" onto every consumer of the tree — the same one-field-
- * two-jobs problem, moved rather than solved.
- *
- * What a consumer still cannot know from `bounds` alone is whether something
- * else was painted on top. That is what {@link ResolvedBounds.occlusion}
- * carries, and it is why the two are resolved together here rather than in five
- * independent implementations.
- */
-
-/** Whether occlusion is knowable for this node. */
-type OcclusionKnowledge = 'known' | 'unknown';
-/** Which of the IR rectangles the published bounds came from. */
-type BoundsSource = 'visible' | 'clipped' | 'intended';
-/** The rectangle a node publishes, plus what is known about it. */
-interface ResolvedBounds {
-    readonly rect: Rect;
-    /**
-     * `known` only when the probe reports paint order. Without it, a rectangle
-     * says where a widget is, not whether a pointer aimed there reaches it.
-     */
-    readonly occlusion: OcclusionKnowledge;
-    readonly source: BoundsSource;
-    /**
-     * True when the clip removed the rectangle entirely — the node exists and is
-     * scrolled out of view.
-     *
-     * A normalizer maps this to **`state.hidden: true` plus
-     * `state.offscreen: true`**. Both are needed and they say different things:
-     * `hidden` because a zero-area rectangle cannot intersect the viewport and
-     * validation refuses it otherwise, and `offscreen` because scrolled-away is
-     * not the same state as never-displayed, and a consumer reading the tree has
-     * no other way to tell them apart.
-     */
-    readonly clippedAway: boolean;
-}
-/** Settings for {@link resolveNodeBounds}. */
-interface ResolveBoundsOptions {
-    /**
-     * The clip imposed by ancestors, where the framework exposes one and has not
-     * already applied it to `visibleRect`.
-     */
-    readonly clip?: ProbeRect;
-    /** Whether the probe reports paint order for this object. */
-    readonly paintOrderKnown?: boolean;
-}
-/**
- * Collapse IR geometry into the rectangle a semantic node publishes.
- *
- * Three tiers, best first:
- * 1. `visibleRect`, where the framework computed the clip intersection itself;
- * 2. `intendedRect ∩ clip`, where a clip is known but not pre-applied;
- * 3. `intendedRect` alone, as a last resort — it is where the widget *asked* to
- *    draw, which is the only thing left when nothing knows about clipping.
- *
- * @param geometry - IR geometry for the object, if it reported any.
- * @param options - Clip and paint-order knowledge.
- * @returns The resolved bounds, or `undefined` when the object reported no
- * geometry at all. A bounds-free node is a legal, expected state — one audited
- * framework hands over a rendered string with no coordinates anywhere — and
- * inventing a rectangle for it would be worse than having none.
- */
-declare function resolveNodeBounds(geometry: ProbeGeometry | undefined, options?: ResolveBoundsOptions): ResolvedBounds | undefined;
-
-/** Why a fact could not be observed. Unknown is retryable; unsupported is not. */
-type ObservationUnknownReason = 'not-reported' | 'temporary' | 'clip-unobservable' | 'legacy-unqualified';
-type ObservationAbsentReason = 'detached' | 'not-displayed' | 'not-laid-out';
-type ObservationUnsupportedReason = 'capability' | 'framework-unobservable' | 'not-negotiated';
-type ObservationEvidence = 'adapter' | 'probe' | 'terminal-grid' | 'viewport-clip' | 'paint-order' | 'hit-grid' | 'legacy-v1';
-/**
- * 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 status: 'unknown';
-    readonly reason: ObservationUnknownReason;
-} | {
-    readonly status: 'unsupported';
-    readonly capability: string;
-    readonly reason: ObservationUnsupportedReason;
-};
-/** Atomic identity of the screen/tree pair used for an observation. */
-interface ObservationStamp {
-    readonly sessionId: string;
-    readonly screenRevision: number;
-    readonly semanticRevision: 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, which is why this is a positive
-     * assertion rather than a tri-state.
-     *
-     * It exists so that `bounds: undefined` keeps its single meaning — "this
-     * producer does not know the geometry". Before this field, an adapter had to
-     * choose between saying "no geometry" and saying "scrolled away", and those
-     * are different facts that a consumer reading a tree generically could not
-     * tell apart.
-     *
-     * 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 orientation?: 'horizontal' | 'vertical';
-    readonly level?: number;
-    readonly positionInSet?: number;
-    readonly setSize?: number;
-    readonly scrollOffset?: number;
-    readonly scrollExtent?: 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?: string;
-    /**
-     * The node's **visible** geometry, guaranteed.
-     *
-     * Normalizers resolve this to the best known visible rectangle — the clip
-     * intersection where a framework computes one, `intendedRect ∩ clip` where a
-     * clip is known, and the intended rectangle only as a last resort. A consumer
-     * therefore never has to ask which rectangle it is holding.
-     *
-     * Still optional: class-B/C frameworks publish nodes without trustworthy
-     * coordinates, and one framework hands over a rendered string with no
-     * geometry anywhere. Absent bounds is a normal state, not a degraded one.
-     */
-    readonly bounds?: Rect;
-    /**
-     * Whether it is knowable that something else was painted over this node.
-     *
-     * `bounds` says where the node is; it does not say whether a pointer aimed
-     * there reaches it. Only some frameworks expose paint order, so this is
-     * `'known'` only when the probe reported it. **Absent means `'unknown'`** —
-     * the conservative value is the default, so a producer has to claim
-     * knowledge rather than have it assumed.
-     *
-     * A consumer performing pointer actions should refuse on `'unknown'` rather
-     * than click and hope: the input lands somewhere real, and if it lands on
-     * another widget the result is attributed to this one. That is a silent
-     * false green, which is a worse failure than a refusal.
-     */
-    readonly occlusion?: OcclusionKnowledge;
-    readonly state?: SemanticState;
-    /** Application-specific, serializable state; never promoted to portable flags. */
-    readonly extended?: SemanticExtendedState;
-    readonly actions?: readonly SemanticAction[];
-    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 bounds, 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;
-    /**
-     * 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>>;
-    /**
-     * Protocol v2 qualified layout facts. V1 snapshots MUST omit this field;
-     * their legacy `bounds` projection deliberately remains unchanged.
-     */
-    readonly geometry?: NodeGeometryObservations;
-}
-/** 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[];
-}
-interface CursorInfo {
-    readonly row: number;
-    readonly column: number;
-    readonly visible: boolean;
-    readonly shape?: 'block' | 'underline' | 'bar';
-}
-interface SemanticSnapshot {
-    readonly v: 1 | 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[];
-    /** Required by v2, forbidden by strict v1 validation. */
-    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>;
-}
-
-/** Machine-readable source of truth for geometry/visibility support. */
-interface FrameworkObservationCapabilities {
-    readonly framework: 'generic' | 'textual' | 'opentui' | 'ink' | 'tview' | 'ratatui' | 'charm';
-    readonly identity: 'stable' | 'frame-local' | 'none';
-    readonly attached: 'supported';
-    readonly displayed: 'supported' | 'conditional' | 'unsupported';
-    readonly intendedRect: 'supported' | 'conditional' | 'unsupported';
-    readonly visibleRect: 'supported' | 'conditional' | 'unsupported';
-    readonly hitTest: 'supported' | 'conditional' | 'unsupported';
-    readonly reason: string;
-}
-type CapabilityAvailability = 'supported' | 'conditional' | 'unsupported';
-type GeometryOperation = 'keyboard-actions' | 'pointer-actions' | 'toBeAttached' | 'toBeDetached' | 'toBeDisplayed' | 'toBeHidden' | 'toBeVisible' | 'toBeOffscreen' | 'toBeInViewport' | 'toReceivePointerEvents' | 'toHaveBounds' | 'toHaveSpatialRelation' | 'cellSnapshot';
-interface FrameworkOperationCapability {
-    readonly framework: FrameworkObservationCapabilities['framework'];
-    readonly operation: GeometryOperation;
-    readonly availability: CapabilityAvailability;
-    readonly reason: string;
-}
-declare const FRAMEWORK_OBSERVATION_CAPABILITIES: readonly FrameworkObservationCapabilities[];
-declare function frameworkObservationCapabilities(framework: string): FrameworkObservationCapabilities | undefined;
-/**
- * Normative operation matrix, derived from the fact registry. Documentation
- * validates against this export; adapters cannot gain an assertion merely by
- * changing prose.
- */
-declare const FRAMEWORK_OPERATION_CAPABILITIES: readonly FrameworkOperationCapability[];
+/** Default adapter-discovery window (ms) before an auto-detected session closes admission. */
+declare const DEFAULT_NEGOTIATION_MS = 2000;
 
 /**
  * The field names of a semantic node and of its state, as data.
@@ -755,7 +135,7 @@ declare const FRAMEWORK_OPERATION_CAPABILITIES: readonly FrameworkOperationCapab
  * schema but missing from the interface fails to compile here, which is the
  * half of the drift a runtime test cannot catch early.
  */
-declare const SEMANTIC_NODE_KEYS: readonly (Exclude<keyof SemanticNode, 'geometry'>)[];
+declare const SEMANTIC_NODE_KEYS: readonly Exclude<keyof SemanticNode, 'geometry'>[];
 /** Every field name on `SemanticState`. */
 declare const SEMANTIC_STATE_KEYS: readonly (keyof SemanticState)[];
 
@@ -768,7 +148,7 @@ type ValidationResult = {
     readonly code: ValidationErrorCode;
     readonly detail: string;
 };
-type ValidationErrorCode = 'schema' | 'unknown-role' | 'duplicate-id' | 'missing-parent' | 'cycle' | 'depth' | 'count' | 'string-bytes' | 'bad-rect' | 'revision' | 'bytes';
+type ValidationErrorCode = 'schema' | 'unknown-role' | 'duplicate-id' | 'missing-parent' | 'cycle' | 'depth' | 'count' | 'string-bytes' | 'bad-rect' | 'provider' | 'revision' | 'bytes';
 /**
  * Full snapshot validation per spec §8.2: unique ids, existing+acyclic parent
  * relations, dense bounded arrays, Unicode scalar strings within byte bounds,
@@ -881,120 +261,6 @@ type LogValidationResult = {
  */
 declare function validateLogRecord(value: unknown, limits: ProtocolLimits): LogValidationResult;
 
-/**
- * Tree deltas: incremental semantic updates bound to an exact base revision.
- *
- * A delta is only ever applied to the revision it names. There is no
- * speculative patching and no fuzzy rebasing: if the receiver does not hold
- * exactly `baseRevision`, it asks for a full snapshot with `get-tree` and
- * throws the delta away (origin spec §8.3). A wrong tree is far more expensive
- * than a redundant snapshot, because every assertion downstream inherits the
- * error silently.
- *
- * ## Composition semantics
- *
- * The semantic tree is a flat node list joined by `parentId`, so a delta is a
- * set of upserts plus a set of removals:
- *
- * - **`changed`** upserts by id: a node absent from the base is inserted, and
- *   a node already present is **replaced wholesale**, never field-merged.
- *   Merging would need a third state meaning "unset this optional field",
- *   which the wire has no way to express.
- * - **`removed`** removes each id **together with its whole subtree**. Cascade
- *   is what keeps a delta small — dropping a dialog is one id, not one id per
- *   descendant — and it is the only rule that cannot leave orphans behind.
- * - **`rootIds`**, when present, replaces the root list outright. When absent
- *   the base roots carry over, minus anything the removals took.
- * - **`cursor`**, when present, replaces the cursor. When absent it is
- *   unchanged. Everything else about the viewport — columns, rows, session id
- *   — is inherited and cannot be changed by a delta.
- *
- * Order matters: removals are applied first, then upserts. That lets one delta
- * move a node out of a removed subtree by re-adding it in `changed`.
- */
-
-/**
- * An incremental update to a semantic tree.
- *
- * Carries no viewport or session id: those belong to the snapshot the delta is
- * composed onto, and a change to them requires a full snapshot. The cursor is
- * the exception — it moves far too often to be worth a snapshot each time.
- */
-interface TreeDelta {
-    /** The revision this delta is composed onto. Must match exactly. */
-    readonly baseRevision: number;
-    /** The revision produced by applying it. Strictly greater than the base. */
-    readonly revision: number;
-    /** Nodes to insert or replace, keyed by `id`. */
-    readonly changed: readonly SemanticNode[];
-    /** Node ids to remove, each together with its subtree. */
-    readonly removed: readonly string[];
-    /** Replacement root list; absent means the base roots carry over. */
-    readonly rootIds?: readonly string[];
-    /**
-     * Replacement cursor; **absent means unchanged**.
-     *
-     * Without this a diffs-only session could never move the cursor, which in a
-     * TUI moves on nearly every keystroke — the mode would be useless for
-     * exactly the interactive applications it exists to make cheap.
-     *
-     * A delta can set the cursor but **cannot clear it**, and the two are not
-     * the same thing: `{ visible: false }` says there is a cursor and it is
-     * hidden, while an absent `SemanticSnapshot.cursor` says there is no cursor
-     * information at all. `cursor` is the only optional field on a snapshot, so
-     * it is the only one with this asymmetry.
-     *
-     * **Producer obligation:** a producer whose tree transitions from having a
-     * cursor to having none MUST send a full snapshot rather than a delta.
-     * Emitting a delta there would leave the receiver holding a cursor the
-     * application has stopped reporting — stale state that looks live. The same
-     * rule already applies to `columns`/`rows`, which a delta also cannot change.
-     */
-    readonly cursor?: CursorInfo;
-}
-/** Structured result: never throws hostile data onward. */
-type DeltaValidationResult = {
-    readonly ok: true;
-    readonly delta: TreeDelta;
-} | {
-    readonly ok: false;
-    readonly code: ValidationErrorCode;
-    readonly detail: string;
-};
-/**
- * Validate the **shape** of an untrusted delta.
- *
- * This checks everything that can be known without the base tree: bounded
- * sizes, well-formed nodes, unique ids, and a base/revision pair that moves
- * forward. It deliberately cannot check parent existence, acyclicity, depth or
- * whether bounds fall inside the viewport — all of those are properties of the
- * *composed* tree, and {@link applyTreeDelta} checks them there.
- *
- * @param value - Untrusted candidate delta (without the message `type` field).
- * @param limits - Active limits.
- * @returns `{ ok: true, delta }` with a deep-frozen delta, or a typed failure.
- * Never throws.
- */
-declare function validateTreeDelta(value: unknown, limits: ProtocolLimits): DeltaValidationResult;
-/**
- * Compose a delta onto the snapshot it names, then validate the result.
- *
- * The base revision must match **exactly**; a mismatch is reported rather than
- * patched around, so the caller can fall back to `get-tree` per origin §8.3.
- *
- * All the invariants a delta cannot check on its own — parents exist, the tree
- * is acyclic, depth and counts are within limits, bounds intersect the viewport
- * — are checked here against the composed tree, by running the composed result
- * through {@link validateSnapshot}. A delta is therefore never trusted to
- * produce a valid tree; it is only trusted to describe one.
- *
- * @param base - The snapshot the delta is composed onto.
- * @param delta - A delta that already passed {@link validateTreeDelta}.
- * @param limits - Active limits.
- * @returns The composed, deep-frozen snapshot, or a typed failure. Never throws.
- */
-declare function applyTreeDelta(base: SemanticSnapshot, delta: TreeDelta, limits: ProtocolLimits): ValidationResult;
-
 /**
  * AccessKit export: `SemanticSnapshot` → an AccessKit `TreeUpdate`.
  *
@@ -1064,6 +330,8 @@ interface AccessKitNode {
     readonly modal?: boolean;
     readonly hidden?: boolean;
     readonly readOnly?: boolean;
+    readonly required?: boolean;
+    readonly multiselectable?: boolean;
     readonly toggled?: AccessKitToggled;
 }
 /** AccessKit's `Tree`. */
@@ -1183,12 +451,44 @@ declare const probeInfoSchema: z.ZodObject<{
     }>;
     capabilities: z.ZodArray<z.ZodEnum<{
         "stable-identity": "stable-identity";
+        "intended-rect": "intended-rect";
         "visible-rect": "visible-rect";
         operations: "operations";
         annotations: "annotations";
         "frame-begin": "frame-begin";
         "paint-order": "paint-order";
     }>>;
+    instrumentation: z.ZodOptional<z.ZodObject<{
+        highestTier: z.ZodEnum<{
+            T0: "T0";
+            T1: "T1";
+            T2: "T2";
+            T3: "T3";
+        }>;
+        semanticClass: z.ZodEnum<{
+            A: "A";
+            B: "B";
+        }>;
+        degradedCapabilities: z.ZodArray<z.ZodEnum<{
+            "intended-geometry": "intended-geometry";
+            "clipped-geometry": "clipped-geometry";
+            "stable-identity": "stable-identity";
+            "semantic-tree": "semantic-tree";
+            "painted-region": "painted-region";
+            "pointer-geometry": "pointer-geometry";
+            "pointer-hit-testing": "pointer-hit-testing";
+            focus: "focus";
+            scroll: "scroll";
+            "render-order": "render-order";
+            "action-strategies": "action-strategies";
+            "keyboard-input": "keyboard-input";
+            "pointer-input": "pointer-input";
+            "focus-input": "focus-input";
+            "paired-revisions": "paired-revisions";
+            "inactive-screen-tree": "inactive-screen-tree";
+            "custom-container-enumeration": "custom-container-enumeration";
+        }>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 /**
  * Validate a probe's self-description.
@@ -1234,13 +534,6 @@ declare function validateProbeFrame(value: unknown, limits: ProtocolLimits): Pro
  */
 declare function validateProbeAnnotations(value: unknown, limits: ProtocolLimits): ProbeAnnotationValidationResult;
 
-/**
- * Wire messages. Transport: length-prefixed JSON frames (see framing.ts).
- * CDP-like: adapter pushes commits; driver issues requests; either side may
- * send errors. All messages are validated against limits BEFORE retention.
- */
-declare const ADAPTER_CAPABILITIES: readonly ["tree", "bounds", "absolute-bounds", "states", "actions", "text-ranges", "render-revisions", "tree-diffs", "logs", "qualified-observations", "pointer-hit-grid"];
-type AdapterCapability = (typeof ADAPTER_CAPABILITIES)[number];
 /** adapter → driver, exactly once, before any other message. */
 interface HelloMessage {
     readonly type: 'hello';
@@ -1259,6 +552,8 @@ interface HelloMessage {
      * negotiates against measured capability rather than assuming a floor.
      */
     readonly probe?: ProbeInfo;
+    /** Application evidence providers frozen into this session contract. */
+    readonly providers?: readonly EvidenceProviderRegistration[];
 }
 /** driver → adapter, reply to hello. */
 interface HelloAckMessage {
@@ -1266,15 +561,8 @@ interface HelloAckMessage {
     readonly protocol: ProtocolId;
     readonly sessionId: string;
     readonly limits: ProtocolLimits;
-    /**
-     * Which traffic the driver wants pushed.
-     *
-     * `diffs` is only ever selected for an adapter that announced the
-     * `tree-diffs` capability, so an adapter that does not know the value never
-     * receives it — the closed set grew without breaking anyone, because the
-     * adapter opts in first.
-     */
-    readonly subscribe: 'snapshots' | 'revisions' | 'diffs';
+    /** Which semantic traffic the driver wants pushed. */
+    readonly subscribe: 'snapshots' | 'revisions';
     /** Marker configuration: producer must emit the signed OSC 8487 commit marker. */
     readonly marker: {
         readonly enabled: boolean;
@@ -1307,19 +595,6 @@ interface SnapshotMessage {
     readonly type: 'snapshot';
     readonly snapshot: SemanticSnapshot;
 }
-/** driver → adapter, request full snapshot (latest, or a held revision). */
-interface GetTreeRequest {
-    readonly type: 'get-tree';
-    readonly requestId: number;
-    readonly revision?: number;
-}
-/** adapter → driver, response to get-tree. */
-interface GetTreeResponse {
-    readonly type: 'get-tree-result';
-    readonly requestId: number;
-    readonly snapshot?: SemanticSnapshot;
-    readonly error?: string;
-}
 /**
  * adapter → driver, a frame has started (capability `frame-begin`).
  *
@@ -1341,17 +616,6 @@ interface FrameBeginMessage {
     readonly type: 'frame-begin';
     readonly revision: number;
 }
-/**
- * adapter → driver, an incremental tree update (capability `tree-diffs`,
- * `subscribe: 'diffs'`).
- *
- * Bound to an exact base revision: see `delta.ts` for composition semantics.
- * A receiver that does not hold `baseRevision` must request a full snapshot
- * with `get-tree` rather than patch speculatively.
- */
-interface TreeDeltaMessage extends TreeDelta {
-    readonly type: 'tree-delta';
-}
 /**
  * adapter → driver, one application log record (capability `logs`).
  *
@@ -1366,18 +630,18 @@ interface LogMessage {
 /** either direction: terminal protocol error; sender closes after emitting. */
 interface ProtocolErrorMessage {
     readonly type: 'error';
-    readonly code: 'bad-token' | 'bad-version' | 'malformed' | 'limit-exceeded' | 'internal';
+    readonly code: 'bad-token' | 'bad-version' | 'malformed' | 'limit-exceeded' | 'duplicate-semantic-key' | 'adapter-guarantee-violation' | 'capability-provider-violation' | 'internal';
     readonly message: string;
 }
-type AdapterToDriverMessage = HelloMessage | RevisionCommitMessage | SnapshotMessage | GetTreeResponse | TreeDeltaMessage | FrameBeginMessage | LogMessage | ProtocolErrorMessage;
-type DriverToAdapterMessage = HelloAckMessage | GetTreeRequest | ProtocolErrorMessage;
+type AdapterToDriverMessage = HelloMessage | RevisionCommitMessage | SnapshotMessage | FrameBeginMessage | LogMessage | ProtocolErrorMessage;
+type DriverToAdapterMessage = HelloAckMessage | ProtocolErrorMessage;
 /** Outcome of parsing one wire message. Mirrors `ProtocolErrorMessage['code']`. */
 type MessageParseResult<T> = {
     readonly ok: true;
     readonly message: T;
 } | {
     readonly ok: false;
-    readonly code: 'bad-version' | 'malformed' | 'limit-exceeded';
+    readonly code: 'bad-version' | 'malformed' | 'limit-exceeded' | 'capability-provider-violation';
     readonly detail: string;
 };
 /**
@@ -1431,10 +695,12 @@ declare function parseDriverMessage(value: unknown, limits: ProtocolLimits): Mes
  *
  * ## Why OSC and not DCS
  *
- * ConPTY rewrites the stream it forwards. A passthrough probe run in CI across
- * the three platforms showed it dropping DCS, APC and OSC 8, while passing
+ * The legacy, frame-based inbox ConPTY rewrote the stream it forwarded. A
+ * permeability probe showed it dropping DCS, APC and OSC 8 while passing
  * private OSC with either terminator, and OSC 133. DCS therefore could not
- * carry a marker on Windows at all.
+ * carry a marker on the original Windows backend. The pinned passthrough
+ * ConPTY now forwards those families, but OSC 8487 remains the single encoding
+ * certified across every supported platform.
  *
  * One encoding is used everywhere rather than negotiating per platform: two
  * paths double the surface that has to stay correct, and the path used least
@@ -1509,6 +775,24 @@ declare function encodeMarker(token: string, sessionId: string, revision: number
  */
 declare function verifyMarkerPayload(payload: string, token: string, sessionId: string): RenderMarker | null;
 
+/** Private, request-addressed cursor synchronization used by Termwright's ConPTY host. */
+declare const CONPTY_HOST_CURSOR_OSC_CODE = 8488;
+/** Versioned payload prefix inside the host-reserved OSC 8488 namespace. */
+declare const CONPTY_HOST_CURSOR_PREFIX = "twh-cpr-v1";
+interface ConPtyHostCursorRequest {
+    readonly token: string;
+}
+interface ConPtyHostCursorResponse extends ConPtyHostCursorRequest {
+    readonly row: number;
+    readonly column: number;
+}
+/** Parses the payload delivered by an OSC 8488 handler, after `8488;`. */
+declare function parseConPtyHostCursorRequest(payload: string): ConPtyHostCursorRequest | null;
+/** Encodes the only reply the patched native host consumes. Coordinates are one-based. */
+declare function encodeConPtyHostCursorResponse(request: ConPtyHostCursorRequest, row: number, column: number): string;
+/** Strictly recognizes a complete host reply before the PTY chooses its input transport. */
+declare function parseConPtyHostCursorResponse(value: Uint8Array | string): ConPtyHostCursorResponse | null;
+
 /**
  * Wire framing: 4-byte big-endian unsigned length prefix + UTF-8 JSON body.
  * The length is checked against limits.maxFrameBytes BEFORE any decoding;
@@ -1562,4 +846,4 @@ declare function encodeFrame(message: unknown, maxFrameBytes: number): Uint8Arra
  */
 declare function projectDto<T>(value: unknown, maxDepth: number): T;
 
-export { ABSOLUTE_LIMITS, ACCESSKIT_ROLE_BY_SEMANTIC_ROLE, ACCESSKIT_ROOT_TREE_ID, ADAPTER_CAPABILITIES, type AccessKitExport, type AccessKitExportOptions, type AccessKitNode, type AccessKitRect, type AccessKitToggled, type AccessKitTree, type AccessKitTreeUpdate, type AdapterCapability, type AdapterToDriverMessage, type BoundsSource, type CapabilityAvailability, type CellPoint, type CoordinateSpace, type CursorInfo, DEFAULT_LIMITS, DEFAULT_NEGOTIATION_MS, type DeltaValidationResult, type DriverToAdapterMessage, ENV_ENDPOINT, ENV_PROTOCOL, ENV_TOKEN, FRAMEWORK_OBSERVATION_CAPABILITIES, FRAMEWORK_OPERATION_CAPABILITIES, FRAME_HEADER_BYTES, type FrameBeginMessage, type FrameDecoder, type FrameworkObservationCapabilities, type FrameworkOperationCapability, type GeometryOperation, type GetTreeRequest, type GetTreeResponse, type HelloAckMessage, type HelloMessage, LOG_LEVELS, LOG_LEVEL_SEVERITY, type LocatorGeometry, type LocatorVisibility, type LogAttrValue, type LogLevel, type LogMessage, type LogRecord, type LogValidationResult, MARKER_MAC_BYTES, MARKER_OSC_CODE, MARKER_OSC_PREFIX, MAX_LOG_ATTRS, type MessageParseResult, type NodeGeometryObservations, type Observation, type ObservationAbsentReason, type ObservationEvidence, type ObservationStamp, type ObservationUnknownReason, type ObservationUnsupportedReason, type OcclusionKnowledge, PROBE_CAPABILITIES, PROBE_UNOBSERVABLE_FIELDS, PROTOCOL_ID, PROTOCOL_V2_ID, PROTOCOL_VERSION, PROVENANCE_SOURCES, type PointerHitGrid, type PointerHitRegion, type PointerHitTest, type ProbeAccessibilityHints, type ProbeAnnotationValidationResult, type ProbeAnnotations, type ProbeCapability, type ProbeExtent, type ProbeFrame, type ProbeGeometry, type ProbeIdentity, type ProbeIdentityKind, type ProbeInfo, type ProbeObject, type ProbeObservedState, type ProbeOperation, type ProbeRect, type ProbeScroll, type ProbeUnobservableField, type ProbeValidationResult, type ProtocolErrorMessage, type ProtocolId, type ProtocolLimits, ProtocolViolation, type ProtocolViolationCode, type ProvenanceSource, type Rect, type RenderMarker, type ResolveBoundsOptions, type ResolvedBounds, type RevisionCommitMessage, SEMANTIC_ACTIONS, SEMANTIC_NODE_KEYS, SEMANTIC_ROLES, SEMANTIC_STATE_KEYS, SUPPORTED_PROTOCOL_IDS, type SemanticAction, type SemanticExtendedArray, type SemanticExtendedObject, type SemanticExtendedState, type SemanticExtendedValue, type SemanticNode, type SemanticRole, type SemanticSnapshot, type SemanticState, type SemanticTextRange, type SnapshotMessage, type SpatialRelation, TOKEN_BYTES, type TreeDelta, type TreeDeltaMessage, type ValidationErrorCode, type ValidationResult, type ViewportIntersection, accessKitNodeId, applyTreeDelta, createFrameDecoder, encodeFrame, encodeMarker, frameworkObservationCapabilities, generateToken, intersectRects, parseAdapterMessage, parseDriverMessage, probeInfoSchema, projectDto, rectArea, resolveNodeBounds, spatialRelation, toAccessKitTreeUpdate, validateLogRecord, validateProbeAnnotations, validateProbeFrame, validateProbeInfo, validateSnapshot, validateTreeDelta, verifyMarkerPayload, viewportIntersection };
+export { ABSOLUTE_LIMITS, ACCESSKIT_ROLE_BY_SEMANTIC_ROLE, ACCESSKIT_ROOT_TREE_ID, type AccessKitExport, type AccessKitExportOptions, type AccessKitNode, type AccessKitRect, type AccessKitToggled, type AccessKitTree, type AccessKitTreeUpdate, AdapterCapability, type AdapterToDriverMessage, CONPTY_HOST_CURSOR_OSC_CODE, CONPTY_HOST_CURSOR_PREFIX, type ConPtyHostCursorRequest, type ConPtyHostCursorResponse, DEFAULT_LIMITS, DEFAULT_NEGOTIATION_MS, type DriverToAdapterMessage, ENV_ENDPOINT, ENV_TOKEN, EvidenceProviderRegistration, FRAME_HEADER_BYTES, type FrameBeginMessage, type FrameDecoder, type HelloAckMessage, type HelloMessage, LOG_LEVELS, LOG_LEVEL_SEVERITY, type LogAttrValue, type LogLevel, type LogMessage, type LogRecord, type LogValidationResult, MARKER_MAC_BYTES, MARKER_OSC_CODE, MARKER_OSC_PREFIX, MAX_LOG_ATTRS, type MessageParseResult, PROTOCOL_ID, PROTOCOL_VERSION, type ProbeAnnotationValidationResult, ProbeAnnotations, ProbeFrame, ProbeInfo, type ProbeValidationResult, type ProtocolErrorMessage, type ProtocolId, type ProtocolLimits, ProtocolViolation, type ProtocolViolationCode, Rect, type RenderMarker, type RevisionCommitMessage, SEMANTIC_NODE_KEYS, SEMANTIC_STATE_KEYS, SemanticNode, SemanticRole, SemanticSnapshot, SemanticState, type SnapshotMessage, TOKEN_BYTES, type ValidationErrorCode, type ValidationResult, accessKitNodeId, createFrameDecoder, encodeConPtyHostCursorResponse, encodeFrame, encodeMarker, generateToken, parseAdapterMessage, parseConPtyHostCursorRequest, parseConPtyHostCursorResponse, parseDriverMessage, probeInfoSchema, projectDto, toAccessKitTreeUpdate, validateLogRecord, validateProbeAnnotations, validateProbeFrame, validateProbeInfo, validateSnapshot, verifyMarkerPayload };