@flyfish-dev/cad-viewer 0.6.2 → 0.6.4

package/README.md

@@ -12,6 +12,18 @@ 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.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`.
+- DXF decoding now honors BOMs and `$DWGCODEPAGE` values such as `ANSI_936`, `CP936`, `GBK`, `BIG5`, `SHIFT_JIS` and Windows code pages before falling back.
+- DXF text entities now normalize common CAD escapes such as `\U+XXXX`, `%%c`, `%%d`, `%%p` and `\P`.
+
 ## What changed in 0.6.2
 
 - Updated the native DWF path to `dwf-viewer` 0.6.4 for upstream DWF/DWFx bug fixes while keeping this package on its own SemVer line.
@@ -93,16 +105,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
@@ -192,7 +206,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();
@@ -215,7 +229,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({
@@ -235,7 +249,8 @@ 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,
   canvasOptions: {
@@ -254,6 +269,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,
@@ -340,7 +356,7 @@ viewer.registerLoader({
 | Format | Loader | Coverage |
 |---|---|---|
 | DWG | `DwgLoader` | Uses LibreDWG WebAssembly. Rendering coverage depends on the entities exposed by LibreDWG conversion. |
-| DXF | `DxfLoader` | Uses `dxf-parser` plus fallback parsing. Supports core entities, blocks/inserts, colors/layers, polylines, text, hatch boundaries and splines as preview polylines. |
+| 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. |
 

package/README.zh-CN.md

@@ -12,6 +12,18 @@
 
 > 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.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` 时显式指定文本编码。
+- DXF 解码现在会优先识别 BOM 和 `$DWGCODEPAGE`，支持 `ANSI_936`、`CP936`、`GBK`、`BIG5`、`SHIFT_JIS` 以及 Windows code page，不再把中文 DXF 退到有损的 ISO-8859-1。
+- DXF 文本实体会归一化常见 CAD 转义，例如 `\U+XXXX`、`%%c`、`%%d`、`%%p` 和 `\P`。
+
 ## 0.6.2 变更
 
 - 原生 DWF 通道升级到 `dwf-viewer` 0.6.4，包含上游 DWF/DWFx bugfix；本包继续按自身 SemVer 发布为 0.6.2。
@@ -93,16 +105,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 启动说明
@@ -192,7 +206,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();
@@ -215,7 +229,7 @@ await viewer.loadFile(file, { signal: controller.signal });
 controller.abort();
 ```
 
-如果你的构建系统或 CDN 对 worker 资源路径有特殊要求，可以显式传入 worker 地址：
+如果你的构建系统或 CDN 对 worker 资源路径有特殊要求，可以显式传入 worker 地址或构造器：
 
 ```ts
 new CadViewer({
@@ -235,7 +249,8 @@ 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,
   canvasOptions: {
@@ -254,6 +269,7 @@ const viewer = new CadViewer({
     maxVisibleTextLabels: 2400
   },
   useWorker: true,                 // DWG 默认开启
+  workerUrl: '/wasm/dwg-worker.js', // 可选覆盖；这是默认地址
   workerTimeoutMs: 0,              // 0 表示不限制
   dwfPreferWebgl: true,
   dwfPreferWasm: true,
@@ -340,7 +356,7 @@ viewer.registerLoader({
 | 格式 | Loader | 支持范围 |
 |---|---|---|
 | DWG | `DwgLoader` | 使用 LibreDWG WebAssembly。渲染完整度取决于 LibreDWG converter 暴露出的实体。 |
-| DXF | `DxfLoader` | 使用 `dxf-parser` + 内置 fallback。支持基础实体、block/insert、颜色/图层、多段线、文字、hatch boundary、spline 预览。 |
+| 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 渲染器展示。 |