quiver-cli 1.3.0 → 2.0.0

package/template/.agents/skills/design/impeccable/scripts/live/svelte-ast.mjs

@@ -1,961 +0,0 @@
-/**
- * AST-based Svelte scaffolding for live component previews.
- *
- * The scaffolder turns the selected block of a route's markup into a detached
- * preview component whose dynamic values arrive as props. The old
- * implementation matched `{...}` with a regex, which flattened control-flow
- * blocks ({#each}, {#if}) into scalar text props and shipped structurally
- * wrong previews. This module uses the app's own svelte compiler
- * (parse with modern: true) and replaces only expressions that are FREE,
- * i.e. reference identifiers not bound by an enclosing template scope:
- *
- *   {#each stages as stage, i}     stages  -> collection prop (array)
- *     <span>{stage.label}</span>   bound   -> left verbatim
- *   {/each}
- *   <p>{footerNote}</p>            free    -> text prop (string)
- *
- * Constructs that cannot work in a detached component (component tags whose
- * imports live in the route file, bind:/use: directives, await blocks,
- * render tags) mark the analysis unsupported; the caller falls back to
- * source-preview mode, which keeps the markup inside the route file where
- * those references still resolve. A wrong preview is worse than a plain one.
- *
- * The compiler is resolved from the APP's node_modules, never bundled: the
- * preview must be parsed by the same svelte version that will compile it.
- */
-
-import { createRequire } from 'node:module';
-import path from 'node:path';
-
-const HANDLER_ATTR_RE = /^on[a-z]/;
-
-/**
- * Resolve the app's svelte compiler synchronously (svelte 5 ships a CJS
- * compiler build, so createRequire works and the accept/scaffold pipeline
- * stays synchronous). Returns { parse, compile, VERSION } or null.
- */
-export function loadSvelteCompiler(appRoot) {
-  try {
-    const req = createRequire(path.join(appRoot, 'package.json'));
-    const mod = req('svelte/compiler');
-    if (typeof mod.parse !== 'function') return null;
-    const major = parseInt(String(mod.VERSION || '0'), 10);
-    if (major < 5) return null; // detached mount() previews are svelte 5 only
-    return { parse: mod.parse, compile: mod.compile, VERSION: mod.VERSION };
-  } catch {
-    return null;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// ESTree helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Collect the root identifiers an ESTree expression reads. Walks generically;
- * skips non-computed member properties and non-computed/non-shorthand object
- * keys, which are names, not references.
- */
-export function collectRootIdentifiers(node, out = new Set()) {
-  if (!node || typeof node !== 'object') return out;
-  if (Array.isArray(node)) {
-    for (const item of node) collectRootIdentifiers(item, out);
-    return out;
-  }
-  switch (node.type) {
-    case 'Identifier':
-      out.add(node.name);
-      return out;
-    case 'MemberExpression':
-      collectRootIdentifiers(node.object, out);
-      if (node.computed) collectRootIdentifiers(node.property, out);
-      return out;
-    case 'Property':
-      if (node.computed) collectRootIdentifiers(node.key, out);
-      collectRootIdentifiers(node.value, out);
-      return out;
-    case 'ArrowFunctionExpression':
-    case 'FunctionExpression': {
-      // Params shadow outer names inside the body.
-      const bound = new Set();
-      for (const param of node.params || []) collectPatternNames(param, bound);
-      const inner = collectRootIdentifiers(node.body, new Set());
-      for (const name of inner) if (!bound.has(name)) out.add(name);
-      return out;
-    }
-    default: {
-      for (const key of Object.keys(node)) {
-        if (key === 'type' || key === 'start' || key === 'end' || key === 'loc' || key === 'range' || key === 'parent') continue;
-        collectRootIdentifiers(node[key], out);
-      }
-      return out;
-    }
-  }
-}
-
-/** Collect names bound by a destructuring pattern (each contexts, const tags). */
-export function collectPatternNames(pattern, out = new Set()) {
-  if (!pattern || typeof pattern !== 'object') return out;
-  switch (pattern.type) {
-    case 'Identifier':
-      out.add(pattern.name);
-      return out;
-    case 'ObjectPattern':
-      for (const prop of pattern.properties || []) {
-        if (prop.type === 'RestElement') collectPatternNames(prop.argument, out);
-        else collectPatternNames(prop.value, out);
-      }
-      return out;
-    case 'ArrayPattern':
-      for (const el of pattern.elements || []) if (el) collectPatternNames(el, out);
-      return out;
-    case 'AssignmentPattern':
-      collectPatternNames(pattern.left, out);
-      return out;
-    case 'RestElement':
-      collectPatternNames(pattern.argument, out);
-      return out;
-    default:
-      return out;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Template analysis
-// ---------------------------------------------------------------------------
-
-class Analysis {
-  constructor(source) {
-    this.source = source;
-    this.replacements = []; // { start, end, prop } source ranges to swap
-    this.contract = [];     // [{ prop, expr, kind, ... }]
-    this.byExpr = new Map(); // expr text -> contract entry
-    this.usedNames = new Set();
-    this.unsupported = null;
-  }
-
-  fail(reason) {
-    if (!this.unsupported) this.unsupported = reason;
-  }
-
-  propFor(exprText, kind, extra = {}) {
-    const existing = this.byExpr.get(exprText);
-    if (existing) return existing;
-    const base = derivePropName(exprText);
-    let name = base;
-    let n = 2;
-    while (this.usedNames.has(name)) name = `${base}${n++}`;
-    this.usedNames.add(name);
-    const entry = { prop: name, expr: exprText, kind, ...extra };
-    this.byExpr.set(exprText, entry);
-    this.contract.push(entry);
-    return entry;
-  }
-}
-
-// A derived prop name lands in `let { <name> } = $props()`; a reserved word
-// there is a syntax error the session only hits at import time.
-const RESERVED_PROP_NAMES = new Set([
-  'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger',
-  'default', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false',
-  'finally', 'for', 'function', 'if', 'implements', 'import', 'in',
-  'instanceof', 'interface', 'let', 'new', 'null', 'package', 'private',
-  'protected', 'public', 'return', 'static', 'super', 'switch', 'this',
-  'throw', 'true', 'try', 'typeof', 'undefined', 'var', 'void', 'while',
-  'with', 'yield',
-]);
-
-export function derivePropName(expr) {
-  const tail = String(expr).match(/(?:\.|\[["']?)([A-Za-z_$][\w$]*)["']?\]?\s*$/);
-  const candidate = (tail && tail[1])
-    || (String(expr).match(/^([A-Za-z_$][\w$]*)$/) || [])[1]
-    || 'value';
-  return RESERVED_PROP_NAMES.has(candidate) ? `${candidate}Value` : candidate;
-}
-
-function exprText(source, node) {
-  return source.slice(node.start, node.end);
-}
-
-// Identifiers that resolve in ANY module scope. They are neither hydratable
-// props nor evidence of route coupling, so they count as neither free nor
-// bound: `{Math.round(x)}` must not mint a prop named `round`, and
-// `{fmt(stage.label)}` must not pass as global-only.
-const GLOBAL_IDENTIFIERS = new Set([
-  'Math', 'JSON', 'Date', 'Intl', 'Number', 'String', 'Boolean', 'Array',
-  'Object', 'Map', 'Set', 'Promise', 'RegExp', 'NaN', 'Infinity', 'undefined',
-  'isNaN', 'isFinite', 'parseInt', 'parseFloat', 'encodeURIComponent',
-  'decodeURIComponent', 'console', 'window', 'document', 'navigator',
-  'location', 'structuredClone', 'crypto',
-]);
-
-function classifyRoots(node, scopes) {
-  const roots = collectRootIdentifiers(node);
-  let bound = 0;
-  let free = 0;
-  for (const name of roots) {
-    if (GLOBAL_IDENTIFIERS.has(name)) continue;
-    if (scopes.some((scope) => scope.has(name))) bound++;
-    else free++;
-  }
-  return { bound, free };
-}
-
-function isFree(node, scopes) {
-  const { bound, free } = classifyRoots(node, scopes);
-  return free > 0 && bound === 0;
-}
-
-/**
- * An expression mixing loop-bound and outer free identifiers (e.g.
- * `{fmt(stage.label)}` where `fmt` lives in the route script) can neither
- * become a prop (the bound part varies per item) nor survive detachment
- * verbatim (the free name is undeclared in the preview and throws at mount,
- * past the compile gate, because globals make it legal to the compiler).
- * Source-preview mode is the only correct home for it.
- */
-function failOnMixedExpression(node, scopes, analysis, source) {
-  const { bound, free } = classifyRoots(node, scopes);
-  if (bound > 0 && free > 0) {
-    analysis.fail(`expression mixing loop and outer identifiers ({${exprText(source, node).slice(0, 60)}}) requires source-preview mode`);
-    return true;
-  }
-  return false;
-}
-
-/**
- * Analyze a parsed template fragment. `scopes` is a stack of Sets of bound
- * names; the outermost call passes an empty stack.
- */
-function analyzeFragment(fragment, analysis, scopes) {
-  if (!fragment || !Array.isArray(fragment.nodes)) return;
-  // ConstTag declarations bind for the whole fragment.
-  const fragmentScope = new Set();
-  const nextScopes = [...scopes, fragmentScope];
-  for (const node of fragment.nodes) {
-    if (node.type === 'ConstTag' && node.declaration) {
-      for (const decl of node.declaration.declarations || []) {
-        collectPatternNames(decl.id, fragmentScope);
-      }
-    }
-  }
-  for (const node of fragment.nodes) analyzeNode(node, analysis, nextScopes);
-}
-
-function analyzeNode(node, analysis, scopes) {
-  if (!node || analysis.unsupported) return;
-  switch (node.type) {
-    case 'Text':
-    case 'Comment':
-      return;
-    case 'ExpressionTag': {
-      if (failOnMixedExpression(node.expression, scopes, analysis, analysis.source)) return;
-      if (isFree(node.expression, scopes)) {
-        const text = exprText(analysis.source, node.expression);
-        const entry = analysis.propFor(text, 'text');
-        // node.start/end include the braces; keep them, swap the inside.
-        analysis.replacements.push({ start: node.expression.start, end: node.expression.end, prop: entry.prop });
-      }
-      return;
-    }
-    case 'HtmlTag': {
-      if (failOnMixedExpression(node.expression, scopes, analysis, analysis.source)) return;
-      if (isFree(node.expression, scopes)) {
-        const text = exprText(analysis.source, node.expression);
-        const entry = analysis.propFor(text, 'raw');
-        analysis.replacements.push({ start: node.expression.start, end: node.expression.end, prop: entry.prop });
-      }
-      return;
-    }
-    case 'ConstTag': {
-      // Its expression may read free names; leave them: the declaration
-      // travels with the markup and stays valid only if its inputs do.
-      if (node.declaration) {
-        for (const decl of node.declaration.declarations || []) {
-          if (decl.init && failOnMixedExpression(decl.init, scopes, analysis, analysis.source)) return;
-          if (decl.init && isFree(decl.init, scopes)) {
-            const text = exprText(analysis.source, decl.init);
-            const entry = analysis.propFor(text, 'text');
-            analysis.replacements.push({ start: decl.init.start, end: decl.init.end, prop: entry.prop });
-          }
-        }
-      }
-      return;
-    }
-    case 'EachBlock': {
-      if (failOnMixedExpression(node.expression, scopes, analysis, analysis.source)) return;
-      if (isFree(node.expression, scopes)) {
-        const text = exprText(analysis.source, node.expression);
-        const item = describeEachItem(node, analysis.source);
-        // Keyed each: the key must evaluate to a distinct value per hydrated
-        // item or Svelte throws each_key_duplicate at mount. A key that is a
-        // plain member of the item (the common `(item.id)` shape) gets a
-        // synthetic per-index value injected by the browser (keyField).
-        // Anything else cannot be hydrated safely; source-preview mode keeps
-        // it correct.
-        if (node.key) {
-          const keyInfo = classifyEachKey(node);
-          if (keyInfo.unsupported) {
-            analysis.fail(keyInfo.unsupported);
-            return;
-          }
-          if (keyInfo.keyField) {
-            if (item.textSlots.some((slot) => slot.key === keyInfo.keyField)) {
-              // The key doubles as a displayed slot; a synthetic value would
-              // change visible text, and the displayed text may not be
-              // unique. Not previewable in a detached component.
-              analysis.fail('each key that is also a displayed field requires source-preview mode');
-              return;
-            }
-            item.keyField = keyInfo.keyField;
-          }
-        }
-        const entry = analysis.propFor(text, 'collection', { item });
-        analysis.replacements.push({ start: node.expression.start, end: node.expression.end, prop: entry.prop });
-      }
-      const bound = new Set();
-      if (node.context) collectPatternNames(node.context, bound);
-      if (node.index) bound.add(node.index);
-      analyzeFragment(node.body, analysis, [...scopes, bound]);
-      if (node.fallback) analyzeFragment(node.fallback, analysis, scopes);
-      return;
-    }
-    case 'IfBlock': {
-      if (failOnMixedExpression(node.test, scopes, analysis, analysis.source)) return;
-      if (isFree(node.test, scopes)) {
-        const text = exprText(analysis.source, node.test);
-        // The browser hydrates a free condition from what the live page
-        // currently shows: when the consequent's root element is present
-        // under the picked element, the condition is on.
-        const entry = analysis.propFor(text, 'condition', {
-          probe: describeElementProbe(node.consequent),
-        });
-        analysis.replacements.push({ start: node.test.start, end: node.test.end, prop: entry.prop });
-      }
-      analyzeFragment(node.consequent, analysis, scopes);
-      if (node.alternate) analyzeFragment(node.alternate, analysis, scopes);
-      return;
-    }
-    case 'KeyBlock': {
-      if (failOnMixedExpression(node.expression, scopes, analysis, analysis.source)) return;
-      if (isFree(node.expression, scopes)) {
-        const text = exprText(analysis.source, node.expression);
-        const entry = analysis.propFor(text, 'text');
-        analysis.replacements.push({ start: node.expression.start, end: node.expression.end, prop: entry.prop });
-      }
-      analyzeFragment(node.fragment, analysis, scopes);
-      return;
-    }
-    case 'SnippetBlock': {
-      const bound = new Set();
-      for (const param of node.parameters || []) collectPatternNames(param, bound);
-      // The snippet's own name becomes available to render tags in this file.
-      analyzeFragment(node.body, analysis, [...scopes, bound]);
-      return;
-    }
-    case 'RegularElement':
-    case 'SlotElement':
-    case 'TitleElement': {
-      if (node.name === 'script') {
-        // An inline script inside the selected block carries route-scoped
-        // code; running it a second time from a detached preview is wrong.
-        analysis.fail('inline script element requires source-preview mode');
-        return;
-      }
-      analyzeAttributes(node, analysis, scopes);
-      if (!analysis.unsupported) analyzeFragment(node.fragment, analysis, scopes);
-      return;
-    }
-    case 'SvelteElement':
-    case 'SvelteFragment':
-    case 'SvelteBoundary': {
-      analyzeAttributes(node, analysis, scopes);
-      if (!analysis.unsupported) analyzeFragment(node.fragment, analysis, scopes);
-      return;
-    }
-    case 'Component':
-    case 'SvelteComponent':
-    case 'SvelteSelf':
-      // The component's import lives in the route file; a detached preview
-      // cannot resolve it. Source-preview mode keeps it working.
-      analysis.fail(`component tag <${node.name || 'Component'}> requires source-preview mode`);
-      return;
-    case 'RenderTag':
-      analysis.fail('render tag requires source-preview mode');
-      return;
-    case 'AwaitBlock':
-      analysis.fail('await block requires source-preview mode');
-      return;
-    case 'SvelteHead':
-    case 'SvelteWindow':
-    case 'SvelteDocument':
-    case 'SvelteBody':
-      analysis.fail(`${node.type} requires source-preview mode`);
-      return;
-    default: {
-      if (node.fragment) analyzeFragment(node.fragment, analysis, scopes);
-      return;
-    }
-  }
-}
-
-function analyzeAttributes(node, analysis, scopes) {
-  for (const attr of node.attributes || []) {
-    switch (attr.type) {
-      case 'Attribute': {
-        if (attr.value === true) break;
-        const parts = Array.isArray(attr.value) ? attr.value : [attr.value];
-        for (const part of parts) {
-          if (!part || part.type !== 'ExpressionTag') continue;
-          if (failOnMixedExpression(part.expression, scopes, analysis, analysis.source)) return;
-          if (!isFree(part.expression, scopes)) continue;
-          const text = exprText(analysis.source, part.expression);
-          const kind = HANDLER_ATTR_RE.test(attr.name) ? 'handler' : 'text';
-          const entry = analysis.propFor(text, kind);
-          analysis.replacements.push({ start: part.expression.start, end: part.expression.end, prop: entry.prop });
-        }
-        break;
-      }
-      case 'ClassDirective': {
-        const expr = attr.expression;
-        if (expr && failOnMixedExpression(expr, scopes, analysis, analysis.source)) return;
-        if (expr && isFree(expr, scopes)) {
-          const text = exprText(analysis.source, expr);
-          // The directive's class name is literal, so the live DOM answers
-          // the condition directly: the class is either present or not.
-          const entry = analysis.propFor(text, 'condition', {
-            probe: { className: attr.name },
-          });
-          analysis.replacements.push({ start: expr.start, end: expr.end, prop: entry.prop });
-        }
-        break;
-      }
-      case 'StyleDirective': {
-        // Unlike ClassDirective, a style directive stores its value in
-        // attribute shape: `true` for the shorthand, else an array of parts.
-        const parts = attr.value === true ? [] : (Array.isArray(attr.value) ? attr.value : [attr.value]);
-        for (const part of parts) {
-          if (part?.type === 'ExpressionTag'
-              && failOnMixedExpression(part.expression, scopes, analysis, analysis.source)) {
-            return;
-          }
-        }
-        const dynamic = parts.some((part) => part?.type === 'ExpressionTag' && isFree(part.expression, scopes));
-        const shorthandFree = attr.value === true && isFree({ type: 'Identifier', name: attr.name }, scopes);
-        if (dynamic || shorthandFree) {
-          // style:opacity={x} carries a css VALUE, not a boolean, and the
-          // computed value on the live element is not reliably recoverable in
-          // the shape the expression produced. A falsified style is worse
-          // than an HMR-resetting preview.
-          analysis.fail(`style:${attr.name} with a dynamic value requires source-preview mode`);
-        }
-        break;
-      }
-      case 'BindDirective':
-        analysis.fail(`bind:${attr.name} requires source-preview mode`);
-        return;
-      case 'UseDirective':
-        analysis.fail(`use:${attr.name} requires source-preview mode`);
-        return;
-      case 'AnimateDirective':
-      case 'TransitionDirective':
-        // Motion directives reference route-scoped or svelte/transition
-        // imports; a detached preview cannot resolve them.
-        analysis.fail(`${attr.type} requires source-preview mode`);
-        return;
-      case 'OnDirective': {
-        // Legacy on:click syntax; treat like handler attributes.
-        const expr = attr.expression;
-        if (expr && failOnMixedExpression(expr, scopes, analysis, analysis.source)) return;
-        if (expr && isFree(expr, scopes)) {
-          const text = exprText(analysis.source, expr);
-          const entry = analysis.propFor(text, 'handler');
-          analysis.replacements.push({ start: expr.start, end: expr.end, prop: entry.prop });
-        }
-        break;
-      }
-      case 'SpreadAttribute':
-        analysis.fail('spread attribute requires source-preview mode');
-        return;
-      default:
-        break;
-    }
-  }
-}
-
-/**
- * Describe the repeating item of an each block for browser-side hydration:
- * the item's root element (tag + static classes, used to count live
- * iterations) and the ordered text slots that reference loop bindings.
- */
-function describeEachItem(node, source) {
-  const body = node.body;
-  const rootEl = (body?.nodes || []).find((n) => n.type === 'RegularElement');
-
-  const textSlots = [];
-  const staticTexts = [];
-  let nestedUnsupported = false;
-  const collectStatics = (fragment) => {
-    for (const child of fragment?.nodes || []) {
-      if (child.type === 'Text') {
-        const trimmed = String(child.data || '').trim();
-        if (trimmed) staticTexts.push(trimmed);
-      } else if (child.type === 'IfBlock') {
-        collectStatics(child.consequent);
-        if (child.alternate) collectStatics(child.alternate);
-      } else if (child.type === 'EachBlock') {
-        collectStatics(child.body);
-      } else if (child.fragment) {
-        collectStatics(child.fragment);
-      }
-    }
-  };
-  collectStatics(body);
-  const attrSlots = [];
-  // The hydration item is a SHALLOW object whose string fields are the exact
-  // property names the markup accesses, filled from the rendered page. That
-  // model supports one item access per slot, optionally wrapped in a global
-  // transform ({Math.round(r.score)} hydrates `score`). Shapes it cannot
-  // represent split two ways: CRASHY ones would throw at mount time against a
-  // shallow item (deep paths like r.meta.label, method calls like r.format())
-  // and force the source-preview fallback; LOSSY ones render wrong but safe
-  // (bare {r}, multi-access expressions that would double their text) and
-  // also fall back in text position, where the damage is visible.
-  const boundAs = (name, scopeInfos) => {
-    for (let i = scopeInfos.length - 1; i >= 0; i--) {
-      const info = scopeInfos[i];
-      if (info.indexName === name) return 'index';
-      if (info.itemName === name) return 'item';
-      if (info.names.has(name)) return 'field';
-    }
-    return null;
-  };
-  const slotKeysOf = (expression, scopeInfos) => {
-    const keys = new Set();
-    let crashy = false;
-    let lossy = false;
-    let touches = false;
-    const visit = (node, ctx) => {
-      if (!node || typeof node !== 'object' || crashy) return;
-      if (Array.isArray(node)) {
-        for (const item of node) visit(item, {});
-        return;
-      }
-      switch (node.type) {
-        case 'Identifier': {
-          const kind = boundAs(node.name, scopeInfos);
-          if (!kind) return;
-          touches = true;
-          if (kind === 'index') return; // the runtime each provides it
-          if (kind === 'item') { lossy = true; return; } // bare item reference
-          if (ctx.callee) { crashy = true; return; } // field() on a hydrated string
-          keys.add(node.name); // destructured context field
-          return;
-        }
-        case 'MemberExpression': {
-          if (
-            !node.computed
-            && node.object?.type === 'Identifier'
-            && boundAs(node.object.name, scopeInfos) === 'item'
-            && node.property?.type === 'Identifier'
-          ) {
-            touches = true;
-            // item.a.b or item.method(): a shallow string field throws here.
-            if (ctx.memberObject || ctx.callee) { crashy = true; return; }
-            keys.add(node.property.name);
-            return;
-          }
-          visit(node.object, { memberObject: true });
-          if (node.computed) visit(node.property, {});
-          return;
-        }
-        case 'CallExpression':
-          visit(node.callee, { callee: true });
-          for (const arg of node.arguments || []) visit(arg, {});
-          return;
-        case 'ArrowFunctionExpression':
-        case 'FunctionExpression': {
-          // Closures cannot hydrate; only lossy when they capture the item.
-          const roots = collectRootIdentifiers(node);
-          if ([...roots].some((name) => boundAs(name, scopeInfos))) { touches = true; lossy = true; }
-          return;
-        }
-        case 'Property':
-          if (node.computed) visit(node.key, {});
-          visit(node.value, {});
-          return;
-        default: {
-          for (const key of Object.keys(node)) {
-            if (key === 'type' || key === 'start' || key === 'end' || key === 'loc' || key === 'range' || key === 'parent') continue;
-            visit(node[key], {});
-          }
-        }
-      }
-    };
-    visit(expression, {});
-    if (crashy) return { crashy: true };
-    if (lossy || keys.size > 1) return { lossy: true };
-    if (!touches || keys.size === 0) return { skip: true };
-    return { key: [...keys][0] };
-  };
-  const staticClassesOf = (el) => {
-    const classes = [];
-    for (const attr of el?.attributes || []) {
-      if (attr.type === 'Attribute' && attr.name === 'class' && Array.isArray(attr.value)) {
-        for (const part of attr.value) {
-          if (part.type === 'Text') classes.push(...part.data.split(/\s+/).filter(Boolean));
-        }
-      }
-    }
-    return classes;
-  };
-  const scopeInfoOf = (eachNode) => {
-    const names = new Set();
-    if (eachNode.context) collectPatternNames(eachNode.context, names);
-    return {
-      names,
-      itemName: eachNode.context?.type === 'Identifier' ? eachNode.context.name : null,
-      indexName: eachNode.index || null,
-    };
-  };
-  const walkForSlots = (fragment, scopeInfos) => {
-    for (const child of fragment?.nodes || []) {
-      if (child.type === 'ExpressionTag') {
-        const slot = slotKeysOf(child.expression, scopeInfos);
-        if (slot.crashy || slot.lossy) { nestedUnsupported = true; continue; }
-        if (slot.skip) continue;
-        textSlots.push({ key: slot.key, expr: exprText(source, child.expression) });
-      } else if (child.type === 'RegularElement' || child.type === 'SvelteElement') {
-        // Bound values in ATTRIBUTES (href={link.href}, src={item.img}) are
-        // part of the item too: the browser reads the rendered attribute off
-        // the live element, so the preview does not mount with empty links.
-        // Only a single-expression attribute hydrates exactly; a mixed value
-        // ("card {r.status}") stays unhydrated because the rendered attribute
-        // is not separable into its parts, which was the prior behavior.
-        for (const attr of child.attributes || []) {
-          if (attr.type !== 'Attribute' || attr.value === true) continue;
-          if (HANDLER_ATTR_RE.test(attr.name)) continue; // functions cannot hydrate
-          const parts = Array.isArray(attr.value) ? attr.value : [attr.value];
-          const exprParts = parts.filter((part) => part?.type === 'ExpressionTag');
-          for (const part of exprParts) {
-            const slot = slotKeysOf(part.expression, scopeInfos);
-            if (slot.crashy) { nestedUnsupported = true; continue; }
-            if (slot.skip || slot.lossy) continue;
-            if (parts.length !== 1) continue; // mixed static+dynamic value
-            attrSlots.push({
-              key: slot.key,
-              expr: exprText(source, part.expression),
-              attr: attr.name,
-              tag: child.name || null,
-              classes: staticClassesOf(child),
-            });
-          }
-        }
-        walkForSlots(child.fragment, scopeInfos);
-        continue;
-      } else if (child.type === 'EachBlock') {
-        const roots = collectRootIdentifiers(child.expression);
-        const boundNested = [...roots].some((name) => boundAs(name, scopeInfos));
-        if (boundNested) nestedUnsupported = true; // nested per-item arrays: no hydration plan yet
-        walkForSlots(child.body, [...scopeInfos, scopeInfoOf(child)]);
-      } else if (child.type === 'IfBlock') {
-        walkForSlots(child.consequent, scopeInfos);
-        if (child.alternate) walkForSlots(child.alternate, scopeInfos);
-      } else if (child.fragment) {
-        walkForSlots(child.fragment, scopeInfos);
-      }
-    }
-  };
-  walkForSlots(body, [scopeInfoOf(node)]);
-
-  const staticClasses = [];
-  for (const attr of rootEl?.attributes || []) {
-    if (attr.type === 'Attribute' && attr.name === 'class' && Array.isArray(attr.value)) {
-      for (const part of attr.value) {
-        if (part.type === 'Text') staticClasses.push(...part.data.split(/\s+/).filter(Boolean));
-      }
-    }
-  }
-
-  return {
-    rootTag: rootEl?.name || null,
-    rootClasses: staticClasses,
-    textSlots,
-    attrSlots,
-    staticTexts,
-    nestedUnsupported,
-  };
-}
-
-/**
- * Classify a keyed each block's key expression:
- *   { keyField }        member of the loop item (e.g. `(expense.id)` when the
- *                       context binds `expense`): browser injects a unique
- *                       per-index value under that field.
- *   {}                  key is the whole loop item or the index: already
- *                       distinct per iteration, nothing to inject.
- *   { unsupported }     free or complex keys: cannot hydrate distinct values.
- */
-function classifyEachKey(node) {
-  const bound = new Set();
-  if (node.context) collectPatternNames(node.context, bound);
-  if (node.index) bound.add(node.index);
-  const key = node.key;
-  const roots = collectRootIdentifiers(key);
-  const usesLoopBinding = [...roots].some((name) => bound.has(name));
-  if (!usesLoopBinding) {
-    // A key that ignores the loop item is constant across iterations:
-    // guaranteed duplicate keys at mount.
-    return { unsupported: 'each key not derived from the loop item requires source-preview mode' };
-  }
-  if (key.type === 'Identifier' && bound.has(key.name)) return {};
-  if (
-    key.type === 'MemberExpression'
-    && !key.computed
-    && key.object?.type === 'Identifier'
-    && bound.has(key.object.name)
-    && key.property?.type === 'Identifier'
-  ) {
-    return { keyField: key.property.name };
-  }
-  return { unsupported: 'complex each key requires source-preview mode' };
-}
-
-/**
- * Describe a fragment's root element for browser presence probing:
- * { tag, classes } of the first RegularElement, or null for text-only
- * fragments (which cannot be probed reliably).
- */
-function describeElementProbe(fragment) {
-  const rootEl = (fragment?.nodes || []).find((n) => n.type === 'RegularElement');
-  if (!rootEl) return null;
-  const classes = [];
-  for (const attr of rootEl.attributes || []) {
-    if (attr.type === 'Attribute' && attr.name === 'class' && Array.isArray(attr.value)) {
-      for (const part of attr.value) {
-        if (part.type === 'Text') classes.push(...part.data.split(/\s+/).filter(Boolean));
-      }
-    }
-  }
-  return { tag: rootEl.name, classes };
-}
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Analyze a markup block and produce the prop-substituted scaffold markup and
- * the v2 prop contract. Returns { ok: false, reason } when the block needs
- * source-preview mode (parse failure or unsupported construct).
- */
-export function analyzeSvelteMarkup(markup, parse) {
-  const source = String(markup || '');
-  let ast;
-  try {
-    ast = parse(source, { modern: true });
-  } catch (err) {
-    return { ok: false, reason: `svelte parse failed: ${err.message}` };
-  }
-  if (ast.instance || ast.module) {
-    return { ok: false, reason: 'selected block contains a script tag' };
-  }
-  const analysis = new Analysis(source);
-  analyzeFragment(ast.fragment, analysis, []);
-  if (analysis.unsupported) {
-    return { ok: false, reason: analysis.unsupported };
-  }
-  for (const entry of analysis.contract) {
-    if (entry.kind === 'collection' && entry.item?.nestedUnsupported) {
-      return { ok: false, reason: 'per-item content (nested blocks or expressions) this preview cannot hydrate requires source-preview mode' };
-    }
-  }
-
-  const markupWithProps = applyReplacements(source, analysis.replacements);
-  return {
-    ok: true,
-    markupWithProps,
-    contract: analysis.contract.map((entry) => ({
-      prop: entry.prop,
-      expr: entry.expr,
-      kind: entry.kind,
-      // Kept for backward compatibility with v1 consumers (fake e2e agent,
-      // text-only restore paths).
-      placeholder: `{${entry.expr}}`,
-      ...(entry.item ? { item: entry.item } : {}),
-      ...(entry.probe ? { probe: entry.probe } : {}),
-    })),
-  };
-}
-
-function applyReplacements(source, replacements) {
-  const sorted = [...replacements].sort((a, b) => b.start - a.start);
-  let out = source;
-  for (const { start, end, prop } of sorted) {
-    out = out.slice(0, start) + prop + out.slice(end);
-  }
-  return out;
-}
-
-/**
- * Restore a variant's markup back to route-source form: every free
- * identifier that matches a contract prop is replaced by its original
- * expression. AST-based so `{#each stages as stage}` restores to
- * `{#each data.stages as stage}` even though the prop appears without braces.
- */
-export function restoreSvelteMarkup(markup, contract, parse) {
-  const source = String(markup || '');
-  const byProp = new Map();
-  for (const entry of contract || []) byProp.set(entry.prop, entry.expr);
-  if (byProp.size === 0) return { ok: true, markup: source };
-
-  let ast;
-  try {
-    ast = parse(source, { modern: true });
-  } catch (err) {
-    return { ok: false, reason: `variant parse failed: ${err.message}` };
-  }
-
-  const replacements = [];
-  const visitExpr = (expression, scopes) => {
-    if (!expression) return;
-    collectFreeIdentifierRanges(expression, scopes, (name, start, end) => {
-      const original = byProp.get(name);
-      if (original != null && original !== name) replacements.push({ start, end, prop: original });
-    });
-  };
-
-  const walk = (fragment, scopes) => {
-    const fragmentScope = new Set();
-    const nextScopes = [...scopes, fragmentScope];
-    for (const node of fragment?.nodes || []) {
-      if (node.type === 'ConstTag' && node.declaration) {
-        for (const decl of node.declaration.declarations || []) collectPatternNames(decl.id, fragmentScope);
-      }
-    }
-    for (const node of fragment?.nodes || []) {
-      switch (node?.type) {
-        case 'ExpressionTag':
-        case 'HtmlTag':
-          visitExpr(node.expression, nextScopes);
-          break;
-        case 'ConstTag':
-          for (const decl of node.declaration?.declarations || []) visitExpr(decl.init, nextScopes);
-          break;
-        case 'EachBlock': {
-          visitExpr(node.expression, nextScopes);
-          const bound = new Set();
-          if (node.context) collectPatternNames(node.context, bound);
-          if (node.index) bound.add(node.index);
-          // The key evaluates per item, so the loop context and index are in
-          // scope there. Visiting it with outer scopes only let a contract
-          // prop that shares a loop binding's name rewrite the key.
-          if (node.key) visitExpr(node.key, [...nextScopes, bound]);
-          walk(node.body, [...nextScopes, bound]);
-          if (node.fallback) walk(node.fallback, nextScopes);
-          break;
-        }
-        case 'IfBlock':
-          visitExpr(node.test, nextScopes);
-          walk(node.consequent, nextScopes);
-          if (node.alternate) walk(node.alternate, nextScopes);
-          break;
-        case 'KeyBlock':
-          visitExpr(node.expression, nextScopes);
-          walk(node.fragment, nextScopes);
-          break;
-        case 'SnippetBlock': {
-          const bound = new Set();
-          for (const param of node.parameters || []) collectPatternNames(param, bound);
-          walk(node.body, [...nextScopes, bound]);
-          break;
-        }
-        default: {
-          for (const attr of node?.attributes || []) {
-            if (attr.type === 'Attribute' && Array.isArray(attr.value)) {
-              for (const part of attr.value) {
-                if (part?.type === 'ExpressionTag') visitExpr(part.expression, nextScopes);
-              }
-            } else if (attr.expression) {
-              visitExpr(attr.expression, nextScopes);
-            }
-          }
-          if (node?.fragment) walk(node.fragment, nextScopes);
-        }
-      }
-    }
-  };
-  walk(ast.fragment, []);
-
-  return { ok: true, markup: applyReplacements(source, replacements) };
-}
-
-/**
- * Report [name, start, end] for every free root identifier READ in an
- * expression (skips member properties, object keys, shadowed names).
- */
-function collectFreeIdentifierRanges(node, scopes, emit) {
-  const visit = (n, localBound) => {
-    if (!n || typeof n !== 'object') return;
-    if (Array.isArray(n)) { for (const item of n) visit(item, localBound); return; }
-    switch (n.type) {
-      case 'Identifier': {
-        const bound = localBound.has(n.name) || scopes.some((s) => s.has(n.name));
-        if (!bound) emit(n.name, n.start, n.end);
-        return;
-      }
-      case 'MemberExpression':
-        visit(n.object, localBound);
-        if (n.computed) visit(n.property, localBound);
-        return;
-      case 'Property':
-        if (n.computed) visit(n.key, localBound);
-        visit(n.value, localBound);
-        return;
-      case 'ArrowFunctionExpression':
-      case 'FunctionExpression': {
-        const inner = new Set(localBound);
-        for (const param of n.params || []) collectPatternNames(param, inner);
-        visit(n.body, inner);
-        return;
-      }
-      default:
-        for (const key of Object.keys(n)) {
-          if (key === 'type' || key === 'start' || key === 'end' || key === 'loc' || key === 'range' || key === 'parent') continue;
-          visit(n[key], localBound);
-        }
-    }
-  };
-  visit(node, new Set());
-}
-
-/**
- * Build the preview component's script block from a v2 contract, with
- * defaults that keep an unhydrated mount rendering instead of crashing.
- */
-export function buildPropsScriptV2(contract) {
-  if (!contract || contract.length === 0) {
-    return '<script>\n  /** @type {Record<string, never>} */\n  let {} = $props();\n</script>\n';
-  }
-  const defaults = {
-    text: "''",
-    raw: "''",
-    condition: 'false',
-    collection: '[]',
-    handler: '() => {}',
-  };
-  const types = {
-    text: 'string',
-    raw: 'string',
-    condition: 'boolean',
-    collection: 'Array<Record<string, unknown>>',
-    handler: '() => void',
-  };
-  const names = contract
-    .map((c) => `${c.prop} = ${defaults[c.kind] ?? "''"}`)
-    .join(', ');
-  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`;
-}