@cadview/core 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -301,6 +301,50 @@ interface ThemeConfig {
 }
 declare const THEMES: Record<Theme, ThemeConfig>;
 
+interface RenderStats {
+    entitiesDrawn: number;
+    entitiesSkipped: number;
+    drawCalls: number;
+    byType: Record<string, number>;
+}
+interface DebugOptions {
+    showFps?: boolean;
+    showRenderStats?: boolean;
+    showDocumentInfo?: boolean;
+    showTimings?: boolean;
+    showCamera?: boolean;
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+}
+interface DebugStats {
+    fps: number;
+    frameTime: number;
+    renderStats: RenderStats;
+    entityCount: number;
+    layerCount: number;
+    visibleLayerCount: number;
+    blockCount: number;
+    parseTime: number;
+    spatialIndexBuildTime: number;
+    totalLoadTime: number;
+    zoom: number;
+    pixelSize: number;
+    viewportBounds: {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    };
+    fileName: string | null;
+    fileSize: number;
+    dxfVersion: string | null;
+}
+type ResolvedDebugOptions = Required<DebugOptions>;
+/**
+ * Render a debug overlay panel on the canvas in screen space.
+ * Follows the same pattern as renderMeasureOverlay — resets transform to screen space.
+ */
+declare function renderDebugOverlay(ctx: CanvasRenderingContext2D, stats: DebugStats, theme: Theme, options: ResolvedDebugOptions, canvasWidth: number, canvasHeight: number): void;
+
 /**
  * Resolve the display color for an entity.
  *
@@ -325,12 +369,12 @@ declare class CanvasRenderer {
     getWidth(): number;
     getHeight(): number;
     updateSize(): void;
-    render(doc: DxfDocument, vt: ViewTransform, theme: Theme, visibleLayers: Set<string>, selectedEntityIndex: number): void;
+    render(doc: DxfDocument, vt: ViewTransform, theme: Theme, visibleLayers: Set<string>, selectedEntityIndex: number): RenderStats;
     renderEmpty(theme: Theme): void;
     destroy(): void;
 }
 
-declare function drawEntity(ctx: CanvasRenderingContext2D, entity: DxfEntity, doc: DxfDocument, vt: ViewTransform, theme: Theme, pixelSize: number): void;
+declare function drawEntity(ctx: CanvasRenderingContext2D, entity: DxfEntity, doc: DxfDocument, vt: ViewTransform, theme: Theme, pixelSize: number, stats?: RenderStats): void;
 
 interface SelectEvent {
     entity: DxfEntity;
@@ -359,6 +403,24 @@ declare class EventEmitter<T extends Record<string, any> = Record<string, any>>
 }
 
 type Tool = 'pan' | 'select' | 'measure';
+/**
+ * Interface for registering custom file format converters.
+ * Converters are checked in order during `loadFile()` and `loadBuffer()`.
+ * The first converter whose `detect()` returns true will be used.
+ */
+interface FormatConverter {
+    /**
+     * Return true if the buffer is in this format.
+     * Implementations should check magic bytes, not file extensions.
+     * Must not throw — return false on any error.
+     */
+    detect(buffer: ArrayBuffer): boolean;
+    /**
+     * Convert the buffer to a DXF string.
+     * The returned string must be valid DXF parseable by `parseDxf()`.
+     */
+    convert(buffer: ArrayBuffer): Promise<string>;
+}
 interface CadViewerOptions {
     theme?: Theme;
     backgroundColor?: string;
@@ -367,6 +429,13 @@ interface CadViewerOptions {
     maxZoom?: number;
     zoomSpeed?: number;
     initialTool?: Tool;
+    /** Format converters for non-DXF file formats (e.g. DWG via @cadview/dwg). */
+    formatConverters?: FormatConverter[];
+    /**
+     * Enable a debug overlay showing FPS, render stats, document info, timing, and camera data.
+     * Pass `true` for defaults, or an object for granular control.
+     */
+    debug?: boolean | DebugOptions;
 }
 declare class CadViewer {
     private canvas;
@@ -381,14 +450,62 @@ declare class CadViewer {
     private currentTool;
     private inputHandler;
     private resizeObserver;
+    private formatConverters;
     private selectedEntityIndex;
     private renderPending;
     private destroyed;
+    private loadGeneration;
     private mouseScreenX;
     private mouseScreenY;
+    private debugEnabled;
+    private debugOptions;
+    private lastRenderStats;
+    private lastDebugStats;
+    private frameTimestamps;
+    private lastDoRenderTime;
+    private lastFrameTime;
+    private parseTime;
+    private spatialIndexBuildTime;
+    private loadedFileName;
+    private loadedFileSize;
+    private debugRafId;
     constructor(canvas: HTMLCanvasElement, options?: CadViewerOptions);
+    /**
+     * Throws if the viewer has been destroyed.
+     * Call at the start of any public method that mutates state.
+     */
+    private guardDestroyed;
+    /**
+     * Run registered format converters on a buffer.
+     * Returns the converted DXF string if a converter matched, or null otherwise.
+     * Each converter's detect() is wrapped in try/catch — a throwing detect() is skipped.
+     */
+    private runConverters;
+    /**
+     * Load a CAD file from a browser File object.
+     * Automatically detects the format using registered converters (e.g. DWG).
+     * Falls back to DXF parsing if no converter matches.
+     */
     loadFile(file: File): Promise<void>;
+    /**
+     * Load a CAD file from an ArrayBuffer with format converter support.
+     * Unlike `loadArrayBuffer()` (sync, DXF-only), this method is async and
+     * checks registered FormatConverters for non-DXF formats.
+     */
+    loadBuffer(buffer: ArrayBuffer): Promise<void>;
+    /**
+     * Load a pre-parsed DxfDocument directly, bypassing the parser.
+     * Useful for custom parsers or pre-processed documents.
+     */
+    loadDocument(doc: DxfDocument): void;
+    /**
+     * Load a DXF string directly (synchronous, no format conversion).
+     */
     loadString(dxf: string): void;
+    /**
+     * Load a DXF file from an ArrayBuffer (synchronous, no format conversion).
+     * For format conversion support (e.g. DWG), use `loadFile()` or `loadBuffer()` instead.
+     */
     loadArrayBuffer(buffer: ArrayBuffer): void;
     /**
      * Clear the current document and reset all state without destroying the viewer.
@@ -419,6 +536,19 @@ declare class CadViewer {
     /** @internal */
     requestRender(): void;
     private doRender;
+    /**
+     * Enable or disable the debug overlay.
+     * Pass `true` for defaults, `false` to disable, or an object for granular control.
+     */
+    setDebug(debug: boolean | DebugOptions): void;
+    private startDebugLoop;
+    private stopDebugLoop;
+    /**
+     * Get the latest debug stats snapshot, or null if debug mode is off.
+     */
+    getDebugStats(): DebugStats | null;
+    private buildDebugStats;
+    private computeViewportBounds;
     /** @internal */
     handlePan(dx: number, dy: number): void;
     /** @internal */
@@ -507,4 +637,4 @@ interface BBox {
 declare function computeEntitiesBounds(entities: DxfEntity[]): BBox | null;
 declare function computeEntityBBox(entity: DxfEntity): BBox | null;
 
-export { type BBox, CadViewer, type CadViewerEventMap, type CadViewerOptions, Camera, CanvasRenderer, type DxfArcEntity, type DxfAttrib, type DxfBlock, type DxfCircleEntity, type DxfDimensionEntity, type DxfDocument, type DxfEllipseEntity, type DxfEntity, type DxfEntityBase, type DxfHatchBoundaryPath, type DxfHatchEdge, type DxfHatchEntity, type DxfHeader, type DxfInsertEntity, type DxfLayer, type DxfLineEntity, type DxfLineType, type DxfLwPolylineEntity, type DxfLwPolylineVertex, type DxfMTextEntity, DxfParseError, type DxfPointEntity, type DxfPolylineEntity, type DxfSplineEntity, type DxfStyle, type DxfTextEntity, EventEmitter, LayerManager, type MeasureEvent, type MeasureState, MeasureTool, type Point2D, type Point3D, type SelectEvent, type SnapResult, type SnapType, SpatialIndex, THEMES, type Theme, type ThemeConfig, type Tool, type ViewTransform, aciToDisplayColor, aciToHex, applyTransform, computeEntitiesBounds, computeEntityBBox, drawEntity, findSnaps, fitToView, hitTest, parseDxf, renderMeasureOverlay, resolveEntityColor, screenToWorld, trueColorToHex, worldToScreen, zoomAtPoint };
+export { type BBox, CadViewer, type CadViewerEventMap, type CadViewerOptions, Camera, CanvasRenderer, type DebugOptions, type DebugStats, type DxfArcEntity, type DxfAttrib, type DxfBlock, type DxfCircleEntity, type DxfDimensionEntity, type DxfDocument, type DxfEllipseEntity, type DxfEntity, type DxfEntityBase, type DxfHatchBoundaryPath, type DxfHatchEdge, type DxfHatchEntity, type DxfHeader, type DxfInsertEntity, type DxfLayer, type DxfLineEntity, type DxfLineType, type DxfLwPolylineEntity, type DxfLwPolylineVertex, type DxfMTextEntity, DxfParseError, type DxfPointEntity, type DxfPolylineEntity, type DxfSplineEntity, type DxfStyle, type DxfTextEntity, EventEmitter, type FormatConverter, LayerManager, type MeasureEvent, type MeasureState, MeasureTool, type Point2D, type Point3D, type RenderStats, type SelectEvent, type SnapResult, type SnapType, SpatialIndex, THEMES, type Theme, type ThemeConfig, type Tool, type ViewTransform, aciToDisplayColor, aciToHex, applyTransform, computeEntitiesBounds, computeEntityBBox, drawEntity, findSnaps, fitToView, hitTest, parseDxf, renderDebugOverlay, renderMeasureOverlay, resolveEntityColor, screenToWorld, trueColorToHex, worldToScreen, zoomAtPoint };

package/dist/index.d.ts

@@ -301,6 +301,50 @@ interface ThemeConfig {
 }
 declare const THEMES: Record<Theme, ThemeConfig>;
 
+interface RenderStats {
+    entitiesDrawn: number;
+    entitiesSkipped: number;
+    drawCalls: number;
+    byType: Record<string, number>;
+}
+interface DebugOptions {
+    showFps?: boolean;
+    showRenderStats?: boolean;
+    showDocumentInfo?: boolean;
+    showTimings?: boolean;
+    showCamera?: boolean;
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+}
+interface DebugStats {
+    fps: number;
+    frameTime: number;
+    renderStats: RenderStats;
+    entityCount: number;
+    layerCount: number;
+    visibleLayerCount: number;
+    blockCount: number;
+    parseTime: number;
+    spatialIndexBuildTime: number;
+    totalLoadTime: number;
+    zoom: number;
+    pixelSize: number;
+    viewportBounds: {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    };
+    fileName: string | null;
+    fileSize: number;
+    dxfVersion: string | null;
+}
+type ResolvedDebugOptions = Required<DebugOptions>;
+/**
+ * Render a debug overlay panel on the canvas in screen space.
+ * Follows the same pattern as renderMeasureOverlay — resets transform to screen space.
+ */
+declare function renderDebugOverlay(ctx: CanvasRenderingContext2D, stats: DebugStats, theme: Theme, options: ResolvedDebugOptions, canvasWidth: number, canvasHeight: number): void;
+
 /**
  * Resolve the display color for an entity.
  *
@@ -325,12 +369,12 @@ declare class CanvasRenderer {
     getWidth(): number;
     getHeight(): number;
     updateSize(): void;
-    render(doc: DxfDocument, vt: ViewTransform, theme: Theme, visibleLayers: Set<string>, selectedEntityIndex: number): void;
+    render(doc: DxfDocument, vt: ViewTransform, theme: Theme, visibleLayers: Set<string>, selectedEntityIndex: number): RenderStats;
     renderEmpty(theme: Theme): void;
     destroy(): void;
 }
 
-declare function drawEntity(ctx: CanvasRenderingContext2D, entity: DxfEntity, doc: DxfDocument, vt: ViewTransform, theme: Theme, pixelSize: number): void;
+declare function drawEntity(ctx: CanvasRenderingContext2D, entity: DxfEntity, doc: DxfDocument, vt: ViewTransform, theme: Theme, pixelSize: number, stats?: RenderStats): void;
 
 interface SelectEvent {
     entity: DxfEntity;
@@ -359,6 +403,24 @@ declare class EventEmitter<T extends Record<string, any> = Record<string, any>>
 }
 
 type Tool = 'pan' | 'select' | 'measure';
+/**
+ * Interface for registering custom file format converters.
+ * Converters are checked in order during `loadFile()` and `loadBuffer()`.
+ * The first converter whose `detect()` returns true will be used.
+ */
+interface FormatConverter {
+    /**
+     * Return true if the buffer is in this format.
+     * Implementations should check magic bytes, not file extensions.
+     * Must not throw — return false on any error.
+     */
+    detect(buffer: ArrayBuffer): boolean;
+    /**
+     * Convert the buffer to a DXF string.
+     * The returned string must be valid DXF parseable by `parseDxf()`.
+     */
+    convert(buffer: ArrayBuffer): Promise<string>;
+}
 interface CadViewerOptions {
     theme?: Theme;
     backgroundColor?: string;
@@ -367,6 +429,13 @@ interface CadViewerOptions {
     maxZoom?: number;
     zoomSpeed?: number;
     initialTool?: Tool;
+    /** Format converters for non-DXF file formats (e.g. DWG via @cadview/dwg). */
+    formatConverters?: FormatConverter[];
+    /**
+     * Enable a debug overlay showing FPS, render stats, document info, timing, and camera data.
+     * Pass `true` for defaults, or an object for granular control.
+     */
+    debug?: boolean | DebugOptions;
 }
 declare class CadViewer {
     private canvas;
@@ -381,14 +450,62 @@ declare class CadViewer {
     private currentTool;
     private inputHandler;
     private resizeObserver;
+    private formatConverters;
     private selectedEntityIndex;
     private renderPending;
     private destroyed;
+    private loadGeneration;
     private mouseScreenX;
     private mouseScreenY;
+    private debugEnabled;
+    private debugOptions;
+    private lastRenderStats;
+    private lastDebugStats;
+    private frameTimestamps;
+    private lastDoRenderTime;
+    private lastFrameTime;
+    private parseTime;
+    private spatialIndexBuildTime;
+    private loadedFileName;
+    private loadedFileSize;
+    private debugRafId;
     constructor(canvas: HTMLCanvasElement, options?: CadViewerOptions);
+    /**
+     * Throws if the viewer has been destroyed.
+     * Call at the start of any public method that mutates state.
+     */
+    private guardDestroyed;
+    /**
+     * Run registered format converters on a buffer.
+     * Returns the converted DXF string if a converter matched, or null otherwise.
+     * Each converter's detect() is wrapped in try/catch — a throwing detect() is skipped.
+     */
+    private runConverters;
+    /**
+     * Load a CAD file from a browser File object.
+     * Automatically detects the format using registered converters (e.g. DWG).
+     * Falls back to DXF parsing if no converter matches.
+     */
     loadFile(file: File): Promise<void>;
+    /**
+     * Load a CAD file from an ArrayBuffer with format converter support.
+     * Unlike `loadArrayBuffer()` (sync, DXF-only), this method is async and
+     * checks registered FormatConverters for non-DXF formats.
+     */
+    loadBuffer(buffer: ArrayBuffer): Promise<void>;
+    /**
+     * Load a pre-parsed DxfDocument directly, bypassing the parser.
+     * Useful for custom parsers or pre-processed documents.
+     */
+    loadDocument(doc: DxfDocument): void;
+    /**
+     * Load a DXF string directly (synchronous, no format conversion).
+     */
     loadString(dxf: string): void;
+    /**
+     * Load a DXF file from an ArrayBuffer (synchronous, no format conversion).
+     * For format conversion support (e.g. DWG), use `loadFile()` or `loadBuffer()` instead.
+     */
     loadArrayBuffer(buffer: ArrayBuffer): void;
     /**
      * Clear the current document and reset all state without destroying the viewer.
@@ -419,6 +536,19 @@ declare class CadViewer {
     /** @internal */
     requestRender(): void;
     private doRender;
+    /**
+     * Enable or disable the debug overlay.
+     * Pass `true` for defaults, `false` to disable, or an object for granular control.
+     */
+    setDebug(debug: boolean | DebugOptions): void;
+    private startDebugLoop;
+    private stopDebugLoop;
+    /**
+     * Get the latest debug stats snapshot, or null if debug mode is off.
+     */
+    getDebugStats(): DebugStats | null;
+    private buildDebugStats;
+    private computeViewportBounds;
     /** @internal */
     handlePan(dx: number, dy: number): void;
     /** @internal */
@@ -507,4 +637,4 @@ interface BBox {
 declare function computeEntitiesBounds(entities: DxfEntity[]): BBox | null;
 declare function computeEntityBBox(entity: DxfEntity): BBox | null;
 
-export { type BBox, CadViewer, type CadViewerEventMap, type CadViewerOptions, Camera, CanvasRenderer, type DxfArcEntity, type DxfAttrib, type DxfBlock, type DxfCircleEntity, type DxfDimensionEntity, type DxfDocument, type DxfEllipseEntity, type DxfEntity, type DxfEntityBase, type DxfHatchBoundaryPath, type DxfHatchEdge, type DxfHatchEntity, type DxfHeader, type DxfInsertEntity, type DxfLayer, type DxfLineEntity, type DxfLineType, type DxfLwPolylineEntity, type DxfLwPolylineVertex, type DxfMTextEntity, DxfParseError, type DxfPointEntity, type DxfPolylineEntity, type DxfSplineEntity, type DxfStyle, type DxfTextEntity, EventEmitter, LayerManager, type MeasureEvent, type MeasureState, MeasureTool, type Point2D, type Point3D, type SelectEvent, type SnapResult, type SnapType, SpatialIndex, THEMES, type Theme, type ThemeConfig, type Tool, type ViewTransform, aciToDisplayColor, aciToHex, applyTransform, computeEntitiesBounds, computeEntityBBox, drawEntity, findSnaps, fitToView, hitTest, parseDxf, renderMeasureOverlay, resolveEntityColor, screenToWorld, trueColorToHex, worldToScreen, zoomAtPoint };
+export { type BBox, CadViewer, type CadViewerEventMap, type CadViewerOptions, Camera, CanvasRenderer, type DebugOptions, type DebugStats, type DxfArcEntity, type DxfAttrib, type DxfBlock, type DxfCircleEntity, type DxfDimensionEntity, type DxfDocument, type DxfEllipseEntity, type DxfEntity, type DxfEntityBase, type DxfHatchBoundaryPath, type DxfHatchEdge, type DxfHatchEntity, type DxfHeader, type DxfInsertEntity, type DxfLayer, type DxfLineEntity, type DxfLineType, type DxfLwPolylineEntity, type DxfLwPolylineVertex, type DxfMTextEntity, DxfParseError, type DxfPointEntity, type DxfPolylineEntity, type DxfSplineEntity, type DxfStyle, type DxfTextEntity, EventEmitter, type FormatConverter, LayerManager, type MeasureEvent, type MeasureState, MeasureTool, type Point2D, type Point3D, type RenderStats, type SelectEvent, type SnapResult, type SnapType, SpatialIndex, THEMES, type Theme, type ThemeConfig, type Tool, type ViewTransform, aciToDisplayColor, aciToHex, applyTransform, computeEntitiesBounds, computeEntityBBox, drawEntity, findSnaps, fitToView, hitTest, parseDxf, renderDebugOverlay, renderMeasureOverlay, resolveEntityColor, screenToWorld, trueColorToHex, worldToScreen, zoomAtPoint };