@mlightcad/mtext-renderer 0.11.0 → 0.11.2

package/lib/cache/fontCacheManager.d.ts

@@ -25,6 +25,13 @@ export declare class FontCacheManager {
      * @returns The font data if found, undefined otherwise
      */
     get(fileName: string): Promise<FontData | undefined>;
+    /**
+     * Finds a font in the cache by primary name or alias.
+     * Font names may include or omit a file extension (e.g. `romans` or `romans.shx`).
+     * @param fontName The font name or alias to look up
+     * @returns The font data if found, undefined otherwise
+     */
+    find(fontName: string): Promise<FontData | undefined>;
     /**
      * Deletes a font from the cache
      * @param fileName The font file name (key)

package/lib/font/baseFont.d.ts

@@ -60,6 +60,10 @@ export declare abstract class BaseFont {
      * @returns The shape data for the character code, or undefined if not found
      */
     abstract getCodeShape(code: number, size: number): BaseTextShape | undefined;
+    /**
+     * Gets a named SHX shape glyph when supported by the font implementation.
+     */
+    getShapeByName(_name: string, _size: number): BaseTextShape | undefined;
     /**
      * Gets the scale factor for this font.
      * This is used to adjust the size of characters when rendering.

package/lib/font/fontLoader.d.ts

@@ -15,6 +15,8 @@ export interface FontInfo {
      * https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API/Encodings
      */
     encoding?: string;
+    /** Where this font entry comes from */
+    source?: 'remote' | 'cache';
 }
 /**
  * Represents the status of a font loading operation

package/lib/font/fontManager.d.ts

@@ -128,7 +128,8 @@ export declare class FontManager {
     setFontLoader(fontLoader: FontLoader): void;
     /**
      * Retrieves information about all available fonts in the system.
-     * Loads font metadata from a CDN if not already loaded.
+     * Merges remote font metadata with fonts stored in IndexedDB (cache-only
+     * entries are included; remote entries win when names collide).
      * @returns Promise that resolves to an array of FontInfo objects
      * @throws {Error} If font metadata cannot be loaded from the CDN
      */
@@ -149,6 +150,27 @@ export declare class FontManager {
      * @returns Promise that resolves to an array of font load statuses
      */
     loadFontsByNames(names: string | readonly string[]): Promise<FontLoadStatus[]>;
+    /**
+     * Parses a user-uploaded font file, registers it for rendering, and stores
+     * it in IndexedDB when {@link enableFontCache} is true.
+     *
+     * Supported formats: `.shx`, `.ttf`, `.otf`, `.woff`.
+     *
+     * @param data - Font file contents or a browser `File` selected by the user
+     * @param fileName - Font file name (e.g. `custom.shx`, `simkai.ttf`). Required when `data` is an `ArrayBuffer`
+     * @param aliases - Optional alias names for the font (e.g. AutoCAD style names)
+     * @param encoding - Optional character encoding for SHX bigfonts
+     * @returns Promise that resolves to the font load status
+     */
+    cacheFont(data: ArrayBuffer | File, fileName?: string, aliases?: string[], encoding?: string): Promise<FontLoadStatus>;
+    /**
+     * Loads a font from IndexedDB by primary name or alias.
+     * No-op when {@link enableFontCache} is false.
+     *
+     * @param fontName - Font name or alias (with or without file extension)
+     * @returns True if the font was found in cache and registered for rendering
+     */
+    loadFontFromCache(fontName: string): Promise<boolean>;
     /**
      * Loads the specified fonts from URLs
      * @param urls - URLs of font files to load.
@@ -184,16 +206,28 @@ export declare class FontManager {
      * @returns The text shape for the character, or undefined if not found
      */
     getCharShape(char: string, fontName: string, size: number): BaseTextShape | undefined;
+    /**
+     * Resolves a named SHX shape glyph from the specified font.
+     */
+    getShapeByName(name: string, fontName: string, size: number): BaseTextShape | undefined;
+    /**
+     * Resolves an SHX shape glyph by numeric character code from the specified font.
+     */
+    getShapeByCode(code: number, 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.
+     * Gets the text shape from configured GDT / symbol fonts (e.g. `amgdt.shx`)
+     * by font-internal character code.
+     *
+     * AutoCAD `%%` symbols resolve against SHX code points (e.g. 126, 129, 132),
+     * not Unicode text semantics. Use {@link BaseFont.getCodeShape} so BIGFONT and
+     * Unicode SHX fonts are queried consistently.
      */
-    getCharShapeFromSymbolFonts(char: string, size: number): BaseTextShape | undefined;
+    getCodeShapeFromSymbolFonts(code: number, size: number): BaseTextShape | undefined;
     /**
      * Gets the scale factor for a specific font
      * @param fontName - The name of the font
@@ -233,6 +267,9 @@ export declare class FontManager {
      * Loads all fonts from the cache
      */
     getAllFontsFromCache(): Promise<void>;
+    private cachedFontDataToFontInfo;
+    private resolveUploadedFontType;
+    private buildUploadedFontAliases;
     /**
      * Registers a loaded font under its primary name and all aliases.
      */

package/lib/font/shxFont.d.ts

@@ -55,6 +55,12 @@ 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;
+    /**
+     * Gets the shape data for a named SHX shape at a given size.
+     *
+     * Shape names are matched case-insensitively via the underlying SHX parser.
+     */
+    getShapeByName(name: string, size: number): ShxTextShape | undefined;
     /** True when the SHX glyph has drawable strokes or a non-zero pen advance. */
     private static hasRenderableStrokes;
     /**

package/lib/renderer/index.d.ts

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

package/lib/renderer/mtext.d.ts

@@ -1,6 +1,6 @@
 import { FontManager } from '../font';
 import { StyleManager } from './styleManager';
-import { ColorSettings, MTextData, MTextLayout, TextStyle } from './types';
+import { ColorSettings, MTextData, MTextLayout, ShapeData, TextStyle } from './types';
 import * as THREE from 'three';
 /**
  * Represents an AutoCAD MText object in Three.js.
@@ -101,6 +101,12 @@ export declare class MText extends THREE.Object3D {
      * @returns The created Three.js object, or undefined if creation fails
      */
     private loadMText;
+    /**
+     * Builds and places one SHX shape glyph.
+     */
+    loadShape(shapeData: ShapeData, style: TextStyle): THREE.Object3D<THREE.Object3DEventMap> | undefined;
+    private finalizePlacement;
+    private createShapeGroup;
     /**
      * Creates a group of text elements from MText data.
      * @param mtextData - The MText data to process

package/lib/renderer/mtextProcessor.d.ts

@@ -275,6 +275,19 @@ export declare class MTextProcessor {
      * @param group The group to add processed geometries to
      */
     private startNewParagraph;
+    /**
+     * Renders one SHX shape glyph for AutoCAD SHAPE entities.
+     *
+     * The glyph is resolved by {@link shapeName} first, then by {@link shapeNumber}.
+     */
+    processShapeGlyph(shapeName?: string, shapeNumber?: number): THREE.Object3D | undefined;
+    private resolveShapeGlyph;
+    /**
+     * Builds geometry for one glyph and appends it to the output buffers.
+     *
+     * @returns Horizontal advance width after width factor and oblique skew.
+     */
+    private buildShapeGeometry;
     /**
      * Render the specified texts
      * @param item Input texts to render
@@ -292,6 +305,7 @@ export declare class MTextProcessor {
     private processBlank;
     private recordVisualLineBreak;
     private recordCurrentLineLayout;
+    private processPercentSymbol;
     private processChar;
     private processLastLine;
     private initLineParams;
@@ -306,6 +320,7 @@ export declare class MTextProcessor {
      * @returns Return the text shape of the specified character
      */
     private shapeHasStrokeGeometry;
+    private resolvePercentSymbolShape;
     private getCharShape;
     private advanceToNextLine;
     private captureCurrentLineAdvance;

package/lib/renderer/shape.d.ts

@@ -0,0 +1,25 @@
+import { FontManager } from '../font';
+import { StyleManager } from './styleManager';
+import { ColorSettings, MTextLayout, ShapeData, TextStyle } from './types';
+import * as THREE from 'three';
+/**
+ * Represents one AutoCAD SHAPE entity in Three.js.
+ */
+export declare class Shape extends THREE.Object3D {
+    private _shapeData;
+    private _style;
+    private _fontsInStyleLoaded;
+    private _styleManager;
+    private _fontManager;
+    private _colorSettings;
+    private _box;
+    constructor(shapeData: ShapeData, style: TextStyle, styleManager: StyleManager, fontManager: FontManager, colorSettings?: ColorSettings);
+    get box(): THREE.Box3;
+    get styleManager(): StyleManager;
+    get textStyle(): TextStyle;
+    createLayoutData(): MTextLayout;
+    asyncDraw(): Promise<void>;
+    syncDraw(): void;
+    private createPlacementData;
+    private getFontName;
+}

package/lib/renderer/shxSymbolControlCodes.d.ts

@@ -1,46 +1,21 @@
+import { PercentSymbolData } from '@mlightcad/mtext-parser';
 /**
  * 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.
+ * When {@link MTextParserOptions.yieldPercentSymbols} is enabled, the parser
+ * emits {@link TokenType.PERCENT_SYMBOL} tokens for these codes. AutoCAD itself
+ * does not rely on the Unicode expansions in the primary text font; it resolves
+ * the symbols through GDT / symbol SHX fonts such as `amgdt.shx` using legacy
+ * control-code 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.
+ * Returns ordered font code points to try for a parser-emitted percent symbol.
  */
-export declare function getShxControlCodeChar(char: string): string | undefined;
+export declare function getPercentSymbolLookupCodes(data: PercentSymbolData): readonly number[];

package/lib/renderer/types.d.ts

@@ -177,6 +177,25 @@ export interface MTextData {
     /** Whether to collect per-character bounding boxes for picking. Default is true */
     collectCharBoxes?: boolean;
 }
+/**
+ * Describes one AutoCAD SHAPE entity for rendering.
+ */
+export interface ShapeData {
+    /** Shape name within the SHX font (DXF group 2). */
+    name?: string;
+    /** Numeric shape code within the SHX font. */
+    shapeNumber?: number;
+    /** Shape height (DXF group 40). */
+    size: number;
+    /** Insertion point in WCS coordinates. */
+    position: Point3d;
+    /** Rotation relative to the shape OCS X axis, in radians. */
+    rotation?: number;
+    /** Extrusion/normal vector. */
+    directionVector?: Point3d;
+    /** Relative X-scale factor. */
+    widthFactor?: number;
+}
 /**
  * Represents a text style configuration that defines the visual appearance and formatting of text.
  * This interface contains properties that control various aspects of text rendering including font,

package/lib/worker/baseRenderer.d.ts

@@ -1,5 +1,5 @@
 import { StyleManager } from '../renderer/styleManager';
-import { ColorSettings, MTextData, MTextLayout, TextStyle } from '../renderer/types';
+import { ColorSettings, MTextData, MTextLayout, ShapeData, TextStyle } from '../renderer/types';
 import * as THREE from 'three';
 /**
  * Represents a rendered MText object that extends THREE.Object3D with additional MText-specific properties.
@@ -55,6 +55,14 @@ export interface MTextBaseRenderer {
      * @returns A Promise resolving to a populated `MTextObject` ready to add to a scene.
      */
     syncRenderMText(mtextContent: MTextData, textStyle: TextStyle, colorSettings?: ColorSettings): MTextObject;
+    /**
+     * Render one SHX shape glyph synchronously.
+     */
+    syncRenderShape(shapeContent: ShapeData, textStyle: TextStyle, colorSettings?: ColorSettings): MTextObject;
+    /**
+     * Render one SHX shape glyph asynchronously.
+     */
+    asyncRenderShape(shapeContent: ShapeData, textStyle: TextStyle, colorSettings?: ColorSettings): Promise<MTextObject>;
     /**
      * Ensure the specified fonts are available to the renderer.
      *

package/lib/worker/mainThreadRenderer.d.ts

@@ -1,5 +1,5 @@
 import { StyleManager } from '../renderer/styleManager';
-import { ColorSettings, MTextData, TextStyle } from '../renderer/types';
+import { ColorSettings, MTextData, ShapeData, TextStyle } from '../renderer/types';
 import { MTextBaseRenderer, MTextObject } from './baseRenderer';
 /**
  * Main thread renderer for MText objects
@@ -30,6 +30,8 @@ export declare class MainThreadRenderer implements MTextBaseRenderer {
      * that default font is loaded and fonts needed in mtext are loaded.
      */
     syncRenderMText(mtextContent: MTextData, textStyle: TextStyle, colorSettings?: ColorSettings): MTextObject;
+    asyncRenderShape(shapeContent: ShapeData, textStyle: TextStyle, colorSettings?: ColorSettings): Promise<MTextObject>;
+    syncRenderShape(shapeContent: ShapeData, textStyle: TextStyle, colorSettings?: ColorSettings): MTextObject;
     /**
      * Load fonts in the main thread
      */

package/lib/worker/unifiedRenderer.d.ts

@@ -1,6 +1,6 @@
-import { DefaultFontsPreset } from '../font';
+import { DefaultFontsPreset, FontLoadStatus } from '../font';
 import { StyleManager } from '../renderer';
-import { ColorSettings, MTextData, TextStyle } from '../renderer/types';
+import { ColorSettings, MTextData, ShapeData, TextStyle } from '../renderer/types';
 import { MTextObject } from './baseRenderer';
 import { WebWorkerRendererConfig } from './webWorkerRenderer';
 export type RenderMode = 'main' | 'worker';
@@ -57,6 +57,8 @@ export declare class UnifiedRenderer {
      * @param colorSettings - Optional color context (ByLayer, ByBlock colors).
      */
     syncRenderMText(mtextContent: MTextData, textStyle: TextStyle, colorSettings?: ColorSettings): MTextObject;
+    asyncRenderShape(shapeContent: ShapeData, textStyle: TextStyle, colorSettings?: ColorSettings, _mode?: RenderMode): Promise<MTextObject>;
+    syncRenderShape(shapeContent: ShapeData, textStyle: TextStyle, colorSettings?: ColorSettings): MTextObject;
     /**
      * Sets the default font fallback chain on the active renderer and workers.
      */
@@ -83,6 +85,12 @@ export declare class UnifiedRenderer {
             name: string[];
         }>;
     }>;
+    /**
+     * Parse and cache a user-uploaded font file in IndexedDB.
+     * Always runs on the main-thread {@link FontManager} so the cache is shared
+     * with the web worker renderer.
+     */
+    cacheFont(data: ArrayBuffer | File, fileName?: string, aliases?: string[], encoding?: string): Promise<FontLoadStatus>;
     /**
      * Clean up resources
      */

package/lib/worker/webWorkerRenderer.d.ts

@@ -1,5 +1,5 @@
 import { StyleManager } from '../renderer/styleManager';
-import { CharBox, ColorSettings, MTextData, TextStyle } from '../renderer/types';
+import { CharBox, ColorSettings, MTextData, ShapeData, TextStyle } from '../renderer/types';
 import { MTextBaseRenderer, MTextObject } from './baseRenderer';
 /**
  * Configuration options for WebWorkerRenderer
@@ -171,6 +171,8 @@ export declare class WebWorkerRenderer implements MTextBaseRenderer {
      * Notes: It isn't supported yet.
      */
     syncRenderMText(_mtextContent: MTextData, _textStyle: TextStyle, _colorSettings?: ColorSettings): MTextObject;
+    asyncRenderShape(_shapeContent: ShapeData, _textStyle: TextStyle, _colorSettings?: ColorSettings): Promise<MTextObject>;
+    syncRenderShape(_shapeContent: ShapeData, _textStyle: TextStyle, _colorSettings?: ColorSettings): MTextObject;
     loadFonts(fonts: readonly string[]): Promise<{
         loaded: string[];
     }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlightcad/mtext-renderer",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "AutoCAD MText renderer based on Three.js",
   "license": "MIT",
   "author": "MLight Lee <mlight.lee@outlook.com>",
@@ -24,6 +24,16 @@
     "README.md",
     "package.json"
   ],
+  "nx": {
+    "targets": {
+      "build": {
+        "outputs": [
+          "{projectRoot}/dist",
+          "{projectRoot}/lib"
+        ]
+      }
+    }
+  },
   "keywords": [
     "autocad",
     "mtext",
@@ -33,7 +43,7 @@
     "3d-text"
   ],
   "dependencies": {
-    "@mlightcad/mtext-parser": "^1.4.1",
+    "@mlightcad/mtext-parser": "^1.5.0",
     "@mlightcad/shx-parser": "^1.3.4",
     "iconv-lite": "^0.7.0",
     "idb": "^8.0.3",