Repository navigation
perf(node): reuse prepared state across renders - #477
Merged
Mohamed Mansour (mohamedmansour) merged 1 commit intoAug 25, 2026
Merged
Mohamed Mansour (mohamedmansour) merged 1 commit into
Mohamed Mansour (mohamedmansour) merged 1 commit into
Conversation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Mohamed Mansour (mohamedmansour)
requested review from
Akrosh Gandhi (akroshg),
Jane Chu (janechu) and
mcritzjam
and
a lite review from Copilot
August 25, 2026 02:15
Copilot started reviewing on behalf of
Mohamed Mansour (mohamedmansour)
August 25, 2026 02:17
View session
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an opt-in Node runtime optimization to reuse a parsed native state snapshot across repeated renders, reducing per-render JSON parse/allocation overhead while documenting the native-memory retention tradeoff.
Changes:
- Introduces an opaque
PreparedStatehandle plusProtocol.prepareState()/Protocol.renderPrepared()in@microsoft/webui. - Extends the Node addon with N-API
External<Value>-backed state preparation and a prepared render path that reuses the existing buffered renderer. - Updates integration tests, benchmark runner/docs, and WebUI specs/docs to reflect the new API and its constraints.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| packages/webui/src/index.ts | Adds PreparedState type plus prepareState() / renderPrepared() wrappers on Protocol. |
| crates/webui-node/src/lib.rs | Implements prepare_state and render_prepared via N-API External<Value> and shares buffered render helper. |
| packages/webui/test/integration.test.ts | Adds integration coverage for immutable prepared snapshots and invalid-handle rejection. |
| packages/webui/README.md | Documents prepared-state APIs, immutability, and native-memory retention tradeoffs. |
| docs/guide/integrations/node.md | Adds API reference entries and a “Reusing immutable state” guide section. |
| examples/integration/node-addon-bench/bench.mjs | Benchmarks preparation cost and prepared-render performance; validates byte-identical output. |
| examples/integration/node-addon-bench/README.md | Updates benchmark case matrix/methodology notes for prepared state. |
| DESIGN.md | Updates the npm distribution/runtime API contract to include prepared-state behavior. |
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Jane Chu (janechu)
approved these changes
Aug 25, 2026
Mohamed Mansour (mohamedmansour)
merged commit Aug 25, 2026
3010b6c
into
microsoft:main
24 checks passed
Mohamed Mansour (mohamedmansour)
added a commit
that referenced
this pull request
Aug 25, 2026
## Summary - reuse the last rendered output size for each Node entry/route in a bounded 64-slot relaxed-atomic table - pack a route fingerprint beside each capacity so bucket collisions miss safely, fall back to 4 KiB, and cap retained hints at 1 MiB - apply the hint to both `render` and `renderPrepared`, shrinking only when a stale same-route hint leaves more than 2x slack - add collision, isolation, clamping, reallocation, byte-equivalence tests and an alternating large/small route benchmark Builds on the prepared-state API merged in #477. ## Performance Windows x64, Node 24.18.0, release addon, Contact Book `/contacts`; median P50 across five paired full benchmark runs: | Prepared render | C1 | This PR | Delta | |---|---:|---:|---:| | 10 contacts | 58.5 us | 54.2 us | **-7.35%** | | 100 contacts | 425.9 us | 406.1 us | **-4.65%** | | 1000 contacts | 4.853 ms | 4.806 ms | **-0.96%** | | alternating `/contacts` + `/` at 1000 | 5.162 ms | 5.098 ms | **-1.23%** | HTML output stayed byte-identical at 34,035 / 252,489 / 2,438,775 bytes. A focused writer test changes cold growth from at least one reallocation to zero after learning the output size. For 128 large/small route alternations while retaining every small buffer (2,438,775-byte large output, 24,331-byte small output), settled RSS deltas were 4.06 MiB for C1 and 3.80 MiB here (three-run medians); native external-memory growth was exactly 3,114,408 bytes for both. Large and small SHA-256 output hashes also matched C1. A same-route synthetic probe alternating 1,048,607-byte and 18-byte output isolated `shrink_to_fit`: 516.2 us P50 with shrink versus 510.4 us without (+1.1%), while C1 was 525.6 us. The bounded shrink therefore remains net-positive versus C1 and prevents a stale large hint from riding on a tiny response. ## Validation - `cargo test -p microsoft-webui-node` - `cargo xtask check` Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Mohamed Mansour (mohamedmansour)
added a commit
that referenced
this pull request
Aug 26, 2026
## Release Bumps WebUI to `0.0.26`. Previous release tag: `v0.0.25` ## Changes since `v0.0.25` Features: - Python hosts now have an official typed PyO3 renderer package with buffered, partial, template, token, and host-driven streaming APIs (feat: add official Python renderer package #453 by @mohamedmansour). - Progressive SSR can place transport-flushed streaming boundaries inside reusable components while preserving component ownership and continuation state (feat: support component-local streaming boundaries #460 by @mohamedmansour). - Components can defer compiler-owned hydration until interaction, with router preload handoff and a combined lazy-render policy (feat: add compiler-driven interaction hydration #485 by @mohamedmansour). - Builds can opt into global Light DOM CSS while preserving explicit authored Shadow roots and deterministic style closures (feat: make Light DOM a global CSS opt-in #429 by @mohamedmansour). - State projection supports application-owned TypeScript 7.0.2 while retaining the TypeScript 6 migration path (feat: support TypeScript 7 projection compilation #452 by @mohamedmansour). - WebUI Press supports layout-scoped compile-time named regions with fallback HTML, state, components, and scripts (feat(press): add compile-time named regions #484 by @mohamedmansour). - FAST v2 and v3 gain plugin-owned local and npm component discovery with validated FAST template transformation (feat: add plugin-owned FAST component discovery #378 by @janechu). Fixes: - Missing condition identifiers are treated as falsy before negation and logical evaluation, aligning SSR with the browser runtime (fix: negate missing condition paths correctly #449 by @mohamedmansour). - FAST route state now scales through escaped scalar kebab-case attributes shared by FAST v2 and v3 (fix: scale FAST route state with scalar attributes #450 by @janechu). - Dynamic Link-mode components wait for native stylesheet readiness across navigation and component assets, preventing unstyled flashes (fix: prevent dynamic component stylesheet flashes #454 by @mohamedmansour). - Authored component definitions defer whenever compiled template metadata has not arrived, including ordinary router navigation (fix: defer authored define() whenever template metadata is missing #461 by @mohamedmansour). - Client structural updates preserve authored order and sibling ownership for shared slots and raw HTML ranges (fix: preserve source order for shared structural slots #465 by @mohamedmansour, fix: preserve siblings around raw HTML updates #466 by @mohamedmansour). - Native-element attributes no longer leak into the local state of a later component (perf(handler): stop native attributes leaking into component state #469 by @mohamedmansour). - Templates-and-state-only SSR bootstrap payloads no longer require component style metadata (fix: allow SSR bootstrap without component styles #475 by @mohamedmansour). - The high-level Rust `serve_request` path now preserves complete render options, including CSP nonces, while sharing the same entry and request path with partial rendering (fix: forward CSP nonces through serve_request #488 by @mohamedmansour). - Projection compilation bounds source reads, excludes binary and unsupported-loader inputs from semantic analysis, and preserves deterministic cleanup under large esbuild graphs (fix: bound projection adapter source reads #489 by @mohamedmansour). - Router pending UI remains mounted through pre-commit work and settles at the synchronous DOM commit, with stale, aborted, and re-entrant navigation cleanup kept generation-safe (fix: settle router pending UI during navigation commits #491 by @mohamedmansour). Docs: - The documentation site adds accessible responsive navigation, improved reading layouts, stronger search behavior, and Playground recovery states (feat: polish WebUI documentation experience #459 by @mohamedmansour). - Slot-resolution implementation guidance now documents pre-order lookup, pending placement ownership, and marker handling (chore: clarify slot resolution comments #471 by @mohamedmansour). - Repeated `w-ref` behavior is now explicit: refs are scalar and the last wired occurrence wins, while stable authored IDs or item components provide identity-based lookup (chore: clarify repeated w-ref behavior #490 by @mohamedmansour). Maintenance: - Release and package policy metadata now constrains the transitive h2 advisory, uses SPDX NuGet licensing, and classifies publishing jobs correctly (chore: allow constrained h2 advisory #451 by @janechu, fix: use modern NuGet license metadata #457 by @janechu, chore: mark publishing jobs as release jobs #458 by @janechu). - The development and CI Rust toolchain is updated to 1.98 with the resulting warnings resolved (Update rust toolchain version and fix clippy warning #462 by @telecos). - Release builds use Thin LTO to retain cross-crate optimization with faster linking (perf: switch release builds to Thin LTO #464 by @mohamedmansour). - Handler and expression hot paths reduce attribute vtable calls, render lookup and scope allocations, and single-term condition overhead (perf(handler): centralize HTML attribute writing in ResponseWriter #467 by @mohamedmansour, perf(expressions): fast-path single-term conditions #470 by @mohamedmansour, perf(handler): reduce render lookup and scope allocations #472 by @mohamedmansour). - Node rendering can reuse immutable prepared-state snapshots and bounded per-route output capacity hints (perf(node): reuse prepared state across renders #477 by @mohamedmansour, perf: reuse Node render output capacity #478 by @mohamedmansour). - Framework hydration releases bootstrap data sooner and reduces allocations for bindings, empty hosts, and visible conditionals (perf: reduce framework hydration allocations #479 by @mohamedmansour, perf: release SSR bootstrap memory after hydration #480 by @mohamedmansour, perf: reduce empty template host overhead #482 by @mohamedmansour, perf: remove visible conditional anchors #483 by @mohamedmansour). - Benchmark tooling now renders the full contact workload, runs Criterion baselines per target, and restores the streaming hydration fixture (fix(bench): render contacts in contact-book benchmark #468 by @mohamedmansour, fix(xtask): run Criterion benchmarks per target #473 by @mohamedmansour, fix: repair streaming hydration benchmark fixture #476 by @mohamedmansour). ## Validation - `cargo xtask check` --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
PreparedStatesnapshots backed by N-APIExternal<Value>Protocol.prepareState()andProtocol.renderPrepared()while sharing the existing buffered render pathPerformance
Release Node addon benchmark on Windows x64 with Node 24.18.0. Prepared and JSON-string renders produced byte-identical output at every workload.
This is an opt-in repeated-state optimization. It removes per-render JSON parsing and associated allocation/GC churn, but each live prepared handle retains one parsed native
Valueuntil JavaScript garbage collection. The N-API external reports an approximate external-memory size to V8.Validation
cargo test -p microsoft-webui-nodepnpm --filter @microsoft/webui test- 62 passedcargo xtask bench node-addoncargo xtask check