feat: add envelope pdf replacement (#2602)

2026-07-27 02:15:05 +10:00 · 2026-03-18 22:53:28 +11:00
parent 5dcdac7ecd
commit 0b605d61c6
39 changed files with 2003 additions and 110 deletions
@@ -203,6 +203,7 @@ Controls how envelope items (individual files within the envelope) can be manage
 | `allowConfigureOrder`  | `boolean` | `true`  | Allow reordering items               |
 | `allowUpload`          | `boolean` | `true`  | Allow uploading new items            |
 | `allowDelete`          | `boolean` | `true`  | Allow deleting items                 |
+| `allowReplace`         | `boolean` | `true`  | Allow replacing an item's PDF        |

 ### Recipients

@@ -0,0 +1,368 @@
+import { useEffect, useState } from 'react';
+
+import { zodResolver } from '@hookform/resolvers/zod';
+import { Plural, Trans, useLingui } from '@lingui/react/macro';
+import type * as DialogPrimitive from '@radix-ui/react-dialog';
+import { AlertTriangleIcon, FileIcon, UploadIcon, XIcon } from 'lucide-react';
+import { type FileRejection, useDropzone } from 'react-dropzone';
+import { useForm } from 'react-hook-form';
+import { z } from 'zod';
+
+import { useCurrentEnvelopeEditor } from '@documenso/lib/client-only/providers/envelope-editor-provider';
+import { APP_DOCUMENT_UPLOAD_SIZE_LIMIT } from '@documenso/lib/constants/app';
+import { megabytesToBytes } from '@documenso/lib/universal/unit-convertions';
+import { trpc } from '@documenso/trpc/react';
+import { ZDocumentTitleSchema } from '@documenso/trpc/server/document-router/schema';
+import type { TReplaceEnvelopeItemPdfPayload } from '@documenso/trpc/server/envelope-router/replace-envelope-item-pdf.types';
+import { buildDropzoneRejectionDescription } from '@documenso/ui/lib/handle-dropzone-rejection';
+import { cn } from '@documenso/ui/lib/utils';
+import { Alert, AlertDescription } from '@documenso/ui/primitives/alert';
+import { Button } from '@documenso/ui/primitives/button';
+import {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@documenso/ui/primitives/dialog';
+import {
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from '@documenso/ui/primitives/form/form';
+import { Input } from '@documenso/ui/primitives/input';
+import { useToast } from '@documenso/ui/primitives/use-toast';
+
+const ZEditEnvelopeItemFormSchema = z.object({
+  title: ZDocumentTitleSchema,
+});
+
+type TEditEnvelopeItemFormSchema = z.infer<typeof ZEditEnvelopeItemFormSchema>;
+
+/**
+ * Note: This should only be visible if the envelope item is editable.
+ */
+export type EnvelopeItemEditDialogProps = {
+  envelopeItem: { id: string; title: string };
+  allowConfigureTitle: boolean;
+  trigger: React.ReactNode;
+} & Omit<DialogPrimitive.DialogProps, 'children'>;
+
+export const EnvelopeItemEditDialog = ({
+  envelopeItem,
+  allowConfigureTitle,
+  trigger,
+  ...props
+}: EnvelopeItemEditDialogProps) => {
+  const { t, i18n } = useLingui();
+  const { toast } = useToast();
+
+  const { envelope, editorFields, setLocalEnvelope, isEmbedded } = useCurrentEnvelopeEditor();
+
+  const [isOpen, setIsOpen] = useState(false);
+  const [replacementFile, setReplacementFile] = useState<{ file: File; pageCount: number } | null>(
+    null,
+  );
+  const [isDropping, setIsDropping] = useState(false);
+
+  const form = useForm<TEditEnvelopeItemFormSchema>({
+    resolver: zodResolver(ZEditEnvelopeItemFormSchema),
+    defaultValues: {
+      title: envelopeItem.title,
+    },
+  });
+
+  const { mutateAsync: replaceEnvelopeItemPdf } = trpc.envelope.item.replacePdf.useMutation({
+    onSuccess: ({ data, fields }) => {
+      setLocalEnvelope({
+        envelopeItems: envelope.envelopeItems.map((item) =>
+          item.id === data.id
+            ? { ...item, documentDataId: data.documentDataId, title: data.title }
+            : item,
+        ),
+      });
+
+      if (fields) {
+        setLocalEnvelope({ fields });
+        editorFields.resetForm(fields);
+      }
+    },
+  });
+
+  const fieldsOnExcessPages =
+    replacementFile !== null
+      ? envelope.fields.filter(
+          (field) =>
+            field.envelopeItemId === envelopeItem.id && field.page > replacementFile.pageCount,
+        )
+      : [];
+
+  const onFileDropRejected = (fileRejections: FileRejection[]) => {
+    toast({
+      title: t`Upload failed`,
+      description: i18n._(buildDropzoneRejectionDescription(fileRejections)),
+      duration: 5000,
+      variant: 'destructive',
+    });
+  };
+
+  const onFileDrop = async (files: File[]) => {
+    const file = files[0];
+
+    if (!file || isDropping) {
+      return;
+    }
+
+    setIsDropping(true);
+
+    try {
+      const arrayBuffer = await file.arrayBuffer();
+      const fileData = new Uint8Array(arrayBuffer.slice(0));
+      const { PDF } = await import('@libpdf/core');
+      const pdfDoc = await PDF.load(fileData);
+
+      setReplacementFile({
+        file,
+        pageCount: pdfDoc.getPageCount(),
+      });
+    } catch (err) {
+      console.error(err);
+
+      toast({
+        title: t`Failed to read file`,
+        description: t`The file is not a valid PDF.`,
+        variant: 'destructive',
+      });
+    }
+
+    setIsDropping(false);
+  };
+
+  const { getRootProps, getInputProps, isDragActive } = useDropzone({
+    accept: { 'application/pdf': ['.pdf'] },
+    maxFiles: 1,
+    maxSize: megabytesToBytes(APP_DOCUMENT_UPLOAD_SIZE_LIMIT),
+    disabled: form.formState.isSubmitting,
+    onDrop: (files) => void onFileDrop(files),
+    onDropRejected: onFileDropRejected,
+  });
+
+  const onSubmit = async (data: TEditEnvelopeItemFormSchema) => {
+    if (isDropping || !replacementFile) {
+      return;
+    }
+
+    try {
+      const { file, pageCount } = replacementFile;
+
+      if (isEmbedded) {
+        const arrayBuffer = await file.arrayBuffer();
+        const fileData = new Uint8Array(arrayBuffer.slice(0));
+
+        const remainingFields = envelope.fields.filter(
+          (field) => field.envelopeItemId !== envelopeItem.id || field.page <= pageCount,
+        );
+
+        setLocalEnvelope({
+          envelopeItems: envelope.envelopeItems.map((item) =>
+            item.id === envelopeItem.id ? { ...item, title: data.title, data: fileData } : item,
+          ),
+          fields: remainingFields,
+        });
+
+        editorFields.resetForm(remainingFields);
+      } else {
+        const payload = {
+          envelopeId: envelope.id,
+          envelopeItemId: envelopeItem.id,
+          title: data.title,
+        } satisfies TReplaceEnvelopeItemPdfPayload;
+
+        const formData = new FormData();
+        formData.append('payload', JSON.stringify(payload));
+        formData.append('file', file);
+
+        await replaceEnvelopeItemPdf(formData);
+      }
+
+      setIsOpen(false);
+    } catch {
+      toast({
+        title: t`Failed to update item`,
+        description: t`Something went wrong while updating the envelope item.`,
+        variant: 'destructive',
+      });
+    }
+  };
+
+  useEffect(() => {
+    if (!isOpen) {
+      form.reset({ title: envelopeItem.title });
+      setReplacementFile(null);
+      setIsDropping(false);
+    }
+  }, [isOpen, form, envelopeItem.title]);
+
+  const formatFileSize = (bytes: number) => {
+    if (bytes < 1024) {
+      return `${bytes} B`;
+    }
+
+    if (bytes < 1024 * 1024) {
+      return `${(bytes / 1024).toFixed(1)} KB`;
+    }
+
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  };
+
+  return (
+    <Dialog
+      {...props}
+      open={isOpen}
+      onOpenChange={(value) => !form.formState.isSubmitting && setIsOpen(value)}
+    >
+      <DialogTrigger onClick={(e) => e.stopPropagation()} asChild>
+        {trigger}
+      </DialogTrigger>
+
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>
+            <Trans>Edit Item</Trans>
+          </DialogTitle>
+          <DialogDescription>
+            <Trans>Update the title or replace the PDF file.</Trans>
+          </DialogDescription>
+        </DialogHeader>
+
+        <Form {...form}>
+          <form onSubmit={form.handleSubmit(onSubmit)}>
+            <fieldset disabled={form.formState.isSubmitting} className="space-y-4">
+              <FormField
+                control={form.control}
+                name="title"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>
+                      <Trans>Document Title</Trans>
+                    </FormLabel>
+                    <FormControl>
+                      <Input
+                        data-testid="envelope-item-edit-title-input"
+                        placeholder={t`Document Title`}
+                        disabled={!allowConfigureTitle}
+                        {...field}
+                      />
+                    </FormControl>
+                    <FormMessage />
+                  </FormItem>
+                )}
+              />
+
+              <div>
+                <FormLabel>
+                  <Trans>Replace PDF</Trans>
+                </FormLabel>
+
+                {replacementFile ? (
+                  <div className="mt-1.5 space-y-2">
+                    <div
+                      data-testid="envelope-item-edit-selected-file"
+                      className="flex items-center justify-between rounded-md border border-border bg-muted/50 px-3 py-2"
+                    >
+                      <div className="flex min-w-0 items-center space-x-2">
+                        <FileIcon className="h-4 w-4 flex-shrink-0 text-muted-foreground" />
+                        <div className="min-w-0">
+                          <p className="truncate text-sm font-medium">
+                            {replacementFile.file.name}
+                          </p>
+                          <p className="text-xs text-muted-foreground">
+                            {formatFileSize(replacementFile.file.size)}
+                            {isDropping ? ' · …' : ' · '}
+                            {!isDropping && replacementFile.pageCount !== null && (
+                              <Plural
+                                one="1 page"
+                                other="# pages"
+                                value={replacementFile.pageCount}
+                              />
+                            )}
+                          </p>
+                        </div>
+                      </div>
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="sm"
+                        data-testid="envelope-item-edit-clear-file"
+                        onClick={() => {
+                          setReplacementFile(null);
+                        }}
+                      >
+                        <XIcon className="h-4 w-4" />
+                      </Button>
+                    </div>
+
+                    {fieldsOnExcessPages.length > 0 && (
+                      <Alert variant="warning" padding="tight">
+                        <AlertTriangleIcon className="h-4 w-4" />
+                        <AlertDescription data-testid="envelope-item-edit-field-warning">
+                          <Plural
+                            one="1 field will be deleted because the new PDF has fewer pages than the current one."
+                            other="# fields will be deleted because the new PDF has fewer pages than the current one."
+                            value={fieldsOnExcessPages.length}
+                          />
+                        </AlertDescription>
+                      </Alert>
+                    )}
+                  </div>
+                ) : (
+                  <div
+                    data-testid="envelope-item-edit-dropzone"
+                    {...getRootProps()}
+                    className={cn(
+                      'mt-1.5 flex cursor-pointer items-center justify-center rounded-md border border-dashed border-border px-4 py-4 transition-colors',
+                      isDragActive
+                        ? 'border-primary/50 bg-primary/5'
+                        : 'hover:border-muted-foreground/50 hover:bg-muted/50',
+                    )}
+                  >
+                    <input {...getInputProps()} />
+                    <div className="flex items-center space-x-2 text-sm text-muted-foreground">
+                      <UploadIcon className="h-4 w-4" />
+                      <span>
+                        <Trans>Drop PDF here or click to select</Trans>
+                      </span>
+                    </div>
+                  </div>
+                )}
+              </div>
+
+              <DialogFooter>
+                <DialogClose asChild>
+                  <Button type="button" variant="secondary">
+                    <Trans>Cancel</Trans>
+                  </Button>
+                </DialogClose>
+
+                <Button
+                  type="submit"
+                  loading={form.formState.isSubmitting}
+                  disabled={isDropping || !replacementFile}
+                  data-testid="envelope-item-edit-update-button"
+                >
+                  <Trans>Update</Trans>
+                </Button>
+              </DialogFooter>
+            </fieldset>
+          </form>
+        </Form>
+      </DialogContent>
+    </Dialog>
+  );
+};
@@ -4,10 +4,11 @@ import { msg } from '@lingui/core/macro';
 import { useLingui } from '@lingui/react';
 import { Trans } from '@lingui/react/macro';
 import { Cloud, FileText, Loader, X } from 'lucide-react';
-import { useDropzone } from 'react-dropzone';
+import { type FileRejection, useDropzone } from 'react-dropzone';
 import { useFormContext } from 'react-hook-form';

 import { APP_DOCUMENT_UPLOAD_SIZE_LIMIT } from '@documenso/lib/constants/app';
+import { buildDropzoneRejectionDescription } from '@documenso/ui/lib/handle-dropzone-rejection';
 import { cn } from '@documenso/ui/lib/utils';
 import { Button } from '@documenso/ui/primitives/button';
 import {
@@ -82,10 +83,10 @@ export const ConfigureDocumentUpload = ({ isSubmitting = false }: ConfigureDocum
    }
  };

-  const onDropRejected = () => {
+  const onDropRejected = (fileRejections: FileRejection[]) => {
    toast({
      title: _(msg`Your document failed to upload.`),
-      description: _(msg`File cannot be larger than ${APP_DOCUMENT_UPLOAD_SIZE_LIMIT}MB`),
+      description: _(buildDropzoneRejectionDescription(fileRejections)),
      duration: 5000,
      variant: 'destructive',
    });
@@ -144,7 +145,7 @@ export const ConfigureDocumentUpload = ({ isSubmitting = false }: ConfigureDocum
                    <div
                      {...getRootProps()}
                      className={cn(
-                        'border-border bg-background relative flex min-h-[160px] cursor-pointer flex-col items-center justify-center rounded-lg border border-dashed transition',
+                        'relative flex min-h-[160px] cursor-pointer flex-col items-center justify-center rounded-lg border border-dashed border-border bg-background transition',
                        {
                          'border-primary/50 bg-primary/5': isDragActive,
                          'hover:bg-muted/30':
@@ -193,21 +194,21 @@ export const ConfigureDocumentUpload = ({ isSubmitting = false }: ConfigureDocum
                  </FormControl>

                  {isLoading && (
-                    <div className="bg-background/50 absolute inset-0 flex items-center justify-center rounded-lg">
-                      <Loader className="text-muted-foreground h-10 w-10 animate-spin" />
+                    <div className="absolute inset-0 flex items-center justify-center rounded-lg bg-background/50">
+                      <Loader className="h-10 w-10 animate-spin text-muted-foreground" />
                    </div>
                  )}
                </div>
              ) : (
                <div className="mt-2 rounded-lg border p-4">
                  <div className="flex items-center gap-x-4">
-                    <div className="bg-primary/10 text-primary flex h-12 w-12 items-center justify-center rounded-md">
+                    <div className="flex h-12 w-12 items-center justify-center rounded-md bg-primary/10 text-primary">
                      <FileText className="h-6 w-6" />
                    </div>

                    <div className="flex-1">
                      <div className="text-sm font-medium">{documentData.name}</div>
-                      <div className="text-muted-foreground text-xs">
+                      <div className="text-xs text-muted-foreground">
                        {formatFileSize(documentData.size)}
                      </div>
                    </div>
@@ -4,6 +4,7 @@ import { msg } from '@lingui/core/macro';
 import { useLingui } from '@lingui/react';
 import { Trans } from '@lingui/react/macro';
 import { EnvelopeType } from '@prisma/client';
+import type { FileRejection } from 'react-dropzone';
 import { useNavigate, useParams } from 'react-router';
 import { match } from 'ts-pattern';

@@ -11,13 +12,13 @@ import { useLimits } from '@documenso/ee/server-only/limits/provider/client';
 import { useAnalytics } from '@documenso/lib/client-only/hooks/use-analytics';
 import { useCurrentOrganisation } from '@documenso/lib/client-only/providers/organisation';
 import { useSession } from '@documenso/lib/client-only/providers/session';
-import { APP_DOCUMENT_UPLOAD_SIZE_LIMIT } from '@documenso/lib/constants/app';
 import { DEFAULT_DOCUMENT_TIME_ZONE, TIME_ZONES } from '@documenso/lib/constants/time-zones';
 import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
 import { formatDocumentsPath, formatTemplatesPath } from '@documenso/lib/utils/teams';
 import { trpc } from '@documenso/trpc/react';
 import type { TCreateDocumentPayloadSchema } from '@documenso/trpc/server/document-router/create-document.types';
 import type { TCreateTemplatePayloadSchema } from '@documenso/trpc/server/template-router/schema';
+import { buildDropzoneRejectionDescription } from '@documenso/ui/lib/handle-dropzone-rejection';
 import { cn } from '@documenso/ui/lib/utils';
 import { DocumentUploadButton as DocumentUploadButtonPrimitive } from '@documenso/ui/primitives/document-upload-button';
 import {
@@ -162,10 +163,10 @@ export const DocumentUploadButtonLegacy = ({
    }
  };

-  const onFileDropRejected = () => {
+  const onFileDropRejected = (fileRejections: FileRejection[]) => {
    toast({
      title: _(msg`Your document failed to upload.`),
-      description: _(msg`File cannot be larger than ${APP_DOCUMENT_UPLOAD_SIZE_LIMIT}MB`),
+      description: _(buildDropzoneRejectionDescription(fileRejections)),
      duration: 5000,
      variant: 'destructive',
    });
@@ -5,7 +5,7 @@ import { msg } from '@lingui/core/macro';
 import { useLingui } from '@lingui/react';
 import { Trans } from '@lingui/react/macro';
 import { DocumentStatus, FieldType, RecipientRole } from '@prisma/client';
-import { FileTextIcon, SparklesIcon } from 'lucide-react';
+import { FileTextIcon, PencilIcon, SparklesIcon } from 'lucide-react';
 import { useRevalidator, useSearchParams } from 'react-router';
 import { isDeepEqual } from 'remeda';
 import { match } from 'ts-pattern';
@@ -28,14 +28,17 @@ import {
  type TSignatureFieldMeta,
  type TTextFieldMeta,
 } from '@documenso/lib/types/field-meta';
+import { canEnvelopeItemsBeModified } from '@documenso/lib/utils/envelope';
 import { canRecipientFieldsBeModified } from '@documenso/lib/utils/recipients';
 import { AnimateGenericFadeInOut } from '@documenso/ui/components/animate/animate-generic-fade-in-out';
+import { cn } from '@documenso/ui/lib/utils';
 import { Alert, AlertDescription, AlertTitle } from '@documenso/ui/primitives/alert';
 import { Button } from '@documenso/ui/primitives/button';
 import { Separator } from '@documenso/ui/primitives/separator';

 import { AiFeaturesEnableDialog } from '~/components/dialogs/ai-features-enable-dialog';
 import { AiFieldDetectionDialog } from '~/components/dialogs/ai-field-detection-dialog';
+import { EnvelopeItemEditDialog } from '~/components/dialogs/envelope-item-edit-dialog';
 import { EditorFieldCheckboxForm } from '~/components/forms/editor/editor-field-checkbox-form';
 import { EditorFieldDateForm } from '~/components/forms/editor/editor-field-date-form';
 import { EditorFieldDropdownForm } from '~/components/forms/editor/editor-field-dropdown-form';
@@ -85,6 +88,11 @@ export const EnvelopeEditorFieldsPage = () => {
  const [isAiEnableDialogOpen, setIsAiEnableDialogOpen] = useState(false);
  const { revalidate } = useRevalidator();

+  const canItemsBeModified = useMemo(
+    () => canEnvelopeItemsBeModified(envelope, envelope.recipients),
+    [envelope, envelope.recipients],
+  );
+
  const selectedField = useMemo(
    () => structuredClone(editorFields.selectedField),
    [editorFields.selectedField],
@@ -157,7 +165,39 @@ export const EnvelopeEditorFieldsPage = () => {
        ref={scrollableContainerRef}
      >
        {/* Horizontal envelope item selector */}
-        <EnvelopeRendererFileSelector className="px-0" fields={editorFields.localFields} />
+        <EnvelopeRendererFileSelector
+          className="px-0"
+          fields={editorFields.localFields}
+          renderItemAction={
+            editorConfig.envelopeItems !== null &&
+            editorConfig.envelopeItems.allowReplace &&
+            canItemsBeModified
+              ? (item) => (
+                  <div className="relative flex h-5 w-5 flex-shrink-0 items-center justify-center">
+                    <div
+                      className={cn(
+                        'h-2 w-2 rounded-full transition-opacity duration-150 group-hover:opacity-0',
+                        { 'bg-green-500': currentEnvelopeItem?.id === item.id },
+                      )}
+                    />
+                    <EnvelopeItemEditDialog
+                      envelopeItem={item}
+                      allowConfigureTitle={editorConfig.envelopeItems?.allowConfigureTitle ?? false}
+                      trigger={
+                        <span
+                          className="absolute inset-0 flex cursor-pointer items-center justify-center opacity-0 transition-opacity duration-150 group-hover:opacity-100"
+                          onClick={(e) => e.stopPropagation()}
+                          data-testid={`envelope-item-edit-button-${item.id}`}
+                        >
+                          <PencilIcon className="h-3.5 w-3.5" />
+                        </span>
+                      }
+                    />
+                  </div>
+                )
+              : undefined
+          }
+        />

        {/* Document View */}
        <div className="mt-4 flex h-full flex-col items-center justify-center">
@@ -5,9 +5,8 @@ import type { DropResult } from '@hello-pangea/dnd';
 import { msg, plural } from '@lingui/core/macro';
 import { Trans, useLingui } from '@lingui/react/macro';
 import { DocumentStatus } from '@prisma/client';
-import { FileWarningIcon, GripVerticalIcon, Loader2 } from 'lucide-react';
-import { X } from 'lucide-react';
-import { ErrorCode as DropzoneErrorCode, type FileRejection } from 'react-dropzone';
+import { FileWarningIcon, GripVerticalIcon, Loader2Icon, PencilIcon, XIcon } from 'lucide-react';
+import { ErrorCode as DropzoneErrorCode, type FileRejection, useDropzone } from 'react-dropzone';

 import { useLimits } from '@documenso/ee/server-only/limits/provider/client';
 import { useEnvelopeAutosave } from '@documenso/lib/client-only/hooks/use-envelope-autosave';
@@ -16,10 +15,13 @@ import { useCurrentOrganisation } from '@documenso/lib/client-only/providers/org
 import { APP_DOCUMENT_UPLOAD_SIZE_LIMIT } from '@documenso/lib/constants/app';
 import type { TEditorEnvelope } from '@documenso/lib/types/envelope-editor';
 import { nanoid } from '@documenso/lib/universal/id';
+import { megabytesToBytes } from '@documenso/lib/universal/unit-convertions';
 import { PRESIGNED_ENVELOPE_ITEM_ID_PREFIX } from '@documenso/lib/utils/embed-config';
 import { canEnvelopeItemsBeModified } from '@documenso/lib/utils/envelope';
 import { trpc } from '@documenso/trpc/react';
 import type { TCreateEnvelopeItemsPayload } from '@documenso/trpc/server/envelope-router/create-envelope-items.types';
+import type { TReplaceEnvelopeItemPdfPayload } from '@documenso/trpc/server/envelope-router/replace-envelope-item-pdf.types';
+import { buildDropzoneRejectionDescription } from '@documenso/ui/lib/handle-dropzone-rejection';
 import { Button } from '@documenso/ui/primitives/button';
 import {
  Card,
@@ -41,13 +43,14 @@ type LocalFile = {
  title: string;
  envelopeItemId: string | null;
  isUploading: boolean;
+  isReplacing: boolean;
  isError: boolean;
 };

 export const EnvelopeEditorUploadPage = () => {
  const organisation = useCurrentOrganisation();

-  const { t } = useLingui();
+  const { t, i18n } = useLingui();
  const { maximumEnvelopeItemCount, remaining } = useLimits();
  const { toast } = useToast();

@@ -72,10 +75,36 @@ export const EnvelopeEditorUploadPage = () => {
        title: item.title,
        envelopeItemId: item.id,
        isUploading: false,
+        isReplacing: false,
        isError: false,
      })),
  );

+  const replacingItemIdRef = useRef<string | null>(null);
+
+  const { open: openReplaceFilePicker, getInputProps: getReplaceInputProps } = useDropzone({
+    accept: { 'application/pdf': ['.pdf'] },
+    maxFiles: 1,
+    maxSize: megabytesToBytes(APP_DOCUMENT_UPLOAD_SIZE_LIMIT),
+    multiple: false,
+    noClick: true,
+    noKeyboard: true,
+    noDrag: true,
+    onDrop: (acceptedFiles) => {
+      const file = acceptedFiles[0];
+      const replacingItemId = replacingItemIdRef.current;
+
+      if (file && replacingItemId) {
+        void onReplacePdf(replacingItemId, file);
+        replacingItemIdRef.current = null;
+      }
+    },
+    onDropRejected: (fileRejections) => void onFileDropRejected(fileRejections),
+    onFileDialogCancel: () => {
+      replacingItemIdRef.current = null;
+    },
+  });
+
  const { mutateAsync: createEnvelopeItems, isPending: isCreatingEnvelopeItems } =
    trpc.envelope.item.createMany.useMutation({
      onSuccess: ({ data }) => {
@@ -108,6 +137,24 @@ export const EnvelopeEditorUploadPage = () => {
    },
  });

+  const { mutateAsync: replaceEnvelopeItemPdf } = trpc.envelope.item.replacePdf.useMutation({
+    onSuccess: ({ data, fields }) => {
+      // Update the envelope item with the new documentDataId.
+      setLocalEnvelope({
+        envelopeItems: envelope.envelopeItems.map((item) =>
+          item.id === data.id ? { ...item, documentDataId: data.documentDataId } : item,
+        ),
+      });
+
+      // When fields were created or deleted during the replacement,
+      // the server returns the full updated field list.
+      if (fields) {
+        setLocalEnvelope({ fields });
+        editorFields.resetForm(fields);
+      }
+    },
+  });
+
  const canItemsBeModified = useMemo(
    () => canEnvelopeItemsBeModified(envelope, envelope.recipients),
    [envelope, envelope.recipients],
@@ -125,6 +172,7 @@ export const EnvelopeEditorUploadPage = () => {
          title: file.name,
          file,
          isUploading: isEmbedded ? false : true,
+          isReplacing: false,
          // Clone the buffer so it can be read multiple times (File.arrayBuffer() consumes the stream once)
          data: isEmbedded ? new Uint8Array((await file.arrayBuffer()).slice(0)) : null,
          isError: false,
@@ -197,12 +245,77 @@ export const EnvelopeEditorUploadPage = () => {
          envelopeItemId: item.id,
          title: item.title,
          isUploading: false,
+          isReplacing: false,
          isError: false,
        })),
      );
    });
  };

+  const onReplacePdf = async (envelopeItemId: string, file: File) => {
+    setLocalFiles((prev) =>
+      prev.map((f) => (f.envelopeItemId === envelopeItemId ? { ...f, isReplacing: true } : f)),
+    );
+
+    try {
+      if (isEmbedded) {
+        // For embedded mode, store the file data locally on the envelope item.
+        // The actual replacement will happen when the embed flow submits.
+        const arrayBuffer = await file.arrayBuffer();
+        const data = new Uint8Array(arrayBuffer.slice(0));
+
+        // Count pages in the new PDF to remove out-of-bounds fields.
+        const { PDF } = await import('@libpdf/core');
+        const pdfDoc = await PDF.load(data);
+        const newPageCount = pdfDoc.getPageCount();
+
+        // Remove fields that are on pages beyond the new PDF's page count.
+        const remainingFields = envelope.fields.filter(
+          (field) => field.envelopeItemId !== envelopeItemId || field.page <= newPageCount,
+        );
+
+        setLocalEnvelope({
+          envelopeItems: envelope.envelopeItems.map((item) =>
+            item.id === envelopeItemId ? { ...item, data } : item,
+          ),
+          fields: remainingFields,
+        });
+
+        editorFields.resetForm(remainingFields);
+
+        return;
+      }
+
+      // Normal mode: upload immediately via tRPC.
+      const payload = {
+        envelopeId: envelope.id,
+        envelopeItemId,
+      } satisfies TReplaceEnvelopeItemPdfPayload;
+
+      const formData = new FormData();
+      formData.append('payload', JSON.stringify(payload));
+      formData.append('file', file);
+
+      const replacePromise = replaceEnvelopeItemPdf(formData);
+      registerPendingMutation(replacePromise);
+
+      await replacePromise;
+    } catch (error) {
+      console.error(error);
+
+      toast({
+        title: t`Replace failed`,
+        description: t`Something went wrong while replacing the PDF`,
+        duration: 5000,
+        variant: 'destructive',
+      });
+    } finally {
+      setLocalFiles((prev) =>
+        prev.map((f) => (f.envelopeItemId === envelopeItemId ? { ...f, isReplacing: false } : f)),
+      );
+    }
+  };
+
  /**
   * Hide the envelope item from the list on deletion.
   */
@@ -346,7 +459,7 @@ export const EnvelopeEditorUploadPage = () => {

    toast({
      title: t`Upload failed`,
-      description: t`File cannot be larger than ${APP_DOCUMENT_UPLOAD_SIZE_LIMIT}MB`,
+      description: i18n._(buildDropzoneRejectionDescription(fileRejections)),
      duration: 5000,
      variant: 'destructive',
    });
@@ -354,6 +467,7 @@ export const EnvelopeEditorUploadPage = () => {

  return (
    <div className="mx-auto max-w-4xl space-y-6 p-8">
+      <input {...getReplaceInputProps()} />
      <Card backdropBlur={false} className="border">
        <CardHeader className="pb-3">
          <CardTitle>
@@ -395,6 +509,7 @@ export const EnvelopeEditorUploadPage = () => {
                        key={localFile.id}
                        isDragDisabled={
                          isCreatingEnvelopeItems ||
+                          localFile.isReplacing ||
                          !canItemsBeModified ||
                          !uploadConfig?.allowConfigureOrder
                        }
@@ -427,7 +542,8 @@ export const EnvelopeEditorUploadPage = () => {
                                  <EnvelopeItemTitleInput
                                    disabled={
                                      envelope.status !== DocumentStatus.DRAFT ||
-                                      !uploadConfig?.allowConfigureTitle
+                                      !uploadConfig?.allowConfigureTitle ||
+                                      localFile.isReplacing
                                    }
                                    value={localFile.title}
                                    dataTestId={`envelope-item-title-input-${localFile.id}`}
@@ -445,15 +561,14 @@ export const EnvelopeEditorUploadPage = () => {
                                    <Trans>Uploading</Trans>
                                  ) : localFile.isError ? (
                                    <Trans>Something went wrong while uploading this file</Trans>
-                                  ) : // <div className="text-xs text-gray-500">2.4 MB • 3 pages</div>
-                                  null}
+                                  ) : null}
                                </div>
                              </div>
                            </div>
                            <div className="flex items-center space-x-2">
                              {localFile.isUploading && (
                                <div className="flex h-6 w-10 items-center justify-center">
-                                  <Loader2 className="h-4 w-4 animate-spin text-muted-foreground" />
+                                  <Loader2Icon className="h-4 w-4 animate-spin text-muted-foreground" />
                                </div>
                              )}

@@ -463,8 +578,28 @@ export const EnvelopeEditorUploadPage = () => {
                                </div>
                              )}

-                              {!localFile.isUploading &&
-                                localFile.envelopeItemId &&
+                              {localFile.envelopeItemId &&
+                                canItemsBeModified &&
+                                uploadConfig?.allowReplace && (
+                                  <Button
+                                    variant="ghost"
+                                    size="sm"
+                                    data-testid={`envelope-item-replace-button-${localFile.id}`}
+                                    disabled={localFile.isReplacing || localFile.isUploading}
+                                    onClick={() => {
+                                      replacingItemIdRef.current = localFile.envelopeItemId;
+                                      openReplaceFilePicker();
+                                    }}
+                                  >
+                                    {localFile.isReplacing ? (
+                                      <Loader2Icon className="h-4 w-4 animate-spin text-muted-foreground" />
+                                    ) : (
+                                      <PencilIcon className="h-4 w-4" />
+                                    )}
+                                  </Button>
+                                )}
+
+                              {localFile.envelopeItemId &&
                                uploadConfig?.allowDelete &&
                                (isEmbedded ? (
                                  <Button
@@ -472,8 +607,9 @@ export const EnvelopeEditorUploadPage = () => {
                                    size="sm"
                                    data-testid={`envelope-item-remove-button-${localFile.id}`}
                                    onClick={() => onFileDelete(localFile.envelopeItemId!)}
+                                    disabled={localFile.isReplacing || localFile.isUploading}
                                  >
-                                    <X className="h-4 w-4" />
+                                    <XIcon className="h-4 w-4" />
                                  </Button>
                                ) : (
                                  <EnvelopeItemDeleteDialog
@@ -487,8 +623,9 @@ export const EnvelopeEditorUploadPage = () => {
                                        variant="ghost"
                                        size="sm"
                                        data-testid={`envelope-item-remove-button-${localFile.id}`}
+                                        disabled={localFile.isReplacing || localFile.isUploading}
                                      >
-                                        <X className="h-4 w-4" />
+                                        <XIcon className="h-4 w-4" />
                                      </Button>
                                    }
                                  />
@@ -9,6 +9,7 @@ type EnvelopeItemSelectorProps = {
  secondaryText: React.ReactNode;
  isSelected: boolean;
  buttonProps: React.ButtonHTMLAttributes<HTMLButtonElement>;
+  actionSlot?: React.ReactNode;
 };

 export const EnvelopeItemSelector = ({
@@ -17,11 +18,12 @@ export const EnvelopeItemSelector = ({
  secondaryText,
  isSelected,
  buttonProps,
+  actionSlot,
 }: EnvelopeItemSelectorProps) => {
  return (
    <button
      title={typeof primaryText === 'string' ? primaryText : undefined}
-      className={`flex h-fit max-w-72 flex-shrink-0 cursor-pointer items-center space-x-3 rounded-lg border px-4 py-3 transition-colors ${
+      className={`group flex h-fit max-w-72 flex-shrink-0 cursor-pointer items-center space-x-3 rounded-lg border px-4 py-3 transition-colors ${
        isSelected
          ? 'border-green-200 bg-green-50 text-green-900 dark:border-green-400/30 dark:bg-green-400/10 dark:text-green-400'
          : 'border-border bg-muted/50 hover:bg-muted/70'
@@ -39,11 +41,13 @@ export const EnvelopeItemSelector = ({
        <div className="truncate text-sm font-medium">{primaryText}</div>
        <div className="text-xs text-gray-500">{secondaryText}</div>
      </div>
-      <div
-        className={cn('h-2 w-2 flex-shrink-0 rounded-full', {
-          'bg-green-500': isSelected,
-        })}
-      ></div>
+      {actionSlot ?? (
+        <div
+          className={cn('h-2 w-2 flex-shrink-0 rounded-full', {
+            'bg-green-500': isSelected,
+          })}
+        />
+      )}
    </button>
  );
 };
@@ -52,12 +56,14 @@ type EnvelopeRendererFileSelectorProps = {
  fields: { envelopeItemId: string }[];
  className?: string;
  secondaryOverride?: React.ReactNode;
+  renderItemAction?: (item: { id: string; title: string }) => React.ReactNode;
 };

 export const EnvelopeRendererFileSelector = ({
  fields,
  className,
  secondaryOverride,
+  renderItemAction,
 }: EnvelopeRendererFileSelectorProps) => {
  const { envelopeItems, currentEnvelopeItem, setCurrentEnvelopeItem } = useCurrentEnvelopeRender();

@@ -86,6 +92,7 @@ export const EnvelopeRendererFileSelector = ({
          buttonProps={{
            onClick: () => setCurrentEnvelopeItem(doc.id),
          }}
+          actionSlot={renderItemAction?.(doc)}
        />
      ))}
    </div>
@@ -5,12 +5,7 @@ import { useLingui } from '@lingui/react/macro';
 import { Trans } from '@lingui/react/macro';
 import { EnvelopeType } from '@prisma/client';
 import { Loader } from 'lucide-react';
-import {
-  ErrorCode as DropzoneErrorCode,
-  ErrorCode,
-  type FileRejection,
-  useDropzone,
-} from 'react-dropzone';
+import { ErrorCode as DropzoneErrorCode, type FileRejection, useDropzone } from 'react-dropzone';
 import { Link, useNavigate, useParams } from 'react-router';
 import { match } from 'ts-pattern';

@@ -25,6 +20,7 @@ import { megabytesToBytes } from '@documenso/lib/universal/unit-convertions';
 import { formatDocumentsPath, formatTemplatesPath } from '@documenso/lib/utils/teams';
 import { trpc } from '@documenso/trpc/react';
 import type { TCreateEnvelopePayload } from '@documenso/trpc/server/envelope-router/create-envelope.types';
+import { buildDropzoneRejectionDescription } from '@documenso/ui/lib/handle-dropzone-rejection';
 import { cn } from '@documenso/ui/lib/utils';
 import { useToast } from '@documenso/ui/primitives/use-toast';

@@ -41,7 +37,7 @@ export const EnvelopeDropZoneWrapper = ({
  type,
  className,
 }: EnvelopeDropZoneWrapperProps) => {
-  const { t } = useLingui();
+  const { t, i18n } = useLingui();
  const { toast } = useToast();
  const { user } = useSession();
  const { folderId } = useParams();
@@ -167,42 +163,9 @@ export const EnvelopeDropZoneWrapper = ({
      return;
    }

-    // Since users can only upload only one file (no multi-upload), we only handle the first file rejection
-    const { file, errors } = fileRejections[0];
-
-    if (!errors.length) {
-      return;
-    }
-
-    const errorNodes = errors.map((error, index) => (
-      <span key={index} className="block">
-        {match(error.code)
-          .with(ErrorCode.FileTooLarge, () => (
-            <Trans>File is larger than {APP_DOCUMENT_UPLOAD_SIZE_LIMIT}MB</Trans>
-          ))
-          .with(ErrorCode.FileInvalidType, () => <Trans>Only PDF files are allowed</Trans>)
-          .with(ErrorCode.FileTooSmall, () => <Trans>File is too small</Trans>)
-          .with(ErrorCode.TooManyFiles, () => (
-            <Trans>Only one file can be uploaded at a time</Trans>
-          ))
-          .otherwise(() => (
-            <Trans>Unknown error</Trans>
-          ))}
-      </span>
-    ));
-
-    const description = (
-      <>
-        <span className="font-medium">
-          <Trans>{file.name} couldn't be uploaded:</Trans>
-        </span>
-        {errorNodes}
-      </>
-    );
-
    toast({
      title: t`Upload failed`,
-      description,
+      description: i18n._(buildDropzoneRejectionDescription(fileRejections)),
      duration: 5000,
      variant: 'destructive',
    });
@@ -11,12 +11,12 @@ import { match } from 'ts-pattern';
 import { useLimits } from '@documenso/ee/server-only/limits/provider/client';
 import { useCurrentOrganisation } from '@documenso/lib/client-only/providers/organisation';
 import { useSession } from '@documenso/lib/client-only/providers/session';
-import { APP_DOCUMENT_UPLOAD_SIZE_LIMIT } from '@documenso/lib/constants/app';
 import { TIME_ZONES } from '@documenso/lib/constants/time-zones';
 import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
 import { formatDocumentsPath, formatTemplatesPath } from '@documenso/lib/utils/teams';
 import { trpc } from '@documenso/trpc/react';
 import type { TCreateEnvelopePayload } from '@documenso/trpc/server/envelope-router/create-envelope.types';
+import { buildDropzoneRejectionDescription } from '@documenso/ui/lib/handle-dropzone-rejection';
 import { cn } from '@documenso/ui/lib/utils';
 import { DocumentUploadButton } from '@documenso/ui/primitives/document-upload-button';
 import {
@@ -39,7 +39,7 @@ export type EnvelopeUploadButtonProps = {
 * Upload an envelope
 */
 export const EnvelopeUploadButton = ({ className, type, folderId }: EnvelopeUploadButtonProps) => {
-  const { t } = useLingui();
+  const { t, i18n } = useLingui();
  const { toast } = useToast();
  const { user } = useSession();

@@ -168,7 +168,7 @@ export const EnvelopeUploadButton = ({ className, type, folderId }: EnvelopeUplo

    toast({
      title: t`Upload failed`,
-      description: t`File cannot be larger than ${APP_DOCUMENT_UPLOAD_SIZE_LIMIT}MB`,
+      description: i18n._(buildDropzoneRejectionDescription(fileRejections)),
      duration: 5000,
      variant: 'destructive',
    });
@@ -79,6 +79,7 @@ export default function EmbedPlaygroundPage() {
    allowConfigureOrder: true,
    allowUpload: true,
    allowDelete: true,
+    allowReplace: true,
  });

  const [recipientsFeatures, setRecipientsFeatures] = useState({
@@ -17,7 +17,10 @@ import {
  ZEmbedEditEnvelopeAuthoringSchema,
 } from '@documenso/lib/types/envelope-editor';
 import type { TEnvelopeFieldAndMeta } from '@documenso/lib/types/field-meta';
-import { buildEmbeddedEditorOptions } from '@documenso/lib/utils/embed-config';
+import {
+  PRESIGNED_ENVELOPE_ITEM_ID_PREFIX,
+  buildEmbeddedEditorOptions,
+} from '@documenso/lib/utils/embed-config';
 import { prisma } from '@documenso/prisma';
 import { trpc } from '@documenso/trpc/react';
 import type { TUpdateEmbeddingEnvelopePayload } from '@documenso/trpc/server/embedding-router/update-embedding-envelope.types';
@@ -172,7 +175,9 @@ const EnvelopeEditPage = ({ embedAuthoringOptions }: EnvelopeEditPageProps) => {
    const files: File[] = [];

    const envelopeItems = envelope.envelopeItems.map((item) => {
-      // Attach any new envelope item files to the request.
+      const isNewItem = item.id.startsWith(PRESIGNED_ENVELOPE_ITEM_ID_PREFIX);
+
+      // Attach any new or replacement envelope item files to the request.
      if (item.data) {
        files.push(
          new File(
@@ -189,7 +194,10 @@ const EnvelopeEditPage = ({ embedAuthoringOptions }: EnvelopeEditPageProps) => {
        id: item.id,
        title: item.title,
        order: item.order,
-        index: item.data ? files.length - 1 : undefined,
+        // For new items, use `index` to reference the file.
+        index: isNewItem && item.data ? files.length - 1 : undefined,
+        // For existing items being replaced, use `replaceFileIndex`.
+        replaceFileIndex: !isNewItem && item.data ? files.length - 1 : undefined,
      };
    });

@@ -59,6 +59,8 @@ export default defineConfig({
      'playwright-core',
      '@playwright/browser-chromium',
      'pdfjs-dist',
+      '@google-cloud/kms',
+      '@google-cloud/secret-manager',
    ],
  },
  optimizeDeps: {
@@ -101,6 +103,8 @@ export default defineConfig({
        '@napi-rs/canvas',
        '@node-rs/bcrypt',
        '@aws-sdk/cloudfront-signer',
+        '@google-cloud/kms',
+        '@google-cloud/secret-manager',
        'nodemailer',
        /playwright/,
        '@playwright/browser-chromium',