From 4abacf541d621bcd785dca7aef4e4d14fedb0300 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Mon, 2 Nov 2026 07:32:26 -0500
Subject: [PATCH 1/2] refactor(mosaic): tighten types to catch misuse at
 compile time

---
 .changeset/mosaic-machine-state-names.md      |  2 +
 packages/mosaic/docs/controllers.md           |  2 +
 packages/mosaic/eslint/config.mjs             | 11 ++-
 packages/mosaic/eslint/import-guards.test.mjs | 33 +++++++
 packages/mosaic/eslint/rules.mjs              | 17 ++++
 .../src/components/action-bar/action-bar.tsx  |  2 +-
 ...anization-profile-profile-section.model.ts |  7 +-
 .../reverification.controller.ts              |  6 +-
 .../user-profile-add-email.controller.ts      |  4 +-
 .../user-profile-passkeys-section.model.ts    |  2 +-
 .../user-profile-add-phone.controller.ts      |  2 +-
 packages/mosaic/src/hooks/use-spin-delay.ts   |  1 +
 packages/mosaic/src/machine/ADOPTION.md       | 51 ++++++-----
 packages/mosaic/src/machine/README.md         | 19 ++--
 packages/mosaic/src/machine/setup.ts          | 24 +++--
 packages/mosaic/src/machine/types.test-d.ts   | 89 +++++++++++++++++++
 packages/mosaic/src/machine/types.ts          |  5 +-
 .../primitives/accordion/accordion-panel.tsx  | 18 ++--
 .../primitives/accordion/accordion-root.tsx   |  6 +-
 .../accordion/accordion-trigger.tsx           |  6 +-
 .../autocomplete/autocomplete-list.tsx        |  4 +-
 .../autocomplete/autocomplete-positioner.tsx  |  4 +-
 .../mosaic/src/primitives/button/button.tsx   |  4 +-
 .../collapsible/collapsible-panel.tsx         | 20 +++--
 .../collapsible/collapsible-root.tsx          |  6 +-
 .../collapsible/collapsible-trigger.tsx       |  6 +-
 .../src/primitives/combobox/combobox-list.tsx |  4 +-
 .../combobox/combobox-positioner.tsx          |  4 +-
 .../src/primitives/combobox/combobox-root.tsx |  1 +
 .../primitives/dialog/dialog-handle.test-d.ts | 22 +++++
 .../src/primitives/dialog/dialog-handle.ts    |  6 +-
 .../file-upload/file-upload-dropzone.tsx      |  6 +-
 .../file-upload/file-upload-item-delete.tsx   |  6 +-
 .../file-upload/file-upload-item-preview.tsx  |  6 +-
 .../file-upload/file-upload-item.tsx          |  4 +-
 .../file-upload/file-upload-root.tsx          |  6 +-
 .../file-upload/file-upload-trigger.tsx       |  6 +-
 .../mosaic/src/primitives/flow/flow-root.tsx  |  2 +-
 .../src/primitives/menu/menu-positioner.tsx   |  5 +-
 .../mosaic/src/primitives/otp/otp-input.tsx   |  6 +-
 .../mosaic/src/primitives/otp/otp-root.tsx    |  6 +-
 .../segmented-control-item.tsx                |  6 +-
 .../segmented-control-root.tsx                |  6 +-
 .../primitives/select/select-positioner.tsx   |  5 +-
 .../src/primitives/table/table-cell.tsx       |  4 +-
 .../src/primitives/table/table-column.tsx     |  6 +-
 .../src/primitives/table/table-header.tsx     |  6 +-
 .../src/primitives/table/table-root.tsx       |  6 +-
 .../mosaic/src/primitives/table/table-row.tsx | 12 +--
 .../mosaic/src/primitives/tabs/tabs-list.tsx  |  6 +-
 .../mosaic/src/primitives/tabs/tabs-tab.tsx   |  8 +-
 .../primitives/tag-input/tag-input-input.tsx  |  6 +-
 .../primitives/tag-input/tag-input-root.tsx   |  6 +-
 .../tag-input/tag-input-tag-remove.tsx        |  6 +-
 .../primitives/tag-input/tag-input-tag.tsx    |  6 +-
 .../primitives/tooltip/tooltip-positioner.tsx |  4 +-
 .../mosaic/src/primitives/utils/css-vars.ts   |  2 +-
 .../src/primitives/utils/use-render.test-d.ts | 11 +++
 .../src/primitives/utils/use-render.test.tsx  |  2 +-
 .../src/primitives/utils/use-render.tsx       |  2 +-
 packages/mosaic/tsconfig.json                 |  5 ++
 61 files changed, 386 insertions(+), 170 deletions(-)
 create mode 100644 .changeset/mosaic-machine-state-names.md
 create mode 100644 packages/mosaic/src/primitives/dialog/dialog-handle.test-d.ts

diff --git a/.changeset/mosaic-machine-state-names.md b/.changeset/mosaic-machine-state-names.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/mosaic-machine-state-names.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/mosaic/docs/controllers.md b/packages/mosaic/docs/controllers.md
index 835e73df287..94f05e37503 100644
--- a/packages/mosaic/docs/controllers.md
+++ b/packages/mosaic/docs/controllers.md
@@ -313,6 +313,8 @@ every successful removal drops focus on the floor.
 - **No machine snapshot in the return value.** Return the plain props the view
   reads (`open`, `pendingKey`, `isDeleting`, `errorMessage`), never `snapshot`
   and `send`.
+- A transition shared across states in a `const` needs `target: 'name' as const`.
+  Without it the target widens to `string` and the machine rejects it.
 - Dismissing must not abandon an in-flight effect. Model `open` as context, and
   give `OPEN`/`CLOSE` no target in the busy state so they don't leave it:
 
diff --git a/packages/mosaic/eslint/config.mjs b/packages/mosaic/eslint/config.mjs
index ab7e3b23c2d..79642a983d9 100644
--- a/packages/mosaic/eslint/config.mjs
+++ b/packages/mosaic/eslint/config.mjs
@@ -4,7 +4,7 @@ import vitest from '@vitest/eslint-plugin';
 import boundaries from 'eslint-plugin-boundaries';
 import noUnneededEffects from 'eslint-plugin-react-you-might-not-need-an-effect';
 
-import { forwardRefParts, noDynamicMessageCatalogs, noModelReactState } from './rules.mjs';
+import { forwardRefParts, noDynamicMessageCatalogs, noModelReactState, noRawInvoke } from './rules.mjs';
 
 const mosaicRoot = path.resolve(import.meta.dirname, '..');
 
@@ -30,6 +30,7 @@ export default [
           'no-model-react-state': noModelReactState,
           'no-dynamic-message-catalogs': noDynamicMessageCatalogs,
           'forward-ref-parts': forwardRefParts,
+          'no-raw-invoke': noRawInvoke,
         },
       },
     },
@@ -63,6 +64,14 @@ export default [
       'mosaic/forward-ref-parts': 'error',
     },
   },
+  {
+    name: 'packages/mosaic - machines',
+    files: ['src/**/*.{ts,tsx}'],
+    ignores: ['src/**/__tests__/**', 'src/**/*.test.{ts,tsx}', 'src/**/*.test-d.{ts,tsx}'],
+    rules: {
+      'mosaic/no-raw-invoke': 'error',
+    },
+  },
   {
     name: 'packages/mosaic - effects',
     files: ['src/features/**/*.{ts,tsx}'],
diff --git a/packages/mosaic/eslint/import-guards.test.mjs b/packages/mosaic/eslint/import-guards.test.mjs
index d063d0d2b97..a06c132093e 100644
--- a/packages/mosaic/eslint/import-guards.test.mjs
+++ b/packages/mosaic/eslint/import-guards.test.mjs
@@ -349,6 +349,38 @@ describe('Mosaic layers', { timeout: 30_000 }, () => {
   });
 });
 
+describe('Mosaic machines', { timeout: 30_000 }, () => {
+  async function rawInvokeMessages(file, source) {
+    const messages = await lintAt(file, source);
+    expect(messages.find(message => message.fatal)).toBeUndefined();
+    return messages.filter(message => message.ruleId === 'mosaic/no-raw-invoke').map(message => message.message);
+  }
+
+  test('rejects an invoke written without fromPromise', async () => {
+    expect(
+      await rawInvokeMessages(
+        `${featureDir}/sample.controller.ts`,
+        'export const state = { invoke: { src: () => Promise.resolve(1), onDone: { target: "idle" } } };',
+      ),
+    ).toEqual(['Write invoke with fromPromise from setup(), so onDone sees the typed output instead of any.']);
+  });
+
+  test('allows an invoke from fromPromise', async () => {
+    expect(
+      await rawInvokeMessages(
+        `${featureDir}/sample.controller.ts`,
+        'declare const fromPromise: (run: () => Promise<number>) => object;\nexport const state = { invoke: fromPromise(() => Promise.resolve(1)) };',
+      ),
+    ).toEqual([]);
+  });
+
+  test('ignores test files', async () => {
+    expect(
+      await rawInvokeMessages(testFixture, 'export const state = { invoke: { src: () => Promise.resolve(1) } };'),
+    ).toEqual([]);
+  });
+});
+
 describe('Mosaic parts', { timeout: 30_000 }, () => {
   async function forwardRefMessages(file, source) {
     const messages = await lintAt(
@@ -499,6 +531,7 @@ describe('Mosaic package configuration', { timeout: 30_000 }, () => {
       'mosaic/no-model-react-state',
       'mosaic/no-dynamic-message-catalogs',
       'mosaic/forward-ref-parts',
+      'mosaic/no-raw-invoke',
       '@typescript-eslint/no-import-type-side-effects',
       ...Object.keys(noUnneededEffects.configs.strict.rules),
     ]) {
diff --git a/packages/mosaic/eslint/rules.mjs b/packages/mosaic/eslint/rules.mjs
index 88b0b363139..26dd217cefd 100644
--- a/packages/mosaic/eslint/rules.mjs
+++ b/packages/mosaic/eslint/rules.mjs
@@ -268,3 +268,20 @@ export const forwardRefParts = {
     };
   },
 };
+
+export const noRawInvoke = {
+  meta: {
+    type: 'problem',
+    schema: [],
+    messages: {
+      useFromPromise: 'Write invoke with fromPromise from setup(), so onDone sees the typed output instead of any.',
+    },
+  },
+  create(context) {
+    return {
+      'Property[key.name="invoke"] > ObjectExpression:has(> Property[key.name="src"])'(node) {
+        context.report({ node, messageId: 'useFromPromise' });
+      },
+    };
+  },
+};
diff --git a/packages/mosaic/src/components/action-bar/action-bar.tsx b/packages/mosaic/src/components/action-bar/action-bar.tsx
index 2d97a731238..f4ed1e2dbb0 100644
--- a/packages/mosaic/src/components/action-bar/action-bar.tsx
+++ b/packages/mosaic/src/components/action-bar/action-bar.tsx
@@ -263,8 +263,8 @@ const Action = React.forwardRef<HTMLButtonElement, ActionBarActionProps>(functio
           <Button
             variant='ghost'
             size='md'
-            color={color}
             {...merged}
+            color={color}
             // eslint-disable-next-line react-hooks/rules-of-hooks -- floating-ui's CompositeItem calls this render callback synchronously during its own render, so the hook keeps a stable position.
             ref={useMergeRefs<unknown>([ref, isRef(itemRef) ? itemRef : undefined])}
             xstyle={[color === 'negative' && styles.destructive, xstyle]}
diff --git a/packages/mosaic/src/features/organization-profile/organization-profile-profile-section/organization-profile-profile-section.model.ts b/packages/mosaic/src/features/organization-profile/organization-profile-profile-section/organization-profile-profile-section.model.ts
index 758ea42432e..ba129472fc2 100644
--- a/packages/mosaic/src/features/organization-profile/organization-profile-profile-section/organization-profile-profile-section.model.ts
+++ b/packages/mosaic/src/features/organization-profile/organization-profile-profile-section/organization-profile-profile-section.model.ts
@@ -4,6 +4,8 @@ import type { OrganizationResource } from '@clerk/shared/types';
 import { useMosaicEnvironment } from '../../../hooks/use-mosaic-environment';
 import { save, SaveError, UNEXPECTED_ERROR } from '../../../utils/errors';
 import { ORGANIZATION_PERMISSIONS } from '../../../utils/permissions';
+import type { OrganizationProfileEditNameValue } from './organization-profile-edit-name.dialog';
+import type { OrganizationProfileEditSlugValue } from './organization-profile-edit-slug.dialog';
 import type { OrganizationProfileProfileSectionViewProps } from './organization-profile-profile-section.view';
 
 type OrganizationProfileProfileSectionModel =
@@ -52,10 +54,11 @@ export function useOrganizationProfileProfileSectionModel(): OrganizationProfile
     ...profile,
     onLogoChange: file => save(() => currentOrganization().setLogo({ file })),
     onRemoveLogo: organization.hasImage ? () => save(() => currentOrganization().setLogo({ file: null })) : undefined,
-    onSubmitName: name => save(() => currentOrganization().update({ name }), ['name']),
+    onSubmitName: name =>
+      save<keyof OrganizationProfileEditNameValue>(() => currentOrganization().update({ name }), ['name']),
     onSubmitSlug: !environment.organizationSettings.slug.disabled
       ? slug =>
-          save(() => {
+          save<keyof OrganizationProfileEditSlugValue>(() => {
             const current = currentOrganization();
             return current.update({ name: current.name, slug });
           }, ['slug'])
diff --git a/packages/mosaic/src/features/reverification/reverification.controller.ts b/packages/mosaic/src/features/reverification/reverification.controller.ts
index d50f5d013a6..d26b8782d2e 100644
--- a/packages/mosaic/src/features/reverification/reverification.controller.ts
+++ b/packages/mosaic/src/features/reverification/reverification.controller.ts
@@ -176,7 +176,7 @@ const factorEvents = {
   },
   SELECT_METHOD: [
     {
-      target: 'methodPickerPreparing',
+      target: 'methodPickerPreparing' as const,
       guard: (ctx, event) => {
         const method = ctx.methods.find(candidate => candidate.id === event.id);
         return topOverlay(ctx) === 'method-picker' && Boolean(method && needsPrepare(method));
@@ -184,12 +184,12 @@ const factorEvents = {
       actions: assign((ctx, event) => selectMethod(ctx, event.id)),
     },
     {
-      target: 'verifying',
+      target: 'verifying' as const,
       guard: ctx => topOverlay(ctx) === 'method-picker',
       actions: assign((ctx, event) => ({ ...selectMethod(ctx, event.id), overlay: [] })),
     },
   ],
-  RESET: 'inactive',
+  RESET: 'inactive' as const,
 } satisfies NonNullable<StateConfig<ReverificationContext, ReverificationEvent>['on']>;
 
 export const reverificationMachine = createMachine({
diff --git a/packages/mosaic/src/features/user-profile/user-profile-email-section/user-profile-add-email.controller.ts b/packages/mosaic/src/features/user-profile/user-profile-email-section/user-profile-add-email.controller.ts
index 048e1a302ba..be357744086 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-email-section/user-profile-add-email.controller.ts
+++ b/packages/mosaic/src/features/user-profile/user-profile-email-section/user-profile-add-email.controller.ts
@@ -64,12 +64,12 @@ const LINK_RESEND_SECONDS = 60;
 const tick = { actions: assign(context => ({ resendSeconds: Math.max(0, context.resendSeconds - 1) })) };
 const fail = assign<ErrorInvokeEvent>((_, event) => ({ error: toFormError(event.error) }));
 const resend = {
-  target: 'starting',
+  target: 'starting' as const,
   guard: (context: Context) => context.resendSeconds === 0,
   actions: assign(() => ({ error: undefined })),
 };
 const start = {
-  target: 'starting',
+  target: 'starting' as const,
   actions: assign<Extract<Event, { type: 'START' }>>((_, event) => ({
     verifyingId: event.id,
     emailAddress: event.emailAddress,
diff --git a/packages/mosaic/src/features/user-profile/user-profile-passkeys-section/user-profile-passkeys-section.model.ts b/packages/mosaic/src/features/user-profile/user-profile-passkeys-section/user-profile-passkeys-section.model.ts
index a927281f3d1..d6e744ef625 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-passkeys-section/user-profile-passkeys-section.model.ts
+++ b/packages/mosaic/src/features/user-profile/user-profile-passkeys-section/user-profile-passkeys-section.model.ts
@@ -173,7 +173,7 @@ export function useUserProfilePasskeysModel(): UserProfilePasskeysModel {
       if (feedback) {
         throw new FormSubmitError<UserProfileRenamePasskeyValues>({ fields: { name: feedback.message } });
       }
-      await save(() => passkey.update({ name }), ['name']);
+      await save<keyof UserProfileRenamePasskeyValues>(() => passkey.update({ name }), ['name']);
     },
     onRemove: async id => {
       const passkey = currentUser().passkeys.find(candidate => candidate.id === id);
diff --git a/packages/mosaic/src/features/user-profile/user-profile-phone-section/user-profile-add-phone.controller.ts b/packages/mosaic/src/features/user-profile/user-profile-phone-section/user-profile-add-phone.controller.ts
index 7db589f8e18..522cd2ddbe4 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-phone-section/user-profile-add-phone.controller.ts
+++ b/packages/mosaic/src/features/user-profile/user-profile-phone-section/user-profile-add-phone.controller.ts
@@ -53,7 +53,7 @@ function missingDependency(): Promise<never> {
 const tick = { actions: assign(context => ({ resendSeconds: Math.max(0, context.resendSeconds - 1) })) };
 const fail = assign<ErrorInvokeEvent>((_, event) => ({ error: toFormError(event.error) }));
 const start = {
-  target: 'sending',
+  target: 'sending' as const,
   actions: assign<Extract<Event, { type: 'START' }>>((_, event) => ({
     verifyingId: event.id,
     phoneNumber: event.phoneNumber,
diff --git a/packages/mosaic/src/hooks/use-spin-delay.ts b/packages/mosaic/src/hooks/use-spin-delay.ts
index 985edc160f9..5a8041beb04 100644
--- a/packages/mosaic/src/hooks/use-spin-delay.ts
+++ b/packages/mosaic/src/hooks/use-spin-delay.ts
@@ -58,6 +58,7 @@ export function useSpinDelay<T>(value: T | null, options: SpinDelayOptions = {})
     if (value !== shown) {
       setShown(value);
     }
+    return undefined;
   }, [value, shown, delay, minDuration]);
 
   return shown;
diff --git a/packages/mosaic/src/machine/ADOPTION.md b/packages/mosaic/src/machine/ADOPTION.md
index b665a491ed0..dee1600a84c 100644
--- a/packages/mosaic/src/machine/ADOPTION.md
+++ b/packages/mosaic/src/machine/ADOPTION.md
@@ -115,10 +115,9 @@ Problems:
 ### After
 
 ```ts
-import { createMachine } from '../../machine/create-machine';
-import { assign } from '../../machine/assign';
+import { setup } from '../../machine/setup';
 
-type Context = { error: string | null };
+type Context = { emailAddress: string; error: string | null };
 type Event = { type: 'SUBMIT'; emailAddress: string } | { type: 'NAVIGATE_DONE' };
 
 type WaitlistDeps = {
@@ -127,20 +126,25 @@ type WaitlistDeps = {
   afterJoinWaitlistUrl?: string;
 };
 
+const { createMachine, assign, fromPromise } = setup<Context, Event>();
+
 function createWaitlistMachine(deps: WaitlistDeps) {
-  return createMachine<Context, Event>({
+  return createMachine({
     id: 'waitlist',
     initial: 'idle',
-    context: { error: null },
+    context: { emailAddress: '', error: null },
     states: {
       idle: {
-        on: { SUBMIT: 'submitting' },
+        on: {
+          SUBMIT: {
+            target: 'submitting',
+            actions: assign((_ctx, e) => ({ emailAddress: e.emailAddress })),
+          },
+        },
       },
       submitting: {
         // Double-submit is impossible: SUBMIT is not handled here.
-        invoke: {
-          src: (ctx, event) =>
-            deps.joinWaitlist({ emailAddress: (event as Extract<Event, { type: 'SUBMIT' }>).emailAddress }),
+        invoke: fromPromise(ctx => deps.joinWaitlist({ emailAddress: ctx.emailAddress }), {
           onDone: {
             target: 'success',
             actions: assign(() => ({ error: null })),
@@ -149,7 +153,7 @@ function createWaitlistMachine(deps: WaitlistDeps) {
             target: 'idle',
             actions: assign((_ctx, e) => ({ error: String(e.error) })),
           },
-        },
+        }),
       },
       success: {
         // Optional auto-navigate on entry:
@@ -375,7 +379,9 @@ type SignInEvent =
   | { type: 'CLEAR_PROVIDER' }
   | { type: 'SUBMIT'; identifier: string };
 
-const signInStartMachine = createMachine<SignInContext, SignInEvent>({
+const { createMachine, assign, fromPromise } = setup<SignInContext, SignInEvent>();
+
+const signInStartMachine = createMachine({
   id: 'signInStart',
   initial: 'idle',
   context: { selectedProvider: null, identifier: '', error: null },
@@ -405,14 +411,13 @@ const signInStartMachine = createMachine<SignInContext, SignInEvent>({
       },
     },
     submitting: {
-      invoke: {
-        src: ctx => signIn.create({ identifier: ctx.identifier }),
+      invoke: fromPromise(ctx => signIn.create({ identifier: ctx.identifier }), {
         onDone: { target: 'idle', actions: assign(() => ({ error: null })) },
         onError: {
           target: 'idle',
           actions: assign((_ctx, e) => ({ error: String(e.error) })),
         },
-      },
+      }),
     },
   },
 });
@@ -521,7 +526,7 @@ type SignInStartEvent =
   | { type: 'TYPE_IDENTIFIER'; value: string }
   | { type: 'SUBMIT_IDENTIFIER' };
 
-const { createMachine, assign } = setup<SignInStartContext, SignInStartEvent>();
+const { createMachine, assign, fromPromise } = setup<SignInStartContext, SignInStartEvent>();
 
 export function createSignInStartMachine(deps: { signInFn: SignInStartContext['signInFn'] }) {
   return createMachine({
@@ -546,17 +551,19 @@ export function createSignInStartMachine(deps: { signInFn: SignInStartContext['s
       submitting: {
         // Both entry points converge here. idle's on-handlers are inactive,
         // so a second CLICK_SOCIAL while already submitting is dropped automatically.
-        invoke: {
-          src: ctx =>
+        invoke: fromPromise(
+          ctx =>
             ctx.activeStrategy === 'email'
               ? ctx.signInFn({ identifier: ctx.identifier })
               : ctx.signInFn({ strategy: ctx.activeStrategy! }),
-          onDone: 'success',
-          onError: {
-            target: 'idle',
-            actions: assign((_, e) => ({ error: String(e.error), activeStrategy: null })),
+          {
+            onDone: 'success',
+            onError: {
+              target: 'idle',
+              actions: assign((_, e) => ({ error: String(e.error), activeStrategy: null })),
+            },
           },
-        },
+        ),
       },
       success: { type: 'final' },
     },
diff --git a/packages/mosaic/src/machine/README.md b/packages/mosaic/src/machine/README.md
index d4951947791..6bad81cb237 100644
--- a/packages/mosaic/src/machine/README.md
+++ b/packages/mosaic/src/machine/README.md
@@ -62,8 +62,9 @@ run it.
 ## Your first machine
 
 ```ts
-import { createMachine } from '../../machine/create-machine';
-import { assign } from '../../machine/assign';
+import { setup } from '../../machine/setup';
+
+const { createMachine, assign, fromPromise } = setup<LoaderContext, LoaderEvent>();
 
 const loader = createMachine({
   initial: 'idle', // where it starts
@@ -74,8 +75,7 @@ const loader = createMachine({
     },
     loading: {
       // `invoke` runs a promise on entry and branches on the result.
-      invoke: {
-        src: () => fetchThing(),
+      invoke: fromPromise(() => fetchThing(), {
         onDone: {
           target: 'success',
           // copy the resolved value into context
@@ -85,7 +85,7 @@ const loader = createMachine({
           target: 'failure',
           actions: assign((_ctx, event) => ({ error: String(event.error) })),
         },
-      },
+      }),
     },
     success: {},
     failure: { on: { FETCH: 'loading' } }, // allow a retry
@@ -114,7 +114,7 @@ factory functions that don't require repeating them:
 ```ts
 import { setup } from '../../machine/setup';
 
-const { createMachine, assign } = setup<LoaderContext, LoaderEvent>();
+const { createMachine, assign, fromPromise } = setup<LoaderContext, LoaderEvent>();
 
 const loader = createMachine({
   // no <LoaderContext, LoaderEvent> needed
@@ -130,17 +130,16 @@ const loader = createMachine({
       },
     },
     loading: {
-      invoke: {
-        src: async ctx => fetchData(ctx.query),
+      invoke: fromPromise(ctx => fetchData(ctx.query), {
         onDone: {
           target: 'success',
-          actions: assign((_, e) => ({ data: String(e.output), error: null })), // e: DoneInvokeEvent<unknown>
+          actions: assign((_, e) => ({ data: e.output, error: null })), // e.output: what fetchData resolves to
         },
         onError: {
           target: 'failure',
           actions: assign((_, e) => ({ error: String(e.error) })), // e: ErrorInvokeEvent
         },
-      },
+      }),
     },
     success: {},
     failure: { on: { FETCH: 'loading' } },
diff --git a/packages/mosaic/src/machine/setup.ts b/packages/mosaic/src/machine/setup.ts
index d639aa03656..3dd4d8e9d1e 100644
--- a/packages/mosaic/src/machine/setup.ts
+++ b/packages/mosaic/src/machine/setup.ts
@@ -67,20 +67,26 @@ export function setup<TContext extends object, TEvent extends EventObject>() {
      * }
      * ```
      *
-     * A raw `src` function (without `fromPromise`) still works — `e.output` is `any`.
+     * A raw `src` function (without `fromPromise`) still type-checks with `e.output: any`, so
+     * `mosaic/no-raw-invoke` rejects it outside tests.
      */
-    fromPromise: <TOutput, TStates extends string = string>(
+    fromPromise: <TOutput, const TDone extends string = never, const TError extends string = never>(
       fn: (context: TContext) => Promise<TOutput>,
       config?: {
-        onDone?: Transition<TContext, DoneInvokeEvent<TOutput>, TStates>;
-        onError?: Transition<TContext, ErrorInvokeEvent, TStates>;
+        onDone?: InferredTransition<TContext, DoneInvokeEvent<TOutput>, TDone>;
+        onError?: InferredTransition<TContext, ErrorInvokeEvent, TError>;
       },
-    ): InvokeConfig<TContext, TEvent, TOutput, TStates> => ({
+    ) =>
       // SAFETY: fn only uses context (no event param), but InvokeConfig.src accepts
       // (context, event) for parity with state-entry event access. The extra event
-      // parameter is unused; callers receive only context at runtime.
-      src: fn as unknown as InvokeConfig<TContext, TEvent, TOutput, TStates>['src'],
-      ...config,
-    }),
+      // parameter is unused; callers receive only context at runtime. The config's
+      // inference slots are all forms of Transition.
+      ({ src: fn, ...config }) as unknown as InvokeConfig<TContext, TEvent, TOutput, TDone | TError>,
   };
 }
+
+type InferredTransition<TContext, TEvent extends EventObject, TStates extends string> =
+  | `${TStates}`
+  | { target: TStates }
+  | { target: TStates }[]
+  | Transition<TContext, TEvent, TStates>;
diff --git a/packages/mosaic/src/machine/types.test-d.ts b/packages/mosaic/src/machine/types.test-d.ts
index e78585f675d..6cbe3fc5470 100644
--- a/packages/mosaic/src/machine/types.test-d.ts
+++ b/packages/mosaic/src/machine/types.test-d.ts
@@ -418,6 +418,95 @@ describe('setup.fromPromise — e.output is typed from src return type', () => {
     });
   });
 
+  test('a machine using fromPromise still rejects unknown state names', () => {
+    make2({
+      // @ts-expect-error — 'nope' is not a state
+      initial: 'nope',
+      context: { url: '', data: null, error: null },
+      states: {
+        idle: {},
+        loading: { invoke: fromPromise(fakeFetch, { onDone: 'idle' }) },
+      },
+    });
+
+    make2({
+      initial: 'idle',
+      context: { url: '', data: null, error: null },
+      states: {
+        // @ts-expect-error — 'nope' is not a state
+        idle: { on: { FETCH: 'nope' } },
+        loading: { invoke: fromPromise(fakeFetch, { onDone: 'idle' }) },
+      },
+    });
+  });
+
+  test('fromPromise rejects unknown targets and accepts known ones', () => {
+    make2({
+      initial: 'idle',
+      context: { url: '', data: null, error: null },
+      states: {
+        idle: {},
+        // @ts-expect-error — 'nope' is not a state
+        done: { invoke: fromPromise(fakeFetch, { onDone: 'nope' }) },
+        // @ts-expect-error — 'nope' is not a state
+        failed: { invoke: fromPromise(fakeFetch, { onError: { target: 'nope' } }) },
+        // @ts-expect-error — 'nope' is not a state
+        guarded: { invoke: fromPromise(fakeFetch, { onDone: [{ target: 'idle' }, { target: 'nope' }] }) },
+        loading: {
+          invoke: fromPromise(fakeFetch, {
+            onDone: [{ target: 'done' }, { target: 'idle' }],
+            onError: 'failed',
+          }),
+        },
+      },
+    });
+  });
+
+  test('a transition without a target does not widen the state names', () => {
+    make2({
+      initial: 'idle',
+      context: { url: '', data: null, error: null },
+      states: {
+        idle: {},
+        loading: {
+          invoke: fromPromise(fakeFetch, {
+            onDone: 'idle',
+            onError: { actions: a2(() => ({ error: 'failed' })) },
+          }),
+        },
+      },
+    });
+  });
+
+  test('a shared fromPromise state is checked against the machine it joins', () => {
+    const known = { invoke: fromPromise(fakeFetch, { onDone: { target: 'idle' } }) };
+    const unknownTarget = { invoke: fromPromise(fakeFetch, { onDone: { target: 'nope' } }) };
+
+    make2({
+      initial: 'idle',
+      context: { url: '', data: null, error: null },
+      states: {
+        idle: {},
+        known,
+        // @ts-expect-error — 'nope' is not a state
+        unknownTarget,
+      },
+    });
+  });
+
+  test('the machine keeps its state names as a union', () => {
+    const fetching = make2({
+      initial: 'idle',
+      context: { url: '', data: null, error: null },
+      states: {
+        idle: {},
+        loading: { invoke: fromPromise(fakeFetch, { onDone: 'idle' }) },
+      },
+    });
+
+    expectTypeOf(createActor(fetching).getSnapshot().value).toEqualTypeOf<'idle' | 'loading'>();
+  });
+
   test('a raw src function still works — e.output is any', () => {
     make2({
       initial: 'idle',
diff --git a/packages/mosaic/src/machine/types.ts b/packages/mosaic/src/machine/types.ts
index e73043cc13c..0355043c18f 100644
--- a/packages/mosaic/src/machine/types.ts
+++ b/packages/mosaic/src/machine/types.ts
@@ -157,7 +157,8 @@ export interface StateConfig<TContext, TEvent extends EventObject, TStates exten
   /**
    * A promise to invoke on entry. Use {@link PromiseSrc} (created by
    * `setup().fromPromise`) to carry the resolved type to `onDone.actions`.
-   * A raw `src` function is also accepted — `e.output` is `any` in that case.
+   * A raw `src` function is also accepted — `e.output` is `any` in that case, so
+   * `mosaic/no-raw-invoke` rejects it outside tests.
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Each state invokes its own output type, and TypeScript cannot express that per-state type here; `unknown` would reject typed `onDone` handlers.
   invoke?: InvokeConfig<TContext, TEvent, any, TStates>;
@@ -179,7 +180,7 @@ export interface MachineConfig<TContext, TEvent extends EventObject, TStates ext
   id?: string;
   initial: NoInfer<TStates> | InitialResolver<TContext, NoInfer<TStates>>;
   context?: TContext;
-  states: Record<TStates, StateConfig<TContext, TEvent, TStates>>;
+  states: Record<TStates, StateConfig<TContext, TEvent, NoInfer<TStates>>>;
 }
 
 /**
diff --git a/packages/mosaic/src/primitives/accordion/accordion-panel.tsx b/packages/mosaic/src/primitives/accordion/accordion-panel.tsx
index 4d07740ac8c..ad96fbbdd11 100644
--- a/packages/mosaic/src/primitives/accordion/accordion-panel.tsx
+++ b/packages/mosaic/src/primitives/accordion/accordion-panel.tsx
@@ -1,9 +1,9 @@
 'use client';
 
-import React from 'react';
+import React, { type CSSProperties } from 'react';
 
 import { usePanelSize } from '../hooks/use-panel-size';
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { useAccordionItemContext } from './accordion-context';
 
 export type AccordionPanelProps = ComponentProps<'div'>;
@@ -17,16 +17,18 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
 
     const state = { open };
 
-    const defaultProps: Record<string, unknown> = {
+    const style: CSSProperties & Record<`--${string}`, string | undefined> = {
+      '--cl-accordion-panel-height': height != null ? `${height}px` : undefined,
+      ...transitionProps.style,
+    };
+
+    const defaultProps = {
       id: panelId,
       role: 'region' as const,
       'aria-labelledby': triggerId,
       ...transitionProps,
-      style: {
-        '--cl-accordion-panel-height': height != null ? `${height}px` : undefined,
-        ...transitionProps.style,
-      },
-    };
+      style,
+    } satisfies DefaultProps<'div'>;
 
     const merged = mergeProps<'div'>(defaultProps, otherProps);
     // The wired id is owned by the primitive: a consumer-supplied id must not
diff --git a/packages/mosaic/src/primitives/accordion/accordion-root.tsx b/packages/mosaic/src/primitives/accordion/accordion-root.tsx
index 2adddfc4c21..80d7128d246 100644
--- a/packages/mosaic/src/primitives/accordion/accordion-root.tsx
+++ b/packages/mosaic/src/primitives/accordion/accordion-root.tsx
@@ -4,7 +4,7 @@ import { Composite } from '@floating-ui/react';
 import React, { type ReactNode, useCallback, useId, useMemo } from 'react';
 
 import { useControllableState } from '../hooks/use-controllable-state';
-import { type ComponentProps, isRef, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, isRef, mergeProps, useRender } from '../utils';
 import { AccordionContext, type AccordionContextValue } from './accordion-context';
 
 export interface AccordionProps extends ComponentProps<'div'> {
@@ -56,7 +56,7 @@ export const AccordionRoot = React.forwardRef<HTMLDivElement, AccordionProps>(fu
           // generic <div> (no widget role). Strip it to avoid an axe violation.
           const { 'aria-orientation': _ao, ...restCompositeProps } = compositeProps;
 
-          const defaultProps: Record<string, unknown> = {
+          const defaultProps = {
             onKeyDown: (event: React.KeyboardEvent<HTMLElement>) => {
               if (event.key !== 'Home' && event.key !== 'End') {
                 return;
@@ -67,7 +67,7 @@ export const AccordionRoot = React.forwardRef<HTMLDivElement, AccordionProps>(fu
               );
               (event.key === 'Home' ? items.at(0) : items.at(-1))?.focus();
             },
-          };
+          } satisfies DefaultProps<'div'>;
 
           const merged = mergeProps<'div'>(defaultProps, mergeProps<'div'>(otherProps, restCompositeProps));
 
diff --git a/packages/mosaic/src/primitives/accordion/accordion-trigger.tsx b/packages/mosaic/src/primitives/accordion/accordion-trigger.tsx
index 7dddcf23a59..766be47b4ff 100644
--- a/packages/mosaic/src/primitives/accordion/accordion-trigger.tsx
+++ b/packages/mosaic/src/primitives/accordion/accordion-trigger.tsx
@@ -3,7 +3,7 @@
 import { CompositeItem } from '@floating-ui/react';
 import React from 'react';
 
-import { type ComponentProps, isRef, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, isRef, mergeProps, useRender } from '../utils';
 import { useAccordionContext, useAccordionItemContext } from './accordion-context';
 
 export type AccordionTriggerProps = ComponentProps<'button'>;
@@ -20,7 +20,7 @@ export const AccordionTrigger = React.forwardRef<HTMLButtonElement, AccordionTri
       <CompositeItem
         disabled={disabled}
         render={(compositeProps: React.HTMLAttributes<HTMLElement>) => {
-          const defaultProps: Record<string, unknown> = {
+          const defaultProps = {
             id: triggerId,
             type: 'button' as const,
             'aria-expanded': open,
@@ -31,7 +31,7 @@ export const AccordionTrigger = React.forwardRef<HTMLButtonElement, AccordionTri
                 ctx.toggle(itemValue);
               }
             },
-          };
+          } satisfies DefaultProps<'button'>;
 
           const merged = mergeProps<'button'>(mergeProps<'button'>(defaultProps, otherProps), compositeProps);
 
diff --git a/packages/mosaic/src/primitives/autocomplete/autocomplete-list.tsx b/packages/mosaic/src/primitives/autocomplete/autocomplete-list.tsx
index d377d58b65c..96cb5c31d9f 100644
--- a/packages/mosaic/src/primitives/autocomplete/autocomplete-list.tsx
+++ b/packages/mosaic/src/primitives/autocomplete/autocomplete-list.tsx
@@ -19,7 +19,7 @@ export const AutocompleteList = React.forwardRef<HTMLDivElement, AutocompleteLis
     }, [setInlineMode]);
 
     const floatingProps = getFloatingProps();
-    const wiredId = floatingProps.id;
+    const wiredId = floatingProps['id'];
 
     const ownProps = {} satisfies DefaultProps<'div'>;
 
@@ -28,7 +28,7 @@ export const AutocompleteList = React.forwardRef<HTMLDivElement, AutocompleteLis
     const merged = mergeProps<'div'>(defaultProps, otherProps);
     // The wired id is owned by the primitive: a consumer-supplied id must not
     // override it, or the aria-controls pairing would silently break.
-    if (wiredId != null) {
+    if (typeof wiredId === 'string') {
       merged.id = wiredId;
     }
 
diff --git a/packages/mosaic/src/primitives/autocomplete/autocomplete-positioner.tsx b/packages/mosaic/src/primitives/autocomplete/autocomplete-positioner.tsx
index 1ba2413cf35..2b06827cf15 100644
--- a/packages/mosaic/src/primitives/autocomplete/autocomplete-positioner.tsx
+++ b/packages/mosaic/src/primitives/autocomplete/autocomplete-positioner.tsx
@@ -18,7 +18,7 @@ export const AutocompletePositioner = React.forwardRef<HTMLDivElement, Autocompl
     const side = parsePlacement(placement).side;
 
     const floatingProps = getFloatingProps();
-    const wiredId = floatingProps.id;
+    const wiredId = floatingProps['id'];
 
     const ownProps = {
       'data-side': side,
@@ -30,7 +30,7 @@ export const AutocompletePositioner = React.forwardRef<HTMLDivElement, Autocompl
     const merged = mergeProps<'div'>(defaultProps, otherProps);
     // The wired id is owned by the primitive: a consumer-supplied id must not
     // override it, or the aria-controls pairing would silently break.
-    if (wiredId != null) {
+    if (typeof wiredId === 'string') {
       merged.id = wiredId;
     }
 
diff --git a/packages/mosaic/src/primitives/button/button.tsx b/packages/mosaic/src/primitives/button/button.tsx
index c208743de10..23001e9641c 100644
--- a/packages/mosaic/src/primitives/button/button.tsx
+++ b/packages/mosaic/src/primitives/button/button.tsx
@@ -2,7 +2,7 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 
 /** Props for {@link Button}. */
 export interface ButtonProps extends ComponentProps<'button'> {
@@ -64,7 +64,7 @@ export const Button = React.forwardRef<HTMLElement, ButtonProps>(function Button
   // button out of the tab order — the one thing `focusableWhenDisabled` exists to avoid.
   const nativelyDisabled = nativeButton && !focusableWhenDisabled;
 
-  const defaultProps: Record<string, unknown> = nativeButton
+  const defaultProps: DefaultProps<'button'> = nativeButton
     ? { type: 'button', disabled: nativelyDisabled ? disabled : undefined }
     : {
         role: 'button',
diff --git a/packages/mosaic/src/primitives/collapsible/collapsible-panel.tsx b/packages/mosaic/src/primitives/collapsible/collapsible-panel.tsx
index 60e2bb3190c..1892e6bbc1c 100644
--- a/packages/mosaic/src/primitives/collapsible/collapsible-panel.tsx
+++ b/packages/mosaic/src/primitives/collapsible/collapsible-panel.tsx
@@ -1,9 +1,9 @@
 'use client';
 
-import React from 'react';
+import React, { type CSSProperties } from 'react';
 
 import { usePanelSize } from '../hooks/use-panel-size';
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { useCollapsibleContext } from './collapsible-context';
 
 export type CollapsiblePanelProps = ComponentProps<'div'>;
@@ -17,17 +17,19 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
 
     const state = { open };
 
-    const defaultProps: Record<string, unknown> = {
+    const style: CSSProperties & Record<`--${string}`, string | undefined> = {
+      '--collapsible-panel-height': height != null ? `${height}px` : undefined,
+      '--collapsible-panel-width': width != null ? `${width}px` : undefined,
+      ...transitionProps.style,
+    };
+
+    const defaultProps = {
       id: panelId,
       role: 'region' as const,
       'aria-labelledby': triggerId,
       ...transitionProps,
-      style: {
-        '--collapsible-panel-height': height != null ? `${height}px` : undefined,
-        '--collapsible-panel-width': width != null ? `${width}px` : undefined,
-        ...transitionProps.style,
-      },
-    };
+      style,
+    } satisfies DefaultProps<'div'>;
 
     const merged = mergeProps<'div'>(defaultProps, otherProps);
     // The wired id is owned by the primitive: a consumer-supplied id must not
diff --git a/packages/mosaic/src/primitives/collapsible/collapsible-root.tsx b/packages/mosaic/src/primitives/collapsible/collapsible-root.tsx
index fb404895c4e..2874b79c7bd 100644
--- a/packages/mosaic/src/primitives/collapsible/collapsible-root.tsx
+++ b/packages/mosaic/src/primitives/collapsible/collapsible-root.tsx
@@ -3,7 +3,7 @@
 import React, { type ReactNode, useId, useMemo } from 'react';
 
 import { useControllableState } from '../hooks/use-controllable-state';
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { CollapsibleContext, type CollapsibleContextValue } from './collapsible-context';
 
 export interface CollapsibleProps extends ComponentProps<'div'> {
@@ -34,9 +34,9 @@ export const CollapsibleRoot = React.forwardRef<HTMLDivElement, CollapsibleProps
 
   const state = { open, disabled };
 
-  const defaultProps: Record<string, unknown> = {
+  const defaultProps = {
     children,
-  };
+  } satisfies DefaultProps<'div'>;
 
   return (
     <CollapsibleContext.Provider value={contextValue}>
diff --git a/packages/mosaic/src/primitives/collapsible/collapsible-trigger.tsx b/packages/mosaic/src/primitives/collapsible/collapsible-trigger.tsx
index 1dd9f526eb2..ad961ccaff7 100644
--- a/packages/mosaic/src/primitives/collapsible/collapsible-trigger.tsx
+++ b/packages/mosaic/src/primitives/collapsible/collapsible-trigger.tsx
@@ -2,7 +2,7 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { useCollapsibleContext } from './collapsible-context';
 
 export type CollapsibleTriggerProps = ComponentProps<'button'>;
@@ -14,7 +14,7 @@ export const CollapsibleTrigger = React.forwardRef<HTMLButtonElement, Collapsibl
 
     const state = { open, disabled };
 
-    const defaultProps: Record<string, unknown> = {
+    const defaultProps = {
       id: triggerId,
       type: 'button' as const,
       'aria-expanded': open,
@@ -25,7 +25,7 @@ export const CollapsibleTrigger = React.forwardRef<HTMLButtonElement, Collapsibl
           setOpen(!open);
         }
       },
-    };
+    } satisfies DefaultProps<'button'>;
 
     const merged = mergeProps<'button'>(defaultProps, otherProps);
     // The wired id is owned by the primitive: a consumer-supplied id must not
diff --git a/packages/mosaic/src/primitives/combobox/combobox-list.tsx b/packages/mosaic/src/primitives/combobox/combobox-list.tsx
index 27103ced218..0cde102f1fd 100644
--- a/packages/mosaic/src/primitives/combobox/combobox-list.tsx
+++ b/packages/mosaic/src/primitives/combobox/combobox-list.tsx
@@ -18,7 +18,7 @@ export const ComboboxList = React.forwardRef<HTMLDivElement, ComboboxListProps>(
   }, [setInlineMode]);
 
   const floatingProps = getFloatingProps();
-  const wiredId = floatingProps.id;
+  const wiredId = floatingProps['id'];
 
   const ownProps = {} satisfies DefaultProps<'div'>;
 
@@ -27,7 +27,7 @@ export const ComboboxList = React.forwardRef<HTMLDivElement, ComboboxListProps>(
   const merged = mergeProps<'div'>(defaultProps, otherProps);
   // The wired id is owned by the primitive: a consumer-supplied id must not
   // override it, or the aria-controls pairing would silently break.
-  if (wiredId != null) {
+  if (typeof wiredId === 'string') {
     merged.id = wiredId;
   }
 
diff --git a/packages/mosaic/src/primitives/combobox/combobox-positioner.tsx b/packages/mosaic/src/primitives/combobox/combobox-positioner.tsx
index 465b7d110a7..6e115601d71 100644
--- a/packages/mosaic/src/primitives/combobox/combobox-positioner.tsx
+++ b/packages/mosaic/src/primitives/combobox/combobox-positioner.tsx
@@ -29,7 +29,7 @@ export const ComboboxPositioner = React.forwardRef<HTMLDivElement, ComboboxPosit
     const side = parsePlacement(placement).side;
 
     const floatingProps = getFloatingProps();
-    const wiredId = floatingProps.id;
+    const wiredId = floatingProps['id'];
 
     const ownProps = {
       'data-side': side,
@@ -41,7 +41,7 @@ export const ComboboxPositioner = React.forwardRef<HTMLDivElement, ComboboxPosit
     const merged = mergeProps<'div'>(defaultProps, otherProps);
     // The wired id is owned by the primitive: a consumer-supplied id must not
     // override it, or the aria-controls pairing would silently break.
-    if (wiredId != null) {
+    if (typeof wiredId === 'string') {
       merged.id = wiredId;
     }
 
diff --git a/packages/mosaic/src/primitives/combobox/combobox-root.tsx b/packages/mosaic/src/primitives/combobox/combobox-root.tsx
index 39d6fd6a3ac..60f70ddec0e 100644
--- a/packages/mosaic/src/primitives/combobox/combobox-root.tsx
+++ b/packages/mosaic/src/primitives/combobox/combobox-root.tsx
@@ -122,6 +122,7 @@ function ComboboxInner(props: ComboboxProps) {
         setSelectedIndex(index);
         return () => setSelectedIndex(current => (current === index ? null : current));
       }
+      return undefined;
     },
     [selectedValue],
   );
diff --git a/packages/mosaic/src/primitives/dialog/dialog-handle.test-d.ts b/packages/mosaic/src/primitives/dialog/dialog-handle.test-d.ts
new file mode 100644
index 00000000000..90b849dd411
--- /dev/null
+++ b/packages/mosaic/src/primitives/dialog/dialog-handle.test-d.ts
@@ -0,0 +1,22 @@
+import { describe, test } from 'vitest';
+
+import { createDialogHandle } from './dialog-handle';
+
+describe('DialogHandle.open', () => {
+  test('a handle that carries a payload requires it', () => {
+    const handle = createDialogHandle<string>();
+
+    handle.open('a');
+    // @ts-expect-error -- The dialog would open about nothing
+    handle.open();
+    // @ts-expect-error -- The dialog would open about nothing
+    handle.open(undefined);
+    // @ts-expect-error -- Not the payload this handle carries
+    handle.open(1);
+  });
+
+  test('a handle with no required payload opens without one', () => {
+    createDialogHandle().open();
+    createDialogHandle<string | undefined>().open(undefined);
+  });
+});
diff --git a/packages/mosaic/src/primitives/dialog/dialog-handle.ts b/packages/mosaic/src/primitives/dialog/dialog-handle.ts
index b399b0f8c1c..704bdbf15ae 100644
--- a/packages/mosaic/src/primitives/dialog/dialog-handle.ts
+++ b/packages/mosaic/src/primitives/dialog/dialog-handle.ts
@@ -48,13 +48,13 @@ export interface DialogHandle<Payload = unknown> {
   /**
    * Opens the attached root. Ignored while no root is mounted.
    *
-   * The optional `payload` is the programmatic counterpart of a trigger's: it reaches the root's
+   * The `payload` is the programmatic counterpart of a trigger's: it reaches the root's
    * children-as-function as `{ payload }`, so an imperative open can carry the content the dialog
    * is about — what a confirmation is asking, which record is being deleted — without the caller
    * holding a second piece of state alongside `open`. A trigger-driven open supersedes it, since
    * a trigger names its own payload.
    */
-  open(payload?: Payload): void;
+  open(payload: Payload): void;
   /** Closes the attached root. Ignored while no root is mounted. */
   close(): void;
   /** Whether the attached root is open. `false` while no root is mounted. */
@@ -90,7 +90,7 @@ export interface DialogHandle<Payload = unknown> {
  * detached trigger can drive the dialog. The type parameter types the `payload` carried from
  * each trigger into the root's children render function.
  */
-export function createDialogHandle<Payload = unknown>(): DialogHandle<Payload> {
+export function createDialogHandle<Payload = void>(): DialogHandle<Payload> {
   const triggers = new Map<string, DialogTriggerRegistration<Payload>>();
   const listeners = new Set<() => void>();
   let root: DialogRootController<Payload> | null = null;
diff --git a/packages/mosaic/src/primitives/file-upload/file-upload-dropzone.tsx b/packages/mosaic/src/primitives/file-upload/file-upload-dropzone.tsx
index 30416c204e9..7c69f86eff2 100644
--- a/packages/mosaic/src/primitives/file-upload/file-upload-dropzone.tsx
+++ b/packages/mosaic/src/primitives/file-upload/file-upload-dropzone.tsx
@@ -2,7 +2,7 @@
 
 import React, { type DragEvent, useRef, useState } from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { useFileUploadContext } from './file-upload-context';
 
 export type FileUploadDropzoneProps = ComponentProps<'div'>;
@@ -19,7 +19,7 @@ export const FileUploadDropzone = React.forwardRef<HTMLDivElement, FileUploadDro
 
     const state = { dragging, disabled };
 
-    const defaultProps: Record<string, unknown> = {
+    const defaultProps = {
       'aria-disabled': disabled || undefined,
       onDragEnter: (event: DragEvent<HTMLDivElement>) => {
         event.preventDefault();
@@ -59,7 +59,7 @@ export const FileUploadDropzone = React.forwardRef<HTMLDivElement, FileUploadDro
           addFiles(files);
         }
       },
-    };
+    } satisfies DefaultProps<'div'>;
 
     return useRender({
       defaultTagName: 'div',
diff --git a/packages/mosaic/src/primitives/file-upload/file-upload-item-delete.tsx b/packages/mosaic/src/primitives/file-upload/file-upload-item-delete.tsx
index 2065ebe049b..f90fd23d85a 100644
--- a/packages/mosaic/src/primitives/file-upload/file-upload-item-delete.tsx
+++ b/packages/mosaic/src/primitives/file-upload/file-upload-item-delete.tsx
@@ -2,7 +2,7 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { useFileUploadContext, useFileUploadItemContext } from './file-upload-context';
 
 export type FileUploadItemDeleteProps = ComponentProps<'button'>;
@@ -15,7 +15,7 @@ export const FileUploadItemDelete = React.forwardRef<HTMLButtonElement, FileUplo
 
     const state = { disabled };
 
-    const defaultProps: Record<string, unknown> = {
+    const defaultProps = {
       type: 'button' as const,
       disabled,
       onClick: () => {
@@ -23,7 +23,7 @@ export const FileUploadItemDelete = React.forwardRef<HTMLButtonElement, FileUplo
           remove();
         }
       },
-    };
+    } satisfies DefaultProps<'button'>;
 
     return useRender({
       defaultTagName: 'button',
diff --git a/packages/mosaic/src/primitives/file-upload/file-upload-item-preview.tsx b/packages/mosaic/src/primitives/file-upload/file-upload-item-preview.tsx
index 0a50f345ffc..21c48de206b 100644
--- a/packages/mosaic/src/primitives/file-upload/file-upload-item-preview.tsx
+++ b/packages/mosaic/src/primitives/file-upload/file-upload-item-preview.tsx
@@ -2,7 +2,7 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { useFileUploadItemContext } from './file-upload-context';
 import { useObjectUrl } from './use-object-url';
 
@@ -20,10 +20,10 @@ export const FileUploadItemPreview = React.forwardRef<HTMLImageElement, FileUplo
     const isImage = file.type.startsWith('image/');
     const objectUrl = useObjectUrl(isImage ? file : undefined);
 
-    const defaultProps: Record<string, unknown> = {
+    const defaultProps = {
       src: objectUrl,
       alt: file.name,
-    };
+    } satisfies DefaultProps<'img'>;
 
     return useRender({
       defaultTagName: 'img',
diff --git a/packages/mosaic/src/primitives/file-upload/file-upload-item.tsx b/packages/mosaic/src/primitives/file-upload/file-upload-item.tsx
index 427a9f24175..30cb26c6db3 100644
--- a/packages/mosaic/src/primitives/file-upload/file-upload-item.tsx
+++ b/packages/mosaic/src/primitives/file-upload/file-upload-item.tsx
@@ -2,7 +2,7 @@
 
 import React, { useCallback, useMemo } from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { FileUploadItemContext, type FileUploadItemContextValue, useFileUploadContext } from './file-upload-context';
 
 export interface FileUploadItemProps extends ComponentProps<'div'> {
@@ -21,7 +21,7 @@ export const FileUploadItem = React.forwardRef<HTMLDivElement, FileUploadItemPro
 
     const state = { image: file.type.startsWith('image/') };
 
-    const defaultProps: Record<string, unknown> = {};
+    const defaultProps = {} satisfies DefaultProps<'div'>;
 
     return (
       <FileUploadItemContext.Provider value={itemContextValue}>
diff --git a/packages/mosaic/src/primitives/file-upload/file-upload-root.tsx b/packages/mosaic/src/primitives/file-upload/file-upload-root.tsx
index 0de6b77a311..16edd40ca44 100644
--- a/packages/mosaic/src/primitives/file-upload/file-upload-root.tsx
+++ b/packages/mosaic/src/primitives/file-upload/file-upload-root.tsx
@@ -3,7 +3,7 @@
 import React, { type CSSProperties, type ReactNode, useCallback, useId, useMemo, useRef } from 'react';
 
 import { useControllableState } from '../hooks/use-controllable-state';
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { isFileAccepted } from './accept';
 import { FileUploadContext, type FileUploadContextValue } from './file-upload-context';
 
@@ -136,7 +136,7 @@ export const FileUploadRoot = React.forwardRef<HTMLDivElement, FileUploadProps>(
 
   const state = { disabled, empty: files.length === 0 };
 
-  const defaultProps: Record<string, unknown> = {
+  const defaultProps = {
     children: (
       <>
         <input
@@ -164,7 +164,7 @@ export const FileUploadRoot = React.forwardRef<HTMLDivElement, FileUploadProps>(
         {children}
       </>
     ),
-  };
+  } satisfies DefaultProps<'div'>;
 
   return (
     <FileUploadContext.Provider value={contextValue}>
diff --git a/packages/mosaic/src/primitives/file-upload/file-upload-trigger.tsx b/packages/mosaic/src/primitives/file-upload/file-upload-trigger.tsx
index 82d09f58686..1628da10a03 100644
--- a/packages/mosaic/src/primitives/file-upload/file-upload-trigger.tsx
+++ b/packages/mosaic/src/primitives/file-upload/file-upload-trigger.tsx
@@ -2,7 +2,7 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { useFileUploadContext } from './file-upload-context';
 
 export type FileUploadTriggerProps = ComponentProps<'button'>;
@@ -14,11 +14,11 @@ export const FileUploadTrigger = React.forwardRef<HTMLButtonElement, FileUploadT
 
     const state = { disabled };
 
-    const defaultProps: Record<string, unknown> = {
+    const defaultProps = {
       type: 'button' as const,
       disabled,
       onClick: () => openFilePicker(),
-    };
+    } satisfies DefaultProps<'button'>;
 
     return useRender({
       defaultTagName: 'button',
diff --git a/packages/mosaic/src/primitives/flow/flow-root.tsx b/packages/mosaic/src/primitives/flow/flow-root.tsx
index b9caa9be812..04b64602f99 100644
--- a/packages/mosaic/src/primitives/flow/flow-root.tsx
+++ b/packages/mosaic/src/primitives/flow/flow-root.tsx
@@ -48,7 +48,7 @@ export const FlowRoot = React.forwardRef<HTMLDivElement, FlowRootProps>(function
       const root = rootRef.current;
       const { height } = getDimensions(activeStep);
       if (root && stepHeightRef.current !== null && height !== stepHeightRef.current) {
-        root.dataset.heightChange = height < stepHeightRef.current ? 'shrink' : 'grow';
+        root.dataset['heightChange'] = height < stepHeightRef.current ? 'shrink' : 'grow';
       }
       stepHeightRef.current = height;
       root?.style.setProperty('--cl-flow-step-height', `${height}px`);
diff --git a/packages/mosaic/src/primitives/menu/menu-positioner.tsx b/packages/mosaic/src/primitives/menu/menu-positioner.tsx
index aaf816ba4c6..2de8dbe5b50 100644
--- a/packages/mosaic/src/primitives/menu/menu-positioner.tsx
+++ b/packages/mosaic/src/primitives/menu/menu-positioner.tsx
@@ -61,8 +61,9 @@ export const MenuPositioner = React.forwardRef<HTMLDivElement, MenuPositionerPro
     const merged = mergeProps<'div'>(defaultProps, otherProps);
     // The menu id is owned by floating-ui's menu role: a consumer-supplied id must
     // not override it, or the trigger's aria-controls pairing would silently break.
-    if (floatingProps.id != null) {
-      merged.id = floatingProps.id;
+    const wiredId = floatingProps['id'];
+    if (typeof wiredId === 'string') {
+      merged.id = wiredId;
     }
 
     const element = useRender({
diff --git a/packages/mosaic/src/primitives/otp/otp-input.tsx b/packages/mosaic/src/primitives/otp/otp-input.tsx
index 8d2c3567b01..c25a41e56f2 100644
--- a/packages/mosaic/src/primitives/otp/otp-input.tsx
+++ b/packages/mosaic/src/primitives/otp/otp-input.tsx
@@ -3,7 +3,7 @@
 import React, { useCallback } from 'react';
 
 import { readingDirectionKeys, useDirection } from '../direction-provider';
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { useOtpContext } from './otp-context';
 import { inputModeForPattern, removeAt, replaceAt, sanitize } from './otp-utils';
 
@@ -51,7 +51,7 @@ export const OtpInput = React.forwardRef<HTMLInputElement, OtpInputProps>(functi
 
   const state = { active: activeIndex === index, filled: char !== '', disabled };
 
-  const defaultProps: Record<string, unknown> = {
+  const defaultProps = {
     id: getInputId(index),
     ...labelProps,
     value: char,
@@ -202,7 +202,7 @@ export const OtpInput = React.forwardRef<HTMLInputElement, OtpInputProps>(functi
       setValue(next);
       queueFocus(Math.min(index + inserted.length, length - 1), next);
     },
-  };
+  } satisfies DefaultProps<'input'>;
 
   return useRender({
     defaultTagName: 'input',
diff --git a/packages/mosaic/src/primitives/otp/otp-root.tsx b/packages/mosaic/src/primitives/otp/otp-root.tsx
index 7a7801983f5..cb174de3d19 100644
--- a/packages/mosaic/src/primitives/otp/otp-root.tsx
+++ b/packages/mosaic/src/primitives/otp/otp-root.tsx
@@ -12,7 +12,7 @@ import React, {
 } from 'react';
 
 import { useControllableState } from '../hooks/use-controllable-state';
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { type FirstInputLabel, OtpContext, type OtpContextValue, type OtpSlot } from './otp-context';
 import { inputModeForPattern, type OtpPattern, sanitize } from './otp-utils';
 
@@ -222,7 +222,7 @@ export const OtpRoot = React.forwardRef<HTMLDivElement, OtpProps>(function OtpRo
 
   const state = { disabled, complete, empty: value.length === 0 };
 
-  const defaultProps: Record<string, unknown> = {
+  const defaultProps = {
     role: 'group',
     children: (
       <>
@@ -243,7 +243,7 @@ export const OtpRoot = React.forwardRef<HTMLDivElement, OtpProps>(function OtpRo
         ) : null}
       </>
     ),
-  };
+  } satisfies DefaultProps<'div'>;
 
   return (
     <OtpContext.Provider value={contextValue}>
diff --git a/packages/mosaic/src/primitives/segmented-control/segmented-control-item.tsx b/packages/mosaic/src/primitives/segmented-control/segmented-control-item.tsx
index 297b63508eb..8c1cd692e22 100644
--- a/packages/mosaic/src/primitives/segmented-control/segmented-control-item.tsx
+++ b/packages/mosaic/src/primitives/segmented-control/segmented-control-item.tsx
@@ -3,7 +3,7 @@
 import { CompositeItem } from '@floating-ui/react';
 import React from 'react';
 
-import { type ComponentProps, isRef, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, isRef, mergeProps, useRender } from '../utils';
 import { useSegmentedControlContext } from './segmented-control-context';
 
 export interface SegmentedControlItemProps extends ComponentProps<'button'> {
@@ -27,7 +27,7 @@ export const SegmentedControlItem = React.forwardRef<HTMLButtonElement, Segmente
     return (
       <CompositeItem
         render={(compositeProps: React.HTMLAttributes<HTMLElement>) => {
-          const defaultProps: Record<string, unknown> = {
+          const defaultProps = {
             role: 'radio' as const,
             type: 'button' as const,
             'aria-checked': isSelected,
@@ -38,7 +38,7 @@ export const SegmentedControlItem = React.forwardRef<HTMLButtonElement, Segmente
                 select(itemValue);
               }
             },
-          };
+          } satisfies DefaultProps<'button'>;
 
           const merged = mergeProps<'button'>(mergeProps<'button'>(defaultProps, otherProps), compositeProps);
           const { ref: compositeRef, ...mergedProps } = merged;
diff --git a/packages/mosaic/src/primitives/segmented-control/segmented-control-root.tsx b/packages/mosaic/src/primitives/segmented-control/segmented-control-root.tsx
index a642dfa3f26..166a4ab402e 100644
--- a/packages/mosaic/src/primitives/segmented-control/segmented-control-root.tsx
+++ b/packages/mosaic/src/primitives/segmented-control/segmented-control-root.tsx
@@ -5,7 +5,7 @@ import React, { useCallback, useLayoutEffect, useMemo, useRef, useState } from '
 
 import { useDirection } from '../direction-provider';
 import { useControllableState } from '../hooks/use-controllable-state';
-import { type ComponentProps, isRef, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, isRef, mergeProps, useRender } from '../utils';
 import {
   SegmentedControlContext,
   type SegmentedControlContextValue,
@@ -79,7 +79,7 @@ export const SegmentedControlRoot = React.forwardRef<HTMLDivElement, SegmentedCo
           onNavigate={onNavigate}
           render={(compositeProps: React.HTMLAttributes<HTMLElement>) => {
             const { onKeyDown: compositeKeyDown, ...otherCompositeProps } = compositeProps;
-            const defaultProps: Record<string, unknown> = {
+            const defaultProps = {
               role: 'radiogroup' as const,
               onKeyDown: (event: React.KeyboardEvent<HTMLElement>) => {
                 navigatedIndexRef.current = -1;
@@ -97,7 +97,7 @@ export const SegmentedControlRoot = React.forwardRef<HTMLDivElement, SegmentedCo
                 }
               },
               'aria-disabled': disabled || undefined,
-            };
+            } satisfies DefaultProps<'div'>;
 
             const merged = mergeProps<'div'>(defaultProps, mergeProps<'div'>(otherProps, otherCompositeProps));
             const { ref: compositeRef, ...mergedProps } = merged;
diff --git a/packages/mosaic/src/primitives/select/select-positioner.tsx b/packages/mosaic/src/primitives/select/select-positioner.tsx
index fe86df5c76d..3943275aa25 100644
--- a/packages/mosaic/src/primitives/select/select-positioner.tsx
+++ b/packages/mosaic/src/primitives/select/select-positioner.tsx
@@ -66,8 +66,9 @@ export const SelectPositioner = React.forwardRef<HTMLDivElement, SelectPositione
     // The listbox id is owned by floating-ui's listbox role: a consumer-supplied
     // id must not override it, or the trigger's aria-controls pairing would
     // silently break.
-    if (floatingProps.id != null) {
-      merged.id = floatingProps.id;
+    const wiredId = floatingProps['id'];
+    if (typeof wiredId === 'string') {
+      merged.id = wiredId;
     }
 
     const element = useRender({
diff --git a/packages/mosaic/src/primitives/table/table-cell.tsx b/packages/mosaic/src/primitives/table/table-cell.tsx
index 82de6ec9bb6..618fa0a3f5c 100644
--- a/packages/mosaic/src/primitives/table/table-cell.tsx
+++ b/packages/mosaic/src/primitives/table/table-cell.tsx
@@ -2,7 +2,7 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { TableRowContext, useCellIndex, useTableContext } from './table-context';
 
 export type TableCellProps = ComponentProps<'td'>;
@@ -21,7 +21,7 @@ export const TableCell = React.forwardRef<HTMLTableCellElement, TableCellProps>(
     [rowHeader, registerRowHeader, id],
   );
 
-  const defaultProps: Record<string, unknown> = rowHeader ? { id, scope: 'row' } : {};
+  const defaultProps: DefaultProps<'th'> = rowHeader ? { id, scope: 'row' } : {};
 
   return useRender({
     defaultTagName: rowHeader ? 'th' : 'td',
diff --git a/packages/mosaic/src/primitives/table/table-column.tsx b/packages/mosaic/src/primitives/table/table-column.tsx
index 89a1950ec2c..a3c45445d66 100644
--- a/packages/mosaic/src/primitives/table/table-column.tsx
+++ b/packages/mosaic/src/primitives/table/table-column.tsx
@@ -2,7 +2,7 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { useCellIndex, useTableContext } from './table-context';
 import { isOwnClick } from './table-dom';
 
@@ -29,7 +29,7 @@ export const TableColumn = React.forwardRef<HTMLTableCellElement, TableColumnPro
     [rowHeader, index, registerRowHeaderColumn],
   );
 
-  const defaultProps: Record<string, unknown> = {
+  const defaultProps = {
     scope: 'col',
     ...(canSort
       ? {
@@ -47,7 +47,7 @@ export const TableColumn = React.forwardRef<HTMLTableCellElement, TableColumnPro
           },
         }
       : {}),
-  };
+  } satisfies DefaultProps<'th'>;
 
   const state = { sortable: canSort, sortDirection };
 
diff --git a/packages/mosaic/src/primitives/table/table-header.tsx b/packages/mosaic/src/primitives/table/table-header.tsx
index a43725598d5..552832aa4a4 100644
--- a/packages/mosaic/src/primitives/table/table-header.tsx
+++ b/packages/mosaic/src/primitives/table/table-header.tsx
@@ -2,7 +2,7 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { TableHeaderContext, useTableContext } from './table-context';
 
 export type TableHeaderProps = ComponentProps<'thead'>;
@@ -12,9 +12,9 @@ export const TableHeader = React.forwardRef<HTMLTableSectionElement, TableHeader
     const { render, children, ...otherProps } = props;
     useTableContext();
 
-    const defaultProps: Record<string, unknown> = {
+    const defaultProps = {
       children: <tr>{children}</tr>,
-    };
+    } satisfies DefaultProps<'thead'>;
 
     return (
       <TableHeaderContext.Provider value>
diff --git a/packages/mosaic/src/primitives/table/table-root.tsx b/packages/mosaic/src/primitives/table/table-root.tsx
index 11a9935de90..13a6624e770 100644
--- a/packages/mosaic/src/primitives/table/table-root.tsx
+++ b/packages/mosaic/src/primitives/table/table-root.tsx
@@ -3,7 +3,7 @@
 import React from 'react';
 
 import { useControllableState } from '../hooks/use-controllable-state';
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import {
   type TableBodyRows,
   TableContext,
@@ -140,7 +140,7 @@ export const TableRoot = React.forwardRef<HTMLTableElement, TableRootProps>(func
     excludeFromNavigation,
   };
 
-  const defaultProps: Record<string, unknown> = {
+  const defaultProps = {
     role: tree ? 'treegrid' : interactive ? 'grid' : undefined,
     'aria-multiselectable': selectionMode === 'multiple' || undefined,
     onKeyDown: (event: React.KeyboardEvent<HTMLTableElement>) => {
@@ -167,7 +167,7 @@ export const TableRoot = React.forwardRef<HTMLTableElement, TableRootProps>(func
         }
       }
     },
-  };
+  } satisfies DefaultProps<'table'>;
 
   return (
     <TableContext.Provider value={contextValue}>
diff --git a/packages/mosaic/src/primitives/table/table-row.tsx b/packages/mosaic/src/primitives/table/table-row.tsx
index 05bdaf29324..eda49480f18 100644
--- a/packages/mosaic/src/primitives/table/table-row.tsx
+++ b/packages/mosaic/src/primitives/table/table-row.tsx
@@ -1,8 +1,8 @@
 'use client';
 
-import React from 'react';
+import React, { type CSSProperties } from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { TableRowContext, type TableRowContextValue, useTableContext, useTableItem } from './table-context';
 import { focusIsInChildRows, isOwnClick, isRtl, openLink, type TableLink } from './table-dom';
 
@@ -62,7 +62,9 @@ export const TableRow = React.forwardRef<HTMLTableRowElement, TableRowProps>(fun
     }
   };
 
-  const defaultProps: Record<string, unknown> = {
+  const style: CSSProperties & Record<`--${string}`, number> = { '--table-row-depth': item.depth };
+
+  const defaultProps = {
     'aria-labelledby': rowHeaderIds,
     'aria-selected': canSelect ? selected : undefined,
     'aria-disabled': disabled || undefined,
@@ -74,7 +76,7 @@ export const TableRow = React.forwardRef<HTMLTableRowElement, TableRowProps>(fun
           'aria-expanded': canExpand ? expanded : undefined,
         }
       : {}),
-    style: { '--table-row-depth': item.depth },
+    style,
     onClick: (event: React.MouseEvent<HTMLTableRowElement>) => {
       if (disabled || !isOwnClick(event)) {
         return;
@@ -112,7 +114,7 @@ export const TableRow = React.forwardRef<HTMLTableRowElement, TableRowProps>(fun
         }
       }
     },
-  };
+  } satisfies DefaultProps<'tr'>;
 
   const rowContext: TableRowContextValue = {
     disabled,
diff --git a/packages/mosaic/src/primitives/tabs/tabs-list.tsx b/packages/mosaic/src/primitives/tabs/tabs-list.tsx
index 6abe1a2f349..191d0d9f844 100644
--- a/packages/mosaic/src/primitives/tabs/tabs-list.tsx
+++ b/packages/mosaic/src/primitives/tabs/tabs-list.tsx
@@ -4,7 +4,7 @@ import { Composite } from '@floating-ui/react';
 import React from 'react';
 
 import { useDirection } from '../direction-provider';
-import { type ComponentProps, isRef, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, isRef, mergeProps, useRender } from '../utils';
 import { useTabsContext } from './tabs-context';
 
 export type TabsListProps = ComponentProps<'div'>;
@@ -19,7 +19,7 @@ export const TabsList = React.forwardRef<HTMLDivElement, TabsListProps>(function
       orientation={orientation}
       rtl={orientation === 'horizontal' && direction === 'rtl'}
       render={(compositeProps: React.HTMLAttributes<HTMLElement>) => {
-        const defaultProps: Record<string, unknown> = {
+        const defaultProps = {
           role: 'tablist' as const,
           onKeyDown: (event: React.KeyboardEvent<HTMLElement>) => {
             if (event.key !== 'Home' && event.key !== 'End') {
@@ -29,7 +29,7 @@ export const TabsList = React.forwardRef<HTMLDivElement, TabsListProps>(function
             const items = Array.from(event.currentTarget.querySelectorAll<HTMLElement>('[role="tab"]:not([disabled])'));
             (event.key === 'Home' ? items.at(0) : items.at(-1))?.focus();
           },
-        };
+        } satisfies DefaultProps<'div'>;
 
         const merged = mergeProps<'div'>(defaultProps, mergeProps<'div'>(otherProps, compositeProps));
 
diff --git a/packages/mosaic/src/primitives/tabs/tabs-tab.tsx b/packages/mosaic/src/primitives/tabs/tabs-tab.tsx
index 0d16f583948..d03f2ea5085 100644
--- a/packages/mosaic/src/primitives/tabs/tabs-tab.tsx
+++ b/packages/mosaic/src/primitives/tabs/tabs-tab.tsx
@@ -3,7 +3,7 @@
 import { CompositeItem } from '@floating-ui/react';
 import React, { useCallback } from 'react';
 
-import { type ComponentProps, isRef, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, isRef, mergeProps, useRender } from '../utils';
 import { useTabsContext } from './tabs-context';
 
 export interface TabsTabProps extends ComponentProps<'button'> {
@@ -33,10 +33,10 @@ export const TabsTab = React.forwardRef<HTMLButtonElement, TabsTabProps>(functio
       ref={register}
       disabled={disabled}
       render={(compositeProps: React.HTMLAttributes<HTMLElement>) => {
-        const defaultProps: Record<string, unknown> = {
+        const defaultProps: DefaultProps<'button'> = {
           id: tabId,
-          role: 'tab' as const,
-          type: 'button' as const,
+          role: 'tab',
+          type: 'button',
           'aria-selected': isSelected,
           'aria-controls': panelId,
           'aria-disabled': disabled || undefined,
diff --git a/packages/mosaic/src/primitives/tag-input/tag-input-input.tsx b/packages/mosaic/src/primitives/tag-input/tag-input-input.tsx
index 1825da38a4c..06ab56b7dd7 100644
--- a/packages/mosaic/src/primitives/tag-input/tag-input-input.tsx
+++ b/packages/mosaic/src/primitives/tag-input/tag-input-input.tsx
@@ -3,7 +3,7 @@
 import React, { useState } from 'react';
 
 import { readingDirectionKeys, useDirection } from '../direction-provider';
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { useTagInputContext } from './tag-input-context';
 import { splitTags } from './tag-input-utils';
 
@@ -21,7 +21,7 @@ export const TagInputInput = React.forwardRef<HTMLInputElement, TagInputInputPro
       setText('');
     };
 
-    const defaultProps: Record<string, unknown> = {
+    const defaultProps = {
       type: 'text',
       value: text,
       disabled,
@@ -61,7 +61,7 @@ export const TagInputInput = React.forwardRef<HTMLInputElement, TagInputInputPro
           focusTag(value[value.length - 1]);
         }
       },
-    };
+    } satisfies DefaultProps<'input'>;
 
     return useRender({
       defaultTagName: 'input',
diff --git a/packages/mosaic/src/primitives/tag-input/tag-input-root.tsx b/packages/mosaic/src/primitives/tag-input/tag-input-root.tsx
index 0b01bbddcbe..65c5f3cfb71 100644
--- a/packages/mosaic/src/primitives/tag-input/tag-input-root.tsx
+++ b/packages/mosaic/src/primitives/tag-input/tag-input-root.tsx
@@ -3,7 +3,7 @@
 import React, { type ReactNode, useCallback, useMemo, useRef, useState } from 'react';
 
 import { useControllableState } from '../hooks/use-controllable-state';
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import {
   type FocusAfterRemove,
   TagInputContext,
@@ -150,7 +150,7 @@ export const TagInputRoot = React.forwardRef<HTMLDivElement, TagInputProps>(func
 
   const state = { disabled, empty: value.length === 0 };
 
-  const defaultProps: Record<string, unknown> = {
+  const defaultProps = {
     onMouseDown: (event: React.MouseEvent<HTMLDivElement>) => {
       if (disabled || !(event.target instanceof Element) || event.target.closest('input, [role="listitem"]')) {
         return;
@@ -175,7 +175,7 @@ export const TagInputRoot = React.forwardRef<HTMLDivElement, TagInputProps>(func
           : null}
       </>
     ),
-  };
+  } satisfies DefaultProps<'div'>;
 
   return (
     <TagInputContext.Provider value={contextValue}>
diff --git a/packages/mosaic/src/primitives/tag-input/tag-input-tag-remove.tsx b/packages/mosaic/src/primitives/tag-input/tag-input-tag-remove.tsx
index 5e5bacb8f8f..216b8f5aad8 100644
--- a/packages/mosaic/src/primitives/tag-input/tag-input-tag-remove.tsx
+++ b/packages/mosaic/src/primitives/tag-input/tag-input-tag-remove.tsx
@@ -2,7 +2,7 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { useTagInputContext, useTagValue } from './tag-input-context';
 
 export type TagInputTagRemoveProps = ComponentProps<'button'>;
@@ -13,7 +13,7 @@ export const TagInputTagRemove = React.forwardRef<HTMLButtonElement, TagInputTag
     const { disabled, remove } = useTagInputContext();
     const tagValue = useTagValue();
 
-    const defaultProps: Record<string, unknown> = {
+    const defaultProps = {
       type: 'button',
       tabIndex: -1,
       disabled,
@@ -23,7 +23,7 @@ export const TagInputTagRemove = React.forwardRef<HTMLButtonElement, TagInputTag
           remove(tagValue, 'input');
         }
       },
-    };
+    } satisfies DefaultProps<'button'>;
 
     return useRender({
       defaultTagName: 'button',
diff --git a/packages/mosaic/src/primitives/tag-input/tag-input-tag.tsx b/packages/mosaic/src/primitives/tag-input/tag-input-tag.tsx
index bb863a7194f..348551e4dad 100644
--- a/packages/mosaic/src/primitives/tag-input/tag-input-tag.tsx
+++ b/packages/mosaic/src/primitives/tag-input/tag-input-tag.tsx
@@ -5,7 +5,7 @@ import React, { useCallback, useEffect, useRef } from 'react';
 
 import { readingDirectionKeys, useDirection } from '../direction-provider';
 import { useTransition } from '../hooks/use-transition';
-import { type ComponentProps, mergeProps, useRender } from '../utils';
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../utils';
 import { TagContext, useTagInputContext } from './tag-input-context';
 
 export interface TagInputTagProps extends ComponentProps<'div'> {
@@ -42,7 +42,7 @@ export const TagInputTag = React.forwardRef<HTMLDivElement, TagInputTagProps>(
 
     const state = { invalid, disabled };
 
-    const defaultProps: Record<string, unknown> = {
+    const defaultProps = {
       ...transitionProps,
       ...inertProps(!present),
       role: 'listitem',
@@ -89,7 +89,7 @@ export const TagInputTag = React.forwardRef<HTMLDivElement, TagInputTagProps>(
             return;
         }
       },
-    };
+    } satisfies DefaultProps<'div'>;
 
     const element = useRender({
       defaultTagName: 'div',
diff --git a/packages/mosaic/src/primitives/tooltip/tooltip-positioner.tsx b/packages/mosaic/src/primitives/tooltip/tooltip-positioner.tsx
index ace27959be9..f7740bb32a2 100644
--- a/packages/mosaic/src/primitives/tooltip/tooltip-positioner.tsx
+++ b/packages/mosaic/src/primitives/tooltip/tooltip-positioner.tsx
@@ -15,7 +15,7 @@ export const TooltipPositioner = React.forwardRef<HTMLDivElement, TooltipPositio
 
     const side = parsePlacement(placement).side;
     const floatingProps = getFloatingProps();
-    const wiredId = floatingProps.id;
+    const wiredId = floatingProps['id'];
 
     const ownProps = {
       'data-side': side,
@@ -27,7 +27,7 @@ export const TooltipPositioner = React.forwardRef<HTMLDivElement, TooltipPositio
     const merged = mergeProps<'div'>(defaultProps, otherProps);
     // The wired id is owned by floating-ui: it pairs with the trigger's aria-describedby.
     // A consumer-supplied id must not override it, or the aria pairing would silently break.
-    merged.id = wiredId;
+    merged.id = typeof wiredId === 'string' ? wiredId : undefined;
 
     return useRender({
       defaultTagName: 'div',
diff --git a/packages/mosaic/src/primitives/utils/css-vars.ts b/packages/mosaic/src/primitives/utils/css-vars.ts
index 4bae8fe31dd..61b27aa9ef4 100644
--- a/packages/mosaic/src/primitives/utils/css-vars.ts
+++ b/packages/mosaic/src/primitives/utils/css-vars.ts
@@ -31,7 +31,7 @@ export function cssVars(opts?: { sideOffset?: SideOffset }): Middleware {
       const side = parsePlacement(placement).side;
 
       // A middleware that already capped the popup (select alignment) owns the height.
-      const alignedHeight = cappedHeight(middlewareData.alignSelectedItem);
+      const alignedHeight = cappedHeight(middlewareData['alignSelectedItem']);
       const availableHeight =
         alignedHeight !== undefined
           ? alignedHeight
diff --git a/packages/mosaic/src/primitives/utils/use-render.test-d.ts b/packages/mosaic/src/primitives/utils/use-render.test-d.ts
index 051fe2eaad4..56356a97a30 100644
--- a/packages/mosaic/src/primitives/utils/use-render.test-d.ts
+++ b/packages/mosaic/src/primitives/utils/use-render.test-d.ts
@@ -2,6 +2,7 @@ import type React from 'react';
 import { describe, expectTypeOf, test } from 'vitest';
 
 import type { ComponentProps, RenderProps } from './use-render';
+import { mergeProps } from './use-render';
 
 type RenderFn<Tag extends keyof React.JSX.IntrinsicElements> = Extract<
   NonNullable<ComponentProps<Tag>['render']>,
@@ -12,6 +13,16 @@ type RenderArg<Tag extends keyof React.JSX.IntrinsicElements> =
 type HasColor<P> = 'color' extends keyof P ? true : false;
 
 describe('use-render', () => {
+  test('the merged props are those of the tag', () => {
+    const merged = mergeProps<'button'>({ id: 'a' }, {});
+
+    expectTypeOf(merged.disabled).toEqualTypeOf<boolean | undefined>();
+    // @ts-expect-error -- Not a button prop
+    merged.onClik = () => {};
+    // @ts-expect-error -- Not a handler
+    merged.onClick = 1;
+  });
+
   test('a part keeps its own tag props', () => {
     expectTypeOf<ComponentProps<'button'>>().toExtend<{ type?: 'button' | 'submit' | 'reset' }>();
   });
diff --git a/packages/mosaic/src/primitives/utils/use-render.test.tsx b/packages/mosaic/src/primitives/utils/use-render.test.tsx
index b8c710dd894..a7ee3e88419 100644
--- a/packages/mosaic/src/primitives/utils/use-render.test.tsx
+++ b/packages/mosaic/src/primitives/utils/use-render.test.tsx
@@ -74,7 +74,7 @@ describe('mergeProps', () => {
     { key: 'style', value: { color: 'red' }, empty: null },
   ])('keeps the first argument $key when the second passes $empty', ({ key, value, empty }) => {
     const result = mergeProps<'button'>({ [key]: value }, { [key]: empty });
-    expect(result[key]).toBe(value);
+    expect(result).toHaveProperty(key, value);
   });
 
   it('lets the second argument clear an event handler with null', () => {
diff --git a/packages/mosaic/src/primitives/utils/use-render.tsx b/packages/mosaic/src/primitives/utils/use-render.tsx
index efc1f0b5cab..884e8296db8 100644
--- a/packages/mosaic/src/primitives/utils/use-render.tsx
+++ b/packages/mosaic/src/primitives/utils/use-render.tsx
@@ -86,7 +86,7 @@ type PropsInput<Tag extends keyof React.JSX.IntrinsicElements> =
 export function mergeProps<Tag extends keyof React.JSX.IntrinsicElements>(
   a: PropsInput<Tag>,
   b: PropsInput<Tag>,
-): Record<string, unknown>;
+): DefaultProps<Tag>;
 export function mergeProps(a: Record<string, unknown>, b: Record<string, unknown>): Record<string, unknown> {
   const merged: Record<string, unknown> = { ...a };
 
diff --git a/packages/mosaic/tsconfig.json b/packages/mosaic/tsconfig.json
index 4fea51f7fad..8dbc7015d31 100644
--- a/packages/mosaic/tsconfig.json
+++ b/packages/mosaic/tsconfig.json
@@ -3,6 +3,11 @@
   "compilerOptions": {
     "rootDir": "src",
     "noUncheckedIndexedAccess": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noUnusedParameters": true,
     "outDir": "dist",
     "declaration": true,
     "declarationMap": true

From 0cba25a86807ce81a8f6b2a0a0d1a0529628be56 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Mon, 2 Nov 2026 12:59:06 -0500
Subject: [PATCH 2/2] fix(mosaic): address review feedback on machine and
 mergeProps types

---
 packages/mosaic/eslint/import-guards.test.mjs |  9 +++++
 packages/mosaic/eslint/rules.mjs              | 15 +++++++-
 packages/mosaic/src/machine/setup.ts          |  1 +
 packages/mosaic/src/machine/types.test-d.ts   | 38 +++++++++++++++++++
 .../src/primitives/utils/use-render.test-d.ts | 11 ++++++
 .../src/primitives/utils/use-render.test.tsx  |  1 +
 .../src/primitives/utils/use-render.tsx       | 10 +++--
 7 files changed, 80 insertions(+), 5 deletions(-)

diff --git a/packages/mosaic/eslint/import-guards.test.mjs b/packages/mosaic/eslint/import-guards.test.mjs
index a06c132093e..491a33bc007 100644
--- a/packages/mosaic/eslint/import-guards.test.mjs
+++ b/packages/mosaic/eslint/import-guards.test.mjs
@@ -365,6 +365,15 @@ describe('Mosaic machines', { timeout: 30_000 }, () => {
     ).toEqual(['Write invoke with fromPromise from setup(), so onDone sees the typed output instead of any.']);
   });
 
+  test.each([
+    ['a quoted src key', 'export const state = { invoke: { "src": () => Promise.resolve(1) } };'],
+    ['a quoted invoke key', 'export const state = { "invoke": { src: () => Promise.resolve(1) } };'],
+    ['an as cast', 'export const state = { invoke: { src: () => Promise.resolve(1) } as object };'],
+    ['satisfies', 'export const state = { invoke: { src: () => Promise.resolve(1) } satisfies object };'],
+  ])('rejects a raw invoke written with %s', async (_name, source) => {
+    expect(await rawInvokeMessages(`${featureDir}/sample.controller.ts`, source)).toHaveLength(1);
+  });
+
   test('allows an invoke from fromPromise', async () => {
     expect(
       await rawInvokeMessages(
diff --git a/packages/mosaic/eslint/rules.mjs b/packages/mosaic/eslint/rules.mjs
index 26dd217cefd..4b8ec13fb60 100644
--- a/packages/mosaic/eslint/rules.mjs
+++ b/packages/mosaic/eslint/rules.mjs
@@ -279,8 +279,19 @@ export const noRawInvoke = {
   },
   create(context) {
     return {
-      'Property[key.name="invoke"] > ObjectExpression:has(> Property[key.name="src"])'(node) {
-        context.report({ node, messageId: 'useFromPromise' });
+      Property(node) {
+        if (propertyName(node.key, node.computed) !== 'invoke') {
+          return;
+        }
+        const invoke = unwrapExpression(node.value);
+        if (
+          invoke.type === 'ObjectExpression' &&
+          invoke.properties.some(
+            property => property.type === 'Property' && propertyName(property.key, property.computed) === 'src',
+          )
+        ) {
+          context.report({ node: invoke, messageId: 'useFromPromise' });
+        }
       },
     };
   },
diff --git a/packages/mosaic/src/machine/setup.ts b/packages/mosaic/src/machine/setup.ts
index 3dd4d8e9d1e..a0e0c8fec2e 100644
--- a/packages/mosaic/src/machine/setup.ts
+++ b/packages/mosaic/src/machine/setup.ts
@@ -89,4 +89,5 @@ type InferredTransition<TContext, TEvent extends EventObject, TStates extends st
   | `${TStates}`
   | { target: TStates }
   | { target: TStates }[]
+  | ((args: { context: TContext; event: TEvent }) => { target?: TStates; context?: Partial<TContext> } | undefined)
   | Transition<TContext, TEvent, TStates>;
diff --git a/packages/mosaic/src/machine/types.test-d.ts b/packages/mosaic/src/machine/types.test-d.ts
index 6cbe3fc5470..c63e23568a6 100644
--- a/packages/mosaic/src/machine/types.test-d.ts
+++ b/packages/mosaic/src/machine/types.test-d.ts
@@ -494,6 +494,44 @@ describe('setup.fromPromise — e.output is typed from src return type', () => {
     });
   });
 
+  test('a function transition is checked against the machine it joins', () => {
+    const known = { invoke: fromPromise(fakeFetch, { onDone: () => ({ target: 'idle' }) }) };
+    const stays = { invoke: fromPromise(fakeFetch, { onError: () => ({ context: { error: 'failed' } }) }) };
+    const unhandled = { invoke: fromPromise(fakeFetch, { onDone: () => undefined }) };
+    const unknownTarget = { invoke: fromPromise(fakeFetch, { onDone: () => ({ target: 'nope' }) }) };
+
+    make2({
+      initial: 'idle',
+      context: { url: '', data: null, error: null },
+      states: {
+        idle: {},
+        known,
+        stays,
+        unhandled,
+        // @ts-expect-error — 'nope' is not a state
+        unknownTarget,
+      },
+    });
+  });
+
+  test('an inline function transition sees the typed output', () => {
+    make2({
+      initial: 'idle',
+      context: { url: '', data: null, error: null },
+      states: {
+        idle: {
+          invoke: fromPromise(fakeFetch, {
+            onDone: ({ event }) => {
+              expectTypeOf(event.output).toEqualTypeOf<FetchResult>();
+              return { target: 'done' };
+            },
+          }),
+        },
+        done: {},
+      },
+    });
+  });
+
   test('the machine keeps its state names as a union', () => {
     const fetching = make2({
       initial: 'idle',
diff --git a/packages/mosaic/src/primitives/utils/use-render.test-d.ts b/packages/mosaic/src/primitives/utils/use-render.test-d.ts
index 56356a97a30..788fb57aef7 100644
--- a/packages/mosaic/src/primitives/utils/use-render.test-d.ts
+++ b/packages/mosaic/src/primitives/utils/use-render.test-d.ts
@@ -23,6 +23,17 @@ describe('use-render', () => {
     merged.onClick = 1;
   });
 
+  test('data attributes keep the typed result', () => {
+    expectTypeOf(mergeProps<'div'>({ 'data-open': '' }, {}).id).toEqualTypeOf<string | undefined>();
+  });
+
+  test('values that are not props of the tag are rejected', () => {
+    // @ts-expect-error -- Not a handler
+    mergeProps<'button'>({}, { onClick: 1 });
+    // @ts-expect-error -- Not a button prop
+    mergeProps<'button'>({}, { onClik: () => {} });
+  });
+
   test('a part keeps its own tag props', () => {
     expectTypeOf<ComponentProps<'button'>>().toExtend<{ type?: 'button' | 'submit' | 'reset' }>();
   });
diff --git a/packages/mosaic/src/primitives/utils/use-render.test.tsx b/packages/mosaic/src/primitives/utils/use-render.test.tsx
index a7ee3e88419..e681e959a8b 100644
--- a/packages/mosaic/src/primitives/utils/use-render.test.tsx
+++ b/packages/mosaic/src/primitives/utils/use-render.test.tsx
@@ -78,6 +78,7 @@ describe('mergeProps', () => {
   });
 
   it('lets the second argument clear an event handler with null', () => {
+    // @ts-expect-error -- Props don't type a handler as null; this pins the runtime behavior
     const result = mergeProps<'button'>({ onClick: () => {} }, { onClick: null });
     expect(result.onClick).toBeNull();
   });
diff --git a/packages/mosaic/src/primitives/utils/use-render.tsx b/packages/mosaic/src/primitives/utils/use-render.tsx
index 884e8296db8..dac75b6f0b7 100644
--- a/packages/mosaic/src/primitives/utils/use-render.tsx
+++ b/packages/mosaic/src/primitives/utils/use-render.tsx
@@ -74,7 +74,7 @@ export type StateAttributesMapping<S> = {
 
 type PropsInput<Tag extends keyof React.JSX.IntrinsicElements> =
   | React.ComponentPropsWithRef<Tag>
-  | Record<string, unknown>;
+  | (React.ComponentPropsWithRef<Tag> & Record<`data-${string}`, string | undefined>);
 
 /**
  * Merges two props objects. Event handlers are chained (both fire),
@@ -88,6 +88,10 @@ export function mergeProps<Tag extends keyof React.JSX.IntrinsicElements>(
   b: PropsInput<Tag>,
 ): DefaultProps<Tag>;
 export function mergeProps(a: Record<string, unknown>, b: Record<string, unknown>): Record<string, unknown> {
+  return mergeRecords(a, b);
+}
+
+function mergeRecords(a: Record<string, unknown>, b: Record<string, unknown>): Record<string, unknown> {
   const merged: Record<string, unknown> = { ...a };
 
   for (const key of Object.keys(b)) {
@@ -263,9 +267,9 @@ export function useRender<
   }
 
   if (React.isValidElement(render)) {
-    // SAFETY: `@types/react` types element `props` as `unknown`; mergeProps reads it
+    // SAFETY: `@types/react` types element `props` as `unknown`; mergeRecords reads it
     // as an untyped bag of props, which is exactly what a cloned element carries.
-    const merged = mergeProps<Tag>(computedProps, render.props as Record<string, unknown>);
+    const merged = mergeRecords(computedProps, render.props as Record<string, unknown>);
     // SAFETY: cloneElement's prop type omits `ref`, but React re-associates a ref passed
     // here at runtime (base-ui clones render elements the same way). Asserting the element's
     // props as an untyped bag lets the merged props + ref through the index signature.