feat: surface missed fonts from workers and keep session bookkeeping in sync (#60)

Report fontNotFound from findAndReplaceFont and forward worker misses to the main thread so hosts can drive missing-font UI, while replaceMissedFonts adopts the intersection of worker-filtered maps to avoid stale entries in worker-only mode.

Author: mlightcad

packages/mtext-renderer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlightcad/mtext-renderer",
-  "version": "0.12.6",
+  "version": "0.12.7",
   "description": "AutoCAD MText renderer based on Three.js",
   "license": "MIT",
   "author": "MLight Lee <mlight.lee@outlook.com>",

packages/mtext-renderer/src/font/fontManager.ts

@@ -561,29 +561,41 @@ export class FontManager {
 
   /**
    * Tries to find the specified font. If not found, uses a replacement font and returns its name.
+   *
+   * When the requested face is not loaded, the original name is recorded in
+   * {@link missedFonts} and {@link events.fontNotFound} is dispatched (once per
+   * miss cycle) so hosts can surface missing-font UI. Lazy loading still
+   * schedules {@link requestFont} for the face that will be fetched.
+   *
    * @param fontName - The font name to find
    * @returns The original font name if found, or the replacement font name if not found
    */
   findAndReplaceFont(fontName: string) {
     const requested = fontName == null ? '' : String(fontName)
+    const missName = this.stripFontFileExtension(requested)
     let font = this.loadedFontMap.get(requested.toLowerCase())
+    if (font == null && missName && missName !== requested) {
+      font = this.loadedFontMap.get(missName.toLowerCase())
+    }
     if (font == null) {
       const mappedFontName = this.fontMapping[requested]
       if (mappedFontName) {
         font = this.loadedFontMap.get(mappedFontName.toLowerCase())
         if (!font && this.lazyFontLoading) {
           void this.requestFont(mappedFontName)
         }
+        // Drawing still asked for the original face — report it even when a
+        // mapping supplies a replacement (do not also request the original).
+        this.recordMissedFonts(missName, false)
         // Prefer the mapped face even while it is still loading (legacy behavior).
         return mappedFontName
       }
     }
     if (font) {
       return requested
     }
-    if (this.lazyFontLoading && requested) {
-      void this.requestFont(requested)
-    }
+    // Not loaded and no mapping — record miss (schedules lazy load once).
+    this.recordMissedFonts(missName, true)
     // Prefer non-BIGFONT defaults as the primary face. BIGFONT SHX files (hztxt,
     // gbcbig, …) map ASCII to GBK fullwidth cells (0xA3xx), which makes Latin
     // runs much wider than AutoCAD and triggers false MTEXT wrapping when the
@@ -815,11 +827,96 @@ export class FontManager {
     return this.loadedFontMap.has(fontName.toLowerCase())
   }
 
+  /**
+   * Applies a missed-font report from another isolate (e.g. a web worker).
+   * Updates {@link missedFonts} and dispatches {@link events.fontNotFound} on
+   * first sighting. Does not call {@link requestFont} — the remote isolate owns loading.
+   */
+  applyRemoteFontNotFound(fontName: string, count: number = 1): void {
+    if (!fontName) {
+      return
+    }
+    const prev = this.missedFonts[fontName] ?? 0
+    this.missedFonts[fontName] = Math.max(prev, count)
+    if (prev === 0) {
+      this.events.fontNotFound.dispatch({
+        fontName,
+        count: this.missedFonts[fontName]
+      })
+    }
+  }
+
+  /**
+   * Clears a missed-font entry after a remote isolate reports the font loaded.
+   * Call before dispatching {@link events.fontLoaded} on the main thread.
+   */
+  applyRemoteFontLoaded(fontName: string): void {
+    if (!fontName) {
+      return
+    }
+    this.clearMissedFontEntry(fontName)
+    this.fontRequestFailed.delete(fontName.toLowerCase())
+  }
+
+  /**
+   * Replaces session-scoped missed-font bookkeeping without dispatching events.
+   * Entries for faces that are already loaded are dropped.
+   */
+  replaceMissedFonts(fonts: Record<string, number>): void {
+    const next: Record<string, number> = {}
+    for (const [name, count] of Object.entries(fonts ?? {})) {
+      if (!name || this.isFontLoaded(name)) {
+        continue
+      }
+      next[name] = count
+    }
+    this.missedFonts = next
+  }
+
+  /**
+   * Clears {@link missedFonts}. Does not unload faces or cancel in-flight loads.
+   */
+  clearMissedFonts(): void {
+    this.missedFonts = {}
+  }
+
+  /**
+   * Strips a trailing `.ttf` / `.otf` / `.woff` / `.shx` extension when present.
+   * Matches the normalization used by {@link getFontByName}.
+   */
+  private stripFontFileExtension(fontName: string): string {
+    if (!fontName) {
+      return fontName
+    }
+    const dotIndex = fontName.lastIndexOf('.')
+    if (
+      (dotIndex > 0 && dotIndex == fontName.length - 4) ||
+      dotIndex == fontName.length - 5
+    ) {
+      return fontName.substring(0, dotIndex)
+    }
+    return fontName
+  }
+
+  /**
+   * Removes {@link missedFonts} entries whose name matches `fontName`
+   * case-insensitively (CAD style names and loaded face names often differ in case).
+   */
+  private clearMissedFontEntry(fontName: string): void {
+    const key = fontName.toLowerCase()
+    for (const name of Object.keys(this.missedFonts)) {
+      if (name.toLowerCase() === key) {
+        delete this.missedFonts[name]
+      }
+    }
+  }
+
   /**
    * Records a font that was requested but not found
    * @param fontName - The name of the font that was not found
+   * @param scheduleLoad - When true (default), also {@link requestFont} on first miss if lazy loading is on
    */
-  private recordMissedFonts(fontName: string) {
+  private recordMissedFonts(fontName: string, scheduleLoad: boolean = true) {
     if (fontName) {
       if (!this.missedFonts[fontName]) {
         this.missedFonts[fontName] = 0
@@ -831,7 +928,7 @@ export class FontManager {
           fontName: fontName,
           count: this.missedFonts[fontName]
         })
-        if (this.lazyFontLoading) {
+        if (scheduleLoad && this.lazyFontLoading) {
           void this.requestFont(fontName)
         }
       }
@@ -892,7 +989,7 @@ export class FontManager {
     if (epoch !== this.loadEpoch || !this.isFontLoaded(fontName)) {
       return
     }
-    delete this.missedFonts[fontName]
+    this.clearMissedFontEntry(fontName)
     this.fontRequestFailed.delete(fontName.toLowerCase())
     this.events.fontLoaded.dispatch({
       fontName: fontName

packages/mtext-renderer/src/worker/mtextWorker.ts

@@ -24,6 +24,7 @@ interface WorkerMessage {
     | 'setLazyFontLoading'
     | 'setAwaitFontsBeforeDraw'
     | 'setFontUrl'
+    | 'setMissedFonts'
     | 'getAvailableFonts'
     | 'getMemoryStats'
   id: string
@@ -33,6 +34,7 @@ interface WorkerMessage {
     colorSettings?: unknown
     fonts?: string[]
     symbolFonts?: string[]
+    missedFonts?: Record<string, number>
     url?: string
     enabled?: boolean
   }
@@ -46,9 +48,11 @@ interface WorkerResponse {
     | 'setLazyFontLoading'
     | 'setAwaitFontsBeforeDraw'
     | 'setFontUrl'
+    | 'setMissedFonts'
     | 'getAvailableFonts'
     | 'getMemoryStats'
     | 'fontLoaded'
+    | 'fontNotFound'
     | 'error'
   id: string
   success: boolean
@@ -70,6 +74,16 @@ fontManager.events.fontLoaded.addEventListener(payload => {
   } as WorkerResponse)
 })
 
+// Forward missed-font reports so the main thread can drive status-bar / UI.
+fontManager.events.fontNotFound.addEventListener(payload => {
+  self.postMessage({
+    type: 'fontNotFound',
+    id: '',
+    success: true,
+    data: { fontName: payload?.fontName, count: payload?.count }
+  } as WorkerResponse)
+})
+
 // Handle messages from main thread
 self.addEventListener('message', async (event: MessageEvent<WorkerMessage>) => {
   const { type, id, data } = event.data
@@ -192,6 +206,20 @@ self.addEventListener('message', async (event: MessageEvent<WorkerMessage>) => {
         break
       }
 
+      case 'setMissedFonts': {
+        const { missedFonts } = (data ?? {}) as {
+          missedFonts?: Record<string, number>
+        }
+        fontManager.replaceMissedFonts(missedFonts ?? {})
+        self.postMessage({
+          type: 'setMissedFonts',
+          id,
+          success: true,
+          data: { missedFonts: { ...fontManager.missedFonts } }
+        } as WorkerResponse)
+        break
+      }
+
       case 'getAvailableFonts': {
         const fonts = await FontManager.instance.getAvailableFonts()
 

packages/mtext-renderer/src/worker/unifiedRenderer.ts

@@ -236,6 +236,24 @@ export class UnifiedRenderer {
     }
   }
 
+  /**
+   * Replaces session-scoped missed-font bookkeeping on the main thread and workers.
+   * When a worker pool is active, {@link WebWorkerRenderer.replaceMissedFonts}
+   * owns the final main-thread map (intersection of worker-filtered results).
+   */
+  async replaceMissedFonts(fonts: Record<string, number>): Promise<void> {
+    if (this.webWorkerRenderer) {
+      await this.webWorkerRenderer.replaceMissedFonts(fonts)
+      return
+    }
+    FontManager.instance.replaceMissedFonts(fonts)
+  }
+
+  /** Clears session-scoped missed-font bookkeeping on the main thread and workers. */
+  async clearMissedFonts(): Promise<void> {
+    await this.replaceMissedFonts({})
+  }
+
   /**
    * Returns font names for a predefined default-font preset.
    */

packages/mtext-renderer/src/worker/webWorkerRenderer.ts

@@ -111,12 +111,20 @@ type SetAwaitFontsBeforeDrawMessage = WorkerMessageBase<
   }
 >
 
+type SetMissedFontsMessage = WorkerMessageBase<
+  'setMissedFonts',
+  {
+    missedFonts: Record<string, number>
+  }
+>
+
 type WorkerMessageTyped =
   | RenderMessage
   | LoadFontsMessage
   | SetDefaultFontsMessage
   | SetLazyFontLoadingMessage
   | SetAwaitFontsBeforeDrawMessage
+  | SetMissedFontsMessage
   | SetFontUrlMessage
   | GetAvailableFontsMessage
   | GetMemoryStatsMessage
@@ -169,6 +177,13 @@ type SetAwaitFontsBeforeDrawResponse = WorkerResponseBase<
   }
 >
 
+type SetMissedFontsResponse = WorkerResponseBase<
+  'setMissedFonts',
+  {
+    missedFonts: Record<string, number>
+  }
+>
+
 /** Push notification from a worker when a font finishes lazy-loading. */
 type FontLoadedNotification = WorkerResponseBase<
   'fontLoaded',
@@ -177,16 +192,27 @@ type FontLoadedNotification = WorkerResponseBase<
   }
 >
 
+/** Push notification from a worker when a requested face is first recorded as missing. */
+type FontNotFoundNotification = WorkerResponseBase<
+  'fontNotFound',
+  {
+    fontName: string
+    count?: number
+  }
+>
+
 type WorkerResponseTyped =
   | RenderResponse
   | LoadFontsResponse
   | SetDefaultFontsResponse
   | SetLazyFontLoadingResponse
   | SetAwaitFontsBeforeDrawResponse
   | SetFontUrlResponse
+  | SetMissedFontsResponse
   | GetAvailableFontsResponse
   | GetMemoryStatsResponse
   | FontLoadedNotification
+  | FontNotFoundNotification
 
 // Serialized MText data from worker (JSON-based)
 interface SerializedMText {
@@ -348,6 +374,7 @@ export class WebWorkerRenderer implements MTextBaseRenderer {
         void this.syncFontToWorkerPool(fontName)
           .then(shouldDispatch => {
             if (shouldDispatch) {
+              FontManager.instance.applyRemoteFontLoaded(fontName)
               FontManager.instance.events.fontLoaded.dispatch({ fontName })
             }
           })
@@ -361,6 +388,17 @@ export class WebWorkerRenderer implements MTextBaseRenderer {
       return
     }
 
+    if (response.type === 'fontNotFound') {
+      const fontName = response.data?.fontName
+      if (fontName) {
+        FontManager.instance.applyRemoteFontNotFound(
+          fontName,
+          response.data?.count ?? 1
+        )
+      }
+      return
+    }
+
     const { id, success, data, error } = response
     const pendingRequest = this.pendingRequests.get(id)
 
@@ -617,6 +655,45 @@ export class WebWorkerRenderer implements MTextBaseRenderer {
     })
   }
 
+  /**
+   * Replaces session-scoped {@link FontManager.missedFonts} on every worker,
+   * then adopts the intersection of worker-filtered maps on the main thread.
+   *
+   * Workers drop faces they have already loaded; in worker-only mode the main
+   * isolate often has an empty {@link FontManager.loadedFontMap}, so the
+   * authoritative "still missing" set comes from the pool responses.
+   */
+  async replaceMissedFonts(fonts: Record<string, number>): Promise<void> {
+    const results = await this.sendMessageToAllWorkers<
+      SetMissedFontsMessage,
+      SetMissedFontsResponse
+    >({
+      type: 'setMissedFonts',
+      data: { missedFonts: { ...(fonts ?? {}) } }
+    })
+
+    if (results.length === 0) {
+      FontManager.instance.replaceMissedFonts(fonts ?? {})
+      return
+    }
+
+    const intersected: Record<string, number> = {}
+    for (const name of Object.keys(results[0]?.missedFonts ?? {})) {
+      if (!results.every(r => (r?.missedFonts?.[name] ?? 0) > 0)) {
+        continue
+      }
+      intersected[name] = Math.max(
+        ...results.map(r => r?.missedFonts?.[name] ?? 0)
+      )
+    }
+    FontManager.instance.replaceMissedFonts(intersected)
+  }
+
+  /** Clears {@link FontManager.missedFonts} on the main thread and every worker. */
+  async clearMissedFonts(): Promise<void> {
+    await this.replaceMissedFonts({})
+  }
+
   /**
    * Render MText in one worker and return serialized data asynchronously.
    */