termwright 0.3.2__tar.gz → 0.4.0__tar.gz

{termwright-0.3.2 → termwright-0.4.0}/.gitignore

@@ -1,5 +1,5 @@
 # Rust
-rust/target/
+target/
 # Python
 python/*.egg-info/
 python/build/

{termwright-0.3.2 → termwright-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: termwright
-Version: 0.3.2
+Version: 0.4.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
@@ -31,8 +31,8 @@ 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.
 
-The protocol client speaks `termwright/2`. Every published semantic revision
-is a complete v2 snapshot with evidence-qualified geometry and pointer
+The protocol client speaks `termwright/3`. Every published semantic revision
+is a complete v3 snapshot with evidence-qualified geometry and pointer
 observations.
 
 **Dormant rule.** Without `TERMWRIGHT_ENDPOINT` and `TERMWRIGHT_TOKEN` the
@@ -235,7 +235,7 @@ 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,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:sem  [3f9c1a04]  0.011s hello-ack session=3f9c1a04… marker=on subscribe=semantic logs=off
   tw:io   [3f9c1a04]  0.048s r1 snapshot nodes=17
 ```
 

{termwright-0.3.2 → termwright-0.4.0}/README.md

@@ -7,8 +7,8 @@ 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.
 
-The protocol client speaks `termwright/2`. Every published semantic revision
-is a complete v2 snapshot with evidence-qualified geometry and pointer
+The protocol client speaks `termwright/3`. Every published semantic revision
+is a complete v3 snapshot with evidence-qualified geometry and pointer
 observations.
 
 **Dormant rule.** Without `TERMWRIGHT_ENDPOINT` and `TERMWRIGHT_TOKEN` the
@@ -211,7 +211,7 @@ 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,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:sem  [3f9c1a04]  0.011s hello-ack session=3f9c1a04… marker=on subscribe=semantic logs=off
   tw:io   [3f9c1a04]  0.048s r1 snapshot nodes=17
 ```
 

{termwright-0.3.2 → termwright-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "termwright"
-version = "0.3.2"
+version = "0.4.0"
 description = "Semantic side-channel client, automatic Textual probe, and annotation SDK for Termwright"
 readme = "README.md"
 requires-python = ">=3.9"

{termwright-0.3.2 → termwright-0.4.0}/src/termwright/__init__.py

@@ -92,7 +92,7 @@ from .tree import (
 )
 from .validate import ValidationResult, validate_snapshot
 
-__version__ = "0.3.2"
+__version__ = "0.4.0"
 
 __all__ = [
     "ABSOLUTE_LIMITS",

{termwright-0.3.2 → termwright-0.4.0}/src/termwright/client.py

@@ -33,7 +33,7 @@ from .messages import (
     parse_driver_message,
     protocol_error,
     revision_commit,
-    snapshot_message,
+    semantic_full_message,
 )
 from .tree import SemanticSnapshot
 from .validate import validate_snapshot
@@ -186,7 +186,7 @@ class SemanticClient:
         self._log_bucket: Optional[_TokenBucket] = None
         #: Records dropped locally for being over budget or over a limit.
         self.logs_dropped = 0
-        self.subscribe = "snapshots"
+        self.subscribe = "semantic"
         self.closed = False
 
     # -- lifecycle ---------------------------------------------------------
@@ -390,10 +390,9 @@ class SemanticClient:
         marker escapes.
         """
         messages = []
-        sent_snapshot = self.subscribe != "revisions"
-        if self.subscribe != "revisions":
-            self._log("io", f"r{wire['revision']} snapshot nodes={len(wire.get('nodes', ()))}")
-            messages.append(snapshot_message(wire))
+        sent_snapshot = True
+        self._log("io", f"r{wire['revision']} semantic-full nodes={len(wire.get('nodes', ()))}")
+        messages.append(semantic_full_message(wire))
         messages.append(revision_commit(wire["revision"]))
         return (
             tuple(encode_frame(message, self._limits.maxFrameBytes) for message in messages),

{termwright-0.3.2 → termwright-0.4.0}/src/termwright/messages.py

@@ -18,11 +18,11 @@ from .logs import LogRecord, validate_log_record
 from .roles import CAPABILITY_SET, EVIDENCE_PROVIDER_CAPABILITY_SET
 from .validate import validate_snapshot
 
-PROTOCOL_ID = "termwright/2"
-PROTOCOL_VERSION = 2
+PROTOCOL_ID = "termwright/3"
+PROTOCOL_VERSION = 3
 
 ERROR_CODES = ("bad-token", "bad-version", "malformed", "limit-exceeded", "duplicate-semantic-key", "adapter-guarantee-violation", "internal")
-SUBSCRIBE_MODES = ("snapshots", "revisions")
+SUBSCRIBE_MODES = ("semantic",)
 
 MAX_IDENTIFIER_LENGTH = 1024
 _MAX_SAFE_INTEGER = 2**53 - 1
@@ -73,15 +73,19 @@ def hello(
         "capabilities": list(capabilities),
     }
     if probe is not None:
+        if not isinstance(probe.get("instrumentation"), Mapping):
+            raise ProtocolViolation(
+                "marker-argument", "probe.instrumentation is required for every probe"
+            )
         message["probe"] = dict(probe)
     if providers:
         message["providers"] = [dict(provider) for provider in providers]
     return message
 
 
-def snapshot_message(snapshot: Mapping[str, Any]) -> Dict[str, Any]:
+def semantic_full_message(snapshot: Mapping[str, Any]) -> Dict[str, Any]:
     """Wrap a wire-form snapshot in its envelope."""
-    return {"type": "snapshot", "snapshot": dict(snapshot)}
+    return {"type": "semantic-full", "snapshot": dict(snapshot)}
 
 
 def revision_commit(revision: int) -> Dict[str, Any]:
@@ -260,6 +264,12 @@ def parse_adapter_message(value: Any, limits: ProtocolLimits = DEFAULT_LIMITS) -
         for item in capabilities:
             if item not in CAPABILITY_SET:
                 return _malformed(f"capabilities: unknown capability {item!r}")
+        if "probe" in message:
+            probe = message["probe"]
+            if not isinstance(probe, dict):
+                return _malformed("probe: expected an object")
+            if not isinstance(probe.get("instrumentation"), dict):
+                return _malformed("probe.instrumentation: required")
         if "providers" in message:
             providers = message["providers"]
             if not isinstance(providers, list) or len(providers) > 64:
@@ -295,7 +305,7 @@ def parse_adapter_message(value: Any, limits: ProtocolLimits = DEFAULT_LIMITS) -
         issue = _exact_keys(message, ("type", "revision")) or _revision(message.get("revision"), "revision")
         return _malformed(issue) if issue else ParseResult(ok=True, message=message)
 
-    if kind == "snapshot":
+    if kind == "semantic-full":
         issue = _exact_keys(message, ("type", "snapshot"))
         if issue:
             return _malformed(issue)
@@ -368,7 +378,7 @@ def parse_driver_message(value: Any, limits: ProtocolLimits = DEFAULT_LIMITS) ->
             if issue:
                 return _malformed(issue)
         if message["subscribe"] not in SUBSCRIBE_MODES:
-            return _malformed("subscribe: expected 'snapshots' or 'revisions'")
+            return _malformed("subscribe: expected 'semantic'")
         marker = message["marker"]
         if not isinstance(marker, dict):
             return _malformed("marker: expected an object")
@@ -383,6 +393,24 @@ def parse_driver_message(value: Any, limits: ProtocolLimits = DEFAULT_LIMITS) ->
                 return _malformed(issue)
         return ParseResult(ok=True, message=message)
 
+    if kind == "semantic-resync-request":
+        issue = _required_keys(
+            message, ("type", "sessionId", "expectedBaseRevision", "reason")
+        )
+        if issue:
+            return _malformed(issue)
+        issue = _identifier(message["sessionId"], "sessionId")
+        if issue:
+            return _malformed(issue)
+        expected = message["expectedBaseRevision"]
+        if expected is not None:
+            issue = _revision(expected, "expectedBaseRevision")
+            if issue:
+                return _malformed(issue)
+        if message["reason"] not in ("base-mismatch", "missing-base", "driver-reset"):
+            return _malformed("reason: unknown semantic resync reason")
+        return ParseResult(ok=True, message=message)
+
     if kind == "error":
         issue = _check_error(message, strict=False)
         return _malformed(issue) if issue else ParseResult(ok=True, message=message)

{termwright-0.3.2 → termwright-0.4.0}/src/termwright/roles.py

@@ -50,6 +50,7 @@ ADAPTER_CAPABILITIES = (
     "render-revisions",
     "logs",
     "pointer-hit-grid",
+    "incremental-tree",
 )
 
 EVIDENCE_PROVIDER_CAPABILITIES = (

{termwright-0.3.2 → termwright-0.4.0}/src/termwright/tree.py

@@ -307,7 +307,7 @@ class SemanticSnapshot:
     rootIds: Sequence[str] = field(default_factory=list)
     nodes: Sequence[SemanticNode] = field(default_factory=list)
     cursor: Optional[CursorInfo] = None
-    v: int = 2
+    v: int = 3
 
     def to_wire(self) -> Dict[str, Any]:
         wire: Dict[str, Any] = {

{termwright-0.3.2 → termwright-0.4.0}/src/termwright/validate.py

@@ -572,8 +572,8 @@ def _snapshot_schema(value: Any, limits: ProtocolLimits) -> None:
     version = snapshot.get("v")
     _strict(snapshot, _SNAPSHOT_KEYS, ())
 
-    if version != 2:
-        raise _Issue(("v",), "expected the literal 2")
+    if version != 3:
+        raise _Issue(("v",), "expected the literal 3")
     if "sessionId" not in snapshot:
         raise _Issue(("sessionId",), "expected a string")
     if _text(snapshot["sessionId"], ("sessionId",), limits) == "":

{termwright-0.3.2 → termwright-0.4.0}/src/termwright_probe/__init__.py

@@ -31,7 +31,7 @@ from .bootstrap import (
 )
 from .defer import when_imported
 
-__version__ = "0.3.2"
+__version__ = "0.4.0"
 
 #: Set once :func:`install` has run, so a second `sitecustomize` on the path
 #: cannot attach the probe twice.

{termwright-0.3.2 → termwright-0.4.0}/src/termwright_probe/textual_tree.py

@@ -506,7 +506,7 @@ def build_snapshot(
         rows=rows,
         rootIds=root_ids,
         nodes=nodes,
-        v=2,
+        v=3,
         coordinateSpace=WireObservation(status="known", value="viewport-cells", evidence=framework_evidence("textual-probe")),
         hitGrid=WireObservation(status="known", value={"regions": hit_regions}, evidence=framework_evidence("textual-compositor-hit-grid")),
     )

{termwright-0.3.2 → termwright-0.4.0}/tests/conftest.py

@@ -29,7 +29,7 @@ def load_vectors(name: str) -> Dict[str, Any]:
 
 
 def geometry(rect: Rect = Rect(0, 0, 1, 1)) -> NodeGeometryObservations:
-    """Known viewport geometry for protocol-v2 unit fixtures."""
+    """Known viewport geometry for protocol-v3 unit fixtures."""
     return NodeGeometryObservations(
         displayed=Observation("known", True, evidence=framework_evidence("python-test")),
         intendedRect=Observation("known", rect, evidence=framework_evidence("python-test")),

{termwright-0.3.2 → termwright-0.4.0}/tests/test_client.py

@@ -70,7 +70,7 @@ class FakeDriver:
         self,
         path: str,
         logs: Optional[Dict[str, Any]] = None,
-        subscribe: str = "snapshots",
+        subscribe: str = "semantic",
     ) -> None:
         self.path = path
         self.logs = logs
@@ -186,7 +186,7 @@ async def test_handshake_and_publish(endpoint):
     await driver.wait_for(2)
 
     snapshot_frame, commit_frame = driver.received[0], driver.received[1]
-    assert snapshot_frame["type"] == "snapshot"
+    assert snapshot_frame["type"] == "semantic-full"
     assert snapshot_frame["snapshot"]["sessionId"] == SESSION
     assert snapshot_frame["snapshot"]["revision"] == 1
     assert commit_frame == {"type": "revision-commit", "revision": 1}
@@ -282,23 +282,23 @@ async def test_nowait_oversize_has_no_marker_and_recovers():
 
     decoder = FrameDecoder(limits.maxFrameBytes, limits.maxDepth)
     messages = [message for frame in writer.frames for message in decoder.push(frame)]
-    assert [message["type"] for message in messages] == ["snapshot", "revision-commit"]
+    assert [message["type"] for message in messages] == ["semantic-full", "revision-commit"]
     assert messages[0]["snapshot"]["revision"] == 1
     assert messages[1]["revision"] == 1
     assert client.connected
 
 
-async def test_a_revisions_subscription_gets_commits_only(endpoint):
-    driver = FakeDriver(endpoint, subscribe="revisions")
+async def test_the_single_semantic_subscription_always_gets_a_full_tree(endpoint):
+    driver = FakeDriver(endpoint, subscribe="semantic")
     await driver.start()
     client = SemanticClient(endpoint, TOKEN, adapter_name="pytest", adapter_version="0.1.0")
     assert await client.start(timeout=2.0) is True
 
     await client.publish(sample_snapshot())
-    await driver.wait_for(1)
+    await driver.wait_for(2)
 
     kinds = [frame["type"] for frame in driver.received]
-    assert kinds == ["revision-commit"], kinds
+    assert kinds == ["semantic-full", "revision-commit"], kinds
 
     await client.close()
     await driver.close()
@@ -363,7 +363,7 @@ async def test_a_write_to_a_stalled_driver_is_bounded(endpoint):
             "protocol": PROTOCOL_ID,
             "sessionId": SESSION,
             "limits": DEFAULT_LIMITS.to_wire(),
-            "subscribe": "snapshots",
+            "subscribe": "semantic",
             "marker": {"enabled": True},
         }
         writer.write(encode_frame(ack, DEFAULT_LIMITS.maxFrameBytes))

{termwright-0.3.2 → termwright-0.4.0}/tests/test_messages.py

@@ -22,20 +22,28 @@ def ack(**changes):
         "protocol": PROTOCOL_ID,
         "sessionId": "s-1",
         "limits": DEFAULT_LIMITS.to_wire(),
-        "subscribe": "snapshots",
+        "subscribe": "semantic",
         "marker": {"enabled": True},
     }
     message.update(changes)
     return message
 
 
-def test_protocol_v2_messages_are_accepted():
+def test_protocol_v3_messages_are_accepted():
     tree = snapshot(nodes=[node(id="root", role="application", name="app")], root_ids=["root"])
     messages = [
         (parse_adapter_message, hello("token", "pytest", "0.1.0", ["tree"])),
-        (parse_adapter_message, {"type": "snapshot", "snapshot": tree.to_wire()}),
+        (parse_adapter_message, {"type": "semantic-full", "snapshot": tree.to_wire()}),
         (parse_driver_message, ack()),
-        (parse_driver_message, ack(subscribe="revisions")),
+        (
+            parse_driver_message,
+            {
+                "type": "semantic-resync-request",
+                "sessionId": "s-1",
+                "expectedBaseRevision": None,
+                "reason": "driver-reset",
+            },
+        ),
     ]
     for parser, message in messages:
         result = parser(message, DEFAULT_LIMITS)

{termwright-0.3.2 → termwright-0.4.0}/tests/test_probe_golden.py

@@ -148,11 +148,11 @@ async def test_instrumented_output_is_the_same_render_plus_markers(endpoint):
                 asyncio.to_thread(run_on_pty, env, release)
             )
             while not any(
-                message.get("type") == "snapshot" for message in driver.received
+                message.get("type") == "semantic-full" for message in driver.received
             ):
                 driver.frame_arrived.clear()
                 if any(
-                    message.get("type") == "snapshot"
+                    message.get("type") == "semantic-full"
                     for message in driver.received
                 ):
                     break
@@ -169,5 +169,5 @@ async def test_instrumented_output_is_the_same_render_plus_markers(endpoint):
         "instrumentation changed the render, not just the commits"
     )
 
-    published = [m for m in driver.received if m.get("type") == "snapshot"]
+    published = [m for m in driver.received if m.get("type") == "semantic-full"]
     assert published, "markers were written but no tree was published"

{termwright-0.3.2 → termwright-0.4.0}/tests/test_probe_session.py

@@ -173,12 +173,12 @@ async def test_it_publishes_a_valid_tree_for_a_real_app(endpoint):
         await wait_for(lambda: client.connected)
         session.on_frame(commit_for(app))
         await wait_for(
-            lambda: any(m.get("type") == "snapshot" for m in driver.received)
+            lambda: any(m.get("type") == "semantic-full" for m in driver.received)
         )
         await pilot.pause()
         await client.close()
 
-    published = [m for m in driver.received if m.get("type") == "snapshot"]
+    published = [m for m in driver.received if m.get("type") == "semantic-full"]
     assert published, "nothing reached the driver"
     snapshot = published[-1]["snapshot"]
     result = validate_snapshot(snapshot, DEFAULT_LIMITS)
@@ -432,7 +432,7 @@ async def test_a_vanilla_app_in_a_child_process_publishes_a_tree(endpoint, tmp_p
         )
         try:
             await wait_for(
-                lambda: any(m.get("type") == "snapshot" for m in driver.received),
+                lambda: any(m.get("type") == "semantic-full" for m in driver.received),
                 timeout=30.0,
             )
         finally:
@@ -440,7 +440,7 @@ async def test_a_vanilla_app_in_a_child_process_publishes_a_tree(endpoint, tmp_p
                 child.terminate()
             await child.wait()
 
-    published = [m for m in driver.received if m.get("type") == "snapshot"]
+    published = [m for m in driver.received if m.get("type") == "semantic-full"]
     assert published, "the child published nothing"
     snapshot = published[-1]["snapshot"]
     result = validate_snapshot(snapshot, DEFAULT_LIMITS)

{termwright-0.3.2 → termwright-0.4.0}/tests/test_probe_tree.py

@@ -298,7 +298,7 @@ async def test_publishes_qualified_geometry_and_exact_hit_grid():
     async with app.run_test(size=(40, 10)) as pilot:
         await pilot.pause()
         snapshot = build_snapshot(app, app.screen, Identities(), session_id="s", revision=1).to_wire()
-    assert snapshot["v"] == 2
+    assert snapshot["v"] == 3
     assert snapshot["coordinateSpace"]["value"] == "viewport-cells"
     assert snapshot["hitGrid"]["status"] == "known"
     approve = by_test_id(snapshot)["approve"]

{termwright-0.3.2 → termwright-0.4.0}/tests/test_validate.py

@@ -31,7 +31,7 @@ def test_snapshot_vectors_match_the_reference_validator():
         )
 
 
-def test_valid_protocol_v2_snapshot_is_accepted():
+def test_valid_protocol_v3_snapshot_is_accepted():
     value = snapshot(
         nodes=[
             node(id="root", role="dialog", name="Permission", rect=Rect(0, 0, 20, 4)),

{termwright-0.3.2 → termwright-0.4.0}/uv.lock

@@ -312,7 +312,7 @@ wheels = [
 
 [[package]]
 name = "termwright"
-version = "0.3.2"
+version = "0.4.0"
 source = { editable = "." }
 
 [package.optional-dependencies]