/**
|
* 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`;
|
}
|
