feat: add Takumi renderer support (#414)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: harlan-zw

docs/content/3.guides/0.takumi.md

@@ -0,0 +1,182 @@
+---
+title: Takumi Renderer
+description: Learn how to use the Takumi renderer for faster OG image generation.
+---
+
+[Takumi](https://github.com/kane50613/takumi) is an alternative renderer built on Rust that directly rasterizes to PNG/JPEG/WebP without an SVG intermediate step.
+
+It's designed as a faster alternative to [Satori](/docs/og-image/guides/satori) for simple templates, offering 2-10x better performance according to [Takumi benchmarks](https://takumi.kane.tw/docs/).
+
+::code-group
+
+```ts [Set Default]
+export default defineNuxtConfig({
+  ogImage: {
+    defaults: {
+      renderer: 'takumi'
+    }
+  }
+})
+```
+
+```ts [defineOgImage]
+defineOgImage({
+  renderer: 'takumi'
+})
+```
+
+```ts [defineOgImageComponent]
+defineOgImageComponent('MyOgImage', {
+  renderer: 'takumi'
+})
+```
+
+::
+
+## Installation
+
+Takumi requires installing the [`@takumi-rs/core`](https://www.npmjs.com/package/@takumi-rs/core) package for Node.js or [`@takumi-rs/wasm`](https://www.npmjs.com/package/@takumi-rs/wasm) for edge runtimes.
+
+::code-group
+
+```sh [pnpm]
+pnpm i -D @takumi-rs/core @takumi-rs/wasm
+```
+
+```bash [yarn]
+yarn add -D @takumi-rs/core @takumi-rs/wasm
+```
+
+```bash [npm]
+npm install -D @takumi-rs/core @takumi-rs/wasm
+```
+
+::
+
+## Pros
+
+- **2-10x faster** than Satori+Resvg for simple templates
+- Direct PNG/JPEG/WebP rasterization (no SVG intermediate)
+- Native [Tailwind CSS](https://tailwindcss.com/) support via `tw` prop
+- Works on Node.js and edge runtimes (WASM)
+- Variable font support
+- WOFF2 font format support
+- RTL text support
+- COLR emoji font support (e.g., Twemoji)
+
+## Cons
+
+- Limited CSS support compared to [Satori](/docs/og-image/guides/satori)
+- No gradient backgrounds
+- Opacity color syntax not fully supported
+- Some flexbox features missing
+
+## Limitations
+
+Takumi has more CSS limitations than Satori. It works best with simple, solid-color templates.
+
+For the full list of supported CSS properties, see the [Takumi documentation](https://takumi.kane.tw/docs/).
+
+### Supported Features
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Solid background colors | ✅ | `bg-gray-900`, `bg-blue-500` |
+| Basic flexbox | ✅ | `flex`, `items-center`, `justify-center` |
+| Text colors (solid) | ✅ | `text-white`, `text-gray-500` |
+| Font sizes and weights | ✅ | `text-6xl`, `font-bold` |
+| Rounded corners | ✅ | `rounded-lg`, `rounded-full` |
+| Emoji | ✅ | Via COLR fonts |
+| Images | ✅ | PNG, JPEG, WebP, SVG |
+| Padding and margin | ✅ | `p-4`, `m-2`, `gap-4` |
+| Width and height | ✅ | `w-full`, `h-16`, `w-[200px]` |
+
+### Unsupported Features
+
+| Feature | Status | Alternative |
+|---------|--------|-------------|
+| Gradient backgrounds | ❌ | Use solid colors or images |
+| Opacity colors (`/60`) | ❌ | Use full opacity colors |
+| `justify-between` | ❌ | Use explicit gaps or padding |
+| `flex-1`, `flex-grow` | ❌ | Use fixed widths |
+| CSS transforms | ❌ | Pre-transform images |
+| Box shadows | ❌ | Use border or images |
+
+::tip
+You can try Takumi in the [online playground](https://takumi.kane.tw/docs/) without any installation.
+::
+
+::warning
+For complex templates with gradients, shadows, or opacity, use the [Satori renderer](/docs/og-image/guides/satori) or [Chromium renderer](/docs/og-image/guides/chromium) instead.
+::
+
+## When to Use Takumi
+
+Takumi is ideal for:
+- Simple templates with solid colors
+- High-throughput scenarios where speed matters
+- Edge runtime deployments where bundle size is important
+- Sites with many pages that need fast OG image generation
+
+Consider [Satori](/docs/og-image/guides/satori) instead when:
+- You need gradient backgrounds
+- You need opacity/transparency effects
+- You need complex flexbox layouts
+
+Consider [Chromium](/docs/og-image/guides/chromium) instead when:
+- You need full CSS support
+- You're prerendering all images at build time
+
+## Example Template
+
+A Takumi-compatible template using only supported features:
+
+```vue
+<script setup lang="ts">
+defineProps<{
+  title: string
+  description?: string
+}>()
+</script>
+
+<template>
+  <div class="w-full h-full flex flex-col items-center justify-center bg-gray-900 text-white p-12">
+    <h1 class="text-6xl font-bold mb-4">
+      {{ title }}
+    </h1>
+    <p v-if="description" class="text-2xl text-gray-400">
+      {{ description }}
+    </p>
+  </div>
+</template>
+```
+
+## Runtime Compatibility
+
+Takumi supports both Node.js and WASM runtimes. The module automatically selects the appropriate binding based on your deployment target.
+
+| Environment | Binding | Notes |
+|-------------|---------|-------|
+| Node.js | `@takumi-rs/core` | Native performance |
+| Cloudflare Workers | `@takumi-rs/wasm` | WASM bundle |
+| Vercel Edge | `@takumi-rs/wasm` | WASM bundle |
+| Netlify Edge | `@takumi-rs/wasm` | WASM bundle |
+| AWS Lambda | `@takumi-rs/core` | Native performance |
+
+See the [Compatibility guide](/docs/og-image/guides/compatibility) for more details on runtime support.
+
+## Disabling Takumi
+
+If you have Takumi installed but want to disable it for specific environments:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  ogImage: {
+    compatibility: {
+      runtime: {
+        takumi: false
+      }
+    }
+  }
+})
+```

package.json

@@ -80,6 +80,7 @@
     "devalue": "catalog:",
     "execa": "catalog:",
     "image-size": "catalog:",
+    "linkedom": "catalog:",
     "magic-string": "catalog:",
     "mocked-exports": "catalog:",
     "nuxt-site-config": "catalog:",
@@ -122,6 +123,8 @@
     "@nuxtjs/eslint-config-typescript": "catalog:",
     "@nuxtjs/i18n": "catalog:",
     "@nuxtjs/tailwindcss": "catalog:",
+    "@takumi-rs/core": "catalog:",
+    "@takumi-rs/wasm": "catalog:",
     "@unocss/nuxt": "catalog:",
     "@unocss/preset-icons": "catalog:",
     "@unocss/runtime": "catalog:",