@agent-native/core 0.149.0 → 0.149.2

package/corpus/templates/slides/changelog/2026-08-10-generated-decks-keep-a-clear-human-readable-title.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-10
+---
+
+Generated decks keep a clear, human-readable title

package/corpus/templates/slides/changelog/2026-08-10-new-deck-creation-now-shows-progress-opens-the-editor-direct.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-10
+---
+
+New deck creation now shows progress, opens the editor directly, and remembers your reference choices

package/corpus/templates/slides/changelog/2026-08-10-presentation-reveals-now-follow-valid-targets.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-10
+---
+
+Presentation reveals now follow validated ordered targets, queue rapid navigation, and settle cleanly after transitions.

package/corpus/templates/slides/changelog/2026-08-10-slides-editing-controls-are-consolidated-into-one-focused-me.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-10
+---
+
+Slides editing controls are consolidated into one focused menu

package/corpus/templates/slides/changelog/2026-08-10-slides-now-verify-and-restyle-every-imported-slide-in-one-pa.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-10
+---
+
+Slides now verify and restyle every imported slide in one pass

package/corpus/templates/slides/changelog/2026-08-10-slides-only-suggests-a-google-connection-for-relevant-reques.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-10
+---
+
+Slides only suggests a Google connection for relevant requests, and the suggestion can be dismissed.

package/corpus/templates/slides/changelog/2026-08-10-the-google-slides-import-option-is-now-labeled-slides.md

@@ -0,0 +1,6 @@
+---
+type: changed
+date: 2026-08-10
+---
+
+The Google Slides import option is now labeled Slides.

package/corpus/templates/slides/server/handlers/import/html-converter.ts

@@ -1,3 +1,5 @@
+import { ASPECT_RATIOS } from "@shared/aspect-ratios";
+
 import type {
   ParsedElement,
   ParsedParagraph,
@@ -165,10 +167,37 @@ export function convertToSlideHtml(
 
 const DEFAULT_SLIDE_WIDTH_EMU = 9144000;
 const DEFAULT_SLIDE_HEIGHT_EMU = 5143500;
-const CSS_PX_PER_POINT = 96 / 72;
 const DEFAULT_PPTX_BACKGROUND = "#000000"; // guard:allow-raw-color - preserve PPTX black when no background is declared
 const DEFAULT_PPTX_FOREGROUND = "#ffffff"; // guard:allow-raw-color - preserve PPTX white when no run color is declared
 
+/**
+ * The absolute px box `toSlidePxX`/`toSlidePxY` scale positions and sizes
+ * against. It must match the aspect-ratio preset the deck actually renders
+ * into (`ASPECT_RATIOS`, chosen by the import actions' own
+ * `nearestAspectRatio`) rather than a fixed 16:9 box: a PDF page or a custom
+ * PPTX slide size is routinely portrait or square, and scaling its elements
+ * against a 960x540 reference while the deck itself renders in an 864x1080
+ * (or other) box stretches every element by the ratio between the two
+ * boxes, most visibly squashing everything into the top fraction of a
+ * taller-than-540 canvas.
+ */
+function referenceBoxForSlide(
+  widthEmu: number,
+  heightEmu: number,
+): { width: number; height: number } {
+  const target = widthEmu / heightEmu;
+  let best: { width: number; height: number } = ASPECT_RATIOS["16:9"];
+  let bestDiff = Infinity;
+  for (const preset of Object.values(ASPECT_RATIOS)) {
+    const diff = Math.abs(preset.width / preset.height - target);
+    if (diff < bestDiff) {
+      bestDiff = diff;
+      best = preset;
+    }
+  }
+  return { width: best.width, height: best.height };
+}
+
 function buildFidelitySlide(
   slide: ParsedSlide,
   imageUrls: string | Record<string, string> | undefined,
@@ -176,9 +205,10 @@ function buildFidelitySlide(
 ): string {
   const widthEmu = slide.widthEmu || DEFAULT_SLIDE_WIDTH_EMU;
   const heightEmu = slide.heightEmu || DEFAULT_SLIDE_HEIGHT_EMU;
+  const refBox = referenceBoxForSlide(widthEmu, heightEmu);
   const background = slide.backgroundColor ?? DEFAULT_PPTX_BACKGROUND;
   const gridStyle = slide.backgroundGrid
-    ? `background-image:linear-gradient(to right, ${esc(slide.backgroundGrid.color)} 0 ${Math.max(0.5, toSlidePxX(slide.backgroundGrid.lineWidthEmu, widthEmu))}px, transparent ${Math.max(0.5, toSlidePxX(slide.backgroundGrid.lineWidthEmu, widthEmu))}px),linear-gradient(to bottom, ${esc(slide.backgroundGrid.color)} 0 ${Math.max(0.5, toSlidePxY(slide.backgroundGrid.lineWidthEmu, heightEmu))}px, transparent ${Math.max(0.5, toSlidePxY(slide.backgroundGrid.lineWidthEmu, heightEmu))}px);background-size:${toSlidePxX(slide.backgroundGrid.stepXEmu, widthEmu)}px ${toSlidePxY(slide.backgroundGrid.stepYEmu, heightEmu)}px;background-position:${toSlidePxX(slide.backgroundGrid.offsetXEmu, widthEmu)}px ${toSlidePxY(slide.backgroundGrid.offsetYEmu, heightEmu)}px;background-repeat:repeat;`
+    ? `background-image:linear-gradient(to right, ${esc(slide.backgroundGrid.color)} 0 ${Math.max(0.5, toSlidePxX(slide.backgroundGrid.lineWidthEmu, widthEmu, refBox.width))}px, transparent ${Math.max(0.5, toSlidePxX(slide.backgroundGrid.lineWidthEmu, widthEmu, refBox.width))}px),linear-gradient(to bottom, ${esc(slide.backgroundGrid.color)} 0 ${Math.max(0.5, toSlidePxY(slide.backgroundGrid.lineWidthEmu, heightEmu, refBox.height))}px, transparent ${Math.max(0.5, toSlidePxY(slide.backgroundGrid.lineWidthEmu, heightEmu, refBox.height))}px);background-size:${toSlidePxX(slide.backgroundGrid.stepXEmu, widthEmu, refBox.width)}px ${toSlidePxY(slide.backgroundGrid.stepYEmu, heightEmu, refBox.height)}px;background-position:${toSlidePxX(slide.backgroundGrid.offsetXEmu, widthEmu, refBox.width)}px ${toSlidePxY(slide.backgroundGrid.offsetYEmu, heightEmu, refBox.height)}px;background-repeat:repeat;`
     : "";
   const elements = slide.elements ?? [];
   const html = elements
@@ -188,6 +218,7 @@ function buildFidelitySlide(
         index,
         widthEmu,
         heightEmu,
+        refBox,
         imageUrls,
         themeFont,
       ),
@@ -203,10 +234,11 @@ function buildFidelityElement(
   index: number,
   widthEmu: number,
   heightEmu: number,
+  refBox: { width: number; height: number },
   imageUrls: string | Record<string, string> | undefined,
   themeFont: string | undefined,
 ): string {
-  const position = `position: absolute; left: ${toSlidePxX(element.x, widthEmu)}px; top: ${toSlidePxY(element.y, heightEmu)}px; width: ${toSlidePxX(element.width, widthEmu)}px; height: ${toSlidePxY(element.height, heightEmu)}px; z-index: ${index}; box-sizing: border-box;`;
+  const position = `position: absolute; left: ${toSlidePxX(element.x, widthEmu, refBox.width)}px; top: ${toSlidePxY(element.y, heightEmu, refBox.height)}px; width: ${toSlidePxX(element.width, widthEmu, refBox.width)}px; height: ${toSlidePxY(element.height, heightEmu, refBox.height)}px; z-index: ${index}; box-sizing: border-box;`;
   const rotation = element.rotation
     ? ` transform: rotate(${element.rotation}deg); transform-origin: center center;`
     : "";
@@ -218,12 +250,18 @@ function buildFidelityElement(
     return `<div class="fmd-pptx-image" data-pptx-element-kind="image" data-pptx-image-name="${esc(element.image?.name ?? "image")}"${objectId} style="${position}${rotation} overflow: hidden;">${url ? `<img src="${esc(url)}" alt="" style="${imageStyle}" />` : `<div class="fmd-img-placeholder" style="width:100%;height:100%;">Imported image: ${esc(element.image?.name ?? "image")}</div>`}</div>`;
   }
 
-  const decoration = shapeDecoration(element, widthEmu);
+  const decoration = shapeDecoration(element, widthEmu, refBox.width);
   if (element.kind === "shape") {
     return `<div class="fmd-pptx-shape" data-pptx-element-kind="shape"${objectId} style="${position}${rotation}${decoration}"></div>`;
   }
 
-  const textStyle = textBoxStyle(element, widthEmu, heightEmu, themeFont);
+  const textStyle = textBoxStyle(
+    element,
+    widthEmu,
+    heightEmu,
+    refBox,
+    themeFont,
+  );
   const defaultFontWeight = element.placeholderType === "title" ? 700 : 400;
   const paragraphs = (element.paragraphs ?? [])
     .map((paragraph, paragraphIndex) =>
@@ -231,6 +269,7 @@ function buildFidelityElement(
         paragraph,
         paragraphIndex,
         widthEmu,
+        refBox.width,
         themeFont,
         defaultFontWeight,
       ),
@@ -239,12 +278,41 @@ function buildFidelityElement(
   return `<div class="fmd-pptx-text" data-pptx-element-kind="text"${objectId} style="${position}${rotation}${decoration}${textStyle}">${paragraphs}</div>`;
 }
 
-function toSlidePxX(valueEmu: number, slideWidthEmu: number): number {
-  return Math.round((valueEmu / slideWidthEmu) * 960 * 1000) / 1000;
+function toSlidePxX(
+  valueEmu: number,
+  slideWidthEmu: number,
+  refWidthPx: number,
+): number {
+  return Math.round((valueEmu / slideWidthEmu) * refWidthPx * 1000) / 1000;
 }
 
-function toSlidePxY(valueEmu: number, slideHeightEmu: number): number {
-  return Math.round((valueEmu / slideHeightEmu) * 540 * 1000) / 1000;
+function toSlidePxY(
+  valueEmu: number,
+  slideHeightEmu: number,
+  refHeightPx: number,
+): number {
+  return Math.round((valueEmu / slideHeightEmu) * refHeightPx * 1000) / 1000;
+}
+
+const EMU_PER_POINT = 12700;
+
+/**
+ * A run's font size (and paragraph spacing) is stored in points, a physical
+ * unit independent of the source slide's own canvas size — unlike
+ * position/size EMUs, a fixed `pt * 96/72` conversion doesn't know how far
+ * `toSlidePxX`/`toSlidePxY` scaled that canvas down (or up) to fit the
+ * deck's aspect-ratio box. Converting the point value to EMU first and
+ * running it through the same `toSlidePxX` scale keeps text sized
+ * proportionally to its box on every source slide size, not just the one
+ * physical size (10in wide) that happens to make the fixed conversion agree
+ * with the 16:9 preset's box.
+ */
+function ptToSlidePx(
+  valuePt: number,
+  widthEmu: number,
+  refWidthPx: number,
+): number {
+  return toSlidePxX(valuePt * EMU_PER_POINT, widthEmu, refWidthPx);
 }
 
 function imageUrlForElement(
@@ -263,10 +331,14 @@ function imageRenderStyle(element: ParsedElement): string {
   return `display:block;position:absolute;left:${(-crop.left / visibleWidth) * 100}%;top:${(-crop.top / visibleHeight) * 100}%;width:${(1 / visibleWidth) * 100}%;height:${(1 / visibleHeight) * 100}%;object-fit:fill;`;
 }
 
-function shapeDecoration(element: ParsedElement, widthEmu: number): string {
+function shapeDecoration(
+  element: ParsedElement,
+  widthEmu: number,
+  refWidthPx: number,
+): string {
   const fill = element.fill ? `background: ${esc(element.fill)};` : "";
   const line = element.lineColor
-    ? `border: ${Math.max(1, toSlidePxX(element.lineWidth ?? 12700, widthEmu))}px solid ${esc(element.lineColor)};`
+    ? `border: ${Math.max(1, toSlidePxX(element.lineWidth ?? 12700, widthEmu, refWidthPx))}px solid ${esc(element.lineColor)};`
     : "";
   const radius = element.shapeType === "roundRect" ? "border-radius: 6px;" : "";
   return `${fill}${line}${radius}`;
@@ -276,13 +348,16 @@ function textBoxStyle(
   element: ParsedElement,
   widthEmu: number,
   heightEmu: number,
+  refBox: { width: number; height: number },
   themeFont: string | undefined,
 ): string {
   const padding = element.padding;
-  const left = padding ? toSlidePxX(padding.left, widthEmu) : 0;
-  const right = padding ? toSlidePxX(padding.right, widthEmu) : 0;
-  const top = padding ? toSlidePxY(padding.top, heightEmu) : 0;
-  const bottom = padding ? toSlidePxY(padding.bottom, heightEmu) : 0;
+  const left = padding ? toSlidePxX(padding.left, widthEmu, refBox.width) : 0;
+  const right = padding ? toSlidePxX(padding.right, widthEmu, refBox.width) : 0;
+  const top = padding ? toSlidePxY(padding.top, heightEmu, refBox.height) : 0;
+  const bottom = padding
+    ? toSlidePxY(padding.bottom, heightEmu, refBox.height)
+    : 0;
   const align = element.paragraphs?.[0]?.alignment ?? "left";
   const vertical =
     element.verticalAlign === "middle"
@@ -297,37 +372,55 @@ function buildFidelityParagraph(
   paragraph: ParsedParagraph,
   paragraphIndex: number,
   widthEmu: number,
+  refWidthPx: number,
   themeFont: string | undefined,
   defaultFontWeight: number,
 ): string {
   const firstRun = paragraph.runs[0];
-  const fontSize = (firstRun?.fontSize ?? 18) * CSS_PX_PER_POINT;
+  const fontSize = ptToSlidePx(firstRun?.fontSize ?? 18, widthEmu, refWidthPx);
   const lineHeight = paragraph.lineSpacing ?? 1.2;
+  const bulletFontSize = ptToSlidePx(
+    paragraph.bulletSize ?? firstRun?.fontSize ?? 18,
+    widthEmu,
+    refWidthPx,
+  );
   const bullet = paragraph.bulletChar
-    ? `<span aria-hidden="true" style="display:inline-block;width:${fontSize * 0.75}px;min-width:${fontSize * 0.75}px;margin-right:${fontSize * 0.65}px;color:${esc(paragraph.bulletColor ?? firstRun?.color ?? DEFAULT_PPTX_FOREGROUND)};font-family:${cssFontFamily(paragraph.bulletFontFamily ?? themeFont)};font-size:${(paragraph.bulletSize ?? firstRun?.fontSize ?? 18) * CSS_PX_PER_POINT}px;">${esc(paragraph.bulletChar)}</span>`
+    ? `<span aria-hidden="true" style="display:inline-block;width:${fontSize * 0.75}px;min-width:${fontSize * 0.75}px;margin-right:${fontSize * 0.65}px;color:${esc(paragraph.bulletColor ?? firstRun?.color ?? DEFAULT_PPTX_FOREGROUND)};font-family:${cssFontFamily(paragraph.bulletFontFamily ?? themeFont)};font-size:${bulletFontSize}px;">${esc(paragraph.bulletChar)}</span>`
     : "";
   const marginLeft = paragraph.marginLeftEmu
-    ? toSlidePxX(paragraph.marginLeftEmu, widthEmu)
+    ? toSlidePxX(paragraph.marginLeftEmu, widthEmu, refWidthPx)
     : 0;
   const indent = paragraph.indentEmu
-    ? toSlidePxX(paragraph.indentEmu, widthEmu)
+    ? toSlidePxX(paragraph.indentEmu, widthEmu, refWidthPx)
     : 0;
   const spacingBefore = paragraph.spaceBeforePt ?? 0;
   const spacingAfter = paragraph.spaceAfterPt ?? 0;
   const bulletMargin = paragraph.bulletChar ? `margin-left:${indent}px;` : "";
+  const marginBefore = ptToSlidePx(spacingBefore, widthEmu, refWidthPx);
+  const marginAfter = ptToSlidePx(spacingAfter, widthEmu, refWidthPx);
   const text = paragraph.runs
-    .map((run) => formatFidelityRun(run, themeFont, defaultFontWeight))
+    .map((run) =>
+      formatFidelityRun(
+        run,
+        widthEmu,
+        refWidthPx,
+        themeFont,
+        defaultFontWeight,
+      ),
+    )
     .join("");
-  return `<p data-pptx-paragraph="${paragraphIndex}" style="display:block;flex:0 0 auto;text-align:${paragraph.alignment ?? "left"};white-space:pre-wrap;margin:${spacingBefore * CSS_PX_PER_POINT}px 0 ${spacingAfter * CSS_PX_PER_POINT}px;line-height:${lineHeight};font-size:${fontSize}px;min-height:${fontSize * lineHeight}px;padding-left:${marginLeft}px;text-indent:${paragraph.bulletChar ? 0 : indent}px;">${bullet.replace("display:inline-block;", `display:inline-block;${bulletMargin}`)}${text}</p>`;
+  return `<p data-pptx-paragraph="${paragraphIndex}" style="display:block;flex:0 0 auto;text-align:${paragraph.alignment ?? "left"};white-space:pre-wrap;margin:${marginBefore}px 0 ${marginAfter}px;line-height:${lineHeight};font-size:${fontSize}px;min-height:${fontSize * lineHeight}px;padding-left:${marginLeft}px;text-indent:${paragraph.bulletChar ? 0 : indent}px;">${bullet.replace("display:inline-block;", `display:inline-block;${bulletMargin}`)}${text}</p>`;
 }
 
 function formatFidelityRun(
   run: ParsedTextRun,
+  widthEmu: number,
+  refWidthPx: number,
   themeFont: string | undefined,
   defaultFontWeight = 400,
 ): string {
   const styles = [
-    `font-size:${(run.fontSize ?? 18) * CSS_PX_PER_POINT}px`,
+    `font-size:${ptToSlidePx(run.fontSize ?? 18, widthEmu, refWidthPx)}px`,
     `font-family:${cssFontFamily(run.fontFamily ?? themeFont)}`,
     `color:${esc(run.color ?? DEFAULT_PPTX_FOREGROUND)}`,
     `font-weight:${run.bold ? 700 : fontWeightForFamily(run.fontFamily, defaultFontWeight)}`,

package/corpus/templates/slides/server/handlers/import/pdf-fidelity-parser.ts

@@ -380,14 +380,23 @@ export function mergeLineRuns(items: TextRunBox[]): TextRunBox[] {
       prev.italic === item.italic &&
       prev.underline === item.underline &&
       prev.href === item.href;
+    const needsSpace =
+      prev !== undefined && item.left - prev.right > item.fontSize * 0.25;
     if (prev && sameStyle) {
-      const needsSpace = item.left - prev.right > item.fontSize * 0.25;
       prev.text += (needsSpace ? " " : "") + item.text;
       prev.right = Math.max(prev.right, item.right);
       prev.top = Math.min(prev.top, item.top);
       prev.bottom = Math.max(prev.bottom, item.bottom);
     } else {
-      runs.push({ ...item });
+      // A word-sized gap has to survive a style change too. Only the
+      // same-style branch used to re-add it, so a heading whose colour
+      // changed mid-line ("7 Air " + "purifying") lost the space at the
+      // boundary and rendered as one jammed-together word.
+      const separator =
+        needsSpace && !/\s$/.test(prev?.text ?? "") && !/^\s/.test(item.text)
+          ? " "
+          : "";
+      runs.push({ ...item, text: separator + item.text });
     }
   }
   return runs;

package/corpus/templates/slides/server/lib/chat-attachments.ts

@@ -119,7 +119,7 @@ export async function prepareSlidesChatAttachments(args: {
           "",
           "File handling rules:",
           "- If the request refers to the current or visible deck, call `view-screen` first to confirm the active deckId, then pass that deckId to import or slide-edit actions.",
-          '- PPTX files: when the user wants the visible deck improved, call `import-pptx --filePath "<path>" --deckId <deckId>` first, then edit those imported slide IDs in place with update-slide. Do not rebuild the source deck with add-slide.',
+          '- PPTX files: when the user wants the visible deck improved, call `import-pptx --filePath "<path>" --deckId <deckId>` first, then use one patch-deck call with requireAllSourceSlides=true and one content patch per imported slide for a deck-wide restyle. Use update-slide only for a targeted one-slide edit. Do not rebuild the source deck with add-slide.',
           '- PDF and DOCX files: call `import-file --filePath "<path>" --format auto --deckId <deckId>` and use the returned extracted text as source material before creating editable slides. For a visual PDF that the user wants preserved, beautified, or restyled from its original layout, pass `--importIntoDeck true` so each page is imported source-faithfully first; keep the full-page image and style around it, with source text persisted in slide notes for inspection.',
           '- Figma `.fig` files: call `import-file --filePath "<path>" --format fig` to start Builder design-system indexing. Do not create a local design system directly from the upload.',
           "- For deck-generation requests, start mutating promptly: create or update the first slide as soon as source material is extracted, then continue slide-by-slide with add-slide/update-slide.",

package/corpus/templates/slides/server/lib/fetch-remote-image.ts

@@ -0,0 +1,192 @@
+import { lookup as dnsLookup, type LookupAddress } from "node:dns";
+import http from "node:http";
+import https from "node:https";
+import type { LookupFunction } from "node:net";
+
+import {
+  isPrivateAddress,
+  MAX_PROXIED_IMAGE_BYTES,
+  MAX_PROXY_REDIRECTS,
+  parseProxyableImageUrl,
+} from "./image-proxy-url.js";
+
+export type RemoteImageFailure =
+  | "unsupported-url"
+  | "blocked-address"
+  | "fetch-failed"
+  | "too-many-redirects"
+  | "not-an-image"
+  | "too-large";
+
+export type RemoteImageResult =
+  | { ok: true; contentType: string; body: Buffer }
+  | { ok: false; reason: RemoteImageFailure };
+
+const REQUEST_TIMEOUT_MS = 15_000;
+
+/**
+ * A `lookup` implementation that only ever hands the socket an address we have
+ * classified as public.
+ *
+ * Validating the hostname separately and then calling `fetch` leaves a gap: the
+ * two resolutions are independent, so a DNS-rebinding host can answer with a
+ * public address for the check and a loopback or metadata address for the
+ * actual connection. Because Node passes this straight to `net.connect`, the
+ * address that is checked here is the address that gets dialled.
+ */
+export const publicOnlyLookup: LookupFunction = (
+  hostname,
+  options,
+  callback,
+) => {
+  const wantsAll =
+    typeof options === "object" && options !== null && options.all === true;
+  const hints = typeof options === "object" && options !== null ? options : {};
+
+  dnsLookup(hostname, { ...hints, all: true }, (err, addresses) => {
+    if (err) {
+      (callback as (e: NodeJS.ErrnoException) => void)(err);
+      return;
+    }
+    const safe = (addresses as LookupAddress[]).filter(
+      (entry) => !isPrivateAddress(entry.address),
+    );
+    if (safe.length === 0) {
+      const blocked: NodeJS.ErrnoException = new Error(
+        `Refusing to connect to a non-public address for ${hostname}`,
+      );
+      blocked.code = "EBLOCKED";
+      (callback as (e: NodeJS.ErrnoException) => void)(blocked);
+      return;
+    }
+    if (wantsAll) {
+      (callback as unknown as (e: null, a: LookupAddress[]) => void)(
+        null,
+        safe,
+      );
+      return;
+    }
+    callback(null, safe[0].address, safe[0].family);
+  });
+};
+
+interface HopResult {
+  status: number;
+  headers: http.IncomingHttpHeaders;
+  read: () => Promise<Buffer | "too-large">;
+  discard: () => void;
+}
+
+function requestHop(target: URL): Promise<HopResult> {
+  return new Promise<HopResult>((resolve, reject) => {
+    const transport = target.protocol === "https:" ? https : http;
+    const request = transport.request(
+      target,
+      {
+        method: "GET",
+        headers: { Accept: "image/*" },
+        lookup: publicOnlyLookup,
+      },
+      (response) => {
+        resolve({
+          status: response.statusCode ?? 0,
+          headers: response.headers,
+          discard: () => response.destroy(),
+          read: () =>
+            new Promise<Buffer | "too-large">((resolveBody, rejectBody) => {
+              const chunks: Buffer[] = [];
+              let total = 0;
+              response.on("data", (chunk: Buffer) => {
+                total += chunk.length;
+                // Stop at the cap instead of buffering first and measuring
+                // after: a chunked response, or one that lies about
+                // Content-Length, would otherwise pull the whole body into
+                // memory before anyone checks it.
+                if (total > MAX_PROXIED_IMAGE_BYTES) {
+                  response.destroy();
+                  resolveBody("too-large");
+                  return;
+                }
+                chunks.push(chunk);
+              });
+              response.on("end", () => resolveBody(Buffer.concat(chunks)));
+              response.on("error", rejectBody);
+            }),
+        });
+      },
+    );
+
+    request.setTimeout(REQUEST_TIMEOUT_MS, () => {
+      request.destroy(new Error("Timed out fetching image"));
+    });
+    request.on("error", reject);
+    request.end();
+  });
+}
+
+/**
+ * Fetch a remote image for the proxy route. Every hop is re-parsed against the
+ * URL policy and every connection is pinned to a validated public address.
+ */
+export async function fetchRemoteImage(
+  raw: string,
+): Promise<RemoteImageResult> {
+  const firstTarget = parseProxyableImageUrl(raw);
+  if (!firstTarget) return { ok: false, reason: "unsupported-url" };
+  let target: URL = firstTarget;
+
+  for (let hop = 0; hop <= MAX_PROXY_REDIRECTS; hop++) {
+    let response: HopResult;
+    try {
+      response = await requestHop(target);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException)?.code;
+      return {
+        ok: false,
+        reason: code === "EBLOCKED" ? "blocked-address" : "fetch-failed",
+      };
+    }
+
+    if (response.status >= 300 && response.status < 400) {
+      response.discard();
+      const location = response.headers.location;
+      const next: URL | null = location
+        ? parseProxyableImageUrl(new URL(location, target).href)
+        : null;
+      if (!next) return { ok: false, reason: "fetch-failed" };
+      target = next;
+      continue;
+    }
+
+    if (response.status < 200 || response.status >= 300) {
+      response.discard();
+      return { ok: false, reason: "fetch-failed" };
+    }
+
+    const contentType = String(response.headers["content-type"] ?? "");
+    if (!contentType.startsWith("image/")) {
+      response.discard();
+      return { ok: false, reason: "not-an-image" };
+    }
+
+    const declared = Number(response.headers["content-length"]);
+    if (Number.isFinite(declared) && declared > MAX_PROXIED_IMAGE_BYTES) {
+      response.discard();
+      return { ok: false, reason: "too-large" };
+    }
+
+    let body: Buffer | "too-large";
+    try {
+      body = await response.read();
+    } catch {
+      // coercion-ok: a truncated transfer has no partial-success form here;
+      // the caller answers 502 either way.
+      return { ok: false, reason: "fetch-failed" };
+    }
+    if (body === "too-large") return { ok: false, reason: "too-large" };
+
+    return { ok: true, contentType, body };
+  }
+
+  return { ok: false, reason: "too-many-redirects" };
+}