@zhin.js/html-renderer 3.0.14 → 3.0.16

package/src/config.ts

@@ -0,0 +1,173 @@
+import type {
+  FontConfig,
+  HtmlRendererAiTextAsImageConfig,
+  HtmlRendererConfig,
+  RasterFormat,
+  WaitUntil,
+} from './types.js';
+
+export interface ShotiumConfig {
+  viewport: { width: number; height: number };
+  scale: number;
+  type: RasterFormat;
+  quality: number;
+  timeout: number;
+  waitUntil: WaitUntil;
+  backgroundColor: string;
+  fontFamily: string;
+  maxImageHeight: number;
+  sliceCompression: number;
+  allowFileAccess: boolean;
+  takeOverHtmlSegments: boolean;
+  cacheDir: string;
+  cacheMaxBytes: number;
+  userAgent: string;
+  idleTimeoutMs: number;
+  logStats: boolean;
+  mode: 'inprocess' | 'daemon';
+}
+
+export interface ResolvedHtmlRendererConfig {
+  defaultWidth: number;
+  defaultFonts: FontConfig[];
+  defaultBackgroundColor: string;
+  aiTextAsImage?: boolean | HtmlRendererAiTextAsImageConfig;
+  shotium: ShotiumConfig;
+}
+
+const DEFAULT_CONFIG: ResolvedHtmlRendererConfig = {
+  defaultWidth: 800,
+  defaultFonts: [],
+  defaultBackgroundColor: '#ffffff',
+  aiTextAsImage: undefined,
+  shotium: {
+    mode: 'inprocess',
+    viewport: { width: 800, height: 600 },
+    scale: 1,
+    type: 'png',
+    quality: 90,
+    timeout: 30_000,
+    waitUntil: 'load',
+    backgroundColor: '#ffffff',
+    fontFamily:
+      '-apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", "Noto Sans SC", sans-serif',
+    maxImageHeight: 0,
+    sliceCompression: 3,
+    allowFileAccess: true,
+    takeOverHtmlSegments: true,
+    cacheDir: '',
+    cacheMaxBytes: 256 * 1024 * 1024,
+    userAgent: '',
+    idleTimeoutMs: 300_000,
+    logStats: false,
+  },
+};
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+function pickNumber(value: unknown, fallback: number, min: number, max: number): number {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? clamp(value, min, max)
+    : fallback;
+}
+
+function pickString<T extends string>(
+  value: unknown,
+  fallback: T,
+  allowed?: readonly T[],
+): T {
+  if (typeof value !== 'string') return fallback;
+  if (allowed && !allowed.includes(value as T)) return fallback;
+  return value as T;
+}
+
+function pickBoolean(value: unknown, fallback: boolean): boolean {
+  return typeof value === 'boolean' ? value : fallback;
+}
+
+function pickConfigRoot(raw: unknown): HtmlRendererConfig & Record<string, unknown> {
+  if (raw && typeof raw === 'object') {
+    const input = raw as HtmlRendererConfig & Record<string, unknown>;
+    if (input.htmlRenderer && typeof input.htmlRenderer === 'object') {
+      return input.htmlRenderer as HtmlRendererConfig & Record<string, unknown>;
+    }
+    return input;
+  }
+  return {};
+}
+
+export function resolveHtmlRendererConfig(raw: unknown): ResolvedHtmlRendererConfig {
+  const input = pickConfigRoot(raw);
+  const viewport = (input.viewport ?? {}) as Record<string, unknown>;
+  const defaultWidth = pickNumber(
+    input.defaultWidth ?? input.width ?? viewport.width,
+    DEFAULT_CONFIG.defaultWidth,
+    1,
+    30_000,
+  );
+  const defaultBackgroundColor = pickString(
+    input.defaultBackgroundColor ?? input.backgroundColor,
+    DEFAULT_CONFIG.defaultBackgroundColor,
+  );
+
+  return {
+    defaultWidth,
+    defaultFonts: Array.isArray(input.defaultFonts) ? input.defaultFonts.filter(Boolean) : [],
+    defaultBackgroundColor,
+    aiTextAsImage: input.aiTextAsImage,
+    shotium: {
+      mode: pickString(input.mode, DEFAULT_CONFIG.shotium.mode, ['inprocess', 'daemon']),
+      viewport: {
+        width: pickNumber(viewport.width ?? input.width ?? input.defaultWidth, defaultWidth, 1, 30_000),
+        height: pickNumber(viewport.height, DEFAULT_CONFIG.shotium.viewport.height, 1, 30_000),
+      },
+      scale: pickNumber(input.scale, DEFAULT_CONFIG.shotium.scale, 0.01, 8),
+      type: pickString(input.type, DEFAULT_CONFIG.shotium.type, ['png', 'jpeg', 'webp']),
+      quality: pickNumber(input.quality, DEFAULT_CONFIG.shotium.quality, 1, 100),
+      timeout: pickNumber(input.timeout, DEFAULT_CONFIG.shotium.timeout, 1, 600_000),
+      waitUntil: pickString(input.waitUntil, DEFAULT_CONFIG.shotium.waitUntil, ['load', 'networkidle']),
+      backgroundColor: pickString(
+        input.backgroundColor ?? input.defaultBackgroundColor,
+        defaultBackgroundColor,
+      ),
+      fontFamily: pickString(input.fontFamily, DEFAULT_CONFIG.shotium.fontFamily),
+      maxImageHeight: pickNumber(
+        input.maxImageHeight,
+        DEFAULT_CONFIG.shotium.maxImageHeight,
+        0,
+        100_000,
+      ),
+      sliceCompression: pickNumber(
+        input.sliceCompression,
+        DEFAULT_CONFIG.shotium.sliceCompression,
+        0,
+        9,
+      ),
+      allowFileAccess: pickBoolean(
+        input.allowFileAccess,
+        DEFAULT_CONFIG.shotium.allowFileAccess,
+      ),
+      takeOverHtmlSegments: pickBoolean(
+        input.takeOverHtmlSegments,
+        DEFAULT_CONFIG.shotium.takeOverHtmlSegments,
+      ),
+      cacheDir: pickString(input.cacheDir, DEFAULT_CONFIG.shotium.cacheDir),
+      cacheMaxBytes: pickNumber(
+        input.cacheMaxBytes,
+        DEFAULT_CONFIG.shotium.cacheMaxBytes,
+        0,
+        Number.MAX_SAFE_INTEGER,
+      ),
+      userAgent: pickString(input.userAgent, DEFAULT_CONFIG.shotium.userAgent),
+      idleTimeoutMs: pickNumber(
+        input.idleTimeoutMs,
+        DEFAULT_CONFIG.shotium.idleTimeoutMs,
+        0,
+        86_400_000,
+      ),
+      logStats: pickBoolean(input.logStats, DEFAULT_CONFIG.shotium.logStats),
+    },
+  };
+}

package/src/engine.ts

@@ -0,0 +1,121 @@
+import {
+  daemon,
+  releaseMemory,
+  screenshot,
+  start,
+  status,
+} from '@shotkit/shotium';
+
+import type {
+  DaemonClient,
+  ScreenshotOptions,
+  ScreenshotResult,
+  StartOptions,
+} from '@shotkit/shotium';
+import type { ShotiumConfig } from './config.js';
+import type { HtmlRendererLogger } from './types.js';
+
+interface Engine {
+  screenshot(options: ScreenshotOptions): Promise<ScreenshotResult>;
+  release(): void;
+  describe(): string;
+  close(): Promise<void>;
+}
+
+function toStartOptions(config: ShotiumConfig): StartOptions {
+  const options: StartOptions = { cacheMaxBytes: config.cacheMaxBytes };
+  const cacheDir = config.cacheDir.trim();
+  if (cacheDir === 'off') options.cacheDir = null;
+  else if (cacheDir) options.cacheDir = cacheDir;
+  if (config.userAgent) options.userAgent = config.userAgent;
+  return options;
+}
+
+function createInprocessEngine(config: ShotiumConfig, logger?: HtmlRendererLogger): Engine {
+  const options = toStartOptions(config);
+  let started = false;
+  let mismatchWarned = false;
+
+  const ensureStarted = (): void => {
+    if (started && status().running) return;
+    try {
+      const result = start(options);
+      logger?.debug?.(
+        `[shotium] in-process engine ready cache=${result.cacheActive ? result.cacheDir : 'off'}`,
+      );
+    } catch (error) {
+      if (!status().running) throw error;
+      if (!mismatchWarned) {
+        mismatchWarned = true;
+        logger?.warn?.(
+          '[shotium] engine already started with different cacheDir/userAgent; reusing current process engine',
+          error,
+        );
+      }
+    }
+    started = true;
+  };
+
+  return {
+    async screenshot(shot) {
+      ensureStarted();
+      return screenshot(shot);
+    },
+    release() {
+      if (status().running) releaseMemory();
+    },
+    describe: () => 'inprocess',
+    async close() {
+      if (status().running) releaseMemory({ releaseWorkingSet: true });
+    },
+  };
+}
+
+function createDaemonEngine(config: ShotiumConfig, logger?: HtmlRendererLogger): Engine {
+  const options = { ...toStartOptions(config), idleTimeoutMs: config.idleTimeoutMs };
+  let client: DaemonClient | null = null;
+  let pending: Promise<DaemonClient> | null = null;
+
+  const connect = async (): Promise<DaemonClient> => {
+    if (client) return client;
+    if (!pending) {
+      pending = daemon.connect(options)
+        .then((connected) => {
+          client = connected;
+          connected.once('close', () => {
+            client = null;
+            logger?.warn?.('[shotium] daemon connection closed; reconnecting on next render');
+          });
+          logger?.debug?.('[shotium] daemon engine connected');
+          return connected;
+        })
+        .finally(() => {
+          pending = null;
+        });
+    }
+    return pending;
+  };
+
+  return {
+    async screenshot(shot) {
+      try {
+        return await (await connect()).screenshot(shot);
+      } catch {
+        client = null;
+        return (await connect()).screenshot(shot);
+      }
+    },
+    release() {},
+    describe: () => 'daemon',
+    async close() {
+      client?.close();
+      client = null;
+    },
+  };
+}
+
+export function createEngine(config: ShotiumConfig, logger?: HtmlRendererLogger): Engine {
+  return config.mode === 'daemon'
+    ? createDaemonEngine(config, logger)
+    : createInprocessEngine(config, logger);
+}

package/src/html.ts

@@ -0,0 +1,113 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import type { FontConfig } from './types.js';
+
+interface WrapOptions {
+  width: number;
+  height?: number;
+  backgroundColor: string;
+  fontFamily: string;
+  fontFaces?: string;
+}
+
+const TEMP_ROOT = path.join(os.tmpdir(), 'zhin-shotium');
+const FONT_DIR = path.join(TEMP_ROOT, 'fonts');
+
+function escapeCssValue(value: string): string {
+  return value.replace(/[<>{};]/g, '');
+}
+
+function fontExtension(data: Buffer): string {
+  const tag = data.subarray(0, 4).toString('ascii');
+  if (tag === 'wOFF') return 'woff';
+  if (tag === 'wOF2') return 'woff2';
+  if (tag === 'OTTO') return 'otf';
+  if (tag === 'ttcf') return 'ttc';
+  return 'ttf';
+}
+
+function toBuffer(data: ArrayBuffer | Buffer): Buffer {
+  return Buffer.isBuffer(data) ? data : Buffer.from(new Uint8Array(data));
+}
+
+export function isFullDocument(html: string): boolean {
+  return /<!doctype\s+html|<html[\s>]/i.test(html);
+}
+
+export function wrapDocument(html: string, options: WrapOptions): string {
+  const fontFaces = options.fontFaces ?? '';
+
+  if (isFullDocument(html)) {
+    if (!fontFaces) return html;
+    const style = `<style>${fontFaces}</style>`;
+    if (/<\/head>/i.test(html)) return html.replace(/<\/head>/i, `${style}</head>`);
+    if (/<body[^>]*>/i.test(html)) {
+      return html.replace(/<body[^>]*>/i, (match) => `${match}${style}`);
+    }
+    return `${style}${html}`;
+  }
+
+  const height = options.height ? `min-height:${Math.round(options.height)}px;` : '';
+
+  return [
+    '<!DOCTYPE html>',
+    '<html><head><meta charset="utf-8">',
+    '<style>',
+    fontFaces,
+    '*,*::before,*::after{box-sizing:border-box}',
+    'html,body{margin:0;padding:0}',
+    `body{width:${Math.round(options.width)}px;${height}`,
+    `background:${escapeCssValue(options.backgroundColor)};`,
+    `font-family:${escapeCssValue(options.fontFamily)};`,
+    '-webkit-font-smoothing:antialiased}',
+    '</style></head><body>',
+    html,
+    '</body></html>',
+  ].join('');
+}
+
+export function buildFontFaces(fonts: readonly FontConfig[]): string {
+  if (fonts.length === 0) return '';
+
+  const rules: string[] = [];
+  for (const font of fonts) {
+    const data = toBuffer(font.data);
+    if (data.length === 0) continue;
+
+    const hash = crypto.createHash('sha1').update(data).digest('hex').slice(0, 16);
+    const file = path.join(FONT_DIR, `${hash}.${fontExtension(data)}`);
+    if (!fs.existsSync(file)) {
+      fs.mkdirSync(FONT_DIR, { recursive: true });
+      fs.writeFileSync(file, data);
+    }
+
+    rules.push(
+      '@font-face{'
+      + `font-family:"${escapeCssValue(font.name).replace(/"/g, '')}";`
+      + `font-weight:${font.weight ?? 400};`
+      + `font-style:${font.style === 'italic' ? 'italic' : 'normal'};`
+      + 'font-display:block;'
+      + `src:url("${pathToFileURL(file).href}")}`,
+    );
+  }
+  return rules.join('');
+}
+
+export async function withDocumentFile<T>(
+  document: string,
+  run: (file: string) => Promise<T>,
+): Promise<T> {
+  fs.mkdirSync(TEMP_ROOT, { recursive: true });
+  const name = `${process.pid}-${crypto.randomBytes(8).toString('hex')}.html`;
+  const file = path.join(TEMP_ROOT, name);
+  fs.writeFileSync(file, document, 'utf8');
+  try {
+    return await run(file);
+  } finally {
+    fs.rm(file, { force: true }, () => {});
+  }
+}

package/src/image.ts

@@ -0,0 +1,251 @@
+import zlib from 'node:zlib';
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+const CHANNELS: Record<number, number> = {
+  0: 1,
+  2: 3,
+  4: 2,
+  6: 4,
+};
+
+const CRC_TABLE = (() => {
+  const table = new Int32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) {
+      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    table[n] = c;
+  }
+  return table;
+})();
+
+function crc32(buf: Buffer): number {
+  let c = -1;
+  for (let i = 0; i < buf.length; i++) {
+    c = CRC_TABLE[(c ^ buf[i]!) & 0xff]! ^ (c >>> 8);
+  }
+  return (c ^ -1) >>> 0;
+}
+
+interface PngChunk {
+  type: string;
+  data: Buffer;
+}
+
+function readChunks(buf: Buffer): PngChunk[] | null {
+  if (buf.length < 8 || !buf.subarray(0, 8).equals(PNG_SIGNATURE)) return null;
+
+  const chunks: PngChunk[] = [];
+  let offset = 8;
+  while (offset + 8 <= buf.length) {
+    const length = buf.readUInt32BE(offset);
+    const type = buf.toString('ascii', offset + 4, offset + 8);
+    const start = offset + 8;
+    const end = start + length;
+    if (end + 4 > buf.length) return null;
+    chunks.push({ type, data: buf.subarray(start, end) });
+    offset = end + 4;
+    if (type === 'IEND') break;
+  }
+  return chunks;
+}
+
+function writeChunk(type: string, data: Buffer): Buffer {
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(data.length, 0);
+  const typeAndData = Buffer.concat([Buffer.from(type, 'ascii'), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(typeAndData), 0);
+  return Buffer.concat([length, typeAndData, crc]);
+}
+
+export function readImageSize(buf: Buffer): { width: number; height: number } | null {
+  const png = readPngInfo(buf);
+  if (png) return { width: png.width, height: png.height };
+  return readJpegSize(buf) ?? readWebpSize(buf);
+}
+
+export interface PngInfo {
+  width: number;
+  height: number;
+  bitDepth: number;
+  colorType: number;
+  interlace: number;
+}
+
+export function readPngInfo(buf: Buffer): PngInfo | null {
+  if (buf.length < 33 || !buf.subarray(0, 8).equals(PNG_SIGNATURE)) return null;
+  if (buf.toString('ascii', 12, 16) !== 'IHDR') return null;
+
+  return {
+    width: buf.readUInt32BE(16),
+    height: buf.readUInt32BE(20),
+    bitDepth: buf[24]!,
+    colorType: buf[25]!,
+    interlace: buf[28]!,
+  };
+}
+
+function readJpegSize(buf: Buffer): { width: number; height: number } | null {
+  if (buf.length < 4 || buf[0] !== 0xff || buf[1] !== 0xd8) return null;
+  let offset = 2;
+  while (offset + 9 < buf.length) {
+    if (buf[offset] !== 0xff) {
+      offset++;
+      continue;
+    }
+    const marker = buf[offset + 1]!;
+    if (marker === 0xff) {
+      offset++;
+      continue;
+    }
+    if (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd9) || marker === 0x01) {
+      offset += 2;
+      continue;
+    }
+    const length = buf.readUInt16BE(offset + 2);
+    const isFrameHeader = marker >= 0xc0 && marker <= 0xcf
+      && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+    if (isFrameHeader) {
+      return {
+        height: buf.readUInt16BE(offset + 5),
+        width: buf.readUInt16BE(offset + 7),
+      };
+    }
+    offset += 2 + length;
+  }
+  return null;
+}
+
+function readWebpSize(buf: Buffer): { width: number; height: number } | null {
+  if (buf.length < 30) return null;
+  if (buf.toString('ascii', 0, 4) !== 'RIFF' || buf.toString('ascii', 8, 12) !== 'WEBP') {
+    return null;
+  }
+  const chunk = buf.toString('ascii', 12, 16);
+  if (chunk === 'VP8X') {
+    return {
+      width: (buf.readUIntLE(24, 3) & 0xffffff) + 1,
+      height: (buf.readUIntLE(27, 3) & 0xffffff) + 1,
+    };
+  }
+  if (chunk === 'VP8 ') {
+    return {
+      width: buf.readUInt16LE(26) & 0x3fff,
+      height: buf.readUInt16LE(28) & 0x3fff,
+    };
+  }
+  if (chunk === 'VP8L') {
+    const bits = buf.readUInt32LE(21);
+    return {
+      width: (bits & 0x3fff) + 1,
+      height: ((bits >> 14) & 0x3fff) + 1,
+    };
+  }
+  return null;
+}
+
+function paeth(a: number, b: number, c: number): number {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  if (pb <= pc) return b;
+  return c;
+}
+
+function unfilter(filtered: Buffer, width: number, height: number, bpp: number): Buffer {
+  const stride = width * bpp;
+  const out = Buffer.alloc(stride * height);
+
+  for (let y = 0; y < height; y++) {
+    const filterType = filtered[y * (stride + 1)]!;
+    const src = y * (stride + 1) + 1;
+    const dst = y * stride;
+    const up = dst - stride;
+
+    for (let x = 0; x < stride; x++) {
+      const rawByte = filtered[src + x]!;
+      const a = x >= bpp ? out[dst + x - bpp]! : 0;
+      const b = y > 0 ? out[up + x]! : 0;
+      const c = x >= bpp && y > 0 ? out[up + x - bpp]! : 0;
+
+      let value: number;
+      switch (filterType) {
+        case 0: value = rawByte; break;
+        case 1: value = rawByte + a; break;
+        case 2: value = rawByte + b; break;
+        case 3: value = rawByte + ((a + b) >> 1); break;
+        case 4: value = rawByte + paeth(a, b, c); break;
+        default: value = rawByte;
+      }
+      out[dst + x] = value & 0xff;
+    }
+  }
+
+  return out;
+}
+
+export function splitPng(buf: Buffer, sliceHeight: number, level = 3): Buffer[] | null {
+  const info = readPngInfo(buf);
+  if (!info) return null;
+  if (info.interlace !== 0 || info.bitDepth !== 8) return null;
+
+  const channels = CHANNELS[info.colorType];
+  if (!channels) return null;
+
+  const height = Math.max(1, Math.floor(sliceHeight));
+  if (height >= info.height) return [buf];
+
+  const chunks = readChunks(buf);
+  if (!chunks) return null;
+
+  const idat = chunks.filter((item) => item.type === 'IDAT').map((item) => item.data);
+  if (idat.length === 0) return null;
+
+  let inflated: Buffer;
+  try {
+    inflated = zlib.inflateSync(Buffer.concat(idat));
+  } catch {
+    return null;
+  }
+
+  const stride = info.width * channels;
+  if (inflated.length < (stride + 1) * info.height) return null;
+
+  const pixels = unfilter(inflated, info.width, info.height, channels);
+  const extras = chunks.filter((item) =>
+    ['PLTE', 'tRNS', 'gAMA', 'sRGB', 'cHRM', 'iCCP', 'pHYs'].includes(item.type));
+
+  const list: Buffer[] = [];
+  for (let top = 0; top < info.height; top += height) {
+    const sliceRows = Math.min(height, info.height - top);
+    const body = Buffer.alloc((stride + 1) * sliceRows);
+    for (let y = 0; y < sliceRows; y++) {
+      body[y * (stride + 1)] = 0;
+      pixels.copy(body, y * (stride + 1) + 1, (top + y) * stride, (top + y + 1) * stride);
+    }
+
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(info.width, 0);
+    ihdr.writeUInt32BE(sliceRows, 4);
+    ihdr[8] = info.bitDepth;
+    ihdr[9] = info.colorType;
+    ihdr[10] = 0;
+    ihdr[11] = 0;
+    ihdr[12] = 0;
+
+    list.push(Buffer.concat([
+      PNG_SIGNATURE,
+      writeChunk('IHDR', ihdr),
+      ...extras.map((item) => writeChunk(item.type, item.data)),
+      writeChunk('IDAT', zlib.deflateSync(body, { level })),
+      writeChunk('IEND', Buffer.alloc(0)),
+    ]));
+  }
+
+  return list;
+}

package/src/index.ts

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