@mlightcad/mtext-renderer 0.12.2 → 0.12.4

package/lib/font/fontManager.d.ts

@@ -51,9 +51,19 @@ export declare class FontManager {
     /**
      * 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}.
+     * 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.
@@ -179,9 +189,11 @@ export declare class FontManager {
      */
     requestFont(fontName: string): Promise<FontLoadStatus[]>;
     /**
-     * Fire-and-forget {@link requestFont} for each name (deduped per name).
+     * 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[]): void;
+    requestFonts(fontNames: readonly string[]): Promise<FontLoadStatus[]>;
     private normalizeFontName;
     /**
      * Parses a user-uploaded font file, registers it for rendering, and stores

package/lib/font/meshFont.d.ts

@@ -146,9 +146,10 @@ export declare class MeshFont extends BaseFont {
      * Gets the shape to display when a character is not found in the font.
      * Uses "?" as a replacement character.
      * @param size - The desired size of the not found shape
-     * @returns The shape data for the not found indicator
+     * @returns The shape data for the not found indicator, or undefined if "?"
+     * cannot be loaded from this font
      */
-    getNotFoundTextShape(size: number): MeshTextShape;
+    getNotFoundTextShape(size: number): MeshTextShape | undefined;
     /**
      * Estimates memory used by this mesh font (parsed opentype + glyphs + geometry cache).
      */

package/lib/renderer/mtext.d.ts

@@ -2,6 +2,21 @@ 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 — and, when awaiting, the
+     * configured default/symbol fallback chains — 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,13 +75,15 @@ export declare class MText extends THREE.Object3D {
      */
     dispose(): void;
     /**
-     * Draw the MText object. Schedules required fonts for background load and
-     * builds the object graph immediately with current fallbacks.
+     * Draw the MText object.
      *
-     * Does not await downloads — callers that need glyphs from newly loaded fonts
-     * should redraw after {@link FontManager.events.fontLoaded}.
+     * 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

@@ -24,7 +24,9 @@ export declare class MainThreadRenderer implements MTextBaseRenderer {
     /**
      * 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; otherwise they are awaited.
+     * {@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

@@ -17,6 +17,8 @@ export declare class UnifiedRenderer {
     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
      *
@@ -75,6 +77,11 @@ export declare class UnifiedRenderer {
      * 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

@@ -186,6 +186,10 @@ export declare class WebWorkerRenderer implements MTextBaseRenderer {
      * 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.2",
+  "version": "0.12.4",
   "description": "AutoCAD MText renderer based on Three.js",
   "license": "MIT",
   "author": "MLight Lee <mlight.lee@outlook.com>",