@cosmicdrift/kumiko-bundled-features 0.190.0 → 0.192.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.190.0",
+  "version": "0.192.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -68,6 +68,7 @@
     "./file-provider-s3-env": "./src/file-provider-s3-env/index.ts",
     "./file-provider-inmemory": "./src/file-provider-inmemory/index.ts",
     "./file-derivatives": "./src/file-derivatives/index.ts",
+    "./derivatives-sharp": "./src/derivatives-sharp/index.ts",
     "./files": "./src/files/index.ts",
     "./user-data-rights": "./src/user-data-rights/index.ts",
     "./user-data-rights/web": "./src/user-data-rights/web/index.ts",
@@ -124,24 +125,25 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.190.0",
-    "@cosmicdrift/kumiko-framework": "0.190.0",
-    "@cosmicdrift/kumiko-headless": "0.190.0",
-    "@cosmicdrift/kumiko-renderer": "0.190.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.190.0",
-    "@cosmicdrift/kumiko-types": "0.190.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.192.0",
+    "@cosmicdrift/kumiko-framework": "0.192.0",
+    "@cosmicdrift/kumiko-headless": "0.192.0",
+    "@cosmicdrift/kumiko-renderer": "0.192.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.192.0",
+    "@cosmicdrift/kumiko-types": "0.192.0",
     "@mollie/api-client": "^4.5.0",
-    "imapflow": "^1.3.3",
-    "mailparser": "^3.9.8",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
     "@types/nodemailer": "^8.0.0",
     "clsx": "^2.1.1",
+    "imapflow": "^1.3.3",
     "lucide-react": "^1.14.0",
+    "mailparser": "^3.9.8",
     "marked": "^18.0.3",
     "nodemailer": "^9.0.1",
     "qrcode": "^1.5.4",
     "react": "^19.2.6",
+    "sharp": "^0.35.3",
     "stripe": "^22.1.1",
     "tailwind-merge": "^3.6.0"
   },

package/src/derivatives-sharp/__tests__/derivatives-sharp.integration.test.ts

@@ -0,0 +1,124 @@
+// Proves the full derive-on-first-use loop through a real sharp render: a
+// write-handler calls ctx.derivatives.variant(), the bytes it stores decode
+// as the promised format/size, and a second call with the same spec hits the
+// cache instead of rendering again.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { createInMemoryFileProvider } from "@cosmicdrift/kumiko-framework/files";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  buildMultipartBody,
+  patchFileInstanceofForBunTest,
+} from "@cosmicdrift/kumiko-framework/testing";
+import sharp from "sharp";
+import { z } from "zod";
+import { createConfigFeature } from "../../config";
+import { fileDerivativesFeature } from "../../file-derivatives";
+import { fileFoundationFeature } from "../../file-foundation";
+import { createFilesFeature } from "../../files";
+import { derivativesSharpFeature } from "../feature";
+import { imageMetadata } from "../render";
+
+const variantTestFeature = defineFeature("derivativessharptest", (r) => {
+  r.requires("file-derivatives");
+  r.writeHandler(
+    "make-thumb",
+    z.object({ fileRefId: z.string() }),
+    async (event, ctx) => {
+      if (!ctx.derivatives || !ctx.files) {
+        return writeFailure(
+          new InternalError({ message: "no ctx.derivatives/ctx.files on write-handler ctx" }),
+        );
+      }
+      const result = await ctx.derivatives.variant(
+        event.payload.fileRefId,
+        { maxEdge: 160, fit: "cover", format: "webp" },
+        "thumb",
+      );
+      const bytes = await ctx.files.ref(result.storageKey).read();
+      const meta = await imageMetadata(bytes);
+      return { isSuccess: true as const, data: { ...result, ...meta } };
+    },
+    { access: { openToAll: true } },
+  );
+});
+
+let stack: TestStack;
+const tenantId = testTenantId(1);
+const user = createTestUser({ id: 1, tenantId, roles: ["Admin"] });
+
+async function jpegBytes(width: number, height: number): Promise<Uint8Array> {
+  return sharp({ create: { width, height, channels: 3, background: { r: 90, g: 140, b: 200 } } })
+    .jpeg()
+    .toBuffer();
+}
+
+beforeAll(async () => {
+  patchFileInstanceofForBunTest();
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      fileFoundationFeature,
+      createFilesFeature(),
+      fileDerivativesFeature,
+      derivativesSharpFeature,
+      variantTestFeature,
+    ],
+    files: { storageProvider: createInMemoryFileProvider() },
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+async function uploadJpeg(): Promise<string> {
+  const token = await stack.jwt.sign(user);
+  const bytes = await jpegBytes(400, 200);
+  const fd = new FormData();
+  fd.append("file", new File([Buffer.from(bytes)], "photo.jpg", { type: "image/jpeg" }));
+  const { body, contentType } = await buildMultipartBody(fd);
+  const res = await stack.app.request("/api/files", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": contentType },
+    body,
+  });
+  expect(res.status).toBe(201);
+  const json = (await res.json()) as { id: string };
+  return json.id;
+}
+
+describe("derivatives-sharp — end to end through ctx.derivatives.variant", () => {
+  test("first call renders a real webp thumb, second call hits the cache", async () => {
+    const fileId = await uploadJpeg();
+
+    const first = await stack.http.writeOk<{
+      storageKey: string;
+      mimeType: string;
+      rendered: boolean;
+      width: number;
+      height: number;
+      format: string;
+    }>("derivativessharptest:write:make-thumb", { fileRefId: fileId }, user);
+
+    expect(first.rendered).toBe(true);
+    expect(first.mimeType).toBe("image/webp");
+    expect(first.format).toBe("webp");
+    expect(first.width).toBe(160);
+    expect(first.height).toBe(160);
+
+    const second = await stack.http.writeOk<{ rendered: boolean }>(
+      "derivativessharptest:write:make-thumb",
+      { fileRefId: fileId },
+      user,
+    );
+    expect(second.rendered).toBe(false);
+  });
+});

package/src/derivatives-sharp/__tests__/render.test.ts

@@ -0,0 +1,234 @@
+// Real sharp roundtrips — no mocked pipeline. Fixtures are built with
+// `sharp({ create: {...} })` so every case decodes real bytes end-to-end.
+
+import { describe, expect, test } from "bun:test";
+import type { VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
+import sharp from "sharp";
+import { imageMetadata, renderImage } from "../render";
+
+async function jpegFixture(
+  width: number,
+  height: number,
+  color = { r: 200, g: 40, b: 40 },
+): Promise<Buffer> {
+  return sharp({ create: { width, height, channels: 3, background: color } })
+    .jpeg()
+    .toBuffer();
+}
+
+async function orientedJpegFixture(width: number, height: number, orientation: number) {
+  return sharp({ create: { width, height, channels: 3, background: { r: 200, g: 40, b: 40 } } })
+    .jpeg()
+    .withMetadata({ orientation })
+    .toBuffer();
+}
+
+async function pngFixture(
+  width: number,
+  height: number,
+  color = { r: 40, g: 120, b: 200 },
+): Promise<Buffer> {
+  return sharp({ create: { width, height, channels: 3, background: color } })
+    .png()
+    .toBuffer();
+}
+
+// Minimal well-formed SVG, valid input for sharp/librsvg — used to prove the
+// renderer rejects it by sniffing bytes, not by trusting a declared mimeType.
+const SVG_BYTES = new TextEncoder().encode(
+  '<svg xmlns="http://www.w3.org/2000/svg" width="10" height="10"><rect width="10" height="10" fill="red"/></svg>',
+);
+
+// Real bytes just need to decode — the test is about the declared
+// "image/bmp" mimeType having no entry in the source-format encoder map, not
+// about the actual pixel format.
+async function unmappedFormatFixture(width: number, height: number): Promise<Buffer> {
+  return sharp({
+    create: { width, height, channels: 3, background: { r: 100, g: 100, b: 100 } },
+  })
+    .tiff()
+    .toBuffer();
+}
+
+// Two flat-colour halves straddled by the blur test's region, so blurring
+// mixes visibly detectable pixels at the boundary without needing synthetic
+// noise texture inside an otherwise-flat fixture.
+async function twoColorPngFixture(width: number, height: number): Promise<Buffer> {
+  const left = { r: 220, g: 20, b: 20 };
+  const right = { r: 20, g: 20, b: 220 };
+  const rightHalf = await sharp({
+    create: { width: width / 2, height, channels: 3, background: right },
+  })
+    .png()
+    .toBuffer();
+  return sharp({ create: { width, height, channels: 3, background: left } })
+    .composite([{ input: rightHalf, left: width / 2, top: 0 }])
+    .png()
+    .toBuffer();
+}
+
+// composite() promotes the output to include an alpha channel even when
+// every input was opaque RGB — read the channel count back instead of
+// assuming it, or the byte offsets below silently point at the wrong pixel.
+async function rawPixel(buffer: Uint8Array, x: number, y: number) {
+  const { data, info } = await sharp(buffer).raw().toBuffer({ resolveWithObject: true });
+  const offset = (y * info.width + x) * info.channels;
+  return Array.from(data.subarray(offset, offset + info.channels));
+}
+
+describe("renderImage — resize/fit", () => {
+  test("maxEdge + cover produces an exact square (the thumb preset)", async () => {
+    const input = await jpegFixture(400, 200);
+    const output = await renderImage(input, { maxEdge: 160, fit: "cover" }, "image/jpeg");
+    const meta = await sharp(output).metadata();
+    expect(meta.width).toBe(160);
+    expect(meta.height).toBe(160);
+  });
+
+  test("size + inside preserves aspect ratio inside the box", async () => {
+    const input = await jpegFixture(400, 200);
+    const output = await renderImage(
+      input,
+      { size: { width: 200, height: 200 }, fit: "inside" },
+      "image/jpeg",
+    );
+    const meta = await sharp(output).metadata();
+    expect(meta.width).toBe(200);
+    expect(meta.height).toBe(100);
+  });
+
+  test("contain pads to fill the exact box", async () => {
+    const input = await jpegFixture(400, 200);
+    const output = await renderImage(
+      input,
+      { size: { width: 100, height: 100 }, fit: "contain" },
+      "image/jpeg",
+    );
+    const meta = await sharp(output).metadata();
+    expect(meta.width).toBe(100);
+    expect(meta.height).toBe(100);
+  });
+
+  test("inside with a maxEdge larger than the source never enlarges", async () => {
+    const input = await jpegFixture(400, 200);
+    const output = await renderImage(input, { maxEdge: 4000, fit: "inside" }, "image/jpeg");
+    const meta = await sharp(output).metadata();
+    expect(meta.width).toBe(400);
+    expect(meta.height).toBe(200);
+  });
+});
+
+describe("renderImage — format contract", () => {
+  test("without spec.format the source format is preserved", async () => {
+    const input = await jpegFixture(400, 200);
+    const output = await renderImage(input, { maxEdge: 100 }, "image/jpeg");
+    const meta = await sharp(output).metadata();
+    expect(meta.format).toBe("jpeg");
+  });
+
+  test("with spec.format the output switches format", async () => {
+    const input = await jpegFixture(400, 200);
+    const output = await renderImage(input, { maxEdge: 100, format: "webp" }, "image/jpeg");
+    const meta = await sharp(output).metadata();
+    expect(meta.format).toBe("webp");
+  });
+
+  test("the image/jpg upload alias is accepted without spec.format", async () => {
+    const input = await jpegFixture(400, 200);
+    const output = await renderImage(input, { maxEdge: 100 }, "image/jpg");
+    const meta = await sharp(output).metadata();
+    expect(meta.format).toBe("jpeg");
+  });
+});
+
+describe("renderImage — EXIF", () => {
+  test("all EXIF is stripped from the output", async () => {
+    const input = await sharp({
+      create: { width: 100, height: 100, channels: 3, background: { r: 10, g: 10, b: 10 } },
+    })
+      .jpeg()
+      .withExif({ IFD0: { Copyright: "kumiko-test" } })
+      .toBuffer();
+
+    const output = await renderImage(input, { maxEdge: 100 }, "image/jpeg");
+    const meta = await sharp(output).metadata();
+    expect(meta.exif).toBeUndefined();
+  });
+
+  test("EXIF orientation is applied (dimensions swap) then normalized away", async () => {
+    const input = await orientedJpegFixture(400, 200, 6);
+    const output = await renderImage(input, {}, "image/jpeg");
+    const meta = await sharp(output).metadata();
+    expect(meta.width).toBe(200);
+    expect(meta.height).toBe(400);
+  });
+});
+
+describe("renderImage — blurRegions", () => {
+  test("burns blur into the region, leaves the rest byte-identical", async () => {
+    const input = await twoColorPngFixture(200, 200);
+    const baseline = await renderImage(input, {}, "image/png");
+    const spec: VariantSpec = {
+      blurRegions: [{ x: 0.35, y: 0.25, width: 0.3, height: 0.5 }],
+    };
+    const blurred = await renderImage(input, spec, "image/png");
+
+    // Region centre sits on the red/blue boundary (x≈0.5) — blur mixes the
+    // two colours there, so it must differ from the untouched baseline.
+    const centreBaseline = await rawPixel(baseline, 100, 100);
+    const centreBlurred = await rawPixel(blurred, 100, 100);
+    expect(centreBlurred).not.toEqual(centreBaseline);
+
+    // Far outside the region: composite never touched these pixels.
+    const farBaseline = await rawPixel(baseline, 10, 10);
+    const farBlurred = await rawPixel(blurred, 10, 10);
+    expect(farBlurred).toEqual(farBaseline);
+  });
+});
+
+describe("renderImage — validation", () => {
+  test("blur sigma below sharp's supported range throws", async () => {
+    const input = await jpegFixture(50, 50);
+    await expect(renderImage(input, { blur: 0.1 }, "image/jpeg")).rejects.toThrow(/blur sigma/);
+  });
+
+  test("quality out of range throws", async () => {
+    const input = await jpegFixture(50, 50);
+    await expect(renderImage(input, { quality: 0 }, "image/jpeg")).rejects.toThrow(/quality/);
+  });
+
+  test("real SVG bytes are rejected even with a spoofed sourceMimeType", async () => {
+    await expect(renderImage(SVG_BYTES, {}, "image/jpeg")).rejects.toThrow(/svg/i);
+  });
+
+  test("real PNG bytes with a spoofed sourceMimeType encode as the declared type", async () => {
+    const input = await pngFixture(50, 50);
+    const output = await renderImage(input, {}, "image/jpeg");
+    const meta = await sharp(output).metadata();
+    expect(meta.format).toBe("jpeg");
+  });
+
+  test("a source mimeType with no encoder mapping throws unless spec.format is set", async () => {
+    const input = await unmappedFormatFixture(50, 50);
+    await expect(renderImage(input, {}, "image/bmp")).rejects.toThrow(/no output encoder/);
+
+    const output = await renderImage(input, { format: "webp" }, "image/bmp");
+    const meta = await sharp(output).metadata();
+    expect(meta.format).toBe("webp");
+  });
+});
+
+describe("imageMetadata", () => {
+  test("returns width/height/format", async () => {
+    const input = await jpegFixture(320, 240);
+    const meta = await imageMetadata(input);
+    expect(meta).toEqual({ width: 320, height: 240, format: "jpeg" });
+  });
+
+  test("returns auto-oriented dimensions for EXIF orientation 6", async () => {
+    const input = await orientedJpegFixture(400, 200, 6);
+    const meta = await imageMetadata(input);
+    expect(meta.width).toBe(200);
+    expect(meta.height).toBe(400);
+  });
+});

package/src/derivatives-sharp/changes.json

@@ -0,0 +1 @@
+[]

package/src/derivatives-sharp/feature.ts

@@ -0,0 +1,22 @@
+// kumiko-feature-version: 1
+
+import { defineFeature, EXT_DERIVATIVE_RENDERER } from "@cosmicdrift/kumiko-framework/engine";
+import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
+import { renderImage } from "./render";
+
+const FEATURE_NAME = "derivatives-sharp";
+
+export const derivativesSharpFeature = defineFeature(FEATURE_NAME, (r) => {
+  r.describe(
+    "Registers an `image/*` renderer against the `derivativeRenderer` extension point declared by `file-derivatives`, backed by sharp. Supports resize/fit (cover, inside, contain), format conversion with quality (webp, avif, jpeg), whole-image blur, and blurring individual regions burned in before resize (see BlurRegion). EXIF orientation is applied and then normalized away, and all other EXIF (including GPS) is dropped. Server-only: sharp is a native binding — never import this from client code.",
+  );
+  r.uiHints({
+    displayLabel: "File Derivatives · Sharp",
+    category: "storage",
+    recommended: false,
+  });
+  r.requires("file-derivatives");
+
+  const plugin: DerivativeRendererPlugin = { render: renderImage };
+  r.useExtension(EXT_DERIVATIVE_RENDERER, "image/*", plugin);
+});

package/src/derivatives-sharp/index.ts

@@ -0,0 +1,2 @@
+export { derivativesSharpFeature } from "./feature";
+export { imageMetadata } from "./render";

package/src/derivatives-sharp/render.ts

@@ -0,0 +1,201 @@
+// sharp-backed renderer for the `derivativeRenderer` extension point —
+// resize/fit, format+quality re-encode, whole-image blur, and pre-resize
+// region blur (see BlurRegion). Server-only: sharp is a native binding.
+
+import type {
+  BlurRegion,
+  DerivativeRendererPlugin,
+  VariantFit,
+  VariantSpec,
+} from "@cosmicdrift/kumiko-types/derivatives-types";
+import type { OverlayOptions, ResizeOptions, Sharp } from "sharp";
+import sharp from "sharp";
+
+const MIN_SHARP_SIGMA = 0.3;
+const MAX_SHARP_SIGMA = 1000;
+
+function normalizeMimeType(mimeType: string): string {
+  return mimeType.toLowerCase().split(";")[0]?.trim() ?? "";
+}
+
+function clampSigma(sigma: number): number {
+  return Math.min(MAX_SHARP_SIGMA, Math.max(MIN_SHARP_SIGMA, sigma));
+}
+
+function assertValidRegion(region: BlurRegion): void {
+  const values = [region.x, region.y, region.width, region.height];
+  if (values.some((v) => !Number.isFinite(v)) || region.width <= 0 || region.height <= 0) {
+    throw new Error(
+      `derivatives-sharp: invalid blurRegion ${JSON.stringify(region)} — x/y/width/height must be finite and width/height must be > 0.`,
+    );
+  }
+}
+
+// Burns each region into the auto-oriented base image, one extract+blur+
+// composite pass per region. Runs BEFORE resize: the regions are relative to
+// the original pixels, and a `fit: "cover"` crop shifts pixel coordinates in
+// a way a post-resize mapping can't reconstruct.
+async function applyBlurRegions(
+  data: Buffer,
+  width: number,
+  height: number,
+  regions: readonly BlurRegion[],
+): Promise<Buffer> {
+  const overlays: OverlayOptions[] = [];
+
+  for (const region of regions) {
+    assertValidRegion(region);
+
+    // AI-detected/user-corrected coordinates can run slightly outside the
+    // frame — clamp instead of rejecting.
+    const left = Math.min(Math.max(Math.round(region.x * width), 0), width);
+    const top = Math.min(Math.max(Math.round(region.y * height), 0), height);
+    const rectWidth = Math.min(Math.round(region.width * width), width - left);
+    const rectHeight = Math.min(Math.round(region.height * height), height - top);
+    if (rectWidth < 1 || rectHeight < 1) continue;
+
+    // ponytail: fixed size-proportional sigma heuristic (no per-region sigma
+    // input) — good enough until a caller needs to tune blur strength itself.
+    const sigma = clampSigma(Math.max(4, Math.min(rectWidth, rectHeight) / 6));
+
+    const patch = await sharp(data)
+      .extract({ left, top, width: rectWidth, height: rectHeight })
+      .blur(sigma)
+      .toBuffer();
+    overlays.push({ input: patch, left, top });
+  }
+
+  if (overlays.length === 0) return data;
+  return sharp(data).composite(overlays).toBuffer();
+}
+
+function buildResizeOptions(width: number, height: number, fit: VariantFit): ResizeOptions {
+  const options: ResizeOptions = { width, height, fit };
+  if (fit === "inside") {
+    // Max-box: never enlarge past the source.
+    options.withoutEnlargement = true;
+  }
+  if (fit === "contain") {
+    // sharp pads "contain" with opaque black by default — transparent instead
+    // so only formats that keep alpha show a border at all (jpeg flattens it).
+    options.background = { r: 0, g: 0, b: 0, alpha: 0 };
+  }
+  return options;
+}
+
+// HARD CONTRACT (see outputMimeType in derivatives-context.ts): with
+// spec.format set, the output MUST be that format; with it unset, the
+// output MUST stay the source format. The caller derives the mimeType from
+// the spec alone and never inspects the bytes, so drifting from this silently
+// mislabels the stored variant. sourceMimeType is a client-declared upload
+// label, not sniffed from bytes, so we can't lean on sharp's "no encoder
+// call" passthrough to honor it — the encoder is always called explicitly
+// from the map below, and an unmapped source mimeType throws instead of
+// silently keeping whatever format sharp actually decoded.
+const SOURCE_FORMAT_ENCODERS: Record<string, (pipeline: Sharp, quality?: number) => Sharp> = {
+  "image/jpeg": (pipeline, quality) =>
+    pipeline.jpeg(quality !== undefined ? { quality } : undefined),
+  // The upload whitelist admits the sloppy-but-common image/jpg alias
+  "image/jpg": (pipeline, quality) =>
+    pipeline.jpeg(quality !== undefined ? { quality } : undefined),
+  "image/png": (pipeline, quality) => pipeline.png(quality !== undefined ? { quality } : undefined),
+  "image/webp": (pipeline, quality) =>
+    pipeline.webp(quality !== undefined ? { quality } : undefined),
+  "image/avif": (pipeline, quality) =>
+    pipeline.avif(quality !== undefined ? { quality } : undefined),
+  // sharp's GifOptions has no quality knob (palette/dither instead) — ignore
+  // the value here rather than pass it through.
+  "image/gif": (pipeline) => pipeline.gif(),
+  "image/tiff": (pipeline, quality) =>
+    pipeline.tiff(quality !== undefined ? { quality } : undefined),
+};
+
+function applyEncoder(pipeline: Sharp, spec: VariantSpec, sourceMimeType: string): Sharp {
+  const quality = spec.quality;
+
+  if (spec.format) {
+    switch (spec.format) {
+      case "webp":
+        return pipeline.webp(quality !== undefined ? { quality } : undefined);
+      case "avif":
+        return pipeline.avif(quality !== undefined ? { quality } : undefined);
+      case "jpeg":
+        return pipeline.jpeg(quality !== undefined ? { quality } : undefined);
+    }
+  }
+
+  const encode = SOURCE_FORMAT_ENCODERS[sourceMimeType];
+  if (!encode) {
+    throw new Error(
+      `derivatives-sharp: no output encoder for source mimeType "${sourceMimeType}" — set spec.format to pick an explicit output format.`,
+    );
+  }
+  return encode(pipeline, quality);
+}
+
+export const renderImage: DerivativeRendererPlugin["render"] = async (
+  input,
+  spec,
+  sourceMimeType,
+) => {
+  const normalizedSource = normalizeMimeType(sourceMimeType);
+
+  // sourceMimeType is a client-declared upload label, not sniffed — decide
+  // the SVG rejection from the actual bytes so a mislabeled upload can't
+  // reach libvips as SVG.
+  const sniffed = await sharp(input).metadata();
+  if (sniffed.format === "svg") {
+    throw new Error(
+      "derivatives-sharp: SVG is not supported — rendering untrusted SVG through libvips is a trust boundary this renderer doesn't need to cross.",
+    );
+  }
+
+  if (spec.quality !== undefined && (spec.quality < 1 || spec.quality > 100)) {
+    throw new Error(`derivatives-sharp: quality ${spec.quality} is out of range (1–100).`);
+  }
+  if (spec.blur !== undefined && (spec.blur < MIN_SHARP_SIGMA || spec.blur > MAX_SHARP_SIGMA)) {
+    throw new Error(
+      `derivatives-sharp: blur sigma ${spec.blur} is out of sharp's supported range (${MIN_SHARP_SIGMA}–${MAX_SHARP_SIGMA}).`,
+    );
+  }
+
+  // rotate() with no argument applies the EXIF orientation and normalizes it
+  // away. sharp drops all other metadata by default — we never call
+  // .withMetadata()/.keepExif(), which is exactly what strips GPS/EXIF from
+  // the output.
+  let pipeline = sharp(input).rotate();
+
+  if (spec.blurRegions && spec.blurRegions.length > 0) {
+    const { data, info } = await pipeline.toBuffer({ resolveWithObject: true });
+    const blurred = await applyBlurRegions(data, info.width, info.height, spec.blurRegions);
+    pipeline = sharp(blurred);
+  }
+
+  const fit = spec.fit ?? "inside";
+  if (spec.size) {
+    pipeline = pipeline.resize(buildResizeOptions(spec.size.width, spec.size.height, fit));
+  } else if (spec.maxEdge) {
+    pipeline = pipeline.resize(buildResizeOptions(spec.maxEdge, spec.maxEdge, fit));
+  }
+
+  if (spec.blur !== undefined) {
+    pipeline = pipeline.blur(spec.blur);
+  }
+
+  pipeline = applyEncoder(pipeline, spec, normalizedSource);
+
+  const buffer = await pipeline.toBuffer();
+  return new Uint8Array(buffer);
+};
+
+export async function imageMetadata(
+  input: Uint8Array,
+): Promise<{ width: number; height: number; format: string }> {
+  const metadata = await sharp(input).metadata();
+  const width = metadata.autoOrient.width;
+  const height = metadata.autoOrient.height;
+  if (!Number.isFinite(width) || !Number.isFinite(height) || !metadata.format) {
+    throw new Error("derivatives-sharp: imageMetadata got a response without width/height/format.");
+  }
+  return { width, height, format: metadata.format };
+}