` outer wrapper so the picked
+ * element's JSX slot keeps a single child — a Fragment `<>` would have
+ * solved the multi-sibling case but failed inside `asChild` / cloneElement
+ * parents with "Invalid prop supplied to React.Fragment".
+ *
+ * That means the marker block is enclosed by the wrapper `
` opener
+ * (with `data-impeccable-variants="ID"`) and its matching `
`. We
+ * walk back to the opener and forward to the closer so accept/discard
+ * remove the entire scaffold, not just the inner markers.
+ *
+ * Marker lines themselves stay where they were so extractOriginal /
+ * extractVariant / extractCss continue to walk the same range.
+ */
+function expandReplaceRange(block, lines, isJsx) {
+ if (!isJsx) return { start: block.start, end: block.end };
+
+ let { start, end } = block;
+
+ // Walk back for the wrapper `
= 0; i--) {
+ if (isVariantEndMarkerLine(lines[i], block.id)) break;
+ if (hasVariantWrapperAttr(lines[i], block.id)) {
+ let opener = i;
+ while (opener > 0 && !/
` by div-depth tracking from the
+ // wrapper opener. Operate on JOINED text instead of per-line: a
+ // multi-line self-closing JSX `` would
+ // fool per-line regex tracking (the `` line never matches selfCloseRe since it needs `` orphaned after accept/discard. Single regex with
+ // `[^>]*?` (which spans newlines in JS) handles either form correctly.
+ const joined = lines.slice(start).join('\n');
+ // Match either `` (self-close, group 1 is `/`), ``
+ // (open, group 1 is empty), or `
`.
+ const tagRe = /]*?(\/?)>|<\/div\s*>/g;
+ let depth = 0;
+ let m;
+ while ((m = tagRe.exec(joined)) !== null) {
+ const isClose = m[0].startsWith('= end) {
+ end = candidateEnd;
+ break;
+ }
+ }
+ }
+
+ return { start, end };
+}
+
+function escapeRegExp(value) {
+ return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function isVariantEndMarkerLine(line, id) {
+ return new RegExp('impeccable-variants-end\\s+' + escapeRegExp(id) + '(?:\\s|--|\\*/|$)').test(line);
+}
+
+function hasVariantWrapperAttr(line, id) {
+ const escaped = escapeRegExp(id);
+ return new RegExp(`data-impeccable-variants\\s*=\\s*(?:"${escaped}"|'${escaped}'|\\{["']${escaped}["']\\})`).test(line);
+}
+
+/**
+ * Join wrapper lines into a single string with `` to close on)
+ * - Same-line `` blocks
+ * - Multi-line `` blocks
+ */
+function stripStyleAndJoin(lines, block) {
+ const out = [];
+ let inStyle = false;
+ for (let i = block.start; i <= block.end; i++) {
+ let line = lines[i];
+
+ if (!inStyle) {
+ // Strip any complete .
+ const closeIdx = line.search(/<\/style\s*>/);
+ if (closeIdx !== -1) {
+ inStyle = false;
+ out.push(line.slice(closeIdx).replace(/<\/style\s*>/, ''));
+ }
+ // else: skip line entirely
+ }
+ }
+ return out.join('\n');
+}
+
+/**
+ * Find the inner content of `…` inside `text`,
+ * handling nested same-tag elements via depth counting. `attrMatch` is a
+ * regex source fragment that must appear inside the opener tag.
+ * Returns the inner string (may be empty), or null if not found.
+ */
+function extractInnerByAttr(text, attrMatch) {
+ const openerRe = new RegExp('<([A-Za-z][A-Za-z0-9]*)\\b[^>]*' + attrMatch + '[^>]*>');
+ const openMatch = text.match(openerRe);
+ if (!openMatch) return null;
+
+ const tagName = openMatch[1];
+ const innerStart = openMatch.index + openMatch[0].length;
+
+ // Match any opener or closer of this tag name after innerStart.
+ // (Does not match self-closing , which doesn't contribute to depth.)
+ const tagRe = new RegExp('<(?:/)?' + tagName + '\\b[^>]*>', 'g');
+ tagRe.lastIndex = innerStart;
+
+ let depth = 1;
+ let m;
+ while ((m = tagRe.exec(text))) {
+ const isClose = m[0].startsWith('$/.test(m[0]);
+ if (isClose) {
+ depth--;
+ if (depth === 0) return text.slice(innerStart, m.index);
+ } else if (!isSelfClose) {
+ depth++;
+ }
+ }
+ return null;
+}
+
+/**
+ * Extract the original element content from within the variant wrapper.
+ * Returns an array of lines.
+ */
+function extractOriginal(lines, block) {
+ const text = stripStyleAndJoin(lines, block);
+ const inner = extractInnerByAttr(text, 'data-impeccable-variant="original"');
+ if (inner === null) return [];
+ return inner.split('\n');
+}
+
+/**
+ * Extract a specific variant's inner content (stripping the wrapper div).
+ * Returns an array of lines, or null if not found.
+ */
+function extractVariant(lines, block, variantNum) {
+ const text = stripStyleAndJoin(lines, block);
+ const inner = extractInnerByAttr(text, 'data-impeccable-variant="' + variantNum + '"');
+ if (inner === null) return null;
+ const result = inner.split('\n');
+ // Collapse a lone empty leading/trailing line (common after string splice).
+ while (result.length > 1 && result[0].trim() === '') result.shift();
+ while (result.length > 1 && result[result.length - 1].trim() === '') result.pop();
+ return result.length > 0 ? result : null;
+}
+
+/**
+ * Extract the colocated ` — return the inner content.
+ * 3. Multi-line: `` on a later line — return
+ * the lines between them.
+ */
+function extractCss(lines, block, id) {
+ const styleAttr = 'data-impeccable-css="' + id + '"';
+ let inStyle = false;
+ const content = [];
+
+ for (let i = block.start; i <= block.end; i++) {
+ const line = lines[i];
+
+ if (!inStyle && line.includes(styleAttr)) {
+ // Self-closing: nothing to carbonize.
+ if (/]*\/\s*>/.test(line)) return null;
+ // Same-line open + close: extract inner text.
+ const sameLine = line.match(/]*>([\s\S]*?)<\/style\s*>/);
+ if (sameLine) {
+ const inner = stripJsxTemplateWrap(sameLine[1]);
+ return inner.length > 0 ? inner.split('\n') : null;
+ }
+ inStyle = true;
+ continue; // skip the anywhere on the line — JSX template-literal closes
+ // (`}`) put the close mid-line, and we don't want to absorb the
+ // template-literal punctuation as CSS content.
+ const closeIdx = line.indexOf('');
+ if (closeIdx !== -1) break;
+ content.push(line);
+ }
+ }
+
+ if (content.length === 0) return null;
+ return stripJsxTemplateLines(content);
+}
+
+/**
+ * Strip a JSX template-literal wrap (`{` … `}`) from CSS extracted out of a
+ * `',
+ )
+ .replace(/\bclassName\s*=\s*\{\s*`([^`]*?)`\s*\}/g, (_match, value) => {
+ const literalClasses = value.replace(/\$\{[^}]*\}/g, ' ').replace(/\s+/g, ' ').trim();
+ return literalClasses ? 'class="' + escapeHtml(literalClasses) + '"' : '';
+ })
+ .replace(/\bclassName\s*=/g, 'class=')
+ .replace(/\sstyle=\{\{([\s\S]*?)\}\}/g, (_match, body) => {
+ const css = jsxStyleObjectToCss(body);
+ return css ? ' style="' + escapeHtml(css) + '"' : '';
+ });
+ }
+
+ function jsxStyleObjectToCss(body) {
+ const declarations = [];
+ const re = /(["'][^"']+["']|[A-Za-z_$][\w$-]*)\s*:\s*(?:"([^"]*)"|'([^']*)'|(-?\d+(?:\.\d+)?))/g;
+ let match;
+ while ((match = re.exec(String(body || '')))) {
+ const prop = jsxStylePropToCss(match[1]);
+ const value = match[2] ?? match[3] ?? match[4] ?? '';
+ if (!prop || value === '') continue;
+ declarations.push(prop + ': ' + value);
+ }
+ return declarations.join('; ');
+ }
+
+ function jsxStylePropToCss(prop) {
+ let out = String(prop || '').trim().replace(/^["']|["']$/g, '');
+ if (!out) return '';
+ if (out.startsWith('--')) return out;
+ return out.replace(/[A-Z]/g, (ch) => '-' + ch.toLowerCase()).replace(/^-ms-/, '-ms-');
+ }
+
+ function buildSvelteExpressionTextMap(sourceOriginal, liveOriginal) {
+ const map = new Map();
+ if (!sourceOriginal || !liveOriginal) return map;
+
+ const sourceNodes = collectTextNodes(sourceOriginal)
+ .filter((node) => /\{[^{}]+\}/.test(node.nodeValue || ''));
+ const liveTexts = collectTextNodes(liveOriginal)
+ .map((node) => normalizePreviewText(node.nodeValue || ''))
+ .filter(Boolean);
+ let liveIndex = 0;
+
+ for (const sourceNode of sourceNodes) {
+ const sourceText = sourceNode.nodeValue || '';
+ const tokens = sourceText.match(/\{[^{}]+\}/g) || [];
+ if (tokens.length === 0) continue;
+
+ const liveText = liveTexts[liveIndex++] || '';
+ if (!liveText) continue;
+
+ if (tokens.length === 1) {
+ const token = tokens[0];
+ const normalizedSource = normalizePreviewText(sourceText);
+ if (normalizedSource === token) {
+ map.set(token, liveText);
+ continue;
+ }
+
+ const match = liveText.match(expressionTextMatcher(sourceText, [token]));
+ if (match && match[1]) map.set(token, match[1].trim());
+ continue;
+ }
+
+ if (normalizePreviewText(sourceText) === tokens.join(' ')) {
+ for (const token of tokens) {
+ const tokenLiveText = liveTexts[liveIndex - 1] || '';
+ if (tokenLiveText) map.set(token, tokenLiveText);
+ }
+ }
+ }
+
+ return map;
+ }
+
+ function expressionTextMatcher(sourceText, tokens) {
+ let pattern = '^';
+ let cursor = 0;
+ for (const token of tokens) {
+ const index = sourceText.indexOf(token, cursor);
+ if (index === -1) continue;
+ pattern += escapeRegExp(sourceText.slice(cursor, index)).replace(/\s+/g, '\\s*');
+ pattern += '(.*?)';
+ cursor = index + token.length;
+ }
+ pattern += escapeRegExp(sourceText.slice(cursor)).replace(/\s+/g, '\\s*') + '$';
+ return new RegExp(pattern);
+ }
+
+ function collectTextNodes(root) {
+ if (!root) return [];
+ const nodes = [];
+ const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+ let node = walker.nextNode();
+ while (node) {
+ nodes.push(node);
+ node = walker.nextNode();
+ }
+ return nodes;
+ }
+
+ function normalizePreviewText(value) {
+ return String(value || '').replace(/\s+/g, ' ').trim();
+ }
+
+ function escapeRegExp(value) {
+ return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+ }
+
+ async function selectVariant(next, checkpointReason) {
+ if (pendingApplyInFlight) { showManualApplyBusyToast(); return; }
+ if (variantSelectionInFlight) return;
+ if (next < 1 || next > arrivedVariants) return;
+ if (next === visibleVariant) return;
+
+ const previous = visibleVariant;
+ variantSelectionInFlight = true;
+ const selectionPromise = (async () => {
+ visibleVariant = next;
+ showOrUpdateCyclingBar();
+ saveSession();
+ const shown = await showVariantInDOM(currentSessionId, next); // calls refreshParamsPanel itself
+ if (!shown) {
+ visibleVariant = previous;
+ await showVariantInDOM(currentSessionId, previous);
+ showOrUpdateCyclingBar();
+ saveSession();
+ return;
+ }
+ updateSelectedElement();
+ showOrUpdateCyclingBar();
+ positionBar();
+ saveSession();
+ if (checkpointReason) queueCheckpoint(checkpointReason);
+ })();
+ variantSelectionPromise = selectionPromise;
+ try {
+ await selectionPromise;
+ } finally {
+ if (variantSelectionPromise === selectionPromise) variantSelectionPromise = null;
+ variantSelectionInFlight = false;
+ }
+ }
+
+ function cycleVariant(dir) {
+ selectVariant(visibleVariant + dir, 'variant_changed');
+ }
+
+ function updateSelectedElement() {
+ if (!currentSessionId) return;
+ if (svelteComponentSession?.sessionId === currentSessionId) {
+ const anchor = resolveSvelteComponentAnchor();
+ if (anchor && !anchor.__impeccableFrozenAnchor) selectedElement = anchor;
+ return;
+ }
+ const wrapper = document.querySelector('[data-impeccable-variants="' + currentSessionId + '"]');
+ if (!wrapper) return;
+ const visEl = pickVariantContent(wrapper, visibleVariant);
+ if (visEl) selectedElement = visEl;
+ }
+
+ function readVisibleVariantFromDOM(sessionId) {
+ if (svelteComponentSession?.sessionId === sessionId && svelteComponentSession.mountedVariant > 0) {
+ return svelteComponentSession.mountedVariant;
+ }
+ const wrapper = document.querySelector('[data-impeccable-variants="' + sessionId + '"]');
+ if (!wrapper) return 0;
+ const variants = wrapper.querySelectorAll('[data-impeccable-variant]:not([data-impeccable-variant="original"])');
+ for (const variant of variants) {
+ if (!isVariantShown(variant)) continue;
+ const idx = parseInt(variant.dataset.impeccableVariant || '0', 10);
+ if (idx > 0) return idx;
+ }
+ return 0;
+ }
+
+ // Resolve the element that represents the variant's visible content.
+ // Contract: each variant div should contain exactly one top-level element
+ // (the full replacement). In practice a model may ship loose siblings or
+ // lead with close.',
+ 'Prefix every preview selector with the matching [data-impeccable-variant="N"] selector.',
+ 'Keep selectors anchored to the generated variant wrapper; do not rely on component CSS scoping for preview rules.',
+ ],
+ forbidden: [
+ 'Do not use @scope for this styleMode.',
+ 'Do not wrap style content in a JSX/TSX template literal ({` ... `}); that syntax is for .tsx/.jsx only.',
+ 'Do not put { immediately after the style opening tag; Astro parses { as expression syntax.',
+ ],
+ };
+ }
+ return {
+ mode: styleMode.mode,
+ styleTag: styleMode.styleTag,
+ strategy: 'scope-rule',
+ rulePattern: '@scope ([data-impeccable-variant="N"]) { :scope > .variant-class { ... } }',
+ selectorExamples: variantNumbers.map((n) => `@scope ([data-impeccable-variant="${n}"]) { :scope > .variant-class { ... } }`),
+ requirements: [
+ 'Use @scope blocks keyed to each [data-impeccable-variant="N"] wrapper.',
+ 'Inside each @scope block, make :scope rules step into the replacement element with a descendant combinator.',
+ 'Use the styleTag exactly; do not add framework-specific style attributes unless this object says to.',
+ ],
+ forbidden: [
+ 'Do not use global [data-impeccable-variant="N"] selector prefixes for this styleMode.',
+ 'Do not add is:inline to the style tag for this styleMode.',
+ ],
+ };
+}
+
+/**
+ * Search project files for the query string (class name, ID, etc.)
+ * Returns the first matching file path, or null.
+ *
+ * Only `node_modules`, `.git`, and `.impeccable` are skipped outright.
+ * dist/build/out are left to the isGeneratedFile guard so the
+ * `includeGenerated` second pass can still find the element there and report
+ * `generatedMatch`.
+ */
+function findFileWithQuery(query, cwd, genOpts = {}) {
+ return findSourceFile({
+ query,
+ cwd,
+ extensions: resolveLiveTemplateExtensions(cwd),
+ fileFilter: (filePath) => genOpts.includeGenerated || !isGeneratedFile(filePath, genOpts),
+ });
+}
+
+/**
+ * Regex that matches a tag opener on a line. Allows the tag name to be
+ * followed by whitespace, `>`, `/`, or end-of-line so that multi-line JSX
+ * openers (e.g. ``) are recognised.
+ */
+const OPENER_RE = /<([A-Za-z][A-Za-z0-9]*)(?=[\s/>]|$)/;
+
+/**
+ * Find the element's start and end line in the file.
+ *
+ * `query` is a class name, attribute fragment (`class="..."`, `className="..."`,
+ * `id="..."`), or a raw text snippet. Because a query can appear on a
+ * continuation line of a multi-line tag (e.g. the `className="..."` row of a
+ * `` JSX tag), we walk backward from the match
+ * line to find the actual tag opener. When `tag` is provided, opener candidates
+ * must match that tag name.
+ */
+/**
+ * Return the smallest leading-whitespace count across a set of lines,
+ * ignoring blank lines (whose indent isn't load-bearing). Used to compute
+ * the common base indent of a multi-line picked element so reindenting
+ * under the wrapper preserves the relative depth between lines.
+ */
+function minLeadingSpaces(lines) {
+ let min = Infinity;
+ for (const l of lines) {
+ if (l.trim() === '') continue;
+ const m = l.match(/^(\s*)/);
+ if (m && m[1].length < min) min = m[1].length;
+ }
+ return min === Infinity ? 0 : min;
+}
+
+function findElement(lines, query, tag = null) {
+ // Iterate all matches — the first substring hit isn't always the right one.
+ for (let i = 0; i < lines.length; i++) {
+ if (!lines[i].includes(query)) continue;
+
+ const stripped = lines[i].trim();
+ if (stripped.startsWith(''; }
+
+/**
+ * `scriptAttrs` is a pre-rendered attribute string (trailing space included)
+ * that the registry supplies for the target file. Astro is the only framework
+ * that uses it today: Astro processes `\n' +
+ open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
+ );
+}
+
+function detectLineEnding(content) {
+ if (content.includes('\r\n')) return '\r\n';
+ if (content.includes('\r')) return '\r';
+ return '\n';
+}
+
+function normalizeLineEndings(content, lineEnding) {
+ return lineEnding === '\n' ? content : content.replace(/\n/g, lineEnding);
+}
+
+function readLineEndingAt(content, index) {
+ if (content[index] === '\r' && content[index + 1] === '\n') return '\r\n';
+ if (content[index] === '\n') return '\n';
+ if (content[index] === '\r') return '\r';
+ return '';
+}
+
+export function insertTag(content, config, port, token, scriptAttrs = '') {
+ const lineEnding = detectLineEnding(content);
+ const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, token, scriptAttrs), lineEnding);
+ // insertBefore: match the LAST occurrence. Anchors like `
+```
+
+**How it works**:
+- `srcset` lists available images with their actual widths (`w` descriptors)
+- `sizes` tells the browser how wide the image will display
+- Browser picks the best file based on viewport width AND device pixel ratio
+
+##### Picture Element for Art Direction
+
+When you need different crops/compositions (not just resolutions):
+
+```html
+
+