styled-components-to-stylex-codemod 0.0.18 → 0.0.20

package/README.md

@@ -119,6 +119,30 @@ const adapter = defineAdapter({
     };
   },
 
+  /**
+   * Optional: inline styled(ImportedComponent) into an intrinsic element.
+   * When the base component can be resolved statically, return the target
+   * element, consumed props, and base StyleX declarations. Return undefined
+   * to keep normal styled(Component) behavior.
+   */
+  resolveBaseComponent(ctx) {
+    if (ctx.importSource !== "@company/ui" || ctx.importedName !== "Flex") {
+      return undefined;
+    }
+
+    const sx: Record<string, string> = { display: "flex" };
+    const consumedProps = ["column", "gap", "align"];
+
+    if (ctx.staticProps.column === true) {
+      sx.flexDirection = "column";
+    }
+    if (typeof ctx.staticProps.gap === "number") {
+      sx.gap = `${ctx.staticProps.gap}px`;
+    }
+
+    return { tagName: "div", consumedProps, sx };
+  },
+
   /**
    * Control which exported components accept external className/style
    * and/or polymorphic `as` prop. Return `{ styles, as }` flags.
@@ -168,10 +192,11 @@ Adapters are the main extension point, see full example above. They let you cont
 
 - how theme paths, CSS variables, and imported values are turned into StyleX-compatible JS values (`resolveValue`)
 - what extra imports to inject into transformed files (returned from `resolveValue`)
-- how helper calls are resolved (via `resolveCall({ ... })` returning `{ expr, imports }`; `null`/`undefined` bails the file)
+- how helper calls are resolved (via `resolveCall({ ... })` returning `{ expr, imports }`, or `{ preserveRuntimeCall: true }` to keep only the original helper runtime call; `null`/`undefined` bails the file)
 - which exported components should support external className/style extension and/or polymorphic `as` prop (`externalInterface`)
 - how className/style merging is handled for components accepting external styling (`styleMerger`)
 - which runtime theme hook import/call to use for emitted wrapper theme conditionals (`themeHook`)
+- how `styled(ImportedComponent)` wrapping an external base component can be inlined into an intrinsic element with static StyleX styles (`resolveBaseComponent`)
 
 #### Cross-file selectors (`consumerPaths`)
 
@@ -224,6 +249,50 @@ Troubleshooting prepass failures with `"auto"`:
 - check resolver inputs (import paths, tsconfig path aliases, and related module resolution config)
 - if needed, switch to a manual `externalInterface(ctx)` function to continue migration while you fix prepass inputs
 
+#### Base component resolution (`resolveBaseComponent`)
+
+Use this when you want to **replace a base component entirely** by inlining its styles. If your codebase has a layout primitive like `<Flex>` whose behavior is purely CSS, the codemod can eliminate the runtime import and render a plain `<div>` instead.
+
+The resolver receives `ctx.importSource`, `ctx.importedName`, and `ctx.staticProps` (from `.attrs()` and JSX call sites). Return `{ tagName, consumedProps, sx }` to inline, or `undefined` to skip.
+
+```tsx
+// Input
+const Container = styled(Flex).attrs({ column: true, gap: 16 })`
+  padding: 8px;
+`;
+```
+
+```ts
+// Adapter
+resolveBaseComponent(ctx) {
+  if (ctx.importedName !== "Flex") return undefined;
+  const sx: Record<string, string> = { display: "flex" };
+  if (ctx.staticProps.column === true) sx.flexDirection = "column";
+  if (typeof ctx.staticProps.gap === "number") sx.gap = `${ctx.staticProps.gap}px`;
+  return { tagName: "div", consumedProps: ["column", "gap", "align"], sx };
+},
+```
+
+```tsx
+// Output — Flex is gone, its styles are merged into stylex.create()
+const styles = stylex.create({
+  container: { display: "flex", flexDirection: "column", gap: "16px", padding: "8px" },
+});
+```
+
+If the base component's styles already exist as a `stylex.create()` object, return `mixins` instead of (or alongside) `sx`. The codemod imports the mixin and includes it in `stylex.props(...)`:
+
+```ts
+resolveBaseComponent(ctx) {
+  return {
+    tagName: "div",
+    consumedProps: ["column", "gap"],
+    mixins: [{ importSource: "./lib/mixins.stylex", importName: "mixins", styleKey: "flex" }],
+  };
+},
+// Output: <div {...stylex.props(mixins.flex, styles.container)} />
+```
+
 #### Dynamic interpolations
 
 When the codemod encounters an interpolation inside a styled template literal, it runs an internal dynamic resolution pipeline which covers common cases like:
@@ -235,6 +304,8 @@ When the codemod encounters an interpolation inside a styled template literal, i
   - With `ctx.cssProperty` (e.g., `color: ${helper()}`) → result used as CSS value in `stylex.create()`
   - Without `ctx.cssProperty` (e.g., `${helper()}`) → result used as StyleX styles in `stylex.props()`
   - Use the optional `usage: "create" | "props"` field to override the default inference
+  - Use `preserveRuntimeCall: true` to keep the original helper call as a runtime style-function
+    override (with or without a static fallback from `expr`)
 - if `resolveCall` returns `null` or `undefined`, the transform **bails the file** and logs a warning
 - helper calls applied to prop values (e.g. `shadow(props.shadow)`) by emitting a StyleX style function that calls the helper at runtime
 - conditional CSS blocks via ternary (e.g. `props.$dim ? "opacity: 0.5;" : ""`)

package/dist/{bridge-consumer-patcher-DhMoL4Od.mjs → bridge-consumer-patcher-C2mFaVmd.mjs}

@@ -1,4 +1,4 @@
-import { t as isSelectorContext } from "./selector-context-heuristic-CGwiJ3HL.mjs";
+import { t as isSelectorContext } from "./selector-context-heuristic-Cki9_tTH.mjs";
 import { resolve } from "node:path";
 import { readFileSync, realpathSync } from "node:fs";
 

package/dist/forwarded-as-consumer-patcher-GPnjkzc_.mjs

@@ -0,0 +1,91 @@
+import { n as escapeRegex } from "./string-utils-Dmym5IkG.mjs";
+import { resolve } from "node:path";
+import { readFileSync, realpathSync } from "node:fs";
+
+//#region src/internal/forwarded-as-consumer-patcher.ts
+/**
+* Post-transform consumer patching for `as` → `forwardedAs`.
+*
+* When a component (e.g., `Flex`) is converted from styled-components to StyleX,
+* unconverted consumer files that wrap it with `styled(Flex)` break when using
+* the `as` prop — styled-components intercepts `as` and replaces `Flex` entirely,
+* losing all StyleX styles.
+*
+* `forwardedAs` tells styled-components to pass the prop through to the wrapped
+* component's own `as` prop, preserving StyleX styles.
+*/
+/**
+* Filter prepass consumers to exclude:
+* - consumers that were actually transformed (no longer use styled-components)
+* - entries whose wrapped target bailed and didn't actually transform
+*
+* Returns a map of consumer paths → entries to patch.
+*/
+function buildForwardedAsReplacements(prepassConsumers, transformedFiles) {
+	const result = /* @__PURE__ */ new Map();
+	for (const [consumerPath, entries] of prepassConsumers) {
+		if (transformedFiles.has(toRealPath(consumerPath))) continue;
+		const surviving = entries.filter((e) => transformedFiles.has(e.targetPath));
+		if (surviving.length > 0) result.set(consumerPath, surviving);
+	}
+	return result;
+}
+/**
+* Patch a single consumer file: replace `as` with `forwardedAs` in JSX props
+* and `.attrs()` calls for the given styled wrapper components.
+*
+* Returns the patched source or `null` if no changes were made.
+*/
+function patchConsumerForwardedAs(filePath, entries) {
+	let source;
+	try {
+		source = readFileSync(filePath, "utf-8");
+	} catch {
+		return null;
+	}
+	if (entries.length === 0) return null;
+	let modified = source;
+	for (const { localStyledName } of entries) {
+		modified = patchJsxAsProp(modified, localStyledName);
+		modified = patchAttrsAsProp(modified, localStyledName);
+	}
+	return modified !== source ? modified : null;
+}
+/**
+* Replace `as=` with `forwardedAs=` in JSX tags for the given component name.
+* Handles both `as="span"` and `as={expr}` forms.
+* Skips tags that already contain `forwardedAs`.
+*/
+function patchJsxAsProp(source, componentName) {
+	const tagRegex = new RegExp(`(<${escapeRegex(componentName)}\\b[^<>]*)\\bas(\\s*[={])`, "g");
+	return source.replace(tagRegex, (match, before, after) => {
+		if (before.includes("forwardedAs") || match.includes("forwardedAs")) return match;
+		return `${before}forwardedAs${after}`;
+	});
+}
+/**
+* Replace `as:` with `forwardedAs:` in object-form `.attrs({...})` calls on
+* the styled declaration for the given component name.
+* Only matches object-form `.attrs({ as: ... })`, NOT function-form
+* `.attrs(({ as }) => ...)` where the destructuring param would be incorrectly patched.
+* Skips attrs blocks that already contain `forwardedAs`.
+*/
+function patchAttrsAsProp(source, componentName) {
+	const attrsRegex = new RegExp(`(const\\s+${escapeRegex(componentName)}\\b[^;]*\\.attrs\\s*\\(\\s*\\{[^)]*?)\\bas(\\s*:)`, "g");
+	return source.replace(attrsRegex, (match, before, after) => {
+		if (before.includes("forwardedAs")) return match;
+		return `${before}forwardedAs${after}`;
+	});
+}
+/** Resolve symlinks so paths match the keys in transformedFiles. */
+function toRealPath(filePath) {
+	const resolved = resolve(filePath);
+	try {
+		return realpathSync(resolved);
+	} catch {
+		return resolved;
+	}
+}
+
+//#endregion
+export { buildForwardedAsReplacements, patchConsumerForwardedAs };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as defineAdapter, i as AdapterInput, t as CollectedWarning } from "./logger-vL9nn4Bu.mjs";
+import { a as defineAdapter, i as AdapterInput, t as CollectedWarning } from "./logger-DSmZSMxN.mjs";
 
 //#region src/run.d.ts
 interface RunTransformOptions {

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as assertValidAdapterInput, o as describeValue, r as defineAdapter, t as Logger } from "./logger-Cn8OiPdU.mjs";
+import { a as assertValidAdapterInput, o as describeValue, r as defineAdapter, t as Logger } from "./logger-Bi5-MGBs.mjs";
 import { run } from "jscodeshift/src/Runner.js";
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve } from "node:path";
@@ -106,6 +106,17 @@ async function runTransform(options) {
 			throw e;
 		}
 	};
+	const resolveBaseComponentWithLogging = (ctx) => {
+		if (!adapterInput.resolveBaseComponent) return;
+		try {
+			return adapterInput.resolveBaseComponent(ctx);
+		} catch (e) {
+			const msg = `adapter.resolveBaseComponent threw an error: ${e instanceof Error ? e.message : String(e)}`;
+			Logger.logError(msg, ctx.filePath, void 0, ctx);
+			Logger.markErrorAsLogged(e);
+			throw e;
+		}
+	};
 	const patterns = Array.isArray(files) ? files : [files];
 	const filePaths = [];
 	const cwd = process.cwd();
@@ -130,9 +141,9 @@ async function runTransform(options) {
 		`Pattern(s): ${consumerPatterns.join(", ")}`,
 		"Check that the glob pattern is correct and files exist."
 	].join("\n"));
-	const { createModuleResolver } = await import("./resolve-imports-BDk6Ms09.mjs");
+	const { createModuleResolver } = await import("./resolve-imports-4bFqrkrQ.mjs");
 	const sharedResolver = createModuleResolver();
-	const { runPrepass } = await import("./run-prepass-ByjC18e6.mjs");
+	const { runPrepass } = await import("./run-prepass-BuYfEK4M.mjs");
 	const absoluteFiles = filePaths.map((f) => resolve(f));
 	const absoluteConsumers = consumerFilePaths.map((f) => resolve(f));
 	let prepassResult;
@@ -154,7 +165,8 @@ async function runTransform(options) {
 				componentsNeedingMarkerSidecar: /* @__PURE__ */ new Map(),
 				componentsNeedingGlobalSelectorBridge: /* @__PURE__ */ new Map()
 			},
-			consumerAnalysis: void 0
+			consumerAnalysis: void 0,
+			forwardedAsConsumers: /* @__PURE__ */ new Map()
 		};
 	}
 	const crossFilePrepassResult = prepassResult.crossFileInfo;
@@ -172,7 +184,8 @@ async function runTransform(options) {
 					}
 					return analysisMap.get(`${realPath}:${ctx.componentName}`) ?? {
 						styles: false,
-						as: false
+						as: false,
+						ref: false
 					};
 				}
 			};
@@ -187,7 +200,8 @@ async function runTransform(options) {
 		},
 		resolveValue: resolveValueWithLogging,
 		resolveCall: resolveCallWithLogging,
-		resolveSelector: resolveSelectorWithLogging
+		resolveSelector: resolveSelectorWithLogging,
+		resolveBaseComponent: adapterInput.resolveBaseComponent ? resolveBaseComponentWithLogging : void 0
 	};
 	const transformPath = (() => {
 		const adjacent = join(__dirname, "transform.mjs");
@@ -217,7 +231,7 @@ async function runTransform(options) {
 	});
 	if (sidecarFiles.size > 0 && !dryRun) for (const [sidecarPath, content] of sidecarFiles) await writeFile(sidecarPath, mergeSidecarContent(sidecarPath, content), "utf-8");
 	if (bridgeResults.size > 0 && !dryRun) {
-		const { buildConsumerReplacements, patchConsumerFile } = await import("./bridge-consumer-patcher-DhMoL4Od.mjs");
+		const { buildConsumerReplacements, patchConsumerFile } = await import("./bridge-consumer-patcher-C2mFaVmd.mjs");
 		const consumerReplacements = buildConsumerReplacements(crossFilePrepassResult.selectorUsages, bridgeResults, transformedFiles);
 		const patchedFiles = [];
 		for (const [consumerPath, replacements] of consumerReplacements) {
@@ -229,6 +243,19 @@ async function runTransform(options) {
 		}
 		if (formatterCommands && patchedFiles.length > 0) await runFormatters(formatterCommands, patchedFiles);
 	}
+	if (prepassResult.forwardedAsConsumers.size > 0 && !dryRun) {
+		const { buildForwardedAsReplacements, patchConsumerForwardedAs } = await import("./forwarded-as-consumer-patcher-GPnjkzc_.mjs");
+		const forwardedAsReplacements = buildForwardedAsReplacements(prepassResult.forwardedAsConsumers, transformedFiles);
+		const patchedFiles = [];
+		for (const [consumerPath, entries] of forwardedAsReplacements) {
+			const patched = patchConsumerForwardedAs(consumerPath, entries);
+			if (patched !== null) {
+				await writeFile(consumerPath, patched, "utf-8");
+				patchedFiles.push(consumerPath);
+			}
+		}
+		if (formatterCommands && patchedFiles.length > 0) await runFormatters(formatterCommands, patchedFiles);
+	}
 	if (formatterCommands && formatterCommands.length > 0 && result.ok > 0 && !dryRun) await runFormatters(formatterCommands, filePaths);
 	const report = Logger.createReport();
 	report.print();

package/dist/{logger-Cn8OiPdU.mjs → logger-Bi5-MGBs.mjs}

@@ -35,6 +35,7 @@ function assertAdapterShape(candidate, where, allowAutoExtIf) {
 	const resolveValue = obj?.resolveValue;
 	const resolveCall = obj?.resolveCall;
 	const resolveSelector = obj?.resolveSelector;
+	const resolveBaseComponent = obj?.resolveBaseComponent;
 	const externalInterface = obj?.externalInterface;
 	if (!candidate || typeof candidate !== "object") throw new Error([
 		`${where}: expected an adapter object.`,
@@ -95,6 +96,19 @@ function assertAdapterShape(candidate, where, allowAutoExtIf) {
 		"",
 		`Docs/examples: ${ADAPTER_DOCS_URL}`
 	].join("\n"));
+	if (resolveBaseComponent !== void 0 && typeof resolveBaseComponent !== "function") throw new Error([
+		`${where}: adapter.resolveBaseComponent must be a function when provided.`,
+		`Received: resolveBaseComponent=${describeValue(resolveBaseComponent)}`,
+		"",
+		"Adapter shape:",
+		"  {",
+		"    resolveBaseComponent(context) {",
+		"      return { tagName, consumedProps, sx?, mixins? } | undefined",
+		"    }",
+		"  }",
+		"",
+		`Docs/examples: ${ADAPTER_DOCS_URL}`
+	].join("\n"));
 	if (!(typeof externalInterface === "function" || allowAutoExtIf && externalInterface === "auto")) {
 		const expected = allowAutoExtIf ? "adapter.externalInterface must be a function or \"auto\"." : "adapter.externalInterface must be a function.";
 		throw new Error([`${where}: ${expected}`, `Received: externalInterface=${describeValue(externalInterface)}`].join("\n"));
@@ -215,11 +229,11 @@ const DEFAULT_THEME_HOOK = {
 *
 *     // Configure external interface for exported components
 *     externalInterface(ctx) {
-*       // Example: Enable styles and `as` for shared components folder
+*       // Example: Enable styles, `as`, and `ref` for shared components folder
 *       if (ctx.filePath.includes("/shared/components/")) {
-*         return { styles: true, as: true };
+*         return { styles: true, as: true, ref: true };
 *       }
-*       return { styles: false, as: false };
+*       return { styles: false, as: false, ref: false };
 *     },
 *
 *     // Optional: provide a custom merger, or use `null` for the default verbose merge output

package/dist/{logger-vL9nn4Bu.d.mts → logger-DSmZSMxN.d.mts}

@@ -164,7 +164,7 @@ type ResolveValueResult = {
    */
   usage?: "props";
 };
-type CallResolveResult = {
+type CallResolveResultWithExpr = {
   /**
    * JS expression string to inline into generated output.
    *
@@ -217,7 +217,38 @@ type CallResolveResult = {
    * Example: `"white-space: nowrap; overflow: hidden; text-overflow: ellipsis;"`
    */
   cssText?: string;
+  /**
+   * When true, keeps the original helper call as a runtime style-function override
+   * in addition to the resolved static value.
+   *
+   * This is useful for incremental migrations where you still want to run an
+   * existing runtime helper (for example `ColorConverter.cssWithAlpha(...)`) while
+   * also emitting a static StyleX fallback.
+   *
+   * Behavior notes:
+   * - In `CallResolveResultWithExpr`, `expr`/`imports` are used as a static fallback in
+   *   `stylex.create(...)`.
+   * - In `CallResolveRuntimeOnlyResult`, no static fallback is emitted.
+   * - The runtime override is only emitted for arrow-function helper call interpolations.
+   * - Theme access in the original call is rewritten to use the wrapper `useTheme()` value.
+   */
+  preserveRuntimeCall?: boolean;
+};
+type CallResolveRuntimeOnlyResult = {
+  /**
+   * Keep the original helper call as a runtime style-function override, without
+   * requiring a static fallback expression.
+   *
+   * This mode is only supported for helper calls used as CSS values (not StyleX
+   * style-object references).
+   */
+  preserveRuntimeCall: true;
+  /**
+   * Optional usage hint. Runtime-only results are treated as CSS-value usage.
+   */
+  usage?: "create";
 };
+type CallResolveResult = CallResolveResultWithExpr | CallResolveRuntimeOnlyResult;
 type ImportSource = {
   kind: "absolutePath";
   value: string;
@@ -232,6 +263,48 @@ type ImportSpec = {
     local?: string;
   }>;
 };
+type ResolveBaseComponentStaticValue = string | number | boolean;
+interface ResolveBaseComponentContext {
+  /**
+   * Import source for the wrapped base component.
+   * - package import: "@linear/orbiter/components/Flex"
+   * - relative import: resolved absolute path
+   */
+  importSource: string;
+  /**
+   * Imported binding name for the wrapped base component.
+   * Example: `import { Flex as OrbiterFlex } ...` -> importedName: "Flex"
+   */
+  importedName: string;
+  /**
+   * Static props from `.attrs({...})` and/or JSX call sites.
+   * Includes only literal values that can be resolved at codemod time.
+   */
+  staticProps: Record<string, ResolveBaseComponentStaticValue>;
+  /**
+   * Absolute path of the file currently being transformed.
+   * Useful for resolver logic that branches by caller file.
+   */
+  filePath: string;
+}
+interface ResolveBaseComponentMixinRef {
+  /** Import source for the mixin namespace/object (module specifier or absolute path) */
+  importSource: string;
+  /** Imported binding name for the mixin namespace/object (e.g., "mixins") */
+  importName: string;
+  /** Property key on the imported namespace/object (e.g., "flex") */
+  styleKey: string;
+}
+interface ResolveBaseComponentResult {
+  /** Intrinsic element to render after inlining (e.g., "div", "section") */
+  tagName: string;
+  /** Props consumed by the resolver and stripped from DOM forwarding */
+  consumedProps: string[];
+  /** Base StyleX declarations merged into stylex.create() (camelCase, no shorthands) */
+  sx?: Record<string, string>;
+  /** External StyleX mixin references included in stylex.props(...) */
+  mixins?: ResolveBaseComponentMixinRef[];
+}
 /**
  * Context for `adapter.resolveSelector(...)`.
  *
@@ -319,14 +392,19 @@ interface ExternalInterfaceContext {
 /**
  * Result type for `adapter.externalInterface(...)`.
  *
- * - `{ styles: true, as: false }` → enable className/style support only
- * - `{ styles: true, as: true }` → enable className/style support AND polymorphic `as` prop
- * - `{ styles: false, as: true }` → enable only polymorphic `as` prop (no style merging)
- * - `{ styles: false, as: false }` → no external interface support
+ * - `styles` — accept external className/style props
+ * - `as` — accept polymorphic `as` prop
+ * - `ref` — include `ref` in the component's public type
+ *
+ * Examples:
+ * - `{ styles: true, as: false, ref: false }` → className/style support only
+ * - `{ styles: true, as: true, ref: true }` → full external interface
+ * - `{ styles: false, as: false, ref: false }` → no external interface support
  */
 type ExternalInterfaceResult = {
   styles: boolean;
   as: boolean;
+  ref: boolean;
 };
 /**
  * Configuration for a custom style merger function that combines stylex.props()
@@ -388,6 +466,10 @@ interface Adapter {
    *
    * Return:
    * - `{ expr, imports }` with the resolved expression
+   * - `{ preserveRuntimeCall: true }` to keep only the original runtime helper call
+   *   (no static fallback)
+   * - Optional: add `preserveRuntimeCall: true` to also keep the original helper
+   *   call at runtime as a wrapper style-function override
    * - `undefined` to bail/skip the file
    */
   resolveCall: (context: CallResolveContext) => CallResolveResult | undefined;
@@ -404,14 +486,22 @@ interface Adapter {
    * - `undefined` to bail/skip the file
    */
   resolveSelector: (context: SelectorResolveContext) => SelectorResolveResult | undefined;
+  /**
+   * Optional resolver for inlining `styled(ImportedBase)` components.
+   *
+   * Return:
+   * - `{ tagName, consumedProps, sx?, mixins? }` to inline the base component
+   * - `undefined` to keep normal `styled(Component)` behavior
+   */
+  resolveBaseComponent?: (context: ResolveBaseComponentContext) => ResolveBaseComponentResult | undefined;
   /**
    * Called for exported styled components to determine their external interface.
    *
    * Return:
-   * - `{ styles: false, as: false }` → no external interface
-   * - `{ styles: true, as: false }` → accept className/style props only
-   * - `{ styles: true, as: true }` → accept className/style props AND polymorphic `as` prop
-   * - `{ styles: false, as: true }` → accept only polymorphic `as` prop
+   * - `{ styles: false, as: false, ref: false }` → no external interface
+   * - `{ styles: true, as: false, ref: false }` → accept className/style props only
+   * - `{ styles: true, as: true, ref: true }` → full external interface
+   * - `{ styles: false, as: true, ref: false }` → accept only polymorphic `as` prop
    */
   externalInterface: (context: ExternalInterfaceContext) => ExternalInterfaceResult;
   /**
@@ -424,7 +514,7 @@ interface Adapter {
    * ```typescript
    * function merger(
    *   styles: StyleXStyles | StyleXStyles[],
-   *   className?: string,
+   *   className?: string | (string | undefined | false | null)[],
    *   style?: React.CSSProperties
    * ): { className?: string; style?: React.CSSProperties }
    * ```
@@ -450,6 +540,7 @@ interface AdapterInput {
   resolveValue: Adapter["resolveValue"];
   resolveCall: Adapter["resolveCall"];
   resolveSelector: Adapter["resolveSelector"];
+  resolveBaseComponent?: Adapter["resolveBaseComponent"];
   /**
    * Called for exported styled components to determine their external interface.
    *
@@ -501,11 +592,11 @@ interface AdapterInput {
  *
  *     // Configure external interface for exported components
  *     externalInterface(ctx) {
- *       // Example: Enable styles and `as` for shared components folder
+ *       // Example: Enable styles, `as`, and `ref` for shared components folder
  *       if (ctx.filePath.includes("/shared/components/")) {
- *         return { styles: true, as: true };
+ *         return { styles: true, as: true, ref: true };
  *       }
- *       return { styles: false, as: false };
+ *       return { styles: false, as: false, ref: false };
  *     },
  *
  *     // Optional: provide a custom merger, or use `null` for the default verbose merge output
@@ -522,7 +613,7 @@ declare function defineAdapter<T extends AdapterInput>(adapter: T): T;
 //#endregion
 //#region src/internal/logger.d.ts
 type Severity = "info" | "warning" | "error";
-type WarningType = "`css` helper function switch must return css templates in all branches" | "`css` helper usage as a function call (css(...)) is not supported" | "`css` helper used outside of a styled component template cannot be statically transformed" | "Adapter helper call in border interpolation did not resolve to a single CSS value" | "Adapter resolveCall returned an unparseable styles expression" | "Adapter resolveCall returned an unparseable value expression" | "Adapter resolveCall returned StyleX styles for helper call where a CSS value was expected" | "Adapter resolveCall returned undefined for helper call" | "Adapter resolved StyleX styles cannot be applied under nested selectors/at-rules" | "Adapter resolved StyleX styles inside pseudo selector but did not provide cssText for property expansion — add cssText to resolveCall result to enable pseudo-wrapping" | 'Adapter resolveCall cssText could not be parsed as CSS declarations — expected semicolon-separated property: value pairs (e.g. "white-space: nowrap; overflow: hidden;")' | "Adapter resolveValue returned an unparseable value expression" | "Adapter resolveValue returned undefined for imported value" | "Arrow function: body is not a recognized pattern (expected ternary, logical, call, or member expression)" | "Arrow function: conditional branches could not be resolved to static or theme values" | "Arrow function: helper call body is not supported" | "Arrow function: indexed theme lookup pattern not matched" | "Arrow function: logical expression pattern not supported" | "Arrow function: prop access cannot be converted to style function for this CSS property" | "Arrow function: theme access path could not be resolved" | "Component selectors like `${OtherComponent}:hover &` are not directly representable in StyleX. Manual refactor is required" | "Conditional `css` block: !important is not supported in StyleX" | "Conditional `css` block: @-rules (e.g., @media, @supports) are not supported" | "CSS block contains unsupported at-rule (only @media is supported; @supports, @container, etc. require manual handling)" | "Conditional `css` block: dynamic interpolation could not be resolved to a single component prop" | "Conditional `css` block: failed to parse expression" | "Conditional `css` block: missing CSS property name" | "Conditional `css` block: missing interpolation expression" | "Conditional `css` block: mixed static/dynamic values with non-theme expressions cannot be safely transformed" | "Conditional `css` block: multiple interpolation slots in a single property value" | "Conditional `css` block: ternary branch value could not be resolved (imported values require adapter support)" | "Conditional `css` block: ternary expressions inside pseudo selectors are not supported" | "Conditional `css` block: unsupported selector" | "Directional border helper styles are not supported" | "Multi-slot border interpolation could not be resolved" | "createGlobalStyle is not supported in StyleX. Global styles should be handled separately (e.g., in a CSS file or using CSS reset libraries)" | "Dynamic styles inside pseudo elements (::before/::after) are not supported by StyleX. See https://github.com/facebook/stylex/issues/1396" | "Failed to parse theme expressions" | "Heterogeneous background values (mix of gradients and colors) not currently supported" | "Higher-order styled factory wrappers (e.g. hoc(styled)) are not supported" | "Imported CSS helper mixins: cannot determine inherited properties for correct pseudo selector handling" | "Styled-components specificity hacks like `&&` / `&&&` are not representable in StyleX" | "Theme-dependent block-level conditional could not be fully resolved (branches may contain dynamic interpolations)" | "Theme-dependant call expression could not be resolved (e.g. theme helper calls like theme.highlight() are not supported)" | "Theme value with fallback (props.theme.X ?? / || default) cannot be resolved statically — use adapter.resolveValue to map theme paths to StyleX tokens" | "Theme-dependent nested prop access requires a project-specific theme source (e.g. useTheme())" | "Theme-dependent template literals require a project-specific theme source (e.g. useTheme())" | "Theme prop overrides on styled components are not supported" | "Universal selectors (`*`) are currently unsupported" | "Unsupported call expression (expected imported helper(...) or imported helper(...)(...))" | "Unsupported conditional test in shouldForwardProp" | "Unsupported shouldForwardProp pattern (only !prop.startsWith(), ![].includes(prop), and prop !== are supported)" | "Unsupported interpolation: arrow function" | "Unsupported interpolation: call expression" | "Unsupported interpolation: identifier" | "Unsupported interpolation: member expression" | "Unsupported interpolation: property" | "Unsupported interpolation: unknown" | "Unsupported nested conditional interpolation" | "Unsupported prop-based inline style expression cannot be safely inlined" | "Unsupported prop-based inline style props.theme access is not supported" | "Unsupported selector interpolation: imported value in selector position" | "Unsupported selector: class selector" | "Unsupported selector: comma-separated selectors must all be simple pseudos or pseudo-elements" | "Unsupported selector: descendant pseudo selector (space before pseudo)" | "Unsupported selector: descendant/child/sibling selector" | "Unsupported selector: interpolated pseudo selector" | "Unsupported selector: sibling combinator" | "Unsupported selector: unresolved interpolation in sibling selector" | "Unsupported selector: ambiguous element selector" | "Unsupported selector: attribute selector on unsupported element" | "Unsupported selector: element selector on exported component" | "Unsupported selector: element selector with combined ancestor and child pseudos" | "Unsupported selector: element selector with dynamic children" | "Unsupported selector: element selector with plain intrinsic children" | "Unsupported selector: element selector pseudo collision" | "Unsupported selector: unresolved interpolation in cross-file component selector" | "Unsupported selector: unresolved interpolation in descendant component selector" | "Unsupported selector: unresolved interpolation in element selector" | "Unsupported selector: unresolved interpolation in reverse component selector" | "Unsupported selector: grouped reverse selector references different components" | "Unsupported selector: unknown component selector" | "Unsupported css`` mixin: after-base mixin style is not a plain object" | "Unsupported css`` mixin: nested contextual conditions in after-base mixin" | "Unsupported css`` mixin: cannot infer base default for after-base contextual override (base value is non-literal)" | "css`` helper function interpolation references closure variable that cannot be hoisted" | "Sibling selector broadened: & + & (adjacent) becomes general sibling (~) in StyleX — interleaved non-matching elements will no longer block the match" | "Using styled-components components as mixins is not supported; use css`` mixins or strings instead" | "styled(ImportedComponent) wraps a component whose file contains internal styled-components — convert the base component's file first to avoid CSS cascade conflicts";
+type WarningType = "`css` helper function switch must return css templates in all branches" | "`css` helper usage as a function call (css(...)) is not supported" | "`css` helper used outside of a styled component template cannot be statically transformed" | "Adapter helper call in border interpolation did not resolve to a single CSS value" | "Adapter resolveCall returned an unparseable styles expression" | "Adapter resolveCall returned an unparseable value expression" | "Adapter resolveCall returned StyleX styles for helper call where a CSS value was expected" | "Adapter resolveCall returned undefined for helper call" | "Adapter resolveBaseComponent threw an error" | "Adapter resolved StyleX styles cannot be applied under nested selectors/at-rules" | "Adapter resolved StyleX styles inside pseudo selector but did not provide cssText for property expansion — add cssText to resolveCall result to enable pseudo-wrapping" | 'Adapter resolveCall cssText could not be parsed as CSS declarations — expected semicolon-separated property: value pairs (e.g. "white-space: nowrap; overflow: hidden;")' | "Adapter resolveValue returned an unparseable value expression" | "Adapter resolveValue returned undefined for imported value" | "Arrow function: body is not a recognized pattern (expected ternary, logical, call, or member expression)" | "Arrow function: conditional branches could not be resolved to static or theme values" | "Arrow function: helper call body is not supported" | "Arrow function: indexed theme lookup pattern not matched" | "Arrow function: logical expression pattern not supported" | "Arrow function: prop access cannot be converted to style function for this CSS property" | "Arrow function: theme access path could not be resolved" | "Component selectors like `${OtherComponent}:hover &` are not directly representable in StyleX. Manual refactor is required" | "Conditional `css` block: !important is not supported in StyleX" | "Conditional `css` block: @-rules (e.g., @media, @supports) are not supported" | "CSS block contains unsupported at-rule (only @media and @container are supported; @supports, etc. require manual handling)" | "Conditional `css` block: dynamic interpolation could not be resolved to a single component prop" | "Conditional `css` block: failed to parse expression" | "Conditional `css` block: missing CSS property name" | "Conditional `css` block: missing interpolation expression" | "Conditional `css` block: mixed static/dynamic values with non-theme expressions cannot be safely transformed" | "Conditional `css` block: multiple interpolation slots in a single property value" | "Conditional `css` block: ternary branch value could not be resolved (imported values require adapter support)" | "Conditional `css` block: ternary expressions inside pseudo selectors are not supported" | "Conditional `css` block: unsupported selector" | "Directional border helper styles are not supported" | "Multi-slot border interpolation could not be resolved" | "createGlobalStyle is not supported in StyleX. Global styles should be handled separately (e.g., in a CSS file or using CSS reset libraries)" | "Dynamic styles inside pseudo elements (::before/::after) are not supported by StyleX. See https://github.com/facebook/stylex/issues/1396" | "Failed to parse theme expressions" | "Heterogeneous background values (mix of gradients and colors) not currently supported" | "Higher-order styled factory wrappers (e.g. hoc(styled)) are not supported" | "Imported CSS helper mixins: cannot determine inherited properties for correct pseudo selector handling" | "Local helper function returns CSS that cannot be decomposed into individual properties" | "Local helper function computes CSS values that cannot be statically traced to the component prop" | "Styled-components specificity hacks like `&&` / `&&&` are not representable in StyleX" | "Theme-dependent block-level conditional could not be fully resolved (branches may contain dynamic interpolations)" | "Theme-dependant call expression could not be resolved (e.g. theme helper calls like theme.highlight() are not supported)" | "Theme value with fallback (props.theme.X ?? / || default) cannot be resolved statically — use adapter.resolveValue to map theme paths to StyleX tokens" | "Theme-dependent nested prop access requires a project-specific theme source (e.g. useTheme())" | "Theme-dependent template literals require a project-specific theme source (e.g. useTheme())" | "Theme prop overrides on styled components are not supported" | "Universal selectors (`*`) are currently unsupported" | "Unsupported call expression (expected imported helper(...) or imported helper(...)(...))" | "Unsupported conditional test in shouldForwardProp" | "Unsupported shouldForwardProp pattern (only !prop.startsWith(), ![].includes(prop), and prop !== are supported)" | "Unsupported interpolation: arrow function" | "Unsupported interpolation: call expression" | "Unsupported interpolation: identifier" | "Unsupported interpolation: member expression" | "Unsupported interpolation: property" | "Unsupported interpolation: unknown" | "Unsupported nested conditional interpolation" | "Unsupported prop-based inline style expression cannot be safely inlined" | "Unsupported prop-based inline style props.theme access is not supported" | "Unsupported selector interpolation: imported value in selector position" | "Unsupported selector: class selector" | "Unsupported selector: comma-separated selectors must all be simple pseudos or pseudo-elements" | "Unsupported selector: descendant pseudo selector (space before pseudo)" | "Unsupported selector: descendant/child/sibling selector" | "Unsupported selector: interpolated pseudo selector" | "Unsupported selector: sibling combinator" | "Unsupported selector: unresolved interpolation in sibling selector" | "Unsupported selector: ambiguous element selector" | "Unsupported selector: attribute selector on unsupported element" | "Unsupported selector: element selector on exported component" | "Unsupported selector: element selector with combined ancestor and child pseudos" | "Unsupported selector: element selector with dynamic children" | "Unsupported selector: element selector with plain intrinsic children" | "Unsupported selector: element selector pseudo collision" | "Unsupported selector: unresolved interpolation in cross-file component selector" | "Unsupported selector: unresolved interpolation in descendant component selector" | "Unsupported selector: unresolved interpolation in element selector" | "Unsupported selector: unresolved interpolation in reverse component selector" | "Unsupported selector: grouped reverse selector references different components" | "Unsupported selector: unknown component selector" | "Unsupported css`` mixin: after-base mixin style is not a plain object" | "Unsupported css`` mixin: nested contextual conditions in after-base mixin" | "Unsupported css`` mixin: cannot infer base default for after-base contextual override (base value is non-literal)" | "css`` helper function interpolation references closure variable that cannot be hoisted" | "Sibling selector broadened: & + & (adjacent) becomes general sibling (~) in StyleX — interleaved non-matching elements will no longer block the match" | "Using styled-components components as mixins is not supported; use css`` mixins or strings instead" | "styled(ImportedComponent) wraps a component whose file contains internal styled-components — convert the base component's file first to avoid CSS cascade conflicts";
 interface WarningLog {
   severity: Severity;
   type: WarningType;