@cadview/core 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -1551,7 +1551,7 @@ function decodeInput(input) {
   const bytes = new Uint8Array(input);
   const sentinelBytes = new TextDecoder("ascii").decode(bytes.slice(0, BINARY_DXF_SENTINEL.length));
   if (sentinelBytes === BINARY_DXF_SENTINEL) {
-    throw new Error("Binary DXF format is not supported. Please export as ASCII DXF.");
+    throw new DxfParseError("Binary DXF format is not supported. Please export as ASCII DXF.");
   }
   let text = new TextDecoder("utf-8").decode(input);
   const versionMatch = text.match(/\$ACADVER[\s\S]*?\n\s*1\s*\n\s*(\S+)/);
@@ -1622,7 +1622,7 @@ function parseDxf(input) {
   try {
     text = decodeInput(input);
   } catch (err) {
-    if (err instanceof Error && err.message.includes("Binary DXF")) {
+    if (err instanceof DxfParseError) {
       throw err;
     }
     throw new DxfParseError("Failed to decode DXF input.", err);
@@ -2485,23 +2485,25 @@ function deBoor(degree, controlPoints, knots, t, weights) {
       const denom = knots[i + degree - r + 1] - knots[i];
       if (Math.abs(denom) < 1e-10) continue;
       const alpha = (t - knots[i]) / denom;
+      const dj = d[j];
+      const djPrev = d[j - 1];
       if (weights) {
         const w0 = w[j - 1] * (1 - alpha);
         const w1 = w[j] * alpha;
         const wSum = w0 + w1;
         if (Math.abs(wSum) < 1e-10) continue;
-        d[j].x = (d[j - 1].x * w0 + d[j].x * w1) / wSum;
-        d[j].y = (d[j - 1].y * w0 + d[j].y * w1) / wSum;
-        d[j].z = (d[j - 1].z * w0 + d[j].z * w1) / wSum;
+        dj.x = (djPrev.x * w0 + dj.x * w1) / wSum;
+        dj.y = (djPrev.y * w0 + dj.y * w1) / wSum;
+        dj.z = (djPrev.z * w0 + dj.z * w1) / wSum;
         w[j] = wSum;
       } else {
-        d[j].x = (1 - alpha) * d[j - 1].x + alpha * d[j].x;
-        d[j].y = (1 - alpha) * d[j - 1].y + alpha * d[j].y;
-        d[j].z = (1 - alpha) * d[j - 1].z + alpha * d[j].z;
+        dj.x = (1 - alpha) * djPrev.x + alpha * dj.x;
+        dj.y = (1 - alpha) * djPrev.y + alpha * dj.y;
+        dj.z = (1 - alpha) * djPrev.z + alpha * dj.z;
       }
     }
   }
-  return d[degree];
+  return d[degree] ?? { x: 0, y: 0, z: 0 };
 }
 function fitPointsToPolyline(fitPoints) {
   if (fitPoints.length < 2) return fitPoints.map((p) => ({ x: p.x, y: p.y }));
@@ -2695,7 +2697,7 @@ function drawMText(ctx, entity, pixelSize) {
 
 // src/renderer/entities/draw-insert.ts
 var MAX_INSERT_DEPTH = 100;
-function drawInsert(ctx, entity, doc, vt, theme, pixelSize, depth = 0) {
+function drawInsert(ctx, entity, doc, vt, theme, pixelSize, depth = 0, stats) {
   if (depth > MAX_INSERT_DEPTH) return;
   const block = doc.blocks.get(entity.blockName);
   if (!block) return;
@@ -2720,9 +2722,9 @@ function drawInsert(ctx, entity, doc, vt, theme, pixelSize, depth = 0) {
         ctx.fillStyle = color;
         ctx.lineWidth = adjustedPixelSize;
         if (blockEntity.type === "INSERT") {
-          drawInsert(ctx, blockEntity, doc, vt, theme, adjustedPixelSize, depth + 1);
+          drawInsert(ctx, blockEntity, doc, vt, theme, adjustedPixelSize, depth + 1, stats);
         } else {
-          drawEntity(ctx, blockEntity, doc, vt, theme, adjustedPixelSize);
+          drawEntity(ctx, blockEntity, doc, vt, theme, adjustedPixelSize, stats);
         }
       }
       ctx.restore();
@@ -2731,7 +2733,7 @@ function drawInsert(ctx, entity, doc, vt, theme, pixelSize, depth = 0) {
 }
 
 // src/renderer/entities/draw-dimension.ts
-function drawDimension(ctx, entity, doc, vt, theme, pixelSize) {
+function drawDimension(ctx, entity, doc, vt, theme, pixelSize, stats) {
   if (entity.blockName) {
     const block = doc.blocks.get(entity.blockName);
     if (block) {
@@ -2740,7 +2742,7 @@ function drawDimension(ctx, entity, doc, vt, theme, pixelSize) {
         ctx.strokeStyle = color;
         ctx.fillStyle = color;
         ctx.lineWidth = pixelSize;
-        drawEntity(ctx, blockEntity, doc, vt, theme, pixelSize);
+        drawEntity(ctx, blockEntity, doc, vt, theme, pixelSize, stats);
       }
       return;
     }
@@ -2817,7 +2819,11 @@ function drawPoint(ctx, entity, pixelSize) {
 }
 
 // src/renderer/entities/draw-entity.ts
-function drawEntity(ctx, entity, doc, vt, theme, pixelSize) {
+function drawEntity(ctx, entity, doc, vt, theme, pixelSize, stats) {
+  if (stats) {
+    stats.drawCalls++;
+    stats.byType[entity.type] = (stats.byType[entity.type] ?? 0) + 1;
+  }
   switch (entity.type) {
     case "LINE":
       drawLine(ctx, entity);
@@ -2847,10 +2853,10 @@ function drawEntity(ctx, entity, doc, vt, theme, pixelSize) {
       drawMText(ctx, entity, pixelSize);
       break;
     case "INSERT":
-      drawInsert(ctx, entity, doc, vt, theme, pixelSize);
+      drawInsert(ctx, entity, doc, vt, theme, pixelSize, 0, stats);
       break;
     case "DIMENSION":
-      drawDimension(ctx, entity, doc, vt, theme, pixelSize);
+      drawDimension(ctx, entity, doc, vt, theme, pixelSize, stats);
       break;
     case "HATCH":
       drawHatch(ctx, entity);
@@ -2897,6 +2903,12 @@ var CanvasRenderer = class {
   render(doc, vt, theme, visibleLayers, selectedEntityIndex) {
     const ctx = this.ctx;
     const dpr = window.devicePixelRatio || 1;
+    const stats = {
+      entitiesDrawn: 0,
+      entitiesSkipped: 0,
+      drawCalls: 0,
+      byType: {}
+    };
     ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
     ctx.fillStyle = THEMES[theme].backgroundColor;
     ctx.fillRect(0, 0, this.width, this.height);
@@ -2906,13 +2918,20 @@ var CanvasRenderer = class {
     ctx.lineJoin = "round";
     for (let i = 0; i < doc.entities.length; i++) {
       const entity = doc.entities[i];
-      if (!entity.visible) continue;
-      if (!visibleLayers.has(entity.layer)) continue;
+      if (!entity.visible) {
+        stats.entitiesSkipped++;
+        continue;
+      }
+      if (!visibleLayers.has(entity.layer)) {
+        stats.entitiesSkipped++;
+        continue;
+      }
       const color = resolveEntityColor(entity, doc.layers, theme);
       ctx.strokeStyle = color;
       ctx.fillStyle = color;
       ctx.lineWidth = pixelSize;
-      drawEntity(ctx, entity, doc, vt, theme, pixelSize);
+      stats.entitiesDrawn++;
+      drawEntity(ctx, entity, doc, vt, theme, pixelSize, stats);
     }
     if (selectedEntityIndex >= 0 && selectedEntityIndex < doc.entities.length) {
       const selEntity = doc.entities[selectedEntityIndex];
@@ -2922,6 +2941,7 @@ var CanvasRenderer = class {
       ctx.lineWidth = pixelSize * 3;
       drawEntity(ctx, selEntity, doc, vt, theme, pixelSize);
     }
+    return stats;
   }
   renderEmpty(theme) {
     const ctx = this.ctx;
@@ -2934,6 +2954,136 @@ var CanvasRenderer = class {
   }
 };
 
+// src/renderer/debug-overlay.ts
+var DEFAULT_DEBUG_OPTIONS = {
+  showFps: true,
+  showRenderStats: true,
+  showDocumentInfo: true,
+  showTimings: true,
+  showCamera: true,
+  position: "top-left"
+};
+function resolveDebugOptions(input) {
+  return { ...DEFAULT_DEBUG_OPTIONS, ...input };
+}
+function formatBytes(bytes) {
+  if (bytes === 0) return "0 B";
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function formatZoom(scale) {
+  if (scale >= 1) return `${scale.toFixed(2)}x`;
+  return `1:${(1 / scale).toFixed(1)}`;
+}
+var FONT = "11px monospace";
+var LINE_HEIGHT = 15;
+var SEPARATOR_HEIGHT = 8;
+var PADDING = 8;
+var MARGIN = 10;
+function renderDebugOverlay(ctx, stats, theme, options, canvasWidth, canvasHeight) {
+  ctx.setTransform(1, 0, 0, 1, 0, 0);
+  const sections = [];
+  if (options.showFps) {
+    sections.push([
+      `FPS: ${stats.fps}  Frame: ${stats.frameTime.toFixed(1)}ms`
+    ]);
+  }
+  if (options.showRenderStats) {
+    const total = stats.renderStats.entitiesDrawn + stats.renderStats.entitiesSkipped;
+    const lines = [
+      `Drawn: ${stats.renderStats.entitiesDrawn} / ${total}  Calls: ${stats.renderStats.drawCalls}`
+    ];
+    const types = Object.entries(stats.renderStats.byType).sort(([, a], [, b]) => b - a).slice(0, 6).map(([type, count]) => `${type}: ${count}`).join("  ");
+    if (types) lines.push(types);
+    sections.push(lines);
+  }
+  if (options.showDocumentInfo) {
+    const lines = [
+      `Layers: ${stats.visibleLayerCount} / ${stats.layerCount}  Blocks: ${stats.blockCount}`
+    ];
+    if (stats.dxfVersion) lines.push(`DXF: ${stats.dxfVersion}`);
+    if (stats.fileName) lines.push(`File: ${stats.fileName}`);
+    if (stats.fileSize > 0) lines.push(`Size: ${formatBytes(stats.fileSize)}`);
+    sections.push(lines);
+  }
+  if (options.showTimings) {
+    const parts = [];
+    if (stats.parseTime > 0) parts.push(`Parse: ${stats.parseTime.toFixed(0)}ms`);
+    if (stats.spatialIndexBuildTime > 0) parts.push(`Index: ${stats.spatialIndexBuildTime.toFixed(0)}ms`);
+    if (stats.totalLoadTime > 0) parts.push(`Load: ${stats.totalLoadTime.toFixed(0)}ms`);
+    if (parts.length > 0) {
+      sections.push([parts.join("  ")]);
+    }
+  }
+  if (options.showCamera) {
+    const b = stats.viewportBounds;
+    sections.push([
+      `Zoom: ${formatZoom(stats.zoom)}  Pixel: ${stats.pixelSize.toFixed(2)}`,
+      `View: [${b.minX.toFixed(0)}, ${b.minY.toFixed(0)}] \u2192 [${b.maxX.toFixed(0)}, ${b.maxY.toFixed(0)}]`
+    ]);
+  }
+  if (sections.length === 0) return;
+  ctx.font = FONT;
+  const rows = [];
+  for (let s = 0; s < sections.length; s++) {
+    if (s > 0) rows.push({ text: "", isSeparator: true });
+    for (const line of sections[s]) {
+      rows.push({ text: line, isSeparator: false });
+    }
+  }
+  let maxWidth = 0;
+  for (const row of rows) {
+    if (!row.isSeparator) {
+      const w = ctx.measureText(row.text).width;
+      if (w > maxWidth) maxWidth = w;
+    }
+  }
+  const panelWidth = maxWidth + PADDING * 2;
+  let panelHeight = PADDING * 2;
+  for (const row of rows) {
+    panelHeight += row.isSeparator ? SEPARATOR_HEIGHT : LINE_HEIGHT;
+  }
+  let x;
+  let y;
+  switch (options.position) {
+    case "top-left":
+      x = MARGIN;
+      y = MARGIN;
+      break;
+    case "top-right":
+      x = canvasWidth - panelWidth - MARGIN;
+      y = MARGIN;
+      break;
+    case "bottom-left":
+      x = MARGIN;
+      y = canvasHeight - panelHeight - MARGIN;
+      break;
+    case "bottom-right":
+      x = canvasWidth - panelWidth - MARGIN;
+      y = canvasHeight - panelHeight - MARGIN;
+      break;
+  }
+  const config = THEMES[theme];
+  ctx.fillStyle = theme === "dark" ? "rgba(0, 0, 0, 0.75)" : "rgba(255, 255, 255, 0.85)";
+  ctx.fillRect(x, y, panelWidth, panelHeight);
+  ctx.strokeStyle = theme === "dark" ? "rgba(255, 255, 255, 0.15)" : "rgba(0, 0, 0, 0.15)";
+  ctx.lineWidth = 1;
+  ctx.strokeRect(x + 0.5, y + 0.5, panelWidth - 1, panelHeight - 1);
+  ctx.fillStyle = theme === "dark" ? config.defaultEntityColor : "rgba(0, 0, 0, 0.85)";
+  ctx.textAlign = "left";
+  ctx.textBaseline = "top";
+  let cursorY = y + PADDING;
+  for (const row of rows) {
+    if (row.isSeparator) {
+      cursorY += SEPARATOR_HEIGHT;
+    } else {
+      ctx.fillText(row.text, x + PADDING, cursorY);
+      cursorY += LINE_HEIGHT;
+    }
+  }
+}
+
 // src/viewer/layers.ts
 var LayerManager = class {
   layers = /* @__PURE__ */ new Map();
@@ -3717,11 +3867,26 @@ var CadViewer = class {
   currentTool;
   inputHandler;
   resizeObserver;
+  formatConverters;
   selectedEntityIndex = -1;
   renderPending = false;
   destroyed = false;
+  loadGeneration = 0;
   mouseScreenX = 0;
   mouseScreenY = 0;
+  // Debug mode state
+  debugEnabled = false;
+  debugOptions;
+  lastRenderStats = null;
+  lastDebugStats = null;
+  frameTimestamps = [];
+  lastDoRenderTime = 0;
+  lastFrameTime = 0;
+  parseTime = 0;
+  spatialIndexBuildTime = 0;
+  loadedFileName = null;
+  loadedFileSize = 0;
+  debugRafId = 0;
   constructor(canvas, options) {
     this.canvas = canvas;
     this.options = {
@@ -3733,6 +3898,15 @@ var CadViewer = class {
       zoomSpeed: options?.zoomSpeed ?? 1.1,
       initialTool: options?.initialTool ?? "pan"
     };
+    this.formatConverters = options?.formatConverters ?? [];
+    if (options?.debug) {
+      this.debugEnabled = true;
+      this.debugOptions = resolveDebugOptions(
+        typeof options.debug === "boolean" ? void 0 : options.debug
+      );
+    } else {
+      this.debugOptions = resolveDebugOptions();
+    }
     this.renderer = new CanvasRenderer(canvas);
     this.camera = new Camera(this.options);
     this.layerManager = new LayerManager();
@@ -3745,24 +3919,124 @@ var CadViewer = class {
     this.resizeObserver.observe(canvas);
     canvas.style.cursor = this.getCursorForTool(this.currentTool);
     this.requestRender();
+    if (this.debugEnabled) {
+      this.startDebugLoop();
+    }
   }
   // === Loading ===
+  /**
+   * Throws if the viewer has been destroyed.
+   * Call at the start of any public method that mutates state.
+   */
+  guardDestroyed() {
+    if (this.destroyed) {
+      throw new Error("CadViewer: cannot call methods on a destroyed instance.");
+    }
+  }
+  /**
+   * 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.
+   */
+  async runConverters(buffer) {
+    for (const converter of this.formatConverters) {
+      let detected = false;
+      try {
+        detected = converter.detect(buffer);
+      } catch {
+        continue;
+      }
+      if (detected) {
+        return converter.convert(buffer);
+      }
+    }
+    return null;
+  }
+  /**
+   * 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.
+   */
   async loadFile(file) {
+    this.guardDestroyed();
+    const generation = ++this.loadGeneration;
+    this.loadedFileName = file.name;
+    this.loadedFileSize = file.size;
     const buffer = await file.arrayBuffer();
-    this.loadArrayBuffer(buffer);
+    if (this.destroyed || generation !== this.loadGeneration) return;
+    const dxfString = await this.runConverters(buffer);
+    if (this.destroyed || generation !== this.loadGeneration) return;
+    const t0 = performance.now();
+    this.doc = dxfString != null ? parseDxf(dxfString) : parseDxf(buffer);
+    this.parseTime = performance.now() - t0;
+    this.onDocumentLoaded();
   }
+  /**
+   * 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.
+   */
+  async loadBuffer(buffer) {
+    this.guardDestroyed();
+    const generation = ++this.loadGeneration;
+    this.loadedFileName = null;
+    this.loadedFileSize = buffer.byteLength;
+    const dxfString = await this.runConverters(buffer);
+    if (this.destroyed || generation !== this.loadGeneration) return;
+    const t0 = performance.now();
+    this.doc = dxfString != null ? parseDxf(dxfString) : parseDxf(buffer);
+    this.parseTime = performance.now() - t0;
+    this.onDocumentLoaded();
+  }
+  /**
+   * Load a pre-parsed DxfDocument directly, bypassing the parser.
+   * Useful for custom parsers or pre-processed documents.
+   */
+  loadDocument(doc) {
+    this.guardDestroyed();
+    ++this.loadGeneration;
+    this.loadedFileName = null;
+    this.loadedFileSize = 0;
+    this.parseTime = 0;
+    if (!doc || !Array.isArray(doc.entities) || !(doc.layers instanceof Map)) {
+      throw new Error("CadViewer: invalid DxfDocument \u2014 expected entities array and layers Map.");
+    }
+    this.doc = doc;
+    this.onDocumentLoaded();
+  }
+  /**
+   * Load a DXF string directly (synchronous, no format conversion).
+   */
   loadString(dxf) {
+    this.guardDestroyed();
+    ++this.loadGeneration;
+    this.loadedFileName = null;
+    this.loadedFileSize = dxf.length;
+    const t0 = performance.now();
     this.doc = parseDxf(dxf);
+    this.parseTime = performance.now() - t0;
     this.onDocumentLoaded();
   }
+  /**
+   * 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) {
+    this.guardDestroyed();
+    ++this.loadGeneration;
+    this.loadedFileName = null;
+    this.loadedFileSize = buffer.byteLength;
+    const t0 = performance.now();
     this.doc = parseDxf(buffer);
+    this.parseTime = performance.now() - t0;
     this.onDocumentLoaded();
   }
   /**
    * Clear the current document and reset all state without destroying the viewer.
    */
   clearDocument() {
+    this.guardDestroyed();
+    ++this.loadGeneration;
     this.doc = null;
     this.selectedEntityIndex = -1;
     this.spatialIndex.clear();
@@ -3773,7 +4047,9 @@ var CadViewer = class {
   onDocumentLoaded() {
     if (!this.doc) return;
     this.layerManager.setLayers(this.doc.layers);
+    const t0 = performance.now();
     this.spatialIndex.build(this.doc.entities);
+    this.spatialIndexBuildTime = performance.now() - t0;
     this.selectedEntityIndex = -1;
     this.measureTool.deactivate();
     if (this.currentTool === "measure") {
@@ -3783,6 +4059,7 @@ var CadViewer = class {
   }
   // === Camera Controls ===
   fitToView() {
+    this.guardDestroyed();
     if (!this.doc) return;
     const bounds = this.computeDocumentBounds();
     if (!bounds) return;
@@ -3794,6 +4071,7 @@ var CadViewer = class {
     this.emitter.emit("viewchange", this.camera.getTransform());
   }
   zoomTo(scale) {
+    this.guardDestroyed();
     const rect = this.canvas.getBoundingClientRect();
     const centerX = rect.width / 2;
     const centerY = rect.height / 2;
@@ -3803,6 +4081,7 @@ var CadViewer = class {
     this.emitter.emit("viewchange", this.camera.getTransform());
   }
   panTo(worldX, worldY) {
+    this.guardDestroyed();
     const rect = this.canvas.getBoundingClientRect();
     const vt = this.camera.getTransform();
     const currentSX = worldX * vt.scale + vt.offsetX;
@@ -3825,15 +4104,18 @@ var CadViewer = class {
     return this.layerManager.getAllLayers();
   }
   setLayerVisible(name, visible) {
+    this.guardDestroyed();
     this.layerManager.setVisible(name, visible);
     this.requestRender();
   }
   setLayerColor(name, color) {
+    this.guardDestroyed();
     this.layerManager.setColorOverride(name, color);
     this.requestRender();
   }
   // === Theme ===
   setTheme(theme) {
+    this.guardDestroyed();
     this.options.theme = theme;
     this.requestRender();
   }
@@ -3841,11 +4123,13 @@ var CadViewer = class {
     return this.options.theme;
   }
   setBackgroundColor(color) {
+    this.guardDestroyed();
     this.options.backgroundColor = color;
     this.requestRender();
   }
   // === Tools ===
   setTool(tool) {
+    this.guardDestroyed();
     if (this.currentTool === "measure" && tool !== "measure") {
       this.measureTool.deactivate();
     }
@@ -3893,6 +4177,7 @@ var CadViewer = class {
   }
   destroy() {
     this.destroyed = true;
+    this.stopDebugLoop();
     this.inputHandler.destroy();
     this.resizeObserver.disconnect();
     this.renderer.destroy();
@@ -3904,7 +4189,12 @@ var CadViewer = class {
   // === Internal (called by InputHandler) ===
   /** @internal */
   requestRender() {
-    if (this.renderPending || this.destroyed) return;
+    if (this.destroyed) return;
+    if (this.debugRafId) {
+      this.doRender();
+      return;
+    }
+    if (this.renderPending) return;
     this.renderPending = true;
     requestAnimationFrame(() => {
       this.renderPending = false;
@@ -3917,13 +4207,24 @@ var CadViewer = class {
       this.renderer.renderEmpty(this.options.theme);
       return;
     }
-    this.renderer.render(
+    const renderStart = performance.now();
+    const stats = this.renderer.render(
       this.doc,
       this.camera.getTransform(),
       this.options.theme,
       this.layerManager.getVisibleLayerNames(),
       this.selectedEntityIndex
     );
+    this.lastFrameTime = performance.now() - renderStart;
+    this.lastRenderStats = stats;
+    const now = performance.now();
+    if (now - this.lastDoRenderTime >= 3) {
+      this.frameTimestamps.push(now);
+    }
+    this.lastDoRenderTime = now;
+    while (this.frameTimestamps.length > 0 && this.frameTimestamps[0] < now - 1e3) {
+      this.frameTimestamps.shift();
+    }
     if (this.currentTool === "measure" && this.measureTool.state.phase !== "idle") {
       const ctx = this.renderer.getContext();
       renderMeasureOverlay(
@@ -3935,7 +4236,104 @@ var CadViewer = class {
         this.options.theme
       );
     }
+    if (this.debugEnabled) {
+      const ctx = this.renderer.getContext();
+      const debugStats = this.buildDebugStats();
+      this.lastDebugStats = debugStats;
+      renderDebugOverlay(
+        ctx,
+        debugStats,
+        this.options.theme,
+        this.debugOptions,
+        this.renderer.getWidth(),
+        this.renderer.getHeight()
+      );
+    }
   }
+  // === Debug Mode ===
+  /**
+   * Enable or disable the debug overlay.
+   * Pass `true` for defaults, `false` to disable, or an object for granular control.
+   */
+  setDebug(debug) {
+    this.guardDestroyed();
+    if (typeof debug === "boolean") {
+      this.debugEnabled = debug;
+    } else {
+      this.debugEnabled = true;
+      this.debugOptions = resolveDebugOptions(debug);
+    }
+    if (this.debugEnabled) {
+      this.startDebugLoop();
+    } else {
+      this.stopDebugLoop();
+      this.requestRender();
+    }
+  }
+  startDebugLoop() {
+    if (this.debugRafId) return;
+    const loop = () => {
+      if (!this.debugEnabled || this.destroyed) {
+        this.debugRafId = 0;
+        return;
+      }
+      this.doRender();
+      this.debugRafId = requestAnimationFrame(loop);
+    };
+    this.debugRafId = requestAnimationFrame(loop);
+  }
+  stopDebugLoop() {
+    if (this.debugRafId) {
+      cancelAnimationFrame(this.debugRafId);
+      this.debugRafId = 0;
+    }
+  }
+  /**
+   * Get the latest debug stats snapshot, or null if debug mode is off.
+   */
+  getDebugStats() {
+    return this.debugEnabled ? this.lastDebugStats : null;
+  }
+  buildDebugStats() {
+    const vt = this.camera.getTransform();
+    const w = this.renderer.getWidth();
+    const h = this.renderer.getHeight();
+    const bounds = this.computeViewportBounds(vt, w, h);
+    return {
+      fps: this.frameTimestamps.length,
+      frameTime: this.lastFrameTime,
+      renderStats: this.lastRenderStats ?? {
+        entitiesDrawn: 0,
+        entitiesSkipped: 0,
+        drawCalls: 0,
+        byType: {}
+      },
+      entityCount: this.doc?.entities.length ?? 0,
+      layerCount: this.doc?.layers.size ?? 0,
+      visibleLayerCount: this.layerManager.getVisibleLayerNames().size,
+      blockCount: this.doc?.blocks.size ?? 0,
+      parseTime: this.parseTime,
+      spatialIndexBuildTime: this.spatialIndexBuildTime,
+      totalLoadTime: this.parseTime + this.spatialIndexBuildTime,
+      zoom: vt.scale,
+      pixelSize: vt.scale > 0 ? 1 / vt.scale : 0,
+      viewportBounds: bounds,
+      fileName: this.loadedFileName,
+      fileSize: this.loadedFileSize,
+      dxfVersion: this.doc?.header.acadVersion ?? null
+    };
+  }
+  computeViewportBounds(vt, w, h) {
+    const [x1, y1] = screenToWorld(vt, 0, h);
+    const [x2, y2] = screenToWorld(vt, w, 0);
+    return {
+      minX: Math.min(x1, x2),
+      minY: Math.min(y1, y2),
+      maxX: Math.max(x1, x2),
+      maxY: Math.max(y1, y2)
+    };
+  }
+  // === Internal (called by InputHandler) ===
   /** @internal */
   handlePan(dx, dy) {
     this.camera.pan(dx, dy);
@@ -4038,6 +4436,7 @@ exports.findSnaps = findSnaps;
 exports.fitToView = fitToView;
 exports.hitTest = hitTest;
 exports.parseDxf = parseDxf;
+exports.renderDebugOverlay = renderDebugOverlay;
 exports.renderMeasureOverlay = renderMeasureOverlay;
 exports.resolveEntityColor = resolveEntityColor;
 exports.screenToWorld = screenToWorld;