@ethercorps/sveltekit-og 4.3.1-next.3 → 4.4.0-next.1

package/README.md

@@ -4,225 +4,67 @@
 
 # SvelteKit Open Graph Image Generation
 
-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.
+Dynamically generate Open Graph images from an HTML+CSS template or Svelte component. No headless browser required.
 
-## Docs
-- With `sveltekit-og@4`, we have [official documentation](https://sveltekit-og.dev). 
+Pick the rendering engine that fits your needs:
 
-## Installation
+- **Satori** (default) — HTML → SVG → PNG, based on [Satori](https://github.com/vercel/satori#documentation).
+- **[Takumi](https://takumi.kane.tw)** — a Rust/WASM engine with more output formats (`webp`, `jpeg`, `ico`, `svg`, …) and a built-in font, available from `@ethercorps/sveltekit-og/takumi` (v4.3.0+).
 
-```bash
-pnpm install @ethercorps/sveltekit-og
-```
+## Table of Contents
 
-## Usage
+- [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)
 
-### 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;
-```
+## Docs
 
-### 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 more detailed information and advanced usage, please refer to the [official documentation](https://sveltekit-og.dev).
 
-- 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 })
-            ],
-		}
-	}
-});
-```
+## Installation
 
-- 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
-      }
-    ]
-  });
-};
+```bash
+pnpm install @ethercorps/sveltekit-og
 ```
 
-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
+## Usage
 
-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`.
+For detailed usage instructions, please see the [Getting Started](https://sveltekit-og.dev/docs/getting-started) section of our documentation.
 
-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.
+Prefer the Takumi engine — more output formats and a built-in font? See the [Takumi Engine](https://sveltekit-og.dev/docs/usage/takumi) guide.
 
 ## 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)
+- **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)
 
-> Just install @ethercorps/sveltekit-og
-> No wasm as of now, only support for nodejs based runtime.
+## Contributing
 
-### v1.2.3 Update (Breaking Changes)
+Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md) to get started.
 
-> Now you have to install dependency by yourself which will make it easier to build for all plateforms.
-
-```
-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)
+- [Takumi](https://takumi.kane.tw)
 - [Noto by Google Fonts](https://fonts.google.com/noto)
 - [fineshopdesign](https://github.com/fineshopdesign/cf-wasm)
 

package/dist/client/component.d.ts

@@ -0,0 +1,19 @@
+import { type Component } from "svelte";
+/**
+ * Render a Svelte component to an HTML string in the browser. The server path uses
+ * `svelte/server`'s `render`, which isn't reliable client-side, so here we mount the
+ * component instead.
+ *
+ * Mounted inside a detached shadow root: the host is never added to the document, so
+ * page CSS can't cascade into the component (nothing from the page leaks into the
+ * rendered image), and the component's own scoped styles stay in the shadow root
+ * instead of piling up in the page's <head> on every render.
+ *
+ * Loaded lazily by render.js, only on the main thread and only when a component is
+ * passed — string-only users and workers never ship this (or Svelte's mount runtime).
+ *
+ * ponytail: captures innerHTML only — inline styles come through, but scoped /
+ * `css="injected"` styles won't (they're separate nodes an engine ignores). Use
+ * inline styles (or the `stylesheets`/tailwind options) for client component rendering.
+ */
+export declare function componentToHtml(component: Component<any>, props: Record<string, unknown>): string;

package/dist/client/component.js

@@ -0,0 +1,32 @@
+import { mount, unmount, flushSync } from "svelte";
+/**
+ * Render a Svelte component to an HTML string in the browser. The server path uses
+ * `svelte/server`'s `render`, which isn't reliable client-side, so here we mount the
+ * component instead.
+ *
+ * Mounted inside a detached shadow root: the host is never added to the document, so
+ * page CSS can't cascade into the component (nothing from the page leaks into the
+ * rendered image), and the component's own scoped styles stay in the shadow root
+ * instead of piling up in the page's <head> on every render.
+ *
+ * Loaded lazily by render.js, only on the main thread and only when a component is
+ * passed — string-only users and workers never ship this (or Svelte's mount runtime).
+ *
+ * ponytail: captures innerHTML only — inline styles come through, but scoped /
+ * `css="injected"` styles won't (they're separate nodes an engine ignores). Use
+ * inline styles (or the `stylesheets`/tailwind options) for client component rendering.
+ */
+export function componentToHtml(component, props) {
+    const host = document.createElement("div");
+    const shadow = host.attachShadow({ mode: "open" });
+    const target = document.createElement("div");
+    shadow.appendChild(target);
+    const instance = mount(component, { target, props });
+    try {
+        flushSync();
+        return target.innerHTML;
+    }
+    finally {
+        unmount(instance);
+    }
+}

package/dist/client/create.d.ts

@@ -0,0 +1,7 @@
+import type { Component, ComponentProps } from "svelte";
+import type { ClientImageResponseOptions } from "./types.js";
+/**
+ * Same API as the client `ImageResponse`, as a plain function. Returns a
+ * `Response` carrying the rendered image bytes.
+ */
+export declare function createImage<T extends string | Component<any>>(element: T, options?: ClientImageResponseOptions, props?: T extends Component<any> ? ComponentProps<T> : never): Response;

package/dist/client/create.js

@@ -0,0 +1,8 @@
+import { ImageResponse } from "./image-response.js";
+/**
+ * Same API as the client `ImageResponse`, as a plain function. Returns a
+ * `Response` carrying the rendered image bytes.
+ */
+export function createImage(element, options, props) {
+    return new ImageResponse(element, options, props);
+}

package/dist/client/engines/satori.d.ts

@@ -0,0 +1,4 @@
+import type { ImageOptions } from "../../types.js";
+/** Engine entry: HTML string in, svg string or png bytes out. Fonts are required here —
+ * render.js fills in the bundled defaults when the caller passes none. */
+export declare function render(html: string, options: ImageOptions): Promise<Uint8Array | string>;

package/dist/client/engines/satori.js

@@ -0,0 +1,81 @@
+import _satori, { init as initSatoriWasm } from "satori/standalone";
+import { Resvg as _Resvg, initWasm as initResvgWasm } from "@resvg/resvg-wasm";
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore - Vite resolves ?url to the emitted asset path
+import yogaUrl from "satori/yoga.wasm?url";
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore - Vite resolves ?url to the emitted asset path
+import resvgWasmUrl from "@resvg/resvg-wasm/index_bg.wasm?url";
+import { loadDynamicAsset } from "../../helpers/emoji.js";
+import { DEFAULT_WIDTH } from "../../helpers/defaults.js";
+import { createVNode } from "../../helpers/toJSX.js";
+import { createLogger } from "../../helpers/logger.js";
+import { handleAsync, ErrorCodes } from "../../helpers/error-handler.js";
+/*
+ * Browser/worker Satori + ReSVG engine. Loaded lazily by render.js so takumi users
+ * never download it. The wasm comes from same-origin bundler-emitted assets
+ * (Vite ?url + fetch(new URL(...))): no CORS, works in browsers and workers alike.
+ * Kept out of the server providers so neither bundle pulls in the other's runtime.
+ *
+ * Each init is memoized; a rejected init clears the cache so the next call retries.
+ */
+let satoriPromise;
+let resvgPromise;
+function useSatori() {
+    satoriPromise ??= (async () => {
+        const bytes = await fetch(new URL(yogaUrl, import.meta.url)).then((r) => r.arrayBuffer());
+        await initSatoriWasm(await WebAssembly.compile(bytes));
+        return _satori;
+    })().catch((error) => {
+        satoriPromise = undefined;
+        throw error;
+    });
+    return satoriPromise;
+}
+function useResvg() {
+    resvgPromise ??= (async () => {
+        await initResvgWasm(fetch(new URL(resvgWasmUrl, import.meta.url)));
+        return _Resvg;
+    })().catch((error) => {
+        resvgPromise = undefined;
+        throw error;
+    });
+    return resvgPromise;
+}
+/** Engine entry: HTML string in, svg string or png bytes out. Fonts are required here —
+ * render.js fills in the bundled defaults when the caller passes none. */
+export function render(html, options) {
+    return options.format === "svg" ? createSvg(html, options) : createPng(html, options);
+}
+async function createSvg(html, options) {
+    const log = createLogger(options.debug ?? false);
+    const vnodes = createVNode(html);
+    const satori = await handleAsync(() => useSatori(), ErrorCodes.SATORI_INIT_FAILED, "Failed to initialize Satori");
+    const satoriOptions = { ...options };
+    satoriOptions.loadAdditionalAsset = loadDynamicAsset({
+        emoji: options.emoji,
+    });
+    log.debug("Generating SVG with Satori (client)");
+    return handleAsync(() => satori(vnodes, satoriOptions), ErrorCodes.SATORI_RENDER_FAILED, "Failed to render SVG with Satori");
+}
+async function createPng(html, options) {
+    const log = createLogger(options.debug ?? false);
+    const svg = await createSvg(html, options);
+    const Resvg = await handleAsync(() => useResvg(), ErrorCodes.RESVG_INIT_FAILED, "Failed to initialize ReSVG");
+    const resvg_options = {
+        fitTo: { mode: "width", value: options.width || DEFAULT_WIDTH },
+    };
+    log.debug("Rendering PNG with ReSVG (client)");
+    return handleAsync(async () => {
+        // free the wasm-backed objects so repeated client renders don't grow wasm memory
+        const resvg = new Resvg(svg, resvg_options);
+        const rendered = resvg.render();
+        try {
+            return rendered.asPng();
+        }
+        finally {
+            rendered.free();
+            resvg.free();
+        }
+    }, ErrorCodes.RESVG_RENDER_FAILED, "Failed to render PNG with ReSVG");
+}

package/dist/client/engines/takumi.d.ts

@@ -0,0 +1,7 @@
+import type { TakumiImageOptions } from "../../takumi/types.js";
+/**
+ * Takumi engine boundary for the client. Exists only so render.js can `import()` it
+ * lazily (own Vite chunk); the actual render is the shared takumi path. Takumi's wasm
+ * embeds a sans-serif font, so no default fonts are injected here.
+ */
+export declare function render(html: string, options: TakumiImageOptions): Promise<Uint8Array | string>;

package/dist/client/engines/takumi.js

@@ -0,0 +1,9 @@
+import { createTakumiImage } from "../../takumi/render.js";
+/**
+ * Takumi engine boundary for the client. Exists only so render.js can `import()` it
+ * lazily (own Vite chunk); the actual render is the shared takumi path. Takumi's wasm
+ * embeds a sans-serif font, so no default fonts are injected here.
+ */
+export function render(html, options) {
+    return createTakumiImage(html, options);
+}

package/dist/client/fonts.d.ts

@@ -0,0 +1,2 @@
+import type { Font } from "../types.js";
+export declare function defaultClientFonts(): Promise<Font[]>;

package/dist/client/fonts.js

@@ -0,0 +1,36 @@
+import { handleAsync, ErrorCodes } from "../helpers/error-handler.js";
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore - Vite resolves ?url to the emitted asset path
+import regularUrl from "./assets/NotoSans-Regular.ttf?url";
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore - Vite resolves ?url to the emitted asset path
+import boldUrl from "./assets/NotoSans-Bold.ttf?url";
+/*
+ * Bundled fallback fonts for the client satori engine. The server falls back to a
+ * CDN that doesn't send CORS headers, so browsers can't use it; these ship with the
+ * package and are served same-origin from the consumer's own build output.
+ *
+ * Loaded once and memoized; a rejected load clears the memo so the next render retries.
+ * Takumi doesn't need this — its wasm embeds a sans-serif.
+ */
+let fontsPromise;
+export function defaultClientFonts() {
+    fontsPromise ??= load().catch((error) => {
+        fontsPromise = undefined;
+        throw error;
+    });
+    return fontsPromise;
+}
+async function fetchFont(url) {
+    const res = await fetch(new URL(url, import.meta.url));
+    if (!res.ok)
+        throw new Error(`${res.status} fetching ${url}`);
+    return res.arrayBuffer();
+}
+async function load() {
+    const [regular, bold] = await handleAsync(() => Promise.all([fetchFont(regularUrl), fetchFont(boldUrl)]), ErrorCodes.FONT_LOAD_FAILED, "Failed to load the bundled default fonts");
+    return [
+        { name: "Noto Sans", data: regular, weight: 400, style: "normal" },
+        { name: "Noto Sans", data: bold, weight: 700, style: "normal" },
+    ];
+}

package/dist/client/image-response.d.ts

@@ -0,0 +1,13 @@
+import type { Component, ComponentProps } from "svelte";
+import type { ClientImageResponseOptions } from "./types.js";
+/**
+ * Client-side OG image, rendered in the browser (or a worker) with the engine
+ * you pick via `options.engine` ("takumi" | "satori", defaults to "takumi").
+ * Extends `Response`, so consume it with `URL.createObjectURL(await res.blob())`.
+ */
+export declare class ImageResponse<T extends string | Component<any>> extends Response {
+    constructor(element: T, options?: ClientImageResponseOptions, props?: T extends Component<any> ? ComponentProps<T> : never);
+    arrayBuffer(): Promise<ArrayBuffer>;
+    blob(): Promise<Blob>;
+    text(): Promise<string>;
+}

package/dist/client/image-response.js

@@ -0,0 +1,88 @@
+import { createClientImage } from "./render.js";
+import { buildImageResponse, CONTENT_TYPES } from "../helpers/response.js";
+import { ImageResponseError, ErrorCodes } from "../helpers/error-handler.js";
+import { DEFAULT_WIDTH, DEFAULT_HEIGHT } from "../helpers/defaults.js";
+const DEFAULT_OPTIONS = {
+    engine: "takumi",
+    width: DEFAULT_WIDTH,
+    height: DEFAULT_HEIGHT,
+    format: "png",
+    emoji: "twemoji",
+    debug: false,
+};
+/**
+ * Client-side OG image, rendered in the browser (or a worker) with the engine
+ * you pick via `options.engine` ("takumi" | "satori", defaults to "takumi").
+ * Extends `Response`, so consume it with `URL.createObjectURL(await res.blob())`.
+ */
+export class ImageResponse extends Response {
+    constructor(element, options, props) {
+        const merged = { ...DEFAULT_OPTIONS, ...options };
+        const engine = (merged.engine ?? "takumi");
+        // Satori only emits png or svg; any other raster format renders as png, so pin it
+        // to png here too — otherwise the Content-Type would mislabel png bytes (e.g. webp).
+        const format = (engine === "satori" && merged.format !== "svg" ? "png" : (merged.format ?? "png"));
+        const opts = { ...merged, format };
+        // response-only fields live on both engine option shapes; read them off the raw input
+        const resp = (options ?? {});
+        const { body, init } = buildImageResponse(() => createClientImage(element, opts, props), {
+            label: format.toUpperCase(),
+            contentType: CONTENT_TYPES[format],
+            debug: merged.debug ?? false,
+            headers: resp.headers,
+            status: resp.status,
+            statusText: resp.statusText,
+        });
+        super(body, init);
+    }
+    /*
+     * Browsers turn an errored body stream into a bare `TypeError: Failed to fetch`
+     * when read through Response's own arrayBuffer()/blob()/text(), which drops the
+     * ImageResponseError (and its .code). Reading the stream directly keeps the
+     * original error, so override the three readers users actually call.
+     */
+    async arrayBuffer() {
+        const reader = this.body.getReader();
+        const chunks = [];
+        let size = 0;
+        for (;;) {
+            let step;
+            try {
+                step = await reader.read();
+            }
+            catch (error) {
+                throw unwrapRenderError(error);
+            }
+            if (step.done)
+                break;
+            chunks.push(step.value);
+            size += step.value.byteLength;
+        }
+        const out = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            out.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return out.buffer;
+    }
+    async blob() {
+        return new Blob([await this.arrayBuffer()], { type: this.headers.get("Content-Type") ?? "" });
+    }
+    async text() {
+        return new TextDecoder().decode(await this.arrayBuffer());
+    }
+}
+/**
+ * The shared body builder wraps every failure as UNKNOWN_ERROR "Failed to generate X"
+ * with the real error in `originalError`. Surface the inner one so callers can check
+ * `error.code` (e.g. COMPONENT_IN_WORKER, FONT_LOAD_FAILED).
+ * ponytail: unwrap here rather than change the shared helper; fold into the v3 realignment.
+ */
+function unwrapRenderError(error) {
+    return error instanceof ImageResponseError &&
+        error.code === ErrorCodes.UNKNOWN_ERROR &&
+        error.originalError instanceof ImageResponseError
+        ? error.originalError
+        : error;
+}

package/dist/client/index.d.ts

@@ -0,0 +1,4 @@
+export { ImageResponse } from "./image-response.js";
+export { createImage } from "./create.js";
+export type { ClientImageResponseOptions } from "./types.js";
+export { CustomFont, resolveFonts } from "../fonts.js";

package/dist/client/index.js

@@ -0,0 +1,6 @@
+export { ImageResponse } from "./image-response.js";
+export { createImage } from "./create.js";
+// CustomFont works anywhere (you supply the bytes); resolveFonts turns it into the
+// shape satori needs. GoogleFont/loadGoogleFont are deliberately not re-exported: a
+// browser can't set the User-Agent, so Google serves woff2 and the loader rejects it.
+export { CustomFont, resolveFonts } from "../fonts.js";

package/dist/client/render.d.ts

@@ -0,0 +1,7 @@
+import type { Component } from "svelte";
+import type { ClientImageResponseOptions } from "./types.js";
+/**
+ * Dispatch to the chosen engine, both running in the browser/worker. Response-only
+ * keys are stripped so they don't leak into the engine options.
+ */
+export declare function createClientImage(element: string | Component<any>, options: ClientImageResponseOptions, props?: Record<string, unknown>): Promise<Uint8Array | string>;

package/dist/client/render.js

@@ -0,0 +1,37 @@
+import { ImageResponseError, ErrorCodes } from "../helpers/error-handler.js";
+/** Components need the DOM to mount; workers have none. */
+const hasDocument = () => typeof document !== "undefined";
+async function toHtml(element, props) {
+    if (typeof element === "string")
+        return element;
+    if (!hasDocument()) {
+        throw new ImageResponseError("Svelte components can't be rendered in a worker (no document). Pass an HTML string instead.", ErrorCodes.COMPONENT_IN_WORKER);
+    }
+    // lazy: only main-thread component users download the mounter + Svelte's mount runtime
+    const { componentToHtml } = await import("./component.js");
+    return componentToHtml(element, props ?? {});
+}
+/**
+ * Dispatch to the chosen engine, both running in the browser/worker. Response-only
+ * keys are stripped so they don't leak into the engine options.
+ */
+export async function createClientImage(element, options, props) {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { engine = "takumi", status, statusText, headers, ...imageOptions } = options;
+    // components are rendered to HTML here (browser mount), so engines only ever see a string
+    const html = await toHtml(element, props);
+    // lazy: one Vite chunk per engine, so the other engine's JS + wasm are never fetched
+    if (engine === "satori") {
+        const satoriOptions = imageOptions;
+        // satori has no built-in font; use the bundled ones unless the caller passed some.
+        // Lives here (not in the engine) so it's unit-testable in node, where the engine can't run.
+        if (!satoriOptions.fonts?.length) {
+            const { defaultClientFonts } = await import("./fonts.js");
+            satoriOptions.fonts = await defaultClientFonts();
+        }
+        const { render } = await import("./engines/satori.js");
+        return render(html, satoriOptions);
+    }
+    const { render } = await import("./engines/takumi.js");
+    return render(html, imageOptions);
+}