@stigmer/react 3.8.0 → 3.9.0

package/src/composer/SessionComposer.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { forwardRef, memo, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState, type DragEvent, type KeyboardEvent } from "react";
+import { forwardRef, memo, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState, type ClipboardEvent, type DragEvent, type KeyboardEvent } from "react";
 import { cn } from "@stigmer/theme";
 import { getUserMessage, type AttachmentInput, type EnvVarInput, type McpServerUsageInput, type ResourceRef } from "@stigmer/sdk";
 import { useComposer } from "./useComposer.js";
@@ -25,6 +25,8 @@ import type { UseWorkspaceEntriesReturn } from "../workspace/useWorkspaceEntries
 import type { UseGitHubConnectionReturn } from "../github/useGitHubConnection.js";
 import { useAttachments } from "../attachment/useAttachments.js";
 import { AttachmentChipList } from "../attachment/AttachmentChipList.js";
+import { extractClipboardFiles } from "../attachment/clipboard.js";
+import { prepareImageForVision } from "../attachment/prepare-image.js";
 import { useFileReferences } from "../file-reference/useFileReferences.js";
 import { FileReferenceChipList } from "../file-reference/FileReferenceChipList.js";
 import { FILE_REF_MIME } from "../internal/file-tree/index.js";
@@ -42,6 +44,7 @@ import {
   SkillIcon,
   SecretsIcon,
   AlertTriangleIcon,
+  ChipSpinner,
   ResolveSpinner,
   XIcon,
 } from "./icons.js";
@@ -439,7 +442,9 @@ export interface SessionComposerProps {
    * Enable file attachment support in the composer.
    *
    * When `true`, renders an attach button in the toolbar and enables
-   * drag-and-drop file upload on the textarea. Attachments are uploaded
+   * drag-and-drop file upload plus clipboard paste on the textarea —
+   * pasting a screenshot attaches it exactly like a picked file, with
+   * a generated `pasted-image-*` filename. Attachments are uploaded
    * immediately via `agentExecution.uploadAttachment()` and included
    * in `context.attachments` on submit.
    *
@@ -794,6 +799,34 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
     [enableAttachments, enableFileReferences, isDisabled, attachments, fileRefs],
   );
 
+  // Clipboard paste — the Cursor-grade "screenshot straight into the chat"
+  // gesture (#284). Scoped to the textarea, never the document: a global
+  // clipboard listener would hijack paste for the host application.
+  const handlePaste = useCallback(
+    (e: ClipboardEvent<HTMLTextAreaElement>) => {
+      if (!enableAttachments || isDisabled) return;
+
+      // Must stay synchronous through preventDefault: clipboard file
+      // handles are only reliable during event dispatch (see clipboard.ts).
+      const files = extractClipboardFiles(e);
+      if (files.length === 0) return;
+
+      // Files replace the default insert — a copied image usually carries
+      // an HTML/text flavor that would paste as junk markup. A text-only
+      // paste never reaches this point and proceeds untouched.
+      e.preventDefault();
+
+      // Pasted images (and only pasted — see prepare-image.ts) are bounded
+      // to provider resolution before upload. prepareImageForVision never
+      // throws; every failure path yields the original file.
+      const addFiles = attachments.addFiles;
+      void Promise.all(files.map(prepareImageForVision)).then((prepared) => {
+        addFiles(prepared);
+      });
+    },
+    [enableAttachments, isDisabled, attachments.addFiles],
+  );
+
   // ---------------------------------------------------------------------------
   // Submit — aggregates one-time runtimeEnv from all setup flows
   // ---------------------------------------------------------------------------
@@ -1191,7 +1224,23 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
   // ---------------------------------------------------------------------------
 
   const mcpBlocked = showMcp && !mcpSetup.allReady;
-  const canSend = composer.canSubmit && !mcpBlocked;
+  // Send waits for in-flight uploads: toAttachmentInputs() carries only
+  // "ready" entries, so a send racing an upload would silently drop the
+  // file the user just pasted — the worst failure for "what's wrong in
+  // this screenshot?". Errored entries never gate (their chip offers
+  // retry/remove); only the uploading phase blocks.
+  const uploadsBlocked = enableAttachments && attachments.isUploading;
+  const canSend = composer.canSubmit && !mcpBlocked && !uploadsBlocked;
+
+  // True when the upload gate is the OPERATIVE blocker — the message would
+  // send right now if uploads were done. Drives the attempt-triggered wait
+  // notice so it never claims "waiting for attachments" when the real
+  // blocker is an empty message or MCP setup.
+  const uploadWaitOperative = composer.canSubmit && !mcpBlocked && uploadsBlocked;
+  const [showUploadWaitNotice, setShowUploadWaitNotice] = useState(false);
+  useEffect(() => {
+    if (!uploadsBlocked) setShowUploadWaitNotice(false);
+  }, [uploadsBlocked]);
 
   const handleTextareaKeyDown = useCallback(
     (e: KeyboardEvent<HTMLTextAreaElement>) => {
@@ -1205,11 +1254,15 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
       }
       if (!canSend && e.key === "Enter" && !e.shiftKey) {
         e.preventDefault();
+        // Disclose the block only on an actual send attempt: a sub-second
+        // picker upload should never flash UI, and the per-chip spinner
+        // already covers passive awareness.
+        if (uploadWaitOperative) setShowUploadWaitNotice(true);
         return;
       }
       composer.textareaProps.onKeyDown(e);
     },
-    [canSend, composer.textareaProps, isEditing, onCancelEdit],
+    [canSend, uploadWaitOperative, composer.textareaProps, isEditing, onCancelEdit],
   );
 
   const workspaceCount = workspace?.entries.length ?? 0;
@@ -1487,6 +1540,7 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
           <textarea
             {...composer.textareaProps}
             onKeyDown={handleTextareaKeyDown}
+            onPaste={handlePaste}
             placeholder={placeholder}
             rows={initialRows}
             autoFocus={autoFocus}
@@ -1535,6 +1589,21 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
           </div>
         ) : null}
 
+        {/* Zone 2.6: Upload-wait notice — shown only after an attempted send
+            while attachments are still uploading (attempt-triggered; see
+            uploadWaitOperative). Muted status styling, not warning: waiting
+            is progress, not a problem. role="status" announces the row to
+            screen readers when it appears. */}
+        {showUploadWaitNotice && (
+          <div
+            role="status"
+            className="mx-3 mb-2 flex items-center gap-2 rounded-md bg-muted px-2.5 py-1.5 text-xs text-muted-foreground"
+          >
+            <ChipSpinner />
+            <span>Waiting for attachments to finish uploading…</span>
+          </div>
+        )}
+
         {/* Zone 2.7: Agent setup warning */}
         {showAgent &&
           agentSetup.state.status === "needsEnvVars" &&

package/src/composer/__tests__/SessionComposer-paste.test.tsx

@@ -0,0 +1,263 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import {
+  render,
+  screen,
+  cleanup,
+  fireEvent,
+  createEvent,
+  act,
+  waitFor,
+} from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { ModelRegistryContext } from "../../models/ModelRegistryContext";
+import { SessionComposer } from "../SessionComposer";
+import { MAX_ATTACHMENT_BYTES } from "../../attachment/attachment-utils";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createMinimalStigmerMock(): Stigmer {
+  return {
+    agentExecution: {
+      uploadAttachment: vi
+        .fn()
+        .mockResolvedValue({ storageKey: "attachments/test-ulid/file" }),
+    },
+    environment: { getPersonal: vi.fn().mockResolvedValue(null) },
+    baseUrl: "http://localhost:8080",
+    getAuthCredential: vi.fn().mockResolvedValue("test-token"),
+    config: {
+      baseUrl: "http://localhost:8080",
+      getAccessToken: vi.fn().mockResolvedValue(""),
+    },
+  } as unknown as Stigmer;
+}
+
+function createWrapper(client: Stigmer) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <StigmerContext.Provider value={client}>
+        <ModelRegistryContext.Provider
+          value={{ models: [], isLoading: false, error: null, refetch: vi.fn() }}
+        >
+          {children}
+        </ModelRegistryContext.Provider>
+      </StigmerContext.Provider>
+    );
+  };
+}
+
+function renderComposer(
+  props?: Partial<React.ComponentProps<typeof SessionComposer>>,
+) {
+  const client = createMinimalStigmerMock();
+  const onSubmit = vi.fn();
+  const onAttachmentValidationError = vi.fn();
+
+  const result = render(
+    <SessionComposer
+      onSubmit={onSubmit}
+      onAttachmentValidationError={onAttachmentValidationError}
+      {...props}
+    />,
+    { wrapper: createWrapper(client) },
+  );
+
+  return { ...result, onSubmit, onAttachmentValidationError, client };
+}
+
+function pngFile(
+  name: string,
+  bytes: Uint8Array<ArrayBuffer> = new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
+): File {
+  return new File([bytes], name, { type: "image/png" });
+}
+
+/**
+ * dom-testing-library special-cases `clipboardData` in event init, so the
+ * handler receives it exactly as a real paste would deliver it. Files are
+ * a plain array cast to FileList — the code only reads it array-like.
+ */
+function pasteInit(files: File[], text = "") {
+  return {
+    clipboardData: {
+      files: files as unknown as FileList,
+      getData: (type: string) => (type === "text/plain" ? text : ""),
+      types: files.length > 0 ? ["Files"] : ["text/plain"],
+    },
+  };
+}
+
+/** Wait until no chip reports "uploading" in its accessible label. */
+async function waitForUploadsSettled(container: HTMLElement) {
+  await waitFor(() => {
+    const uploading = container.querySelector('[aria-label*=", uploading"]');
+    expect(uploading).toBeNull();
+  });
+}
+
+afterEach(cleanup);
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("SessionComposer — clipboard paste", () => {
+  it("attaches a pasted screenshot as a chip and uploads its bytes", async () => {
+    const { container, client } = renderComposer();
+    const textarea = screen.getByRole("textbox");
+
+    await act(async () => {
+      fireEvent.paste(textarea, pasteInit([pngFile("image.png")]));
+    });
+
+    // The generic clipboard name is replaced by a synthesized unique one.
+    const chip = container.querySelector('[role="listitem"]');
+    expect(chip).toBeTruthy();
+    expect(chip!.getAttribute("aria-label")).toMatch(/^pasted-image-\d{6}-\d+\.png/);
+
+    await waitFor(() => {
+      expect(
+        (client as unknown as { agentExecution: { uploadAttachment: ReturnType<typeof vi.fn> } })
+          .agentExecution.uploadAttachment,
+      ).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it("suppresses the default text insert when the clipboard carries files", async () => {
+    renderComposer();
+    const textarea = screen.getByRole("textbox");
+
+    const event = createEvent.paste(textarea, pasteInit([pngFile("image.png")], "<img src=...>"));
+    await act(async () => {
+      fireEvent(textarea, event);
+    });
+
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("leaves a text-only paste completely untouched", async () => {
+    const { container } = renderComposer();
+    const textarea = screen.getByRole("textbox");
+
+    const event = createEvent.paste(textarea, pasteInit([], "plain words"));
+    await act(async () => {
+      fireEvent(textarea, event);
+    });
+
+    expect(event.defaultPrevented).toBe(false);
+    expect(container.querySelector('[role="listitem"]')).toBeNull();
+  });
+
+  it("gives two screenshots pasted in one turn distinct filenames", async () => {
+    const { container } = renderComposer();
+    const textarea = screen.getByRole("textbox");
+
+    await act(async () => {
+      fireEvent.paste(textarea, pasteInit([pngFile("image.png")]));
+    });
+    await act(async () => {
+      fireEvent.paste(textarea, pasteInit([pngFile("image.png")]));
+    });
+
+    const chips = Array.from(container.querySelectorAll('[role="listitem"]'));
+    expect(chips).toHaveLength(2);
+    const labels = chips.map((c) => c.getAttribute("aria-label"));
+    expect(labels[0]).not.toBe(labels[1]);
+  });
+
+  it("is inert when attachments are disabled (guest mode)", async () => {
+    const { container } = renderComposer({ enableAttachments: false });
+    const textarea = screen.getByRole("textbox");
+
+    const event = createEvent.paste(textarea, pasteInit([pngFile("image.png")]));
+    await act(async () => {
+      fireEvent(textarea, event);
+    });
+
+    expect(event.defaultPrevented).toBe(false);
+    expect(container.querySelector('[role="listitem"]')).toBeNull();
+  });
+
+  it("is inert while the composer is disabled", async () => {
+    const { container } = renderComposer({ disabled: true });
+    const textarea = screen.getByRole("textbox");
+
+    const event = createEvent.paste(textarea, pasteInit([pngFile("image.png")]));
+    await act(async () => {
+      fireEvent(textarea, event);
+    });
+
+    expect(event.defaultPrevented).toBe(false);
+    expect(container.querySelector('[role="listitem"]')).toBeNull();
+  });
+
+  it("routes an oversized paste through onAttachmentValidationError with no chip", async () => {
+    const { container, onAttachmentValidationError } = renderComposer();
+    const textarea = screen.getByRole("textbox");
+
+    const huge = pngFile("image.png", new Uint8Array(MAX_ATTACHMENT_BYTES + 1));
+    await act(async () => {
+      fireEvent.paste(textarea, pasteInit([huge]));
+    });
+
+    expect(onAttachmentValidationError).toHaveBeenCalledTimes(1);
+    expect(onAttachmentValidationError.mock.calls[0][0]).toContain("10 MB");
+    expect(container.querySelector('[role="listitem"]')).toBeNull();
+  });
+
+  it("includes the pasted attachment in the submit context", async () => {
+    const { container, onSubmit } = renderComposer();
+    const textarea = screen.getByRole("textbox");
+
+    await act(async () => {
+      fireEvent.paste(textarea, pasteInit([pngFile("image.png")]));
+    });
+    await waitForUploadsSettled(container);
+
+    await act(async () => {
+      fireEvent.change(textarea, { target: { value: "What is wrong in this screenshot?" } });
+    });
+    await act(async () => {
+      fireEvent.keyDown(textarea, { key: "Enter", shiftKey: false });
+    });
+
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    const [, , context] = onSubmit.mock.calls[0];
+    expect(context?.attachments).toHaveLength(1);
+    expect(context.attachments[0].filename).toMatch(/^pasted-image-/);
+    expect(context.attachments[0].storageKey).toBe("attachments/test-ulid/file");
+    expect(context.attachments[0].contentType).toBe("image/png");
+  });
+
+  it("keeps the drop path working: same-named drops are uniquified, not clobbered", async () => {
+    const { container } = renderComposer();
+    const dropTarget = container.querySelector("[class*='rounded-xl']")!;
+
+    const dropEvent = (files: File[]) => ({
+      dataTransfer: {
+        types: ["Files"],
+        getData: () => "",
+        files: files as unknown as FileList,
+      },
+      preventDefault: vi.fn(),
+      stopPropagation: vi.fn(),
+    });
+
+    await act(async () => {
+      fireEvent.drop(
+        dropTarget,
+        dropEvent([
+          new File(["a"], "notes.md", { type: "text/markdown" }),
+          new File(["b"], "notes.md", { type: "text/markdown" }),
+        ]),
+      );
+    });
+
+    expect(screen.getByText("notes.md")).toBeTruthy();
+    expect(screen.getByText("notes-2.md")).toBeTruthy();
+  });
+});

package/src/composer/__tests__/SessionComposer-uploadGate.test.tsx

@@ -0,0 +1,239 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import {
+  render,
+  screen,
+  cleanup,
+  fireEvent,
+  act,
+  waitFor,
+} from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { ModelRegistryContext } from "../../models/ModelRegistryContext";
+import { SessionComposer } from "../SessionComposer";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const WAIT_NOTICE = "Waiting for attachments to finish uploading…";
+
+/**
+ * Stigmer mock whose uploadAttachment resolution is controlled by the test,
+ * so a test can hold the composer in the "uploading" phase deliberately.
+ */
+function createDeferredUploadMock() {
+  const pending: Array<(value: { storageKey: string }) => void> = [];
+  const rejectors: Array<(err: Error) => void> = [];
+
+  const uploadAttachment = vi.fn(
+    () =>
+      new Promise<{ storageKey: string }>((resolve, reject) => {
+        pending.push(resolve);
+        rejectors.push(reject);
+      }),
+  );
+
+  const client = {
+    agentExecution: { uploadAttachment },
+    environment: { getPersonal: vi.fn().mockResolvedValue(null) },
+    baseUrl: "http://localhost:8080",
+    getAuthCredential: vi.fn().mockResolvedValue("test-token"),
+    config: {
+      baseUrl: "http://localhost:8080",
+      getAccessToken: vi.fn().mockResolvedValue(""),
+    },
+  } as unknown as Stigmer;
+
+  return {
+    client,
+    uploadAttachment,
+    resolveAll: () => {
+      for (const resolve of pending.splice(0)) {
+        resolve({ storageKey: "attachments/test-ulid/file" });
+      }
+      rejectors.length = 0;
+    },
+    rejectAll: () => {
+      for (const reject of rejectors.splice(0)) {
+        reject(new Error("upload failed for test"));
+      }
+      pending.length = 0;
+    },
+  };
+}
+
+function createWrapper(client: Stigmer) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <StigmerContext.Provider value={client}>
+        <ModelRegistryContext.Provider
+          value={{ models: [], isLoading: false, error: null, refetch: vi.fn() }}
+        >
+          {children}
+        </ModelRegistryContext.Provider>
+      </StigmerContext.Provider>
+    );
+  };
+}
+
+function renderComposer(client: Stigmer) {
+  const onSubmit = vi.fn();
+  const result = render(<SessionComposer onSubmit={onSubmit} />, {
+    wrapper: createWrapper(client),
+  });
+  return { ...result, onSubmit };
+}
+
+function pasteImage(textarea: Element) {
+  fireEvent.paste(textarea, {
+    clipboardData: {
+      files: [
+        new File([new Uint8Array([0x89, 0x50, 0x4e, 0x47])], "image.png", {
+          type: "image/png",
+        }),
+      ] as unknown as FileList,
+      getData: () => "",
+      types: ["Files"],
+    },
+  });
+}
+
+function typeAndEnter(textarea: Element, message: string) {
+  fireEvent.change(textarea, { target: { value: message } });
+  fireEvent.keyDown(textarea, { key: "Enter", shiftKey: false });
+}
+
+afterEach(cleanup);
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("SessionComposer — mid-upload send gate", () => {
+  it("blocks Enter while an upload is in flight and shows the wait notice", async () => {
+    const mock = createDeferredUploadMock();
+    const { onSubmit } = renderComposer(mock.client);
+    const textarea = screen.getByRole("textbox");
+
+    await act(async () => {
+      pasteImage(textarea);
+    });
+    await act(async () => {
+      typeAndEnter(textarea, "What is wrong in this screenshot?");
+    });
+
+    expect(onSubmit).not.toHaveBeenCalled();
+    expect(screen.getByText(WAIT_NOTICE)).toBeTruthy();
+    expect(screen.getByText(WAIT_NOTICE).closest('[role="status"]')).toBeTruthy();
+  });
+
+  it("clears the notice and sends WITH the attachment once uploads settle", async () => {
+    const mock = createDeferredUploadMock();
+    const { onSubmit } = renderComposer(mock.client);
+    const textarea = screen.getByRole("textbox");
+
+    await act(async () => {
+      pasteImage(textarea);
+    });
+    await act(async () => {
+      typeAndEnter(textarea, "What is wrong here?");
+    });
+    expect(onSubmit).not.toHaveBeenCalled();
+
+    await act(async () => {
+      mock.resolveAll();
+    });
+
+    await waitFor(() => {
+      expect(screen.queryByText(WAIT_NOTICE)).toBeNull();
+    });
+
+    await act(async () => {
+      fireEvent.keyDown(textarea, { key: "Enter", shiftKey: false });
+    });
+
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    const [message, , context] = onSubmit.mock.calls[0];
+    expect(message).toBe("What is wrong here?");
+    expect(context?.attachments).toHaveLength(1);
+    expect(context.attachments[0].storageKey).toBe("attachments/test-ulid/file");
+  });
+
+  it("does not show the notice when Enter is blocked for another reason (empty message)", async () => {
+    const mock = createDeferredUploadMock();
+    renderComposer(mock.client);
+    const textarea = screen.getByRole("textbox");
+
+    await act(async () => {
+      pasteImage(textarea);
+    });
+    // Enter with an empty message: blocked by canSubmit, not by uploads —
+    // claiming "waiting for attachments" here would be a lie.
+    await act(async () => {
+      fireEvent.keyDown(textarea, { key: "Enter", shiftKey: false });
+    });
+
+    expect(screen.queryByText(WAIT_NOTICE)).toBeNull();
+  });
+
+  it("does not wedge the composer when an upload errors — send proceeds without the failed file", async () => {
+    const mock = createDeferredUploadMock();
+    const { onSubmit } = renderComposer(mock.client);
+    const textarea = screen.getByRole("textbox");
+
+    await act(async () => {
+      pasteImage(textarea);
+    });
+    await act(async () => {
+      mock.rejectAll();
+    });
+
+    // The errored chip stays visible with retry/remove, but must not gate.
+    await waitFor(() => {
+      const chip = document.querySelector('[aria-label*="upload failed"]');
+      expect(chip).toBeTruthy();
+    });
+
+    await act(async () => {
+      typeAndEnter(textarea, "Send it anyway");
+    });
+
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    // The failed upload has no storage key — it must not ride the send.
+    const [, , context] = onSubmit.mock.calls[0];
+    expect(context?.attachments ?? []).toHaveLength(0);
+  });
+
+  it("gates a fast follow-up paste too: Enter between two uploads still waits for the second", async () => {
+    const mock = createDeferredUploadMock();
+    const { onSubmit } = renderComposer(mock.client);
+    const textarea = screen.getByRole("textbox");
+
+    await act(async () => {
+      pasteImage(textarea);
+    });
+    await act(async () => {
+      mock.resolveAll();
+    });
+    await act(async () => {
+      pasteImage(textarea);
+    });
+
+    await act(async () => {
+      typeAndEnter(textarea, "Compare these two");
+    });
+    expect(onSubmit).not.toHaveBeenCalled();
+
+    await act(async () => {
+      mock.resolveAll();
+    });
+    await act(async () => {
+      fireEvent.keyDown(textarea, { key: "Enter", shiftKey: false });
+    });
+
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit.mock.calls[0][2]?.attachments).toHaveLength(2);
+  });
+});

package/src/index.ts

@@ -463,21 +463,31 @@ export type {
 export type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
 export { ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 
-// Attachment — file upload behavior hook and styled chip list
+// Attachment — file upload behavior hook, styled chip list, clipboard paste,
+// and vision-resolution image preparation
 export {
   useAttachments,
   AttachmentChipList,
   MAX_ATTACHMENT_BYTES,
+  MAX_VISION_LONG_EDGE_PX,
+  MAX_VISION_PIXELS,
   detectContentType,
+  exceedsVisionResolution,
+  extractClipboardFiles,
+  fitToVisionResolution,
   formatFileSize,
+  prepareImageForVision,
+  uniquifyFilename,
   validateAttachmentSize,
 } from "./attachment/index.js";
 export type {
   AttachmentPhase,
   AttachmentEntry,
+  ClipboardFilesSource,
   UseAttachmentsOptions,
   UseAttachmentsReturn,
   AttachmentChipListProps,
+  VisionFitSize,
 } from "./attachment/index.js";
 
 // File Reference — workspace file-reference behavior hook and styled chip list