termwright 0.2.0__tar.gz → 0.3.0__tar.gz

{termwright-0.2.0 → termwright-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: termwright
-Version: 0.2.0
+Version: 0.3.0
 Summary: Semantic side-channel client, automatic Textual probe, and annotation SDK for Termwright
 Project-URL: Homepage, https://github.com/gorce-ai/termwright
 Project-URL: Source, https://github.com/gorce-ai/termwright/tree/main/clients/python
@@ -17,9 +17,9 @@ Requires-Python: >=3.9
 Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
 Requires-Dist: pytest>=7; extra == 'dev'
-Requires-Dist: textual>=0.60; extra == 'dev'
+Requires-Dist: textual>=8.2.8; extra == 'dev'
 Provides-Extra: textual
-Requires-Dist: textual>=0.60; extra == 'textual'
+Requires-Dist: textual>=8.2.8; extra == 'textual'
 Description-Content-Type: text/markdown
 
 # termwright (Python)
@@ -28,8 +28,12 @@ Semantic side-channel client, automatic probe and optional annotation SDK for
 [Textual](https://textual.textualize.io).
 
 An instrumented app publishes its widget tree over a unix socket and commits
-each render with a signed OSC marker, so the driver can assert on *roles and
-names* instead of screen-scraping cells.
+each render with a signed OSC marker, so the driver can assert on _roles and
+names_ instead of screen-scraping cells.
+
+The protocol client speaks `termwright/2`. Every published semantic revision
+is a complete v2 snapshot with evidence-qualified geometry and pointer
+observations.
 
 **Dormant rule.** Without `TERMWRIGHT_ENDPOINT` and `TERMWRIGHT_TOKEN` the
 probe installs nothing, opens no socket, writes no marker, and renders exactly
@@ -42,7 +46,10 @@ pip install termwright              # protocol client + probe + annotation SDK
 pip install "termwright[textual]"   # + Textual itself
 ```
 
-Requires Python 3.9+. The protocol modules have no third-party dependencies.
+Requires Python 3.9+. The Textual extra accepts Textual 8.2.8 or newer as an
+advisory packaging floor. Runtime capability checks and behavioral
+conformance, not the version string, decide whether strong semantics engage;
+the protocol modules have no third-party dependencies.
 
 ## Automatic Textual semantics
 
@@ -70,15 +77,15 @@ useful for a custom runner, is:
 python -m termwright_probe -- python app.py
 ```
 
-Under the driver this publishes, after every flushed frame:
+Under the driver this publishes after every causally ordered frame enqueue:
 
 ```
 application "PermissionApp"
-  region                          bounds=(0,0,80,24)
-    text "Allow bash to run?"     bounds=(0,0,80,1)  testId=prompt
-    button "Approve"              bounds=(1,0,80,3)  testId=approve  [focused]
-    button "Reject"               bounds=(4,0,80,3)  testId=reject
-    textbox "Reason"              bounds=(7,0,80,3)  testId=reason
+  region                          visibleRect=(0,0,80,24)
+    text "Allow bash to run?"     visibleRect=(0,0,80,1)  testId=prompt
+    button "Approve"              visibleRect=(1,0,80,3)  testId=approve  [focused]
+    button "Reject"               visibleRect=(4,0,80,3)  testId=reject
+    textbox "Reason"              visibleRect=(7,0,80,3)  testId=reason
 ```
 
 ### Roles and names
@@ -131,7 +138,7 @@ recreate. `actions` uses the protocol's closed descriptive vocabulary; it never
 registers an out-of-band callback, and interaction still becomes real PTY
 input.
 
-The API intentionally has no bounds, focus, visibility, rendered-text or
+The API intentionally has no geometry, focus, visibility, rendered-text or
 portable-state arguments. Those physical facts remain probe-owned, and merge
 tests enforce that the annotation cannot replace them.
 
@@ -147,7 +154,22 @@ Any TUI can drive the client directly. You own the render; the client owns the
 revision numbers and hands you the marker to write after the render's last byte.
 
 ```python
-from termwright import SemanticNode, SemanticSnapshot, Rect, client_from_env
+from termwright import (
+    NodeGeometryObservations,
+    Observation,
+    Rect,
+    SemanticNode,
+    SemanticSnapshot,
+    client_from_env,
+    framework_evidence,
+)
+
+def geometry(rect: Rect) -> NodeGeometryObservations:
+    return NodeGeometryObservations(
+        displayed=Observation("known", True, evidence=framework_evidence("my-adapter")),
+        intendedRect=Observation("known", rect, evidence=framework_evidence("my-adapter")),
+        visibleRect=Observation("known", rect, evidence=framework_evidence("my-adapter")),
+    )
 
 client = client_from_env(adapter_name="my-tui", adapter_version="1.0.0")
 if client is not None and await client.start():
@@ -156,10 +178,14 @@ if client is not None and await client.start():
             sessionId="", revision=0, columns=80, rows=24,   # both are overwritten
             rootIds=["root"],
             nodes=[
-                SemanticNode(id="root", role="dialog", name="Permission"),
+                SemanticNode(id="root", role="dialog", name="Permission",
+                             geometry=geometry(Rect(0, 0, 80, 24))),
                 SemanticNode(id="ok", parentId="root", role="button", name="Approve",
-                             bounds=Rect(row=1, column=2, width=9, height=1)),
+                             geometry=geometry(Rect(row=1, column=2, width=9, height=1))),
             ],
+            coordinateSpace=Observation("known", "viewport-cells", evidence=framework_evidence("my-adapter")),
+            hitGrid=Observation("unsupported", capability="pointer-hit-grid",
+                                reason="framework-unobservable"),
         )
     )
     sys.stdout.write(marker)   # only after the render is fully written
@@ -208,8 +234,8 @@ or, on a session that came up:
 
 ```text
   tw:sem  [p41207]   0.002s dial unix:/tmp/tw-8f21/s timeout=5000ms
-  tw:sem  [p41207]   0.003s hello sent adapter=textual/1.0.0 caps=tree,bounds,…
-  tw:sem  [3f9c1a04]  0.011s hello-ack session=3f9c1a04… marker=on subscribe=diffs logs=off
+  tw:sem  [p41207]   0.003s hello sent adapter=textual/1.0.0 caps=tree,states,actions,render-revisions,intended-geometry,clipped-geometry,pointer-hit-grid
+  tw:sem  [3f9c1a04]  0.011s hello-ack session=3f9c1a04… marker=on subscribe=snapshots logs=off
   tw:io   [3f9c1a04]  0.048s r1 snapshot nodes=17
 ```
 
@@ -241,8 +267,16 @@ python -m termwright_probe -- python app.py
 `app.py` imports no termwright, calls nothing of ours, and is not edited. The
 launcher puts a generated `sitecustomize.py` on `PYTHONPATH`; CPython imports
 it during startup, before the script's own directory reaches `sys.path`; the
-probe waits there until the application imports Textual and attaches to
-`App.post_display_hook`. A driver that already sets `TERMWRIGHT_ENDPOINT` and
+probe waits there until the application imports Textual and observes the
+capability-checked `App._display` / driver enqueue / `post_display_hook`
+boundary. The
+marker is appended without waiting to the same WriterThread FIFO, after the
+frame; a full queue fails the semantic channel instead of blocking Textual's
+event loop. No Textual version is allowlisted. Strong probing accepts only a
+live built-in `LinuxDriver` or `WindowsDriver` whose concrete WriterThread and
+bounded FIFO pass the runtime checks; custom
+`driver_class` values and inline mode fail the semantic channel explicitly
+rather than publishing an unprovable commit. A driver that already sets `TERMWRIGHT_ENDPOINT` and
 `TERMWRIGHT_TOKEN` can compose the same thing itself:
 
 ```python
@@ -265,21 +299,22 @@ the claim that the probe observes rather than redraws.
 
 **What it reports automatically.**
 
-| Fact | Where it comes from |
-|---|---|
-| `bounds` = what is on screen | `MapGeometry.visible_region`, Textual's `clip ∩ region` |
-| `occlusion: "known"` | widgets ranked by `MapGeometry.order`, the compositor's own sort key |
-| roles for your own widget classes | the MRO, so `SaveButton(Button)` is a button with no registration |
-| `frameworkType` on anything unrecognised | the widget's class name |
+| Fact                                      | Where it comes from                                                    |
+| ----------------------------------------- | ---------------------------------------------------------------------- |
+| intended and visible rectangles           | `MapGeometry.region` and `MapGeometry.visible_region`                  |
+| exact pointer recipient                   | `Screen.get_widget_at`, compressed into the snapshot hit grid          |
+| roles for your own widget classes         | the MRO, so `SaveButton(Button)` is a button with no registration      |
+| `frameworkType` on anything unrecognised  | the widget's class name                                                |
 | scrolled out of view vs `display = False` | both `hidden`; the first also `state.offscreen`, with a zero-area rect |
 
-Because paint order is real here, the driver allows pointer actions against
-Textual nodes; it refuses them for producers that cannot say whether a node's
-cells are covered.
+The driver allows pointer actions only when the snapshot's hit grid names the
+node as the recipient at the target cell. Paint order alone is not sufficient.
 
 **Where the injection reaches**, measured on CPython 3.12 (see
 `docs/architecture/audit/textual.md` for the full table): a plain script,
-`-m`, `-c`, a console-script entry point and `uv run` all work. `python -S`
+`-m`, `-c`, a console-script entry point, `uv run` and `poetry run` all work. The
+Python 3.12 CI lane installs both environment managers and executes these real
+subprocess cases. `python -S`
 and `python -E` do not, and are not meant to — the first disables `site`
 entirely and the second makes the interpreter ignore `PYTHONPATH`. Both are
 the person running the interpreter opting out.
@@ -301,28 +336,45 @@ not listed here follows them.
   type for that reason and for no other — no other state here is inferred.
 - **Widgets on an inactive screen are absent, not `hidden`** (rule 4). The
   probe walks `app.screen`, so a pushed-over screen's widgets are not in the
-  tree at all. A widget hidden on the *active* screen (`display = False`) does
+  tree at all. A widget hidden on the _active_ screen (`display = False`) does
   publish `hidden: true`. Textual owns the screen stack; reaching into it would
-  mean publishing widgets that no longer receive events.
-- **`poetry` is unverified.** Poetry was not installed on the machine where the
-  injection table was measured. It runs the interpreter from the project venv
-  as a subprocess and passes the environment through, so it is *expected* to
-  behave like the venv row, and that expectation has not been confirmed. Treat
-  a poetry-run application as untested for the probe until somebody watches it
-  work.
-- **The probe instruments grandchildren too.** `PYTHONPATH` is inherited, so a
-  process the application spawns is also instrumented unless the variable is
-  scrubbed. Visible to the application as well: it can read its own
-  environment. This is a property of the injection mechanism, not a decision.
-- **The probe does not report `frame-begin`** (probe capability). Textual calls
-  `post_display_hook` from the `finally` of `App._display`, *after* the frame
-  has been flushed, so there is no instant the probe could honestly call the
-  start of a frame. Consumers must not read a missing `frame-begin` as "no
-  frame in progress".
+  mean publishing widgets that no longer receive events. The handshake records
+  this narrower limitation as the machine-readable
+  `inactive-screen-tree` degradation.
+- **Ownership is process-local and one-shot.** The first application
+  interpreter atomically owns the generated bootstrap. Before the
+  application's first line, the probe captures its credentials privately and
+  removes the endpoint, token, owner marker, and bootstrap path from the
+  inherited environment. Python children and grandchildren therefore cannot
+  attach to the parent's semantic session. `poetry run` receives a one-hop
+  launcher marker so ownership is claimed by its target interpreter, not by
+  Poetry's own console process.
+- **The probe does not report `frame-begin`** (probe capability). A frame is
+  accepted only when the same `_display` attempt successfully enqueued output
+  through a capability-checked non-headless built-in driver before
+  `post_display_hook`. The writer is preflighted before snapshot publication,
+  then its marker is appended to that same FIFO. A full or replaced writer
+  fails closed without blocking on queue capacity. This exposes no instant the
+  probe could honestly call the start of a frame. Consumers must not read a
+  missing `frame-begin` as "no frame in progress".
 - **A `Static` subclass with a custom `render()` is named by its `content`**
   (rule 2), which is the markup it was given rather than what it draws. Textual
   renders to a strip of segments with no text handle the adapter can read.
 
+## Application evidence providers
+
+`termwright.evidence` exposes closed pointer, focus, scroll, paint,
+terminal-input-mode, and action-strategy provider families.
+`ApplicationFocusEvidenceProvider.observe` returns a semantic
+recipient mapping or authoritative `None`; the wire keeps `focused` and `none`
+distinct from an unnegotiated provider. Registration must happen before the
+session freeze, and providers publish evidence/recipes only—physical input is
+still sent through the PTY.
+
+`ApplicationTerminalInputModeEvidenceProvider.observe` reports the production
+parser's exact mouse and focus modes. It is authoritative evidence for hidden
+ConPTY state, not a callback or a request to synthesize terminal modes.
+
 ## Conformance
 
 `tests/` runs against `clients/test-vectors/`, which is generated from the

{termwright-0.2.0 → termwright-0.3.0}/README.md

@@ -4,8 +4,12 @@ Semantic side-channel client, automatic probe and optional annotation SDK for
 [Textual](https://textual.textualize.io).
 
 An instrumented app publishes its widget tree over a unix socket and commits
-each render with a signed OSC marker, so the driver can assert on *roles and
-names* instead of screen-scraping cells.
+each render with a signed OSC marker, so the driver can assert on _roles and
+names_ instead of screen-scraping cells.
+
+The protocol client speaks `termwright/2`. Every published semantic revision
+is a complete v2 snapshot with evidence-qualified geometry and pointer
+observations.
 
 **Dormant rule.** Without `TERMWRIGHT_ENDPOINT` and `TERMWRIGHT_TOKEN` the
 probe installs nothing, opens no socket, writes no marker, and renders exactly
@@ -18,7 +22,10 @@ pip install termwright              # protocol client + probe + annotation SDK
 pip install "termwright[textual]"   # + Textual itself
 ```
 
-Requires Python 3.9+. The protocol modules have no third-party dependencies.
+Requires Python 3.9+. The Textual extra accepts Textual 8.2.8 or newer as an
+advisory packaging floor. Runtime capability checks and behavioral
+conformance, not the version string, decide whether strong semantics engage;
+the protocol modules have no third-party dependencies.
 
 ## Automatic Textual semantics
 
@@ -46,15 +53,15 @@ useful for a custom runner, is:
 python -m termwright_probe -- python app.py
 ```
 
-Under the driver this publishes, after every flushed frame:
+Under the driver this publishes after every causally ordered frame enqueue:
 
 ```
 application "PermissionApp"
-  region                          bounds=(0,0,80,24)
-    text "Allow bash to run?"     bounds=(0,0,80,1)  testId=prompt
-    button "Approve"              bounds=(1,0,80,3)  testId=approve  [focused]
-    button "Reject"               bounds=(4,0,80,3)  testId=reject
-    textbox "Reason"              bounds=(7,0,80,3)  testId=reason
+  region                          visibleRect=(0,0,80,24)
+    text "Allow bash to run?"     visibleRect=(0,0,80,1)  testId=prompt
+    button "Approve"              visibleRect=(1,0,80,3)  testId=approve  [focused]
+    button "Reject"               visibleRect=(4,0,80,3)  testId=reject
+    textbox "Reason"              visibleRect=(7,0,80,3)  testId=reason
 ```
 
 ### Roles and names
@@ -107,7 +114,7 @@ recreate. `actions` uses the protocol's closed descriptive vocabulary; it never
 registers an out-of-band callback, and interaction still becomes real PTY
 input.
 
-The API intentionally has no bounds, focus, visibility, rendered-text or
+The API intentionally has no geometry, focus, visibility, rendered-text or
 portable-state arguments. Those physical facts remain probe-owned, and merge
 tests enforce that the annotation cannot replace them.
 
@@ -123,7 +130,22 @@ Any TUI can drive the client directly. You own the render; the client owns the
 revision numbers and hands you the marker to write after the render's last byte.
 
 ```python
-from termwright import SemanticNode, SemanticSnapshot, Rect, client_from_env
+from termwright import (
+    NodeGeometryObservations,
+    Observation,
+    Rect,
+    SemanticNode,
+    SemanticSnapshot,
+    client_from_env,
+    framework_evidence,
+)
+
+def geometry(rect: Rect) -> NodeGeometryObservations:
+    return NodeGeometryObservations(
+        displayed=Observation("known", True, evidence=framework_evidence("my-adapter")),
+        intendedRect=Observation("known", rect, evidence=framework_evidence("my-adapter")),
+        visibleRect=Observation("known", rect, evidence=framework_evidence("my-adapter")),
+    )
 
 client = client_from_env(adapter_name="my-tui", adapter_version="1.0.0")
 if client is not None and await client.start():
@@ -132,10 +154,14 @@ if client is not None and await client.start():
             sessionId="", revision=0, columns=80, rows=24,   # both are overwritten
             rootIds=["root"],
             nodes=[
-                SemanticNode(id="root", role="dialog", name="Permission"),
+                SemanticNode(id="root", role="dialog", name="Permission",
+                             geometry=geometry(Rect(0, 0, 80, 24))),
                 SemanticNode(id="ok", parentId="root", role="button", name="Approve",
-                             bounds=Rect(row=1, column=2, width=9, height=1)),
+                             geometry=geometry(Rect(row=1, column=2, width=9, height=1))),
             ],
+            coordinateSpace=Observation("known", "viewport-cells", evidence=framework_evidence("my-adapter")),
+            hitGrid=Observation("unsupported", capability="pointer-hit-grid",
+                                reason="framework-unobservable"),
         )
     )
     sys.stdout.write(marker)   # only after the render is fully written
@@ -184,8 +210,8 @@ or, on a session that came up:
 
 ```text
   tw:sem  [p41207]   0.002s dial unix:/tmp/tw-8f21/s timeout=5000ms
-  tw:sem  [p41207]   0.003s hello sent adapter=textual/1.0.0 caps=tree,bounds,…
-  tw:sem  [3f9c1a04]  0.011s hello-ack session=3f9c1a04… marker=on subscribe=diffs logs=off
+  tw:sem  [p41207]   0.003s hello sent adapter=textual/1.0.0 caps=tree,states,actions,render-revisions,intended-geometry,clipped-geometry,pointer-hit-grid
+  tw:sem  [3f9c1a04]  0.011s hello-ack session=3f9c1a04… marker=on subscribe=snapshots logs=off
   tw:io   [3f9c1a04]  0.048s r1 snapshot nodes=17
 ```
 
@@ -217,8 +243,16 @@ python -m termwright_probe -- python app.py
 `app.py` imports no termwright, calls nothing of ours, and is not edited. The
 launcher puts a generated `sitecustomize.py` on `PYTHONPATH`; CPython imports
 it during startup, before the script's own directory reaches `sys.path`; the
-probe waits there until the application imports Textual and attaches to
-`App.post_display_hook`. A driver that already sets `TERMWRIGHT_ENDPOINT` and
+probe waits there until the application imports Textual and observes the
+capability-checked `App._display` / driver enqueue / `post_display_hook`
+boundary. The
+marker is appended without waiting to the same WriterThread FIFO, after the
+frame; a full queue fails the semantic channel instead of blocking Textual's
+event loop. No Textual version is allowlisted. Strong probing accepts only a
+live built-in `LinuxDriver` or `WindowsDriver` whose concrete WriterThread and
+bounded FIFO pass the runtime checks; custom
+`driver_class` values and inline mode fail the semantic channel explicitly
+rather than publishing an unprovable commit. A driver that already sets `TERMWRIGHT_ENDPOINT` and
 `TERMWRIGHT_TOKEN` can compose the same thing itself:
 
 ```python
@@ -241,21 +275,22 @@ the claim that the probe observes rather than redraws.
 
 **What it reports automatically.**
 
-| Fact | Where it comes from |
-|---|---|
-| `bounds` = what is on screen | `MapGeometry.visible_region`, Textual's `clip ∩ region` |
-| `occlusion: "known"` | widgets ranked by `MapGeometry.order`, the compositor's own sort key |
-| roles for your own widget classes | the MRO, so `SaveButton(Button)` is a button with no registration |
-| `frameworkType` on anything unrecognised | the widget's class name |
+| Fact                                      | Where it comes from                                                    |
+| ----------------------------------------- | ---------------------------------------------------------------------- |
+| intended and visible rectangles           | `MapGeometry.region` and `MapGeometry.visible_region`                  |
+| exact pointer recipient                   | `Screen.get_widget_at`, compressed into the snapshot hit grid          |
+| roles for your own widget classes         | the MRO, so `SaveButton(Button)` is a button with no registration      |
+| `frameworkType` on anything unrecognised  | the widget's class name                                                |
 | scrolled out of view vs `display = False` | both `hidden`; the first also `state.offscreen`, with a zero-area rect |
 
-Because paint order is real here, the driver allows pointer actions against
-Textual nodes; it refuses them for producers that cannot say whether a node's
-cells are covered.
+The driver allows pointer actions only when the snapshot's hit grid names the
+node as the recipient at the target cell. Paint order alone is not sufficient.
 
 **Where the injection reaches**, measured on CPython 3.12 (see
 `docs/architecture/audit/textual.md` for the full table): a plain script,
-`-m`, `-c`, a console-script entry point and `uv run` all work. `python -S`
+`-m`, `-c`, a console-script entry point, `uv run` and `poetry run` all work. The
+Python 3.12 CI lane installs both environment managers and executes these real
+subprocess cases. `python -S`
 and `python -E` do not, and are not meant to — the first disables `site`
 entirely and the second makes the interpreter ignore `PYTHONPATH`. Both are
 the person running the interpreter opting out.
@@ -277,28 +312,45 @@ not listed here follows them.
   type for that reason and for no other — no other state here is inferred.
 - **Widgets on an inactive screen are absent, not `hidden`** (rule 4). The
   probe walks `app.screen`, so a pushed-over screen's widgets are not in the
-  tree at all. A widget hidden on the *active* screen (`display = False`) does
+  tree at all. A widget hidden on the _active_ screen (`display = False`) does
   publish `hidden: true`. Textual owns the screen stack; reaching into it would
-  mean publishing widgets that no longer receive events.
-- **`poetry` is unverified.** Poetry was not installed on the machine where the
-  injection table was measured. It runs the interpreter from the project venv
-  as a subprocess and passes the environment through, so it is *expected* to
-  behave like the venv row, and that expectation has not been confirmed. Treat
-  a poetry-run application as untested for the probe until somebody watches it
-  work.
-- **The probe instruments grandchildren too.** `PYTHONPATH` is inherited, so a
-  process the application spawns is also instrumented unless the variable is
-  scrubbed. Visible to the application as well: it can read its own
-  environment. This is a property of the injection mechanism, not a decision.
-- **The probe does not report `frame-begin`** (probe capability). Textual calls
-  `post_display_hook` from the `finally` of `App._display`, *after* the frame
-  has been flushed, so there is no instant the probe could honestly call the
-  start of a frame. Consumers must not read a missing `frame-begin` as "no
-  frame in progress".
+  mean publishing widgets that no longer receive events. The handshake records
+  this narrower limitation as the machine-readable
+  `inactive-screen-tree` degradation.
+- **Ownership is process-local and one-shot.** The first application
+  interpreter atomically owns the generated bootstrap. Before the
+  application's first line, the probe captures its credentials privately and
+  removes the endpoint, token, owner marker, and bootstrap path from the
+  inherited environment. Python children and grandchildren therefore cannot
+  attach to the parent's semantic session. `poetry run` receives a one-hop
+  launcher marker so ownership is claimed by its target interpreter, not by
+  Poetry's own console process.
+- **The probe does not report `frame-begin`** (probe capability). A frame is
+  accepted only when the same `_display` attempt successfully enqueued output
+  through a capability-checked non-headless built-in driver before
+  `post_display_hook`. The writer is preflighted before snapshot publication,
+  then its marker is appended to that same FIFO. A full or replaced writer
+  fails closed without blocking on queue capacity. This exposes no instant the
+  probe could honestly call the start of a frame. Consumers must not read a
+  missing `frame-begin` as "no frame in progress".
 - **A `Static` subclass with a custom `render()` is named by its `content`**
   (rule 2), which is the markup it was given rather than what it draws. Textual
   renders to a strip of segments with no text handle the adapter can read.
 
+## Application evidence providers
+
+`termwright.evidence` exposes closed pointer, focus, scroll, paint,
+terminal-input-mode, and action-strategy provider families.
+`ApplicationFocusEvidenceProvider.observe` returns a semantic
+recipient mapping or authoritative `None`; the wire keeps `focused` and `none`
+distinct from an unnegotiated provider. Registration must happen before the
+session freeze, and providers publish evidence/recipes only—physical input is
+still sent through the PTY.
+
+`ApplicationTerminalInputModeEvidenceProvider.observe` reports the production
+parser's exact mouse and focus modes. It is authoritative evidence for hidden
+ConPTY state, not a callback or a request to synthesize terminal modes.
+
 ## Conformance
 
 `tests/` runs against `clients/test-vectors/`, which is generated from the

{termwright-0.2.0 → termwright-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "termwright"
-version = "0.2.0"
+version = "0.3.0"
 description = "Semantic side-channel client, automatic Textual probe, and annotation SDK for Termwright"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -22,8 +22,8 @@ classifiers = [
 dependencies = []
 
 [project.optional-dependencies]
-textual = ["textual>=0.60"]
-dev = ["pytest>=7", "pytest-asyncio>=0.21", "textual>=0.60"]
+textual = ["textual>=8.2.8"]
+dev = ["pytest>=7", "pytest-asyncio>=0.21", "textual>=8.2.8"]
 
 [project.urls]
 Homepage = "https://github.com/gorce-ai/termwright"

{termwright-0.2.0 → termwright-0.3.0}/src/termwright/__init__.py

@@ -20,13 +20,29 @@ from .client import (
     CAPABILITIES_WITH_LOGS,
     DEFAULT_CAPABILITIES,
     ENV_ENDPOINT,
-    ENV_PROTOCOL,
     ENV_TOKEN,
     SemanticClient,
     client_from_env,
 )
 from .debug import ENV_DEBUG, ENV_DEBUG_FILE, DebugLog, debug_path
 from .errors import ProtocolViolation, TermwrightError
+from .evidence import (
+    ApplicationActionStrategyProvider,
+    ApplicationFocusEvidenceProvider,
+    ApplicationScrollEvidenceProvider,
+    ApplicationPaintEvidenceProvider,
+    ApplicationTerminalInputModeEvidenceProvider,
+    EvidenceProviderLifecycleError,
+    EvidenceProviderRegistry,
+    EvidenceProviderRegistration,
+    EvidenceRevisionContext,
+    default_evidence_provider_registry,
+    register_action_strategy_provider,
+    register_focus_evidence_provider,
+    register_scroll_evidence_provider,
+    register_paint_evidence_provider,
+    register_terminal_input_mode_evidence_provider,
+)
 from .framing import FRAME_HEADER_BYTES, FrameDecoder, encode_frame, project_dto
 from .limits import ABSOLUTE_LIMITS, DEFAULT_LIMITS, ProtocolLimits
 from .logs import (
@@ -53,20 +69,30 @@ from .messages import (
     parse_adapter_message,
     parse_driver_message,
 )
-from .roles import ADAPTER_CAPABILITIES, SEMANTIC_ACTIONS, SEMANTIC_ROLES
+from .roles import (
+    ADAPTER_CAPABILITIES,
+    EVIDENCE_PROVIDER_CAPABILITIES,
+    SEMANTIC_ACTIONS,
+    SEMANTIC_ROLES,
+)
 from .tree import (
+    EvidenceProvenance,
     CursorInfo,
     NodeGeometryObservations,
     Observation,
+    framework_evidence,
     Rect,
     SemanticNode,
     SemanticSnapshot,
+    SemanticScrollState,
+    SemanticPaintedRegion,
     SemanticState,
     SemanticTextRange,
+    SemanticValueObservation,
 )
-from .validate import ValidationResult, apply_tree_delta, validate_snapshot, validate_tree_delta
+from .validate import ValidationResult, validate_snapshot
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "ABSOLUTE_LIMITS",
@@ -79,14 +105,23 @@ __all__ = [
     "flatten_attrs",
     "validate_log_record",
     "ADAPTER_CAPABILITIES",
+    "ApplicationActionStrategyProvider",
+    "ApplicationFocusEvidenceProvider",
+    "ApplicationScrollEvidenceProvider",
+    "ApplicationPaintEvidenceProvider",
+    "ApplicationTerminalInputModeEvidenceProvider",
     "DEFAULT_CAPABILITIES",
     "DEFAULT_LIMITS",
     "DebugLog",
     "ENV_DEBUG",
     "ENV_DEBUG_FILE",
     "ENV_ENDPOINT",
-    "ENV_PROTOCOL",
     "ENV_TOKEN",
+    "EvidenceProviderLifecycleError",
+    "EvidenceProviderRegistry",
+    "EvidenceProviderRegistration",
+    "EvidenceRevisionContext",
+    "EVIDENCE_PROVIDER_CAPABILITIES",
     "FRAME_HEADER_BYTES",
     "FrameDecoder",
     "MARKER_MAC_BYTES",
@@ -99,27 +134,36 @@ __all__ = [
     "ProtocolViolation",
     "RenderMarker",
     "CursorInfo",
+    "EvidenceProvenance",
     "NodeGeometryObservations",
     "Observation",
+    "framework_evidence",
     "Rect",
     "SEMANTIC_ACTIONS",
     "SEMANTIC_ROLES",
     "SemanticClient",
     "SemanticNode",
     "SemanticSnapshot",
+    "SemanticScrollState",
+    "SemanticPaintedRegion",
     "SemanticState",
     "SemanticTextRange",
+    "SemanticValueObservation",
     "TermwrightError",
     "ValidationResult",
     "client_from_env",
     "debug_path",
+    "default_evidence_provider_registry",
     "encode_frame",
     "encode_marker",
     "parse_adapter_message",
     "parse_driver_message",
     "project_dto",
-    "apply_tree_delta",
+    "register_action_strategy_provider",
+    "register_focus_evidence_provider",
+    "register_scroll_evidence_provider",
+    "register_paint_evidence_provider",
+    "register_terminal_input_mode_evidence_provider",
     "validate_snapshot",
-    "validate_tree_delta",
     "verify_marker_payload",
 ]