@mlightcad/mtext-renderer 0.12.1 → 0.12.3

package/lib/font/fontManager.d.ts

@@ -48,6 +48,22 @@ export declare class FontManager {
     missedFonts: Record<string, number>;
     /** Flag to enable/disable font caching */
     enableFontCache: boolean;
+    /**
+     * When true (default), missing fonts are fetched/parsed in the background
+     * via {@link requestFont} instead of requiring an open-time preload.
+     * Drawing continues with temporary fallbacks until {@link events.fontLoaded}
+     * unless {@link awaitFontsBeforeDraw} (or a per-draw override) waits first.
+     */
+    lazyFontLoading: boolean;
+    /**
+     * When true, {@link MText.asyncDraw} / {@link Shape.asyncDraw} wait for fonts
+     * referenced by the content and style to finish loading before building
+     * geometry. Useful with {@link lazyFontLoading} when callers prefer a single
+     * draw pass instead of redrawing on {@link events.fontLoaded}.
+     *
+     * Has no effect when {@link lazyFontLoading} is false (draw already awaits).
+     */
+    awaitFontsBeforeDraw: boolean;
     /**
      * Default fonts to use when a requested font is not found or lacks a glyph.
      * Insertion order is preserved; earlier entries are tried first.
@@ -66,6 +82,18 @@ export declare class FontManager {
         /** Event triggered when a font is successfully loaded */
         fontLoaded: EventManager<FontManagerEventArgs>;
     };
+    /** In-flight {@link requestFont} promises keyed by normalized font name. */
+    private fontRequestInFlight;
+    /**
+     * Fonts whose latest {@link requestFont} finished without registering the
+     * face. Prevents per-glyph retry storms until {@link release} clears state.
+     */
+    private fontRequestFailed;
+    /**
+     * Bumped by full {@link release} so in-flight loads that complete after a
+     * release do not re-register fonts into a cleared manager.
+     */
+    private loadEpoch;
     private constructor();
     /**
      * Gets the singleton instance of the FontManager
@@ -94,7 +122,7 @@ export declare class FontManager {
      * ```ts
      * FontManager.instance.setDefaultFonts('r12r14')
      * FontManager.instance.setDefaultFonts(['hztxt', 'simsun', 'gdt'])
-     * FontManager.instance.setDefaultFonts('simkai')
+     * FontManager.instance.setDefaultFonts('simsun')
      * ```
      */
     setDefaultFonts(fonts: DefaultFontsPreset): void;
@@ -152,6 +180,21 @@ export declare class FontManager {
      * @returns Promise that resolves to an array of font load statuses
      */
     loadFontsByNames(names: string | readonly string[]): Promise<FontLoadStatus[]>;
+    /**
+     * Schedules a non-blocking load for a font that is not yet in memory.
+     *
+     * Concurrent callers for the same name share one in-flight promise.
+     * Already-loaded fonts resolve immediately. Safe to call from sync draw
+     * paths — do not await from the hot glyph loop.
+     */
+    requestFont(fontName: string): Promise<FontLoadStatus[]>;
+    /**
+     * Requests each font name via {@link requestFont} (deduped per name).
+     * Callers may ignore the returned promise for fire-and-forget loads, or
+     * await it when they need fonts before drawing.
+     */
+    requestFonts(fontNames: readonly string[]): Promise<FontLoadStatus[]>;
+    private normalizeFontName;
     /**
      * Parses a user-uploaded font file, registers it for rendering, and stores
      * it in IndexedDB when {@link enableFontCache} is true.

package/lib/font/shxFont.d.ts

@@ -102,10 +102,35 @@ export declare class ShxFont extends BaseFont {
      * Clears layout/code caches and disposes retained shape geometries.
      */
     dispose(): void;
+    /**
+     * Sentinel returned by {@link getCode} when `char` has no representation
+     * in this BIGFONT's legacy encoding. Never a real SHX/BIGFONT code point
+     * (those are non-negative), so callers can distinguish "cannot encode"
+     * from "encodes to some rarely-used code".
+     */
+    private static readonly NOT_ENCODABLE;
     /**
      * Resolves the internal SHX character code for a given Unicode character.
+     *
+     * For BIGFONT fonts, `char` is converted through a legacy encoding (e.g.
+     * GBK) via `iconv-lite`. Characters outside that encoding's repertoire
+     * (math/symbol glyphs like the diameter sign, U+2205) are not rejected by
+     * `iconv.encode` — it silently substitutes a replacement byte (commonly
+     * ASCII `?`, 0x3F). Left unchecked, that byte resolves to the BIGFONT's
+     * own, perfectly valid `?` glyph, so `hasChar`/`getCharShape` report a
+     * false positive: the caller believes this font renders the character,
+     * when it actually renders an unrelated question mark. That masked the
+     * real GDT/symbol-font fallback for diameter dimension text stored as a
+     * literal U+2205 (mlightcad/cad-viewer#473) — the correct glyph exists in
+     * `amgdt.shx`, but the fallback chain in {@link FontManager} never got a
+     * chance because this font's bogus "yes" won first.
+     *
+     * A decode-of-the-encoded-bytes round trip catches this: encoding is lossy
+     * exactly when it can't recover the original character.
+     *
      * @param char - The input character.
-     * @returns The internal SHX code used for lookup.
+     * @returns The internal SHX code used for lookup, or {@link NOT_ENCODABLE}
+     * when `char` cannot be represented in this font's encoding.
      */
     private getCode;
 }

package/lib/renderer/mtext.d.ts

@@ -2,6 +2,20 @@ import { FontManager } from '../font';
 import { StyleManager } from './styleManager';
 import { ColorSettings, MTextData, MTextLayout, ShapeData, TextStyle } from './types';
 import * as THREE from 'three';
+/**
+ * Options for {@link MText.asyncDraw} / {@link Shape.asyncDraw}.
+ */
+export interface MTextDrawOptions {
+    /**
+     * Wait for fonts referenced by the content/style to finish loading before
+     * building geometry.
+     *
+     * Defaults to `true` when {@link FontManager.lazyFontLoading} is false, or
+     * when {@link FontManager.awaitFontsBeforeDraw} is true. Otherwise fonts are
+     * scheduled in the background and the first draw may use fallbacks.
+     */
+    awaitFonts?: boolean;
+}
 /**
  * Represents an AutoCAD MText object in Three.js.
  * This class extends THREE.Object3D to provide MText rendering capabilities,
@@ -60,9 +74,15 @@ export declare class MText extends THREE.Object3D {
      */
     dispose(): void;
     /**
-     * Draw the MText object. This method loads required fonts on demand and builds the object graph.
+     * Draw the MText object.
+     *
+     * With {@link FontManager.lazyFontLoading} and without awaiting fonts, this
+     * schedules downloads in the background and builds geometry immediately with
+     * current fallbacks — redraw after {@link FontManager.events.fontLoaded} if
+     * you need the final faces. Pass `{ awaitFonts: true }` or set
+     * {@link FontManager.awaitFontsBeforeDraw} to wait for referenced fonts first.
      */
-    asyncDraw(): Promise<void>;
+    asyncDraw(options?: MTextDrawOptions): Promise<void>;
     /**
      * Draw the MText object. This method assumes that fonts needed are loaded. If font needed
      * not found, the default font will be used.

package/lib/renderer/shape.d.ts

@@ -1,4 +1,5 @@
 import { FontManager } from '../font';
+import { MTextDrawOptions } from './mtext';
 import { StyleManager } from './styleManager';
 import { ColorSettings, MTextLayout, ShapeData, TextStyle } from './types';
 import * as THREE from 'three';
@@ -18,7 +19,7 @@ export declare class Shape extends THREE.Object3D {
     get styleManager(): StyleManager;
     get textStyle(): TextStyle;
     createLayoutData(): MTextLayout;
-    asyncDraw(): Promise<void>;
+    asyncDraw(options?: MTextDrawOptions): Promise<void>;
     syncDraw(): void;
     private createPlacementData;
     private getFontName;

package/lib/worker/mainThreadRenderer.d.ts

@@ -22,8 +22,11 @@ export declare class MainThreadRenderer implements MTextBaseRenderer {
      */
     setFontUrl(value: string): Promise<void>;
     /**
-     * Render MText directly in the main thread asynchronously. It will ensure that default font
-     * is loaded. And fonts needed in mtext are loaded on demand.
+     * Render MText directly in the main thread asynchronously. Fonts referenced by
+     * the text/style are scheduled via {@link FontManager.requestFonts} when
+     * {@link FontManager.lazyFontLoading} is enabled (unless
+     * {@link FontManager.awaitFontsBeforeDraw} waits for them first); otherwise
+     * they are awaited.
      */
     asyncRenderMText(mtextContent: MTextData, textStyle: TextStyle, colorSettings?: ColorSettings): Promise<MTextObject>;
     /**

package/lib/worker/unifiedRenderer.d.ts

@@ -15,6 +15,10 @@ export declare class UnifiedRenderer {
     private defaultMode;
     private workerConfig;
     private webWorkerConfigured;
+    /** Last lazyFontLoading value pushed to the worker pool, if any. */
+    private workerLazyFontLoading;
+    /** Last awaitFontsBeforeDraw value pushed to the worker pool, if any. */
+    private workerAwaitFontsBeforeDraw;
     /**
      * Constructor
      *
@@ -68,6 +72,16 @@ export declare class UnifiedRenderer {
      * Sets the default font fallback chain on the active renderer and workers.
      */
     setDefaultFonts(fonts: DefaultFontsPreset | string | readonly string[]): Promise<void>;
+    /**
+     * Mirrors {@link FontManager.lazyFontLoading} onto the main thread and any
+     * existing worker pool.
+     */
+    setLazyFontLoading(enabled: boolean): Promise<void>;
+    /**
+     * Mirrors {@link FontManager.awaitFontsBeforeDraw} onto the main thread and
+     * any existing worker pool.
+     */
+    setAwaitFontsBeforeDraw(enabled: boolean): Promise<void>;
     /**
      * Returns font names for a predefined default-font preset.
      */

package/lib/worker/webWorkerRenderer.d.ts

@@ -140,6 +140,15 @@ export declare class WebWorkerRenderer implements MTextBaseRenderer {
     private readyPromise;
     private isInitialized;
     private defaultStyleManager;
+    /**
+     * Fonts known to be present in every worker after an explicit loadFonts or
+     * after a lazy fontLoaded was fan-out to the full pool.
+     */
+    private poolSyncedFonts;
+    /** In-flight pool-wide font syncs keyed by normalized font name. */
+    private poolFontSyncInFlight;
+    /** Fonts already forwarded as main-thread fontLoaded for this pool lifetime. */
+    private poolFontLoadedDispatched;
     constructor(config?: WebWorkerRendererConfig);
     /**
      * Used to manage materials used by texts
@@ -151,6 +160,11 @@ export declare class WebWorkerRenderer implements MTextBaseRenderer {
      * Handles messages coming from any worker.
      */
     private handleWorkerMessage;
+    /**
+     * Ensures every worker has `fontName`, then returns whether the main thread
+     * should emit {@link FontManager.events.fontLoaded} for this name.
+     */
+    private syncFontToWorkerPool;
     /**
      * Attaches message and error handlers to a worker.
      */
@@ -168,6 +182,14 @@ export declare class WebWorkerRenderer implements MTextBaseRenderer {
      * Syncs the default font fallback chain to all workers.
      */
     setDefaultFonts(fonts: readonly string[], symbolFonts: readonly string[]): Promise<void>;
+    /**
+     * Mirrors {@link FontManager.lazyFontLoading} into every worker isolate.
+     */
+    setLazyFontLoading(enabled: boolean): Promise<void>;
+    /**
+     * Mirrors {@link FontManager.awaitFontsBeforeDraw} into every worker isolate.
+     */
+    setAwaitFontsBeforeDraw(enabled: boolean): Promise<void>;
     /**
      * Render MText in one worker and return serialized data asynchronously.
      */

package/package.json

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