From a56f95f182f87ede9b77eff240f4be934f5b50a6 Mon Sep 17 00:00:00 2001
From: Camiel van Schoonhoven <camiel.vanschoonhoven@shopify.com>
Date: Mon, 2 Nov 2026 13:28:14 -0700
Subject: [PATCH 1/5] feat(documents): add a document from a file, in a code
 editor

The Add a document dialog had two plain fields, so the only way to add an
existing file was to paste it in. Long content also pushed the dialog off
the page: the textarea grew to fit every line, down and sideways.

A dashed strip above Title now takes a dropped file, or a browsed one. The
whole form accepts the drop, so a near miss doesn't open the file in the
tab. The file's name becomes the title unless one was typed, and its text
becomes the content. Only UTF-8 text up to 1 MB is accepted; anything else
says why and leaves the fields alone.

Content is now the shared code editor in a fixed-height box, with word
wrap, so long files scroll and long lines wrap. It highlights by the
title's extension, the same rule the document viewers use, which is why a
dropped file keeps its extension in the title. Both document dialogs are
wider to give the editor room. CodeEditor takes an options override for
the editor's aria label and placeholder.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../Project/AddDocumentDialog.test.tsx        |  18 ++
 src/components/Project/AddDocumentDialog.tsx  |   2 +-
 .../Project/DocumentFileDropZone.tsx          |  77 +++++++
 src/components/Project/DocumentForm.test.tsx  | 213 ++++++++++++++++++
 src/components/Project/DocumentForm.tsx       |  66 +++++-
 src/components/Project/documentFile.test.ts   |  55 +++++
 src/components/Project/documentFile.ts        |  42 ++++
 src/components/Project/useFileDrop.ts         |  45 ++++
 .../shared/CodeViewer/CodeEditor.tsx          |  11 +-
 .../Tangent/components/AddResourceButton.tsx  |   6 +-
 10 files changed, 519 insertions(+), 16 deletions(-)
 create mode 100644 src/components/Project/DocumentFileDropZone.tsx
 create mode 100644 src/components/Project/DocumentForm.test.tsx
 create mode 100644 src/components/Project/documentFile.test.ts
 create mode 100644 src/components/Project/documentFile.ts
 create mode 100644 src/components/Project/useFileDrop.ts

diff --git a/src/components/Project/AddDocumentDialog.test.tsx b/src/components/Project/AddDocumentDialog.test.tsx
index b0b0fef1bc..91a630f9cc 100644
--- a/src/components/Project/AddDocumentDialog.test.tsx
+++ b/src/components/Project/AddDocumentDialog.test.tsx
@@ -23,6 +23,24 @@ vi.mock("@/providers/AnalyticsProvider", () => ({
   useAnalytics: () => ({ track }),
 }));
 
+vi.mock("@/components/shared/CodeViewer/CodeEditor", () => ({
+  default: ({
+    value,
+    onChange,
+    options,
+  }: {
+    value: string;
+    onChange: (value: string) => void;
+    options: { ariaLabel: string };
+  }) => (
+    <textarea
+      aria-label={options.ariaLabel}
+      value={value}
+      onChange={(event) => onChange(event.target.value)}
+    />
+  ),
+}));
+
 function mockCreate({ isPending = false } = {}) {
   vi.mocked(useCreateProjectResource).mockReturnValue({
     mutate,
diff --git a/src/components/Project/AddDocumentDialog.tsx b/src/components/Project/AddDocumentDialog.tsx
index 3cc3c92d4b..bed3e3b012 100644
--- a/src/components/Project/AddDocumentDialog.tsx
+++ b/src/components/Project/AddDocumentDialog.tsx
@@ -46,7 +46,7 @@ export function AddDocumentDialog({
 
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
-      <DialogContent>
+      <DialogContent className="sm:max-w-4xl">
         <DialogHeader>
           <DialogTitle>Add Document</DialogTitle>
         </DialogHeader>
diff --git a/src/components/Project/DocumentFileDropZone.tsx b/src/components/Project/DocumentFileDropZone.tsx
new file mode 100644
index 0000000000..8b2678c898
--- /dev/null
+++ b/src/components/Project/DocumentFileDropZone.tsx
@@ -0,0 +1,77 @@
+import { type ChangeEvent, useRef } from "react";
+
+import { Button } from "@/components/ui/button";
+import { FieldMessage } from "@/components/ui/field-message";
+import { Icon } from "@/components/ui/icon";
+import { BlockStack, InlineStack } from "@/components/ui/layout";
+import { Text } from "@/components/ui/typography";
+import { cn } from "@/lib/utils";
+import { tracking } from "@/utils/tracking";
+
+interface DocumentFileDropZoneProps {
+  isDraggingFile: boolean;
+  error: string | null;
+  disabled: boolean;
+  onFileChosen: (file: File) => void;
+}
+
+export function DocumentFileDropZone({
+  isDraggingFile,
+  error,
+  disabled,
+  onFileChosen,
+}: DocumentFileDropZoneProps) {
+  const fileInputRef = useRef<HTMLInputElement>(null);
+
+  const handleFileChange = (event: ChangeEvent<HTMLInputElement>) => {
+    const file = event.target.files?.[0];
+    event.target.value = "";
+    if (file) onFileChosen(file);
+  };
+
+  return (
+    <BlockStack gap="1" aria-live="polite">
+      <InlineStack
+        gap="2"
+        align="center"
+        className={cn(
+          "w-full rounded-md border border-dashed px-3 py-3 transition-colors",
+          isDraggingFile ? "border-primary bg-primary/5" : "border-input",
+        )}
+      >
+        <Icon name="FileUp" size="sm" className="text-muted-foreground" />
+        {isDraggingFile ? (
+          <Text size="xs" tone="subdued">
+            Drop to fill in the title and content
+          </Text>
+        ) : (
+          <Text size="xs" tone="subdued">
+            Drop a text file here, or{" "}
+            <Button
+              type="button"
+              variant="link"
+              size="inline-xs"
+              disabled={disabled}
+              onClick={() => fileInputRef.current?.click()}
+              {...tracking("projects.add_document_browse_file")}
+            >
+              browse
+            </Button>
+          </Text>
+        )}
+        <input
+          ref={fileInputRef}
+          type="file"
+          hidden
+          onChange={handleFileChange}
+          data-testid="document-file-input"
+        />
+      </InlineStack>
+      {error && (
+        <FieldMessage tone="critical" icon="CircleAlert">
+          {error}
+        </FieldMessage>
+      )}
+    </BlockStack>
+  );
+}
diff --git a/src/components/Project/DocumentForm.test.tsx b/src/components/Project/DocumentForm.test.tsx
new file mode 100644
index 0000000000..4b95c0a797
--- /dev/null
+++ b/src/components/Project/DocumentForm.test.tsx
@@ -0,0 +1,213 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { DocumentForm } from "./DocumentForm";
+
+const track = vi.fn();
+
+vi.mock("@/providers/AnalyticsProvider", () => ({
+  useAnalytics: () => ({ track }),
+}));
+
+vi.mock("@/components/shared/CodeViewer/CodeEditor", () => ({
+  default: ({
+    value,
+    language,
+    onChange,
+    options,
+  }: {
+    value: string;
+    language: string;
+    onChange: (value: string) => void;
+    options: { ariaLabel: string };
+  }) => (
+    <textarea
+      aria-label={options.ariaLabel}
+      data-language={language}
+      value={value}
+      onChange={(event) => onChange(event.target.value)}
+    />
+  ),
+}));
+
+const titleField = () => screen.getByLabelText("Title");
+const contentField = () => screen.getByLabelText("Content");
+const form = () => titleField().closest("form") as HTMLFormElement;
+const draggingHint = () =>
+  screen.queryByText("Drop to fill in the title and content");
+
+function renderForm({ isSubmitting = false } = {}) {
+  render(
+    <DocumentForm
+      onSubmit={vi.fn()}
+      onCancel={vi.fn()}
+      isSubmitting={isSubmitting}
+    />,
+  );
+}
+
+function fileDrag(...files: File[]) {
+  return { dataTransfer: { files, types: ["Files"] } };
+}
+
+const modelCard = () => new File(["Trained on Q3 data"], "model-card.md");
+
+describe("DocumentForm file drop", () => {
+  afterEach(() => {
+    vi.resetAllMocks();
+  });
+
+  it("fills the title and content from a dropped file", async () => {
+    renderForm();
+
+    fireEvent.drop(contentField(), fileDrag(modelCard()));
+
+    await waitFor(() => {
+      expect(contentField()).toHaveValue("Trained on Q3 data");
+    });
+    expect(titleField()).toHaveValue("model-card.md");
+    expect(track).toHaveBeenCalledWith(
+      "projects.add_document_from_file_completed",
+      { method: "drop" },
+    );
+  });
+
+  it("highlights the content as the title's extension says, as the saved document will be", async () => {
+    const user = userEvent.setup();
+    renderForm();
+
+    expect(contentField()).toHaveAttribute("data-language", "plaintext");
+
+    await user.type(titleField(), "train.py");
+    expect(contentField()).toHaveAttribute("data-language", "python");
+  });
+
+  it("fills the title and content from a browsed file", async () => {
+    const user = userEvent.setup();
+    renderForm();
+
+    await user.upload(screen.getByTestId("document-file-input"), modelCard());
+
+    await waitFor(() => {
+      expect(contentField()).toHaveValue("Trained on Q3 data");
+    });
+    expect(titleField()).toHaveValue("model-card.md");
+    expect(track).toHaveBeenCalledWith(
+      "projects.add_document_from_file_completed",
+      { method: "browse" },
+    );
+  });
+
+  it("keeps a title the user typed", async () => {
+    const user = userEvent.setup();
+    renderForm();
+
+    await user.type(titleField(), "Q3 model card");
+    fireEvent.drop(form(), fileDrag(modelCard()));
+
+    await waitFor(() => {
+      expect(contentField()).toHaveValue("Trained on Q3 data");
+    });
+    expect(titleField()).toHaveValue("Q3 model card");
+  });
+
+  it("replaces a title it took from an earlier file", async () => {
+    renderForm();
+
+    fireEvent.drop(form(), fileDrag(new File(["wrong"], "wrong-file.txt")));
+    await waitFor(() => {
+      expect(titleField()).toHaveValue("wrong-file.txt");
+    });
+
+    fireEvent.drop(form(), fileDrag(modelCard()));
+    await waitFor(() => {
+      expect(titleField()).toHaveValue("model-card.md");
+    });
+    expect(contentField()).toHaveValue("Trained on Q3 data");
+  });
+
+  it("says why a file that isn't text can't be added, and leaves the fields alone", async () => {
+    const user = userEvent.setup();
+    renderForm();
+
+    await user.type(contentField(), "Draft");
+    fireEvent.drop(
+      form(),
+      fileDrag(new File([new Uint8Array([0xff, 0xfe, 0x00])], "chart.png")),
+    );
+
+    expect(
+      await screen.findByText(
+        "chart.png isn't a text file. Only text can be added as a document.",
+      ),
+    ).toBeInTheDocument();
+    expect(contentField()).toHaveValue("Draft");
+    expect(titleField()).toHaveValue("");
+  });
+
+  it("clears the error once a readable file arrives", async () => {
+    renderForm();
+
+    fireEvent.drop(
+      form(),
+      fileDrag(new File([new Uint8Array([0xff])], "chart.png")),
+    );
+    await screen.findByText(/chart\.png isn't a text file/);
+
+    fireEvent.drop(form(), fileDrag(modelCard()));
+    await waitFor(() => {
+      expect(screen.queryByText(/chart\.png isn't a text file/)).toBeNull();
+    });
+  });
+
+  it("ignores a file dropped while the document is saving", async () => {
+    renderForm({ isSubmitting: true });
+
+    fireEvent.drop(form(), fileDrag(modelCard()));
+
+    await waitFor(() => {
+      expect(track).not.toHaveBeenCalled();
+    });
+    expect(contentField()).toHaveValue("");
+  });
+
+  it("highlights while a file is dragged over the form", () => {
+    renderForm();
+
+    fireEvent.dragEnter(form(), fileDrag());
+    expect(draggingHint()).toBeInTheDocument();
+
+    fireEvent.dragLeave(form(), fileDrag());
+    expect(draggingHint()).toBeNull();
+  });
+
+  it("stays highlighted while the drag crosses from the form into a field", () => {
+    renderForm();
+
+    fireEvent.dragEnter(form(), fileDrag());
+    fireEvent.dragEnter(titleField(), fileDrag());
+    fireEvent.dragLeave(form(), fileDrag());
+    expect(draggingHint()).toBeInTheDocument();
+
+    fireEvent.dragLeave(titleField(), fileDrag());
+    expect(draggingHint()).toBeNull();
+  });
+
+  it("leaves dragged text to the fields", () => {
+    renderForm();
+
+    const textDrag = { dataTransfer: { files: [], types: ["text/plain"] } };
+    fireEvent.dragEnter(form(), textDrag);
+
+    expect(draggingHint()).toBeNull();
+    expect(fireEvent.dragOver(contentField(), textDrag)).toBe(true);
+  });
+
+  it("claims a file drag, so the browser doesn't open the file instead", () => {
+    renderForm();
+
+    expect(fireEvent.dragOver(contentField(), fileDrag())).toBe(false);
+    expect(fireEvent.drop(contentField(), fileDrag())).toBe(false);
+  });
+});
diff --git a/src/components/Project/DocumentForm.tsx b/src/components/Project/DocumentForm.tsx
index 0ee8e8c49d..61b890091f 100644
--- a/src/components/Project/DocumentForm.tsx
+++ b/src/components/Project/DocumentForm.tsx
@@ -1,15 +1,21 @@
 import { type FormEvent, useState } from "react";
 
+import { languageFor } from "@/components/shared/CodeViewer";
+import CodeEditor from "@/components/shared/CodeViewer/CodeEditor";
 import { Button } from "@/components/ui/button";
 import { DialogFooter } from "@/components/ui/dialog";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
 import { BlockStack, InlineStack } from "@/components/ui/layout";
-import { Textarea } from "@/components/ui/textarea";
+import { useAnalytics } from "@/providers/AnalyticsProvider";
 import { documentResourceInput } from "@/services/projects/resourceDescriptor";
 import type { CreateResourceInput } from "@/services/projects/types";
 import { tracking } from "@/utils/tracking";
 
+import { readDocumentFile } from "./documentFile";
+import { DocumentFileDropZone } from "./DocumentFileDropZone";
+import { useFileDrop } from "./useFileDrop";
+
 interface DocumentFormProps {
   onSubmit: (input: CreateResourceInput) => void;
   onCancel: () => void;
@@ -21,8 +27,35 @@ export function DocumentForm({
   onCancel,
   isSubmitting = false,
 }: DocumentFormProps) {
+  const { track } = useAnalytics();
   const [title, setTitle] = useState("");
   const [content, setContent] = useState("");
+  const [titleFromFile, setTitleFromFile] = useState<string | null>(null);
+  const [fileError, setFileError] = useState<string | null>(null);
+
+  const fillFromFile = async (file: File, method: "drop" | "browse") => {
+    if (isSubmitting) return;
+
+    const result = await readDocumentFile(file);
+    if (!result.ok) {
+      setFileError(result.error);
+      return;
+    }
+
+    setFileError(null);
+    setTitle((current) =>
+      current.trim() === "" || current === titleFromFile
+        ? result.title
+        : current,
+    );
+    setTitleFromFile(result.title);
+    setContent(result.content);
+    track("projects.add_document_from_file_completed", { method });
+  };
+
+  const { isDraggingFile, dropTargetProps } = useFileDrop(
+    (file) => void fillFromFile(file, "drop"),
+  );
 
   const trimmedTitle = title.trim();
   const trimmedContent = content.trim();
@@ -36,28 +69,39 @@ export function DocumentForm({
   };
 
   return (
-    <form onSubmit={handleSubmit}>
+    <form onSubmit={handleSubmit} className="min-w-0" {...dropTargetProps}>
       <BlockStack gap="4">
+        <DocumentFileDropZone
+          isDraggingFile={isDraggingFile}
+          error={fileError}
+          disabled={isSubmitting}
+          onFileChosen={(file) => void fillFromFile(file, "browse")}
+        />
+
         <BlockStack gap="2">
           <Label htmlFor="add-document-title">Title</Label>
           <Input
             id="add-document-title"
             value={title}
             onChange={(event) => setTitle(event.target.value)}
-            placeholder="Model card"
+            placeholder="model-card.md"
             autoFocus
           />
         </BlockStack>
 
         <BlockStack gap="2">
-          <Label htmlFor="add-document-content">Content</Label>
-          <Textarea
-            id="add-document-content"
-            value={content}
-            onChange={(event) => setContent(event.target.value)}
-            placeholder="What this document records"
-            className="min-h-32"
-          />
+          <Label>Content</Label>
+          <div className="h-[50vh] min-h-40 w-full overflow-hidden rounded-md border border-input shadow-xs focus-within:border-ring focus-within:ring-[3px] focus-within:ring-ring/50">
+            <CodeEditor
+              value={content}
+              language={languageFor(trimmedTitle)}
+              onChange={setContent}
+              options={{
+                ariaLabel: "Content",
+                placeholder: "What this document records",
+              }}
+            />
+          </div>
         </BlockStack>
 
         <DialogFooter className="w-full">
diff --git a/src/components/Project/documentFile.test.ts b/src/components/Project/documentFile.test.ts
new file mode 100644
index 0000000000..7be22066f2
--- /dev/null
+++ b/src/components/Project/documentFile.test.ts
@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+
+import { readDocumentFile } from "./documentFile";
+
+describe("readDocumentFile", () => {
+  it("reads a text file into its content, titled with its whole name", async () => {
+    const file = new File(["# Model card\n\nTrained on Q3"], "model-card.md");
+
+    await expect(readDocumentFile(file)).resolves.toEqual({
+      ok: true,
+      title: "model-card.md",
+      content: "# Model card\n\nTrained on Q3",
+    });
+  });
+
+  it("reads text whatever the file is called", async () => {
+    const file = new File(["plain words"], "NOTES");
+
+    await expect(readDocumentFile(file)).resolves.toMatchObject({
+      ok: true,
+      content: "plain words",
+    });
+  });
+
+  it("refuses bytes that are not UTF-8 text", async () => {
+    const file = new File(
+      [new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0xff])],
+      "chart.png",
+    );
+
+    await expect(readDocumentFile(file)).resolves.toEqual({
+      ok: false,
+      error:
+        "chart.png isn't a text file. Only text can be added as a document.",
+    });
+  });
+
+  it("refuses valid UTF-8 that carries NUL bytes, as binary formats do", async () => {
+    const file = new File(["header\0\0\0body"], "model.bin");
+
+    await expect(readDocumentFile(file)).resolves.toMatchObject({ ok: false });
+  });
+
+  it("refuses a file larger than 1 MB", async () => {
+    const file = new File(
+      [new Uint8Array(1024 * 1024 + 1).fill(97)],
+      "big.txt",
+    );
+
+    await expect(readDocumentFile(file)).resolves.toEqual({
+      ok: false,
+      error: "big.txt is larger than 1 MB.",
+    });
+  });
+});
diff --git a/src/components/Project/documentFile.ts b/src/components/Project/documentFile.ts
new file mode 100644
index 0000000000..db03413941
--- /dev/null
+++ b/src/components/Project/documentFile.ts
@@ -0,0 +1,42 @@
+const MAX_DOCUMENT_FILE_MB = 1;
+const MAX_DOCUMENT_FILE_BYTES = MAX_DOCUMENT_FILE_MB * 1024 * 1024;
+
+type DocumentFileReadResult =
+  { ok: true; title: string; content: string } | { ok: false; error: string };
+
+function decodeText(bytes: ArrayBuffer): string | null {
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    return text.includes("\0") ? null : text;
+  } catch {
+    return null;
+  }
+}
+
+export async function readDocumentFile(
+  file: File,
+): Promise<DocumentFileReadResult> {
+  if (file.size > MAX_DOCUMENT_FILE_BYTES) {
+    return {
+      ok: false,
+      error: `${file.name} is larger than ${MAX_DOCUMENT_FILE_MB} MB.`,
+    };
+  }
+
+  let bytes: ArrayBuffer;
+  try {
+    bytes = await file.arrayBuffer();
+  } catch {
+    return { ok: false, error: `Couldn't read ${file.name}.` };
+  }
+
+  const content = decodeText(bytes);
+  if (content === null) {
+    return {
+      ok: false,
+      error: `${file.name} isn't a text file. Only text can be added as a document.`,
+    };
+  }
+
+  return { ok: true, title: file.name, content };
+}
diff --git a/src/components/Project/useFileDrop.ts b/src/components/Project/useFileDrop.ts
new file mode 100644
index 0000000000..d255b9d72e
--- /dev/null
+++ b/src/components/Project/useFileDrop.ts
@@ -0,0 +1,45 @@
+import { type DragEvent, useRef, useState } from "react";
+
+function carriesFiles(event: DragEvent) {
+  return event.dataTransfer.types.includes("Files");
+}
+
+export function useFileDrop(onFile: (file: File) => void) {
+  const [isDraggingFile, setIsDraggingFile] = useState(false);
+  // dragenter and dragleave fire again on every child the pointer crosses, so a
+  // single dragleave does not mean the drag has left the target.
+  const dragDepth = useRef(0);
+
+  const onDragEnter = (event: DragEvent) => {
+    if (!carriesFiles(event)) return;
+    dragDepth.current += 1;
+    setIsDraggingFile(true);
+  };
+
+  const onDragOver = (event: DragEvent) => {
+    if (!carriesFiles(event)) return;
+    event.preventDefault();
+    event.dataTransfer.dropEffect = "copy";
+  };
+
+  const onDragLeave = (event: DragEvent) => {
+    if (!carriesFiles(event)) return;
+    dragDepth.current = Math.max(0, dragDepth.current - 1);
+    if (dragDepth.current === 0) setIsDraggingFile(false);
+  };
+
+  const onDrop = (event: DragEvent) => {
+    if (!carriesFiles(event)) return;
+    event.preventDefault();
+    dragDepth.current = 0;
+    setIsDraggingFile(false);
+
+    const [file] = event.dataTransfer.files;
+    if (file) onFile(file);
+  };
+
+  return {
+    isDraggingFile,
+    dropTargetProps: { onDragEnter, onDragOver, onDragLeave, onDrop },
+  };
+}
diff --git a/src/components/shared/CodeViewer/CodeEditor.tsx b/src/components/shared/CodeViewer/CodeEditor.tsx
index e378831a07..201a4bad81 100644
--- a/src/components/shared/CodeViewer/CodeEditor.tsx
+++ b/src/components/shared/CodeViewer/CodeEditor.tsx
@@ -1,4 +1,5 @@
 import MonacoEditor from "@monaco-editor/react";
+import type { editor } from "monaco-editor";
 
 import { useMonacoTheme } from "@/hooks/useMonacoTheme";
 
@@ -7,9 +8,16 @@ interface CodeEditorProps {
   language: string;
   onChange?: (value: string) => void;
   readOnly?: boolean;
+  options?: editor.IStandaloneEditorConstructionOptions;
 }
 
-function CodeEditor({ value, language, onChange, readOnly }: CodeEditorProps) {
+function CodeEditor({
+  value,
+  language,
+  onChange,
+  readOnly,
+  options,
+}: CodeEditorProps) {
   const monacoTheme = useMonacoTheme();
 
   return (
@@ -25,6 +33,7 @@ function CodeEditor({ value, language, onChange, readOnly }: CodeEditorProps) {
         wordWrap: "on",
         automaticLayout: true,
         readOnly,
+        ...options,
       }}
     />
   );
diff --git a/src/routes/v2/pages/Tangent/components/AddResourceButton.tsx b/src/routes/v2/pages/Tangent/components/AddResourceButton.tsx
index 8f1aa286fe..3850a8ce93 100644
--- a/src/routes/v2/pages/Tangent/components/AddResourceButton.tsx
+++ b/src/routes/v2/pages/Tangent/components/AddResourceButton.tsx
@@ -112,10 +112,10 @@ export function AddResourceButton({
     void openResourceDialog(AddPipelineRunDialog, "add-pipeline-run");
   }
 
-  // The pipeline and run pickers are browsers and want the room; two fields
-  // and a pair of buttons do not.
+  // The pipeline and run pickers are browsers and want the whole screen; a
+  // document editor wants width, but lines that span a wide monitor read badly.
   function handleAddDocument() {
-    void openResourceDialog(AddDocumentDialog, "add-document", "md");
+    void openResourceDialog(AddDocumentDialog, "add-document", "xl");
   }
 
   return (

From ba625fa66e792fad47dbe7521eeb05125b860511 Mon Sep 17 00:00:00 2001
From: Camiel van Schoonhoven <camiel.vanschoonhoven@shopify.com>
Date: Mon, 2 Nov 2026 13:42:12 -0700
Subject: [PATCH 2/5] refactor(documents): share the text-file reader and the
 file-drop hook

The app already reads uploaded files four ways, and none checks that a
file is text or caps its size. Only part of the document reader was about
documents, so the general part moves out where the other file pickers can
adopt it.

readTextFile in src/utils/textFile.ts reads a file as strict UTF-8 under an
optional byte limit. It returns a reason rather than a message, so each
caller words its own errors. documentFile.ts keeps what is about
documents: the 1 MB limit, the messages and the title. useFileDrop moves
to src/hooks with its own tests; the form's tests keep only what the form
adds on top.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 react-compiler.config.js                      |  1 +
 src/components/Project/DocumentForm.test.tsx  | 29 ------
 src/components/Project/DocumentForm.tsx       |  2 +-
 src/components/Project/documentFile.test.ts   | 34 +++----
 src/components/Project/documentFile.ts        | 45 +++------
 src/hooks/useFileDrop.test.tsx                | 98 +++++++++++++++++++
 .../Project => hooks}/useFileDrop.ts          |  0
 src/utils/textFile.test.ts                    | 72 ++++++++++++++
 src/utils/textFile.ts                         | 31 ++++++
 9 files changed, 232 insertions(+), 80 deletions(-)
 create mode 100644 src/hooks/useFileDrop.test.tsx
 rename src/{components/Project => hooks}/useFileDrop.ts (100%)
 create mode 100644 src/utils/textFile.test.ts
 create mode 100644 src/utils/textFile.ts

diff --git a/react-compiler.config.js b/react-compiler.config.js
index 3c046fd131..5e43f0b048 100644
--- a/react-compiler.config.js
+++ b/react-compiler.config.js
@@ -50,6 +50,7 @@ export const REACT_COMPILER_ENABLED_DIRS = [
   "src/hooks/useRerunProjectIds.ts",
   "src/hooks/useTrackRecentlyViewedProject.ts",
   "src/hooks/useTrackRecentlyViewedPipeline.ts",
+  "src/hooks/useFileDrop.ts",
   "src/services/localPipelines/useLocalPipelines.ts",
   "src/services/projects/useLocalPipelineStatus.ts",
   "src/services/projects/usePipelineProjects.ts",
diff --git a/src/components/Project/DocumentForm.test.tsx b/src/components/Project/DocumentForm.test.tsx
index 4b95c0a797..cc32f95e1b 100644
--- a/src/components/Project/DocumentForm.test.tsx
+++ b/src/components/Project/DocumentForm.test.tsx
@@ -181,33 +181,4 @@ describe("DocumentForm file drop", () => {
     fireEvent.dragLeave(form(), fileDrag());
     expect(draggingHint()).toBeNull();
   });
-
-  it("stays highlighted while the drag crosses from the form into a field", () => {
-    renderForm();
-
-    fireEvent.dragEnter(form(), fileDrag());
-    fireEvent.dragEnter(titleField(), fileDrag());
-    fireEvent.dragLeave(form(), fileDrag());
-    expect(draggingHint()).toBeInTheDocument();
-
-    fireEvent.dragLeave(titleField(), fileDrag());
-    expect(draggingHint()).toBeNull();
-  });
-
-  it("leaves dragged text to the fields", () => {
-    renderForm();
-
-    const textDrag = { dataTransfer: { files: [], types: ["text/plain"] } };
-    fireEvent.dragEnter(form(), textDrag);
-
-    expect(draggingHint()).toBeNull();
-    expect(fireEvent.dragOver(contentField(), textDrag)).toBe(true);
-  });
-
-  it("claims a file drag, so the browser doesn't open the file instead", () => {
-    renderForm();
-
-    expect(fireEvent.dragOver(contentField(), fileDrag())).toBe(false);
-    expect(fireEvent.drop(contentField(), fileDrag())).toBe(false);
-  });
 });
diff --git a/src/components/Project/DocumentForm.tsx b/src/components/Project/DocumentForm.tsx
index 61b890091f..33304f729a 100644
--- a/src/components/Project/DocumentForm.tsx
+++ b/src/components/Project/DocumentForm.tsx
@@ -7,6 +7,7 @@ import { DialogFooter } from "@/components/ui/dialog";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
 import { BlockStack, InlineStack } from "@/components/ui/layout";
+import { useFileDrop } from "@/hooks/useFileDrop";
 import { useAnalytics } from "@/providers/AnalyticsProvider";
 import { documentResourceInput } from "@/services/projects/resourceDescriptor";
 import type { CreateResourceInput } from "@/services/projects/types";
@@ -14,7 +15,6 @@ import { tracking } from "@/utils/tracking";
 
 import { readDocumentFile } from "./documentFile";
 import { DocumentFileDropZone } from "./DocumentFileDropZone";
-import { useFileDrop } from "./useFileDrop";
 
 interface DocumentFormProps {
   onSubmit: (input: CreateResourceInput) => void;
diff --git a/src/components/Project/documentFile.test.ts b/src/components/Project/documentFile.test.ts
index 7be22066f2..e38ebe048f 100644
--- a/src/components/Project/documentFile.test.ts
+++ b/src/components/Project/documentFile.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 
 import { readDocumentFile } from "./documentFile";
 
@@ -13,20 +13,8 @@ describe("readDocumentFile", () => {
     });
   });
 
-  it("reads text whatever the file is called", async () => {
-    const file = new File(["plain words"], "NOTES");
-
-    await expect(readDocumentFile(file)).resolves.toMatchObject({
-      ok: true,
-      content: "plain words",
-    });
-  });
-
-  it("refuses bytes that are not UTF-8 text", async () => {
-    const file = new File(
-      [new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0xff])],
-      "chart.png",
-    );
+  it("explains that only text can be a document", async () => {
+    const file = new File([new Uint8Array([0xff, 0xfe, 0x00])], "chart.png");
 
     await expect(readDocumentFile(file)).resolves.toEqual({
       ok: false,
@@ -35,12 +23,6 @@ describe("readDocumentFile", () => {
     });
   });
 
-  it("refuses valid UTF-8 that carries NUL bytes, as binary formats do", async () => {
-    const file = new File(["header\0\0\0body"], "model.bin");
-
-    await expect(readDocumentFile(file)).resolves.toMatchObject({ ok: false });
-  });
-
   it("refuses a file larger than 1 MB", async () => {
     const file = new File(
       [new Uint8Array(1024 * 1024 + 1).fill(97)],
@@ -52,4 +34,14 @@ describe("readDocumentFile", () => {
       error: "big.txt is larger than 1 MB.",
     });
   });
+
+  it("names the file it couldn't read", async () => {
+    const file = new File(["gone"], "moved.txt");
+    vi.spyOn(file, "arrayBuffer").mockRejectedValue(new Error("NotFound"));
+
+    await expect(readDocumentFile(file)).resolves.toEqual({
+      ok: false,
+      error: "Couldn't read moved.txt.",
+    });
+  });
 });
diff --git a/src/components/Project/documentFile.ts b/src/components/Project/documentFile.ts
index db03413941..18073d12af 100644
--- a/src/components/Project/documentFile.ts
+++ b/src/components/Project/documentFile.ts
@@ -1,42 +1,29 @@
+import { readTextFile, type TextFileReadFailure } from "@/utils/textFile";
+
 const MAX_DOCUMENT_FILE_MB = 1;
-const MAX_DOCUMENT_FILE_BYTES = MAX_DOCUMENT_FILE_MB * 1024 * 1024;
 
 type DocumentFileReadResult =
   { ok: true; title: string; content: string } | { ok: false; error: string };
 
-function decodeText(bytes: ArrayBuffer): string | null {
-  try {
-    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-    return text.includes("\0") ? null : text;
-  } catch {
-    return null;
+function failureMessage(reason: TextFileReadFailure, fileName: string) {
+  switch (reason) {
+    case "too_large":
+      return `${fileName} is larger than ${MAX_DOCUMENT_FILE_MB} MB.`;
+    case "not_text":
+      return `${fileName} isn't a text file. Only text can be added as a document.`;
+    case "unreadable":
+      return `Couldn't read ${fileName}.`;
   }
 }
 
 export async function readDocumentFile(
   file: File,
 ): Promise<DocumentFileReadResult> {
-  if (file.size > MAX_DOCUMENT_FILE_BYTES) {
-    return {
-      ok: false,
-      error: `${file.name} is larger than ${MAX_DOCUMENT_FILE_MB} MB.`,
-    };
-  }
-
-  let bytes: ArrayBuffer;
-  try {
-    bytes = await file.arrayBuffer();
-  } catch {
-    return { ok: false, error: `Couldn't read ${file.name}.` };
-  }
-
-  const content = decodeText(bytes);
-  if (content === null) {
-    return {
-      ok: false,
-      error: `${file.name} isn't a text file. Only text can be added as a document.`,
-    };
-  }
+  const result = await readTextFile(file, {
+    maxBytes: MAX_DOCUMENT_FILE_MB * 1024 * 1024,
+  });
 
-  return { ok: true, title: file.name, content };
+  return result.ok
+    ? { ok: true, title: file.name, content: result.text }
+    : { ok: false, error: failureMessage(result.reason, file.name) };
 }
diff --git a/src/hooks/useFileDrop.test.tsx b/src/hooks/useFileDrop.test.tsx
new file mode 100644
index 0000000000..eee4679bb7
--- /dev/null
+++ b/src/hooks/useFileDrop.test.tsx
@@ -0,0 +1,98 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { useFileDrop } from "./useFileDrop";
+
+function DropTarget({ onFile }: { onFile: (file: File) => void }) {
+  const { isDraggingFile, dropTargetProps } = useFileDrop(onFile);
+
+  return (
+    <div
+      data-testid="drop-target"
+      data-dragging={String(isDraggingFile)}
+      {...dropTargetProps}
+    >
+      <input aria-label="Field" />
+    </div>
+  );
+}
+
+function renderTarget() {
+  const onFile = vi.fn();
+  render(<DropTarget onFile={onFile} />);
+  return onFile;
+}
+
+const target = () => screen.getByTestId("drop-target");
+const field = () => screen.getByLabelText("Field");
+const isDragging = () => target().dataset.dragging === "true";
+
+function fileDrag(...files: File[]) {
+  return { dataTransfer: { files, types: ["Files"] } };
+}
+
+const textDrag = { dataTransfer: { files: [], types: ["text/plain"] } };
+
+describe("useFileDrop", () => {
+  it("hands over the first dropped file", () => {
+    const onFile = renderTarget();
+    const first = new File(["a"], "a.txt");
+
+    fireEvent.drop(field(), fileDrag(first, new File(["b"], "b.txt")));
+
+    expect(onFile).toHaveBeenCalledExactlyOnceWith(first);
+  });
+
+  it("claims a file drag, so the browser doesn't open the file instead", () => {
+    renderTarget();
+
+    expect(fireEvent.dragOver(field(), fileDrag())).toBe(false);
+    expect(fireEvent.drop(field(), fileDrag())).toBe(false);
+  });
+
+  it("leaves dragged text to the elements under it", () => {
+    const onFile = renderTarget();
+
+    fireEvent.dragEnter(target(), textDrag);
+
+    expect(isDragging()).toBe(false);
+    expect(fireEvent.dragOver(field(), textDrag)).toBe(true);
+    expect(fireEvent.drop(field(), textDrag)).toBe(true);
+    expect(onFile).not.toHaveBeenCalled();
+  });
+
+  it("reports a file dragged over the target until it leaves", () => {
+    renderTarget();
+
+    fireEvent.dragEnter(target(), fileDrag());
+    expect(isDragging()).toBe(true);
+
+    fireEvent.dragLeave(target(), fileDrag());
+    expect(isDragging()).toBe(false);
+  });
+
+  it("keeps reporting the drag while it crosses into a child", () => {
+    renderTarget();
+
+    fireEvent.dragEnter(target(), fileDrag());
+    fireEvent.dragEnter(field(), fileDrag());
+    fireEvent.dragLeave(target(), fileDrag());
+    expect(isDragging()).toBe(true);
+
+    fireEvent.dragLeave(field(), fileDrag());
+    expect(isDragging()).toBe(false);
+  });
+
+  it("stops reporting the drag once the file lands", () => {
+    renderTarget();
+
+    fireEvent.dragEnter(target(), fileDrag());
+    fireEvent.dragEnter(field(), fileDrag());
+    fireEvent.drop(field(), fileDrag(new File(["a"], "a.txt")));
+    expect(isDragging()).toBe(false);
+
+    fireEvent.dragEnter(target(), fileDrag());
+    fireEvent.dragLeave(target(), fileDrag());
+    expect(isDragging()).toBe(false);
+  });
+});
diff --git a/src/components/Project/useFileDrop.ts b/src/hooks/useFileDrop.ts
similarity index 100%
rename from src/components/Project/useFileDrop.ts
rename to src/hooks/useFileDrop.ts
diff --git a/src/utils/textFile.test.ts b/src/utils/textFile.test.ts
new file mode 100644
index 0000000000..c4e71a7c79
--- /dev/null
+++ b/src/utils/textFile.test.ts
@@ -0,0 +1,72 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { readTextFile } from "./textFile";
+
+describe("readTextFile", () => {
+  it("reads a text file", async () => {
+    const file = new File(["# Model card\n\nTrained on Q3"], "model-card.md");
+
+    await expect(readTextFile(file)).resolves.toEqual({
+      ok: true,
+      text: "# Model card\n\nTrained on Q3",
+    });
+  });
+
+  it("reads text whatever the file is called", async () => {
+    const file = new File(["plain words"], "NOTES");
+
+    await expect(readTextFile(file)).resolves.toEqual({
+      ok: true,
+      text: "plain words",
+    });
+  });
+
+  it("refuses bytes that are not UTF-8 text", async () => {
+    const file = new File(
+      [new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0xff])],
+      "chart.png",
+    );
+
+    await expect(readTextFile(file)).resolves.toEqual({
+      ok: false,
+      reason: "not_text",
+    });
+  });
+
+  it("refuses valid UTF-8 that carries NUL bytes, as binary formats do", async () => {
+    const file = new File(["header\0\0\0body"], "model.bin");
+
+    await expect(readTextFile(file)).resolves.toEqual({
+      ok: false,
+      reason: "not_text",
+    });
+  });
+
+  it("refuses a file larger than the limit", async () => {
+    const file = new File(["12345"], "five-bytes.txt");
+
+    await expect(readTextFile(file, { maxBytes: 4 })).resolves.toEqual({
+      ok: false,
+      reason: "too_large",
+    });
+  });
+
+  it("accepts a file exactly at the limit", async () => {
+    const file = new File(["1234"], "four-bytes.txt");
+
+    await expect(readTextFile(file, { maxBytes: 4 })).resolves.toEqual({
+      ok: true,
+      text: "1234",
+    });
+  });
+
+  it("says so when the browser can't read the file", async () => {
+    const file = new File(["gone"], "moved.txt");
+    vi.spyOn(file, "arrayBuffer").mockRejectedValue(new Error("NotFound"));
+
+    await expect(readTextFile(file)).resolves.toEqual({
+      ok: false,
+      reason: "unreadable",
+    });
+  });
+});
diff --git a/src/utils/textFile.ts b/src/utils/textFile.ts
new file mode 100644
index 0000000000..5365da0b69
--- /dev/null
+++ b/src/utils/textFile.ts
@@ -0,0 +1,31 @@
+export type TextFileReadFailure = "too_large" | "not_text" | "unreadable";
+
+type TextFileReadResult =
+  { ok: true; text: string } | { ok: false; reason: TextFileReadFailure };
+
+function decodeText(bytes: ArrayBuffer): string | null {
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    // Binary formats can still decode as valid UTF-8, but text never holds NUL.
+    return text.includes("\0") ? null : text;
+  } catch {
+    return null;
+  }
+}
+
+export async function readTextFile(
+  file: File,
+  { maxBytes = Infinity }: { maxBytes?: number } = {},
+): Promise<TextFileReadResult> {
+  if (file.size > maxBytes) return { ok: false, reason: "too_large" };
+
+  let bytes: ArrayBuffer;
+  try {
+    bytes = await file.arrayBuffer();
+  } catch {
+    return { ok: false, reason: "unreadable" };
+  }
+
+  const text = decodeText(bytes);
+  return text === null ? { ok: false, reason: "not_text" } : { ok: true, text };
+}

From 542a78fb8dd036b9f34ba1ed307724816038f98b Mon Sep 17 00:00:00 2001
From: Camiel van Schoonhoven <camiel.vanschoonhoven@shopify.com>
Date: Mon, 2 Nov 2026 14:53:30 -0700
Subject: [PATCH 3/5] refactor(documents): name the document size limit in
 bytes

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 src/components/Project/documentFile.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/components/Project/documentFile.ts b/src/components/Project/documentFile.ts
index 18073d12af..e0cf1a203f 100644
--- a/src/components/Project/documentFile.ts
+++ b/src/components/Project/documentFile.ts
@@ -1,6 +1,7 @@
 import { readTextFile, type TextFileReadFailure } from "@/utils/textFile";
 
 const MAX_DOCUMENT_FILE_MB = 1;
+const MAX_DOCUMENT_FILE_BYTES = MAX_DOCUMENT_FILE_MB * 1024 * 1024;
 
 type DocumentFileReadResult =
   { ok: true; title: string; content: string } | { ok: false; error: string };
@@ -20,7 +21,7 @@ export async function readDocumentFile(
   file: File,
 ): Promise<DocumentFileReadResult> {
   const result = await readTextFile(file, {
-    maxBytes: MAX_DOCUMENT_FILE_MB * 1024 * 1024,
+    maxBytes: MAX_DOCUMENT_FILE_BYTES,
   });
 
   return result.ok

From faaac73b5af1540f4142c8c21be5d4584729e46a Mon Sep 17 00:00:00 2001
From: Camiel van Schoonhoven <camiel.vanschoonhoven@shopify.com>
Date: Tue, 3 Nov 2026 10:09:16 -0700
Subject: [PATCH 4/5] refactor(documents): read files with the existing
 readTextFromFile

readTextFile in src/utils duplicated readTextFromFile in src/utils/dom.ts,
and it and useFileDrop each had one caller. useFileDrop moves back next
to DocumentForm, and textFile.ts goes away.

readTextFromFile becomes the strict reader: it decodes UTF-8 with fatal
errors and refuses NUL bytes, throwing NotTextFileError so the documents
reader can word its own message. The .yaml check that lived inside it
moves to readYamlFromFile, which the two canvas drop handlers now call,
so they still refuse other files. They also gain the text check, and a
file the browser can't read now rejects instead of never settling.

The 1 MB limit stays in documentFile.ts, now checked before reading.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 react-compiler.config.js                      |  1 -
 src/components/Project/DocumentForm.tsx       |  2 +-
 src/components/Project/documentFile.test.ts   |  6 ++
 src/components/Project/documentFile.ts        | 33 ++++-----
 .../Project}/useFileDrop.test.tsx             |  0
 .../Project}/useFileDrop.ts                   |  0
 .../ReactFlow/FlowCanvas/FlowCanvas.tsx       |  4 +-
 .../FlowCanvas/hooks/useDropBehavior.test.tsx |  2 +-
 .../FlowCanvas/hooks/useFileDropHandler.ts    |  4 +-
 src/utils/dom.test.ts                         | 68 ++++++++++++++++++
 src/utils/dom.ts                              | 45 +++++++-----
 src/utils/textFile.test.ts                    | 72 -------------------
 src/utils/textFile.ts                         | 31 --------
 13 files changed, 124 insertions(+), 144 deletions(-)
 rename src/{hooks => components/Project}/useFileDrop.test.tsx (100%)
 rename src/{hooks => components/Project}/useFileDrop.ts (100%)
 create mode 100644 src/utils/dom.test.ts
 delete mode 100644 src/utils/textFile.test.ts
 delete mode 100644 src/utils/textFile.ts

diff --git a/react-compiler.config.js b/react-compiler.config.js
index 5e43f0b048..3c046fd131 100644
--- a/react-compiler.config.js
+++ b/react-compiler.config.js
@@ -50,7 +50,6 @@ export const REACT_COMPILER_ENABLED_DIRS = [
   "src/hooks/useRerunProjectIds.ts",
   "src/hooks/useTrackRecentlyViewedProject.ts",
   "src/hooks/useTrackRecentlyViewedPipeline.ts",
-  "src/hooks/useFileDrop.ts",
   "src/services/localPipelines/useLocalPipelines.ts",
   "src/services/projects/useLocalPipelineStatus.ts",
   "src/services/projects/usePipelineProjects.ts",
diff --git a/src/components/Project/DocumentForm.tsx b/src/components/Project/DocumentForm.tsx
index 33304f729a..61b890091f 100644
--- a/src/components/Project/DocumentForm.tsx
+++ b/src/components/Project/DocumentForm.tsx
@@ -7,7 +7,6 @@ import { DialogFooter } from "@/components/ui/dialog";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
 import { BlockStack, InlineStack } from "@/components/ui/layout";
-import { useFileDrop } from "@/hooks/useFileDrop";
 import { useAnalytics } from "@/providers/AnalyticsProvider";
 import { documentResourceInput } from "@/services/projects/resourceDescriptor";
 import type { CreateResourceInput } from "@/services/projects/types";
@@ -15,6 +14,7 @@ import { tracking } from "@/utils/tracking";
 
 import { readDocumentFile } from "./documentFile";
 import { DocumentFileDropZone } from "./DocumentFileDropZone";
+import { useFileDrop } from "./useFileDrop";
 
 interface DocumentFormProps {
   onSubmit: (input: CreateResourceInput) => void;
diff --git a/src/components/Project/documentFile.test.ts b/src/components/Project/documentFile.test.ts
index e38ebe048f..483a7f1537 100644
--- a/src/components/Project/documentFile.test.ts
+++ b/src/components/Project/documentFile.test.ts
@@ -35,6 +35,12 @@ describe("readDocumentFile", () => {
     });
   });
 
+  it("accepts a file of exactly 1 MB", async () => {
+    const file = new File([new Uint8Array(1024 * 1024).fill(97)], "full.txt");
+
+    await expect(readDocumentFile(file)).resolves.toMatchObject({ ok: true });
+  });
+
   it("names the file it couldn't read", async () => {
     const file = new File(["gone"], "moved.txt");
     vi.spyOn(file, "arrayBuffer").mockRejectedValue(new Error("NotFound"));
diff --git a/src/components/Project/documentFile.ts b/src/components/Project/documentFile.ts
index e0cf1a203f..dabc3baa20 100644
--- a/src/components/Project/documentFile.ts
+++ b/src/components/Project/documentFile.ts
@@ -1,4 +1,4 @@
-import { readTextFile, type TextFileReadFailure } from "@/utils/textFile";
+import { NotTextFileError, readTextFromFile } from "@/utils/dom";
 
 const MAX_DOCUMENT_FILE_MB = 1;
 const MAX_DOCUMENT_FILE_BYTES = MAX_DOCUMENT_FILE_MB * 1024 * 1024;
@@ -6,25 +6,26 @@ const MAX_DOCUMENT_FILE_BYTES = MAX_DOCUMENT_FILE_MB * 1024 * 1024;
 type DocumentFileReadResult =
   { ok: true; title: string; content: string } | { ok: false; error: string };
 
-function failureMessage(reason: TextFileReadFailure, fileName: string) {
-  switch (reason) {
-    case "too_large":
-      return `${fileName} is larger than ${MAX_DOCUMENT_FILE_MB} MB.`;
-    case "not_text":
-      return `${fileName} isn't a text file. Only text can be added as a document.`;
-    case "unreadable":
-      return `Couldn't read ${fileName}.`;
-  }
+function readFailureMessage(error: unknown, fileName: string) {
+  return error instanceof NotTextFileError
+    ? `${fileName} isn't a text file. Only text can be added as a document.`
+    : `Couldn't read ${fileName}.`;
 }
 
 export async function readDocumentFile(
   file: File,
 ): Promise<DocumentFileReadResult> {
-  const result = await readTextFile(file, {
-    maxBytes: MAX_DOCUMENT_FILE_BYTES,
-  });
+  if (file.size > MAX_DOCUMENT_FILE_BYTES) {
+    return {
+      ok: false,
+      error: `${file.name} is larger than ${MAX_DOCUMENT_FILE_MB} MB.`,
+    };
+  }
 
-  return result.ok
-    ? { ok: true, title: file.name, content: result.text }
-    : { ok: false, error: failureMessage(result.reason, file.name) };
+  try {
+    const content = await readTextFromFile(file);
+    return { ok: true, title: file.name, content };
+  } catch (error) {
+    return { ok: false, error: readFailureMessage(error, file.name) };
+  }
 }
diff --git a/src/hooks/useFileDrop.test.tsx b/src/components/Project/useFileDrop.test.tsx
similarity index 100%
rename from src/hooks/useFileDrop.test.tsx
rename to src/components/Project/useFileDrop.test.tsx
diff --git a/src/hooks/useFileDrop.ts b/src/components/Project/useFileDrop.ts
similarity index 100%
rename from src/hooks/useFileDrop.ts
rename to src/components/Project/useFileDrop.ts
diff --git a/src/components/shared/ReactFlow/FlowCanvas/FlowCanvas.tsx b/src/components/shared/ReactFlow/FlowCanvas/FlowCanvas.tsx
index 9dfa058132..374c84fc77 100644
--- a/src/components/shared/ReactFlow/FlowCanvas/FlowCanvas.tsx
+++ b/src/components/shared/ReactFlow/FlowCanvas/FlowCanvas.tsx
@@ -46,7 +46,7 @@ import {
   type TaskSpec,
 } from "@/utils/componentSpec";
 import { componentMetadata } from "@/utils/componentTracking";
-import { readTextFromFile } from "@/utils/dom";
+import { readYamlFromFile } from "@/utils/dom";
 import { deselectAllNodes } from "@/utils/flowUtils";
 import createNodesFromComponentSpec from "@/utils/nodes/createNodesFromComponentSpec";
 import {
@@ -637,7 +637,7 @@ const FlowCanvasContent = ({
     if (event.dataTransfer.files.length > 0) {
       try {
         // Parse the imported YAML to get the component spec
-        const content = await readTextFromFile(event.dataTransfer.files[0]);
+        const content = await readYamlFromFile(event.dataTransfer.files[0]);
         const hydratedComponentRef = await hydrateComponentReference({
           text: content,
         });
diff --git a/src/routes/v2/pages/Editor/components/FlowCanvas/hooks/useDropBehavior.test.tsx b/src/routes/v2/pages/Editor/components/FlowCanvas/hooks/useDropBehavior.test.tsx
index 6d6d36c1fa..1b1f0683c4 100644
--- a/src/routes/v2/pages/Editor/components/FlowCanvas/hooks/useDropBehavior.test.tsx
+++ b/src/routes/v2/pages/Editor/components/FlowCanvas/hooks/useDropBehavior.test.tsx
@@ -66,7 +66,7 @@ vi.mock("@/routes/v2/pages/Editor/store/actions/useTaskActions", () => ({
 }));
 vi.mock("@/hooks/useToastNotification", () => ({ default: () => vi.fn() }));
 vi.mock("@/utils/dom", () => ({
-  readTextFromFile: async () => "name: Search",
+  readYamlFromFile: async () => "name: Search",
 }));
 
 const spec = new YamlDeserializer(new IncrementingIdGenerator()).deserialize({
diff --git a/src/routes/v2/pages/Editor/components/FlowCanvas/hooks/useFileDropHandler.ts b/src/routes/v2/pages/Editor/components/FlowCanvas/hooks/useFileDropHandler.ts
index afcde28b25..2beb8b8f7a 100644
--- a/src/routes/v2/pages/Editor/components/FlowCanvas/hooks/useFileDropHandler.ts
+++ b/src/routes/v2/pages/Editor/components/FlowCanvas/hooks/useFileDropHandler.ts
@@ -8,7 +8,7 @@ import { useTaskActions } from "@/routes/v2/pages/Editor/store/actions/useTaskAc
 import { useSharedStores } from "@/routes/v2/shared/store/SharedStoreContext";
 import type { HydratedComponentReference } from "@/utils/componentSpec";
 import { componentMetadata } from "@/utils/componentTracking";
-import { readTextFromFile } from "@/utils/dom";
+import { readYamlFromFile } from "@/utils/dom";
 
 import { useValidateComponentDrop } from "./useValidateComponentDrop";
 
@@ -33,7 +33,7 @@ export function useFileDropHandler() {
 
   return async (file: File, spec: ComponentSpec, position: XYPosition) => {
     try {
-      const content = await readTextFromFile(file);
+      const content = await readYamlFromFile(file);
       const hydrated = await validateComponentDrop({ text: content });
 
       if (!hydrated || navigation.activeSpec !== spec) return;
diff --git a/src/utils/dom.test.ts b/src/utils/dom.test.ts
new file mode 100644
index 0000000000..73e6e61eef
--- /dev/null
+++ b/src/utils/dom.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { NotTextFileError, readTextFromFile, readYamlFromFile } from "./dom";
+
+describe("readTextFromFile", () => {
+  it("reads a text file", async () => {
+    const file = new File(["# Model card\n\nTrained on Q3"], "model-card.md");
+
+    await expect(readTextFromFile(file)).resolves.toBe(
+      "# Model card\n\nTrained on Q3",
+    );
+  });
+
+  it("reads text whatever the file is called", async () => {
+    const file = new File(["plain words"], "NOTES");
+
+    await expect(readTextFromFile(file)).resolves.toBe("plain words");
+  });
+
+  it("reads an empty file as empty text", async () => {
+    const file = new File([], "empty.txt");
+
+    await expect(readTextFromFile(file)).resolves.toBe("");
+  });
+
+  it("refuses bytes that are not UTF-8 text", async () => {
+    const file = new File(
+      [new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0xff])],
+      "chart.png",
+    );
+
+    await expect(readTextFromFile(file)).rejects.toBeInstanceOf(
+      NotTextFileError,
+    );
+  });
+
+  it("refuses valid UTF-8 that carries NUL bytes, as binary formats do", async () => {
+    const file = new File(["header\0\0\0body"], "model.bin");
+
+    await expect(readTextFromFile(file)).rejects.toBeInstanceOf(
+      NotTextFileError,
+    );
+  });
+
+  it("passes on the browser's error when it can't read the file", async () => {
+    const file = new File(["gone"], "moved.txt");
+    const notFound = new Error("NotFound");
+    vi.spyOn(file, "arrayBuffer").mockRejectedValue(notFound);
+
+    await expect(readTextFromFile(file)).rejects.toBe(notFound);
+  });
+});
+
+describe("readYamlFromFile", () => {
+  it("reads a YAML file", async () => {
+    const file = new File(["name: Train"], "component.yaml");
+
+    await expect(readYamlFromFile(file)).resolves.toBe("name: Train");
+  });
+
+  it("refuses a file that isn't named .yaml", async () => {
+    const file = new File(["name: Train"], "component.txt");
+
+    await expect(readYamlFromFile(file)).rejects.toThrow(
+      "Only YAML files are supported",
+    );
+  });
+});
diff --git a/src/utils/dom.ts b/src/utils/dom.ts
index c4da1fd91b..e68e268c75 100644
--- a/src/utils/dom.ts
+++ b/src/utils/dom.ts
@@ -1,29 +1,38 @@
 import type { MouseEvent } from "react";
 
-import { getStringFromData } from "./string";
-
 export function hasNewTabModifier(event: MouseEvent) {
   return event.ctrlKey || event.metaKey;
 }
 
+export class NotTextFileError extends Error {
+  constructor(fileName: string) {
+    super(`${fileName} is not a UTF-8 text file`);
+    this.name = "NotTextFileError";
+    Object.setPrototypeOf(this, NotTextFileError.prototype);
+  }
+}
+
+function decodeText(bytes: ArrayBuffer): string | null {
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    // Binary formats can still decode as valid UTF-8, but text never holds NUL.
+    return text.includes("\0") ? null : text;
+  } catch {
+    return null;
+  }
+}
+
 export async function readTextFromFile(file: File): Promise<string> {
-  return new Promise((resolve, reject) => {
-    if (!file.name.endsWith(".yaml")) {
-      reject("Only YAML files are supported");
-    }
-
-    const reader = new FileReader();
-    reader.onload = async (e) => {
-      const content = e.target?.result;
-      if (!content) {
-        reject("Failed to read file");
-      } else {
-        resolve(getStringFromData(content));
-      }
-    };
+  const text = decodeText(await file.arrayBuffer());
+  if (text === null) throw new NotTextFileError(file.name);
+  return text;
+}
 
-    reader.readAsText(file);
-  });
+export async function readYamlFromFile(file: File): Promise<string> {
+  if (!file.name.endsWith(".yaml")) {
+    throw new Error("Only YAML files are supported");
+  }
+  return readTextFromFile(file);
 }
 
 export function createPromiseFromDomEvent(
diff --git a/src/utils/textFile.test.ts b/src/utils/textFile.test.ts
deleted file mode 100644
index c4e71a7c79..0000000000
--- a/src/utils/textFile.test.ts
+++ /dev/null
@@ -1,72 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-import { readTextFile } from "./textFile";
-
-describe("readTextFile", () => {
-  it("reads a text file", async () => {
-    const file = new File(["# Model card\n\nTrained on Q3"], "model-card.md");
-
-    await expect(readTextFile(file)).resolves.toEqual({
-      ok: true,
-      text: "# Model card\n\nTrained on Q3",
-    });
-  });
-
-  it("reads text whatever the file is called", async () => {
-    const file = new File(["plain words"], "NOTES");
-
-    await expect(readTextFile(file)).resolves.toEqual({
-      ok: true,
-      text: "plain words",
-    });
-  });
-
-  it("refuses bytes that are not UTF-8 text", async () => {
-    const file = new File(
-      [new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0xff])],
-      "chart.png",
-    );
-
-    await expect(readTextFile(file)).resolves.toEqual({
-      ok: false,
-      reason: "not_text",
-    });
-  });
-
-  it("refuses valid UTF-8 that carries NUL bytes, as binary formats do", async () => {
-    const file = new File(["header\0\0\0body"], "model.bin");
-
-    await expect(readTextFile(file)).resolves.toEqual({
-      ok: false,
-      reason: "not_text",
-    });
-  });
-
-  it("refuses a file larger than the limit", async () => {
-    const file = new File(["12345"], "five-bytes.txt");
-
-    await expect(readTextFile(file, { maxBytes: 4 })).resolves.toEqual({
-      ok: false,
-      reason: "too_large",
-    });
-  });
-
-  it("accepts a file exactly at the limit", async () => {
-    const file = new File(["1234"], "four-bytes.txt");
-
-    await expect(readTextFile(file, { maxBytes: 4 })).resolves.toEqual({
-      ok: true,
-      text: "1234",
-    });
-  });
-
-  it("says so when the browser can't read the file", async () => {
-    const file = new File(["gone"], "moved.txt");
-    vi.spyOn(file, "arrayBuffer").mockRejectedValue(new Error("NotFound"));
-
-    await expect(readTextFile(file)).resolves.toEqual({
-      ok: false,
-      reason: "unreadable",
-    });
-  });
-});
diff --git a/src/utils/textFile.ts b/src/utils/textFile.ts
deleted file mode 100644
index 5365da0b69..0000000000
--- a/src/utils/textFile.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-export type TextFileReadFailure = "too_large" | "not_text" | "unreadable";
-
-type TextFileReadResult =
-  { ok: true; text: string } | { ok: false; reason: TextFileReadFailure };
-
-function decodeText(bytes: ArrayBuffer): string | null {
-  try {
-    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-    // Binary formats can still decode as valid UTF-8, but text never holds NUL.
-    return text.includes("\0") ? null : text;
-  } catch {
-    return null;
-  }
-}
-
-export async function readTextFile(
-  file: File,
-  { maxBytes = Infinity }: { maxBytes?: number } = {},
-): Promise<TextFileReadResult> {
-  if (file.size > maxBytes) return { ok: false, reason: "too_large" };
-
-  let bytes: ArrayBuffer;
-  try {
-    bytes = await file.arrayBuffer();
-  } catch {
-    return { ok: false, reason: "unreadable" };
-  }
-
-  const text = decodeText(bytes);
-  return text === null ? { ok: false, reason: "not_text" } : { ok: true, text };
-}

From bd33f82846cc9eb11069797b35cecf6e4719a77f Mon Sep 17 00:00:00 2001
From: Camiel van Schoonhoven <camiel.vanschoonhoven@shopify.com>
Date: Tue, 3 Nov 2026 10:09:17 -0700
Subject: [PATCH 5/5] fix(documents): fill the form from the latest file read
 only

Each read filled the form when it finished. If an earlier file finished
after a later one, the title stayed the later file's while the content
became the earlier file's. Only the latest read now fills the form, and
Add stays disabled until it finishes, so the draft can't be added while
it is about to change. Local files read instantly, but files kept in a
cloud drive can take seconds to download first.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 src/components/Project/DocumentForm.test.tsx | 60 +++++++++++++++++++-
 src/components/Project/DocumentForm.tsx      | 14 ++++-
 2 files changed, 71 insertions(+), 3 deletions(-)

diff --git a/src/components/Project/DocumentForm.test.tsx b/src/components/Project/DocumentForm.test.tsx
index cc32f95e1b..a9389649a2 100644
--- a/src/components/Project/DocumentForm.test.tsx
+++ b/src/components/Project/DocumentForm.test.tsx
@@ -1,4 +1,10 @@
-import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import {
+  act,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
@@ -53,6 +59,19 @@ function fileDrag(...files: File[]) {
 
 const modelCard = () => new File(["Trained on Q3 data"], "model-card.md");
 
+function fileReadOnCue(text: string, name: string) {
+  const file = new File([text], name);
+  let finishReading = () => {};
+  const bytes = new Promise<ArrayBuffer>((resolve) => {
+    finishReading = () => resolve(new TextEncoder().encode(text).buffer);
+  });
+  vi.spyOn(file, "arrayBuffer").mockReturnValue(bytes);
+  return { file, finishReading };
+}
+
+const addButton = () => screen.getByRole("button", { name: "Add" });
+const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
+
 describe("DocumentForm file drop", () => {
   afterEach(() => {
     vi.resetAllMocks();
@@ -127,6 +146,45 @@ describe("DocumentForm file drop", () => {
     expect(contentField()).toHaveValue("Trained on Q3 data");
   });
 
+  it("keeps the later file when an earlier one finishes reading last", async () => {
+    renderForm();
+    const first = fileReadOnCue("first draft", "first.md");
+    const second = fileReadOnCue("second draft", "second.md");
+
+    fireEvent.drop(form(), fileDrag(first.file));
+    fireEvent.drop(form(), fileDrag(second.file));
+
+    second.finishReading();
+    await waitFor(() => {
+      expect(contentField()).toHaveValue("second draft");
+    });
+
+    await act(async () => {
+      first.finishReading();
+      await settle();
+    });
+    expect(contentField()).toHaveValue("second draft");
+    expect(titleField()).toHaveValue("second.md");
+  });
+
+  it("holds off adding until a dropped file has been read", async () => {
+    const user = userEvent.setup();
+    renderForm();
+    await user.type(titleField(), "notes.md");
+    await user.type(contentField(), "Draft");
+    expect(addButton()).toBeEnabled();
+
+    const slow = fileReadOnCue("Trained on Q3 data", "model-card.md");
+    fireEvent.drop(form(), fileDrag(slow.file));
+    expect(addButton()).toBeDisabled();
+
+    slow.finishReading();
+    await waitFor(() => {
+      expect(addButton()).toBeEnabled();
+    });
+    expect(contentField()).toHaveValue("Trained on Q3 data");
+  });
+
   it("says why a file that isn't text can't be added, and leaves the fields alone", async () => {
     const user = userEvent.setup();
     renderForm();
diff --git a/src/components/Project/DocumentForm.tsx b/src/components/Project/DocumentForm.tsx
index 61b890091f..1e49f0054c 100644
--- a/src/components/Project/DocumentForm.tsx
+++ b/src/components/Project/DocumentForm.tsx
@@ -1,4 +1,4 @@
-import { type FormEvent, useState } from "react";
+import { type FormEvent, useRef, useState } from "react";
 
 import { languageFor } from "@/components/shared/CodeViewer";
 import CodeEditor from "@/components/shared/CodeViewer/CodeEditor";
@@ -32,11 +32,18 @@ export function DocumentForm({
   const [content, setContent] = useState("");
   const [titleFromFile, setTitleFromFile] = useState<string | null>(null);
   const [fileError, setFileError] = useState<string | null>(null);
+  const [isReadingFile, setIsReadingFile] = useState(false);
+  const latestReadId = useRef(0);
 
   const fillFromFile = async (file: File, method: "drop" | "browse") => {
     if (isSubmitting) return;
 
+    const readId = ++latestReadId.current;
+    setIsReadingFile(true);
     const result = await readDocumentFile(file);
+    if (readId !== latestReadId.current) return;
+
+    setIsReadingFile(false);
     if (!result.ok) {
       setFileError(result.error);
       return;
@@ -60,7 +67,10 @@ export function DocumentForm({
   const trimmedTitle = title.trim();
   const trimmedContent = content.trim();
   const canSubmit =
-    trimmedTitle !== "" && trimmedContent !== "" && !isSubmitting;
+    trimmedTitle !== "" &&
+    trimmedContent !== "" &&
+    !isSubmitting &&
+    !isReadingFile;
 
   const handleSubmit = (event: FormEvent) => {
     event.preventDefault();