Proposal: compile client code from real Rust to JavaScript instead of runtime expressions (working spike + benchmarks)

[GoldStrikeArch]

The problem: runtime expressions have a structural ceiling

I love how far $() expressions get with so little machinery, but after building a few non-trivial islands I keep hitting the same two walls, and I think they are structural rather than incremental.

The surface is an expression subset, not a language. A runtime expression is one syn::Expr transliterated to a JavaScript string. There is no match, no for, no if statements, no structs or enums, no arrays, no ?, no assignment, not even &&/||. Integers are a compile error; there is one number type. Anything with a loop or a data structure (a filterable list, a grid, a state machine) cannot be written client-side today.

Correctness is by naming convention, checked nowhere. Every operation in the shared vocabulary is implemented twice: once in the Rust surrogate types and once in the TypeScript browser surrogates. The compiler never checks that the two sides agree; it only checks that the Rust side typechecks against the surrogate mirror. Whenever the two implementations disagree, the same $() expression evaluates differently on the server and in the browser. The tracker already shows this bug class:

• String comparison in reactive expressions disagrees between server and client #236
• f64 text rendering differs between server and client #237
• trim() strips U+FEFF in the browser but not on the server #238
• Define and test Unicode semantics for shared String methods #125
• Capturing a tuple in a runtime expression throws at hydration #254: this is because the deserializer has no array case (still open but there is a fix in fix(runtime): hydrate a tuple captured by a runtime expression #255)

Each of these got fixed individually, but the design keeps generating them: every new vocabulary method is a new chance for the two implementations to drift.

On top of those two walls: state crosses to the client as one-time JSON snapshots (signals are the only live handles), the hand-written browser runtime scans the DOM once so HTML swapped in by anything else silently loses its bindings, and third-party JavaScript is a script tag plus globals.

What I tried

I spent some time on a spike: a rustc codegen backend that compiles monomorphized MIR to readable JavaScript, targeting the dom-expressions runtime that SolidJS is built on. The idea is the solid-start shape with Rust as the language: the server stays exactly today's Topcoat (hyper, view!, SSR), and client components become real Rust functions compiled to JS. No WASM, no Node in the user's toolchain, no bundler in the serving path.

What compiles today: structs, enums, tuples, arrays, slices, closures, dyn and vtables, drop glue, generics, recursion, per-width integer semantics (BigInt for i64/u64/i128), Box, Vec, String, format!, Rc/Arc, iterators and sort, real async fn/.await, and panics with #[track_caller] locations. It builds the real core and alloc into a sysroot; there are no surrogate types. Unsupported constructs (byte punning, threads, std) use a reachability-gated error system borrowed from rust-gpu: they only fail your build if your code actually reaches them, with a call chain in the message.

On the framework side: view! gained a third emitter that produces dom-expressions calls, the client runtime is the real solid-js 1.9.14 (one 9.1 KB gzip bundle), and the server emitter and the compiled client allocate identical hydration keys, enforced by a jsdom parity harness that asserts node identity. #[island] gives per-island chunks with lazy hydration, #[procedure] works from compiled code over a typed serde wire, and #[js_extern] declares foreign JavaScript with checked shapes and .d.ts emission.

The emitted JavaScript is meant to be read: names come from debug info, the output goes through an expression queue and destination-passing codegen so it does not look machine generated, and source maps step back through the original Rust in DevTools. Example of real compiled output:

function area(r) {
  return Math.imul(r.w, r.h) | 0;
}

Live demos

Everything below is served at https://goldstrikearch.github.io/topcoat/ and compiled from Rust, so the islands contain zero hand-written JavaScript. Source code is here

• /island/showcase/: Game of Life, falling sand on a canvas, and Minesweeper with recursive flood fill and none of these is expressible in the current expression language
• /bench/: the js-framework-benchmark app as an island

Benchmarks

I ran the full upstream krausest js-framework-benchmark harness locally over six implementations, with every reference implementation matching its published numbers. Full tables and methodology are in bench/RESULTS.md; the run is reproducible via bench/setup.sh && bench/run.sh with committed pins.

implementation	geomean vs vanillajs keyed	transferred (brotli)	first paint
vanillajs keyed	1.00	2.5 KB	53.7 ms
vanillajs non-keyed	0.85	2.4 KB	58.3 ms
topcoat-vanilla (compiled Rust, direct DOM)	0.98	9.8 KB	81.6 ms
solid keyed	1.15	4.5 KB	58.9 ms
leptos keyed (WASM)	1.16	48.8 KB	241.1 ms
topcoat-island (idiomatic view!)	2.76	21.2 KB	47.9 ms

Compiled Rust runs at hand-written JavaScript speed: topcoat-vanilla lands ahead of Solid and of Leptos on the geometric mean, at a fifth of Leptos's wire weight and a third of its first paint. And topcoat-island posts the fastest first paint of the entire field because the server already rendered the page; its 2.76 geomean is the known cost of the unkeyed list model on three specific operations (partial update, select, swap), discussed under limitations. A counter-only page pays about 14 KB gzip total including the shared runtime.

What this buys over today

• Client code gets the whole language: loops, match, structs, enums, collections, recursion and async all run in the browser (the showcase programs are the proof)
• One semantics instead of two: rustc typechecks client code against the real core, and the compiler implements Rust semantics in the output. Those bug classes above disappears by construction because there is no second implementation to drift.
• An FFI story: #[js_extern] with checked shapes and .d.ts output replaces call-a-global-and-hope; #[repr(C)] structs cross as plain objects with no converter layer.
• Real hydration: the real Solid runtime (yes, it is a real solid-js runtime :D) replaces the one-shot DOM scan, and per-island chunks mean a page pays only for the islands it has.
• Debuggability: the emitted JS is reviewable and source maps step through the original Rust (you can also see it in demos).
• It is additive: the existing runtime and $() path are untouched; the spike coexists with them.
• The performance is superior to what you will write in JS by hand (as we can make way more optimizations)

Limitations

• The backend pins one rustc nightly forever, the rust-gpu maintenance model. I didn't dig too much into it, whether it can be solved or not
• npm package resolution is not built; only single-file ESM or vendored libraries work. Closures cannot yet cross #[js_extern] (a small hand-written bootstrap covers addEventListener cases; the benchmark entry's is 22 lines)
• panic=abort only, no unwinding yet
• Permanently out by architecture: byte punning across representations (f64 through serde, TypeId, SIMD), threads, std itself.

Questions

1. Is compiled-Rust-to-JavaScript a direction Topcoat wants for the client story, in principle?
2. Any objection to solid-js as the target runtime? It was chosen because signals match Topcoat's model and its hydration contract could be extracted into an executable test suite.
3. The spike is additive today. Is coexistence with $() expressions the right long-term shape, or would maintainers want convergence?
4. What would the distribution story need to look like (prebuilt backends per release channel, toolchain pinning UX) before a serious upstreaming conversation makes sense?

Happy to go as deep as anyone wants on any of this. The branch, the compiler spec and the benchmark harness are all public:

• branch: https://github.com/GoldStrikeArch/topcoat/tree/spike/rust-js/spike/rustc-codegen-js
• compiler spec (value model, heap, templates, FFI): CONTRACT.md
• benchmark tables: bench/RESULTS.md

[AmeinEskinder]

Four of the five issues in your bug-class list are mine, so let me add the part the tracker doesn't show: how each was actually found. I think that bears on the argument more than the count does.

One correction first — #254 has a fix open at #255. The issue is open; the fix isn't merged. I'd rather that read accurately than more damningly than it deserves.

#236 and #238 were found by reading the two implementations side by side. That's the honest case for "a careful reviewer catches these."

#237 is the one I'd point at. It reported four divergences, and fixing them was routine. But building a differential harness against rustc turned up a fifth nobody had seen: when two equally short digit strings are exactly equidistant from the value, ECMAScript resolves the tie to the even final digit and Rust resolves it away from zero, so 1690060720831323.25 renders …323.3 on the server and …323.2 in the browser. Three mismatches in the first 20,027 random doubles. It is invisible to reading — the reporter missed it, I missed it, and it only surfaced against a 300,016-value comparison with real Display output.

#254 I found by hunting the class rather than by hitting it: diffing the surrogate method sets between the two sides looking for asymmetries. tuple.rs exists on the Rust side with no tuple.ts; the grammar compiles pair.0 to pair[0]; hydrateSurrogate has no array case. One deliberate pass produced a live one.

The strongest evidence I can offer, though, is a mitigation I wrote rather than a bug I found. #270 adds a Decimal with independent comparators in both languages, and I pinned them together with a shared comparison table asserted on both sides — precisely because I did not trust two implementations of one algorithm to stay in sync across a release. That is a design property being papered over, and I am the one who wrote the paper.

Two honest counterweights. Each instance was cheap to fix, and parity tests now exist for the methods involved, so the standing exposure is new vocabulary rather than the current surface. And I should disclose that I have open PRs in the layer this proposal would replace (#255, #269, #270, #271), so I am not a neutral party on whether it should be replaced.

Whether four in a week is a rate that justifies a change this size is a judgement I don't think a contributor should make on your behalf. But the diagnosis matches what I found from the inside.

[GoldStrikeArch]

@AmeinEskinder

Thank you! This is a better account of the bug class than my summary, from the person who actually did the fixing. I've updated the issue so #254 reads with "fix open at #255".

And I should disclose that I have open PRs in the layer this proposal would replace (#255, #269, #270, #271), so I am not a neutral party on whether it should be replaced.

To be clear on the scope of this issue: the whole spike is additive and nothing here proposes replacing current work. The demos exist to establish what a real compiler path makes possible so maintainers can judge the direction. Whether and how it lands is a separate discussion and unlikely to happen "fast" (if it will happen at all 😅 ) as first of all the whole spike was just a research, the compiler is real, it works but I only tested a subset of possible "common programs" you can make. There are likely a lot of edge cases missed and so on. It can be a "separate track" within this repo, so it can replace $() expressions at some point or run side-by-side (again, depends on how maintainers would take it, maybe they will say "thanks, but no" which is also a valid answer)