Transformer can’t reliably parse your generic polymorphic props type

[SalahAdDin]

Astro Info

Astro                    v6.1.3
Node                     v24.14.1
System                   Linux (x64)
Package Manager          pnpm
Output                   server
Adapter                  @astrojs/node
Integrations             none

If this issue only occurs in one browser, which browser is a problem?

Firefox

Describe the Bug

In our standard code rules, we use to interface strictly for components.
We are creating some polymorphic components and defining them as follows:

interface Props<Tag extends HTMLTag = "button" | "a"> extends Polymorphic<
  { as: Tag } & ButtonVariants
> {
  disabled?: boolean;
  fullWidth?: boolean;
  ariaLabel?: string;
}

const {
  as: Tag = "button",
  variant = "solid",
  size = "md",
  color = "primary",
  fullWidth = false,
  disabled = false,
  ariaLabel,
  href,
  class: className,
  ...rest
} = Astro.props as Props<typeof Tag>;

const classes = cn(
  buttonVariants({
    variant,
    size,
    color,
    fullWidth,
  }),
  disabled && "pointer-events-none",
  className,
  Tag === "button" && "cursor-pointer",
);
---

<Tag
  {...rest}
  href={Tag === "a" ? (disabled ? undefined : href) : undefined}
  disabled={Tag === "button" ? disabled || undefined : undefined}
  aria-disabled={Tag === "a" ? disabled || undefined : undefined}
  aria-label={ariaLabel}
  class={classes}
>
  <slot />
</Tag>

When we save this component, the Astro language server crashes with the following error:

There was an error transforming /home/LuisAlaguna/Projects/central-mosque-bogota/frontend/src/components/actions/Button/Button.astro to TSX. An empty file will be returned instead. Please create an issue: https://github.com/withastro/astro/issues
Error: TypeError: Cannot read properties of undefined (reading 'map').
panic: runtime error: slice bounds out of range [:15370] with capacity 1792

goroutine 6 [running]:
github.com/withastro/compiler/internal/js_scanner.GetPropsType({0x1622a00, 0x6a4, 0x700})
        github.com/withastro/compiler/internal/js_scanner/js_scanner.go:430 +0x11f
github.com/withastro/compiler/internal/printer.renderTsx(0x1413838, 0x150d760, 0x1413ab0)
        github.com/withastro/compiler/internal/printer/print-to-tsx.go:336 +0xc7
github.com/withastro/compiler/internal/printer.PrintToTSX({0x1622300, 0x6a4}, 0x150d760, {0x0, 0x0}, {{0x3c714, 0x6}, {0x17ea850, 0x6c}, {0x17ea850, ...}, ...}, ...)
        github.com/withastro/compiler/internal/printer/print-to-tsx.go:35 +0x12
main.main.ConvertToTSX.func3({{}, 0x7ff8000100000089, 0x17f5698}, {0x1434260, 0x2, 0x2})
        ./astro-wasm.go:293 +0xf
syscall/js.handleEvent()
        syscall/js/func.go:100 +0x23
exit code: 2

Then, the extension does not work.

What's the expected result?

It should be able to transform the component even using polymorphic generic types and interfaces in components.

We are following this documentation: https://docs.astro.build/en/guides/typescript/#polymorphic-type

Link to Minimal Reproducible Example

https://github.com/SalahAdDin/central-mosque-bogota/tree/main/frontend

Participation

• I am willing to submit a pull request for this issue.

[astrobot-houston]

I was able to reproduce this issue. The crash occurs in the Go compiler's js_scanner.GetPropsType function when two conditions are met simultaneously: (1) the frontmatter contains --- sequences inside JSDoc comments (such as embedded Astro code examples in your documentation comments), and (2) the Props interface uses generic type parameters (e.g., Props<Tag extends HTMLTag = ...>). The --- inside JSDoc confuses the compiler's frontmatter boundary detection, causing GetPropsType to compute an incorrect buffer offset that exceeds the actual capacity, resulting in the Go runtime panic (slice bounds out of range).

I was unable to find a fix for this issue. The bug is in the upstream @astrojs/compiler Go package (both v2.13.1 used by the language server and v3.0.1 used by Astro core are affected), so it cannot be fixed in this repository — it needs to be fixed at withastro/compiler. As a workaround, you can remove the --- sequences from your JSDoc comments in the frontmatter. For example, replace the embedded Astro code examples that use --- delimiters with a different documentation format, or move the JSDoc comment outside the frontmatter. Alternatively, removing the generic type parameter from the Props interface (using a non-generic interface Props extends Polymorphic<...>) will also avoid the crash.

P3: minor bug. This affects users who combine two specific patterns: generic Props interfaces with type parameters AND JSDoc comments containing --- (Astro frontmatter delimiters) inside the component frontmatter. Both conditions must be present simultaneously to trigger the crash. Most users are unlikely to encounter this since embedding --- in JSDoc comments within frontmatter is uncommon, and there is a straightforward workaround (removing --- from JSDoc or removing the generic type parameter).

Full Triage Report

Reproduction

Reproduced: Yes, on @astrojs/compiler@2.13.1 (language server) and @astrojs/compiler@3.0.1 (Astro core).

Minimal reproduction (354 bytes):

---
/**
 * ```astro
 * ---
 * import Foo from 'foo';
 * ---
 *
 * <Foo />
 * ```
 *
 * ```astro
 * ---
 * import Bar from 'bar';
 * ---
 *
 * <Bar />
 * ```
 */

interface Props<T = string> {
  value?: T;
}

const { value } = Astro.props;
---

<div>{value}</div>

Error output:

panic: runtime error: slice bounds out of range [:527] with capacity 288

goroutine 6 [running]:
github.com/withastro/compiler/internal/js_scanner.GetPropsType(...)
    github.com/withastro/compiler/internal/js_scanner/js_scanner.go:430 +0x11f

Diagnosis

Root Cause

The bug is in the Go compiler's js_scanner.GetPropsType function. When the Astro parser encounters --- sequences inside JSDoc comments within the frontmatter, it miscalculates the frontmatter boundaries. This causes GetPropsType to compute an incorrect slice offset that far exceeds the actual buffer capacity.

Conditions Required (ALL must be present)

1. Multiple --- pairs inside JSDoc comments in the frontmatter (e.g., embedded Astro code examples)
2. Generic type parameters on the Props interface (e.g., Props<T = string>, Props<Tag extends HTMLTag>)

Isolation Testing Results

Test	--- in JSDoc	Generic Props	Crash?
1	One pair	Yes (+ Polymorphic)	No
2	Two pairs	No (plain)	No
3	Two pairs	Yes (<T = string>)	Yes
4	Two pairs	No (extends, no generic)	No

Affected Code Path

The crash occurs in the convertToTSX code path used by the language server and VS Code extension for IDE features (type checking, completions, etc.). The transform build path is also affected since both call into the same GetPropsType Go function.

Affected Versions

• @astrojs/compiler@2.13.1 (used by @astrojs/language-server@2.16.5 via @astrojs/check@0.9.8)
• @astrojs/compiler@3.0.1 (used by astro@6.1.3)

Upstream Issue

This bug must be fixed in the withastro/compiler repository, specifically in internal/js_scanner/js_scanner.go in the GetPropsType function.

Workarounds

1. Remove --- from JSDoc comments in frontmatter (restructure documentation)
2. Remove generic type parameters from the Props interface
3. Move documentation comments outside the frontmatter

This report was made by an LLM. Mistakes happen, check important info.

[SalahAdDin]

It is not related to --- in documentation, but the length of the docs:

import { cn } from "@utils/styles.utils";

/**
 * @component Button
 * @title Button
 * @description Semantic button component for actions and navigation.
 * Renders either a `<button>` or an `<a>` depending on the `href` prop and
 * exposes size, color, and variant controls via class-variance-authority.
 * @figmaUrl
 * @usage
 *
 * ```astro nocollapse
 * ---
 * import Button from "@components/actions/Button/Button.astro";
 * ---
 *
 * <Button>Click me</Button>
 * ```

 */

It does not fail, but:

/**
 * @component Button
 * @title Button
 * @description Semantic button component for actions and navigation.
 * Renders either a `<button>` or an `<a>` depending on the `href` prop and
 * exposes size, color, and variant controls via class-variance-authority.
 * @figmaUrl
 *
 * @preview
 *
 * @usage
 *
 * ```astro nocollapse
 * ---
 * import Button from "@components/actions/Button/Button.astro";
 * ---
 *
 * <Button>Click me</Button>
 * ```
 *
 * ## Link
 *
 * When `href` is provided the component renders as an anchor element.
 *
 * ```astro nocollapse
 * ---
 * import Button from "@components/actions/Button/Button.astro";
 * ---
 *
 * ```
 *
 */

It fails.

For DropdownItem.astro, only the following documentation works:

/**
 * @component DropdownItem
 * @title Dropdown Item
 * @description Focusable menu item used inside dropdown content. Renders as a `<button>` by default, or as an `<a>` via `as="a"`.
 *
 * @preview
 *
 * @usage
 *
 */

Actually, it is not clear where it is failing.

[matthewp]

Astrobot, please try again based on this new information.

[astrobot-houston]

• Reproduced: Yes — on both @astrojs/compiler@4.0.0 (Astro core) and @astrojs/compiler@2.13.1 (language server), confirmed via convertToTSX() and astro check.
• Exploration: Yes — root cause fully traced to the upstream @astrojs/compiler Go code; a proposed fix with test cases has been documented but cannot be applied in this repository.
• Unit Test: No — the bug is in the upstream @astrojs/compiler Go/WASM package. Four test cases have been proposed for the compiler repo's js_scanner_test.go.
• Priority: P2: has workaround. This crashes the language server and astro check when using generic Props with JSDoc comments containing HTML tags — a documented pattern for polymorphic components. Workarounds exist (remove HTML from JSDoc comments, or remove generic type parameters from Props). Builds are unaffected.

The root cause is in @astrojs/compiler's GetPropsType function (internal/js_scanner/js_scanner.go). Unlike the sibling FindTopLevelReturns function which correctly skips comment tokens, GetPropsType has no comment handling at all. When a block comment (e.g., JSDoc) contains </> characters (from embedded HTML like <Button>Click me</Button>), those characters are processed by the angle-bracket tracking logic meant for generic type parameters. Each < found in the comment inflates the position counter by the full comment length, causing an out-of-bounds slice access that panics the Go/WASM runtime. The --- sequences in the reporter's examples are a red herring — the actual trigger is </> inside comments combined with generic Props.

I was unable to find a fix for this issue. The bug is in the upstream @astrojs/compiler Go package (compiled to WASM), so it cannot be fixed in this repository. The fix requires two changes in withastro/compiler: (1) add CommentToken/CommentLineTerminatorToken handling to skip comments in GetPropsType, and (2) fix a < double-counting bug in the angle-bracket tracking loop. A detailed proposed fix with four test cases has been documented. The upstream issue is withastro/compiler#1159. As a workaround, remove HTML tags from JSDoc comments in the frontmatter, or use a non-generic Props interface.

Full Triage Report

Reproduction

Reproduced: Yes, on @astrojs/compiler@4.0.0 and @astrojs/compiler@2.13.1.

Minimal reproduction (187 bytes):

---
/**
 * ```astro
 * ---
 * import Foo from 'foo';
 * ---
 * <Foo xxxxx />
 * ```
 */
interface Props<T = string> {
  value?: T;
}
const { value } = Astro.props;
---
<div>{value}</div>

Error output:

panic: runtime error: slice bounds out of range [:198] with capacity 192

goroutine 6 [running]:
github.com/withastro/compiler/internal/js_scanner.GetPropsType(...)
    github.com/withastro/compiler/internal/js_scanner/js_scanner.go:637 +0x13d

Diagnosis

Root Cause

The bug is in @astrojs/compiler's GetPropsType function in internal/js_scanner/js_scanner.go. There are two defects:

Defect 1 (primary): Comment tokens are not skipped. The GetPropsType function uses a JS lexer to tokenize the full .astro file. Block comments (/* ... */) are returned as single CommentToken tokens. The sibling FindTopLevelReturns function in the same file correctly skips these (line 88-92), but GetPropsType has no comment handling at all. When a comment contains </> characters (e.g., HTML tags in JSDoc code examples), the bytes.ContainsAny(value, "<>") check matches. The inner for _, c := range value loop then iterates over every byte, and for each < byte, executes i += len(value) — adding the entire comment length to the position counter. After the loop, the outer loop's i += len(value) adds it again. For a comment of length L with N < characters, i is inflated by L × N bytes.

Defect 2: Double-counting of < tokens. The < token increments i both inside the inner for loop and at the bottom of the outer loop, resulting in a double-count of 1 byte per <.

Why --- appears correlated

The --- is not the direct cause. Embedded Astro code examples that include --- almost always also include HTML elements (like <Button>), which provide the </> characters that trigger the real bug. A comment with only --- but no </> would NOT crash; a comment with </> but no --- WOULD crash.

Trigger conditions (ALL must be present)

1. A block comment (/* ... */) in the frontmatter containing < or > characters
2. Generic type parameters on the Props interface (e.g., Props<T>, Props<Tag extends HTMLTag>)
3. Enough content that the inflated position exceeds the source buffer's capacity

Systematic test results

</> in comment	Generic Props	Crash?
None	Yes	✅ Pass
None (long docs)	Yes	✅ Pass
Yes	No	✅ Pass
Yes (small)	Yes	✅ Pass (within cap)
Yes (larger)	Yes	❌ Crash
Yes (multiple)	Yes	❌ Crash

Affected versions

• @astrojs/compiler@4.0.0 (latest, used by astro@6.3.6)
• @astrojs/compiler@2.13.1 (used by language server)
• All earlier versions with GetPropsType

Affected code paths

• convertToTSX (language server, astro check, IDE features) — crashes
• astro build — NOT affected (uses transform, handles Props differently)

Proposed Fix (for withastro/compiler)

Change 1: Add comment token handling to GetPropsType:

if token == js.CommentToken || token == js.CommentLineTerminatorToken {
    i += len(value)
    continue
}

Change 2: Fix double-counting in <> handling:

// Before:
if c == '<' {
    pairs['<']++
    i += len(value)  // ← REMOVE
    continue
}
// ...
end = i             // ← CHANGE to: end = i + len(value)

// After:
if c == '<' {
    pairs['<']++
    continue
}
// ...
end = i + len(value)

Proposed test cases: Four tests added covering generic Props with JSDoc containing HTML tags, embedded Astro code examples, multiple HTML tags, and non-generic Props as a control.

Workarounds

1. Remove HTML tags from JSDoc/block comments in frontmatter
2. Remove generic type parameters from the Props interface (use non-generic interface Props extends Polymorphic<...>)
3. Move documentation comments containing HTML outside the frontmatter

Upstream issue

withastro/compiler#1159

This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.

[matthewp]

@SalahAdDin can you check if this is a problem with https://github.com/withastro/compiler-rs as well? And if so, please file an issue there.

[Princesseuh]

The Rust compiler does not have a TSX output, so it's not a valid alternative here.

[SalahAdDin]

The Rust compiler does not have a TSX output, so it's not a valid alternative here.

@matthewp, so we have any other alternative?

[matthewp]

@SalahAdDin No, we're going to add TSX output to the new compiler, at which time we can fix this issue.