t3st

.changeset/backend-relative-support-link.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Use a root-relative link (`/contact/support`) for the `passwordHasher` "contact support" reference so the generated API reference renders it as an internal same-tab link instead of an external one.

.claude/skills/mosaic/SKILL.md

@@ -46,6 +46,7 @@ this skill is the _how-to_.
 | -------------------------------------------------------------------- | ------------------------------------------------------ |
 | Building on / authoring a headless primitive (`@clerk/headless`)     | `references/headless.md`                               |
 | Styling a component with StyleX (tokens, `stylex.create`, CSS build) | `references/stylex.md`                                 |
+| Building an enter/exit transition, or any motion that reads as wrong | `references/motion.md`                                 |
 | Styling a component the legacy way (slot recipes, `useRecipe`)       | `references/styling.md`                                |
 | Authoring or debugging a state machine, or wiring one to React       | `references/machines.md` → in-tree `machine/README.md` |
 | Writing the controller (Clerk adapter, permissions, revalidate)      | `references/controllers.md`                            |

.claude/skills/mosaic/references/stylex.md

@@ -295,6 +295,28 @@ device, while touch devices look correct.
   then grep `dist-mosaic/styles.css` for the two selectors and compare their
   specificity.
 
+- **A button that opens something takes the pressed fill while open**, so a
+  disclosure trigger stays visibly engaged for as long as its surface is. Disclosure
+  primitives already set `data-open` on the trigger (`popover-trigger.tsx` and
+  friends), so this is styling-only — no headless change. It needs the _same_
+  exclusion as `:active`, or hovering an open trigger lifts it back to the lighter
+  hover step:
+
+  ```ts
+  backgroundColor: {
+    default: 'transparent',
+    ':enabled:active': neutralStep1,
+    ':enabled[data-open]': neutralStep1,
+    '@media (hover: hover)': {
+      default: null,
+      ':enabled:hover:not(:active):not([data-open])': neutralStep0,
+    },
+  },
+  ```
+
+  Worked example: `button.styles.ts`, applied across every filled/outline/ghost cell
+  (`link` opts out — it reads as text, not a control).
+
 Worked example: `packages/ui/src/mosaic/components/button/button.styles.ts`.
 
 - **DO** use `:focus-visible` for focus rings (never bare `:focus`). For a
@@ -341,6 +363,12 @@ Worked example: `packages/ui/src/mosaic/components/button/button.styles.ts`.
   drag, and an overshoot extrapolates past the target color for nothing. A
   transform at `--cl-duration-fast` still wants the curve.
 
+- **DON'T** reuse `--cl-ease-default` for something **leaving**. It is an arrival
+  curve; run backwards it stalls for most of its duration and its overshoot
+  becomes a wobble past the target. Departures take `easingVars['--cl-ease-exit']`
+  at a shorter duration. See `motion.md` — enter/exit asymmetry has its own
+  reference, with the measurements behind these rules.
+
 - **DO** gate transitions/animations of **motion-bearing** properties on reduced
   motion — `transform`, `translate`, `scale`, `rotate`, positional insets — in the
   same object. `prefers-reduced-motion` is a vestibular-safety signal, so color
@@ -468,6 +496,61 @@ value, sub-pattern A collapses it to a single `--var` atom; reach for a raw inli
 > values, and even then the first move is usually to write a single `--cl`/`--_cl`
 > var rather than a raw inline style.
 
+**Every condition is a value key, never a top-level object.** A pseudo/at-rule
+goes _inside_ the property it modifies (`transitionProperty: { default: …, '@media …': … }`),
+not as a bare key on the style object. A top-level `'@media …': { … }` block is
+legacy syntax and the `@stylexjs/no-legacy-contextual-styles` +
+`@stylexjs/valid-styles` rules reject it (only `::before`/`::after` may sit at the
+top level). Reduced-motion is the common case:
+
+```ts
+transitionProperty: { default: 'opacity, transform', '@media (prefers-reduced-motion: reduce)': 'none' },
+```
+
+### Reacting to `data-*` state (the headless-transition case)
+
+Headless primitives drive animation off `data-*` attributes — e.g. the popover
+popup carries its own `data-starting-style` (entering frame) and
+`data-ending-style` (exiting). You can style off these in StyleX; it depends on
+_whose_ attribute you're reading:
+
+- **The element's own attribute → wrap in `:where(...)`.** Conditional keys must
+  start with `:` or `@`, so a bare `[data-*]` is rejected — but `:where([data-*])`
+  is a valid pseudo-class string that matches the same element (zero specificity;
+  StyleX self-doubles the atom class so the conditional still wins):
+
+  ```ts
+  popup: {
+    opacity: { default: 1, ':where([data-starting-style], [data-ending-style])': 0 },
+    transform: { default: 'scale(1)', ':where([data-starting-style], [data-ending-style])': 'scale(0.94)' },
+    // Reduced motion drops `transform` and keeps the fade — the gate belongs on the
+    // moving property, not the whole transition.
+    transitionProperty: { default: 'opacity, transform', '@media (prefers-reduced-motion: reduce)': 'opacity' },
+    // Positional against `transitionProperty`, and branched by direction: the exit is
+    // shorter and takes the departure curve. See `motion.md`.
+    transitionDuration: {
+      default: `${durationVars['--cl-duration-fast']}, ${durationVars['--cl-duration-base']}`,
+      ':where([data-ending-style])': durationVars['--cl-duration-fast'],
+    },
+    transitionTimingFunction: {
+      default: `linear, ${easingVars['--cl-ease-default']}`,
+      ':where([data-ending-style])': `linear, ${easingVars['--cl-ease-exit']}`,
+    },
+  },
+  ```
+
+- **Another element's attribute → `stylex.when.*`.** For relational state use
+  `stylex.when.ancestor(sel)` / `.descendant(sel)` / `.siblingBefore(sel)` /
+  `.siblingAfter(sel)` / `.anySibling(sel)`, each taking a `:${string}` or
+  `[${string}]` selector and returning a valid conditional key
+  (`:where-ancestor(...)` etc.). Use this when a parent/sibling owns the state
+  (e.g. a `[data-open]` container theming its children); use `:where([data-*])`
+  when the element owns it.
+
+So: `:where(...)` for self-state, `stylex.when.*` for relational state. Both
+compile to real attribute selectors in `styles.css`, so animation stays
+CSS-native — no JS state plumbing through the component.
+
 ## Public contract & composition (`props.ts`)
 
 The element carries three things, and nothing else is a contract:
@@ -501,6 +584,39 @@ className left-to-right and merges `style` with the consumer object spread last:
 - **DON'T** call `stylex.props` twice on one element or spread `{...props}` after
   the merge result — fuse everything through the one `mergeStyleProps` call.
 
+### Type every part with `MosaicComponentProps`
+
+`MosaicComponentProps<Tag>` is the native props for `Tag` minus the non-standard HTML
+`color` attribute, plus `render`. It drops `color` from the props **and** from the
+`render` callback's argument, so a callback's props spread straight into a Mosaic
+component whose own `color` is a variant union (`Button`, `Heading`, `Text`).
+
+```tsx
+export interface PopoverPopupProps extends MosaicComponentProps<'div'> { … }
+```
+
+- **DON'T** type a Mosaic part with the headless `ComponentProps<Tag>` (or
+  `React.ComponentPropsWithoutRef<typeof Primitive.X>`). Those keep `color: string`, and
+  every consumer then has to strip it: `props: Omit<React.HTMLAttributes<HTMLElement>, 'color'>`.
+- **DON'T** re-export a headless part straight onto the Mosaic namespace object
+  (`Popover.Trigger = Primitive.Trigger`) — that leaks the wide type. Bridge it:
+
+  ```tsx
+  const Trigger = React.forwardRef<HTMLButtonElement, MosaicComponentProps<'button'>>(
+    function PopoverTrigger(props, ref) {
+      return (
+        <Primitive.Trigger
+          ref={ref}
+          {...props}
+        />
+      );
+    },
+  );
+  ```
+
+- If a consumer needs to annotate a `render` callback, the API is wrong — fix the
+  part's props type instead. Inline callbacks infer with no annotation.
+
 ## Build & CSS delivery (two contexts, same babel)
 
 - **Published** (`build:mosaic` → `@stylexjs/rollup-plugin`): compiles the
@@ -526,7 +642,8 @@ token colors aren't down-leveled into an invalid polyfill.
   `::before`/`::after`/`::backdrop`, `@starting-style` (enter animations),
   `stylex.keyframes(...)`, `anchor-size(width|height)` (popover/menu matching its
   trigger), CSS counters, `@media (hover: hover)` / `(prefers-reduced-motion)` /
-  `(pointer: coarse)`.
+  `(pointer: coarse)`, `data-*` state via `:where([data-*])` (self) or
+  `stylex.when.*` (relational) — see "Reacting to `data-*` state" above.
 - Prefer CSS-native solutions over JS workarounds for anything StyleX supports.
 - Avoid manual `@layer` / `@property` inside `create` (StyleX owns layering;
   `@property` compiles but emits invalid output).

.github/workflows/expo-native-build.yml

@@ -27,7 +27,7 @@ env:
   SDK_PACK_DIR: /tmp/clerk-expo-pack
   E2E_INSTANCE_NAME: clerkstage-with-native-components
   BAPI_URL: https://api.clerkstage.dev
-  MAESTRO_RUNNER_VERSION: '1.1.21'
+  MAESTRO_VERSION: '2.8.0'
 
 jobs:
   native-build:
@@ -214,33 +214,32 @@ jobs:
           path: ${{ steps.native-build-key.outputs.artifact }}
           key: ${{ steps.native-build-cache.outputs.cache-primary-key }}
 
-      - name: Cache maestro-runner
+      - name: Cache maestro CLI
         if: steps.keys.outputs.pk != ''
         uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
-          path: ~/.maestro-runner
-          key: maestro-runner-${{ runner.os }}-${{ runner.arch }}-${{ env.MAESTRO_RUNNER_VERSION }}
+          path: ~/.maestro
+          key: maestro-${{ runner.os }}-${{ env.MAESTRO_VERSION }}
 
-      - name: Install maestro-runner
+      - name: Install maestro CLI
         if: steps.keys.outputs.pk != ''
         run: |
           set -o pipefail
-          if [ -x "$HOME/.maestro-runner/bin/maestro-runner" ]; then
-            echo "Using cached maestro-runner"
+          if [ -x "$HOME/.maestro/bin/maestro" ]; then
+            echo "Using cached Maestro"
           else
             installed=0
             for i in 1 2 3; do
-              if curl -fsSL --retry 3 --retry-delay 5 "https://open.devicelab.dev/install/maestro-runner" |
-                bash -s -- --version "$MAESTRO_RUNNER_VERSION"; then
-                if [ -x "$HOME/.maestro-runner/bin/maestro-runner" ]; then installed=1; break; fi
+              if curl -fLs --retry 3 --retry-delay 5 "https://get.maestro.mobile.dev" | MAESTRO_VERSION="$MAESTRO_VERSION" bash; then
+                if [ -x "$HOME/.maestro/bin/maestro" ]; then installed=1; break; fi
               fi
-              echo "maestro-runner install attempt $i failed (or binary missing); retrying"
+              echo "Maestro install attempt $i failed (or binary missing); retrying"
               sleep 5
             done
-            [ "$installed" = 1 ] || { echo "::error::maestro-runner install failed after 3 attempts"; exit 1; }
+            [ "$installed" = 1 ] || { echo "::error::Maestro install failed after 3 attempts"; exit 1; }
           fi
-          echo "$HOME/.maestro-runner/bin" >> "$GITHUB_PATH"
-          "$HOME/.maestro-runner/bin/maestro-runner" --version
+          echo "$HOME/.maestro/bin" >> "$GITHUB_PATH"
+          "$HOME/.maestro/bin/maestro" --version
 
       - name: Boot iOS simulator
         id: sim
@@ -281,16 +280,10 @@ jobs:
       - name: Run iOS e2e (Maestro)
         id: run_e2e_ios
         if: matrix.platform == 'ios' && steps.user.outputs.user_id != ''
-        # Burn-in: e2e cannot fail the check yet. Flip to hard-fail in a
-        # follow-up once the suite has proven quiet.
-        continue-on-error: true
         working-directory: ${{ env.FIXTURE_DIR }}
         env:
           CLERK_TEST_EMAIL: ${{ steps.user.outputs.email }}
           CLERK_TEST_PASSWORD: ${{ steps.user.outputs.password }}
-          MAESTRO_DEVICE: ${{ steps.sim.outputs.udid }}
-          MAESTRO_DRIVER: wda
-          MAESTRO_PLATFORM: ios
           SIM_UDID: ${{ steps.sim.outputs.udid }}
         run: |
           echo "Using simulator $SIM_UDID"
@@ -349,13 +342,10 @@ jobs:
       - name: Run Android e2e (Maestro)
         id: run_e2e_android
         if: matrix.platform == 'android' && steps.user.outputs.user_id != ''
-        continue-on-error: true
         uses: reactivecircus/android-emulator-runner@e89f39f1abbbd05b1113a29cf4db69e7540cae5a # v2
         env:
           CLERK_TEST_EMAIL: ${{ steps.user.outputs.email }}
           CLERK_TEST_PASSWORD: ${{ steps.user.outputs.password }}
-          MAESTRO_DRIVER: devicelab
-          MAESTRO_PLATFORM: android
         with:
           api-level: 34
           target: google_apis
@@ -383,7 +373,7 @@ jobs:
 
       # Test reports record flow env (and typed input) in plaintext;
       # add-mask only covers step logs, not artifact contents.
-      - name: Scrub test credentials from maestro-runner reports
+      - name: Scrub test credentials from Maestro debug output
         if: always() && (steps.run_e2e_ios.outcome == 'failure' || steps.run_e2e_android.outcome == 'failure')
         env:
           CLERK_TEST_PASSWORD: ${{ steps.user.outputs.password }}
@@ -395,7 +385,7 @@ jobs:
             \( -name '*.html' -o -name '*.json' -o -name '*.log' -o -name '*.txt' -o -name '*.xml' -o -name '*.yaml' \) \
             -exec perl -pi -e 's/\Q$ENV{CLERK_TEST_PASSWORD}\E/[REDACTED]/g' {} +
 
-      - name: Upload maestro-runner artifacts on e2e failure
+      - name: Upload Maestro artifacts on e2e failure
         if: always() && (steps.run_e2e_ios.outcome == 'failure' || steps.run_e2e_android.outcome == 'failure')
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
@@ -413,5 +403,5 @@ jobs:
           [ "$outcome" = "skipped" ] && outcome="$ANDROID_OUTCOME"
           echo "## Maestro e2e (${{ matrix.platform }}): $outcome" >> "$GITHUB_STEP_SUMMARY"
           if [ "$outcome" = "failure" ]; then
-            echo "::warning::Maestro e2e failed (burn-in mode: not failing the job). See the maestro-${{ matrix.platform }} artifact."
+            echo "::error::Maestro e2e failed. See the maestro-${{ matrix.platform }} artifact."
           fi

.typedoc/custom-plugin.mjs

@@ -87,11 +87,19 @@ const LINK_REPLACEMENTS = [
   ['enterprise-account', '/docs/reference/backend/types/backend-enterprise-account'],
   ['enterprise-account-connection', '/docs/reference/backend/types/backend-enterprise-account-connection'],
   ['enterprise-connection', '/docs/reference/backend/types/backend-enterprise-connection'],
+  [
+    'enterprise-connection-custom-attribute',
+    '/docs/reference/backend/types/backend-enterprise-connection-custom-attribute',
+  ],
   ['enterprise-connection-oauth-config', '/docs/reference/backend/types/backend-enterprise-connection-oauth-config'],
   [
     'enterprise-connection-saml-connection',
     '/docs/reference/backend/types/backend-enterprise-connection-saml-connection',
   ],
+  [
+    'enterprise-connection-saml-connection-login-hint',
+    '/docs/reference/backend/types/backend-enterprise-connection-saml-connection-login-hint',
+  ],
   ['external-account', '/docs/reference/backend/types/backend-external-account'],
   ['phone-number', '/docs/reference/backend/types/backend-phone-number'],
   ['protect-check-resource', '/docs/reference/types/protect-check-resource'],
@@ -114,9 +122,11 @@ const LINK_REPLACEMENTS = [
   ['billing-per-unit-total-tier', '/docs/reference/types/billing-per-unit-total-tier'],
   ['billing-subscription-item-resource', '/docs/reference/types/billing-subscription-item-resource'],
   ['billing-subscription-item-seats', '/docs/reference/types/billing-subscription-item-seats'],
+  ['billing-subscription-item-status', '/docs/reference/backend/types/billing-subscription-item-status'],
   ['feature-resource', '/docs/reference/types/feature-resource'],
   ['billing-statement-group', '/docs/reference/types/billing-statement-group'],
   ['billing-statement-resource', '/docs/reference/types/billing-statement-resource'],
+  ['billing-totals', '/docs/reference/types/billing-totals'],
   ['billing-subscription-resource', '/docs/reference/types/billing-subscription-resource'],
   ['clerk-api-response-error', '/docs/reference/types/clerk-api-response-error'],
   ['clerk-api-error', '/docs/reference/types/clerk-api-error'],