perf: reduce empty template host overhead

[Mohamed Mansour (mohamedmansour)]

Summary

Empty scriptless templates were still paying for TemplateElement's per-instance state despite having no DOM, bindings, events, CSS, or lifecycle work. This adds a narrow minimal-host fast path while leaving every behavior-bearing or CSS-bearing template on the existing full host path.

• use a prototype-only HTMLElement host only when metadata and the registered style closure prove there is no work
• preserve delayed parent : writes through the existing pending-state store
• exclude stateless static opt-outs from retained streaming update targets
• keep CSS-bearing empty templates on TemplateElement, avoiding duplicate style lifecycle code

The simplification reduced the PR from 454 to 304 added lines and removed the extra pending-state module.

Performance

Measured against d8601ca0 (including #479 and #480) in Chrome 151.0.7922.174. Each row uses 24 empty compiler-owned tags, 2 warmups, and 12 interleaved fresh-realm runs per arm. Incremental heap is sampled with forced GC immediately before and after definition/upgrade.

Hosts	JS heap (main -> PR)	JS reduction	JS saved/host	Combined saved/host	Install P50 (main -> PR)	Install reduction
5,000	905,240 B -> 117,428 B	87.03%	157.56 B	288.85 B	17.00 -> 5.80 ms	65.88%
15,000	2,194,146 B -> 274,864 B	87.47%	127.95 B	257.05 B	44.45 -> 16.15 ms	63.67%
30,000	4,129,812 B -> 517,516 B	87.47%	120.41 B	248.97 B	93.45 -> 32.55 ms	65.17%

Per-instance framework-owned properties fall from 14 to 0 for hosts with no queued writes.

Compared with the earlier implementation in this PR, the simplified branch uses another 3-12% less incremental JS heap and installs 14-18% faster. A prior run on e971c13a was discarded after #479 landed.

Correctness

• parent properties queued before definition are applied on connection or streaming activation; newer post-definition writes win
• hosts without queued writes remain zero-field; only actual queued keys become own properties
• CSS-bearing empty templates retain the existing TemplateElement style path
• templates with HTML, bindings, blocks, events, state roots, Shadow DOM, or CSS remain on TemplateElement
• state-capable dormant hosts remain streaming update targets; minimal hosts without setState do not
• ordinary authored data-ws remains untouched outside streaming mode

Validation

• pnpm --dir packages/webui-framework test:unit - 328 passed
• focused static-host, template-element, styles, and streaming pipeline tests - 140 passed
• cargo xtask check - all checks passed

[Copilot]

Pull request overview

This PR reduces overhead for empty compiler-owned templates while preserving deferred state, CSS installation, and streaming behavior.

Changes:

• Uses minimal HTMLElement hosts for non-reactive empty templates.
• Centralizes pending parent-state handling.
• Excludes stateless hosts from streaming targets.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
packages/webui-framework/src/template-element.ts	Uses the shared pending-state helper.
packages/webui-framework/src/streaming-pipeline.test.ts	Tests streaming retention behavior.
packages/webui-framework/src/streaming-deferred.ts	Filters stateless static hosts.
packages/webui-framework/src/static-host.ts	Implements minimal hosts, styles, and state handling.
packages/webui-framework/src/static-host.test.ts	Tests host behavior, properties, and styles.
packages/webui-framework/src/pending-parent-state.ts	Centralizes pending parent-property storage.

Suppressed comments (4)

packages/webui-framework/src/static-host.ts:69

• This branch introduces a second runtime representation for th: 1 templates, but the checked-in contract still says every scriptless component receives a compiler-owned TemplateElement (DESIGN.md:4855-4864, also src/element.ts:13-14). That is now false for empty templates, so update the DESIGN/source documentation alongside this change to describe the zero-work/CSS-only HTMLElement host and its intentionally absent framework state/lifecycle API.

  if (installation) {
    void installation.catch((error) => {

packages/webui-framework/src/static-host.ts:75

• Applying arbitrary queued : property names before checking hasAttribute() lets a valid parent binding such as :has-attribute shadow this callback's own DOM method and throw during upgrade. The existing TemplateElement path checks its marker and installs styles before consuming pending state; perform the streaming check/style installation before applying the queued values here.

    });
  }
}

/** Define the smallest client-rendering element for a compiler-owned template. */

packages/webui-framework/src/static-host.ts:83

• The activation hook consumes arbitrary queued : properties before installNoopHostStyles() calls getRootNode() and reads ownerDocument. A queued :get-root-node value can therefore shadow the method and make streamed upgrade fail; install/resolve styles before applying pending values, matching TemplateElement.$mount()'s ordering.

  if (templateIsNoopHost(meta)) {
    // The tag still needs custom-element identity, queued parent properties,

packages/webui-framework/src/static-host.ts:119

• This adds a valid th case in which the compiler-owned host is an HTMLElement, but DESIGN.md:4855-4863 still says every scriptless template gets a TemplateElement and only activates after a state/property write. Please update the specification (and the corresponding hydration docs if applicable) to describe the no-op host's CSS and pending-property behavior so the documented runtime contract matches this change.

      return true;
    }

    protected $shouldApplySSRBootstrapState(): boolean {
      return false;

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.