@pylonsync/functions 0.3.239 → 0.3.241

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.239",
+  "version": "0.3.241",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/ssr-runtime.test.ts

@@ -0,0 +1,182 @@
+// Tests for the Next-style `opengraph-image.png` / `twitter-image.png`
+// file convention wired up in `applyAutoSocialImages`.
+import { afterEach, describe, expect, test } from "bun:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { applyAutoIcons, applyAutoSocialImages } from "./ssr-runtime";
+
+// A minimal PNG: 8-byte signature + an IHDR chunk carrying width/height.
+// `readSocialImageMeta` only reads the first 32 bytes, so a full valid
+// PNG isn't required to exercise the dimension reader.
+function pngHeader(w: number, h: number): Buffer {
+  const b = Buffer.alloc(24);
+  b.write("\x89PNG\r\n\x1a\n", 0, "latin1");
+  b.writeUInt32BE(13, 8); // IHDR length
+  b.write("IHDR", 12, "latin1");
+  b.writeUInt32BE(w, 16);
+  b.writeUInt32BE(h, 20);
+  return b;
+}
+
+let prevCwd: string | null = null;
+const tmpDirs: string[] = [];
+
+function makeApp(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pylon-og-"));
+  tmpDirs.push(dir);
+  prevCwd = process.cwd();
+  process.chdir(dir);
+  return dir;
+}
+
+afterEach(() => {
+  if (prevCwd) {
+    process.chdir(prevCwd);
+    prevCwd = null;
+  }
+  for (const d of tmpDirs.splice(0)) {
+    fs.rmSync(d, { recursive: true, force: true });
+  }
+});
+
+describe("opengraph-image file convention", () => {
+  test("auto-injects og:image + twitter:image with dims from a colocated png", () => {
+    const dir = makeApp();
+    fs.mkdirSync(path.join(dir, "app", "blog"), { recursive: true });
+    fs.writeFileSync(
+      path.join(dir, "app", "blog", "opengraph-image.png"),
+      pngHeader(1200, 630),
+    );
+
+    const md = applyAutoSocialImages(
+      "app/blog/page",
+      { host: "example.com" },
+      undefined,
+    );
+
+    expect(md?.openGraph?.image).toContain(
+      "https://example.com/_pylon/og?src=app%2Fblog%2Fopengraph-image.png",
+    );
+    expect(md?.openGraph?.imageType).toBe("image/png");
+    expect(md?.openGraph?.imageWidth).toBe(1200);
+    expect(md?.openGraph?.imageHeight).toBe(630);
+    expect(md?.openGraph?.imageSecureUrl).toBe(md?.openGraph?.image);
+    // Twitter falls back to the og image + a large-summary card.
+    expect(md?.twitter?.card).toBe("summary_large_image");
+    expect(md?.twitter?.image).toContain(
+      "/_pylon/og?src=app%2Fblog%2Fopengraph-image.png",
+    );
+  });
+
+  test("inherits the nearest ancestor image (root app/opengraph-image.png)", () => {
+    const dir = makeApp();
+    fs.mkdirSync(path.join(dir, "app", "deep", "nested"), { recursive: true });
+    fs.writeFileSync(
+      path.join(dir, "app", "opengraph-image.png"),
+      pngHeader(800, 418),
+    );
+
+    const md = applyAutoSocialImages(
+      "app/deep/nested/page",
+      { host: "x.test" },
+      undefined,
+    );
+    expect(md?.openGraph?.image).toContain(
+      "/_pylon/og?src=app%2Fopengraph-image.png",
+    );
+    expect(md?.openGraph?.imageWidth).toBe(800);
+  });
+
+  test("a closer image overrides an ancestor", () => {
+    const dir = makeApp();
+    fs.mkdirSync(path.join(dir, "app", "blog"), { recursive: true });
+    fs.writeFileSync(path.join(dir, "app", "opengraph-image.png"), pngHeader(1, 1));
+    fs.writeFileSync(
+      path.join(dir, "app", "blog", "opengraph-image.png"),
+      pngHeader(1200, 630),
+    );
+    const md = applyAutoSocialImages("app/blog/page", { host: "x.test" }, undefined);
+    expect(md?.openGraph?.image).toContain(
+      "/_pylon/og?src=app%2Fblog%2Fopengraph-image.png",
+    );
+    expect(md?.openGraph?.imageWidth).toBe(1200);
+  });
+
+  test("explicit metadata.openGraph.image always wins", () => {
+    const dir = makeApp();
+    fs.mkdirSync(path.join(dir, "app"), { recursive: true });
+    fs.writeFileSync(path.join(dir, "app", "opengraph-image.png"), pngHeader(1, 1));
+    const md = applyAutoSocialImages(
+      "app/page",
+      { host: "x.test" },
+      { openGraph: { image: "https://cdn.example/custom.png" } },
+    );
+    expect(md?.openGraph?.image).toBe("https://cdn.example/custom.png");
+  });
+
+  test("no colocated image leaves metadata untouched", () => {
+    makeApp(); // empty cwd, no app/ image
+    const input = { title: "Hello" };
+    const md = applyAutoSocialImages("app/page", { host: "x.test" }, input);
+    expect(md).toEqual(input);
+  });
+
+  test("localhost host yields an http (non-secure) absolute URL", () => {
+    const dir = makeApp();
+    fs.mkdirSync(path.join(dir, "app"), { recursive: true });
+    fs.writeFileSync(path.join(dir, "app", "opengraph-image.png"), pngHeader(10, 10));
+    const md = applyAutoSocialImages("app/page", { host: "localhost:4321" }, undefined);
+    expect(md?.openGraph?.image).toContain("http://localhost:4321/_pylon/og?src=");
+    expect(md?.openGraph?.imageSecureUrl).toBeUndefined();
+  });
+});
+
+describe("icon / apple-icon / favicon file convention", () => {
+  test("auto-wires <link rel=icon> + apple-touch-icon (relative URL + sizes)", () => {
+    const dir = makeApp();
+    fs.mkdirSync(path.join(dir, "app"), { recursive: true });
+    fs.writeFileSync(path.join(dir, "app", "icon.png"), pngHeader(512, 512));
+    fs.writeFileSync(path.join(dir, "app", "apple-icon.png"), pngHeader(180, 180));
+
+    const md = applyAutoIcons("app/page", undefined);
+    expect(md?.icons?.icon?.url).toContain("/_pylon/og?src=app%2Ficon.png");
+    expect(md?.icons?.icon?.url.startsWith("/")).toBe(true); // relative
+    expect(md?.icons?.icon?.type).toBe("image/png");
+    expect(md?.icons?.icon?.sizes).toBe("512x512");
+    expect(md?.icons?.apple?.url).toContain("/_pylon/og?src=app%2Fapple-icon.png");
+    expect(md?.icons?.apple?.sizes).toBe("180x180");
+  });
+
+  test("svg icon gets sizes=any; inherits from a parent folder", () => {
+    const dir = makeApp();
+    fs.mkdirSync(path.join(dir, "app", "blog"), { recursive: true });
+    fs.writeFileSync(path.join(dir, "app", "icon.svg"), "<svg/>");
+    const md = applyAutoIcons("app/blog/page", undefined);
+    expect(md?.icons?.icon?.url).toContain("/_pylon/og?src=app%2Ficon.svg");
+    expect(md?.icons?.icon?.type).toBe("image/svg+xml");
+    expect(md?.icons?.icon?.sizes).toBe("any");
+  });
+
+  test("favicon.ico is the icon fallback", () => {
+    const dir = makeApp();
+    fs.mkdirSync(path.join(dir, "app"), { recursive: true });
+    fs.writeFileSync(path.join(dir, "app", "favicon.ico"), Buffer.alloc(8));
+    const md = applyAutoIcons("app/page", undefined);
+    expect(md?.icons?.icon?.url).toContain("/_pylon/og?src=app%2Ffavicon.ico");
+    expect(md?.icons?.icon?.type).toBe("image/x-icon");
+    expect(md?.icons?.icon?.sizes).toBeUndefined(); // .ico is multi-size
+  });
+
+  test("explicit metadata.icons wins; no file → untouched", () => {
+    const dir = makeApp();
+    fs.mkdirSync(path.join(dir, "app"), { recursive: true });
+    fs.writeFileSync(path.join(dir, "app", "icon.png"), pngHeader(1, 1));
+    const explicit = { icons: { icon: { url: "/custom.ico" } } };
+    expect(applyAutoIcons("app/page", explicit)?.icons?.icon?.url).toBe("/custom.ico");
+
+    makeApp(); // fresh empty cwd
+    const input = { title: "T" };
+    expect(applyAutoIcons("app/page", input)).toEqual(input);
+  });
+});

package/src/ssr-runtime.ts

@@ -274,6 +274,14 @@ export interface SsrMetadata {
     title?: string;
     description?: string;
     image?: string;
+    /** `og:image:secure_url` — set automatically to the https image URL. */
+    imageSecureUrl?: string;
+    /** `og:image:type` (e.g. "image/png"). */
+    imageType?: string;
+    /** `og:image:width` / `og:image:height` in pixels. */
+    imageWidth?: number;
+    imageHeight?: number;
+    imageAlt?: string;
     url?: string;
     type?: string;
   };
@@ -283,6 +291,13 @@ export interface SsrMetadata {
     description?: string;
     image?: string;
   };
+  /** `<link rel="icon">` / `<link rel="apple-touch-icon">`. Auto-wired
+   *  from the app/icon.* + app/apple-icon.* + app/favicon.ico file
+   *  conventions, or set explicitly. */
+  icons?: {
+    icon?: { url: string; type?: string; sizes?: string };
+    apple?: { url: string; type?: string; sizes?: string };
+  };
 }
 
 /**
@@ -309,7 +324,14 @@ function renderMetadata(React: any, m: SsrMetadata | undefined): any {
   if (og) {
     if (og.title != null) kids.push(el("meta", { key: "ogt", property: "og:title", content: og.title }));
     if (og.description != null) kids.push(el("meta", { key: "ogd", property: "og:description", content: og.description }));
-    if (og.image) kids.push(el("meta", { key: "ogi", property: "og:image", content: og.image }));
+    if (og.image) {
+      kids.push(el("meta", { key: "ogi", property: "og:image", content: og.image }));
+      if (og.imageSecureUrl) kids.push(el("meta", { key: "ogis", property: "og:image:secure_url", content: og.imageSecureUrl }));
+      if (og.imageType) kids.push(el("meta", { key: "ogit", property: "og:image:type", content: og.imageType }));
+      if (og.imageWidth != null) kids.push(el("meta", { key: "ogiw", property: "og:image:width", content: String(og.imageWidth) }));
+      if (og.imageHeight != null) kids.push(el("meta", { key: "ogih", property: "og:image:height", content: String(og.imageHeight) }));
+      if (og.imageAlt) kids.push(el("meta", { key: "ogia", property: "og:image:alt", content: og.imageAlt }));
+    }
     if (og.url) kids.push(el("meta", { key: "ogu", property: "og:url", content: og.url }));
     if (og.type) kids.push(el("meta", { key: "ogy", property: "og:type", content: og.type }));
   }
@@ -320,6 +342,21 @@ function renderMetadata(React: any, m: SsrMetadata | undefined): any {
     if (tw.description != null) kids.push(el("meta", { key: "twd", name: "twitter:description", content: tw.description }));
     if (tw.image) kids.push(el("meta", { key: "twi", name: "twitter:image", content: tw.image }));
   }
+  const ic = m.icons;
+  if (ic) {
+    if (ic.icon) {
+      const a: Record<string, string> = { key: "icn", rel: "icon", href: ic.icon.url };
+      if (ic.icon.type) a.type = ic.icon.type;
+      if (ic.icon.sizes) a.sizes = ic.icon.sizes;
+      kids.push(el("link", a));
+    }
+    if (ic.apple) {
+      const a: Record<string, string> = { key: "aicn", rel: "apple-touch-icon", href: ic.apple.url };
+      if (ic.apple.type) a.type = ic.apple.type;
+      if (ic.apple.sizes) a.sizes = ic.apple.sizes;
+      kids.push(el("link", a));
+    }
+  }
   return kids.length > 0 ? el(React.Fragment, null, ...kids) : null;
 }
 
@@ -402,6 +439,253 @@ function findBoundary(componentPath: string, fileName: string): string | null {
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// Social-card image file convention (Next-style `opengraph-image.png` /
+// `twitter-image.png` colocated with a `page.tsx`). Drop the file in a
+// route folder and Pylon auto-emits the `<meta og:image>` (absolute URL,
+// dimensions, type) pointing at the `/_pylon/og` asset endpoint — no
+// metadata wiring required. An explicit `metadata.openGraph.image` always
+// wins. Resolved fresh per render off the filesystem (same model as
+// layouts / boundaries) so dropping a new image is picked up without a
+// restart.
+// ---------------------------------------------------------------------------
+
+const SOCIAL_IMAGE_EXTS = [".png", ".jpg", ".jpeg", ".webp", ".gif", ".avif"];
+
+/** Walk up from a page's directory to the nearest colocated
+ *  `<base>.<imgext>` (Next inheritance: a closer file overrides an
+ *  ancestor's). Returns the cwd-relative path WITH extension, or null. */
+function findColocatedImage(
+  componentPath: string,
+  base: string,
+  exts: string[] = SOCIAL_IMAGE_EXTS,
+): 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("/")) : "";
+  while (dir && dir !== "." && dir !== "/") {
+    for (const ext of exts) {
+      if (fs.existsSync(path.join(cwd, dir, `${base}${ext}`))) {
+        return `${dir}/${base}${ext}`;
+      }
+    }
+    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;
+  const buf = Buffer.alloc(CAP);
+  const n = fs.readSync(fd, buf, 0, CAP, 0);
+  if (n < 4 || buf[0] !== 0xff || buf[1] !== 0xd8) return null;
+  let i = 2;
+  while (i + 9 < n) {
+    if (buf[i] !== 0xff) {
+      i++;
+      continue;
+    }
+    let marker = buf[i + 1];
+    while (marker === 0xff && i + 1 < n) {
+      i++;
+      marker = buf[i + 1];
+    }
+    const seg = i + 2;
+    if (seg + 2 > n) break;
+    const len = buf.readUInt16BE(seg);
+    const isSOF =
+      marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+    if (isSOF) {
+      if (seg + 7 <= n) {
+        return { h: buf.readUInt16BE(seg + 3), w: buf.readUInt16BE(seg + 5) };
+      }
+      return null;
+    }
+    if (marker === 0xd9 || marker === 0xda) break; // EOI / SOS
+    i = seg + len;
+  }
+  return null;
+}
+
+/** Content-type + pixel dimensions + mtime for a colocated image. Dims
+ *  are best-effort (PNG/GIF from the header, JPEG via SOF scan). */
+function readSocialImageMeta(relPath: string): {
+  type: string;
+  width?: number;
+  height?: number;
+  v: number;
+} {
+  const fs = require("node:fs");
+  const path = require("node:path");
+  const ext = relPath.slice(relPath.lastIndexOf(".")).toLowerCase();
+  const type =
+    ext === ".png" ? "image/png"
+    : ext === ".jpg" || ext === ".jpeg" ? "image/jpeg"
+    : ext === ".webp" ? "image/webp"
+    : ext === ".gif" ? "image/gif"
+    : ext === ".avif" ? "image/avif"
+    : ext === ".svg" ? "image/svg+xml"
+    : ext === ".ico" ? "image/x-icon"
+    : "application/octet-stream";
+  let width: number | undefined;
+  let height: number | undefined;
+  let v = 0;
+  try {
+    const abs = path.join(process.cwd(), relPath);
+    v = Math.floor(fs.statSync(abs).mtimeMs);
+    const fd = fs.openSync(abs, "r");
+    try {
+      const head = Buffer.alloc(32);
+      fs.readSync(fd, head, 0, 32, 0);
+      if (ext === ".png" && head.toString("latin1", 1, 4) === "PNG") {
+        width = head.readUInt32BE(16); // IHDR: 8 sig + 4 len + 4 "IHDR"
+        height = head.readUInt32BE(20);
+      } else if (ext === ".gif" && head.toString("latin1", 0, 3) === "GIF") {
+        width = head.readUInt16LE(6);
+        height = head.readUInt16LE(8);
+      } else if (ext === ".jpg" || ext === ".jpeg") {
+        const d = readJpegSize(fs, fd);
+        if (d) {
+          width = d.w;
+          height = d.h;
+        }
+      }
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    /* dims/mtime are best-effort */
+  }
+  return { type, width, height, v };
+}
+
+/** Absolute origin for OG URLs (crawlers require absolute). Prefers the
+ *  request Host (works for any custom domain the app serves), falling
+ *  back to PYLON_PUBLIC_URL. Empty string → relative (dev last resort). */
+function resolveRequestOrigin(headers: Record<string, string> | undefined): string {
+  const host = headers?.["host"];
+  if (host) {
+    const proto =
+      headers?.["x-forwarded-proto"] ||
+      (/^(localhost|127\.|\[?::1|0\.0\.0\.0)/.test(host) ? "http" : "https");
+    return `${proto}://${host}`;
+  }
+  const env = ((globalThis as any).process?.env?.PYLON_PUBLIC_URL || "")
+    .trim()
+    .replace(/\/+$/, "");
+  return env;
+}
+
+/** Merge auto-discovered social-card images into a page's metadata. An
+ *  explicit `openGraph.image` / `twitter.image` always wins; otherwise a
+ *  colocated `opengraph-image.*` (and `twitter-image.*`, falling back to
+ *  the og file) is wired in with absolute URL + dimensions. */
+// Icon file conventions. `icon.*` → <link rel="icon">; `apple-icon.*` →
+// <link rel="apple-touch-icon">; `favicon.ico` is the legacy fallback for
+// the icon link. Unlike og:image, icon links use a RELATIVE URL (resolved
+// same-origin by the browser) so no request origin is needed.
+const ICON_EXTS = [".png", ".svg", ".ico", ".jpg", ".jpeg"];
+const APPLE_ICON_EXTS = [".png", ".jpg", ".jpeg"];
+
+/** `sizes` attribute for an icon link: "any" for vector SVG, "WxH" for a
+ *  raster with known dimensions, omitted for .ico (multi-size). */
+function iconSizes(rel: string, m: { width?: number; height?: number }): string | undefined {
+  if (rel.toLowerCase().endsWith(".svg")) return "any";
+  if (m.width && m.height) return `${m.width}x${m.height}`;
+  return undefined;
+}
+
+/** Merge auto-discovered favicons (icon.* / apple-icon.* / favicon.ico)
+ *  into a page's metadata. Explicit `metadata.icons.*` wins. */
+export function applyAutoIcons(
+  component: string,
+  metadata: SsrMetadata | undefined,
+): SsrMetadata | undefined {
+  const hasIcon = !!metadata?.icons?.icon;
+  const hasApple = !!metadata?.icons?.apple;
+  if (hasIcon && hasApple) return metadata;
+
+  const iconFile = hasIcon
+    ? null
+    : findColocatedImage(component, "icon", ICON_EXTS) ??
+      findColocatedImage(component, "favicon", [".ico"]);
+  const appleFile = hasApple
+    ? null
+    : findColocatedImage(component, "apple-icon", APPLE_ICON_EXTS);
+  if (!iconFile && !appleFile) return metadata;
+
+  const linkFor = (rel: string, v: number): string =>
+    `/_pylon/og?src=${encodeURIComponent(rel)}${v ? `&v=${v}` : ""}`;
+  const out: SsrMetadata = { ...(metadata ?? {}) };
+  out.icons = { ...(out.icons ?? {}) };
+
+  if (iconFile && !hasIcon) {
+    const m = readSocialImageMeta(iconFile);
+    const sizes = iconSizes(iconFile, m);
+    out.icons.icon = {
+      url: linkFor(iconFile, m.v),
+      type: m.type,
+      ...(sizes ? { sizes } : {}),
+    };
+  }
+  if (appleFile && !hasApple) {
+    const m = readSocialImageMeta(appleFile);
+    out.icons.apple = {
+      url: linkFor(appleFile, m.v),
+      type: m.type,
+      ...(m.width && m.height ? { sizes: `${m.width}x${m.height}` } : {}),
+    };
+  }
+  return out;
+}
+
+export function applyAutoSocialImages(
+  component: string,
+  headers: Record<string, string> | undefined,
+  metadata: SsrMetadata | undefined,
+): SsrMetadata | undefined {
+  const hasOg = !!metadata?.openGraph?.image;
+  const hasTw = !!metadata?.twitter?.image;
+  if (hasOg && hasTw) return metadata;
+
+  const ogFile = hasOg ? null : findColocatedImage(component, "opengraph-image");
+  const twFile = hasTw
+    ? null
+    : findColocatedImage(component, "twitter-image") ?? ogFile;
+  if (!ogFile && !twFile) return metadata;
+
+  const origin = resolveRequestOrigin(headers);
+  const urlFor = (rel: string, v: number): string =>
+    `${origin}/_pylon/og?src=${encodeURIComponent(rel)}${v ? `&v=${v}` : ""}`;
+  const out: SsrMetadata = { ...(metadata ?? {}) };
+
+  if (ogFile && !hasOg) {
+    const m = readSocialImageMeta(ogFile);
+    const url = urlFor(ogFile, m.v);
+    out.openGraph = {
+      ...(out.openGraph ?? {}),
+      image: url,
+      imageType: m.type,
+      ...(m.width ? { imageWidth: m.width } : {}),
+      ...(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),
+    };
+  }
+  return out;
+}
+
 /**
  * Drain a `renderToReadableStream` reader, injecting `headBlob` immediately
  * before the first `</head>` (or, if the document has none, the blob is
@@ -742,6 +1026,11 @@ export async function handleRenderRoute(
     if (typeof mod.generateMetadata === "function") {
       metadata = await mod.generateMetadata(props);
     }
+    // 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 = applyAutoIcons(msg.component, metadata);
     const metaFragment = renderMetadata(React, metadata);
 
     // Resolve the layout chain. Each layout module exports a default