@nuvio/ast-engine 0.5.4 → 1.0.0

package/dist/index.d.ts

@@ -1,6 +1,11 @@
 import { PatchOp } from '@nuvio/shared';
+export { NUVIO_ID_PATTERN, isValidNuvioId, suggestNuvioId } from '@nuvio/shared';
+import { JSXOpeningElement } from '@babel/types';
+
+type ClassNameMode = "literal-only" | "cn-basic" | "cn-conditional" | "classnames-static" | "unsupported";
+declare function classifyHostClassNameMode(opening: JSXOpeningElement): ClassNameMode;
+declare function readFlattenedClassName(opening: JSXOpeningElement, mode: ClassNameMode): string | undefined;
 
-type ClassNameMode = "literal-only" | "cn-basic";
 type Breakpoint = "base" | "sm" | "md" | "lg" | "xl";
 type BreakpointBuckets = {
     base: string[];
@@ -31,10 +36,24 @@ declare function applyPatchToSource(source: string, filePath: string, hostId: st
     activeBreakpoint?: Breakpoint;
 }): Promise<ApplyPatchToSourceResult>;
 
+type InsertNuvioIdResult = {
+    ok: true;
+    source: string;
+    id: string;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * Insert `data-nuvio-id` on the JSX opening element at the given 1-based line / 0-based column.
+ */
+declare function insertDataNuvioIdAtLocation(source: string, filePath: string, line: number, column: number, id: string): Promise<InsertNuvioIdResult>;
+
 /**
  * Phase 2 — conservative Tailwind v3-style allowlist for `mergeTailwindClassName`.
  * Expand intentionally; unknown tokens are rejected before `tailwind-merge`.
  */
 declare function validateTailwindFragment(fragment: string): void;
 
-export { type ApplyPatchToSourceResult, applyPatchToSource, mergeAtBreakpoint, parseClassNameByBreakpoint, removeAtBreakpoint, validateTailwindFragment };
+export { type ApplyPatchToSourceResult, type ClassNameMode, type InsertNuvioIdResult, applyPatchToSource, classifyHostClassNameMode, insertDataNuvioIdAtLocation, mergeAtBreakpoint, parseClassNameByBreakpoint, readFlattenedClassName, removeAtBreakpoint, validateTailwindFragment };

package/dist/index.js

@@ -2,7 +2,7 @@
 import { createRequire as createRequire2 } from "module";
 import path from "path";
 import { parse as parse2 } from "@babel/parser";
-import * as t2 from "@babel/types";
+import * as t4 from "@babel/types";
 import prettier from "prettier";
 import { twMerge } from "tailwind-merge";
 
@@ -36,14 +36,14 @@ function normalizeTailwindToken(raw) {
 function validateTailwindFragment(fragment) {
   const tokens = fragment.trim().split(/\s+/).filter(Boolean);
   for (const raw of tokens) {
-    const t3 = normalizeTailwindToken(raw);
-    if (!t3) {
+    const t6 = normalizeTailwindToken(raw);
+    if (!t6) {
       continue;
     }
-    if (SPACING.test(t3) || TEXT_SIZE.test(t3) || FONT_WEIGHT.test(t3) || LEADING.test(t3) || COLOR_SOLID.test(t3) || COLOR_SCALE.test(t3) || BG_COLOR_OPACITY.test(t3) || ROUNDED.test(t3) || LAYOUT.test(t3) || FLEX.test(t3) || GRID_COLS.test(t3) || BORDER_W.test(t3) || BORDER_COLOR.test(t3) || RING.test(t3) || RING_COLOR.test(t3) || TEXT_ALIGN.test(t3) || TRACKING.test(t3) || OPACITY.test(t3) || SHADOW.test(t3) || W_WIDTH.test(t3) || H_HEIGHT.test(t3) || MAX_W.test(t3) || MIN_H.test(t3)) {
+    if (SPACING.test(t6) || TEXT_SIZE.test(t6) || FONT_WEIGHT.test(t6) || LEADING.test(t6) || COLOR_SOLID.test(t6) || COLOR_SCALE.test(t6) || BG_COLOR_OPACITY.test(t6) || ROUNDED.test(t6) || LAYOUT.test(t6) || FLEX.test(t6) || GRID_COLS.test(t6) || BORDER_W.test(t6) || BORDER_COLOR.test(t6) || RING.test(t6) || RING_COLOR.test(t6) || TEXT_ALIGN.test(t6) || TRACKING.test(t6) || OPACITY.test(t6) || SHADOW.test(t6) || W_WIDTH.test(t6) || H_HEIGHT.test(t6) || MAX_W.test(t6) || MIN_H.test(t6)) {
       continue;
     }
-    throw new Error(`Unknown or disallowed Tailwind utility: ${t3}`);
+    throw new Error(`Unknown or disallowed Tailwind utility: ${t6}`);
   }
 }
 
@@ -103,6 +103,279 @@ function applySetTableDataField(ast, arrayName, rowKey, field, value) {
   }
 }
 
+// src/classname-binding.ts
+import * as t3 from "@babel/types";
+
+// src/classname-mode.ts
+import * as t2 from "@babel/types";
+var CN_CALLEES = /* @__PURE__ */ new Set(["cn", "clsx"]);
+var CLASSNAMES_CALLEES = /* @__PURE__ */ new Set(["classnames", "clsx", "cn"]);
+function isCnCallee(call) {
+  return t2.isIdentifier(call.callee) && CN_CALLEES.has(call.callee.name);
+}
+function isClassnamesCallee(call) {
+  return t2.isIdentifier(call.callee) && CLASSNAMES_CALLEES.has(call.callee.name);
+}
+function isExpressionArg(arg) {
+  return t2.isExpression(arg);
+}
+function isConditionalTailwindArg(arg) {
+  return t2.isLogicalExpression(arg) && arg.operator === "&&" && t2.isStringLiteral(arg.right);
+}
+function isStaticObjectArg(arg) {
+  if (!t2.isObjectExpression(arg)) {
+    return false;
+  }
+  return arg.properties.every((prop) => {
+    if (!t2.isObjectProperty(prop) || prop.computed) {
+      return false;
+    }
+    const keyOk = t2.isIdentifier(prop.key) || t2.isStringLiteral(prop.key);
+    if (!keyOk) {
+      return false;
+    }
+    return !t2.isStringLiteral(prop.value);
+  });
+}
+function objectArgClassKeys(obj) {
+  const keys = [];
+  for (const prop of obj.properties) {
+    if (!t2.isObjectProperty(prop)) {
+      continue;
+    }
+    if (t2.isIdentifier(prop.key)) {
+      keys.push(prop.key.name);
+    } else if (t2.isStringLiteral(prop.key)) {
+      keys.push(prop.key.value);
+    }
+  }
+  return keys;
+}
+function classifyClassNameCall(call) {
+  const args = call.arguments.filter(isExpressionArg);
+  if (args.length === 0) {
+    return "unsupported";
+  }
+  const hasObject = args.some((a) => isStaticObjectArg(a));
+  if (hasObject && isClassnamesCallee(call)) {
+    if (args.every((a) => t2.isStringLiteral(a) || isStaticObjectArg(a))) {
+      return "classnames-static";
+    }
+    return "unsupported";
+  }
+  if (!isCnCallee(call)) {
+    return "unsupported";
+  }
+  if (args.every((a) => t2.isStringLiteral(a))) {
+    return "cn-basic";
+  }
+  if (args.every((a) => t2.isStringLiteral(a) || isConditionalTailwindArg(a))) {
+    return "cn-conditional";
+  }
+  return "unsupported";
+}
+function classifyHostClassNameMode(opening) {
+  for (const attr of opening.attributes) {
+    if (!t2.isJSXAttribute(attr) || !t2.isJSXIdentifier(attr.name, { name: "className" })) {
+      continue;
+    }
+    if (t2.isStringLiteral(attr.value)) {
+      return "literal-only";
+    }
+    if (t2.isJSXExpressionContainer(attr.value) && t2.isCallExpression(attr.value.expression)) {
+      return classifyClassNameCall(attr.value.expression);
+    }
+    return "unsupported";
+  }
+  return "literal-only";
+}
+function readFlattenedClassName(opening, mode) {
+  for (const attr of opening.attributes) {
+    if (!t2.isJSXAttribute(attr) || !t2.isJSXIdentifier(attr.name, { name: "className" })) {
+      continue;
+    }
+    if (t2.isStringLiteral(attr.value)) {
+      return attr.value.value;
+    }
+    if (!t2.isJSXExpressionContainer(attr.value) || !t2.isCallExpression(attr.value.expression)) {
+      return void 0;
+    }
+    const call = attr.value.expression;
+    const parts = [];
+    for (const arg of call.arguments.filter(isExpressionArg)) {
+      if (t2.isStringLiteral(arg)) {
+        parts.push(arg.value);
+      } else if (isConditionalTailwindArg(arg) && t2.isStringLiteral(arg.right)) {
+        parts.push(arg.right.value);
+      } else if (isStaticObjectArg(arg)) {
+        parts.push(...objectArgClassKeys(arg));
+      }
+    }
+    if (parts.length === 0) {
+      return void 0;
+    }
+    if (mode === "literal-only" || mode === "cn-basic" || mode === "cn-conditional" || mode === "classnames-static") {
+      return parts.join(" ");
+    }
+    return void 0;
+  }
+  return void 0;
+}
+
+// src/classname-binding.ts
+function isExpressionArg2(arg) {
+  return t3.isExpression(arg);
+}
+function isStaticObjectArg2(arg) {
+  if (!t3.isObjectExpression(arg)) {
+    return false;
+  }
+  return arg.properties.every((prop) => {
+    if (!t3.isObjectProperty(prop) || prop.computed) {
+      return false;
+    }
+    return (t3.isIdentifier(prop.key) || t3.isStringLiteral(prop.key)) && !t3.isStringLiteral(prop.value);
+  });
+}
+function readCallFlattened(call) {
+  const parts = [];
+  for (const arg of call.arguments.filter(isExpressionArg2)) {
+    if (t3.isStringLiteral(arg)) {
+      parts.push(arg.value);
+    } else if (t3.isLogicalExpression(arg) && arg.operator === "&&" && t3.isStringLiteral(arg.right)) {
+      parts.push(arg.right.value);
+    } else if (isStaticObjectArg2(arg)) {
+      for (const prop of arg.properties) {
+        if (!t3.isObjectProperty(prop)) {
+          continue;
+        }
+        if (t3.isIdentifier(prop.key)) {
+          parts.push(prop.key.name);
+        } else if (t3.isStringLiteral(prop.key)) {
+          parts.push(prop.key.value);
+        }
+      }
+    }
+  }
+  return parts.join(" ");
+}
+function writeCnBasic(call, next) {
+  call.arguments = [t3.stringLiteral(next)];
+}
+function writeCnConditional(call, next) {
+  const newTokenList = next.trim().split(/\s+/).filter(Boolean);
+  const conditionalArgs = [];
+  const used = /* @__PURE__ */ new Set();
+  for (const arg of call.arguments.filter(isExpressionArg2)) {
+    if (t3.isLogicalExpression(arg) && arg.operator === "&&" && t3.isStringLiteral(arg.right)) {
+      const oldTokens = arg.right.value.split(/\s+/).filter(Boolean);
+      const kept = newTokenList.filter((tok) => oldTokens.includes(tok));
+      for (const tok of kept) {
+        used.add(tok);
+      }
+      arg.right = t3.stringLiteral(kept.join(" "));
+      conditionalArgs.push(arg);
+    }
+  }
+  const baseTokens = newTokenList.filter((tok) => !used.has(tok));
+  const baseStr = baseTokens.join(" ");
+  const literalArgs = call.arguments.filter(
+    (a) => isExpressionArg2(a) && t3.isStringLiteral(a)
+  );
+  if (literalArgs.length > 0) {
+    literalArgs[0].value = baseStr;
+    call.arguments = [literalArgs[0], ...conditionalArgs];
+  } else {
+    call.arguments = [t3.stringLiteral(baseStr), ...conditionalArgs];
+  }
+}
+function writeClassnamesStatic(call, next) {
+  const newTokenList = next.trim().split(/\s+/).filter(Boolean);
+  const objectArgs = call.arguments.filter(
+    (a) => isExpressionArg2(a) && isStaticObjectArg2(a)
+  );
+  const objectKeys = /* @__PURE__ */ new Set();
+  for (const obj of objectArgs) {
+    if (!isStaticObjectArg2(obj)) {
+      continue;
+    }
+    for (const prop of obj.properties) {
+      if (!t3.isObjectProperty(prop)) {
+        continue;
+      }
+      if (t3.isIdentifier(prop.key)) {
+        objectKeys.add(prop.key.name);
+      } else if (t3.isStringLiteral(prop.key)) {
+        objectKeys.add(prop.key.value);
+      }
+    }
+  }
+  const baseTokens = newTokenList.filter((tok) => !objectKeys.has(tok));
+  const baseStr = baseTokens.join(" ");
+  const nonObjectArgs = call.arguments.filter(
+    (a) => isExpressionArg2(a) && !isStaticObjectArg2(a) && t3.isStringLiteral(a)
+  );
+  if (nonObjectArgs.length > 0) {
+    nonObjectArgs[0].value = baseStr;
+    call.arguments = [nonObjectArgs[0], ...objectArgs];
+  } else if (baseStr.length > 0) {
+    call.arguments = [t3.stringLiteral(baseStr), ...objectArgs];
+  } else {
+    call.arguments = [...objectArgs];
+  }
+}
+function getClassNameBinding(opening, classNameMode) {
+  for (const attr of opening.attributes) {
+    if (!t3.isJSXAttribute(attr) || !t3.isJSXIdentifier(attr.name, { name: "className" })) {
+      continue;
+    }
+    if (t3.isStringLiteral(attr.value)) {
+      const literal = attr.value;
+      return {
+        read: () => literal.value,
+        write: (next) => {
+          attr.value = t3.stringLiteral(next);
+        }
+      };
+    }
+    if (!t3.isJSXExpressionContainer(attr.value) || !t3.isCallExpression(attr.value.expression)) {
+      return null;
+    }
+    const call = attr.value.expression;
+    const detected = classifyClassNameCall(call);
+    if (classNameMode === "cn-basic" && detected === "cn-basic") {
+      return {
+        read: () => readCallFlattened(call),
+        write: (next) => writeCnBasic(call, next)
+      };
+    }
+    if (classNameMode === "cn-conditional" && detected === "cn-conditional") {
+      return {
+        read: () => readCallFlattened(call),
+        write: (next) => writeCnConditional(call, next)
+      };
+    }
+    if (classNameMode === "classnames-static" && detected === "classnames-static") {
+      return {
+        read: () => readCallFlattened(call),
+        write: (next) => writeClassnamesStatic(call, next)
+      };
+    }
+    if (classNameMode === "cn-basic" && detected === "cn-conditional") {
+      return null;
+    }
+    return null;
+  }
+  return {
+    read: () => "",
+    write: (next) => {
+      opening.attributes.push(
+        t3.jsxAttribute(t3.jsxIdentifier("className"), t3.stringLiteral(next))
+      );
+    }
+  };
+}
+
 // src/apply-patch.ts
 var require3 = createRequire2(import.meta.url);
 var traverse2 = require3("@babel/traverse").default;
@@ -111,18 +384,18 @@ function extractRowKeysFromSource(ast) {
   const keys = [];
   traverse2(ast, {
     VariableDeclarator(path2) {
-      if (!t2.isIdentifier(path2.node.id) || path2.node.id.name !== "tableData") {
+      if (!t4.isIdentifier(path2.node.id) || path2.node.id.name !== "tableData") {
         return;
       }
-      if (!t2.isArrayExpression(path2.node.init)) {
+      if (!t4.isArrayExpression(path2.node.init)) {
         return;
       }
       for (const el of path2.node.init.elements) {
-        if (!el || !t2.isObjectExpression(el)) {
+        if (!el || !t4.isObjectExpression(el)) {
           continue;
         }
         for (const prop of el.properties) {
-          if (t2.isObjectProperty(prop) && t2.isIdentifier(prop.key, { name: "id" }) && t2.isNumericLiteral(prop.value)) {
+          if (t4.isObjectProperty(prop) && t4.isIdentifier(prop.key, { name: "id" }) && t4.isNumericLiteral(prop.value)) {
             keys.push(String(prop.value.value));
           }
         }
@@ -132,15 +405,15 @@ function extractRowKeysFromSource(ast) {
   return keys;
 }
 function templateLiteralMatchesHostId(attr, hostId, rowKeys) {
-  if (!t2.isJSXExpressionContainer(attr.value)) {
+  if (!t4.isJSXExpressionContainer(attr.value)) {
     return false;
   }
   const expr = attr.value.expression;
-  if (!t2.isTemplateLiteral(expr) || expr.expressions.length !== 1) {
+  if (!t4.isTemplateLiteral(expr) || expr.expressions.length !== 1) {
     return false;
   }
   const ex = expr.expressions[0];
-  const mapOk = t2.isIdentifier(ex, { name: "product" }) || t2.isIdentifier(ex, { name: "item" }) || t2.isMemberExpression(ex) && !ex.computed && t2.isIdentifier(ex.object, { name: "product" }) && t2.isIdentifier(ex.property, { name: "id" });
+  const mapOk = t4.isIdentifier(ex, { name: "product" }) || t4.isIdentifier(ex, { name: "item" }) || t4.isMemberExpression(ex) && !ex.computed && t4.isIdentifier(ex.object, { name: "product" }) && t4.isIdentifier(ex.property, { name: "id" });
   if (!mapOk) {
     return false;
   }
@@ -154,13 +427,13 @@ function findHostOpening(ast, hostId) {
   traverse2(ast, {
     JSXOpeningElement(path2) {
       for (const attr of path2.node.attributes) {
-        if (!t2.isJSXAttribute(attr)) {
+        if (!t4.isJSXAttribute(attr)) {
           continue;
         }
-        if (!t2.isJSXIdentifier(attr.name, { name: "data-nuvio-id" })) {
+        if (!t4.isJSXIdentifier(attr.name, { name: "data-nuvio-id" })) {
           continue;
         }
-        if (t2.isStringLiteral(attr.value) && attr.value.value === hostId) {
+        if (t4.isStringLiteral(attr.value) && attr.value.value === hostId) {
           found = path2;
           path2.stop();
           return;
@@ -183,18 +456,18 @@ function applySetText(openingPath, text) {
   const jsx = parent;
   const { children } = jsx.node;
   if (children.length === 0) {
-    jsx.node.children = [t2.jsxText(text)];
+    jsx.node.children = [t4.jsxText(text)];
     return;
   }
-  if (children.length === 1 && t2.isJSXText(children[0])) {
+  if (children.length === 1 && t4.isJSXText(children[0])) {
     children[0].value = text;
     return;
   }
-  if (children.length === 1 && t2.isJSXExpressionContainer(children[0]) && t2.isStringLiteral(children[0].expression)) {
+  if (children.length === 1 && t4.isJSXExpressionContainer(children[0]) && t4.isStringLiteral(children[0].expression)) {
     children[0].expression.value = text;
     return;
   }
-  jsx.node.children = [t2.jsxText(text)];
+  jsx.node.children = [t4.jsxText(text)];
 }
 function emptyBreakpointBuckets() {
   return {
@@ -246,7 +519,7 @@ function serializeClassNameFromBuckets(buckets) {
     const merged = buckets[bp].join(" ").trim();
     if (merged) {
       out.push(
-        ...merged.split(/\s+/).filter(Boolean).map((t3) => prefixTokenForBreakpoint(t3, bp))
+        ...merged.split(/\s+/).filter(Boolean).map((t6) => prefixTokenForBreakpoint(t6, bp))
       );
     }
   }
@@ -305,13 +578,13 @@ function removeAtBreakpoint(className, fragment, activeBreakpoint) {
   }
   const idx = BREAKPOINT_ORDER.indexOf(activeBreakpoint);
   for (const tok of toRemove) {
-    buckets[activeBreakpoint] = buckets[activeBreakpoint].filter((t3) => t3 !== tok);
+    buckets[activeBreakpoint] = buckets[activeBreakpoint].filter((t6) => t6 !== tok);
     const stillPresent = flattenTokensAtBreakpointFromBuckets(buckets, activeBreakpoint).includes(tok);
     if (stillPresent) {
       for (let i = idx; i >= 0; i--) {
         const bp = BREAKPOINT_ORDER[i];
         if (buckets[bp].includes(tok)) {
-          buckets[bp] = buckets[bp].filter((t3) => t3 !== tok);
+          buckets[bp] = buckets[bp].filter((t6) => t6 !== tok);
           break;
         }
       }
@@ -319,41 +592,6 @@ function removeAtBreakpoint(className, fragment, activeBreakpoint) {
   }
   return serializeClassNameFromBuckets(buckets);
 }
-function getClassNameBinding(opening, classNameMode) {
-  for (const attr of opening.attributes) {
-    if (t2.isJSXAttribute(attr) && t2.isJSXIdentifier(attr.name, { name: "className" })) {
-      if (t2.isStringLiteral(attr.value)) {
-        const literal = attr.value;
-        return {
-          read: () => literal.value,
-          write: (next) => {
-            attr.value = t2.stringLiteral(next);
-          }
-        };
-      }
-      if (classNameMode === "cn-basic" && t2.isJSXExpressionContainer(attr.value) && t2.isCallExpression(attr.value.expression) && (t2.isIdentifier(attr.value.expression.callee) && (attr.value.expression.callee.name === "cn" || attr.value.expression.callee.name === "clsx") || false)) {
-        const call = attr.value.expression;
-        if (call.arguments.every((arg) => t2.isStringLiteral(arg))) {
-          return {
-            read: () => call.arguments.map((arg) => arg.value).join(" "),
-            write: (next) => {
-              call.arguments = [t2.stringLiteral(next)];
-            }
-          };
-        }
-      }
-      return null;
-    }
-  }
-  return {
-    read: () => "",
-    write: (next) => {
-      opening.attributes.push(
-        t2.jsxAttribute(t2.jsxIdentifier("className"), t2.stringLiteral(next))
-      );
-    }
-  };
-}
 function parentSupportsLayoutMoves(parentOpening) {
   const binding = getClassNameBinding(parentOpening, "literal-only");
   if (!binding) {
@@ -365,7 +603,7 @@ function parentSupportsLayoutMoves(parentOpening) {
 function collectJsxElementChildIndices(parent) {
   const indices = [];
   parent.children.forEach((child, i) => {
-    if (t2.isJSXElement(child)) {
+    if (t4.isJSXElement(child)) {
       indices.push(i);
     }
   });
@@ -415,26 +653,26 @@ function applySetHidden(openingPath, hidden, classNameMode, activeBreakpoint) {
   const opening = openingPath.node;
   let clsAttr;
   for (const attr of opening.attributes) {
-    if (t2.isJSXAttribute(attr) && t2.isJSXIdentifier(attr.name, { name: "className" })) {
+    if (t4.isJSXAttribute(attr) && t4.isJSXIdentifier(attr.name, { name: "className" })) {
       clsAttr = attr;
       break;
     }
   }
-  if (!clsAttr || !t2.isStringLiteral(clsAttr.value)) {
+  if (!clsAttr || !t4.isStringLiteral(clsAttr.value)) {
     return;
   }
   const tokens = clsAttr.value.value.split(/\s+/).filter((tok) => tok && tok !== "hidden");
-  clsAttr.value = t2.stringLiteral(twMerge(tokens.join(" ")));
+  clsAttr.value = t4.stringLiteral(twMerge(tokens.join(" ")));
 }
 function collectNuvioIds(ast) {
   const ids = /* @__PURE__ */ new Set();
   traverse2(ast, {
     JSXOpeningElement(path2) {
       for (const attr of path2.node.attributes) {
-        if (!t2.isJSXAttribute(attr) || !t2.isJSXIdentifier(attr.name, { name: "data-nuvio-id" })) {
+        if (!t4.isJSXAttribute(attr) || !t4.isJSXIdentifier(attr.name, { name: "data-nuvio-id" })) {
           continue;
         }
-        if (t2.isStringLiteral(attr.value)) {
+        if (t4.isStringLiteral(attr.value)) {
           ids.add(attr.value.value);
         }
       }
@@ -444,28 +682,28 @@ function collectNuvioIds(ast) {
 }
 function setNuvioIdOnOpening(opening, id) {
   for (const attr of opening.attributes) {
-    if (t2.isJSXAttribute(attr) && t2.isJSXIdentifier(attr.name, { name: "data-nuvio-id" })) {
-      if (t2.isStringLiteral(attr.value)) {
+    if (t4.isJSXAttribute(attr) && t4.isJSXIdentifier(attr.name, { name: "data-nuvio-id" })) {
+      if (t4.isStringLiteral(attr.value)) {
         attr.value.value = id;
         return;
       }
     }
   }
   opening.attributes.push(
-    t2.jsxAttribute(t2.jsxIdentifier("data-nuvio-id"), t2.stringLiteral(id))
+    t4.jsxAttribute(t4.jsxIdentifier("data-nuvio-id"), t4.stringLiteral(id))
   );
 }
 function remapDescendantNuvioIds(element, taken) {
   const stack = [];
   for (const child of element.children) {
-    if (t2.isJSXElement(child)) {
+    if (t4.isJSXElement(child)) {
       stack.push(child);
     }
   }
   while (stack.length > 0) {
     const el = stack.pop();
     for (const attr of el.openingElement.attributes) {
-      if (!t2.isJSXAttribute(attr) || !t2.isJSXIdentifier(attr.name, { name: "data-nuvio-id" }) || !t2.isStringLiteral(attr.value)) {
+      if (!t4.isJSXAttribute(attr) || !t4.isJSXIdentifier(attr.name, { name: "data-nuvio-id" }) || !t4.isStringLiteral(attr.value)) {
         continue;
       }
       const nextId = uniqueDuplicateId(attr.value.value, taken);
@@ -473,7 +711,7 @@ function remapDescendantNuvioIds(element, taken) {
       taken.add(nextId);
     }
     for (const child of el.children) {
-      if (t2.isJSXElement(child)) {
+      if (t4.isJSXElement(child)) {
         stack.push(child);
       }
     }
@@ -501,8 +739,8 @@ function applyDuplicateHost(ast, openingPath, hostId) {
   }
   const taken = collectNuvioIds(ast);
   const newId = uniqueDuplicateId(hostId, taken);
-  const clone = t2.cloneNode(hostPath.node, true);
-  if (!t2.isJSXElement(clone)) {
+  const clone = t4.cloneNode(hostPath.node, true);
+  if (!t4.isJSXElement(clone)) {
     throw new Error("Failed to clone host element");
   }
   setNuvioIdOnOpening(clone.openingElement, newId);
@@ -521,21 +759,29 @@ function applyMergeClassName(openingPath, fragment, classNameMode, activeBreakpo
   const opening = openingPath.node;
   const binding = getClassNameBinding(opening, classNameMode);
   if (!binding) {
-    throw new Error(
-      classNameMode === "cn-basic" ? "className must be a string literal or simple cn()/clsx() string list in cn-basic mode" : "className must be a string literal for Phase 2 patches"
-    );
+    throw new Error(classNamePatchErrorMessage(classNameMode));
   }
   const current = binding.read();
   binding.write(mergeAtBreakpoint(current, fragment.trim(), activeBreakpoint));
 }
+function classNamePatchErrorMessage(mode) {
+  switch (mode) {
+    case "cn-conditional":
+      return 'className must be cn()/clsx() with string literals and condition && "token" branches';
+    case "classnames-static":
+      return "className must be classnames()/clsx() with string literals and a static object map";
+    case "cn-basic":
+      return "className must be a string literal or simple cn()/clsx() string list";
+    default:
+      return "className must be a string literal for Phase 2 patches";
+  }
+}
 function applyRemoveClassName(openingPath, fragment, classNameMode, activeBreakpoint) {
   validateTailwindFragment(fragment);
   const opening = openingPath.node;
   const binding = getClassNameBinding(opening, classNameMode);
   if (!binding) {
-    throw new Error(
-      classNameMode === "cn-basic" ? "className must be a string literal or simple cn()/clsx() string list in cn-basic mode" : "className must be a string literal for Phase 2 patches"
-    );
+    throw new Error(classNamePatchErrorMessage(classNameMode));
   }
   const current = binding.read();
   binding.write(removeAtBreakpoint(current, fragment.trim(), activeBreakpoint));
@@ -642,10 +888,123 @@ async function applyPatchToSource(source, filePath, hostId, ops, options) {
   const diffSummary = `${base}: ${opBits.join("; ")}`;
   return { ok: true, source: formatted, diffSummary };
 }
+
+// src/insert-nuvio-id.ts
+import { createRequire as createRequire3 } from "module";
+import { parse as parse3 } from "@babel/parser";
+import * as t5 from "@babel/types";
+import prettier2 from "prettier";
+
+// src/nuvio-id.ts
+import {
+  isValidNuvioId,
+  NUVIO_ID_PATTERN,
+  suggestNuvioId
+} from "@nuvio/shared";
+
+// src/insert-nuvio-id.ts
+var require4 = createRequire3(import.meta.url);
+var traverse3 = require4("@babel/traverse").default;
+var generate2 = require4("@babel/generator").default;
+function hasNuvioIdAttr(opening) {
+  return opening.attributes.some(
+    (attr) => t5.isJSXAttribute(attr) && t5.isJSXIdentifier(attr.name, { name: "data-nuvio-id" })
+  );
+}
+function findOpeningAtLocation(ast, line, column) {
+  const onLine = [];
+  traverse3(ast, {
+    JSXOpeningElement(path2) {
+      const loc = path2.node.loc?.start;
+      if (!loc || loc.line !== line) {
+        return;
+      }
+      onLine.push({ path: path2, column: loc.column });
+    }
+  });
+  if (onLine.length === 0) {
+    return null;
+  }
+  const exact = onLine.find((entry) => entry.column === column);
+  if (exact) {
+    return exact.path;
+  }
+  if (onLine.length === 1) {
+    return onLine[0].path;
+  }
+  onLine.sort(
+    (a, b) => Math.abs(a.column - column) - Math.abs(b.column - column)
+  );
+  return onLine[0].path;
+}
+async function formatSource(source, filePath) {
+  try {
+    return await prettier2.format(source, {
+      filepath: filePath,
+      parser: "typescript"
+    });
+  } catch {
+    return source;
+  }
+}
+async function insertDataNuvioIdAtLocation(source, filePath, line, column, id) {
+  if (!isValidNuvioId(id)) {
+    return {
+      ok: false,
+      code: "invalid_id",
+      message: "Id must be segmented lowercase (e.g. page.title)"
+    };
+  }
+  let ast;
+  try {
+    ast = parse3(source, {
+      sourceType: "module",
+      plugins: ["typescript", "jsx"],
+      sourceFilename: filePath
+    });
+  } catch (e) {
+    return { ok: false, code: "parse_error", message: String(e) };
+  }
+  const openingPath = findOpeningAtLocation(ast, line, column);
+  if (!openingPath) {
+    return {
+      ok: false,
+      code: "node_not_found",
+      message: "No JSX element at that source location"
+    };
+  }
+  const opening = openingPath.node;
+  if (hasNuvioIdAttr(opening)) {
+    return {
+      ok: false,
+      code: "already_tagged",
+      message: "Element already has data-nuvio-id"
+    };
+  }
+  if (opening.name.type !== "JSXIdentifier") {
+    return {
+      ok: false,
+      code: "unsupported_tag",
+      message: "Cannot tag dynamic JSX member expressions"
+    };
+  }
+  opening.attributes.push(
+    t5.jsxAttribute(t5.jsxIdentifier("data-nuvio-id"), t5.stringLiteral(id))
+  );
+  const generated = generate2(ast, { retainLines: true }).code;
+  const formatted = await formatSource(generated, filePath);
+  return { ok: true, source: formatted, id };
+}
 export {
+  NUVIO_ID_PATTERN,
   applyPatchToSource,
+  classifyHostClassNameMode,
+  insertDataNuvioIdAtLocation,
+  isValidNuvioId,
   mergeAtBreakpoint,
   parseClassNameByBreakpoint,
+  readFlattenedClassName,
   removeAtBreakpoint,
+  suggestNuvioId,
   validateTailwindFragment
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuvio/ast-engine",
-  "version": "0.5.4",
+  "version": "1.0.0",
   "description": "Nuvio AST patch engine: parse TSX/JSX, apply whitelist Tailwind merges and text edits, format with Prettier.",
   "license": "MIT",
   "repository": {
@@ -41,7 +41,7 @@
     "@babel/types": "^7.26.9",
     "prettier": "^3.5.1",
     "tailwind-merge": "^2.6.0",
-    "@nuvio/shared": "0.5.4"
+    "@nuvio/shared": "1.0.0"
   },
   "devDependencies": {
     "@types/babel__traverse": "^7.20.7",