@akairos/typeset-studio 0.2.8 → 0.3.1

package/dist/lib/index.js

@@ -1,14 +1,16 @@
 import {
   plugin,
   typesetStudioAdapter
-} from "./index-y2tk7642.js";
+} from "./index-51d5rpf7.js";
 import {
   applyTemplateImages,
   getDefaultConfig,
   resolveTypesetResult,
   runTypeset,
   validateTemplateAssets
-} from "./index-qszn98j2.js";
+} from "./index-3ptjkctd.js";
+import"./index-94yttj49.js";
+import"./index-nwch18wp.js";
 import {
   drawPageToContext,
   renderPageToCanvas,
@@ -16,12 +18,13 @@ import {
   renderTypesetResultToPngs,
   resolveCanvasFont,
   resolveCanvasFontFamily
-} from "./index-697fkv5y.js";
+} from "./index-dz9pmgbk.js";
 import {
   readFontFamilyName,
   registerServerFonts,
   scanLocalFonts
-} from "./index-6c43c7h4.js";
+} from "./index-2vgqm8ms.js";
+import"./index-xg6pyfw6.js";
 import"./index-37x76zdn.js";
 export {
   validateTemplateAssets,

package/dist/lib/render-epbcmzxe.js

@@ -0,0 +1,14 @@
+import {
+  renderRouter,
+  resolveTypesetResult
+} from "./index-3ptjkctd.js";
+import"./index-94yttj49.js";
+import"./index-nwch18wp.js";
+import"./index-dz9pmgbk.js";
+import"./index-2vgqm8ms.js";
+import"./index-xg6pyfw6.js";
+import"./index-37x76zdn.js";
+export {
+  resolveTypesetResult,
+  renderRouter
+};

package/dist/lib/server-font.js

@@ -0,0 +1,9 @@
+import {
+  registerArticleCoverFont
+} from "./index-94yttj49.js";
+import"./index-nwch18wp.js";
+import"./index-xg6pyfw6.js";
+import"./index-37x76zdn.js";
+export {
+  registerArticleCoverFont
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akairos/typeset-studio",
-  "version": "0.2.8",
+  "version": "0.3.1",
   "description": "Algorithmic typesetting studio & zzhub-pipeline image renderer plugin",
   "publishConfig": {
     "access": "public"
@@ -16,6 +16,18 @@
   "module": "./dist/lib/index.js",
   "types": "./src/index.ts",
   "exports": {
+    "./cover": {
+      "types": "./src/cover.ts",
+      "import": "./dist/cover/cover.js"
+    },
+    "./editor": {
+      "types": "./src/web/editor.ts",
+      "import": "./dist/editor/editor.js"
+    },
+    "./server-font": {
+      "types": "./src/server-font.ts",
+      "import": "./dist/lib/server-font.js"
+    },
     ".": {
       "import": "./dist/lib/index.js",
       "types": "./src/index.ts",
@@ -31,6 +43,8 @@
     "dist/assets",
     "dist/index.html",
     "dist/lib",
+    "dist/editor",
+    "dist/cover",
     "src",
     "public/fonts/README.md",
     "public/fonts/fonts.json",
@@ -41,7 +55,7 @@
     "dev:server": "bun --watch src/server/index.ts",
     "dev:all": "bun --watch src/server/index.ts & vite",
     "build": "vite build && bun run build:lib",
-    "build:lib": "rm -rf dist/lib && bun build src/index.ts src/adapter.ts --outdir dist/lib --target node --splitting --external @napi-rs/canvas",
+    "build:lib": "rm -rf dist/lib dist/editor dist/cover && bun build src/index.ts src/adapter.ts src/server-font.ts --outdir dist/lib --target node --splitting --external @napi-rs/canvas && bun build src/cover.ts --outdir dist/cover --target browser && bun build src/web/editor.ts --outdir dist/editor --target browser --production --external react --external react/jsx-runtime --external react/jsx-dev-runtime",
     "build:watch": "vite build --watch",
     "preview": "vite preview",
     "server": "bun run src/server/index.ts",

package/src/adapter.test.ts

@@ -2,6 +2,47 @@ import { afterAll, describe, expect, it } from "bun:test";
 import { existsSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { typesetStudioAdapter, type ImageRenderInput } from "./adapter";
+import { normalizeArticleCoverTitle } from "./cover";
+
+it("uses preview title normalization only for trusted cover snapshots and rejects empty normalized titles", async () => {
+  const { mkdtemp, rm } = await import("node:fs/promises");
+  const { tmpdir } = await import("node:os");
+  const directory = await mkdtemp(join(tmpdir(), "typeset-cover-title-"));
+  const previousUrl = process.env.TYPESET_STUDIO_URL;
+  const previousSnapshot = process.env.ZZHUB_PIPELINE_COVER_SNAPSHOT;
+  const requests: any[] = [];
+  // 只替换远程传输边界，读取实际 adapter 构造的标题，不能冒充正式渲染结果。
+  const server = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: async request => {
+    requests.push(await request.json());
+    return Response.json({ ok: true, pages: [{ pageNumber: 1, dataUrl: "data:image/png;base64,", bodyImageCount: 0, bodyImageSources: [], bodyImageIds: [] }] });
+  } });
+  const render = (title: string) => typesetStudioAdapter.render({
+    title, route: "wechat-article", bodyText: "", outputDir: directory, state: { route: {} },
+  });
+  try {
+    process.env.TYPESET_STUDIO_URL = server.url.toString();
+    process.env.ZZHUB_PIPELINE_COVER_SNAPSHOT = "1";
+    for (const raw of ["AI", "#AI", "  #AI", "## 标题", "# #AI", "正文 #尾"]) {
+      await render(raw);
+      const title = normalizeArticleCoverTitle(raw);
+      expect(requests.at(-1).title).toBe(title);
+      expect(requests.at(-1).markdown).toBe(`# ${title}`);
+    }
+    const accepted = requests.length;
+    for (const raw of ["", " \t ", " ### "]) await expect(render(raw)).rejects.toThrow("title is empty after normalization");
+    expect(requests.length).toBe(accepted);
+    delete process.env.ZZHUB_PIPELINE_COVER_SNAPSHOT;
+    await render("  #AI");
+    expect(requests.at(-1).markdown).toBe("# #AI");
+    await render("");
+    expect(requests.at(-1).markdown).toBe("# 未命名文章");
+  } finally {
+    if (previousUrl === undefined) delete process.env.TYPESET_STUDIO_URL; else process.env.TYPESET_STUDIO_URL = previousUrl;
+    if (previousSnapshot === undefined) delete process.env.ZZHUB_PIPELINE_COVER_SNAPSHOT; else process.env.ZZHUB_PIPELINE_COVER_SNAPSHOT = previousSnapshot;
+    server.stop(true);
+    await rm(directory, { recursive: true, force: true });
+  }
+});
 
 describe("Typeset Studio — zzhub-pipeline ImageRenderPlugin Adapter", () => {
   const tempTestDir = join(process.cwd(), "tmp", `test-adapter-${Date.now()}`);

package/src/adapter.ts

@@ -2,6 +2,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { extname, join } from "node:path";
 import type { FlowImage, PipelineCoverTheme } from "./core/types";
 import type { RenderRequestBody } from "./server/routes/render";
+import { normalizeArticleCoverTitle } from "./core/article-cover";
 
 // ── Typeset Studio & zzhub-pipeline compatible types ──────────────
 
@@ -266,7 +267,7 @@ async function renderLocalBatch(
 
 export const typesetStudioAdapter: ImageRenderPlugin = {
   name: "typeset-studio",
-  version: "0.2.8",
+  version: "0.3.1",
 
   async doctor(): Promise<PipelinePluginDoctorCheck[]> {
     const checks: PipelinePluginDoctorCheck[] = [];
@@ -353,7 +354,9 @@ export const typesetStudioAdapter: ImageRenderPlugin = {
     // pipeline 的模式标记只选择分页方式，具体模板名才参与模板解析。
     const template = ["wechat-cover-split", "poster-3-4", "longform-3-4"].includes(input.template || "") ? undefined : input.template;
     input.onProgress?.({ stage: "typeset", message: "开始排版", route, account });
-    const title = cleanTitle(input.title || state.metadata?.title || "");
+    const rawTitle = input.title || state.metadata?.title || "";
+    const title = process.env.ZZHUB_PIPELINE_COVER_SNAPSHOT === "1" ? normalizeArticleCoverTitle(rawTitle) : cleanTitle(rawTitle);
+    if (process.env.ZZHUB_PIPELINE_COVER_SNAPSHOT === "1" && !title) throw new RangeError("Article cover title is empty after normalization");
     const common: RenderRequestBody = {
       account,
       title,

package/src/core/article-cover.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "bun:test";
+import { ARTICLE_COVER_FONT, ARTICLE_COVER_IMAGE_KEY, createArticleCoverConfig, normalizeArticleCoverTitle, validateArticleCoverControls } from "./article-cover";
+import { applyTemplateImages } from "./template";
+import { drawPageToContext } from "./canvas-draw";
+import { getCanvasSpec } from "./geometry";
+
+const id = "12345678-1234-4234-8234-123456789abc";
+const assetId = "87654321-4321-4321-8321-cba987654321";
+const controls = { backgroundColor: "#F1F8FF", titleColor: "#123ABC", fontSize: 120, textAlign: "center", safePadding: 120 };
+
+describe("finite article-cover contract", () => {
+  it.each([
+    ["AI", "AI"], ["#AI", "AI"], ["  #AI", "AI"], ["## 标题", "标题"],
+    ["# #AI", "AI"], ["正文 #尾", "正文 #尾"], [" \t ", ""], [" ### ", ""],
+  ])("normalizes cover title %j once and remains idempotent", (raw, expected) => {
+    expect(normalizeArticleCoverTitle(raw)).toBe(expected);
+    expect(normalizeArticleCoverTitle(normalizeArticleCoverTitle(raw))).toBe(expected);
+  });
+
+  it("normalizes finite controls and rejects paths, extra schema and invalid ranges", () => {
+    expect(validateArticleCoverControls(controls)).toMatchObject({ backgroundColor: "#f1f8ff", titleColor: "#123abc" });
+    for (const input of [{ ...controls, fontSize: 79 }, { ...controls, fontSize: 201 }, { ...controls, safePadding: 59 }, { ...controls, safePadding: 201 }, { ...controls, fontSize: 80.5 }, { ...controls, fontPath: "/private/font" }, { ...controls, backgroundColor: "url(https://invalid)" }, { ...controls, schemaVersion: 99 }]) {
+      expect(() => validateArticleCoverControls(input)).toThrow();
+    }
+    expect(() => createArticleCoverConfig({ id, name: "非法路径", controls, assetId: "/private/image" })).toThrow();
+  });
+
+  it("fixes title and square regions while retaining the historical canvas id and font identity", async () => {
+    const config = createArticleCoverConfig({ id, name: "有限封面", controls, assetId });
+    expect(getCanvasSpec(config.aspectRatio)).toMatchObject({ width: 3350, height: 1000, ratio: 3.35 });
+    const padding = config.algorithm.safeArea;
+    expect(3350 - padding.left - padding.right).toBe(2350 - 240);
+    expect(config.typography.headingFont).toBe(ARTICLE_COVER_FONT.family);
+    for (const font of Object.values(config.coverTheme!.typography)) expect(font).toMatchObject({ fontFamily: ARTICLE_COVER_FONT.family, fontSize: 120, minFontSize: 120 });
+    const images = applyTemplateImages([], config.images, { [ARTICLE_COVER_IMAGE_KEY]: "/trusted/square.jpg" });
+    expect(images[0]!.src).toBe("/trusted/square.jpg");
+    expect(images[0]!.x! + padding.left).toBe(2350); expect(images[0]!.y! + padding.top).toBe(0);
+    const draws: unknown[][] = [];
+    const context = new Proxy({ drawImage: (...args: unknown[]) => draws.push(args) } as any, { get: (target, key) => key in target ? target[key] : () => {} });
+    const source = { width: 2000, height: 1000 };
+    await drawPageToContext(context, {
+      page: { pageNumber: 1, lines: [], images: images as any, textBottom: 0, fillRatio: 0 },
+      spec: getCanvasSpec(config.aspectRatio), config, getImage: async () => source,
+    });
+    expect(draws).toEqual([[source, 500, 0, 1000, 1000, -500, -500, 1000, 1000]]);
+  });
+});

package/src/core/article-cover.ts

@@ -0,0 +1,97 @@
+import type { CoverFont, TypesetConfig } from "./types";
+
+export interface ArticleCoverControls {
+  backgroundColor: string;
+  titleColor: string;
+  fontSize: number;
+  textAlign: "left" | "center" | "right";
+  safePadding: number;
+}
+
+export const ARTICLE_COVER_FONT = Object.freeze({
+  id: "publishing-noto-cjk-regular-v1",
+  sha256: "b76b0433203017ca80401b2ee0dd69350349871c4b19d504c34dbdd80541690a",
+  family: "Publishing Cover",
+});
+export const ARTICLE_COVER_IMAGE_KEY = "article_cover_image";
+export const DEFAULT_ARTICLE_COVER_CONTROLS: Readonly<ArticleCoverControls> = Object.freeze({
+  backgroundColor: "#ffffff", titleColor: "#171717", fontSize: 120,
+  textAlign: "left", safePadding: 120,
+});
+
+/** 预览与快照渲染共用标题清理，重复调用不会继续改变标题。 */
+export function normalizeArticleCoverTitle(raw: string): string {
+  return raw.trim().replace(/^(?:#+\s*)+/, "").trim();
+}
+
+function object(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new RangeError("Invalid article cover object");
+  return value as Record<string, unknown>;
+}
+
+function exactKeys(value: Record<string, unknown>, keys: string[]) {
+  if (Object.keys(value).length !== keys.length || Object.keys(value).some(key => !keys.includes(key))) throw new RangeError("Unsupported article cover fields");
+}
+
+function color(value: unknown) {
+  if (typeof value !== "string" || !/^#[a-f\d]{6}$/i.test(value)) throw new RangeError("Article cover colors must be six-digit hex");
+  return value.toLowerCase();
+}
+
+/** 只开放已验证的封面控件，模板不携带字体、路径、URL 或自由布局。 */
+export function validateArticleCoverControls(value: unknown): ArticleCoverControls {
+  const input = object(value);
+  exactKeys(input, ["backgroundColor", "titleColor", "fontSize", "textAlign", "safePadding"]);
+  if (!Number.isInteger(input.fontSize) || (input.fontSize as number) < 80 || (input.fontSize as number) > 200) throw new RangeError("Article cover fontSize must be an integer between 80 and 200");
+  if (!Number.isInteger(input.safePadding) || (input.safePadding as number) < 60 || (input.safePadding as number) > 200) throw new RangeError("Article cover safePadding must be an integer between 60 and 200");
+  if (!["left", "center", "right"].includes(input.textAlign as string)) throw new RangeError("Invalid article cover textAlign");
+  return {
+    backgroundColor: color(input.backgroundColor), titleColor: color(input.titleColor),
+    fontSize: input.fontSize as number, textAlign: input.textAlign as ArticleCoverControls["textAlign"], safePadding: input.safePadding as number,
+  };
+}
+
+/** 方图素材仅用身份占位，可信后端通过 templateImageOverrides 绑定实际文件。 */
+export function createArticleCoverConfig(value: {
+  id: string; name: string; controls: unknown; assetId: string;
+}): TypesetConfig {
+  const input = object(value);
+  exactKeys(input, ["id", "name", "controls", "assetId"]);
+  const uuid = /^[a-f\d]{8}(-[a-f\d]{4}){3}-[a-f\d]{12}$/i;
+  if (typeof input.id !== "string" || !uuid.test(input.id) || typeof input.assetId !== "string" || !uuid.test(input.assetId)) throw new RangeError("Article cover and asset ids must be UUIDs");
+  if (typeof input.name !== "string" || !input.name.trim() || input.name.trim().length > 80) throw new RangeError("Article cover name must contain 1 to 80 characters");
+  const controls = validateArticleCoverControls(input.controls);
+  const safeArea = { top: controls.safePadding, right: 1000 + controls.safePadding, bottom: controls.safePadding, left: controls.safePadding };
+  const font: CoverFont = { fontFamily: ARTICLE_COVER_FONT.family, fontSize: controls.fontSize, minFontSize: controls.fontSize, fontWeight: 400, lineHeight: 1.2, letterSpacing: 0 };
+  return {
+    id: input.id, name: input.name.trim(), slot: "article_cover", aspectRatio: "wechat-cover-2.35",
+    algorithm: {
+      baseFontSize: controls.fontSize, scaleRatio: 1, lineHeightMultiplier: 1.2,
+      obstacleGap: 0, targetFillRatio: 1, contentBottomGap: 0,
+      textAlign: controls.textAlign, verticalAlign: "center", safeArea,
+    },
+    theme: {
+      bgColor: controls.backgroundColor, textColor: controls.titleColor, headingColor: controls.titleColor,
+      accentColor: controls.titleColor, quoteColor: controls.titleColor, captionColor: controls.titleColor,
+      watermarkColor: controls.titleColor, cardBg: controls.backgroundColor,
+    },
+    typography: { headingFont: ARTICLE_COVER_FONT.family, bodyFont: ARTICLE_COVER_FONT.family },
+    footerText: "", watermarkText: "",
+    chrome: { showHeader: false, showWatermark: false, showPageNumber: false, showFooter: false, showFooterDivider: false, showFooterText: false, showFillRatio: false },
+    coverTheme: {
+      id: input.id, format: "wechat-cover-split",
+      typography: { title: { ...font }, subtitle: { ...font }, footer: { ...font } },
+      colors: { text: controls.titleColor, accent: controls.titleColor, muted: controls.titleColor },
+      background: { fill: { type: "solid", color: controls.backgroundColor }, image: null, overlay: null },
+      decoration: { pattern: "none", color: controls.titleColor, opacity: 0, size: 1, image: null },
+      layout: { textAlign: controls.textAlign, verticalAlign: "center", safeArea: { ...safeArea } },
+    },
+    images: [{
+      id: ARTICLE_COVER_IMAGE_KEY, templateAssetKey: ARTICLE_COVER_IMAGE_KEY,
+      src: `asset:${input.assetId}`, alt: "文章封面方图", fit: "cover", isAbsolute: true,
+      // 绘制坐标相对文字 stage，抵消留白后落在画布右侧 1000 方图区域。
+      x: 2350 - controls.safePadding, y: -controls.safePadding,
+      width: 1000, height: 1000, borderRadius: 0, captionHeight: 0, pageIndex: 1, zIndex: 20,
+    }],
+  };
+}

package/src/core/canvas-draw.ts

@@ -271,7 +271,15 @@ export async function drawPageToContext(
       ctx.clip();
 
       if (loadedImg) {
-        ctx.drawImage(loadedImg, -w / 2, -h / 2, w, h);
+        if (img.fit === "cover") {
+          const sourceWidth = loadedImg.naturalWidth || loadedImg.width;
+          const sourceHeight = loadedImg.naturalHeight || loadedImg.height;
+          if (!(sourceWidth > 0 && sourceHeight > 0)) throw new Error("Invalid cover image dimensions");
+          const scale = Math.max(w / sourceWidth, h / sourceHeight);
+          const cropWidth = w / scale;
+          const cropHeight = h / scale;
+          ctx.drawImage(loadedImg, (sourceWidth - cropWidth) / 2, (sourceHeight - cropHeight) / 2, cropWidth, cropHeight, -w / 2, -h / 2, w, h);
+        } else ctx.drawImage(loadedImg, -w / 2, -h / 2, w, h);
       } else {
         ctx.fillStyle = theme.cardBg || "#222222";
         ctx.fillRect(-w / 2, -h / 2, w, h);

package/src/core/types.ts

@@ -70,6 +70,7 @@ export interface FlowImage {
   rotate?: number; // Rotation in degrees (e.g. -15 to 45)
   opacity?: number; // Opacity (0.1 to 1.0)
   borderRadius?: number; // Border radius in px (default 12)
+  fit?: "cover"; // 固定方图可按中心裁切，缺省沿用既有拉伸行为。
 }
 
 export interface FlowLineFragment {

package/src/cover.ts

@@ -0,0 +1,10 @@
+export {
+  ARTICLE_COVER_FONT,
+  ARTICLE_COVER_IMAGE_KEY,
+  DEFAULT_ARTICLE_COVER_CONTROLS,
+  normalizeArticleCoverTitle,
+  validateArticleCoverControls,
+  createArticleCoverConfig,
+  type ArticleCoverControls,
+} from "./core/article-cover";
+export type { TypesetConfig } from "./core/types";

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.8",
+    version: "0.3.1",
     time: new Date().toISOString(),
   });
 });

package/src/server/routes/render.ts

@@ -8,6 +8,8 @@ import {
   getDefaultTemplateId,
   getSlotDefaultTemplateId,
 } from "./templates";
+import { ARTICLE_COVER_FONT } from "../../core/article-cover";
+import { registerArticleCoverFont } from "../../server-font";
 
 export const renderRouter = new Hono();
 renderRouter.onError((error, c) => {
@@ -139,6 +141,13 @@ export function resolveTypesetResult(body: RenderRequestBody): {
 
   const resolvedImages = applyTemplateImages(body.images || [], effectiveConfig.images, body.templateImageOverrides);
 
+  // 插件在独立子进程渲染，字体必须在实际排版进程中校验并注册。
+  if (effectiveConfig.typography.headingFont === ARTICLE_COVER_FONT.family || effectiveConfig.typography.bodyFont === ARTICLE_COVER_FONT.family) {
+    const path = process.env.TYPESET_ARTICLE_COVER_FONT_PATH;
+    if (!path) throw new Error("Article cover font path is not configured for this renderer");
+    registerArticleCoverFont({ path });
+  }
+
   // 封面主题先使用目标字号，单页放不下时缩到契约允许的最小字号。
   let result: TypesetResult;
   while (true) {

package/src/server-font.test.ts

@@ -0,0 +1,46 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { registerArticleCoverFont } from "./server-font";
+import { ARTICLE_COVER_FONT, ARTICLE_COVER_IMAGE_KEY, createArticleCoverConfig } from "./cover";
+import { runTypeset } from "./core/engine";
+import { applyTemplateImages } from "./core/template";
+import { renderPageToPng } from "./core/canvas-renderer";
+import { createCanvas, loadImage } from "@napi-rs/canvas";
+
+test("strict cover font rejects missing, relative and mismatched font bytes", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "typeset-font-"));
+  try {
+    const file = join(directory, "wrong.ttc"); await writeFile(file, "invalid-font");
+    expect(() => registerArticleCoverFont({ path: "relative.ttc" })).toThrow("trusted absolute path");
+    expect(() => registerArticleCoverFont({ path: join(directory, "missing.ttc") })).toThrow("unavailable");
+    expect(() => registerArticleCoverFont({ path: file })).toThrow("hash mismatch");
+  } finally { await rm(directory, { recursive: true }); }
+});
+
+const fontPath = process.env.TYPESET_ARTICLE_COVER_FONT_PATH;
+test.skipIf(!fontPath)("trusted font renders 3350 PNG, left-only text and a non-stretched right square; long title fails", async () => {
+  expect(registerArticleCoverFont({ path: fontPath! })).toEqual(ARTICLE_COVER_FONT);
+  const config = createArticleCoverConfig({
+    id: "12345678-1234-4234-8234-123456789abc", name: "权威封面",
+    controls: { backgroundColor: "#ffffff", titleColor: "#123456", fontSize: 120, textAlign: "center", safePadding: 120 },
+    assetId: "87654321-4321-4321-8321-cba987654321",
+  });
+  const square = createCanvas(1000, 1000); const squareContext = square.getContext("2d");
+  squareContext.fillStyle = "#ff0000"; squareContext.fillRect(0, 0, 1000, 1000);
+  const images = applyTemplateImages([], config.images, { [ARTICLE_COVER_IMAGE_KEY]: square.toDataURL("image/png") });
+  const result = runTypeset({ markdown: "# 可信字体封面", config, images, maxPages: 1 });
+  expect(result.pageCount).toBe(1);
+  for (const line of result.pages[0]!.lines) {
+    expect(line.x + config.algorithm.safeArea.left).toBeGreaterThanOrEqual(120);
+    const width = line.fragments.reduce((sum, fragment) => sum + fragment.occupiedWidth + (fragment.gapBefore || 0), 0);
+    expect(line.x + width + config.algorithm.safeArea.left).toBeLessThanOrEqual(2230);
+  }
+  const png = await renderPageToPng(result.pages[0]!, result.canvasSpec, result.config, 1);
+  expect(png.readUInt32BE(16)).toBe(3350); expect(png.readUInt32BE(20)).toBe(1000);
+  const canvas = createCanvas(3350, 1000); const context = canvas.getContext("2d"); context.drawImage(await loadImage(png), 0, 0);
+  expect(Array.from(context.getImageData(3350 - 1, 0, 1, 1).data)).toEqual([255, 0, 0, 255]);
+  expect(Array.from(context.getImageData(2350, 999, 1, 1).data)).toEqual([255, 0, 0, 255]);
+  expect(() => runTypeset({ markdown: `# ${"超长标题".repeat(200)}`, config, images, maxPages: 1 })).toThrow();
+});

package/src/server-font.ts

@@ -0,0 +1,23 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { GlobalFonts } from "@napi-rs/canvas";
+import { clearCache } from "@chenglou/pretext";
+import { ARTICLE_COVER_FONT } from "./core/article-cover";
+
+let registered = false;
+
+/** 字体路径只由可信部署指定，字节身份不匹配时禁止排版。 */
+export function registerArticleCoverFont({ path }: { path: string }): typeof ARTICLE_COVER_FONT {
+  if (typeof path !== "string" || !isAbsolute(path)) throw new Error("Article cover font requires a trusted absolute path");
+  let bytes: Buffer;
+  try { bytes = readFileSync(path); }
+  catch { throw new Error("Article cover font file is unavailable"); }
+  if (createHash("sha256").update(bytes).digest("hex") !== ARTICLE_COVER_FONT.sha256) throw new Error("Article cover font hash mismatch");
+  if (!registered || !GlobalFonts.has(ARTICLE_COVER_FONT.family)) {
+    if (!GlobalFonts.registerFromPath(path, ARTICLE_COVER_FONT.family) || !GlobalFonts.has(ARTICLE_COVER_FONT.family)) throw new Error("Article cover font registration failed");
+    registered = true;
+    clearCache();
+  }
+  return ARTICLE_COVER_FONT;
+}

package/src/web/components/CoverControls.tsx

@@ -0,0 +1,22 @@
+import { useId } from "react";
+import type { ArticleCoverControls } from "../../core/article-cover";
+
+export interface CoverControlsProps {
+  value: ArticleCoverControls;
+  onChange: (value: ArticleCoverControls) => void;
+  disabled?: boolean;
+}
+
+/** 只编辑有限配置；保存、素材上传与服务端 PNG 由宿主接线。 */
+export function CoverControls({ value, onChange, disabled = false }: CoverControlsProps) {
+  const id = useId();
+  return <fieldset className="typeset-cover-controls" disabled={disabled}>
+    <legend>文章封面</legend>
+    <label htmlFor={`${id}-background`}>背景色</label><input id={`${id}-background`} type="color" value={value.backgroundColor} onChange={event => onChange({ ...value, backgroundColor: event.target.value })} />
+    <label htmlFor={`${id}-title`}>标题色</label><input id={`${id}-title`} type="color" value={value.titleColor} onChange={event => onChange({ ...value, titleColor: event.target.value })} />
+    <label htmlFor={`${id}-size`}>标题字号</label><input id={`${id}-size`} type="number" min={80} max={200} step={1} value={value.fontSize} onChange={event => onChange({ ...value, fontSize: Number(event.target.value) })} />
+    <label htmlFor={`${id}-align`}>水平对齐</label><select id={`${id}-align`} value={value.textAlign} onChange={event => onChange({ ...value, textAlign: event.target.value as ArticleCoverControls["textAlign"] })}><option value="left">左对齐</option><option value="center">居中</option><option value="right">右对齐</option></select>
+    <label htmlFor={`${id}-padding`}>安全留白</label><input id={`${id}-padding`} type="number" min={60} max={200} step={1} value={value.safePadding} onChange={event => onChange({ ...value, safePadding: Number(event.target.value) })} />
+    <p>画布 3350×1000：左侧 2350 为标题，右侧 1000 为中心裁切方图。字体固定，预览以服务端 PNG 为准。</p>
+  </fieldset>;
+}

package/src/web/components/Header.tsx

@@ -58,7 +58,7 @@ export const Header: React.FC<HeaderProps> = ({
           </span>
           <span className="hidden 2xl:inline">Typeset Studio</span>
         </div>
-        <span className="text-xs text-[#888888] dark:text-[#555555] font-mono hidden 2xl:inline">v0.2.8</span>
+        <span className="text-xs text-[#888888] dark:text-[#555555] font-mono hidden 2xl:inline">v0.3.1</span>
         <div title={templateName || "未命名模板"} className="flex min-w-0 items-center gap-1.5 px-2 py-0.5 rounded-full bg-[#f5f5f5] dark:bg-[#111111] border border-[#e5e5e5] dark:border-[#222222] text-[11px] text-emerald-600 dark:text-[#00e676]">
           <span className="w-1.5 h-1.5 shrink-0 rounded-full bg-emerald-500 dark:bg-[#00e676]" />
           <span aria-live="polite" className="max-w-40 truncate">{templateName || "未命名模板"}</span>

package/src/web/editor.ts

@@ -0,0 +1 @@
+export { CoverControls, type CoverControlsProps } from "./components/CoverControls";

package/dist/lib/render-064weavx.js

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