feat: generate TSX protocol declarations

Author: Roy Lin

.gitattributes

@@ -0,0 +1 @@
+packages/typescript/src/generated/protocol.ts text eol=lf

.github/workflows/ci.yml

@@ -35,6 +35,12 @@ jobs:
         shell: bash
         run: cargo install just --locked
 
+      - name: Install Node.js LTS
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          package-manager-cache: false
+
       - name: Run local verification gate
         shell: bash
         run: just verify

Cargo.lock

@@ -18,6 +18,11 @@ path = "src/lib.rs"
 name = "a3s-gui-native-input-conformance"
 path = "src/bin/native_input_conformance.rs"
 
+[[bin]]
+name = "a3s-gui-generate-tsx-protocol"
+path = "src/bin/generate_tsx_protocol.rs"
+required-features = ["typescript-schema"]
+
 [[bin]]
 name = "a3s-gui-winui-input-smoke"
 path = "src/bin/winui_input_smoke.rs"
@@ -111,6 +116,7 @@ authoring = [
     "dep:swc_ecma_parser",
 ]
 design-system = ["authoring"]
+typescript-schema = ["dep:ts-rs"]
 appkit = []
 appkit-native = [
     "appkit",
@@ -146,6 +152,7 @@ swc_atoms = { version = "9.0.3", optional = true }
 swc_common = { version = "23.0.2", optional = true }
 swc_ecma_ast = { version = "25.0.0", optional = true }
 swc_ecma_parser = { version = "41.1.2", optional = true }
+ts-rs = { version = "12.0.1", optional = true, default-features = false, features = ["serde-compat", "no-serde-warnings"] }
 writeable = "0.6.3"
 
 [dev-dependencies]

Cargo.toml

@@ -6,7 +6,7 @@
   <a href="https://github.com/A3S-Lab/GUI/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/A3S-Lab/GUI/actions/workflows/ci.yml/badge.svg"></a>
   <img alt="Rust 1.95.0" src="https://img.shields.io/badge/Rust-1.95.0-2F3945?style=flat-square&logo=rust&logoColor=white">
   <img alt="Roadmap milestone M3 current" src="https://img.shields.io/badge/roadmap-M3%20current-0067C0?style=flat-square">
-  <img alt="TSX milestone T1 Rust foundation" src="https://img.shields.io/badge/TSX-T1%20Rust%20foundation-1687D9?style=flat-square">
+  <img alt="TSX milestone T1 protocol SDK" src="https://img.shields.io/badge/TSX-T1%20protocol%20SDK-1687D9?style=flat-square">
   <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-2F3945?style=flat-square"></a>
 </p>
 
@@ -20,8 +20,9 @@ path uses a DOM, CSSOM, WebView, or framework-owned content renderer.
 > AppKit/GTK4/WinUI control hosts are established dogfood baselines. The first
 > generic self-drawn layout-to-Scene slice has landed; self-drawn text shaping,
 > editing/IME, accessibility bridges, and real thin-host presentation remain
-> roadmap work. The TypeScript runtime, executable process host, and npm
-> packages have not been implemented yet; the landed Rust TSX protocol is not
+> roadmap work. Rust-generated TypeScript wire declarations and a private
+> development package now exist, but the JSX runtime, executable process host,
+> callback/state runtime, and publishable npm packages do not; this is not yet
 > a runnable TSX application. React Aria component parity is not claimed yet.
 
 The target is unambiguous: A3S draws all application content. The existing
@@ -146,12 +147,16 @@ render, host-frame, and event sequences before mutation, preserves the active
 revision after a rejected frame, and maps self-drawn snapshots and dispatches
 directly. 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. Canonical hello, counter render,
-commit, and event fixtures plus a Rust RSX/TSX Native IR and accessibility
-parity test pin this slice. Actual process I/O, TypeScript declarations, JSX
-runtime, callback registry, and packages remain. The design keeps component
-state and callbacks in Node, platform/GPU handles inside a separate Rust
-process, and Rust as the only native reconciler. Read the
+unknown-kind, and unsupported-protocol input. Numeric `u64` wire values are
+bounded to JavaScript's exact integer range; arbitrary layout/scene
+fingerprints are fixed 16-digit lowercase hexadecimal strings. Rust DTOs now
+generate the checked-in `@a3s/gui/protocol` declarations and declaration
+fingerprint. Canonical hello, counter render, commit, and event fixtures are
+parsed and byte-canonicalized in both Rust and Node 24, while a Rust RSX/TSX
+Native IR and accessibility parity test pins the semantic slice. Actual process
+I/O, the JSX runtime, callback registry/state, and publishable packages remain.
+The design keeps component state and callbacks in Node, platform/GPU handles
+inside a separate Rust process, and Rust as 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.
 
@@ -361,7 +366,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 | T1 Rust foundation in progress | Strict handshake/framing, transactional render/commit/event messages, self-drawn snapshot/dispatch adapters, counter golden/parity fixtures, and revision-scoped drop-policy bridge landed; process I/O, TypeScript declarations, JSX runtime, Node callback registry/state, packages, and stable SDK remain |
+| T0-T5 · TSX native authoring | T1 protocol SDK in progress | Strict handshake/framing, transactional render/commit/event messages, self-drawn adapters, safe JSON integer/fingerprint encoding, Rust-generated TypeScript declarations with drift CI, private package skeleton, counter golden/parity fixtures, and revision-scoped drop-policy bridge landed; process I/O, JSX runtime, Node callback registry/state, calculator parity, 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
@@ -478,6 +483,10 @@ crate root.
 # Graphics paths, examples, and whitespace.
 just verify
 
+# Focused Rust-to-TypeScript declaration and Node fixture gates.
+just check-tsx-protocol
+just test-typescript
+
 # Matching host-native library tests and all-target compile check.
 just native-ci
 ```
@@ -490,6 +499,7 @@ just native-input-conformance path/to/native-evidence.json
 just winui-input-smoke path/to/winui-smoke.json
 ```
 
+The cross-language fixture gate uses Node 24 LTS and has no npm dependencies.
 The WinUI smoke runner requires an interactive Windows desktop and Windows App
 Runtime 1.7. AppKit and GTK4 native checks require their matching host
 toolchains; GTK4 requires 4.14 or newer development libraries.
@@ -505,7 +515,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/framing plus transactional render, commit, and event sessions
+|- tsx_protocol/         strict session DTOs plus Rust-owned TypeScript declaration generation
 |- native.rs             portable NativeElement UI IR
 |- layout/               deterministic records, style projection, diffs, and tests
 |- drawing.rs            Graphics boundary and reference/GPU renderer wrappers
@@ -518,6 +528,7 @@ src/
 `- *_native/             AppKit, GTK4, and WinUI control hosts during migration
 
 examples/                headless, self-drawn, calculator, dogfood, controls, and playground apps
+packages/typescript/     private @a3s/gui protocol declarations and cross-language fixtures
 docs/                    architecture, contracts, packaging, language, and roadmap
 packaging/               unsigned native smoke-bundle assets and validators
 ```

README.md

@@ -977,9 +977,15 @@ committed state on validation or response-encoding failure. It tracks the TSX
 callback-scope revision separately from the self-drawn host snapshot revision,
 so callback-only rerenders can reuse identical Native IR safely. Feature-gated
 adapters consume `SelfDrawnFrameSnapshot` and `SelfDrawnInputDispatch`
-directly. The feature-independent foundation has no Node, Nub, N-API,
-Graphics, legacy renderer, or OS-toolkit dependency; commands, process I/O,
-generated TypeScript, and the Node implementation remain T1 work.
+directly. All numeric `u64` wire values are rejected above JavaScript's safe
+integer limit, while arbitrary layout/scene fingerprints use lossless fixed
+hexadecimal strings. An optional build-only `typescript-schema` feature walks
+the Rust DTO graph, emits a deterministically ordered declaration module, and
+pins it with an FNV-1a fingerprint. A private TypeScript package imports that
+module in Node 24 and independently canonicalizes the Rust golden fixtures.
+The feature-independent foundation has no Node, Nub, N-API, Graphics, legacy
+renderer, or OS-toolkit dependency; commands, process I/O, the JSX runtime,
+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

docs/architecture.md

@@ -626,8 +626,10 @@ Gates:
 Status: architecture accepted; the Rust-side strict handshake/framing,
 transactional render/commit/event session, self-drawn snapshot/event adapters,
 counter golden/parity fixtures, and revision-scoped drop-policy
-protocol/resolver adapter have landed. Process I/O, generated TypeScript, the
-JSX runtime, Node callback registry, and visible TSX application remain.
+protocol/resolver adapter have landed. Rust-generated TypeScript declarations,
+a fixed schema fingerprint, a private `@a3s/gui` package skeleton, and shared
+Rust/Node fixture gates have also landed. Process I/O, 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
@@ -653,7 +655,7 @@ decisions are recorded in
 - reuse the resolved `ProtocolUiFrameV1` input vocabulary behind a new TSX
   session envelope
 - extend the landed Rust RSX/static-TSX counter parity fixture to the
-  calculator and generated TypeScript CI
+  calculator; generated TypeScript and Node fixture CI now cover the counter
 
 Gate: TSX is a peer authoring frontend and cannot bypass Native IR, layout,
 Graphics, interaction, accessibility, or capability checks.
@@ -667,14 +669,17 @@ self-drawn host revisions, 16 MiB-capped little-endian framing, incremental
 decoding, four canonical JSON fixtures, and static counter Native
 IR/accessibility parity have landed. The core remains free of Node and Graphics
 dependencies; self-drawn conversions compile only with `platform-runtime`.
+All numeric `u64` fields are bounded to JavaScript's safe integer range, full
+64-bit scene/layout fingerprints use fixed hexadecimal strings, and optional
+`typescript-schema` generation now produces the checked-in declarations and
+fingerprint. Node 24 independently imports that module and canonicalizes the
+same four fixtures without an npm dependency.
 
-- generated TypeScript declarations from versioned Rust DTOs
 - automatic `jsx-runtime` and `jsx-dev-runtime` exports
 - deterministic child, prop, key, and event normalization
 - add command messages, local process I/O, and generated structured diagnostic
   declarations to the landed application session
-- extend the landed static counter semantic parity to TypeScript CI and the
-  calculator fixture
+- extend the landed static counter semantic parity to the calculator fixture
 
 Gates:
 

docs/roadmap.md

@@ -1,7 +1,8 @@
 # TSX to Native Runtime Architecture
 
-Status: proposed API; the Rust T1 protocol foundation is in progress. No
-TypeScript package or executable TSX host is implemented yet.
+Status: proposed API; the T1 protocol SDK foundation is in progress. A private
+development package contains Rust-generated wire declarations and tests, but
+no JSX runtime or executable TSX host is implemented yet.
 
 This document defines an optional TypeScript authoring path for A3S GUI. The
 developer experience is a directly executable `.tsx` application:
@@ -380,6 +381,10 @@ contract and is easy to inspect. Each message is framed as a little-endian
 oversized, truncated, invalid UTF-8, duplicate-field, unknown-kind, and
 unsupported-version messages before state mutation. The initial maximum JSON
 payload size is explicit in the handshake and bounded to 16 MiB or less.
+Every numeric `u64` field is also bounded to `Number.MAX_SAFE_INTEGER` before
+transport. Layout and scene fingerprints may use all 64 bits, so they cross the
+JSON boundary as exactly sixteen lowercase hexadecimal digits instead of
+lossy numbers.
 
 Landed Rust foundation: `tsx_protocol` defines strict direction-specific
 control messages with the fixed `a3s.gui.tsx` identifier, atomic
@@ -393,9 +398,12 @@ ordered `event` batches, permits exactly one render in flight, and leaves the
 active revision unchanged on validation, host, or response-encoding failure.
 Its feature-gated adapters project `SelfDrawnFrameSnapshot` and
 `SelfDrawnInputDispatch` directly; no planned-widget response is involved.
-Canonical hello, counter render, committed, and event fixtures pin the wire
-spelling. Command messages, actual local process I/O, generated TypeScript,
-and the TypeScript peer remain pending.
+The optional `typescript-schema` feature walks these Rust DTOs, writes one
+deterministically ordered TypeScript module, and fingerprints its declaration
+body. Canonical hello, counter render, committed, and event fixtures pin the
+wire spelling in Rust and in dependency-free Node 24 tests. Command messages,
+actual local process I/O, the JSX runtime, and the TypeScript peer remain
+pending.
 
 ### Messages
 
@@ -551,10 +559,12 @@ minimum M4 text/input slice.
 Status: architecture accepted; the Rust-side strict handshake/framing,
 render/commit/event session, counter parity fixtures, self-drawn adapters, and
 drop-policy DTO/resolver adapter are implemented. Calculator and
-cross-language fixtures, commands, and Node-side transport are pending.
+commands, JSX execution, and Node-side transport are pending. Rust-generated
+declarations and shared Rust/Node counter fixtures are implemented.
 
 - accept process, ownership, identity, protocol, and packaging decisions
-- extend the landed Rust golden frame/event fixtures into cross-language CI
+- retain the landed shared Rust/Node golden frame/event gate and extend it to
+  the calculator scenario
 - define the first counter and calculator parity scenarios
 - record unsupported React and browser behaviors explicitly
 
@@ -567,17 +577,18 @@ Status: Rust transport foundation in progress. `hello`/`welcome`, atomic limit
 and renderer negotiation, exact message-id sequencing, 16 MiB-capped framing,
 incremental decoding, strict `render`/`committed`/`event` DTOs, transactional
 session ordering, self-drawn adapters, four canonical JSON fixtures, and the
-static counter Native IR/accessibility parity test have landed.
+static counter Native IR/accessibility parity test have landed. Safe-integer
+validation, hexadecimal 64-bit fingerprints, deterministic Rust-generated
+TypeScript declarations, a fixed schema fingerprint, the private package
+skeleton, and Node 24 declaration/fixture tests have also landed.
 
 - extend the landed application messages with 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
 - publish local development exports for `jsx-runtime` and `jsx-dev-runtime`
 - implement element/child/prop normalization, keys, and action registration
-- extend the landed static counter parity fixture to generated TypeScript CI
-  and the calculator scenario
+- extend the landed static counter parity fixture to the calculator scenario
 
 Gates:
 
@@ -652,8 +663,8 @@ green.
 
 ## First Reviewable Commit Sequence
 
-1. Add session DTOs, framing limits, and protocol golden fixtures.
-2. Add generated TypeScript wire declarations and drift CI.
+1. Add session DTOs, framing limits, and protocol golden fixtures. Landed.
+2. Add generated TypeScript wire declarations and drift CI. Landed.
 3. Add the automatic JSX runtime with normalization and key tests.
 4. Add action ids, callback scopes, and event-vector dispatch.
 5. Add the headless host binary and a static TSX counter fixture.