@deneb-ui/cli 2.0.71 → 2.0.73

package/src/arc/semantic.cjs

@@ -1,5 +1,5 @@
-'use strict';
-
+const fs = require('fs');
+const path = require('path');
 const recast = require('recast');
 const {
   parseSource,
@@ -9,6 +9,7 @@ const {
   hasJsxAttribute,
   collectJsxText,
   findJsxAttribute,
+  unwrapExpr,
 } = require('./ast.cjs');
 const {
   activeAdapters,
@@ -28,11 +29,46 @@ const {
   DECORATIVE_TAGS,
 } = require('./adapters.cjs');
 const { shortHash } = require('./fs-utils.cjs');
+const { resolveImportSpecifier } = require('./scanner.cjs');
 const { BROAD_CONTENT_CONTAINERS } = require('./fivora-contract.cjs');
 
 const TECHNICAL_TEXT_RE = /^(true|false|null|undefined|px|rem|em|auto|hidden|flex|grid|sr-only)$/i;
 const ARIA_ONLY_RE = /^(aria-|data-state|data-slot|data-orientation)/;
 const SKIP_ATTR_NAMES = new Set(['className', 'class', 'style', 'key', 'id', 'role', 'type', 'name', 'htmlFor', 'suppressHydrationWarning']);
+const USER_FACING_PROP_NAMES = new Set([
+  'title',
+  'heading',
+  'subheading',
+  'subtitle',
+  'label',
+  'description',
+  'caption',
+  'badge',
+  'buttonText',
+  'ctaText',
+  'helperText',
+  'summary',
+]);
+
+const importedDataCache = new Map();
+
+function resolveImportedBinding(specifier, identifierName, currentFileAbs, profile) {
+  if (!specifier || !profile?.root || !currentFileAbs) return null;
+  const resolved = resolveImportSpecifier(profile, currentFileAbs, specifier);
+  if (!resolved || !fs.existsSync(resolved)) return null;
+  if (importedDataCache.has(resolved)) {
+    return importedDataCache.get(resolved).get(identifierName) || null;
+  }
+  try {
+    const src = fs.readFileSync(resolved, 'utf8');
+    const importedAst = parseSource(src, resolved);
+    const importedBindings = collectStringBindings(importedAst);
+    importedDataCache.set(resolved, importedBindings);
+    return importedBindings.get(identifierName) || null;
+  } catch {
+    return null;
+  }
+}
 
 function fingerprintCandidate(features) {
   return shortHash(JSON.stringify(features));
@@ -42,9 +78,10 @@ function normalizeText(value) {
   return String(value || '').replace(/\s+/g, ' ').trim();
 }
 
-function isStaticSkipText(text) {
+function isStaticSkipText(text, isLogoContext = false) {
   const value = normalizeText(text);
-  if (!value || value.length < 2) return true;
+  if (!value) return true;
+  if (value.length < 2 && !isLogoContext) return true;
   if (TECHNICAL_TEXT_RE.test(value)) return true;
   if (/^[{}`\\]/.test(value)) return true;
   if (/^https?:\/\/(localhost|127\.0\.0\.1)/i.test(value)) return true;
@@ -350,6 +387,7 @@ function collectItemFieldUsage(callback, itemParam) {
   }
 
   let usesItemAsComponent = false;
+  let usesDirectItem = false;
   const componentProps = new Set();
   recast.types.visit(callback, {
     visitJSXOpeningElement(pathNode) {
@@ -364,6 +402,11 @@ function collectItemFieldUsage(callback, itemParam) {
       this.traverse(pathNode);
     },
     visitJSXExpressionContainer(pathNode) {
+      const rawExpr = pathNode.node.expression;
+      const unwrapped = unwrapTypeCasts(rawExpr);
+      if (unwrapped && (unwrapped.type === 'Identifier' || unwrapped.type === 'JSXIdentifier') && unwrapped.name === itemParam) {
+        usesDirectItem = true;
+      }
       const properties = findItemMemberProperties(pathNode.node.expression);
       for (const property of properties) {
         if (componentProps.has(property)) continue;
@@ -385,7 +428,7 @@ function collectItemFieldUsage(callback, itemParam) {
     },
   });
 
-  return { usage, usesItemAsComponent };
+  return { usage, usesItemAsComponent, usesDirectItem };
 }
 
 function classNameOf(node) {
@@ -485,7 +528,14 @@ function analyzeFile({ code, relativeFile, profile, graph, ownerScope, component
       const mapInfo = inMapCallback(pathNode);
       let apiOwned = false;
       if (mapInfo && mapInfo.objectName) {
-        const binding = bindings.get(mapInfo.objectName);
+        let binding = bindings.get(mapInfo.objectName);
+        if (!binding && imports[mapInfo.objectName]) {
+          const currentFileAbs = profile?.root ? path.join(profile.root, relativeFile) : null;
+          binding = resolveImportedBinding(imports[mapInfo.objectName], mapInfo.objectName, currentFileAbs, profile);
+          if (binding) {
+            bindings.set(mapInfo.objectName, binding);
+          }
+        }
         if (!binding || binding.kind !== 'array') apiOwned = true;
       }
 
@@ -514,11 +564,24 @@ function analyzeFile({ code, relativeFile, profile, graph, ownerScope, component
       const parents = parentNames(pathNode);
       const actionNode = resolveActionWithAdapters(node, adapters) || (ACTION_TAGS.has(name) ? node : null);
 
+      const isHeaderNav =
+        parents.some((p) => /header|nav|navbar/i.test(p)) ||
+        /header|nav|navbar/i.test(name) ||
+        /header|nav/i.test(relativeFile) ||
+        componentMeta?.role === 'navigation';
+      const ariaLabel = getJsxAttributeLiteral(node, 'aria-label') || '';
+      const isExplicitLogo = /\b(site-logo|brand-logo|nav-logo|header-logo|monogram)\b/i.test(className);
+      const isLogoContext =
+        isExplicitLogo ||
+        (isHeaderNav && /\blogo\b/i.test(className)) ||
+        (isHeaderNav && /\b(logo|home)\b/i.test(ariaLabel)) ||
+        (isHeaderNav && (href === '/' || href === ''));
+
       const baseMeta = {
         loc,
         tag: name,
         file: relativeFile,
-        ownerScope,
+        ownerScope: (isLogoContext && isHeaderNav) ? 'common' : ownerScope,
         componentName: componentMeta?.name,
         role: componentMeta?.role,
         className,
@@ -529,6 +592,43 @@ function analyzeFile({ code, relativeFile, profile, graph, ownerScope, component
         fromBinding: textInfo.fromBinding,
       };
 
+      if (isLogoContext) {
+        if ((IMAGE_TAGS.has(name) || recognition?.kind === 'image') && src && !src.startsWith('{')) {
+          usedLocs.add(loc);
+          candidates.push({
+            ...baseMeta,
+            kind: 'image',
+            operation: 'extract-image',
+            value: src,
+            extra: { alt: alt || 'Logo', isBrandLogo: true },
+            confidence: 0.98,
+            reason: 'brand-logo-image',
+            fingerprint: fingerprintCandidate({ tag: name, kind: 'logo-image' }),
+          });
+          this.traverse(pathNode);
+          return;
+        }
+
+        if (name === 'Link' || name === 'a' || name === 'span') {
+          const logoText = textInfo.text || collectJsxText(node);
+          if (logoText && !isStaticSkipText(logoText, true)) {
+            usedLocs.add(loc);
+            candidates.push({
+              ...baseMeta,
+              kind: 'text',
+              operation: 'extract-text',
+              value: logoText,
+              extra: { tag: name, isBrandLogo: true },
+              confidence: 0.98,
+              reason: 'brand-logo-text',
+              fingerprint: fingerprintCandidate({ tag: name, kind: 'logo-text', text: logoText }),
+            });
+            this.traverse(pathNode);
+            return;
+          }
+        }
+      }
+
       if ((IMAGE_TAGS.has(name) || recognition?.kind === 'image') && src && !src.startsWith('{')) {
         usedLocs.add(loc);
         candidates.push({
@@ -569,6 +669,43 @@ function analyzeFile({ code, relativeFile, profile, graph, ownerScope, component
         });
       }
 
+      const isCustomComponent = Boolean(name && ((name[0] >= 'A' && name[0] <= 'Z') || name.includes('.')));
+      if (isCustomComponent && !apiOwned && node.openingElement && Array.isArray(node.openingElement.attributes)) {
+        for (const attr of node.openingElement.attributes) {
+          if (attr.type === 'JSXAttribute' && attr.name && USER_FACING_PROP_NAMES.has(attr.name.name)) {
+            const propName = attr.name.name;
+            let propValue = '';
+            if (attr.value) {
+              if (attr.value.type === 'StringLiteral' || attr.value.type === 'Literal') {
+                propValue = String(attr.value.value || '');
+              } else if (attr.value.type === 'JSXExpressionContainer') {
+                const expr = attr.value.expression;
+                if (expr && (expr.type === 'StringLiteral' || expr.type === 'Literal')) {
+                  propValue = String(expr.value || '');
+                }
+              }
+            }
+            if (propValue && !isStaticSkipText(propValue)) {
+              const propLoc = `${loc}:${propName}`;
+              if (!usedLocs.has(propLoc)) {
+                usedLocs.add(propLoc);
+                candidates.push({
+                  ...baseMeta,
+                  loc: propLoc,
+                  kind: 'text',
+                  operation: 'extract-prop',
+                  value: propValue,
+                  extra: { propName, tag: name },
+                  confidence: 0.88,
+                  reason: `component-prop-${propName}`,
+                  fingerprint: fingerprintCandidate({ tag: name, kind: 'prop', propName }),
+                });
+              }
+            }
+          }
+        }
+      }
+
       const insideForm = parents.some((p) => FORM_CONTAINER_TAGS.has(p));
 
       const actionableHref = href || (name === 'Button' ? getJsxAttributeLiteral(node, 'href') : null);
@@ -736,13 +873,15 @@ function analyzeFile({ code, relativeFile, profile, graph, ownerScope, component
         bindings.get(mapInfo.objectName)?.kind === 'array'
       ) {
         const arr = bindings.get(mapInfo.objectName);
-        const { usage: itemUsage, usesItemAsComponent } = collectItemFieldUsage(mapInfo.callback, mapInfo.itemParam);
+        const { usage: itemUsage, usesItemAsComponent, usesDirectItem } = collectItemFieldUsage(mapInfo.callback, mapInfo.itemParam);
         const objectItems = arr.items.every((item) => item.type === 'object');
+        const stringItems = arr.items.every((item) => item.type === 'string');
         const boundProperties = [...itemUsage.keys()];
         const convertible =
-          objectItems &&
-          boundProperties.length > 0 &&
-          arr.items.some((item) => boundProperties.some((key) => key in item.value));
+          (objectItems &&
+            boundProperties.length > 0 &&
+            arr.items.some((item) => boundProperties.some((key) => key in item.value))) ||
+          (stringItems && usesDirectItem);
 
         candidates.push({
           ...baseMeta,
@@ -751,10 +890,11 @@ function analyzeFile({ code, relativeFile, profile, graph, ownerScope, component
           value: arr.items,
           extra: {
             staticCollection: true,
+            isPrimitiveArray: stringItems && usesDirectItem,
             binding: mapInfo.objectName,
             itemParam: mapInfo.itemParam,
             indexParam: mapInfo.indexParam,
-            itemFields: [...itemUsage.entries()].map(([key, role]) => ({ key, role })),
+            itemFields: stringItems ? [] : [...itemUsage.entries()].map(([key, role]) => ({ key, role })),
             objectItems,
             hasComponentRef: usesItemAsComponent,
           },
@@ -766,7 +906,7 @@ function analyzeFile({ code, relativeFile, profile, graph, ownerScope, component
           reason: usesItemAsComponent
             ? 'collection-holds-component-ref'
             : convertible
-              ? 'static-array-map'
+              ? (stringItems ? 'static-primitive-array-map' : 'static-array-map')
               : 'collection-shape-partial',
           fingerprint: fingerprintCandidate({ tag: name, kind: 'collection', size: arr.items.length }),
         });

package/src/arc/transformer.cjs

@@ -19,6 +19,8 @@ const {
   jsxPreviewAttr,
   jsxTemplatePathAttr,
   wrapTextInEditableSpan,
+  unwrapExpr,
+  extractItemMemberName,
   jsxStyleAttrs,
   ensureStyleAttrs,
   b,
@@ -27,10 +29,14 @@ 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 targetLoc = parts.length > 4 ? parts.slice(0, 4).join(':') : loc;
   let found = null;
   recast.types.visit(ast, {
     visitJSXElement(pathNode) {
-      if (locKey(pathNode.node) === loc) {
+      const k = locKey(pathNode.node);
+      if (k === targetLoc || k === loc) {
         found = pathNode;
         return false;
       }
@@ -243,6 +249,14 @@ function applyTransformToElement(pathNode, transform) {
     ensurePreviewPath(node, transform.field);
     return;
   }
+  if (transform.operation === 'extract-prop') {
+    const propName = transform.propName || 'title';
+    replaceAttrValue(node, propName, siteDataBinding(transform.field.split('.'), transform.fallback, transform.fieldType || 'text'));
+    if (!hasJsxAttribute(node, 'data-preview-field-path') && !hasJsxAttribute(node, 'data-preview-list-path')) {
+      ensurePreviewPath(node, transform.field);
+    }
+    return;
+  }
   if (transform.operation === 'wrap-text-span') {
     wrapLiteralTextChildren(node, transform.field, transform.fallback);
     return;
@@ -397,7 +411,11 @@ function applyCollectionTransform(ast, transform, isClient = false, isTypeScript
     );
   }
 
-  markItemFields(callback, { listPath, binding, indexName });
+  if (transform.isPrimitiveArray) {
+    markPrimitiveItemFields(callback, { listPath, binding, indexName });
+  } else {
+    markItemFields(callback, { listPath, binding, indexName });
+  }
   markComponentRefItemsStatic(callback, binding);
 
   const container = findListContainer(mapCall);
@@ -535,9 +553,66 @@ function markComponentRefItemsStatic(callback, binding) {
 }
 
 function itemMemberName(expr, binding) {
-  if (!expr || expr.type !== 'MemberExpression' || expr.computed) return null;
-  if (expr.object?.type !== 'Identifier' || expr.object.name !== binding) return null;
-  return expr.property?.name || null;
+  return extractItemMemberName(expr, binding);
+}
+
+function isDirectItemExpr(expr, binding) {
+  if (!expr) return false;
+  const unwrapped = unwrapExpr(expr);
+  return Boolean(
+    unwrapped &&
+      (unwrapped.type === 'Identifier' || unwrapped.type === 'JSXIdentifier') &&
+      unwrapped.name === binding
+  );
+}
+
+function markPrimitiveItemFields(callback, { listPath, binding, indexName }) {
+  recast.types.visit(callback, {
+    visitJSXElement(pathNode) {
+      const node = pathNode.node;
+      const textChild = (node.children || []).find(
+        (child) => child.type === 'JSXExpressionContainer' && isDirectItemExpr(child.expression, binding)
+      );
+      if (textChild && !hasJsxAttribute(node, 'data-preview-field-path')) {
+        const tagName = getJsxName(node);
+        if (
+          node.children.length === 1 &&
+          (tagName === 'span' || tagName === 'p' || tagName === 'li') &&
+          !hasJsxAttribute(node, 'data-preview-item-path')
+        ) {
+          node.openingElement.attributes.push(
+            jsxTemplatePathAttr('data-preview-field-path', listPath, indexName, '')
+          );
+        } else {
+          wrapPrimitiveItemFieldInSpan(node, textChild, listPath, indexName);
+        }
+      }
+      this.traverse(pathNode);
+    },
+  });
+}
+
+function wrapPrimitiveItemFieldInSpan(node, textChild, listPath, indexName) {
+  const nextChildren = [];
+  for (const child of node.children || []) {
+    if (child === textChild) {
+      nextChildren.push(
+        b.jsxElement(
+          b.jsxOpeningElement(
+            b.jsxIdentifier('span'),
+            [jsxTemplatePathAttr('data-preview-field-path', listPath, indexName, '')],
+            false
+          ),
+          b.jsxClosingElement(b.jsxIdentifier('span')),
+          [child],
+          false
+        )
+      );
+    } else {
+      nextChildren.push(child);
+    }
+  }
+  node.children = nextChildren;
 }
 
 /** The nearest JSX element that wraps the map expression. */
@@ -642,6 +717,61 @@ function bindArrayDeclaration(ast, mapCallPath, listPath, isClient = false, merg
     },
   });
 
+  if (!bound) {
+    recast.types.visit(ast, {
+      visitImportDeclaration(pathNode) {
+        if (bound) return false;
+        const node = pathNode.node;
+        const spec = (node.specifiers || []).find(
+          (s) => (s.local?.name || s.imported?.name) === arrayName
+        );
+        if (!spec) {
+          this.traverse(pathNode);
+          return;
+        }
+
+        const defaultName = 'DEFAULT_' + arrayName;
+        if (spec.type === 'ImportSpecifier') {
+          spec.local = b.identifier(defaultName);
+        } else if (spec.type === 'ImportDefaultSpecifier') {
+          spec.local = b.identifier(defaultName);
+        }
+
+        const fnPath = findEnclosingFunction(mapCallPath);
+        if (fnPath && fnPath.node.body?.type === 'BlockStatement') {
+          const body = fnPath.node.body.body;
+          const already = body.some(
+            (stmt) =>
+              recast.print(stmt).code.includes(`const ${arrayName} =`) ||
+              recast.print(stmt).code.includes(`const ${arrayName}:`)
+          );
+          if (!already) {
+            const localId = b.identifier(arrayName);
+            if (isTypeScript) {
+              localId.typeAnnotation = b.tsTypeAnnotation(b.tsArrayType(b.tsAnyKeyword()));
+            }
+            const localDecl = b.variableDeclaration('const', [
+              b.variableDeclarator(
+                localId,
+                mergeDefaultRefs
+                  ? mergeDefaultItemRefsBinding(listPath.split('.'), defaultName)
+                  : siteDataListBinding(listPath.split('.'), b.identifier(defaultName))
+              ),
+            ]);
+            const hookIdx = body.findIndex((stmt) => recast.print(stmt).code.includes('useSiteData'));
+            if (hookIdx >= 0) {
+              body.splice(hookIdx + 1, 0, localDecl);
+            } else {
+              body.unshift(localDecl);
+            }
+          }
+        }
+        bound = true;
+        return false;
+      },
+    });
+  }
+
   return bound;
 }
 
@@ -823,13 +953,15 @@ function injectSiteDataHook(ast) {
 }
 
 function resolveSiteDataSpecifier(profile, fromRelativeFile) {
-  const aliases = profile.aliasMap || {};
+  const aliases = (profile && profile.aliasMap) || {};
   const hasAt = Object.keys(aliases).some((k) => k === '@/*' || k.startsWith('@/'));
-  const siteDataRel = profile.hasSrc ? 'src/data/site-data.json' : 'data/site-data.json';
-  if (hasAt && profile.hasSrc) return '@/data/site-data.json';
+  const hasSrc = Boolean(profile && profile.hasSrc);
+  const siteDataRel = hasSrc ? 'src/data/site-data.json' : 'data/site-data.json';
+  if (hasAt && hasSrc) return '@/data/site-data.json';
 
-  const fromAbs = path.join(profile.root, fromRelativeFile);
-  const toAbs = path.join(profile.root, siteDataRel);
+  const root = profile && profile.root ? profile.root : process.cwd();
+  const fromAbs = path.join(root, fromRelativeFile || 'page.tsx');
+  const toAbs = path.join(root, siteDataRel);
   let relSpec = path.relative(path.dirname(fromAbs), toAbs).replace(/\\/g, '/');
   if (!relSpec.startsWith('.')) relSpec = './' + relSpec;
   return relSpec;
@@ -853,6 +985,7 @@ function applyFilePlan(filePlan, profile) {
     'extract-alt',
     'extract-placeholder',
     'extract-text',
+    'extract-prop',
     'wrap-text-span',
     'collection-conversion',
     'style-bind',
@@ -915,6 +1048,8 @@ function applyFilePlan(filePlan, profile) {
   healEmptyStateConditionals(ast);
   healHiddenPreviewMarkers(ast);
   healLegacyProductDetailLinks(ast);
+  healSectionOverflowHidden(ast);
+  healDecorativeOverlays(ast);
 
   // Page keys are stamped in a separate route-driven pass so App Router and
   // Pages Router projects are handled by the same logic.
@@ -1152,11 +1287,98 @@ function instrumentLayoutSource(code, siteDataImport, providerImport = '@deneb-u
 
   ensureProviderInitialData(ast, jsonIdent);
   injectPlatformAdditionalPages(ast, providerImport);
+  injectDualModeTheme(ast, jsonIdent, providerImport);
   sanitizeDuplicateBindings(ast);
   const next = printSource(ast, code);
   return { code: next, updated: next !== code };
 }
 
+/**
+ * Injects <ThemeStyles /> and <ThemeToggle /> into the layout JSX tree.
+ * ThemeStyles applies light/dark variables and auto-contrast rules.
+ * ThemeToggle provides an out-of-the-box floating theme switcher.
+ */
+function injectDualModeTheme(ast, jsonIdent, providerImport = '@deneb-ui/ui') {
+  if (!ast) return;
+  let hasThemeStyles = false;
+  let hasThemeToggle = false;
+  recast.types.visit(ast, {
+    visitJSXIdentifier(pathNode) {
+      if (pathNode.node.name === 'ThemeStyles') hasThemeStyles = true;
+      if (pathNode.node.name === 'ThemeToggle') hasThemeToggle = true;
+      this.traverse(pathNode);
+    },
+  });
+
+  const importsToAdd = [];
+  if (!hasThemeStyles) importsToAdd.push('ThemeStyles');
+  if (!hasThemeToggle) importsToAdd.push('ThemeToggle');
+  if (importsToAdd.length === 0) return;
+
+  if (!hasThemeStyles) {
+    let stylesInjected = false;
+    const snippet = parseSource(
+      `<ThemeStyles theme={${jsonIdent}?.template?.structure?.theme || ${jsonIdent}?.theme} enableDualMode />`,
+      'snippet.tsx'
+    );
+    const stylesEl = snippet.program.body[0].expression;
+
+    // Try <head> first
+    recast.types.visit(ast, {
+      visitJSXElement(pathNode) {
+        if (stylesInjected) return false;
+        const name = getJsxName(pathNode.node);
+        if (name === 'head' || name === 'Head') {
+          pathNode.node.children = [b.jsxText('\n        '), stylesEl, ...(pathNode.node.children || [])];
+          stylesInjected = true;
+          return false;
+        }
+        this.traverse(pathNode);
+      },
+    });
+
+    // If no <head>, inject inside SiteDataProvider or <body>
+    if (!stylesInjected) {
+      recast.types.visit(ast, {
+        visitJSXElement(pathNode) {
+          if (stylesInjected) return false;
+          const name = getJsxName(pathNode.node);
+          if (name === 'SiteDataProvider' || name === 'body') {
+            pathNode.node.children = [b.jsxText('\n        '), stylesEl, ...(pathNode.node.children || [])];
+            stylesInjected = true;
+            return false;
+          }
+          this.traverse(pathNode);
+        },
+      });
+    }
+  }
+
+  if (!hasThemeToggle) {
+    let toggleInjected = false;
+    const snippet = parseSource(
+      '<ThemeToggle showLabel className="fixed bottom-6 left-6 z-40" />',
+      'snippet.tsx'
+    );
+    const toggleEl = snippet.program.body[0].expression;
+
+    recast.types.visit(ast, {
+      visitJSXElement(pathNode) {
+        if (toggleInjected) return false;
+        const name = getJsxName(pathNode.node);
+        if (name === 'SiteDataProvider' || name === 'body') {
+          pathNode.node.children = [...(pathNode.node.children || []), b.jsxText('\n        '), toggleEl];
+          toggleInjected = true;
+          return false;
+        }
+        this.traverse(pathNode);
+      },
+    });
+  }
+
+  ensureImport(ast, providerImport || '@deneb-ui/ui', importsToAdd);
+}
+
 /**
  * Injects <PlatformAdditionalPages /> into the layout JSX tree after <main>.
  * This component handles all additionalPages visual-editing markers correctly
@@ -1329,8 +1551,9 @@ function sanitizeContradictoryMarkersInSource(code, relativeFile) {
   const healedEmpty = healEmptyStateConditionals(ast);
   const healedHidden = healHiddenPreviewMarkers(ast);
   const healedOverflow = healSectionOverflowHidden(ast);
-  if (cleaned === 0 && healedBroad === 0 && healedEmpty === 0 && healedHidden === 0 && healedOverflow === 0) return { code, updated: false };
-  return { code: printSource(ast, code), updated: true, count: cleaned + healedBroad + healedEmpty + healedHidden + healedOverflow };
+  const healedOverlay = healDecorativeOverlays(ast);
+  if (cleaned === 0 && healedBroad === 0 && healedEmpty === 0 && healedHidden === 0 && healedOverflow === 0 && healedOverlay === 0) return { code, updated: false };
+  return { code: printSource(ast, code), updated: true, count: cleaned + healedBroad + healedEmpty + healedHidden + healedOverflow + healedOverlay };
 }
 
 function healBroadContainerMarkers(ast) {
@@ -1622,6 +1845,71 @@ function healSectionOverflowHidden(ast) {
   return healed;
 }
 
+function healDecorativeOverlays(ast) {
+  let healed = 0;
+  recast.types.visit(ast, {
+    visitJSXElement(pathNode) {
+      const node = pathNode.node;
+      const tag = getJsxName(node);
+      const lower = String(tag || '').toLowerCase();
+      if (lower !== 'div' && lower !== 'span') {
+        this.traverse(pathNode);
+        return;
+      }
+      const hasRealChildren = (node.children || []).some(
+        (c) => c.type === 'JSXElement' || (c.type === 'JSXText' && c.value.trim().length > 0)
+      );
+      if (hasRealChildren) {
+        this.traverse(pathNode);
+        return;
+      }
+      const classAttr = (node.openingElement.attributes || []).find(
+        (a) => a.type === 'JSXAttribute' && a.name && (a.name.name === 'className' || a.name.name === 'class')
+      );
+      if (!classAttr || !classAttr.value) {
+        this.traverse(pathNode);
+        return;
+      }
+      let modified = false;
+      const overlayPattern = /\b(?:bg-gradient-|bg-black\/|bg-white\/|bg-slate-\d+\/|backdrop-blur)/;
+      const isAbsolute = /\babsolute\b/;
+      const hasPointerEvents = /\bpointer-events-(?:none|auto)\b/;
+
+      if (classAttr.value.type === 'StringLiteral' || classAttr.value.type === 'Literal') {
+        const val = String(classAttr.value.value || '');
+        if (isAbsolute.test(val) && overlayPattern.test(val) && !hasPointerEvents.test(val)) {
+          classAttr.value.value = `${val} pointer-events-none`;
+          modified = true;
+        }
+      } else if (classAttr.value.type === 'JSXExpressionContainer') {
+        const expr = classAttr.value.expression;
+        if (expr && (expr.type === 'StringLiteral' || expr.type === 'Literal')) {
+          const val = String(expr.value || '');
+          if (isAbsolute.test(val) && overlayPattern.test(val) && !hasPointerEvents.test(val)) {
+            expr.value = `${val} pointer-events-none`;
+            modified = true;
+          }
+        } else if (expr && expr.type === 'TemplateLiteral') {
+          const fullText = (expr.quasis || []).map((q) => q.value?.raw || '').join(' ');
+          if (isAbsolute.test(fullText) && overlayPattern.test(fullText) && !hasPointerEvents.test(fullText)) {
+            const lastQuasi = expr.quasis[expr.quasis.length - 1];
+            if (lastQuasi && lastQuasi.value) {
+              lastQuasi.value.raw = `${lastQuasi.value.raw} pointer-events-none`;
+              if (lastQuasi.value.cooked) {
+                lastQuasi.value.cooked = `${lastQuasi.value.cooked} pointer-events-none`;
+              }
+              modified = true;
+            }
+          }
+        }
+      }
+      if (modified) healed++;
+      this.traverse(pathNode);
+    },
+  });
+  return healed;
+}
+
 function healMissingSiteDataHooks(code, filePath = 'file.tsx') {
   if (!code.includes('siteData')) return code;
   try {
@@ -1651,6 +1939,7 @@ module.exports = {
   healEmptyStateConditionals,
   healHiddenPreviewMarkers,
   healSectionOverflowHidden,
+  healDecorativeOverlays,
   healLegacyProductDetailLinks,
   healMissingSiteDataHooks,
   injectSiteDataHook,