@akairos/typeset-studio 0.2.2 → 0.2.3

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 {
@@ -482,6 +467,11 @@ export function findTemplateByKeyOrName(key: string): TypesetConfig | null {
   return templates.find((tpl) => tpl.name.toLowerCase().includes(lowerKey)) ?? 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();
 
 // List all templates
@@ -599,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);
@@ -618,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 });
@@ -634,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

@@ -9,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,
@@ -18,6 +20,9 @@ export const App: React.FC = () => {
     images,
     addImage,
     updateImage,
+    toggleImageBackground,
+    resetImageLayout,
+    backgroundImageIds,
     removeImage,
     moveImage,
     highlightWords,
@@ -29,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">(() => {
@@ -179,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++) {
@@ -229,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);
     }
@@ -255,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 */}
@@ -263,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}

package/src/web/components/CanvasViewport.tsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useRef } from "react";
+import React, { useEffect, useRef, useState } from "react";
 import { LayoutGrid, Rows, ZoomIn } from "lucide-react";
 import { drawPageToContext } from "../../core/canvas-draw";
 import { CanvasSpec, FlowPage, TypesetConfig, TypesetResult } from "../../core/types";
@@ -19,6 +19,7 @@ const CanvasCard: React.FC<CanvasCardProps> = ({
   zoom,
 }) => {
   const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const [paintError, setPaintError] = useState<string | null>(null);
 
   useEffect(() => {
     const canvas = canvasRef.current;
@@ -26,69 +27,82 @@ const CanvasCard: React.FC<CanvasCardProps> = ({
     const ctx = canvas.getContext("2d");
     if (!ctx) return;
 
+    canvas.dataset.renderState = "loading";
+    setPaintError(null);
     let cancelled = false;
+    const controller = new AbortController();
 
     const getImage = (src: string) => {
       if (!src) return Promise.resolve(null);
       return new Promise((resolve) => {
         const img = new Image();
-        img.crossOrigin = "anonymous";
-        img.onload = () => {
-          if (!cancelled) resolve(img);
+        let fallback: HTMLImageElement | undefined;
+        const finish = (image: HTMLImageElement | null) => {
+          controller.signal.removeEventListener("abort", abort);
+          img.onload = img.onerror = null;
+          if (fallback) fallback.onload = fallback.onerror = null;
+          resolve(image);
         };
+        const abort = () => finish(null);
+        if (controller.signal.aborted) { finish(null); return; }
+        controller.signal.addEventListener("abort", abort, { once: true });
+        img.crossOrigin = "anonymous";
+        img.onload = () => finish(img);
         img.onerror = () => {
-          const img2 = new Image();
-          img2.onload = () => {
-            if (!cancelled) resolve(img2);
-          };
-          img2.onerror = () => {
-            if (!cancelled) resolve(null);
-          };
-          img2.src = src;
+          fallback = new Image();
+          fallback.onload = () => finish(fallback!);
+          fallback.onerror = () => finish(null);
+          fallback.src = src;
         };
         img.src = src;
       });
     };
 
-    const paint = () => {
-      if (cancelled || !canvas) return;
-      drawPageToContext(ctx, {
-        page,
-        spec,
-        config,
-        totalPageCount,
-        getImage,
-        isServer: false,
+    // 每次绘制使用独立缓冲画布，只提交当前代的完整结果。
+    const paint = async () => {
+      const buffer = document.createElement("canvas");
+      buffer.width = spec.width;
+      buffer.height = spec.height;
+      const bufferContext = buffer.getContext("2d");
+      if (!bufferContext) return;
+      await drawPageToContext(bufferContext, {
+        page, spec, config, totalPageCount, getImage, isServer: false,
       });
+      if (!cancelled) {
+        ctx.clearRect(0, 0, spec.width, spec.height);
+        ctx.drawImage(buffer, 0, 0);
+        canvas.dataset.renderState = "ready";
+      }
     };
-
-    paint();
-
-    // Trigger re-render as soon as external web fonts (Google Fonts, Wenkai) finish loading
-    if (typeof document !== "undefined" && (document as any).fonts) {
-      (document as any).fonts.ready.then(() => {
-        paint();
-      });
-    }
+    paint().catch((error) => {
+      if (cancelled) return;
+      canvas.dataset.renderState = "error";
+      ctx.clearRect(0, 0, spec.width, spec.height);
+      setPaintError(error instanceof Error ? error.message : "画布绘制失败");
+    });
 
     return () => {
       cancelled = true;
+      controller.abort();
     };
   }, [page, spec, config, totalPageCount]);
 
   return (
-    <canvas
-      id={`typeset-page-${page.pageNumber}`}
-      ref={canvasRef}
-      width={spec.width}
-      height={spec.height}
-      className="typeset-page absolute top-0 left-0 border border-[#e0e0e0] dark:border-[#222222] shadow-sm select-none"
-      style={{
-        width: spec.width * zoom,
-        height: spec.height * zoom,
-        backgroundColor: config.theme.bgColor,
-      }}
-    />
+    <>
+      <canvas
+        id={`typeset-page-${page.pageNumber}`}
+        ref={canvasRef}
+        width={spec.width}
+        height={spec.height}
+        className="typeset-page absolute top-0 left-0 border border-[#e0e0e0] dark:border-[#222222] shadow-sm select-none"
+        style={{
+          width: spec.width * zoom,
+          height: spec.height * zoom,
+          backgroundColor: config.theme.bgColor,
+        }}
+      />
+      {paintError && <div role="alert" className="absolute inset-0 flex items-center justify-center bg-white/90 p-4 text-sm text-red-600">{paintError}</div>}
+    </>
   );
 };
 

package/src/web/components/EditorSidebar.tsx

@@ -28,6 +28,9 @@ interface EditorSidebarProps {
   highlightWords: string[];
   onHighlightWordsChange: (words: string[]) => void;
   adminKey: string;
+  onToggleBackground: (id: string, enabled: boolean) => void;
+  onResetImageLayout: (id: string) => void;
+  backgroundImageIds: string[];
 }
 
 export const EditorSidebar: React.FC<EditorSidebarProps> = ({
@@ -35,6 +38,9 @@ export const EditorSidebar: React.FC<EditorSidebarProps> = ({
   onMarkdownChange,
   images,
   onAddImage,
+  onToggleBackground,
+  onResetImageLayout,
+  backgroundImageIds,
   onUpdateImage,
   onRemoveImage,
   onMoveImage,
@@ -342,6 +348,35 @@ export const EditorSidebar: React.FC<EditorSidebarProps> = ({
                     </button>
                   </div>
 
+                  <div className="flex flex-col gap-2 text-[11px]">
+                    <label className="flex items-center gap-2">
+                      <input type="checkbox" checked={img.templateAssetKey !== undefined} onChange={(event) => onUpdateImage(img.id, {
+                        templateAssetKey: event.target.checked ? `asset_${img.id.replace(/[^a-zA-Z0-9_-]/g, "_")}` : undefined,
+                        repeatEveryPage: false,
+                      })} />
+                      固定模板素材
+                    </label>
+                    {img.templateAssetKey !== undefined && <>
+                      <label className="flex flex-col gap-1">素材标识
+                        <input aria-label="素材标识" value={img.templateAssetKey} onChange={(event) => onUpdateImage(img.id, { templateAssetKey: event.target.value })}
+                          className="w-full bg-white dark:bg-[#181818] border border-[#d4d4d4] dark:border-[#262626] rounded px-1.5 py-1" />
+                      </label>
+                      {images.some((other) => other.id !== img.id && other.templateAssetKey === img.templateAssetKey) &&
+                        <span role="alert" className="text-red-600">素材标识不能重复</span>}
+                      <label className="flex items-center gap-2">
+                        <input type="checkbox" disabled={!img.isAbsolute} checked={Boolean(img.isAbsolute && img.repeatEveryPage)} onChange={(event) => onUpdateImage(img.id, { repeatEveryPage: event.target.checked })} />
+                        每页重复
+                      </label>
+                      {!img.isAbsolute && <span className="text-[#888888]">每页重复仅支持自由图层，避免阻塞文字排版。</span>}
+                      <span className="text-[#888888]">默认保留此图，仅按素材标识明确替换。</span>
+                    </>}
+                    {img.isAbsolute && <label className="flex items-center gap-2">
+                      <input type="checkbox" checked={backgroundImageIds.includes(img.id)} onChange={(event) => onToggleBackground(img.id, event.target.checked)} />
+                      设为整页背景
+                    </label>}
+                    <button type="button" onClick={() => onResetImageLayout(img.id)} title="恢复上传或应用模板时的尺寸、位置和图层设置" className="rounded border border-[#d4d4d4] dark:border-[#333333] px-2 py-1.5 hover:bg-[#eeeeee] dark:hover:bg-[#222222]">重置布局</button>
+                  </div>
+
                   {!img.isAbsolute ? (
                     <>
                       {/* Flow Settings */}

package/src/web/components/TemplateModal.tsx

@@ -1,5 +1,6 @@
 import React, { useEffect, useState } from "react";
 import { Check, FolderPlus, Trash2, X, Sparkles, Star } from "lucide-react";
+import { validateTemplateAssets } from "../../core/template";
 import { TemplateSlot, TypesetConfig } from "../../core/types";
 
 interface TemplateModalProps {
@@ -13,6 +14,8 @@ interface TemplateModalProps {
 interface SlotsResponse {
   ok: boolean;
   account: string;
+  message?: string;
+  error?: string;
   slots: {
     article_cover?: { id: string; template?: TypesetConfig };
     newspic_cover?: { id: string; template?: TypesetConfig };
@@ -41,13 +44,14 @@ export const TemplateModal: React.FC<TemplateModalProps> = ({
 
   const fetchSlots = async (acc = account) => {
     try {
-      const res = await fetch(`/api/templates/slots?account=${encodeURIComponent(acc)}`);
+      const res = await fetch(`/api/templates/slots?account=${encodeURIComponent(acc)}`, { headers: { "x-admin-key": adminKey } });
       const data: SlotsResponse = await res.json();
+      if (!res.ok || !data.ok) throw new Error(data.message || data.error || "获取槽位失败");
       if (data.ok && data.slots) {
         setSlotsData(data.slots);
       }
-    } catch {
-      // ignore
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "模板请求失败");
     }
   };
 
@@ -62,11 +66,12 @@ export const TemplateModal: React.FC<TemplateModalProps> = ({
         body: JSON.stringify({ slot, templateId, account }),
       });
       const data = await res.json();
+      if (!res.ok || !data.ok) throw new Error(data.message || data.error || "设置默认模板失败");
       if (data.ok) {
         await fetchSlots(account);
       }
-    } catch {
-      // ignore
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "模板请求失败");
     }
   };
 
@@ -78,7 +83,7 @@ export const TemplateModal: React.FC<TemplateModalProps> = ({
         headers: adminKey ? { "x-admin-key": adminKey } : {},
       });
       const data = await res.json();
-      if (data.ok && Array.isArray(data.templates)) {
+      if (res.ok && data.ok && Array.isArray(data.templates)) {
         setTemplates(data.templates);
       } else {
         setError(data.message || "获取模板失败，请检查密钥");
@@ -97,12 +102,13 @@ export const TemplateModal: React.FC<TemplateModalProps> = ({
       setTemplateName(currentConfig.name ? `${currentConfig.name} 副本` : "我的自定义模板");
       setSaveSlot(currentConfig.aspectRatio === "wechat-cover-2.35" ? "article_cover" : "newspic_content");
     }
-  }, [isOpen, account]);
+  }, [isOpen, account, adminKey]);
 
   const handleSave = async () => {
     if (!templateName.trim()) return;
     setIsSaving(true);
     try {
+      validateTemplateAssets(currentConfig.images);
       const tplToSave: TypesetConfig = {
         ...currentConfig,
         id: undefined, // auto generate
@@ -120,14 +126,14 @@ export const TemplateModal: React.FC<TemplateModalProps> = ({
       });
 
       const data = await res.json();
-      if (data.ok) {
+      if (res.ok && data.ok) {
         await fetchTemplates();
         await fetchSlots(account);
       } else {
-        setError(data.message || "保存模板失败");
+        setError(data.message || data.error || "保存模板失败");
       }
-    } catch {
-      setError("保存模板请求异常");
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "保存模板请求异常");
     } finally {
       setIsSaving(false);
     }
@@ -135,14 +141,16 @@ export const TemplateModal: React.FC<TemplateModalProps> = ({
 
   const handleDelete = async (id: string) => {
     try {
-      await fetch(`/api/templates/${id}`, {
+      const res = await fetch(`/api/templates/${encodeURIComponent(id)}`, {
         method: "DELETE",
         headers: adminKey ? { "x-admin-key": adminKey } : {},
       });
+      const data = await res.json();
+      if (!res.ok || !data.ok) throw new Error(data.message || data.error || "删除模板失败");
       setTemplates((prev) => prev.filter((t) => t.id !== id));
       await fetchSlots(account);
-    } catch {
-      // ignore
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "模板请求失败");
     }
   };
 

package/src/web/hooks/image-layout.ts

@@ -0,0 +1,31 @@
+import type { FlowImage, TypesetConfig } from "../../core/types";
+import { getCanvasSpec } from "../../core/geometry";
+
+export type ImageLayout = Pick<FlowImage, "x" | "y" | "width" | "height" | "isAbsolute" | "layoutPreset" | "pageIndex" | "zIndex" | "rotate" | "opacity" | "borderRadius" | "captionHeight">;
+
+// 仅保存布局，恢复时不覆盖图片来源、说明和固定素材标识。
+export function snapshotImageLayout(image: FlowImage): ImageLayout {
+  return {
+    x: image.x, y: image.y, width: image.width, height: image.height,
+    isAbsolute: image.isAbsolute, layoutPreset: image.layoutPreset, pageIndex: image.pageIndex,
+    zIndex: image.zIndex, rotate: image.rotate, opacity: image.opacity,
+    borderRadius: image.borderRadius, captionHeight: image.captionHeight,
+  };
+}
+
+// 切回绕排或取消固定素材时关闭重复，防止图片占满每一页。
+export function restoreImageLayout(image: FlowImage, layout: Partial<FlowImage>): FlowImage {
+  const restored = { ...image, ...layout };
+  if (!restored.isAbsolute || !restored.templateAssetKey) restored.repeatEveryPage = false;
+  return restored;
+}
+
+// 背景使用整张画布，旋转归零，取消后由布局快照还原。
+export function backgroundImageLayout(config: TypesetConfig): Partial<FlowImage> {
+  const spec = getCanvasSpec(config.aspectRatio);
+  return {
+    isAbsolute: true, layoutPreset: "custom", zIndex: 0, rotate: 0, borderRadius: 0, captionHeight: 0,
+    x: -config.algorithm.safeArea.left, y: -config.algorithm.safeArea.top,
+    width: spec.width, height: spec.height,
+  };
+}

package/src/web/hooks/useLocalFonts.ts

@@ -14,6 +14,7 @@ export function useLocalFonts() {
       if (!data.ok || !Array.isArray(data.fonts)) return;
 
       setFonts(data.fonts);
+      let added = false;
 
       // Register newly discovered fonts dynamically in browser DOM via FontFace API
       if (typeof window !== "undefined" && "FontFace" in window && (document as any).fonts) {
@@ -21,22 +22,30 @@ export function useLocalFonts() {
           try {
             // Check if font is already added
             let alreadyAdded = false;
+            const existing: FontFace[] = [];
             (document.fonts as any).forEach((f: any) => {
               if (f.family === font.family || f.family === `"${font.family}"`) {
                 alreadyAdded = true;
+                existing.push(f);
               }
             });
 
+            if (refresh) {
+              existing.forEach((face) => document.fonts.delete(face));
+              alreadyAdded = false;
+            }
             if (!alreadyAdded) {
-              const fontFace = new FontFace(font.family, `url(${font.url})`);
+              const fontFace = new FontFace(font.family, `url(${font.url}${refresh ? `?v=${Date.now()}` : ""})`);
               const loaded = await fontFace.load();
               (document.fonts as any).add(loaded);
+              added = true;
             }
           } catch (err) {
             console.warn(`[useLocalFonts] Failed to load web font ${font.family}:`, err);
           }
         }
       }
+      if (added) window.dispatchEvent(new Event("typeset-fonts-loaded"));
     } catch (err) {
       console.warn("[useLocalFonts] Failed to fetch local fonts:", err);
     } finally {