Summary
stx's pre-parse pass (the one that merges <script client> blocks into a scope IIFE and the one that expands @push/@include/@section/etc.) treats the source as one flat string. It does not respect HTML comment boundaries. Two distinct symptoms result:
- Backticks inside an HTML comment poison the script merge. A
`inside<!-- ... -->gets concatenated into the merged IIFE body and flips the JS parser into template-literal mode, breaking every script after it. - Directive names inside an HTML comment get substituted. Writing
<!-- styles handled in @push('styles') below -->causes the pre-parser to expand the@push('styles')reference at the comment location, splicing the entire styles block into the middle of the comment and destroying the surrounding HTML structure.
Both are silent. Neither produces a compile warning. Both manifest downstream as "the scope didn't register" / "the page renders weird DOM" / "every script after this comment is dead."
Reproduction — Bug 1: backtick in HTML comment
<script client>
function greet() {
console.log('hello')
}
</script>
<!-- This comment uses `template literals` inside backticks for readability. -->
<button @click="greet()">Greet</button>Expected: button click logs hello.
Actual: scope IIFE never finishes parsing. greet is undefined. Button click logs:
[STX] Handler error: greet() ReferenceError: greet is not definedThe merged setup body contains the comment text. The lone ` puts the JS parser into "I'm reading a template literal" mode for everything that follows the comment, including the entire scope registration block at the end of the IIFE. JS parser bails. Scope never registers.
Reproduction — Bug 2: stx directives in HTML comment
<!-- /resources/views/article/[id].stx -->
@extends('layouts/default')
@section('content')
<article>
<!-- Body. Serif typography, generous leading, drop cap on the
first paragraph (handled in @push('styles') below). -->
<p :text="content"></p>
</article>
@endsection
@push('styles')
<style>
article p:first-of-type::first-letter { font-size: 3em; float: left; }
</style>
@endpushExpected: comment is inert, article renders, styles get pushed into <head>.
Actual: the @push('styles') reference inside the comment is interpreted by the pre-parser as if it were a real @push directive call. The matching @push/@endpush block at the bottom of the file gets substituted at the comment location:
<article>
<!-- Body. ... drop cap on the
first paragraph (handled in <style>
article p:first-of-type::first-letter { ... }
</style> below). -->
<p :text="content"></p>
</article>The comment never closes (--> is now wrapped inside the spliced-in <style> block). The article becomes unparseable DOM. Every <script data-stx-scoped> block that follows is nested inside the broken structure and silently fails to execute. Scope registered: false in console.
Same class of bug affects @include, @section, @extends, @yield, @slot, @if, @for, @push, @prepend, @stack, etc. — anything the pre-parser scans for.
Root cause
In packages/stx/src/ — the directive-scanner and the script-merge tokenizer both operate on the source as a flat string. They don't have HTML-comment awareness.
Specifically:
Bug 1: the script-merge pass (concatenates every
<script client>body into one IIFE) appears to also pull through HTML comment text. The merged source has the backtick in it. Bun's transpiler / browser's JS parser then chokes on the unterminated template literal.Bug 2: the directive expander (
@push,@include, etc.) does a string search/replace without skipping content inside<!-- ... -->. The directive expands wherever its name appears, including inside a comment.
Why it's bad
Both symptoms are catastrophic and silent:
- A backtick character inside a comment kills every script on the page. The character that triggered the failure is a prose punctuation character a developer would never expect to be load-bearing.
- A directive name inside a comment doesn't just get ignored — it actively rewrites the page structure. The comment is exactly the place developers put references to things ("see @push('styles') below"), so the bug hits the most natural prose.
- Neither bug shows up as "syntax error at line N". They show up as "the page acts weird and I can't tell why."
I have grep guardrails I run in my project — but they're a poor substitute for the parser doing the right thing:
# Bug 1
grep -nE '<!--[^>]*`' resources/**/*.stx
# Bug 2
grep -nE '<!--[^>]*@(push|include|section|extends|yield|slot|if|for)' resources/**/*.stxSuggested fix
Both passes need to skip content inside <!-- ... -->. A small pre-pass that masks comment regions with placeholders before tokenizing, then unmasks afterward, would address both.
// Mask HTML comments so subsequent passes don't see their content.
const COMMENT_RE = /<!--[\s\S]*?-->/g
const masked: string[] = []
const sourceMasked = source.replace(COMMENT_RE, (m) => {
const i = masked.push(m) - 1
return `__STX_COMMENT_${i}__`
})
// ... run directive expansion + script merge on `sourceMasked` ...
// Unmask at the end:
const final = sourceMasked.replace(/__STX_COMMENT_(\d+)__/g, (_, i) => masked[+i])This is the standard "treat comments as opaque" trick. It costs effectively nothing and fixes both bugs.
Environment
@stacksjs/stx@0.2.64- Bun.Transpiler used for the JS pass
- Reproductions are minimal — any
.stxfile with the patterns above will hit them
🤖 Filed via Claude Code