@mlightcad/cad-simple-viewer 1.8.0-preview.3 → 1.8.0-preview.4

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 mlightcad
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 mlightcad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,205 +1,207 @@
-# CAD Simple Viewer
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![npm version](https://img.shields.io/npm/v/@mlightcad/cad-simple-viewer.svg)](https://www.npmjs.com/package/@mlightcad/cad-simple-viewer)
-
-This package provides the **high-performance** core components of a CAD viewer such as document management, command handling, and collaboration between the UI and rendering engines. It's designed for optimal performance when handling large CAD files.
-
-This module doesn't depend on any UI framework and doesn't provide any UI except canvas. If you want to integrate a high-performance CAD viewer into a web application with your own UI, this module is the correct choice. It fully supports **mobile layout and touch interaction**—responsive chrome for phones and tablets, plus pinch-to-zoom, single-finger pan, and tap-to-select—so hosts can ship a mobile-friendly viewer without a separate mobile stack.
-
-## Key Features
-- Document management optimized for large files
-- Efficient command stack and undo/redo operations
-- Optimized integration with rendering engines
-- Performance-focused settings and context management
-- Framework-agnostic design for maximum flexibility
-- Mobile-ready layout and touch gestures for phones and tablets
-
-## When Should You Choose cad-simple-viewer?
-
-Use `cad-simple-viewer` if you need **core CAD logic only** (document management, command stack, rendering engine integration) without any UI framework dependencies. This package is ideal if:
-
-- You want to build your **own custom UI** or integrate CAD functionality into a non-Vue or non-web environment.
-- You require maximum flexibility and performance for handling large CAD files, and plan to connect the logic to your own rendering or UI layer.
-- You want a framework-agnostic solution that provides only the essential CAD operations and canvas rendering.
-
-**Recommended for:** Custom integrations, headless CAD processing, or advanced users building highly tailored CAD solutions.
-
-## Directory Structure (partial)
-- `src/app/` – Document/context management, settings
-- `src/command/` – Command implementations (open, zoom, select, etc.)
-- `src/editor/` – Command stack, input handling, global functions
-- `src/service/` – Layer/entity services and UI layer store
-- `src/view/` – Layout and scene management
-- `src/util/` – Utilities
-
-## Installation
-
-```bash
-npm install @mlightcad/cad-simple-viewer
-```
-
-## File open landing entry
-
-Landing pages that only need the file picker / data-source registry can import the DocManager-free subpath so the full viewer stays lazy:
-
-```ts
-import {
-  AcUiFileOpenPanel,
-  AcApDataSourceManager,
-  acapInvokeDataSourceMenuAction
-} from '@mlightcad/cad-simple-viewer/file-open-panel'
-```
-
-Pass cloud sources via `manager` / `getSources`. Load `@mlightcad/cad-simple-viewer` (main entry) only when opening a drawing.
-
-## Usage
-
-Please refer to [cad-simple-viewer-demo](https://github.com/mlight-lee/cad-simple-viewer-demo) on basic usage and advanced usage.
-
-To learn about the built-in notification center (and how to replace the default bell UI while still receiving font-missing and unsupported-entity alerts), see [docs/notification-center.md](./docs/notification-center.md).
-
-For the plain-DOM toolbar engine (`AcUiToolbar`, shortcut bar, and host customization), see [docs/toolbar.md](./docs/toolbar.md).
-
-### Plugins and data sources
-
-- **`pluginManager`** — load command plugins (`AcApPlugin`) via `loadPlugin` / `registerLazyPlugin`.
-- **`dataSourceManager`** — registry of drawing origins (built-in **local** and **URL**, plus optional cloud plugins such as `@mlightcad/cad-onedrive-plugin` and `@mlightcad/cad-google-drive-plugin`). Open menus in hosts rebuild from `acapBuildDataSourceMenu(dataSourceManager.list())`. Cloud sources that use a popup File Picker must keep **Sign in** and **Open** as separate clicks so browsers do not block the picker.
-
-While `cad-simple-viewer` doesn't support saving drawings to DWG/DXF files, it provides comprehensive support for **modifying drawings in real-time**. You can add, edit, and delete entities within the drawing, and the viewer will automatically update to reflect these changes.
-
-When you modify entities, you're working directly with the underlying drawing database. The viewer automatically detects these changes and updates the display accordingly. This real-time synchronization ensures that:
-
-- All modifications are immediately visible
-- The command stack properly tracks changes for undo/redo operations. This will be implemented soon.
-
-This capability makes `cad-simple-viewer` suitable for applications that need to not only display CAD files but also allow users to interact with and modify the drawing content.
-
-**Important Note**: The usage patterns in `cad-simple-viewer` are **very similar to AutoCAD RealDWG**. If you're familiar with AutoCAD RealDWG development, you'll find the API structure and workflow nearly identical. The main difference is that we use the [**realdwg-web API**](https://mlight-lee.github.io/realdwg-web/) instead of the native RealDWG libraries.
-
-In [cad-simple-viewer-demo](https://github.com/mlight-lee/cad-simple-viewer-demo) it demonstrates how to create one drawing with [**realdwg-web API**](https://mlight-lee.github.io/realdwg-web/).
-
-## Layer services
-
-Layer table mutations are centralized in `AcApLayerService`. UI integrations should use `AcApDocument.layerStore`, which observes that document's layer table and delegates mutations to its layer service.
-
-### Turning layers on/off from UI vs CLI
-
-`AcApLayerService.setLayerOn` accepts `{ switchCurrentLayer?: boolean }`:
-
-- **CLI commands** leave the default `false`. Batch helpers skip the current layer instead.
-- **UI callers** (`AcApLayerStore`, Vue `useLayers`) pass `true` so hiding or freezing the active layer moves `CLAYER` to another visible layer first.
-
-### LAYISO `LockAndFade` mode
-
-The `LockAndFade` isolation keyword matches AutoCAD naming but the viewer **locks** non-isolated layers only. It does not apply a visual fade; users are notified when selecting this mode in the `LAYISO` command.
-
-## Web Worker deployment
-
-The viewer ships an MTEXT layout worker. DXF is parsed by the built-in converter
-in `@mlightcad/data-model` (no separate worker). **DWG support is opt-in**: this
-package does not depend on or register `@mlightcad/libredwg-converter` (GPL).
-Hosts that need DWG must add that dependency (or another converter), deploy its
-worker (+ wasm) assets, register the converter, and optionally pass
-`webworkerFileUrls.dwgParser` for readiness checks.
-
-```typescript
-import {
-  AcApDocManager,
-  LIBREDWG_PARSER_WORKER_FILE,
-  MTEXT_RENDERER_WORKER_FILE
-} from '@mlightcad/cad-simple-viewer'
-import {
-  AcDbDatabaseConverterManager,
-  AcDbFileType
-} from '@mlightcad/data-model'
-import { AcDbLibreDwgConverter } from '@mlightcad/libredwg-converter'
-
-const dwgParserUrl = `./workers/${LIBREDWG_PARSER_WORKER_FILE}`
-AcDbDatabaseConverterManager.instance.register(
-  AcDbFileType.DWG,
-  new AcDbLibreDwgConverter({
-    convertByEntityType: false,
-    useWorker: true,
-    parserWorkerUrl: dwgParserUrl
-  })
-)
-
-const workerUrls = {
-  dwgParser: dwgParserUrl,
-  mtextRender: `./workers/${MTEXT_RENDERER_WORKER_FILE}`
-}
-
-// Option 1: check before creating the manager
-const ready = await AcApDocManager.checkWebworkerReadiness(workerUrls)
-if (!ready) {
-  throw new Error('CAD worker scripts are missing or blocked')
-}
-
-const manager = AcApDocManager.createInstance({ webworkerFileUrls: workerUrls })
-
-// Option 2: check on an existing manager instance
-if (!(await manager.areWorkersReady())) {
-  throw new Error('CAD worker scripts are missing or blocked')
-}
-```
-
-`areWorkersReady()` and `checkWebworkerReadiness()` use HEAD requests internally. Successful URL probes are cached for the current page lifecycle; failures are not cached at the probe layer, so a transient network error can succeed on a later `areWorkersReady()` call. After each check, `manager.workersReady` is `true` or `false` (`null` only before the first check). Only URLs you pass are probed — `dwgParser` is skipped when omitted.
-
-You can also enable automatic checks during initialization:
-
-```typescript
-AcApDocManager.createInstance({
-  webworkerFileUrls: workerUrls,
-  checkWorkersOnInit: true
-})
-
-manager.events.workersReady.addEventListener(({ ready }) => {
-  if (!ready) console.error('CAD workers are not reachable')
-})
-```
-
-## Available Exports
-
-### Core Classes
-
-- `AcApContext` - Main application context
-- `AcApDocManager` - Document management
-- `AcApDocument` - Individual document handling (includes `layerService` and `layerStore`)
-- `AcApSettingManager` - Settings management
-
-### Services
-
-- `AcApLayerService` - Layer table mutations with undo
-- `AcApLayerStore` - Cached layer rows and UI-friendly mutations (via `AcApDocument.layerStore`)
-- `AcApEntityService` - Entity selection, transform, and edit helpers
-- `acapRunServiceEdit` - Undo-wrapped edits outside command transactions
-
-### Commands
-
-- `AcApOpenCmd` - Open file command
-- `AcApZoomCmd` - Zoom command
-- `AcApPanCmd` - Pan command
-- `AcApSelectCmd` - Selection command
-
-SVG export (`csvg`) is provided by the optional `@mlightcad/cad-svg-plugin` package.
-
-### Editor Components
-
-- `AcEditor` - Main editor class
-- `AcEdCommandStack` - Command stack management
-- `AcEdSelectionSet` - Selection handling
-- `AcEdInputPoint` - Input point management
-
-### View Components
-
-- `AcTrScene` - Scene management
-- `AcTrLayoutView` - Layout view handling
-- `AcTrView2d` - 2D view management
-
-## Role in MLightCAD
-This package acts as the core logic layer, connecting the frontend UI with the rendering engines and managing all document-related operations.
-
-## License
-
+# CAD Simple Viewer
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/@mlightcad/cad-simple-viewer.svg)](https://www.npmjs.com/package/@mlightcad/cad-simple-viewer)
+
+This package provides the **high-performance** core components of a CAD viewer such as document management, command handling, and collaboration between the UI and rendering engines. It's designed for optimal performance when handling large CAD files.
+
+This module doesn't depend on any UI framework. Besides the canvas it can optionally mount plain-DOM **simple UI chrome** (toolbar + dock palettes for layers / find / review / measurements) via `AcApDocManagerOptions.simpleUi` (default **on**; types and helpers from `@mlightcad/cad-simple-viewer`). Pass `simpleUi: false` when you bring your own UI (e.g. Vue `cad-editor`) or run headless. It fully supports **mobile layout and touch interaction**—responsive chrome for phones and tablets, plus pinch-to-zoom, single-finger pan, and tap-to-select—so hosts can ship a mobile-friendly viewer without a separate mobile stack.
+
+## Key Features
+- Document management optimized for large files
+- Efficient command stack and undo/redo operations
+- Optimized integration with rendering engines
+- Performance-focused settings and context management
+- Framework-agnostic design for maximum flexibility
+- Mobile-ready layout and touch gestures for phones and tablets
+
+## When Should You Choose cad-simple-viewer?
+
+Use `cad-simple-viewer` if you need **core CAD logic only** (document management, command stack, rendering engine integration) without any UI framework dependencies. This package is ideal if:
+
+- You want to build your **own custom UI** or integrate CAD functionality into a non-Vue or non-web environment.
+- You require maximum flexibility and performance for handling large CAD files, and plan to connect the logic to your own rendering or UI layer.
+- You want a framework-agnostic solution that provides only the essential CAD operations and canvas rendering.
+
+**Recommended for:** Custom integrations, headless CAD processing, or advanced users building highly tailored CAD solutions.
+
+## Directory Structure (partial)
+- `src/app/` – Document/context management, settings
+- `src/command/` – Command implementations (open, zoom, select, etc.)
+- `src/editor/` – Command stack, input handling, global functions
+- `src/service/` – Layer/entity services and UI layer store
+- `src/view/` – Layout and scene management
+- `src/util/` – Utilities
+
+## Installation
+
+```bash
+npm install @mlightcad/cad-simple-viewer
+```
+
+## File open landing entry
+
+Landing pages that only need the file picker / data-source registry can import the DocManager-free subpath so the full viewer stays lazy:
+
+```ts
+import {
+  AcUiFileOpenPanel,
+  AcApDataSourceManager,
+  acapInvokeDataSourceMenuAction
+} from '@mlightcad/cad-simple-viewer/file-open-panel'
+```
+
+Pass cloud sources via `manager` / `getSources`. Load `@mlightcad/cad-simple-viewer` (main entry) only when opening a drawing.
+
+## Usage
+
+Please refer to [cad-simple-viewer-demo](https://github.com/mlight-lee/cad-simple-viewer-demo) on basic usage and advanced usage.
+
+To learn about the built-in notification center (and how to replace the default bell UI while still receiving font-missing and unsupported-entity alerts), see [docs/notification-center.md](./docs/notification-center.md).
+
+For the plain-DOM toolbar engine (`AcUiToolbar`, shortcut bar, and host customization), see [docs/toolbar.md](./docs/toolbar.md).
+
+For how Smart Blocks Search and Convert (`BSEARCH`) finds repeated geometry, pairs texts and converts copies into blocks, see [docs/smart-blocks-search-and-convert.md](./docs/smart-blocks-search-and-convert.md).
+
+### Plugins and data sources
+
+- **`pluginManager`** — load command plugins (`AcApPlugin`) via `loadPlugin` / `registerLazyPlugin`.
+- **`dataSourceManager`** — registry of drawing origins (built-in **local** and **URL**, plus optional cloud plugins such as `@mlightcad/cad-onedrive-plugin` and `@mlightcad/cad-google-drive-plugin`). Open menus in hosts rebuild from `acapBuildDataSourceMenu(dataSourceManager.list())`. Cloud sources that use a popup File Picker must keep **Sign in** and **Open** as separate clicks so browsers do not block the picker.
+
+While `cad-simple-viewer` doesn't support saving drawings to DWG/DXF files, it provides comprehensive support for **modifying drawings in real-time**. You can add, edit, and delete entities within the drawing, and the viewer will automatically update to reflect these changes.
+
+When you modify entities, you're working directly with the underlying drawing database. The viewer automatically detects these changes and updates the display accordingly. This real-time synchronization ensures that:
+
+- All modifications are immediately visible
+- The command stack properly tracks changes for undo/redo operations. This will be implemented soon.
+
+This capability makes `cad-simple-viewer` suitable for applications that need to not only display CAD files but also allow users to interact with and modify the drawing content.
+
+**Important Note**: The usage patterns in `cad-simple-viewer` are **very similar to AutoCAD RealDWG**. If you're familiar with AutoCAD RealDWG development, you'll find the API structure and workflow nearly identical. The main difference is that we use the [**realdwg-web API**](https://mlight-lee.github.io/realdwg-web/) instead of the native RealDWG libraries.
+
+In [cad-simple-viewer-demo](https://github.com/mlight-lee/cad-simple-viewer-demo) it demonstrates how to create one drawing with [**realdwg-web API**](https://mlight-lee.github.io/realdwg-web/).
+
+## Layer services
+
+Layer table mutations are centralized in `AcApLayerService`. UI integrations should use `AcApDocument.layerStore`, which observes that document's layer table and delegates mutations to its layer service.
+
+### Turning layers on/off from UI vs CLI
+
+`AcApLayerService.setLayerOn` accepts `{ switchCurrentLayer?: boolean }`:
+
+- **CLI commands** leave the default `false`. Batch helpers skip the current layer instead.
+- **UI callers** (`AcApLayerStore`, Vue `useLayers`) pass `true` so hiding or freezing the active layer moves `CLAYER` to another visible layer first.
+
+### LAYISO `LockAndFade` mode
+
+The `LockAndFade` isolation keyword matches AutoCAD naming but the viewer **locks** non-isolated layers only. It does not apply a visual fade; users are notified when selecting this mode in the `LAYISO` command.
+
+## Web Worker deployment
+
+The viewer ships an MTEXT layout worker. DXF is parsed by the built-in converter
+in `@mlightcad/data-model` (no separate worker). **DWG support is opt-in**: this
+package does not depend on or register `@mlightcad/libredwg-converter` (GPL).
+Hosts that need DWG must add that dependency (or another converter), deploy its
+worker (+ wasm) assets, register the converter, and optionally pass
+`webworkerFileUrls.dwgParser` for readiness checks.
+
+```typescript
+import {
+  AcApDocManager,
+  LIBREDWG_PARSER_WORKER_FILE,
+  MTEXT_RENDERER_WORKER_FILE
+} from '@mlightcad/cad-simple-viewer'
+import {
+  AcDbDatabaseConverterManager,
+  AcDbFileType
+} from '@mlightcad/data-model'
+import { AcDbLibreDwgConverter } from '@mlightcad/libredwg-converter'
+
+const dwgParserUrl = `./workers/${LIBREDWG_PARSER_WORKER_FILE}`
+AcDbDatabaseConverterManager.instance.register(
+  AcDbFileType.DWG,
+  new AcDbLibreDwgConverter({
+    convertByEntityType: false,
+    useWorker: true,
+    parserWorkerUrl: dwgParserUrl
+  })
+)
+
+const workerUrls = {
+  dwgParser: dwgParserUrl,
+  mtextRender: `./workers/${MTEXT_RENDERER_WORKER_FILE}`
+}
+
+// Option 1: check before creating the manager
+const ready = await AcApDocManager.checkWebworkerReadiness(workerUrls)
+if (!ready) {
+  throw new Error('CAD worker scripts are missing or blocked')
+}
+
+const manager = AcApDocManager.createInstance({ webworkerFileUrls: workerUrls })
+
+// Option 2: check on an existing manager instance
+if (!(await manager.areWorkersReady())) {
+  throw new Error('CAD worker scripts are missing or blocked')
+}
+```
+
+`areWorkersReady()` and `checkWebworkerReadiness()` use HEAD requests internally. Successful URL probes are cached for the current page lifecycle; failures are not cached at the probe layer, so a transient network error can succeed on a later `areWorkersReady()` call. After each check, `manager.workersReady` is `true` or `false` (`null` only before the first check). Only URLs you pass are probed — `dwgParser` is skipped when omitted.
+
+You can also enable automatic checks during initialization:
+
+```typescript
+AcApDocManager.createInstance({
+  webworkerFileUrls: workerUrls,
+  checkWorkersOnInit: true
+})
+
+manager.events.workersReady.addEventListener(({ ready }) => {
+  if (!ready) console.error('CAD workers are not reachable')
+})
+```
+
+## Available Exports
+
+### Core Classes
+
+- `AcApContext` - Main application context
+- `AcApDocManager` - Document management
+- `AcApDocument` - Individual document handling (includes `layerService` and `layerStore`)
+- `AcApSettingManager` - Settings management
+
+### Services
+
+- `AcApLayerService` - Layer table mutations with undo
+- `AcApLayerStore` - Cached layer rows and UI-friendly mutations (via `AcApDocument.layerStore`)
+- `AcApEntityService` - Entity selection, transform, and edit helpers
+- `acapRunServiceEdit` - Undo-wrapped edits outside command transactions
+
+### Commands
+
+- `AcApOpenCmd` - Open file command
+- `AcApZoomCmd` - Zoom command
+- `AcApPanCmd` - Pan command
+- `AcApSelectCmd` - Selection command
+
+SVG export (`csvg`) is provided by the optional `@mlightcad/cad-svg-plugin` package.
+
+### Editor Components
+
+- `AcEditor` - Main editor class
+- `AcEdCommandStack` - Command stack management
+- `AcEdSelectionSet` - Selection handling
+- `AcEdInputPoint` - Input point management
+
+### View Components
+
+- `AcTrScene` - Scene management
+- `AcTrLayoutView` - Layout view handling
+- `AcTrView2d` - 2D view management
+
+## Role in MLightCAD
+This package acts as the core logic layer, connecting the frontend UI with the rendering engines and managing all document-related operations.
+
+## License
+
 MIT