Projected zero-copy hydration: emit only the hydratable state surface

[mohamedmansour]

Problem

Every SSR render re-serialized the entire application state into the #webui-data bootstrap <script> block — even though the client only ever hydrates a small @observable/@attr subset. For a ~1MB state payload that is a full, wasteful serde_json serialization pass on every render, and it was the dominant startup CPU cost on webui-node (and every other host).

Approach — move the decision to build time, apply zero-copy at runtime

BUILD (once)                              RENDER (every request)
────────────                              ──────────────────────
scan sibling .ts  ─┐                      full state ──► project to schema ──► #webui-data
  @observable/@attr │  union → sorted,       (Value)      (binary_search over    (only hydratable
template roots (tr) ─┘  deduped allowlist                  sorted allowlist)       keys emitted)
        │                    │
        └──► WebUIProtocol.hydration_schema (protobuf field 6)

• Build time: the WebUI parser plugin scans each component's sibling .ts for @observable/@attr fields, unions them with the template reactive roots, and aggregates a sorted/deduped WebUIProtocol.hydration_schema.
• Render time: the handler projects the full state object down to that allowlist via a zero-alloc binary_search and serializes only the projected bag (reusing the existing buffered </-escape). The full state is still parsed once because templates render HTML from it — that parse is legitimate and unchanged; only the redundant re-serialization of the whole tree into the script block is removed.

Over-inclusion is harmless (the client ignores unknown keys), so the schema is a safe superset — no field a component needs is ever dropped. No backwards compatibility is kept: the bootstrap block now contains only the hydratable surface.

Evidence

webui-node end-to-end (real addon, contact-book-manager, 1MB payload)

Scenario	render() wall-clock	#webui-data size
1MB in a server-only field (projected out)	0.852 ms/op	16,130 bytes
1MB in a hydratable field (old full-emit)	2.575 ms/op	1,064,703 bytes
small state (floor)	0.126 ms/op	—

→ 3.0× faster, −1.72 ms/op on the node render path when a large server-only field is projected out. The residual 0.85 ms is the mandatory serde_json::from_str(1MB) that feeds HTML rendering — not waste. CPU now tracks the hydratable surface, not the total payload size.

bootstrap_state_bench (render-isolation, Rust, --release)

Payload	projected_typical (the win)	projected_full (anti-regression guard)	without_plugin (floor)
64 KB	738 ns	66.0 µs	82 ns
256 KB	715 ns	269 µs	79 ns
1 MB	691 ns	1.88 ms	74 ns

projected_typical stays flat (~700 ns) from 64 KB to 1 MB because it only serializes the metadata-sized hydratable subset. projected_full (every key marked hydratable) scales with payload and reproduces the old cost — proving projection is what saves it, and that we don't regress when everything genuinely is hydratable. (Criterion's red "regressed" deltas are noise from a shared, contended dev box; this bench exercises only render-side code, which is unchanged by the build-time scanner work.)

Host + example coverage (all green)

Projection is verified end-to-end on every host that renders a protocol:

• node — render_projects_state_to_hydration_schema
• wasm — render_projects_state_to_hydration_schema
• ffi — handler_render_projects_state_to_hydration_schema (real C ABI)
• dotnet — Handler_Render_ProjectsStateToHydrationSchema (real C ABI via a committed protobuf fixture; 7/7 C# tests pass)
• example apps — contact_book_manager_projects_hydration_surface, commerce_projects_hydration_surface build the real apps and assert the schema + projected render.

WebUIRenderer/webui_render (one-shot, no schema) is unaffected; dotnet needed zero binding-code changes — it is a pure FFI consumer, so the win lands automatically.

Scanner robustness (webui-parser/src/hydration.rs)

A deterministic, allocation-light byte scanner — no regex, no recursion, no unwrap/expect, UTF-8-safe slicing, and safe on truncated input. Handles the real authoring shapes: TS member modifiers (public/readonly/…), get/set accessors, definite-assignment (subtotal!: string), decorator factories (@attr({ attribute: 'x' })), stacked decorators, inter-token comments, and semicolon-less fields. 27 unit tests. The scanner deliberately biases toward over-inclusion because a miss silently breaks hydration.

Deep review + fixes

A full-branch code review found no blocking issues and flagged three under-inclusion gaps, all fixed here:

1. (SHOULD-FIX) A sibling .ts/.js that exists but can't be read (I/O error or non-UTF-8) previously fell through to has_script = false, silently downgrading the component to a static host and dropping its hydration surface. Now a hard build error in both webui-parser and webui-discovery, matching the sibling HTML/CSS reads. Added a non-UTF-8 regression test.
2. (NIT) @observable get fullName() scanned get and missed fullName. The scanner now reads the accessor name after a leading get/set (with the same "only when an identifier follows" rule, so a field literally named get still works). Added accessor tests.
3. (NIT) write_projected_state now debug_assert!s the schema is sorted — a mis-sorted hand-built protocol fails at test time, at zero release cost.

Also marked *.bin binary in .gitattributes so the committed protobuf fixture is never EOL-normalized on checkout.

Validation

• cargo xtask check — ✨ all checks passed (164.5s): license-headers → fmt → clippy → deny → test → build → wasm → examples → bench → docs.
• DESIGN.md, rfcs/hydration-schema.md, and docs/guide/concepts/routing.md updated to match behavior.

Acceptance checklist

• cargo xtask check passes
• Tests added/updated (scanner, per-host projection, example apps, non-UTF-8 regression, dotnet)
• DESIGN.md + docs updated
• No new recursion/regex in core paths
• No new unwrap/expect in library code
• Allocation-disciplined (zero-copy projection over the sorted allowlist)
• License headers on all new source files
• FFI cannot panic across the boundary (release is panic = "abort")
• Protobuf schema change cascade-tested (proto → handler → ffi → node → wasm → dotnet)