@zzclub/pipeline 0.13.0 → 0.13.2

package/src/wechat-preview/assets/templates/export-shell.html

@@ -12,11 +12,17 @@
       <script id="zzhub-wechat-export-result" type="application/json">{"status":"pending"}</script>
     </div>
     <script>
+      var renderFinished = false;
+      var resolveRender;
+      window.__zzhubRenderReady = new Promise(function (resolve) { resolveRender = resolve; });
       window.__ZZHUB_SET_RESULT__ = function (payload) {
+        if (renderFinished) return;
+        renderFinished = true;
         var el = document.getElementById("zzhub-wechat-export-result");
         if (el) {
           el.textContent = JSON.stringify(payload);
         }
+        resolveRender();
       };
       window.addEventListener("error", function (event) {
         window.__ZZHUB_SET_RESULT__({

package/src/wechat-preview/browser/editor-export.ts

@@ -13,24 +13,17 @@ interface BrowserPayload {
   customCss?: string;
 }
 
+type BrowserResult =
+  | { status: "success"; html: string; semanticHtml?: string }
+  | { status: "error"; error: string };
+
 declare global {
   interface Window {
     __ZZHUB_WECHAT_PAYLOAD__?: BrowserPayload;
+    __ZZHUB_SET_RESULT__: (result: BrowserResult) => void;
   }
 }
 
-function setResult(
-  result:
-    | { status: "success"; html: string; semanticHtml?: string }
-    | { status: "error"; error: string },
-): void {
-  const el = document.getElementById("zzhub-wechat-export-result");
-  if (!el) {
-    return;
-  }
-  el.textContent = JSON.stringify(result);
-}
-
 async function main(): Promise<void> {
   const payload = window.__ZZHUB_WECHAT_PAYLOAD__;
   if (!payload) {
@@ -51,7 +44,7 @@ async function main(): Promise<void> {
     .use(gfm);
   await editor.create();
   const semanticHtml = editor.action(getHTML());
-  const html = renderWechatHtml({
+  const html = await renderWechatHtml({
     semanticHtml,
     baseCss: articleCss,
     customCss: payload.customCss,
@@ -59,10 +52,10 @@ async function main(): Promise<void> {
     theme: payload.exportTheme,
   });
   await editor.destroy();
-  setResult({ status: "success", html, semanticHtml });
+  window.__ZZHUB_SET_RESULT__({ status: "success", html, semanticHtml });
 }
 
 void main().catch((error: unknown) => {
   const detail = error instanceof Error ? error.message : String(error);
-  setResult({ status: "error", error: detail });
+  window.__ZZHUB_SET_RESULT__({ status: "error", error: detail });
 });

package/src/wechat-preview/index.ts

@@ -4,14 +4,13 @@ import { createRequire } from "module";
 import { dirname, isAbsolute, join, resolve } from "path";
 import { pathToFileURL } from "url";
 import {
-  ChromeDumpError,
-  dumpHtmlDom,
   ensureParentDir,
   escapeHtml,
   findChrome,
   readUtf8,
   renderTemplate,
 } from "../imgx/runtime";
+import { ChromeRenderError, dumpReadyHtml } from "../imgx/chrome-render";
 import {
   PACKAGE_ROOT,
   TEMPLATE_PATH,
@@ -45,6 +44,7 @@ export type WechatExportErrorKind =
 export interface WechatExportDebugInfo {
   chrome_path?: string;
   virtual_time_budget_ms?: number;
+  timeout_ms?: number;
   bundle_stale?: boolean;
   bundle_rebuilt?: boolean;
   shell_path?: string;
@@ -94,7 +94,7 @@ export interface ExportMarkdownToWechatHtmlInput {
     editorVars?: Record<string, string>;
     exportTheme?: Record<string, string>;
   };
-  /** Chrome virtual-time-budget in ms (default 15000). */
+  /** 浏览器真实等待上限，默认 15000 毫秒。 */
   timeoutMs?: number;
   /** Write intermediate artifacts for debugging. */
   debugDir?: string;
@@ -320,7 +320,7 @@ export async function exportMarkdownToWechatHtml(
   input: ExportMarkdownToWechatHtmlInput,
 ): Promise<ExportMarkdownToWechatHtmlResult> {
   const started = Date.now();
-  const timeoutMs = input.timeoutMs ?? 15_000;
+  const timeoutMs = input.timeoutMs && Number.isFinite(input.timeoutMs) && input.timeoutMs > 0 ? input.timeoutMs : 15_000;
   const title = input.title ?? "Wechat Preview Export";
   let chromePath: string | undefined;
   let bundleRebuilt = false;
@@ -339,7 +339,7 @@ export async function exportMarkdownToWechatHtml(
       markdownPath: input.markdownPath,
       debug: {
         chrome_path: chromePath,
-        virtual_time_budget_ms: timeoutMs,
+        timeout_ms: timeoutMs,
         bundle_stale: bundleStale,
         bundle_rebuilt: bundleRebuilt,
         debug_dir: input.debugDir,
@@ -401,29 +401,31 @@ export async function exportMarkdownToWechatHtml(
 
     let dumpedDom: string;
     try {
-      dumpedDom = dumpHtmlDom({
+      dumpedDom = await dumpReadyHtml({
         chromePath,
         html: shellHtml,
-        virtualTimeBudgetMs: timeoutMs,
-        keepTempOnError: Boolean(input.debugDir),
+        timeoutMs,
       });
     } catch (error) {
-      if (error instanceof ChromeDumpError) {
+      if (error instanceof ChromeRenderError) {
         if (input.debugDir) {
           await writeDebugArtifacts(input.debugDir, {
             "00-payload-markdown.md": markdown,
             "01-export-shell.html": shellHtml,
             "meta.json": JSON.stringify({
               status: "failed",
-              kind: "chrome_failed",
+              kind: error.kind,
               error: error.message,
               stderr: error.stderr,
               duration_ms: Date.now() - started,
+              timeout_ms: timeoutMs,
             }, null, 2),
           });
         }
-        throw makeError("chrome_failed", error.message, {
-          shell_path: error.tempHtmlPath,
+        throw makeError(error.kind, error.kind === "timeout"
+          ? `Wechat preview export did not finish before timeout (${timeoutMs}ms real time)`
+          : error.message, {
+          shell_path: input.debugDir ? join(input.debugDir, "01-export-shell.html") : undefined,
           stderr_tail: stderrTail(error.stderr),
           debug_dir: input.debugDir,
         });
@@ -445,15 +447,15 @@ export async function exportMarkdownToWechatHtml(
           "02-dump-dom.html": dumpedDom,
           "meta.json": JSON.stringify({
             status: "failed",
-            kind: "timeout",
+            kind: "render_error",
             error: error instanceof Error ? error.message : String(error),
             duration_ms: Date.now() - started,
           }, null, 2),
         });
       }
       throw makeError(
-        "timeout",
-        `Wechat preview export did not finish before timeout (${timeoutMs}ms): ${
+        "render_error",
+        `Wechat preview export returned an invalid result: ${
           error instanceof Error ? error.message : String(error)
         }`,
       );
@@ -483,15 +485,15 @@ export async function exportMarkdownToWechatHtml(
           "02-dump-dom.html": dumpedDom,
           "meta.json": JSON.stringify({
             status: "failed",
-            kind: "timeout",
+            kind: "render_error",
             status_value: result.status,
             duration_ms: Date.now() - started,
           }, null, 2),
         });
       }
       throw makeError(
-        "timeout",
-        `Wechat preview export did not finish before timeout (status=${result.status}, budget=${timeoutMs}ms)`,
+        "render_error",
+        `Wechat preview export returned an incomplete result (status=${result.status})`,
       );
     }
 

package/src/wechat-preview/server/types.ts

@@ -11,6 +11,7 @@ export type PreviewEntryStatus = "success" | "failed";
 export interface PreviewEntryDebug {
   chrome_path?: string;
   virtual_time_budget_ms?: number;
+  timeout_ms?: number;
   bundle_stale?: boolean;
   bundle_rebuilt?: boolean;
   shell_path?: string;

package/src/wechat-preview/wechat-export.integration.test.ts

@@ -1,10 +1,14 @@
-import { afterAll, describe, expect, test } from "bun:test";
+import { afterEach, describe, expect, test } from "bun:test";
 import { mkdtemp, readFile, rm, writeFile } from "fs/promises";
 import { tmpdir } from "os";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
+import { PNG } from "pngjs";
 import { findChrome } from "../imgx/runtime";
-import { exportMarkdownToWechatHtml } from "./index";
+import { dumpReadyHtml } from "../imgx/chrome-render";
+import { TEMPLATE_PATH } from "../runtime-paths";
+import { replaceImageUrls } from "../providers/wechat";
+import { exportMarkdownToWechatHtml, extractRenderResult } from "./index";
 
 const fixturePath = join(
   dirname(fileURLToPath(import.meta.url)),
@@ -15,7 +19,7 @@ const fixturePath = join(
 describe("semantic WeChat HTML export", () => {
   let tempDir: string | null = null;
 
-  afterAll(async () => {
+  afterEach(async () => {
     if (tempDir) await rm(tempDir, { recursive: true, force: true });
   });
 
@@ -91,4 +95,125 @@ describe("semantic WeChat HTML export", () => {
     expect(preview).not.toContain("editor-export.js");
     expect(preview).not.toContain("browser-dist");
   }, 30_000);
+
+  test.skipIf(findChrome() === null)("preserves Crepe image scaling and captions through export and upload URL replacement", async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "zzhub-wechat-images-"));
+    for (const [name, width, height] of [["large", 1200, 600], ["small", 200, 400]] as const) {
+      const png = new PNG({ width, height });
+      png.data.fill(255);
+      await writeFile(join(tempDir, `${name}.png`), PNG.sync.write(png));
+    }
+
+    // 同一图片的不同缩放必须各自生效，小图不能按正文宽度放大。
+    const scaledImages = [
+      { name: "large", ratio: "0.50", width: 50, maxWidth: 600 },
+      { name: "large", ratio: "1.00", width: 100, maxWidth: 1200 },
+      { name: "large", ratio: "1.50", width: 100, maxWidth: 1800 },
+      { name: "small", ratio: "0.50", width: 50, maxWidth: 100 },
+      { name: "small", ratio: "1.00", width: 100, maxWidth: 200 },
+      { name: "small", ratio: "1.50", width: 100, maxWidth: 300 },
+    ];
+    const ordinaryAlts = ["普通说明", "", "2026", "0.00", "-0.50", "0.5", "1.00x", "Infinity"];
+    const markdownPath = join(tempDir, "images.md");
+    await writeFile(markdownPath, [
+      ...scaledImages.map(({ name, ratio }, index) => `![${ratio}](./${name}.png "缩放图注 ${index}")`),
+      ...ordinaryAlts.map(alt => `![${alt}](./small.png "普通图注")`),
+      '行内图片 ![0.50](./small.png "行内图注") 后文',
+    ].join("\n\n"));
+
+    const result = await exportMarkdownToWechatHtml({
+      markdownPath,
+      outPath: join(tempDir, "images.html"),
+      account: "default",
+    });
+    const uploadedHtml = replaceImageUrls(result.html, {
+      [join(tempDir, "large.png")]: "https://mmbiz.qpic.cn/large.png",
+      [join(tempDir, "small.png")]: "https://mmbiz.qpic.cn/small.png",
+    });
+    const images = uploadedHtml.match(/<img\b[^>]*>/g) ?? [];
+    expect(images).toHaveLength(scaledImages.length + ordinaryAlts.length + 1);
+    scaledImages.forEach(({ name, width, maxWidth }, index) => {
+      expect(images[index]).toContain(`width: ${width}%;`);
+      expect(images[index]).toContain(`max-width: ${maxWidth}px;`);
+      expect(images[index]).toContain("height: auto;");
+      expect(images[index]).toContain(`src="https://mmbiz.qpic.cn/${name}.png"`);
+      expect(images[index]).toContain(`data-src="https://mmbiz.qpic.cn/${name}.png"`);
+      expect(uploadedHtml).toMatch(new RegExp(`<p[^>]*>缩放图注 ${index}</p>`));
+    });
+    ordinaryAlts.forEach((alt, index) => {
+      expect(images[scaledImages.length + index]).toContain(`alt="${alt}"`);
+      expect(images[scaledImages.length + index]).toContain("width: auto;");
+      expect(images[scaledImages.length + index]).toContain("max-width: 100%;");
+    });
+    expect(uploadedHtml).toMatch(/<p[^>]*>普通图注<\/p>/);
+    expect(images.at(-1)).toContain('alt="0.50"');
+    expect(images.at(-1)).toContain("width: auto;");
+    expect(uploadedHtml).not.toContain(">行内图注</p>");
+    expect(uploadedHtml).not.toContain(tempDir);
+  }, 30_000);
+
+  test.skipIf(findChrome() === null)("reports an export error when a scaled image cannot be decoded", async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "zzhub-wechat-image-error-"));
+    const markdownPath = join(tempDir, "images.md");
+    await writeFile(join(tempDir, "broken.png"), "not an image");
+    await writeFile(markdownPath, '![0.50](./broken.png "失败图注")');
+
+    await expect(exportMarkdownToWechatHtml({
+      markdownPath,
+      outPath: join(tempDir, "images.html"),
+      account: "default",
+    })).rejects.toMatchObject({
+      kind: "render_error",
+      message: expect.stringContaining("无法读取缩放图片的原始尺寸"),
+    });
+  }, 30_000);
+
+  test.skipIf(findChrome() === null)("waits for remote PNG and GIF responses before completing scaled HTML export", async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "zzhub-wechat-remote-"));
+    const png = new PNG({ width: 200, height: 100 });
+    png.data.fill(255);
+    const pngBytes = PNG.sync.write(png);
+    const gif = Buffer.from("R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7", "base64");
+    const requested = Promise.withResolvers<void>();
+    const release = Promise.withResolvers<void>();
+    const server = Bun.serve({ hostname: "127.0.0.1", port: 0, async fetch(request) {
+      requested.resolve();
+      await release.promise;
+      const isGif = request.url.endsWith(".gif");
+      return new Response(isGif ? gif : pngBytes, { headers: { "content-type": isGif ? "image/gif" : "image/png", "cache-control": "no-store" } });
+    } });
+    const markdownPath = join(tempDir, "images.md");
+    await writeFile(markdownPath, `![0.50](http://127.0.0.1:${server.port}/photo.png "远程图注")\n\n![0.50](http://127.0.0.1:${server.port}/motion.gif "动图图注")`);
+    let finished = false;
+    const exporting = exportMarkdownToWechatHtml({ markdownPath, outPath: join(tempDir, "images.html"), account: "default" })
+      .then(result => { finished = true; return result; });
+    try {
+      await Promise.race([requested.promise, exporting]);
+      // 人为延迟网络响应，确认导出不会提前读到 pending。
+      await Bun.sleep(800);
+      expect(finished).toBe(false);
+      release.resolve();
+      const { html } = await exporting;
+      expect(html).toContain("width: 50%;");
+      expect(html).toContain("max-width: 100px;");
+      expect(html).toContain("max-width: 0.5px;");
+      expect(html).toContain("远程图注</p>");
+      expect(html).toContain("动图图注</p>");
+      expect(html).toContain("/motion.gif");
+    } finally {
+      release.resolve();
+      await exporting.catch(() => {});
+      await server.stop(true);
+    }
+  }, 30_000);
+
+  test.skipIf(findChrome() === null)("settles the export result when the browser module fails to load", async () => {
+    const html = (await readFile(TEMPLATE_PATH, "utf8"))
+      .replace("{{PAGE_TITLE}}", "加载失败")
+      .replace("{{CSS_LINK}}", "")
+      .replace("{{PAYLOAD_JSON}}", "{}")
+      .replace("{{SCRIPT_URL}}", "file:///missing/wechat-editor.js");
+    const result = extractRenderResult(await dumpReadyHtml({ chromePath: findChrome()!, html, timeoutMs: 5000 }));
+    expect(result).toEqual({ status: "error", error: "failed to load wechat preview bundle" });
+  }, 10_000);
 });

package/src/wechat-preview/wechat-renderer.ts

@@ -34,7 +34,7 @@ export interface WechatElementRenderer {
   selector: string;
   /** Optional selector used after CSS has been inlined. Defaults to selector. */
   finalizeSelector?: string;
-  prepare?: (element: HTMLElement, context: WechatRenderContext) => void;
+  prepare?: (element: HTMLElement, context: WechatRenderContext) => void | Promise<void>;
   finalize?: (element: HTMLElement, context: WechatRenderContext) => void;
 }
 
@@ -220,11 +220,12 @@ function imageIsOnlyContent(parent: HTMLElement, image: HTMLElement): boolean {
   });
 }
 
+// 图片缩放与图注共用导出流程，分别读取 alt 和 title。
 const imageRenderer: WechatElementRenderer = {
   kind: "image",
   selector: "img",
   finalizeSelector: "figure, figcaption",
-  prepare(element, context) {
+  async prepare(element, context) {
     setNodeKind(element, "image");
     const src = element.getAttribute("src");
     if (src) element.setAttribute("data-src", src);
@@ -234,6 +235,24 @@ const imageRenderer: WechatElementRenderer = {
       return;
     }
 
+    // Crepe 仅将独立图片的缩放比例序列化为两位小数。
+    const alt = element.getAttribute("alt") ?? "";
+    const ratio = /^(?:0|[1-9]\d*)\.\d{2}$/.test(alt) ? Number(alt) : 0;
+    if (ratio > 0 && Number.isFinite(ratio)) {
+      // DOMParser 文档不加载图片，用浏览器图片对象读取原始尺寸。
+      const sourceImage = new Image();
+      sourceImage.src = src ?? "";
+      try {
+        await sourceImage.decode();
+        if (!sourceImage.naturalWidth) throw new Error("图片原始宽度为空");
+      } catch (error) {
+        throw new Error(`无法读取缩放图片的原始尺寸：${element.getAttribute("title") || "无图注"}`, { cause: error });
+      }
+      element.style.width = `${Math.min(ratio, 1) * 100}%`;
+      element.style.maxWidth = `${sourceImage.naturalWidth * ratio}px`;
+      element.style.height = "auto";
+    }
+
     const figure = context.document.createElement("figure");
     setNodeKind(figure, "image-block");
     parent.replaceWith(figure);
@@ -500,11 +519,12 @@ export function createWechatRendererRegistry(
   return DEFAULT_RENDERERS.map((renderer) => overrides[renderer.kind] ?? renderer);
 }
 
-function runRendererPhase(
+/** 按渲染器顺序执行，等待图片尺寸读取完成。 */
+async function runRendererPhase(
   phase: "prepare" | "finalize",
   renderers: WechatElementRenderer[],
   context: WechatRenderContext,
-): void {
+): Promise<void> {
   for (const renderer of renderers) {
     const handler = renderer[phase];
     if (!handler) continue;
@@ -515,7 +535,7 @@ function runRendererPhase(
     if (context.root.matches(selector)) elements.push(context.root);
     elements.push(...Array.from(context.root.querySelectorAll<HTMLElement>(selector)));
     for (const element of elements) {
-      if (element.isConnected || element === context.root) handler(element, context);
+      if (element.isConnected || element === context.root) await handler(element, context);
     }
   }
 }
@@ -640,7 +660,8 @@ function sanitizeTree(root: HTMLElement): void {
   }
 }
 
-export function renderWechatHtml(input: RenderWechatHtmlInput): string {
+/** 完成图片缩放后，将文章样式内联为公众号 HTML。 */
+export async function renderWechatHtml(input: RenderWechatHtmlInput): Promise<string> {
   const sourceDocument = parseHtml("");
   const compatibilityRoot = sourceDocument.createElement("section");
   compatibilityRoot.className = "milkdown";
@@ -655,7 +676,7 @@ export function renderWechatHtml(input: RenderWechatHtmlInput): string {
 
   const references: WechatLinkReference[] = [];
   const renderers = createWechatRendererRegistry(input.renderers);
-  runRendererPhase("prepare", renderers, {
+  await runRendererPhase("prepare", renderers, {
     document: sourceDocument,
     root,
     theme: input.theme,
@@ -687,7 +708,7 @@ export function renderWechatHtml(input: RenderWechatHtmlInput): string {
   const finalRoot = finalDocument.querySelector<HTMLElement>(".zzhub-wechat-article");
   if (!finalRoot) throw new Error("Wechat article root missing after CSS inlining");
 
-  runRendererPhase("finalize", renderers, {
+  await runRendererPhase("finalize", renderers, {
     document: finalDocument,
     root: finalRoot,
     theme: input.theme,