@empty-sekai/renderer-wasm 0.1.0

package/dist/worker-client.js

@@ -0,0 +1,105 @@
+/**
+ * Worker 客户端：在主线程驱动渲染 Worker，返回 Promise。
+ *
+ * 这是浏览器中的推荐入口——skia 光栅化在 Worker 内同步执行，不阻塞 UI。
+ *
+ * ```ts
+ * import { AlliumWorkerClient } from "@allium/renderer-wasm/worker";
+ *
+ * const client = await AlliumWorkerClient.spawn({
+ *   workerUrl: new URL("@allium/renderer-wasm/worker.js", import.meta.url),
+ *   moduleUrl: new URL("@allium/renderer-wasm/allium_renderer_wasm.js", import.meta.url).href,
+ * });
+ * const jpeg = await client.render({ cardJson, masterData, fonts, assets });
+ * ```
+ */
+import { ImageFormat } from "./renderer.js";
+export { ImageFormat };
+export class AlliumWorkerClient {
+    worker;
+    nextId = 1;
+    pending = new Map();
+    constructor(worker) {
+        this.worker = worker;
+        this.worker.onmessage = (ev) => {
+            const msg = ev.data;
+            const entry = this.pending.get(msg.id);
+            if (!entry)
+                return;
+            this.pending.delete(msg.id);
+            if (msg.ok)
+                entry.resolve(msg.result);
+            else
+                entry.reject(new Error(msg.error));
+        };
+        this.worker.onerror = (ev) => {
+            const err = new Error(ev.message || "Worker 错误");
+            for (const { reject } of this.pending.values())
+                reject(err);
+            this.pending.clear();
+        };
+    }
+    /** 启动 Worker 并完成初始化握手。 */
+    static async spawn(opts) {
+        const worker = new Worker(opts.workerUrl, { type: "module" });
+        const client = new AlliumWorkerClient(worker);
+        await client.post({
+            id: client.nextId++,
+            kind: "init",
+            payload: { moduleUrl: opts.moduleUrl, wasmUrl: opts.wasmUrl },
+        });
+        return client;
+    }
+    /** 渲染名片，返回编码图片字节。 */
+    async render(req) {
+        const result = await this.post({ id: this.nextId++, kind: "render", payload: req }, this.collectTransfer(req));
+        return result;
+    }
+    /**
+     * 分层裁剪渲染，返回裁剪后的 WebP 字节及其在原画布的偏移。
+     */
+    async renderLayerCropped(req) {
+        const result = await this.post({ id: this.nextId++, kind: "renderLayerCropped", payload: req }, this.collectTransfer(req));
+        return result;
+    }
+    /**
+     * 批量分层裁剪渲染：一次返回所有元素的 WebP 字节 + 元数据。
+     */
+    async renderAllLayers(req) {
+        const result = await this.post({ id: this.nextId++, kind: "renderAllLayers", payload: req }, this.collectTransfer(req));
+        return result;
+    }
+    /** 收集名片所需素材 key。 */
+    async collectAssetKeys(cardJson, masterData) {
+        const result = await this.post({
+            id: this.nextId++,
+            kind: "collectAssetKeys",
+            payload: { cardJson, masterData },
+        });
+        return result;
+    }
+    /** 终止 Worker，拒绝所有在途请求。 */
+    terminate() {
+        this.worker.terminate();
+        for (const { reject } of this.pending.values()) {
+            reject(new Error("Worker 已终止"));
+        }
+        this.pending.clear();
+    }
+    collectTransfer(req) {
+        // 转移字体/素材的 ArrayBuffer，避免结构化克隆复制大缓冲。
+        // 注意：转移后调用方的 Uint8Array 会失效（detached）；如需复用请先复制。
+        const transfer = [];
+        for (const f of req.fonts)
+            transfer.push(f.bytes.buffer);
+        for (const a of req.assets)
+            transfer.push(a.bytes.buffer);
+        return transfer;
+    }
+    post(msg, transfer = []) {
+        return new Promise((resolve, reject) => {
+            this.pending.set(msg.id, { resolve, reject });
+            this.worker.postMessage(msg, transfer);
+        });
+    }
+}

package/dist/worker.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 渲染 Worker 入口。在 Worker 线程加载 wasm 并串行处理请求。
+ *
+ * 用法（主线程通过 `./worker-client` 间接使用，或手动）：
+ * ```ts
+ * const worker = new Worker(
+ *   new URL("@allium/renderer-wasm/worker.js", import.meta.url),
+ *   { type: "module" },
+ * );
+ * ```
+ *
+ * 协议见 `./protocol`。请求严格串行（单 AlliumRenderer 实例）。
+ */
+export {};

package/dist/worker.js

@@ -0,0 +1,96 @@
+/**
+ * 渲染 Worker 入口。在 Worker 线程加载 wasm 并串行处理请求。
+ *
+ * 用法（主线程通过 `./worker-client` 间接使用，或手动）：
+ * ```ts
+ * const worker = new Worker(
+ *   new URL("@allium/renderer-wasm/worker.js", import.meta.url),
+ *   { type: "module" },
+ * );
+ * ```
+ *
+ * 协议见 `./protocol`。请求严格串行（单 AlliumRenderer 实例）。
+ */
+import { AlliumRenderer, ImageFormat } from "./renderer.js";
+let renderer = null;
+let moduleUrl = null;
+let wasmUrl;
+async function ensureRenderer() {
+    if (renderer)
+        return renderer;
+    if (!moduleUrl)
+        throw new Error("Worker 未初始化（先发送 init 消息）");
+    const factoryModule = (await import(/* @vite-ignore */ moduleUrl));
+    renderer = await AlliumRenderer.create(factoryModule.default, wasmUrl);
+    return renderer;
+}
+function handleInit(payload) {
+    moduleUrl = payload.moduleUrl;
+    wasmUrl = payload.wasmUrl;
+    renderer = null; // 下次请求时按新 URL 重建
+}
+function applyInputs(r, req) {
+    for (const { family, bytes } of req.fonts)
+        r.registerFont(family, bytes);
+    for (const [name, json] of Object.entries(req.masterData)) {
+        r.loadMasterData(name, json);
+    }
+    r.init();
+    for (const { key, bytes } of req.assets)
+        r.putAsset(key, bytes);
+}
+async function handle(msg) {
+    switch (msg.kind) {
+        case "init": {
+            handleInit(msg.payload);
+            return { transfer: [] };
+        }
+        case "render": {
+            const r = await ensureRenderer();
+            applyInputs(r, msg.payload);
+            const out = r.render(msg.payload.cardJson, msg.payload.format ?? ImageFormat.Jpeg, msg.payload.profileJson);
+            return { result: out, transfer: [out.buffer] };
+        }
+        case "renderLayerCropped": {
+            const r = await ensureRenderer();
+            applyInputs(r, msg.payload);
+            const out = r.renderLayerCropped(msg.payload.cardJson, msg.payload.quality ?? 80, msg.payload.profileJson);
+            return { result: out, transfer: [out.data.buffer] };
+        }
+        case "renderAllLayers": {
+            const r = await ensureRenderer();
+            applyInputs(r, msg.payload);
+            const layers = r.renderAllLayers(msg.payload.cardJson, msg.payload.quality ?? 80, msg.payload.includeProperties ?? true, msg.payload.profileJson);
+            // 每层 data 是独立 Uint8Array，全部 transfer 回主线程，避免大缓冲克隆。
+            const transfer = layers
+                .map((l) => l.data.buffer)
+                .filter((b) => b.byteLength > 0);
+            return { result: layers, transfer };
+        }
+        case "collectAssetKeys": {
+            const r = await ensureRenderer();
+            for (const [name, json] of Object.entries(msg.payload.masterData)) {
+                r.loadMasterData(name, json);
+            }
+            r.init();
+            const keys = r.collectAssetKeys(msg.payload.cardJson);
+            return { result: keys, transfer: [] };
+        }
+    }
+}
+self.onmessage = async (ev) => {
+    const msg = ev.data;
+    try {
+        const { result, transfer } = await handle(msg);
+        const res = { id: msg.id, ok: true, result };
+        self.postMessage(res, transfer);
+    }
+    catch (err) {
+        const res = {
+            id: msg.id,
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+        self.postMessage(res);
+    }
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@empty-sekai/renderer-wasm",
+  "version": "0.1.0",
+  "description": "Browser wasm build of the allium custom-profile-card renderer (skia CPU + FreeType).",
+  "type": "module",
+  "license": "AGPL-3.0-only",
+  "files": [
+    "dist/",
+    "src/",
+    "LICENSE",
+    "LICENSE-EXCEPTION",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./worker": {
+      "types": "./dist/worker-client.d.ts",
+      "import": "./dist/worker-client.js"
+    },
+    "./allium_renderer_wasm.wasm": "./dist/allium_renderer_wasm.wasm"
+  },
+  "scripts": {
+    "build:wasm": "bash ./build.sh",
+    "build:ts": "tsc -p tsconfig.json && node ./scripts/copy-artifacts.mjs",
+    "build": "npm run build:wasm && npm run build:ts"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/emscripten.ts

@@ -0,0 +1,37 @@
+/**
+ * emscripten 运行时模块类型（MODULARIZE + EXPORT_ES6 产物）。
+ *
+ * 构建产物 `allium_renderer_wasm.js` 默认导出一个工厂函数
+ * `createAlliumRenderer(moduleArg?) => Promise<EmscriptenModule>`。
+ * 其导出函数集合与 `.cargo/config.toml` 的 EXPORTED_FUNCTIONS /
+ * EXPORTED_RUNTIME_METHODS 必须保持一致。
+ */
+
+export interface EmscriptenModule {
+  /** wasm 线性内存的字节视图。ALLOW_MEMORY_GROWTH 下增长后会被替换，每次用前重读。 */
+  HEAPU8: Uint8Array;
+  HEAPU32: Uint32Array;
+
+  _malloc(size: number): number;
+  _free(ptr: number): void;
+
+  getValue(ptr: number, type: "i32" | "i8" | "i16" | "float" | "double" | "*"): number;
+  setValue(ptr: number, value: number, type: "i32" | "i8" | "i16" | "float" | "double" | "*"): void;
+  lengthBytesUTF8(str: string): number;
+  stringToUTF8(str: string, outPtr: number, maxBytes: number): void;
+  UTF8ToString(ptr: number, maxBytes?: number): string;
+
+  cwrap(
+    name: string,
+    returnType: "number" | "void" | null,
+    argTypes: Array<"number" | "string" | "array">,
+  ): (...args: number[]) => number;
+
+  // alr_* 导出（直接引用形式，cwrap 是更安全的调用入口）
+  _alr_alloc(size: number): number;
+  _alr_free(ptr: number, size: number): void;
+}
+
+export type EmscriptenModuleFactory = (
+  moduleArg?: Partial<EmscriptenModule> & { locateFile?: (path: string, prefix: string) => string },
+) => Promise<EmscriptenModule>;

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @empty-sekai/renderer-wasm — 浏览器名片渲染。
+ *
+ * 入口导出核心封装与类型。Worker 调度见子路径 `@empty-sekai/renderer-wasm/worker`。
+ *
+ * 最小用法（主线程，注意 skia 光栅化同步阻塞）：
+ * ```ts
+ * import createAlliumRenderer from "@empty-sekai/renderer-wasm/allium_renderer_wasm.js";
+ * import { AlliumRenderer, ImageFormat } from "@empty-sekai/renderer-wasm";
+ *
+ * const r = await AlliumRenderer.create(createAlliumRenderer);
+ * r.registerFont("FZLanTingHei-DB-GBK", await fetchBytes("/fonts/lanting.ttf"));
+ * for (const [name, json] of tables) r.loadMasterData(name, json);
+ * r.init();
+ * for (const key of r.collectAssetKeys(cardJson)) {
+ *   r.putAsset(key, await fetchBytes(assetUrl(key)));
+ * }
+ * const jpeg = r.render(cardJson, ImageFormat.Jpeg);
+ * ```
+ */
+
+export { AlliumRenderer, ImageFormat, AlliumRenderError } from "./renderer.js";
+export type { CroppedLayerOutput, LayerCrop } from "./renderer.js";
+export type { EmscriptenModule, EmscriptenModuleFactory } from "./emscripten.js";