@flyfish-dev/cad-viewer 0.6.3 → 0.6.5

package/README.md

@@ -12,6 +12,19 @@ The project provides a clean loader architecture for **DWG**, **DXF**, **DWF**,
 
 > DWG support uses `@mlightcad/libredwg-web` / LibreDWG WebAssembly in a worker. DXF support uses JavaScript parsing plus a built-in fallback parser. DWF, DWFx and XPS support is powered by `dwf-viewer` 0.6.x, including DWF 6+ ZIP containers, WHIP/W2D 2D sheets, W3D/HSF 3D eModel geometry, DWFx/OPC/XPS pages, adaptive CAD line weights and an optional raster WASM fallback.
 
+## What changed in 0.6.5
+
+- Preserved active DWG VPORT/header UCS saved views and applied safe planar scene transforms exactly once across geometry, text, inserts, bounds and interaction coordinates.
+- Added DWG LTYPE normalization and Canvas2D/WebGL rendering for dashed, dotted, BYLAYER and BYBLOCK linetypes, including continuous polyline phase and entity/global scale handling.
+- Preserved LibreDWG closed-polyline flags and added guarded fallbacks for tilted views, complex SHX linetype glyphs and pathological microscopic patterns.
+- Added public line-pattern helpers, `getSourceDocument()` and an eight-case DWG normalization regression suite.
+
+## What changed in 0.6.4
+
+- Added a stable package export for `@flyfish-dev/cad-viewer/wasm/dwg-worker.js`.
+- DWG worker loading now defaults to the page-relative runtime asset `wasm/dwg-worker.js`, making npm package assets and static demo deployments use the same worker file.
+- Dev, demo, Cloudflare Pages and npm library builds now build and copy the DWG worker asset explicitly before serving or packaging runtime files.
+
 ## What changed in 0.6.3
 
 - Added `dxfEncoding` for overriding DXF text decoding when legacy files omit or misdeclare `$DWGCODEPAGE`.
@@ -79,6 +92,7 @@ The project provides a clean loader architecture for **DWG**, **DXF**, **DWF**,
 - **Pure frontend viewer component**: `new CadViewer({ container })` or `new CadViewer({ canvas })`.
 - **Loader registry**: DWG, DXF and DWF loaders are independent and replaceable; native-renderable loaders can mount their own optimized viewer.
 - **DWG preview**: browser-local parsing through LibreDWG WebAssembly, executed in a Web Worker by default.
+- **DWG view and linetype fidelity**: active planar saved views, closed polylines, LTYPE tables, BYLAYER/BYBLOCK inheritance, dash/dot patterns and stable pattern scaling.
 - **DXF preview**: JavaScript parser path with fallback support for common ASCII DXF `ENTITIES`.
 - **DWF/DWFx/XPS preview**: powered by `dwf-viewer` for DWF ZIP packages, WebGL-accelerated W2D and XPS/DWFx 2D vectors, W3D/HSF eModel geometry, embedded XPS fonts, adaptive CAD line weights and raster fallback.
 - **CAD color handling**: ACI, BYLAYER, BYBLOCK inheritance, DWG layer colors, true color, fill color, opacity and adaptive contrast.
@@ -99,16 +113,18 @@ npm install
 npm run dev
 ```
 
-The DWG and DWF render paths need runtime WASM assets in a public directory. This repository copies and validates them for the demo:
+The DWG and DWF render paths need runtime assets in a public directory: `libredwg-web.js`, `libredwg-web.wasm`, `dwg-worker.js` and `dwfv-render.wasm`. This repository copies, builds and validates them for the demo:
 
 ```bash
 npm run copy:wasm
+npm run build:worker
+npm run copy:worker
 npm run check:wasm
 ```
 
-The demo resolves `wasmPath` to an absolute URL before sending it to the DWG worker and uses the same directory for `dwfv-render.wasm`. In your own app, prefer an absolute path or URL, for example `/wasm` or `new URL('wasm/', document.baseURI).href`. Avoid passing a worker-relative path such as `./wasm` unless it is resolved on the UI thread first.
+The demo resolves `wasmPath` to an absolute URL before sending it to the DWG worker and uses the same directory for `dwfv-render.wasm`. The default DWG worker URL is `wasm/dwg-worker.js`, resolved against the page URL. In your own app, prefer absolute paths or URLs, for example `/wasm`, `/wasm/dwg-worker.js` or `new URL('wasm/', document.baseURI).href`. Avoid passing a worker-relative path such as `./wasm` unless it is resolved on the UI thread first.
 
-When publishing the npm package, `build:lib` copies these files into `dist/wasm` and exposes them as package subpaths. Applications still need to serve the `.wasm` files from a public URL and pass that directory as `wasmPath`, or pass `dwfWasmUrl` explicitly.
+When publishing the npm package, `build:lib` copies these files into `dist/wasm` and exposes them as package subpaths, including `./wasm/dwg-worker.js`. Applications still need to serve the runtime files from a public URL and pass that directory as `wasmPath`, or pass `dwfWasmUrl` / `workerUrl` explicitly.
 
 
 ## Demo startup notes
@@ -198,7 +214,7 @@ For very large drawings, lower `maxCurveSegments`, increase `spatialIndexCellCou
 
 ## Worker-backed DWG parsing
 
-`DwgLoader` uses a module Web Worker by default in browsers. The worker imports `@mlightcad/libredwg-web`, initializes LibreDWG WASM inside the worker thread, caches that WASM instance, decodes DWG bytes, normalizes the result into a structured-clone-safe `CadDocument`, and sends only the normalized scene back to the UI thread. Canvas rendering remains on the main thread.
+`DwgLoader` uses a module Web Worker by default in browsers. The default worker URL is `wasm/dwg-worker.js`, resolved relative to the page. The worker imports `@mlightcad/libredwg-web`, initializes LibreDWG WASM inside the worker thread, caches that WASM instance, decodes DWG bytes, normalizes the result into a structured-clone-safe `CadDocument`, and sends only the normalized scene back to the UI thread. Canvas rendering remains on the main thread.
 
 ```ts
 const controller = new AbortController();
@@ -221,7 +237,7 @@ await viewer.loadFile(file, { signal: controller.signal });
 controller.abort();
 ```
 
-Advanced deployments can override the worker constructor when the bundler or CDN has a custom asset layout:
+Advanced deployments can override the worker URL or constructor when the bundler or CDN has a custom asset layout:
 
 ```ts
 new CadViewer({
@@ -241,7 +257,7 @@ const viewer = new CadViewer({
   container,             // HTMLElement; creates a canvas inside
   canvas,                // optional existing HTMLCanvasElement
   renderer: 'auto',      // 'auto' | 'webgl' | 'canvas2d'
-  wasmPath: '/wasm',     // directory containing libredwg-web.wasm and dwfv-render.wasm
+  wasmPath: '/wasm',     // directory containing libredwg-web.js, libredwg-web.wasm and dwfv-render.wasm
   dxfEncoding: 'gb18030', // optional override when legacy DXF codepage metadata is wrong
   dwfWasmUrl: '/wasm/dwfv-render.wasm',
   autoFit: true,
@@ -261,6 +277,7 @@ const viewer = new CadViewer({
     maxVisibleTextLabels: 2400
   },
   useWorker: true,                 // default for DWG
+  workerUrl: '/wasm/dwg-worker.js', // optional override; this is the default path
   workerTimeoutMs: 0,              // 0 = disabled
   dwfPreferWebgl: true,
   dwfPreferWasm: true,
@@ -282,6 +299,8 @@ viewer.zoomIn();
 viewer.zoomOut();
 await viewer.preloadDwg();       // optional DWG worker/WASM warmup
 viewer.setCanvasOptions({ background: '#f7f8fb', foreground: '#111827' });
+viewer.getDocument();            // transformed render-space CadDocument
+viewer.getSourceDocument();      // parser-owned WCS CadDocument
 viewer.clear();
 viewer.destroy();
 ```
@@ -346,7 +365,7 @@ viewer.registerLoader({
 
 | Format | Loader | Coverage |
 |---|---|---|
-| DWG | `DwgLoader` | Uses LibreDWG WebAssembly. Rendering coverage depends on the entities exposed by LibreDWG conversion. |
+| DWG | `DwgLoader` | Uses LibreDWG WebAssembly. Preserves active planar saved views, closed polylines and LTYPE definitions; Canvas2D/WebGL render dash/dot patterns with BYLAYER/BYBLOCK inheritance. Complex SHX glyphs use a marker approximation. |
 | DXF | `DxfLoader` | Uses `dxf-parser` plus fallback parsing. Supports codepage-aware text decoding, CAD text escape normalization, core entities, blocks/inserts, colors/layers, polylines, hatch boundaries and splines as preview polylines. |
 | DWF | `DwfLoader` + `dwf-viewer` | DWF 6+ ZIP packages, WHIP/W2D 2D sheets, W3D/HSF 3D eModel pages, model tree metadata, WebGL rendering and optional WASM fallback. |
 | DWFx / XPS | `DwfLoader` + `dwf-viewer` | DWFx/OPC/XPS pages with WebGL-accelerated vector paths, embedded fonts, text, images, package resources and adaptive overview line weights through the native DWF renderer. |
@@ -376,6 +395,7 @@ new CadViewer({ canvasOptions: { trueColorByteOrder: 'bgr' } });
 npm install
 npm run dev          # run the demo
 npm run typecheck    # TypeScript validation
+npm test             # build the library and run DWG normalization regressions
 npm run build        # library + demo
 npm run preview      # preview built demo
 ```

package/README.zh-CN.md

@@ -12,6 +12,19 @@
 
 > DWG 使用 `@mlightcad/libredwg-web` / LibreDWG WebAssembly，并默认运行在 Worker 中。DXF 使用 JavaScript 解析器并带内置 fallback。DWF、DWFx、XPS 由 `dwf-viewer` 0.6.x 驱动，覆盖 DWF 6+ ZIP 包、WHIP/W2D 2D 图纸、W3D/HSF 3D eModel、DWFx/OPC/XPS 页面、自适应 CAD 线宽和可选 raster WASM fallback。
 
+## 0.6.5 变更
+
+- 保留 DWG active VPORT/header UCS saved view，并将安全的平面场景变换只应用一次，统一覆盖几何、文字、INSERT、bounds 和交互坐标。
+- 新增 DWG LTYPE 归一化与 Canvas2D/WebGL 线型渲染，支持虚线、点线、BYLAYER、BYBLOCK、多段线连续相位以及实体/全局缩放。
+- 保留 LibreDWG 的闭合多段线标志；对倾斜视图、复杂 SHX 线型 glyph 和异常微小 pattern 提供明确降级策略。
+- 新增公开线型工具、`getSourceDocument()` 和 8 项 DWG normalization 回归测试。
+
+## 0.6.4 变更
+
+- 新增稳定的 package subpath：`@flyfish-dev/cad-viewer/wasm/dwg-worker.js`。
+- DWG worker 默认改为页面相对运行时资源 `wasm/dwg-worker.js`，npm 包资源和静态 Demo 部署使用同一份 worker 文件。
+- dev、demo、Cloudflare Pages 和 npm library 构建都会显式构建并复制 DWG worker 运行时资源。
+
 ## 0.6.3 变更
 
 - 新增 `dxfEncoding`，用于旧 DXF 缺少或误写 `$DWGCODEPAGE` 时显式指定文本编码。
@@ -79,6 +92,7 @@
 - **纯前端组件**：`new CadViewer({ container })` 或 `new CadViewer({ canvas })`。
 - **正确的 loader 架构**：DWG / DXF / DWF 独立 loader，可替换、可扩展；native-renderable loader 可以挂载自己的优化渲染器。
 - **DWG 预览**：通过 LibreDWG WebAssembly 在浏览器本地解析，默认在 Web Worker 中执行。
+- **DWG 视图与线型保真**：active 平面 saved view、闭合多段线、LTYPE 表、BYLAYER/BYBLOCK 继承、dash/dot pattern 和稳定线型缩放。
 - **DXF 预览**：JavaScript 解析，支持常见 ASCII DXF `ENTITIES`，并带 fallback parser。
 - **DWF/DWFx/XPS 预览**：由 `dwf-viewer` 支持 DWF ZIP 包、WebGL 加速 W2D 与 XPS/DWFx 2D 矢量、W3D/HSF eModel、XPS 嵌入字体、自适应 CAD 线宽和 raster fallback。
 - **CAD 颜色处理**：支持 ACI、BYLAYER、BYBLOCK 继承、DWG 图层颜色、true color、填充色、透明度和自适应对比度。
@@ -99,16 +113,18 @@ npm install
 npm run dev
 ```
 
-DWG 和 DWF 渲染链路需要将运行时 WASM 文件放到公开目录。Demo 使用以下命令复制并校验到 `public/wasm`：
+DWG 和 DWF 渲染链路需要把运行时资源放到公开目录：`libredwg-web.js`、`libredwg-web.wasm`、`dwg-worker.js` 和 `dwfv-render.wasm`。Demo 使用以下命令复制、构建并校验到 `public/wasm`：
 
 ```bash
 npm run copy:wasm
+npm run build:worker
+npm run copy:worker
 npm run check:wasm
 ```
 
-Demo 会先把 `wasmPath` 解析为绝对 URL，再发送给 DWG worker，并复用同一目录查找 `dwfv-render.wasm`。你自己的应用也建议使用绝对路径或绝对 URL，例如 `/wasm` 或 `new URL('wasm/', document.baseURI).href`。不要直接把未解析的 `./wasm` 传入 worker，否则它可能会相对于 worker chunk 请求资源。
+Demo 会先把 `wasmPath` 解析为绝对 URL，再发送给 DWG worker，并复用同一目录查找 `dwfv-render.wasm`。默认 DWG worker 地址是 `wasm/dwg-worker.js`，相对于页面 URL 解析。你自己的应用也建议使用绝对路径或绝对 URL，例如 `/wasm`、`/wasm/dwg-worker.js` 或 `new URL('wasm/', document.baseURI).href`。不要直接把未解析的 `./wasm` 传入 worker，否则它可能会相对于 worker 请求资源。
 
-发布 npm 包时，`build:lib` 会把这些文件复制到 `dist/wasm` 并作为 package subpath 暴露出来。应用侧仍需要把 `.wasm` 放到可公开访问的 URL，并把该目录传给 `wasmPath`，或者显式传入 `dwfWasmUrl`。
+发布 npm 包时，`build:lib` 会把这些文件复制到 `dist/wasm` 并作为 package subpath 暴露出来，包括 `./wasm/dwg-worker.js`。应用侧仍需要把运行时资源放到可公开访问的 URL，并把该目录传给 `wasmPath`，或者显式传入 `dwfWasmUrl` / `workerUrl`。
 
 
 ## Demo 启动说明
@@ -198,7 +214,7 @@ new CadViewer({
 
 ## Worker 化 DWG 解析
 
-`DwgLoader` 在浏览器里默认使用 module Web Worker。Worker 内部导入 `@mlightcad/libredwg-web`，初始化 LibreDWG WASM，缓存该 WASM 实例，解码 DWG 字节，并把结果归一化为可 structured-clone 的 `CadDocument` 后发送回 UI 线程。Canvas 渲染仍然留在主线程。
+`DwgLoader` 在浏览器里默认使用 module Web Worker。默认 worker 地址是 `wasm/dwg-worker.js`，相对于页面 URL 解析。Worker 内部导入 `@mlightcad/libredwg-web`，初始化 LibreDWG WASM，缓存该 WASM 实例，解码 DWG 字节，并把结果归一化为可 structured-clone 的 `CadDocument` 后发送回 UI 线程。Canvas 渲染仍然留在主线程。
 
 ```ts
 const controller = new AbortController();
@@ -221,7 +237,7 @@ await viewer.loadFile(file, { signal: controller.signal });
 controller.abort();
 ```
 
-如果你的构建系统或 CDN 对 worker 资源路径有特殊要求，可以显式传入 worker 地址：
+如果你的构建系统或 CDN 对 worker 资源路径有特殊要求，可以显式传入 worker 地址或构造器：
 
 ```ts
 new CadViewer({
@@ -241,7 +257,7 @@ const viewer = new CadViewer({
   container,             // 容器元素，组件会自动创建 canvas
   canvas,                // 也可以传入已有 canvas
   renderer: 'auto',      // 'auto' | 'webgl' | 'canvas2d'
-  wasmPath: '/wasm',     // LibreDWG WebAssembly 资源路径。Worker 场景建议使用绝对路径/URL
+  wasmPath: '/wasm',     // 包含 libredwg-web.js、libredwg-web.wasm 和 dwfv-render.wasm 的目录
   dxfEncoding: 'gb18030', // 可选：旧 DXF codepage 元数据错误时显式指定编码
   dwfWasmUrl: '/wasm/dwfv-render.wasm',
   autoFit: true,
@@ -261,6 +277,7 @@ const viewer = new CadViewer({
     maxVisibleTextLabels: 2400
   },
   useWorker: true,                 // DWG 默认开启
+  workerUrl: '/wasm/dwg-worker.js', // 可选覆盖；这是默认地址
   workerTimeoutMs: 0,              // 0 表示不限制
   dwfPreferWebgl: true,
   dwfPreferWasm: true,
@@ -282,6 +299,8 @@ viewer.zoomIn();
 viewer.zoomOut();
 await viewer.preloadDwg();       // 可选 DWG worker/WASM 预热
 viewer.setCanvasOptions({ background: '#f7f8fb', foreground: '#111827' });
+viewer.getDocument();            // 已应用 saved view 的渲染场景 CadDocument
+viewer.getSourceDocument();      // parser 保留的原始 WCS CadDocument
 viewer.clear();
 viewer.destroy();
 ```
@@ -346,7 +365,7 @@ viewer.registerLoader({
 
 | 格式 | Loader | 支持范围 |
 |---|---|---|
-| DWG | `DwgLoader` | 使用 LibreDWG WebAssembly。渲染完整度取决于 LibreDWG converter 暴露出的实体。 |
+| DWG | `DwgLoader` | 使用 LibreDWG WebAssembly。保留 active 平面 saved view、闭合多段线和 LTYPE 定义；Canvas2D/WebGL 支持 dash/dot 与 BYLAYER/BYBLOCK 继承，复杂 SHX glyph 使用 marker 近似。 |
 | DXF | `DxfLoader` | 使用 `dxf-parser` + 内置 fallback。支持 codepage-aware 文本解码、CAD 文本转义归一化、基础实体、block/insert、颜色/图层、多段线、hatch boundary、spline 预览。 |
 | DWF | `DwfLoader` + `dwf-viewer` | DWF 6+ ZIP 包、WHIP/W2D 2D 图纸、W3D/HSF 3D eModel、模型树元数据、WebGL 渲染和可选 WASM fallback。 |
 | DWFx / XPS | `DwfLoader` + `dwf-viewer` | DWFx/OPC/XPS 页面，包含 WebGL 加速 vector path、嵌入字体、文本、图片、包内资源和自适应总览线宽，通过原生 DWF 渲染器展示。 |
@@ -376,6 +395,7 @@ new CadViewer({ canvasOptions: { trueColorByteOrder: 'bgr' } });
 npm install
 npm run dev          # 运行 demo
 npm run typecheck    # TypeScript 检查
+npm test             # 构建 library 并运行 DWG normalization 回归测试
 npm run build        # 构建 library + demo
 npm run preview      # 预览构建后的 demo
 ```