fix(ui): keep @clerk/headless out of the published mosaic export

The experimental subpath pointed at `src/mosaic/styles`, which is the StyleX
build barrel: it pulls every migrated component into the graph so one stylesheet
can be extracted. Publishing it made all of those components, and the headless
primitive types behind them, part of the API. Give the export its own narrow
entry instead.

`@clerk/headless` is private, so leaving it external published a dependency that
404s on install. Bundling it broke differently: the declaration builder cannot
follow the re-export chains in its emitted `dist/*.d.ts`. Correct the
`tsconfig.mosaic.json` paths so it resolves to source (primitives live under
`src/primitives`, so the old wildcard missed menu, popover, dialog and tabs and
silently fell back to `dist`).

StyleX moves to devDependencies and gets bundled: it compiles away at build
time, so consumers should not inherit our version.

Author: alexcarpenter

packages/ui/package.json

@@ -113,7 +113,6 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@clerk/headless": "workspace:^",
     "@clerk/localizations": "workspace:^",
     "@clerk/shared": "workspace:^",
     "@emotion/cache": "11.11.0",
@@ -123,7 +122,6 @@
     "@solana/wallet-adapter-base": "catalog:module-manager",
     "@solana/wallet-adapter-react": "catalog:module-manager",
     "@solana/wallet-standard": "catalog:module-manager",
-    "@stylexjs/stylex": "0.19.0",
     "@swc/helpers": "catalog:repo",
     "copy-to-clipboard": "3.3.3",
     "core-js": "catalog:repo",
@@ -133,6 +131,7 @@
     "qrcode.react": "4.2.0"
   },
   "devDependencies": {
+    "@clerk/headless": "workspace:^",
     "@floating-ui/react-dom": "^2.1.8",
     "@rsdoctor/rspack-plugin": "^1.5.9",
     "@rspack/cli": "catalog:rspack",
@@ -141,6 +140,7 @@
     "@rspack/plugin-react-refresh": "catalog:rspack",
     "@stylexjs/eslint-plugin": "0.19.0",
     "@stylexjs/rollup-plugin": "0.19.0",
+    "@stylexjs/stylex": "0.19.0",
     "@stylexjs/unplugin": "0.19.0",
     "@svgr/rollup": "^8.1.0",
     "@svgr/webpack": "^6.5.1",

packages/ui/src/mosaic/components/menu/index.ts

@@ -1,2 +1,2 @@
 export { Menu, MenuContent, MenuItem, MenuSeparator, MenuTrigger } from './menu';
-export type { MenuContentProps, MenuItemProps, MenuProps, MenuSeparatorProps, MenuTriggerProps } from './menu';
+export type { MenuContentProps, MenuItemProps, MenuTriggerProps } from './menu';

packages/ui/src/mosaic/components/menu/menu.tsx

@@ -2,7 +2,6 @@ import type {
   MenuItemProps as PrimitiveMenuItemProps,
   MenuPopupProps,
   MenuPortalProps,
-  MenuProps,
   MenuSeparatorProps,
 } from '@clerk/headless/menu';
 import { Menu as Primitive } from '@clerk/headless/menu';
@@ -16,8 +15,6 @@ import { Icon } from '../icon';
 import { reset } from '../reset.styles';
 import { styles } from './menu.styles';
 
-export type { MenuProps, MenuSeparatorProps };
-
 export type MenuTriggerProps = MosaicComponentProps<'button'>;
 
 /**

packages/ui/src/mosaic/components/popover/index.ts

@@ -3,7 +3,6 @@ export type {
   PopoverCloseProps,
   PopoverDescriptionProps,
   PopoverPopupProps,
-  PopoverRootProps,
   PopoverSize,
   PopoverTitleProps,
   PopoverTriggerProps,

packages/ui/src/mosaic/components/popover/popover.tsx

@@ -1,4 +1,3 @@
-import type { PopoverProps as HeadlessPopoverProps } from '@clerk/headless/popover';
 import { Popover as Primitive } from '@clerk/headless/popover';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
@@ -10,8 +9,6 @@ import { sizes, styles } from './popover.styles';
 
 export type PopoverSize = 'sm' | 'md' | 'lg';
 
-export type PopoverRootProps = HeadlessPopoverProps;
-
 /**
  * The headless parts type their props (and the `render` callback's argument) against
  * the raw tag props, which carry the non-standard HTML `color` attribute typed

packages/ui/src/mosaic/index.ts

@@ -0,0 +1,7 @@
+// Public entry for `@clerk/ui/experimental/mosaic`. The side-effect import keeps every migrated
+// component in the StyleX graph so the emitted `styles.css` stays complete, without making them API:
+// `./styles` is the build barrel, and re-exporting it would publish the headless primitive types too.
+import './styles';
+
+export { UserButton } from './user-button/user-button';
+export type { UserButtonProps } from './user-button/user-button';

packages/ui/src/mosaic/styles/index.ts

@@ -24,13 +24,7 @@ export type { IconProps } from '../components/icon';
 export { Item } from '../components/item';
 export type { ItemProps } from '../components/item';
 export { Menu } from '../components/menu';
-export type {
-  MenuContentProps,
-  MenuItemProps,
-  MenuProps,
-  MenuSeparatorProps,
-  MenuTriggerProps,
-} from '../components/menu';
+export type { MenuContentProps, MenuItemProps, MenuTriggerProps } from '../components/menu';
 export { scrollAreaRoot, scrollAreaVars, scrollAreaViewport } from '../components/scroll-area';
 export type { ScrollAreaGutter } from '../components/scroll-area';
 export { Spinner } from '../components/spinner';
@@ -43,7 +37,6 @@ export type {
   PopoverCloseProps,
   PopoverDescriptionProps,
   PopoverPopupProps,
-  PopoverRootProps,
   PopoverSize,
   PopoverTitleProps,
   PopoverTriggerProps,

packages/ui/tsconfig.mosaic.json

@@ -7,8 +7,10 @@
       // declaration bundle. Its published `dist/*.d.ts` are re-export barrels that
       // rolldown-plugin-dts can't follow when inlining, so building types against source
       // (the monorepo default) lets Mosaic components import headless types directly.
+      // `utils` and `hooks` sit at the source root; every other subpath is a primitive.
       "@clerk/headless/utils": ["../headless/src/utils/index.ts"],
-      "@clerk/headless/*": ["../headless/src/*"],
+      "@clerk/headless/hooks": ["../headless/src/hooks/index.ts"],
+      "@clerk/headless/*": ["../headless/src/primitives/*"],
       // Preserve the base config's test-only aliases (extends replaces `paths` wholesale).
       "@/core/*": ["../clerk-js/src/core/*"],
       "@/*": ["./src/*"],

packages/ui/tsdown.mosaic.config.mts

@@ -2,17 +2,20 @@ import stylexPlugin from '@stylexjs/rollup-plugin';
 import { defineConfig } from 'tsdown';
 import { mosaicLightningCssTargets } from './stylex-lightningcss.config.mjs';
 
-// Isolated Mosaic build: compiles ONLY the StyleX barrel (`src/mosaic/styles`)
-// with the StyleX rollup plugin, emitting transformed ESM + a single static
-// `styles.css` that consumers import. Kept separate from the main tsdown build so
-// the Emotion-based code is untouched and this entry stays Emotion-free.
+// Isolated Mosaic build: compiles `src/mosaic` with the StyleX rollup plugin, emitting transformed
+// ESM + a single static `styles.css` that consumers import. Kept separate from the main tsdown build
+// so the Emotion-based code is untouched and this entry stays Emotion-free.
+//
+// The entry is the narrow public surface, not the `src/mosaic/styles` barrel: the barrel exists to
+// pull every migrated component into the StyleX graph, and pointing the published export at it would
+// make all of them (and the headless primitive types behind them) API.
 //
 // `useCSSLayers` wraps StyleX's atomic rules in `@layer priorityN` for correct
 // intra-StyleX precedence; consumers import the sheet into a layer they control
 // (`@import '@clerk/ui/experimental/mosaic/styles.css' layer(components)`), under which those nest
 // cleanly, and override from a later layer.
 export default defineConfig({
-  entry: ['./src/mosaic/styles/index.ts'],
+  entry: ['./src/mosaic/index.ts'],
   outDir: './dist-mosaic',
   format: ['esm'],
   dts: true,
@@ -22,10 +25,21 @@ export default defineConfig({
   minify: false,
   // Use the standard React JSX runtime, not Emotion's — the Mosaic build must be Emotion-free.
   tsconfig: './tsconfig.mosaic.json',
-  // `@clerk/headless` stays external here (the main build inlines it): this entry exists to
-  // extract `styles.css`, and only that file is exported from the package — so there is nothing
-  // to gain from pulling the primitives and their deps into a bundle nobody imports.
-  external: ['react', 'react-dom', '@stylexjs/stylex', /^@clerk\/headless/],
+  // tsdown externalizes everything in `dependencies` by default, which is what we want for
+  // `@clerk/shared`: it carries the Clerk context, so the host's copy has to be the one we read.
+  // The two below have to override that default.
+  //
+  // `@clerk/headless` is a private workspace package. Left external, `@clerk/ui` publishes with a
+  // dependency that does not exist on npm, and installing it 404s. `tsconfig.mosaic.json` already
+  // resolves it to source, so this is the backstop: if a subpath ever escapes those `paths`, the
+  // build fails loudly here instead of silently externalizing an unpublishable package.
+  //
+  // StyleX is compiled away at build time; only the tiny `props` merger survives. Bundling it keeps
+  // it out of consumer trees entirely, so nobody inherits our StyleX version or has to have it.
+  deps: {
+    neverBundle: ['react', 'react-dom'],
+    alwaysBundle: [/^@clerk\/headless/, '@stylexjs/stylex'],
+  },
   // The bundle collapses every module into one, so the per-file `'use client'` directives are lost.
   // Everything here is interactive and hook-driven, so the entry is a client boundary in whole —
   // without this, importing it from a React Server Component fails.