@akairos/typeset-studio 0.2.2 → 0.2.4

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,6 +3,7 @@ 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 {
   FlowBlock,
   FlowImage,
@@ -76,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,
@@ -93,78 +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),
+    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 flowBlocks = createFlowBlocks(segmentText);
-
-      // 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 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;

package/src/core/inline-text.ts

@@ -6,6 +6,10 @@ export function normalizeMixedTextSpacing(text: string): string {
 
 export function parseInlineRuns(text: string, highlightWords: string[] = []): InlineTextRun[] {
   const runs: InlineTextRun[] = [];
+  // 空词不能参与正则匹配，否则游标无法前进。
+  const escapedWords = highlightWords.filter((word) => word.length > 0)
+    .map((word) => word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  const hlRegex = escapedWords.length ? new RegExp(`(${escapedWords.join("|")})`, "g") : null;
   // Tokenize markdown bold **text**, italic *text*, highlight ==text==, or matching highlightWords
   // Simple token regex
   const pattern = /(\*\*[^*]+\*\*|\*[^*]+\*|==[^=]+==)/g;
@@ -14,14 +18,12 @@ export function parseInlineRuns(text: string, highlightWords: string[] = []): In
 
   function pushTextWithHighlights(str: string, baseStyle: Partial<InlineTextRun> = {}) {
     if (!str) return;
-    if (highlightWords.length === 0) {
+    if (!hlRegex) {
       runs.push({ text: str, ...baseStyle });
       return;
     }
 
-    // Match any of highlightWords
-    const escapedWords = highlightWords.map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
-    const hlRegex = new RegExp(`(${escapedWords.join("|")})`, "g");
+    hlRegex.lastIndex = 0;
     let hlLast = 0;
     let hlMatch: RegExpExecArray | null;
 

package/src/core/obstacle-flow.ts

@@ -31,6 +31,10 @@ export interface PaginateOptions {
   textAlign?: "left" | "center" | "right";
   verticalAlign?: "top" | "center" | "bottom";
   initialPageNumber?: number;
+  targetFillRatio?: number;
+  pageFillRatios?: Record<number, number>;
+  templateImages?: FlowImage[];
+  lastPageNumber?: number;
 }
 
 /**
@@ -46,6 +50,7 @@ export function paginateBlocks(
 ): FlowPage[] {
   ensurePretextRuntime();
 
+  let textHeight = stageHeight;
   const gap = options.obstacleGap ?? 24;
   const imageLimit = options.pageImageLimit ?? 2;
 
@@ -75,7 +80,7 @@ export function paginateBlocks(
     const lines: PlacedLine[] = [];
     let y = initialY;
 
-    while (y + block.lineHeight <= stageHeight && lines.length < limit) {
+    while (y + block.lineHeight <= textHeight && lines.length < limit) {
       if (!layoutNextRichInlineLineRange(block.prepared, stageWidth, cursor)) {
         return { lines, cursor, y, done: true };
       }
@@ -154,6 +159,7 @@ export function paginateBlocks(
           highlight: originalRun.highlight,
           gapBefore: frag.gapBefore,
           occupiedWidth: frag.occupiedWidth,
+          letterSpacing: originalRun.letterSpacing,
         };
       });
 
@@ -209,16 +215,27 @@ export function paginateBlocks(
   const unassignedImages = allImages.filter((img) => !img.pageIndex);
   let segmentImagesPlaced = false;
 
-  const MAX_PAGES = options.maxPages ?? 50;
+  const MAX_PAGES = options.maxPages || 50;
+  // 固定素材独立选择，不占正文图片配额；重复素材不驱动新分页。
+  const templateImages = options.templateImages || [];
+  const lastTemplatePage = Math.max(0, ...templateImages.filter((image) => !image.repeatEveryPage).map((image) => image.pageIndex || 1));
+  const lastPageNumber = Math.max(options.lastPageNumber || 0, isSegmentMode ? 0 : lastTemplatePage);
+  const templatesForPage = (page: number) => templateImages.filter((image) => image.repeatEveryPage || (image.pageIndex || 1) === page);
+  // 显式图片页之间允许空页，不能提前结束丢图。
+  const lastImagePage = isSegmentMode ? 0 : Math.max(0, ...allImages.map((image) => image.pageIndex || 0));
+  const hasRemaining = () => blockIndex < prepared.length ||
+    (!isSegmentMode && (unassignedIndex < unassignedImages.length || initialPageNumber + pages.length <= lastImagePage)) ||
+    (isSegmentMode && !segmentImagesPlaced && (allImages.length > 0 || templatesForPage(initialPageNumber).length > 0)) ||
+    initialPageNumber + pages.length <= lastPageNumber;
 
   // Pagination loop
-  while (
-    pages.length < MAX_PAGES &&
-    (blockIndex < prepared.length ||
-      (!isSegmentMode && unassignedIndex < unassignedImages.length) ||
-      (isSegmentMode && !segmentImagesPlaced && allImages.length > 0))
-  ) {
+  while (pages.length < MAX_PAGES && hasRemaining()) {
     const pageNum = initialPageNumber + pages.length;
+    const targetFill = options.pageFillRatios?.[pageNum] ?? options.targetFillRatio ?? 1;
+    if (!Number.isFinite(targetFill) || targetFill <= 0 || targetFill > 1) {
+      throw new RangeError("targetFillRatio must be greater than 0 and at most 1");
+    }
+    textHeight = stageHeight * targetFill;
     let targetImages: FlowImage[] = [];
 
     if (isSegmentMode) {
@@ -236,7 +253,7 @@ export function paginateBlocks(
       }
     }
 
-    const images = targetImages.map((img, idx) =>
+    const images = [...targetImages, ...templatesForPage(pageNum)].map((img, idx) =>
       resolveImagePlacement(img, idx, stageWidth, stageHeight),
     );
     const lines: FlowLine[] = [];
@@ -296,15 +313,11 @@ export function paginateBlocks(
     if (
       blockIndex === initialBlockIndex &&
       compareCursor(cursor, initialCursor) === 0 &&
-      !images.length
+      !targetImages.length && !images.some((image) => !image.isAbsolute && !image.repeatEveryPage) && blockIndex < prepared.length
     ) {
-      // Emergency escape to prevent infinite loop
-      break;
+      throw new RangeError("Text cannot fit in the available page area; reduce font size or enlarge the safe area");
     }
 
-    if (!lines.length && !images.length) {
-      break;
-    }
 
     const textBottom = lines.reduce((max, l) => Math.max(max, l.y + l.lineHeight), 0);
     const flowImages = images.filter((img) => !img.isAbsolute);
@@ -354,5 +367,6 @@ export function paginateBlocks(
     });
   }
 
+  if (hasRemaining()) throw new RangeError(`Content exceeds maxPages=${MAX_PAGES}; no content was discarded`);
   return pages;
 }

package/src/core/page-images.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "bun:test";
 import { getDefaultConfig, runTypeset } from "./engine";
 import { FlowImage } from "./types";
+import { parseInlineRuns } from "./inline-text";
 
 describe("Multi-Page Image Assignment & Intra-Page Ordering", () => {
   const config = getDefaultConfig("longform-3-4");
@@ -106,3 +107,92 @@ describe("Multi-Page Image Assignment & Intra-Page Ordering", () => {
     expect(page2Images[1]?.id).toBe("img_a");
   });
 });
+
+const config = getDefaultConfig();
+const textOf = (result: ReturnType<typeof runTypeset>) => result.pages.flatMap((page) => page.lines).map((line) => line.text).join("");
+
+describe("Pagination regressions", () => {
+  it("ignores empty highlight terms and reuses matching across styled fragments", () => {
+    const runs = parseInlineRuns("正文**正文**正文", ["", "正文"]);
+    expect(runs.map((run) => run.text).join("")).toBe("正文正文正文");
+    expect(runs.every((run) => run.highlight)).toBe(true);
+    expect(parseInlineRuns("a.b", ["", "."])[1]).toEqual({ text: ".", highlight: true });
+  });
+
+  it("retains every character of overflowing manual segments and their images", () => {
+    const first = "甲乙丙丁戊己庚辛壬癸".repeat(180);
+    const result = runTypeset({ markdown: first + "\n---\n第二段", config, images: [
+      { id: "second", src: "data:,", alt: "", pageIndex: 2, isAbsolute: true, width: 20, height: 20 },
+    ] });
+    expect(textOf(result)).toBe(first + "第二段");
+    expect(result.pages.at(-1)?.images[0]?.id).toBe("second");
+    expect(result.pages.map((page) => page.pageNumber)).toEqual(result.pages.map((_, index) => index + 1));
+  });
+
+  it("keeps explicit later images and intervening empty pages", () => {
+    const result = runTypeset({ markdown: "正文", config, images: [
+      { id: "late", src: "data:,", alt: "", pageIndex: 4, width: 20, height: 20 },
+    ] });
+    expect(result.pageCount).toBe(4);
+    expect(result.pages[1]?.lines).toHaveLength(0);
+    expect(result.pages[3]?.images[0]?.id).toBe("late");
+  });
+
+  it("applies global and per-page target fills without losing content", () => {
+    const markdown = "正文段落测试".repeat(250);
+    const normal = runTypeset({ markdown, config });
+    const limited = runTypeset({ markdown, config, pageFillRatios: { 1: 0.35 } });
+    expect(limited.pages[0].lines.length).toBeLessThan(normal.pages[0].lines.length);
+    expect(textOf(limited)).toBe(markdown);
+  });
+
+  it("enforces min and max pages without truncating or inventing blank pages", () => {
+    const markdown = "正文段落测试".repeat(80);
+    const result = runTypeset({ markdown, config, minPages: 3 });
+    expect(result.pageCount).toBeGreaterThanOrEqual(3);
+    expect(textOf(result)).toBe(markdown);
+    expect(() => runTypeset({ markdown: markdown.repeat(10), config, maxPages: 1 })).toThrow("maxPages=1");
+    expect(() => runTypeset({ markdown: "短文", config, minPages: 3 })).toThrow("minPages=3");
+  });
+});
+
+// 固定素材页码对应最终输出页，重复素材不能驱动额外分页。
+describe("Fixed asset pagination", () => {
+  const fixed: FlowImage = { id: "bg", src: "bg.png", alt: "", templateAssetKey: "background", isAbsolute: true, x: 0, y: 0, width: 20, height: 20, repeatEveryPage: true };
+  it("repeats on automatic pages without consuming content image slots", () => {
+    const result = runTypeset({ markdown: "正文测试".repeat(400), config, images: [fixed,
+      { id: "body", src: "body.png", alt: "", isAbsolute: true, width: 20, height: 20 },
+    ] });
+    expect(result.pageCount).toBeGreaterThan(1);
+    expect(result.pages.every((page) => page.images.filter((image) => image.id === "bg").length === 1)).toBe(true);
+    expect(result.pages[0].images.some((image) => image.id === "body")).toBe(true);
+    const short = runTypeset({ markdown: "短文", config, images: [{ ...fixed, pageIndex: 40 }] });
+    expect(short.pageCount).toBe(1);
+  });
+  it("uses final output page numbers across manual overflow and repeats on continuation pages", () => {
+    const result = runTypeset({ markdown: "正文测试".repeat(400) + "\n---\n第二段", config, images: [fixed,
+      { ...fixed, id: "only", templateAssetKey: "logo", repeatEveryPage: false, pageIndex: 2 },
+    ] });
+    expect(result.pages.every((page) => page.images.some((image) => image.id === "bg"))).toBe(true);
+    expect(result.pages.filter((page) => page.images.some((image) => image.id === "only")).map((page) => page.pageNumber)).toEqual([2]);
+    const gaps = runTypeset({ markdown: "甲\n---\n乙", config, images: [{ ...fixed, repeatEveryPage: false, pageIndex: 4 }] });
+    expect(gaps.pageCount).toBe(4);
+    expect(gaps.pages[3].images[0].id).toBe("bg");
+  });
+  it("preserves saved flow asset coordinates when ordinary image counts change", () => {
+    const asset = { ...fixed, repeatEveryPage: false, isAbsolute: false, layoutPreset: "mid-right" as const, x: 100, y: 300, width: 120, height: 80 };
+    const ordinary: FlowImage = { id: "ordinary", src: "body.png", alt: "", isAbsolute: true, width: 20, height: 20 };
+    for (const images of [[asset], [ordinary, { ...ordinary, id: "second" }, asset]]) {
+      const result = runTypeset({ markdown: "正文测试".repeat(400), config, images });
+      for (const page of result.pages) {
+        if (page.pageNumber === 1) expect(page.images.find((image) => image.id === asset.id)).toMatchObject({ x: 100, y: 300, width: 120, height: 80 });
+        else expect(page.images.some((image) => image.id === asset.id)).toBe(false);
+      }
+      expect(result.pages[0].images.filter((image) => !image.templateAssetKey)).toHaveLength(images.length - 1);
+    }
+  });
+  it("rejects repeating flow assets before pagination", () => {
+    expect(() => runTypeset({ markdown: "正文", config, images: [{ ...fixed, isAbsolute: false, width: 2000, height: 2000 }] }))
+      .toThrow("每页重复仅支持自由定位模式");
+  });
+});

package/src/core/pretext.ts

@@ -5,6 +5,10 @@ export {
 } from "@chenglou/pretext/rich-inline";
 export type { RichInlineCursor } from "@chenglou/pretext/rich-inline";
 
+// Node ESM 使用标准加载器，浏览器不会加载原生模块。
+const requireFn = typeof process !== "undefined" && process.versions?.node
+  ? (await import("node:module")).createRequire(import.meta.url)
+  : undefined;
 let initialized = false;
 
 /**
@@ -37,8 +41,6 @@ export function ensurePretextRuntime(): void {
 
   // Node/Bun headless environment
   try {
-    // Dynamic import to prevent bundler errors in browser
-    const requireFn = (import.meta as any).require || (globalThis as any).require;
     if (requireFn) {
       const { createCanvas } = requireFn("@napi-rs/canvas");
 

package/src/core/template.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import { applyTemplateImages } from "./template";
+import { applyTemplateImages, validateTemplateAssets } from "./template";
 import { FlowImage } from "./types";
 
 describe("applyTemplateImages - Template Image Persistence & Intersection Logic", () => {
@@ -177,3 +177,40 @@ describe("applyTemplateImages - Template Image Persistence & Intersection Logic"
     expect(result).toEqual(actualImages);
   });
 });
+
+// 固定素材不能占普通图片布局位置，也不能随普通图片一起替换。
+describe("Fixed template assets", () => {
+  const fixed: FlowImage = { id: "background", src: "bg.png", alt: "背景", templateAssetKey: "background", isAbsolute: true, x: -50, y: -50, width: 1080, height: 1440, zIndex: 0 };
+  const slot: FlowImage = { id: "slot", src: "sample.png", alt: "示例", x: 100, y: 200, width: 300, height: 200, layoutPreset: "custom" };
+  const actual: FlowImage = { id: "actual", src: "new.png", alt: "新图" };
+
+  it("keeps fixed sources and maps normal images only to normal slots", () => {
+    const result = applyTemplateImages([actual], [fixed, slot]);
+    expect(result).toHaveLength(2);
+    expect(result[0]).toMatchObject({ ...actual, x: 100, y: 200, width: 300 });
+    expect(result[1]).toEqual(fixed);
+  });
+
+  it("replaces only the named source without mutating the template", () => {
+    const result = applyTemplateImages([actual], [fixed, slot], { background: "replacement.png" });
+    expect(result[1]).toEqual({ ...fixed, src: "replacement.png" });
+    expect(fixed.src).toBe("bg.png");
+    expect(applyTemplateImages([], [{ ...fixed, templateAssetKey: "constructor" }])[0].src).toBe("bg.png");
+    expect(() => applyTemplateImages([], [fixed], { missing: "new.png" })).toThrow("未知模板素材");
+    expect(() => applyTemplateImages([], [fixed, { ...fixed, id: "duplicate" }])).toThrow("重复");
+  });
+
+  it("reapplying and switching templates removes old fixed layers", () => {
+    const first = applyTemplateImages([actual], [fixed, slot]);
+    expect(applyTemplateImages(first, [fixed, slot])).toEqual(first);
+    expect(applyTemplateImages(first, [slot]).some((image) => image.templateAssetKey)).toBe(false);
+    expect(applyTemplateImages(first, [])).toEqual([first[0]]);
+    expect(applyTemplateImages([], [fixed])).toEqual([fixed]);
+  });
+
+  it("only allows repeating fixed assets in absolute mode", () => {
+    expect(() => validateTemplateAssets([{ ...fixed, isAbsolute: false, repeatEveryPage: true }])).toThrow("每页重复仅支持自由定位模式");
+    expect(() => validateTemplateAssets([{ ...fixed, isAbsolute: false, repeatEveryPage: false }])).not.toThrow();
+    expect(() => validateTemplateAssets([{ ...fixed, repeatEveryPage: true }])).not.toThrow();
+  });
+});