The design language that makes your AI harness better at design.
JavaScript
Stop emitting a JSDoc cast into every Svelte variant (fixes #580)
Paul Bakaus5961269cb5e7
diff --git a/scripts/test-suites.mjs b/scripts/test-suites.mjsindex c488973e1..7f726fa6e 100644--- a/scripts/test-suites.mjs+++ b/scripts/test-suites.mjs@@ -161,6 +161,7 @@ export const SUITES = {'tests/live-source-search.test.mjs','tests/live-svelte-ast.test.mjs','tests/live-svelte-component-accept.test.mjs',+ 'tests/live-svelte-props-script.test.mjs','tests/live-tanstack-adapter.test.mjs','tests/live-target-context.test.mjs','tests/live-ui-surfaces.test.mjs',diff --git a/skill/scripts/live/svelte-ast.mjs b/skill/scripts/live/svelte-ast.mjsindex 06e18b62e..dae6f8312 100644--- a/skill/scripts/live/svelte-ast.mjs+++ b/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`;}diff --git a/skill/scripts/live/svelte-component.mjs b/skill/scripts/live/svelte-component.mjsindex 4993453a7..8e2c33deb 100644--- a/skill/scripts/live/svelte-component.mjs+++ b/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);diff --git a/tests/live-svelte-props-script.test.mjs b/tests/live-svelte-props-script.test.mjsnew file mode 100644index 000000000..e662a276d--- /dev/null+++ b/tests/live-svelte-props-script.test.mjs@@ -0,0 +1,163 @@+/**+ * The variant components live mode scaffolds must survive the app's own Svelte+ * compiler AND parse as JavaScript afterwards. Run with:+ * node --test tests/live-svelte-props-script.test.mjs+ *+ * `compileCheckVariants` already compiles each variant with `generate: false`,+ * which proves the .svelte source parses. It cannot prove the emitted module+ * parses, and that is the gap this suite covers. In issue #580, esrap 2.3.3+ * (Svelte's JS printer, pulled in by `esrap: ^2.2.12`) printed a+ * `/** @type {...} *\/` written directly before a destructuring declaration as+ * JSDoc cast syntax on the template's own declaration,+ *+ * var /** @type {{ title: string; }} *\/ (h1) = root();+ *+ * which compiles without complaint and then dies in the browser's dynamic+ * import with "Unexpected token '('". Nothing rendered, and the failure+ * surfaced two layers away from the comment that caused it.+ *+ * Two things follow, and both shape this file:+ *+ * 1. The assertion is on the emitted JavaScript, never on the comment style. A+ * future printer that mangles some other construct fails here too, which a+ * test pinned to `@typedef` would not.+ * 2. The compiler is imported as ESM, because that is what the dev server+ * resolves. Svelte's export map sends `require` to a prebuilt CJS compiler+ * and `import` to `src/compiler`, and only the latter goes through the+ * installed esrap. Reaching for `createRequire` here (as `loadSvelteCompiler`+ * does) compiles with a different printer than the browser ever sees, and+ * the guard passes while the product is broken. That is not hypothetical:+ * the first draft of this suite did exactly that and reported green.+ */++import { describe, it, before, beforeEach, afterEach } from 'node:test';+import assert from 'node:assert/strict';+import fs from 'node:fs';+import path from 'node:path';+import os from 'node:os';+import { createRequire } from 'node:module';+import { fileURLToPath } from 'node:url';++import { buildPropsScriptV2 } from '../skill/scripts/live/svelte-ast.mjs';+import { scaffoldSvelteComponentSession } from '../skill/scripts/live/svelte-component.mjs';++const require = createRequire(import.meta.url);+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');++let compile;+let acornParse;+let svelteVersion;+let printerVersion;++before(async () => {+ // ESM import, not createRequire: see note 2 in the header. This is the build+ // a Vite dev server loads, and the only one that uses the installed esrap.+ const compiler = await import('svelte/compiler');+ compile = compiler.compile;+ svelteVersion = compiler.VERSION;+ acornParse = require('acorn').parse;+ try {+ printerVersion = require('esrap/package.json').version;+ } catch {+ printerVersion = 'unknown';+ }+});++function assertEmittedJsParses(svelteSource, label) {+ const { js } = compile(svelteSource, {+ generate: 'client',+ // dev:true is what a dev server uses, and it is the mode that carries the+ // defect: the extra location metadata is where the stray annotation lands.+ dev: true,+ filename: 'v1.svelte',+ });+ try {+ acornParse(js.code, { ecmaVersion: 'latest', sourceType: 'module' });+ } catch (err) {+ const line = js.code.split('\n')[(err.loc?.line ?? 1) - 1] || '';+ assert.fail(+ `${label}: svelte ${svelteVersion} (printer esrap ${printerVersion}) emitted JavaScript that does not parse.\n`+ + ` ${err.message}\n`+ + ` offending line: ${line.trim()}\n`+ + ` The browser reports this as a mount failure, not as a compile error, `+ + `because the .svelte source is valid and only the emitted module is not.\n`+ + ` source:\n${svelteSource}`,+ );+ }+}++describe('scaffolded props scripts emit parseable JavaScript', () => {+ // The empty contract is the shape the CI fixture hit: a picked element with+ // no dynamic values at all.+ const CONTRACTS = {+ 'no props': [],+ 'one text prop': [{ prop: 'title', expr: 'title', kind: 'text' }],+ 'every prop kind': [+ { prop: 'title', expr: 'title', kind: 'text' },+ { prop: 'body', expr: 'post.body', kind: 'raw' },+ { prop: 'isOpen', expr: 'open', kind: 'condition' },+ { prop: 'items', expr: 'stages', kind: 'collection' },+ { prop: 'onSelect', expr: 'select', kind: 'handler' },+ ],+ };++ for (const [label, contract] of Object.entries(CONTRACTS)) {+ it(`buildPropsScriptV2: ${label}`, () => {+ const source = `${buildPropsScriptV2(contract)}\n<h1 class="hero-title">Fixture</h1>\n`;+ assertEmittedJsParses(source, `buildPropsScriptV2 (${label})`);+ });+ }++ // Deliberately NOT asserted here: that the old `@type` shape still breaks.+ // Whether it breaks depends on the installed printer (esrap 2.3.3 yes, 2.3.2+ // no), and this repo's lockfile carries a good one while a fresh fixture+ // install pulls the bad one. An assertion that upstream is still broken would+ // fail in this repo and pass in CI, which is the wrong way round for a guard.+ // The live-e2e suite installs fresh and is where the real printer gets+ // exercised; these cases pin what we emit, on whatever printer is present.+});++describe('the real scaffolder writes variants that parse', () => {+ let scratch;++ beforeEach(() => {+ scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'impeccable-svelte-scaffold-'));+ // The scaffolder resolves the compiler from the app root, so the staged app+ // needs a package.json and a reachable svelte. Symlinking the repo's+ // node_modules is what the static fixture sweep already does.+ fs.writeFileSync(path.join(scratch, 'package.json'), JSON.stringify({ name: 'app', type: 'module' }));+ fs.symlinkSync(path.join(REPO_ROOT, 'node_modules'), path.join(scratch, 'node_modules'), 'dir');+ });++ afterEach(() => {+ fs.rmSync(scratch, { recursive: true, force: true });+ });++ const CASES = {+ 'static markup (the #580 shape)': ['<h1 class="hero-title">Vite 8 + SvelteKit Fixture</h1>'],+ 'markup with a free expression': ['<h1 class="hero-title">{headline}</h1>'],+ };++ for (const [label, originalLines] of Object.entries(CASES)) {+ it(label, () => {+ const result = scaffoldSvelteComponentSession({+ id: 'testsession',+ count: 3,+ sourceFile: 'src/routes/+page.svelte',+ sourceStartLine: 1,+ sourceEndLine: originalLines.length,+ originalLines,+ cwd: scratch,+ });+ assert.equal(result.fallback, undefined, `scaffold fell back: ${result.reason}`);++ const dir = path.join(scratch, 'node_modules', '.impeccable-live', 'testsession');+ const variants = fs.readdirSync(dir).filter((name) => /^v\d+\.svelte$/.test(name));+ assert.ok(variants.length > 0, 'scaffolder wrote no variant files');++ for (const name of variants) {+ assertEmittedJsParses(fs.readFileSync(path.join(dir, name), 'utf-8'), `${label} / ${name}`);+ }+ });+ }+});