@stigmer/react 3.12.4 → 3.12.5

package/settings/settings-nav.js

@@ -1,4 +1,4 @@
-import { Activity, AppWindow, BarChart3, Box, Building2, CreditCard, KeyRound, Link, MessageSquare, MousePointerClick, Plug, Scale, ShieldCheck, Users, } from "lucide-react";
+import { Activity, AppWindow, BarChart3, Box, Building2, CreditCard, KeyRound, Link, MessageSquare, MousePointerClick, Plug, Scale, ShieldCheck, SlidersHorizontal, UserCog, Users, } from "lucide-react";
 /** Canonical settings sidebar/grouped navigation model. */
 export const SETTINGS_NAV_GROUPS = [
     {
@@ -6,6 +6,11 @@ export const SETTINGS_NAV_GROUPS = [
         description: "Manage your team, organization identity, and identity providers.",
         items: [
             { href: "/settings/org-profile", label: "Org Profile", icon: Building2 },
+            {
+                href: "/settings/org-preferences",
+                label: "Preferences",
+                icon: SlidersHorizontal,
+            },
             { href: "/settings/members", label: "Members", icon: Users },
             { href: "/settings/invitations", label: "Invitations", icon: Link },
             {
@@ -42,6 +47,17 @@ export const SETTINGS_NAV_GROUPS = [
             { href: "/settings/usage", label: "Usage", icon: BarChart3 },
         ],
     },
+    {
+        label: "Account",
+        description: "Personal settings that apply to you across the platform.",
+        items: [
+            {
+                href: "/settings/account-preferences",
+                label: "Preferences",
+                icon: UserCog,
+            },
+        ],
+    },
 ];
 /**
  * Stigmer-internal platform-operator navigation group.

package/settings/settings-nav.js.map

@@ -1 +1 @@
-{"version":3,"file":"settings-nav.js","sourceRoot":"","sources":["../../src/settings/settings-nav.ts"],"names":[],"mappings":"AACA,OAAO,EACL,QAAQ,EACR,SAAS,EACT,SAAS,EACT,GAAG,EACH,SAAS,EACT,UAAU,EACV,QAAQ,EACR,IAAI,EACJ,aAAa,EACb,iBAAiB,EACjB,IAAI,EACJ,KAAK,EACL,WAAW,EACX,KAAK,GACN,MAAM,cAAc,CAAC;AAiCtB,2DAA2D;AAC3D,MAAM,CAAC,MAAM,mBAAmB,GAAgC;IAC9D;QACE,KAAK,EAAE,cAAc;QACrB,WAAW,EACT,kEAAkE;QACpE,KAAK,EAAE;YACL,EAAE,IAAI,EAAE,uBAAuB,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,EAAE;YACxE,EAAE,IAAI,EAAE,mBAAmB,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE;YAC5D,EAAE,IAAI,EAAE,uBAAuB,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE;YACnE;gBACE,IAAI,EAAE,8BAA8B;gBACpC,KAAK,EAAE,oBAAoB;gBAC3B,IAAI,EAAE,WAAW;aAClB;SACF;KACF;IACD;QACE,KAAK,EAAE,eAAe;QACtB,WAAW,EACT,mFAAmF;QACrF,KAAK,EAAE;YACL,EAAE,IAAI,EAAE,oBAAoB,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE;YACjE;gBACE,IAAI,EAAE,4BAA4B;gBAClC,KAAK,EAAE,kBAAkB;gBACzB,IAAI,EAAE,IAAI;aACX;YACD,EAAE,IAAI,EAAE,wBAAwB,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,GAAG,EAAE;YACpE,EAAE,IAAI,EAAE,sBAAsB,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE;YACtE;gBACE,IAAI,EAAE,wBAAwB;gBAC9B,KAAK,EAAE,cAAc;gBACrB,IAAI,EAAE,aAAa;aACpB;SACF;KACF;IACD;QACE,KAAK,EAAE,iBAAiB;QACxB,WAAW,EAAE,sCAAsC;QACnD,KAAK,EAAE;YACL,EAAE,IAAI,EAAE,mBAAmB,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE;YACjE,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE;SAC7D;KACF;CACF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAqB;IAC3D,KAAK,EAAE,UAAU;IACjB,WAAW,EACT,kEAAkE;IACpE,KAAK,EAAE;QACL;YACE,IAAI,EAAE,8BAA8B;YACpC,KAAK,EAAE,oBAAoB;YAC3B,IAAI,EAAE,KAAK;YACX,kBAAkB,EAAE,0BAA0B;SAC/C;QACD;YACE,IAAI,EAAE,2BAA2B;YACjC,KAAK,EAAE,iBAAiB;YACxB,IAAI,EAAE,iBAAiB;YACvB,kBAAkB,EAAE,4BAA4B;SACjD;QACD;YACE,IAAI,EAAE,6BAA6B;YACnC,KAAK,EAAE,mBAAmB;YAC1B,IAAI,EAAE,QAAQ;YACd,kBAAkB,EAAE,4BAA4B;SACjD;KACF;CACF,CAAC"}
+{"version":3,"file":"settings-nav.js","sourceRoot":"","sources":["../../src/settings/settings-nav.ts"],"names":[],"mappings":"AACA,OAAO,EACL,QAAQ,EACR,SAAS,EACT,SAAS,EACT,GAAG,EACH,SAAS,EACT,UAAU,EACV,QAAQ,EACR,IAAI,EACJ,aAAa,EACb,iBAAiB,EACjB,IAAI,EACJ,KAAK,EACL,WAAW,EACX,iBAAiB,EACjB,OAAO,EACP,KAAK,GACN,MAAM,cAAc,CAAC;AAiCtB,2DAA2D;AAC3D,MAAM,CAAC,MAAM,mBAAmB,GAAgC;IAC9D;QACE,KAAK,EAAE,cAAc;QACrB,WAAW,EACT,kEAAkE;QACpE,KAAK,EAAE;YACL,EAAE,IAAI,EAAE,uBAAuB,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,EAAE;YACxE;gBACE,IAAI,EAAE,2BAA2B;gBACjC,KAAK,EAAE,aAAa;gBACpB,IAAI,EAAE,iBAAiB;aACxB;YACD,EAAE,IAAI,EAAE,mBAAmB,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE;YAC5D,EAAE,IAAI,EAAE,uBAAuB,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE;YACnE;gBACE,IAAI,EAAE,8BAA8B;gBACpC,KAAK,EAAE,oBAAoB;gBAC3B,IAAI,EAAE,WAAW;aAClB;SACF;KACF;IACD;QACE,KAAK,EAAE,eAAe;QACtB,WAAW,EACT,mFAAmF;QACrF,KAAK,EAAE;YACL,EAAE,IAAI,EAAE,oBAAoB,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE;YACjE;gBACE,IAAI,EAAE,4BAA4B;gBAClC,KAAK,EAAE,kBAAkB;gBACzB,IAAI,EAAE,IAAI;aACX;YACD,EAAE,IAAI,EAAE,wBAAwB,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,GAAG,EAAE;YACpE,EAAE,IAAI,EAAE,sBAAsB,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE;YACtE;gBACE,IAAI,EAAE,wBAAwB;gBAC9B,KAAK,EAAE,cAAc;gBACrB,IAAI,EAAE,aAAa;aACpB;SACF;KACF;IACD;QACE,KAAK,EAAE,iBAAiB;QACxB,WAAW,EAAE,sCAAsC;QACnD,KAAK,EAAE;YACL,EAAE,IAAI,EAAE,mBAAmB,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE;YACjE,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE;SAC7D;KACF;IACD;QACE,KAAK,EAAE,SAAS;QAChB,WAAW,EAAE,0DAA0D;QACvE,KAAK,EAAE;YACL;gBACE,IAAI,EAAE,+BAA+B;gBACrC,KAAK,EAAE,aAAa;gBACpB,IAAI,EAAE,OAAO;aACd;SACF;KACF;CACF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAqB;IAC3D,KAAK,EAAE,UAAU;IACjB,WAAW,EACT,kEAAkE;IACpE,KAAK,EAAE;QACL;YACE,IAAI,EAAE,8BAA8B;YACpC,KAAK,EAAE,oBAAoB;YAC3B,IAAI,EAAE,KAAK;YACX,kBAAkB,EAAE,0BAA0B;SAC/C;QACD;YACE,IAAI,EAAE,2BAA2B;YACjC,KAAK,EAAE,iBAAiB;YACxB,IAAI,EAAE,iBAAiB;YACvB,kBAAkB,EAAE,4BAA4B;SACjD;QACD;YACE,IAAI,EAAE,6BAA6B;YACnC,KAAK,EAAE,mBAAmB;YAC1B,IAAI,EAAE,QAAQ;YACd,kBAAkB,EAAE,4BAA4B;SACjD;KACF;CACF,CAAC"}

package/src/attachment/AttachmentChipList.tsx

@@ -154,9 +154,20 @@ function AttachmentChip({
 
 /** Shared accessible name: filename, size, and upload status. */
 function chipAriaLabel(entry: AttachmentEntry): string {
+  const isPreparing = entry.phase === "preparing";
   const isUploading = entry.phase === "uploading";
   const isError = entry.phase === "error";
-  return `${entry.file.name}, ${formatFileSize(entry.file.size)}${isUploading ? ", uploading" : ""}${isError ? ", upload failed" : ""}`;
+  return `${entry.file.name}, ${formatFileSize(entry.file.size)}${isPreparing ? ", preparing" : ""}${isUploading ? ", uploading" : ""}${isError ? ", upload failed" : ""}`;
+}
+
+/**
+ * True while the entry has work in flight (`preparing` or `uploading`) —
+ * the chips render both identically (dimmed + spinner): to the user each
+ * means "your file is on its way", and the split is audible in the
+ * accessible label where it actually informs.
+ */
+function isChipBusy(entry: AttachmentEntry): boolean {
+  return entry.phase === "preparing" || entry.phase === "uploading";
 }
 
 // ---------------------------------------------------------------------------
@@ -212,7 +223,7 @@ function ImageAttachmentChip({
   }
 
   const isError = entry.phase === "error";
-  const isUploading = entry.phase === "uploading";
+  const isBusy = isChipBusy(entry);
 
   return (
     // The remove badge and retry pill are SIBLINGS of the preview button,
@@ -250,7 +261,7 @@ function ImageAttachmentChip({
               onError={() => setLoadFailed(true)}
               className={cn(
                 "stg:h-full stg:w-full stg:object-cover",
-                (isUploading || isError) && "stg:opacity-50",
+                (isBusy || isError) && "stg:opacity-50",
               )}
             />
           ) : (
@@ -261,7 +272,7 @@ function ImageAttachmentChip({
               aria-hidden="true"
             />
           )}
-          {isUploading && (
+          {isBusy && (
             <span className="stg:absolute stg:inset-0 stg:flex stg:items-center stg:justify-center">
               <ChipSpinner size={16} />
             </span>
@@ -322,7 +333,7 @@ function FileAttachmentChip({
   readonly disabled?: boolean;
 }) {
   const isError = entry.phase === "error";
-  const isUploading = entry.phase === "uploading";
+  const isBusy = isChipBusy(entry);
 
   return (
     <span
@@ -333,12 +344,12 @@ function FileAttachmentChip({
         isError
           ? "stg:border stg:border-destructive/30 stg:bg-destructive-subtle stg:text-destructive"
           : "stg:bg-muted-subtle stg:text-foreground",
-        isUploading && "stg:opacity-70",
+        isBusy && "stg:opacity-70",
       )}
     >
-      {isUploading && <ChipSpinner />}
+      {isBusy && <ChipSpinner />}
       {isError && <ErrorDot />}
-      {!isUploading && !isError && <FileIcon />}
+      {!isBusy && !isError && <FileIcon />}
 
       <span className="stg:truncate">{entry.file.name}</span>
 

package/src/attachment/__tests__/AttachmentChipList.test.tsx

@@ -101,6 +101,18 @@ describe("AttachmentChipList — image miniature", () => {
     expect(container.querySelector("svg.stg\\:animate-spin")).toBeTruthy();
   });
 
+  it("treats the preparing phase as busy: spinner over the miniature, 'preparing' in the accessible label (#369)", async () => {
+    const preparing = entry({ id: "prep", phase: "preparing", storageKey: null });
+
+    const { container } = renderChips([preparing]);
+
+    await waitFor(() => expect(chipImage(container)).toBeTruthy());
+    expect(container.querySelector("svg.stg\\:animate-spin")).toBeTruthy();
+    expect(
+      screen.getByRole("listitem", { name: /shot\.png.*preparing/ }),
+    ).toBeTruthy();
+  });
+
   it("renders image chips preview-only: no visible filename or size text", async () => {
     const { container } = renderChips([entry()]);
 

package/src/attachment/__tests__/useAttachments.test.ts

@@ -0,0 +1,293 @@
+/**
+ * useAttachments lifecycle tests, centered on the `preparing` phase
+ * (stigmer/stigmer#369): entries must exist from the instant a
+ * prepare-flagged file is added, transition through preparation to
+ * upload, and honor the deferred-validation and cancellation contracts
+ * documented on {@link AddFilesOptions.prepareImages}.
+ */
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+
+vi.mock("../../hooks", () => ({
+  useStigmer: vi.fn(),
+}));
+vi.mock("../prepare-image.js", () => ({
+  prepareImageForVision: vi.fn(),
+}));
+
+import { useStigmer } from "../../hooks";
+import { prepareImageForVision } from "../prepare-image.js";
+import { useAttachments } from "../useAttachments.js";
+import { MAX_ATTACHMENT_BYTES } from "../attachment-utils.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((r) => {
+    resolve = r;
+  });
+  return { promise, resolve };
+}
+
+function makeFile(name: string, sizeBytes: number, type = "image/png"): File {
+  return new File([new Uint8Array(sizeBytes)], name, { type });
+}
+
+/** Wires useStigmer to an uploadAttachment mock that resolves immediately. */
+function mockStigmer() {
+  const uploadAttachment = vi
+    .fn()
+    .mockResolvedValue({ storageKey: "attachments/test/key" });
+  vi.mocked(useStigmer).mockReturnValue({
+    agentExecution: { uploadAttachment },
+  } as unknown as ReturnType<typeof useStigmer>);
+  return { uploadAttachment };
+}
+
+const prepareMock = vi.mocked(prepareImageForVision);
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// The preparing phase
+// ---------------------------------------------------------------------------
+
+describe("useAttachments — prepareImages lifecycle", () => {
+  it("shows the entry immediately in the preparing phase, gating submit", () => {
+    mockStigmer();
+    const gap = deferred<File>();
+    prepareMock.mockReturnValue(gap.promise);
+
+    const { result } = renderHook(() => useAttachments());
+
+    act(() => {
+      result.current.addFiles([makeFile("shot.png", 1024)], {
+        prepareImages: true,
+      });
+    });
+
+    expect(result.current.entries).toHaveLength(1);
+    expect(result.current.entries[0].phase).toBe("preparing");
+    expect(result.current.entries[0].file.name).toBe("shot.png");
+    expect(result.current.isPreparing).toBe(true);
+    // preparing gates exactly like uploading — the silent-drop guard.
+    expect(result.current.isUploading).toBe(true);
+    expect(result.current.allReady).toBe(false);
+  });
+
+  it("swaps to the prepared file (name, type) and proceeds to upload → ready", async () => {
+    const { uploadAttachment } = mockStigmer();
+    const gap = deferred<File>();
+    prepareMock.mockReturnValue(gap.promise);
+
+    const { result } = renderHook(() => useAttachments());
+
+    act(() => {
+      result.current.addFiles([makeFile("shot.png", 4096)], {
+        prepareImages: true,
+      });
+    });
+
+    // Preparation re-encoded to JPEG: name and MIME follow.
+    act(() => {
+      gap.resolve(makeFile("shot.jpg", 2048, "image/jpeg"));
+    });
+
+    await waitFor(() => {
+      expect(result.current.entries[0].phase).toBe("ready");
+    });
+    expect(result.current.entries[0].file.name).toBe("shot.jpg");
+    expect(result.current.entries[0].contentType).toBe("image/jpeg");
+    expect(uploadAttachment).toHaveBeenCalledTimes(1);
+    expect(result.current.toAttachmentInputs()).toEqual([
+      {
+        filename: "shot.jpg",
+        storageKey: "attachments/test/key",
+        contentType: "image/jpeg",
+      },
+    ]);
+  });
+
+  it("accepts a raw file over the size limit when preparation brings it under (the #369 paste contract)", async () => {
+    const { uploadAttachment } = mockStigmer();
+    const onValidationError = vi.fn();
+    const gap = deferred<File>();
+    prepareMock.mockReturnValue(gap.promise);
+
+    const { result } = renderHook(() =>
+      useAttachments({ onValidationError }),
+    );
+
+    // 10 MB + 1 raw screenshot — would be rejected by up-front validation.
+    act(() => {
+      result.current.addFiles(
+        [makeFile("huge-screenshot.png", MAX_ATTACHMENT_BYTES + 1)],
+        { prepareImages: true },
+      );
+    });
+    expect(result.current.entries[0].phase).toBe("preparing");
+
+    act(() => {
+      gap.resolve(makeFile("huge-screenshot.png", 512 * 1024));
+    });
+
+    await waitFor(() => {
+      expect(result.current.entries[0].phase).toBe("ready");
+    });
+    expect(onValidationError).not.toHaveBeenCalled();
+    expect(uploadAttachment).toHaveBeenCalledTimes(1);
+  });
+
+  it("removes the entry and reports via onValidationError when still oversized after preparation", async () => {
+    const { uploadAttachment } = mockStigmer();
+    const onValidationError = vi.fn();
+    const oversized = makeFile("giant.zip", MAX_ATTACHMENT_BYTES + 1, "application/zip");
+    // Non-image passthrough: preparation returns the original untouched.
+    prepareMock.mockResolvedValue(oversized);
+
+    const { result } = renderHook(() =>
+      useAttachments({ onValidationError }),
+    );
+
+    act(() => {
+      result.current.addFiles([oversized], { prepareImages: true });
+    });
+    expect(result.current.entries).toHaveLength(1);
+
+    await waitFor(() => {
+      expect(result.current.entries).toHaveLength(0);
+    });
+    expect(onValidationError).toHaveBeenCalledWith(
+      expect.stringContaining("giant.zip"),
+    );
+    expect(uploadAttachment).not.toHaveBeenCalled();
+  });
+
+  it("discards the preparation result when the entry is removed mid-preparation", async () => {
+    const { uploadAttachment } = mockStigmer();
+    const gap = deferred<File>();
+    prepareMock.mockReturnValue(gap.promise);
+
+    const { result } = renderHook(() => useAttachments());
+
+    act(() => {
+      result.current.addFiles([makeFile("shot.png", 1024)], {
+        prepareImages: true,
+      });
+    });
+    const id = result.current.entries[0].id;
+
+    act(() => {
+      result.current.removeEntry(id);
+    });
+    expect(result.current.entries).toHaveLength(0);
+
+    // Late completion must not resurrect the entry or start an upload.
+    await act(async () => {
+      gap.resolve(makeFile("shot.jpg", 512, "image/jpeg"));
+      await gap.promise;
+    });
+    expect(result.current.entries).toHaveLength(0);
+    expect(uploadAttachment).not.toHaveBeenCalled();
+  });
+
+  it("discards the preparation result on clear()", async () => {
+    const { uploadAttachment } = mockStigmer();
+    const gap = deferred<File>();
+    prepareMock.mockReturnValue(gap.promise);
+
+    const { result } = renderHook(() => useAttachments());
+
+    act(() => {
+      result.current.addFiles([makeFile("shot.png", 1024)], {
+        prepareImages: true,
+      });
+    });
+
+    act(() => {
+      result.current.clear();
+    });
+
+    await act(async () => {
+      gap.resolve(makeFile("shot.jpg", 512, "image/jpeg"));
+      await gap.promise;
+    });
+    expect(result.current.entries).toHaveLength(0);
+    expect(uploadAttachment).not.toHaveBeenCalled();
+  });
+
+  it("uniquifies the prepared name against other entries' settled names", async () => {
+    mockStigmer();
+    const gap = deferred<File>();
+    prepareMock.mockReturnValue(gap.promise);
+
+    const { result } = renderHook(() => useAttachments());
+
+    // A settled entry already owns "pasted-image.png".
+    act(() => {
+      result.current.addFiles([makeFile("pasted-image.png", 256)]);
+    });
+    // The prepared file lands on the same name.
+    act(() => {
+      result.current.addFiles([makeFile("other.png", 256)], {
+        prepareImages: true,
+      });
+    });
+    act(() => {
+      gap.resolve(makeFile("pasted-image.png", 128));
+    });
+
+    await waitFor(() => {
+      expect(result.current.entries[1].phase).toBe("ready");
+    });
+    expect(result.current.entries[1].file.name).toBe("pasted-image-2.png");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// The unflagged path — byte-identical to the pre-#369 behavior
+// ---------------------------------------------------------------------------
+
+describe("useAttachments — unflagged addFiles", () => {
+  it("never enters the preparing phase and never calls prepareImageForVision", async () => {
+    mockStigmer();
+
+    const { result } = renderHook(() => useAttachments());
+
+    act(() => {
+      result.current.addFiles([makeFile("picked.png", 1024)]);
+    });
+
+    expect(result.current.entries[0].phase).toBe("uploading");
+    expect(result.current.isPreparing).toBe(false);
+    expect(prepareMock).not.toHaveBeenCalled();
+
+    await waitFor(() => {
+      expect(result.current.entries[0].phase).toBe("ready");
+    });
+  });
+
+  it("still validates size up front and rejects without creating an entry", () => {
+    const { uploadAttachment } = mockStigmer();
+    const onValidationError = vi.fn();
+
+    const { result } = renderHook(() =>
+      useAttachments({ onValidationError }),
+    );
+
+    act(() => {
+      result.current.addFiles([
+        makeFile("too-big.png", MAX_ATTACHMENT_BYTES + 1),
+      ]);
+    });
+
+    expect(result.current.entries).toHaveLength(0);
+    expect(onValidationError).toHaveBeenCalledTimes(1);
+    expect(uploadAttachment).not.toHaveBeenCalled();
+  });
+});

package/src/attachment/index.ts

@@ -1,5 +1,6 @@
 export { useAttachments } from "./useAttachments.js";
 export type {
+  AddFilesOptions,
   AttachmentPhase,
   AttachmentEntry,
   UseAttachmentsOptions,

package/src/attachment/useAttachments.ts

@@ -12,6 +12,7 @@ import {
   uniquifyFilename,
   validateAttachmentSize,
 } from "./attachment-utils.js";
+import { prepareImageForVision } from "./prepare-image.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -20,11 +21,16 @@ import {
 /**
  * Lifecycle phase of a single attachment managed by {@link useAttachments}.
  *
+ * - `preparing` — client-side image preparation is running (see
+ *   {@link AddFilesOptions.prepareImages}); the entry exists so the UI can
+ *   show the file from the instant it was added, but no bytes have been
+ *   sent yet. Only entries added with `prepareImages` ever visit this
+ *   phase — everything else starts at `uploading`.
  * - `uploading` — bytes are being sent to the server
  * - `ready` — upload succeeded, `storageKey` is available
  * - `error` — upload failed, `error` describes the failure
  */
-export type AttachmentPhase = "uploading" | "ready" | "error";
+export type AttachmentPhase = "preparing" | "uploading" | "ready" | "error";
 
 /**
  * State for a single file being managed by the hook.
@@ -50,7 +56,12 @@ export type AttachmentPhase = "uploading" | "ready" | "error";
 export interface AttachmentEntry {
   /** Unique client-side identifier for this attachment. */
   readonly id: string;
-  /** The original `File` object selected by the user. */
+  /**
+   * The `File` object backing this attachment. For entries added with
+   * {@link AddFilesOptions.prepareImages} this starts as the user's
+   * original file and swaps to the prepared file (possibly smaller, with
+   * a matching extension/MIME change) when the `preparing` phase ends.
+   */
   readonly file: File;
   /** Current upload lifecycle phase. */
   readonly phase: AttachmentPhase;
@@ -71,25 +82,59 @@ export interface UseAttachmentsOptions {
   readonly onValidationError?: (message: string) => void;
 }
 
+/** Per-call options for {@link UseAttachmentsReturn.addFiles}. */
+export interface AddFilesOptions {
+  /**
+   * Bound image files to provider vision resolution before upload (via
+   * {@link prepareImageForVision}) — the paste-to-attach treatment
+   * (stigmer/stigmer#284). Each file's entry appears immediately in the
+   * `preparing` phase, so a large screenshot shows a chip the instant it
+   * is pasted instead of after the 150-350 ms decode/downscale/re-encode
+   * (stigmer/stigmer#369). Non-image files pass through preparation
+   * untouched.
+   *
+   * Meant for pasted content only: a picked or dragged file may be the
+   * subject of the task ("read the EXIF"), and silently re-encoding it
+   * would be a regression — see prepare-image.ts for the doctrine.
+   *
+   * With this flag, size validation runs against the PREPARED bytes (the
+   * bytes that actually upload), so an oversized paste that downscales
+   * under the limit is accepted — identical to preparing before calling
+   * `addFiles`, which is what this option replaces. A file still
+   * oversized after preparation is removed and reported via
+   * `onValidationError`.
+   */
+  readonly prepareImages?: boolean;
+}
+
 /** Return value of {@link useAttachments}. */
 export interface UseAttachmentsReturn {
-  /** Current attachment entries (uploading, ready, or errored). */
+  /** Current attachment entries (preparing, uploading, ready, or errored). */
   readonly entries: readonly AttachmentEntry[];
-  /** True when at least one entry is in the `"uploading"` phase. */
+  /**
+   * True while any entry has work in flight (`preparing` or
+   * `uploading`). This is the submit gate: `toAttachmentInputs()` carries
+   * only `ready` entries, so a send while this is true would silently
+   * drop the file the user just added.
+   */
   readonly isUploading: boolean;
+  /** True when at least one entry is in the `"preparing"` phase. */
+  readonly isPreparing: boolean;
   /** Number of entries that are ready for submission. */
   readonly readyCount: number;
-  /** True when there are entries and all are ready (none uploading or errored). */
+  /** True when there are entries and all are ready (none preparing, uploading, or errored). */
   readonly allReady: boolean;
   /** True when there is at least one entry (in any phase). */
   readonly hasEntries: boolean;
   /**
    * Add one or more files. Each file is validated and uploaded
    * immediately. Invalid files (e.g., too large) are rejected via
-   * `onValidationError` and not added.
+   * `onValidationError` and not added. With
+   * {@link AddFilesOptions.prepareImages}, images are bounded to vision
+   * resolution first — entries appear at once in the `preparing` phase.
    */
-  readonly addFiles: (files: FileList | File[]) => void;
-  /** Remove an entry by its stable ID. Aborts in-flight uploads. */
+  readonly addFiles: (files: FileList | File[], addOptions?: AddFilesOptions) => void;
+  /** Remove an entry by its stable ID. Aborts in-flight preparation and uploads. */
   readonly removeEntry: (id: string) => void;
   /** Retry a failed upload. */
   readonly retryEntry: (id: string) => void;
@@ -220,13 +265,92 @@ export function useAttachments(
     [stigmer],
   );
 
+  // The `preparing` half of the lifecycle (AddFilesOptions.prepareImages):
+  // runs prepareImageForVision on the raw file, then hands the result to
+  // the normal validate → uniquify → upload sequence. The entry already
+  // exists (created by addFiles in the `preparing` phase), so this
+  // transitions it rather than creating it.
+  const prepareEntry = useCallback(
+    async (id: string, rawFile: File) => {
+      // Registered under the same id the upload path uses, so removeEntry
+      // and clear() cancel a preparation exactly like an upload. The
+      // signal is only ever read, never passed down — prepareImageForVision
+      // never throws and cannot be interrupted; cancellation means
+      // discarding its result.
+      const controller = new AbortController();
+      abortControllers.current.set(id, controller);
+
+      const prepared = await prepareImageForVision(rawFile);
+      if (controller.signal.aborted) return;
+      // Hand-off point: from here the upload path owns the map slot
+      // (uploadFile registers its own controller under this id).
+      abortControllers.current.delete(id);
+
+      // Deferred validation — deliberately on the PREPARED bytes, the
+      // bytes that actually upload: a 12 MB screenshot that downscales
+      // under the limit must pass, exactly as it did when callers
+      // prepared before calling addFiles. Rejection removes the chip the
+      // user has been watching, so the toast is the explanation.
+      const sizeError = validateAttachmentSize(prepared);
+      if (sizeError) {
+        setEntries((prev) => prev.filter((e) => e.id !== id));
+        options?.onValidationError?.(sizeError);
+        return;
+      }
+
+      // Preparation may rename (extension follows the re-encode format),
+      // so uniquify now, against every OTHER entry's settled name —
+      // same downstream-breakage rule as the un-prepared path.
+      const takenNames = new Set(
+        entriesRef.current.filter((e) => e.id !== id).map((e) => e.file.name),
+      );
+      const uniqueName = uniquifyFilename(prepared.name, takenNames);
+      const file =
+        uniqueName === prepared.name
+          ? prepared
+          : new File([prepared], uniqueName, {
+              type: prepared.type,
+              lastModified: prepared.lastModified,
+            });
+      const contentType = detectContentType(file);
+
+      setEntries((prev) =>
+        prev.map((e) =>
+          e.id === id
+            ? { ...e, file, contentType, phase: "uploading" as const }
+            : e,
+        ),
+      );
+      uploadFile(id, file, contentType);
+    },
+    [options, uploadFile],
+  );
+
   const addFiles = useCallback(
-    (files: FileList | File[]) => {
+    (files: FileList | File[], addOptions?: AddFilesOptions) => {
       const fileArray = Array.from(files);
       const validEntries: AttachmentEntry[] = [];
       const takenNames = new Set(entriesRef.current.map((e) => e.file.name));
 
       for (const rawFile of fileArray) {
+        if (addOptions?.prepareImages) {
+          // The entry must exist THIS tick — the whole point of the
+          // preparing phase is feedback during the decode/downscale gap.
+          // Size validation and name uniquification move to prepareEntry:
+          // both depend on the prepared file (final bytes, final name).
+          const id = generateId();
+          validEntries.push({
+            id,
+            file: rawFile,
+            phase: "preparing",
+            contentType: detectContentType(rawFile),
+            storageKey: null,
+            error: null,
+          });
+          void prepareEntry(id, rawFile);
+          continue;
+        }
+
         const sizeError = validateAttachmentSize(rawFile);
         if (sizeError) {
           options?.onValidationError?.(sizeError);
@@ -266,7 +390,7 @@ export function useAttachments(
         setEntries((prev) => [...prev, ...validEntries]);
       }
     },
-    [options, uploadFile],
+    [options, uploadFile, prepareEntry],
   );
 
   const removeEntry = useCallback((id: string) => {
@@ -317,7 +441,14 @@ export function useAttachments(
       }));
   }, [entries]);
 
-  const isUploading = entries.some((e) => e.phase === "uploading");
+  const isPreparing = entries.some((e) => e.phase === "preparing");
+  // `preparing` counts as uploading-in-the-gate sense: both phases mean
+  // "this file will be lost if the message sends now" (see the
+  // isUploading doc). Hosts that gate submit on isUploading inherit the
+  // preparing gate without a code change.
+  const isUploading = entries.some(
+    (e) => e.phase === "preparing" || e.phase === "uploading",
+  );
   const readyCount = entries.filter((e) => e.phase === "ready").length;
   const hasEntries = entries.length > 0;
   const allReady = hasEntries && readyCount === entries.length;
@@ -325,6 +456,7 @@ export function useAttachments(
   return {
     entries,
     isUploading,
+    isPreparing,
     readyCount,
     allReady,
     hasEntries,