@ethercorps/sveltekit-og 4.3.1-next.2 → 4.4.0-next.0

package/dist/client/types.d.ts

@@ -0,0 +1,14 @@
+import type { ImageResponseOptions } from "../types.js";
+import type { TakumiImageResponseOptions } from "../takumi/types.js";
+/**
+ * Options for the client `ImageResponse` / `createImage`. The `engine` field
+ * selects the renderer and narrows the rest of the options to that engine's
+ * shape (fonts, formats and emoji differ between the two).
+ *
+ * @default engine "takumi"
+ */
+export type ClientImageResponseOptions = ({
+    engine?: "takumi";
+} & TakumiImageResponseOptions) | ({
+    engine: "satori";
+} & ImageResponseOptions);

package/dist/client/types.js

@@ -0,0 +1 @@
+export {};

package/dist/fonts.d.ts

@@ -1,4 +1,4 @@
-import type { FinalFontOptions, FontStyle, FontWeight, MayBePromise } from './types.js';
+import type { FinalFontOptions, FontStyle, FontWeight, MayBePromise } from "./types.js";
 interface BaseFontOptions {
     weight?: FontWeight;
     style?: FontStyle;
@@ -7,24 +7,24 @@ interface BaseFontOptions {
  * All font types inherit from this class.
  */
 export declare class BaseFont {
-    protected input: any;
     name: string;
     style: FontStyle;
     weight: FontWeight;
-    constructor(name: string, input: any, { weight, style }?: BaseFontOptions);
+    constructor(name: string, { weight, style }?: BaseFontOptions);
     /** * Abstract getter that returns the promised ArrayBuffer.
      * Overridden by CustomFont and GoogleFont for lazy loading.
      */
     get data(): MayBePromise<Buffer | ArrayBuffer>;
 }
 export declare class CustomFont extends BaseFont {
+    protected input: MayBePromise<Buffer | ArrayBuffer> | (() => MayBePromise<Buffer | ArrayBuffer>);
     private promise?;
     constructor(name: string, input: MayBePromise<Buffer | ArrayBuffer> | (() => MayBePromise<Buffer | ArrayBuffer>), options?: BaseFontOptions);
     /** A promise which resolves to font data as `ArrayBuffer` (Lazy load and CACHED) */
     get data(): Promise<Buffer | ArrayBuffer>;
 }
 /** Loads Google font ArrayBuffer with caching. */
-export declare const loadGoogleFont: (family: string, { text, weight, style, display }?: {
+export declare const loadGoogleFont: (family: string, { text, weight, style, display, }?: {
     text?: string;
     weight?: string | number;
     style?: FontStyle;

package/dist/fonts.js

@@ -1,14 +1,12 @@
-import { FONT_CACHE_MAP } from './helpers/cache.js';
+import { FONT_CACHE_MAP } from "./helpers/cache.js";
 /** * Base font class defining the structure required by Satori.
  * All font types inherit from this class.
  */
 export class BaseFont {
-    input;
     name;
     style;
     weight;
-    constructor(name, input, { weight = 400, style = 'normal' } = {}) {
-        this.input = input;
+    constructor(name, { weight = 400, style = "normal" } = {}) {
         this.name = name;
         this.style = style;
         this.weight = weight;
@@ -17,13 +15,15 @@ export class BaseFont {
      * Overridden by CustomFont and GoogleFont for lazy loading.
      */
     get data() {
-        return this.input;
+        throw new Error("The 'data' getter must be implemented by subclasses of BaseFont.");
     }
 }
 export class CustomFont extends BaseFont {
+    input;
     promise;
     constructor(name, input, options) {
-        super(name, input, options);
+        super(name, options);
+        this.input = input;
     }
     /** A promise which resolves to font data as `ArrayBuffer` (Lazy load and CACHED) */
     get data() {
@@ -33,7 +33,7 @@ export class CustomFont extends BaseFont {
             return Promise.resolve(cachedData);
         }
         const fallback = async () => {
-            const buffer = typeof this.input === 'function' ? this.input() : this.input;
+            const buffer = typeof this.input === "function" ? this.input() : this.input;
             const resolvedBuffer = await buffer;
             FONT_CACHE_MAP.set(cacheKey, resolvedBuffer);
             return resolvedBuffer;
@@ -43,17 +43,21 @@ export class CustomFont extends BaseFont {
     }
 }
 /** Constructs Google font css url */
-const constructGoogleFontCssUrl = (family, { text, weight = 400, style = 'normal', display } = {}) => {
+const constructGoogleFontCssUrl = (family, { text, weight = 400, style = "normal", display, } = {}) => {
     // Logic to build the URL (e.g., https://fonts.googleapis.com/css2?family=...wght@...)
     const params = {
-        family: `${family.replaceAll(' ', '+')}:${style === 'italic' ? 'ital,' : ''}wght@${style === 'italic' ? '1,' : ''}${weight}`,
+        family: `${family.replaceAll(" ", "+")}:${style === "italic" ? "ital," : ""}wght@${style === "italic" ? "1," : ""}${weight}`,
     };
     if (text)
         params.text = encodeURIComponent(text);
-    return `https://fonts.googleapis.com/css2?${Object.keys(params).map((key) => `${key}=${params[key]}`).join('&')}`;
+    if (display)
+        params.display = display;
+    return `https://fonts.googleapis.com/css2?${Object.entries(params)
+        .map(([key, value]) => `${key}=${value}`)
+        .join("&")}`;
 };
 /** Loads Google font ArrayBuffer with caching. */
-export const loadGoogleFont = async (family, { text, weight = 400, style = 'normal', display } = {}) => {
+export const loadGoogleFont = async (family, { text, weight = 400, style = "normal", display, } = {}) => {
     const cssUrl = constructGoogleFontCssUrl(family, { text, weight, display, style });
     const fromMap = FONT_CACHE_MAP.get(cssUrl);
     if (fromMap) {
@@ -84,7 +88,7 @@ export class GoogleFont extends BaseFont {
     text;
     promise;
     constructor(family, options = {}) {
-        super(options.name || family, undefined, options);
+        super(options.name || family, options);
         this.family = family;
         this.text = options.text;
     }
@@ -108,5 +112,5 @@ export async function resolveFonts(fontClasses) {
             style: fontClass.style,
         };
     }));
-    return resolvedFonts.filter(font => font !== null);
+    return resolvedFonts.filter((font) => font !== null);
 }

package/dist/helpers/create.d.ts

@@ -1,4 +1,7 @@
-import type { Component } from 'svelte';
-import type { ComponentOptions, ImageOptions } from '../types.js';
-export declare function createSvg(element: string | Component, imageOptions: ImageOptions, componentOptions?: ComponentOptions): Promise<string>;
-export declare function createPng(element: string | Component, imageOptions: ImageOptions, componentOptions?: ComponentOptions): Promise<Uint8Array<ArrayBufferLike>>;
+import type { Component } from "svelte";
+import type { ComponentOptions, ImageOptions } from "../types.js";
+/** Single entry for the Satori and ReSVG engine */
+export declare function createImage(element: string | Component<any>, imageOptions: ImageOptions, componentOptions?: ComponentOptions): Promise<Uint8Array | string>;
+/** Create an SVG string from a Svelte component or HTML string using Satori */
+export declare function createSvg(element: string | Component<any>, imageOptions: ImageOptions, componentOptions?: ComponentOptions): Promise<string>;
+export declare function createPng(element: string | Component<any>, imageOptions: ImageOptions, componentOptions?: ComponentOptions): Promise<Uint8Array<ArrayBufferLike>>;

package/dist/helpers/create.js

@@ -1,38 +1,49 @@
-import { loadDynamicAsset } from './emoji.js';
-import { default_fonts, DEFAULT_WIDTH } from '../helpers/defaults.js';
-import { useResvg, useSatori } from '../providers/instances.js';
-import { createVNode } from './toJSX.js';
+import { loadDynamicAsset } from "./emoji.js";
+import { default_fonts, DEFAULT_WIDTH } from "../helpers/defaults.js";
+import { useResvg, useSatori } from "../providers/instances.js";
+import { createVNode } from "./toJSX.js";
+import { createLogger } from "./logger.js";
+import { handleAsync, ErrorCodes } from "./error-handler.js";
+/** Single entry for the Satori and ReSVG engine */
+export function createImage(element, imageOptions, componentOptions) {
+    return imageOptions.format === "svg"
+        ? createSvg(element, imageOptions, componentOptions)
+        : createPng(element, imageOptions, componentOptions);
+}
+/** Create an SVG string from a Svelte component or HTML string using Satori */
 export async function createSvg(element, imageOptions, componentOptions) {
-    const [satori, vnodes] = await Promise.all([useSatori(), createVNode(element, componentOptions)]);
-    const satoriOptions = structuredClone(imageOptions);
-    if (!Object.hasOwn(satoriOptions, 'fonts')) {
-        satoriOptions['fonts'] = await default_fonts();
+    const log = createLogger(imageOptions.debug ?? false);
+    const vnodes = createVNode(element, componentOptions);
+    const satori = await useSatori(imageOptions.debug);
+    const satoriOptions = { ...imageOptions };
+    if (!satoriOptions.fonts) {
+        satoriOptions.fonts = await handleAsync(() => default_fonts(), ErrorCodes.FONT_LOAD_FAILED, "Failed to load default fonts for Satori");
     }
-    satoriOptions['loadAdditionalAsset'] = loadDynamicAsset({
-        emoji: imageOptions.emoji
+    satoriOptions.loadAdditionalAsset = loadDynamicAsset({
+        emoji: imageOptions.emoji,
     });
-    if (satoriOptions.debug) {
-        console.info('VNode proivided to satori:', vnodes, '\n');
-        console.info('Options proivided to satori:', imageOptions, '\n');
-    }
-    return satori(vnodes, satoriOptions);
+    log.debug("Generating SVG with Satori");
+    log.info("VNode provided to satori:", JSON.stringify(vnodes, null, 2), "\n");
+    log.info("Options provided to satori:", imageOptions);
+    return handleAsync(() => satori(vnodes, satoriOptions), ErrorCodes.SATORI_RENDER_FAILED, "Failed to render SVG with Satori");
 }
+/* Create a PNG image from a Svelte component or HTML string using Satori and ReSVG */
 export async function createPng(element, imageOptions, componentOptions) {
-    const svg = await createSvg(element, imageOptions, componentOptions);
-    if (imageOptions.debug) {
-        console.info('SVG generated by satori:', svg, '\n');
-    }
-    const resvg_instance = await useResvg();
+    const log = createLogger(imageOptions.debug ?? false);
+    const svg = await handleAsync(() => createSvg(element, imageOptions, componentOptions), ErrorCodes.SATORI_RENDER_FAILED, "Failed to create SVG for PNG rendering");
+    log.debug("SVG generated by satori for ReSVG: \n", svg, "\n");
+    const resvg_instance = await handleAsync(() => useResvg(imageOptions.debug), ErrorCodes.RESVG_INIT_FAILED, "Failed to initialize ReSVG");
     const resvg_options = {
         fitTo: {
-            mode: 'width',
+            mode: "width",
             value: imageOptions.width || DEFAULT_WIDTH,
-        }
+        },
     };
-    if (imageOptions.debug) {
-        console.info('Options provided to ReSVG:', resvg_options, '\n');
-    }
-    const resvg = new resvg_instance(svg, resvg_options);
-    const png_data = resvg.render();
-    return png_data.asPng();
+    log.debug("Rendering PNG with ReSVG");
+    log.info("Options provided to ReSVG:", resvg_options, "\n");
+    return handleAsync(async () => {
+        const resvg = new resvg_instance(svg, resvg_options);
+        const png_data = resvg.render();
+        return png_data.asPng();
+    }, ErrorCodes.RESVG_RENDER_FAILED, "Failed to render PNG with ReSVG");
 }

package/dist/helpers/defaults.d.ts

@@ -1,7 +1,7 @@
-import type { SatoriOptions } from 'satori';
-import type { ImageOptions } from '../types.js';
-import type { EmojiType } from './emoji.js';
-export declare function default_fonts(): Promise<SatoriOptions['fonts']>;
+import type { SatoriOptions } from "satori";
+import type { ImageOptions } from "../types.js";
+import type { EmojiType } from "./emoji.js";
+export declare function default_fonts(): Promise<SatoriOptions["fonts"]>;
 export declare const DEFAULT_FORMAT = "png";
 export declare const DEFAULT_WIDTH = 1200;
 export declare const DEFAULT_HEIGHT = 630;

package/dist/helpers/defaults.js

@@ -1,37 +1,47 @@
-export async function default_fonts() {
-    const [noto_sans_regular_font_resp, noto_sans_bold_font_reps] = await Promise.all([
-        fetch('https://cdn-sveltekit-og.ethercorps.io/NotoSans-Regular.ttf'), fetch('https://cdn-sveltekit-og.ethercorps.io/NotoSans-Bold.ttf')
-    ]);
-    if (!(noto_sans_bold_font_reps.ok || noto_sans_bold_font_reps.ok)) {
-        console.error('Not able to load default fonts');
-        throw new Error('Not able to load default fonts');
-    }
-    const [noto_sans_regular_font, noto_sans_bold_font] = await Promise.all([noto_sans_regular_font_resp.arrayBuffer(), noto_sans_bold_font_reps.arrayBuffer()]);
+import { handleAsyncAll, validateResponse, ErrorCodes } from "./error-handler.js";
+// fetched once per process; a rejected fetch clears the cache so the next request retries
+let defaultFontsPromise;
+export function default_fonts() {
+    defaultFontsPromise ??= loadDefaultFonts().catch((error) => {
+        defaultFontsPromise = undefined;
+        throw error;
+    });
+    return defaultFontsPromise;
+}
+async function loadDefaultFonts() {
+    const [noto_sans_regular_font_resp, noto_sans_bold_font_reps] = await handleAsyncAll([
+        () => fetch("https://cdn-sveltekit-og.ethercorps.io/NotoSans-Regular.ttf"),
+        () => fetch("https://cdn-sveltekit-og.ethercorps.io/NotoSans-Bold.ttf"),
+    ], ErrorCodes.FONT_LOAD_FAILED, "Failed to fetch default fonts");
+    const [noto_sans_regular_font, noto_sans_bold_font] = await handleAsyncAll([
+        () => validateResponse(noto_sans_regular_font_resp, ErrorCodes.FONT_LOAD_FAILED, "Failed to validate regular font response"),
+        () => validateResponse(noto_sans_bold_font_reps, ErrorCodes.FONT_LOAD_FAILED, "Failed to validate bold font response"),
+    ], ErrorCodes.FONT_LOAD_FAILED, "Failed to process font responses");
     return [
         {
             data: noto_sans_regular_font,
-            name: 'Inter',
+            name: "Inter",
             weight: 400,
-            style: 'normal'
+            style: "normal",
         },
         {
             data: noto_sans_bold_font,
-            name: 'Inter',
+            name: "Inter",
             weight: 700,
-            style: 'normal'
-        }
+            style: "normal",
+        },
     ];
 }
-export const DEFAULT_FORMAT = 'png';
+export const DEFAULT_FORMAT = "png";
 export const DEFAULT_WIDTH = 1200;
 export const DEFAULT_HEIGHT = 630;
-export const DEFAULT_EMOJI_PROVIDER = 'twemoji';
+export const DEFAULT_EMOJI_PROVIDER = "twemoji";
 export const DEFAULT_STATUS_CODE = 200;
-export const DEFAULT_STATUS_TEXT = 'Success';
+export const DEFAULT_STATUS_TEXT = "Success";
 export const DEFAULT_OPTIONS = {
     height: DEFAULT_HEIGHT,
     width: DEFAULT_WIDTH,
     debug: false,
     format: DEFAULT_FORMAT,
-    emoji: 'twemoji'
+    emoji: "twemoji",
 };

package/dist/helpers/emoji.d.ts

@@ -8,6 +8,6 @@ declare const emoji_apis: {
 };
 export declare const loadDynamicAsset: ({ emoji }: {
     emoji: EmojiType;
-}) => (...args: any[]) => Promise<string | undefined>;
+}) => (code: string, text: string) => Promise<string | undefined>;
 export type EmojiType = keyof typeof emoji_apis;
 export {};

package/dist/helpers/emoji.js

@@ -1,4 +1,5 @@
-import { DEFAULT_EMOJI_PROVIDER } from '../helpers/defaults.js';
+import { DEFAULT_EMOJI_PROVIDER } from "../helpers/defaults.js";
+import { handleAsync, ErrorCodes } from "./error-handler.js";
 // Code stolen from @vercel/og and https://github.com/fineshopdesign/cf-wasm
 const U200D = String.fromCharCode(8205);
 const UFE0Fg = /\uFE0F/g;
@@ -11,7 +12,7 @@ function toCodePoint(unicodeSurrogates) {
     while (i < unicodeSurrogates.length) {
         c = unicodeSurrogates.charCodeAt(i++);
         if (p) {
-            r.push((65536 + (p - 55296 << 10) + (c - 56320)).toString(16));
+            r.push((65536 + ((p - 55296) << 10) + (c - 56320)).toString(16));
             p = 0;
         }
         else if (55296 <= c && c <= 56319) {
@@ -24,32 +25,41 @@ function toCodePoint(unicodeSurrogates) {
     return r.join("-");
 }
 const emoji_apis = {
-    twemoji: (code) => "https://cdn.jsdelivr.net/gh/twitter/twemoji@14.0.2/assets/svg/" + code.toLowerCase() + ".svg",
+    twemoji: (code) => "https://cdn.jsdelivr.net/gh/twitter/twemoji@14.0.2/assets/svg/" +
+        code.toLowerCase() +
+        ".svg",
     openmoji: "https://cdn.jsdelivr.net/npm/@svgmoji/openmoji@2.0.0/svg/",
     blobmoji: "https://cdn.jsdelivr.net/npm/@svgmoji/blob@2.0.0/svg/",
     noto: "https://cdn.jsdelivr.net/gh/svgmoji/svgmoji/packages/svgmoji__noto/svg/",
-    fluent: (code) => "https://cdn.jsdelivr.net/gh/shuding/fluentui-emoji-unicode/assets/" + code.toLowerCase() + "_color.svg",
-    fluentFlat: (code) => "https://cdn.jsdelivr.net/gh/shuding/fluentui-emoji-unicode/assets/" + code.toLowerCase() + "_flat.svg"
+    fluent: (code) => "https://cdn.jsdelivr.net/gh/shuding/fluentui-emoji-unicode/assets/" +
+        code.toLowerCase() +
+        "_color.svg",
+    fluentFlat: (code) => "https://cdn.jsdelivr.net/gh/shuding/fluentui-emoji-unicode/assets/" +
+        code.toLowerCase() +
+        "_flat.svg",
 };
-function loadEmoji(code, type) {
-    if (!type || !emoji_apis[type]) {
-        type = DEFAULT_EMOJI_PROVIDER;
-    }
-    const api = emoji_apis[type];
-    if (typeof api === "function") {
-        return fetch(api(code));
-    }
-    return fetch(`${api}${code.toUpperCase()}.svg`);
+async function loadEmoji(code, type) {
+    return handleAsync(async () => {
+        if (!type || !emoji_apis[type]) {
+            type = DEFAULT_EMOJI_PROVIDER;
+        }
+        const api = emoji_apis[type];
+        if (typeof api === "function") {
+            return fetch(api(code));
+        }
+        return fetch(`${api}${code.toUpperCase()}.svg`);
+    }, ErrorCodes.EMOJI_LOAD_FAILED, `Failed to load emoji for code: ${code}`);
 }
 export const loadDynamicAsset = ({ emoji }) => {
-    const fn = async (code, text) => {
+    return async (code, text) => {
         if (code === "emoji") {
-            return `data:image/svg+xml;base64,` + btoa(await (await loadEmoji(getIconCode(text), emoji)).text());
+            return handleAsync(async () => {
+                const iconCode = getIconCode(text);
+                const emojiResponse = await loadEmoji(iconCode, emoji);
+                const svgText = await emojiResponse.text();
+                const base64Data = btoa(svgText);
+                return `data:image/svg+xml;base64,` + base64Data;
+            }, ErrorCodes.EMOJI_LOAD_FAILED, `Failed to process emoji: ${text}`);
         }
     };
-    return async (...args) => {
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore
-        return await fn(...args);
-    };
 };

package/dist/helpers/error-handler.d.ts

@@ -0,0 +1,38 @@
+export declare class ImageResponseError extends Error {
+    code: string;
+    originalError?: Error | undefined;
+    constructor(message: string, code: string, originalError?: Error | undefined);
+}
+/** Coerce anything thrown into an ImageResponseError, keeping existing ones as-is. */
+export declare function toImageResponseError(error: unknown): ImageResponseError;
+export declare const ErrorCodes: {
+    readonly FONT_LOAD_FAILED: "FONT_LOAD_FAILED";
+    readonly VNODE_CREATION_FAILED: "VNODE_CREATION_FAILED";
+    readonly SATORI_RENDER_FAILED: "SATORI_RENDER_FAILED";
+    readonly RESVG_INIT_FAILED: "RESVG_INIT_FAILED";
+    readonly RESVG_RENDER_FAILED: "RESVG_RENDER_FAILED";
+    readonly SATORI_INIT_FAILED: "SATORI_INIT_FAILED";
+    readonly EMOJI_LOAD_FAILED: "EMOJI_LOAD_FAILED";
+    readonly TAKUMI_INIT_FAILED: "TAKUMI_INIT_FAILED";
+    readonly TAKUMI_RENDER_FAILED: "TAKUMI_RENDER_FAILED";
+    readonly COMPONENT_IN_WORKER: "COMPONENT_IN_WORKER";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+};
+/**
+ * Wraps an async operation with error handling and logging
+ */
+export declare function handleAsync<T = unknown>(operation: () => Promise<T>, errorCode: string, errorMessage: string): Promise<T>;
+/**
+ * Wraps a sync operation with error handling and logging
+ */
+export declare function handleSync<T>(operation: () => T, errorCode: string, errorMessage: string): T;
+/**
+ * Wraps multiple async operations with error handling
+ */
+export declare function handleAsyncAll<T extends readonly unknown[]>(operations: {
+    readonly [K in keyof T]: () => Promise<T[K]>;
+}, errorCode: string, errorMessage: string): Promise<T>;
+/**
+ * Validates a response and throws if not ok
+ */
+export declare function validateResponse(response: Response, errorCode: string, errorMessage: string): Promise<ArrayBuffer>;

package/dist/helpers/error-handler.js

@@ -0,0 +1,76 @@
+export class ImageResponseError extends Error {
+    code;
+    originalError;
+    constructor(message, code, originalError) {
+        super(message);
+        this.code = code;
+        this.originalError = originalError;
+        this.name = "ImageResponseError";
+    }
+}
+/** Coerce anything thrown into an ImageResponseError, keeping existing ones as-is. */
+export function toImageResponseError(error) {
+    if (error instanceof ImageResponseError)
+        return error;
+    const err = error instanceof Error ? error : new Error(String(error));
+    return new ImageResponseError(err.message, ErrorCodes.UNKNOWN_ERROR, err);
+}
+export const ErrorCodes = {
+    FONT_LOAD_FAILED: "FONT_LOAD_FAILED",
+    VNODE_CREATION_FAILED: "VNODE_CREATION_FAILED",
+    SATORI_RENDER_FAILED: "SATORI_RENDER_FAILED",
+    RESVG_INIT_FAILED: "RESVG_INIT_FAILED",
+    RESVG_RENDER_FAILED: "RESVG_RENDER_FAILED",
+    SATORI_INIT_FAILED: "SATORI_INIT_FAILED",
+    EMOJI_LOAD_FAILED: "EMOJI_LOAD_FAILED",
+    TAKUMI_INIT_FAILED: "TAKUMI_INIT_FAILED",
+    TAKUMI_RENDER_FAILED: "TAKUMI_RENDER_FAILED",
+    COMPONENT_IN_WORKER: "COMPONENT_IN_WORKER",
+    UNKNOWN_ERROR: "UNKNOWN_ERROR",
+};
+/**
+ * Wraps an async operation with error handling and logging
+ */
+export async function handleAsync(operation, errorCode, errorMessage) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        throw new ImageResponseError(errorMessage, errorCode, err);
+    }
+}
+/**
+ * Wraps a sync operation with error handling and logging
+ */
+export function handleSync(operation, errorCode, errorMessage) {
+    try {
+        return operation();
+    }
+    catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        throw new ImageResponseError(errorMessage, errorCode, err);
+    }
+}
+/**
+ * Wraps multiple async operations with error handling
+ */
+export async function handleAsyncAll(operations, errorCode, errorMessage) {
+    try {
+        return (await Promise.all(operations.map((op) => op())));
+    }
+    catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        throw new ImageResponseError(errorMessage, errorCode, err);
+    }
+}
+/**
+ * Validates a response and throws if not ok
+ */
+export async function validateResponse(response, errorCode, errorMessage) {
+    if (!response.ok) {
+        throw new ImageResponseError(`${errorMessage} (HTTP ${response.status})`, errorCode);
+    }
+    const buffer = await response.arrayBuffer();
+    return buffer;
+}

package/dist/helpers/logger.d.ts

@@ -0,0 +1,7 @@
+export type Logger = ReturnType<typeof createLogger>;
+export declare function createLogger(debug: boolean): {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+};

package/dist/helpers/logger.js

@@ -0,0 +1,21 @@
+const PREFIX = "[SvelteKit-OG]";
+export function createLogger(debug) {
+    return {
+        debug: (message, ...args) => {
+            if (debug)
+                console.log(`${PREFIX} 🔍 ${message}`, ...args);
+        },
+        info: (message, ...args) => {
+            if (debug)
+                console.info(`${PREFIX} ℹ️ ${message}`, ...args);
+        },
+        warn: (message, ...args) => {
+            if (debug)
+                console.warn(`${PREFIX} ⚠️ ${message}`, ...args);
+        },
+        error: (message, ...args) => {
+            if (debug)
+                console.error(`${PREFIX} ❌ ${message}`, ...args);
+        },
+    };
+}

package/dist/helpers/response.d.ts

@@ -0,0 +1,30 @@
+/** format → content type for every format either engine can emit; satori uses the
+ * png/svg subset, takumi the whole map. */
+export declare const CONTENT_TYPES: {
+    readonly png: "image/png";
+    readonly jpeg: "image/jpeg";
+    readonly webp: "image/webp";
+    readonly ico: "image/x-icon";
+    readonly raw: "application/octet-stream";
+    readonly svg: "image/svg+xml";
+};
+type ImageProducer = () => Promise<Uint8Array | string>;
+interface BuildOptions {
+    /** uppercased format, used in logs e.g. "PNG" */
+    label: string;
+    contentType: string;
+    debug: boolean;
+    headers?: Record<string, string>;
+    status?: number;
+    statusText?: string;
+}
+/**
+ * Shared body + response init for both engines' ImageResponse. Streams the image
+ * out as bytes (a Response stream can't take a raw string), with consistent
+ * cache headers and error handling.
+ */
+export declare function buildImageResponse(produce: ImageProducer, opts: BuildOptions): {
+    body: ReadableStream;
+    init: ResponseInit;
+};
+export {};

package/dist/helpers/response.js

@@ -0,0 +1,52 @@
+import { createLogger } from "./logger.js";
+import { handleAsync, toImageResponseError, ErrorCodes } from "./error-handler.js";
+import { DEFAULT_STATUS_CODE, DEFAULT_STATUS_TEXT } from "./defaults.js";
+import { formatBytes } from "./utils.js";
+/** format → content type for every format either engine can emit; satori uses the
+ * png/svg subset, takumi the whole map. */
+export const CONTENT_TYPES = {
+    png: "image/png",
+    jpeg: "image/jpeg",
+    webp: "image/webp",
+    ico: "image/x-icon",
+    raw: "application/octet-stream",
+    svg: "image/svg+xml",
+};
+// TextEncoder is stateless; one shared instance instead of one per svg response
+const textEncoder = new TextEncoder();
+/**
+ * Shared body + response init for both engines' ImageResponse. Streams the image
+ * out as bytes (a Response stream can't take a raw string), with consistent
+ * cache headers and error handling.
+ */
+export function buildImageResponse(produce, opts) {
+    const log = createLogger(opts.debug);
+    const body = new ReadableStream({
+        async start(controller) {
+            try {
+                const out = await handleAsync(produce, ErrorCodes.UNKNOWN_ERROR, `Failed to generate ${opts.label}`);
+                const bytes = typeof out === "string" ? textEncoder.encode(out) : out;
+                log.info(`Generated ${opts.label}: ${formatBytes(bytes.byteLength)}`);
+                controller.enqueue(bytes);
+                controller.close();
+            }
+            catch (error) {
+                const err = toImageResponseError(error);
+                log.error("Failed to create image response:", err.message);
+                controller.error(err);
+            }
+        },
+    });
+    const init = {
+        headers: {
+            "Content-Type": opts.contentType,
+            "Cache-Control": opts.debug
+                ? "no-cache, no-store"
+                : "public, immutable, no-transform, max-age=31536000",
+            ...opts.headers,
+        },
+        status: opts.status || DEFAULT_STATUS_CODE,
+        statusText: opts.statusText || DEFAULT_STATUS_TEXT,
+    };
+    return { body, init };
+}

package/dist/helpers/to-html.d.ts

@@ -0,0 +1,10 @@
+import type { Component } from "svelte";
+/**
+ * Render a Svelte component to its SSR html parts. Shared by both engines — satori
+ * feeds body+head to satori-html, takumi passes the html string straight in. Use
+ * `<svelte:options css="injected" />` to get component styles into `head`.
+ */
+export declare function renderComponentToHtml(component: Component<any>, props?: Record<string, unknown>): {
+    head: string;
+    body: string;
+};