@akairos/typeset-studio 0.2.1 → 0.2.3

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

@@ -2,17 +2,13 @@ export {
   prepareRichInline,
   layoutNextRichInlineLineRange,
   materializeRichInlineLineRange,
-  measureRichInlineStats,
 } from "@chenglou/pretext/rich-inline";
 export type { RichInlineCursor } from "@chenglou/pretext/rich-inline";
 
-export {
-  prepare,
-  layoutNextLineRange,
-  materializeLineRange,
-  measureLineStats,
-} from "@chenglou/pretext";
-
+// Node ESM 使用标准加载器，浏览器不会加载原生模块。
+const requireFn = typeof process !== "undefined" && process.versions?.node
+  ? (await import("node:module")).createRequire(import.meta.url)
+  : undefined;
 let initialized = false;
 
 /**
@@ -45,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();
+  });
+});

package/src/core/template.ts

@@ -1,49 +1,61 @@
-import { FlowImage, TypesetConfig } from "./types";
+import { FlowImage } from "./types";
 
-/**
- * Applies template image layout configurations to current content images based on index intersection:
- * - If current images exist and template has images:
- *   For 0 <= i < min(template.images.length, current.images.length), apply template layout properties
- *   (isAbsolute, layoutPreset, x, y, width, height, rotate, opacity, zIndex, borderRadius, captionHeight, pageIndex)
- *   while preserving the current image's content identity (id, src, alt, caption).
- *   Current images beyond template.images.length remain untouched ("取交集，另外俩图用户自己调").
- * - If current images are empty (0 images), adopt the template's images (with freshly generated IDs).
- * - If template has no images, current images remain untouched.
- */
+// 固定素材标识用于显式替换，同一模板内必须唯一。
+export function validateTemplateAssets(images: FlowImage[] = []): void {
+  if (!Array.isArray(images)) throw new RangeError("模板图片必须是数组");
+  const keys = new Set<string>();
+  for (const image of images) {
+    if (!image || typeof image !== "object") throw new RangeError("无效的模板图片");
+    if (image.templateAssetKey === undefined) continue;
+    const key = image.templateAssetKey;
+    if (image.repeatEveryPage !== undefined && typeof image.repeatEveryPage !== "boolean") throw new RangeError(`素材 ${key} 的每页重复开关必须是布尔值`);
+    if (typeof key !== "string" || !/^[a-zA-Z0-9_-]+$/.test(key)) {
+      throw new RangeError("素材标识只能包含字母、数字、下划线和短横线");
+    }
+    if (image.repeatEveryPage && !image.isAbsolute) throw new RangeError(`素材 ${key} 的每页重复仅支持自由定位模式`);
+    if (keys.has(key)) throw new RangeError(`重复的模板素材标识：${key}`);
+    keys.add(key);
+  }
+}
+
+// 普通配图按位置套用布局，固定素材仅通过标识替换来源。
 export function applyTemplateImages(
   currentImages: FlowImage[],
-  templateImages?: FlowImage[],
+  templateImages: FlowImage[] = [],
+  overrides: Record<string, string> = {},
 ): FlowImage[] {
-  if (!templateImages || templateImages.length === 0) {
-    return currentImages;
+  validateTemplateAssets(templateImages);
+  if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) throw new RangeError("素材替换必须是标识到图片地址的映射");
+  const fixed = templateImages.filter((image) => image.templateAssetKey);
+  for (const [key, src] of Object.entries(overrides)) {
+    if (!fixed.some((image) => image.templateAssetKey === key)) throw new RangeError(`未知模板素材：${key}`);
+    if (typeof src !== "string" || !src.trim()) throw new RangeError(`素材 ${key} 的替换图片不能为空`);
   }
-
-  if (currentImages.length === 0) {
-    return templateImages.map((tplImg) => ({
-      ...tplImg,
-      id: `img_${Date.now()}_${Math.random().toString(36).substring(2, 6)}`,
-    }));
-  }
-
-  return currentImages.map((currentImg, idx) => {
-    if (idx < templateImages.length) {
-      const tplImg = templateImages[idx];
+  const content = currentImages.filter((image) => !image.templateAssetKey);
+  const slots = templateImages.filter((image) => !image.templateAssetKey);
+  const mapped = content.length === 0
+    ? slots.map((image) => ({ ...image, id: `img_${crypto.randomUUID()}` }))
+    : content.map((image, index) => {
+      const slot = slots[index];
+      if (!slot) return image;
       return {
-        ...currentImg,
-        layoutPreset: tplImg.layoutPreset ?? currentImg.layoutPreset,
-        isAbsolute: tplImg.isAbsolute ?? currentImg.isAbsolute,
-        x: tplImg.x ?? currentImg.x,
-        y: tplImg.y ?? currentImg.y,
-        width: tplImg.width ?? currentImg.width,
-        height: tplImg.height ?? currentImg.height,
-        rotate: tplImg.rotate ?? currentImg.rotate,
-        opacity: tplImg.opacity ?? currentImg.opacity,
-        zIndex: tplImg.zIndex ?? currentImg.zIndex,
-        borderRadius: tplImg.borderRadius ?? currentImg.borderRadius,
-        captionHeight: tplImg.captionHeight ?? currentImg.captionHeight,
-        pageIndex: tplImg.pageIndex ?? currentImg.pageIndex,
+        ...image,
+        layoutPreset: slot.layoutPreset ?? image.layoutPreset,
+        isAbsolute: slot.isAbsolute ?? image.isAbsolute,
+        x: slot.x ?? image.x,
+        y: slot.y ?? image.y,
+        width: slot.width ?? image.width,
+        height: slot.height ?? image.height,
+        rotate: slot.rotate ?? image.rotate,
+        opacity: slot.opacity ?? image.opacity,
+        zIndex: slot.zIndex ?? image.zIndex,
+        borderRadius: slot.borderRadius ?? image.borderRadius,
+        captionHeight: slot.captionHeight ?? image.captionHeight,
+        pageIndex: slot.pageIndex ?? image.pageIndex,
       };
-    }
-    return currentImg;
-  });
+    });
+  return [...mapped, ...fixed.map((image) => ({
+    ...image,
+    src: Object.hasOwn(overrides, image.templateAssetKey!) ? overrides[image.templateAssetKey!] : image.src,
+  }))];
 }

package/src/core/types.ts

@@ -20,6 +20,7 @@ export interface InlineTextRun {
   italic?: boolean;
   highlight?: boolean;
   font?: string;
+  letterSpacing?: number;
 }
 
 export type ContentBlockKind =
@@ -55,6 +56,8 @@ export interface FlowImage {
   src: string;
   alt: string;
   caption?: string;
+  templateAssetKey?: string; // 固定模板素材的唯一标识
+  repeatEveryPage?: boolean; // 开启时忽略页码，在所有输出页重复
   x?: number;
   y?: number;
   width?: number;
@@ -77,6 +80,7 @@ export interface FlowLineFragment {
   highlight?: boolean;
   gapBefore: number;
   occupiedWidth: number;
+  letterSpacing?: number;
 }
 
 export interface FlowLine {
@@ -163,6 +167,7 @@ export interface TypesetConfig {
   watermarkText: string;
   chrome?: TypesetChromeConfig;
   images?: FlowImage[];
+  coverTheme?: PipelineCoverTheme;
 }
 
 export interface TypesetResult {
@@ -171,3 +176,44 @@ export interface TypesetResult {
   canvasSpec: CanvasSpec;
   config: TypesetConfig;
 }
+
+// 流水线解析后的封面主题，与 pipeline 的公开契约保持一致。
+export interface CoverFont {
+  fontFamily: string;
+  fontSize: number;
+  minFontSize: number;
+  fontWeight: number;
+  lineHeight: number;
+  letterSpacing: number;
+}
+export interface CoverImage {
+  src: string;
+  fit: "cover" | "contain" | "fill";
+  position: { x: number; y: number };
+  opacity: number;
+}
+export interface PipelineCoverTheme {
+  id: string;
+  format: "poster-3-4" | "wechat-cover-split";
+  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 }> };
+    image: CoverImage | null;
+    overlay: { color: string; opacity: number } | null;
+  };
+  decoration: {
+    pattern: "none" | "lines" | "grid" | "dots" | "rings" | "burst";
+    color: string;
+    opacity: number;
+    size: number;
+    image: CoverImage | null;
+  };
+  layout: {
+    textAlign: "left" | "center" | "right";
+    verticalAlign: "top" | "center" | "bottom";
+    safeArea: AlgorithmParams["safeArea"];
+  };
+}

package/src/core/typography.ts

@@ -1,19 +1,5 @@
 import { ContentBlockKind } from "./types";
 
-export interface TypographicScale {
-  base: number;
-  ratio: number;
-}
-
-export const MODULAR_SCALES: Record<string, number> = {
-  minorSecond: 1.067,
-  majorSecond: 1.125,
-  minorThird: 1.2,
-  majorThird: 1.25,
-  perfectFourth: 1.333,
-  goldenRatio: 1.618,
-};
-
 export function modularScale(base: number, ratio: number, step: number): number {
   return Math.round(base * Math.pow(ratio, step));
 }

package/src/index.ts

@@ -15,7 +15,7 @@ export {
   readFontFamilyName,
   type LocalFontInfo,
 } from "./core/font-loader";
-export { applyTemplateImages } from "./core/template";
+export { applyTemplateImages, validateTemplateAssets } from "./core/template";
 
 export {
   typesetStudioAdapter,
@@ -31,14 +31,17 @@ export { resolveTypesetResult, type RenderRequestBody } from "./server/routes/re
 
 export type {
   AlgorithmParams,
-  AspectRatioPreset,
+  AspectRatioType,
   CanvasSpec,
   ContentBlockKind,
+  CoverFont,
+  CoverImage,
+  PipelineCoverTheme,
   FlowBlock,
   FlowImage,
   FlowLine,
   FlowPage,
-  InlineFragment,
+  FlowLineFragment,
   TemplateSlot,
   ThemeColors,
   TypesetChromeConfig,

package/src/server/auth.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from "fs";
 import { resolve } from "path";
+import { randomBytes } from "node:crypto";
 import type { Context, Next } from "hono";
 
 const ENV_PATH = resolve(process.cwd(), ".env");
@@ -26,7 +27,7 @@ export function getOrGenerateAdminKey(): string {
   }
 
   // Generate a new secure key
-  const randomSuffix = Math.random().toString(36).substring(2, 10) + Math.random().toString(36).substring(2, 10);
+  const randomSuffix = randomBytes(24).toString("hex");
   const newKey = `tsk_${randomSuffix}`;
 
   try {
@@ -53,18 +54,6 @@ export async function authMiddleware(c: Context, next: Next) {
 
   const providedKey = headerKey || bearerKey || queryKey;
 
-  // Seamless local use: requests from localhost / loopback are trusted for dev
-  const host = c.req.header("host") || "";
-  const isLocal =
-    host.includes("localhost") ||
-    host.includes("127.0.0.1") ||
-    host.includes("0.0.0.0") ||
-    host.includes("[::1]");
-
-  if (isLocal) {
-    return next();
-  }
-
   if (!providedKey || providedKey !== adminKey) {
     return c.json(
       {
@@ -78,3 +67,19 @@ export async function authMiddleware(c: Context, next: Next) {
 
   return next();
 }
+
+// 仅真实回环连接且来源为本机网页时允许自动取钥。
+export function isLocalRequest(c: Context): boolean {
+  if (c.req.header("forwarded") || c.req.header("x-forwarded-for") || c.req.header("x-forwarded-host")) return false;
+  const peer = c.env?.peerAddress;
+  if (!["127.0.0.1", "::1", "::ffff:127.0.0.1"].includes(peer)) return false;
+  const isLoopback = (value: string) => {
+    try {
+      return ["localhost", "127.0.0.1", "[::1]"].includes(new URL(value).hostname);
+    } catch {
+      return false;
+    }
+  };
+  return isLoopback(c.req.url) && isLoopback(`http://${c.req.header("host") || ""}`) &&
+    (!c.req.header("origin") || isLoopback(c.req.header("origin")!));
+}