@mlightcad/cad-html-plugin

HTML export for @mlightcad/cad-simple-viewer: snapshot format, offline viewer runtime, and optional plugin integration.

| Command | Description | |---------|-------------| | -chtml | Export via command-line prompts (no dialog; AutoCAD-style - prefix) | | chtml | Same as -chtml when no UI command is registered (e.g. cad-simple-viewer only). In cad-viewer, chtml opens an export options dialog instead |

The plugin path is designed for lazy loading so the export bundle is only downloaded when a user runs -chtml or confirms export from the chtml dialog (or runs chtml in a host that has no dialog command). Low-level APIs (packHtml, snapshot types, scene collectors) are also exported for custom pipelines and the headless CLI @mlightcad/cad-html-exporter-cli.

Key features

• Display-only snapshot — layers, layouts, line/mesh batches, extents, and drawing units (no editable DXF/DWG payload)
• Self-contained HTML — gzip/base64 snapshot + inline viewer runtime; opens offline in any modern browser
• Offline viewer — pan/zoom (OrbitControls), layer panel, layout switching, measurement, object snap (OSNAP)
• i18n — embedded English / Chinese / Czech / Turkish UI; initial language follows the browser (zh* → Chinese, cs* → Czech, tr* → Turkish, otherwise English); the toolbar language button cycles through the supported locales, and the choice persists in localStorage
• Plugin API — implements AcApPlugin; register once with registerLazyHtmlPlugin
• Composable API — build snapshots from your own pipeline or call packHtml with a pre-built snapshot

Installation

pnpm add @mlightcad/cad-html-plugin

Peer dependencies:

• @mlightcad/cad-simple-viewer (for -chtml / scene snapshot builder)
• @mlightcad/data-model
• @mlightcad/three-renderer
• three

Runtime dependency (bundled with this package):

• fflate

Build

The package produces two artifacts:

| Output | Description | |--------|-------------| | dist/index.js | Library entry (snapshot types, codec, packHtml, createHtmlPlugin, …) | | dist/register.js | Lightweight lazy-registration entry (safe for static import in app bundles) | | dist/viewer-runtime.iife.js | Offline viewer bootstrap (loaded/inlined into exported HTML) |

pnpm --filter @mlightcad/cad-html-plugin build

Copy or serve viewer-runtime.iife.js from your app assets when using the browser export path (see Integration below).

Usage

Lazy registration (recommended)

Register the plugin with the document manager's plugin manager. Import from the /register subpath so only the registration stub enters your initial bundle; the main plugin chunk loads on first use of -chtml or chtml (see command table above):

import { AcApDocManager } from '@mlightcad/cad-simple-viewer'
import { registerLazyHtmlPlugin } from '@mlightcad/cad-html-plugin/register'

AcApDocManager.createInstance({
  container: document.getElementById('cad-container')!,
  htmlViewerRuntimeUrl: './viewer-runtime.iife.js'
})

registerLazyHtmlPlugin(AcApDocManager.instance.pluginManager)

Do not import registerLazyHtmlPlugin from the package root (@mlightcad/cad-html-plugin) in application code — that resolves to the full library build and defeats lazy loading.

After registration (command-line export):

await AcApDocManager.instance.editor.executeCommand('-chtml')
// or
AcApDocManager.instance.sendStringToExecute('-chtml')

In cad-viewer, use chtml to open the export options dialog; -chtml remains available on the command line for prompt-based export.

cad-viewer registers this plugin automatically via registerLazyPlugins() in its app bootstrap and registers the chtml dialog command separately.

End-to-end export (command or convertor)

import { AcApHtmlConvertor } from '@mlightcad/cad-html-plugin'

await new AcApHtmlConvertor().convert('my-drawing.dwg')

Low-level snapshot assembly

import {
  ACEX_SNAPSHOT_VERSION,
  type AcExSnapshotV1,
  buildViewerMetadata,
  collectBatchesFromObject3D,
  buildOsnapCatalog,
  packHtml,
  HTML_VIEWER_RUNTIME_FILE
} from '@mlightcad/cad-html-plugin'

const snapshot: AcExSnapshotV1 = /* built via AcApHtmlSnapshotBuilder or manually */

const runtime = await fetch(`./${HTML_VIEWER_RUNTIME_FILE}`).then(r => r.text())
const html = packHtml(snapshot, {
  title: 'My Drawing',
  viewerRuntime: runtime
})

Scene → snapshot (viewer integration)

import { AcApHtmlSnapshotBuilder } from '@mlightcad/cad-html-plugin'

const snapshot = await new AcApHtmlSnapshotBuilder().buildAsync(
  view.cadScene,
  document.database,
  { title: 'Drawing', background: view.backgroundColor }
)

Headless / CLI

For DXF/DWG → HTML without a browser UI, use @mlightcad/cad-html-exporter-cli. It runs the same snapshot + packHtml pipeline inside Playwright.

Integration checklist

When embedding HTML export in a web app:

1. Build @mlightcad/cad-html-plugin and expose viewer-runtime.iife.js at a URL your app can fetch (e.g. Vite public/ copy — see cad-viewer-example / cad-simple-viewer-example vite configs).
2. Register via @mlightcad/cad-html-plugin/register (or load the plugin eagerly).
3. Optionally set htmlViewerRuntimeUrl on AcApDocManager.createInstance() to override the default ./viewer-runtime.iife.js path.
4. Ensure fonts used by the drawing are reachable during export if you rely on web-font substitution.

The generated HTML itself needs no backend; only the export step may fetch the runtime bundle and fonts.

Subpath exports:

import { registerLazyHtmlPlugin } from '@mlightcad/cad-html-plugin/register'
import '@mlightcad/cad-html-plugin/viewer-runtime' // dist/viewer-runtime.iife.js

Main exports

| Export | Role | |--------|------| | createHtmlPlugin | Async factory used by the lazy loader | | HTML_PLUGIN_NAME, HTML_PLUGIN_TRIGGERS | Plugin id and command triggers | | @mlightcad/cad-html-plugin/register | registerLazyHtmlPlugin and registration constants | | AcApExportHtmlCmd, AcApHtmlConvertor | -chtml command and full export workflow | | AcApHtmlSnapshotBuilder | Live Three.js scene → AcExSnapshotV1 | | packHtml, AcExPackHtmlOptions | Assemble HTML from snapshot + runtime source | | HTML_VIEWER_RUNTIME_FILE | Default runtime filename (viewer-runtime.iife.js) | | AcExSnapshotV1, ACEX_SNAPSHOT_VERSION, batch/layer types | Snapshot schema | | encodeSnapshot, decodeSnapshot | Gzip/base64 codec for embedded payloads | | collectBatchesFromObject3D | THREE.js scene → line/mesh batches | | buildViewerMetadata | Database → viewer meta (units, extents, background, …) | | buildOsnapCatalog, OSNAP primitive helpers | Analytic snap geometry for the offline viewer | | AcExHtmlI18n, detectAcExHtmlLocale, detectBrowserAcExHtmlLocale, resolveAcExHtmlLocale | Viewer UI strings and locale detection |

Project layout

| Path | Role | |------|------| | src/register.ts | Lazy plugin registration (/register entry) and createHtmlPlugin | | src/AcApHtmlPlugin.ts | Plugin lifecycle (onLoad / onUnload) | | src/AcApExportHtmlCmd.ts | -chtml command (command-line prompts) | | src/AcApHtmlConvertor.ts | Export orchestration (snapshot, runtime fetch, download) | | src/AcApHtmlSnapshotBuilder.ts | Three.js scene → snapshot builder | | src/AcExSnapshotTypes.ts | Snapshot schema (v1) | | src/AcExSnapshotCodec.ts | Encode/decode embedded snapshot script tag | | src/AcExSceneBatchCollector.ts | THREE.js traversal → export batches | | src/AcExHtmlPackager.ts | packHtml — shell + snapshot + runtime | | src/AcExHtmlViewerRuntime.ts | Offline viewer (built as IIFE) | | src/AcExHtmlShell.ts | Static HTML/CSS shell markup | | src/AcExOsnap*.ts | Object snap index and primitives | | src/AcExMeasurement.ts | Distance/area measurement in the offline viewer | | src/AcExHtmlI18n.ts | English / Chinese / Czech / Turkish UI messages |

Role in MLightCAD

This package combines the export format / offline viewer runtime with viewer integration (plugin, snapshot builder, -chtml command). @mlightcad/cad-simple-viewer stays free of HTML export code; heavy export logic can be lazy-loaded. cad-viewer adds a chtml dialog command on top. @mlightcad/cad-html-exporter-cli provides a Node/Playwright entry point for batch conversion.

License

MIT