Merge branch 'main' into fix/cc-recipient-order-last

Adds a dedicated self-hosting page documenting how to apply an
Enterprise license key, and cross-links it from the related docs.

New page: self-hosting/configuration/license.mdx — "Apply Your License
Key"
Set NEXT_PRIVATE_DOCUMENSO_LICENSE_KEY (Docker Compose / docker run /
.env tabs)

apps/docs/content/docs/policies/enterprise-edition.mdx

@@ -76,6 +76,8 @@ The Enterprise Edition is required when you:
     4. Restart your Documenso instance
     5. Verify the license is active in the **Admin Panel** under the **Stats** section
 
+    See [Apply Your License Key](/docs/self-hosting/configuration/license) for the full walkthrough, including how to enable individual features once licensed.
+
   </Accordion>
 </Accordions>
 
@@ -197,7 +199,7 @@ See [Support](/docs/policies/support) for complete support options.
     1. Sign the Enterprise license agreement
     2. Receive license key and access credentials
     3. Deploy using [self-hosting guides](/docs/self-hosting) or access Documenso Cloud
-    4. Configure Enterprise features with support assistance
+    4. Apply the key — see [Apply Your License Key](/docs/self-hosting/configuration/license) — and configure Enterprise features with support assistance
 
   </Step>
   <Step>
@@ -238,6 +240,7 @@ See [Support](/docs/policies/support) for complete support options.
 
 ## Related
 
+- [Apply Your License Key](/docs/self-hosting/configuration/license) - Step-by-step license activation
 - [Community Edition](/docs/policies/community-edition) - AGPL-3.0 open-source license
 - [Licenses](/docs/policies/licenses) - Complete licensing overview and FAQ
 - [Support](/docs/policies/support) - Support channels and response times

apps/docs/content/docs/self-hosting/configuration/environment.mdx

@@ -443,11 +443,11 @@ Telemetry collects only: app version, installation ID, and node ID. No personal
 
 ## Enterprise Features
 
-These variables require an active [Enterprise Edition](/docs/policies/enterprise-edition) license. Obtain a license key from [license.documenso.com](https://license.documenso.com) and set it below to unlock enterprise features such as SSO, embed editor, and 21 CFR Part 11 compliance.
+These variables require an active [Enterprise Edition](/docs/policies/enterprise-edition) license. Obtain a license key from [license.documenso.com](https://license.documenso.com) and set it below to unlock enterprise features such as SSO, embed editor, and 21 CFR Part 11 compliance. See [Apply Your License Key](/docs/self-hosting/configuration/license) for step-by-step setup.
 
 | Variable                             | Description                                      |
 | ------------------------------------ | ------------------------------------------------ |
-| `NEXT_PRIVATE_DOCUMENSO_LICENSE_KEY` | License key for enterprise features              |
+| `NEXT_PRIVATE_DOCUMENSO_LICENSE_KEY` | License key for enterprise features — see [Apply Your License Key](/docs/self-hosting/configuration/license) for how to apply it |
 | `NEXT_PRIVATE_STRIPE_API_KEY`        | Stripe API key for billing                       |
 | `NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET` | Stripe webhook secret                            |
 | `NEXT_PRIVATE_SES_ACCESS_KEY_ID`     | AWS SES access key for email domain verification |

apps/docs/content/docs/self-hosting/configuration/license.mdx

@@ -0,0 +1,107 @@
+---
+title: Apply Your License Key
+description: Activate your Enterprise license key to unlock enterprise features on your self-hosted instance.
+---
+
+import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+A license key activates the Enterprise features available to your self-hosted instance, such as CSC signing, SSO, embed white-labelling, and 21 CFR Part 11 compliance.
+
+<Callout type="info">
+  The license key applies to your **whole instance**, not an individual user account. There's one
+  key per deployment.
+</Callout>
+
+## Prerequisites
+
+- An active Enterprise license key — contact [sales](https://documen.so/enterprise) to set up an
+  Enterprise subscription, then copy your key from [license.documenso.com](https://license.documenso.com).
+  See [Enterprise Edition](/docs/policies/enterprise-edition) for details.
+- A running self-hosted Documenso instance that you're able to restart
+
+## Step 1: Set the environment variable
+
+Set `NEXT_PRIVATE_DOCUMENSO_LICENSE_KEY` to your license key.
+
+<Tabs items={['Docker Compose', 'docker run', '.env']}>
+<Tab value="Docker Compose">
+
+Add the variable to your `.env` file (or directly under `environment:` in `compose.yml`):
+
+```bash
+NEXT_PRIVATE_DOCUMENSO_LICENSE_KEY=your-license-key-here
+```
+
+Then apply it:
+
+```bash
+docker compose up -d
+```
+
+</Tab>
+<Tab value="docker run">
+
+```bash
+docker run -d \
+  --name documenso \
+  -e NEXT_PRIVATE_DOCUMENSO_LICENSE_KEY=your-license-key-here \
+  documenso/documenso:latest
+```
+
+</Tab>
+<Tab value=".env">
+
+If you're running Documenso directly (not in a container), add the variable to your `.env` file:
+
+```bash
+NEXT_PRIVATE_DOCUMENSO_LICENSE_KEY=your-license-key-here
+```
+
+</Tab>
+</Tabs>
+
+## Step 2: Restart the instance
+
+The license key is only read once, at process startup. Setting the variable in a running container or shell has no effect until the process restarts.
+
+```bash
+# Docker Compose
+docker compose restart documenso
+
+# Docker
+docker restart documenso
+```
+
+On startup, Documenso validates the key against the Documenso license server and caches the result locally for future startups, so a brief license-server outage won't lock you out.
+
+## What the license enables
+
+A valid license doesn't turn every enterprise feature on everywhere — activation depends on the feature:
+
+- **CSC signing** activates instance-wide automatically once the license is active and CSC transport is configured. See [CSC / QES Signing](/docs/self-hosting/configuration/signing-certificate/csc-qes) for the full setup.
+- **SSO, embed white-labelling, 21 CFR Part 11, and similar** are provisioned per organisation. Follow each feature's own guide to configure it once the license is active.
+
+## Troubleshooting
+
+<Accordions type="multiple">
+  <Accordion title="Enterprise features are still unavailable after applying the key">
+    - Confirm the key is present in the environment the running process actually reads — `docker
+      exec` into the container and check `env | grep LICENSE` if unsure.
+    - Confirm the instance was fully restarted after the variable was set, not just reloaded.
+    - Re-copy the key to rule out truncation or accidental whitespace.
+  </Accordion>
+  <Accordion title="A specific feature still isn't working">
+    Instance-wide features (like CSC signing) also need their own configuration — an active license
+    alone isn't enough. Check that feature's guide to confirm the required settings are in place.
+    Per-organisation features additionally need to be provisioned for the organisation that's using
+    them.
+  </Accordion>
+</Accordions>
+
+## See Also
+
+- [Environment Variables](/docs/self-hosting/configuration/environment) - Complete configuration reference
+- [Enterprise Edition](/docs/policies/enterprise-edition) - What's included and how to purchase a license
+- [CSC / QES Signing](/docs/self-hosting/configuration/signing-certificate/csc-qes) - Enable CSC-based signing

apps/docs/content/docs/self-hosting/configuration/meta.json

@@ -2,6 +2,7 @@
   "title": "Configuration",
   "pages": [
     "environment",
+    "license",
     "database",
     "email",
     "storage",

apps/docs/content/docs/self-hosting/configuration/signing-certificate/csc-qes.mdx

@@ -49,7 +49,7 @@ The callback URL is fixed — Documenso derives it from `NEXT_PUBLIC_WEBAPP_URL`
 
 ### Enterprise Edition license
 
-CSC mode is gated by the `instanceCscSigning` license flag. Without a valid Enterprise license, the transport refuses to start (`CSC_UNLICENSED`).
+CSC mode is gated by the `instanceCscSigning` license flag. Without a valid Enterprise license, the transport refuses to start (`CSC_UNLICENSED`). See [Apply Your License Key](/docs/self-hosting/configuration/license) to activate one.
 
 </Step>
 <Step>

apps/docs/content/docs/self-hosting/index.mdx

@@ -141,7 +141,7 @@ See the [Quick Start guide](/docs/self-hosting/getting-started/quick-start) for
 
 Self-hosted Documenso includes full core functionality under the AGPL-3.0 license. If you need enterprise features such as SSO, embed editor white label, or 21 CFR Part 11 compliance, you can activate them with a license key.
 
-See [Enterprise Edition](/docs/policies/enterprise-edition) for details and [Licenses](/docs/policies/licenses) for a comparison.
+See [Enterprise Edition](/docs/policies/enterprise-edition) for details and [Licenses](/docs/policies/licenses) for a comparison. Already have a key? See [Apply Your License Key](/docs/self-hosting/configuration/license).
 
 ---
 

apps/remix/app/components/general/envelope-editor/envelope-editor-recipient-form.tsx

@@ -7,7 +7,12 @@ import { useOptionalSession } from '@documenso/lib/client-only/providers/session
 import type { TDetectedRecipientSchema } from '@documenso/lib/server-only/ai/envelope/detect-recipients/schema';
 import { ZRecipientAuthOptionsSchema } from '@documenso/lib/types/document-auth';
 import { nanoid } from '@documenso/lib/universal/id';
-import { canRecipientBeModified as utilCanRecipientBeModified } from '@documenso/lib/utils/recipients';
+import {
+  isAssistantLastSigner,
+  isCcRecipient,
+  normalizeRecipientSigningOrders,
+  canRecipientBeModified as utilCanRecipientBeModified,
+} from '@documenso/lib/utils/recipients';
 import { trpc } from '@documenso/trpc/react';
 import { RecipientActionAuthSelect } from '@documenso/ui/components/recipient/recipient-action-auth-select';
 import {
@@ -156,16 +161,12 @@ export const EnvelopeEditorRecipientForm = () => {
   }, [watchedSigners]);
 
   const normalizeSigningOrders = (signers: typeof watchedSigners) => {
-    return signers
-      .sort((a, b) => (a.signingOrder ?? 0) - (b.signingOrder ?? 0))
-      .map((signer, index) => ({ ...signer, signingOrder: index + 1 }));
+    return normalizeRecipientSigningOrders(signers, (signer) => canRecipientBeModified(signer.id));
   };
 
-  const {
-    append: appendSigner,
-    fields: signers,
-    remove: removeSigner,
-  } = useFieldArray({
+  const activeRecipientCount = watchedSigners.filter((signer) => !isCcRecipient(signer)).length;
+
+  const { fields: signers, remove: removeSigner } = useFieldArray({
     control,
     name: 'signers',
     keyName: 'nativeId',
@@ -208,14 +209,31 @@ export const EnvelopeEditorRecipientForm = () => {
     return utilCanRecipientBeModified(recipient, fields);
   };
 
+  const appendNormalizedSigner = (signer: (typeof watchedSigners)[number], shouldFocus = false) => {
+    const updatedSigners = normalizeSigningOrders([...form.getValues('signers'), signer]);
+
+    form.setValue('signers', updatedSigners, {
+      shouldValidate: true,
+      shouldDirty: true,
+    });
+
+    if (shouldFocus) {
+      const signerIndex = updatedSigners.findIndex((updatedSigner) => updatedSigner.formId === signer.formId);
+
+      if (signerIndex !== -1) {
+        requestAnimationFrame(() => form.setFocus(`signers.${signerIndex}.email`));
+      }
+    }
+  };
+
   const onAddSigner = () => {
-    appendSigner({
+    appendNormalizedSigner({
       formId: nanoid(12),
       name: '',
       email: '',
       role: RecipientRole.SIGNER,
       actionAuth: [],
-      signingOrder: signers.length > 0 ? (signers[signers.length - 1]?.signingOrder ?? 0) + 1 : 1,
+      signingOrder: activeRecipientCount + 1,
     });
   };
 
@@ -323,18 +341,16 @@ export const EnvelopeEditorRecipientForm = () => {
 
       form.setFocus(`signers.${emptySignerIndex}.email`);
     } else {
-      appendSigner(
+      appendNormalizedSigner(
         {
           formId: nanoid(12),
           name: currentEditorName ?? '',
           email: currentEditorEmail ?? '',
           role: RecipientRole.SIGNER,
           actionAuth: [],
-          signingOrder: signers.length > 0 ? (signers[signers.length - 1]?.signingOrder ?? 0) + 1 : 1,
-        },
-        {
-          shouldFocus: true,
+          signingOrder: activeRecipientCount + 1,
         },
+        true,
       );
 
       void form.trigger('signers');
@@ -369,18 +385,14 @@ export const EnvelopeEditorRecipientForm = () => {
 
       items.splice(insertIndex, 0, reorderedSigner);
 
-      const updatedSigners = items.map((signer, index) => ({
-        ...signer,
-        signingOrder: !canRecipientBeModified(signer.id) ? signer.signingOrder : index + 1,
-      }));
+      const updatedSigners = normalizeSigningOrders(items);
 
       form.setValue('signers', updatedSigners, {
         shouldValidate: true,
         shouldDirty: true,
       });
 
-      const lastSigner = updatedSigners[updatedSigners.length - 1];
-      if (lastSigner.role === RecipientRole.ASSISTANT) {
+      if (isAssistantLastSigner(updatedSigners)) {
         toast({
           title: t`Warning: Assistant as last signer`,
           description: t`Having an assistant as the last signer means they will be unable to take any action as there are no subsequent signers to assist.`,
@@ -411,18 +423,19 @@ export const EnvelopeEditorRecipientForm = () => {
         return;
       }
 
-      const updatedSigners = currentSigners.map((signer, idx) => ({
-        ...signer,
-        role: idx === index ? role : signer.role,
-        signingOrder: !canRecipientBeModified(signer.id) ? signer.signingOrder : idx + 1,
-      }));
+      const updatedSigners = normalizeSigningOrders(
+        currentSigners.map((signer, idx) => ({
+          ...signer,
+          role: idx === index ? role : signer.role,
+        })),
+      );
 
       form.setValue('signers', updatedSigners, {
         shouldValidate: true,
         shouldDirty: true,
       });
 
-      if (role === RecipientRole.ASSISTANT && index === updatedSigners.length - 1) {
+      if (role === RecipientRole.ASSISTANT && isAssistantLastSigner(updatedSigners)) {
         toast({
           title: t`Warning: Assistant as last signer`,
           description: t`Having an assistant as the last signer means they will be unable to take any action as there are no subsequent signers to assist.`,
@@ -447,22 +460,30 @@ export const EnvelopeEditorRecipientForm = () => {
       const currentSigners = form.getValues('signers');
       const signer = currentSigners[index];
 
-      // Remove signer from current position and insert at new position
-      const remainingSigners = currentSigners.filter((_, idx) => idx !== index);
-      const newPosition = Math.min(Math.max(0, newOrder - 1), currentSigners.length - 1);
-      remainingSigners.splice(newPosition, 0, signer);
+      if (isCcRecipient(signer)) {
+        return;
+      }
 
-      const updatedSigners = remainingSigners.map((s, idx) => ({
-        ...s,
-        signingOrder: !canRecipientBeModified(s.id) ? s.signingOrder : idx + 1,
-      }));
+      const nonCcSigners = currentSigners.filter((s) => !isCcRecipient(s));
+      const ccSigners = currentSigners.filter((s) => isCcRecipient(s));
+      const currentSigningOrderIndex = nonCcSigners.findIndex((s) => s.formId === signer.formId);
+
+      if (currentSigningOrderIndex === -1) {
+        return;
+      }
+
+      const [reorderedSigner] = nonCcSigners.splice(currentSigningOrderIndex, 1);
+      const newPosition = Math.min(Math.max(0, newOrder - 1), nonCcSigners.length);
+      nonCcSigners.splice(newPosition, 0, reorderedSigner);
+
+      const updatedSigners = normalizeSigningOrders([...nonCcSigners, ...ccSigners]);
 
       form.setValue('signers', updatedSigners, {
         shouldValidate: true,
         shouldDirty: true,
       });
 
-      if (signer.role === RecipientRole.ASSISTANT && newPosition === remainingSigners.length - 1) {
+      if (signer.role === RecipientRole.ASSISTANT && isAssistantLastSigner(updatedSigners)) {
         toast({
           title: t`Warning: Assistant as last signer`,
           description: t`Having an assistant as the last signer means they will be unable to take any action as there are no subsequent signers to assist.`,
@@ -476,10 +497,12 @@ export const EnvelopeEditorRecipientForm = () => {
     setShowSigningOrderConfirmation(false);
 
     const currentSigners = form.getValues('signers');
-    const updatedSigners = currentSigners.map((signer) => ({
-      ...signer,
-      role: signer.role === RecipientRole.ASSISTANT ? RecipientRole.SIGNER : signer.role,
-    }));
+    const updatedSigners = normalizeSigningOrders(
+      currentSigners.map((signer) => ({
+        ...signer,
+        role: signer.role === RecipientRole.ASSISTANT ? RecipientRole.SIGNER : signer.role,
+      })),
+    );
 
     form.setValue('signers', updatedSigners, {
       shouldValidate: true,
@@ -796,6 +819,7 @@ export const EnvelopeEditorRecipientForm = () => {
                         isDragDisabled={
                           !isSigningOrderSequential ||
                           isSubmitting ||
+                          isCcRecipient(signer) ||
                           !canRecipientBeModified(signer.id) ||
                           !signer.signingOrder
                         }
@@ -819,7 +843,11 @@ export const EnvelopeEditorRecipientForm = () => {
                               })}
                             >
                               <div className="flex flex-row items-center gap-x-2">
-                                {isSigningOrderSequential && (
+                                {isSigningOrderSequential && isCcRecipient(signer) && (
+                                  <div className="mt-auto h-10 w-[4.25rem] flex-shrink-0" />
+                                )}
+
+                                {isSigningOrderSequential && !isCcRecipient(signer) && (
                                   <FormField
                                     control={form.control}
                                     name={`signers.${index}.signingOrder`}
@@ -835,7 +863,7 @@ export const EnvelopeEditorRecipientForm = () => {
                                         <FormControl>
                                           <Input
                                             type="number"
-                                            max={signers.length}
+                                            max={activeRecipientCount}
                                             data-testid="signing-order-input"
                                             className={cn(
                                               'w-10 text-center',
@@ -976,7 +1004,6 @@ export const EnvelopeEditorRecipientForm = () => {
                                           onValueChange={(value) => {
                                             // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
                                             handleRoleChange(index, value as RecipientRole);
-                                            field.onChange(value);
                                           }}
                                           disabled={
                                             snapshot.isDragging || isSubmitting || !canRecipientBeModified(signer.id)

apps/remix/app/components/tables/admin-claims-table.tsx

@@ -38,16 +38,11 @@ export const AdminClaimsTable = ({ licenseFlags }: AdminClaimsTableProps) => {
 
   const parsedSearchParams = ZUrlSearchParamsSchema.parse(Object.fromEntries(searchParams ?? []));
 
-  const { data, isLoading, isLoadingError } = trpc.admin.claims.find.useQuery(
-    {
-      query: parsedSearchParams.query,
-      page: parsedSearchParams.page,
-      perPage: parsedSearchParams.perPage,
-    },
-    {
-      placeholderData: (previousData) => previousData,
-    },
-  );
+  const { data, isLoading, isLoadingError } = trpc.admin.claims.find.useQuery({
+    query: parsedSearchParams.query,
+    page: parsedSearchParams.page,
+    perPage: parsedSearchParams.perPage,
+  });
 
   const onPaginationChange = (page: number, perPage: number) => {
     updateSearchParams({

apps/remix/app/components/tables/admin-document-jobs-table.tsx

@@ -19,16 +19,11 @@ export const AdminDocumentJobsTable = ({ envelopeId }: { envelopeId: string }) =
 
   const parsedSearchParams = ZUrlSearchParamsSchema.parse(Object.fromEntries(searchParams ?? []));
 
-  const { data, isLoading, isLoadingError, refetch, isFetching } = trpc.admin.document.findJobs.useQuery(
-    {
-      envelopeId: envelopeId,
-      page: parsedSearchParams.page,
-      perPage: parsedSearchParams.perPage,
-    },
-    {
-      placeholderData: (previousData) => previousData,
-    },
-  );
+  const { data, isLoading, isLoadingError, refetch, isFetching } = trpc.admin.document.findJobs.useQuery({
+    envelopeId: envelopeId,
+    page: parsedSearchParams.page,
+    perPage: parsedSearchParams.perPage,
+  });
 
   const onPaginationChange = (page: number, perPage: number) => {
     updateSearchParams({

apps/remix/app/components/tables/admin-email-transports-table.tsx

@@ -30,16 +30,11 @@ export const AdminEmailTransportsTable = () => {
 
   const parsedSearchParams = ZUrlSearchParamsSchema.parse(Object.fromEntries(searchParams ?? []));
 
-  const { data, isLoading, isLoadingError } = trpc.admin.emailTransport.find.useQuery(
-    {
-      query: parsedSearchParams.query,
-      page: parsedSearchParams.page,
-      perPage: parsedSearchParams.perPage,
-    },
-    {
-      placeholderData: (previousData) => previousData,
-    },
-  );
+  const { data, isLoading, isLoadingError } = trpc.admin.emailTransport.find.useQuery({
+    query: parsedSearchParams.query,
+    page: parsedSearchParams.page,
+    perPage: parsedSearchParams.perPage,
+  });
 
   const onPaginationChange = (page: number, perPage: number) => {
     updateSearchParams({

apps/remix/app/components/tables/admin-organisation-stats-table.tsx

@@ -77,20 +77,15 @@ export const AdminOrganisationStatsTable = ({ displayMode = 'usage' }: AdminOrga
   const orderByColumn = parseOrderByColumn(searchParams?.get('orderByColumn') ?? undefined);
   const orderByDirection = parseOrderByDirection(searchParams?.get('orderByDirection') ?? undefined);
 
-  const { data, isLoading, isLoadingError } = trpc.admin.organisation.stats.find.useQuery(
-    {
-      query: parsedSearchParams.query,
-      page: parsedSearchParams.page,
-      perPage: parsedSearchParams.perPage,
-      period,
-      claimId,
-      orderByColumn,
-      orderByDirection,
-    },
-    {
-      placeholderData: (previousData) => previousData,
-    },
-  );
+  const { data, isLoading, isLoadingError } = trpc.admin.organisation.stats.find.useQuery({
+    query: parsedSearchParams.query,
+    page: parsedSearchParams.page,
+    perPage: parsedSearchParams.perPage,
+    period,
+    claimId,
+    orderByColumn,
+    orderByDirection,
+  });
 
   const onPaginationChange = (page: number, perPage: number) => {
     updateSearchParams({

apps/remix/app/components/tables/admin-organisations-table.tsx

@@ -55,18 +55,13 @@ export const AdminOrganisationsTable = ({
 
   const parsedSearchParams = ZUrlSearchParamsSchema.parse(Object.fromEntries(searchParams ?? []));
 
-  const { data, isLoading, isLoadingError } = trpc.admin.organisation.find.useQuery(
-    {
-      query: parsedSearchParams.query,
-      page: parsedSearchParams.page,
-      perPage: parsedSearchParams.perPage,
-      ownerUserId,
-      memberUserId,
-    },
-    {
-      placeholderData: (previousData) => previousData,
-    },
-  );
+  const { data, isLoading, isLoadingError } = trpc.admin.organisation.find.useQuery({
+    query: parsedSearchParams.query,
+    page: parsedSearchParams.page,
+    perPage: parsedSearchParams.perPage,
+    ownerUserId,
+    memberUserId,
+  });
 
   const onPaginationChange = (page: number, perPage: number) => {
     updateSearchParams({

apps/remix/app/components/tables/admin-user-teams-table.tsx

@@ -28,17 +28,12 @@ export const AdminUserTeamsTable = ({ userId }: AdminUserTeamsTableProps) => {
 
   const parsedSearchParams = ZUrlSearchParamsSchema.parse(Object.fromEntries(searchParams ?? []));
 
-  const { data, isLoading, isLoadingError } = trpc.admin.user.findTeams.useQuery(
-    {
-      userId,
-      query: parsedSearchParams.query,
-      page: parsedSearchParams.page,
-      perPage: parsedSearchParams.perPage,
-    },
-    {
-      placeholderData: (previousData) => previousData,
-    },
-  );
+  const { data, isLoading, isLoadingError } = trpc.admin.user.findTeams.useQuery({
+    userId,
+    query: parsedSearchParams.query,
+    page: parsedSearchParams.page,
+    perPage: parsedSearchParams.perPage,
+  });
 
   const onPaginationChange = (page: number, perPage: number) => {
     updateSearchParams({

apps/remix/app/components/tables/inbox-table.tsx

@@ -46,15 +46,10 @@ export const InboxTable = () => {
   const page = searchParams?.get?.('page') ? Number(searchParams.get('page')) : undefined;
   const perPage = searchParams?.get?.('perPage') ? Number(searchParams.get('perPage')) : undefined;
 
-  const { data, isLoading, isLoadingError } = trpc.document.inbox.find.useQuery(
-    {
-      page: page || 1,
-      perPage: perPage || 10,
-    },
-    {
-      placeholderData: (previousData) => previousData,
-    },
-  );
+  const { data, isLoading, isLoadingError } = trpc.document.inbox.find.useQuery({
+    page: page || 1,
+    perPage: perPage || 10,
+  });
 
   const columns = useMemo(() => {
     return [

apps/remix/app/components/tables/organisation-teams-table.tsx

@@ -28,17 +28,12 @@ export const OrganisationTeamsTable = () => {
 
   const parsedSearchParams = ZUrlSearchParamsSchema.parse(Object.fromEntries(searchParams ?? []));
 
-  const { data, isLoading, isLoadingError } = trpc.team.find.useQuery(
-    {
-      organisationId: organisation.id,
-      query: parsedSearchParams.query,
-      page: parsedSearchParams.page,
-      perPage: parsedSearchParams.perPage,
-    },
-    {
-      placeholderData: (previousData) => previousData,
-    },
-  );
+  const { data, isLoading, isLoadingError } = trpc.team.find.useQuery({
+    organisationId: organisation.id,
+    query: parsedSearchParams.query,
+    page: parsedSearchParams.page,
+    perPage: parsedSearchParams.perPage,
+  });
 
   const onPaginationChange = (page: number, perPage: number) => {
     updateSearchParams({

apps/remix/app/routes/_authenticated+/t.$teamUrl+/documents._index.tsx

@@ -91,7 +91,6 @@ export default function DocumentsPage() {
       folderId,
     },
     {
-      placeholderData: (previousData) => previousData,
       ...SKIP_QUERY_BATCH_META,
     },
   );

apps/remix/app/routes/_authenticated+/t.$teamUrl+/settings.webhooks.$id._index.tsx

@@ -72,19 +72,14 @@ export default function WebhookPage({ params }: Route.ComponentProps) {
     data,
     isLoading: isLogsLoading,
     isLoadingError: isLogsLoadingError,
-  } = trpc.webhook.calls.find.useQuery(
-    {
-      webhookId: params.id,
-      page: parsedSearchParams.page,
-      perPage: parsedSearchParams.perPage,
-      status: parsedSearchParams.status,
-      events: parsedSearchParams.events,
-      query: parsedSearchParams.query,
-    },
-    {
-      placeholderData: (previousData) => previousData,
-    },
-  );
+  } = trpc.webhook.calls.find.useQuery({
+    webhookId: params.id,
+    page: parsedSearchParams.page,
+    perPage: parsedSearchParams.perPage,
+    status: parsedSearchParams.status,
+    events: parsedSearchParams.events,
+    query: parsedSearchParams.query,
+  });
 
   /**
    * Handle debouncing the search query.

apps/remix/app/routes/_authenticated+/t.$teamUrl+/templates._index.tsx

@@ -66,7 +66,6 @@ export default function TemplatesPage() {
     },
     {
       enabled: !isOrgView,
-      placeholderData: (previousData) => previousData,
     },
   );
 
@@ -77,7 +76,6 @@ export default function TemplatesPage() {
     },
     {
       enabled: isOrgView,
-      placeholderData: (previousData) => previousData,
     },
   );
 

apps/remix/package.json

@@ -36,8 +36,8 @@
     "@lingui/react": "^5.6.0",
     "@oslojs/crypto": "^1.0.1",
     "@oslojs/encoding": "^1.1.0",
-    "@react-router/node": "^7.12.0",
-    "@react-router/serve": "^7.12.0",
+    "@react-router/node": "^7.18.1",
+    "@react-router/serve": "^7.18.1",
     "@simplewebauthn/browser": "^13.2.2",
     "@simplewebauthn/server": "^13.2.2",
     "@tanstack/react-query": "5.90.10",
@@ -81,8 +81,8 @@
     "@babel/preset-typescript": "^7.28.5",
     "@lingui/babel-plugin-lingui-macro": "^5.6.0",
     "@lingui/vite-plugin": "^5.6.0",
-    "@react-router/dev": "^7.12.0",
-    "@react-router/remix-routes-option-adapter": "^7.12.0",
+    "@react-router/dev": "^7.18.1",
+    "@react-router/remix-routes-option-adapter": "^7.18.1",
     "@rollup/plugin-babel": "^6.1.0",
     "@rollup/plugin-commonjs": "^28.0.9",
     "@rollup/plugin-json": "^6.1.0",

packages/app-tests/e2e/document-flow/stepper-component.spec.ts

@@ -225,15 +225,20 @@ test('[DOCUMENT_FLOW]: should be able to create a document with multiple recipie
   await page.getByLabel('Receives copy').click();
   await page.getByRole('button', { name: 'Add Signer' }).click();
 
-  await page.getByLabel('Email').nth(2).fill('user3@example.com');
-  await page.getByLabel('Name').nth(2).fill('User 3');
-  await page.getByRole('combobox').nth(2).click();
+  // CC recipients are kept last, so new rows are inserted above the CC row.
+  await expect(page.getByLabel('Email')).toHaveCount(3);
+
+  await page.getByLabel('Email').nth(1).fill('user3@example.com');
+  await page.getByLabel('Name').nth(1).fill('User 3');
+  await page.getByRole('combobox').nth(1).click();
   await page.getByLabel('Needs to approve').click();
   await page.getByRole('button', { name: 'Add Signer' }).click();
 
-  await page.getByLabel('Email').nth(3).fill('user4@example.com');
-  await page.getByLabel('Name').nth(3).fill('User 4');
-  await page.getByRole('combobox').nth(3).click();
+  await expect(page.getByLabel('Email')).toHaveCount(4);
+
+  await page.getByLabel('Email').nth(2).fill('user4@example.com');
+  await page.getByLabel('Name').nth(2).fill('User 4');
+  await page.getByRole('combobox').nth(2).click();
   await page.getByLabel('Needs to view').click();
 
   await page.getByRole('button', { name: 'Continue' }).click();

packages/app-tests/e2e/teams/default-recipients.spec.ts

@@ -110,7 +110,7 @@ test.describe('Default Recipients', () => {
     await page.getByRole('button', { name: 'Add Signer' }).click();
 
     // Add a regular signer using the v2 editor
-    await page.getByTestId('signer-email-input').last().fill('regular-signer@documenso.com');
+    await page.getByTestId('signer-email-input').first().fill('regular-signer@documenso.com');
     await page
       .getByPlaceholder(/Recipient/)
       .first()

packages/lib/client-only/hooks/use-editor-recipients.ts

@@ -7,9 +7,10 @@ import { DocumentSigningOrder, RecipientRole } from '@prisma/client';
 import { useId } from 'react';
 import type { UseFormReturn } from 'react-hook-form';
 import { useForm } from 'react-hook-form';
-import { prop, sortBy } from 'remeda';
 import { z } from 'zod';
 
+import { isCcRecipient, normalizeRecipientSigningOrders, sortRecipientsForSigningOrder } from '../../utils/recipients';
+
 const LocalRecipientSchema = z.object({
   formId: z.string().min(1),
   id: z.number().optional(),
@@ -94,13 +95,13 @@ export const useEditorRecipients = ({ envelope }: EditorRecipientsProps): UseEdi
       name: recipient.name,
       email: recipient.email,
       role: recipient.role,
-      signingOrder: recipient.signingOrder ?? index + 1,
+      signingOrder: isCcRecipient(recipient) ? undefined : (recipient.signingOrder ?? index + 1),
       actionAuth: ZRecipientAuthOptionsSchema.parse(recipient.authOptions)?.actionAuth ?? undefined,
     }));
 
     const signers: TLocalRecipient[] =
       formRecipients.length > 0
-        ? sortBy(formRecipients, [prop('signingOrder'), 'asc'], [prop('id'), 'asc'])
+        ? normalizeRecipientSigningOrders(sortRecipientsForSigningOrder(formRecipients))
         : [
             {
               formId: initialId,

packages/lib/server-only/envelope/create-envelope.ts

@@ -35,6 +35,7 @@ import { getFileServerSide } from '../../universal/upload/get-file.server';
 import { putPdfFileServerSide } from '../../universal/upload/put-file.server';
 import { extractDerivedDocumentMeta } from '../../utils/document';
 import { createDocumentAuthOptions, createRecipientAuthOptions } from '../../utils/document-auth';
+import { getRecipientSigningOrder } from '../../utils/recipients';
 import { buildTeamWhereQuery } from '../../utils/teams';
 import { incrementDocumentId, incrementTemplateId } from '../envelope/increment-id';
 import { assertOrganisationRatesAndLimits } from '../rate-limit/assert-organisation-rates-and-limits';
@@ -461,7 +462,7 @@ export const createEnvelope = async ({
             name: recipient.name,
             email: recipient.email,
             role: recipient.role,
-            signingOrder: recipient.signingOrder,
+            signingOrder: getRecipientSigningOrder(recipient),
             token: nanoid(),
             sendStatus: recipient.role === RecipientRole.CC ? SendStatus.SENT : SendStatus.NOT_SENT,
             signingStatus: recipient.role === RecipientRole.CC ? SigningStatus.SIGNED : SigningStatus.NOT_SIGNED,

packages/lib/server-only/envelope/duplicate-envelope.ts

@@ -8,6 +8,7 @@ import { ZSignatureLevelSchema } from '../../types/signature-level';
 import { mapEnvelopeToWebhookDocumentPayload, ZWebhookDocumentSchema } from '../../types/webhook-payload';
 import { nanoid, prefixedId } from '../../universal/id';
 import type { EnvelopeIdOptions } from '../../utils/envelope';
+import { getRecipientSigningOrder } from '../../utils/recipients';
 import { getEnvelopeWhereInput } from '../envelope/get-envelope-by-id';
 import { incrementDocumentId, incrementTemplateId } from '../envelope/increment-id';
 import { assertOrganisationRatesAndLimits } from '../rate-limit/assert-organisation-rates-and-limits';
@@ -190,7 +191,7 @@ export const duplicateEnvelope = async ({ id, userId, teamId, overrides }: Dupli
             email: recipient.email,
             name: recipient.name,
             role: recipient.role,
-            signingOrder: recipient.signingOrder,
+            signingOrder: getRecipientSigningOrder(recipient),
             token: nanoid(),
             fields: includeFields
               ? {

packages/lib/server-only/recipient/create-envelope-recipients.ts

@@ -9,7 +9,7 @@ import { EnvelopeType, RecipientRole, SendStatus, SigningStatus } from '@prisma/
 
 import { AppError, AppErrorCode } from '../../errors/app-error';
 import type { EnvelopeIdOptions } from '../../utils/envelope';
-import { mapRecipientToLegacyRecipient } from '../../utils/recipients';
+import { getRecipientSigningOrder, mapRecipientToLegacyRecipient } from '../../utils/recipients';
 import { assertEnvelopeMutable } from '../envelope/assert-envelope-mutable';
 import { getEnvelopeWhereInput } from '../envelope/get-envelope-by-id';
 import { assertCompatibleRecipientRole } from '../signature-level/assert-compatible-recipient-role';
@@ -112,7 +112,7 @@ export const createEnvelopeRecipients = async ({
             name: recipient.name,
             email: recipient.email,
             role: recipient.role,
-            signingOrder: recipient.signingOrder,
+            signingOrder: getRecipientSigningOrder(recipient),
             token: nanoid(),
             sendStatus: recipient.role === RecipientRole.CC ? SendStatus.SENT : SendStatus.NOT_SENT,
             signingStatus: recipient.role === RecipientRole.CC ? SigningStatus.SIGNED : SigningStatus.NOT_SIGNED,

packages/lib/server-only/recipient/set-document-recipients.ts

@@ -14,7 +14,11 @@ import { AppError, AppErrorCode } from '../../errors/app-error';
 import { jobs } from '../../jobs/client';
 import { extractDerivedDocumentEmailSettings } from '../../types/document-email';
 import { type EnvelopeIdOptions, mapSecondaryIdToDocumentId } from '../../utils/envelope';
-import { canRecipientBeModified, isRecipientEmailValidForSending } from '../../utils/recipients';
+import {
+  canRecipientBeModified,
+  getRecipientSigningOrder,
+  isRecipientEmailValidForSending,
+} from '../../utils/recipients';
 import { assertEnvelopeMutable } from '../envelope/assert-envelope-mutable';
 import { getEnvelopeWhereInput } from '../envelope/get-envelope-by-id';
 import { assertCompatibleRecipientRole } from '../signature-level/assert-compatible-recipient-role';
@@ -161,7 +165,7 @@ export const setDocumentRecipients = async ({
             name: recipient.name,
             email: recipient.email,
             role: recipient.role,
-            signingOrder: recipient.signingOrder,
+            signingOrder: getRecipientSigningOrder(recipient),
             envelopeId: envelope.id,
             sendStatus: recipient.role === RecipientRole.CC ? SendStatus.SENT : SendStatus.NOT_SENT,
             signingStatus: recipient.role === RecipientRole.CC ? SigningStatus.SIGNED : SigningStatus.NOT_SIGNED,
@@ -171,7 +175,7 @@ export const setDocumentRecipients = async ({
             name: recipient.name,
             email: recipient.email,
             role: recipient.role,
-            signingOrder: recipient.signingOrder,
+            signingOrder: getRecipientSigningOrder(recipient),
             token: nanoid(),
             envelopeId: envelope.id,
             sendStatus: recipient.role === RecipientRole.CC ? SendStatus.SENT : SendStatus.NOT_SENT,

packages/lib/server-only/recipient/set-template-recipients.ts

@@ -11,6 +11,7 @@ import { type TRecipientActionAuthTypes, ZRecipientAuthOptionsSchema } from '../
 import { nanoid } from '../../universal/id';
 import { createRecipientAuthOptions } from '../../utils/document-auth';
 import { type EnvelopeIdOptions, mapSecondaryIdToTemplateId } from '../../utils/envelope';
+import { getRecipientSigningOrder } from '../../utils/recipients';
 import { getEnvelopeWhereInput } from '../envelope/get-envelope-by-id';
 import { assertCompatibleRecipientRole } from '../signature-level/assert-compatible-recipient-role';
 
@@ -142,7 +143,7 @@ export const setTemplateRecipients = async ({ userId, teamId, id, recipients }:
             name: recipient.name,
             email: recipient.email,
             role: recipient.role,
-            signingOrder: recipient.signingOrder,
+            signingOrder: getRecipientSigningOrder(recipient),
             envelopeId: envelope.id,
             authOptions,
           },
@@ -150,7 +151,7 @@ export const setTemplateRecipients = async ({ userId, teamId, id, recipients }:
             name: recipient.name,
             email: recipient.email,
             role: recipient.role,
-            signingOrder: recipient.signingOrder,
+            signingOrder: getRecipientSigningOrder(recipient),
             token: nanoid(),
             envelopeId: envelope.id,
             authOptions,

packages/lib/server-only/recipient/update-envelope-recipients.ts

@@ -11,7 +11,7 @@ import { AppError, AppErrorCode } from '../../errors/app-error';
 import { extractLegacyIds } from '../../universal/id';
 import type { EnvelopeIdOptions } from '../../utils/envelope';
 import { mapFieldToLegacyField } from '../../utils/fields';
-import { canRecipientBeModified } from '../../utils/recipients';
+import { canRecipientBeModified, getRecipientSigningOrder } from '../../utils/recipients';
 import { assertEnvelopeMutable } from '../envelope/assert-envelope-mutable';
 import { getEnvelopeWhereInput } from '../envelope/get-envelope-by-id';
 import { assertCompatibleRecipientRole } from '../signature-level/assert-compatible-recipient-role';
@@ -148,7 +148,7 @@ export const updateEnvelopeRecipients = async ({
             name: mergedRecipient.name,
             email: mergedRecipient.email,
             role: mergedRecipient.role,
-            signingOrder: mergedRecipient.signingOrder,
+            signingOrder: getRecipientSigningOrder(mergedRecipient),
             envelopeId: envelope.id,
             sendStatus: mergedRecipient.role === RecipientRole.CC ? SendStatus.SENT : SendStatus.NOT_SENT,
             signingStatus: mergedRecipient.role === RecipientRole.CC ? SigningStatus.SIGNED : SigningStatus.NOT_SIGNED,

packages/lib/server-only/template/create-document-from-direct-template.ts

@@ -40,6 +40,7 @@ import {
   extractDocumentAuthMethods,
 } from '../../utils/document-auth';
 import { mapSecondaryIdToTemplateId } from '../../utils/envelope';
+import { getRecipientSigningOrder } from '../../utils/recipients';
 import { sendDocument } from '../document/send-document';
 import { validateFieldAuth } from '../document/validate-field-auth';
 import { incrementDocumentId } from '../envelope/increment-id';
@@ -398,7 +399,7 @@ export const createDocumentFromDirectTemplate = async ({
                 }),
                 sendStatus: recipient.role === RecipientRole.CC ? SendStatus.SENT : SendStatus.NOT_SENT,
                 signingStatus: recipient.role === RecipientRole.CC ? SigningStatus.SIGNED : SigningStatus.NOT_SIGNED,
-                signingOrder: recipient.signingOrder,
+                signingOrder: getRecipientSigningOrder(recipient),
                 token: nanoid(),
               };
             }),

packages/lib/server-only/template/create-document-from-template.ts

@@ -47,6 +47,7 @@ import {
 } from '../../utils/document-auth';
 import type { EnvelopeIdOptions } from '../../utils/envelope';
 import { mapSecondaryIdToTemplateId } from '../../utils/envelope';
+import { getRecipientSigningOrder } from '../../utils/recipients';
 import { buildTeamWhereQuery } from '../../utils/teams';
 import { getEnvelopeWhereInput } from '../envelope/get-envelope-by-id';
 import { incrementDocumentId } from '../envelope/increment-id';
@@ -591,7 +592,7 @@ export const createDocumentFromTemplate = async ({
                 }),
                 sendStatus: recipient.role === RecipientRole.CC ? SendStatus.SENT : SendStatus.NOT_SENT,
                 signingStatus: recipient.role === RecipientRole.CC ? SigningStatus.SIGNED : SigningStatus.NOT_SIGNED,
-                signingOrder: recipient.signingOrder,
+                signingOrder: getRecipientSigningOrder(recipient),
                 token: recipient.token,
               };
             }),

packages/lib/utils/recipients.test.ts

@@ -0,0 +1,81 @@
+import { RecipientRole } from '@prisma/client';
+import { describe, expect, it } from 'vitest';
+
+import {
+  getRecipientSigningOrder,
+  isAssistantLastSigner,
+  normalizeRecipientSigningOrders,
+  sortRecipientsForSigningOrder,
+} from './recipients';
+
+describe('recipient signing order helpers', () => {
+  it('sorts CC recipients after ordered active recipients', () => {
+    const recipients = [
+      { id: 1, role: RecipientRole.CC, signingOrder: 1 },
+      { id: 2, role: RecipientRole.SIGNER, signingOrder: 2 },
+      { id: 3, role: RecipientRole.APPROVER, signingOrder: 1 },
+    ];
+
+    expect(sortRecipientsForSigningOrder(recipients).map((recipient) => recipient.id)).toEqual([3, 2, 1]);
+  });
+
+  it('keeps original order when recipients have the same signing order', () => {
+    const recipients = [
+      { id: 2, role: RecipientRole.SIGNER, signingOrder: 1 },
+      { id: 1, role: RecipientRole.APPROVER, signingOrder: 1 },
+    ];
+
+    expect(sortRecipientsForSigningOrder(recipients).map((recipient) => recipient.id)).toEqual([2, 1]);
+  });
+
+  it('sorts and normalizes active recipient signing order and removes it from CC recipients', () => {
+    const recipients = [
+      { id: 1, role: RecipientRole.CC, signingOrder: 1 },
+      { id: 2, role: RecipientRole.SIGNER, signingOrder: 4 },
+      { id: 3, role: RecipientRole.APPROVER, signingOrder: 2 },
+    ];
+
+    expect(normalizeRecipientSigningOrders(sortRecipientsForSigningOrder(recipients))).toEqual([
+      { id: 3, role: RecipientRole.APPROVER, signingOrder: 1 },
+      { id: 2, role: RecipientRole.SIGNER, signingOrder: 2 },
+      { id: 1, role: RecipientRole.CC, signingOrder: undefined },
+    ]);
+  });
+
+  it('preserves caller order while normalizing signing order', () => {
+    const recipients = [
+      { id: 2, role: RecipientRole.ASSISTANT, signingOrder: 2 },
+      { id: 1, role: RecipientRole.SIGNER, signingOrder: 1 },
+      { id: 3, role: RecipientRole.CC, signingOrder: 1 },
+    ];
+
+    expect(normalizeRecipientSigningOrders(recipients)).toEqual([
+      { id: 2, role: RecipientRole.ASSISTANT, signingOrder: 1 },
+      { id: 1, role: RecipientRole.SIGNER, signingOrder: 2 },
+      { id: 3, role: RecipientRole.CC, signingOrder: undefined },
+    ]);
+  });
+
+  it('coerces CC signing order to null for persistence', () => {
+    expect(getRecipientSigningOrder({ role: RecipientRole.CC, signingOrder: 1 })).toBeNull();
+    expect(getRecipientSigningOrder({ role: RecipientRole.SIGNER, signingOrder: 1 })).toBe(1);
+  });
+
+  it('checks whether the last non-CC recipient is an assistant', () => {
+    expect(
+      isAssistantLastSigner([
+        { role: RecipientRole.SIGNER },
+        { role: RecipientRole.ASSISTANT },
+        { role: RecipientRole.CC },
+      ]),
+    ).toBe(true);
+
+    expect(
+      isAssistantLastSigner([
+        { role: RecipientRole.ASSISTANT },
+        { role: RecipientRole.SIGNER },
+        { role: RecipientRole.CC },
+      ]),
+    ).toBe(false);
+  });
+});

packages/lib/utils/recipients.ts

@@ -1,6 +1,6 @@
 import { isSignatureFieldType } from '@documenso/prisma/guards/is-signature-field';
-import type { Envelope } from '@prisma/client';
-import { type Field, RecipientRole, SigningStatus } from '@prisma/client';
+import type { Envelope, Field, Recipient } from '@prisma/client';
+import { RecipientRole, SigningStatus } from '@prisma/client';
 
 import { NEXT_PUBLIC_WEBAPP_URL } from '../constants/app';
 import { AppError, AppErrorCode } from '../errors/app-error';
@@ -15,6 +15,66 @@ import { zEmail } from './zod';
  */
 export const RECIPIENT_ROLES_THAT_REQUIRE_FIELDS = [RecipientRole.SIGNER] as const;
 
+// signingOrder isn't required when submitting the recipient form (Zod: z.number().optional())
+type RecipientWithSigningOrder = Pick<Recipient, 'role'> & Partial<Pick<Recipient, 'signingOrder'>>;
+
+export const isCcRecipient = (recipient: Pick<Recipient, 'role'>) => {
+  return recipient.role === RecipientRole.CC;
+};
+
+export const getRecipientSigningOrder = (recipient: RecipientWithSigningOrder) => {
+  if (isCcRecipient(recipient)) {
+    return null;
+  }
+
+  return recipient.signingOrder ?? null;
+};
+
+export const isAssistantLastSigner = (recipients: Pick<Recipient, 'role'>[]) => {
+  const nonCcRecipients = recipients.filter((recipient) => !isCcRecipient(recipient));
+  const lastNonCcRecipient = nonCcRecipients[nonCcRecipients.length - 1];
+
+  return lastNonCcRecipient?.role === RecipientRole.ASSISTANT;
+};
+
+export const sortRecipientsForSigningOrder = <T extends RecipientWithSigningOrder>(recipients: T[]): T[] => {
+  return [...recipients].sort((r1, r2) => {
+    const r1IsCcRecipient = isCcRecipient(r1);
+    const r2IsCcRecipient = isCcRecipient(r2);
+
+    // CC recipients always sort after non-CC recipients.
+    if (r1IsCcRecipient !== r2IsCcRecipient) {
+      return r1IsCcRecipient ? 1 : -1;
+    }
+
+    // Order by signing order; missing orders sort last.
+    const r1SigningOrder = r1.signingOrder ?? Number.MAX_SAFE_INTEGER;
+    const r2SigningOrder = r2.signingOrder ?? Number.MAX_SAFE_INTEGER;
+
+    return r1SigningOrder - r2SigningOrder;
+  });
+};
+
+export const normalizeRecipientSigningOrders = <T extends RecipientWithSigningOrder>(
+  recipients: T[],
+  canUpdateRecipient: (recipient: T) => boolean = () => true,
+): Array<T & { signingOrder?: number }> => {
+  const nonCcRecipients = recipients.filter((recipient) => !isCcRecipient(recipient));
+  const ccRecipients = recipients.filter((recipient) => isCcRecipient(recipient));
+
+  const normalizedNonCcRecipients = nonCcRecipients.map((recipient, index) => ({
+    ...recipient,
+    signingOrder: canUpdateRecipient(recipient) ? index + 1 : (recipient.signingOrder ?? index + 1),
+  }));
+
+  const normalizedCcRecipients = ccRecipients.map((recipient) => ({
+    ...recipient,
+    signingOrder: undefined,
+  }));
+
+  return [...normalizedNonCcRecipients, ...normalizedCcRecipients];
+};
+
 /**
  * Returns recipients who are missing required fields for their role.
  *

packages/ui/primitives/document-flow/add-signers.tsx

@@ -6,7 +6,13 @@ import { useSession } from '@documenso/lib/client-only/providers/session';
 import { ZRecipientAuthOptionsSchema } from '@documenso/lib/types/document-auth';
 import type { TRecipientLite } from '@documenso/lib/types/recipient';
 import { nanoid } from '@documenso/lib/universal/id';
-import { canRecipientBeModified as utilCanRecipientBeModified } from '@documenso/lib/utils/recipients';
+import {
+  isAssistantLastSigner,
+  isCcRecipient,
+  normalizeRecipientSigningOrders,
+  sortRecipientsForSigningOrder,
+  canRecipientBeModified as utilCanRecipientBeModified,
+} from '@documenso/lib/utils/recipients';
 import { trpc } from '@documenso/trpc/react';
 import { AnimateGenericFadeInOut } from '@documenso/ui/components/animate/animate-generic-fade-in-out';
 import { RecipientActionAuthSelect } from '@documenso/ui/components/recipient/recipient-action-auth-select';
@@ -24,7 +30,6 @@ import { motion } from 'framer-motion';
 import { GripVerticalIcon, HelpCircle, Plus, Trash } from 'lucide-react';
 import { useCallback, useId, useMemo, useRef, useState } from 'react';
 import { useFieldArray, useForm } from 'react-hook-form';
-import { prop, sortBy } from 'remeda';
 
 import { DocumentReadOnlyFields, mapFieldsWithRecipients } from '../../components/document/document-read-only-fields';
 import type { RecipientAutoCompleteOption } from '../../components/recipient/recipient-autocomplete-input';
@@ -118,18 +123,18 @@ export const AddSignersFormPartial = ({
     defaultValues: {
       signers:
         recipients.length > 0
-          ? sortBy(
-              recipients.map((recipient, index) => ({
-                nativeId: recipient.id,
-                formId: String(recipient.id),
-                name: recipient.name,
-                email: recipient.email,
-                role: recipient.role,
-                signingOrder: recipient.signingOrder ?? index + 1,
-                actionAuth: ZRecipientAuthOptionsSchema.parse(recipient.authOptions)?.actionAuth ?? undefined,
-              })),
-              [prop('signingOrder'), 'asc'],
-              [prop('nativeId'), 'asc'],
+          ? normalizeRecipientSigningOrders(
+              sortRecipientsForSigningOrder(
+                recipients.map((recipient, index) => ({
+                  nativeId: recipient.id,
+                  formId: String(recipient.id),
+                  name: recipient.name,
+                  email: recipient.email,
+                  role: recipient.role,
+                  signingOrder: isCcRecipient(recipient) ? undefined : (recipient.signingOrder ?? index + 1),
+                  actionAuth: ZRecipientAuthOptionsSchema.parse(recipient.authOptions)?.actionAuth ?? undefined,
+                })),
+              ),
             )
           : defaultRecipients,
       signingOrder: signingOrder || DocumentSigningOrder.PARALLEL,
@@ -168,18 +173,14 @@ export const AddSignersFormPartial = ({
   }, [watchedSigners]);
 
   const normalizeSigningOrders = (signers: typeof watchedSigners) => {
-    return signers
-      .sort((a, b) => (a.signingOrder ?? 0) - (b.signingOrder ?? 0))
-      .map((signer, index) => ({ ...signer, signingOrder: index + 1 }));
+    return normalizeRecipientSigningOrders(signers, (signer) => canRecipientBeModified(signer.nativeId));
   };
 
+  const activeRecipientCount = watchedSigners.filter((signer) => !isCcRecipient(signer)).length;
+
   const onFormSubmit = form.handleSubmit(onSubmit);
 
-  const {
-    append: appendSigner,
-    fields: signers,
-    remove: removeSigner,
-  } = useFieldArray({
+  const { fields: signers, remove: removeSigner } = useFieldArray({
     control,
     name: 'signers',
   });
@@ -258,14 +259,31 @@ export const AddSignersFormPartial = ({
     return utilCanRecipientBeModified(recipient, fields);
   };
 
+  const appendNormalizedSigner = (signer: (typeof watchedSigners)[number], shouldFocus = false) => {
+    const updatedSigners = normalizeSigningOrders([...form.getValues('signers'), signer]);
+
+    form.setValue('signers', updatedSigners, {
+      shouldValidate: true,
+      shouldDirty: true,
+    });
+
+    if (shouldFocus) {
+      const signerIndex = updatedSigners.findIndex((updatedSigner) => updatedSigner.formId === signer.formId);
+
+      if (signerIndex !== -1) {
+        requestAnimationFrame(() => form.setFocus(`signers.${signerIndex}.email`));
+      }
+    }
+  };
+
   const onAddSigner = () => {
-    appendSigner({
+    appendNormalizedSigner({
       formId: nanoid(12),
       name: '',
       email: '',
       role: RecipientRole.SIGNER,
       actionAuth: [],
-      signingOrder: signers.length > 0 ? (signers[signers.length - 1]?.signingOrder ?? 0) + 1 : 1,
+      signingOrder: activeRecipientCount + 1,
     });
   };
 
@@ -310,18 +328,16 @@ export const AddSignersFormPartial = ({
 
       form.setFocus(`signers.${emptySignerIndex}.email`);
     } else {
-      appendSigner(
+      appendNormalizedSigner(
         {
           formId: nanoid(12),
           name: user?.name ?? '',
           email: user?.email ?? '',
           role: RecipientRole.SIGNER,
           actionAuth: [],
-          signingOrder: signers.length > 0 ? (signers[signers.length - 1]?.signingOrder ?? 0) + 1 : 1,
-        },
-        {
-          shouldFocus: true,
+          signingOrder: activeRecipientCount + 1,
         },
+        true,
       );
 
       void form.trigger('signers');
@@ -356,18 +372,14 @@ export const AddSignersFormPartial = ({
 
       items.splice(insertIndex, 0, reorderedSigner);
 
-      const updatedSigners = items.map((signer, index) => ({
-        ...signer,
-        signingOrder: !canRecipientBeModified(signer.nativeId) ? signer.signingOrder : index + 1,
-      }));
+      const updatedSigners = normalizeSigningOrders(items);
 
       form.setValue('signers', updatedSigners, {
         shouldValidate: true,
         shouldDirty: true,
       });
 
-      const lastSigner = updatedSigners[updatedSigners.length - 1];
-      if (lastSigner.role === RecipientRole.ASSISTANT) {
+      if (isAssistantLastSigner(updatedSigners)) {
         toast({
           title: _(msg`Warning: Assistant as last signer`),
           description: _(
@@ -402,18 +414,19 @@ export const AddSignersFormPartial = ({
         return;
       }
 
-      const updatedSigners = currentSigners.map((signer, idx) => ({
-        ...signer,
-        role: idx === index ? role : signer.role,
-        signingOrder: !canRecipientBeModified(signer.nativeId) ? signer.signingOrder : idx + 1,
-      }));
+      const updatedSigners = normalizeSigningOrders(
+        currentSigners.map((signer, idx) => ({
+          ...signer,
+          role: idx === index ? role : signer.role,
+        })),
+      );
 
       form.setValue('signers', updatedSigners, {
         shouldValidate: true,
         shouldDirty: true,
       });
 
-      if (role === RecipientRole.ASSISTANT && index === updatedSigners.length - 1) {
+      if (role === RecipientRole.ASSISTANT && isAssistantLastSigner(updatedSigners)) {
         toast({
           title: _(msg`Warning: Assistant as last signer`),
           description: _(
@@ -440,22 +453,30 @@ export const AddSignersFormPartial = ({
       const currentSigners = form.getValues('signers');
       const signer = currentSigners[index];
 
-      // Remove signer from current position and insert at new position
-      const remainingSigners = currentSigners.filter((_, idx) => idx !== index);
-      const newPosition = Math.min(Math.max(0, newOrder - 1), currentSigners.length - 1);
-      remainingSigners.splice(newPosition, 0, signer);
+      if (isCcRecipient(signer)) {
+        return;
+      }
 
-      const updatedSigners = remainingSigners.map((s, idx) => ({
-        ...s,
-        signingOrder: !canRecipientBeModified(s.nativeId) ? s.signingOrder : idx + 1,
-      }));
+      const nonCcSigners = currentSigners.filter((s) => !isCcRecipient(s));
+      const ccSigners = currentSigners.filter((s) => isCcRecipient(s));
+      const currentSigningOrderIndex = nonCcSigners.findIndex((s) => s.formId === signer.formId);
+
+      if (currentSigningOrderIndex === -1) {
+        return;
+      }
+
+      const [reorderedSigner] = nonCcSigners.splice(currentSigningOrderIndex, 1);
+      const newPosition = Math.min(Math.max(0, newOrder - 1), nonCcSigners.length);
+      nonCcSigners.splice(newPosition, 0, reorderedSigner);
+
+      const updatedSigners = normalizeSigningOrders([...nonCcSigners, ...ccSigners]);
 
       form.setValue('signers', updatedSigners, {
         shouldValidate: true,
         shouldDirty: true,
       });
 
-      if (signer.role === RecipientRole.ASSISTANT && newPosition === remainingSigners.length - 1) {
+      if (signer.role === RecipientRole.ASSISTANT && isAssistantLastSigner(updatedSigners)) {
         toast({
           title: _(msg`Warning: Assistant as last signer`),
           description: _(
@@ -471,10 +492,12 @@ export const AddSignersFormPartial = ({
     setShowSigningOrderConfirmation(false);
 
     const currentSigners = form.getValues('signers');
-    const updatedSigners = currentSigners.map((signer) => ({
-      ...signer,
-      role: signer.role === RecipientRole.ASSISTANT ? RecipientRole.SIGNER : signer.role,
-    }));
+    const updatedSigners = normalizeSigningOrders(
+      currentSigners.map((signer) => ({
+        ...signer,
+        role: signer.role === RecipientRole.ASSISTANT ? RecipientRole.SIGNER : signer.role,
+      })),
+    );
 
     form.setValue('signers', updatedSigners, {
       shouldValidate: true,
@@ -642,6 +665,7 @@ export const AddSignersFormPartial = ({
                         isDragDisabled={
                           !isSigningOrderSequential ||
                           isSubmitting ||
+                          isCcRecipient(signer) ||
                           !canRecipientBeModified(signer.nativeId) ||
                           !signer.signingOrder
                         }
@@ -663,7 +687,9 @@ export const AddSignersFormPartial = ({
                                 'grid-cols-12 pr-3': isSigningOrderSequential,
                               })}
                             >
-                              {isSigningOrderSequential && (
+                              {isSigningOrderSequential && isCcRecipient(signer) && <div className="col-span-2" />}
+
+                              {isSigningOrderSequential && !isCcRecipient(signer) && (
                                 <FormField
                                   control={form.control}
                                   name={`signers.${index}.signingOrder`}
@@ -679,7 +705,7 @@ export const AddSignersFormPartial = ({
                                       <FormControl>
                                         <Input
                                           type="number"
-                                          max={signers.length}
+                                          max={activeRecipientCount}
                                           data-testid="signing-order-input"
                                           className={cn(
                                             'w-full text-center',