@zhin.js/html-renderer 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 凉菜
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# @zhin.js/html-renderer
+
+HTML → PNG/SVG，供 Zhin.js 出站富媒体段（`segment.html` / `segment.markdown`）与可选 `aiTextAsImage` 使用。
+
+基于 `@zhin.js/satori` + `@resvg/resvg-js`，**不**再作为插件加载。
+
+## 安装
+
+```bash
+pnpm add @zhin.js/html-renderer
+```
+
+未安装时，Adapter policy 为 `html:'image'` / `markdown:'image'` 的出站会自动 **降级为 text** 并打一次 warning。
+
+## 配置（zhin.config.yml）
+
+```yaml
+htmlRenderer:
+  defaultWidth: 1080
+  defaultBackgroundColor: "#ffffff"
+  aiTextAsImage: false   # true 时纯文本出站转 PNG（before.sendMessage）
+```
+
+## API
+
+```typescript
+import { createHtmlRenderer } from '@zhin.js/html-renderer';
+
+const renderer = createHtmlRenderer({ defaultWidth: 540 });
+const png = await renderer.render('<div>Hello</div>', { format: 'png' });
+```
+
+Core 出站链通过动态 import 自动调用，业务代码通常只需 `segment.html({ html: '...' })`。
+
+## IM 组件与 Context（安装包后 zhin 启动自动注册）
+
+无需再写 plugins 列表，安装 `@zhin.js/html-renderer` 后启动时自动：
+
+| 能力 | 说明 |
+|------|------|
+| **`RenderImage` 组件** | 模板/命令中 `<RenderImage html="..." width="540"/>`，异步渲染为 `image` 段 |
+| **`html-renderer` Context** | `useContext('html-renderer', (r) => …)` 或 `inject('html-renderer')` |
+| **Agent 工具** | `html_render`、`html_card`（需已装 `@zhin.js/agent` 且 tool 服务可用） |
+
+自定义组件仍用 `defineComponent` + `addComponent`；需要转图时在组件内 `inject('html-renderer')` 或返回 `segment.html({ html })` 走出站 policy。

package/lib/ai-text-as-image.d.ts

@@ -0,0 +1,13 @@
+import type { SendContent, SendOptions } from '@zhin.js/core';
+import type { HtmlRendererConfig, HtmlRendererLogger, HtmlRendererService } from './types.js';
+export declare function extractPlainTextForImage(content: SendContent, skipIfRich: boolean): string | null;
+export declare function registerAiTextAsImageOutput(params: {
+    root: {
+        on: (ev: 'before.sendMessage', fn: (o: SendOptions) => unknown) => void;
+        off?: (ev: 'before.sendMessage', fn: (o: SendOptions) => unknown) => void;
+    };
+    logger: HtmlRendererLogger;
+    fullConfig: HtmlRendererConfig;
+    getRenderer: () => HtmlRendererService;
+}): (() => void) | undefined;
+//# sourceMappingURL=ai-text-as-image.d.ts.map

package/lib/ai-text-as-image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-text-as-image.d.ts","sourceRoot":"","sources":["../src/ai-text-as-image.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE9D,OAAO,KAAK,EAEV,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAgCpB,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,WAAW,EACpB,UAAU,EAAE,OAAO,GAClB,MAAM,GAAG,IAAI,CA0Bf;AAQD,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,IAAI,EAAE;QACJ,EAAE,EAAE,CAAC,EAAE,EAAE,oBAAoB,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,OAAO,KAAK,IAAI,CAAC;QACxE,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,oBAAoB,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,OAAO,KAAK,IAAI,CAAC;KAC3E,CAAC;IACF,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,kBAAkB,CAAC;IAC/B,WAAW,EAAE,MAAM,mBAAmB,CAAC;CACxC,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CA6D3B"}

package/lib/ai-text-as-image.js

@@ -0,0 +1,115 @@
+import { segment } from '@zhin.js/core';
+const RICH_STRING = /<\s*(image|video|audio|file|forward|xml|json|face|at)\b/i;
+function isAiImageFeatureOn(raw) {
+    if (raw === true)
+        return true;
+    if (raw == null || raw === false)
+        return false;
+    if (typeof raw === 'object' && raw.enabled === false)
+        return false;
+    return true;
+}
+function mergeAiConfig(base, raw) {
+    const obj = raw === true || raw === false || raw == null ? {} : raw;
+    return {
+        onlyAdapters: obj.onlyAdapters,
+        minLength: obj.minLength ?? 1,
+        maxLength: obj.maxLength ?? 12_000,
+        skipIfRich: obj.skipIfRich !== false,
+        width: obj.width ?? base.defaultWidth ?? 720,
+        height: obj.height,
+        backgroundColor: obj.backgroundColor ?? base.defaultBackgroundColor ?? '#ffffff',
+        fontSize: obj.fontSize ?? 16,
+        color: obj.color ?? '#1a1a1a',
+        padding: obj.padding ?? 20,
+        scale: obj.scale ?? 2,
+        fileName: obj.fileName ?? 'message.png',
+    };
+}
+export function extractPlainTextForImage(content, skipIfRich) {
+    const parts = (Array.isArray(content) ? content : [content]);
+    if (parts.length === 0)
+        return null;
+    const texts = [];
+    for (const p of parts) {
+        if (typeof p === 'string') {
+            if (skipIfRich && (RICH_STRING.test(p) || /\bCQ:/i.test(p)))
+                return null;
+            texts.push(p);
+            continue;
+        }
+        if (p == null || typeof p !== 'object')
+            return null;
+        const t = p.type;
+        if (typeof t !== 'string')
+            return null;
+        if (t !== 'text')
+            return null;
+        const raw = p.data?.text;
+        if (raw != null && typeof raw !== 'string')
+            return null;
+        texts.push(raw ?? '');
+    }
+    return texts.join('');
+}
+function buildPlainTextHtml(text, opts) {
+    const pad = opts.padding ?? 20;
+    const escaped = segment.escape(text);
+    return `<div style="display:flex;flex-direction:column;width:100%;box-sizing:border-box;padding:${pad}px;font-family:Noto Sans SC,sans-serif;font-size:${opts.fontSize}px;color:${opts.color};line-height:1.65;white-space:pre-wrap;word-break:break-word;">${escaped}</div>`;
+}
+export function registerAiTextAsImageOutput(params) {
+    const { root, logger, fullConfig, getRenderer } = params;
+    if (!isAiImageFeatureOn(fullConfig.aiTextAsImage)) {
+        logger.debug?.('html-renderer: aiTextAsImage 未启用');
+        return;
+    }
+    const aiOpts = mergeAiConfig(fullConfig, fullConfig.aiTextAsImage);
+    const handler = async (options) => {
+        try {
+            const { context, content } = options;
+            if (content == null)
+                return options;
+            if (aiOpts.onlyAdapters?.length && !aiOpts.onlyAdapters.includes(context)) {
+                return options;
+            }
+            const plain = extractPlainTextForImage(content, aiOpts.skipIfRich !== false);
+            if (plain == null)
+                return options;
+            const trimmed = plain.trim();
+            if (trimmed.length < (aiOpts.minLength ?? 1))
+                return options;
+            const maxLen = aiOpts.maxLength ?? 0;
+            if (maxLen > 0 && plain.length > maxLen) {
+                logger.debug?.(`html-renderer: 文本过长 (${plain.length}>${maxLen})，跳过转图`);
+                return options;
+            }
+            const html = buildPlainTextHtml(plain, aiOpts);
+            const renderer = getRenderer();
+            const result = await renderer.render(html, {
+                width: aiOpts.width,
+                height: aiOpts.height,
+                format: 'png',
+                backgroundColor: aiOpts.backgroundColor,
+                scale: aiOpts.scale,
+            });
+            if (result.format !== 'png' || typeof result.data !== 'object')
+                return options;
+            const base64 = Buffer.from(result.data).toString('base64');
+            const dataUrl = `data:${result.mimeType};base64,${base64}`;
+            return {
+                ...options,
+                content: segment('image', { url: dataUrl, name: aiOpts.fileName }),
+            };
+        }
+        catch (e) {
+            logger.warn?.('html-renderer: aiTextAsImage failed', e);
+            return options;
+        }
+    };
+    root.on('before.sendMessage', handler);
+    logger.info?.('html-renderer: aiTextAsImage enabled');
+    return () => {
+        root.off?.('before.sendMessage', handler);
+    };
+}
+//# sourceMappingURL=ai-text-as-image.js.map

package/lib/ai-text-as-image.js.map

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

package/lib/index.d.ts

@@ -0,0 +1,6 @@
+export { createHtmlRenderer } from './renderer.js';
+export { registerAiTextAsImageOutput, extractPlainTextForImage } from './ai-text-as-image.js';
+export type { FontConfig, HtmlRendererAiTextAsImageConfig, HtmlRendererConfig, HtmlRendererLogger, HtmlRendererService, OutputFormat, RenderOptions, RenderResult, } from './types.js';
+/** 动态 import 时使用的包名（与 package.json name 一致） */
+export declare const HTML_RENDERER_PACKAGE = "@zhin.js/html-renderer";
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,2BAA2B,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAC9F,YAAY,EACV,UAAU,EACV,+BAA+B,EAC/B,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,+CAA+C;AAC/C,eAAO,MAAM,qBAAqB,2BAA2B,CAAC"}

package/lib/index.js

@@ -0,0 +1,5 @@
+export { createHtmlRenderer } from './renderer.js';
+export { registerAiTextAsImageOutput, extractPlainTextForImage } from './ai-text-as-image.js';
+/** 动态 import 时使用的包名（与 package.json name 一致） */
+export const HTML_RENDERER_PACKAGE = '@zhin.js/html-renderer';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,2BAA2B,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAY9F,+CAA+C;AAC/C,MAAM,CAAC,MAAM,qBAAqB,GAAG,wBAAwB,CAAC"}

package/lib/renderer.d.ts

@@ -0,0 +1,3 @@
+import type { HtmlRendererConfig, HtmlRendererLogger, HtmlRendererService } from './types.js';
+export declare function createHtmlRenderer(config?: HtmlRendererConfig, logger?: HtmlRendererLogger): HtmlRendererService;
+//# sourceMappingURL=renderer.d.ts.map

package/lib/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAEV,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EAGpB,MAAM,YAAY,CAAC;AA0MpB,wBAAgB,kBAAkB,CAChC,MAAM,GAAE,kBAAuB,EAC/B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,mBAAmB,CA6ErB"}

package/lib/renderer.js

@@ -0,0 +1,216 @@
+import { htmlToSvg, getAllBuiltinFonts, h } from '@zhin.js/satori';
+import { Resvg } from '@resvg/resvg-js';
+const DEFAULT_CONFIG = {
+    defaultWidth: 800,
+    defaultFonts: [],
+    defaultBackgroundColor: '#ffffff',
+    cacheFonts: true,
+    fontUrls: [],
+};
+const fontCache = new Map();
+let defaultFontLoaded = false;
+function toFontConfig(f) {
+    return { name: f.name, data: f.data, weight: f.weight, style: f.style };
+}
+function uniqueFontsForRender(list) {
+    const m = new Map();
+    for (const f of list) {
+        const k = `${f.name}\0${f.weight ?? 400}\0${f.style ?? 'normal'}`;
+        m.set(k, f);
+    }
+    return [...m.values()];
+}
+function mergeFontLists(...lists) {
+    const flat = [];
+    for (const list of lists)
+        flat.push(...list);
+    return uniqueFontsForRender(flat);
+}
+function ensureBuiltinFontsCached(logger) {
+    if (defaultFontLoaded)
+        return;
+    try {
+        const builtinFonts = getAllBuiltinFonts();
+        if (builtinFonts.length > 0) {
+            for (const font of builtinFonts) {
+                const fc = toFontConfig(font);
+                fontCache.set(`${font.name}-${font.weight}`, fc);
+                logger?.debug?.(`Builtin font: ${font.name} (${Math.round(font.data.byteLength / 1024)}KB)`);
+            }
+            fontCache.set('default', toFontConfig(builtinFonts[0]));
+            defaultFontLoaded = true;
+            return;
+        }
+    }
+    catch (e) {
+        logger?.warn?.('html-renderer: builtin fonts failed', e);
+    }
+    defaultFontLoaded = true;
+    logger?.warn?.('html-renderer: no builtin fonts available');
+}
+function emojiToTwemojiUrl(emoji) {
+    const codePoints = [];
+    for (const char of emoji) {
+        const cp = char.codePointAt(0);
+        if (cp && cp !== 0xfe0f)
+            codePoints.push(cp.toString(16));
+    }
+    return `https://cdn.jsdelivr.net/gh/twitter/twemoji@14.0.2/assets/svg/${codePoints.join('-')}.svg`;
+}
+async function loadEmojiImage(emoji, logger) {
+    try {
+        const url = emojiToTwemojiUrl(emoji);
+        const response = await fetch(url);
+        if (!response.ok) {
+            logger?.debug?.(`Failed to load emoji ${emoji}: ${response.status}`);
+            return null;
+        }
+        const svg = await response.text();
+        return `data:image/svg+xml;base64,${Buffer.from(svg).toString('base64')}`;
+    }
+    catch (error) {
+        logger?.debug?.(`Failed to load emoji ${emoji}:`, error);
+        return null;
+    }
+}
+const emojiCache = new Map();
+async function loadAdditionalAsset(languageCode, segment, logger) {
+    if (languageCode === 'emoji') {
+        if (emojiCache.has(segment))
+            return emojiCache.get(segment);
+        const result = await loadEmojiImage(segment, logger);
+        if (result)
+            emojiCache.set(segment, result);
+        return result;
+    }
+    return null;
+}
+function wrapHtmlFragment(html, backgroundColor) {
+    if (html.includes('<!DOCTYPE') || html.includes('<html'))
+        return html;
+    return `<div style="display:flex;flex-direction:column;width:100%;height:100%;margin:0;padding:0;box-sizing:border-box;background-color:${backgroundColor};font-family:Noto Sans SC,sans-serif">${html}</div>`;
+}
+async function renderHtmlToSvg(html, width, height, fonts, backgroundColor, logger) {
+    ensureBuiltinFontsCached(logger);
+    const finalFonts = mergeFontLists(getAllBuiltinFonts().map(toFontConfig), fonts);
+    if (finalFonts.length === 0) {
+        logger?.warn?.('html-renderer: no fonts; non-ascii text may fail');
+    }
+    const svg = await htmlToSvg(wrapHtmlFragment(html, backgroundColor ?? '#ffffff'), {
+        width,
+        ...(height != null && { height }),
+        fonts: finalFonts.map((f) => ({
+            name: f.name,
+            data: f.data,
+            weight: f.weight,
+            style: f.style,
+        })),
+        loadAdditionalAsset: async (code, seg) => (await loadAdditionalAsset(code, seg, logger)) ?? '',
+    });
+    const wm = svg.match(/width="(\d+)"/);
+    const hm = svg.match(/height="(\d+)"/);
+    return {
+        svg,
+        width: wm ? parseInt(wm[1], 10) : width,
+        height: hm ? parseInt(hm[1], 10) : height || width,
+    };
+}
+function svgToPng(svg, scale = 1) {
+    const resvg = new Resvg(svg, {
+        fitTo: scale !== 1
+            ? {
+                mode: 'zoom',
+                value: scale,
+            }
+            : undefined,
+    });
+    const pngData = resvg.render();
+    return Buffer.from(pngData.asPng());
+}
+function serializeJsxToHtml(element) {
+    if (typeof element === 'string' || typeof element === 'number') {
+        return String(element);
+    }
+    if (element == null)
+        return '';
+    if (Array.isArray(element)) {
+        return element.map(serializeJsxToHtml).join('');
+    }
+    if (typeof element === 'object' && element !== null && 'type' in element) {
+        const { type, props = {} } = element;
+        const { children, style, dangerouslySetInnerHTML, ...restProps } = props;
+        let styleStr = '';
+        if (style && typeof style === 'object') {
+            styleStr = Object.entries(style)
+                .map(([key, value]) => `${key.replace(/([A-Z])/g, '-$1').toLowerCase()}: ${value}`)
+                .join('; ');
+        }
+        const attrs = Object.entries(restProps)
+            .filter(([key]) => key !== 'dangerouslySetInnerHTML')
+            .map(([key, value]) => `${key}="${value}"`)
+            .join(' ');
+        const styleAttr = styleStr ? ` style="${styleStr}"` : '';
+        const attrStr = attrs ? ` ${attrs}` : '';
+        if (dangerouslySetInnerHTML?.__html) {
+            return `<${type}${attrStr}${styleAttr}>${dangerouslySetInnerHTML.__html}</${type}>`;
+        }
+        const childrenHtml = children ? serializeJsxToHtml(children) : '';
+        const selfClosingTags = ['img', 'br', 'hr', 'input', 'meta', 'link'];
+        if (selfClosingTags.includes(type) && !childrenHtml) {
+            return `<${type}${attrStr}${styleAttr} />`;
+        }
+        return `<${type}${attrStr}${styleAttr}>${childrenHtml}</${type}>`;
+    }
+    return '';
+}
+export function createHtmlRenderer(config = {}, logger) {
+    const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+    ensureBuiltinFontsCached(logger);
+    for (const font of mergedConfig.defaultFonts) {
+        fontCache.set(`${font.name}-${font.weight || 400}`, font);
+    }
+    return {
+        async render(html, options = {}) {
+            const { width = mergedConfig.defaultWidth, height, format = 'png', backgroundColor = mergedConfig.defaultBackgroundColor, fonts = [], scale = 1, } = options;
+            ensureBuiltinFontsCached(logger);
+            const allFonts = uniqueFontsForRender([...fontCache.values(), ...fonts]);
+            const { svg, width: actualWidth, height: actualHeight } = await renderHtmlToSvg(html, width, height, allFonts, backgroundColor, logger);
+            if (format === 'svg') {
+                return {
+                    data: svg,
+                    format: 'svg',
+                    width: actualWidth,
+                    height: actualHeight,
+                    mimeType: 'image/svg+xml',
+                };
+            }
+            const png = svgToPng(svg, scale);
+            return {
+                data: png,
+                format: 'png',
+                width: Math.round(actualWidth * scale),
+                height: Math.round(actualHeight * scale),
+                mimeType: 'image/png',
+            };
+        },
+        async renderJsx(element, options = {}) {
+            return this.render(serializeJsxToHtml(element), options);
+        },
+        async renderComponent(component, props, options = {}) {
+            return this.render(h(component, props), options);
+        },
+        registerFont(font) {
+            fontCache.set(`${font.name}-${font.weight || 400}`, font);
+            logger?.debug?.(`Font registered: ${font.name}`);
+        },
+        getFonts() {
+            return Array.from(fontCache.values());
+        },
+        clearFonts() {
+            fontCache.clear();
+            defaultFontLoaded = false;
+            logger?.debug?.('Font cache cleared');
+        },
+    };
+}
+//# sourceMappingURL=renderer.js.map

package/lib/renderer.js.map

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

package/lib/types.d.ts

@@ -0,0 +1,61 @@
+import type { HtmlComponent } from '@zhin.js/satori';
+export type OutputFormat = 'svg' | 'png';
+export interface FontConfig {
+    name: string;
+    data: ArrayBuffer | Buffer;
+    weight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+    style?: 'normal' | 'italic';
+}
+export interface RenderOptions {
+    width?: number;
+    height?: number;
+    format?: OutputFormat;
+    backgroundColor?: string;
+    fonts?: FontConfig[];
+    enableEmoji?: boolean;
+    scale?: number;
+}
+export interface RenderResult {
+    data: Buffer | string;
+    format: OutputFormat;
+    width: number;
+    height: number;
+    mimeType: string;
+}
+export interface HtmlRendererAiTextAsImageConfig {
+    enabled?: boolean;
+    onlyAdapters?: string[];
+    minLength?: number;
+    maxLength?: number;
+    skipIfRich?: boolean;
+    width?: number;
+    height?: number;
+    backgroundColor?: string;
+    fontSize?: number;
+    color?: string;
+    padding?: number;
+    scale?: number;
+    fileName?: string;
+}
+export interface HtmlRendererConfig {
+    defaultWidth?: number;
+    defaultFonts?: FontConfig[];
+    defaultBackgroundColor?: string;
+    cacheFonts?: boolean;
+    fontUrls?: string[];
+    aiTextAsImage?: boolean | HtmlRendererAiTextAsImageConfig;
+}
+export interface HtmlRendererService {
+    render(html: string, options?: RenderOptions): Promise<RenderResult>;
+    renderJsx(element: unknown, options?: RenderOptions): Promise<RenderResult>;
+    renderComponent<P>(component: HtmlComponent<P>, props: P, options?: RenderOptions): Promise<RenderResult>;
+    registerFont(font: FontConfig): void;
+    getFonts(): FontConfig[];
+    clearFonts(): void;
+}
+export interface HtmlRendererLogger {
+    debug?: (...args: unknown[]) => void;
+    warn?: (...args: unknown[]) => void;
+    info?: (...args: unknown[]) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

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

package/lib/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@zhin.js/html-renderer",
+  "version": "0.0.1",
+  "description": "HTML to PNG/SVG for Zhin.js (satori + resvg); optional peer of zhin.js",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "README.md"
+  ],
+  "keywords": [
+    "zhin",
+    "zhin.js",
+    "html",
+    "image",
+    "satori",
+    "png"
+  ],
+  "author": {
+    "name": "lc-cn",
+    "email": "admin@liucl.cn",
+    "url": "https://github.com/lc-cn"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@resvg/resvg-js": "^2.6.2",
+    "@zhin.js/satori": "0.2.14"
+  },
+  "peerDependencies": {
+    "@zhin.js/core": "1.3.1"
+  },
+  "peerDependenciesMeta": {
+    "@zhin.js/core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "@zhin.js/core": "1.3.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "packages/toolkit/html-renderer"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "rimraf lib"
+  }
+}

package/src/ai-text-as-image.ts

@@ -0,0 +1,146 @@
+import type { SendContent, SendOptions } from '@zhin.js/core';
+import { segment } from '@zhin.js/core';
+import type {
+  HtmlRendererAiTextAsImageConfig,
+  HtmlRendererConfig,
+  HtmlRendererLogger,
+  HtmlRendererService,
+} from './types.js';
+
+const RICH_STRING = /<\s*(image|video|audio|file|forward|xml|json|face|at)\b/i;
+
+function isAiImageFeatureOn(raw: HtmlRendererConfig['aiTextAsImage']): boolean {
+  if (raw === true) return true;
+  if (raw == null || raw === false) return false;
+  if (typeof raw === 'object' && raw.enabled === false) return false;
+  return true;
+}
+
+function mergeAiConfig(
+  base: HtmlRendererConfig,
+  raw: HtmlRendererConfig['aiTextAsImage'],
+): HtmlRendererAiTextAsImageConfig {
+  const obj = raw === true || raw === false || raw == null ? {} : raw;
+  return {
+    onlyAdapters: obj.onlyAdapters,
+    minLength: obj.minLength ?? 1,
+    maxLength: obj.maxLength ?? 12_000,
+    skipIfRich: obj.skipIfRich !== false,
+    width: obj.width ?? base.defaultWidth ?? 720,
+    height: obj.height,
+    backgroundColor: obj.backgroundColor ?? base.defaultBackgroundColor ?? '#ffffff',
+    fontSize: obj.fontSize ?? 16,
+    color: obj.color ?? '#1a1a1a',
+    padding: obj.padding ?? 20,
+    scale: obj.scale ?? 2,
+    fileName: obj.fileName ?? 'message.png',
+  };
+}
+
+export function extractPlainTextForImage(
+  content: SendContent,
+  skipIfRich: boolean,
+): string | null {
+  const parts = (Array.isArray(content) ? content : [content]) as (
+    | string
+    | { type?: unknown; data?: Record<string, unknown> }
+  )[];
+
+  if (parts.length === 0) return null;
+
+  const texts: string[] = [];
+
+  for (const p of parts) {
+    if (typeof p === 'string') {
+      if (skipIfRich && (RICH_STRING.test(p) || /\bCQ:/i.test(p))) return null;
+      texts.push(p);
+      continue;
+    }
+    if (p == null || typeof p !== 'object') return null;
+    const t = p.type;
+    if (typeof t !== 'string') return null;
+    if (t !== 'text') return null;
+    const raw = p.data?.text;
+    if (raw != null && typeof raw !== 'string') return null;
+    texts.push(raw ?? '');
+  }
+
+  return texts.join('');
+}
+
+function buildPlainTextHtml(text: string, opts: HtmlRendererAiTextAsImageConfig): string {
+  const pad = opts.padding ?? 20;
+  const escaped = segment.escape(text);
+  return `<div style="display:flex;flex-direction:column;width:100%;box-sizing:border-box;padding:${pad}px;font-family:Noto Sans SC,sans-serif;font-size:${opts.fontSize}px;color:${opts.color};line-height:1.65;white-space:pre-wrap;word-break:break-word;">${escaped}</div>`;
+}
+
+export function registerAiTextAsImageOutput(params: {
+  root: {
+    on: (ev: 'before.sendMessage', fn: (o: SendOptions) => unknown) => void;
+    off?: (ev: 'before.sendMessage', fn: (o: SendOptions) => unknown) => void;
+  };
+  logger: HtmlRendererLogger;
+  fullConfig: HtmlRendererConfig;
+  getRenderer: () => HtmlRendererService;
+}): (() => void) | undefined {
+  const { root, logger, fullConfig, getRenderer } = params;
+
+  if (!isAiImageFeatureOn(fullConfig.aiTextAsImage)) {
+    logger.debug?.('html-renderer: aiTextAsImage 未启用');
+    return;
+  }
+
+  const aiOpts = mergeAiConfig(fullConfig, fullConfig.aiTextAsImage);
+
+  const handler = async (options: SendOptions) => {
+    try {
+      const { context, content } = options;
+      if (content == null) return options;
+
+      if (aiOpts.onlyAdapters?.length && !aiOpts.onlyAdapters.includes(context)) {
+        return options;
+      }
+
+      const plain = extractPlainTextForImage(content, aiOpts.skipIfRich !== false);
+      if (plain == null) return options;
+
+      const trimmed = plain.trim();
+      if (trimmed.length < (aiOpts.minLength ?? 1)) return options;
+      const maxLen = aiOpts.maxLength ?? 0;
+      if (maxLen > 0 && plain.length > maxLen) {
+        logger.debug?.(`html-renderer: 文本过长 (${plain.length}>${maxLen})，跳过转图`);
+        return options;
+      }
+
+      const html = buildPlainTextHtml(plain, aiOpts);
+      const renderer = getRenderer();
+      const result = await renderer.render(html, {
+        width: aiOpts.width,
+        height: aiOpts.height,
+        format: 'png',
+        backgroundColor: aiOpts.backgroundColor,
+        scale: aiOpts.scale,
+      });
+
+      if (result.format !== 'png' || typeof result.data !== 'object') return options;
+
+      const base64 = Buffer.from(result.data as Buffer).toString('base64');
+      const dataUrl = `data:${result.mimeType};base64,${base64}`;
+
+      return {
+        ...options,
+        content: segment('image', { url: dataUrl, name: aiOpts.fileName }),
+      };
+    } catch (e) {
+      logger.warn?.('html-renderer: aiTextAsImage failed', e);
+      return options;
+    }
+  };
+
+  root.on('before.sendMessage', handler);
+  logger.info?.('html-renderer: aiTextAsImage enabled');
+
+  return () => {
+    root.off?.('before.sendMessage', handler);
+  };
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export { createHtmlRenderer } from './renderer.js';
+export { registerAiTextAsImageOutput, extractPlainTextForImage } from './ai-text-as-image.js';
+export type {
+  FontConfig,
+  HtmlRendererAiTextAsImageConfig,
+  HtmlRendererConfig,
+  HtmlRendererLogger,
+  HtmlRendererService,
+  OutputFormat,
+  RenderOptions,
+  RenderResult,
+} from './types.js';
+
+/** 动态 import 时使用的包名（与 package.json name 一致） */
+export const HTML_RENDERER_PACKAGE = '@zhin.js/html-renderer';

package/src/renderer.ts

@@ -0,0 +1,293 @@
+import { htmlToSvg, getAllBuiltinFonts, h } from '@zhin.js/satori';
+import type { HtmlComponent } from '@zhin.js/satori';
+import { Resvg } from '@resvg/resvg-js';
+import type {
+  FontConfig,
+  HtmlRendererConfig,
+  HtmlRendererLogger,
+  HtmlRendererService,
+  RenderOptions,
+  RenderResult,
+} from './types.js';
+
+const DEFAULT_CONFIG: Required<Omit<HtmlRendererConfig, 'aiTextAsImage'>> = {
+  defaultWidth: 800,
+  defaultFonts: [],
+  defaultBackgroundColor: '#ffffff',
+  cacheFonts: true,
+  fontUrls: [],
+};
+
+const fontCache: Map<string, FontConfig> = new Map();
+let defaultFontLoaded = false;
+
+function toFontConfig(f: {
+  name: string;
+  data: ArrayBuffer | Buffer;
+  weight?: FontConfig['weight'];
+  style?: FontConfig['style'];
+}): FontConfig {
+  return { name: f.name, data: f.data, weight: f.weight, style: f.style };
+}
+
+function uniqueFontsForRender(list: FontConfig[]): FontConfig[] {
+  const m = new Map<string, FontConfig>();
+  for (const f of list) {
+    const k = `${f.name}\0${f.weight ?? 400}\0${f.style ?? 'normal'}`;
+    m.set(k, f);
+  }
+  return [...m.values()];
+}
+
+function mergeFontLists(...lists: FontConfig[][]): FontConfig[] {
+  const flat: FontConfig[] = [];
+  for (const list of lists) flat.push(...list);
+  return uniqueFontsForRender(flat);
+}
+
+function ensureBuiltinFontsCached(logger?: HtmlRendererLogger): void {
+  if (defaultFontLoaded) return;
+
+  try {
+    const builtinFonts = getAllBuiltinFonts();
+    if (builtinFonts.length > 0) {
+      for (const font of builtinFonts) {
+        const fc = toFontConfig(font);
+        fontCache.set(`${font.name}-${font.weight}`, fc);
+        logger?.debug?.(`Builtin font: ${font.name} (${Math.round(font.data.byteLength / 1024)}KB)`);
+      }
+      fontCache.set('default', toFontConfig(builtinFonts[0]));
+      defaultFontLoaded = true;
+      return;
+    }
+  } catch (e) {
+    logger?.warn?.('html-renderer: builtin fonts failed', e);
+  }
+  defaultFontLoaded = true;
+  logger?.warn?.('html-renderer: no builtin fonts available');
+}
+
+function emojiToTwemojiUrl(emoji: string): string {
+  const codePoints: string[] = [];
+  for (const char of emoji) {
+    const cp = char.codePointAt(0);
+    if (cp && cp !== 0xfe0f) codePoints.push(cp.toString(16));
+  }
+  return `https://cdn.jsdelivr.net/gh/twitter/twemoji@14.0.2/assets/svg/${codePoints.join('-')}.svg`;
+}
+
+async function loadEmojiImage(emoji: string, logger?: HtmlRendererLogger): Promise<string | null> {
+  try {
+    const url = emojiToTwemojiUrl(emoji);
+    const response = await fetch(url);
+    if (!response.ok) {
+      logger?.debug?.(`Failed to load emoji ${emoji}: ${response.status}`);
+      return null;
+    }
+    const svg = await response.text();
+    return `data:image/svg+xml;base64,${Buffer.from(svg).toString('base64')}`;
+  } catch (error) {
+    logger?.debug?.(`Failed to load emoji ${emoji}:`, error);
+    return null;
+  }
+}
+
+const emojiCache: Map<string, string> = new Map();
+
+async function loadAdditionalAsset(
+  languageCode: string,
+  segment: string,
+  logger?: HtmlRendererLogger,
+): Promise<string | null> {
+  if (languageCode === 'emoji') {
+    if (emojiCache.has(segment)) return emojiCache.get(segment)!;
+    const result = await loadEmojiImage(segment, logger);
+    if (result) emojiCache.set(segment, result);
+    return result;
+  }
+  return null;
+}
+
+function wrapHtmlFragment(html: string, backgroundColor: string): string {
+  if (html.includes('<!DOCTYPE') || html.includes('<html')) return html;
+  return `<div style="display:flex;flex-direction:column;width:100%;height:100%;margin:0;padding:0;box-sizing:border-box;background-color:${backgroundColor};font-family:Noto Sans SC,sans-serif">${html}</div>`;
+}
+
+async function renderHtmlToSvg(
+  html: string,
+  width: number,
+  height: number | undefined,
+  fonts: FontConfig[],
+  backgroundColor: string | undefined,
+  logger?: HtmlRendererLogger,
+): Promise<{ svg: string; width: number; height: number }> {
+  ensureBuiltinFontsCached(logger);
+  const finalFonts = mergeFontLists(getAllBuiltinFonts().map(toFontConfig), fonts);
+  if (finalFonts.length === 0) {
+    logger?.warn?.('html-renderer: no fonts; non-ascii text may fail');
+  }
+
+  const svg = await htmlToSvg(wrapHtmlFragment(html, backgroundColor ?? '#ffffff'), {
+    width,
+    ...(height != null && { height }),
+    fonts: finalFonts.map((f) => ({
+      name: f.name,
+      data: f.data,
+      weight: f.weight,
+      style: f.style,
+    })),
+    loadAdditionalAsset: async (code, seg) =>
+      (await loadAdditionalAsset(code, seg, logger)) ?? '',
+  });
+
+  const wm = svg.match(/width="(\d+)"/);
+  const hm = svg.match(/height="(\d+)"/);
+  return {
+    svg,
+    width: wm ? parseInt(wm[1], 10) : width,
+    height: hm ? parseInt(hm[1], 10) : height || width,
+  };
+}
+
+function svgToPng(svg: string, scale: number = 1): Buffer {
+  const resvg = new Resvg(svg, {
+    fitTo:
+      scale !== 1
+        ? {
+            mode: 'zoom',
+            value: scale,
+          }
+        : undefined,
+  });
+  const pngData = resvg.render();
+  return Buffer.from(pngData.asPng());
+}
+
+function serializeJsxToHtml(element: unknown): string {
+  if (typeof element === 'string' || typeof element === 'number') {
+    return String(element);
+  }
+  if (element == null) return '';
+  if (Array.isArray(element)) {
+    return element.map(serializeJsxToHtml).join('');
+  }
+  if (typeof element === 'object' && element !== null && 'type' in element) {
+    const { type, props = {} } = element as { type: string; props?: Record<string, unknown> };
+    const { children, style, dangerouslySetInnerHTML, ...restProps } = props as {
+      children?: unknown;
+      style?: Record<string, unknown>;
+      dangerouslySetInnerHTML?: { __html?: string };
+    };
+
+    let styleStr = '';
+    if (style && typeof style === 'object') {
+      styleStr = Object.entries(style)
+        .map(([key, value]) => `${key.replace(/([A-Z])/g, '-$1').toLowerCase()}: ${value}`)
+        .join('; ');
+    }
+
+    const attrs = Object.entries(restProps)
+      .filter(([key]) => key !== 'dangerouslySetInnerHTML')
+      .map(([key, value]) => `${key}="${value}"`)
+      .join(' ');
+
+    const styleAttr = styleStr ? ` style="${styleStr}"` : '';
+    const attrStr = attrs ? ` ${attrs}` : '';
+
+    if (dangerouslySetInnerHTML?.__html) {
+      return `<${type}${attrStr}${styleAttr}>${dangerouslySetInnerHTML.__html}</${type}>`;
+    }
+
+    const childrenHtml = children ? serializeJsxToHtml(children) : '';
+    const selfClosingTags = ['img', 'br', 'hr', 'input', 'meta', 'link'];
+    if (selfClosingTags.includes(type) && !childrenHtml) {
+      return `<${type}${attrStr}${styleAttr} />`;
+    }
+
+    return `<${type}${attrStr}${styleAttr}>${childrenHtml}</${type}>`;
+  }
+
+  return '';
+}
+
+export function createHtmlRenderer(
+  config: HtmlRendererConfig = {},
+  logger?: HtmlRendererLogger,
+): HtmlRendererService {
+  const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+  ensureBuiltinFontsCached(logger);
+  for (const font of mergedConfig.defaultFonts) {
+    fontCache.set(`${font.name}-${font.weight || 400}`, font);
+  }
+
+  return {
+    async render(html: string, options: RenderOptions = {}): Promise<RenderResult> {
+      const {
+        width = mergedConfig.defaultWidth,
+        height,
+        format = 'png',
+        backgroundColor = mergedConfig.defaultBackgroundColor,
+        fonts = [],
+        scale = 1,
+      } = options;
+
+      ensureBuiltinFontsCached(logger);
+      const allFonts = uniqueFontsForRender([...fontCache.values(), ...fonts]);
+
+      const { svg, width: actualWidth, height: actualHeight } = await renderHtmlToSvg(
+        html,
+        width,
+        height,
+        allFonts,
+        backgroundColor,
+        logger,
+      );
+
+      if (format === 'svg') {
+        return {
+          data: svg,
+          format: 'svg',
+          width: actualWidth,
+          height: actualHeight,
+          mimeType: 'image/svg+xml',
+        };
+      }
+
+      const png = svgToPng(svg, scale);
+      return {
+        data: png,
+        format: 'png',
+        width: Math.round(actualWidth * scale),
+        height: Math.round(actualHeight * scale),
+        mimeType: 'image/png',
+      };
+    },
+
+    async renderJsx(element: unknown, options: RenderOptions = {}): Promise<RenderResult> {
+      return this.render(serializeJsxToHtml(element), options);
+    },
+
+    async renderComponent<P>(
+      component: HtmlComponent<P>,
+      props: P,
+      options: RenderOptions = {},
+    ): Promise<RenderResult> {
+      return this.render(h(component, props), options);
+    },
+
+    registerFont(font: FontConfig): void {
+      fontCache.set(`${font.name}-${font.weight || 400}`, font);
+      logger?.debug?.(`Font registered: ${font.name}`);
+    },
+
+    getFonts(): FontConfig[] {
+      return Array.from(fontCache.values());
+    },
+
+    clearFonts(): void {
+      fontCache.clear();
+      defaultFontLoaded = false;
+      logger?.debug?.('Font cache cleared');
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,72 @@
+import type { HtmlComponent } from '@zhin.js/satori';
+
+export type OutputFormat = 'svg' | 'png';
+
+export interface FontConfig {
+  name: string;
+  data: ArrayBuffer | Buffer;
+  weight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+  style?: 'normal' | 'italic';
+}
+
+export interface RenderOptions {
+  width?: number;
+  height?: number;
+  format?: OutputFormat;
+  backgroundColor?: string;
+  fonts?: FontConfig[];
+  enableEmoji?: boolean;
+  scale?: number;
+}
+
+export interface RenderResult {
+  data: Buffer | string;
+  format: OutputFormat;
+  width: number;
+  height: number;
+  mimeType: string;
+}
+
+export interface HtmlRendererAiTextAsImageConfig {
+  enabled?: boolean;
+  onlyAdapters?: string[];
+  minLength?: number;
+  maxLength?: number;
+  skipIfRich?: boolean;
+  width?: number;
+  height?: number;
+  backgroundColor?: string;
+  fontSize?: number;
+  color?: string;
+  padding?: number;
+  scale?: number;
+  fileName?: string;
+}
+
+export interface HtmlRendererConfig {
+  defaultWidth?: number;
+  defaultFonts?: FontConfig[];
+  defaultBackgroundColor?: string;
+  cacheFonts?: boolean;
+  fontUrls?: string[];
+  aiTextAsImage?: boolean | HtmlRendererAiTextAsImageConfig;
+}
+
+export interface HtmlRendererService {
+  render(html: string, options?: RenderOptions): Promise<RenderResult>;
+  renderJsx(element: unknown, options?: RenderOptions): Promise<RenderResult>;
+  renderComponent<P>(
+    component: HtmlComponent<P>,
+    props: P,
+    options?: RenderOptions,
+  ): Promise<RenderResult>;
+  registerFont(font: FontConfig): void;
+  getFonts(): FontConfig[];
+  clearFonts(): void;
+}
+
+export interface HtmlRendererLogger {
+  debug?: (...args: unknown[]) => void;
+  warn?: (...args: unknown[]) => void;
+  info?: (...args: unknown[]) => void;
+}