@akairos/typeset-studio 0.2.1 → 0.2.3

package/src/server/index.ts

@@ -1,24 +1,23 @@
 import { existsSync, mkdirSync } from "fs";
 import { join } from "path";
 import { Hono } from "hono";
-import { cors } from "hono/cors";
 import { serveStatic } from "hono/bun";
-import { authMiddleware, getOrGenerateAdminKey } from "./auth";
+import { authMiddleware, getOrGenerateAdminKey, isLocalRequest } from "./auth";
 import { renderRouter } from "./routes/render";
 import { templatesRouter } from "./routes/templates";
 import { uploadRouter } from "./routes/upload";
 import { fontsRouter } from "./routes/fonts";
+import { resolveDataDir } from "../core/data-dir";
 
 export const app = new Hono();
 
-app.use("*", cors());
 
 // Health check (public)
 app.get("/api/health", (c) => {
   return c.json({
     status: "ok",
     name: "Typeset Studio Server",
-    version: "0.1.0",
+    version: "0.2.2",
     time: new Date().toISOString(),
   });
 });
@@ -36,17 +35,12 @@ app.post("/api/auth/verify", async (c) => {
 
 // Get active admin key for seamless local development
 app.get("/api/auth/current-key", (c) => {
-  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 (!isLocalRequest(c)) return c.json({ ok: false, isLocal: false }, 403);
   const adminKey = getOrGenerateAdminKey();
   return c.json({
     ok: true,
     key: adminKey,
-    isLocal,
+    isLocal: true,
   });
 });
 
@@ -60,11 +54,11 @@ app.route("/api/upload", uploadRouter);
 app.route("/api/render", renderRouter);
 
 // Static uploads serving
-const UPLOAD_DIR = join(process.cwd(), "data", "uploads");
+const UPLOAD_DIR = join(resolveDataDir(), "uploads");
 if (!existsSync(UPLOAD_DIR)) {
   mkdirSync(UPLOAD_DIR, { recursive: true });
 }
-app.use("/uploads/*", serveStatic({ root: "./data" }));
+app.use("/uploads/*", serveStatic({ root: resolveDataDir() }));
 
 // Static local font serving
 app.get("/fonts/:filename", async (c) => {
@@ -111,19 +105,20 @@ if (existsSync(DIST_DIR)) {
 }
 
 const PORT = Number(process.env.PORT || 4890);
-const adminKey = getOrGenerateAdminKey();
+getOrGenerateAdminKey();
 
 console.log(`
 ┌────────────────────────────────────────────────────────┐
 │               ⚡ Typeset Studio Server                 │
 ├────────────────────────────────────────────────────────┤
 │  Web URL:    http://localhost:${PORT}                   │
-│  Admin Key:  ${adminKey}                      │
 │  Protected:  X-Admin-Key header required               │
 └────────────────────────────────────────────────────────┘
 `);
 
 export default {
+  hostname: process.env.TYPESET_HOST || "127.0.0.1",
   port: PORT,
-  fetch: app.fetch,
+  fetch: (request: Request, server: Bun.Server<undefined>) =>
+    app.fetch(request, { peerAddress: server.requestIP(request)?.address }),
 };

package/src/server/routes/fonts.ts

@@ -1,5 +1,5 @@
 import { Hono } from "hono";
-import { registerServerFonts, scanLocalFonts } from "../../core/font-loader";
+import { registerServerFonts } from "../../core/font-loader";
 
 export const fontsRouter = new Hono();
 

package/src/server/routes/render.ts

@@ -10,6 +10,12 @@ import {
 } from "./templates";
 
 export const renderRouter = new Hono();
+renderRouter.onError((error, c) => {
+  if (error.message.startsWith("模板素材 ")) return c.json({ ok: false, error: error.message }, 422);
+  if (error instanceof RangeError) return c.json({ ok: false, error: error.message }, 400);
+  console.error("渲染失败", error);
+  return c.json({ ok: false, error: "Render failed" }, 500);
+});
 
 export interface RenderRequestBody {
   result?: TypesetResult;
@@ -26,7 +32,16 @@ export interface RenderRequestBody {
   text?: string;
   images?: FlowImage[];
   highlightWords?: string[];
-  config?: Partial<TypesetConfig>;
+  config?: Omit<Partial<TypesetConfig>, "algorithm" | "theme" | "typography"> & {
+    algorithm?: Partial<TypesetConfig["algorithm"]>;
+    theme?: Partial<TypesetConfig["theme"]>;
+    typography?: Partial<TypesetConfig["typography"]>;
+  };
+  minPages?: number;
+  maxPages?: number;
+  pageFillRatios?: Record<number, number>;
+  templateImageOverrides?: Record<string, string>;
+  preserveTemplateStyle?: boolean;
 }
 
 function inferSlot(route?: string, kind?: string, aspectRatio?: string): TemplateSlot | undefined {
@@ -74,6 +89,7 @@ export function resolveTypesetResult(body: RenderRequestBody): {
   let baseConfig: TypesetConfig | null = null;
   if (targetKey) {
     baseConfig = findTemplateByKeyOrName(targetKey);
+    if (!baseConfig) throw new RangeError(`Template '${targetKey}' not found`);
   }
 
   // 2. Resolve by slot and account
@@ -99,35 +115,56 @@ export function resolveTypesetResult(body: RenderRequestBody): {
     baseConfig = getDefaultConfig(isCover ? "wechat-cover-2.35" : "longform-3-4");
   }
 
+  // 插件保留模板样式；直接 API 调用仍允许显式覆盖配置。
+  const overrides = body.preserveTemplateStyle && baseConfig.id ? {} : body.config;
+
   // Merge any config overrides
   const effectiveConfig: TypesetConfig = {
     ...baseConfig,
-    ...(body.config || {}),
+    ...(overrides || {}),
     algorithm: {
       ...baseConfig.algorithm,
-      ...(body.config?.algorithm || {}),
+      ...(overrides?.algorithm || {}),
     },
     theme: {
       ...baseConfig.theme,
-      ...(body.config?.theme || {}),
+      ...(overrides?.theme || {}),
     },
     typography: {
       ...baseConfig.typography,
-      ...(body.config?.typography || {}),
+      ...(overrides?.typography || {}),
     },
+    chrome: { ...baseConfig.chrome, ...overrides?.chrome },
   };
 
-  const inputImages = body.images;
-  const resolvedImages = inputImages && inputImages.length > 0
-    ? (effectiveConfig.images ? applyTemplateImages(inputImages, effectiveConfig.images) : inputImages)
-    : (effectiveConfig.images || []);
-
-  const result = runTypeset({
-    markdown,
-    images: resolvedImages,
-    config: effectiveConfig,
-    highlightWords: body.highlightWords || [],
-  });
+  const resolvedImages = applyTemplateImages(body.images || [], effectiveConfig.images, body.templateImageOverrides);
+
+  // 封面主题先使用目标字号，单页放不下时缩到契约允许的最小字号。
+  let result: TypesetResult;
+  while (true) {
+    try {
+      result = runTypeset({
+        markdown, images: resolvedImages, config: effectiveConfig,
+        highlightWords: body.highlightWords || [],
+        minPages: body.minPages, maxPages: body.maxPages, pageFillRatios: body.pageFillRatios,
+      });
+      break;
+    } catch (error) {
+      const theme = effectiveConfig.coverTheme;
+      if (!theme || body.kind !== "cover" || !(error instanceof Error) ||
+        !/exceeds maxPages|cannot fit/.test(error.message)) throw error;
+      const title = theme.typography.title;
+      if (!Number.isFinite(title.fontSize) || !Number.isFinite(title.minFontSize) || title.minFontSize <= 0) {
+        throw new RangeError("Invalid cover theme font size");
+      }
+      if (title.fontSize <= title.minFontSize) throw error;
+      effectiveConfig.coverTheme = {
+        ...theme, typography: { ...theme.typography, title: {
+          ...title, fontSize: Math.max(title.minFontSize, Math.floor(title.fontSize * 0.9)),
+        } },
+      };
+    }
+  }
 
   return {
     templateId: baseConfig.id,
@@ -162,7 +199,7 @@ renderRouter.post("/png", async (c) => {
   }
 
   const pngBuffer = await renderPageToPng(targetPage, result.canvasSpec, result.config, result.pageCount);
-  return new Response(pngBuffer, {
+  return new Response(new Uint8Array(pngBuffer), {
     status: 200,
     headers: {
       "Content-Type": "image/png",
@@ -186,6 +223,12 @@ renderRouter.post("/export", async (c) => {
       pageNumber: item.pageNumber,
       dataUrl: `data:image/png;base64,${item.buffer.toString("base64")}`,
       byteLength: item.buffer.length,
+      imageIds: result.pages.find((page) => page.pageNumber === item.pageNumber)!.images.map((image) => image.id),
+      bodyImageCount: result.pages.find((page) => page.pageNumber === item.pageNumber)!.images.filter((image) => !image.templateAssetKey).length,
+      bodyImageSources: result.pages.find((page) => page.pageNumber === item.pageNumber)!.images.filter((image) => !image.templateAssetKey).map((image) => image.src),
+      bodyImageIds: result.pages.find((page) => page.pageNumber === item.pageNumber)!.images.filter((image) => !image.templateAssetKey).map((image) => image.id),
+      imageCount: result.pages.find((page) => page.pageNumber === item.pageNumber)!.images.length,
+      imageSources: result.pages.find((page) => page.pageNumber === item.pageNumber)!.images.map((image) => image.src),
     })),
   });
 });

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

@@ -87,3 +87,99 @@ describe("Template Slots & Fallback Compatibility", () => {
     expect(data.result.pageCount).toBeGreaterThanOrEqual(1);
   });
 });
+
+// 鉴权、模板覆盖和数据目录共用隔离测试环境。
+describe("Storage and authentication regressions", () => {
+  it("rejects forged local Hosts and never returns a remote key", async () => {
+    for (const host of ["localhost.attacker.example", "localhost", "127.0.0.1"]) {
+      const response = await app.request("http://remote.example/api/templates", { headers: { host } });
+      expect(response.status).toBe(401);
+      const keyResponse = await app.request("http://remote.example/api/auth/current-key", { headers: { host } });
+      expect(keyResponse.status).toBe(403);
+      expect(await keyResponse.text()).not.toContain(adminKey);
+    }
+    const untrustedOrigin = await app.request("http://localhost/api/auth/current-key", {
+      headers: { host: "localhost", origin: "https://attacker.example" },
+    }, { peerAddress: "127.0.0.1" });
+    expect(untrustedOrigin.status).toBe(403);
+    const local = await app.request("http://localhost/api/auth/current-key", {
+      headers: { host: "localhost", origin: "http://localhost:5173" },
+    }, { peerAddress: "127.0.0.1" });
+    expect(local.status).toBe(200);
+  });
+
+  it("rejects traversal for template CRUD and resolver paths", async () => {
+    const template = { ...(await (await app.request("/api/templates/tpl_wechat_cover_minimal", { headers: authHeaders })).json()).template, id: "../escaped" };
+    const save = await app.request("/api/templates", {
+      method: "POST", headers: authHeaders, body: JSON.stringify(template),
+    });
+    expect(save.status).toBe(400);
+    for (const method of ["GET", "DELETE"]) {
+      const response = await app.request("/api/templates/..%2Fescaped", { method, headers: authHeaders });
+      expect(response.status).toBe(400);
+    }
+    const resolve = await app.request("/api/templates/resolve/..%2Fescaped", { headers: authHeaders });
+    expect(resolve.status).toBe(404);
+  });
+
+  it("uses saved builtin overrides and does not recreate deleted templates", async () => {
+    const id = "tpl_longform_vintage_news";
+    const original = (await (await app.request(`/api/templates/${id}`, { headers: authHeaders })).json()).template;
+    try {
+      const save = await app.request("/api/templates", {
+        method: "POST", headers: authHeaders,
+        body: JSON.stringify({ ...original, footerText: "磁盘覆盖" }),
+      });
+      expect(save.status).toBe(200);
+      const resolved = await (await app.request(`/api/templates/resolve/${id}`, { headers: authHeaders })).json();
+      expect(resolved.template.footerText).toBe("磁盘覆盖");
+      const deleted = await app.request(`/api/templates/${id}`, { method: "DELETE", headers: authHeaders });
+      expect(deleted.status).toBe(200);
+      expect((await app.request(`/api/templates/${id}`, { headers: authHeaders })).status).toBe(404);
+      expect((await app.request(`/api/templates/resolve/${id}`, { headers: authHeaders })).status).toBe(404);
+    } finally {
+      await app.request("/api/templates", { method: "POST", headers: authHeaders, body: JSON.stringify(original) });
+    }
+  });
+
+  it("serves uploaded files from the configured data directory", async () => {
+    const data = new FormData();
+    data.append("file", new File(["uploaded-image-bytes"], "test.png", { type: "image/png" }));
+    const response = await app.request("/api/upload", { method: "POST", headers: { "x-admin-key": adminKey }, body: data });
+    expect(response.status).toBe(200);
+    const uploaded = await response.json();
+    const fetched = await app.request(uploaded.url);
+    expect(fetched.status).toBe(200);
+    expect(await fetched.text()).toBe("uploaded-image-bytes");
+  });
+});
+
+describe("Fixed asset rendering API", () => {
+  it("preserves template styles, validates identifiers, and fails for missing fixed files", async () => {
+    const { getDefaultConfig } = await import("../../core/engine");
+    const id = "fixed_asset_api_test";
+    const template = { ...getDefaultConfig(), id, images: [
+      { id: "bg", src: "/missing-background.png", alt: "", isAbsolute: true, templateAssetKey: "background", zIndex: 0 },
+    ] };
+    try {
+      expect((await app.request("/api/templates", { method: "POST", headers: authHeaders, body: JSON.stringify(template) })).status).toBe(200);
+      const response = await app.request("/api/render", { method: "POST", headers: authHeaders, body: JSON.stringify({
+        template: id, markdown: "正文", preserveTemplateStyle: true,
+        config: { theme: { bgColor: "#123456" }, typography: { bodyFont: "Other Font" } },
+      }) });
+      const rendered = await response.json();
+      expect(rendered.result.config.theme.bgColor).toBe(template.theme.bgColor);
+      expect(rendered.result.config.typography.bodyFont).toBe(template.typography.bodyFont);
+      expect(rendered.result.pages[0].images[0].templateAssetKey).toBe("background");
+      const missing = await app.request("/api/render/export", { method: "POST", headers: authHeaders, body: JSON.stringify({ template: id, markdown: "正文" }) });
+      expect(missing.status).toBe(422);
+      expect((await missing.json()).error).toContain("background");
+      const unknown = await app.request("/api/render", { method: "POST", headers: authHeaders, body: JSON.stringify({ template: id, templateImageOverrides: { unknown: "new.png" } }) });
+      expect(unknown.status).toBe(400);
+      const duplicate = await app.request("/api/templates", { method: "POST", headers: authHeaders, body: JSON.stringify({ ...template, images: [...template.images, { ...template.images[0], id: "bg2" }] }) });
+      expect(duplicate.status).toBe(400);
+    } finally {
+      await app.request(`/api/templates/${id}`, { method: "DELETE", headers: authHeaders });
+    }
+  });
+});

package/src/server/routes/templates.ts

@@ -1,23 +1,12 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
-import { dirname, join, resolve } from "path";
-import { fileURLToPath } from "url";
+import { dirname, join } from "path";
 import { Hono } from "hono";
 import { getDefaultConfig } from "../../core/engine";
 import { TemplateSlot, TypesetConfig } from "../../core/types";
+import { resolveDataDir } from "../../core/data-dir";
+import { validateTemplateAssets } from "../../core/template";
 
-export function resolveDataDir(): string {
-  if (process.env.TYPESET_DATA_DIR) {
-    return process.env.TYPESET_DATA_DIR;
-  }
-  const currentDir = typeof __dirname !== "undefined" ? __dirname : dirname(fileURLToPath(import.meta.url));
-  const candidateLib = resolve(currentDir, "../../data");
-  if (existsSync(candidateLib)) return candidateLib;
-  const candidateSrc = resolve(currentDir, "../../../data");
-  if (existsSync(candidateSrc)) return candidateSrc;
-  const candidateCwd = resolve(process.cwd(), "data");
-  if (existsSync(candidateCwd)) return candidateCwd;
-  return candidateLib;
-}
+export { resolveDataDir } from "../../core/data-dir";
 
 const TEMPLATES_DIR = join(resolveDataDir(), "templates");
 
@@ -29,7 +18,11 @@ function ensureTemplatesDir(): void {
       // Ignore write errors in read-only environments
     }
   }
-  seedDefaultTemplates();
+  const seedMarker = join(TEMPLATES_DIR, ".initialized");
+  if (!existsSync(seedMarker)) {
+    seedDefaultTemplates();
+    try { writeFileSync(seedMarker, "1"); } catch { /* 只读安装目录保留读取能力。 */ }
+  }
 }
 
 export const BUILTIN_PRESETS: TypesetConfig[] = [
@@ -383,7 +376,7 @@ export function getSlotDefaultTemplateId(slot: TemplateSlot, account = "default"
 }
 
 export function setSlotDefaultTemplateId(slot: TemplateSlot, templateId: string, account = "default"): void {
-  const dir = join(process.cwd(), "data");
+  const dir = dirname(DEFAULT_SETTINGS_PATH);
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
   }
@@ -420,7 +413,7 @@ export function getDefaultTemplateId(): string | null {
 }
 
 export function setDefaultTemplateId(id: string): void {
-  const dir = join(process.cwd(), "data");
+  const dir = dirname(DEFAULT_SETTINGS_PATH);
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
   }
@@ -439,21 +432,13 @@ export function setDefaultTemplateId(id: string): void {
 export function findTemplateByKeyOrName(key: string): TypesetConfig | null {
   const lowerKey = key.trim().toLowerCase();
 
-  // 1. Direct match in built-in memory presets
-  const builtin = BUILTIN_PRESETS.find(
-    (p) => p.id?.toLowerCase() === lowerKey || p.name.toLowerCase() === lowerKey,
-  );
-  if (builtin) return builtin;
-
-  // 2. Partial match in built-in memory presets
-  const builtinPartial = BUILTIN_PRESETS.find((p) => p.name.toLowerCase().includes(lowerKey));
-  if (builtinPartial) return builtinPartial;
-
-  // 3. Scan disk if templates directory exists
-  if (!existsSync(TEMPLATES_DIR)) return null;
+  if (!lowerKey) return null;
+  ensureTemplatesDir();
+  if (!existsSync(TEMPLATES_DIR)) return BUILTIN_PRESETS.find((p) =>
+    p.id?.toLowerCase() === lowerKey || p.name.toLowerCase() === lowerKey) ?? null;
 
-  const directPath = join(TEMPLATES_DIR, `${key}.json`);
-  if (existsSync(directPath)) {
+  const directPath = templatePath(key);
+  if (directPath && existsSync(directPath)) {
     try {
       return JSON.parse(readFileSync(directPath, "utf-8"));
     } catch {
@@ -464,6 +449,7 @@ export function findTemplateByKeyOrName(key: string): TypesetConfig | null {
   // Scan all templates on disk
   const files = readdirSync(TEMPLATES_DIR).filter((f) => f.endsWith(".json"));
 
+  const templates: TypesetConfig[] = [];
   for (const file of files) {
     try {
       const content = readFileSync(join(TEMPLATES_DIR, file), "utf-8");
@@ -471,25 +457,19 @@ export function findTemplateByKeyOrName(key: string): TypesetConfig | null {
       if (tpl.id?.toLowerCase() === lowerKey || tpl.name.toLowerCase() === lowerKey) {
         return tpl;
       }
+      templates.push(tpl);
     } catch {
       // ignore
     }
   }
 
-  // Partial match by name
-  for (const file of files) {
-    try {
-      const content = readFileSync(join(TEMPLATES_DIR, file), "utf-8");
-      const tpl = JSON.parse(content) as TypesetConfig;
-      if (tpl.name.toLowerCase().includes(lowerKey)) {
-        return tpl;
-      }
-    } catch {
-      // ignore
-    }
-  }
+  // 精确匹配优先，名称模糊匹配复用已读取的模板。
+  return templates.find((tpl) => tpl.name.toLowerCase().includes(lowerKey)) ?? null;
+}
 
-  return null;
+// 模板标识只用作文件名，名称查询继续支持中文和模糊匹配。
+function templatePath(id: string): string | null {
+  return /^[a-zA-Z0-9_-]+$/.test(id) ? join(TEMPLATES_DIR, `${id}.json`) : null;
 }
 
 export const templatesRouter = new Hono();
@@ -609,7 +589,8 @@ templatesRouter.get("/resolve/:key", (c) => {
 templatesRouter.get("/:id", (c) => {
   ensureTemplatesDir();
   const id = c.req.param("id");
-  const filePath = join(TEMPLATES_DIR, `${id}.json`);
+  const filePath = templatePath(id);
+  if (!filePath) return c.json({ ok: false, error: "Invalid template id" }, 400);
 
   if (!existsSync(filePath)) {
     return c.json({ ok: false, error: "Template not found" }, 404);
@@ -628,13 +609,20 @@ templatesRouter.post("/", async (c) => {
     return c.json({ ok: false, error: "Template name is required" }, 400);
   }
 
+  try {
+    validateTemplateAssets(body.images);
+  } catch (error) {
+    return c.json({ ok: false, error: error instanceof Error ? error.message : "无效的模板素材" }, 400);
+  }
+
   const id = body.id || `tpl_${Date.now()}_${Math.random().toString(36).substring(2, 7)}`;
   const templateToSave: TypesetConfig = {
     ...body,
     id,
   };
 
-  const filePath = join(TEMPLATES_DIR, `${id}.json`);
+  const filePath = templatePath(id);
+  if (!filePath) return c.json({ ok: false, error: "Invalid template id" }, 400);
   writeFileSync(filePath, JSON.stringify(templateToSave, null, 2), "utf-8");
 
   return c.json({ ok: true, template: templateToSave });
@@ -644,7 +632,8 @@ templatesRouter.post("/", async (c) => {
 templatesRouter.delete("/:id", (c) => {
   ensureTemplatesDir();
   const id = c.req.param("id");
-  const filePath = join(TEMPLATES_DIR, `${id}.json`);
+  const filePath = templatePath(id);
+  if (!filePath) return c.json({ ok: false, error: "Invalid template id" }, 400);
 
   if (existsSync(filePath)) {
     unlinkSync(filePath);

package/src/server/routes/upload.ts

@@ -1,8 +1,9 @@
 import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
 import { Hono } from "hono";
+import { resolveDataDir } from "../../core/data-dir";
 
-const UPLOAD_DIR = join(process.cwd(), "data", "uploads");
+const UPLOAD_DIR = join(resolveDataDir(), "uploads");
 
 function ensureUploadDir(): void {
   if (!existsSync(UPLOAD_DIR)) {

package/src/web/App.tsx

@@ -1,5 +1,4 @@
 import React, { useEffect, useRef, useState } from "react";
-import { toPng } from "html-to-image";
 import { AuthModal } from "./components/AuthModal";
 import { CanvasViewport } from "./components/CanvasViewport";
 import { EditorSidebar } from "./components/EditorSidebar";
@@ -10,7 +9,9 @@ import { useAuth } from "./hooks/useAuth";
 import { useTypeset } from "./hooks/useTypeset";
 
 export const App: React.FC = () => {
+  const { adminKey, setAdminKey, isVerified } = useAuth();
   const {
+    error: templateError,
     aspectRatio,
     switchAspectRatio,
     config,
@@ -19,6 +20,9 @@ export const App: React.FC = () => {
     images,
     addImage,
     updateImage,
+    toggleImageBackground,
+    resetImageLayout,
+    backgroundImageIds,
     removeImage,
     moveImage,
     highlightWords,
@@ -30,9 +34,7 @@ export const App: React.FC = () => {
     updateSafeArea,
     loadTemplate,
     setConfig,
-  } = useTypeset();
-
-  const { adminKey, setAdminKey, isVerified } = useAuth();
+  } = useTypeset(adminKey, isVerified);
 
   // Default to Light Mode per user requirement
   const [themeMode, setThemeMode] = useState<"light" | "dark">(() => {
@@ -180,6 +182,9 @@ export const App: React.FC = () => {
     setIsExporting(true);
     try {
       const canvasElements = document.querySelectorAll<HTMLCanvasElement>("canvas.typeset-page");
+      if ([...canvasElements].some((canvas) => canvas.dataset.renderState !== "ready")) {
+        throw new Error("画布尚未完成绘制，请检查素材或稍后再导出");
+      }
       if (canvasElements.length > 0) {
         let exportSucceeded = true;
         for (let i = 0; i < canvasElements.length; i++) {
@@ -197,7 +202,6 @@ export const App: React.FC = () => {
           }
         }
         if (exportSucceeded) {
-          setIsExporting(false);
           return;
         }
       }
@@ -231,7 +235,7 @@ export const App: React.FC = () => {
       }
     } catch (err) {
       console.error("Export failed:", err);
-      alert("导出失败，请检查网络或后端服务连接");
+      alert(err instanceof Error ? err.message : "导出失败，请检查网络或后端服务连接");
     } finally {
       setIsExporting(false);
     }
@@ -257,6 +261,8 @@ export const App: React.FC = () => {
         onToggleThemeMode={toggleThemeMode}
       />
 
+      {templateError && <div role="alert" className="px-4 py-2 text-sm text-red-600">{templateError}</div>}
+
       {/* Main Workspace (3-column layout) */}
       <div className="flex flex-1 min-h-0 overflow-hidden relative">
         {/* Left: Content Editor Sidebar */}
@@ -265,6 +271,9 @@ export const App: React.FC = () => {
           onMarkdownChange={setMarkdown}
           images={images}
           onAddImage={addImage}
+          onToggleBackground={toggleImageBackground}
+          onResetImageLayout={resetImageLayout}
+          backgroundImageIds={backgroundImageIds}
           onUpdateImage={updateImage}
           onRemoveImage={removeImage}
           onMoveImage={moveImage}