@ethercorps/sveltekit-og 4.2.1 → 4.3.0-next.10

package/README.md

@@ -6,8 +6,24 @@
 
 Dynamically generate Open Graph images from an HTML+CSS template or Svelte component using fast and efficient conversion from HTML > SVG > PNG. Based on [Satori](https://github.com/vercel/satori#documentation). No headless browser required.
 
+## Table of Contents
+
+- [SvelteKit Open Graph Image Generation](#sveltekit-open-graph-image-generation)
+    - [Table of Contents](#table-of-contents)
+    - [Docs](#docs)
+    - [Installation](#installation)
+    - [Usage](#usage)
+    - [Examples](#examples)
+    - [Contributing](#contributing)
+    - [Changelog](#changelog)
+    - [License](#license)
+    - [Acknowledgements](#acknowledgements)
+    - [Authors](#authors)
+    - [Contributors](#contributors)
+
 ## Docs
-- With `sveltekit-og@4`, we have [official documentation](https://sveltekit-og.dev). 
+
+For more detailed information and advanced usage, please refer to the [official documentation](https://sveltekit-og.dev).
 
 ## Installation
 
@@ -17,210 +33,28 @@ pnpm install @ethercorps/sveltekit-og
 
 ## Usage
 
-### Vite (Recommended)
-
-- Add vite plugin
-
-```typescript title="vite.cofig.js"
-import { sveltekit } from '@sveltejs/kit/vite';
-import { sveltekitOG } from '@ethercorps/sveltekit-og/plugin';
-const config = {
-	plugins: [sveltekit(), sveltekitOG()]
-};
- 
-export default config;
-```
-
-### Rollup (will be deprecated in v5)
-- Add `rollupWasm` to `build.rollupOptions.plugins` in `vite.cofig.js` file.
-- For more information, check [docs](https://sveltekit-og.dev/docs/getting-started)
-
-```ts title="vite.cofig.js"
-import { sveltekit } from '@sveltejs/kit/vite';
-import { defineConfig } from 'vitest/config';
-import { rollupWasm } from '@ethercorps/sveltekit-og/plugin';
-
-export default defineConfig({
-	plugins: [sveltekit()],
-	build: {
-		rollupOptions: {
-			plugins: [rollupWasm()],
-		}
-	}
-});
-```
-
-- For node adapter update config with `rollupWasm`
-- Check node runtime [docs](https://sveltekit-og.dev/docs/runtime/node)
-
-```ts title="vite.cofig.js"
-import { sveltekit } from '@sveltejs/kit/vite';
-import { defineConfig } from 'vitest/config';
-import { rollupWasm } from '@ethercorps/sveltekit-og/plugin';
-
-export default defineConfig({
-	plugins: [sveltekit()],
-	build: {
-		rollupOptions: {
-			plugins: [
-				rollupWasm({ esmImport: false })
-            ],
-		}
-	}
-});
-```
-
-- Create a file at `/src/routes/og/+server.ts`. Alternatively, you can use JavaScript by removing the types from this example.
-
-```typescript
-// src/routes/og/+server.ts
-import { ImageResponse } from '@ethercorps/sveltekit-og';
-import { RequestHandler } from './$types';
-
-const template = `
- <div tw="bg-gray-50 flex w-full h-full items-center justify-center">
-    <div tw="flex flex-col md:flex-row w-full py-12 px-4 md:items-center justify-between p-8">
-      <h2 tw="flex flex-col text-3xl sm:text-4xl font-bold tracking-tight text-gray-900 text-left">
-        <span>Ready to dive in?</span>
-        <span tw="text-indigo-600">Start your free trial today.</span>
-      </h2>
-      <div tw="mt-8 flex md:mt-0">
-        <div tw="flex rounded-md shadow">
-          <a href="#" tw="flex items-center justify-center rounded-md border border-transparent bg-indigo-600 px-5 py-3 text-base font-medium text-white">Get started</a>
-        </div>
-        <div tw="ml-3 flex rounded-md shadow">
-          <a href="#" tw="flex items-center justify-center rounded-md border border-transparent bg-white px-5 py-3 text-base font-medium text-indigo-600">Learn more</a>
-        </div>
-      </div>
-    </div>
-  </div>
-`;
-
-const fontFile = await fetch('https://og-playground.vercel.app/inter-latin-ext-400-normal.woff');
-const fontData: ArrayBuffer = await fontFile.arrayBuffer();
-
-export const GET: RequestHandler = async () => {
-  return await new ImageResponse(template, {
-    height: 630,
-    width: 1200,
-    fonts: [
-      {
-        name: 'Inter Latin',
-        data: fontData,
-        weight: 400
-      }
-    ]
-  });
-};
-```
-
-Then run `npm dev` and visit `localhost:5173/og` to view your generated PNG. Remember that hot module reloading does not work with server routes, so if you change your HTML or CSS, hard refresh the route to see changes.
-
-## Example Output
-
-![Rendered OG image](https://github.com/etherCorps/sveltekit-og/blob/main/static/og.png)
-
-## Headers
-
-When run in development, image headers contain `cache-control: no-cache, no-store`. In production, image headers contain `'cache-control': 'public, immutable, no-transform, max-age=31536000'`, which caches the image for 1 year. In both cases, the `'content-type': 'image/png'` is used.
-
-## Styling
-
-Notice that our example uses TailwindCSS classes (e.g. `tw="bg-gray-50"`). Alternatively, your HTML can contain style attributes using any of [the subset of CSS supported by Satori](https://github.com/vercel/satori#css).
-
-Satori supports only a subset of HTML and CSS. For full details, see [Satori’s documentation](https://github.com/vercel/satori#documentation). Notably, Satori only supports flex-based layouts.
-
-## Fonts
-
-Satori supports `ttf`, `otf`, and `woff` font formats; `woff2` is not supported. To maximize the font parsing speed, `ttf` or `otf` are recommended over `woff`.
-
-By default, `@ethercorps/sveltekit-og` includes only 'Noto Sans' font. If you need to use other fonts, you can specify them as shown in the example. Notably, you can also import a font file that is stored locally within your project and are not required to use fetch.
+For detailed usage instructions, please see the [Getting Started](https://sveltekit-og.dev/docs/getting-started) section of our documentation.
 
 ## Examples
 
-- `ImageResponse` · [_source_](/src/routes/+server.ts) · [_demo_](https://vercel.sveltekit-og.dev)
-- `Component Rendering` · [_source_](/src/routes/sc/+server.ts) · [_demo_](https://vercel.sveltekit-og.dev/sc)
-
-## API Reference
-
-The package exposes an `ImageResponse` constructors, with the following options available:
-
-```typescript
-import {ImageResponse} from '@ethercorps/sveltekit-og'
-import {SvelteComponent} from "svelte";
-
-ImageResponse(
-    element : string | Component,
-    options : {
-      width ? : number = 1200
-      height ? : number = 630,
-      backgroundColor ? : string = "#fff"
-      fonts ? : {
-          name: string,
-          data: ArrayBuffer,
-          weight: number,
-          style: 'normal' | 'italic'
-      }[]
-      debug ? : boolean = false
-      // Options that will be passed to the HTTP response
-      status ? : number = 200
-      statusText ? : string
-      headers ? : Record<string, string>
-    },
-    // Component props if components. 
-    ComponentProps<Component>
-  )
-```
-
-## Changelog
-
-### v4.0.0 (Breaking Changes)
-
-> Just install @ethercorps/sveltekit-og
-
-> Support for NodeJS, Deno, Cloudflare Pages, Cloudflare Workers, Vercel and Netlify.
-
-> No support for Bun tried and failed.
-
-
-### v3.0.0 (Breaking Changes)
-
-> Just install @ethercorps/sveltekit-og
-> No wasm as of now, only support for nodejs based runtime.
+- **ImageResponse**: [_source_](/src/routes/+server.ts) · [_demo_](https://vercel.sveltekit-og.dev)
+- **Component Rendering**: [_source_](/src/routes/sc/+server.ts) · [_demo_](https://vercel.sveltekit-og.dev/sc)
 
-### v1.2.3 Update (Breaking Changes)
+## Contributing
 
-> Now you have to install dependency by yourself which will make it easier to build for all plateforms.
+Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md) to get started.
 
-```
-npm i @resvg/resvg-js
-```
-
-```
-npm i satori
-```
-
-> From now on their will be no issues related to build, and soon this library going to have its own documentation.
-
-### v1.2.2 Update (Breaking Change)
-
-- We don't provide access to satori from `@ethercorps/sveltekit-og`.
-
-### v1.0.0 Update (Breaking Changes)
+## Changelog
 
-Finally, We have added html to react like element like object converter out of the box and with svelte compiler.
-Now you can use `{ toReactElement }` with `"@ethercorps/sveltekit-og"` like:
+All notable changes to this project are documented in the [changelog](CHANGELOG.md).
 
-- We have changed to function based instead of class based ImageResponse and componentToImageResponse.
-- Removed `@resvg/resvg-wasm` with `@resvg/resvg-js` because of internal errors.
-- Removed `satori-html` because now we have `toReactElement` out of the box with svelte compiler.
-  > If you find a problem related to undefined a please check [_vite.config.js_](/vite.config.ts) and add ` define: { _a: 'undefined' } in config.`
+## License
 
-> If you find any issue and have suggestion for this project please open a ticket and if you want to contribute please create a new discussion.
+This project is licensed under the [MIT License](LICENSE).
 
 ## Acknowledgements
 
-This project will not be possible without the following projects:
+This project would not be possible without the following projects:
 
 - [Satori & @vercel/og](https://github.com/vercel/satori)
 - [Noto by Google Fonts](https://fonts.google.com/noto)

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,32 +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>;
 }
-/** * A helper class to load Custom fonts, typically from local files.
- * The input must be a function provided by the user (e.g., using $app/server/read).
- */
 export declare class CustomFont extends BaseFont {
+    protected input: MayBePromise<Buffer | ArrayBuffer> | (() => MayBePromise<Buffer | ArrayBuffer>);
     private promise?;
-    /**
-     * Creates an instance of CustomFont.
-     * @param name The name of the font (for CSS font-family).
-     * @param input Font data as ArrayBuffer or a function that resolves to ArrayBuffer (user must provide the loading logic).
-     */
     constructor(name: string, input: MayBePromise<Buffer | ArrayBuffer> | (() => MayBePromise<Buffer | ArrayBuffer>), options?: BaseFontOptions);
-    /** A promise which resolves to font data as `ArrayBuffer` (Lazy load) */
+    /** 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,43 +15,47 @@ 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.");
     }
 }
-/** * A helper class to load Custom fonts, typically from local files.
- * The input must be a function provided by the user (e.g., using $app/server/read).
- */
 export class CustomFont extends BaseFont {
+    input;
     promise;
-    /**
-     * Creates an instance of CustomFont.
-     * @param name The name of the font (for CSS font-family).
-     * @param input Font data as ArrayBuffer or a function that resolves to ArrayBuffer (user must provide the loading logic).
-     */
     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) */
+    /** A promise which resolves to font data as `ArrayBuffer` (Lazy load and CACHED) */
     get data() {
-        // Defines the loading mechanism: execute the input function or resolve the promise/buffer.
-        const fallback = async () => (typeof this.input === 'function' ? this.input() : this.input);
-        // Memoization: ensures the input function is executed only once.
+        const cacheKey = `${this.name}-${this.weight}-${this.style}`;
+        const cachedData = FONT_CACHE_MAP.get(cacheKey);
+        if (cachedData) {
+            return Promise.resolve(cachedData);
+        }
+        const fallback = async () => {
+            const buffer = typeof this.input === "function" ? this.input() : this.input;
+            const resolvedBuffer = await buffer;
+            FONT_CACHE_MAP.set(cacheKey, resolvedBuffer);
+            return resolvedBuffer;
+        };
         this.promise = this.promise?.then(null, fallback) ?? fallback();
         return this.promise;
     }
 }
 /** 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('&')}`;
+    return `https://fonts.googleapis.com/css2?${Object.keys(params)
+        .map((key) => `${key}=${params[key]}`)
+        .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 +86,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 +110,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,4 @@
-import type { Component } from 'svelte';
-import type { ComponentOptions, ImageOptions } from '../types.js';
+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>>;

package/dist/helpers/create.js

@@ -1,38 +1,40 @@
-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 { handleAsyncAll, handleAsync, ErrorCodes } from "./error-handler.js";
 export async function createSvg(element, imageOptions, componentOptions) {
-    const [satori, vnodes] = await Promise.all([useSatori(), createVNode(element, componentOptions)]);
+    const log = createLogger(imageOptions.debug ?? false);
+    const [satori, vnodes] = await handleAsyncAll([() => useSatori(imageOptions.debug), () => Promise.resolve(createVNode(element, componentOptions))], ErrorCodes.SATORI_RENDER_FAILED, "Failed to initialize Satori or create VNode");
     const satoriOptions = structuredClone(imageOptions);
-    if (!Object.hasOwn(satoriOptions, 'fonts')) {
-        satoriOptions['fonts'] = await default_fonts();
+    if (!Object.hasOwn(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");
 }
 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,38 @@
+import { handleAsyncAll, validateResponse, ErrorCodes } from "./error-handler.js";
 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()]);
+    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.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,27 +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) => {
         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) => {

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

@@ -0,0 +1,37 @@
+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 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>;