Stop emitting a JSDoc cast into every Svelte variant (fixes #580)

Live mode scaffolds each Svelte variant with a props script that annotated the
declaration:

    /** @type {{ title: string; }} */
    let { title } = $props();

A JSDoc `@type` written directly before a value is also JSDoc's cast syntax,
and esrap 2.3.3, the printer Svelte emits JS through, moves that annotation
onto the template's own declaration:

    var /** @type {{ title: string; }} */ (h1) = root();

`var (h1) = ...` does not parse. The .svelte source is valid, the compile
succeeds, and the failure lands in the browser's dynamic import as "Unexpected
token '('": the variant never mounts and the session shows nothing. `@typedef`
carries the same shape without being a cast, so both builders emit that.

This is not test-only. Every Svelte variant we generate carried the construct,
so live mode was broken for any user whose install resolved esrap 2.3.3.
Svelte declares `esrap: ^2.2.12`, so a fresh install takes it; this repo's
lockfile pins 2.3.0, which is why unit tests stayed green while the fixture,
which installs into a temp dir, did not.

Two reasons the existing pre-publish guard could not have caught it, now
recorded next to it:

  - `compileCheckVariants` compiles with `generate: false`, so there is no
    emitted JS to inspect.
  - `loadSvelteCompiler` resolves the compiler through createRequire, which
    Svelte's export map routes to a prebuilt CJS build. A dev server imports
    `src/compiler`, and only that path runs the app's installed printer. The
    guard was checking a different compiler than the browser runs.

The new suite therefore imports the compiler as ESM and asserts the emitted
JavaScript parses, rather than pinning the comment style: a future printer that
mangles some other construct fails it too. The first draft used createRequire
and reported green against the exact input that breaks in a browser, which is
the mistake worth not repeating.

Verified against svelte 5.56.9 with esrap 2.3.3. Full live-e2e sweep green,
26 fixtures.

Written with AI assistance (Claude Code).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

skill/scripts/live/svelte-ast.mjs

@@ -933,9 +933,17 @@ function collectFreeIdentifierRanges(node, scopes, emit) {
  * Build the preview component's script block from a v2 contract, with
  * defaults that keep an unhydrated mount rendering instead of crashing.
  */
+// `/** @type {...} */` directly before a destructuring declaration is also
+// JSDoc's cast syntax, and Svelte 5.50+ re-emits the annotation in cast form
+// onto the template's own declaration: `var /** @type {...} */ (h1) = root()`.
+// That is a syntax error, so the browser's dynamic import of the variant dies
+// with "Unexpected token '('" and nothing renders. `@typedef` carries the same
+// shape without being a cast. Keep it a typedef; see PROPS_SCRIPT_SHAPES in
+// tests/live-svelte-props-script.test.mjs, which compiles what these builders
+// emit and parses the result.
 export function buildPropsScriptV2(contract) {
   if (!contract || contract.length === 0) {
-    return '<script>\n  /** @type {Record<string, never>} */\n  let {} = $props();\n</script>\n';
+    return '<script>\n  /** @typedef {Record<string, never>} Props */\n  let {} = $props();\n</script>\n';
   }
   const defaults = {
     text: "''",
@@ -957,5 +965,5 @@ export function buildPropsScriptV2(contract) {
   const typeFields = contract
     .map((c) => `    ${c.prop}?: ${types[c.kind] ?? 'string'};`)
     .join('\n');
-  return `<script>\n  /** @type {{\n${typeFields}\n  }} */\n  let { ${names} } = $props();\n</script>\n`;
+  return `<script>\n  /** @typedef {{\n${typeFields}\n  }} Props */\n  let { ${names} } = $props();\n</script>\n`;
 }

skill/scripts/live/svelte-component.mjs

@@ -154,13 +154,19 @@ export function parseSvelteComponentFile(content) {
   return { markup, cssLines, styleBlock };
 }
 
+// A JSDoc `@type` directly before a destructuring declaration is JSDoc cast
+// syntax, and Svelte 5.50+ re-emits it onto the template's own declaration as
+// `var /** @type {...} */ (h1) = root()`, which does not parse. The browser's
+// import of the variant then fails with "Unexpected token '('" and the session
+// shows nothing. `@typedef` documents the same shape without being a cast.
+// tests/live-svelte-props-script.test.mjs compiles and parses what this emits.
 function buildPropsScript(contract) {
   if (contract.length === 0) {
-    return '<script>\n  /** @type {Record<string, never>} */\n  let {} = $props();\n</script>\n';
+    return '<script>\n  /** @typedef {Record<string, never>} Props */\n  let {} = $props();\n</script>\n';
   }
   const names = contract.map((c) => c.prop).join(', ');
   const typeFields = contract.map((c) => `    ${c.prop}: string;`).join('\n');
-  return `<script>\n  /** @type {{\n${typeFields}\n  }} */\n  let { ${names} } = $props();\n</script>\n`;
+  return `<script>\n  /** @typedef {{\n${typeFields}\n  }} Props */\n  let { ${names} } = $props();\n</script>\n`;
 }
 
 function buildVariantStub(variantNum, originalWithProps, contract) {
@@ -1111,6 +1117,24 @@ export function removeSvelteComponentSession(id, cwd = process.cwd()) {
  * seeded one) used to surface as a red Vite overlay in the user's page plus
  * a mount-failure round trip; bounced at publish time it is a private
  * agent-side fix with the exact file and line.
+ *
+ * What this deliberately does NOT prove is that the emitted module is valid
+ * JavaScript, and issue #580 was exactly that gap: valid .svelte source whose
+ * generated JS did not parse, so this check passed and the browser's import
+ * failed with "Unexpected token '('". Two reasons it cannot close the gap, both
+ * structural rather than oversights:
+ *
+ *   - `generate: false` produces no JS to inspect, and generating it here would
+ *     spend a full codegen per variant on the publish path.
+ *   - `loadSvelteCompiler` reaches the compiler through createRequire, which
+ *     Svelte's export map routes to a prebuilt CJS build. The dev server
+ *     imports `src/compiler` instead, and only that path uses the app's
+ *     installed printer (esrap). The two can disagree, so even a generated
+ *     check here would be checking a different compiler than the one whose
+ *     output the browser runs.
+ *
+ * tests/live-svelte-props-script.test.mjs covers the emitted JS, importing the
+ * compiler as ESM so it sees what the dev server sees.
  */
 export function compileCheckVariants(id, cwd = process.cwd()) {
   const manifest = findSvelteComponentManifest(id, cwd);