ReviewOS

stacks/stx

hasSignalsSyntax matches directive syntax inside escaped <pre><code>, so docs pages ship ~159KB of runtime they never use

#1835
Closed glennmichael123 opened this 22 days ago · 1 comment
22 days ago

Summary

hasSignalsSyntax scans the raw template for directive patterns with no notion of where they appear, so a documentation page that quotes stx syntax inside an escaped code sample counts as reactive. The page ships the full signals runtime and gets data-stx-auto stamped on <body>, for markup that is inert text.

Repro

<main>
  <h1>The :if directive</h1>
  <pre><code>&lt;div :if="open"&gt;&lt;/div&gt;</code></pre>
</main>

Through processDirectives:

ships runtime? true

The sample is HTML-escaped — &lt;div — so it is unambiguously text, not markup. /\s:[a-z][\w-]*\s*=\s*["']/i matches it anyway, because :if="open" survives escaping intact (only < and > are encoded).

Cost

The runtime is ~159KB uncompressed / ~39KB gzip. Every page of the stx documentation that shows a :if=, x-model= or @click= example pays it. This is the framework's own docs site, and any consumer docs site built with stx.

Second-order effect

Since #1827, fragment responses carry X-STX-Runtime, keyed on whether the page actually shipped a runtime. That header faithfully reports true for these pages, so a runtime-less page navigating to a docs page hands off to a full load rather than an SPA swap. The header is doing the right thing with the answer it is given — the over-shipping is upstream of it, here.

The cost is bounded (once any runtime-shipping page has loaded, window.stx persists for the session, so at most one hand-off follows), but it is avoidable.

Suggested direction

Strip <pre>, <code>, <script>, <style> and HTML comments before scanning — the same treatment stripInertRegions now applies in packages/router/src/client.ts. Measured over the 339 rendered docs pages in this repo, that reduces raw {⁠{ matches from 53 to 4.

Worth checking whether @raw/@endraw regions should be excluded on the same pass; there is a separate leak where @raw@endraw renders literally into output.

Found while verifying #1827.

22 days ago

Fixed in 630cc24.

escaped sample        159,384 bytes -> 386
highlighted sample    162,469 bytes -> 3,471

Over the 339 docs pages in this repo, the count that would ship a runtime falls from 47 to 8.

The design choice worth knowing

Detection runs against a copy with inert regions blanked — but only TEXT is blanked, and every TAG is kept intact including its attributes, inside <pre> / <code> and HTML comments.

Dropping whole regions would have been simpler and wrong in the expensive direction. <pre> content is parsed as HTML, so a real reactive element can live inside one:

<pre><button @click="go()">run</button></pre>

That button is a real button. Region-dropping loses its runtime and breaks the page — much worse than shipping bytes you do not need. Keeping tags also handles syntax-highlighted samples for free, where the block genuinely contains real <span>s and only the text between them is the quoted directive. That case would have defeated a naive "no < in the body" heuristic, which was my first attempt.

Verified in both directions

Byte-for-byte, not just by predicate:

beforeafter
escaped sampleruntimenone
highlighted sampleruntimenone
inline <code> spannonenone
real <button @click> inside <pre>events script, 2655 Bidentical
client script with state()runtime, 160572 Bidentical
:if over a store, no scriptruntime, 159370 Bidentical

Every real case is unchanged; only the two documentation shapes moved.

On the second-order effect

This also removes the over-shipping that #1827's X-STX-Runtime header was faithfully reporting — a runtime-less page navigating to a docs page no longer hands off to a full browser load. Worth noting that header was never wrong; it was reporting the truth about a page that should not have needed a runtime.

Not addressed

The @raw/@endraw leak mentioned in the report is a separate mechanism (a directive that renders literally rather than a detection question) and still deserves its own issue.

Full suite 10760 pass in a clean worktree; the two failures are the pre-existing crosswind-arbitrary-values case and a package-exports timeout that passes in isolation.

Sign in to comment on this issue.