@deneb-ui/cli 2.0.84 → 2.0.86

package/src/arc/transformer.cjs

@@ -27,16 +27,28 @@ const {
 } = require('./ast.cjs');
 const { toPosix } = require('./fs-utils.cjs');
 const { BROAD_CONTENT_CONTAINERS } = require('./fivora-contract.cjs');
-
-function findElementByLoc(ast, loc) {
-  if (!loc) return null;
-  const parts = loc.split(':');
+const {
+  hasMetadataExport,
+  hasClientDirective,
+  needsClientDirective,
+  canSafelyInjectClientDirective,
+  ensureClientDirective,
+} = require('./rsc-boundary.cjs');
+
+function findElementByLoc(ast, loc, tagName = null) {
+  if (!loc && !tagName) return null;
+  const parts = loc ? loc.split(':') : [];
   const targetLoc = parts.length > 4 ? parts.slice(0, 4).join(':') : loc;
   let found = null;
   recast.types.visit(ast, {
     visitJSXElement(pathNode) {
       const k = locKey(pathNode.node);
-      if (k === targetLoc || k === loc) {
+      const name = getJsxName(pathNode.node);
+      if (loc && (k === targetLoc || k === loc || (parts.length >= 2 && k && k.startsWith(`${parts[0]}:${parts[1]}`)))) {
+        found = pathNode;
+        return false;
+      }
+      if (!loc && tagName && (name === tagName || name.endsWith(`.${tagName}`))) {
         found = pathNode;
         return false;
       }
@@ -235,7 +247,18 @@ function applyTransformToElement(pathNode, transform) {
     ensurePreviewPath(node, transform.field);
     return;
   }
-  if (transform.operation === 'extract-image') {
+  if (transform.operation === 'extract-image' || transform.operation === 'extract-picture') {
+    const tagName = getJsxName(node);
+    if (tagName === 'picture') {
+      const children = node.children || [];
+      const imgChild = children.find((c) => c && c.type === 'JSXElement' && (getJsxName(c) === 'img' || getJsxName(c) === 'Image'));
+      if (imgChild) {
+        replaceAttrValue(imgChild, 'src', siteDataBinding(transform.field.split('.'), transform.fallback, 'image'));
+        ensurePreviewPath(imgChild, transform.field);
+      }
+      ensurePreviewPath(node, transform.field);
+      return;
+    }
     replaceAttrValue(node, 'src', siteDataBinding(transform.field.split('.'), transform.fallback, 'image'));
     ensurePreviewPath(node, transform.field);
     return;
@@ -257,6 +280,59 @@ function applyTransformToElement(pathNode, transform) {
     }
     return;
   }
+  if (transform.operation === 'bind-button-with-icon') {
+    ensurePreviewPath(node, transform.field);
+    ensureStyleAttrs(node, transform.field, 'button');
+    for (let i = 0; i < (node.children || []).length; i++) {
+      const child = node.children[i];
+      if (child.type === 'JSXText' && child.value.trim().length > 0) {
+        node.children[i] = b.jsxExpressionContainer(
+          siteDataBinding(transform.field.split('.'), child.value.trim(), 'text')
+        );
+      }
+    }
+    return;
+  }
+  if (transform.operation === 'bind-highlighted-heading') {
+    ensurePreviewPath(node, transform.field);
+    ensureStyleAttrs(node, transform.field, 'text');
+    for (let i = 0; i < (node.children || []).length; i++) {
+      const child = node.children[i];
+      if (child.type === 'JSXText' && child.value.trim().length > 0) {
+        node.children[i] = b.jsxExpressionContainer(
+          siteDataBinding(transform.field.split('.'), child.value.trim(), 'text')
+        );
+      } else if (child.type === 'JSXElement') {
+        const highlightField = `${transform.field}Highlight`;
+        ensurePreviewPath(child, highlightField);
+        for (let j = 0; j < (child.children || []).length; j++) {
+          if (child.children[j].type === 'JSXText' && child.children[j].value.trim().length > 0) {
+            child.children[j] = b.jsxExpressionContainer(
+              siteDataBinding(highlightField.split('.'), child.children[j].value.trim(), 'text')
+            );
+          }
+        }
+      }
+    }
+    return;
+  }
+  if (transform.operation === 'prop-flow-callsite') {
+    if (transform.propTransforms) {
+      for (const [propName, propInfo] of Object.entries(transform.propTransforms)) {
+        replaceAttrValue(
+          node,
+          propName,
+          siteDataBinding(propInfo.field.split('.'), propInfo.fallback, propInfo.type || 'text')
+        );
+      }
+    }
+    if (transform.previewPath && !hasJsxAttribute(node, 'previewPath')) {
+      node.openingElement.attributes.push(
+        b.jsxAttribute(b.jsxIdentifier('previewPath'), b.stringLiteral(transform.previewPath))
+      );
+    }
+    return;
+  }
   if (transform.operation === 'wrap-text-span') {
     wrapLiteralTextChildren(node, transform.field, transform.fallback);
     return;
@@ -283,6 +359,33 @@ function applyTransformToElement(pathNode, transform) {
       return;
     }
     ensureStyleAttrs(node, transform.stylePath, transform.styleKind || 'text');
+    return;
+  }
+  if (transform.operation === 'extract-tailwind-bg') {
+    const classAttr = findJsxAttribute(node, 'className') || findJsxAttribute(node, 'class');
+    if (classAttr && classAttr.value) {
+      if (classAttr.value.type === 'StringLiteral' || classAttr.value.type === 'Literal') {
+        const cleaned = String(classAttr.value.value).replace(/\bbg-\[url\([^)]+\)\]\s*/g, '').trim();
+        classAttr.value = b.stringLiteral(cleaned);
+      }
+    }
+    const urlParts = transform.field.split('.');
+    const styleExpr = b.objectExpression([
+      b.property(
+        'init',
+        b.identifier('backgroundImage'),
+        b.templateLiteral(
+          [
+            b.templateElement({ raw: 'url(', cooked: 'url(' }, false),
+            b.templateElement({ raw: ')', cooked: ')' }, true),
+          ],
+          [siteDataBinding(urlParts, transform.fallback || transform.bgUrl || '', 'image')]
+        )
+      ),
+    ]);
+    replaceAttrValue(node, 'style', styleExpr);
+    ensurePreviewPath(node, transform.field);
+    return;
   }
 }
 
@@ -392,6 +495,22 @@ function applyCollectionTransform(ast, transform, isClient = false, isTypeScript
   const itemRoot = findElementByLoc(ast, transform.loc);
   if (!itemRoot) return false;
 
+  const rootTagName = getJsxName(itemRoot.node);
+  const isCustomChild = /^[A-Z]/.test(rootTagName);
+
+  if (isCustomChild) {
+    if (!hasJsxAttribute(itemRoot.node, 'previewItemPath')) {
+      itemRoot.node.openingElement.attributes.push(
+        jsxTemplatePathAttr('previewItemPath', listPath, indexName)
+      );
+    }
+    if (!hasJsxAttribute(itemRoot.node, 'index')) {
+      itemRoot.node.openingElement.attributes.push(
+        b.jsxAttribute(b.jsxIdentifier('index'), b.jsxExpressionContainer(b.identifier(indexName)))
+      );
+    }
+  }
+
   if (!hasJsxAttribute(itemRoot.node, 'data-preview-item-path')) {
     itemRoot.node.openingElement.attributes.push(
       jsxTemplatePathAttr('data-preview-item-path', listPath, indexName)
@@ -416,7 +535,9 @@ function applyCollectionTransform(ast, transform, isClient = false, isTypeScript
   } else {
     markItemFields(callback, { listPath, binding, indexName });
   }
-  markComponentRefItemsStatic(callback, binding);
+  if (!isCustomChild) {
+    markComponentRefItemsStatic(callback, binding);
+  }
 
   const container = findListContainer(mapCall);
   if (container && !hasJsxAttribute(container, 'data-preview-list-path')) {
@@ -615,6 +736,469 @@ function wrapPrimitiveItemFieldInSpan(node, textChild, listPath, indexName) {
   node.children = nextChildren;
 }
 
+function instrumentChildCardComponent(ast, transform, isTypeScript = false) {
+  const componentName = transform.componentName;
+  const listPath = transform.listField || transform.listPath || '';
+  if (!componentName) return false;
+
+  let instrumented = false;
+
+  function updateTsInterface(rootAst, interfaceName) {
+    recast.types.visit(rootAst, {
+      visitTSInterfaceDeclaration(pathNode) {
+        if (pathNode.node.id?.name === interfaceName) {
+          const body = pathNode.node.body?.body || [];
+          if (!body.some((prop) => prop.key?.name === 'previewItemPath')) {
+            const sig1 = b.tsPropertySignature(b.identifier('previewItemPath'), b.tsTypeAnnotation(b.tsStringKeyword()));
+            sig1.optional = true;
+            body.push(sig1);
+            instrumented = true;
+          }
+          if (!body.some((prop) => prop.key?.name === 'index')) {
+            const sig2 = b.tsPropertySignature(b.identifier('index'), b.tsTypeAnnotation(b.tsNumberKeyword()));
+            sig2.optional = true;
+            body.push(sig2);
+            instrumented = true;
+          }
+        }
+        this.traverse(pathNode);
+      },
+      visitTSTypeAliasDeclaration(pathNode) {
+        if (pathNode.node.id?.name === interfaceName && pathNode.node.typeAnnotation?.type === 'TSTypeLiteral') {
+          const members = pathNode.node.typeAnnotation.members || [];
+          if (!members.some((m) => m.key?.name === 'previewItemPath')) {
+            const sig1 = b.tsPropertySignature(b.identifier('previewItemPath'), b.tsTypeAnnotation(b.tsStringKeyword()));
+            sig1.optional = true;
+            members.push(sig1);
+            instrumented = true;
+          }
+          if (!members.some((m) => m.key?.name === 'index')) {
+            const sig2 = b.tsPropertySignature(b.identifier('index'), b.tsTypeAnnotation(b.tsNumberKeyword()));
+            sig2.optional = true;
+            members.push(sig2);
+            instrumented = true;
+          }
+        }
+        this.traverse(pathNode);
+      },
+    });
+  }
+
+  function instrumentFunctionProps(fnNode, isTs) {
+    let changed = false;
+    let params = fnNode.params || [];
+    if (!params.length) {
+      fnNode.params = [
+        b.objectPattern([
+          b.property('init', b.identifier('previewItemPath'), b.identifier('previewItemPath')),
+          b.property('init', b.identifier('index'), b.identifier('index')),
+        ]),
+      ];
+      changed = true;
+    } else {
+      const firstParam = params[0];
+      if (firstParam.type === 'ObjectPattern') {
+        const hasPreviewPath = firstParam.properties.some(
+          (p) => p.key?.name === 'previewItemPath' || p.argument?.name === 'previewItemPath'
+        );
+        if (!hasPreviewPath) {
+          const prop = b.property('init', b.identifier('previewItemPath'), b.identifier('previewItemPath'));
+          prop.shorthand = true;
+          firstParam.properties.push(prop);
+          changed = true;
+        }
+        const hasIndex = firstParam.properties.some(
+          (p) => p.key?.name === 'index' || p.argument?.name === 'index'
+        );
+        if (!hasIndex) {
+          const prop = b.property('init', b.identifier('index'), b.identifier('index'));
+          prop.shorthand = true;
+          firstParam.properties.push(prop);
+          changed = true;
+        }
+
+        if (isTs && firstParam.typeAnnotation?.typeAnnotation) {
+          const typeAnn = firstParam.typeAnnotation.typeAnnotation;
+          if (typeAnn.type === 'TSTypeReference' && typeAnn.typeName?.name) {
+            updateTsInterface(ast, typeAnn.typeName.name);
+          }
+        }
+      } else if (firstParam.type === 'Identifier') {
+        const paramName = firstParam.name;
+        if (isTs && firstParam.typeAnnotation?.typeAnnotation) {
+          const typeAnn = firstParam.typeAnnotation.typeAnnotation;
+          if (typeAnn.type === 'TSTypeReference' && typeAnn.typeName?.name) {
+            updateTsInterface(ast, typeAnn.typeName.name);
+          }
+        }
+        recast.types.visit(fnNode.body || fnNode, {
+          visitVariableDeclarator(vPath) {
+            if (vPath.node.id?.type === 'ObjectPattern' && vPath.node.init?.name === paramName) {
+              const propsList = vPath.node.id.properties;
+              if (!propsList.some((p) => p.key?.name === 'previewItemPath')) {
+                const prop = b.property('init', b.identifier('previewItemPath'), b.identifier('previewItemPath'));
+                prop.shorthand = true;
+                propsList.push(prop);
+                changed = true;
+              }
+              if (!propsList.some((p) => p.key?.name === 'index')) {
+                const prop = b.property('init', b.identifier('index'), b.identifier('index'));
+                prop.shorthand = true;
+                propsList.push(prop);
+                changed = true;
+              }
+            }
+            this.traverse(vPath);
+          },
+        });
+      }
+    }
+    return changed;
+  }
+
+  recast.types.visit(ast, {
+    visitFunctionDeclaration(pathNode) {
+      if (pathNode.node.id?.name === componentName) {
+        if (instrumentFunctionProps(pathNode.node, isTypeScript)) instrumented = true;
+      }
+      this.traverse(pathNode);
+    },
+    visitVariableDeclarator(pathNode) {
+      if (pathNode.node.id?.name === componentName) {
+        const init = pathNode.node.init;
+        if (init && (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression')) {
+          if (instrumentFunctionProps(init, isTypeScript)) instrumented = true;
+        }
+      }
+      this.traverse(pathNode);
+    },
+    visitExportDefaultDeclaration(pathNode) {
+      const decl = pathNode.node.declaration;
+      if (decl && (decl.type === 'FunctionDeclaration' || decl.type === 'ArrowFunctionExpression' || decl.type === 'FunctionExpression')) {
+        const fnName = decl.id?.name;
+        if (!fnName || fnName === componentName) {
+          if (instrumentFunctionProps(decl, isTypeScript)) instrumented = true;
+        }
+      }
+      this.traverse(pathNode);
+    },
+  });
+
+  let rootElement = null;
+  recast.types.visit(ast, {
+    visitReturnStatement(pathNode) {
+      if (!rootElement && pathNode.node.argument) {
+        let arg = pathNode.node.argument;
+        if (arg.type === 'ParenthesizedExpression') arg = arg.expression;
+        if (arg.type === 'JSXElement') {
+          rootElement = arg;
+        }
+      }
+      this.traverse(pathNode);
+    },
+  });
+
+  if (rootElement) {
+    if (!hasJsxAttribute(rootElement, 'data-preview-item-path')) {
+      if (listPath) {
+        rootElement.openingElement.attributes.push(
+          jsxTemplatePathAttr('data-preview-item-path', listPath, 'index')
+        );
+      } else {
+        rootElement.openingElement.attributes.push(
+          b.jsxAttribute(
+            b.jsxIdentifier('data-preview-item-path'),
+            b.jsxExpressionContainer(b.identifier('previewItemPath'))
+          )
+        );
+      }
+      instrumented = true;
+    }
+  }
+
+  recast.types.visit(ast, {
+    visitJSXElement(pathNode) {
+      const node = pathNode.node;
+      const tagName = getJsxName(node);
+
+      const srcAttr = findJsxAttribute(node, 'src');
+      if (srcAttr && (tagName === 'img' || tagName === 'Image') && !hasJsxAttribute(node, 'data-preview-field-path')) {
+        const rawCode = recast.print(srcAttr.value).code;
+        if (/image|photo|avatar|thumb|img|src/i.test(rawCode)) {
+          const imgField = (transform.itemFields || []).find((f) => f.type === 'image' || /image|photo/i.test(f.key))?.key || 'image';
+          if (listPath) {
+            node.openingElement.attributes.push(
+              jsxTemplatePathAttr('data-preview-field-path', listPath, 'index', `.${imgField}`)
+            );
+          } else {
+            node.openingElement.attributes.push(
+              b.jsxAttribute(
+                b.jsxIdentifier('data-preview-field-path'),
+                b.jsxExpressionContainer(
+                  b.templateLiteral(
+                    [
+                      b.templateElement({ raw: '', cooked: '' }, false),
+                      b.templateElement({ raw: `.${imgField}`, cooked: `.${imgField}` }, true),
+                    ],
+                    [b.identifier('previewItemPath')]
+                  )
+                )
+              )
+            );
+          }
+          instrumented = true;
+        }
+      }
+
+      for (const child of node.children || []) {
+        if (child.type === 'JSXExpressionContainer') {
+          const exprCode = recast.print(child.expression).code;
+          if (!hasJsxAttribute(node, 'data-preview-field-path')) {
+            if (/name|title|heading/i.test(exprCode)) {
+              const nameField = (transform.itemFields || []).find((f) => /name|title|heading/i.test(f.key))?.key || 'name';
+              if (listPath) {
+                node.openingElement.attributes.push(
+                  jsxTemplatePathAttr('data-preview-field-path', listPath, 'index', `.${nameField}`)
+                );
+              } else {
+                node.openingElement.attributes.push(
+                  b.jsxAttribute(
+                    b.jsxIdentifier('data-preview-field-path'),
+                    b.jsxExpressionContainer(
+                      b.templateLiteral(
+                        [
+                          b.templateElement({ raw: '', cooked: '' }, false),
+                          b.templateElement({ raw: `.${nameField}`, cooked: `.${nameField}` }, true),
+                        ],
+                        [b.identifier('previewItemPath')]
+                      )
+                    )
+                  )
+                );
+              }
+              instrumented = true;
+              break;
+            } else if (/price|cost|amount/i.test(exprCode)) {
+              const priceField = (transform.itemFields || []).find((f) => /price|cost/i.test(f.key))?.key || 'price';
+              if (listPath) {
+                node.openingElement.attributes.push(
+                  jsxTemplatePathAttr('data-preview-field-path', listPath, 'index', `.${priceField}`)
+                );
+              } else {
+                node.openingElement.attributes.push(
+                  b.jsxAttribute(
+                    b.jsxIdentifier('data-preview-field-path'),
+                    b.jsxExpressionContainer(
+                      b.templateLiteral(
+                        [
+                          b.templateElement({ raw: '', cooked: '' }, false),
+                          b.templateElement({ raw: `.${priceField}`, cooked: `.${priceField}` }, true),
+                        ],
+                        [b.identifier('previewItemPath')]
+                      )
+                    )
+                  )
+                );
+              }
+              instrumented = true;
+              break;
+            } else if (/description|desc|subtitle/i.test(exprCode)) {
+              const descField = (transform.itemFields || []).find((f) => /desc/i.test(f.key))?.key || 'description';
+              if (listPath) {
+                node.openingElement.attributes.push(
+                  jsxTemplatePathAttr('data-preview-field-path', listPath, 'index', `.${descField}`)
+                );
+              } else {
+                node.openingElement.attributes.push(
+                  b.jsxAttribute(
+                    b.jsxIdentifier('data-preview-field-path'),
+                    b.jsxExpressionContainer(
+                      b.templateLiteral(
+                        [
+                          b.templateElement({ raw: '', cooked: '' }, false),
+                          b.templateElement({ raw: `.${descField}`, cooked: `.${descField}` }, true),
+                        ],
+                        [b.identifier('previewItemPath')]
+                      )
+                    )
+                  )
+                );
+              }
+              instrumented = true;
+              break;
+            }
+          }
+        }
+      }
+      this.traverse(pathNode);
+    },
+  });
+
+  return instrumented;
+}
+
+function instrumentReusableComponent(ast, transform, isTypeScript = false) {
+  const componentName = transform.componentName;
+  const propTransforms = transform.propTransforms || {};
+  const propNames = Object.keys(propTransforms);
+  if (!propNames.length) return false;
+
+  let instrumented = false;
+
+  function updateTsInterface(rootAst, interfaceName) {
+    recast.types.visit(rootAst, {
+      visitTSInterfaceDeclaration(pathNode) {
+        if (pathNode.node.id?.name === interfaceName) {
+          const body = pathNode.node.body?.body || [];
+          if (!body.some((m) => m.key?.name === 'previewPath')) {
+            const sig = b.tsPropertySignature(b.identifier('previewPath'), b.tsTypeAnnotation(b.tsStringKeyword()));
+            sig.optional = true;
+            body.push(sig);
+            instrumented = true;
+          }
+        }
+        this.traverse(pathNode);
+      },
+      visitTSTypeAliasDeclaration(pathNode) {
+        if (pathNode.node.id?.name === interfaceName && pathNode.node.typeAnnotation?.type === 'TSTypeLiteral') {
+          const members = pathNode.node.typeAnnotation.members || [];
+          if (!members.some((m) => m.key?.name === 'previewPath')) {
+            const sig = b.tsPropertySignature(b.identifier('previewPath'), b.tsTypeAnnotation(b.tsStringKeyword()));
+            sig.optional = true;
+            members.push(sig);
+            instrumented = true;
+          }
+        }
+        this.traverse(pathNode);
+      },
+    });
+  }
+
+  function instrumentFunctionProps(fnNode, isTs) {
+    let changed = false;
+    let params = fnNode.params || [];
+    if (!params.length) {
+      fnNode.params = [
+        b.objectPattern([
+          b.property('init', b.identifier('previewPath'), b.identifier('previewPath')),
+        ]),
+      ];
+      changed = true;
+    } else {
+      const firstParam = params[0];
+      if (firstParam.type === 'ObjectPattern') {
+        const hasPreviewPath = firstParam.properties.some(
+          (p) => p.key?.name === 'previewPath' || p.argument?.name === 'previewPath'
+        );
+        if (!hasPreviewPath) {
+          const prop = b.property('init', b.identifier('previewPath'), b.identifier('previewPath'));
+          prop.shorthand = true;
+          firstParam.properties.push(prop);
+          changed = true;
+        }
+        if (isTs && firstParam.typeAnnotation?.typeAnnotation) {
+          const typeAnn = firstParam.typeAnnotation.typeAnnotation;
+          if (typeAnn.type === 'TSTypeReference' && typeAnn.typeName?.name) {
+            updateTsInterface(ast, typeAnn.typeName.name);
+          }
+        }
+      } else if (firstParam.type === 'Identifier') {
+        const paramName = firstParam.name;
+        if (isTs && firstParam.typeAnnotation?.typeAnnotation) {
+          const typeAnn = firstParam.typeAnnotation.typeAnnotation;
+          if (typeAnn.type === 'TSTypeReference' && typeAnn.typeName?.name) {
+            updateTsInterface(ast, typeAnn.typeName.name);
+          }
+        }
+        recast.types.visit(fnNode.body || fnNode, {
+          visitVariableDeclarator(vPath) {
+            if (vPath.node.id?.type === 'ObjectPattern' && vPath.node.init?.name === paramName) {
+              const propsList = vPath.node.id.properties;
+              if (!propsList.some((p) => p.key?.name === 'previewPath')) {
+                const prop = b.property('init', b.identifier('previewPath'), b.identifier('previewPath'));
+                prop.shorthand = true;
+                propsList.push(prop);
+                changed = true;
+              }
+            }
+            this.traverse(vPath);
+          },
+        });
+      }
+    }
+    return changed;
+  }
+
+  recast.types.visit(ast, {
+    visitFunctionDeclaration(pathNode) {
+      if (!componentName || pathNode.node.id?.name === componentName) {
+        if (instrumentFunctionProps(pathNode.node, isTypeScript)) instrumented = true;
+      }
+      this.traverse(pathNode);
+    },
+    visitVariableDeclarator(pathNode) {
+      if (pathNode.node.id?.name === componentName) {
+        const init = pathNode.node.init;
+        if (init && (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression')) {
+          if (instrumentFunctionProps(init, isTypeScript)) instrumented = true;
+        }
+      }
+      this.traverse(pathNode);
+    },
+    visitExportDefaultDeclaration(pathNode) {
+      const decl = pathNode.node.declaration;
+      if (decl && (decl.type === 'FunctionDeclaration' || decl.type === 'ArrowFunctionExpression' || decl.type === 'FunctionExpression')) {
+        const fnName = decl.id?.name;
+        if (!fnName || fnName === componentName) {
+          if (instrumentFunctionProps(decl, isTypeScript)) instrumented = true;
+        }
+      }
+      this.traverse(pathNode);
+    },
+  });
+
+  recast.types.visit(ast, {
+    visitJSXElement(pathNode) {
+      const node = pathNode.node;
+      for (const child of node.children || []) {
+        if (child.type === 'JSXExpressionContainer') {
+          const expr = child.expression;
+          let propMatch = null;
+          if (expr && expr.type === 'Identifier' && propNames.includes(expr.name)) {
+            propMatch = expr.name;
+          } else if (expr && expr.type === 'LogicalExpression' && expr.left?.name && propNames.includes(expr.left.name)) {
+            propMatch = expr.left.name;
+          }
+          if (propMatch && !hasJsxAttribute(node, 'data-preview-field-path')) {
+            const previewAttr = b.jsxAttribute(
+              b.jsxIdentifier('data-preview-field-path'),
+              b.jsxExpressionContainer(
+                b.conditionalExpression(
+                  b.identifier('previewPath'),
+                  b.templateLiteral(
+                    [
+                      b.templateElement({ raw: '', cooked: '' }, false),
+                      b.templateElement({ raw: `.${propMatch}`, cooked: `.${propMatch}` }, true),
+                    ],
+                    [b.identifier('previewPath')]
+                  ),
+                  b.identifier('undefined')
+                )
+              )
+            );
+            node.openingElement.attributes.push(previewAttr);
+            instrumented = true;
+            break;
+          }
+        }
+      }
+      this.traverse(pathNode);
+    },
+  });
+
+  return instrumented;
+}
+
 /** The nearest JSX element that wraps the map expression. */
 function findListContainer(mapCallPath) {
   let current = mapCallPath.parent;
@@ -973,7 +1557,8 @@ function applyFilePlan(filePlan, profile) {
   }
 
   const ast = parseSource(filePlan.originalCode, filePlan.file);
-  const isClient = hasDirective(ast, 'use client') || /['"]use client['"]/.test(filePlan.originalCode.slice(0, 400));
+  let isClient = hasDirective(ast, 'use client') || hasClientDirective(ast) || /['"]use client['"]/.test(filePlan.originalCode.slice(0, 400));
+  const hasMetadata = hasMetadataExport(ast);
   let applied = 0;
   const failures = [];
 
@@ -982,6 +1567,7 @@ function applyFilePlan(filePlan, profile) {
     'form-submit-action',
     'extract-url',
     'extract-image',
+    'extract-picture',
     'extract-alt',
     'extract-placeholder',
     'extract-text',
@@ -989,6 +1575,12 @@ function applyFilePlan(filePlan, profile) {
     'wrap-text-span',
     'collection-conversion',
     'style-bind',
+    'extract-tailwind-bg',
+    'instrument-child-card',
+    'bind-button-with-icon',
+    'bind-highlighted-heading',
+    'prop-flow-callsite',
+    'instrument-reusable-component',
   ]);
 
   const isTypeScript = Boolean(filePlan.file && /\.(tsx|ts)$/.test(filePlan.file));
@@ -1005,6 +1597,24 @@ function applyFilePlan(filePlan, profile) {
     if (transform.decision === 'skip') continue;
     if (!supported.has(transform.operation)) continue;
 
+    if (transform.operation === 'instrument-child-card') {
+      try {
+        if (instrumentChildCardComponent(ast, transform, isTypeScript)) applied++;
+      } catch (err) {
+        failures.push({ loc: transform.loc, reason: err.message });
+      }
+      continue;
+    }
+
+    if (transform.operation === 'instrument-reusable-component') {
+      try {
+        if (instrumentReusableComponent(ast, transform, isTypeScript)) applied++;
+      } catch (err) {
+        failures.push({ loc: transform.loc, reason: err.message });
+      }
+      continue;
+    }
+
     if (transform.operation === 'collection-conversion') {
       try {
         if (applyCollectionTransform(ast, transform, isClient, isTypeScript)) applied++;
@@ -1015,7 +1625,7 @@ function applyFilePlan(filePlan, profile) {
       continue;
     }
 
-    const pathNode = findElementByLoc(ast, transform.loc);
+    const pathNode = findElementByLoc(ast, transform.loc, transform.componentName || transform.tag);
     if (!pathNode) {
       failures.push({ loc: transform.loc, reason: 'node-not-found' });
       continue;
@@ -1032,6 +1642,13 @@ function applyFilePlan(filePlan, profile) {
     return { code: filePlan.originalCode, changed: false, applied, failures };
   }
 
+  if (!isClient && profile?.router === 'next-app' && !hasMetadata && canSafelyInjectClientDirective(ast, filePlan.file, profile)) {
+    if (needsClientDirective(ast, filePlan.originalCode)) {
+      ensureClientDirective(ast);
+      isClient = true;
+    }
+  }
+
   const siteDataImport = resolveSiteDataSpecifier(profile, filePlan.file);
   if (isClient) {
     const runtimeSpecifier = resolveSiteDataRuntimeSpecifier(profile);
@@ -1624,6 +2241,108 @@ function findFirstLeafChild(node) {
   return null;
 }
 
+function isUnsafeToStripCondition(leftExpr, rightExpr, pathNode) {
+  if (!leftExpr || !rightExpr) return true;
+
+  // 1. Collect all identifiers used on the left-hand side
+  const leftIdentifiers = new Set();
+  recast.types.visit(leftExpr, {
+    visitIdentifier(idPath) {
+      leftIdentifiers.add(idPath.node.name);
+      return false;
+    },
+  });
+
+  if (leftIdentifiers.size === 0) return true;
+
+  // 2. State & modal variable keywords (e.g., selectedDish, lightboxIndex, isOpen, activeTab)
+  const stateKeywordRegex = /(?:open|active|selected|current|expanded|visible|show|modal|dialog|lightbox|drawer|loading|tab|filter|step|index)/i;
+  for (const id of leftIdentifiers) {
+    if (stateKeywordRegex.test(id)) {
+      return true; // NEVER strip modal/state/selection guards
+    }
+  }
+
+  // 3. Null / undefined / equality / comparison checks
+  let hasComparisonOrNullCheck = false;
+  recast.types.visit(leftExpr, {
+    visitBinaryExpression(bPath) {
+      const op = bPath.node.operator;
+      if (['!==', '!=', '===', '==', '>', '<', '>=', '<='].includes(op)) {
+        hasComparisonOrNullCheck = true;
+      }
+      this.traverse(bPath);
+    },
+    visitUnaryExpression(uPath) {
+      if (uPath.node.operator === '!') {
+        hasComparisonOrNullCheck = true;
+      }
+      this.traverse(uPath);
+    },
+  });
+  if (hasComparisonOrNullCheck) return true;
+
+  // 4. Check if ANY identifier in leftExpr is referenced inside rightExpr
+  let rightReferencesLeftId = false;
+  recast.types.visit(rightExpr, {
+    visitIdentifier(idPath) {
+      if (leftIdentifiers.has(idPath.node.name)) {
+        rightReferencesLeftId = true;
+        return false;
+      }
+      this.traverse(idPath);
+    },
+  });
+  if (rightReferencesLeftId) return true;
+
+  // 5. Check if rightExpr or any of its ancestors is an interactive modal / dialog / overlay / AnimatePresence
+  let curr = pathNode;
+  while (curr && curr.parent) {
+    const parentNode = curr.parent.node;
+    if (parentNode && parentNode.type === 'JSXElement') {
+      const parentTag = getJsxName(parentNode);
+      if (/^(?:AnimatePresence|Dialog|Modal|Lightbox|Drawer|Popup|Sheet|Portal)$/i.test(parentTag)) {
+        return true;
+      }
+    }
+    curr = curr.parent;
+  }
+
+  let isModalOrOverlay = false;
+  recast.types.visit(rightExpr, {
+    visitJSXElement(elPath) {
+      const node = elPath.node;
+      const tag = getJsxName(node);
+      if (/^(?:AnimatePresence|Dialog|Modal|Lightbox|Drawer|Popup|Sheet|Portal)$/i.test(tag)) {
+        isModalOrOverlay = true;
+        return false;
+      }
+      const classAttr = findJsxAttribute(node, 'className') || findJsxAttribute(node, 'class');
+      if (classAttr && classAttr.value) {
+        const val = classAttr.value.value || '';
+        if (typeof val === 'string' && (/fixed\s+inset-0/i.test(val) || /z-(?:50|\[50\]|40)/i.test(val) || /backdrop-blur/i.test(val))) {
+          isModalOrOverlay = true;
+          return false;
+        }
+      }
+      const roleAttr = findJsxAttribute(node, 'role');
+      if (roleAttr && roleAttr.value && /^(?:dialog|alertdialog)$/i.test(String(roleAttr.value.value || ''))) {
+        isModalOrOverlay = true;
+        return false;
+      }
+      this.traverse(elPath);
+    },
+  });
+  if (isModalOrOverlay) return true;
+
+  // 6. Only allow stripping if leftExpr is purely a direct siteData content member chain
+  const leftCode = recast.print(leftExpr).code;
+  const isDirectContentCheck = /siteData(?:\?\.|\.)content(?:\?\.|\.)/i.test(leftCode);
+  if (!isDirectContentCheck) return true;
+
+  return false;
+}
+
 function healEmptyStateConditionals(ast) {
   let healed = 0;
 
@@ -1650,9 +2369,11 @@ function healEmptyStateConditionals(ast) {
     visitLogicalExpression(pathNode) {
       const expr = pathNode.node;
       if (expr.operator === '&&' && jsxHasPreviewMarker(expr.right)) {
-        pathNode.replace(expr.right);
-        healed++;
-        return false;
+        if (!isUnsafeToStripCondition(expr.left, expr.right, pathNode)) {
+          pathNode.replace(expr.right);
+          healed++;
+          return false;
+        }
       }
       this.traverse(pathNode);
     },
@@ -1663,20 +2384,24 @@ function healEmptyStateConditionals(ast) {
         return;
       }
       if (expr.type === 'LogicalExpression' && expr.operator === '&&' && jsxHasPreviewMarker(expr.right)) {
-        pathNode.node.expression = expr.right;
-        healed++;
-        return false;
+        if (!isUnsafeToStripCondition(expr.left, expr.right, pathNode)) {
+          pathNode.node.expression = expr.right;
+          healed++;
+          return false;
+        }
       }
       if (
         expr.type === 'ConditionalExpression' &&
         jsxHasPreviewMarker(expr.consequent) &&
         (isNullish(expr.alternate) || isNullish(expr.consequent))
       ) {
-        pathNode.node.expression = jsxHasPreviewMarker(expr.consequent) && !isNullish(expr.consequent)
-          ? expr.consequent
-          : expr.alternate;
-        healed++;
-        return false;
+        if (!isUnsafeToStripCondition(expr.test, expr.consequent, pathNode)) {
+          pathNode.node.expression = jsxHasPreviewMarker(expr.consequent) && !isNullish(expr.consequent)
+            ? expr.consequent
+            : expr.alternate;
+          healed++;
+          return false;
+        }
       }
       this.traverse(pathNode);
     },
@@ -1928,6 +2653,77 @@ function healMissingSiteDataHooks(code, filePath = 'file.tsx') {
   return code;
 }
 
+function healUnguardedModalConditionals(ast) {
+  let healed = 0;
+  const stateVariables = [];
+  recast.types.visit(ast, {
+    visitVariableDeclarator(pathNode) {
+      const node = pathNode.node;
+      if (node.id && node.id.type === 'ArrayPattern') {
+        const first = node.id.elements[0];
+        if (first && first.type === 'Identifier') {
+          stateVariables.push(first.name);
+        }
+      }
+      this.traverse(pathNode);
+    },
+  });
+
+  if (stateVariables.length === 0) return 0;
+
+  recast.types.visit(ast, {
+    visitJSXElement(pathNode) {
+      const tag = getJsxName(pathNode.node);
+      if (tag === 'AnimatePresence') {
+        for (const child of pathNode.node.children || []) {
+          if (child.type === 'JSXExpressionContainer') {
+            let inner = child.expression;
+            if (inner && inner.type === 'ParenthesizedExpression') {
+              inner = inner.expression;
+            }
+            if (inner && (inner.type === 'JSXElement' || inner.type === 'JSXFragment')) {
+              const innerIds = new Set();
+              recast.types.visit(inner, {
+                visitIdentifier(idPath) {
+                  innerIds.add(idPath.node.name);
+                  return false;
+                },
+              });
+
+              const matchingVar = stateVariables.find((sv) => innerIds.has(sv));
+              if (matchingVar) {
+                let guardExpr;
+                if (/index/i.test(matchingVar)) {
+                  guardExpr = b.binaryExpression('!==', b.identifier(matchingVar), b.nullLiteral());
+                } else {
+                  guardExpr = b.identifier(matchingVar);
+                }
+                child.expression = b.logicalExpression('&&', guardExpr, inner);
+                healed++;
+              }
+            }
+          }
+        }
+      }
+      this.traverse(pathNode);
+    },
+  });
+
+  return healed;
+}
+
+function healUnguardedModalConditionalsInSource(code, filePath = 'file.tsx') {
+  if (!code.includes('AnimatePresence') && !code.includes('fixed inset-0')) return { code, updated: false };
+  try {
+    const ast = parseSource(code, filePath);
+    const healed = healUnguardedModalConditionals(ast);
+    if (healed > 0) {
+      return { code: printSource(ast, code), updated: true, count: healed };
+    }
+  } catch {}
+  return { code, updated: false };
+}
+
 module.exports = {
   applyFilePlan,
   applyCollectionTransform,
@@ -1947,6 +2743,9 @@ module.exports = {
   healDecorativeOverlays,
   healLegacyProductDetailLinks,
   healMissingSiteDataHooks,
+  healUnguardedModalConditionals,
+  healUnguardedModalConditionalsInSource,
   injectSiteDataHook,
+  instrumentChildCardComponent,
 };