feat: add automatic TSX runtime core

Author: Roy Lin

.github/workflows/ci.yml

@@ -41,6 +41,10 @@ jobs:
           node-version: "24"
           package-manager-cache: false
 
+      - name: Install TypeScript SDK development dependencies
+        shell: bash
+        run: npm --prefix packages/typescript ci --ignore-scripts
+
       - name: Run local verification gate
         shell: bash
         run: just verify

.gitignore

@@ -1 +1,2 @@
 /target/
+/packages/typescript/node_modules/

README.md

@@ -6,24 +6,26 @@
   <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 protocol SDK" src="https://img.shields.io/badge/TSX-T1%20protocol%20SDK-1687D9?style=flat-square">
+  <img alt="TSX milestone T1 JSX core" src="https://img.shields.io/badge/TSX-T1%20JSX%20core-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>
 
 **A3S GUI** is a Rust-native, cross-platform semantic UI and rendering runtime.
-Rust RSX is available today; a planned `@a3s/gui` automatic JSX runtime will
-let standard TSX executed by Node or Nub feed the same native pipeline. Neither
-path uses a DOM, CSSOM, WebView, or framework-owned content renderer.
+Rust RSX is available today; a private headless `@a3s/gui` automatic JSX core
+now lets standard TSX lower into the same versioned native frame vocabulary.
+Neither path uses a DOM, CSSOM, WebView, or framework-owned content renderer.
 
 > [!IMPORTANT]
 > The repository is in its P0 renderer migration. The semantic runtime and
 > 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. 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.
+> roadmap work. Rust-generated TypeScript wire declarations, automatic JSX
+> entry points, strict element/frame normalization, and cross-language counter
+> gates now exist in a private development package. The committed callback
+> registry, state/hooks, executable process host, and publishable npm packages
+> do not; this is not yet a runnable native TSX application. React Aria
+> component parity is not claimed yet.
 
 The target is unambiguous: A3S draws all application content. The existing
 `appkit-native`, `gtk4-native`, and `winui-native` modules create controls only
@@ -98,7 +100,7 @@ contract.
 
 ## TSX to native, without a browser
 
-The planned TypeScript path follows
+The in-progress 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
@@ -152,9 +154,14 @@ 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.
+parsed and byte-canonicalized in both Rust and Node 24. The private automatic
+JSX runtime now expands synchronous function components, normalizes elements,
+children, keys, props, styles, windows, and callbacks, and produces that exact
+counter render fixture; pinned TypeScript 5.9 compiles the corresponding real
+TSX source. Rust now proves the complete compiled counter trees are equal
+before Native IR and accessibility parity. Actual process I/O, committed and
+rollback callback scopes, state/hooks, the native host, 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,
@@ -366,7 +373,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 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 |
+| T0-T5 · TSX native authoring | T1 headless JSX core in progress | Strict handshake/framing, transactional render/commit/event messages, self-drawn adapters, safe JSON integer/fingerprint encoding, Rust-generated declarations, standard JSX entry points, strict element/frame normalization, TypeScript/Node golden gates, counter parity, and the drop-policy bridge landed; process I/O, committed callback scopes/state, calculator parity, native host, 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

docs/architecture.md

@@ -982,10 +982,15 @@ 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.
+module in Node 24, exposes standard automatic JSX entry points, normalizes
+immutable elements into canonical protocol frames, and independently
+canonicalizes the Rust golden fixtures. Pinned TypeScript 5.9 also type-checks
+a real `react-jsx`/`jsxImportSource` counter fixture. Function event props are
+replaced by deterministic action ids and retained only in a read-only
+per-frame callback snapshot.
 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.
+renderer, or OS-toolkit dependency; committed callback scopes, commands,
+process I/O, and the Node session 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/roadmap.md

@@ -628,8 +628,11 @@ transactional render/commit/event session, self-drawn snapshot/event adapters,
 counter golden/parity fixtures, and revision-scoped drop-policy
 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.
+Rust/Node fixture gates have also landed. The automatic JSX entry points,
+synchronous function-component expansion, strict frame normalization,
+callback-to-action lowering, and real TSX type gate are now included. Process
+I/O, committed callback scopes, state/hooks, the native host, and a 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
@@ -672,11 +675,15 @@ 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.
-
-- automatic `jsx-runtime` and `jsx-dev-runtime` exports
-- deterministic child, prop, key, and event normalization
+fingerprint. Standard automatic JSX entry points, immutable elements,
+synchronous function-component expansion, strict child/key/prop/style/window
+normalization, deterministic callback-to-action ids, and read-only per-frame
+callback snapshots now lower into those declarations. Node 24 canonicalizes
+the same four fixtures, while pinned TypeScript 5.9 type-checks a real
+`react-jsx`/`jsxImportSource` counter; the package has no production dependency
+or install script.
+
+- committed/rollback callback scopes and ordered event-vector dispatch
 - 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 the calculator fixture

docs/tsx-native-runtime.md

@@ -1,8 +1,11 @@
 # TSX to Native Runtime Architecture
 
-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.
+Status: proposed API; the T1 headless JSX core is in progress. A private
+development package now contains Rust-generated wire declarations, standard
+automatic JSX entry points, synchronous function-component and child/key/prop
+normalization, deterministic frame lowering, and cross-language golden tests.
+The revision-scoped callback registry, state/hooks, process session, and
+executable native host are not implemented yet.
 
 This document defines an optional TypeScript authoring path for A3S GUI. The
 developer experience is a directly executable `.tsx` application:
@@ -401,9 +404,11 @@ Its feature-gated adapters project `SelfDrawnFrameSnapshot` and
 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.
+wire spelling in Rust and Node 24 tests. The private TypeScript peer now
+provides standard automatic JSX entry points, synchronous function-component
+expansion, strict normalization, deterministic frame lowering, and a pinned
+TypeScript 5.9 `react-jsx` fixture. Command messages, actual local process I/O,
+committed callback scopes, state/hooks, and host supervision remain pending.
 
 ### Messages
 
@@ -559,8 +564,9 @@ 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
-commands, JSX execution, and Node-side transport are pending. Rust-generated
-declarations and shared Rust/Node counter fixtures are implemented.
+commands, stateful JSX execution, revision-scoped callbacks, and Node-side
+transport are pending. Rust-generated declarations, the headless automatic
+JSX core, and shared Rust/Node counter fixtures are implemented.
 
 - accept process, ownership, identity, protocol, and packaging decisions
 - retain the landed shared Rust/Node golden frame/event gate and extend it to
@@ -580,14 +586,17 @@ session ordering, self-drawn adapters, four canonical JSON fixtures, and the
 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.
+skeleton, automatic `jsx-runtime`/`jsx-dev-runtime`, immutable element records,
+synchronous function-component expansion, strict child/key/prop/style/window
+normalization, deterministic callback-to-action ids, read-only callback
+snapshots, and Node 24 plus TypeScript 5.9 golden/type tests have also landed.
 
 - extend the landed application messages with command messages and actual
   local process I/O
+- promote the landed per-frame callback snapshot into committed/rollback
+  revision scopes and dispatch ordered event vectors against it
 - connect the landed strict drop-policy query/response DTOs to that transport
   and the Node callback registry
-- 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 the calculator scenario
 
 Gates:
@@ -665,7 +674,7 @@ green.
 
 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.
+3. Add the automatic JSX runtime with normalization and key tests. Landed.
 4. Add action ids, callback scopes, and event-vector dispatch.
 5. Add the headless host binary and a static TSX counter fixture.
 6. Add state/reducer/effect scheduling and counter interaction tests.

justfile

@@ -309,7 +309,7 @@ check-tsx-protocol:
     cargo run --locked --quiet --no-default-features --features typescript-schema --bin a3s-gui-generate-tsx-protocol -- --check
     cargo test --locked --no-default-features --features typescript-schema --lib tsx_protocol::typescript::
 
-# Run dependency-free cross-language protocol fixture tests
+# Type-check automatic TSX and run dependency-free runtime/fixture tests
 test-typescript:
     npm --prefix packages/typescript test
 

packages/typescript/README.md

@@ -1,19 +1,38 @@
 # @a3s/gui TypeScript development package
 
-This private package currently contains the generated protocol-v1 declarations
-and cross-language golden tests only. It is not a published SDK and does not yet
-provide `jsx-runtime`, `jsx-dev-runtime`, a Node process host, components, hooks,
-or a callback registry.
+This private package contains the first headless protocol-v1 JSX core. It now
+provides the standard `jsx-runtime` and `jsx-dev-runtime` entry points,
+immutable A3S element records, synchronous function-component expansion,
+fragment/child/key/prop normalization, preview `Window`/`View`/`Text`/`Button`
+tokens, and deterministic lowering to the Rust-generated
+`ProtocolUiFrameV1` declarations.
+
+Function event props become collision-safe action ids. Their functions are
+retained in a read-only callback snapshot and never enter JSON. That snapshot
+is not yet the committed/rollback revision registry: event-vector dispatch,
+state/hooks, the Node process session, the native host executable, and the
+stable full semantic component API remain later delivery slices. This package
+is therefore not a published SDK or a runnable native TSX application yet.
+
+Install the pinned development compiler without running dependency scripts:
+
+```sh
+npm ci --ignore-scripts
+```
 
 Regenerate the protocol module from the Rust DTO source of truth:
 
 ```sh
 just generate-tsx-protocol
 ```
 
-Check drift and run the dependency-free Node fixture tests:
+Check declaration drift, compile the real automatic-runtime TSX fixture, and
+run the dependency-free Node runtime/golden tests:
 
 ```sh
 just check-tsx-protocol
 just test-typescript
 ```
+
+The TypeScript package has no production dependencies or install scripts. The
+pinned TypeScript compiler is a test-only development dependency.

packages/typescript/package-lock.json

@@ -4,8 +4,20 @@
   "private": true,
   "description": "Development-only TypeScript protocol package for the A3S self-drawn GUI runtime",
   "type": "module",
-  "types": "./src/generated/protocol.ts",
+  "types": "./src/index.ts",
   "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./jsx-runtime": {
+      "types": "./src/jsx-runtime.d.ts",
+      "default": "./src/jsx-runtime.ts"
+    },
+    "./jsx-dev-runtime": {
+      "types": "./src/jsx-dev-runtime.d.ts",
+      "default": "./src/jsx-dev-runtime.ts"
+    },
     "./protocol": {
       "types": "./src/generated/protocol.ts",
       "default": "./src/generated/protocol.ts"
@@ -15,6 +27,11 @@
     "node": ">=24"
   },
   "scripts": {
-    "test": "node --test tests/*.test.mjs"
+    "typecheck": "tsc -p tsconfig.json",
+    "test:runtime": "node --test tests/*.test.mjs",
+    "test": "npm run typecheck && npm run test:runtime"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3"
   }
 }