@akairos/typeset-studio 0.2.5 → 0.2.6

package/src/core/canvas-draw.ts

@@ -1,4 +1,5 @@
 import { computeStageDimensions } from "./geometry";
+import { drawCanvasFill, drawCanvasPattern, drawCanvasBorder, validateCanvasStyle } from "./canvas-style";
 import { CanvasSpec, FlowPage, TypesetConfig } from "./types";
 
 /**
@@ -85,12 +86,14 @@ export async function drawPageToContext(
 ): Promise<void> {
   const { page, spec, config, totalPageCount = 1, getImage, isServer = false } = options;
   const { algorithm, theme, chrome } = config;
+  validateCanvasStyle(config.canvasStyle);
 
   // 1. Clear & Background Fill
   ctx.save();
   ctx.fillStyle = theme.bgColor;
   ctx.fillRect(0, 0, spec.width, spec.height);
   ctx.restore();
+  if (config.canvasStyle?.fill) drawCanvasFill(ctx, spec, config.canvasStyle.fill);
 
   // 主题背景、纹理和装饰图使用整张画布坐标。
   const coverTheme = config.coverTheme;
@@ -109,26 +112,28 @@ export async function drawPageToContext(
     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));
+    if (!config.canvasStyle?.fill) {
+      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;
       }
-      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();
     }
-    ctx.fillRect(0, 0, spec.width, spec.height);
-    ctx.restore();
     await drawCoverImage(coverTheme.background.image);
     if (coverTheme.background.overlay) {
       ctx.save();
@@ -138,37 +143,41 @@ export async function drawPageToContext(
       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 (!config.canvasStyle?.pattern) {
+      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") {
-        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();
     }
-    if (decoration.pattern === "dots") ctx.fill(); else ctx.stroke();
-    ctx.restore();
     await drawCoverImage(decoration.image);
   }
 
+  if (config.canvasStyle?.pattern) drawCanvasPattern(ctx, spec, config.canvasStyle.pattern);
+
   // 2. Compute Stage Layout Dimensions
   const { stageX, stageY } = computeStageDimensions(
     spec,
@@ -400,4 +409,5 @@ export async function drawPageToContext(
       ctx.restore();
     }
   }
+  drawCanvasBorder(ctx, spec, config.canvasStyle?.border);
 }

package/src/core/canvas-presets.ts

@@ -0,0 +1,37 @@
+import { getDefaultConfig } from "./engine";
+import { DEFAULT_BORDER, DEFAULT_PATTERN } from "./canvas-style";
+import type { CanvasFill, CanvasPattern, CanvasBorder, TypesetConfig } from "./types";
+
+// 预设仅使用程序绘制，不依赖图片文件或远程素材。
+const designs: Array<{
+  id: string; name: string; fill: CanvasFill; pattern: CanvasPattern["pattern"];
+  ink: string; accent: string; texture: string; border: CanvasBorder["style"];
+  size: number; opacity: number; font: string;
+}> = [
+  { id: "sage", name: "浅草信笺 · 径向渐变 / 圆点", fill: { type: "radial", position: { x: 15, y: 10 }, stops: [{ color: "#f8f6e8", offset: 0 }, { color: "#d0e5d7", offset: 100 }] }, pattern: "dots", ink: "#243c32", accent: "#47785c", texture: "#47785c", border: "solid", size: 48, opacity: 0.16, font: "Songti SC" },
+  { id: "sunset", name: "落日来信 · 线性渐变 / 波浪", fill: { type: "linear", angle: 70, stops: [{ color: "#fff2d8", offset: 0 }, { color: "#f1c2a2", offset: 55 }, { color: "#df9b91", offset: 100 }] }, pattern: "waves", ink: "#663b32", accent: "#ab503d", texture: "#a55f4c", border: "gradient", size: 88, opacity: 0.12, font: "Kaiti SC" },
+  { id: "blueprint", name: "工程蓝图 · 深蓝渐变 / 网格", fill: { type: "linear", angle: 115, stops: [{ color: "#142f48", offset: 0 }, { color: "#071923", offset: 100 }] }, pattern: "grid", ink: "#e6f1ec", accent: "#a1d7c6", texture: "#91c3d0", border: "corners", size: 56, opacity: 0.12, font: "PingFang SC" },
+  { id: "eclipse", name: "月蚀光场 · 径向渐变 / 圆环", fill: { type: "radial", position: { x: 85, y: 12 }, stops: [{ color: "#53747a", offset: 0 }, { color: "#182e38", offset: 45 }, { color: "#0e1d27", offset: 100 }] }, pattern: "rings", ink: "#f1eddf", accent: "#ddba80", texture: "#e3c899", border: "gradient", size: 92, opacity: 0.10, font: "Songti SC" },
+  { id: "paper", name: "旧纸书页 · 纸张颗粒 / 双线框", fill: { type: "solid", color: "#f2ead8" }, pattern: "grain", ink: "#403b30", accent: "#8a503b", texture: "#6b533e", border: "double", size: 24, opacity: 0.16, font: "Songti SC" },
+  { id: "rose", name: "玫瑰邮笺 · 柔粉渐变 / 斜线", fill: { type: "linear", angle: 120, stops: [{ color: "#fff6ef", offset: 0 }, { color: "#efd6d4", offset: 100 }] }, pattern: "diagonal", ink: "#583f45", accent: "#9f5f68", texture: "#ae777a", border: "dashed", size: 64, opacity: 0.10, font: "Kaiti SC" },
+  { id: "checker", name: "黄油棋盘 · 奶油底色 / 棋盘格", fill: { type: "solid", color: "#faf2d9" }, pattern: "checker", ink: "#3c4937", accent: "#66784c", texture: "#b5bb89", border: "solid", size: 104, opacity: 0.10, font: "PingFang SC" },
+  { id: "burst", name: "日光放射 · 暖黄渐变 / 放射线", fill: { type: "radial", position: { x: 80, y: 20 }, stops: [{ color: "#fff7d1", offset: 0 }, { color: "#e8c982", offset: 100 }] }, pattern: "burst", ink: "#58452b", accent: "#976333", texture: "#aa7739", border: "corners", size: 100, opacity: 0.12, font: "PingFang SC" },
+  { id: "ruled", name: "雾蓝手账 · 浅蓝渐变 / 横线", fill: { type: "linear", angle: 90, stops: [{ color: "#f0f5f4", offset: 0 }, { color: "#d3e3e8", offset: 100 }] }, pattern: "lines", ink: "#304d5b", accent: "#4b7484", texture: "#7294a3", border: "double", size: 64, opacity: 0.14, font: "Kaiti SC" },
+];
+
+export const CANVAS_PRESETS: TypesetConfig[] = designs.map((design) => {
+  const base = getDefaultConfig("longform-3-4");
+  return {
+    ...base, id: `tpl_canvas_${design.id}`, name: design.name, slot: "newspic_content", images: [],
+    algorithm: { ...base.algorithm, baseFontSize: 42, scaleRatio: 1.3, targetFillRatio: 0.83,
+      safeArea: { top: 126, right: 108, bottom: 110, left: 108 } },
+    typography: { headingFont: design.font, bodyFont: design.font },
+    theme: { ...base.theme, bgColor: design.fill.type === "solid" ? design.fill.color : design.fill.stops[0].color,
+      textColor: design.ink, headingColor: design.ink, accentColor: design.accent, quoteColor: design.accent,
+      captionColor: design.accent, watermarkColor: design.accent },
+    chrome: { ...base.chrome, showHeader: false, showFooter: false }, footerText: "", watermarkText: "",
+    canvasStyle: { fill: design.fill,
+      pattern: { ...DEFAULT_PATTERN, pattern: design.pattern, color: design.texture, size: design.size, opacity: design.opacity },
+      border: { ...DEFAULT_BORDER, style: design.border, color: design.accent, endColor: design.texture, width: 2, inset: 38, radius: design.id === "paper" ? 0 : 22, opacity: 0.65 } },
+  };
+});

package/src/core/canvas-renderer.test.ts

@@ -105,3 +105,59 @@ it("renders pipeline cover theme gradients, decoration, typography and minimum f
   expect(smallArea.config.coverTheme!.typography.title.fontSize).toBeLessThan(font.fontSize);
   expect(smallArea.config.coverTheme!.typography.title.fontSize).toBeGreaterThanOrEqual(font.minFontSize);
 });
+
+// 实际像素校验渐变、花纹、边框以及重复渲染的确定性。
+describe("Canvas backgrounds and borders", () => {
+  it("draws editable fills, every pattern and every border deterministically", async () => {
+    const { createCanvas } = await import("@napi-rs/canvas");
+    const { drawCanvasFill, drawCanvasPattern, drawCanvasBorder, validateCanvasStyle, DEFAULT_PATTERN, DEFAULT_BORDER, PATTERN_LABELS, BORDER_LABELS } = await import("./canvas-style");
+    const spec = { ...runTypeset({ markdown: "", config: getDefaultConfig() }).canvasSpec, width: 120, height: 160 };
+    const canvas = createCanvas(spec.width, spec.height);
+    const ctx = canvas.getContext("2d");
+    const reset = () => { ctx.fillStyle = "#ffffff"; ctx.fillRect(0, 0, spec.width, spec.height); };
+    const pixel = (x: number, y: number) => Array.from(ctx.getImageData(x, y, 1, 1).data);
+    const changedPixels = () => Array.from(ctx.getImageData(0, 0, spec.width, spec.height).data).filter((value, index) => index % 4 !== 3 && value !== 255).length;
+    drawCanvasFill(ctx as any, spec, { type: "linear", angle: 0, stops: [{ color: "#ff0000", offset: 0 }, { color: "#0000ff", offset: 100 }] });
+    expect(pixel(0, 80)[0]).toBeGreaterThan(250);
+    expect(pixel(119, 80)[2]).toBeGreaterThan(250);
+    drawCanvasFill(ctx as any, spec, { type: "radial", position: { x: 0, y: 0 }, stops: [{ color: "#ffffff", offset: 0 }, { color: "#000000", offset: 100 }] });
+    expect(pixel(0, 0)[0]).toBeGreaterThan(pixel(119, 159)[0] + 200);
+    for (const pattern of Object.keys(PATTERN_LABELS) as Array<keyof typeof PATTERN_LABELS>) {
+      reset();
+      drawCanvasPattern(ctx as any, spec, { ...DEFAULT_PATTERN, pattern, color: "#123456", opacity: 1, size: 24 });
+      expect(changedPixels() > 0).toBe(pattern !== "none");
+      const first = canvas.toBuffer("image/png");
+      reset();
+      drawCanvasPattern(ctx as any, spec, { ...DEFAULT_PATTERN, pattern, color: "#123456", opacity: 1, size: 24 });
+      expect(first.equals(canvas.toBuffer("image/png"))).toBe(true);
+    }
+    for (const style of Object.keys(BORDER_LABELS) as Array<keyof typeof BORDER_LABELS>) {
+      reset();
+      drawCanvasBorder(ctx as any, spec, { ...DEFAULT_BORDER, style, inset: 10, width: 2, color: "#123456" });
+      expect(changedPixels() > 0).toBe(style !== "none");
+    }
+    expect(() => validateCanvasStyle({ pattern: { ...DEFAULT_PATTERN, size: 0 } })).toThrow(RangeError);
+    expect(() => validateCanvasStyle({ fill: { type: "linear", angle: 0, stops: [{ color: "bad", offset: 0 }, { color: "#000000", offset: 100 }] } })).toThrow(RangeError);
+  });
+
+  it("renders all preset templates and retains borders above a fixed image", async () => {
+    const { CANVAS_PRESETS } = await import("./canvas-presets");
+    const { validateCanvasStyle } = await import("./canvas-style");
+    const { createCanvas } = await import("@napi-rs/canvas");
+    const { renderPageToCanvas } = await import("./canvas-renderer");
+    for (const config of CANVAS_PRESETS) {
+      validateCanvasStyle(config.canvasStyle);
+      const result = runTypeset({ markdown: "# 模板试色\n记录想法，让文字留在喜欢的背景上。", config });
+      expect(result.pageCount).toBe(1);
+      const png = await renderPageToPng(result.pages[0], result.canvasSpec, config);
+      expect(png.length).toBeGreaterThan(1000);
+    }
+    const white = createCanvas(10, 10);
+    white.getContext("2d").fillStyle = "#ffffff";
+    white.getContext("2d").fillRect(0, 0, 10, 10);
+    const config = { ...getDefaultConfig(), canvasStyle: { border: { style: "solid" as const, color: "#ff0000", endColor: "#ff0000", inset: 20, width: 8, radius: 0, opacity: 1 } } };
+    const result = runTypeset({ markdown: "正文", config, images: [{ id: "bg", src: `data:image/png;base64,${white.toBuffer("image/png").toString("base64")}`, alt: "", isAbsolute: true, zIndex: 0, x: -100, y: -100, width: 2000, height: 2000, templateAssetKey: "background" }] });
+    const canvas = await renderPageToCanvas(result.pages[0], result.canvasSpec, config);
+    expect(Array.from(canvas.getContext("2d").getImageData(24, 300, 1, 1).data)).toEqual([255, 0, 0, 255]);
+  });
+});

package/src/core/canvas-style.ts

@@ -0,0 +1,149 @@
+import type { CanvasBorder, CanvasFill, CanvasPattern, CanvasSpec, CanvasStyle } from "./types";
+
+export const DEFAULT_PATTERN: CanvasPattern = { pattern: "none", color: "#527561", opacity: 0.12, size: 56 };
+export const DEFAULT_BORDER: CanvasBorder = { style: "none", color: "#527561", endColor: "#d7ad72", width: 3, inset: 32, radius: 24, opacity: 0.8 };
+export const PATTERN_LABELS: Record<CanvasPattern["pattern"], string> = {
+  none: "无花纹", lines: "横线", grid: "网格", dots: "圆点", diagonal: "斜线", waves: "波浪",
+  rings: "同心圆", burst: "放射线", checker: "棋盘格", grain: "纸张颗粒",
+};
+export const BORDER_LABELS: Record<CanvasBorder["style"], string> = {
+  none: "无边框", solid: "实线", dashed: "虚线", double: "双线", corners: "四角装饰", gradient: "渐变描边",
+};
+
+// 限制颜色和密度，避免无效配置或过密花纹拖慢渲染。
+export function validateCanvasStyle(style?: CanvasStyle): void {
+  if (style === undefined) return;
+  if (!style || typeof style !== "object" || Array.isArray(style)) throw new RangeError("无效的背景与边框配置");
+  const color = (value: string) => { if (typeof value !== "string" || !/^#[0-9a-f]{6}$/i.test(value)) throw new RangeError("背景装饰颜色必须是六位十六进制颜色"); };
+  const number = (value: number, min: number, max: number) => { if (!Number.isFinite(value) || value < min || value > max) throw new RangeError(`背景装饰参数必须在 ${min} 到 ${max} 之间`); };
+  if (style.fill) {
+    const fill = style.fill;
+    if (fill.type === "solid") color(fill.color);
+    else {
+      if (fill.type === "linear") number(fill.angle, 0, 360);
+      else if (fill.type === "radial") { number(fill.position?.x, 0, 100); number(fill.position?.y, 0, 100); }
+      else throw new RangeError("未知背景类型");
+      if (!Array.isArray(fill.stops) || fill.stops.length < 2 || fill.stops.length > 8) throw new RangeError("渐变需要 2 到 8 个颜色节点");
+      for (const stop of fill.stops) { if (!stop) throw new RangeError("无效的渐变节点"); color(stop.color); number(stop.offset, 0, 100); }
+    }
+  }
+  if (style.pattern) {
+    const pattern = style.pattern;
+    if (!Object.hasOwn(PATTERN_LABELS, pattern.pattern)) throw new RangeError("未知背景花纹");
+    color(pattern.color); number(pattern.opacity, 0, 1); number(pattern.size, 16, 240);
+  }
+  if (style.border) {
+    const border = style.border;
+    if (!Object.hasOwn(BORDER_LABELS, border.style)) throw new RangeError("未知边框样式");
+    color(border.color); color(border.endColor); number(border.width, 1, 24);
+    number(border.inset, 0, 200); number(border.radius, 0, 200); number(border.opacity, 0, 1);
+  }
+}
+
+// 浏览器与 Skia 使用同一组 Canvas 2D 指令。
+export function drawCanvasFill(ctx: CanvasRenderingContext2D, spec: CanvasSpec, fill: CanvasFill): void {
+  ctx.save();
+  if (fill.type === "solid") ctx.fillStyle = fill.color;
+  else {
+    let gradient: CanvasGradient;
+    if (fill.type === "linear") {
+      const angle = fill.angle * Math.PI / 180;
+      const distance = Math.abs(Math.cos(angle)) * spec.width / 2 + Math.abs(Math.sin(angle)) * spec.height / 2;
+      const dx = Math.cos(angle) * distance;
+      const dy = Math.sin(angle) * distance;
+      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;
+      const radius = Math.hypot(Math.max(x, spec.width - x), Math.max(y, spec.height - y));
+      gradient = ctx.createRadialGradient(x, y, 0, x, y, radius);
+    }
+    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();
+}
+
+// 颗粒使用固定种子，重复导出和远程出图保持一致。
+export function drawCanvasPattern(ctx: CanvasRenderingContext2D, spec: CanvasSpec, decoration: CanvasPattern): void {
+  if (decoration.pattern === "none" || decoration.opacity === 0) return;
+  const { width, height } = spec;
+  const size = Math.max(16, decoration.size);
+  ctx.save();
+  ctx.strokeStyle = ctx.fillStyle = decoration.color;
+  ctx.globalAlpha = decoration.opacity;
+  ctx.lineWidth = 1.5;
+  ctx.beginPath();
+  switch (decoration.pattern) {
+    case "grid":
+    case "lines":
+      if (decoration.pattern === "grid") for (let x = size / 2; x < width; x += size) { ctx.moveTo(x, 0); ctx.lineTo(x, height); }
+      for (let y = size / 2; y < height; y += size) { ctx.moveTo(0, y); ctx.lineTo(width, y); }
+      break;
+    case "dots":
+      for (let x = size / 2; x < width; x += size) for (let y = size / 2; y < height; y += size) { ctx.moveTo(x + 2, y); ctx.arc(x, y, 2, 0, Math.PI * 2); }
+      break;
+    case "diagonal":
+      for (let x = -height; x < width; x += size) { ctx.moveTo(x, 0); ctx.lineTo(x + height, height); }
+      break;
+    case "waves":
+      for (let y = -size; y < height + size; y += size) {
+        ctx.moveTo(0, y);
+        for (let x = 0; x < width; x += size * 2) ctx.bezierCurveTo(x + size * 0.5, y - size * 0.45, x + size * 1.5, y + size * 0.45, x + size * 2, y);
+      }
+      break;
+    case "rings":
+      for (let r = size; r < Math.hypot(width, height); r += size) { ctx.moveTo(width * 0.82 + r, height * 0.18); ctx.arc(width * 0.82, height * 0.18, r, 0, Math.PI * 2); }
+      break;
+    case "burst":
+      for (let a = 0; a < Math.PI * 2; a += Math.PI / Math.max(8, Math.round(size / 3))) {
+        ctx.moveTo(width * 0.8, height * 0.2); ctx.lineTo(width * 0.8 + Math.cos(a) * width * 2, height * 0.2 + Math.sin(a) * height * 2);
+      }
+      break;
+    case "checker":
+      for (let x = 0; x < width; x += size) for (let y = 0; y < height; y += size) if ((Math.round(x / size) + Math.round(y / size)) % 2 === 0) ctx.rect(x, y, size, size);
+      break;
+    case "grain": {
+      let seed = 42;
+      const random = () => { seed = (Math.imul(seed, 1664525) + 1013904223) >>> 0; return seed / 4294967296; };
+      for (let i = 0; i < width * height / (size * 3); i++) { const x = random() * width; const y = random() * height; ctx.rect(x, y, 0.6 + random() * 1.2, 0.6 + random() * 1.2); }
+      break;
+    }
+  }
+  if (["dots", "checker", "grain"].includes(decoration.pattern)) ctx.fill(); else ctx.stroke();
+  ctx.restore();
+}
+
+// 边框最后绘制，固定背景图不会将边框盖住。
+export function drawCanvasBorder(ctx: CanvasRenderingContext2D, spec: CanvasSpec, border?: CanvasBorder): void {
+  if (!border || border.style === "none" || border.opacity === 0) return;
+  const inset = Math.min(border.inset + border.width / 2, Math.min(spec.width, spec.height) / 2 - 1);
+  const width = spec.width - inset * 2;
+  const height = spec.height - inset * 2;
+  ctx.save();
+  ctx.globalAlpha = border.opacity;
+  ctx.lineWidth = border.width;
+  ctx.strokeStyle = border.color;
+  if (border.style === "gradient") {
+    const gradient = ctx.createLinearGradient(0, 0, spec.width, spec.height);
+    gradient.addColorStop(0, border.color); gradient.addColorStop(1, border.endColor);
+    ctx.strokeStyle = gradient;
+  }
+  if (border.style === "dashed") ctx.setLineDash([border.width * 4, border.width * 3]);
+  const outline = (gap: number) => {
+    ctx.beginPath(); ctx.roundRect(inset + gap, inset + gap, width - gap * 2, height - gap * 2, Math.max(0, border.radius - gap)); ctx.stroke();
+  };
+  if (border.style === "corners") {
+    const length = Math.min(width, height) * 0.12;
+    for (const x of [inset, spec.width - inset]) for (const y of [inset, spec.height - inset]) {
+      const dx = x === inset ? 1 : -1;
+      const dy = y === inset ? 1 : -1;
+      ctx.beginPath(); ctx.moveTo(x + dx * length, y); ctx.lineTo(x, y); ctx.lineTo(x, y + dy * length); ctx.stroke();
+    }
+  } else {
+    outline(0);
+    if (border.style === "double") outline(border.width * 3 + 4);
+  }
+  ctx.restore();
+}

package/src/core/engine.ts

@@ -4,6 +4,7 @@ import { paginateBlocks } from "./obstacle-flow";
 import { computeBlockStyles } from "./typography";
 import { resolveImagePlacement } from "./image-layout";
 import { validateTemplateAssets } from "./template";
+import { validateCanvasStyle } from "./canvas-style";
 import {
   FlowBlock,
   FlowImage,
@@ -86,6 +87,7 @@ export function runTypeset(params: {
     throw new RangeError("Invalid page constraints: maxPages must be 0 or at least minPages");
   }
   validateTemplateAssets(images);
+  validateCanvasStyle(config.canvasStyle);
   if (images.some((image) => !image.repeatEveryPage && image.pageIndex != null && (!Number.isInteger(image.pageIndex) || image.pageIndex < 1 || image.pageIndex > 50))) {
     throw new RangeError("Image pageIndex must be an integer between 1 and 50");
   }

package/src/core/types.ts

@@ -152,6 +152,34 @@ export interface TypesetChromeConfig {
 
 export type TemplateSlot = "article_cover" | "newspic_cover" | "newspic_content";
 
+export type CanvasFill = { type: "solid"; color: string } |
+  { type: "linear"; angle: number; stops: Array<{ color: string; offset: number }> } |
+  { type: "radial"; position: { x: number; y: number }; stops: Array<{ color: string; offset: number }> };
+
+export interface CanvasPattern {
+  pattern: "none" | "lines" | "grid" | "dots" | "rings" | "burst" | "diagonal" | "waves" | "checker" | "grain";
+  color: string;
+  opacity: number;
+  size: number;
+}
+
+export interface CanvasBorder {
+  style: "none" | "solid" | "dashed" | "double" | "corners" | "gradient";
+  color: string;
+  endColor: string;
+  width: number;
+  inset: number;
+  radius: number;
+  opacity: number;
+}
+
+// 背景装饰独立于文字主题，封面和正文模板共用。
+export interface CanvasStyle {
+  fill?: CanvasFill;
+  pattern?: CanvasPattern;
+  border?: CanvasBorder;
+}
+
 export interface TypesetConfig {
   id?: string;
   name: string;
@@ -168,6 +196,7 @@ export interface TypesetConfig {
   chrome?: TypesetChromeConfig;
   images?: FlowImage[];
   coverTheme?: PipelineCoverTheme;
+  canvasStyle?: CanvasStyle;
 }
 
 export interface TypesetResult {
@@ -198,9 +227,7 @@ export interface PipelineCoverTheme {
   typography: { title: CoverFont; subtitle: CoverFont; footer: CoverFont };
   colors: { text: string; accent: string; muted: string };
   background: {
-    fill: { type: "solid"; color: string } |
-      { type: "linear"; angle: number; stops: Array<{ color: string; offset: number }> } |
-      { type: "radial"; position: { x: number; y: number }; stops: Array<{ color: string; offset: number }> };
+    fill: CanvasFill;
     image: CoverImage | null;
     overlay: { color: string; opacity: number } | null;
   };

package/src/index.ts

@@ -33,6 +33,10 @@ export type {
   AlgorithmParams,
   AspectRatioType,
   CanvasSpec,
+  CanvasStyle,
+  CanvasFill,
+  CanvasPattern,
+  CanvasBorder,
   ContentBlockKind,
   CoverFont,
   CoverImage,

package/src/server/index.ts

@@ -17,7 +17,7 @@ app.get("/api/health", (c) => {
   return c.json({
     status: "ok",
     name: "Typeset Studio Server",
-    version: "0.2.5",
+    version: "0.2.6",
     time: new Date().toISOString(),
   });
 });

package/src/server/routes/slots.test.ts

@@ -183,3 +183,25 @@ describe("Fixed asset rendering API", () => {
     }
   });
 });
+
+it("adds Canvas presets once, preserves edits and renders saved colors through the template API", async () => {
+  const { CANVAS_PRESETS } = await import("../../core/canvas-presets");
+  const list = await (await app.request("/api/templates", { headers: authHeaders })).json();
+  for (const preset of CANVAS_PRESETS) expect(list.templates.some((template: { id: string }) => template.id === preset.id)).toBe(true);
+  const preset = CANVAS_PRESETS[0];
+  try {
+    const custom = { ...preset, canvasStyle: { ...preset.canvasStyle, fill: { type: "solid", color: "#123456" } } };
+    expect((await app.request("/api/templates", { method: "POST", headers: authHeaders, body: JSON.stringify(custom) })).status).toBe(200);
+    const loaded = await (await app.request(`/api/templates/${preset.id}`, { headers: authHeaders })).json();
+    expect(loaded.template.canvasStyle.fill.color).toBe("#123456");
+    const rendered = await (await app.request("/api/render", { method: "POST", headers: authHeaders, body: JSON.stringify({ template: preset.id, markdown: "# 自定义背景", preserveTemplateStyle: true, config: { canvasStyle: { fill: { type: "solid", color: "#ffffff" } } } }) })).json();
+    expect(rendered.result.config.canvasStyle.fill.color).toBe("#123456");
+    const invalid = await app.request("/api/templates", { method: "POST", headers: authHeaders, body: JSON.stringify({ ...custom, canvasStyle: { pattern: { pattern: "grid", color: "#123456", opacity: 1, size: 0 } } }) });
+    expect(invalid.status).toBe(400);
+    await app.request(`/api/templates/${preset.id}`, { method: "DELETE", headers: authHeaders });
+    const again = await (await app.request("/api/templates", { headers: authHeaders })).json();
+    expect(again.templates.some((template: { id: string }) => template.id === preset.id)).toBe(false);
+  } finally {
+    await app.request("/api/templates", { method: "POST", headers: authHeaders, body: JSON.stringify(preset) });
+  }
+});

package/src/server/routes/templates.ts

@@ -5,6 +5,8 @@ import { getDefaultConfig } from "../../core/engine";
 import { TemplateSlot, TypesetConfig } from "../../core/types";
 import { resolveDataDir } from "../../core/data-dir";
 import { validateTemplateAssets } from "../../core/template";
+import { validateCanvasStyle } from "../../core/canvas-style";
+import { CANVAS_PRESETS } from "../../core/canvas-presets";
 
 export { resolveDataDir } from "../../core/data-dir";
 
@@ -23,6 +25,17 @@ function ensureTemplatesDir(): void {
     seedDefaultTemplates();
     try { writeFileSync(seedMarker, "1"); } catch { /* 只读安装目录保留读取能力。 */ }
   }
+  // 新预设仅补充一次，不覆盖已编辑模板，也不重新生成用户删除的预设。
+  const canvasMarker = join(TEMPLATES_DIR, ".canvas-presets-v1");
+  if (!existsSync(canvasMarker)) {
+    try {
+      for (const preset of CANVAS_PRESETS) {
+        const path = join(TEMPLATES_DIR, `${preset.id}.json`);
+        if (!existsSync(path)) writeFileSync(path, JSON.stringify(preset, null, 2), "utf-8");
+      }
+      writeFileSync(canvasMarker, "1");
+    } catch { /* 只读安装目录继续使用现有模板。 */ }
+  }
 }
 
 export const BUILTIN_PRESETS: TypesetConfig[] = [
@@ -334,6 +347,7 @@ export const BUILTIN_PRESETS: TypesetConfig[] = [
         showFillRatio: false,
       },
     },
+    ...CANVAS_PRESETS,
   ];
 
 function seedDefaultTemplates(): void {
@@ -611,6 +625,7 @@ templatesRouter.post("/", async (c) => {
 
   try {
     validateTemplateAssets(body.images);
+    validateCanvasStyle(body.canvasStyle);
   } catch (error) {
     return c.json({ ok: false, error: error instanceof Error ? error.message : "无效的模板素材" }, 400);
   }

package/src/web/App.tsx

@@ -4,7 +4,8 @@ import { CanvasViewport } from "./components/CanvasViewport";
 import { EditorSidebar } from "./components/EditorSidebar";
 import { Header } from "./components/Header";
 import { ParamsInspector } from "./components/ParamsInspector";
-import { TemplateModal } from "./components/TemplateModal";
+import { TemplateDrawer } from "./components/TemplateDrawer";
+import { SaveTemplateModal } from "./components/SaveTemplateModal";
 import { useAuth } from "./hooks/useAuth";
 import { useTypeset } from "./hooks/useTypeset";
 
@@ -57,7 +58,9 @@ export const App: React.FC = () => {
   const [viewMode, setViewMode] = useState<"grid" | "stack">("grid");
   const [zoom, setZoom] = useState<number>(0.45);
   const [isAutoFit, setIsAutoFit] = useState<boolean>(true);
-  const [isTemplateModalOpen, setIsTemplateModalOpen] = useState(false);
+  const [isTemplateDrawerOpen, setIsTemplateDrawerOpen] = useState(false);
+  const [isSaveTemplateOpen, setIsSaveTemplateOpen] = useState(false);
+  const [templateRefreshKey, setTemplateRefreshKey] = useState(0);
   const [isAuthModalOpen, setIsAuthModalOpen] = useState(false);
   const [isExporting, setIsExporting] = useState(false);
   const viewportRef = useRef<HTMLDivElement>(null);
@@ -251,7 +254,10 @@ export const App: React.FC = () => {
         onZoomChange={handleZoomChange}
         onAutoFit={handleAutoFit}
         isAutoFit={isAutoFit}
-        onOpenTemplates={() => setIsTemplateModalOpen(true)}
+        onOpenTemplates={() => setIsTemplateDrawerOpen((open) => !open)}
+        isTemplateDrawerOpen={isTemplateDrawerOpen}
+        templateName={config.name}
+        onSaveTemplate={() => setIsSaveTemplateOpen(true)}
         onOpenAuth={() => setIsAuthModalOpen(true)}
         onExport={handleExport}
         isExporting={isExporting}
@@ -300,6 +306,10 @@ export const App: React.FC = () => {
           config={config}
           onUpdateAlgorithm={updateAlgorithm}
           onUpdateTheme={updateTheme}
+          onUpdateCanvasStyle={(canvasStyle) => setConfig((prev) => ({
+            ...prev, canvasStyle,
+            theme: { ...prev.theme, bgColor: canvasStyle.fill?.type === "solid" ? canvasStyle.fill.color : canvasStyle.fill?.stops[0].color || prev.theme.bgColor },
+          }))}
           onUpdateTypography={updateTypography}
           onUpdateSafeArea={updateSafeArea}
           onUpdateBranding={(footer, watermark) => {
@@ -319,17 +329,27 @@ export const App: React.FC = () => {
             }));
           }}
         />
+        <TemplateDrawer
+          isOpen={isTemplateDrawerOpen}
+          onClose={() => setIsTemplateDrawerOpen(false)}
+          refreshKey={templateRefreshKey}
+          onApplyTemplate={loadTemplate}
+          adminKey={adminKey}
+        />
       </div>
 
       {/* Modals */}
-      <TemplateModal
-        isOpen={isTemplateModalOpen}
-        onClose={() => setIsTemplateModalOpen(false)}
+      <SaveTemplateModal
+        isOpen={isSaveTemplateOpen}
+        onClose={() => setIsSaveTemplateOpen(false)}
         currentConfig={{
           ...config,
           images,
         }}
-        onApplyTemplate={loadTemplate}
+        onSaved={(template) => {
+          setConfig((prev) => ({ ...prev, id: template.id, name: template.name, slot: template.slot }));
+          setTemplateRefreshKey((key) => key + 1);
+        }}
         adminKey={adminKey}
       />