@ampless/plugin-og-image 0.2.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ampless contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @ampless/plugin-og-image
+
+Dynamic Open Graph image generation for [ampless](https://github.com/heavymoons/ampless). SNS crawlers hit `https://<your-site>/og/<slug>`, the Next.js route renders a JSX card containing the post title + excerpt + site name + an optional image (theme banner or the first image in the post body), and Next.js `ImageResponse` returns a PNG. WebP / AVIF source images are decoded to PNG on the fly via [@jsquash](https://github.com/jamsinclair/jSquash) so Satori can paint them.
+
+> **Pre-release / alpha.** Breaking changes possible in any minor version until v1.0.
+
+## Install
+
+```bash
+npm install @ampless/plugin-og-image@alpha
+```
+
+## Configure
+
+In `cms.config.ts`:
+
+```ts
+import { defineConfig } from 'ampless'
+import ogImagePlugin, { loadFontFromUrl } from '@ampless/plugin-og-image'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    ogImagePlugin({
+      // Required: at least one font. Satori cannot render without one.
+      fonts: [
+        {
+          name: 'Inter',
+          // Lazy loader — runs once per route invocation, then cached
+          // in-process. Ship the .ttf / .otf from your CDN or public/.
+          data: loadFontFromUrl('https://example.com/fonts/Inter-Regular.ttf'),
+          weight: 400,
+        },
+      ],
+      // Image strategy: 'content' (first image in post body) | 'theme'
+      // (use `themeImageUrl`) | 'none' | (post) => url | null
+      image: 'content',
+      // Used when image === 'theme'
+      // themeImageUrl: 'https://example.com/og-banner.png',
+    }),
+  ],
+})
+```
+
+Add the dispatcher route in your Next.js app (the `_shared` template ships one at `app/site/[siteId]/og/[slug]/route.ts`).
+
+## Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `fonts` | required | At least one font must be provided |
+| `size` | `{ width: 1200, height: 630 }` | OG card dimensions |
+| `image` | `'content'` | `'theme'` / `'content'` / `'none'` / `(post) => url \| null` |
+| `themeImageUrl` | none | Used when `image === 'theme'` |
+| `render` | built-in card | Override to fully customize the JSX |
+
+## What it produces
+
+- A `metadata()` hook that injects `openGraph.images: [{ url: '<site>/og/<slug>', width, height }]` into per-post metadata, so SNS crawlers know where to fetch the card.
+- An `ogImage.render(ctx)` that the dispatcher route turns into a PNG via `next/og`.
+
+## Trust level
+
+`untrusted` — runs only in the Next.js request path (no Lambda hooks). No AWS credentials are touched; fonts and post images are fetched over plain HTTPS.
+
+## License
+
+[MIT](../../LICENSE)

package/dist/chunk-BDDYGEJD.js

@@ -0,0 +1,60 @@
+// src/load-image.ts
+function toBase64(bytes) {
+  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64");
+}
+function toArrayBuffer(bytes) {
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+async function decodeWebp(bytes) {
+  try {
+    const webp = await import("@jsquash/webp");
+    const png = await import("@jsquash/png");
+    const imageData = await webp.decode(toArrayBuffer(bytes));
+    const pngBytes = await png.encode(imageData);
+    return `data:image/png;base64,${toBase64(new Uint8Array(pngBytes))}`;
+  } catch (err) {
+    console.error("[plugin-og-image] webp decode failed:", err);
+    return null;
+  }
+}
+async function decodeAvif(bytes) {
+  try {
+    const avif = await import("@jsquash/avif");
+    const png = await import("@jsquash/png");
+    const imageData = await avif.decode(toArrayBuffer(bytes));
+    const pngBytes = await png.encode(imageData);
+    return `data:image/png;base64,${toBase64(new Uint8Array(pngBytes))}`;
+  } catch (err) {
+    console.error("[plugin-og-image] avif decode failed:", err);
+    return null;
+  }
+}
+async function loadImageForOg(url) {
+  let res;
+  try {
+    res = await fetch(url);
+  } catch (err) {
+    console.error("[plugin-og-image] fetch failed:", err);
+    return null;
+  }
+  if (!res.ok) {
+    console.error("[plugin-og-image] fetch non-ok:", res.status, url);
+    return null;
+  }
+  const contentType = (res.headers.get("content-type") ?? "").toLowerCase().split(";")[0].trim();
+  const bytes = new Uint8Array(await res.arrayBuffer());
+  if (contentType === "image/png" || contentType === "image/jpeg" || contentType === "image/jpg") {
+    return `data:${contentType};base64,${toBase64(bytes)}`;
+  }
+  if (contentType === "image/webp") {
+    return decodeWebp(bytes);
+  }
+  if (contentType === "image/avif") {
+    return decodeAvif(bytes);
+  }
+  return null;
+}
+
+export {
+  loadImageForOg
+};

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import { OgImageFont, Post, Config, OgImageRenderContext, AmplessPlugin } from 'ampless';
+import { ReactElement } from 'react';
+export { loadImageForOg } from './load-image.js';
+
+/**
+ * Return a font loader that fetches `url` lazily and caches the result.
+ * Use in `cms.config.ts`:
+ *
+ *     ogImagePlugin({
+ *       fonts: [
+ *         { name: 'Inter', data: loadFontFromUrl('https://.../Inter.ttf') },
+ *       ],
+ *     })
+ */
+declare function loadFontFromUrl(url: string): () => Promise<ArrayBuffer>;
+
+interface DefaultCardProps {
+    title: string;
+    excerpt?: string;
+    siteName: string;
+    /** Optional pre-decoded data URL — produced by loadImageForOg(). */
+    imageDataUrl?: string | null;
+    /** Font name registered with ogImagePlugin's `fonts` array. */
+    fontFamily: string;
+}
+declare function DefaultCard(props: DefaultCardProps): ReactElement;
+
+/**
+ * Image strategy:
+ *  - 'theme'   : use the URL passed in `themeImageUrl`
+ *  - 'content' : use the first image found in the post body
+ *  - 'none'    : never include an image
+ *  - function  : pick the URL yourself (return null to omit)
+ */
+type OgImageStrategy = 'theme' | 'content' | 'none' | ((post: Post, site: Config['site']) => string | null | undefined);
+interface OgImagePluginOptions {
+    fonts: OgImageFont[];
+    size?: {
+        width: number;
+        height: number;
+    };
+    image?: OgImageStrategy;
+    themeImageUrl?: string;
+    /** Override the entire card render. Receives the same context the route hands the plugin. */
+    render?: (ctx: OgImageRenderContext) => Promise<ReactElement> | ReactElement;
+}
+/**
+ * OG image plugin. Contributes:
+ *  - `metadata(post)` → tells SNS crawlers the per-post OG image URL.
+ *  - `ogImage.render(ctx)` → invoked by the dispatcher route at request time.
+ *
+ * The dispatcher route picks the first plugin in `cms.config.plugins`
+ * that has an `ogImage` config, so only register one OG image plugin per site.
+ */
+declare function ogImagePlugin(options: OgImagePluginOptions): AmplessPlugin;
+
+export { DefaultCard, type OgImagePluginOptions, type OgImageStrategy, ogImagePlugin as default, loadFontFromUrl };

package/dist/index.js

@@ -0,0 +1,196 @@
+import {
+  loadImageForOg
+} from "./chunk-BDDYGEJD.js";
+
+// src/index.ts
+import {
+  definePlugin,
+  extractFirstImageUrl
+} from "ampless";
+
+// src/default-card.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+function DefaultCard(props) {
+  const { title, excerpt, siteName, imageDataUrl, fontFamily } = props;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      style: {
+        display: "flex",
+        width: "100%",
+        height: "100%",
+        backgroundColor: "#ffffff",
+        padding: 64,
+        fontFamily
+      },
+      children: [
+        /* @__PURE__ */ jsxs(
+          "div",
+          {
+            style: {
+              display: "flex",
+              flexDirection: "column",
+              justifyContent: "space-between",
+              flex: 1,
+              // Leave room for the image on the right when present, otherwise
+              // let the text occupy the whole card.
+              paddingRight: imageDataUrl ? 48 : 0
+            },
+            children: [
+              /* @__PURE__ */ jsxs("div", { style: { display: "flex", flexDirection: "column" }, children: [
+                /* @__PURE__ */ jsx(
+                  "div",
+                  {
+                    style: {
+                      fontSize: 64,
+                      fontWeight: 700,
+                      color: "#111111",
+                      lineHeight: 1.2,
+                      // Satori has no text-overflow:ellipsis — but it does clip to
+                      // the box. A high lineClamp is the recommended hint.
+                      display: "flex"
+                    },
+                    children: title
+                  }
+                ),
+                excerpt ? /* @__PURE__ */ jsx(
+                  "div",
+                  {
+                    style: {
+                      fontSize: 28,
+                      color: "#555555",
+                      lineHeight: 1.4,
+                      marginTop: 24,
+                      display: "flex"
+                    },
+                    children: excerpt
+                  }
+                ) : null
+              ] }),
+              /* @__PURE__ */ jsx(
+                "div",
+                {
+                  style: {
+                    fontSize: 24,
+                    color: "#888888",
+                    display: "flex"
+                  },
+                  children: siteName
+                }
+              )
+            ]
+          }
+        ),
+        imageDataUrl ? /* @__PURE__ */ jsx(
+          "div",
+          {
+            style: {
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              width: 400,
+              height: 400
+            },
+            children: /* @__PURE__ */ jsx(
+              "img",
+              {
+                src: imageDataUrl,
+                width: 400,
+                height: 400,
+                style: {
+                  width: 400,
+                  height: 400,
+                  borderRadius: 16,
+                  objectFit: "cover"
+                },
+                alt: ""
+              }
+            )
+          }
+        ) : null
+      ]
+    }
+  );
+}
+
+// src/load-font.ts
+var cache = /* @__PURE__ */ new Map();
+function loadFontFromUrl(url) {
+  return () => {
+    const hit = cache.get(url);
+    if (hit) return hit;
+    const promise = fetch(url).then(async (res) => {
+      if (!res.ok) {
+        cache.delete(url);
+        throw new Error(`[plugin-og-image] failed to load font ${url}: HTTP ${res.status}`);
+      }
+      return res.arrayBuffer();
+    });
+    cache.set(url, promise);
+    return promise;
+  };
+}
+
+// src/index.ts
+function pickImageUrl(strategy, themeImageUrl, post, site) {
+  if (typeof strategy === "function") {
+    return strategy(post, site) ?? null;
+  }
+  switch (strategy) {
+    case "theme":
+      return themeImageUrl ?? null;
+    case "content":
+      return extractFirstImageUrl(post);
+    case "none":
+    default:
+      return null;
+  }
+}
+function ogImagePlugin(options) {
+  if (!options.fonts || options.fonts.length === 0) {
+    throw new Error("[plugin-og-image] at least one font must be provided in `fonts`");
+  }
+  const size = options.size ?? { width: 1200, height: 630 };
+  const strategy = options.image ?? "content";
+  const fontFamily = options.fonts[0].name;
+  const defaultRender = async (ctx) => {
+    const url = pickImageUrl(strategy, options.themeImageUrl, ctx.post, ctx.site);
+    const imageDataUrl = url ? await ctx.image(url) : null;
+    return DefaultCard({
+      title: ctx.post.title,
+      excerpt: ctx.post.excerpt,
+      siteName: ctx.site.name,
+      imageDataUrl,
+      fontFamily
+    });
+  };
+  return definePlugin({
+    name: "og-image",
+    apiVersion: 1,
+    trust_level: "untrusted",
+    metadata(post, site) {
+      const baseUrl = site.url.replace(/\/$/, "");
+      const url = `${baseUrl}/og/${post.slug}`;
+      return {
+        openGraph: {
+          images: [{ url, width: size.width, height: size.height }]
+        },
+        twitter: {
+          card: "summary_large_image",
+          images: [url]
+        }
+      };
+    },
+    ogImage: {
+      fonts: options.fonts,
+      size,
+      render: options.render ?? defaultRender
+    }
+  });
+}
+export {
+  DefaultCard,
+  ogImagePlugin as default,
+  loadFontFromUrl,
+  loadImageForOg
+};

package/dist/load-image.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Fetch `url` and return a data URL usable inside Satori JSX.
+ *
+ * Behavior:
+ *  - PNG / JPEG: pass through as a data URL (no re-encode).
+ *  - WebP: decode to ImageData, re-encode to PNG, return data URL.
+ *  - AVIF: same as WebP.
+ *  - GIF / SVG / other: returns null (Satori can't render animated GIFs,
+ *    and SVG isn't supported via the image() helper — embed SVG with the
+ *    Satori `<img src="data:image/svg+xml;...">` form if you need it).
+ *  - Any fetch / decode error: returns null so the OG card still renders
+ *    without an image instead of 500ing the route.
+ */
+declare function loadImageForOg(url: string): Promise<string | null>;
+
+export { loadImageForOg };

package/dist/load-image.js

@@ -0,0 +1,6 @@
+import {
+  loadImageForOg
+} from "./chunk-BDDYGEJD.js";
+export {
+  loadImageForOg
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@ampless/plugin-og-image",
+  "version": "0.2.0-alpha.0",
+  "description": "Dynamic Open Graph image generation plugin for ampless",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./load-image": {
+      "import": "./dist/load-image.js",
+      "types": "./dist/load-image.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heavymoons/ampless.git",
+    "directory": "packages/plugin-og-image"
+  },
+  "homepage": "https://github.com/heavymoons/ampless/tree/main/packages/plugin-og-image#readme",
+  "bugs": "https://github.com/heavymoons/ampless/issues",
+  "dependencies": {
+    "@jsquash/avif": "^1.2.0",
+    "@jsquash/png": "^3.0.0",
+    "@jsquash/webp": "^1.4.0",
+    "ampless": "0.2.0-alpha.0"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0"
+  },
+  "keywords": [
+    "ampless",
+    "plugin",
+    "og-image",
+    "opengraph"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}