@mlightcad/mtext-renderer 0.12.0 → 0.12.2

package/lib/font/fontManager.d.ts

@@ -48,6 +48,12 @@ 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}.
+     */
+    lazyFontLoading: 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 +72,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 +112,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 +170,19 @@ 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[]>;
+    /**
+     * Fire-and-forget {@link requestFont} for each name (deduped per name).
+     */
+    requestFonts(fontNames: readonly string[]): void;
+    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/colorUtils.d.ts

@@ -1,10 +1,30 @@
+import { MTextColor } from '@mlightcad/mtext-parser';
 import { ColorSettings } from './types';
 export declare function resolveMTextColor(colorSettings: ColorSettings): number;
+/** Wire-format for an `MTextColor` carried on worker glyph payloads. */
+export interface SerializedMTextColor {
+    aci?: number | null;
+    rgbValue?: number | null;
+}
+/**
+ * Serializes an `MTextColor` for worker → main-thread transfer.
+ *
+ * Prefer this over baking only the resolved RGB: ACI 7 (canvas foreground) and
+ * ACI 255 (literal white) both resolve to `0xffffff` on a dark canvas, but only
+ * ACI 7 must invert when the background flips.
+ */
+export declare function serializeMTextColor(color: MTextColor): SerializedMTextColor;
+/** Revives a wire-format color into a real `MTextColor` instance. */
+export declare function deserializeMTextColor(serialized?: SerializedMTextColor | null): MTextColor | undefined;
 /**
  * Rebuild ColorSettings for a worker-deserialized glyph material.
  *
- * Worker meshes already carry the final resolved RGB in their serialized
- * material. When the entity base color is ByLayer, preserve that semantic only
- * for glyphs that match the layer fallback color.
+ * Prefer {@link serializedColor} when the worker attached the original segment
+ * color (ACI / RGB). Falling back to resolved RGB alone cannot distinguish
+ * ACI 7 from ACI 255.
+ *
+ * Without a serialized color, preserve ByLayer / ByBlock / entity ACI when the
+ * glyph RGB still matches the entity base resolution; otherwise bake RGB for
+ * true inline overrides.
  */
-export declare function buildWorkerMaterialColorSettings(base: ColorSettings, resolvedColor: number, baseByLayer: boolean): ColorSettings;
+export declare function buildWorkerMaterialColorSettings(base: ColorSettings, resolvedColor: number, baseByLayer: boolean, serializedColor?: SerializedMTextColor | null): ColorSettings;

package/lib/renderer/mtext.d.ts

@@ -60,7 +60,11 @@ 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. Schedules required fonts for background load and
+     * builds the object graph immediately with current fallbacks.
+     *
+     * Does not await downloads — callers that need glyphs from newly loaded fonts
+     * should redraw after {@link FontManager.events.fontLoaded}.
      */
     asyncDraw(): Promise<void>;
     /**

package/lib/worker/mainThreadRenderer.d.ts

@@ -22,8 +22,9 @@ 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; otherwise they are awaited.
      */
     asyncRenderMText(mtextContent: MTextData, textStyle: TextStyle, colorSettings?: ColorSettings): Promise<MTextObject>;
     /**

package/lib/worker/unifiedRenderer.d.ts

@@ -15,6 +15,8 @@ export declare class UnifiedRenderer {
     private defaultMode;
     private workerConfig;
     private webWorkerConfigured;
+    /** Last lazyFontLoading value pushed to the worker pool, if any. */
+    private workerLazyFontLoading;
     /**
      * Constructor
      *
@@ -68,6 +70,11 @@ 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>;
     /**
      * Returns font names for a predefined default-font preset.
      */

package/lib/worker/webWorkerRenderer.d.ts

@@ -113,6 +113,11 @@ interface SerializedChild {
         opacity: number;
         side?: number;
         linewidth?: number;
+        /** Original segment colour when the worker preserved ACI/RGB semantics. */
+        mtextColor?: {
+            aci?: number | null;
+            rgbValue?: number | null;
+        };
     };
     charBoxType?: CharBox['type'];
     lineLayouts?: Array<{
@@ -135,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
@@ -146,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.
      */
@@ -163,6 +182,10 @@ 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>;
     /**
      * Render MText in one worker and return serialized data asynchronously.
      */

package/package.json

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