@pylonsync/functions 0.3.317 → 0.3.319

package/dist/ssr-og-runtime.d.ts

@@ -0,0 +1,25 @@
+export interface OgFont {
+    name: string;
+    data: ArrayBuffer | Buffer | Uint8Array;
+    weight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+    style?: "normal" | "italic";
+}
+export interface RenderOgOptions {
+    width?: number;
+    height?: number;
+    /** Extra/override fonts. When omitted, the bundled Inter (400+600) is used. */
+    fonts?: OgFont[];
+    /**
+     * Emoji provider passthrough for Satori (`graphemeImages` / `loadAdditionalAsset`).
+     * Left undefined by default — emoji render as tofu unless the app supplies fonts.
+     */
+    loadAdditionalAsset?: (code: string, text: string) => Promise<string> | string;
+}
+/**
+ * Render a React element to a PNG buffer via Satori + resvg.
+ *
+ * `element` is whatever the user's `opengraph-image.tsx` produced — a React
+ * element created by the *user's* react. Satori consumes it structurally
+ * (by `type`/`props`), so the react instance doesn't matter.
+ */
+export declare function renderOgImage(element: unknown, options?: RenderOgOptions): Promise<Uint8Array>;

package/dist/ssr-runtime.d.ts

@@ -335,7 +335,7 @@ export declare function isSafeRedirect(url: string, opts: {
 /** Merge auto-discovered favicons (icon.* / apple-icon.* / favicon.ico)
  *  into a page's metadata. Explicit `metadata.icons.*` wins. */
 export declare function applyAutoIcons(component: string, metadata: SsrMetadata | undefined): SsrMetadata | undefined;
-export declare function applyAutoSocialImages(component: string, headers: Record<string, string> | undefined, metadata: SsrMetadata | undefined): SsrMetadata | undefined;
+export declare function applyAutoSocialImages(component: string, headers: Record<string, string> | undefined, metadata: SsrMetadata | undefined, requestUrl?: string): SsrMetadata | undefined;
 /**
  * Dev-only tail chunk: the `__PYLON_DEV__` info blob (cache verdict, render
  * mode/timing, route) + the HUD bootstrap. Embedded after the page tail so the
@@ -541,5 +541,14 @@ export declare function serializeRobots(robots: Robots | undefined): string;
  * runner). 1-hour cache — sitemaps/robots change rarely; tune via a CDN.
  */
 export declare function handleDataRoute(msg: RenderRouteMessage, kind: "sitemap" | "robots", send: Send): Promise<void>;
+/**
+ * Import an `opengraph-image.tsx`, call its default export, render the
+ * returned `ImageResponse` (or raw React element) to a PNG via Satori +
+ * resvg (see `./ssr-og-runtime`), and stream the bytes back with an image
+ * content-type. This is the code path behind the `opengraph-image` file
+ * convention (Next.js `next/og` parity). Errors surface as a 500 with a
+ * short plain-text body so a broken OG module doesn't wedge the runner.
+ */
+export declare function handleOgImageRoute(msg: RenderRouteMessage, send: Send): Promise<void>;
 export declare function handleRenderRoute(msg: RenderRouteMessage, send: Send): Promise<void>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.317",
+  "version": "0.3.319",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",
@@ -44,6 +44,10 @@
     "database"
   ],
   "license": "MIT OR Apache-2.0",
+  "dependencies": {
+    "satori": "^0.26.0",
+    "@resvg/resvg-wasm": "^2.6.2"
+  },
   "devDependencies": {
     "typescript": "^5.5",
     "react": "^19.0.0",

package/src/ssr-og-image.test.ts

@@ -0,0 +1,164 @@
+// Tests for the dynamic OG image convention (app/**/opengraph-image.tsx →
+// PNG, Next.js `next/og` parity): the render engine (`renderOgImage`, the
+// Satori→resvg pipeline) plus `handleOgImageRoute` end-to-end — import a temp
+// module, render, and emit the response_start/chunk/done protocol with an
+// image content-type. Fixtures live UNDER this package dir so their
+// `import React from "react"` / `@pylonsync/react` resolve via workspace
+// walk-up (an os.tmpdir() fixture has no node_modules to reach).
+
+import { afterEach, describe, expect, test } from "bun:test";
+import * as React from "react";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { renderOgImage } from "./ssr-og-runtime";
+import { handleOgImageRoute, type RenderRouteMessage } from "./ssr-runtime";
+
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const isPng = (b: Uint8Array): boolean =>
+  Buffer.from(b.subarray(0, 8)).equals(PNG_MAGIC);
+// PNG IHDR: 8-byte signature, then len(4)+"IHDR"(4)+width(4 BE)+height(4 BE).
+const pngSize = (b: Uint8Array): { w: number; h: number } => {
+  const buf = Buffer.from(b);
+  return { w: buf.readUInt32BE(16), h: buf.readUInt32BE(20) };
+};
+
+describe("renderOgImage (Satori → resvg pipeline)", () => {
+  test("renders a React element to a PNG of the requested size", async () => {
+    const el = React.createElement(
+      "div",
+      {
+        style: {
+          display: "flex",
+          width: "100%",
+          height: "100%",
+          alignItems: "center",
+          justifyContent: "center",
+          fontFamily: "Inter",
+          fontSize: 48,
+          color: "#0f172a",
+          background: "#ffffff",
+        },
+      },
+      "Hello OG",
+    );
+    const png = await renderOgImage(el, { width: 600, height: 400 });
+    expect(isPng(png)).toBe(true);
+    expect(png.byteLength).toBeGreaterThan(1000);
+    expect(pngSize(png)).toEqual({ w: 600, h: 400 });
+  });
+
+  test("defaults to 1200×630 when no size is given", async () => {
+    const el = React.createElement(
+      "div",
+      { style: { display: "flex", fontFamily: "Inter", fontSize: 40 } },
+      "Default size",
+    );
+    const png = await renderOgImage(el);
+    expect(pngSize(png)).toEqual({ w: 1200, h: 630 });
+  });
+});
+
+describe("handleOgImageRoute (end-to-end import + render)", () => {
+  const baseDir = path.dirname(fileURLToPath(import.meta.url));
+  const tmpdirs: string[] = [];
+  const prevCwd = process.cwd();
+  afterEach(() => {
+    process.chdir(prevCwd);
+    for (const d of tmpdirs.splice(0)) {
+      try {
+        fs.rmSync(d, { recursive: true, force: true });
+      } catch {
+        /* best effort */
+      }
+    }
+  });
+
+  function fixture(src: string): void {
+    const dir = fs.mkdtempSync(path.join(baseDir, "og-fixture-"));
+    tmpdirs.push(dir);
+    fs.mkdirSync(path.join(dir, "app"), { recursive: true });
+    fs.writeFileSync(path.join(dir, "app", "opengraph-image.tsx"), src);
+    process.chdir(dir);
+  }
+
+  const collect = async (): Promise<any[]> => {
+    const sent: any[] = [];
+    const msg = {
+      component: "app/opengraph-image",
+      call_id: "og1",
+      params: {},
+      search_params: {},
+    } as unknown as RenderRouteMessage;
+    await handleOgImageRoute(msg, (m) => sent.push(m));
+    return sent;
+  };
+
+  test("ImageResponse default export → 200 image/png with the rendered bytes", async () => {
+    // The fixture returns the exact shape `new ImageResponse(el, opts)`
+    // produces — the `__pylonImageResponse` brand + `element`/`options` — so
+    // this asserts the runtime's structural contract without pulling the
+    // whole @pylonsync/react barrel into a temp module. The real
+    // `ImageResponse` integration is covered by the live acme e2e.
+    fixture(
+      `import React from "react";
+       export default function OG() {
+         return {
+           __pylonImageResponse: true,
+           element: React.createElement("div",
+             { style: { display: "flex", width: "100%", height: "100%", fontSize: 40, fontFamily: "Inter" } },
+             "Branded"),
+           options: { width: 500, height: 300, headers: { "cache-control": "public, max-age=60" } },
+         };
+       }`,
+    );
+    const sent = await collect();
+    const start = sent.find((m) => m.type === "response_start");
+    const chunk = sent.find((m) => m.type === "render_chunk");
+    expect(start.status).toBe(200);
+    expect(start.headers["content-type"]).toBe("image/png");
+    // options.headers override the default cache-control.
+    expect(start.headers["cache-control"]).toBe("public, max-age=60");
+    const png = new Uint8Array(Buffer.from(chunk.data, "base64"));
+    expect(isPng(png)).toBe(true);
+    expect(pngSize(png)).toEqual({ w: 500, h: 300 });
+    expect(sent.some((m) => m.type === "render_done")).toBe(true);
+  });
+
+  test("bare React element + `export const size` also renders", async () => {
+    fixture(
+      `import React from "react";
+       export const size = { width: 640, height: 360 };
+       export default function OG() {
+         return React.createElement("div",
+           { style: { display: "flex", fontSize: 32, fontFamily: "Inter" } }, "Bare");
+       }`,
+    );
+    const sent = await collect();
+    const start = sent.find((m) => m.type === "response_start");
+    const png = new Uint8Array(
+      Buffer.from(sent.find((m) => m.type === "render_chunk").data, "base64"),
+    );
+    expect(start.status).toBe(200);
+    expect(start.headers["content-type"]).toBe("image/png");
+    // default cache-control applies when the module set none.
+    expect(start.headers["cache-control"]).toContain("public");
+    expect(pngSize(png)).toEqual({ w: 640, h: 360 });
+  });
+
+  test("a throwing opengraph-image surfaces as 500 text/plain (no wedge)", async () => {
+    fixture(
+      `export default function OG() { throw new Error("boom"); }`,
+    );
+    const sent = await collect();
+    const start = sent.find((m) => m.type === "response_start");
+    const body = Buffer.from(
+      sent.find((m) => m.type === "render_chunk").data,
+      "base64",
+    ).toString("utf8");
+    expect(start.status).toBe(500);
+    expect(start.headers["content-type"]).toContain("text/plain");
+    expect(body).toContain("boom");
+    expect(sent.some((m) => m.type === "render_done")).toBe(true);
+  });
+});

package/src/ssr-og-runtime.ts

@@ -0,0 +1,137 @@
+// ---------------------------------------------------------------------------
+// Dynamic OpenGraph image rendering — the JSX → PNG pipeline.
+//
+// This is the server-only engine behind the `opengraph-image.tsx` file
+// convention (Next.js `next/og` parity). A user module default-exports a
+// function returning an `ImageResponse` (or a raw React element); the SSR
+// runner calls it, hands the element here, and we:
+//
+//   1. Satori renders the React element tree to an SVG string. Satori is a
+//      flexbox-only layout engine — multi-child nodes need explicit
+//      `display: flex` (documented; same constraint as next/og).
+//   2. resvg (WASM) rasterizes the SVG to a PNG.
+//
+// Both deps resolve from the FRAMEWORK's node_modules (this file lives under
+// /pylon/packages/functions/src, so a bare import walks up to /pylon/
+// node_modules) — deliberately NOT the user cwd (unlike react/react-dom).
+// resvg is the WASM build (`@resvg/resvg-wasm`); the native napi build is
+// unreliable under Bun. WASM under Bun is proven by loro-crdt in the same
+// runtime.
+//
+// Fonts: Satori CANNOT synthesize text without a font buffer, and cannot
+// parse woff2 or variable fonts. We bundle static Inter (400 + 600) as the
+// default; apps override via `ImageResponse`'s `fonts` option.
+// ---------------------------------------------------------------------------
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+// Satori's font descriptor.
+export interface OgFont {
+	name: string;
+	data: ArrayBuffer | Buffer | Uint8Array;
+	weight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+	style?: "normal" | "italic";
+}
+
+export interface RenderOgOptions {
+	width?: number;
+	height?: number;
+	/** Extra/override fonts. When omitted, the bundled Inter (400+600) is used. */
+	fonts?: OgFont[];
+	/**
+	 * Emoji provider passthrough for Satori (`graphemeImages` / `loadAdditionalAsset`).
+	 * Left undefined by default — emoji render as tofu unless the app supplies fonts.
+	 */
+	loadAdditionalAsset?: (
+		code: string,
+		text: string,
+	) => Promise<string> | string;
+}
+
+const DEFAULT_WIDTH = 1200;
+const DEFAULT_HEIGHT = 630;
+
+// ---- lazy, memoized module + wasm init -----------------------------------
+// satori + resvg are only pulled in when an OG render actually happens, and
+// the wasm is initialized exactly once per Bun process (init is not
+// re-entrant — a second initWasm throws).
+
+let satoriMod: Promise<typeof import("satori")> | null = null;
+function loadSatori() {
+	if (!satoriMod) satoriMod = import("satori");
+	return satoriMod;
+}
+
+let resvgReady: Promise<typeof import("@resvg/resvg-wasm")> | null = null;
+function loadResvg() {
+	if (!resvgReady) {
+		resvgReady = (async () => {
+			const mod = await import("@resvg/resvg-wasm");
+			// Locate the wasm binary next to the package entry and init once.
+			const entry = fileURLToPath(import.meta.resolve("@resvg/resvg-wasm"));
+			const wasmPath = entry.replace(/index\.[^/]+$/, "index_bg.wasm");
+			await mod.initWasm(readFileSync(wasmPath));
+			return mod;
+		})();
+	}
+	return resvgReady;
+}
+
+// ---- default fonts (bundled static Inter) --------------------------------
+
+let defaultFonts: OgFont[] | null = null;
+function loadDefaultFonts(): OgFont[] {
+	if (defaultFonts) return defaultFonts;
+	const read = (rel: string) =>
+		readFileSync(fileURLToPath(new URL(rel, import.meta.url)));
+	defaultFonts = [
+		{
+			name: "Inter",
+			data: read("../assets/fonts/Inter-Regular.ttf"),
+			weight: 400,
+			style: "normal",
+		},
+		{
+			name: "Inter",
+			data: read("../assets/fonts/Inter-SemiBold.ttf"),
+			weight: 600,
+			style: "normal",
+		},
+	];
+	return defaultFonts;
+}
+
+/**
+ * Render a React element to a PNG buffer via Satori + resvg.
+ *
+ * `element` is whatever the user's `opengraph-image.tsx` produced — a React
+ * element created by the *user's* react. Satori consumes it structurally
+ * (by `type`/`props`), so the react instance doesn't matter.
+ */
+export async function renderOgImage(
+	element: unknown,
+	options: RenderOgOptions = {},
+): Promise<Uint8Array> {
+	const width = options.width ?? DEFAULT_WIDTH;
+	const height = options.height ?? DEFAULT_HEIGHT;
+	const fonts = options.fonts?.length ? options.fonts : loadDefaultFonts();
+
+	const { default: satori } = await loadSatori();
+	// Satori's types want ReactNode; the element is structurally compatible.
+	const svg = await satori(element as never, {
+		width,
+		height,
+		fonts: fonts as never,
+		// Our public type is friendlier (sync-or-async → string); Satori's exact
+		// signature is stricter but tolerant at runtime.
+		loadAdditionalAsset: options.loadAdditionalAsset as never,
+	});
+
+	const { Resvg } = await loadResvg();
+	const resvg = new Resvg(svg, {
+		fitTo: { mode: "width", value: width },
+		font: { loadSystemFonts: false },
+	});
+	return resvg.render().asPng();
+}

package/src/ssr-runtime.ts

@@ -816,6 +816,54 @@ function findColocatedImage(
   return null;
 }
 
+const OG_IMAGE_CODE_EXTS = [".tsx", ".ts", ".jsx", ".js"];
+
+/**
+ * Walk up from a page's directory to the nearest colocated dynamic OG
+ * module (`opengraph-image.{tsx,ts,jsx,js}`) and return the CONCRETE
+ * request path that renders it (origin-less), or null.
+ *
+ * The path is derived from the live request URL (`url`), not the file path,
+ * so dynamic params are already substituted:
+ *   - colocated with the page  → `${url}/opengraph-image`
+ *   - an ancestor at depth n    → first n concrete URL segments + `/opengraph-image`
+ *     (root → `/opengraph-image`). Route groups `(x)` don't count toward
+ *     depth; a trailing catch-all only lives at the page's own segment, so
+ *     ancestor slicing stays 1:1 with the URL.
+ * Mirrors `findColocatedImage`'s inheritance walk (closer file wins).
+ */
+function findColocatedOgImageRoute(
+  componentPath: string,
+  url: string,
+): string | null {
+  const fs = require("node:fs");
+  const path = require("node:path");
+  const cwd = process.cwd();
+  let dir = componentPath.replace(/\\/g, "/");
+  dir = dir.includes("/") ? dir.slice(0, dir.lastIndexOf("/")) : "";
+  const pageDir = dir;
+  const urlSegs = url.split("/").filter(Boolean);
+  // Non-route-group segment depth of a cwd-relative dir below `app/`.
+  const nonGroupDepth = (d: string): number => {
+    const segs = d.split("/").filter(Boolean);
+    const appIdx = segs.indexOf("app");
+    const below = appIdx >= 0 ? segs.slice(appIdx + 1) : segs;
+    return below.filter((s) => !(s.startsWith("(") && s.endsWith(")"))).length;
+  };
+  while (dir && dir !== "." && dir !== "/") {
+    for (const ext of OG_IMAGE_CODE_EXTS) {
+      if (fs.existsSync(path.join(cwd, dir, `opengraph-image${ext}`))) {
+        const prefix =
+          dir === pageDir ? urlSegs : urlSegs.slice(0, nonGroupDepth(dir));
+        return "/" + [...prefix, "opengraph-image"].join("/");
+      }
+    }
+    const slash = dir.lastIndexOf("/");
+    dir = slash >= 0 ? dir.slice(0, slash) : "";
+  }
+  return null;
+}
+
 /** Best-effort JPEG dimensions: scan SOF markers in the first 128KB. */
 function readJpegSize(fs: any, fd: number): { w: number; h: number } | null {
   const CAP = 128 * 1024;
@@ -1090,6 +1138,7 @@ export function applyAutoSocialImages(
   component: string,
   headers: Record<string, string> | undefined,
   metadata: SsrMetadata | undefined,
+  requestUrl?: string,
 ): SsrMetadata | undefined {
   const hasOg = !!metadata?.openGraph?.image;
   const hasTw = !!metadata?.twitter?.image;
@@ -1099,7 +1148,16 @@ export function applyAutoSocialImages(
   const twFile = hasTw
     ? null
     : findColocatedImage(component, "twitter-image") ?? ogFile;
-  if (!ogFile && !twFile) return metadata;
+
+  // Dynamic (code) OG image: `app/**/opengraph-image.{tsx,ts,jsx,js}`. Only a
+  // fallback when there's no explicit metadata image and no static raster —
+  // a static file colocated at the same/closer level wins (Next parity).
+  const ogRoute =
+    hasOg || ogFile || requestUrl == null
+      ? null
+      : findColocatedOgImageRoute(component, requestUrl);
+
+  if (!ogFile && !twFile && !ogRoute) return metadata;
 
   const origin = resolveRequestOrigin(headers);
   const urlFor = (rel: string, v: number): string =>
@@ -1117,15 +1175,34 @@ export function applyAutoSocialImages(
       ...(m.height ? { imageHeight: m.height } : {}),
       ...(url.startsWith("https:") ? { imageSecureUrl: url } : {}),
     };
-  }
-  if (twFile && !hasTw) {
-    const m = readSocialImageMeta(twFile);
-    out.twitter = {
-      card: "summary_large_image",
-      ...(out.twitter ?? {}),
-      image: urlFor(twFile, m.v),
+  } else if (ogRoute && !hasOg) {
+    const url = `${origin}${ogRoute}`;
+    out.openGraph = {
+      ...(out.openGraph ?? {}),
+      image: url,
+      imageType: "image/png",
+      imageWidth: 1200,
+      imageHeight: 630,
+      ...(url.startsWith("https:") ? { imageSecureUrl: url } : {}),
     };
   }
+  // Twitter falls back to the OG image (static file first, then dynamic route).
+  if (!hasTw) {
+    if (twFile) {
+      const m = readSocialImageMeta(twFile);
+      out.twitter = {
+        card: "summary_large_image",
+        ...(out.twitter ?? {}),
+        image: urlFor(twFile, m.v),
+      };
+    } else if (ogRoute) {
+      out.twitter = {
+        card: "summary_large_image",
+        ...(out.twitter ?? {}),
+        image: `${origin}${ogRoute}`,
+      };
+    }
+  }
   return out;
 }
 
@@ -2404,6 +2481,106 @@ export async function handleDataRoute(
   }
 }
 
+/**
+ * Import an `opengraph-image.tsx`, call its default export, render the
+ * returned `ImageResponse` (or raw React element) to a PNG via Satori +
+ * resvg (see `./ssr-og-runtime`), and stream the bytes back with an image
+ * content-type. This is the code path behind the `opengraph-image` file
+ * convention (Next.js `next/og` parity). Errors surface as a 500 with a
+ * short plain-text body so a broken OG module doesn't wedge the runner.
+ */
+export async function handleOgImageRoute(
+  msg: RenderRouteMessage,
+  send: Send,
+): Promise<void> {
+  const emitError = (status: number, body: string): void => {
+    send({
+      type: "response_start",
+      call_id: msg.call_id,
+      status,
+      headers: { "content-type": "text/plain; charset=utf-8" },
+    });
+    send({
+      type: "render_chunk",
+      call_id: msg.call_id,
+      data: Buffer.from(body, "utf8").toString("base64"),
+    });
+    send({ type: "render_done", call_id: msg.call_id });
+  };
+  try {
+    const cwd = process.cwd();
+    const mod = await importModule(cwd, msg.component);
+    const exp = mod.default ?? mod.Image ?? mod.image;
+    if (exp == null) {
+      throw new Error(
+        `opengraph-image module "${msg.component}" has no default export`,
+      );
+    }
+    // Next passes `{ params }`; we also hand `searchParams` for query-driven
+    // cards. A non-function default (a pre-built element/response) is used
+    // as-is.
+    const produced =
+      typeof exp === "function"
+        ? await exp({ params: msg.params, searchParams: msg.search_params })
+        : exp;
+
+    // The default export may return an `ImageResponse` (element + options)
+    // or a bare React element. Detect the former structurally (brand set by
+    // @pylonsync/react — no cross-package import / instanceof needed).
+    const isImageResponse =
+      produced != null &&
+      typeof produced === "object" &&
+      (produced as { __pylonImageResponse?: unknown }).__pylonImageResponse ===
+        true;
+    const element = isImageResponse
+      ? (produced as { element: unknown }).element
+      : produced;
+    const options = isImageResponse
+      ? ((produced as { options?: Record<string, any> }).options ?? {})
+      : {};
+
+    // For a bare-element return, honor the Next-style `export const size` /
+    // `export const contentType` module exports.
+    const width = options.width ?? mod.size?.width;
+    const height = options.height ?? mod.size?.height;
+    const contentType =
+      options.contentType ?? mod.contentType ?? "image/png";
+
+    const { renderOgImage } = await import("./ssr-og-runtime");
+    const png = await renderOgImage(element, {
+      width,
+      height,
+      fonts: options.fonts,
+      loadAdditionalAsset: options.loadAdditionalAsset,
+    });
+
+    const headers: Record<string, string> = {
+      "content-type": contentType,
+      // OG cards are expensive to render and change rarely; cache hard at
+      // the CDN. The on-disk ISR layer (serve_via_ssr_rpc) also keys by URL.
+      "cache-control": "public, max-age=3600, s-maxage=86400",
+      ...(options.headers ?? {}),
+    };
+    send({
+      type: "response_start",
+      call_id: msg.call_id,
+      status: 200,
+      headers,
+    });
+    send({
+      type: "render_chunk",
+      call_id: msg.call_id,
+      data: Buffer.from(png).toString("base64"),
+    });
+    send({ type: "render_done", call_id: msg.call_id });
+  } catch (e: any) {
+    emitError(
+      500,
+      `pylon: failed to render opengraph-image (${msg.component}): ${e?.message ?? String(e)}\n`,
+    );
+  }
+}
+
 export async function handleRenderRoute(
   msg: RenderRouteMessage,
   send: Send,
@@ -2423,6 +2600,13 @@ export async function handleRenderRoute(
       : null;
   if (dataKind) return handleDataRoute(msg, dataKind, send);
 
+  // `opengraph-image` (and future `twitter-image`) render to a PNG, not
+  // HTML. Same basename-detection contract: the SDK only registers this
+  // component path for app/**/opengraph-image.*.
+  if (/(^|[\\/])opengraph-image$/.test(msg.component)) {
+    return handleOgImageRoute(msg, send);
+  }
+
   // Dev HUD: wall-clock for the whole render, surfaced in the dev overlay's
   // render row. `performance.now()` is monotonic; harmless in prod (unused).
   const renderStart = isDevMode() ? performance.now() : 0;
@@ -2619,7 +2803,7 @@ export async function handleRenderRoute(
     // File conventions: auto-wire <meta og:image>/<twitter:image> from a
     // colocated opengraph-image.* / twitter-image.*, and <link rel="icon">
     // from icon.* / apple-icon.* / favicon.ico — unless the page set them.
-    metadata = applyAutoSocialImages(msg.component, msg.headers, metadata);
+    metadata = applyAutoSocialImages(msg.component, msg.headers, metadata, msg.url);
     metadata = applyAutoIcons(msg.component, metadata);
     const metaFragment = renderMetadata(React, metadata);