feat: add strict TSX protocol handshake

Author: Roy Lin

README.md

@@ -98,7 +98,7 @@ contract.
 
 ## TSX to native, without a browser
 
-The proposed TypeScript path follows
+The planned TypeScript path follows
 [Nub](https://github.com/nubjs/nub)'s strongest runtime idea: keep stock Node,
 transform `.tsx` through its normal loader pipeline, and let a narrow Rust
 boundary own native work. A3S adds a standard automatic JSX runtime and a
@@ -136,10 +136,16 @@ function Counter() {
 await createApp(Counter).run();
 ```
 
-This sample documents the target API; it is not runnable yet. The proposed
-design keeps component state and callbacks in Node, keeps platform/GPU handles
-inside a separate Rust process, reuses resolved `ProtocolUiFrameV1` records,
-and sends complete frames so Rust remains the only native reconciler. Read the
+This sample documents the target API; it is not runnable yet. The Rust-side
+session entrance is now executable: strict `hello`/`welcome` DTOs negotiate the
+renderer, capabilities, debug channels, one in-flight render, and a JSON
+payload limit no larger than 16 MiB; incremental and blocking codecs enforce a
+little-endian `u32` length prefix and reject empty, oversized, truncated,
+invalid UTF-8, duplicate-field, unknown-kind, and unsupported-protocol input
+before a session is bound. The remaining design keeps component state and callbacks in Node,
+keeps platform/GPU handles inside a separate Rust process, reuses resolved
+`ProtocolUiFrameV1` records, and sends complete frames so Rust remains the only
+native reconciler. Read the
 [TSX native runtime architecture](docs/tsx-native-runtime.md) for protocol,
 identity, failure recovery, packaging, and T0-T5 delivery gates.
 
@@ -349,7 +355,7 @@ independently.
 | M4 · Text and interaction cutover | In progress | Stable-id raw input, long press, move, typed and collection drag/drop, timed drop activation, and fail-closed dynamic drop policy resolution landed; shaping, glyphs, editing/IME, accessibility bridges, overlays, and complete calculator scenarios remain |
 | M5 · Default cutover | Planned | Make self-drawn content the default, then delete the three legacy widget renderers |
 | H0-H5 · Thin platform hosts | H0 complete; H1 in progress | Atomic frames, lifecycle recovery, stable-id raw input/reducers, long press, captured move, typed drag/drop negotiation and timed target activation, zero-toolkit firewalls, and an interactive calculator landed; the Graphics raw-surface edge remains |
-| T0-T5 · TSX native authoring | First protocol slice landed | Rust-side revision-scoped drop-policy DTOs and resolver bridge landed; automatic JSX runtime, Node transport/callback registry, state/event runtime, self-drawn native window, packages, and stable SDK remain |
+| T0-T5 · TSX native authoring | T1 Rust foundation in progress | Strict handshake, bounded length-prefixed framing, message sequencing, and revision-scoped drop-policy DTO/resolver bridge landed; render/event messages, TypeScript declarations, JSX runtime, Node callback transport, state runtime, self-drawn native window, packages, and stable SDK remain |
 | M6-M8 · React Aria components | Catalog pinned; conformance planned | 51/51 families mapped; collection DnD authoring/behavior slice landed; eight public parts, full software, accessibility, and three-OS self-drawn evidence remain |
 
 The dependency-ordered plan and acceptance gates are in the
@@ -493,6 +499,7 @@ src/
 |- rsx_app/              ComponentCx, hooks, components, and binding scope
 |- rsx_ui/               built-in semantic design-system registry
 |- protocol.rs           versioned frame, event, action, ACK, and recovery boundary
+|- tsx_protocol/         strict handshake, message sequencing, and bounded framing
 |- native.rs             portable NativeElement UI IR
 |- layout/               deterministic records, style projection, diffs, and tests
 |- drawing.rs            Graphics boundary and reference/GPU renderer wrappers

docs/architecture.md

@@ -961,6 +961,19 @@ and events are rejected until delivery is acknowledged. Password values remain
 available to in-process reducers but are removed from commands, accessibility,
 responses, session debug output, and retained diagnostics.
 
+The optional TSX process boundary begins in the feature-independent
+`tsx_protocol` module rather than in a Node or native-backend feature. Its
+strict `hello`/`welcome` messages carry the fixed `a3s.gui.tsx` protocol id,
+version range, opaque session id, per-sender message id, render revision,
+renderer request/selection, capabilities, debug channels, and negotiated
+limits. `TsxHostHandshakeV1` mutates from unbound to negotiated only after the
+complete response fits the negotiated limit. Both stream and incremental JSON
+codecs validate a little-endian `u32` length before allocation, enforce the
+16 MiB protocol-v1 JSON-payload ceiling, and poison an incremental decoder
+after any framing or strict-JSON violation. This Rust transport foundation has
+no Node, Nub, N-API, Graphics, legacy renderer, or OS-toolkit dependency;
+render/event session messages and the Node implementation remain T1 work.
+
 Drop policies that participate in hit testing use a separate synchronous
 protocol-v1 exchange rather than an action invocation. A
 `ProtocolDropPolicyQueryV1` carries the session, committed render revision,

docs/react-aria-native.md

@@ -186,7 +186,9 @@ The first shared interaction milestone is available in the portable runtime:
   timeout/disconnect/failure, mismatched response metadata, wrong decision
   types, and disallowed operations all fail closed to `cancel`. Strict protocol
   v1 DTOs and `ProtocolDropPolicyResolverV1` bridge this contract without Rust
-  evaluating JavaScript. The Node callback registry/transport, external
+  evaluating JavaScript. The separate TSX boundary now also has strict atomic
+  handshake negotiation and bounded length-prefixed JSON framing, but its
+  render/event messages and Node callback registry/transport, external
   files/directories and cross-application transfer, drag previews, and full
   conformance evidence remain separate M7 work, so no affected family is
   marked conformant.

docs/roadmap.md

@@ -623,9 +623,10 @@ Gates:
 
 ## P0-T TSX Native Authoring Track
 
-Status: architecture accepted; the first Rust-side revision-scoped drop-policy
-protocol and resolver adapter has landed, while the JSX runtime, Node callback
-registry, process transport, and visible TSX application have not started.
+Status: architecture accepted; the Rust-side strict handshake, bounded framing,
+message sequencing, and revision-scoped drop-policy protocol/resolver adapter
+have landed. Render/event transport messages, generated TypeScript, the JSX
+runtime, Node callback registry, and visible TSX application remain.
 
 This track is dependency-coupled to the renderer and H0-H5 host programs
 without blocking Rust RSX work. Headless protocol and JSX-runtime work can
@@ -657,10 +658,16 @@ Graphics, interaction, accessibility, or capability checks.
 
 ### T1 - Headless JSX and protocol slice
 
+Status: Rust transport foundation in progress. Strict `hello`/`welcome` DTOs,
+atomic negotiation, the fixed protocol/session/message/revision envelope,
+16 MiB-capped little-endian length framing, incremental decoding, and the first
+canonical JSON fixture have landed without Node or Graphics dependencies.
+
 - generated TypeScript declarations from versioned Rust DTOs
 - automatic `jsx-runtime` and `jsx-dev-runtime` exports
 - deterministic child, prop, key, and event normalization
-- bounded length-prefixed IPC, handshake, revisions, event sequencing, and
+- extend the landed bounded length-prefixed framing, handshake, and message-id
+  sequencing with render revisions, event sequencing, process I/O, and
   structured diagnostics
 - static TSX counter rendered through the current headless semantic path
 

docs/tsx-native-runtime.md

@@ -377,8 +377,17 @@ JSON is the protocol-1 payload encoding because it matches the current Serde
 contract and is easy to inspect. Each message is framed as a little-endian
 `u32` byte length followed by UTF-8 JSON. The receiver rejects zero-length,
 oversized, truncated, invalid UTF-8, duplicate-field, unknown-kind, and
-unsupported-version messages before state mutation. The initial maximum frame
-size is explicit in the handshake and bounded to 16 MiB or less.
+unsupported-version messages before state mutation. The initial maximum JSON
+payload size is explicit in the handshake and bounded to 16 MiB or less.
+
+Landed Rust foundation: `tsx_protocol` defines strict direction-specific
+control messages with the fixed `a3s.gui.tsx` identifier, atomic
+`TsxHostHandshakeV1` negotiation, exact per-sender `TsxMessageSequenceV1`, and
+blocking plus incremental framed JSON codecs. The decoder validates a declared
+length before allocating, becomes unusable after a framing/JSON violation, and
+has a checked end-of-stream path for partial headers and payloads. A canonical
+`hello-v1.json` fixture pins the current wire spelling. Render/event/command
+messages, actual local process I/O, and the TypeScript peer are still pending.
 
 ### Messages
 
@@ -440,10 +449,9 @@ packages/typescript/
 `- tests/
 
 src/tsx_protocol/
-|- envelope.rs
-|- message.rs
-|- framing.rs
-|- limits.rs
+|- message.rs      strict control DTOs and common envelope metadata
+|- handshake.rs    atomic capability, renderer, and limit negotiation
+|- framing.rs      limits plus blocking and incremental JSON framing
 `- tests.rs
 
 src/platform_host/       shared zero-widget host contract and OS shells
@@ -522,9 +530,9 @@ minimum M4 text/input slice.
 
 ### T0 - Contract and Architecture
 
-Status: architecture accepted; the Rust-side drop-policy DTO and resolver
-adapter are implemented. The remaining T0 review fixtures and Node-side
-transport are pending.
+Status: architecture accepted; the Rust-side strict handshake/framing boundary
+and drop-policy DTO/resolver adapter are implemented. The remaining parity
+fixtures, application message set, and Node-side transport are pending.
 
 - accept process, ownership, identity, protocol, and packaging decisions
 - pin cross-language golden frame and event fixtures
@@ -536,7 +544,12 @@ cannot bypass Native IR, layout, Graphics, interaction, or accessibility.
 
 ### T1 - Headless Protocol and JSX Core
 
-- add the bounded framed transport and handshake DTOs in Rust
+Status: Rust transport foundation in progress. `hello`/`welcome`, atomic limit
+and renderer negotiation, exact message-id sequencing, 16 MiB-capped framing,
+incremental decoding, and the first canonical JSON fixture have landed.
+
+- extend the landed bounded framing and handshake DTOs with render/event/
+  command messages and actual local process I/O
 - connect the landed strict drop-policy query/response DTOs to that transport
   and the Node callback registry
 - generate TypeScript protocol declarations from Rust DTOs

justfile

@@ -331,8 +331,8 @@ check-core-graph:
     set -euo pipefail
 
     core_graph="$(cargo tree --locked --no-default-features --prefix none)"
-    if grep -Eq '^(a3s-graphics|wgpu) ' <<<"$core_graph"; then
-        echo "graphics dependencies entered the semantic-only graph" >&2
+    if grep -Eq '^(a3s-graphics|wgpu|napi|napi-derive|neon|neon-build|node-bindgen|node-bindgen-macro|deno_core|rusty_v8) ' <<<"$core_graph"; then
+        echo "graphics or embedded JavaScript/Node dependencies entered the semantic-only graph" >&2
         exit 1
     fi
 

src/lib.rs

@@ -67,6 +67,7 @@ mod semantic_event;
 pub mod semantic_ui;
 pub mod style;
 pub mod svg;
+pub mod tsx_protocol;
 pub mod web;
 #[cfg(feature = "winui")]
 pub mod winui;
@@ -477,6 +478,7 @@ pub use style::{
     VisibilityMode, WhiteSpaceMode, WordBreakMode,
 };
 pub use svg::{SVG_ELEMENTS, SVG_TAG_METADATA_KEY};
+pub use tsx_protocol::*;
 pub use web::WebProps;
 #[cfg(feature = "winui")]
 pub use winui::{