@stigmer/react 3.8.0 → 3.10.0

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

@@ -0,0 +1,326 @@
+import { describe, it, expect, vi, beforeAll, afterEach } from "vitest";
+import {
+  render,
+  cleanup,
+  waitFor,
+  fireEvent,
+  screen,
+} from "@testing-library/react";
+import { AttachmentChipList } from "../AttachmentChipList.js";
+import type { AttachmentChipListProps } from "../AttachmentChipList.js";
+import type { AttachmentEntry } from "../useAttachments.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function entry(overrides: Partial<AttachmentEntry> = {}): AttachmentEntry {
+  return {
+    id: overrides.id ?? "entry-1",
+    file:
+      overrides.file ??
+      new File([new Uint8Array([0x89, 0x50, 0x4e, 0x47])], "shot.png", {
+        type: "image/png",
+      }),
+    phase: overrides.phase ?? "ready",
+    contentType: overrides.contentType ?? "image/png",
+    storageKey: overrides.storageKey ?? "attachments/test/shot.png",
+    error: overrides.error ?? null,
+  };
+}
+
+function renderChips(
+  entries: AttachmentEntry[],
+  props: Partial<AttachmentChipListProps> = {},
+) {
+  return render(
+    <AttachmentChipList
+      entries={entries}
+      onRemove={vi.fn()}
+      onRetry={vi.fn()}
+      {...props}
+    />,
+  );
+}
+
+/** The chip's miniature `<img>` (decorative, `aria-hidden`) — never the lightbox image. */
+function chipImage(container: HTMLElement): HTMLImageElement | null {
+  return container.querySelector('img[aria-hidden="true"]');
+}
+
+// happy-dom does not implement the native dialog show/close methods.
+beforeAll(() => {
+  HTMLDialogElement.prototype.showModal = function showModal() {
+    this.open = true;
+  };
+  HTMLDialogElement.prototype.close = function close() {
+    this.open = false;
+  };
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// Image miniature — visible in every phase (#371 gap 2)
+// ---------------------------------------------------------------------------
+
+describe("AttachmentChipList — image miniature", () => {
+  it("renders an object-URL miniature for a ready image entry", async () => {
+    const { container } = renderChips([entry()]);
+
+    await waitFor(() => {
+      const img = chipImage(container);
+      expect(img).toBeTruthy();
+      expect(img!.getAttribute("src")).toContain("blob:");
+      expect(img!.getAttribute("alt")).toBe("");
+    });
+  });
+
+  it("keeps the generic file icon for non-image entries", () => {
+    const md = entry({
+      file: new File(["# notes"], "notes.md", { type: "text/markdown" }),
+      contentType: "text/markdown",
+    });
+
+    const { container } = renderChips([md]);
+
+    expect(container.querySelector("img")).toBeNull();
+    expect(container.querySelector("svg")).toBeTruthy();
+  });
+
+  it("keeps the miniature visible while uploading — the spinner overlays it, never replaces it", async () => {
+    const uploading = entry({ id: "up", phase: "uploading", storageKey: null });
+
+    const { container } = renderChips([uploading]);
+
+    await waitFor(() => expect(chipImage(container)).toBeTruthy());
+    // Spinner present alongside the image, not instead of it.
+    expect(container.querySelector("svg.animate-spin")).toBeTruthy();
+  });
+
+  it("renders image chips preview-only: no visible filename or size text", async () => {
+    const { container } = renderChips([entry()]);
+
+    await waitFor(() => expect(chipImage(container)).toBeTruthy());
+
+    // The tile is the chip — the name lives in the tooltip and accessible
+    // label, never as a text node (file chips, by contrast, keep theirs).
+    expect(screen.queryByText("shot.png")).toBeNull();
+    const tile = screen.getByRole("listitem", { name: /^shot\.png/ });
+    expect(tile.getAttribute("title")).toBe("shot.png");
+    // Remove is an always-visible corner badge, not hover-revealed.
+    expect(screen.getByRole("button", { name: "Remove shot.png" })).toBeTruthy();
+  });
+
+  it("keeps visible filename and size text on non-image chips", () => {
+    const md = entry({
+      file: new File(["# notes"], "notes.md", { type: "text/markdown" }),
+      contentType: "text/markdown",
+    });
+
+    renderChips([md]);
+
+    expect(screen.getByText("notes.md")).toBeTruthy();
+  });
+
+  it("keeps the miniature visible on upload error, alongside the retry action", async () => {
+    const errored = entry({
+      id: "err",
+      phase: "error",
+      error: "boom",
+      storageKey: null,
+    });
+
+    const { container } = renderChips([errored]);
+
+    await waitFor(() => expect(chipImage(container)).toBeTruthy());
+    expect(
+      screen.getByRole("button", { name: "Retry uploading shot.png" }),
+    ).toBeTruthy();
+  });
+
+  it("revokes the object URL on unmount", async () => {
+    const revokeSpy = vi.spyOn(URL, "revokeObjectURL");
+    const { container, unmount } = renderChips([entry()]);
+
+    await waitFor(() => expect(chipImage(container)).toBeTruthy());
+    const src = chipImage(container)!.getAttribute("src")!;
+
+    unmount();
+
+    expect(revokeSpy).toHaveBeenCalledWith(src);
+  });
+
+  it("revokes the object URL when the entry is removed from the list", async () => {
+    const revokeSpy = vi.spyOn(URL, "revokeObjectURL");
+    const image = entry();
+    const { container, rerender } = render(
+      <AttachmentChipList entries={[image]} onRemove={vi.fn()} onRetry={vi.fn()} />,
+    );
+
+    await waitFor(() => expect(chipImage(container)).toBeTruthy());
+    const src = chipImage(container)!.getAttribute("src")!;
+
+    rerender(
+      <AttachmentChipList entries={[]} onRemove={vi.fn()} onRetry={vi.fn()} />,
+    );
+
+    expect(container.querySelector("img")).toBeNull();
+    expect(revokeSpy).toHaveBeenCalledWith(src);
+  });
+
+  it("degrades to the compact file chip when the image fails to decode", async () => {
+    const { container } = renderChips([entry()]);
+
+    await waitFor(() => expect(chipImage(container)).toBeTruthy());
+    fireEvent.error(chipImage(container)!);
+
+    // No broken-image glyph, no preview affordance — just the file treatment.
+    expect(container.querySelector("img")).toBeNull();
+    expect(screen.queryByRole("button", { name: "Preview shot.png" })).toBeNull();
+    expect(container.querySelector("svg")).toBeTruthy();
+    expect(
+      screen.getByRole("button", { name: "Remove shot.png" }),
+    ).toBeTruthy();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Click-to-open — built-in lightbox and the onPreview seam (#371 gap 3)
+// ---------------------------------------------------------------------------
+
+describe("AttachmentChipList — preview", () => {
+  it("opens the built-in lightbox with the full image when the chip body is clicked", async () => {
+    renderChips([entry()]);
+
+    expect(document.querySelector("dialog")).toBeNull();
+
+    fireEvent.click(screen.getByRole("button", { name: "Preview shot.png" }));
+
+    const dialog = document.querySelector("dialog");
+    expect(dialog).toBeTruthy();
+    expect(dialog!.getAttribute("aria-label")).toBe("Preview shot.png");
+    // The lightbox derives its own object URL; the full image carries the
+    // filename as meaningful alt text (unlike the decorative miniature).
+    await waitFor(() => {
+      const full = dialog!.querySelector("img");
+      expect(full).toBeTruthy();
+      expect(full!.getAttribute("src")).toContain("blob:");
+      expect(full!.getAttribute("alt")).toBe("shot.png");
+    });
+  });
+
+  it("closes the lightbox on Escape (the dialog's cancel event)", () => {
+    renderChips([entry()]);
+
+    fireEvent.click(screen.getByRole("button", { name: "Preview shot.png" }));
+    const dialog = document.querySelector("dialog")!;
+
+    fireEvent(dialog, new Event("cancel"));
+
+    expect(document.querySelector("dialog")).toBeNull();
+  });
+
+  it("closes the lightbox on backdrop click, but not on content clicks", async () => {
+    renderChips([entry()]);
+
+    fireEvent.click(screen.getByRole("button", { name: "Preview shot.png" }));
+    const dialog = document.querySelector("dialog")!;
+    await waitFor(() => expect(dialog.querySelector("img")).toBeTruthy());
+
+    // A click landing on content (the image) must not close.
+    fireEvent.click(dialog.querySelector("img")!);
+    expect(document.querySelector("dialog")).toBeTruthy();
+
+    // A click landing on the dialog element itself is the backdrop.
+    fireEvent.click(dialog);
+    expect(document.querySelector("dialog")).toBeNull();
+  });
+
+  it("closes the lightbox via its close button", () => {
+    renderChips([entry()]);
+
+    fireEvent.click(screen.getByRole("button", { name: "Preview shot.png" }));
+    fireEvent.click(
+      screen.getByRole("button", { name: "Close image preview" }),
+    );
+
+    expect(document.querySelector("dialog")).toBeNull();
+  });
+
+  it("closes the lightbox when the previewed entry is removed from the list", () => {
+    const image = entry();
+    const { rerender } = renderChips([image]);
+
+    fireEvent.click(screen.getByRole("button", { name: "Preview shot.png" }));
+    expect(document.querySelector("dialog")).toBeTruthy();
+
+    rerender(
+      <AttachmentChipList entries={[]} onRemove={vi.fn()} onRetry={vi.fn()} />,
+    );
+
+    expect(document.querySelector("dialog")).toBeNull();
+  });
+
+  it("routes the click to onPreview instead of opening the built-in lightbox", () => {
+    const onPreview = vi.fn();
+    const image = entry();
+    renderChips([image], { onPreview });
+
+    fireEvent.click(screen.getByRole("button", { name: "Preview shot.png" }));
+
+    expect(onPreview).toHaveBeenCalledTimes(1);
+    expect(onPreview).toHaveBeenCalledWith(image);
+    expect(document.querySelector("dialog")).toBeNull();
+  });
+
+  it("offers no preview affordance on non-image entries", () => {
+    const md = entry({
+      file: new File(["# notes"], "notes.md", { type: "text/markdown" }),
+      contentType: "text/markdown",
+    });
+
+    renderChips([md]);
+
+    expect(screen.queryByRole("button", { name: /^Preview/ })).toBeNull();
+  });
+
+  it("keeps preview clickable while remove/retry are disabled (preview is read-only)", async () => {
+    const { container } = renderChips([entry()], { disabled: true });
+
+    await waitFor(() => expect(chipImage(container)).toBeTruthy());
+
+    const preview = screen.getByRole("button", {
+      name: "Preview shot.png",
+    }) as HTMLButtonElement;
+    const remove = screen.getByRole("button", {
+      name: "Remove shot.png",
+    }) as HTMLButtonElement;
+
+    expect(preview.disabled).toBe(false);
+    expect(remove.disabled).toBe(true);
+
+    fireEvent.click(preview);
+    expect(document.querySelector("dialog")).toBeTruthy();
+  });
+
+  it("handles unicode filenames across the chip, preview target, and lightbox", () => {
+    const name = "スクリーンショット 2026-08-10.png";
+    const unicode = entry({
+      file: new File([new Uint8Array([0x89, 0x50, 0x4e, 0x47])], name, {
+        type: "image/png",
+      }),
+    });
+
+    renderChips([unicode]);
+
+    fireEvent.click(screen.getByRole("button", { name: `Preview ${name}` }));
+
+    const dialog = document.querySelector("dialog");
+    expect(dialog).toBeTruthy();
+    expect(dialog!.getAttribute("aria-label")).toBe(`Preview ${name}`);
+  });
+});

package/src/attachment/__tests__/attachment-utils.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from "vitest";
+import { uniquifyFilename } from "../attachment-utils.js";
+
+describe("uniquifyFilename", () => {
+  const cases: Array<{
+    scenario: string;
+    name: string;
+    taken: string[];
+    expected: string;
+  }> = [
+    {
+      scenario: "returns the name unchanged when nothing collides",
+      name: "report.pdf",
+      taken: [],
+      expected: "report.pdf",
+    },
+    {
+      scenario: "suffixes -2 before the extension on first collision",
+      name: "report.pdf",
+      taken: ["report.pdf"],
+      expected: "report-2.pdf",
+    },
+    {
+      scenario: "walks past already-taken suffixes",
+      name: "report.pdf",
+      taken: ["report.pdf", "report-2.pdf", "report-3.pdf"],
+      expected: "report-4.pdf",
+    },
+    {
+      scenario: "handles names without an extension",
+      name: "Makefile",
+      taken: ["Makefile"],
+      expected: "Makefile-2",
+    },
+    {
+      scenario: "treats a leading dot as a hidden-file prefix, not an extension",
+      name: ".env",
+      taken: [".env"],
+      expected: ".env-2",
+    },
+    {
+      scenario: "only splits on the last dot of a multi-dot name",
+      name: "backup.tar.gz",
+      taken: ["backup.tar.gz"],
+      expected: "backup.tar-2.gz",
+    },
+  ];
+
+  for (const { scenario, name, taken, expected } of cases) {
+    it(scenario, () => {
+      expect(uniquifyFilename(name, new Set(taken))).toBe(expected);
+    });
+  }
+});

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

@@ -0,0 +1,110 @@
+import { describe, it, expect } from "vitest";
+import { extractClipboardFiles } from "../clipboard.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * The function only reads `clipboardData.files` as an array-like, so a
+ * plain array cast to FileList is a faithful stand-in (same pattern as the
+ * composer fileref tests).
+ */
+function clipboardEventWith(files: File[]): { clipboardData: { files: FileList } } {
+  return { clipboardData: { files: files as unknown as FileList } };
+}
+
+function imageFile(name: string, type = "image/png"): File {
+  return new File([new Uint8Array([0x89, 0x50, 0x4e, 0x47])], name, { type });
+}
+
+const SYNTHESIZED_NAME = /^pasted-image-\d{6}-\d+\.[a-z]+$/;
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("extractClipboardFiles", () => {
+  it("returns an empty array for a text-only paste (null clipboardData)", () => {
+    expect(extractClipboardFiles({ clipboardData: null })).toEqual([]);
+  });
+
+  it("returns an empty array when the clipboard carries no files", () => {
+    expect(extractClipboardFiles(clipboardEventWith([]))).toEqual([]);
+  });
+
+  it("renames the browser's generic image.png to a synthesized name", () => {
+    const [file] = extractClipboardFiles(clipboardEventWith([imageFile("image.png")]));
+
+    expect(file.name).toMatch(SYNTHESIZED_NAME);
+    expect(file.name.endsWith(".png")).toBe(true);
+    expect(file.type).toBe("image/png");
+  });
+
+  it("renames generic names for every image flavor browsers produce", () => {
+    const cases: Array<[string, string, string]> = [
+      ["image.jpg", "image/jpeg", ".jpg"],
+      ["image.jpeg", "image/jpeg", ".jpg"],
+      ["image.gif", "image/gif", ".gif"],
+      ["image.webp", "image/webp", ".webp"],
+      ["image.tiff", "image/tiff", ".tiff"],
+      ["IMAGE.PNG", "image/png", ".png"],
+      // Empty name with an image MIME (some WebKit paste payloads).
+      ["", "image/png", ".png"],
+    ];
+
+    for (const [name, type, expectedExt] of cases) {
+      const [file] = extractClipboardFiles(clipboardEventWith([imageFile(name, type)]));
+      expect(file.name, `input name '${name}'`).toMatch(SYNTHESIZED_NAME);
+      expect(file.name.endsWith(expectedExt), `'${file.name}' should end with ${expectedExt}`).toBe(true);
+    }
+  });
+
+  it("gives two images pasted together distinct names", () => {
+    const files = extractClipboardFiles(
+      clipboardEventWith([imageFile("image.png"), imageFile("image.png")]),
+    );
+
+    expect(files).toHaveLength(2);
+    expect(files[0].name).not.toBe(files[1].name);
+  });
+
+  it("gives images from separate pastes distinct names (session inputs/ dir accumulates)", () => {
+    const [first] = extractClipboardFiles(clipboardEventWith([imageFile("image.png")]));
+    const [second] = extractClipboardFiles(clipboardEventWith([imageFile("image.png")]));
+
+    expect(first.name).not.toBe(second.name);
+  });
+
+  it("keeps the real name of a file pasted from a file manager", () => {
+    const [file] = extractClipboardFiles(
+      clipboardEventWith([imageFile("architecture-sketch.png")]),
+    );
+
+    expect(file.name).toBe("architecture-sketch.png");
+  });
+
+  it("does not rename a non-image file even when named image.png", () => {
+    const pdf = new File([new Uint8Array([0x25, 0x50])], "image.png", {
+      type: "application/pdf",
+    });
+
+    const [file] = extractClipboardFiles(clipboardEventWith([pdf]));
+    expect(file.name).toBe("image.png");
+  });
+
+  it("preserves bytes and metadata across a rename", async () => {
+    const original = new File([new Uint8Array([1, 2, 3, 4])], "image.png", {
+      type: "image/png",
+      lastModified: 1723200000000,
+    });
+
+    const [renamed] = extractClipboardFiles(clipboardEventWith([original]));
+
+    expect(renamed.type).toBe("image/png");
+    expect(renamed.lastModified).toBe(1723200000000);
+    expect(new Uint8Array(await renamed.arrayBuffer())).toEqual(
+      new Uint8Array([1, 2, 3, 4]),
+    );
+  });
+});

package/src/attachment/__tests__/prepare-image.browser.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect } from "vitest";
+import { prepareImageForVision } from "../prepare-image.js";
+import { fitToVisionResolution } from "../vision-fit.js";
+
+/**
+ * Real-Chromium half of the prepare-image coverage: decode, resize, and
+ * encode against an actual rendering engine (happy-dom has no canvas 2D
+ * or createImageBitmap — see prepare-image.test.ts for the guard rails).
+ */
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeCanvas(width: number, height: number): [HTMLCanvasElement, CanvasRenderingContext2D] {
+  const canvas = document.createElement("canvas");
+  canvas.width = width;
+  canvas.height = height;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("test environment must provide a 2D context");
+  return [canvas, ctx];
+}
+
+/** Flat fills and text — the compressible content of a UI screenshot. */
+function drawUiLike(ctx: CanvasRenderingContext2D, width: number, height: number) {
+  ctx.fillStyle = "#f5f5f5";
+  ctx.fillRect(0, 0, width, height);
+  ctx.fillStyle = "#3355aa";
+  ctx.fillRect(40, 40, width / 2, 120);
+  ctx.fillStyle = "#111111";
+  ctx.font = "24px sans-serif";
+  for (let y = 220; y < height - 40; y += 48) {
+    ctx.fillText("Error: connection refused at line 42 — retry failed", 48, y);
+  }
+}
+
+/** Per-pixel noise — the least-compressible content a photo can approach. */
+function drawNoise(ctx: CanvasRenderingContext2D, width: number, height: number) {
+  const imageData = ctx.createImageData(width, height);
+  const data = imageData.data;
+  for (let i = 0; i < data.length; i += 4) {
+    data[i] = Math.floor(Math.random() * 256);
+    data[i + 1] = Math.floor(Math.random() * 256);
+    data[i + 2] = Math.floor(Math.random() * 256);
+    data[i + 3] = 255;
+  }
+  ctx.putImageData(imageData, 0, 0);
+}
+
+async function fileFromCanvas(
+  canvas: HTMLCanvasElement,
+  name: string,
+  type: string,
+): Promise<File> {
+  const blob = await new Promise<Blob | null>((resolve) => canvas.toBlob(resolve, type));
+  if (!blob) throw new Error(`canvas could not encode ${type}`);
+  return new File([blob], name, { type });
+}
+
+async function imageFile(
+  width: number,
+  height: number,
+  name: string,
+  type: string,
+  draw: (ctx: CanvasRenderingContext2D, w: number, h: number) => void = drawUiLike,
+): Promise<File> {
+  const [canvas, ctx] = makeCanvas(width, height);
+  draw(ctx, width, height);
+  return fileFromCanvas(canvas, name, type);
+}
+
+async function decodedSize(file: File): Promise<{ width: number; height: number }> {
+  const bitmap = await createImageBitmap(file);
+  const size = { width: bitmap.width, height: bitmap.height };
+  bitmap.close();
+  return size;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("prepareImageForVision — real pixel pipeline", () => {
+  it("resizes an oversized PNG screenshot to the fitted resolution, staying PNG", async () => {
+    const input = await imageFile(3000, 2000, "screenshot.png", "image/png");
+    const expected = fitToVisionResolution(3000, 2000);
+
+    const prepared = await prepareImageForVision(input);
+
+    expect(prepared).not.toBe(input);
+    expect(prepared.type).toBe("image/png");
+    expect(prepared.name).toBe("screenshot.png");
+    expect(prepared.size).toBeLessThan(input.size);
+    expect(prepared.lastModified).toBe(input.lastModified);
+    await expect(decodedSize(prepared)).resolves.toEqual(expected);
+  });
+
+  it("passes a within-limits PNG through byte-identical (no generation loss on re-edit)", async () => {
+    const input = await imageFile(400, 300, "small.png", "image/png");
+
+    const prepared = await prepareImageForVision(input);
+
+    expect(prepared).toBe(input);
+  });
+
+  it("passes a within-limits JPEG through byte-identical", async () => {
+    const input = await imageFile(640, 480, "photo.jpg", "image/jpeg");
+
+    const prepared = await prepareImageForVision(input);
+
+    expect(prepared).toBe(input);
+  });
+
+  it("keeps JPEG format when resizing a JPEG source", async () => {
+    const input = await imageFile(4000, 3000, "camera.jpg", "image/jpeg");
+    const expected = fitToVisionResolution(4000, 3000);
+
+    const prepared = await prepareImageForVision(input);
+
+    expect(prepared.type).toBe("image/jpeg");
+    expect(prepared.name).toBe("camera.jpg");
+    await expect(decodedSize(prepared)).resolves.toEqual(expected);
+  });
+
+  it("re-encodes a within-limits WebP to PNG so the Cursor harness can display it", async () => {
+    const input = await imageFile(800, 600, "clip.webp", "image/webp");
+
+    const prepared = await prepareImageForVision(input);
+
+    expect(prepared).not.toBe(input);
+    expect(prepared.type).toBe("image/png");
+    expect(prepared.name).toBe("clip.png");
+    // Format normalization only — the dimensions stay untouched.
+    await expect(decodedSize(prepared)).resolves.toEqual({ width: 800, height: 600 });
+  });
+
+  it("keeps worst-case photographic content under the runner's inline byte cap", async () => {
+    // Evidence gate from the T05 plan. Pure noise is the least-compressible
+    // content an image can carry; at the fitted resolution a noise PNG
+    // encodes to ~3.4 MB — over the runner's per-image inline cap — which
+    // is exactly what the PNG-density JPEG fallback exists to catch.
+    // The cap constant mirrors MAX_VISION_IMAGE_BYTES in the runner's
+    // shared/attachment-vision.ts (a measurement bound in a test, never a
+    // production dependency).
+    const RUNNER_INLINE_IMAGE_CAP = 3 * 1024 * 1024;
+
+    const input = await imageFile(3000, 2000, "photo.png", "image/png", drawNoise);
+
+    const prepared = await prepareImageForVision(input);
+
+    expect(prepared.size).toBeLessThan(RUNNER_INLINE_IMAGE_CAP);
+    // Noise defeats PNG, so the ratio rule must have picked JPEG.
+    expect(prepared.type).toBe("image/jpeg");
+    expect(prepared.name).toBe("photo.jpg");
+  });
+
+  it("prefers PNG for UI-like content even though JPEG is available", async () => {
+    const input = await imageFile(3000, 2000, "dialog.png", "image/png", drawUiLike);
+
+    const prepared = await prepareImageForVision(input);
+
+    // Flat fills and text compress better in PNG than JPEG-at-half-size,
+    // and PNG keeps UI text crisp — the ratio rule must keep PNG here.
+    expect(prepared.type).toBe("image/png");
+  });
+});

package/src/attachment/__tests__/prepare-image.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from "vitest";
+import { prepareImageForVision } from "../prepare-image.js";
+
+/**
+ * happy-dom half of the prepare-image coverage: the guard rails that make
+ * the function safe to call from any environment. The actual pixel work
+ * (decode, resize, encode) runs in real Chromium — see
+ * prepare-image.browser.test.ts.
+ */
+describe("prepareImageForVision — environment guard rails", () => {
+  it("returns a non-image file untouched (same instance)", async () => {
+    const pdf = new File([new Uint8Array([0x25, 0x50, 0x44, 0x46])], "brief.pdf", {
+      type: "application/pdf",
+    });
+
+    await expect(prepareImageForVision(pdf)).resolves.toBe(pdf);
+  });
+
+  it("returns an image untouched when the canvas pipeline is unavailable", async () => {
+    // happy-dom has no createImageBitmap — the exact situation of an old
+    // browser or a privacy extension that blocks canvas. The paste must
+    // still work end to end with the original bytes; it merely degrades
+    // at the runner with the standard disclosure.
+    expect(typeof createImageBitmap).toBe("undefined");
+
+    const png = new File([new Uint8Array([0x89, 0x50, 0x4e, 0x47])], "shot.png", {
+      type: "image/png",
+    });
+
+    await expect(prepareImageForVision(png)).resolves.toBe(png);
+  });
+});