@homebound/truss 2.0.0-next.7 → 2.0.0

package/build/plugin/index.js

@@ -5,8 +5,9 @@ import { resolve, dirname, isAbsolute } from "path";
 // src/plugin/transform.ts
 import { parse } from "@babel/parser";
 import _traverse2 from "@babel/traverse";
-import _generate from "@babel/generator";
+import _generate2 from "@babel/generator";
 import * as t4 from "@babel/types";
+import { basename } from "path";
 
 // src/plugin/resolve-chain.ts
 function resolveFullChain(chain, mapping) {
@@ -397,15 +398,32 @@ function resolveDelegateCall(abbr, entry, node, mapping, mediaQuery, pseudoClass
       pseudoElement,
       dynamicProps: targetEntry.props,
       incremented: false,
+      appendPx: true,
       dynamicExtraDefs: targetEntry.extraDefs,
       argNode: argAst
     };
   }
 }
 function resolveAddCall(node, mapping, mediaQuery, pseudoClass, pseudoElement) {
+  if (node.args.length === 1) {
+    const styleArg = node.args[0];
+    if (styleArg.type === "SpreadElement") {
+      throw new UnsupportedPatternError(`add() does not support spread arguments`);
+    }
+    if (styleArg.type === "ObjectExpression") {
+      throw new UnsupportedPatternError(
+        `add(cssProp) does not accept object literals -- pass an existing CssProp expression instead`
+      );
+    }
+    return {
+      key: "__composed_css_prop",
+      defs: {},
+      styleArrayArg: styleArg
+    };
+  }
   if (node.args.length !== 2) {
     throw new UnsupportedPatternError(
-      `add() requires exactly 2 arguments (property name and value), got ${node.args.length}. The add({...}) object overload is not supported -- use add("propName", value) instead`
+      `add() requires exactly 2 arguments (property name and value), got ${node.args.length}. Supported overloads are add(cssProp) and add("propName", value)`
     );
   }
   const propArg = node.args[0];
@@ -512,7 +530,7 @@ function mergeOverlappingConditions(segments) {
   const propToIndices = /* @__PURE__ */ new Map();
   for (let i = 0; i < segments.length; i++) {
     const seg = segments[i];
-    if (seg.dynamicProps || seg.whenPseudo || seg.error) continue;
+    if (seg.dynamicProps || seg.styleArrayArg || seg.whenPseudo || seg.error) continue;
     for (const prop of Object.keys(seg.defs)) {
       if (!propToIndices.has(prop)) propToIndices.set(prop, []);
       propToIndices.get(prop).push(i);
@@ -882,6 +900,39 @@ function insertStylexNamespaceImport(ast, localName) {
   const idx = findLastImportIndex(ast);
   ast.program.body.splice(idx + 1, 0, stylexImport);
 }
+function findNamedImportBinding(ast, source, importedName) {
+  for (const node of ast.program.body) {
+    if (!t.isImportDeclaration(node) || node.source.value !== source) continue;
+    for (const spec of node.specifiers) {
+      if (t.isImportSpecifier(spec) && t.isIdentifier(spec.imported, { name: importedName })) {
+        return spec.local.name;
+      }
+    }
+  }
+  return null;
+}
+function upsertNamedImports(ast, source, imports) {
+  if (imports.length === 0) return;
+  for (const node of ast.program.body) {
+    if (!t.isImportDeclaration(node) || node.source.value !== source) continue;
+    for (const entry of imports) {
+      const exists = node.specifiers.some(function(spec) {
+        return t.isImportSpecifier(spec) && t.isIdentifier(spec.imported, { name: entry.importedName });
+      });
+      if (exists) continue;
+      node.specifiers.push(t.importSpecifier(t.identifier(entry.localName), t.identifier(entry.importedName)));
+    }
+    return;
+  }
+  const importDecl = t.importDeclaration(
+    imports.map(function(entry) {
+      return t.importSpecifier(t.identifier(entry.localName), t.identifier(entry.importedName));
+    }),
+    t.stringLiteral(source)
+  );
+  const idx = findLastImportIndex(ast);
+  ast.program.body.splice(idx + 1, 0, importDecl);
+}
 function extractChain(node, cssBinding) {
   const chain = [];
   let current = node;
@@ -937,6 +988,9 @@ function collectCreateData(chains) {
           collectTypographyLookup(createEntries, runtimeLookups, seg);
           continue;
         }
+        if (seg.styleArrayArg) {
+          continue;
+        }
         if (seg.dynamicProps) {
           if (!createEntries.has(seg.key)) {
             createEntries.set(seg.key, {
@@ -1180,65 +1234,47 @@ function isValidIdentifier(s) {
 
 // src/plugin/rewrite-sites.ts
 import _traverse from "@babel/traverse";
+import _generate from "@babel/generator";
 import * as t3 from "@babel/types";
+var generate = _generate.default ?? _generate;
 var traverse = _traverse.default ?? _traverse;
 function rewriteExpressionSites(options) {
   for (const site of options.sites) {
     const propsArgs = buildPropsArgsFromChain(site.resolvedChain, options);
     const cssAttrPath = getCssAttributePath(site.path);
     if (cssAttrPath) {
-      const propsCall = t3.callExpression(
-        t3.memberExpression(t3.identifier(options.stylexNamespaceName), t3.identifier("props")),
-        propsArgs
+      cssAttrPath.replaceWith(
+        t3.jsxSpreadAttribute(
+          buildCssSpreadExpression(
+            cssAttrPath,
+            propsArgs,
+            site.path.node.loc?.start.line ?? null,
+            options.mergePropsHelperName,
+            options.needsMergePropsHelper,
+            options
+          )
+        )
       );
-      const openingElement = cssAttrPath.parentPath;
-      let existingClassNameExpr = null;
-      if (openingElement && openingElement.isJSXOpeningElement()) {
-        const attrs = openingElement.node.attributes;
-        for (let i = 0; i < attrs.length; i++) {
-          const attr = attrs[i];
-          if (t3.isJSXAttribute(attr) && t3.isJSXIdentifier(attr.name, { name: "className" })) {
-            if (t3.isStringLiteral(attr.value)) {
-              existingClassNameExpr = attr.value;
-            } else if (t3.isJSXExpressionContainer(attr.value) && t3.isExpression(attr.value.expression)) {
-              existingClassNameExpr = attr.value.expression;
-            }
-            attrs.splice(i, 1);
-            break;
-          }
-        }
-      }
-      let spreadExpr;
-      if (existingClassNameExpr) {
-        const rId = t3.identifier("__r");
-        const mergedClassName = t3.callExpression(
-          t3.memberExpression(
-            t3.binaryExpression(
-              "+",
-              t3.binaryExpression("+", existingClassNameExpr, t3.stringLiteral(" ")),
-              t3.logicalExpression("||", t3.memberExpression(rId, t3.identifier("className")), t3.stringLiteral(""))
-            ),
-            t3.identifier("trim")
-          ),
-          []
-        );
-        spreadExpr = t3.callExpression(
-          t3.arrowFunctionExpression(
-            [rId],
-            t3.objectExpression([t3.spreadElement(rId), t3.objectProperty(t3.identifier("className"), mergedClassName)])
-          ),
-          [propsCall]
-        );
-      } else {
-        spreadExpr = propsCall;
-      }
-      cssAttrPath.replaceWith(t3.jsxSpreadAttribute(spreadExpr));
       continue;
     }
-    site.path.replaceWith(t3.arrayExpression(propsArgs));
+    site.path.replaceWith(buildStyleArrayExpression(propsArgs, site.path.node.loc?.start.line ?? null, options));
   }
   rewriteStyleObjectExpressions(options.ast);
-  rewriteCssAttributeExpressions(options.ast, options.stylexNamespaceName);
+  rewriteCssAttributeExpressions(
+    options.ast,
+    options.filename,
+    options.debug,
+    options.stylexNamespaceName,
+    options.mergePropsHelperName,
+    options.needsMergePropsHelper,
+    options.trussPropsHelperName,
+    options.needsTrussPropsHelper,
+    options.trussDebugInfoName,
+    options.needsTrussDebugInfo,
+    options.asStyleArrayHelperName,
+    options.needsAsStyleArrayHelper,
+    options.skippedCssPropMessages
+  );
 }
 function getCssAttributePath(path) {
   const parentPath = path.parentPath;
@@ -1298,6 +1334,18 @@ function buildPropsArgs(segments, options) {
       args.push(t3.spreadElement(t3.logicalExpression("??", lookupAccess, t3.arrayExpression([]))));
       continue;
     }
+    if (seg.styleArrayArg) {
+      args.push(
+        t3.spreadElement(
+          buildUnknownObjectSpreadFallback(
+            seg.styleArrayArg,
+            options.asStyleArrayHelperName,
+            options.needsAsStyleArrayHelper
+          )
+        )
+      );
+      continue;
+    }
     const ref = t3.memberExpression(t3.identifier(options.createVarName), t3.identifier(seg.key));
     if (seg.dynamicProps && seg.argNode) {
       let argExpr;
@@ -1305,6 +1353,12 @@ function buildPropsArgs(segments, options) {
         argExpr = t3.callExpression(t3.identifier(options.maybeIncHelperName), [seg.argNode]);
       } else if (seg.incremented) {
         argExpr = seg.argNode;
+      } else if (seg.appendPx) {
+        argExpr = t3.binaryExpression(
+          "+",
+          t3.callExpression(t3.identifier("String"), [seg.argNode]),
+          t3.stringLiteral("px")
+        );
       } else {
         argExpr = t3.callExpression(t3.identifier("String"), [seg.argNode]);
       }
@@ -1315,25 +1369,165 @@ function buildPropsArgs(segments, options) {
   }
   return args;
 }
-function rewriteCssAttributeExpressions(ast, stylexNamespaceName) {
+function rewriteCssAttributeExpressions(ast, filename, debug, stylexNamespaceName, mergePropsHelperName, needsMergePropsHelper, trussPropsHelperName, needsTrussPropsHelper, trussDebugInfoName, needsTrussDebugInfo, asStyleArrayHelperName, needsAsStyleArrayHelper, skippedCssPropMessages) {
   traverse(ast, {
     JSXAttribute(path) {
       if (!t3.isJSXIdentifier(path.node.name, { name: "css" })) return;
       const value = path.node.value;
       if (!t3.isJSXExpressionContainer(value)) return;
       if (!t3.isExpression(value.expression)) return;
-      const expr = normalizeStyleArrayLikeExpression(value.expression, path, /* @__PURE__ */ new Set());
-      if (!expr) return;
-      const propsArgs = buildStyleArrayLikePropsArgs(expr, path, /* @__PURE__ */ new Set());
-      if (!propsArgs) return;
-      const propsCall = t3.callExpression(
-        t3.memberExpression(t3.identifier(stylexNamespaceName), t3.identifier("props")),
-        propsArgs
+      if (!isCssRewriteableExpression(value.expression, path)) {
+        skippedCssPropMessages.push({
+          message: explainSkippedCssRewrite(value.expression, path),
+          line: path.node.loc?.start.line ?? null
+        });
+        return;
+      }
+      const propsArgs = lowerCssExpressionToPropsArgs(
+        value.expression,
+        path,
+        asStyleArrayHelperName,
+        needsAsStyleArrayHelper
+      );
+      if (!propsArgs) {
+        skippedCssPropMessages.push({
+          message: explainSkippedCssRewrite(value.expression, path),
+          line: path.node.loc?.start.line ?? null
+        });
+        return;
+      }
+      path.replaceWith(
+        t3.jsxSpreadAttribute(
+          buildCssSpreadExpression(
+            path,
+            propsArgs,
+            path.node.loc?.start.line ?? null,
+            mergePropsHelperName,
+            needsMergePropsHelper,
+            {
+              filename,
+              debug,
+              stylexNamespaceName,
+              trussPropsHelperName,
+              needsTrussPropsHelper,
+              trussDebugInfoName,
+              needsTrussDebugInfo
+            }
+          )
+        )
       );
-      path.replaceWith(t3.jsxSpreadAttribute(propsCall));
     }
   });
 }
+function buildStyleArrayExpression(propsArgs, line, options) {
+  const elements = buildDebugElements(line, options);
+  elements.push(...propsArgs);
+  return t3.arrayExpression(elements);
+}
+function buildPropsCall(propsArgs, line, options) {
+  if (!options.debug) {
+    return t3.callExpression(
+      t3.memberExpression(t3.identifier(options.stylexNamespaceName), t3.identifier("props")),
+      propsArgs
+    );
+  }
+  options.needsTrussPropsHelper.current = true;
+  const args = buildDebugElements(line, options);
+  args.push(...propsArgs);
+  return t3.callExpression(t3.identifier(options.trussPropsHelperName), [
+    t3.identifier(options.stylexNamespaceName),
+    ...args
+  ]);
+}
+function buildDebugElements(line, options) {
+  if (!options.debug || line === null) {
+    return [];
+  }
+  options.needsTrussDebugInfo.current = true;
+  return [t3.newExpression(t3.identifier(options.trussDebugInfoName), [t3.stringLiteral(`${options.filename}:${line}`)])];
+}
+function isCssRewriteableExpression(expr, path) {
+  return !!lowerCssExpressionToPropsArgs(expr, path, "asStyleArray", { current: false });
+}
+function lowerCssExpressionToPropsArgs(expr, path, asStyleArrayHelperName, needsAsStyleArrayHelper) {
+  return buildStyleObjectPropsArgs(expr, path, asStyleArrayHelperName, needsAsStyleArrayHelper) ?? buildStyleArrayLikePropsArgsFromExpression(expr, path, asStyleArrayHelperName, needsAsStyleArrayHelper) ?? buildUnknownCssValuePropsArgs(expr, asStyleArrayHelperName, needsAsStyleArrayHelper);
+}
+function explainSkippedCssRewrite(expr, path) {
+  if (t3.isObjectExpression(expr)) {
+    for (const prop of expr.properties) {
+      if (!t3.isSpreadElement(prop)) {
+        return `[truss] Unsupported pattern: Could not rewrite css prop: object contains a non-spread property (${formatNodeSnippet(expr)})`;
+      }
+      const normalizedArg = normalizeStyleArrayLikeExpression(prop.argument, path, /* @__PURE__ */ new Set());
+      if (!normalizedArg) {
+        return `[truss] Unsupported pattern: Could not rewrite css prop: spread argument is not style-array-like (${formatNodeSnippet(prop.argument)})`;
+      }
+    }
+    return `[truss] Unsupported pattern: Could not rewrite css prop: object spread composition was not recognized (${formatNodeSnippet(expr)})`;
+  }
+  return `[truss] Unsupported pattern: Could not rewrite css prop: expression is not style-array-like (${formatNodeSnippet(expr)})`;
+}
+function formatNodeSnippet(node) {
+  return generate(node, { compact: true, comments: true }).code;
+}
+function buildCssSpreadExpression(path, propsArgs, line, mergePropsHelperName, needsMergePropsHelper, options) {
+  const existingClassNameExpr = removeExistingClassNameAttribute(path);
+  if (!existingClassNameExpr) return buildPropsCall(propsArgs, line, options);
+  needsMergePropsHelper.current = true;
+  const args = buildDebugElements(line, options);
+  args.push(...propsArgs);
+  return t3.callExpression(t3.identifier(mergePropsHelperName), [
+    t3.identifier(options.stylexNamespaceName),
+    existingClassNameExpr,
+    ...args
+  ]);
+}
+function removeExistingClassNameAttribute(path) {
+  const openingElement = path.parentPath;
+  if (!openingElement || !openingElement.isJSXOpeningElement()) return null;
+  const attrs = openingElement.node.attributes;
+  for (let i = 0; i < attrs.length; i++) {
+    const attr = attrs[i];
+    if (!t3.isJSXAttribute(attr) || !t3.isJSXIdentifier(attr.name, { name: "className" })) continue;
+    let classNameExpr = null;
+    if (t3.isStringLiteral(attr.value)) {
+      classNameExpr = attr.value;
+    } else if (t3.isJSXExpressionContainer(attr.value) && t3.isExpression(attr.value.expression)) {
+      classNameExpr = attr.value.expression;
+    }
+    attrs.splice(i, 1);
+    return classNameExpr;
+  }
+  return null;
+}
+function buildStyleObjectPropsArgs(expr, path, asStyleArrayHelperName, needsAsStyleArrayHelper) {
+  if (!t3.isObjectExpression(expr) || expr.properties.length === 0) return null;
+  const propsArgs = [];
+  for (const prop of expr.properties) {
+    if (!t3.isSpreadElement(prop)) return null;
+    const normalizedArg = normalizeStyleArrayLikeExpression(prop.argument, path, /* @__PURE__ */ new Set());
+    if (!normalizedArg) {
+      propsArgs.push(
+        t3.spreadElement(
+          buildUnknownObjectSpreadFallback(prop.argument, asStyleArrayHelperName, needsAsStyleArrayHelper)
+        )
+      );
+      continue;
+    }
+    const nestedArgs = buildStyleArrayLikePropsArgs(normalizedArg, path, /* @__PURE__ */ new Set());
+    if (nestedArgs && t3.isArrayExpression(normalizedArg)) {
+      propsArgs.push(...nestedArgs);
+    } else {
+      propsArgs.push(t3.spreadElement(buildSafeSpreadArgument(normalizedArg)));
+    }
+  }
+  return propsArgs.length > 0 ? propsArgs : null;
+}
+function buildStyleArrayLikePropsArgsFromExpression(expr, path, asStyleArrayHelperName, needsAsStyleArrayHelper) {
+  const normalizedExpr = normalizeStyleArrayLikeExpression(expr, path, /* @__PURE__ */ new Set());
+  if (!normalizedExpr) return null;
+  return buildStyleArrayLikePropsArgs(normalizedExpr, path, /* @__PURE__ */ new Set());
+}
 function buildStyleArrayLikePropsArgs(expr, path, seen) {
   if (seen.has(expr)) return null;
   seen.add(expr);
@@ -1351,7 +1545,7 @@ function buildStyleArrayLikePropsArgs(expr, path, seen) {
         if (nestedArgs && t3.isArrayExpression(normalizedArg)) {
           propsArgs.push(...nestedArgs);
         } else {
-          propsArgs.push(t3.spreadElement(normalizedArg));
+          propsArgs.push(t3.spreadElement(buildSafeSpreadArgument(normalizedArg)));
         }
         continue;
       }
@@ -1359,11 +1553,15 @@ function buildStyleArrayLikePropsArgs(expr, path, seen) {
     }
     return propsArgs;
   }
-  if (t3.isIdentifier(expr) || t3.isMemberExpression(expr) || t3.isConditionalExpression(expr)) {
-    return [t3.spreadElement(expr)];
+  if (t3.isIdentifier(expr) || t3.isMemberExpression(expr) || t3.isConditionalExpression(expr) || t3.isLogicalExpression(expr) || t3.isCallExpression(expr)) {
+    return [t3.spreadElement(buildSafeSpreadArgument(expr))];
   }
   return null;
 }
+function buildUnknownCssValuePropsArgs(expr, asStyleArrayHelperName, needsAsStyleArrayHelper) {
+  if (!(t3.isIdentifier(expr) || t3.isMemberExpression(expr) || t3.isCallExpression(expr))) return null;
+  return [t3.spreadElement(buildUnknownObjectSpreadFallback(expr, asStyleArrayHelperName, needsAsStyleArrayHelper))];
+}
 function rewriteStyleObjectExpressions(ast) {
   traverse(ast, {
     ObjectExpression(path) {
@@ -1388,16 +1586,17 @@ function tryBuildStyleArrayFromObject(path) {
       // I.e. `...Css.df.$`, `...(cond ? Css.df.$ : {})`, or `...styles.wrapper`
     );
     if (!normalizedArg) {
-      return null;
+      elements.push(t3.spreadElement(buildInlineAsStyleArrayExpression(prop.argument)));
+      continue;
     }
-    if (isStyleArrayLike(normalizedArg, path, /* @__PURE__ */ new Set())) {
+    if (isKnownStyleArrayLike(normalizedArg, path, /* @__PURE__ */ new Set())) {
       sawStyleArray = true;
     }
     if (t3.isArrayExpression(normalizedArg)) {
       elements.push(...normalizedArg.elements);
       continue;
     }
-    elements.push(t3.spreadElement(normalizedArg));
+    elements.push(t3.spreadElement(buildSafeSpreadArgument(normalizedArg)));
   }
   if (!sawStyleArray) return null;
   return t3.arrayExpression(elements);
@@ -1406,13 +1605,24 @@ function normalizeStyleArrayLikeExpression(expr, path, seen) {
   if (seen.has(expr)) return null;
   seen.add(expr);
   if (t3.isArrayExpression(expr)) return expr;
+  if (t3.isLogicalExpression(expr) && expr.operator === "&&") {
+    const consequent = normalizeStyleArrayLikeExpression(expr.right, path, seen);
+    if (!consequent) return null;
+    return t3.conditionalExpression(expr.left, consequent, t3.arrayExpression([]));
+  }
+  if (t3.isLogicalExpression(expr) && (expr.operator === "||" || expr.operator === "??")) {
+    const left = normalizeStyleArrayLikeExpression(expr.left, path, seen);
+    const right = normalizeStyleArrayLikeBranch(expr.right, path, seen);
+    if (!left || !right) return null;
+    return t3.logicalExpression(expr.operator, left, right);
+  }
   if (t3.isConditionalExpression(expr)) {
     const consequent = normalizeStyleArrayLikeBranch(expr.consequent, path, seen);
     const alternate = normalizeStyleArrayLikeBranch(expr.alternate, path, seen);
     if (!consequent || !alternate) return null;
     return t3.conditionalExpression(expr.test, consequent, alternate);
   }
-  if (t3.isIdentifier(expr) || t3.isMemberExpression(expr)) {
+  if (t3.isIdentifier(expr) || t3.isMemberExpression(expr) || t3.isCallExpression(expr)) {
     const nestedSeen = new Set(seen);
     nestedSeen.delete(expr);
     if (isStyleArrayLike(expr, path, nestedSeen)) return expr;
@@ -1429,6 +1639,12 @@ function isStyleArrayLike(expr, path, seen) {
   if (seen.has(expr)) return false;
   seen.add(expr);
   if (t3.isArrayExpression(expr)) return true;
+  if (t3.isLogicalExpression(expr) && expr.operator === "&&") {
+    return isStyleArrayLike(expr.right, path, seen);
+  }
+  if (t3.isLogicalExpression(expr) && (expr.operator === "||" || expr.operator === "??")) {
+    return isStyleArrayLike(expr.left, path, seen) && isStyleArrayLikeBranch(expr.right, path, seen);
+  }
   if (t3.isConditionalExpression(expr)) {
     return isStyleArrayLikeBranch(expr.consequent, path, seen) && isStyleArrayLikeBranch(expr.alternate, path, seen);
   }
@@ -1439,7 +1655,11 @@ function isStyleArrayLike(expr, path, seen) {
     const init = bindingPath.node.init;
     return !!(init && isStyleArrayLike(init, bindingPath, seen));
   }
-  if (t3.isMemberExpression(expr) && !expr.computed && t3.isIdentifier(expr.property)) {
+  if (t3.isCallExpression(expr)) {
+    const returnExpr = getCallStyleArrayLikeExpression(expr, path);
+    return returnExpr ? isStyleArrayLike(returnExpr, path, seen) : true;
+  }
+  if (t3.isMemberExpression(expr)) {
     const object = expr.object;
     if (!t3.isIdentifier(object)) return false;
     const binding = path.scope.getBinding(object.name);
@@ -1447,7 +1667,8 @@ function isStyleArrayLike(expr, path, seen) {
     if (!bindingPath || !bindingPath.isVariableDeclarator()) return false;
     const init = bindingPath.node.init;
     if (!init || !t3.isObjectExpression(init)) return false;
-    const propertyName = expr.property.name;
+    const propertyName = getStaticMemberPropertyName(expr, path);
+    if (!propertyName) return false;
     for (const prop of init.properties) {
       if (!t3.isObjectProperty(prop) || prop.computed) continue;
       if (!isMatchingPropertyName(prop.key, propertyName)) continue;
@@ -1457,6 +1678,49 @@ function isStyleArrayLike(expr, path, seen) {
   }
   return false;
 }
+function isKnownStyleArrayLike(expr, path, seen) {
+  if (seen.has(expr)) return false;
+  seen.add(expr);
+  if (t3.isArrayExpression(expr)) return true;
+  if (t3.isLogicalExpression(expr) && expr.operator === "&&") {
+    return isKnownStyleArrayLike(expr.right, path, seen);
+  }
+  if (t3.isLogicalExpression(expr) && (expr.operator === "||" || expr.operator === "??")) {
+    return isKnownStyleArrayLike(expr.left, path, seen) && isStyleArrayLikeBranch(expr.right, path, seen);
+  }
+  if (t3.isConditionalExpression(expr)) {
+    return isStyleArrayLikeBranch(expr.consequent, path, seen) && isStyleArrayLikeBranch(expr.alternate, path, seen);
+  }
+  if (t3.isIdentifier(expr)) {
+    const binding = path.scope.getBinding(expr.name);
+    const bindingPath = binding?.path;
+    if (!bindingPath || !bindingPath.isVariableDeclarator()) return false;
+    const init = bindingPath.node.init;
+    return !!(init && isKnownStyleArrayLike(init, bindingPath, seen));
+  }
+  if (t3.isCallExpression(expr)) {
+    const returnExpr = getCallStyleArrayLikeExpression(expr, path);
+    return !!(returnExpr && isKnownStyleArrayLike(returnExpr, path, seen));
+  }
+  if (t3.isMemberExpression(expr)) {
+    const object = expr.object;
+    if (!t3.isIdentifier(object)) return false;
+    const binding = path.scope.getBinding(object.name);
+    const bindingPath = binding?.path;
+    if (!bindingPath || !bindingPath.isVariableDeclarator()) return false;
+    const init = bindingPath.node.init;
+    if (!init || !t3.isObjectExpression(init)) return false;
+    const propertyName = getStaticMemberPropertyName(expr, path);
+    if (!propertyName) return false;
+    for (const prop of init.properties) {
+      if (!t3.isObjectProperty(prop) || prop.computed) continue;
+      if (!isMatchingPropertyName(prop.key, propertyName)) continue;
+      const value = prop.value;
+      return t3.isExpression(value) && isKnownStyleArrayLike(value, bindingPath, seen);
+    }
+  }
+  return false;
+}
 function isStyleArrayLikeBranch(expr, path, seen) {
   return isEmptyObjectExpression(expr) || isStyleArrayLike(expr, path, seen);
 }
@@ -1466,11 +1730,74 @@ function isMatchingPropertyName(key, name) {
 function isEmptyObjectExpression(expr) {
   return t3.isObjectExpression(expr) && expr.properties.length === 0;
 }
+function buildUnknownObjectSpreadFallback(expr, asStyleArrayHelperName, needsAsStyleArrayHelper) {
+  needsAsStyleArrayHelper.current = true;
+  return t3.callExpression(t3.identifier(asStyleArrayHelperName), [expr]);
+}
+function buildInlineAsStyleArrayExpression(expr) {
+  return t3.conditionalExpression(
+    t3.callExpression(t3.memberExpression(t3.identifier("Array"), t3.identifier("isArray")), [expr]),
+    expr,
+    t3.conditionalExpression(expr, t3.arrayExpression([expr]), t3.arrayExpression([]))
+  );
+}
+function buildSafeSpreadArgument(expr) {
+  return t3.isConditionalExpression(expr) || t3.isLogicalExpression(expr) ? t3.parenthesizedExpression(expr) : expr;
+}
+function getStaticMemberPropertyName(expr, path) {
+  if (!expr.computed && t3.isIdentifier(expr.property)) {
+    return expr.property.name;
+  }
+  if (t3.isStringLiteral(expr.property)) {
+    return expr.property.value;
+  }
+  if (t3.isIdentifier(expr.property)) {
+    const binding = path.scope.getBinding(expr.property.name);
+    const bindingPath = binding?.path;
+    if (!bindingPath || !bindingPath.isVariableDeclarator()) return null;
+    const init = bindingPath.node.init;
+    return t3.isStringLiteral(init) ? init.value : null;
+  }
+  return null;
+}
+function getCallStyleArrayLikeExpression(expr, path) {
+  const localReturnExpr = getLocalFunctionReturnExpression(expr, path);
+  if (localReturnExpr) return localReturnExpr;
+  const firstArg = expr.arguments[0];
+  if (firstArg && !t3.isSpreadElement(firstArg) && (t3.isArrowFunctionExpression(firstArg) || t3.isFunctionExpression(firstArg))) {
+    return getFunctionLikeReturnExpression(firstArg);
+  }
+  return null;
+}
+function getLocalFunctionReturnExpression(expr, path) {
+  if (!t3.isIdentifier(expr.callee)) return null;
+  const binding = path.scope.getBinding(expr.callee.name);
+  const bindingPath = binding?.path;
+  if (!bindingPath) return null;
+  if (bindingPath.isFunctionDeclaration()) {
+    return getFunctionLikeReturnExpression(bindingPath.node);
+  }
+  if (bindingPath.isVariableDeclarator()) {
+    const init = bindingPath.node.init;
+    if (init && (t3.isArrowFunctionExpression(init) || t3.isFunctionExpression(init))) {
+      return getFunctionLikeReturnExpression(init);
+    }
+  }
+  return null;
+}
+function getFunctionLikeReturnExpression(fn) {
+  if (t3.isExpression(fn.body)) {
+    return fn.body;
+  }
+  if (fn.body.body.length !== 1) return null;
+  const stmt = fn.body.body[0];
+  return t3.isReturnStatement(stmt) && stmt.argument && t3.isExpression(stmt.argument) ? stmt.argument : null;
+}
 
 // src/plugin/transform.ts
 var traverse2 = _traverse2.default ?? _traverse2;
-var generate = _generate.default ?? _generate;
-function transformTruss(code, filename, mapping) {
+var generate2 = _generate2.default ?? _generate2;
+function transformTruss(code, filename, mapping, options = {}) {
   if (!code.includes("Css")) return null;
   const ast = parse(code, {
     sourceType: "module",
@@ -1506,6 +1833,18 @@ function transformTruss(code, filename, mapping) {
   const stylexNamespaceName = existingStylexNamespace ?? reservePreferredName(usedTopLevelNames, "stylex");
   const createVarName = reservePreferredName(usedTopLevelNames, "css", "css_");
   const maybeIncHelperName = needsMaybeInc ? reservePreferredName(usedTopLevelNames, "__maybeInc") : null;
+  const existingMergePropsHelperName = findNamedImportBinding(ast, "@homebound/truss/runtime", "mergeProps");
+  const mergePropsHelperName = existingMergePropsHelperName ?? reservePreferredName(usedTopLevelNames, "mergeProps");
+  const needsMergePropsHelper = { current: false };
+  const existingAsStyleArrayHelperName = findNamedImportBinding(ast, "@homebound/truss/runtime", "asStyleArray");
+  const asStyleArrayHelperName = existingAsStyleArrayHelperName ?? reservePreferredName(usedTopLevelNames, "asStyleArray");
+  const needsAsStyleArrayHelper = { current: false };
+  const existingTrussPropsHelperName = findNamedImportBinding(ast, "@homebound/truss/runtime", "trussProps");
+  const trussPropsHelperName = existingTrussPropsHelperName ?? reservePreferredName(usedTopLevelNames, "trussProps");
+  const needsTrussPropsHelper = { current: false };
+  const existingTrussDebugInfoName = findNamedImportBinding(ast, "@homebound/truss/runtime", "TrussDebugInfo");
+  const trussDebugInfoName = existingTrussDebugInfoName ?? reservePreferredName(usedTopLevelNames, "TrussDebugInfo");
+  const needsTrussDebugInfo = { current: false };
   const runtimeLookupNames = /* @__PURE__ */ new Map();
   for (const [lookupKey] of runtimeLookups) {
     runtimeLookupNames.set(lookupKey, reservePreferredName(usedTopLevelNames, `__${lookupKey}`));
@@ -1514,15 +1853,42 @@ function transformTruss(code, filename, mapping) {
   rewriteExpressionSites({
     ast,
     sites,
+    filename: basename(filename),
+    debug: options.debug ?? false,
     createVarName,
     stylexNamespaceName,
     maybeIncHelperName,
+    mergePropsHelperName,
+    needsMergePropsHelper,
+    trussPropsHelperName,
+    needsTrussPropsHelper,
+    trussDebugInfoName,
+    needsTrussDebugInfo,
+    asStyleArrayHelperName,
+    needsAsStyleArrayHelper,
+    skippedCssPropMessages: errorMessages,
     runtimeLookupNames
   });
   removeCssImport(ast, cssBindingName);
   if (!findStylexNamespaceImport(ast)) {
     insertStylexNamespaceImport(ast, stylexNamespaceName);
   }
+  if (needsMergePropsHelper.current || needsAsStyleArrayHelper.current || needsTrussPropsHelper.current || needsTrussDebugInfo.current) {
+    const runtimeImports = [];
+    if (needsMergePropsHelper.current) {
+      runtimeImports.push({ importedName: "mergeProps", localName: mergePropsHelperName });
+    }
+    if (needsAsStyleArrayHelper.current) {
+      runtimeImports.push({ importedName: "asStyleArray", localName: asStyleArrayHelperName });
+    }
+    if (needsTrussPropsHelper.current) {
+      runtimeImports.push({ importedName: "trussProps", localName: trussPropsHelperName });
+    }
+    if (needsTrussDebugInfo.current) {
+      runtimeImports.push({ importedName: "TrussDebugInfo", localName: trussDebugInfoName });
+    }
+    upsertNamedImports(ast, "@homebound/truss/runtime", runtimeImports);
+  }
   const markerVarNames = collectReferencedMarkerNames(createEntries);
   const hoistedMarkerDecls = hoistMarkerDeclarations(ast, markerVarNames);
   const declarationsToInsert = [];
@@ -1549,10 +1915,12 @@ function transformTruss(code, filename, mapping) {
     declarationsToInsert.push(consoleError);
   }
   if (declarationsToInsert.length > 0) {
-    const insertIndex = findLastImportIndex(ast) + 1;
-    ast.program.body.splice(insertIndex, 0, ...declarationsToInsert);
+    const insertIndex = ast.program.body.findIndex(function(node) {
+      return !t4.isImportDeclaration(node);
+    });
+    ast.program.body.splice(insertIndex === -1 ? ast.program.body.length : insertIndex, 0, ...declarationsToInsert);
   }
-  const output = generate(ast, {
+  const output = generate2(ast, {
     sourceFileName: filename,
     retainLines: false
   });
@@ -1770,6 +2138,9 @@ function resolveCssExpression(node, cssBindingName, mapping, filename) {
       if (seg.typographyLookup) {
         return { error: `typography() with a runtime key is not supported in .css.ts files` };
       }
+      if (seg.styleArrayArg) {
+        return { error: `add(cssProp) is not supported in .css.ts files` };
+      }
       if (seg.mediaQuery) {
         return { error: `media query modifiers (ifSm, ifMd, etc.) are not supported in .css.ts files` };
       }
@@ -1808,9 +2179,9 @@ ${body}
 
 // src/plugin/rewrite-css-ts-imports.ts
 import { parse as parse3 } from "@babel/parser";
-import _generate2 from "@babel/generator";
+import _generate3 from "@babel/generator";
 import * as t7 from "@babel/types";
-var generate2 = _generate2.default ?? _generate2;
+var generate3 = _generate3.default ?? _generate3;
 function rewriteCssTsImports(code, filename) {
   if (!code.includes(".css.ts")) {
     return { code, changed: false };
@@ -1848,7 +2219,7 @@ function rewriteCssTsImports(code, filename) {
     const insertIndex = findLastImportIndex(ast) + 1;
     ast.program.body.splice(insertIndex, 0, ...sideEffectImports);
   }
-  const output = generate2(ast, {
+  const output = generate3(ast, {
     sourceFileName: filename,
     retainLines: false
   });
@@ -1864,6 +2235,7 @@ var CSS_TS_QUERY = "?truss-css";
 function trussPlugin(opts) {
   let mapping = null;
   let projectRoot;
+  let debug = false;
   const externalPackages = opts.externalPackages ?? [];
   function mappingPath() {
     return resolve(projectRoot || process.cwd(), opts.mapping);
@@ -1879,6 +2251,7 @@ function trussPlugin(opts) {
     enforce: "pre",
     configResolved(config) {
       projectRoot = config.root;
+      debug = config.command === "serve" || config.mode === "development" || config.mode === "test";
     },
     buildStart() {
       ensureMapping();
@@ -1911,7 +2284,7 @@ function trussPlugin(opts) {
       if (!hasCssDsl) {
         return { code: rewrittenCode, map: null };
       }
-      const result = transformTruss(rewrittenCode, id, ensureMapping());
+      const result = transformTruss(rewrittenCode, fileId, ensureMapping(), { debug });
       if (!result) {
         if (!rewrittenImports.changed) return null;
         return { code: rewrittenCode, map: null };