@akairos/typeset-studio 0.2.2 → 0.2.4

package/dist/lib/render-xxd348m1.js

@@ -0,0 +1,11 @@
+import {
+  renderRouter,
+  resolveTypesetResult
+} from "./index-t9w3p2p9.js";
+import"./index-zdhqg5f0.js";
+import"./index-6c43c7h4.js";
+import"./index-37x76zdn.js";
+export {
+  resolveTypesetResult,
+  renderRouter
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akairos/typeset-studio",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Algorithmic typesetting studio & zzhub-pipeline image renderer plugin",
   "publishConfig": {
     "access": "public"
@@ -32,7 +32,6 @@
     "dist/index.html",
     "dist/lib",
     "src",
-    "data/templates",
     "public/fonts/README.md",
     "public/fonts/fonts.json",
     "README.md"
@@ -42,7 +41,7 @@
     "dev:server": "bun --watch src/server/index.ts",
     "dev:all": "bun --watch src/server/index.ts & vite",
     "build": "vite build && bun run build:lib",
-    "build:lib": "bun build src/index.ts src/adapter.ts --outdir dist/lib --target node --external @napi-rs/canvas",
+    "build:lib": "rm -rf dist/lib && bun build src/index.ts src/adapter.ts --outdir dist/lib --target node --splitting --external @napi-rs/canvas",
     "build:watch": "vite build --watch",
     "preview": "vite preview",
     "server": "bun run src/server/index.ts",

package/src/adapter.test.ts

@@ -140,3 +140,120 @@ describe("Typeset Studio — zzhub-pipeline ImageRenderPlugin Adapter", () => {
     expect(result.pageCount).toBe(0);
   });
 });
+
+describe("Remote adapter regressions", () => {
+  it("authenticates, transfers local bytes and preserves page image summaries", async () => {
+    const { app } = await import("./server/index");
+    const { getOrGenerateAdminKey } = await import("./server/auth");
+    const { createCanvas } = await import("@napi-rs/canvas");
+    const { mkdtemp, writeFile, rm } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const directory = await mkdtemp(join(tmpdir(), "typeset-remote-"));
+    const imagePath = join(directory, "source.png");
+    await writeFile(imagePath, createCanvas(8, 8).toBuffer("image/png"));
+    const requests: any[] = [];
+    const server = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: async (request) => {
+      if (request.url.endsWith("/api/render/export")) requests.push(await request.clone().json());
+      return app.fetch(request);
+    } });
+    const previousUrl = process.env.TYPESET_STUDIO_URL;
+    const previousKey = process.env.TYPESET_ADMIN_KEY;
+    process.env.TYPESET_STUDIO_URL = server.url.toString();
+    process.env.TYPESET_ADMIN_KEY = getOrGenerateAdminKey();
+    try {
+      const progress: string[] = [];
+      const output = await typesetStudioAdapter.render({
+        route: "wechat-newspic", outputDir: directory, title: "远程测试", bodyText: "完整正文".repeat(100),
+        state: { route: { account: "default" } },
+        minPages: 3, maxPages: 8,
+        bodyImages: [{ marker: "one", path: imagePath }],
+        pageSpecs: [{ page: 2, imageMarkers: ["one"], targetFillRatio: 0.5 }],
+        accountVisualParams: { bg: "#123456", highlight: "#abcdef", footer: "测试署名", fallbackIcon: imagePath },
+        onProgress: (event) => progress.push(event.stage),
+      });
+      expect(output.pageCount).toBeGreaterThanOrEqual(3);
+      expect(output.pages[1].imageCount).toBe(1);
+      expect(output.pages[1].imageSources).toEqual([imagePath]);
+      expect(requests[1].images[0].src).toStartWith("data:image/png;base64,");
+      expect(requests[1].minPages).toBe(3);
+      expect(requests[1].pageFillRatios[2]).toBe(0.5);
+      expect(requests[1].config.theme.bgColor).toBe("#123456");
+      expect(requests[0].config.images[0].id).toBe("account_icon");
+      expect(progress).toEqual(["typeset", "cover", "content"]);
+      process.env.TYPESET_ADMIN_KEY = "wrong-test-key";
+      await expect(typesetStudioAdapter.render({
+        route: "wechat-article", outputDir: directory, title: "失败", bodyText: "", state: { route: {} },
+      })).rejects.toThrow("401");
+    } finally {
+      if (previousUrl === undefined) delete process.env.TYPESET_STUDIO_URL; else process.env.TYPESET_STUDIO_URL = previousUrl;
+      if (previousKey === undefined) delete process.env.TYPESET_ADMIN_KEY; else process.env.TYPESET_ADMIN_KEY = previousKey;
+      server.stop(true);
+      await rm(directory, { recursive: true, force: true });
+    }
+  });
+});
+
+it("uses selected/default Studio templates and produces identical fixed assets locally and remotely", async () => {
+  const { app } = await import("./server/index");
+  const { getOrGenerateAdminKey } = await import("./server/auth");
+  const { getDefaultConfig } = await import("./core/engine");
+  const { getSlotDefaultTemplateId, setSlotDefaultTemplateId } = await import("./server/routes/templates");
+  const { createCanvas } = await import("@napi-rs/canvas");
+  const { mkdtemp, writeFile, rm } = await import("node:fs/promises");
+  const { tmpdir } = await import("node:os");
+  const directory = await mkdtemp(join(tmpdir(), "typeset-fixed-adapter-"));
+  const source = join(directory, "background.png");
+  const replacement = join(directory, "replacement.png");
+  const canvas = createCanvas(20, 20);
+  const context = canvas.getContext("2d");
+  context.fillStyle = "#ff0000";
+  context.fillRect(0, 0, 20, 20);
+  await writeFile(source, canvas.toBuffer("image/png"));
+  context.fillStyle = "#00ff00";
+  context.fillRect(0, 0, 20, 20);
+  await writeFile(replacement, canvas.toBuffer("image/png"));
+  const headers = { "Content-Type": "application/json", "x-admin-key": getOrGenerateAdminKey() };
+  const templateId = "fixed_adapter_test";
+  const config = getDefaultConfig("square-1-1");
+  const previousUrl = process.env.TYPESET_STUDIO_URL;
+  const previousKey = process.env.TYPESET_ADMIN_KEY;
+  const previousDefault = getSlotDefaultTemplateId("newspic_cover", "fixed-test");
+  const server = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: (request) => app.fetch(request) });
+  try {
+    const saved = await app.request("/api/templates", { method: "POST", headers, body: JSON.stringify({
+      ...config, id: templateId, images: [{ id: "bg", src: source, alt: "", templateAssetKey: "background", repeatEveryPage: true,
+        isAbsolute: true, x: -100, y: -100, width: 1080, height: 1080, zIndex: 0, borderRadius: 0 }],
+    }) });
+    expect(saved.status).toBe(200);
+    setSlotDefaultTemplateId("newspic_cover", templateId, "fixed-test");
+    delete process.env.TYPESET_STUDIO_URL;
+    const input: ImageRenderInput = { route: "wechat-newspic", title: "模板测试", bodyText: "", outputDir: join(directory, "local"),
+      state: { route: { account: "fixed-test" } }, template: "poster-3-4", theme: "unrelated-theme",
+      accountVisualParams: { bg: "#123456", fallbackIcon: "/must-not-load.png" },
+    };
+    const defaultOutput = await typesetStudioAdapter.render(input);
+    expect(defaultOutput.pages[0].imageCount).toBe(0);
+    const selected = { ...input, studioTemplates: { cover: templateId }, templateImageOverrides: { cover: { background: replacement } } };
+    const local = await typesetStudioAdapter.render({ ...selected, outputDir: join(directory, "override") });
+    expect(readFileSync(local.assets[0].path).equals(readFileSync(defaultOutput.assets[0].path))).toBe(false);
+    process.env.TYPESET_STUDIO_URL = server.url.toString();
+    process.env.TYPESET_ADMIN_KEY = getOrGenerateAdminKey();
+    const remote = await typesetStudioAdapter.render({ ...selected, outputDir: join(directory, "remote") });
+    expect(readFileSync(remote.assets[0].path).equals(readFileSync(local.assets[0].path))).toBe(true);
+    expect(remote.pages[0]).toEqual({ page: 1, imageCount: 0, imageSources: [] });
+    const resolved = await (await app.request(`/api/templates/${templateId}`, { headers })).json();
+    expect(resolved.template.images[0].src).toBe(source);
+    const unknown = { ...selected, templateImageOverrides: { cover: { missing: replacement } } };
+    await expect(typesetStudioAdapter.render(unknown)).rejects.toThrow("未知模板素材");
+    await expect(typesetStudioAdapter.render({ ...selected,
+      templateImageOverrides: { cover: { background: join(directory, "missing.png") } },
+    })).rejects.toThrow("模板素材 background 加载失败");
+  } finally {
+    server.stop(true);
+    await app.request(`/api/templates/${templateId}`, { method: "DELETE", headers });
+    setSlotDefaultTemplateId("newspic_cover", previousDefault, "fixed-test");
+    if (previousUrl === undefined) delete process.env.TYPESET_STUDIO_URL; else process.env.TYPESET_STUDIO_URL = previousUrl;
+    if (previousKey === undefined) delete process.env.TYPESET_ADMIN_KEY; else process.env.TYPESET_ADMIN_KEY = previousKey;
+    await rm(directory, { recursive: true, force: true });
+  }
+});

package/src/adapter.ts

@@ -1,9 +1,7 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { renderTypesetResultToPngs } from "./core/canvas-renderer";
-import { scanLocalFonts } from "./core/font-loader";
-import type { FlowImage } from "./core/types";
-import { resolveTypesetResult, type RenderRequestBody } from "./server/routes/render";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { extname, join } from "node:path";
+import type { FlowImage, PipelineCoverTheme } from "./core/types";
+import type { RenderRequestBody } from "./server/routes/render";
 
 // ── Typeset Studio & zzhub-pipeline compatible types ──────────────
 
@@ -15,8 +13,14 @@ export interface PipelinePluginDoctorCheck {
 }
 
 export interface ImageRenderInput {
-  coverTheme?: any;
-  onProgress?: (progress: any) => void;
+  /** Studio 模板与任务素材替换，旧插件可忽略。 */
+  studioTemplates?: { cover?: string; content?: string };
+  templateImageOverrides?: { cover?: Record<string, string>; content?: Record<string, string> };
+  coverTheme?: PipelineCoverTheme;
+  onProgress?: (progress: {
+    stage: string; message?: string; current?: number; total?: number;
+    unit?: "pages" | "files" | "bytes" | "targets"; route?: string; account?: string;
+  }) => void;
   state: {
     route: {
       account?: string;
@@ -34,6 +38,7 @@ export interface ImageRenderInput {
         pagination_mode?: string;
         min_pages?: number;
         max_pages?: number;
+        target_fill_ratio?: number;
         page_specs?: Array<{
           page: number;
           image_markers: string[];
@@ -141,7 +146,7 @@ function mapBodyImages(
 // ── Typeset Studio Pipeline Adapter ───────────────────────────────
 
 // 配置远程地址后，由独立服务负责图片渲染。
-const REMOTE_STUDIO_URL = process.env.TYPESET_STUDIO_URL?.replace(/\/$/, "");
+const remoteStudioUrl = () => process.env.TYPESET_STUDIO_URL?.replace(/\/$/, "");
 
 // 下载远程生成的页面，并写入流水线输出目录。
 async function renderRemoteBatch(
@@ -151,23 +156,53 @@ async function renderRemoteBatch(
   route: "wechat-article" | "wechat-newspic",
   kind: "cover" | "page",
 ): Promise<ImageRenderOutput> {
+  // 远程进程无法读取客户端文件，发送图片字节并保留来源摘要映射。
+  const sources = new Map<string, string>();
+  const originalImages = new Map([...(body.config?.images || []), ...(body.images || [])].map((image) => [image.id, image.src]));
+  const transfer = async (src: string) => {
+    if (/^(https?:|data:)/i.test(src) || src.startsWith("/uploads/")) return src;
+    const bytes = await readFile(src);
+    const mime = ({ ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".svg": "image/svg+xml", ".webp": "image/webp", ".gif": "image/gif" } as Record<string, string>)[extname(src).toLowerCase()] || "image/png";
+    const dataUrl = `data:${mime};base64,${bytes.toString("base64")}`;
+    sources.set(dataUrl, src);
+    return dataUrl;
+  };
+  const requestBody = structuredClone(body);
+  for (const image of requestBody.images || []) image.src = await transfer(image.src);
+  // 保留模板样式时，备用配置不参与正常模板渲染，也不读取其本地素材。
+  if (!requestBody.preserveTemplateStyle) {
+    for (const image of requestBody.config?.images || []) image.src = await transfer(image.src);
+  }
+  for (const [key, src] of Object.entries(requestBody.templateImageOverrides || {})) {
+    try {
+      requestBody.templateImageOverrides![key] = await transfer(src);
+    } catch (error) {
+      throw new Error(`模板素材 ${key} 加载失败：${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  const coverTheme = requestBody.config?.coverTheme;
+  for (const image of requestBody.preserveTemplateStyle ? [] : [coverTheme?.background.image, coverTheme?.decoration.image]) {
+    if (image) image.src = await transfer(image.src);
+  }
   const res = await fetch(`${studioUrl}/api/render/export`, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(body),
+    headers: { "Content-Type": "application/json", "X-Admin-Key": process.env.TYPESET_ADMIN_KEY || "" },
+    body: JSON.stringify(requestBody),
   });
   if (!res.ok) {
-    throw new Error(`Cloud Typeset Studio returned HTTP ${res.status}: ${res.statusText}`);
+    const detail = (await res.text()).slice(0, 500);
+    throw new Error(`Cloud Typeset Studio returned HTTP ${res.status}: ${detail || res.statusText}`);
   }
   const data = (await res.json()) as {
     ok: boolean;
     pageCount: number;
-    pages: Array<{ pageNumber: number; dataUrl: string }>;
+    pages: Array<{ pageNumber: number; dataUrl: string; imageCount: number; imageSources: string[]; imageIds: string[]; bodyImageCount: number; bodyImageSources: string[]; bodyImageIds: string[] }>;
   };
   const assets: RenderAsset[] = [];
   const pagesSummary: ImageRenderOutput["pages"] = [];
 
-  for (const pageItem of data.pages) {
+  if (!data.ok || !Array.isArray(data.pages)) throw new Error("Invalid Typeset Studio export response");
+  for (const pageItem of (kind === "cover" ? data.pages.slice(0, 1) : data.pages)) {
     const pageNum = pageItem.pageNumber;
     const base64Data = pageItem.dataUrl.replace(/^data:image\/png;base64,/, "");
     const buffer = Buffer.from(base64Data, "base64");
@@ -184,12 +219,12 @@ async function renderRemoteBatch(
     });
     pagesSummary.push({
       page: pageNum,
-      imageCount: 0,
-      imageSources: [],
+      imageCount: pageItem.bodyImageCount,
+      imageSources: pageItem.bodyImageSources.map((src, index) => originalImages.get(pageItem.bodyImageIds[index]) || sources.get(src) || src),
     });
   }
 
-  return { assets, pageCount: data.pageCount, pages: pagesSummary };
+  return { assets, pageCount: assets.length, pages: pagesSummary };
 }
 
 // 本地渲染与远程服务共用请求，保留各自的图片输出方式。
@@ -199,6 +234,9 @@ async function renderLocalBatch(
   route: RenderAsset["route"],
   kind: RenderAsset["kind"],
 ): Promise<ImageRenderOutput> {
+  const [{ resolveTypesetResult }, { renderTypesetResultToPngs }] = await Promise.all([
+    import("./server/routes/render"), import("./core/canvas-renderer"),
+  ]);
   const { result } = resolveTypesetResult(body);
   const pngs = await renderTypesetResultToPngs(result);
   const outputs = kind === "cover" ? pngs.slice(0, 1) : pngs;
@@ -216,7 +254,7 @@ async function renderLocalBatch(
     const path = join(outputDir, filename);
     await writeFile(path, output.buffer);
     assets.push({ kind, route, path, ...(kind === "page" ? { index: pageNumber } : {}) });
-    const images = result.pages[index].images;
+    const images = result.pages[index].images.filter((image) => !image.templateAssetKey);
     pages.push({
       page: pageNumber,
       imageCount: images.length,
@@ -228,19 +266,23 @@ async function renderLocalBatch(
 
 export const typesetStudioAdapter: ImageRenderPlugin = {
   name: "typeset-studio",
-  version: "0.2.2",
+  version: "0.2.4",
 
   async doctor(): Promise<PipelinePluginDoctorCheck[]> {
     const checks: PipelinePluginDoctorCheck[] = [];
 
+    const REMOTE_STUDIO_URL = remoteStudioUrl();
     if (REMOTE_STUDIO_URL) {
       try {
-        const res = await fetch(`${REMOTE_STUDIO_URL}/api/health`);
-        const data = (await res.json()) as { name?: string };
+        const res = await fetch(`${REMOTE_STUDIO_URL}/api/auth/verify`, {
+          method: "POST", headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ key: process.env.TYPESET_ADMIN_KEY || "" }),
+        });
+        const data = (await res.json()) as { ok?: boolean };
         checks.push({
           name: "remote-service",
-          ok: res.ok,
-          message: `Connected to Cloud Typeset Studio at ${REMOTE_STUDIO_URL} (${data.name || "active"})`,
+          ok: res.ok && data.ok === true,
+          message: data.ok ? `Authenticated with Typeset Studio at ${REMOTE_STUDIO_URL}` : "Remote admin key is missing or invalid",
         });
       } catch (err) {
         checks.push({
@@ -273,6 +315,7 @@ export const typesetStudioAdapter: ImageRenderPlugin = {
     }
 
     try {
+      const { scanLocalFonts } = await import("./core/font-loader");
       const localFonts = scanLocalFonts();
       checks.push({
         name: "local-fonts",
@@ -295,15 +338,35 @@ export const typesetStudioAdapter: ImageRenderPlugin = {
     await mkdir(outputDir, { recursive: true });
     if (route === "blog") return { assets: [], pageCount: 0, pages: [] };
 
+    const REMOTE_STUDIO_URL = remoteStudioUrl();
     const account = state.route.account || "default";
+    const saved = state.intent?.newspic_render;
+    const pageSpecs = input.pageSpecs ?? saved?.page_specs?.map((spec) => ({
+      page: spec.page, imageMarkers: spec.image_markers, imageLayout: spec.image_layout, targetFillRatio: spec.target_fill_ratio,
+    }));
+    const visual = input.accountVisualParams || {};
+    const stateVisual = state.route.account_visual_params;
+    const footer = visual.footer ?? stateVisual?.footer;
+    const bg = visual.bg ?? stateVisual?.bg;
+    const highlight = visual.highlight ?? stateVisual?.highlight;
+    const fallbackIcon = visual.fallbackIcon ?? stateVisual?.fallback_icon;
+    // pipeline 的模式标记只选择分页方式，具体模板名才参与模板解析。
+    const template = ["wechat-cover-split", "poster-3-4", "longform-3-4"].includes(input.template || "") ? undefined : input.template;
+    input.onProgress?.({ stage: "typeset", message: "开始排版", route, account });
     const title = cleanTitle(input.title || state.metadata?.title || "");
     const common: RenderRequestBody = {
       account,
       title,
-      template: input.template,
-      images: mapBodyImages(input.bodyImages, input.pageSpecs),
+      preserveTemplateStyle: true,
+      images: mapBodyImages(input.bodyImages, pageSpecs),
       highlightWords: state.route.highlight_words || [],
-      config: { footerText: input.accountVisualParams?.footer, watermarkText: `@${account}` },
+      config: {
+        ...(footer !== undefined ? { footerText: footer } : {}),
+        watermarkText: `@${account}`,
+        ...((bg || highlight) ? { theme: {
+          ...(bg ? { bgColor: bg } : {}), ...(highlight ? { accentColor: highlight } : {}),
+        } } : {}),
+      },
     };
     const articleCover = route === "wechat-article";
     const renderRoute = articleCover ? "wechat-article" : "wechat-newspic";
@@ -314,13 +377,34 @@ export const typesetStudioAdapter: ImageRenderPlugin = {
         ? renderRemoteBatch(REMOTE_STUDIO_URL, body, outputDir, renderRoute, kind)
         : renderLocalBatch(body, outputDir, renderRoute, kind);
 
+    const coverTheme = input.coverTheme;
+    const coverConfig = { ...common.config, algorithm: { targetFillRatio: 1 } };
+    if (coverTheme) {
+      coverConfig.coverTheme = coverTheme;
+      if (footer) coverConfig.chrome = { showHeader: false, showFooter: true, showFooterDivider: false, showFooterText: true };
+      coverConfig.algorithm = { ...coverTheme.layout, targetFillRatio: 1 };
+      coverConfig.theme = {
+        bgColor: coverTheme.background.fill.type === "solid" ? coverTheme.background.fill.color : "transparent",
+        textColor: coverTheme.colors.text, headingColor: coverTheme.colors.text,
+        accentColor: coverTheme.colors.accent, quoteColor: coverTheme.colors.muted,
+        captionColor: coverTheme.colors.muted, watermarkColor: coverTheme.colors.muted,
+      };
+    }
+    const firstPageImages = (common.images || []).filter((image) => !image.pageIndex || image.pageIndex === 1)
+      .map((image) => ({ ...image, pageIndex: 1 }));
+    if (fallbackIcon) coverConfig.images = [{
+      id: "account_icon", src: fallbackIcon, alt: "账号标识", isAbsolute: true,
+      x: 0, y: 0, width: 48, height: 48, zIndex: 20, pageIndex: 1,
+      templateAssetKey: "account_icon",
+    }];
     const cover = await renderBatch({
-      ...common,
-      route: renderRoute,
-      slot: articleCover ? "article_cover" : "newspic_cover",
-      ...(articleCover ? {} : { kind: "cover" }),
-      markdown: `# ${title}`,
+      ...common, config: coverConfig, images: firstPageImages,
+      template: input.studioTemplates?.cover || template,
+      templateImageOverrides: input.templateImageOverrides?.cover,
+      route: renderRoute, slot: articleCover ? "article_cover" : "newspic_cover",
+      kind: "cover", maxPages: 1, markdown: `# ${title}`,
     }, "cover");
+    input.onProgress?.({ stage: "cover", message: "封面已生成", current: 1, total: 1, unit: "pages", route, account });
     const paginationMode = input.template === "longform-3-4"
       ? "multi"
       : input.template === "poster-3-4"
@@ -331,10 +415,17 @@ export const typesetStudioAdapter: ImageRenderPlugin = {
     const content = await renderBatch({
       ...common,
       route: "wechat-newspic",
+      template: input.studioTemplates?.content || template,
+      templateImageOverrides: input.templateImageOverrides?.content,
       kind: "content",
       slot: "newspic_content",
       markdown: bodyText || `# ${title}`,
+      config: { ...common.config, ...(saved?.target_fill_ratio != null ? { algorithm: { targetFillRatio: saved.target_fill_ratio } } : {}) },
+      minPages: input.minPages ?? saved?.min_pages,
+      maxPages: input.maxPages ?? saved?.max_pages,
+      pageFillRatios: Object.fromEntries((pageSpecs || []).filter((spec) => spec.targetFillRatio != null).map((spec) => [spec.page, spec.targetFillRatio!])),
     }, "page");
+    input.onProgress?.({ stage: "content", message: "正文已生成", current: content.pageCount, total: content.pageCount, unit: "pages", route, account });
     return { ...content, assets: [...cover.assets, ...content.assets] };
   },
 };

package/src/core/canvas-draw.ts

@@ -92,6 +92,83 @@ export async function drawPageToContext(
   ctx.fillRect(0, 0, spec.width, spec.height);
   ctx.restore();
 
+  // 主题背景、纹理和装饰图使用整张画布坐标。
+  const coverTheme = config.coverTheme;
+  const drawCoverImage = async (image: NonNullable<typeof coverTheme>["background"]["image"]) => {
+    if (!image) return;
+    const loaded = await getImage(image.src);
+    if (!loaded) throw new Error("Failed to load cover theme image");
+    const scale = image.fit === "contain" ? Math.min(spec.width / loaded.width, spec.height / loaded.height)
+      : Math.max(spec.width / loaded.width, spec.height / loaded.height);
+    const width = image.fit === "fill" ? spec.width : loaded.width * scale;
+    const height = image.fit === "fill" ? spec.height : loaded.height * scale;
+    ctx.save();
+    ctx.globalAlpha = image.opacity;
+    ctx.drawImage(loaded, (spec.width - width) * image.position.x / 100,
+      (spec.height - height) * image.position.y / 100, width, height);
+    ctx.restore();
+  };
+  if (coverTheme) {
+    const fill = coverTheme.background.fill;
+    ctx.save();
+    if (fill.type === "solid") ctx.fillStyle = fill.color;
+    else {
+      let gradient;
+      if (fill.type === "linear") {
+        const angle = fill.angle * Math.PI / 180;
+        const dx = Math.cos(angle) * spec.width / 2;
+        const dy = Math.sin(angle) * spec.height / 2;
+        gradient = ctx.createLinearGradient(spec.width / 2 - dx, spec.height / 2 - dy, spec.width / 2 + dx, spec.height / 2 + dy);
+      } else {
+        const x = spec.width * fill.position.x / 100;
+        const y = spec.height * fill.position.y / 100;
+        gradient = ctx.createRadialGradient(x, y, 0, x, y, Math.hypot(spec.width, spec.height));
+      }
+      for (const stop of fill.stops) gradient.addColorStop(stop.offset / 100, stop.color);
+      ctx.fillStyle = gradient;
+    }
+    ctx.fillRect(0, 0, spec.width, spec.height);
+    ctx.restore();
+    await drawCoverImage(coverTheme.background.image);
+    if (coverTheme.background.overlay) {
+      ctx.save();
+      ctx.fillStyle = coverTheme.background.overlay.color;
+      ctx.globalAlpha = coverTheme.background.overlay.opacity;
+      ctx.fillRect(0, 0, spec.width, spec.height);
+      ctx.restore();
+    }
+    const decoration = coverTheme.decoration;
+    ctx.save();
+    ctx.strokeStyle = ctx.fillStyle = decoration.color;
+    ctx.globalAlpha = decoration.opacity;
+    const size = Math.max(8, decoration.size);
+    ctx.beginPath();
+    if (["lines", "grid", "dots"].includes(decoration.pattern)) {
+      for (let x = 0; x < spec.width; x += size) {
+        if (decoration.pattern === "grid") { ctx.moveTo(x, 0); ctx.lineTo(x, spec.height); }
+        if (decoration.pattern === "dots") {
+          for (let y = 0; y < spec.height; y += size) { ctx.moveTo(x + 2, y); ctx.arc(x, y, 2, 0, Math.PI * 2); }
+        }
+      }
+      if (decoration.pattern !== "dots") {
+        for (let y = 0; y < spec.height; y += size) { ctx.moveTo(0, y); ctx.lineTo(spec.width, y); }
+      }
+    } else if (decoration.pattern === "rings") {
+      for (let radius = size; radius < Math.hypot(spec.width, spec.height); radius += size) {
+        ctx.moveTo(spec.width / 2 + radius, spec.height / 2);
+        ctx.arc(spec.width / 2, spec.height / 2, radius, 0, Math.PI * 2);
+      }
+    } else if (decoration.pattern === "burst") {
+      for (let angle = 0; angle < Math.PI * 2; angle += Math.PI / Math.max(8, Math.round(size / 3))) {
+        ctx.moveTo(spec.width / 2, spec.height / 2);
+        ctx.lineTo(spec.width / 2 + Math.cos(angle) * spec.width, spec.height / 2 + Math.sin(angle) * spec.height);
+      }
+    }
+    if (decoration.pattern === "dots") ctx.fill(); else ctx.stroke();
+    ctx.restore();
+    await drawCoverImage(decoration.image);
+  }
+
   // 2. Compute Stage Layout Dimensions
   const { stageX, stageY } = computeStageDimensions(
     spec,
@@ -154,48 +231,58 @@ export async function drawPageToContext(
     return za - zb;
   });
 
-  for (const img of sortedImages) {
-    const loadedImg = await getImage(img.src);
-    const imgX = stageX + img.x;
-    const imgY = stageY + img.y;
-    const centerX = imgX + img.width / 2;
-    const centerY = imgY + img.height / 2;
+  const drawImages = async (images: typeof sortedImages) => {
+    for (const img of images) {
+      let loadedImg;
+      try {
+        loadedImg = await getImage(img.src);
+      } catch (error) {
+        if (img.templateAssetKey) throw new Error(`模板素材 ${img.templateAssetKey} 加载失败：${error instanceof Error ? error.message : String(error)}`);
+        throw error;
+      }
+      if (!loadedImg && img.templateAssetKey) throw new Error(`模板素材 ${img.templateAssetKey} 加载失败：图片不存在或无法读取`);
+      const imgX = stageX + img.x;
+      const imgY = stageY + img.y;
+      const centerX = imgX + img.width / 2;
+      const centerY = imgY + img.height / 2;
 
-    ctx.save();
-    ctx.translate(centerX, centerY);
-    if (img.rotate) {
-      ctx.rotate((img.rotate * Math.PI) / 180);
-    }
-    ctx.globalAlpha = img.opacity ?? 1;
+      ctx.save();
+      ctx.translate(centerX, centerY);
+      if (img.rotate) {
+        ctx.rotate((img.rotate * Math.PI) / 180);
+      }
+      ctx.globalAlpha = img.opacity ?? 1;
 
-    const w = img.width;
-    const h = img.height;
-    const radius = Math.min(img.borderRadius ?? 12, w / 2, h / 2);
+      const w = img.width;
+      const h = img.height;
+      const radius = Math.min(img.borderRadius ?? 12, w / 2, h / 2);
 
-    ctx.beginPath();
-    ctx.roundRect(-w / 2, -h / 2, w, h, radius);
-    ctx.clip();
-
-    if (loadedImg) {
-      ctx.drawImage(loadedImg, -w / 2, -h / 2, w, h);
-    } else {
-      ctx.fillStyle = theme.cardBg || "#222222";
-      ctx.fillRect(-w / 2, -h / 2, w, h);
-    }
-    ctx.restore();
+      ctx.beginPath();
+      ctx.roundRect(-w / 2, -h / 2, w, h, radius);
+      ctx.clip();
 
-    // Image Caption (e.g., "图 1：建筑结构中的空间秩序感")
-    if (img.caption?.trim()) {
-      ctx.save();
-      const capFontSize = Math.max(14, Math.round(algorithm.baseFontSize * 0.45));
-      ctx.font = resolveCanvasFont(`400 ${capFontSize}px PingFang SC`, isServer);
-      ctx.fillStyle = theme.captionColor;
-      ctx.textBaseline = "top";
-      ctx.textAlign = "center";
-      ctx.fillText(img.caption, centerX, imgY + h + 12);
+      if (loadedImg) {
+        ctx.drawImage(loadedImg, -w / 2, -h / 2, w, h);
+      } else {
+        ctx.fillStyle = theme.cardBg || "#222222";
+        ctx.fillRect(-w / 2, -h / 2, w, h);
+      }
       ctx.restore();
+
+      // Image Caption (e.g., "图 1：建筑结构中的空间秩序感")
+      if (img.caption?.trim()) {
+        ctx.save();
+        const capFontSize = Math.max(14, Math.round(algorithm.baseFontSize * 0.45));
+        ctx.font = resolveCanvasFont(`400 ${capFontSize}px PingFang SC`, isServer);
+        ctx.fillStyle = theme.captionColor;
+        ctx.textBaseline = "top";
+        ctx.textAlign = "center";
+        ctx.fillText(img.caption, centerX, imgY + h + 12);
+        ctx.restore();
+      }
     }
-  }
+  };
+  await drawImages(sortedImages.filter((image) => (image.zIndex ?? (image.isAbsolute ? 20 : 5)) < 10));
 
   // 5. Text Flow Lines & Fragments
   for (const line of page.lines) {
@@ -258,15 +345,20 @@ export async function drawPageToContext(
         ctx.fillStyle = theme.textColor;
       }
 
+      ctx.letterSpacing = `${fragment.letterSpacing || 0}px`;
       ctx.fillText(fragment.text, cursorX, lineY);
 
       // Measure fragment advance precisely with ctx.measureText
       // to ensure zero text overlap regardless of font metrics
-      const measuredWidth = ctx.measureText(fragment.text).width;
+      const measuredWidth = fragment.letterSpacing ? fragment.occupiedWidth : ctx.measureText(fragment.text).width;
       cursorX += measuredWidth + (fragment.gapBefore || 0);
     }
   }
 
+  await drawImages(sortedImages.filter((image) => (image.zIndex ?? (image.isAbsolute ? 20 : 5)) >= 10));
+
+  ctx.letterSpacing = "0px";
+
   // 6. Footer Section
   const showFooter = chrome?.showFooter ?? !isCover;
   const showFooterDivider = chrome?.showFooterDivider ?? (!isCover && Boolean(config.footerText?.trim()));
@@ -286,9 +378,20 @@ export async function drawPageToContext(
       ctx.restore();
     }
 
+    if (chrome?.showFillRatio) {
+      ctx.save();
+      ctx.font = resolveCanvasFont("500 13px PingFang SC", isServer);
+      ctx.fillStyle = theme.captionColor;
+      ctx.textBaseline = "middle";
+      ctx.textAlign = "right";
+      ctx.fillText(`填充率 ${Math.round(page.fillRatio * 100)}%`, spec.width - algorithm.safeArea.right, footerY);
+      ctx.restore();
+    }
     if (showFooterText) {
       ctx.save();
-      ctx.font = resolveCanvasFont('500 13px PingFang SC', isServer);
+      const font = coverTheme?.typography.footer;
+      ctx.font = resolveCanvasFont(font ? `${font.fontWeight} ${font.fontSize}px "${font.fontFamily}"` : '500 13px PingFang SC', isServer);
+      ctx.letterSpacing = `${font?.letterSpacing || 0}px`;
       ctx.fillStyle = theme.watermarkColor || theme.captionColor;
       ctx.globalAlpha = 0.6;
       ctx.textBaseline = "middle";