@cosmicdrift/kumiko-bundled-features 0.285.2 → 0.287.0

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

@@ -2,7 +2,11 @@
 // `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 type {
+  ResolvedOverlayLayer,
+  VariantSpec,
+} from "@cosmicdrift/kumiko-types/derivatives-types";
+import jsQR from "jsqr";
 import sharp from "sharp";
 import { imageMetadata, renderImage } from "../render";
 
@@ -285,6 +289,247 @@ describe("renderImage — validation", () => {
   });
 });
 
+// jsQR needs a plain RGBA buffer, not sharp's own metadata/format handling —
+// this is the one test proving the AC ("readable with a phone camera") for
+// real: a pixel/byte-presence check would only prove placement, not that the
+// QR survives resize + a lossy re-encode.
+async function decodeQr(buffer: Uint8Array): Promise<string | null> {
+  const { data, info } = await sharp(buffer)
+    .ensureAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+  const result = jsQR(new Uint8ClampedArray(data), info.width, info.height);
+  return result?.data ?? null;
+}
+
+async function tinyImageOverlayBase64(
+  width: number,
+  height: number,
+  color: { r: number; g: number; b: number },
+): Promise<string> {
+  const buffer = await sharp({ create: { width, height, channels: 3, background: color } })
+    .png()
+    .toBuffer();
+  return buffer.toString("base64");
+}
+
+describe("renderImage — overlays", () => {
+  test("a qr overlay is actually scannable after resize + a lossy re-encode", async () => {
+    const input = await jpegFixture(800, 800);
+    const layer: ResolvedOverlayLayer = {
+      kind: "qr",
+      data: "https://example.com/v/abc123",
+      widthPct: 0.4,
+      gravity: "south-east",
+    };
+
+    const output = await renderImage(
+      input,
+      { maxEdge: 400, format: "webp", resolvedOverlays: [layer] },
+      "image/jpeg",
+    );
+
+    expect(await decodeQr(output)).toBe("https://example.com/v/abc123");
+  });
+
+  test("an unresolved `overlays` field is inert for the renderer — only `resolvedOverlays` composites", async () => {
+    const input = await jpegFixture(400, 400);
+    const spec: VariantSpec = {
+      overlays: [{ kind: "qr", dataToken: "vehicle-1", widthPct: 0.4, gravity: "center" }],
+    };
+
+    const output = await renderImage(input, spec, "image/jpeg");
+    const baseline = await renderImage(input, {}, "image/jpeg");
+    expect(Buffer.compare(output, baseline)).toBe(0);
+  });
+
+  test("the overlay width is the same fraction of the output at two different aspect ratios", async () => {
+    // PNG in and out (spec.format unset preserves the source format) — the
+    // fraction assertion below needs exact pixel equality, which a lossy
+    // jpeg re-encode wouldn't guarantee.
+    const input = await pngFixture(800, 800, { r: 250, g: 250, b: 250 });
+    const overlayColor = { r: 10, g: 200, b: 10 };
+    const imageBase64 = await tinyImageOverlayBase64(40, 40, overlayColor);
+    const layer: ResolvedOverlayLayer = {
+      kind: "image",
+      imageBase64,
+      widthPct: 0.25,
+      gravity: "south-east",
+    };
+
+    async function overlayPixelWidth(width: number, height: number): Promise<number> {
+      const output = await renderImage(
+        input,
+        { size: { width, height }, fit: "cover", resolvedOverlays: [layer] },
+        "image/png",
+      );
+      const { data, info } = await sharp(output).raw().toBuffer({ resolveWithObject: true });
+      const y = height - 1;
+      for (let x = 0; x < width; x++) {
+        const offset = (y * info.width + x) * info.channels;
+        if (
+          data[offset] === overlayColor.r &&
+          data[offset + 1] === overlayColor.g &&
+          data[offset + 2] === overlayColor.b
+        ) {
+          return width - x;
+        }
+      }
+      throw new Error("overlay color not found in bottom row");
+    }
+
+    expect(await overlayPixelWidth(640, 360)).toBe(Math.round(640 * 0.25));
+    expect(await overlayPixelWidth(400, 400)).toBe(Math.round(400 * 0.25));
+  });
+
+  test("a square overlay on a wide output is clamped to the output height instead of overrunning it", async () => {
+    // widthPct alone would ask for an 800x800 layer (aspect-preserved from a
+    // square source) on a 1600x400 output — taller than the base image, which
+    // sharp's composite() rejects unless the resize also bounds height.
+    const outputWidth = 1600;
+    const outputHeight = 400;
+    const input = await pngFixture(outputWidth, outputHeight, { r: 250, g: 250, b: 250 });
+    const overlayColor = { r: 10, g: 200, b: 10 };
+    const imageBase64 = await tinyImageOverlayBase64(100, 100, overlayColor);
+    const layer: ResolvedOverlayLayer = {
+      kind: "image",
+      imageBase64,
+      widthPct: 0.5,
+      gravity: "center",
+    };
+
+    const output = await renderImage(input, { resolvedOverlays: [layer] }, "image/png");
+    const { data, info } = await sharp(output).raw().toBuffer({ resolveWithObject: true });
+
+    const centerX = Math.floor(info.width / 2);
+    let minY = info.height;
+    let maxY = -1;
+    for (let y = 0; y < info.height; y++) {
+      const offset = (y * info.width + centerX) * info.channels;
+      if (
+        data[offset] === overlayColor.r &&
+        data[offset + 1] === overlayColor.g &&
+        data[offset + 2] === overlayColor.b
+      ) {
+        minY = Math.min(minY, y);
+        maxY = Math.max(maxY, y);
+      }
+    }
+
+    expect(maxY).toBeGreaterThan(-1);
+    expect(maxY - minY + 1).toBeLessThanOrEqual(outputHeight);
+  });
+
+  test("an SVG overlay layer is rejected the same way a source SVG is", async () => {
+    const input = await jpegFixture(200, 200);
+    const layer: ResolvedOverlayLayer = {
+      kind: "image",
+      imageBase64: Buffer.from(SVG_BYTES).toString("base64"),
+      widthPct: 0.3,
+      gravity: "center",
+    };
+
+    await expect(renderImage(input, { resolvedOverlays: [layer] }, "image/jpeg")).rejects.toThrow(
+      /svg/i,
+    );
+  });
+
+  test("more than MAX_OVERLAY_LAYERS throws instead of decoding+resizing each one", async () => {
+    const input = await jpegFixture(200, 200);
+    const overlays: ResolvedOverlayLayer[] = Array.from({ length: 9 }, () => ({
+      kind: "image",
+      imageBase64: "",
+      widthPct: 0.1,
+      gravity: "center",
+    }));
+
+    await expect(renderImage(input, { resolvedOverlays: overlays }, "image/jpeg")).rejects.toThrow(
+      /overlays has 9 entries/,
+    );
+  });
+
+  test("widthPct outside (0, 1] throws", async () => {
+    const input = await jpegFixture(200, 200);
+    const layer: ResolvedOverlayLayer = {
+      kind: "image",
+      imageBase64: await tinyImageOverlayBase64(10, 10, { r: 1, g: 1, b: 1 }),
+      widthPct: 1.5,
+      gravity: "center",
+    };
+
+    await expect(renderImage(input, { resolvedOverlays: [layer] }, "image/jpeg")).rejects.toThrow(
+      /widthPct/,
+    );
+  });
+
+  test("marginPct outside [0, 0.5) throws", async () => {
+    const input = await jpegFixture(200, 200);
+    const layer: ResolvedOverlayLayer = {
+      kind: "image",
+      imageBase64: await tinyImageOverlayBase64(10, 10, { r: 1, g: 1, b: 1 }),
+      widthPct: 0.2,
+      marginPct: 0.5,
+      gravity: "north-west",
+    };
+
+    await expect(renderImage(input, { resolvedOverlays: [layer] }, "image/jpeg")).rejects.toThrow(
+      /marginPct/,
+    );
+  });
+
+  test("a qr data length beyond MAX_QR_DATA_LENGTH throws", async () => {
+    const input = await jpegFixture(200, 200);
+    const layer: ResolvedOverlayLayer = {
+      kind: "qr",
+      data: "x".repeat(1025),
+      widthPct: 0.3,
+      gravity: "center",
+    };
+
+    await expect(renderImage(input, { resolvedOverlays: [layer] }, "image/jpeg")).rejects.toThrow(
+      /qr overlay data length/,
+    );
+  });
+
+  test("an empty qr data throws instead of encoding an empty QR", async () => {
+    const input = await jpegFixture(200, 200);
+    const layer: ResolvedOverlayLayer = { kind: "qr", data: "", widthPct: 0.3, gravity: "center" };
+
+    await expect(renderImage(input, { resolvedOverlays: [layer] }, "image/jpeg")).rejects.toThrow(
+      /qr overlay data length/,
+    );
+  });
+
+  test("an overlay image beyond MAX_OVERLAY_IMAGE_BYTES throws", async () => {
+    const input = await jpegFixture(200, 200);
+    const oversized = Buffer.alloc(513 * 1024, 1).toString("base64");
+    const layer: ResolvedOverlayLayer = {
+      kind: "image",
+      imageBase64: oversized,
+      widthPct: 0.3,
+      gravity: "center",
+    };
+
+    await expect(renderImage(input, { resolvedOverlays: [layer] }, "image/jpeg")).rejects.toThrow(
+      /overlay image is/,
+    );
+  });
+
+  test("a qr overlay that would render below MIN_QR_PIXEL_WIDTH throws instead of caching an unscannable image", async () => {
+    const input = await jpegFixture(200, 200);
+    const layer: ResolvedOverlayLayer = {
+      kind: "qr",
+      data: "https://example.com/v/abc123",
+      widthPct: 0.05,
+      gravity: "center",
+    };
+
+    await expect(
+      renderImage(input, { maxEdge: 200, resolvedOverlays: [layer] }, "image/jpeg"),
+    ).rejects.toThrow(/below the 160px minimum/);
+  });
+});
+
 describe("imageMetadata", () => {
   test("returns width/height/format", async () => {
     const input = await jpegFixture(320, 240);

package/src/derivatives-sharp/changes.json

@@ -1 +1,8 @@
-[]
+[
+  {
+    "version": "0.287.0",
+    "type": "improvement",
+    "title": "Render overlay layers (QR codes, badge images) onto image variants",
+    "detail": "The sharp renderer composites resolved overlay layers after resize and before final encoding. Overlay bytes go through the same SVG rejection as the source image, with DoS caps on layer count, size, and QR data length enforced in assertRenderSpecBounds."
+  }
+]

package/src/derivatives-sharp/render.ts

@@ -5,9 +5,12 @@
 import type {
   BlurRegion,
   DerivativeRendererPlugin,
+  OverlayGravity,
+  ResolvedOverlayLayer,
   VariantFit,
   VariantSpec,
 } from "@cosmicdrift/kumiko-types/derivatives-types";
+import QRCode from "qrcode";
 import type { OverlayOptions, ResizeOptions, Sharp } from "sharp";
 import sharp from "sharp";
 
@@ -25,6 +28,16 @@ const MAX_OUTPUT_EDGE = 8192;
 // unbounded region list is a CPU/RAM-multiplying DoS knob independent of
 // output size.
 const MAX_BLUR_REGIONS = 64;
+// Every layer decodes and resizes separately before the composite — an
+// unbounded list is the same CPU/RAM multiplier MAX_BLUR_REGIONS caps.
+const MAX_OVERLAY_LAYERS = 8;
+// Layer bytes ride inside the spec, which is hashed on every variant() call.
+const MAX_OVERLAY_IMAGE_BYTES = 512 * 1024;
+const MAX_QR_DATA_LENGTH = 1024;
+// Below roughly this, a QR's modules land on too few pixels to survive
+// camera capture — the AC claims phone-scannable, so an under-sized layer
+// throws instead of caching a silently unusable image.
+const MIN_QR_PIXEL_WIDTH = 160;
 // sequentialRead trades random pixel access for lower peak memory on
 // streamed formats — applied at every decode entry point below since none
 // of them need non-sequential access to the *original* bytes (extract runs
@@ -39,6 +52,18 @@ function clampSigma(sigma: number): number {
   return Math.min(MAX_SHARP_SIGMA, Math.max(MIN_SHARP_SIGMA, sigma));
 }
 
+// Shared trust boundary for every image byte source this renderer decodes —
+// the original upload (renderImage) and an overlay layer's bytes (applyOverlays)
+// alike: a base64 string in a field declaration isn't more trustworthy than
+// an upload just because it came from app code.
+function assertNotSvg(format: string | undefined): void {
+  if (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.",
+    );
+  }
+}
+
 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) {
@@ -86,6 +111,102 @@ async function applyBlurRegions(
   return sharp(data, SHARP_INPUT_OPTIONS).composite(overlays).toBuffer();
 }
 
+// Placement is anchored to the OUTPUT box (overlays run after resize, see
+// applyOverlays), then clamped the same way applyBlurRegions clamps its
+// region coordinates — a caller-declared marginPct can't push a layer
+// off-canvas.
+function overlayPosition(
+  gravity: OverlayGravity,
+  marginPx: number,
+  outputWidth: number,
+  outputHeight: number,
+  layerWidth: number,
+  layerHeight: number,
+): { left: number; top: number } {
+  let left: number;
+  let top: number;
+  switch (gravity) {
+    case "north-west":
+      left = marginPx;
+      top = marginPx;
+      break;
+    case "north-east":
+      left = outputWidth - layerWidth - marginPx;
+      top = marginPx;
+      break;
+    case "south-west":
+      left = marginPx;
+      top = outputHeight - layerHeight - marginPx;
+      break;
+    case "south-east":
+      left = outputWidth - layerWidth - marginPx;
+      top = outputHeight - layerHeight - marginPx;
+      break;
+    case "center":
+      left = (outputWidth - layerWidth) / 2;
+      top = (outputHeight - layerHeight) / 2;
+      break;
+    default:
+      throw new Error(`derivatives-sharp: unknown overlay gravity "${gravity satisfies never}".`);
+  }
+  const maxLeft = Math.max(0, outputWidth - layerWidth);
+  const maxTop = Math.max(0, outputHeight - layerHeight);
+  return {
+    left: Math.min(Math.max(Math.round(left), 0), maxLeft),
+    top: Math.min(Math.max(Math.round(top), 0), maxTop),
+  };
+}
+
+// Runs AFTER resize (see the AC in renderImage) so a layer sized as a
+// fraction of the output is a fraction of what the caller actually gets,
+// regardless of the source's own dimensions or `fit` crop.
+async function applyOverlays(
+  pipeline: Sharp,
+  layers: readonly ResolvedOverlayLayer[],
+): Promise<Sharp> {
+  const { data, info } = await pipeline.toBuffer({ resolveWithObject: true });
+
+  const composites: OverlayOptions[] = [];
+  for (const layer of layers) {
+    const layerBytes =
+      layer.kind === "qr"
+        ? await QRCode.toBuffer(layer.data, { margin: 1, errorCorrectionLevel: "M" })
+        : Buffer.from(layer.imageBase64, "base64");
+
+    const layerMeta = await sharp(layerBytes, SHARP_INPUT_OPTIONS).metadata();
+    assertNotSvg(layerMeta.format);
+
+    const targetWidth = Math.max(1, Math.round(info.width * layer.widthPct));
+    if (layer.kind === "qr" && targetWidth < MIN_QR_PIXEL_WIDTH) {
+      throw new Error(
+        `derivatives-sharp: qr overlay would render at ${targetWidth}px wide, below the ${MIN_QR_PIXEL_WIDTH}px minimum a camera can reliably scan.`,
+      );
+    }
+
+    // PNG (not the layer's own format) to keep any alpha through the resize.
+    // height caps the other axis too — sharp's composite() rejects an input
+    // larger than the base image, which a tall/square layer would otherwise
+    // hit once widthPct alone drives its width past the output's height.
+    const resized = await sharp(layerBytes, SHARP_INPUT_OPTIONS)
+      .resize({ width: targetWidth, height: info.height, fit: "inside" })
+      .png()
+      .toBuffer({ resolveWithObject: true });
+
+    const marginPx = Math.round(info.width * (layer.marginPct ?? 0));
+    const { left, top } = overlayPosition(
+      layer.gravity,
+      marginPx,
+      info.width,
+      info.height,
+      resized.info.width,
+      resized.info.height,
+    );
+    composites.push({ input: resized.data, left, top });
+  }
+
+  return sharp(data, SHARP_INPUT_OPTIONS).composite(composites);
+}
+
 function buildResizeOptions(width: number, height: number, fit: VariantFit): ResizeOptions {
   const options: ResizeOptions = { width, height, fit };
   if (fit === "inside") {
@@ -153,6 +274,51 @@ function applyEncoder(pipeline: Sharp, spec: VariantSpec, sourceMimeType: string
   return encode(pipeline, quality);
 }
 
+// Split out of assertRenderSpecBounds (not inlined there) purely to stay
+// under the AST-guard complexity budget — see assertRenderSpecBounds's own
+// comment. Still the single call site for every overlay bound.
+function assertOverlayLayerBounds(layer: ResolvedOverlayLayer): void {
+  if (!Number.isFinite(layer.widthPct) || layer.widthPct <= 0 || layer.widthPct > 1) {
+    throw new Error(
+      `derivatives-sharp: overlay widthPct ${layer.widthPct} is out of range — must be a finite number in (0, 1].`,
+    );
+  }
+  if (layer.marginPct !== undefined && (layer.marginPct < 0 || layer.marginPct >= 0.5)) {
+    throw new Error(
+      `derivatives-sharp: overlay marginPct ${layer.marginPct} is out of range — must be within [0, 0.5).`,
+    );
+  }
+  if (layer.kind === "qr") {
+    if (layer.data.length === 0 || layer.data.length > MAX_QR_DATA_LENGTH) {
+      throw new Error(
+        `derivatives-sharp: qr overlay data length ${layer.data.length} is out of range — must be 1–${MAX_QR_DATA_LENGTH} characters.`,
+      );
+    }
+    // skip: qr layers have no imageBase64 field to validate; this return also
+    // narrows the union below to the image variant without a cast.
+    return;
+  }
+  const byteLength = Buffer.byteLength(layer.imageBase64, "base64");
+  if (byteLength > MAX_OVERLAY_IMAGE_BYTES) {
+    throw new Error(
+      `derivatives-sharp: overlay image is ${byteLength} bytes, exceeding the limit of ${MAX_OVERLAY_IMAGE_BYTES}.`,
+    );
+  }
+}
+
+function assertOverlayBounds(layers: readonly ResolvedOverlayLayer[] | undefined): void {
+  // skip: no overlays configured for this variant, nothing to validate
+  if (!layers) return;
+  if (layers.length > MAX_OVERLAY_LAYERS) {
+    throw new Error(
+      `derivatives-sharp: overlays has ${layers.length} entries, exceeding the limit of ${MAX_OVERLAY_LAYERS} — each layer decodes and resizes separately before the composite.`,
+    );
+  }
+  for (const layer of layers) {
+    assertOverlayLayerBounds(layer);
+  }
+}
+
 // Input-validation for the DoS caps above — kept out of renderImage so the
 // complexity hotspot stays under the AST-guard budget.
 function assertRenderSpecBounds(spec: VariantSpec): void {
@@ -181,6 +347,7 @@ function assertRenderSpecBounds(spec: VariantSpec): void {
       );
     }
   }
+  assertOverlayBounds(spec.resolvedOverlays);
 }
 
 export const renderImage: DerivativeRendererPlugin["render"] = async (
@@ -194,11 +361,7 @@ export const renderImage: DerivativeRendererPlugin["render"] = async (
   // the SVG rejection from the actual bytes so a mislabeled upload can't
   // reach libvips as SVG.
   const sniffed = await sharp(input, SHARP_INPUT_OPTIONS).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.",
-    );
-  }
+  assertNotSvg(sniffed.format);
 
   assertRenderSpecBounds(spec);
 
@@ -225,6 +388,10 @@ export const renderImage: DerivativeRendererPlugin["render"] = async (
     pipeline = pipeline.blur(spec.blur);
   }
 
+  if (spec.resolvedOverlays && spec.resolvedOverlays.length > 0) {
+    pipeline = await applyOverlays(pipeline, spec.resolvedOverlays);
+  }
+
   pipeline = applyEncoder(pipeline, spec, normalizedSource);
 
   const buffer = await pipeline.toBuffer();

package/src/file-derivatives/__tests__/public-variant-route.integration.test.ts

@@ -77,9 +77,23 @@ const widgetEntity = createEntity({
   },
 });
 
+// Registered as a real entity (so upload's registry-hardening resolves it)
+// but with no EXT_DERIVATIVE_PUBLIC_PREDICATE registration — the "no
+// predicate registered for this entityType" default-deny case below needs
+// an entity that upload can attach to, distinct from "the entityType string
+// isn't registered at all" (which upload now rejects before the file ever
+// reaches file_refs, see kumiko-framework#3005).
+const noPredicateEntity = createEntity({
+  table: "public_variant_no_predicate",
+  fields: {
+    img: createImageField({ variants: { thumb: { maxEdge: 160, format: "webp" } } }),
+  },
+});
+
 let predicateCalls = 0;
 const widgetPredicateFeature = defineFeature("publicvariantroutetest", (r) => {
   r.entity("widget", widgetEntity);
+  r.entity("nopredicate", noPredicateEntity);
   r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, "widget", {
     isPublic: (args: DerivativePublicPredicateArgs) => {
       predicateCalls++;
@@ -161,7 +175,7 @@ async function uploadFile(
 
 describe("GET /media/:fileRefId/:variant (anonymous, default-deny)", () => {
   test("no predicate registered for the FileRef's entityType → 404", async () => {
-    const fileId = await uploadFile(userA, { entityType: "unregistered-type", entityId: "x" });
+    const fileId = await uploadFile(userA, { entityType: "nopredicate", entityId: "x" });
 
     const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/thumb`);
 

package/src/file-derivatives/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.287.0",
+    "type": "improvement",
+    "title": "Add overlay stage (QR codes, badge images) to derived image variants",
+    "detail": "VariantSpec now supports declarative overlay layers (qr via a resolver-token, or a base64 image) composited onto derived image variants. QR values are never free text — only a dataToken resolved server-side via a new extension point, keeping the anonymous derivative route from becoming an open image generator."
+  },
   {
     "version": "0.194.0",
     "type": "breaking",

package/src/file-derivatives/feature.ts

@@ -9,6 +9,7 @@
 import { cachedResponse, computeRevisionEtag } from "@cosmicdrift/kumiko-framework/api";
 import {
   defineFeature,
+  EXT_DERIVATIVE_OVERLAY_RESOLVER,
   EXT_DERIVATIVE_PUBLIC_PREDICATE,
   EXT_DERIVATIVE_RENDERER,
   type FeatureDefinition,
@@ -78,7 +79,7 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
 
   return defineFeature(FEATURE_NAME, (r) => {
     r.describe(
-      "Declares the `derivativeRenderer` extension point. `ctx.derivatives.variant(fileRefId, spec, name)` derives a variant of a tracked FileRef the first time it's requested and reuses the stored result afterwards (derive-on-first-use, keyed by a hash of the spec). Mount at least one `derivatives-*` renderer feature alongside this one — without a registered renderer for the FileRef's MIME type, every `variant(...)` call throws. Also declares the `derivativePublicPredicate` extension point (`r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, '<entityType>', { isPublic })`) and, when `createFileDerivativesFeature({resolveApexTenant})` is passed a host-resolver, mounts an anonymous `GET {basePath}/:fileRefId/:variant` route that serves any variant name the FileRef's field declared in its `variants` for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef or an undeclared variant name. The route's only rate-limit (`per: \"ip\"`) trusts the first `x-forwarded-for` hop — deployers must ensure their ingress overwrites rather than appends to that header, or the throttle is bypassable by rotating it.",
+      "Declares the `derivativeRenderer` extension point. `ctx.derivatives.variant(fileRefId, spec, name)` derives a variant of a tracked FileRef the first time it's requested and reuses the stored result afterwards (derive-on-first-use, keyed by a hash of the spec). Mount at least one `derivatives-*` renderer feature alongside this one — without a registered renderer for the FileRef's MIME type, every `variant(...)` call throws. Also declares the `derivativePublicPredicate` extension point (`r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, '<entityType>', { isPublic })`) and, when `createFileDerivativesFeature({resolveApexTenant})` is passed a host-resolver, mounts an anonymous `GET {basePath}/:fileRefId/:variant` route that serves any variant name the FileRef's field declared in its `variants` for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef or an undeclared variant name. The route's only rate-limit (`per: \"ip\"`) trusts the first `x-forwarded-for` hop — deployers must ensure their ingress overwrites rather than appends to that header, or the throttle is bypassable by rotating it. Also declares the `derivativeOverlayResolver` extension point (`r.useExtension(EXT_DERIVATIVE_OVERLAY_RESOLVER, '<entityType>', { resolve })`), used to turn a variant's `overlays[].dataToken` into the actual QR payload for that FileRef's entityType before the variant is rendered — a variant declaring a `qr` overlay throws at request-time if no resolver is registered for the FileRef's entityType.",
     );
     r.uiHints({
       displayLabel: "File Derivatives",
@@ -108,6 +109,13 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
         // entityType.
       },
     });
+    r.extendsRegistrar(EXT_DERIVATIVE_OVERLAY_RESOLVER, {
+      onRegister: () => {
+        // No side-effects at register-time — resolution happens in
+        // variant(), keyed by the FileRef's entityType, before the spec
+        // hash is computed.
+      },
+    });
 
     // Registered ONLY when resolveApexTenant is supplied — r.queryHandler
     // registers publicVariantQuery into the feature's dispatch table as a