@termwright/protocol 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,1565 @@
+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[];
+/** Entropy behind a session token, in bytes (256 bits). */
+declare const TOKEN_BYTES = 32;
+/**
+ * Mint a session token for `TERMWRIGHT_TOKEN`.
+ *
+ * **The token is an opaque UTF-8 string end to end.** Whatever lands in the
+ * env var is what both sides feed to the HMAC as the key — the driver must not
+ * decode it back to bytes, and an adapter must not re-encode it. Honouring
+ * that is what keeps non-JS clients (Python, Go, Rust) interoperable, since
+ * they only ever see the string.
+ *
+ * The encoding here (base64url, 43 characters) is therefore a convention, not
+ * a constraint: it is compact, shell-safe, and free of `=` padding.
+ *
+ * @returns A fresh 256-bit token. Never log or embed it; it authenticates the
+ * render markers.
+ */
+declare function generateToken(): string;
+
+/**
+ * Typed protocol failures. Everything in this package fails closed: a hostile
+ * or merely malformed input never produces a partially-trusted value, it
+ * produces a {@link ProtocolViolation} (imperative APIs) or a structured
+ * `{ ok: false }` result (validation APIs).
+ */
+/** Machine-readable reason a value was rejected. */
+type ProtocolViolationCode = 
+/** Declared frame length exceeds the negotiated ceiling. */
+'frame-oversized'
+/** Frame header/body is structurally impossible (zero length, bad JSON). */
+ | 'frame-malformed'
+/** Frame body is not well-formed UTF-8. */
+ | 'frame-encoding'
+/** Decoder already failed; it is poisoned and refuses further input. */
+ | 'decoder-poisoned'
+/** Value is not representable as JSON (undefined, bigint, function, NaN…). */
+ | 'dto-scalar'
+/** String contains unpaired surrogates. */
+ | 'dto-string'
+/** Object graph is not a tree: the same object is reachable twice. */
+ | 'dto-alias'
+/** Property is an accessor (getter/setter) rather than plain data. */
+ | 'dto-accessor'
+/** Value carries symbol keys. */
+ | 'dto-symbol'
+/** Value is a Proxy, or has a prototype other than Object/Array/null. */
+ | 'dto-prototype'
+/** Array has holes or extra own properties. */
+ | 'dto-sparse'
+/** Property name is reserved (`__proto__`, `constructor`, `prototype`). */
+ | 'dto-key'
+/** Nesting exceeds the permitted depth. */
+ | 'dto-depth'
+/** A marker argument is outside its permitted domain. */
+ | 'marker-argument';
+/**
+ * Thrown when untrusted input violates a protocol invariant.
+ *
+ * Never carries the offending value or the session token — only a code and a
+ * short structural description safe to log.
+ */
+declare class ProtocolViolation extends Error {
+    /** Machine-readable reason. */
+    readonly code: ProtocolViolationCode;
+    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.
+ */
+interface ProtocolLimits {
+    readonly maxFrameBytes: number;
+    /**
+     * Byte ceiling for one snapshot or probe frame.
+     *
+     * 2 MiB rather than 1: at the measured 217.5 B/node a full `maxNodes` tree
+     * is 1 062 KiB before a single provenance byte, so the old default
+     * contradicted the node ceiling it shipped with.
+     */
+    readonly maxSnapshotBytes: number;
+    readonly maxNodes: number;
+    readonly maxDepth: number;
+    readonly maxStringBytes: number;
+    readonly maxRelationTargets: number;
+    readonly maxQueuedFrames: number;
+    readonly maxPendingWaiters: number;
+    readonly maxSessions: number;
+    /** Byte ceiling for one serialised application log record. */
+    readonly maxLogRecordBytes: number;
+    /** Log records the driver buffers per session before evicting the oldest. */
+    readonly maxLogQueue: number;
+}
+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[];
+
+/**
+ * The field names of a semantic node and of its state, as data.
+ *
+ * These exist because a schema is invisible to anything that is not TypeScript.
+ * The cross-language vector generator and the client comparators cannot see a
+ * zod shape, so until now they carried hand-maintained field lists — and three
+ * fields (`frameworkType`, `occlusion`, `p`/`px`) reached three clients late
+ * precisely because nobody remembered to extend those lists. A generator that
+ * reads this array cannot forget a field the schema already has.
+ *
+ * Derived from the schema rather than written out, so there is one source of
+ * truth and not a third copy to drift. The list does not vary with limits: only
+ * the bounds inside the fields do.
+ */
+
+/**
+ * Every field name on `SemanticNode`.
+ *
+ * The `keyof` annotation is the load-bearing part: a field present in the
+ * 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'>)[];
+/** Every field name on `SemanticState`. */
+declare const SEMANTIC_STATE_KEYS: readonly (keyof SemanticState)[];
+
+/** Structured result: never throws hostile data onward. */
+type ValidationResult = {
+    readonly ok: true;
+    readonly snapshot: SemanticSnapshot;
+} | {
+    readonly ok: false;
+    readonly code: ValidationErrorCode;
+    readonly detail: string;
+};
+type ValidationErrorCode = 'schema' | 'unknown-role' | 'duplicate-id' | 'missing-parent' | 'cycle' | 'depth' | 'count' | 'string-bytes' | 'bad-rect' | 'revision' | 'bytes';
+/**
+ * Full snapshot validation per spec §8.2: unique ids, existing+acyclic parent
+ * relations, dense bounded arrays, Unicode scalar strings within byte bounds,
+ * safe-integer rects intersecting the viewport unless state.hidden, strictly
+ * increasing revisions (checked by caller against session state), deep
+ * immutability of the returned value.
+ *
+ * The value is first projected with {@link projectDto}, so getters on hostile
+ * input are rejected without being invoked and the returned snapshot is a
+ * deep-frozen plain copy that shares no references with the input.
+ *
+ * @param value - Untrusted candidate snapshot.
+ * @param limits - Active limits; callers may tighten but never widen these.
+ * @returns `{ ok: true, snapshot }` with a deep-frozen snapshot, or
+ * `{ ok: false, code, detail }`. Never throws.
+ */
+declare function validateSnapshot(value: unknown, limits: ProtocolLimits): ValidationResult;
+
+/**
+ * Application log records carried over the semantic channel.
+ *
+ * A TUI cannot print diagnostics to the screen without corrupting the render,
+ * so applications write them to an internal logger instead. The `logs`
+ * capability lets an instrumented adapter forward those records to the driver,
+ * where they become assertable test state rather than invisible side effects.
+ *
+ * Records are bounded exactly like snapshots: projected into frozen plain DTOs
+ * before retention, checked against a byte ceiling, and rejected wholesale on
+ * any violation. A misbehaving logger degrades into dropped records, never
+ * into unbounded driver memory.
+ */
+
+/**
+ * Severity ladder, ordered from least to most severe. Deliberately the
+ * intersection of the ladders used by pino, winston, consola, Python
+ * `logging`, Go `slog` and Rust `tracing`, so every bridge maps onto it
+ * without inventing a level.
+ */
+declare const LOG_LEVELS: readonly ["trace", "debug", "info", "warn", "error", "fatal"];
+type LogLevel = (typeof LOG_LEVELS)[number];
+/** Numeric severity, useful for threshold comparisons. Higher is more severe. */
+declare const LOG_LEVEL_SEVERITY: Readonly<Record<LogLevel, number>>;
+/**
+ * Structured attribute value. Scalars only, by design: nested objects make
+ * record size unbounded and depth-dependent, and every bridge already has to
+ * flatten for its own transport. `@termwright/logs` does the flattening.
+ */
+type LogAttrValue = string | number | boolean | null;
+/** Maximum number of attribute keys on one record. */
+declare const MAX_LOG_ATTRS = 64;
+/**
+ * One application log record.
+ *
+ * @remarks
+ * `ts` is **Unix epoch milliseconds**, not session-relative: the adapter has no
+ * reliable view of when the driver considers the session to have started, so
+ * the only clock both sides can agree on without negotiation is the wall
+ * clock. The driver rebases it onto the session/cast timeline.
+ */
+interface LogRecord {
+    /** Unix epoch milliseconds when the record was produced. */
+    readonly ts: number;
+    readonly level: LogLevel;
+    /** Human-readable message, already formatted by the source logger. */
+    readonly message: string;
+    /** Flat structured context. Nested values are flattened by the bridge. */
+    readonly attrs?: Readonly<Record<string, LogAttrValue>>;
+    /** Logger/channel name, e.g. `http` or `db.pool`. */
+    readonly logger?: string;
+    /**
+     * Per-session counter assigned by the adapter, **strictly increasing**: every
+     * record carries a `seq` greater than the previous one on the same session.
+     *
+     * The two failure modes are distinguishable on purpose:
+     * - a **gap upward** means records were dropped at the source (rate limit,
+     *   queue overflow) rather than lost in transit, and is expected under load;
+     * - a **duplicate or a decrease** means the sender is broken, so the receiver
+     *   rejects that record and emits a diagnostic instead of retaining it.
+     *
+     * This is a rule *between* records, not about the shape of one, so
+     * {@link validateLogRecord} cannot enforce it — it only checks that `seq` is
+     * a non-negative safe integer. Ordering is enforced by the driver, which is
+     * the only party that sees the whole session.
+     */
+    readonly seq: number;
+    /** Semantic revision current when the record was produced, when known. */
+    readonly revision?: number;
+}
+/** Structured result: never throws hostile data onward. */
+type LogValidationResult = {
+    readonly ok: true;
+    readonly record: LogRecord;
+} | {
+    readonly ok: false;
+    readonly code: ValidationErrorCode;
+    readonly detail: string;
+};
+/**
+ * Validate an untrusted log record.
+ *
+ * Mirrors {@link import('./validate.js').validateSnapshot}: the value is
+ * projected into a frozen plain DTO first (so getters are rejected without
+ * being invoked), then measured against the byte ceiling, then checked field
+ * by field.
+ *
+ * @param value - Untrusted candidate record.
+ * @param limits - Active limits; `maxLogRecordBytes` and `maxStringBytes` apply.
+ * @returns `{ ok: true, record }` with a deep-frozen record, or a typed
+ * failure. Never throws.
+ */
+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`.
+ *
+ * A pure transformation into AccessKit's serde JSON shape. This module takes
+ * **no dependency** on AccessKit — the protocol package depends on `zod` only —
+ * so the output is data a bridge can hand to a real adapter, not a binding.
+ *
+ * ## Why there is no native bridge in 1.0
+ *
+ * AccessKit's platform adapters attach an accessibility tree to a **native
+ * window**: an `NSView` on macOS, an `HWND` on Windows, a toplevel on AT-SPI.
+ * A terminal application has none of those. The terminal emulator owns the
+ * window, and the application under test is a child process writing bytes to a
+ * pseudo-terminal. There is nothing for an adapter to attach to, and nothing an
+ * assistive technology could route back to us.
+ *
+ * The geometry gap is the same problem seen from the other side. Our `bounds`
+ * are **terminal cells** — row 3, column 12 — while AccessKit's `Rect` is in
+ * physical pixels relative to the window origin. Converting requires the cell
+ * size and window position, which live in the emulator, not in the process
+ * being tested. Guessing a cell size would produce coordinates that look
+ * authoritative and point nowhere.
+ *
+ * So the export is *bridge-ready*, not a bridge: it is the half of the problem
+ * that can be solved correctly without a window. An embedder that does own one
+ * (a GUI terminal emulator embedding termwright) can supply {@link
+ * AccessKitExportOptions.cellSize} and get real geometry.
+ *
+ * ## Schema provenance
+ *
+ * Shapes verified against `accesskit` 0.24.1 (docs.rs, August 2026):
+ * `TreeUpdate { nodes, tree, tree_id, focus }`, `Tree { root, toolkit_name,
+ * toolkit_version }`, `NodeId(u64)`, `Rect { x0, y0, x1, y1 }`, and
+ * `#[serde(rename_all = "camelCase")]` on `Role`, `Action` and `Node`.
+ * `TreeId` is a UUID, with the nil UUID reserved for the root tree.
+ */
+
+/** The nil UUID, which AccessKit reserves for the root tree (`TreeId::ROOT`). */
+declare const ACCESSKIT_ROOT_TREE_ID = "00000000-0000-0000-0000-000000000000";
+/** AccessKit's `Rect`: minimum and maximum coordinates, not origin plus size. */
+interface AccessKitRect {
+    readonly x0: number;
+    readonly y0: number;
+    readonly x1: number;
+    readonly y1: number;
+}
+/** AccessKit's `Toggled`, used for tri-state checkboxes. */
+type AccessKitToggled = 'false' | 'true' | 'mixed';
+/**
+ * An AccessKit `Node` in its serde JSON form. Only the properties this export
+ * can populate faithfully are modelled.
+ */
+interface AccessKitNode {
+    readonly role: string;
+    readonly label?: string;
+    readonly description?: string;
+    readonly value?: string;
+    readonly children?: readonly number[];
+    readonly bounds?: AccessKitRect;
+    readonly actions?: readonly string[];
+    readonly labelledBy?: readonly number[];
+    readonly describedBy?: readonly number[];
+    readonly disabled?: boolean;
+    readonly selected?: boolean;
+    readonly expanded?: boolean;
+    readonly busy?: boolean;
+    readonly modal?: boolean;
+    readonly hidden?: boolean;
+    readonly readOnly?: boolean;
+    readonly toggled?: AccessKitToggled;
+}
+/** AccessKit's `Tree`. */
+interface AccessKitTree {
+    readonly root: number;
+    readonly toolkitName?: string;
+    readonly toolkitVersion?: string;
+}
+/** AccessKit's `TreeUpdate`. */
+interface AccessKitTreeUpdate {
+    readonly nodes: readonly (readonly [number, AccessKitNode])[];
+    readonly tree?: AccessKitTree;
+    readonly treeId: string;
+    readonly focus: number;
+}
+/** Settings for {@link toAccessKitTreeUpdate}. */
+interface AccessKitExportOptions {
+    /** Tree identity; defaults to the nil UUID AccessKit reserves for the root. */
+    readonly treeId?: string;
+    readonly toolkitName?: string;
+    readonly toolkitVersion?: string;
+    /**
+     * Pixel size of one terminal cell. Supply it only if you genuinely know it —
+     * an embedder that owns the window does; a headless test run does not.
+     * Without it `bounds` is omitted and cell rects are reported separately.
+     */
+    readonly cellSize?: {
+        readonly width: number;
+        readonly height: number;
+    };
+}
+/** The export, plus the cell geometry AccessKit has nowhere to put. */
+interface AccessKitExport {
+    readonly update: AccessKitTreeUpdate;
+    /**
+     * Cell-space rects keyed by AccessKit node id, for every node that had
+     * `bounds`. AccessKit's `Node` has no extension point for foreign
+     * coordinates, so carrying them alongside is the honest option: a consumer
+     * that understands terminal cells can use them, and one that does not is
+     * not misled by pixel coordinates that were never measured.
+     */
+    readonly cellBounds: Readonly<Record<string, Rect>>;
+}
+/**
+ * ARIA-aligned protocol roles to AccessKit roles.
+ *
+ * Every target is a real `accesskit::Role` variant in its camelCase serde
+ * spelling. `textbox` is resolved per node rather than here, because a
+ * multiline textbox maps to a different AccessKit role.
+ */
+declare const ACCESSKIT_ROLE_BY_SEMANTIC_ROLE: Readonly<Record<SemanticRole, string>>;
+/**
+ * Map a protocol node id (a string) onto an AccessKit node id (a number).
+ *
+ * Stable across processes and languages: SHA-256 of the UTF-8 id, truncated to
+ * 53 bits. At the protocol's 5 000-node ceiling the collision probability is
+ * about 1.4e-9, and {@link toAccessKitTreeUpdate} detects a collision rather
+ * than silently merging two nodes.
+ *
+ * @param id - Protocol node id.
+ */
+declare function accessKitNodeId(id: string): number;
+/**
+ * Convert a validated semantic snapshot into an AccessKit `TreeUpdate`.
+ *
+ * Two structural differences from our model are worth knowing:
+ *
+ * - **Focus is a tree-level property.** AccessKit puts `focus` on the
+ *   `TreeUpdate`, not on a node, so the node carrying `state.focused` becomes
+ *   the update's focus. If no node claims focus, the root does.
+ * - **Children are explicit.** Our tree is a flat list joined by `parentId`;
+ *   AccessKit nodes carry a `children` array, which is derived here in the
+ *   snapshot's node order.
+ *
+ * @param snapshot - A snapshot that already passed `validateSnapshot`.
+ * @param options - Tree identity, toolkit metadata and optional cell geometry.
+ * @throws {ProtocolViolation} If two node ids collide in the 53-bit id space.
+ */
+declare function toAccessKitTreeUpdate(snapshot: SemanticSnapshot, options?: AccessKitExportOptions): AccessKitExport;
+
+/**
+ * Validation for Probe IR frames.
+ *
+ * Same discipline as the semantic tree: project into a frozen plain DTO first
+ * so a getter on hostile input is rejected without running, then measure
+ * against the byte ceiling, then check the shape. A probe runs inside the
+ * process under test, which may be broken or malicious, so this is a hostile
+ * boundary in exactly the way the adapter channel is.
+ */
+
+/** Structured result: never throws hostile data onward. */
+type ProbeValidationResult = {
+    readonly ok: true;
+    readonly frame: ProbeFrame;
+} | {
+    readonly ok: false;
+    readonly code: ValidationErrorCode;
+    readonly detail: string;
+};
+/** Result of validating one optional-SDK annotation at the probe boundary. */
+type ProbeAnnotationValidationResult = {
+    readonly ok: true;
+    readonly annotations: ProbeAnnotations;
+} | {
+    readonly ok: false;
+    readonly code: ValidationErrorCode;
+    readonly detail: string;
+};
+/** Schema for the handshake block a probe sends about itself. */
+declare const probeInfoSchema: z.ZodObject<{
+    framework: z.ZodString;
+    frameworkVersion: z.ZodOptional<z.ZodString>;
+    probeVersion: z.ZodString;
+    identityKind: z.ZodEnum<{
+        stable: "stable";
+        "frame-local": "frame-local";
+    }>;
+    capabilities: z.ZodArray<z.ZodEnum<{
+        "stable-identity": "stable-identity";
+        "visible-rect": "visible-rect";
+        operations: "operations";
+        annotations: "annotations";
+        "frame-begin": "frame-begin";
+        "paint-order": "paint-order";
+    }>>;
+}, z.core.$strict>;
+/**
+ * Validate a probe's self-description.
+ *
+ * Enforces the one consistency rule the pair has: a probe may not claim the
+ * `stable-identity` capability while declaring `identityKind: 'frame-local'`.
+ * Those two together would tell a consumer it is safe to correlate objects
+ * across frames in a framework where nothing survives the frame.
+ */
+declare function validateProbeInfo(value: unknown): {
+    readonly ok: true;
+    readonly info: ProbeInfo;
+} | {
+    readonly ok: false;
+    readonly detail: string;
+};
+/**
+ * Validate an untrusted probe frame.
+ *
+ * Beyond the shape, three cross-object rules are checked, each of them a way an
+ * IR frame can be internally inconsistent rather than merely malformed:
+ * identities must be unique within the frame, a declared parent must exist in
+ * the same frame, and a field cannot be both reported and declared
+ * unobservable.
+ *
+ * @param value - Untrusted candidate frame.
+ * @param limits - Active limits; `maxNodes`, `maxStringBytes` and
+ * `maxSnapshotBytes` apply.
+ * @returns `{ ok: true, frame }` deep-frozen, or a typed failure. Never throws.
+ */
+declare function validateProbeFrame(value: unknown, limits: ProtocolLimits): ProbeValidationResult;
+/**
+ * Validate one developer annotation before adding it to an otherwise trusted
+ * framework observation.
+ *
+ * Annotation registries intentionally use `Symbol.for` so an optional SDK and
+ * an injected probe can meet without importing one another. That also makes
+ * the registry a hostile boundary: application code can forge an entry with a
+ * getter, cycle, oversized value or unknown action. Reusing the complete frame
+ * validator here keeps both boundaries byte-for-byte consistent. Callers can
+ * then omit only the bad annotation instead of losing the framework frame or
+ * closing the probe channel.
+ */
+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';
+    readonly protocol: ProtocolId;
+    readonly token: string;
+    readonly adapter: {
+        readonly name: string;
+        readonly version: string;
+    };
+    readonly capabilities: readonly AdapterCapability[];
+    /**
+     * Present when the sender is a probe rather than a hand-written adapter.
+     *
+     * Carries what the probe can actually offer — framework and versions, the
+     * best identity it can produce, and its optional abilities — so the driver
+     * negotiates against measured capability rather than assuming a floor.
+     */
+    readonly probe?: ProbeInfo;
+}
+/** driver → adapter, reply to hello. */
+interface HelloAckMessage {
+    readonly type: 'hello-ack';
+    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';
+    /** Marker configuration: producer must emit the signed OSC 8487 commit marker. */
+    readonly marker: {
+        readonly enabled: boolean;
+    };
+    /**
+     * Log-channel budget, sent only when the adapter announced the `logs`
+     * capability. **Absent means logs are disabled** — an adapter that receives
+     * no `logs` field must not emit `log` messages at all.
+     *
+     * The adapter enforces the rate itself and drops locally when over budget,
+     * leaving a gap in `LogRecord.seq` so the driver can report how many records
+     * were lost. Enforcing it at the source is what keeps a log storm from
+     * consuming the frame budget the semantic tree needs.
+     */
+    readonly logs?: {
+        readonly enabled: boolean;
+        /** Sustained ceiling on records per second. */
+        readonly maxRecordsPerSecond: number;
+        /** Records allowed in a burst on top of the sustained rate. */
+        readonly burst: number;
+    };
+}
+/** adapter → driver after each committed render (always, regardless of mode). */
+interface RevisionCommitMessage {
+    readonly type: 'revision-commit';
+    readonly revision: number;
+}
+/** adapter → driver, full snapshot for a revision (subscribe: 'snapshots'). */
+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`).
+ *
+ * **Optional, and its absence means nothing.** 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; one decouples submission from the flush with a ticker. A
+ * receiver that reads "no frame-begin" as "no frame in progress" turns four of
+ * the six frameworks into a hang rather than an error.
+ *
+ * `FRAME_END` is the existing `revision-commit`, which stays advisory.
+ *
+ * **Abandoned frames**: a probe may begin a frame and never finish it — a
+ * crash, an interrupted render. A `frame-begin` for revision N implicitly
+ * closes every frame below N. Without that rule an open frame waits forever,
+ * which is the timeout it replaced, only now wearing a false air of precision.
+ */
+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`).
+ *
+ * Sent only after the driver enabled logs in `hello-ack`. Records are
+ * independent of renders: they are not paired with a revision and never gate
+ * snapshot publication.
+ */
+interface LogMessage {
+    readonly type: 'log';
+    readonly record: LogRecord;
+}
+/** 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 message: string;
+}
+type AdapterToDriverMessage = HelloMessage | RevisionCommitMessage | SnapshotMessage | GetTreeResponse | TreeDeltaMessage | FrameBeginMessage | LogMessage | ProtocolErrorMessage;
+type DriverToAdapterMessage = HelloAckMessage | GetTreeRequest | 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 detail: string;
+};
+/**
+ * Parse and validate one adapter → driver message.
+ *
+ * **Strict reader**: this is the hostile-input boundary, so unknown fields are
+ * rejected rather than ignored. See {@link parseDriverMessage} for why the
+ * other direction is tolerant.
+ *
+ * @param value - Untrusted decoded frame body.
+ * @param limits - Active session limits, applied to any embedded snapshot.
+ * @returns A frozen message on success, or a typed failure. Never throws.
+ */
+declare function parseAdapterMessage(value: unknown, limits: ProtocolLimits): MessageParseResult<AdapterToDriverMessage>;
+/**
+ * Parse and validate one driver → adapter message.
+ *
+ * **Tolerant reader.** Unlike {@link parseAdapterMessage}, unknown envelope
+ * fields are ignored rather than rejected, and are carried through to the
+ * caller so a reader that does understand them still can. Known fields stay
+ * strictly type-checked, and closed sets (`type`, `code`, `subscribe`) stay
+ * closed — an unknown message type is still `malformed`.
+ *
+ * The asymmetry is about who is speaking, not about the message. The driver is
+ * the trusted party and behaviour is governed by negotiated capabilities, so a
+ * newer driver may add an optional field without invalidating every adapter
+ * already published. Traffic in the other direction crosses the hostile-input
+ * boundary and stays strict.
+ *
+ * @param value - Decoded frame body from the driver.
+ * @param limits - Active session limits used for the projection depth bound.
+ * @returns A frozen message on success, or a typed failure. Never throws.
+ */
+declare function parseDriverMessage(value: unknown, limits: ProtocolLimits): MessageParseResult<DriverToAdapterMessage>;
+
+/**
+ * Render-commit marker: emitted by the adapter into the PTY stdout AFTER the
+ * last byte of the render belonging to revision N. It is a frame COMMIT
+ * signal (Neovim `flush` semantics), never a data carrier.
+ *
+ * Encoding: a private OSC sequence terminated by BEL:
+ *
+ *   OSC 8487 ; 'twm;' <revision> ';' <mac> BEL
+ *   i.e. `\x1b]8487;twm;{rev};{mac}\x07`
+ *
+ * where mac = base64url(HMAC-SHA256(token, `${sessionId}:${revision}`))
+ * truncated to 16 bytes. The driver's VT layer registers an OSC handler,
+ * verifies the MAC, and removes the sequence from the visible grid. Ordinary
+ * application output cannot forge it. Emitted only after a successful
+ * handshake; never during a normal (non-instrumented) run.
+ *
+ * ## 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
+ * private OSC with either terminator, and OSC 133. DCS therefore could not
+ * carry a marker on Windows at all.
+ *
+ * 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
+ * is the one that rots unnoticed. BEL is emitted rather than ST because it is
+ * the terminator ConPTY was observed to forward most reliably; receivers
+ * accept both, since a VT parser consumes the terminator before dispatching
+ * anyway.
+ *
+ * ## Why 8487
+ *
+ * OSC numbers have no registry, only convention, so the number is chosen to
+ * sit clear of everything in use: xterm's allocations (0–14, 46, 50, 52, 104,
+ * 110–119), OSC 8 hyperlinks, 9 and 1337 (iTerm2), 99 and 30001 (kitty), 133
+ * (FinalTerm shell integration — also the sequence ConPTY is known to
+ * forward), 633 (VS Code), 697 (ConEmu) and 777–779 (urxvt/VTE). 8487 is the
+ * ASCII codes of `T` and `W` — termwright — and appears in none of them.
+ *
+ * The `twm;` tag after the number is kept as a self-identifying guard: if
+ * anything ever does claim 8487, a marker still says what it is instead of
+ * being mistaken for that other feature's payload.
+ */
+/** The private OSC number carrying render-commit markers. */
+declare const MARKER_OSC_CODE = 8487;
+/**
+ * The tag opening a marker payload, immediately after `OSC 8487;`.
+ *
+ * A VT parser hands an OSC handler everything after the number and its
+ * separator, which is exactly what {@link verifyMarkerPayload} expects:
+ *
+ * ```ts
+ * term.parser.registerOscHandler(MARKER_OSC_CODE, (data) => {
+ *   const marker = verifyMarkerPayload(data, token, sessionId);
+ *   if (marker !== null) commit(marker.revision);
+ *   return true; // consumed: keeps the sequence out of the visible grid
+ * });
+ * ```
+ */
+declare const MARKER_OSC_PREFIX = "twm;";
+/** Bytes of HMAC-SHA256 output retained in the marker MAC. */
+declare const MARKER_MAC_BYTES = 16;
+interface RenderMarker {
+    readonly revision: number;
+    readonly mac: string;
+}
+/**
+ * Build the full escape sequence for a marker.
+ *
+ * @param token - Per-launch session token (`TERMWRIGHT_TOKEN`); used as the
+ * HMAC key and never appears in the emitted bytes.
+ * @param sessionId - Session id from the handshake, bound into the MAC so a
+ * marker from one session cannot be replayed into another.
+ * @param revision - Positive safe integer identifying the committed render.
+ * @returns The complete `OSC … BEL` sequence to write to stdout.
+ * @throws {ProtocolViolation} If the revision is not a positive safe integer,
+ * or the token/sessionId are empty.
+ */
+declare function encodeMarker(token: string, sessionId: string, revision: number): string;
+/**
+ * Parse+verify an OSC payload (the part after `OSC 8487;`). Returns null on any mismatch.
+ *
+ * Total function: hostile payloads yield `null`, never an exception. The MAC
+ * comparison is constant-time, and only canonically-formatted revisions are
+ * accepted so `1` and `01` cannot both authenticate the same commit.
+ *
+ * A trailing BEL or ST is tolerated. A VT parser consumes the terminator
+ * before dispatching, so a handler normally passes a payload without one,
+ * while a caller scanning raw output with a regex may keep it — both must work.
+ *
+ * @param payload - Everything after `OSC 8487;`, i.e. `twm;{rev};{mac}`.
+ * @param token - Per-launch session token used as the HMAC key.
+ * @param sessionId - Session id the marker must be bound to.
+ */
+declare function verifyMarkerPayload(payload: string, token: string, sessionId: string): RenderMarker | null;
+
+/**
+ * Wire framing: 4-byte big-endian unsigned length prefix + UTF-8 JSON body.
+ * The length is checked against limits.maxFrameBytes BEFORE any decoding;
+ * oversized, partial or duplicated frames fail closed with a typed error.
+ * Decoded values MUST be projected into immutable plain DTOs (no accessors,
+ * proxies, symbols, functions, non-plain prototypes) before retention.
+ */
+interface FrameDecoder {
+    /** Feed raw bytes; returns fully decoded, validated, frozen messages. */
+    push(chunk: Uint8Array): readonly unknown[];
+    /** Bytes currently buffered (bounded by maxFrameBytes + 4). */
+    readonly buffered: number;
+}
+/** Size of the big-endian length prefix that precedes every frame body. */
+declare const FRAME_HEADER_BYTES = 4;
+/**
+ * Create a streaming decoder for length-prefixed JSON frames.
+ *
+ * A frame whose declared length exceeds `maxFrameBytes` is rejected before its
+ * body is read. Any violation poisons the decoder permanently: subsequent
+ * `push` calls throw rather than resynchronising on attacker-chosen offsets.
+ *
+ * @param maxFrameBytes - Per-frame byte ceiling; must be a positive safe integer.
+ * @throws {ProtocolViolation} On an invalid ceiling, or (from `push`) on any
+ * oversized, malformed, non-UTF-8 or non-projectable frame.
+ */
+declare function createFrameDecoder(maxFrameBytes: number): FrameDecoder;
+/**
+ * Serialise a message into a single length-prefixed frame.
+ *
+ * @param message - A JSON-representable value.
+ * @param maxFrameBytes - Per-frame byte ceiling applied to the encoded body.
+ * @returns Header + UTF-8 JSON body, ready to write to the transport.
+ * @throws {ProtocolViolation} If the value is not JSON-representable or the
+ * encoded body exceeds `maxFrameBytes`.
+ */
+declare function encodeFrame(message: unknown, maxFrameBytes: number): Uint8Array;
+/**
+ * Deep-project an untrusted parsed value into a frozen, plain, JSON-safe DTO.
+ * Throws ProtocolViolation on aliases, cycles, sparse arrays, accessors,
+ * non-JSON scalars, or depth/size beyond limits.
+ *
+ * Properties are inspected with `Object.getOwnPropertyDescriptor`, so a getter
+ * on hostile input is detected and rejected without ever being invoked.
+ *
+ * @param value - Untrusted input, typically the result of `JSON.parse`.
+ * @param maxDepth - Maximum nesting depth; the root sits at depth 0.
+ * @returns A structurally identical, deep-frozen copy. The `T` type parameter
+ * is an unchecked assertion — validate the shape separately.
+ * @throws {ProtocolViolation}
+ */
+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 };