@mlightcad/mtext-renderer 0.10.15 → 0.11.0

package/lib/font/defaultFontLoader.d.ts

@@ -1,7 +1,7 @@
 import { FontInfo, FontLoader, FontLoadStatus } from './fontLoader';
 /**
  * Default implementation of the FontLoader interface.
- * This class provides font loading functionality using [this font repository](https://mlightcad.gitlab.io/cad-data/fonts/).
+ * This class provides font loading functionality using [this font repository](https://cdn.jsdelivr.net/gh/mlightcad/cad-data/fonts/).
  * It loads font metadata from a JSON file and provides access to available fonts.
  */
 export declare class DefaultFontLoader implements FontLoader {
@@ -42,7 +42,7 @@ export declare class DefaultFontLoader implements FontLoader {
      * @param fontNames - Array of font names to load
      * @returns Promise that resolves to an array of FontLoadStatus objects
      */
-    load(fontNames: string[]): Promise<FontLoadStatus[]>;
+    load(fontNames: readonly string[]): Promise<FontLoadStatus[]>;
     /**
      * Build one font map. The key is font name. The value is font info.
      */

package/lib/font/defaultFontsPresets.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Preset names for common AutoCAD-era default font fallback chains.
+ *
+ * Third-party DWG viewers often mirror fonts that were widely bundled or
+ * referenced during the AutoCAD R12/R14 era, then simplified in later releases.
+ */
+export type DefaultFontsPreset = 
+/** SHX symbol fonts plus mesh CJK fallback (library default). */
+'minimal'
+/** Classic R12/R14 stack: SHX basics, GB big font, then mesh CJK and AMGDT. */
+ | 'r12r14'
+/** Later-era stack: hztxt big font with simsun and AMGDT symbols. */
+ | 'modern'
+/** Western SHX fonts plus simsun and AMGDT; no CJK-specific SHX big fonts. */
+ | 'international'
+/** Broad CJK coverage: both GB big-font SHX files plus common mesh fallbacks. */
+ | 'cjk';
+/**
+ * Predefined text-font fallback chains (primary / big-font substitutes and CJK
+ * mesh fallbacks). Symbol fonts such as `amgdt` are configured separately via
+ * {@link SYMBOL_FONTS_PRESETS}.
+ */
+export declare const DEFAULT_FONTS_PRESETS: Record<DefaultFontsPreset, readonly string[]>;
+/**
+ * GDT / SHX symbol-font chains used for AutoCAD control codes (`%%c`, `%%d`,
+ * `%%p`, `%%130`, etc.). Earlier entries are tried first.
+ */
+export declare const SYMBOL_FONTS_PRESETS: Record<DefaultFontsPreset, readonly string[]>;
+export declare function isDefaultFontsPreset(value: string): value is DefaultFontsPreset;

package/lib/font/fontLoader.d.ts

@@ -44,7 +44,7 @@ export interface FontLoader {
      * @param fontNames - Array of font names to load
      * @returns Promise that resolves to an array of FontLoadStatus objects indicating the load status of each font
      */
-    load(fontNames: string[]): Promise<FontLoadStatus[]>;
+    load(fontNames: readonly string[]): Promise<FontLoadStatus[]>;
     /**
      * Retrieves information about all available fonts in the system
      * @returns Promise that resolves to an array of FontInfo objects containing details about available fonts

package/lib/font/fontManager.d.ts

@@ -1,6 +1,7 @@
 import { EventManager } from '../common';
 import { BaseFont } from './baseFont';
 import { BaseTextShape } from './baseTextShape';
+import { DefaultFontsPreset } from './defaultFontsPresets';
 import { FontType } from './font';
 import { FontInfo, FontLoader, FontLoadStatus } from './fontLoader';
 /**
@@ -45,8 +46,17 @@ export declare class FontManager {
     missedFonts: Record<string, number>;
     /** Flag to enable/disable font caching */
     enableFontCache: boolean;
-    /** Default font to use when a requested font is not found */
-    defaultFont: string;
+    /**
+     * Default fonts to use when a requested font is not found or lacks a glyph.
+     * Insertion order is preserved; earlier entries are tried first.
+     */
+    defaultFonts: Set<string>;
+    /**
+     * GDT / SHX symbol fonts for AutoCAD control-code glyphs (`%%c`, `%%d`, `%%p`,
+     * `%%nnn`, etc.). Separate from {@link defaultFonts} so text fallbacks are not
+     * polluted by symbol-font code-point matches.
+     */
+    symbolFonts: Set<string>;
     /** Event managers for font-related events */
     readonly events: {
         /** Event triggered when a font cannot be found */
@@ -70,6 +80,47 @@ export declare class FontManager {
      * @param mapping - The font mapping to set
      */
     setFontMapping(mapping: FontMapping): void;
+    /**
+     * Sets the default font fallback chain.
+     *
+     * Pass a {@link DefaultFontsPreset} name to apply a predefined AutoCAD-era
+     * fallback stack, or pass one or more font names to define a custom chain.
+     * Earlier entries are tried first when a glyph is missing.
+     *
+     * @param fonts - A preset name, a single font name, or an ordered list of font names
+     * @example
+     * ```ts
+     * FontManager.instance.setDefaultFonts('r12r14')
+     * FontManager.instance.setDefaultFonts(['hztxt', 'simsun', 'gdt'])
+     * FontManager.instance.setDefaultFonts('simkai')
+     * ```
+     */
+    setDefaultFonts(fonts: DefaultFontsPreset): void;
+    setDefaultFonts(fonts: string | readonly string[]): void;
+    /**
+     * Sets the symbol-font fallback chain for AutoCAD control-code glyphs.
+     *
+     * Pass a {@link DefaultFontsPreset} name to apply a predefined symbol stack,
+     * or pass one or more font names to define a custom chain.
+     *
+     * @param fonts - A preset name, a single font name, or an ordered list of font names
+     */
+    setSymbolFonts(fonts: DefaultFontsPreset): void;
+    setSymbolFonts(fonts: string | readonly string[]): void;
+    /**
+     * Returns the font names for a predefined default-font preset.
+     * @param preset - The preset to look up
+     */
+    getDefaultFontsPreset(preset: DefaultFontsPreset): readonly string[];
+    /**
+     * Returns the symbol-font names for a predefined preset.
+     * @param preset - The preset to look up
+     */
+    getSymbolFontsPreset(preset: DefaultFontsPreset): readonly string[];
+    /**
+     * Font names that should be loaded for the active default and symbol chains.
+     */
+    getFontsToLoad(): readonly string[];
     /**
      * Sets the font loader
      * @param fontLoader - The font loader to set
@@ -83,12 +134,12 @@ export declare class FontManager {
      */
     getAvailableFonts(): Promise<FontInfo[]>;
     /**
-     * Return true if the default font was loaded.
-     * @returns True if the default font was loaded. False otherwise.
+     * Return true if all default fonts were loaded.
+     * @returns True if every font in `defaultFonts` is loaded. False otherwise.
      */
     isDefaultFontLoaded(): boolean;
     /**
-     * Loads the default font
+     * Loads all default and symbol fonts
      * @returns Promise that resolves to the font load statuses
      */
     loadDefaultFont(): Promise<FontLoadStatus[]>;
@@ -97,7 +148,7 @@ export declare class FontManager {
      * @param names - Font names to load.
      * @returns Promise that resolves to an array of font load statuses
      */
-    loadFontsByNames(names: string | string[]): Promise<FontLoadStatus[]>;
+    loadFontsByNames(names: string | readonly string[]): Promise<FontLoadStatus[]>;
     /**
      * Loads the specified fonts from URLs
      * @param urls - URLs of font files to load.
@@ -125,13 +176,24 @@ export declare class FontManager {
      */
     getFontByChar(char: string): BaseFont | undefined;
     /**
-     * Gets the text shape for a specific character with the specified font and size
+     * Gets the text shape for a specific character in the named font only.
+     * Does not fall back to bigFont, default fonts, or other loaded fonts.
      * @param char - The character to get the shape for
      * @param fontName - The name of the font to use
      * @param size - The size of the character
      * @returns The text shape for the character, or undefined if not found
      */
     getCharShape(char: string, fontName: string, size: number): BaseTextShape | undefined;
+    /**
+     * Gets the text shape from the first loaded default font that contains the character.
+     * Used after primary and optional bigFont lookups per AutoCAD text-style semantics.
+     */
+    getCharShapeFromDefaults(char: string, size: number): BaseTextShape | undefined;
+    /**
+     * Gets the text shape from configured GDT / symbol fonts (e.g. `amgdt.shx`).
+     * Used for AutoCAD percent codes and other symbol-font code points.
+     */
+    getCharShapeFromSymbolFonts(char: string, size: number): BaseTextShape | undefined;
     /**
      * Gets the scale factor for a specific font
      * @param fontName - The name of the font
@@ -171,6 +233,10 @@ export declare class FontManager {
      * Loads all fonts from the cache
      */
     getAllFontsFromCache(): Promise<void>;
+    /**
+     * Registers a loaded font under its primary name and all aliases.
+     */
+    private registerFontInMap;
     /**
      * Gets a record of all unsupported characters across all loaded fonts
      * @returns A record mapping unsupported characters to their occurrence count

package/lib/font/index.d.ts

@@ -1,6 +1,7 @@
 export * from './baseFont';
 export * from './baseTextShape';
 export * from './defaultFontLoader';
+export * from './defaultFontsPresets';
 export * from './font';
 export * from './fontFactory';
 export * from './fontLoader';

package/lib/font/meshFont.d.ts

@@ -82,6 +82,15 @@ export declare class MeshFont extends BaseFont {
      * @returns An object containing the opentype font and parsed metadata
      */
     private parseMeshFont;
+    /**
+     * Whether opentype maps the character to a real glyph (not .notdef at index 0).
+     *
+     * opentype.js ≤1.3.4: {@link OpenTypeFont.hasChar} used `charToGlyphIndex(c) !== null`,
+     * but CmapEncoding returns 0 for missing code points — see
+     * https://github.com/opentypejs/opentype.js/issues/330 (fixed in 2.0.0).
+     * We keep `index > 0` here so hasChar stays aligned with {@link _loadGlyphIfNeeded}.
+     */
+    private opentypeHasGlyph;
     /**
      * Return true if this font contains glyph of the specified character. Otherwise, return false.
      * @param char - The character to check

package/lib/font/shxFont.d.ts

@@ -32,31 +32,8 @@ export declare class ShxFont extends BaseFont {
     getSpaceAdvance(size: number): number;
     generateShapes(text: string, size: number): ShxTextShape[];
     /**
-     * Scale factor that converts AutoCAD's `TEXT.height` (cap-height in the SHX
-     * convention) into the em-box-scaled size expected by `generateShapes`.
-     *
-     * SHX glyphs are defined with `baseUp` units of cap-height (height of an
-     * uppercase letter above the baseline) and `height` units of total em-box
-     * (cap-height + descender + headroom for accents). AutoCAD's DXF group 40
-     * for TEXT/ATTRIB/MTEXT is the cap-height — the historical SHX convention
-     * since the format's introduction in AutoCAD R2 (1985), kept by AutoCAD
-     * when TrueType support was added in the early 1990s so that DWGs portable
-     * across font formats render at consistent visual sizes.
-     *
-     * Returning `1` (the previous behavior) meant SHX glyphs were rendered at
-     * `baseUp / height` of the expected size — typically ~0.75 for western
-     * fonts like `romans.shx`/`complex.shx` where `baseUp=21, height=28`.
-     * Multiplying by `height / baseUp` restores the cap-height interpretation.
-     *
-     * Mirrors the behavior already in place for mesh fonts (see
-     * `meshFontParser.ts` where `scaleFactor = unitsPerEm / glyph('A').yMax`),
-     * isolated to the glyph render path only — `mtextProcessor.currentLayoutFontSize`
-     * divides by this factor to keep layout metrics (line height, attachment
-     * offsets, blank width) on the original cap-height scale.
-     *
-     * @returns `height / baseUp` when both are populated and positive; `1`
-     *   otherwise (e.g. exotic BIGFONT/symbol fonts without standard metrics),
-     *   matching the prior behavior as a safe fallback.
+     * SHX font always has fixed scale factor 1.
+     * @returns Always return value 1
      */
     getScaleFactor(): number;
     /**
@@ -78,6 +55,8 @@ export declare class ShxFont extends BaseFont {
      * @returns The shape data for the character code, or undefined if not found
      */
     getCodeShape(code: number, size: number): ShxTextShape | undefined;
+    /** True when the SHX glyph has drawable strokes or a non-zero pen advance. */
+    private static hasRenderableStrokes;
     /**
      * For an unsupported char, use "？" as a replacement.
      */

package/lib/renderer/colorUtils.d.ts

@@ -1,2 +1,10 @@
 import { ColorSettings } from './types';
 export declare function resolveMTextColor(colorSettings: ColorSettings): number;
+/**
+ * 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.
+ */
+export declare function buildWorkerMaterialColorSettings(base: ColorSettings, resolvedColor: number, baseByLayer: boolean): ColorSettings;

package/lib/renderer/index.d.ts

@@ -1,5 +1,6 @@
 export * from './colorUtils';
 export * from './constants';
 export * from './mtext';
+export * from './mtextDataUtils';
 export * from './styleManager';
 export * from './types';

package/lib/renderer/mtextDataUtils.d.ts

@@ -0,0 +1,27 @@
+import { MTextData } from './types';
+/**
+ * Minimum width-to-height ratio for a declared MTEXT wrap box to be treated as
+ * a real column width rather than a mistaken width factor or other bad DXF value.
+ */
+export declare const MIN_REASONABLE_MTEXT_WIDTH_HEIGHT_RATIO = 1.5;
+/**
+ * Conservative CJK full-width glyph advance as a fraction of cap height, used
+ * only when estimating a replacement wrap width from explicit line content.
+ */
+export declare const CJK_MTEXT_CHAR_WIDTH_HEIGHT_RATIO = 0.8;
+/**
+ * Estimates a usable MTEXT wrap width from the longest explicit line in the raw
+ * MTEXT string while preserving explicit line breaks such as `\P`.
+ */
+export declare function estimateMTextWrapWidth(text: string, height: number): number;
+/**
+ * Resolves the MTEXT wrap width used for layout and anchoring.
+ *
+ * Some CAD files contain MTEXT group-code 41 values that are smaller than a
+ * single glyph height, usually because the value came from a text width factor
+ * instead of an actual wrapping box width. Treating that tiny positive value as
+ * the word-wrap width forces CJK text to wrap one character per line. When the
+ * width is clearly impossible as a layout width, estimate a usable width from
+ * the longest explicit MTEXT line and preserve explicit line breaks such as `\P`.
+ */
+export declare function resolveMTextWrapWidth(mtextData: Pick<MTextData, 'text' | 'height' | 'width'>): number;

package/lib/renderer/mtextProcessor.d.ts

@@ -59,6 +59,7 @@ export declare class MTextProcessor {
     private _options;
     private _totalHeight;
     private _hOffset;
+    private _maxLineAdvance;
     private _vOffset;
     private _lineCount;
     private _currentLineObjects;
@@ -103,6 +104,13 @@ export declare class MTextProcessor {
      * The maximum width of one text line
      */
     get maxWidth(): number;
+    /**
+     * Maximum logical pen advance across processed visual lines.
+     *
+     * Unlike visible geometry bounds, this keeps the text insertion origin tied to
+     * the layout pen position even when glyphs have side bearings or overhangs.
+     */
+    get maxLineAdvance(): number;
     /**
      * The direction that the text string follows from its start to its finish.
      */
@@ -297,8 +305,10 @@ export declare class MTextProcessor {
      * @param char Input one character
      * @returns Return the text shape of the specified character
      */
+    private shapeHasStrokeGeometry;
     private getCharShape;
     private advanceToNextLine;
+    private captureCurrentLineAdvance;
     private countFinalCharBoxes;
     private applyPendingEmptyLineYAdjust;
     private resolveCharBoxTarget;
@@ -314,6 +324,12 @@ export declare class MTextProcessor {
      * a rough fallback when the font has no space definition.
      */
     private calculateBlankWidthForFont;
+    /**
+     * Merges line-based geometries for LineSegments. SHX glyphs use indexed
+     * BufferGeometry while fraction/divider decorations omit an index; normalize
+     * to non-indexed form so mergeGeometries accepts the batch.
+     */
+    private mergeLineGeometries;
     /**
      * Convert the text shape geometries to three.js object
      * @param geometries Input text shape geometries

package/lib/renderer/percentControlCodes.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Expands AutoCAD `%%` stroke control codes into `\K`/`\k`, `\O`/`\o`, and `\L`/`\l`
+ * inline formatting commands understood by {@link @mlightcad/mtext-parser}.
+ */
+export declare function expandPercentControlCodes(text: string): string;

package/lib/renderer/shxSymbolControlCodes.d.ts

@@ -0,0 +1,46 @@
+/**
+ * AutoCAD percent-sign symbol codes (`%%c`, `%%d`, `%%p`) and their SHX
+ * symbol-font code points.
+ *
+ * Named percent codes are expanded by {@link @mlightcad/mtext-parser} into Unicode
+ * before rendering. AutoCAD itself does not rely on those Unicode code points in
+ * the primary text font; it resolves the symbols through GDT / symbol SHX fonts
+ * such as `amgdt.shx` using legacy control-code code points.
+ *
+ * References:
+ * - AutoCAD "Text Symbols and Special Characters"
+ * - AutoCAD "Control Codes and Special Characters" (`%%nnn`)
+ * - Legacy SHX convention: 127 = degree, 128 = plus/minus, 129 = diameter
+ * - Modern `amgdt.shx`: degree at 126/176, ± at 177, diameter at U+2205 (∅);
+ *   code 130 = angle (∠). Legacy bytes 127–128 must not be used when CJK mesh
+ *   fonts in the fallback chain expose unrelated glyphs at those code points.
+ */
+export type AutoCadPercentSymbolCode = 'c' | 'd' | 'p';
+/**
+ * Ordered SHX byte-code candidates for each named AutoCAD percent symbol.
+ * Earlier entries are preferred when present in the symbol-font fallback chain
+ * Earlier entries are preferred when present in {@link FontManager.symbolFonts}.
+ */
+export declare const AUTOCAD_PERCENT_SYMBOL_CONTROL_CODES: Readonly<Record<AutoCadPercentSymbolCode, readonly number[]>>;
+/**
+ * Returns whether a character originated from an AutoCAD named percent symbol.
+ */
+export declare function isAutoCadPercentSymbolChar(char: string): boolean;
+/**
+ * Returns whether a character likely came from an AutoCAD numeric percent code
+ * (`%%ddd`) expanded by mtext-parser into {@link String.fromCharCode}.
+ *
+ * AutoCAD resolves these byte-oriented SHX code points from GDT / symbol fonts
+ * (e.g. `amgdt.shx`), not from the primary text font—even when the text font
+ * defines a glyph at the same code (as with `txt.shx` at code 132).
+ */
+export declare function isAutoCadNumericPercentControlCodeChar(char: string): boolean;
+/**
+ * Returns ordered SHX control-code characters to try in symbol-font fallbacks
+ * for an AutoCAD percent-symbol Unicode expansion.
+ */
+export declare function getShxControlCodeCandidates(char: string): readonly string[];
+/**
+ * @deprecated Use {@link getShxControlCodeCandidates} instead.
+ */
+export declare function getShxControlCodeChar(char: string): string | undefined;

package/lib/worker/baseRenderer.d.ts

@@ -63,7 +63,7 @@ export interface MTextBaseRenderer {
      * @param fonts Font names to load (without extension for built-ins).
      * @returns A Promise with the list of fonts that were processed.
      */
-    loadFonts(fonts: string[]): Promise<{
+    loadFonts(fonts: readonly string[]): Promise<{
         loaded: string[];
     }>;
     /**

package/lib/worker/mainThreadRenderer.d.ts

@@ -33,7 +33,7 @@ export declare class MainThreadRenderer implements MTextBaseRenderer {
     /**
      * Load fonts in the main thread
      */
-    loadFonts(fonts: string[]): Promise<{
+    loadFonts(fonts: readonly string[]): Promise<{
         loaded: string[];
     }>;
     /**

package/lib/worker/unifiedRenderer.d.ts

@@ -1,3 +1,4 @@
+import { DefaultFontsPreset } from '../font';
 import { StyleManager } from '../renderer';
 import { ColorSettings, MTextData, TextStyle } from '../renderer/types';
 import { MTextObject } from './baseRenderer';
@@ -56,10 +57,22 @@ export declare class UnifiedRenderer {
      * @param colorSettings - Optional color context (ByLayer, ByBlock colors).
      */
     syncRenderMText(mtextContent: MTextData, textStyle: TextStyle, colorSettings?: ColorSettings): MTextObject;
+    /**
+     * Sets the default font fallback chain on the active renderer and workers.
+     */
+    setDefaultFonts(fonts: DefaultFontsPreset | string | readonly string[]): Promise<void>;
+    /**
+     * Returns font names for a predefined default-font preset.
+     */
+    getDefaultFontsPreset(preset: DefaultFontsPreset): readonly string[];
+    /**
+     * Returns symbol-font names for a predefined preset.
+     */
+    getSymbolFontsPreset(preset: DefaultFontsPreset): readonly string[];
     /**
      * Load fonts using the current mode
      */
-    loadFonts(fonts: string[]): Promise<{
+    loadFonts(fonts: readonly string[]): Promise<{
         loaded: string[];
     }>;
     /**

package/lib/worker/webWorkerRenderer.d.ts

@@ -158,6 +158,10 @@ export declare class WebWorkerRenderer implements MTextBaseRenderer {
      * @param value - URL to load fonts
      */
     setFontUrl(value: string): Promise<void>;
+    /**
+     * Syncs the default font fallback chain to all workers.
+     */
+    setDefaultFonts(fonts: readonly string[], symbolFonts: readonly string[]): Promise<void>;
     /**
      * Render MText in one worker and return serialized data asynchronously.
      */
@@ -167,7 +171,7 @@ export declare class WebWorkerRenderer implements MTextBaseRenderer {
      * Notes: It isn't supported yet.
      */
     syncRenderMText(_mtextContent: MTextData, _textStyle: TextStyle, _colorSettings?: ColorSettings): MTextObject;
-    loadFonts(fonts: string[]): Promise<{
+    loadFonts(fonts: readonly string[]): Promise<{
         loaded: string[];
     }>;
     getAvailableFonts(): Promise<{
@@ -179,7 +183,6 @@ export declare class WebWorkerRenderer implements MTextBaseRenderer {
      * Reconstruct MText object from JSON serialized data
      */
     reconstructMText(serializedData: SerializedMText, colorSettings: ColorSettings): MTextObject;
-    private buildMaterialColorSettings;
     private deserializeCharBoxes;
     private collectLayout;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlightcad/mtext-renderer",
-  "version": "0.10.15",
+  "version": "0.11.0",
   "description": "AutoCAD MText renderer based on Three.js",
   "license": "MIT",
   "author": "MLight Lee <mlight.lee@outlook.com>",
@@ -34,13 +34,13 @@
   ],
   "dependencies": {
     "@mlightcad/mtext-parser": "^1.4.1",
-    "@mlightcad/shx-parser": "^1.3.2",
+    "@mlightcad/shx-parser": "^1.3.4",
     "iconv-lite": "^0.7.0",
     "idb": "^8.0.3",
-    "opentype.js": "^1.3.4"
+    "opentype.js": "^2.0.0"
   },
   "devDependencies": {
-    "@types/opentype.js": "^1.3.8",
+    "@types/opentype.js": "^1.3.10",
     "@types/three": "^0.172.0",
     "vitest": "^3.2.4"
   },