@nifrajs/image 2.9.1 → 2.11.0

package/README.md

@@ -1,9 +1,20 @@
 # @nifrajs/image
 
-Image optimization for nifra - a CLS-safe responsive <Image> + pluggable loaders (CDN or self-hosted) + pure-JS dimension reading. Zero-dependency core; optional Bun.Image-backed resize endpoint at @nifrajs/image/server.
+Image optimization for nifra - a CLS-safe responsive <Image> + pluggable loaders (CDN or self-hosted) + pure-JS dimension reading. The zero-dependency core also includes safe, cacheable Open Graph SVG generation at `@nifrajs/image/og` - useful where you control the consumer, but no major crawler renders SVG for `og:image`, so a social card needs an injected PNG/JPEG rasterizer. The optional Bun.Image-backed resize endpoint lives at `@nifrajs/image/server`.
 
 Part of the **[nifra](https://nifra.dev)** full-stack TypeScript framework - one core, five UI libraries, every runtime. Scaffold a new app with `bun create nifra`.
 
+For crawler-compatible cards, adapt the renderer you choose to the public PNG seam:
+
+```ts
+import { createResvgRasterizer } from "@nifrajs/image/og-png"
+import { Resvg } from "@resvg/resvg-js"
+
+const rasterizer = createResvgRasterizer(Resvg)
+```
+
+The codec remains an application dependency; the package's default stays explicit SVG output.
+
 ## Install
 
 ```sh

package/dist/index.d.ts

@@ -6,5 +6,7 @@
  */
 export { type ImageFormat, type ImageInfo, imageDimensions, readImageDimensions, } from "./dimensions.js";
 export { type HtmlImageAttrs, toHtmlAttrs } from "./html.js";
+export { type OgImageOptions, type OgImageRasterized, type OgImageRasterizer, ogImageResponse, renderOgImage, } from "./og.js";
+export { createPngRasterizer, createResvgRasterizer, type PngRenderer, type ResvgConstructor, type ResvgRenderer, } from "./og-png.js";
 export { type CloudflareLoaderOptions, cloudflareLoader, type ImageLoader, type ImageProps, identityLoader, type ResolvedImage, resolveImage, type SelfHostedLoaderOptions, type SignImageUrlOptions, selfHostedLoader, signImageUrl, } from "./resolve.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,eAAe,EACf,mBAAmB,GACpB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,KAAK,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAC5D,OAAO,EACL,KAAK,uBAAuB,EAC5B,gBAAgB,EAChB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,cAAc,EACd,KAAK,aAAa,EAClB,YAAY,EACZ,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,gBAAgB,EAChB,YAAY,GACb,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,eAAe,EACf,mBAAmB,GACpB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,KAAK,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAC5D,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,eAAe,EACf,aAAa,GACd,MAAM,SAAS,CAAA;AAChB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,KAAK,uBAAuB,EAC5B,gBAAgB,EAChB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,cAAc,EACd,KAAK,aAAa,EAClB,YAAY,EACZ,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,gBAAgB,EAChB,YAAY,GACb,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -6,5 +6,7 @@
  */
 export { imageDimensions, readImageDimensions, } from "./dimensions.js";
 export { toHtmlAttrs } from "./html.js";
+export { ogImageResponse, renderOgImage, } from "./og.js";
+export { createPngRasterizer, createResvgRasterizer, } from "./og-png.js";
 export { cloudflareLoader, identityLoader, resolveImage, selfHostedLoader, signImageUrl, } from "./resolve.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAGL,eAAe,EACf,mBAAmB,GACpB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAuB,WAAW,EAAE,MAAM,WAAW,CAAA;AAC5D,OAAO,EAEL,gBAAgB,EAGhB,cAAc,EAEd,YAAY,EAGZ,gBAAgB,EAChB,YAAY,GACb,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAGL,eAAe,EACf,mBAAmB,GACpB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAuB,WAAW,EAAE,MAAM,WAAW,CAAA;AAC5D,OAAO,EAIL,eAAe,EACf,aAAa,GACd,MAAM,SAAS,CAAA;AAChB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GAItB,MAAM,aAAa,CAAA;AACpB,OAAO,EAEL,gBAAgB,EAGhB,cAAc,EAEd,YAAY,EAGZ,gBAAgB,EAChB,YAAY,GACb,MAAM,cAAc,CAAA"}

package/dist/og-png.d.ts

@@ -0,0 +1,27 @@
+import type { OgImageRasterizer } from "./og.js";
+/** A dependency-free shape implemented by SVG→PNG codecs such as Resvg, Satori, or a WASM backend. */
+export type PngRenderer = (svg: string) => Uint8Array | Promise<Uint8Array>;
+export interface ResvgRenderer {
+    render(): {
+        asPng(): Uint8Array | Promise<Uint8Array>;
+    };
+}
+export type ResvgConstructor = new (svg: string) => ResvgRenderer;
+/**
+ * Adapt an injected SVG→PNG renderer to `ogImageResponse`.
+ *
+ * The renderer stays application-owned because codec/WASM choice is runtime-specific. For example:
+ *
+ * ```ts
+ * import { Resvg } from "@resvg/resvg-js"
+ * import { createPngRasterizer } from "@nifrajs/image/og-png"
+ * const rasterizer = createPngRasterizer((svg) => new Resvg(svg).render().asPng())
+ * ```
+ *
+ * This is the public reference adapter; the core package remains zero-dependency and keeps SVG as its
+ * explicit default for callers that do not opt into a codec.
+ */
+export declare function createPngRasterizer(render: PngRenderer): OgImageRasterizer;
+/** Reference adapter for Resvg-compatible constructors, without making the optional codec a dependency. */
+export declare function createResvgRasterizer(Resvg: ResvgConstructor): OgImageRasterizer;
+//# sourceMappingURL=og-png.d.ts.map

package/dist/og-png.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"og-png.d.ts","sourceRoot":"","sources":["../src/og-png.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAEhD,sGAAsG;AACtG,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;AAE3E,MAAM,WAAW,aAAa;IAC5B,MAAM,IAAI;QAAE,KAAK,IAAI,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;KAAE,CAAA;CACxD;AAED,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,EAAE,MAAM,KAAK,aAAa,CAAA;AAEjE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,iBAAiB,CAE1E;AAED,2GAA2G;AAC3G,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,GAAG,iBAAiB,CAEhF"}

package/dist/og-png.js

@@ -0,0 +1,22 @@
+/**
+ * Adapt an injected SVG→PNG renderer to `ogImageResponse`.
+ *
+ * The renderer stays application-owned because codec/WASM choice is runtime-specific. For example:
+ *
+ * ```ts
+ * import { Resvg } from "@resvg/resvg-js"
+ * import { createPngRasterizer } from "@nifrajs/image/og-png"
+ * const rasterizer = createPngRasterizer((svg) => new Resvg(svg).render().asPng())
+ * ```
+ *
+ * This is the public reference adapter; the core package remains zero-dependency and keeps SVG as its
+ * explicit default for callers that do not opt into a codec.
+ */
+export function createPngRasterizer(render) {
+    return async (svg) => ({ bytes: await render(svg), contentType: "image/png" });
+}
+/** Reference adapter for Resvg-compatible constructors, without making the optional codec a dependency. */
+export function createResvgRasterizer(Resvg) {
+    return createPngRasterizer((svg) => new Resvg(svg).render().asPng());
+}
+//# sourceMappingURL=og-png.js.map

package/dist/og-png.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"og-png.js","sourceRoot":"","sources":["../src/og-png.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAmB;IACrD,OAAO,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAA;AAChF,CAAC;AAED,2GAA2G;AAC3G,MAAM,UAAU,qBAAqB,CAAC,KAAuB;IAC3D,OAAO,mBAAmB,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,CAAA;AACtE,CAAC"}

package/dist/og.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Dependency-free Open Graph image generation.
+ *
+ * **The default SVG output does not work as a social card.** X, Facebook, LinkedIn, Slack, Discord
+ * and iMessage all refuse `image/svg+xml` for `og:image` and render nothing - the link preview is
+ * blank, and it is blank silently, which is the failure mode this package exists to prevent
+ * elsewhere. Serving SVG is only useful where you control the consumer: an internal dashboard, a
+ * docs thumbnail, a preview route you look at yourself.
+ *
+ * **For a card a crawler will actually render, pass `rasterizer`.** It receives the SVG and returns
+ * PNG/JPEG/WebP bytes - a Satori + Resvg pair is the usual choice. Keeping it injected rather than
+ * bundled is what keeps a WASM rasterizer out of `@nifrajs/image` and out of every browser bundle
+ * that imports this package for something else.
+ *
+ * ```ts
+ * import { ogImageResponse } from "@nifrajs/image/og"
+ *
+ * // Renders on X, Facebook, LinkedIn, Slack.
+ * export const GET = (request: Request) =>
+ *   ogImageResponse({ title: "Ship it", rasterizer: pngRasterizer }, request)
+ * ```
+ */
+export interface OgImageRasterized {
+    readonly bytes: Uint8Array;
+    readonly contentType: string;
+}
+export type OgImageRasterizer = (svg: string) => OgImageRasterized | Promise<OgImageRasterized>;
+export interface OgImageOptions {
+    readonly title: string;
+    readonly description?: string;
+    readonly eyebrow?: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly background?: string;
+    readonly foreground?: string;
+    readonly accent?: string;
+    /** Optional PNG/JPEG/WebP backend. Omit to serve the generated SVG. */
+    readonly rasterizer?: OgImageRasterizer;
+    /** Browser/cache freshness in seconds. Default one year. */
+    readonly cacheMaxAge?: number;
+    /** Maximum bytes accepted from an injected rasterizer. Default 10 MiB. */
+    readonly maxBytes?: number;
+}
+/** Render a bounded, deterministic SVG suitable for an `og:image` endpoint. */
+export declare function renderOgImage(options: OgImageOptions): string;
+/**
+ * Build a cacheable OG image response. GET and HEAD are supported; conditional requests short-circuit
+ * rasterization, so a crawler revalidation never repeats expensive codec work.
+ */
+export declare function ogImageResponse(options: OgImageOptions, request?: Request): Promise<Response>;
+//# sourceMappingURL=og.d.ts.map

package/dist/og.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"og.d.ts","sourceRoot":"","sources":["../src/og.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;AAE/F,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,uEAAuE;IACvE,QAAQ,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAA;IACvC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAkGD,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAmB7D;AA8BD;;;GAGG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,QAAQ,CAAC,CAoCnB"}

package/dist/og.js

@@ -0,0 +1,191 @@
+/**
+ * Dependency-free Open Graph image generation.
+ *
+ * **The default SVG output does not work as a social card.** X, Facebook, LinkedIn, Slack, Discord
+ * and iMessage all refuse `image/svg+xml` for `og:image` and render nothing - the link preview is
+ * blank, and it is blank silently, which is the failure mode this package exists to prevent
+ * elsewhere. Serving SVG is only useful where you control the consumer: an internal dashboard, a
+ * docs thumbnail, a preview route you look at yourself.
+ *
+ * **For a card a crawler will actually render, pass `rasterizer`.** It receives the SVG and returns
+ * PNG/JPEG/WebP bytes - a Satori + Resvg pair is the usual choice. Keeping it injected rather than
+ * bundled is what keeps a WASM rasterizer out of `@nifrajs/image` and out of every browser bundle
+ * that imports this package for something else.
+ *
+ * ```ts
+ * import { ogImageResponse } from "@nifrajs/image/og"
+ *
+ * // Renders on X, Facebook, LinkedIn, Slack.
+ * export const GET = (request: Request) =>
+ *   ogImageResponse({ title: "Ship it", rasterizer: pngRasterizer }, request)
+ * ```
+ */
+const DEFAULT_WIDTH = 1200;
+const DEFAULT_HEIGHT = 630;
+const DEFAULT_MAX_AGE = 31_536_000;
+const DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+const COLOR = /^(?:#[0-9a-fA-F]{3,8}|[A-Za-z]{1,32})$/;
+function boundedText(value, name, max, required = false) {
+    if (value === undefined && !required)
+        return "";
+    if (typeof value !== "string" || value.length === 0 || value.length > max) {
+        throw new TypeError(`og image: ${name} must be a non-empty string of at most ${max} characters`);
+    }
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code <= 31 || code === 127)
+            throw new TypeError(`og image: ${name} contains a control character`);
+    }
+    return value;
+}
+function dimension(value, name, fallback) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > 4096) {
+        throw new RangeError(`og image: ${name} must be a safe integer between 1 and 4096`);
+    }
+    return resolved;
+}
+function color(value, name, fallback) {
+    const resolved = value ?? fallback;
+    if (!COLOR.test(resolved))
+        throw new TypeError(`og image: ${name} must be a safe color token`);
+    return resolved;
+}
+function nonNegativeInteger(value, name, fallback) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved < 0) {
+        throw new RangeError(`og image: ${name} must be a non-negative safe integer`);
+    }
+    return resolved;
+}
+function escapeXml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&apos;");
+}
+function wrap(value, maxChars) {
+    if (value === "")
+        return [];
+    const words = value.split(/\s+/);
+    const lines = [];
+    let line = "";
+    for (const word of words) {
+        if (word.length > maxChars) {
+            if (line !== "") {
+                lines.push(line);
+                line = "";
+            }
+            for (let index = 0; index < word.length; index += maxChars) {
+                lines.push(word.slice(index, index + maxChars));
+            }
+            continue;
+        }
+        const candidate = line === "" ? word : `${line} ${word}`;
+        if (candidate.length > maxChars && line !== "") {
+            lines.push(line);
+            line = word;
+        }
+        else
+            line = candidate;
+    }
+    if (line !== "")
+        lines.push(line);
+    return lines;
+}
+function textLines(lines, x, y, size, fill) {
+    return lines
+        .map((line, index) => `<text x="${x}" y="${y + index * Math.round(size * 1.18)}" fill="${fill}" font-family="Arial, Helvetica, sans-serif" font-size="${size}" font-weight="700">${escapeXml(line)}</text>`)
+        .join("");
+}
+/** Render a bounded, deterministic SVG suitable for an `og:image` endpoint. */
+export function renderOgImage(options) {
+    const width = dimension(options.width, "width", DEFAULT_WIDTH);
+    const height = dimension(options.height, "height", DEFAULT_HEIGHT);
+    const title = boundedText(options.title, "title", 240, true);
+    const description = boundedText(options.description, "description", 480);
+    const eyebrow = boundedText(options.eyebrow, "eyebrow", 64);
+    const background = color(options.background, "background", "#101827");
+    const foreground = color(options.foreground, "foreground", "#f8fafc");
+    const accent = color(options.accent, "accent", "#6ee7b7");
+    const titleLines = wrap(title, width >= 900 ? 32 : 24).slice(0, 6);
+    const descriptionLines = wrap(description, width >= 900 ? 72 : 48).slice(0, 4);
+    const titleY = eyebrow === "" ? Math.round(height * 0.43) : Math.round(height * 0.48);
+    const descriptionY = titleY + titleLines.length * 58 + 28;
+    const eyebrowMarkup = eyebrow === ""
+        ? ""
+        : `<text x="84" y="112" fill="${accent}" font-family="Arial, Helvetica, sans-serif" font-size="24" font-weight="700" letter-spacing="3">${escapeXml(eyebrow)}</text>`;
+    const descriptionMarkup = textLines(descriptionLines, 84, descriptionY, 24, foreground);
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img" aria-label="${escapeXml(title)}"><rect width="${width}" height="${height}" fill="${background}"/><rect x="84" y="${height - 70}" width="180" height="8" rx="4" fill="${accent}"/>${eyebrowMarkup}${textLines(titleLines, 84, titleY, 52, foreground)}${descriptionMarkup}</svg>`;
+}
+async function sha256(value) {
+    const input = new Uint8Array(value.byteLength);
+    input.set(value);
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", input));
+    return [...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function weakTag(value) {
+    const trimmed = value.trim();
+    return trimmed.startsWith("W/") ? trimmed.slice(2).trim() : trimmed;
+}
+function ifNoneMatch(request, etag) {
+    const value = request?.headers.get("if-none-match");
+    if (value === null || value === undefined)
+        return false;
+    return (value.trim() === "*" ||
+        value.split(",").some((candidate) => weakTag(candidate) === weakTag(etag)));
+}
+function contentType(value) {
+    if (!/^[A-Za-z0-9!#$&^_.+-]+\/[A-Za-z0-9!#$&^_.+-]+$/.test(value)) {
+        throw new TypeError("og image: rasterizer content type must be a media type");
+    }
+    return value;
+}
+/**
+ * Build a cacheable OG image response. GET and HEAD are supported; conditional requests short-circuit
+ * rasterization, so a crawler revalidation never repeats expensive codec work.
+ */
+export async function ogImageResponse(options, request) {
+    if (request !== undefined && request.method !== "GET" && request.method !== "HEAD") {
+        return new Response(null, { status: 405, headers: { Allow: "GET, HEAD" } });
+    }
+    const cacheMaxAge = nonNegativeInteger(options.cacheMaxAge, "cacheMaxAge", DEFAULT_MAX_AGE);
+    const maxBytes = nonNegativeInteger(options.maxBytes, "maxBytes", DEFAULT_MAX_BYTES);
+    const svg = renderOgImage(options);
+    let bytes;
+    let mediaType = "image/svg+xml";
+    try {
+        if (options.rasterizer === undefined)
+            bytes = new TextEncoder().encode(svg);
+        else {
+            const rasterized = await options.rasterizer(svg);
+            if (!(rasterized.bytes instanceof Uint8Array) || rasterized.bytes.byteLength > maxBytes) {
+                throw new TypeError("og image: rasterizer output exceeds maxBytes");
+            }
+            bytes = rasterized.bytes;
+            mediaType = contentType(rasterized.contentType);
+        }
+    }
+    catch {
+        return Response.json({ error: "image_generation_failed" }, { status: 500 });
+    }
+    // Hash the bytes actually sent. A rasterizer may produce different pixels for the same SVG
+    // (for example after a backend/font update), so hashing only the source would make a conditional
+    // request incorrectly return 304 for a changed representation.
+    const etag = `"${await sha256(bytes)}"`;
+    const headers = new Headers({
+        "cache-control": `public, max-age=${cacheMaxAge}, immutable`,
+        "content-type": `${mediaType}${mediaType === "image/svg+xml" ? "; charset=utf-8" : ""}`,
+        etag,
+        "content-length": String(bytes.byteLength),
+        "x-content-type-options": "nosniff",
+    });
+    if (ifNoneMatch(request, etag))
+        return new Response(null, { status: 304, headers });
+    if (request?.method === "HEAD")
+        return new Response(null, { status: 200, headers });
+    return new Response(bytes, { status: 200, headers });
+}
+//# sourceMappingURL=og.js.map

package/dist/og.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"og.js","sourceRoot":"","sources":["../src/og.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/image",
-  "version": "2.9.1",
+  "version": "2.11.0",
   "description": "Image optimization for nifra - a CLS-safe responsive <Image> + pluggable loaders (CDN or self-hosted) + pure-JS dimension reading. Zero-dependency core; optional Bun.Image-backed resize endpoint at @nifrajs/image/server.",
   "keywords": [
     "bun",
@@ -30,6 +30,16 @@
       "bun": "./src/backend.ts",
       "types": "./dist/backend.d.ts",
       "default": "./dist/backend.js"
+    },
+    "./og": {
+      "bun": "./src/og.ts",
+      "types": "./dist/og.d.ts",
+      "default": "./dist/og.js"
+    },
+    "./og-png": {
+      "bun": "./src/og-png.ts",
+      "types": "./dist/og-png.d.ts",
+      "default": "./dist/og-png.js"
     }
   },
   "files": [

package/src/index.ts

@@ -11,6 +11,20 @@ export {
   readImageDimensions,
 } from "./dimensions.ts"
 export { type HtmlImageAttrs, toHtmlAttrs } from "./html.ts"
+export {
+  type OgImageOptions,
+  type OgImageRasterized,
+  type OgImageRasterizer,
+  ogImageResponse,
+  renderOgImage,
+} from "./og.ts"
+export {
+  createPngRasterizer,
+  createResvgRasterizer,
+  type PngRenderer,
+  type ResvgConstructor,
+  type ResvgRenderer,
+} from "./og-png.ts"
 export {
   type CloudflareLoaderOptions,
   cloudflareLoader,

package/src/og-png.ts

@@ -0,0 +1,33 @@
+import type { OgImageRasterizer } from "./og.ts"
+
+/** A dependency-free shape implemented by SVG→PNG codecs such as Resvg, Satori, or a WASM backend. */
+export type PngRenderer = (svg: string) => Uint8Array | Promise<Uint8Array>
+
+export interface ResvgRenderer {
+  render(): { asPng(): Uint8Array | Promise<Uint8Array> }
+}
+
+export type ResvgConstructor = new (svg: string) => ResvgRenderer
+
+/**
+ * Adapt an injected SVG→PNG renderer to `ogImageResponse`.
+ *
+ * The renderer stays application-owned because codec/WASM choice is runtime-specific. For example:
+ *
+ * ```ts
+ * import { Resvg } from "@resvg/resvg-js"
+ * import { createPngRasterizer } from "@nifrajs/image/og-png"
+ * const rasterizer = createPngRasterizer((svg) => new Resvg(svg).render().asPng())
+ * ```
+ *
+ * This is the public reference adapter; the core package remains zero-dependency and keeps SVG as its
+ * explicit default for callers that do not opt into a codec.
+ */
+export function createPngRasterizer(render: PngRenderer): OgImageRasterizer {
+  return async (svg) => ({ bytes: await render(svg), contentType: "image/png" })
+}
+
+/** Reference adapter for Resvg-compatible constructors, without making the optional codec a dependency. */
+export function createResvgRasterizer(Resvg: ResvgConstructor): OgImageRasterizer {
+  return createPngRasterizer((svg) => new Resvg(svg).render().asPng())
+}

package/src/og.ts

@@ -0,0 +1,237 @@
+/**
+ * Dependency-free Open Graph image generation.
+ *
+ * **The default SVG output does not work as a social card.** X, Facebook, LinkedIn, Slack, Discord
+ * and iMessage all refuse `image/svg+xml` for `og:image` and render nothing - the link preview is
+ * blank, and it is blank silently, which is the failure mode this package exists to prevent
+ * elsewhere. Serving SVG is only useful where you control the consumer: an internal dashboard, a
+ * docs thumbnail, a preview route you look at yourself.
+ *
+ * **For a card a crawler will actually render, pass `rasterizer`.** It receives the SVG and returns
+ * PNG/JPEG/WebP bytes - a Satori + Resvg pair is the usual choice. Keeping it injected rather than
+ * bundled is what keeps a WASM rasterizer out of `@nifrajs/image` and out of every browser bundle
+ * that imports this package for something else.
+ *
+ * ```ts
+ * import { ogImageResponse } from "@nifrajs/image/og"
+ *
+ * // Renders on X, Facebook, LinkedIn, Slack.
+ * export const GET = (request: Request) =>
+ *   ogImageResponse({ title: "Ship it", rasterizer: pngRasterizer }, request)
+ * ```
+ */
+
+export interface OgImageRasterized {
+  readonly bytes: Uint8Array
+  readonly contentType: string
+}
+
+export type OgImageRasterizer = (svg: string) => OgImageRasterized | Promise<OgImageRasterized>
+
+export interface OgImageOptions {
+  readonly title: string
+  readonly description?: string
+  readonly eyebrow?: string
+  readonly width?: number
+  readonly height?: number
+  readonly background?: string
+  readonly foreground?: string
+  readonly accent?: string
+  /** Optional PNG/JPEG/WebP backend. Omit to serve the generated SVG. */
+  readonly rasterizer?: OgImageRasterizer
+  /** Browser/cache freshness in seconds. Default one year. */
+  readonly cacheMaxAge?: number
+  /** Maximum bytes accepted from an injected rasterizer. Default 10 MiB. */
+  readonly maxBytes?: number
+}
+
+const DEFAULT_WIDTH = 1200
+const DEFAULT_HEIGHT = 630
+const DEFAULT_MAX_AGE = 31_536_000
+const DEFAULT_MAX_BYTES = 10 * 1024 * 1024
+const COLOR = /^(?:#[0-9a-fA-F]{3,8}|[A-Za-z]{1,32})$/
+
+function boundedText(
+  value: string | undefined,
+  name: string,
+  max: number,
+  required = false,
+): string {
+  if (value === undefined && !required) return ""
+  if (typeof value !== "string" || value.length === 0 || value.length > max) {
+    throw new TypeError(`og image: ${name} must be a non-empty string of at most ${max} characters`)
+  }
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index)
+    if (code <= 31 || code === 127)
+      throw new TypeError(`og image: ${name} contains a control character`)
+  }
+  return value
+}
+
+function dimension(value: number | undefined, name: string, fallback: number): number {
+  const resolved = value ?? fallback
+  if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > 4096) {
+    throw new RangeError(`og image: ${name} must be a safe integer between 1 and 4096`)
+  }
+  return resolved
+}
+
+function color(value: string | undefined, name: string, fallback: string): string {
+  const resolved = value ?? fallback
+  if (!COLOR.test(resolved)) throw new TypeError(`og image: ${name} must be a safe color token`)
+  return resolved
+}
+
+function nonNegativeInteger(value: number | undefined, name: string, fallback: number): number {
+  const resolved = value ?? fallback
+  if (!Number.isSafeInteger(resolved) || resolved < 0) {
+    throw new RangeError(`og image: ${name} must be a non-negative safe integer`)
+  }
+  return resolved
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;")
+}
+
+function wrap(value: string, maxChars: number): string[] {
+  if (value === "") return []
+  const words = value.split(/\s+/)
+  const lines: string[] = []
+  let line = ""
+  for (const word of words) {
+    if (word.length > maxChars) {
+      if (line !== "") {
+        lines.push(line)
+        line = ""
+      }
+      for (let index = 0; index < word.length; index += maxChars) {
+        lines.push(word.slice(index, index + maxChars))
+      }
+      continue
+    }
+    const candidate = line === "" ? word : `${line} ${word}`
+    if (candidate.length > maxChars && line !== "") {
+      lines.push(line)
+      line = word
+    } else line = candidate
+  }
+  if (line !== "") lines.push(line)
+  return lines
+}
+
+function textLines(
+  lines: readonly string[],
+  x: number,
+  y: number,
+  size: number,
+  fill: string,
+): string {
+  return lines
+    .map(
+      (line, index) =>
+        `<text x="${x}" y="${y + index * Math.round(size * 1.18)}" fill="${fill}" font-family="Arial, Helvetica, sans-serif" font-size="${size}" font-weight="700">${escapeXml(line)}</text>`,
+    )
+    .join("")
+}
+
+/** Render a bounded, deterministic SVG suitable for an `og:image` endpoint. */
+export function renderOgImage(options: OgImageOptions): string {
+  const width = dimension(options.width, "width", DEFAULT_WIDTH)
+  const height = dimension(options.height, "height", DEFAULT_HEIGHT)
+  const title = boundedText(options.title, "title", 240, true)
+  const description = boundedText(options.description, "description", 480)
+  const eyebrow = boundedText(options.eyebrow, "eyebrow", 64)
+  const background = color(options.background, "background", "#101827")
+  const foreground = color(options.foreground, "foreground", "#f8fafc")
+  const accent = color(options.accent, "accent", "#6ee7b7")
+  const titleLines = wrap(title, width >= 900 ? 32 : 24).slice(0, 6)
+  const descriptionLines = wrap(description, width >= 900 ? 72 : 48).slice(0, 4)
+  const titleY = eyebrow === "" ? Math.round(height * 0.43) : Math.round(height * 0.48)
+  const descriptionY = titleY + titleLines.length * 58 + 28
+  const eyebrowMarkup =
+    eyebrow === ""
+      ? ""
+      : `<text x="84" y="112" fill="${accent}" font-family="Arial, Helvetica, sans-serif" font-size="24" font-weight="700" letter-spacing="3">${escapeXml(eyebrow)}</text>`
+  const descriptionMarkup = textLines(descriptionLines, 84, descriptionY, 24, foreground)
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img" aria-label="${escapeXml(title)}"><rect width="${width}" height="${height}" fill="${background}"/><rect x="84" y="${height - 70}" width="180" height="8" rx="4" fill="${accent}"/>${eyebrowMarkup}${textLines(titleLines, 84, titleY, 52, foreground)}${descriptionMarkup}</svg>`
+}
+
+async function sha256(value: Uint8Array): Promise<string> {
+  const input = new Uint8Array(value.byteLength)
+  input.set(value)
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", input))
+  return [...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("")
+}
+
+function weakTag(value: string): string {
+  const trimmed = value.trim()
+  return trimmed.startsWith("W/") ? trimmed.slice(2).trim() : trimmed
+}
+
+function ifNoneMatch(request: Request | undefined, etag: string): boolean {
+  const value = request?.headers.get("if-none-match")
+  if (value === null || value === undefined) return false
+  return (
+    value.trim() === "*" ||
+    value.split(",").some((candidate) => weakTag(candidate) === weakTag(etag))
+  )
+}
+
+function contentType(value: string): string {
+  if (!/^[A-Za-z0-9!#$&^_.+-]+\/[A-Za-z0-9!#$&^_.+-]+$/.test(value)) {
+    throw new TypeError("og image: rasterizer content type must be a media type")
+  }
+  return value
+}
+
+/**
+ * Build a cacheable OG image response. GET and HEAD are supported; conditional requests short-circuit
+ * rasterization, so a crawler revalidation never repeats expensive codec work.
+ */
+export async function ogImageResponse(
+  options: OgImageOptions,
+  request?: Request,
+): Promise<Response> {
+  if (request !== undefined && request.method !== "GET" && request.method !== "HEAD") {
+    return new Response(null, { status: 405, headers: { Allow: "GET, HEAD" } })
+  }
+  const cacheMaxAge = nonNegativeInteger(options.cacheMaxAge, "cacheMaxAge", DEFAULT_MAX_AGE)
+  const maxBytes = nonNegativeInteger(options.maxBytes, "maxBytes", DEFAULT_MAX_BYTES)
+  const svg = renderOgImage(options)
+  let bytes: Uint8Array
+  let mediaType = "image/svg+xml"
+  try {
+    if (options.rasterizer === undefined) bytes = new TextEncoder().encode(svg)
+    else {
+      const rasterized = await options.rasterizer(svg)
+      if (!(rasterized.bytes instanceof Uint8Array) || rasterized.bytes.byteLength > maxBytes) {
+        throw new TypeError("og image: rasterizer output exceeds maxBytes")
+      }
+      bytes = rasterized.bytes
+      mediaType = contentType(rasterized.contentType)
+    }
+  } catch {
+    return Response.json({ error: "image_generation_failed" }, { status: 500 })
+  }
+  // Hash the bytes actually sent. A rasterizer may produce different pixels for the same SVG
+  // (for example after a backend/font update), so hashing only the source would make a conditional
+  // request incorrectly return 304 for a changed representation.
+  const etag = `"${await sha256(bytes)}"`
+  const headers = new Headers({
+    "cache-control": `public, max-age=${cacheMaxAge}, immutable`,
+    "content-type": `${mediaType}${mediaType === "image/svg+xml" ? "; charset=utf-8" : ""}`,
+    etag,
+    "content-length": String(bytes.byteLength),
+    "x-content-type-options": "nosniff",
+  })
+  if (ifNoneMatch(request, etag)) return new Response(null, { status: 304, headers })
+  if (request?.method === "HEAD") return new Response(null, { status: 200, headers })
+  return new Response(bytes, { status: 200, headers })
+}