@karinjs/plugin-shotium 0.0.1 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KarinJS
+
+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

@@ -1,3 +1,147 @@
 # @karinjs/plugin-shotium
 
-Placeholder release. Real content is published via CI (OIDC).
+karin 的 [shotium](https://github.com/sj817/shotium) 截图渲染插件。
+
+shotium 是一个被裁剪过的 chromium：只留下 Blink 布局、Skia CPU 光栅化、字体与图片解码，以及 chromium 的网络栈，
+V8、content 框架、GPU 进程、DevTools 协议全部拿掉了。
+它以 Node-API 的形式跑在 node 进程里，没有浏览器进程，也没有 CDP 往返。
+
+对 karin 来说，这意味着渲染模板图这件事不再需要装一个 100+ MB 的浏览器。
+代价是页面里的 JavaScript 不会执行——模板必须是服务端渲染好的静态 HTML。
+
+## 安装
+
+```bash
+pnpm add @karinjs/plugin-shotium -w
+```
+
+装好重启 karin 即可，插件会自己把渲染器注册进 karin 的渲染器列表。
+
+## 它做了什么
+
+karin 的渲染器就是一个函数：收下 `Options`，还回 base64。
+这个插件把 karin/puppeteer 那一套参数翻译成 shotium 的参数，再把结果翻译回去。
+
+| karin | shotium | 说明 |
+| --- | --- | --- |
+| `file` | `file` | 本地路径按配置转成 `file://` 或桥接 http 地址 |
+| `data` | — | 交给 karin 的 `renderTpl` 先跑 art-template |
+| `selector` | `selector` | 引擎内部用 `Document::querySelector` 解析，不注入脚本 |
+| `fullPage` | `fullPage` | 与 `selector` 互斥，`fullPage` 优先 |
+| `setViewport.width/height` | `viewport` | |
+| `setViewport.deviceScaleFactor` | `scale` | |
+| `type` / `quality` | `type` / `quality` | png 不带 `quality` |
+| `omitBackground` | `omitBackground` | jpeg 没有 alpha，会被忽略 |
+| `clip` | `clip` | `clip.scale` 无对应项 |
+| `pageGotoParams.waitUntil` | `pageGotoParams.waitUntil` | `networkidle0/2` 统一归到 `networkidle` |
+| `pageGotoParams.timeout` | `pageGotoParams.timeout` | `0`(不超时) 回退到引擎默认值 |
+| `headers` | `headers` | 只对同源子资源生效，见下 |
+| `multiPage` | — | 插件侧对同一张图做无损切割 |
+| `waitForSelector` 等 | — | 引擎没有 JS 运行时，忽略并提示一次 |
+
+### 分片渲染
+
+`multiPage` 在 puppeteer 那边是「改视窗高度重截几次」，
+这里换成了「截一次，再把 PNG 按行切开」：不重新布局，也就不会出现分片之间样式对不上的情况。
+切割直接在 zlib 层面做，不依赖任何图像库。
+
+因为切割器只认 PNG，`multiPage` 配上 jpeg/webp 时会自动切到 png，并在日志里提示一次。
+
+切割要把整张图重压一遍，这一步在大图上并不便宜。1440x2541 那张图上，
+同一份像素 deflate level 9 要 1.3s、level 6 要 0.48s、level 3 只要 0.19s，
+而体积差别只有个位数百分比，所以默认用 level 3，可以通过 `sliceCompression` 调。
+
+### 本地文件怎么交给引擎
+
+`localAccess` 有三档：
+
+- `file`（默认路径）：`file://` 直接打开，同时打开引擎的 `allowFileAccess`，
+  模板里 `file://` 形式的图片、字体照常能读到。
+- `http`：借用 **karin 自己的 express 服务**，把本地文件挂在一个带随机 token 的路径下转成 `http://` 再截图。
+  插件不另开端口。
+  http 文档下 chromium 会拒绝加载 `file://` 子资源，所以这条路径上 HTML/CSS 里的 `file://` 引用会被一并改写成桥接地址。
+- `auto`（默认）：平时走 `file`，只有调用方传了 `headers` 时才切到 `http`——
+  引擎只对同源子资源发送自定义头，`file://` 文档没有同源可言，headers 会被整个丢掉。
+
+桥接路径里带一段进程级随机 token，并且只放行渲染会用到的后缀，
+避免 karin 监听在 `0.0.0.0` 时把工作目录直接暴露出去。
+
+## 配置
+
+首次运行会在 `@karinjs/@karinjs-plugin-shotium/config/config.json` 生成默认配置，也可以在 WebUI 里改。
+
+| 字段 | 默认值 | 说明 |
+| --- | --- | --- |
+| `mode` | `inprocess` | `inprocess` 进程内 / `daemon` 常驻守护进程 |
+| `localAccess` | `auto` | 见上 |
+| `type` | `png` | 调用方没指定时的截图格式 |
+| `quality` | `90` | jpeg / webp 的压缩质量 |
+| `viewport` | `800x600` | 默认视窗 |
+| `scale` | `1` | 默认设备像素比 |
+| `timeout` | `30000` | 默认导航超时 |
+| `autoMultiPageHeight` | `4000` | `multiPage: true` 时每片的高度 |
+| `sliceCompression` | `3` | 分片重新编码的 deflate 级别 0-9 |
+| `cacheDir` | `''` | HTTP 磁盘缓存目录，留空用引擎默认，填 `off` 关闭 |
+| `cacheMaxBytes` | `256MB` | 缓存上限 |
+| `userAgent` | `''` | 留空使用引擎内置 |
+| `idleTimeoutMs` | `300000` | 守护进程空闲退出时间 |
+| `logStats` | `true` | 日志里带上引擎耗时统计 |
+
+改完配置会热重建引擎，不需要重启 karin。
+
+## 性能与实测
+
+性能结论以 Shotium 主仓库的[六平台基准报告](https://sj817.github.io/shotium/)为准。
+README 不再混用不同机器、版本和页面的绝对耗时，也不跨平台排名。
+
+### 标准基准
+
+下面摘录 Shotium 0.3.3 的 `linux-x64` 合格结果。三者在同一原生 runner、同一静态页面、
+PNG、1280×720、scale 1、`waitUntil: load` 条件下测试；表内为 p50，越低越好。
+
+| 场景 | Shotium | Puppeteer Shell | Puppeteer Chrome |
+| --- | ---: | ---: | ---: |
+| 冷启动 | 53 ms | 282 ms（5.32×） | 471 ms（8.89×） |
+| 启动稳定后的首张 | 21.028 ms | 104.061 ms（4.95×） | 114.146 ms（5.43×） |
+| 预热截图 | 24.905 ms | 131.601 ms（5.28×） | 157.438 ms（6.32×） |
+| 启动—截图—关闭循环 | 53.989 ms | 289.344 ms（5.36×） | 565.139 ms（10.47×） |
+
+数据来源：[Shotium 0.3.3 基准报告](https://github.com/sj817/shotium/blob/main/benchmark-results/v0.3.3/20260830T000525Z-gh33274826755-a1/report.zh-CN.md)。
+该次六平台聚合结果标记为“不完整”，所以上表只引用其中状态为“通过”、允许排名的
+`linux-x64` 同平台数据，不推测缺失结果。
+
+### KKK 帮助卡片兼容性实测
+
+2026-08-30 使用 `karin-plugin-kkk` 2.42.2、`@karinjs/plugin-shotium` 0.1.0 和
+Shotium 0.3.3，在 Windows x64 对实际 SSR 帮助卡片进行了明暗主题冒烟测试：
+
+| 主题 | 尺寸 | PNG 大小 | 插件总耗时 | 引擎耗时 |
+| --- | ---: | ---: | ---: | ---: |
+| 亮色 | 1440×2673 | 5.58 MB | 800 ms | 781.2 ms |
+| 暗色 | 1440×2673 | 6.01 MB | 746 ms | 732.5 ms |
+
+两张卡片的布局、中文、背景和主题均正确。此处只有各一次样本，而且隔离测试没有启动
+KKK 的 3780 字体服务，20 个 HarmonyOS 字体请求回退到系统字体，因此它只用于兼容性证明，
+不参与上面的性能排名。
+
+这类大卡片会同时承担数 MB CSS 解析和大尺寸 PNG 编码成本；Shotium 主要节省的是冷启动、
+常驻内存与浏览器进程/CDP 往返开销。页面越小、调用越频繁，固定开销差异越明显。
+
+需要更快的话，按收益排序：
+
+1. 输出换成 `jpeg` 或 `webp`；代价是 jpeg 没有 alpha 通道，`omitBackground` 会失效。
+2. 模板侧把 CSS purge 掉，别把整份 tailwind 内联进每张图。
+3. 图别做那么大——同一份内容宽度减半，像素少四分之三。
+
+## 已知限制
+
+- **页面里的 JavaScript 不会执行。** 模板必须是 SSR 好的静态 HTML。
+  用 Vue/React 组件路径当模板的 `file_type`（`vue3`、`vueString`、`react`）会直接报错。
+- `data:` 开头的地址不能当作**主文档**（子资源里的 data URI 正常）。
+  插件会把 `file_type: 'htmlString'` 的字符串先落盘再截。
+- 没有 `waitForSelector` / `waitForFunction` / `waitForRequest` / `waitForResponse`。
+- 抗锯齿是确定性的灰阶抗锯齿，和 puppeteer 的输出会有极细微的差别。
+
+## License
+
+MIT

package/dist/chunk-76RKNDUT.js

@@ -0,0 +1,118 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger, karin } from 'node-karin';
+import { basePath } from 'node-karin/root';
+
+// package.json
+var package_default = {
+  name: "@karinjs/plugin-shotium",
+  version: "0.2.1",
+  description: "karin \u7684 shotium \u622A\u56FE\u3001\u6E32\u67D3\u63D2\u4EF6",
+  keywords: [
+    "karin",
+    "node-karin",
+    "karin-plugin",
+    "shotium",
+    "screenshot",
+    "render"
+  ],
+  license: "MIT",
+  author: "sj817",
+  type: "module",
+  main: "dist/index.js",
+  types: "dist/index.d.ts",
+  files: [
+    "dist"
+  ],
+  repository: {
+    type: "git",
+    url: "git+https://github.com/KarinJS/plugin-shotium.git"
+  },
+  scripts: {
+    build: "tsc && tsup",
+    dev: "tsx src/app.ts",
+    lint: "eslint src/",
+    pub: "pnpm publish --access public",
+    rm: `node -e "require('fs').rmSync('dist', { recursive: true, force: true })"`,
+    sync: 'curl -X PUT "https://registry-direct.npmmirror.com/-/package/@karinjs/plugin-shotium/syncs"',
+    test: "vitest run",
+    "test:watch": "vitest"
+  },
+  dependencies: {
+    "@shotkit/shotium": "^0.3.3"
+  },
+  devDependencies: {
+    "@types/express": "5.0.6",
+    "@types/node": "^22.19.15",
+    eslint: "^9.7.0",
+    neostandard: "^0.12.1",
+    "node-karin": "^1.17.0",
+    tsup: "^8.5.1",
+    tsx: "^4.19.3",
+    typescript: "^5.8.2",
+    vitest: "^4.1.8"
+  },
+  karin: {
+    main: "src/index.ts",
+    apps: [],
+    web: "dist/web.config.js",
+    "ts-web": "src/web.config.ts",
+    files: [
+      "config"
+    ]
+  },
+  publishConfig: {
+    access: "public",
+    registry: "https://registry.npmjs.org"
+  }
+};
+var HMR_KEY = "karin-plugin-shotium-hmr";
+var defaultConfig = {
+  mode: "inprocess",
+  localAccess: "auto",
+  type: "png",
+  quality: 90,
+  viewport: {
+    width: 800,
+    height: 600
+  },
+  scale: 1,
+  timeout: 3e4,
+  autoMultiPageHeight: 4e3,
+  sliceCompression: 3,
+  cacheDir: "",
+  cacheMaxBytes: 256 * 1024 * 1024,
+  userAgent: "",
+  idleTimeoutMs: 3e5,
+  logStats: true
+};
+var pluginName = package_default.name.replace(/\//g, "-");
+var pluginVersion = package_default.version;
+var configPath = path.resolve(basePath, pluginName, "config", "config.json");
+var init = () => {
+  if (!fs.existsSync(configPath)) {
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2));
+    logger.info(`[${pluginName}] \u9996\u6B21\u8FD0\u884C\uFF0C\u5DF2\u521B\u5EFA\u9ED8\u8BA4\u914D\u7F6E\u6587\u4EF6: ${configPath}`);
+  }
+};
+var getConfig = () => {
+  try {
+    const data = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    return {
+      ...defaultConfig,
+      ...data,
+      viewport: { ...defaultConfig.viewport, ...data?.viewport ?? {} }
+    };
+  } catch (error) {
+    logger.error(`[${pluginName}] \u914D\u7F6E\u8BFB\u53D6\u5931\u8D25\uFF0C\u5DF2\u56DE\u9000\u5230\u9ED8\u8BA4\u914D\u7F6E: ${error instanceof Error ? error.message : String(error)}`);
+    return { ...defaultConfig };
+  }
+};
+var saveConfig = (config) => {
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+  karin.emit(HMR_KEY, config);
+};
+init();
+
+export { HMR_KEY, configPath, defaultConfig, getConfig, package_default, pluginName, pluginVersion, saveConfig };

package/dist/index.d.ts

@@ -0,0 +1,224 @@
+import { ScreenshotOptions } from '@shotkit/shotium';
+import { Snapka } from 'node-karin';
+
+var name = "@karinjs/plugin-shotium";
+var version = "0.2.1";
+var description = "karin 的 shotium 截图、渲染插件";
+var keywords = [
+	"karin",
+	"node-karin",
+	"karin-plugin",
+	"shotium",
+	"screenshot",
+	"render"
+];
+var license = "MIT";
+var author = "sj817";
+var type = "module";
+var main = "dist/index.js";
+var types = "dist/index.d.ts";
+var files = [
+	"dist"
+];
+var repository = {
+	type: "git",
+	url: "git+https://github.com/KarinJS/plugin-shotium.git"
+};
+var scripts = {
+	build: "tsc && tsup",
+	dev: "tsx src/app.ts",
+	lint: "eslint src/",
+	pub: "pnpm publish --access public",
+	rm: "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+	sync: "curl -X PUT \"https://registry-direct.npmmirror.com/-/package/@karinjs/plugin-shotium/syncs\"",
+	test: "vitest run",
+	"test:watch": "vitest"
+};
+var dependencies = {
+	"@shotkit/shotium": "^0.3.3"
+};
+var devDependencies = {
+	"@types/express": "5.0.6",
+	"@types/node": "^22.19.15",
+	eslint: "^9.7.0",
+	neostandard: "^0.12.1",
+	"node-karin": "^1.17.0",
+	tsup: "^8.5.1",
+	tsx: "^4.19.3",
+	typescript: "^5.8.2",
+	vitest: "^4.1.8"
+};
+var karin = {
+	main: "src/index.ts",
+	apps: [
+	],
+	web: "dist/web.config.js",
+	"ts-web": "src/web.config.ts",
+	files: [
+		"config"
+	]
+};
+var publishConfig = {
+	access: "public",
+	registry: "https://registry.npmjs.org"
+};
+var _package = {
+	name: name,
+	version: version,
+	description: description,
+	keywords: keywords,
+	license: license,
+	author: author,
+	type: type,
+	main: main,
+	types: types,
+	files: files,
+	repository: repository,
+	scripts: scripts,
+	dependencies: dependencies,
+	devDependencies: devDependencies,
+	karin: karin,
+	publishConfig: publishConfig
+};
+
+/**
+ * 热更新key
+ */
+declare const HMR_KEY = "karin-plugin-shotium-hmr";
+/**
+ * 本地文件的加载方式
+ * - `file`: 直接以 `file://` 交给引擎，配合 `allowFileAccess` 读取同目录下的子资源
+ * - `http`: 借用 karin 自身的 express 服务把本地文件转成 `http://` 再交给引擎
+ * - `auto`: 默认走 `file`，当调用方传了 `headers` 时自动切到 `http`
+ *   （引擎只对同源子资源发送自定义头，`file://` 文档没有同源可言）
+ */
+type LocalAccess = 'auto' | 'file' | 'http';
+/**
+ * 插件配置
+ */
+interface ShotiumConfig {
+    /** 引擎运行方式：进程内 / 常驻守护进程 */
+    mode: 'inprocess' | 'daemon';
+    /** 本地文件加载方式 */
+    localAccess: LocalAccess;
+    /** 默认截图类型 */
+    type: 'png' | 'jpeg' | 'webp';
+    /** 默认压缩质量 1-100，仅 jpeg/webp 生效 */
+    quality: number;
+    /** 默认视窗 */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** 默认设备像素比 0.01-8 */
+    scale: number;
+    /** 默认导航超时(ms) */
+    timeout: number;
+    /** `multiPage: true` 时单张分片的最大高度(css px) */
+    autoMultiPageHeight: number;
+    /**
+     * 分片重新编码时的 deflate 级别 0-9
+     *
+     * 分片要把引擎给的整张 PNG 拆开重压一遍，这一步在大图上并不便宜：
+     * 同一份像素 level 9 要 1.3s、level 6 要 0.5s、level 3 只要 0.19s，
+     * 而体积差别只有个位数百分比。发到聊天里的图不值得为这点体积多等半秒。
+     */
+    sliceCompression: number;
+    /** HTTP 磁盘缓存目录，留空使用引擎默认目录，填 `off` 关闭缓存 */
+    cacheDir: string;
+    /** HTTP 磁盘缓存上限(字节) */
+    cacheMaxBytes: number;
+    /** 自定义 UA，留空使用引擎内置 */
+    userAgent: string;
+    /** daemon 模式下的空闲退出时间(ms)，0 表示不退出 */
+    idleTimeoutMs: number;
+    /** 打印每次截图的耗时统计 */
+    logStats: boolean;
+}
+/**
+ * 默认配置
+ */
+declare const defaultConfig: ShotiumConfig;
+/** 插件名称 */
+declare const pluginName: string;
+/** 插件版本 */
+declare const pluginVersion: string;
+/** 配置文件路径 */
+declare const configPath: string;
+/**
+ * 获取配置
+ * @returns 合并默认值之后的配置
+ */
+declare const getConfig: () => ShotiumConfig;
+/**
+ * 保存配置
+ * @param config 配置
+ */
+declare const saveConfig: (config: ShotiumConfig) => void;
+
+/**
+ * karin 里能传、但 shotium 做不到的选项
+ *
+ * shotium 砍掉了 V8，页面里没有脚本会跑，
+ * 这些「等某个东西发生」的开关自然也就没有意义，遇到时提示一次即可。
+ */
+declare const UNSUPPORTED_KEYS: readonly ["waitForSelector", "waitForFunction", "waitForRequest", "waitForResponse"];
+/**
+ * 把 karin 的 `waitUntil` 归一成 shotium 的两档
+ *
+ * @param waitUntil karin/puppeteer 的取值，可能是数组
+ * @returns shotium 的取值
+ */
+declare const toWaitUntil: (waitUntil?: string | string[]) => "load" | "networkidle" | undefined;
+/**
+ * 把 karin 的截图参数翻译成 shotium 的截图参数
+ *
+ * 只做纯粹的字段映射，`file` 由调用方在外面决定用 `file://` 还是走 http 桥接。
+ *
+ * @param options karin 截图参数
+ * @param config 插件配置
+ * @returns shotium 截图参数（不含 `file`）
+ */
+declare const toScreenshotOptions: (options: Snapka, config: ShotiumConfig) => Omit<ScreenshotOptions, "file">;
+/**
+ * 取出调用方传了、但引擎不支持的选项名
+ * @param options karin 截图参数
+ * @returns 选项名列表
+ */
+declare const pickUnsupported: (options: Snapka) => string[];
+/**
+ * 计算每一片的高度(css px)
+ * @param multiPage karin 的 multiPage 参数
+ * @param autoHeight `true` 时使用的默认高度
+ * @returns 分片高度，不分片时返回 0
+ */
+declare const toSliceHeight: (multiPage: number | boolean | undefined, autoHeight: number) => number;
+
+/** PNG 基本信息 */
+interface PngInfo {
+    width: number;
+    height: number;
+    bitDepth: number;
+    colorType: number;
+    interlace: number;
+}
+/**
+ * 读取 PNG 的宽高等基本信息
+ * @param buf PNG 数据
+ * @returns 基本信息，不是合法 PNG 时返回 null
+ */
+declare const readPngInfo: (buf: Buffer) => PngInfo | null;
+/**
+ * 把一张 PNG 按高度切成若干张 PNG
+ *
+ * 与「改视窗高度重新截图」相比，这里是对同一次渲染结果做无损切割：
+ * 不会重新布局，也就不会出现分片之间样式对不上的问题。
+ *
+ * @param buf 原始 PNG
+ * @param sliceHeight 每片高度(设备像素)
+ * @param level deflate 级别 0-9，越低越快、体积越大
+ * @returns 切好的 PNG 列表；无法处理时返回 null，由调用方回退
+ */
+declare const splitPng: (buf: Buffer, sliceHeight: number, level?: number) => Buffer[] | null;
+
+export { HMR_KEY, type LocalAccess, type PngInfo, type ShotiumConfig, UNSUPPORTED_KEYS, configPath, defaultConfig, getConfig, pickUnsupported, _package as pkg, pluginName, pluginVersion, readPngInfo, saveConfig, splitPng, toScreenshotOptions, toSliceHeight, toWaitUntil };

package/dist/index.js

@@ -0,0 +1,498 @@
+import { getConfig, HMR_KEY, pluginName, pluginVersion } from './chunk-76RKNDUT.js';
+export { HMR_KEY, configPath, defaultConfig, getConfig, package_default as pkg, pluginName, pluginVersion, saveConfig } from './chunk-76RKNDUT.js';
+import fs2 from 'node:fs';
+import path2 from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { karin, logger, registerRender, renderTpl, app } from 'node-karin';
+import { karinPathHtml } from 'node-karin/root';
+import { start, status, stop, screenshot, daemon } from '@shotkit/shotium';
+import zlib from 'node:zlib';
+
+var toStartOptions = (config) => {
+  const options = {
+    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;
+};
+var createInprocessEngine = (config) => {
+  const result = start(toStartOptions(config));
+  logger.info(
+    `[${pluginName}] \u8FDB\u7A0B\u5185\u5F15\u64CE\u5DF2\u542F\u52A8: cache=${result.cacheActive ? result.cacheDir : "\u5DF2\u5173\u95ED"}`
+  );
+  return {
+    screenshot: (options) => screenshot(options),
+    close: async () => {
+      if (status().running) await stop();
+    }
+  };
+};
+var createDaemonEngine = (config) => {
+  let client = null;
+  let pending = null;
+  const connect = async () => {
+    if (client) return client;
+    if (!pending) {
+      pending = daemon.connect({
+        ...toStartOptions(config),
+        idleTimeoutMs: config.idleTimeoutMs
+      }).then((connected) => {
+        client = connected;
+        connected.once("close", () => {
+          client = null;
+          logger.warn(`[${pluginName}] \u5B88\u62A4\u8FDB\u7A0B\u8FDE\u63A5\u5DF2\u65AD\u5F00\uFF0C\u4E0B\u6B21\u622A\u56FE\u65F6\u4F1A\u91CD\u8FDE`);
+        });
+        logger.info(`[${pluginName}] \u5B88\u62A4\u8FDB\u7A0B\u5F15\u64CE\u5DF2\u8FDE\u63A5`);
+        return connected;
+      }).finally(() => {
+        pending = null;
+      });
+    }
+    return pending;
+  };
+  return {
+    screenshot: async (options) => {
+      try {
+        return await (await connect()).screenshot(options);
+      } catch (error) {
+        client = null;
+        return await (await connect()).screenshot(options);
+      }
+    },
+    close: async () => {
+      client?.close();
+      client = null;
+    }
+  };
+};
+var createEngine = (config) => {
+  return config.mode === "daemon" ? createDaemonEngine(config) : createInprocessEngine(config);
+};
+var PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+var CHANNELS = {
+  0: 1,
+  // 灰度
+  2: 3,
+  // RGB
+  4: 2,
+  // 灰度 + alpha
+  6: 4
+  // RGBA
+};
+var 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 ? 3988292384 ^ c >>> 1 : c >>> 1;
+    }
+    table[n] = c;
+  }
+  return table;
+})();
+var crc32 = (buf) => {
+  let c = -1;
+  for (let i = 0; i < buf.length; i++) {
+    c = CRC_TABLE[(c ^ buf[i]) & 255] ^ c >>> 8;
+  }
+  return (c ^ -1) >>> 0;
+};
+var readChunks = (buf) => {
+  if (buf.length < 8 || !buf.subarray(0, 8).equals(PNG_SIGNATURE)) return null;
+  const chunks = [];
+  let offset = 8;
+  while (offset + 8 <= buf.length) {
+    const length = buf.readUInt32BE(offset);
+    const type = buf.toString("ascii", offset + 4, offset + 8);
+    const start2 = offset + 8;
+    const end = start2 + length;
+    if (end + 4 > buf.length) return null;
+    chunks.push({ type, data: buf.subarray(start2, end) });
+    offset = end + 4;
+    if (type === "IEND") break;
+  }
+  return chunks;
+};
+var writeChunk = (type, data) => {
+  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]);
+};
+var readPngInfo = (buf) => {
+  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]
+  };
+};
+var paeth = (a, b, c) => {
+  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;
+};
+var unfilter = (filtered, width, height, bpp) => {
+  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 raw = 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;
+      switch (filterType) {
+        case 0:
+          value = raw;
+          break;
+        case 1:
+          value = raw + a;
+          break;
+        case 2:
+          value = raw + b;
+          break;
+        case 3:
+          value = raw + (a + b >> 1);
+          break;
+        case 4:
+          value = raw + paeth(a, b, c);
+          break;
+        default:
+          value = raw;
+      }
+      out[dst + x] = value & 255;
+    }
+  }
+  return out;
+};
+var splitPng = (buf, sliceHeight, level = 3) => {
+  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 raw;
+  try {
+    raw = zlib.inflateSync(Buffer.concat(idat));
+  } catch {
+    return null;
+  }
+  const stride = info.width * channels;
+  if (raw.length < (stride + 1) * info.height) return null;
+  const pixels = unfilter(raw, info.width, info.height, channels);
+  const extras = chunks.filter((item) => ["PLTE", "tRNS", "gAMA", "sRGB", "cHRM", "iCCP", "pHYs"].includes(item.type));
+  const list = [];
+  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;
+};
+var ALLOWED_EXT = {
+  ".html": "text/html; charset=utf-8",
+  ".htm": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".bmp": "image/bmp",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".eot": "application/vnd.ms-fontobject"
+};
+var REWRITE_EXT = /* @__PURE__ */ new Set([".html", ".htm", ".css", ".svg"]);
+var token = crypto.randomBytes(16).toString("hex");
+var mountPath = `/shotium/${token}/fs`;
+var mounted = false;
+var toUrlPath = (file) => {
+  const posix = path2.resolve(file).split(path2.sep).join("/").replace(/^\/+/, "");
+  return `${mountPath}/${posix.split("/").map(encodeURIComponent).join("/")}`;
+};
+var toFilePath = (urlPath) => {
+  const raw = decodeURIComponent(urlPath).replace(/^\/+/, "");
+  return /^[a-zA-Z]:/.test(raw) ? raw : `/${raw}`;
+};
+var rewriteFileUrls = (text) => {
+  return text.replace(/file:\/\/\/?[^"')\s>]+/g, (match) => {
+    try {
+      return toUrlPath(fileURLToPath(new URL(match)));
+    } catch {
+      return match;
+    }
+  });
+};
+var handler = (req, res) => {
+  const file = path2.normalize(toFilePath(req.path));
+  const ext = path2.extname(file).toLowerCase();
+  if (file.includes("..")) {
+    res.status(403).end("forbidden");
+    return;
+  }
+  const type = ALLOWED_EXT[ext];
+  if (!type) {
+    res.status(415).end("unsupported file type");
+    return;
+  }
+  if (!fs2.existsSync(file) || !fs2.statSync(file).isFile()) {
+    res.status(404).end("not found");
+    return;
+  }
+  res.setHeader("Content-Type", type);
+  if (REWRITE_EXT.has(ext)) {
+    res.end(rewriteFileUrls(fs2.readFileSync(file, "utf-8")));
+    return;
+  }
+  fs2.createReadStream(file).pipe(res);
+};
+var mountBridge = () => {
+  if (mounted) return;
+  app.use(mountPath, handler);
+  mounted = true;
+  logger.debug(`[${pluginName}] \u672C\u5730\u8D44\u6E90\u6865\u63A5\u5DF2\u6302\u8F7D: ${mountPath}`);
+};
+var isBridgeAvailable = () => {
+  return process.env.HTTP_ENABLE !== "false" && !!process.env.HTTP_PORT;
+};
+var toBridgeUrl = (file) => {
+  mountBridge();
+  const port = process.env.HTTP_PORT || "7777";
+  return `http://127.0.0.1:${port}${toUrlPath(file)}`;
+};
+var toFileUrl = (file) => pathToFileURL(path2.resolve(file)).href;
+
+// src/convert.ts
+var UNSUPPORTED_KEYS = [
+  "waitForSelector",
+  "waitForFunction",
+  "waitForRequest",
+  "waitForResponse"
+];
+var toWaitUntil = (waitUntil) => {
+  if (!waitUntil) return void 0;
+  const list = Array.isArray(waitUntil) ? waitUntil : [waitUntil];
+  return list.some((item) => item.startsWith("networkidle")) ? "networkidle" : "load";
+};
+var toScreenshotOptions = (options, config) => {
+  const type = options.type ?? config.type;
+  const result = { type };
+  if (type !== "png") {
+    result.quality = options.quality ?? config.quality;
+  }
+  if (options.fullPage) {
+    result.fullPage = true;
+  } else if (options.selector) {
+    result.selector = options.selector;
+  }
+  if (options.omitBackground && type !== "jpeg") {
+    result.omitBackground = true;
+  }
+  if (options.clip && !result.fullPage && !result.selector) {
+    result.clip = {
+      x: options.clip.x,
+      y: options.clip.y,
+      width: options.clip.width,
+      height: options.clip.height
+    };
+  }
+  const width = options.setViewport?.width ?? config.viewport.width;
+  const height = options.setViewport?.height ?? config.viewport.height;
+  result.viewport = { width, height };
+  const scale = options.setViewport?.deviceScaleFactor ?? config.scale;
+  if (scale && scale !== 1) result.scale = scale;
+  const waitUntil = toWaitUntil(options.pageGotoParams?.waitUntil);
+  const timeout = options.pageGotoParams?.timeout;
+  if (waitUntil || typeof timeout === "number") {
+    result.pageGotoParams = {
+      ...waitUntil ? { waitUntil } : {},
+      /** puppeteer 用 0 表示不超时，shotium 没有这个约定，回退到默认值 */
+      ...typeof timeout === "number" && timeout > 0 ? { timeout } : {}
+    };
+  }
+  if (options.headers && Object.keys(options.headers).length > 0) {
+    result.headers = options.headers;
+  }
+  return result;
+};
+var pickUnsupported = (options) => {
+  return UNSUPPORTED_KEYS.filter((key) => {
+    const value = options[key];
+    return Array.isArray(value) ? value.length > 0 : !!value;
+  });
+};
+var toSliceHeight = (multiPage, autoHeight) => {
+  if (multiPage === true) return autoHeight;
+  if (typeof multiPage === "number" && multiPage > 0) return multiPage;
+  return 0;
+};
+
+// src/index.ts
+var RENDER_ID = "@karinjs/plugin-shotium";
+var stringHtmlDir = path2.join(karinPathHtml, "shotium");
+var warned = /* @__PURE__ */ new Set();
+var warnOnce = (key, message) => {
+  if (warned.has(key)) return;
+  warned.add(key);
+  logger.warn(`[${pluginName}] ${message}`);
+};
+var writeHtmlString = (html, name) => {
+  fs2.mkdirSync(stringHtmlDir, { recursive: true });
+  const hash = crypto.createHash("md5").update(html).digest("hex").slice(0, 8);
+  const file = path2.join(stringHtmlDir, `${name || "render"}-${hash}.html`);
+  if (!fs2.existsSync(file)) fs2.writeFileSync(file, html);
+  return file;
+};
+var resolveTarget = (file, config, hasHeaders) => {
+  if (/^https?:\/\//.test(file)) {
+    return { target: file, allowFileAccess: false };
+  }
+  const local = file.startsWith("file:") ? fileURLToPath(file) : path2.resolve(file);
+  const wantHttp = config.localAccess === "http" || config.localAccess === "auto" && hasHeaders;
+  if (wantHttp) {
+    if (isBridgeAvailable()) {
+      return { target: toBridgeUrl(local), allowFileAccess: false };
+    }
+    warnOnce("bridge", "karin \u7684 http \u670D\u52A1\u4E0D\u53EF\u7528\uFF0C\u672C\u5730\u6587\u4EF6\u5DF2\u56DE\u9000\u5230 file:// \u65B9\u5F0F");
+  }
+  return { target: toFileUrl(local), allowFileAccess: true };
+};
+var formatBytes = (bytes) => {
+  const units = ["B", "KB", "MB", "GB"];
+  if (!bytes || bytes < 0) return "0 B";
+  const i = Math.min(units.length - 1, Math.floor(Math.log(bytes) / Math.log(1024)));
+  const value = bytes / Math.pow(1024, i);
+  return `${i === 0 ? Math.round(value) : value.toFixed(2)} ${units[i]}`;
+};
+var main = async () => {
+  let config = getConfig();
+  let engine = createEngine(config);
+  karin.on(HMR_KEY, async () => {
+    logger.info(`[${pluginName}] \u68C0\u6D4B\u5230\u914D\u7F6E\u70ED\u66F4\u65B0\uFF0C\u6B63\u5728\u91CD\u5EFA\u5F15\u64CE...`);
+    const previous = engine;
+    config = getConfig();
+    engine = createEngine(config);
+    await previous.close().catch(() => {
+    });
+    logger.info(`[${pluginName}] \u5F15\u64CE\u91CD\u5EFA\u5B8C\u6210`);
+  });
+  registerRender(RENDER_ID, async (options) => {
+    const time = Date.now();
+    if (options.file_type && options.file_type !== "auto") {
+      if (options.file_type === "htmlString") {
+        options.file = writeHtmlString(options.file, options.file_name);
+        options.file_type = "auto";
+      } else {
+        throw new Error(
+          `[${pluginName}] shotium \u6CA1\u6709 JS \u8FD0\u884C\u65F6\uFF0C\u65E0\u6CD5\u6E32\u67D3 file_type: ${options.file_type}\uFF0C\u8BF7\u5148\u5728\u63D2\u4EF6\u4FA7\u5B8C\u6210 SSR \u518D\u628A html \u4EA4\u8FC7\u6765`
+        );
+      }
+    }
+    options.encoding = "base64";
+    const data = renderTpl(options);
+    const unsupported = pickUnsupported(data);
+    if (unsupported.length > 0) {
+      warnOnce(
+        `unsupported:${unsupported.join(",")}`,
+        `\u4EE5\u4E0B\u9009\u9879\u5728 shotium \u4E0B\u65E0\u6548\uFF0C\u5DF2\u5FFD\u7565: ${unsupported.join("\u3001")}\uFF08\u5F15\u64CE\u4E0D\u5E26 JS \u8FD0\u884C\u65F6\uFF09`
+      );
+    }
+    const hasHeaders = !!data.headers && Object.keys(data.headers).length > 0;
+    const { target, allowFileAccess } = resolveTarget(data.file, config, hasHeaders);
+    const shot = toScreenshotOptions(data, config);
+    const sliceHeight = toSliceHeight(data.multiPage, config.autoMultiPageHeight);
+    if (sliceHeight > 0 && shot.type !== "png") {
+      warnOnce(
+        "multiPageType",
+        `\u5206\u7247\u6E32\u67D3\u53EA\u80FD\u8F93\u51FA png\uFF0C\u672C\u6B21\u5DF2\u628A ${shot.type} \u5207\u6362\u4E3A png`
+      );
+      shot.type = "png";
+      delete shot.quality;
+    }
+    const result = await engine.screenshot({ ...shot, file: target, allowFileAccess });
+    const image = result.image;
+    if (!image) throw new Error(`[${pluginName}] \u5F15\u64CE\u6CA1\u6709\u8FD4\u56DE\u56FE\u7247\u6570\u636E`);
+    if (data.path) {
+      fs2.mkdirSync(path2.dirname(path2.resolve(data.path)), { recursive: true });
+      fs2.writeFileSync(path2.resolve(data.path), image);
+    }
+    const name = path2.basename(data.file_name || data.file || "unknown");
+    const stats = config.logStats ? ` \u7F51\u7EDC: ${result.stats.requests}(\u7F13\u5B58 ${result.stats.fromCache}/\u5931\u8D25 ${result.stats.failed}) \u5F15\u64CE: ${result.stats.timing.total.toFixed(1)}ms` : "";
+    if (sliceHeight === 0) {
+      logger.info(
+        `[${RENDER_ID}][${name}] \u622A\u56FE\u5B8C\u6210 \u5927\u5C0F: ${logger.green(formatBytes(image.length))} \u8017\u65F6: ${logger.green(String(Date.now() - time))} ms${stats}`
+      );
+      return image.toString("base64");
+    }
+    const list = splitPng(image, Math.round(sliceHeight * (shot.scale ?? 1)), config.sliceCompression);
+    if (!list) {
+      warnOnce("split", "\u5F53\u524D\u56FE\u7247\u683C\u5F0F\u65E0\u6CD5\u5206\u7247\uFF0C\u5DF2\u6309\u6574\u5F20\u8FD4\u56DE");
+      return [image.toString("base64")];
+    }
+    logger.info(
+      `[${RENDER_ID}][${name}] \u5206\u7247\u622A\u56FE\u5B8C\u6210 ${list.length} \u5F20 \u5927\u5C0F: ${logger.green(formatBytes(image.length))} \u8017\u65F6: ${logger.green(String(Date.now() - time))} ms${stats}`
+    );
+    return list.map((item) => item.toString("base64"));
+  });
+  logger.info(
+    `${logger.violet(`[\u63D2\u4EF6:${pluginVersion}]`)} ${logger.green(pluginName)} \u521D\u59CB\u5316\u5B8C\u6210~`
+  );
+};
+main();
+
+export { UNSUPPORTED_KEYS, pickUnsupported, readPngInfo, splitPng, toScreenshotOptions, toSliceHeight, toWaitUntil };

package/dist/web.config.d.ts

@@ -0,0 +1,14 @@
+import { GetConfigResponse, ComponentConfig } from 'node-karin';
+
+/** WebUI 提交上来的表单 */
+type FormValue = Record<string, unknown>;
+declare const webConfig: {
+    info: GetConfigResponse['info'];
+    components: () => ComponentConfig[];
+    save: (config: FormValue) => {
+        success: boolean;
+        message: string;
+    };
+};
+
+export { webConfig as default };

package/dist/web.config.js

@@ -0,0 +1,162 @@
+import { package_default, getConfig, defaultConfig, saveConfig } from './chunk-76RKNDUT.js';
+import { components } from 'node-karin';
+
+var toNumber = (value, fallback) => {
+  const num = Number(value);
+  return Number.isFinite(num) ? num : fallback;
+};
+var webConfig = {
+  info: {
+    id: package_default.name,
+    name: "shotium \u6E32\u67D3\u5668",
+    version: package_default.version,
+    description: package_default.description,
+    author: [
+      {
+        name: "sj817",
+        home: "https://github.com/sj817",
+        avatar: "https://github.com/sj817.png"
+      }
+    ],
+    icon: {
+      name: "camera",
+      size: 24,
+      color: "#0969da"
+    }
+  },
+  components: () => {
+    const config = getConfig();
+    return [
+      components.radio.group("mode", {
+        label: "\u5F15\u64CE\u8FD0\u884C\u65B9\u5F0F",
+        orientation: "horizontal",
+        description: "\u8FDB\u7A0B\u5185\u6700\u7701\u4E8B\uFF1B\u5B88\u62A4\u8FDB\u7A0B\u53EF\u4EE5\u8BA9 karin \u91CD\u542F\u65F6\u4E0D\u7528\u91CD\u65B0\u4ED8\u51B7\u542F\u52A8\u7684\u94B1",
+        defaultValue: config.mode,
+        radio: [
+          components.radio.create("inprocess", { label: "\u8FDB\u7A0B\u5185", value: "inprocess" }),
+          components.radio.create("daemon", { label: "\u5B88\u62A4\u8FDB\u7A0B", value: "daemon" })
+        ]
+      }),
+      components.radio.group("localAccess", {
+        label: "\u672C\u5730\u6587\u4EF6\u52A0\u8F7D\u65B9\u5F0F",
+        orientation: "horizontal",
+        description: "auto: \u9ED8\u8BA4 file\uFF0C\u5E26\u81EA\u5B9A\u4E49\u8BF7\u6C42\u5934\u65F6\u81EA\u52A8\u8D70 http\uFF1Bfile: \u76F4\u63A5 file:// \u6253\u5F00\uFF1Bhttp: \u501F\u7528 karin \u81EA\u8EAB\u7684 http \u670D\u52A1\u8F6C\u6210 http:// \u518D\u622A\u56FE",
+        defaultValue: config.localAccess,
+        radio: [
+          components.radio.create("auto", { label: "auto", value: "auto" }),
+          components.radio.create("file", { label: "file", value: "file" }),
+          components.radio.create("http", { label: "http", value: "http" })
+        ]
+      }),
+      components.divider.create("divider0"),
+      components.radio.group("type", {
+        label: "\u9ED8\u8BA4\u622A\u56FE\u683C\u5F0F",
+        orientation: "horizontal",
+        description: "\u8C03\u7528\u65B9\u6CA1\u6709\u6307\u5B9A\u683C\u5F0F\u65F6\u4F7F\u7528",
+        defaultValue: config.type,
+        radio: [
+          components.radio.create("png", { label: "png", value: "png" }),
+          components.radio.create("jpeg", { label: "jpeg", value: "jpeg" }),
+          components.radio.create("webp", { label: "webp", value: "webp" })
+        ]
+      }),
+      components.input.number("quality", {
+        label: "\u9ED8\u8BA4\u538B\u7F29\u8D28\u91CF",
+        description: "1-100\uFF0C\u53EA\u5BF9 jpeg / webp \u751F\u6548",
+        defaultValue: String(config.quality)
+      }),
+      components.input.number("viewportWidth", {
+        label: "\u9ED8\u8BA4\u89C6\u7A97\u5BBD\u5EA6",
+        description: "\u5355\u4F4D css \u50CF\u7D20",
+        defaultValue: String(config.viewport.width)
+      }),
+      components.input.number("viewportHeight", {
+        label: "\u9ED8\u8BA4\u89C6\u7A97\u9AD8\u5EA6",
+        description: "\u5355\u4F4D css \u50CF\u7D20",
+        defaultValue: String(config.viewport.height)
+      }),
+      components.input.number("scale", {
+        label: "\u9ED8\u8BA4\u8BBE\u5907\u50CF\u7D20\u6BD4",
+        description: "0.01-8\uFF0C\u76F8\u5F53\u4E8E puppeteer \u7684 deviceScaleFactor",
+        defaultValue: String(config.scale)
+      }),
+      components.input.number("timeout", {
+        label: "\u9ED8\u8BA4\u5BFC\u822A\u8D85\u65F6(ms)",
+        defaultValue: String(config.timeout)
+      }),
+      components.input.number("autoMultiPageHeight", {
+        label: "\u81EA\u52A8\u5206\u7247\u9AD8\u5EA6",
+        description: "\u8C03\u7528\u65B9\u4F20 multiPage: true \u65F6\uFF0C\u6BCF\u7247\u7684\u9AD8\u5EA6(css \u50CF\u7D20)",
+        defaultValue: String(config.autoMultiPageHeight)
+      }),
+      components.input.number("sliceCompression", {
+        label: "\u5206\u7247\u91CD\u65B0\u7F16\u7801\u7684\u538B\u7F29\u7EA7\u522B",
+        description: "0-9\u3002\u5206\u7247\u8981\u628A\u6574\u5F20\u56FE\u62C6\u5F00\u91CD\u538B\u4E00\u904D\uFF0C\u7EA7\u522B\u8D8A\u4F4E\u8D8A\u5FEB\u3001\u4F53\u79EF\u8D8A\u5927\uFF0C3 \u662F\u6298\u4E2D\u503C",
+        defaultValue: String(config.sliceCompression)
+      }),
+      components.divider.create("divider1"),
+      components.input.string("cacheDir", {
+        label: "HTTP \u7F13\u5B58\u76EE\u5F55",
+        description: "\u7559\u7A7A\u4F7F\u7528\u5F15\u64CE\u9ED8\u8BA4\u76EE\u5F55\uFF1B\u586B off \u8868\u793A\u5173\u95ED\u7F13\u5B58",
+        defaultValue: config.cacheDir,
+        isRequired: false
+      }),
+      components.input.number("cacheMaxBytes", {
+        label: "HTTP \u7F13\u5B58\u4E0A\u9650(\u5B57\u8282)",
+        defaultValue: String(config.cacheMaxBytes)
+      }),
+      components.input.string("userAgent", {
+        label: "\u81EA\u5B9A\u4E49 UA",
+        description: "\u7559\u7A7A\u4F7F\u7528\u5F15\u64CE\u5185\u7F6E UA",
+        defaultValue: config.userAgent,
+        isRequired: false
+      }),
+      components.input.number("idleTimeoutMs", {
+        label: "\u5B88\u62A4\u8FDB\u7A0B\u7A7A\u95F2\u9000\u51FA(ms)",
+        description: "0 \u8868\u793A\u4E0D\u9000\u51FA\uFF0C\u4EC5\u5B88\u62A4\u8FDB\u7A0B\u6A21\u5F0F\u751F\u6548",
+        defaultValue: String(config.idleTimeoutMs)
+      }),
+      components.switch.create("logStats", {
+        label: "\u6253\u5370\u5F15\u64CE\u8017\u65F6\u7EDF\u8BA1",
+        description: "\u6BCF\u6B21\u622A\u56FE\u5728\u65E5\u5FD7\u91CC\u5E26\u4E0A\u8BF7\u6C42\u6570\u4E0E\u5F15\u64CE\u8017\u65F6",
+        defaultSelected: config.logStats,
+        color: "success"
+      })
+    ];
+  },
+  save: (form) => {
+    try {
+      const current = getConfig();
+      const cacheDir = String(form.cacheDir ?? "").trim();
+      const next = {
+        mode: form.mode || current.mode,
+        localAccess: form.localAccess || current.localAccess,
+        type: form.type || current.type,
+        quality: toNumber(form.quality, current.quality),
+        viewport: {
+          width: toNumber(form.viewportWidth, current.viewport.width),
+          height: toNumber(form.viewportHeight, current.viewport.height)
+        },
+        scale: toNumber(form.scale, current.scale),
+        timeout: toNumber(form.timeout, current.timeout),
+        autoMultiPageHeight: toNumber(form.autoMultiPageHeight, defaultConfig.autoMultiPageHeight),
+        sliceCompression: Math.min(9, Math.max(0, toNumber(form.sliceCompression, defaultConfig.sliceCompression))),
+        cacheDir,
+        cacheMaxBytes: toNumber(form.cacheMaxBytes, current.cacheMaxBytes),
+        userAgent: String(form.userAgent ?? ""),
+        idleTimeoutMs: toNumber(form.idleTimeoutMs, current.idleTimeoutMs),
+        logStats: form.logStats !== false
+      };
+      saveConfig(next);
+      return { success: true, message: "\u4FDD\u5B58\u6210\u529F" };
+    } catch (error) {
+      return {
+        success: false,
+        message: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+};
+var web_config_default = webConfig;
+
+export { web_config_default as default };

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@karinjs/plugin-shotium",
-  "version": "0.0.1",
-  "description": "Placeholder release to reserve the package name for Trusted Publishing.",
-  "license": "MIT"
-}
+  "version": "0.2.1",
+  "description": "karin 的 shotium 截图、渲染插件",
+  "keywords": [
+    "karin",
+    "node-karin",
+    "karin-plugin",
+    "shotium",
+    "screenshot",
+    "render"
+  ],
+  "license": "MIT",
+  "author": "sj817",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KarinJS/plugin-shotium.git"
+  },
+  "dependencies": {
+    "@shotkit/shotium": "^0.3.3"
+  },
+  "devDependencies": {
+    "@types/express": "5.0.6",
+    "@types/node": "^22.19.15",
+    "eslint": "^9.7.0",
+    "neostandard": "^0.12.1",
+    "node-karin": "^1.17.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.8"
+  },
+  "karin": {
+    "main": "src/index.ts",
+    "apps": [],
+    "web": "dist/web.config.js",
+    "ts-web": "src/web.config.ts",
+    "files": [
+      "config"
+    ]
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc && tsup",
+    "dev": "tsx src/app.ts",
+    "lint": "eslint src/",
+    "pub": "pnpm publish --access public",
+    "rm": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "sync": "curl -X PUT \"https://registry-direct.npmmirror.com/-/package/@karinjs/plugin-shotium/syncs\"",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}