fix(api): make pixelate actually pixelate (#709)

Sharp keeps one set of resize options per pipeline, so the chained shrink-then-grow collapsed into a single resize back to the original size and both the full-image and region paths returned the input untouched.

Run the two resizes as separate pipelines, pinned to fit: "fill" so a skewed block grid cannot crop the picture.

Also in this change:
- stop passing quality to the PNG encoder, which Sharp reads as "quantise to a palette" and which dithered the flat blocks and inflated the file
- replace the region instead of blending into it, so a part-transparent image no longer shows the original through the mosaic
- throw on unreadable dimensions rather than falling back to a 1x1 image

Five new integration tests on content-bearing fixtures, each verified against a deliberate mutant.

Fixes #678

apps/api/src/routes/tools/pixelate.ts

@@ -1,5 +1,5 @@
 import type { FastifyInstance } from "fastify";
-import sharp from "sharp";
+import sharp, { type Sharp } from "sharp";
 import { z } from "zod";
 import { resolveOutputFormat } from "../../lib/output-format.js";
 import { InputValidationError } from "../../modality/contract.js";
@@ -17,17 +17,60 @@ const settingsSchema = z.object({
     .optional(),
 });
 
+/**
+ * Shrink to one pixel per block, then blow it back up with nearest-neighbour.
+ *
+ * The two resizes have to run as separate pipelines. Sharp holds a single set
+ * of resize options per pipeline, so chaining them lets the second call
+ * replace the first and the image comes back untouched (issue #678).
+ *
+ * `fit: "fill"` pins both steps to exact dimensions; the default `cover` would
+ * crop whenever the block grid does not divide the image evenly.
+ */
+async function mosaic(
+  source: Sharp,
+  width: number,
+  height: number,
+  blockSize: number,
+): Promise<Buffer> {
+  const cols = Math.max(1, Math.round(width / blockSize));
+  const rows = Math.max(1, Math.round(height / blockSize));
+
+  // The shrink resamples with the default kernel, so a block's colour is drawn
+  // from the region it covers rather than one sampled pixel. Nearest-neighbour
+  // on the way back up is what keeps the block edges hard.
+  const shrunk = await source.resize(cols, rows, { fit: "fill" }).png().toBuffer();
+
+  return sharp(shrunk)
+    .resize(width, height, { fit: "fill", kernel: sharp.kernel.nearest })
+    .png()
+    .toBuffer();
+}
+
+/** A fully opaque rectangle, used as a stencil to clear the region being replaced. */
+function opaqueRect(width: number, height: number): Promise<Buffer> {
+  return sharp({
+    create: { width, height, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 1 } },
+  })
+    .png()
+    .toBuffer();
+}
+
 export function registerPixelate(app: FastifyInstance) {
   createToolRoute(app, {
     toolId: "pixelate",
     settingsSchema,
     process: async (inputBuffer, settings, filename) => {
       const meta = await sharp(inputBuffer).metadata();
-      const w = meta.width ?? 1;
+      if (!meta.width || !meta.height) {
-      const h = meta.height ?? 1;
+        // Defaulting to 1x1 here would hand back a one-pixel image with a 200.
+        throw new InputValidationError("Could not read image dimensions");
+      }
+      const w = meta.width;
+      const h = meta.height;
       const bs = settings.blockSize;
 
-      let buf: Buffer;
+      let pixelated: Sharp;
 
       if (settings.region) {
         // Reject if origin is completely outside image bounds
@@ -43,34 +86,34 @@ export function registerPixelate(app: FastifyInstance) {
           height: Math.min(settings.region.height, h - settings.region.top),
         };
 
-        // Extract region, pixelate it, composite back
+        const region = await mosaic(sharp(inputBuffer).extract(r), r.width, r.height, bs);
-        const rw = Math.max(1, Math.round(r.width / bs));
-        const rh = Math.max(1, Math.round(r.height / bs));
 
-        const pixelatedRegion = await sharp(inputBuffer)
+        // The mosaic has to REPLACE the region, not blend into it. Compositing
-          .extract({ left: r.left, top: r.top, width: r.width, height: r.height })
+        // straight over means any block whose averaged alpha is below 255 lets
-          .resize(rw, rh, { kernel: sharp.kernel.nearest })
+        // the original show through, so a partly transparent image keeps the
-          .resize(r.width, r.height, { kernel: sharp.kernel.nearest })
+        // detail the user asked to hide. Punching the region out with an opaque
-          .toBuffer();
+        // rectangle first leaves nothing underneath to bleed back in.
-
+        pixelated = sharp(inputBuffer)
-        buf = await sharp(inputBuffer)
+          .ensureAlpha()
-          .composite([{ input: pixelatedRegion, left: r.left, top: r.top }])
+          .composite([
-          .toBuffer();
+            {
+              input: await opaqueRect(r.width, r.height),
+              left: r.left,
+              top: r.top,
+              blend: "dest-out",
+            },
+            { input: region, left: r.left, top: r.top },
+          ]);
       } else {
-        // Full image pixelation
+        pixelated = sharp(await mosaic(sharp(inputBuffer), w, h, bs));
-        const smallW = Math.max(1, Math.round(w / bs));
-        const smallH = Math.max(1, Math.round(h / bs));
-
-        buf = await sharp(inputBuffer)
-          .resize(smallW, smallH, { kernel: sharp.kernel.nearest })
-          .resize(w, h, { kernel: sharp.kernel.nearest })
-          .toBuffer();
       }
 
       const outputFormat = await resolveOutputFormat(inputBuffer, filename);
-      const buffer = await sharp(buf)
+      // Sharp reads `quality` on PNG as "quantise down to a palette", which
-        .toFormat(outputFormat.format, { quality: outputFormat.quality })
+      // dithers the flat blocks this tool exists to produce and inflates the
-        .toBuffer();
+      // file. Every other encoder wants the hint.
+      const encodeOptions = outputFormat.format === "png" ? {} : { quality: outputFormat.quality };
+      const buffer = await pixelated.toFormat(outputFormat.format, encodeOptions).toBuffer();
       const base = filename.replace(/\.[^.]+$/, "");
       const ext = outputFormat.extension;
       return {

tests/integration/tools/image/pixelate.test.ts

@@ -3,6 +3,10 @@
  *
  * Covers full-image pixelation, region pixelation, dimension preservation,
  * region bounds validation, region clamping, and schema validation.
+ *
+ * The pixel-level assertions use the scene fixture, not png200: png200 is a
+ * single flat colour, so pixelating it is a genuine no-op and every oracle
+ * built on it passes whether or not the tool does anything (issue #678).
  */
 
 import sharp from "sharp";
@@ -16,6 +20,11 @@ import {
 } from "../../test-server.js";
 
 const PNG = readFixture(fixtures.image.base.png200);
+const SCENE = readFixture(fixtures.image.scene);
+const ISOLATED = readFixture(fixtures.image.portrait.isolated);
+const SCENE_W = 800;
+const SCENE_H = 500;
+const CHANNELS = 4;
 
 let testApp: TestApp;
 let app: TestApp["app"];
@@ -31,7 +40,173 @@ afterAll(async () => {
   await testApp.cleanup();
 }, 10_000);
 
+interface Box {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+/** Run a fixture through the tool, returning the encoded file and its RGBA pixels. */
+async function pixelate(content: Buffer, settings: Record<string, unknown>) {
+  const { body, contentType } = createMultipartPayload([
+    { name: "file", filename: "input.png", contentType: "image/png", content },
+    { name: "settings", content: JSON.stringify(settings) },
+  ]);
+
+  const res = await app.inject({
+    method: "POST",
+    url: "/api/v1/tools/image/pixelate",
+    headers: { authorization: `Bearer ${adminToken}`, "content-type": contentType },
+    body,
+  });
+  expect(res.statusCode).toBe(200);
+
+  const dlRes = await app.inject({
+    method: "GET",
+    url: JSON.parse(res.body).downloadUrl,
+    headers: { authorization: `Bearer ${adminToken}` },
+  });
+
+  const { data, info } = await sharp(dlRes.rawPayload)
+    .ensureAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+  const source = await sharp(content).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  // The offset arithmetic below indexes both buffers with the same geometry, so
+  // pin it. A reshaped fixture must fail loudly, not read past the end and
+  // compare undefined to undefined, which counts as equal and passes.
+  expect([info.width, info.height, info.channels]).toEqual([
+    source.info.width,
+    source.info.height,
+    CHANNELS,
+  ]);
+  return { file: dlRes.rawPayload, pixels: data, source: source.data, width: info.width };
+}
+
+const offset = (width: number, x: number, y: number) => (y * width + x) * CHANNELS;
+
+const samePixel = (a: Buffer, ai: number, b: Buffer, bi: number) =>
+  a[ai] === b[bi] && a[ai + 1] === b[bi + 1] && a[ai + 2] === b[bi + 2] && a[ai + 3] === b[bi + 3];
+
+/**
+ * Names every blockSize-aligned block inside `box` that is not one flat colour.
+ * The box must divide evenly, otherwise block borders drift off the grid and the
+ * result says more about rounding than about the tool.
+ */
+function nonFlatBlocks(pixels: Buffer, width: number, box: Box, blockSize: number): string[] {
+  expect([box.width % blockSize, box.height % blockSize]).toEqual([0, 0]);
+
+  const uneven: string[] = [];
+  for (let by = 0; by < box.height / blockSize; by++) {
+    for (let bx = 0; bx < box.width / blockSize; bx++) {
+      const originX = box.left + bx * blockSize;
+      const originY = box.top + by * blockSize;
+      const corner = offset(width, originX, originY);
+      for (let y = originY; y < originY + blockSize; y++) {
+        for (let x = originX; x < originX + blockSize; x++) {
+          if (!samePixel(pixels, offset(width, x, y), pixels, corner)) {
+            uneven.push(`(${bx},${by})`);
+            y = originY + blockSize;
+            break;
+          }
+        }
+      }
+    }
+  }
+  return uneven;
+}
+
+/** Coarse thumbnail, for comparing where content sits rather than its detail. */
+const lowFrequency = (png: Buffer) =>
+  sharp(png).resize(8, 5, { fit: "fill" }).removeAlpha().raw().toBuffer();
+
+const maxDelta = (a: Buffer, b: Buffer) => {
+  let worst = 0;
+  for (let i = 0; i < a.length; i++) worst = Math.max(worst, Math.abs(a[i] - b[i]));
+  return worst;
+};
+
+const WHOLE_SCENE: Box = { left: 0, top: 0, width: SCENE_W, height: SCENE_H };
+
 describe("Pixelate", () => {
+  it("flattens the image into uniform blocks", async () => {
+    // 20 divides the 800x500 scene into an exact 40x25 grid, so block borders
+    // land on known coordinates and no rounding slack is needed.
+    const { pixels, source, width } = await pixelate(SCENE, { blockSize: 20 });
+
+    // Guards the narrow case where the resize no-ops and the encode happens to
+    // be lossless. The block check below is what catches a plain passthrough.
+    expect(pixels.equals(source)).toBe(false);
+
+    const uneven = nonFlatBlocks(pixels, width, WHOLE_SCENE, 20);
+    expect(uneven.length, `blocks that are not one flat colour: ${uneven.slice(0, 10)}`).toBe(0);
+  });
+
+  it("scales the blocks with blockSize", async () => {
+    // A coarser request has to produce coarser blocks. Asserting flatness on the
+    // 50 grid pins the size from above; the 20 grid in the test above pins it
+    // from below, so neither a hardcoded nor an ignored blockSize survives both.
+    // 50 is used rather than 40 because it divides 500 as well as 800.
+    const coarse = await pixelate(SCENE, { blockSize: 50 });
+    const fine = await pixelate(SCENE, { blockSize: 20 });
+
+    const uneven = nonFlatBlocks(coarse.pixels, coarse.width, WHOLE_SCENE, 50);
+    expect(uneven.length, `blocks that are not one flat colour: ${uneven.slice(0, 10)}`).toBe(0);
+    expect(coarse.pixels.equals(fine.pixels)).toBe(false);
+  });
+
+  it("keeps the picture in place when the block grid skews the aspect ratio", async () => {
+    // 800/48 and 500/48 round to a 17x10 grid, whose 1.70 aspect does not match
+    // the image's 1.60. This is the case that needs fit: "fill" on both resizes;
+    // the default "cover" crops and shifts the picture instead, which no
+    // dimension assertion can see because the output is still 800x500.
+    const { file } = await pixelate(SCENE, { blockSize: 48 });
+
+    const delta = maxDelta(await lowFrequency(SCENE), await lowFrequency(file));
+    // Measured: 9 with fill, 66 with cover.
+    expect(delta).toBeLessThan(20);
+  });
+
+  it("pixelates only the requested region", async () => {
+    // 200x160 at blockSize 20 is an exact 10x8 grid inside the region.
+    const region: Box = { left: 100, top: 80, width: 200, height: 160 };
+    const { pixels, source, width } = await pixelate(SCENE, { blockSize: 20, region });
+
+    const uneven = nonFlatBlocks(pixels, width, region, 20);
+    expect(uneven.length, `blocks that are not one flat colour: ${uneven.slice(0, 10)}`).toBe(0);
+
+    let changedInside = 0;
+    let changedOutside = 0;
+    for (let y = 0; y < SCENE_H; y++) {
+      for (let x = 0; x < SCENE_W; x++) {
+        const i = offset(width, x, y);
+        if (samePixel(pixels, i, source, i)) continue;
+        const inside =
+          x >= region.left &&
+          x < region.left + region.width &&
+          y >= region.top &&
+          y < region.top + region.height;
+        if (inside) changedInside++;
+        else changedOutside++;
+      }
+    }
+
+    expect(changedOutside).toBe(0);
+    expect(changedInside).toBeGreaterThan(0);
+  });
+
+  it("replaces a region of a transparent image instead of blending into it", async () => {
+    // Compositing the mosaic with the default `over` blend lets the original
+    // show through anywhere the block's averaged alpha is below 255, so a
+    // part-transparent image keeps the detail the user asked to hide.
+    const region: Box = { left: 0, top: 200, width: 400, height: 400 };
+    const { pixels, width } = await pixelate(ISOLATED, { blockSize: 20, region });
+
+    const uneven = nonFlatBlocks(pixels, width, region, 20);
+    expect(uneven.length, `blocks still showing the original: ${uneven.slice(0, 10)}`).toBe(0);
+  });
+
   it("pixelates entire image with default blockSize", async () => {
     const { body, contentType } = createMultipartPayload([
       { name: "file", filename: "test.png", contentType: "image/png", content: PNG },