ReviewOS

stacks/stx

HTML comments are not respected by the pre-parse pass — backticks + stx directives inside `<!-- -->` break the page

#1699
Closed glennmichael123 opened this 23 days ago · 0 comments
23 days ago

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:

  1. 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.
  2. 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 defined

The 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>
@endpush

Expected: 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/**/*.stx

Suggested 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 .stx file with the patterns above will hit them

🤖 Filed via Claude Code

Sign in to comment on this issue.