@pylonsync/functions 0.3.240 → 0.3.241

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.240",
+  "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

@@ -4,7 +4,7 @@ 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 { applyAutoSocialImages } from "./ssr-runtime";
+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
@@ -131,3 +131,52 @@ describe("opengraph-image file convention", () => {
     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

@@ -291,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 };
+  };
 }
 
 /**
@@ -335,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;
 }
 
@@ -433,14 +455,18 @@ 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): string | 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 SOCIAL_IMAGE_EXTS) {
+    for (const ext of exts) {
       if (fs.existsSync(path.join(cwd, dir, `${base}${ext}`))) {
         return `${dir}/${base}${ext}`;
       }
@@ -502,6 +528,8 @@ function readSocialImageMeta(relPath: string): {
     : 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;
@@ -556,6 +584,65 @@ function resolveRequestOrigin(headers: Record<string, string> | undefined): stri
  *  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,
@@ -939,9 +1026,11 @@ export async function handleRenderRoute(
     if (typeof mod.generateMetadata === "function") {
       metadata = await mod.generateMetadata(props);
     }
-    // File convention: auto-wire <meta og:image>/<twitter:image> from a
-    // colocated opengraph-image.* / twitter-image.* unless the page set one.
+    // 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