From d32f3cb893566f5cfbbbce888f53e207f886ce64 Mon Sep 17 00:00:00 2001 From: slhx agent Date: Mon, 13 Jul 2026 09:53:26 +0200 Subject: [PATCH] perf(render): pre-size generated view output --- AGENTS.md | 2 +- REQUIREMENTS.md | 3 ++ hemx/Cargo.toml | 4 +++ hemx/benches/render.rs | 58 ++++++++++++++++++++++++++++++++++ hemx/src/lib.rs | 27 +++++++++++++++- hemx/templates/bench_page.heml | 11 +++++++ 6 files changed, 103 insertions(+), 2 deletions(-) create mode 100644 hemx/benches/render.rs create mode 100644 hemx/templates/bench_page.heml diff --git a/AGENTS.md b/AGENTS.md index d534849..49fe089 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -57,7 +57,7 @@ Keep it stable. Prefer pointers to canonical sources over copied structure, file - Use the same Workout command surface for tests, production build, and mobile release: `cargo run -p hemx-xtask -- workout test`, `cargo run -p hemx-xtask -- workout build`, `HEMX_WORKOUT_ORIGIN=https://workout.example.com cargo run -p hemx-xtask -- workout mobile-release`, and `HEMX_WORKOUT_ORIGIN=https://workout.example.com cargo run -p hemx-xtask -- workout mobile-verify`; Android/iOS SDKs, store submission targets, and signing remain external blockers, not repo-owned secrets, and do not imply a broad `hemx-mobile` framework. req: examples/006 req: examples/011 req: examples/013 - hemx core stays small: effects, typed ids, registries, and wire schema only; keep features in core only when they fit typed resources plus the closed EffectBatch op set, and treat DOM details as runtime lowering. Workspace crates stay separated, stable-Rust-compatible, and free of kitchen-sink boundaries; new primitives must delete special cases. Public identifiers should flow through typed wrappers over internal `ResourceId`/`ResourceRef`, not special-case opcodes. Wire output lowers symbolic authoring names to compact metadata and postcard/form-encoded envelopes, not JSON. ABI/schema versions and build fingerprints must guard runtime/server compatibility. v0 scope is the checked hypermedia core plus page/runtime/wire/diagnostic/test/axum proof, not optional sync/wasm/query/auth/router breadth. req: v0_scope/001 req: v0_scope/002 req: v0_scope/005 req: laws/001 req: invariant/001 req: invariant/005 req: typed_id/001 req: typed_id/003 req: effect_algebra/001 req: effect_algebra/006 req: wire/001 req: wire/002 req: wire/003 req: wire/004 req: wire/005 req: wire/006 req: abi/001 req: abi/002 req: abi/003 req: abi/004 req: abi/005 req: misc/001 req: misc/002 req: misc/003 req: misc/004 req: misc/005 req: misc/006 req: misc/007 req: misc/008 req: misc/009 req: misc/010 - Routing, auth, sessions, transport, transitions, sync, async data helpers, multipart parsing/uploads, and storage belong in integration/user crates; hemx-axum preserves normal HTTP auth, credentials, CSRF, multipart/browser fallback, and progressive-enhancement semantics rather than defining policy in core. Sync is optional integration state reconciliation over push/transport, not core. req: auth/001 req: auth/002 req: auth/003 req: auth/004 req: auth/005 req: async_data/001 req: async_data/002 req: async_data/003 req: multipart/001 req: multipart/002 req: multipart/003 req: sync/001 req: sync/008 -- Public examples and beginner APIs should use templates plus Rust, generated component APIs, resources, view wrappers, render/page helpers, `#[hemx::app]`, plain `#[hemx::handler]` functions, and `IntoEffect`, not atoms, raw ids, selectors, wire formats, runtime opcodes, manual registries, `$OUT_DIR` includes, raw render/lower calls, raw HTML construction, imperative DOM mutation, or raw effect constructors; keep advanced layers out of starters. req: canonical_authoring/001 req: canonical_authoring/004 req: canonical_authoring/006 req: canonical_authoring/010 req: canonical_authoring/015 req: invariant/003 req: dx/001 req: dx/002 req: dx/010 req: component/003 req: component/004 req: view/001 req: view/002 req: html_safety/001 req: html_safety/003 req: html_safety/005 req: public_api/001 req: public_api/002 req: public_api/003 req: public_api/005 req: public_api/006 req: progressive_disclosure/001 req: progressive_disclosure/002 req: progressive_disclosure/003 req: derive_app/001 req: derive_app/002 req: derive_handler/001 req: derive_handler/002 req: derive_handler/003 req: derive_handler/004 req: derive_handler/005 +- Public examples and beginner APIs should use templates plus Rust, generated component APIs, resources, view wrappers, render/page helpers, `#[hemx::app]`, plain `#[hemx::handler]` functions, and `IntoEffect`, not atoms, raw ids, selectors, wire formats, runtime opcodes, manual registries, `$OUT_DIR` includes, raw render/lower calls, raw HTML construction, imperative DOM mutation, or raw effect constructors; keep advanced layers out of starters. req: canonical_authoring/001 req: canonical_authoring/004 req: canonical_authoring/006 req: canonical_authoring/010 req: canonical_authoring/015 req: invariant/003 req: dx/001 req: dx/002 req: dx/010 req: component/003 req: component/004 req: view/001 req: view/002 req: view/003 req: html_safety/001 req: html_safety/003 req: html_safety/005 req: public_api/001 req: public_api/002 req: public_api/003 req: public_api/005 req: public_api/006 req: progressive_disclosure/001 req: progressive_disclosure/002 req: progressive_disclosure/003 req: derive_app/001 req: derive_app/002 req: derive_handler/001 req: derive_handler/002 req: derive_handler/003 req: derive_handler/004 req: derive_handler/005 - Typed partial swaps should stay expressed as generated target plus rendered partial plus swap kind, not selector-driven rerendering or response-side selector retargeting; HTTP, page navigation, push, and island behavior adapt around that loop, and docs should layer new primitives progressively. Navigation is an effect/page-swap concern, not a core router framework; enhanced links and GET forms preserve real URL/history semantics so page state stays reloadable/shareable without a client state graph. Push streams carry postcard EffectBatch over server-owned SSE/WebSocket transport and keep `data-hemx-sse` root-scoped/same-origin by default. Preserve keyed/optional scope identity for addressable loop nodes, reconcile filtered keyed collections without clearing retained rows, prefer generated keyed-slot helpers over low-level keyed calls, and route self/row-update diagnostics toward local `data-hemx-slot`/`h-key` targets. req: canonical_authoring/002 req: canonical_authoring/014 req: modes/001 req: scope/001 req: list/001 req: list/002 req: list/003 req: list/004 req: list/005 req: list/006 req: nav/001 req: nav/002 req: nav/003 req: nav/004 req: nav/005 req: push/001 req: push/002 req: push/003 req: push/004 req: push/005 req: push/006 req: push/007 req: progressive_disclosure/004 req: page_swap/001 req: page_swap/002 req: page_swap/003 req: locality/001 req: locality/002 req: target_policy/001 req: target_policy/002 - `examples/html_examples` is the copy-paste HTML pattern gallery for htmx-style examples; keep exact htmx URL slugs visible while translating behavior to boring `.heml`, generated resources, and server-owned Rust state, not HTMX syntax, selector targeting, or user-authored browser JavaScript. Shared runtime loading and declarative `data-hemx-*` are allowed. Boost containers enhance same-origin descendants only and preserve native external/download/new-tab behavior. req: htmx_equivalents/001 req: htmx_equivalents/003 req: htmx_equivalents/005 req: examples/005 req: examples/007 req: examples/012 req: page_swap/007 req: page_swap/008 - Use `cargo run -p hemx-xtask -- app new PATH` for the generic page/form/keyed-row/notice starter, and `cargo run -p hemx-xtask -- app new --mobile PATH` for the phone-first starter with host capabilities, recovery truth, and release-kit commands; do not treat it as a mobile framework or store-submission bot. req: ceremony/005 req: ceremony/006 req: ceremony/007 diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md index e86b347..b8af52d 100644 --- a/REQUIREMENTS.md +++ b/REQUIREMENTS.md @@ -794,6 +794,9 @@ what a valid business email is. [north_star] ### req: view/002 0 002 Generated slot types may target `Display`, `Hemplate`, or explicit view wrappers. Type errors suggest the expected renderable view type. [north_star] +### req: view/003 +0 003 Generated `Hemplate` views expose a template-derived size hint, and trusted hemx render helpers use it to pre-size output without changing rendered HTML. [north_star] + --- ## diagnostics diff --git a/hemx/Cargo.toml b/hemx/Cargo.toml index 11b5ed4..388de76 100644 --- a/hemx/Cargo.toml +++ b/hemx/Cargo.toml @@ -6,6 +6,10 @@ edition.workspace = true [lib] path = "src/lib.rs" +[[bench]] +name = "render" +harness = false + [dependencies] hemplate = { path = "../../hemplate/hemplate" } hemx-core = { path = "../hemx-core" } diff --git a/hemx/benches/render.rs b/hemx/benches/render.rs new file mode 100644 index 0000000..434895c --- /dev/null +++ b/hemx/benches/render.rs @@ -0,0 +1,58 @@ +//! Generated-view rendering baseline: `cargo bench -p hemx --bench render`. + +use hemplate::Hemplate; +use std::hint::black_box; +use std::time::Instant; + +const ITERATIONS: u32 = 100_000; +const ROUNDS: usize = 7; + +#[derive(Hemplate)] +struct BenchPage { + title: String, + body: String, + items: Vec, +} + +fn page() -> BenchPage { + BenchPage { + title: String::from("Production readiness"), + body: "Checked hypermedia without a parallel client application. ".repeat(4), + items: (0..20).map(|index| format!("item-{index}")).collect(), + } +} + +fn median_ns(mut render: impl FnMut() -> usize) -> u128 { + for _ in 0..10_000 { + black_box(render()); + } + let mut rounds = [0_u128; ROUNDS]; + for round in &mut rounds { + let start = Instant::now(); + for _ in 0..ITERATIONS { + black_box(render()); + } + *round = start.elapsed().as_nanos() / u128::from(ITERATIONS); + } + rounds.sort_unstable(); + rounds[ROUNDS / 2] +} + +fn main() { + let view = page(); + let unhinted = median_ns(|| { + let mut html = String::new(); + view.render_into(&mut html).expect("generated view renders"); + black_box(html.len()) + }); + let hinted = median_ns(|| { + let mut html = String::with_capacity(view.size_hint()); + view.render_into(&mut html).expect("generated view renders"); + black_box(html.len()) + }); + println!( + "unhinted_median_ns={unhinted} hinted_median_ns={hinted} size_hint={} html_len={}", + view.size_hint(), + view.render().expect("generated view renders").len(), + ); +} diff --git a/hemx/src/lib.rs b/hemx/src/lib.rs index f1a21e7..a18258a 100644 --- a/hemx/src/lib.rs +++ b/hemx/src/lib.rs @@ -80,7 +80,7 @@ pub mod __private { } fn render_template(view: &impl hemplate::Hemplate) -> Html { - let mut html = String::new(); + let mut html = String::with_capacity(view.size_hint()); view.render_into(&mut html) .expect("hemplate view renders into hemx effect payload"); __private::html_trusted(html) @@ -186,6 +186,8 @@ pub mod prelude { #[cfg(test)] mod tests { + use std::cell::Cell; + struct InlineView; impl hemplate::Hemplate for InlineView { @@ -195,6 +197,29 @@ mod tests { } } + struct HintTrackingView(Cell); + + impl hemplate::Hemplate for HintTrackingView { + fn render_into(&self, out: &mut String) -> Result<(), hemplate::error::HemplateError> { + out.push_str("hinted"); + Ok(()) + } + + fn size_hint(&self) -> usize { + self.0.set(true); + 23 + } + } + + #[test] + fn trusted_render_path_uses_the_view_size_hint() { + // req: view/003 req: html_safety/002 + let view = HintTrackingView(Cell::new(false)); + + assert_eq!(crate::page(&view).as_str(), "hinted"); + assert!(view.0.get(), "trusted render path must consult size_hint"); + } + #[test] fn page_is_the_short_safe_html_helper() { // req: dx/006 req: html_safety/002 diff --git a/hemx/templates/bench_page.heml b/hemx/templates/bench_page.heml new file mode 100644 index 0000000..a145b3a --- /dev/null +++ b/hemx/templates/bench_page.heml @@ -0,0 +1,11 @@ + + +{+ self.title +} + +

{+ self.title +}

+

{+ self.body +}

+
    +
  • {+ item +}
    • +
+ +