@akairos/typeset-studio 0.2.1 → 0.2.3

package/src/core/canvas-draw.ts

@@ -12,16 +12,16 @@ export function resolveCanvasFontFamily(fontName: string, isServer: boolean = fa
   const trimmed = rawFirst.replace(/["'\\]/g, "").trim();
 
   // 1. Explicit font priority matching: The chosen font family MUST come first
-  if (trimmed.includes("Noto Sans") || trimmed === "Noto Sans SC") {
+  if (trimmed.includes("Noto Sans")) {
     return isServer ? '"Hiragino Sans GB", sans-serif' : '"Noto Sans SC", "PingFang SC", sans-serif';
   }
-  if (trimmed.includes("PingFang") || trimmed === "PingFang SC") {
+  if (trimmed.includes("PingFang")) {
     return isServer ? '"Hiragino Sans GB", sans-serif' : '"PingFang SC", "Noto Sans SC", sans-serif';
   }
-  if (trimmed.includes("Noto Serif") || trimmed === "Noto Serif SC") {
+  if (trimmed.includes("Noto Serif")) {
     return isServer ? '"Songti SC", serif' : '"Noto Serif SC", "Songti SC", serif';
   }
-  if (trimmed.includes("Songti") || trimmed === "Songti SC" || trimmed === "STSong") {
+  if (trimmed.includes("Songti") || trimmed === "STSong") {
     return isServer ? '"Songti SC", serif' : '"Songti SC", "Noto Serif SC", serif';
   }
   if (trimmed.includes("Kai") || trimmed.includes("WenKai")) {
@@ -29,7 +29,7 @@ export function resolveCanvasFontFamily(fontName: string, isServer: boolean = fa
       ? '"STKaiti", "Kaiti SC", "Songti SC", serif'
       : '"LXGW WenKai GB Screen", "LXGW WenKai Screen", "Kaiti SC", "STKaiti", serif';
   }
-  if (trimmed.includes("Yuan") || trimmed.includes("Yuanti")) {
+  if (trimmed.includes("Yuan")) {
     return isServer
       ? '"STYuanti", "Yuanti SC", "Hiragino Sans GB", sans-serif'
       : '"Yuanti SC", "STYuanti", "PingFang SC", sans-serif';
@@ -43,7 +43,7 @@ export function resolveCanvasFontFamily(fontName: string, isServer: boolean = fa
 
   // 2. Generic fallbacks (including custom and project-local fonts)
   if (trimmed.toLowerCase().includes("serif") || trimmed.includes("Song")) {
-    return isServer ? `"${trimmed}", "Songti SC", serif` : `"${trimmed}", "Songti SC", serif`;
+    return `"${trimmed}", "Songti SC", serif`;
   }
   return isServer
     ? `"${trimmed}", "Hiragino Sans GB", "PingFang SC", sans-serif`
@@ -92,8 +92,85 @@ 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 { stageWidth, stageHeight, stageX, stageY } = computeStageDimensions(
+  const { stageX, stageY } = computeStageDimensions(
     spec,
     algorithm.safeArea,
     algorithm.contentBottomGap,
@@ -111,7 +188,7 @@ export async function drawPageToContext(
     // Keep header bar in safe upper margin, safely above stageY
     const headerY = Math.max(24, Math.floor(algorithm.safeArea.top * 0.45));
 
-    if (showWatermark && config.watermarkText?.trim()) {
+    if (showWatermark) {
       ctx.save();
       ctx.font = resolveCanvasFont("600 14px PingFang SC", isServer);
       ctx.fillStyle = theme.watermarkColor;
@@ -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 (showFooterText && config.footerText?.trim()) {
+    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";

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

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "bun:test";
 import { getDefaultConfig, runTypeset } from "./engine";
 import { renderPageToPng, renderTypesetResultToPngs } from "./canvas-renderer";
+import type { PipelineCoverTheme } from "./types";
 
 describe("Server-Side Canvas Native PNG Renderer", () => {
   it("renders a single 2.35:1 WeChat cover page to a valid PNG buffer", async () => {
@@ -47,3 +48,60 @@ describe("Server-Side Canvas Native PNG Renderer", () => {
     expect(pngs[1]!.buffer.length).toBeGreaterThan(1000);
   });
 });
+
+// 绘制顺序必须跨越文字层，页脚开关需要产生真实输出。
+describe("Canvas layer regressions", () => {
+  it("draws background images, text and foreground images in order", async () => {
+    const { drawPageToContext } = await import("./canvas-draw");
+    const config = getDefaultConfig();
+    const result = runTypeset({ markdown: "正文", config });
+    const page = result.pages[0];
+    page.images = [
+      { id: "front", src: "front", alt: "", x: 0, y: 0, width: 20, height: 20, isAbsolute: true },
+      { id: "back", src: "back", alt: "", x: 0, y: 0, width: 20, height: 20, zIndex: 0 },
+    ];
+    const operations: string[] = [];
+    const context = new Proxy({
+      drawImage: (image: string) => operations.push(image),
+      fillText: (text: string) => operations.push(text),
+      measureText: () => ({ width: 20 }),
+    } as any, { get: (target, key) => key in target ? target[key] : () => {} });
+    config.chrome = { showHeader: false, showFooter: true, showFillRatio: true, showFooterText: false };
+    await drawPageToContext(context, { page, spec: result.canvasSpec, config, getImage: async (src) => src });
+    expect(operations[0]).toBe("back");
+    expect(operations[1]).toBe("正文");
+    expect(operations[2]).toBe("front");
+    expect(operations[3]).toContain("填充率");
+  });
+});
+
+it("renders pipeline cover theme gradients, decoration, typography and minimum font size", async () => {
+  const { resolveTypesetResult } = await import("../server/routes/render");
+  const { createCanvas } = await import("@napi-rs/canvas");
+  const font = { fontFamily: "Songti SC", fontSize: 112, minFontSize: 36, fontWeight: 700, lineHeight: 1.3, letterSpacing: 2 };
+  const coverTheme: PipelineCoverTheme = {
+    id: "test", format: "poster-3-4",
+    typography: { title: font, subtitle: font, footer: { ...font, fontSize: 24 } },
+    colors: { text: "#171717", accent: "#059669", muted: "#666666" },
+    background: { fill: { type: "solid", color: "#ffffff" }, image: null, overlay: null },
+    decoration: { pattern: "none", color: "#059669", opacity: 0.1, size: 64, image: null },
+    layout: { textAlign: "center", verticalAlign: "center", safeArea: { top: 90, right: 84, bottom: 64, left: 84 } },
+  };
+  coverTheme.background.fill = { type: "linear", angle: 45, stops: [{ color: "#112233", offset: 0 }, { color: "#334455", offset: 100 }] };
+  coverTheme.decoration.pattern = "grid";
+  const image = `data:image/png;base64,${createCanvas(5, 5).toBuffer("image/png").toString("base64")}`;
+  coverTheme.decoration.image = { src: image, fit: "contain", opacity: 0.3, position: { x: 50, y: 50 } };
+  const { result } = resolveTypesetResult({
+    kind: "cover", slot: "newspic_cover", maxPages: 1, markdown: "# 封面主题测试",
+    config: { coverTheme, algorithm: { ...coverTheme.layout, targetFillRatio: 1 } },
+  });
+  expect(result.pages[0].lines[0].font).toContain(coverTheme.typography.title.fontFamily);
+  const buffer = await renderPageToPng(result.pages[0], result.canvasSpec, result.config, result.pageCount);
+  expect(buffer.length).toBeGreaterThan(1000);
+  const smallArea = resolveTypesetResult({
+    kind: "cover", slot: "newspic_cover", maxPages: 1, markdown: "# 封面主题测试",
+    config: { coverTheme, algorithm: { safeArea: { top: 600, bottom: 700, left: 84, right: 84 }, targetFillRatio: 1 } },
+  }).result;
+  expect(smallArea.config.coverTheme!.typography.title.fontSize).toBeLessThan(font.fontSize);
+  expect(smallArea.config.coverTheme!.typography.title.fontSize).toBeGreaterThanOrEqual(font.minFontSize);
+});

package/src/core/canvas-renderer.ts

@@ -2,6 +2,7 @@ import { createCanvas, loadImage, type Canvas } from "@napi-rs/canvas";
 import { existsSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { drawPageToContext } from "./canvas-draw";
+import { resolveDataDir } from "./data-dir";
 import { registerServerFonts } from "./font-loader";
 import { CanvasSpec, FlowPage, TypesetConfig, TypesetResult } from "./types";
 
@@ -18,7 +19,7 @@ async function safeLoadImage(src: string): Promise<any | null> {
   if (!src) return null;
   try {
     if (src.startsWith("/uploads/") || src.startsWith("uploads/")) {
-      const localPath = join(process.cwd(), "data", src.replace(/^\//, ""));
+      const localPath = join(resolveDataDir(), src.replace(/^\//, ""));
       if (existsSync(localPath)) {
         return await loadImage(localPath);
       }

package/src/core/data-dir.ts

@@ -0,0 +1,13 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// 源码和安装包共用同一数据根目录，环境变量优先。
+export function resolveDataDir(): string {
+  if (process.env.TYPESET_DATA_DIR) return resolve(process.env.TYPESET_DATA_DIR);
+  const moduleDir = dirname(fileURLToPath(import.meta.url));
+  const packageData = resolve(moduleDir, "../../data");
+  if (existsSync(packageData)) return packageData;
+  const cwdData = resolve(process.cwd(), "data");
+  return existsSync(cwdData) ? cwdData : packageData;
+}

package/src/core/engine.ts

@@ -3,8 +3,8 @@ import { parseContentBlocks, parseInlineRuns, splitTextByPages } from "./inline-
 import { paginateBlocks } from "./obstacle-flow";
 import { computeBlockStyles } from "./typography";
 import { resolveImagePlacement } from "./image-layout";
+import { validateTemplateAssets } from "./template";
 import {
-  ContentBlock,
   FlowBlock,
   FlowImage,
   FlowPage,
@@ -12,7 +12,7 @@ import {
   TypesetResult,
 } from "./types";
 
-export function getDefaultConfig(aspectRatio = "longform-3-4" as TypesetConfig["aspectRatio"]): TypesetConfig {
+export function getDefaultConfig(aspectRatio: TypesetConfig["aspectRatio"] = "longform-3-4"): TypesetConfig {
   const spec = getCanvasSpec(aspectRatio);
   const isCover = aspectRatio === "wechat-cover-2.35";
   const isSquare = aspectRatio === "square-1-1";
@@ -77,8 +77,18 @@ export function runTypeset(params: {
   images?: FlowImage[];
   config: TypesetConfig;
   highlightWords?: string[];
+  minPages?: number;
+  maxPages?: number;
+  pageFillRatios?: Record<number, number>;
 }): TypesetResult {
-  const { markdown, images = [], config, highlightWords = [] } = params;
+  const { markdown, images = [], config, highlightWords = [], minPages = 1, maxPages = 0, pageFillRatios } = params;
+  if (!Number.isInteger(minPages) || minPages < 1 || !Number.isInteger(maxPages) || maxPages < 0 || (maxPages > 0 && maxPages < minPages)) {
+    throw new RangeError("Invalid page constraints: maxPages must be 0 or at least minPages");
+  }
+  validateTemplateAssets(images);
+  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");
+  }
   const spec = getCanvasSpec(config.aspectRatio);
   const { stageWidth, stageHeight } = computeStageDimensions(
     spec,
@@ -94,85 +104,105 @@ export function runTypeset(params: {
     bodyFont: config.typography.bodyFont,
   });
 
+  if (config.coverTheme) {
+    const fonts = config.coverTheme.typography;
+    for (const [kind, style] of Object.entries(blockStyles)) {
+      const font = kind.includes("heading") ? fonts.title : fonts.subtitle;
+      Object.assign(style, {
+        font: `${font.fontWeight} ${font.fontSize}px "${font.fontFamily}"`,
+        lineHeight: Math.round(font.fontSize * font.lineHeight),
+      });
+    }
+  }
+
+  // 自动分页和手动分页共用相同的文字块样式。
+  const createFlowBlocks = (text: string): FlowBlock[] => parseContentBlocks(text).map((block) => ({
+    ...blockStyles[block.kind],
+    kind: block.kind,
+    text: block.text,
+    runs: parseInlineRuns(block.text, highlightWords).map((run) => ({
+      ...run, letterSpacing: config.coverTheme?.typography[block.kind.includes("heading") ? "title" : "subtitle"].letterSpacing,
+    })),
+    bullet: block.kind === "list-item" ? block.bullet ?? "•" : undefined,
+    textIndent: block.kind === "list-item" ? 28 : block.kind === "quote" ? 20 : 0,
+    keepWithNext: ["heading", "subheading", "minor-heading"].includes(block.kind),
+  }));
+
+  const templateImages = images.filter((image) => image.templateAssetKey);
+  const contentImages = images.filter((image) => !image.templateAssetKey);
+
   // Check if explicit page markers exist
   const pageSegments = splitTextByPages(markdown);
   let pages: FlowPage[] = [];
 
   if (pageSegments.length > 1) {
-    // Multi-page explicit segmentation
-    pages = pageSegments.map((segmentText, index) => {
-      const pageNum = index + 1;
-      const rawBlocks = parseContentBlocks(segmentText);
-      const flowBlocks: FlowBlock[] = rawBlocks.map((b) => ({
-        ...blockStyles[b.kind],
-        kind: b.kind,
-        text: b.text,
-        runs: parseInlineRuns(b.text, highlightWords),
-        bullet: b.kind === "list-item" ? b.bullet ?? "•" : undefined,
-        textIndent: b.kind === "list-item" ? 28 : b.kind === "quote" ? 20 : 0,
-        keepWithNext: ["heading", "subheading", "minor-heading"].includes(b.kind),
-      }));
-
-      // Match images explicitly configured for this page (img.pageIndex === pageNum).
-      // If an image has no pageIndex, fallback to Page 1 (index === 0).
-      const pageImages = images.filter((img) => {
-        if (img.pageIndex !== undefined && img.pageIndex !== null && img.pageIndex > 0) {
-          return img.pageIndex === pageNum;
-        }
-        return index === 0;
-      });
-
-      const subPages = paginateBlocks(flowBlocks, stageWidth, stageHeight, pageImages, {
+    // 手动段落溢出继续分页，图片仍归属原始段落，最终页码连续。
+    const segmentCount = Math.max(pageSegments.length, ...contentImages.map((image) => image.pageIndex || 1));
+    if (segmentCount > 50) throw new RangeError("Content exceeds engine limit of 50 pages");
+    for (let index = 0; index < segmentCount; index++) {
+      const pageImages = contentImages.filter((image) => (image.pageIndex || 1) === index + 1);
+      const subPages = paginateBlocks(createFlowBlocks(pageSegments[index] || ""), stageWidth, stageHeight, pageImages, {
         obstacleGap: config.algorithm.obstacleGap,
         pageImageLimit: 2,
         textAlign: config.algorithm.textAlign,
         verticalAlign: config.algorithm.verticalAlign,
-        initialPageNumber: pageNum,
+        initialPageNumber: pages.length + 1,
+        templateImages,
+        targetFillRatio: pageFillRatios?.[index + 1] ?? config.algorithm.targetFillRatio,
       });
-
-      const firstSubPage = subPages[0] ?? {
-        pageNumber: pageNum,
-        lines: [],
-        images: pageImages.map((img, idx) =>
-          resolveImagePlacement(img, idx, stageWidth, stageHeight),
-        ),
-        textBottom: 0,
-        fillRatio: 0,
-      };
-
-      return {
-        ...firstSubPage,
-        pageNumber: pageNum,
-      };
-    });
+      pages.push(...(subPages.length ? subPages : [{
+        pageNumber: pages.length + 1, lines: [], images: [], textBottom: 0, fillRatio: 0,
+      }]));
+    }
+    const lastTemplatePage = Math.max(0, ...templateImages.filter((image) => !image.repeatEveryPage).map((image) => image.pageIndex || 1));
+    if (pages.length < lastTemplatePage) {
+      pages.push(...paginateBlocks([], stageWidth, stageHeight, [], {
+        initialPageNumber: pages.length + 1, lastPageNumber: lastTemplatePage, templateImages,
+      }));
+    }
   } else {
     // Single page or auto-flowing pagination
-    const rawBlocks = parseContentBlocks(markdown);
-    const flowBlocks: FlowBlock[] = rawBlocks.map((b) => ({
-      ...blockStyles[b.kind],
-      kind: b.kind,
-      text: b.text,
-      runs: parseInlineRuns(b.text, highlightWords),
-      bullet: b.kind === "list-item" ? b.bullet ?? "•" : undefined,
-      textIndent: b.kind === "list-item" ? 28 : b.kind === "quote" ? 20 : 0,
-      keepWithNext: ["heading", "subheading", "minor-heading"].includes(b.kind),
-    }));
+    const flowBlocks = createFlowBlocks(markdown);
 
-    pages = paginateBlocks(flowBlocks, stageWidth, stageHeight, images, {
+    pages = paginateBlocks(flowBlocks, stageWidth, stageHeight, contentImages, {
       obstacleGap: config.algorithm.obstacleGap,
       pageImageLimit: config.aspectRatio === "longform-3-4" ? 2 : 1,
       textAlign: config.algorithm.textAlign,
       verticalAlign: config.algorithm.verticalAlign,
+      targetFillRatio: config.algorithm.targetFillRatio,
+      pageFillRatios,
+      templateImages,
     });
   }
 
+  // 少页约束通过缩短每页文字区分配正文，无法分配时明确报错。
+  if (pageSegments.length === 1 && pages.length < minPages && markdown.trim()) {
+    for (let attempt = 1; attempt <= 8 && pages.length < minPages; attempt++) {
+      const ratio = config.algorithm.targetFillRatio * Math.pow(0.75, attempt);
+      try {
+        pages = paginateBlocks(createFlowBlocks(markdown), stageWidth, stageHeight, contentImages, {
+          obstacleGap: config.algorithm.obstacleGap,
+          pageImageLimit: config.aspectRatio === "longform-3-4" ? 2 : 1,
+          textAlign: config.algorithm.textAlign,
+          verticalAlign: config.algorithm.verticalAlign,
+          targetFillRatio: ratio,
+          templateImages,
+          pageFillRatios: pageFillRatios && Object.fromEntries(Object.entries(pageFillRatios).map(([page, fill]) => [page, Math.min(fill, ratio)])),
+        });
+      } catch { break; }
+    }
+  }
+  if (pages.length < minPages && minPages > 1) throw new RangeError(`Content cannot satisfy minPages=${minPages}; lower the minimum page count`);
+  if (pages.length > 50) throw new RangeError("Content exceeds engine limit of 50 pages");
+  if (maxPages > 0 && pages.length > maxPages) throw new RangeError(`Content exceeds maxPages=${maxPages}; no content was discarded`);
+
   // Ensure at least 1 page exists
   if (pages.length === 0) {
     pages = [
       {
         pageNumber: 1,
         lines: [],
-        images: images.map((img, idx) =>
+        images: images.filter((image) => !image.templateAssetKey || image.repeatEveryPage || (image.pageIndex || 1) === 1).map((img, idx) =>
           resolveImagePlacement(img, idx, stageWidth, stageHeight),
         ),
         textBottom: 0,

package/src/core/font-loader.test.ts

@@ -33,6 +33,26 @@ describe("Project-Local Fonts Scanning & Registration", () => {
     expect(Array.isArray(data.fonts)).toBe(true);
   });
 
+  it("decodes Unicode SFNT family records without modifying the source", () => {
+    const family = "测试字体";
+    const name = Buffer.from(family, "utf16le").swap16();
+    const fixture = Buffer.alloc(46 + name.length);
+    fixture.writeUInt32BE(0x10000, 0);
+    fixture.writeUInt16BE(1, 4);
+    fixture.write("name", 12);
+    fixture.writeUInt32BE(28, 20);
+    fixture.writeUInt16BE(1, 30);
+    fixture.writeUInt16BE(18, 32);
+    fixture.writeUInt16BE(3, 34);
+    fixture.writeUInt16BE(16, 40);
+    fixture.writeUInt16BE(name.length, 42);
+    name.copy(fixture, 46);
+    const path = join(isolatedFontsDir, "Unicode.ttf");
+    writeFileSync(path, fixture);
+    expect(readFontFamilyName(path)).toBe(family);
+    expect(readFontFamilyName(path)).toBe(family);
+  });
+
   it("recognizes fonts.json manifest metadata when present", () => {
     const dummyFontPath = join(isolatedFontsDir, "MockCustomFont.ttf");
     const manifestPath = join(isolatedFontsDir, "fonts.json");

package/src/core/font-loader.ts

@@ -1,3 +1,5 @@
+import { clearCache } from "@chenglou/pretext";
+import { createRequire } from "node:module";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, extname, join, resolve } from "node:path";
 
@@ -56,7 +58,8 @@ export function readFontFamilyName(filePath: string): string | null {
       if (nameId === 1 || nameId === 16) {
         let str = "";
         if (platformId === 0 || platformId === 3) {
-          str = buf.toString("utf16be", strOffset, strOffset + length).trim();
+          if (length % 2 !== 0) continue;
+          str = Buffer.from(buf.subarray(strOffset, strOffset + length)).swap16().toString("utf16le").trim();
         } else {
           str = buf.toString("utf8", strOffset, strOffset + length).trim();
         }
@@ -180,7 +183,7 @@ export function registerServerFonts(options?: { refresh?: boolean }): LocalFontI
   }
 
   try {
-    const { GlobalFonts } = require("@napi-rs/canvas");
+    const { GlobalFonts } = createRequire(import.meta.url)("@napi-rs/canvas");
     if (GlobalFonts && typeof GlobalFonts.registerFromPath === "function") {
       for (const font of fonts) {
         try {
@@ -194,6 +197,7 @@ export function registerServerFonts(options?: { refresh?: boolean }): LocalFontI
         }
       }
       registeredServerFonts = true;
+      clearCache();
     }
   } catch {
     // Client-side or @napi-rs/canvas not available

package/src/core/image-layout.ts

@@ -22,6 +22,10 @@ export function resolveImagePlacement(
   stageWidth: number,
   stageHeight: number,
 ): ResolvedFlowImage {
+  // 固定素材沿用模板坐标，普通配图数量变化不能移动它。
+  if (img.templateAssetKey && img.x != null && img.y != null && img.width != null && img.height != null) {
+    return { ...img, x: img.x, y: img.y, width: img.width, height: img.height };
+  }
   const preset = img.layoutPreset || "auto";
   const padding = 16;
   const captionH = img.captionHeight ?? 36;