@nebula-spatial/cad-loader 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this package are documented in this file.
+
+## 0.2.0
+
+- Added document-level CAD sessions with progressive content loading and viewport demand control.
+- Added read-only CAD render resources, INSERT and text selection helpers, and CAD session metadata.
+- Added public APIs for font resolution, document rendering, and scene annotations.
+- Retained the existing `loadGeo()`, load session, and `core` APIs.
+
+## 0.1.0
+
+- Initial public release of the browser-side DXB3/DXBS CAD pack loader.

package/README.md

@@ -1,46 +1,75 @@
 # @nebula-spatial/cad-loader
 
-浏览器侧 DXB3/DXBS CAD pack Loader。它接收 URL、File、ArrayBuffer 或兼容的
-结构化 source，保留 Worker、主线程 fallback、增量构建、flow control、abort
-和 dispose 生命周期，并直接返回可挂载到 Three.js 场景的 `GeoNode`。
+浏览器侧 DXB3/DXBS CAD pack 加载运行时。负责解析文档、构建 Three.js 渲染资源，并
+提供图层、INSERT、文本和外部资源的文档级访问能力。
 
-```ts
-import { loadGeo } from '@nebula-spatial/cad-loader';
+有完整视图需求的应用通常通过 `@nebula-spatial/viewer` 的 `viewer.cad.open()` 接入。
+本包适用于需要自行管理 Three.js 场景或 CAD 文档生命周期的集成。
 
-const node = loadGeo('/api/files/demo/result');
-scene.add(node);
-await node.ready;
-```
+## 文档会话
 
-CAD 产品可以在 Viewer 提供世界坐标后，通过 Loader 的只读语义查询解析
-Block/INSERT。该能力不包含选择状态或属性面板 UI：
+`createCadDocumentSession()` 是推荐的文档级入口。会话提供 header、基础内容就绪状态、
+视口需求和只读渲染资源；调用方负责场景挂载和相机/视口同步。
 
 ```ts
 import {
-  pickCadInsertAtPoint,
-  resolveCadInsertDetails,
+  createCadDocumentSession,
+  getCadDocumentRenderResource,
 } from '@nebula-spatial/cad-loader';
 
-const selection = pickCadInsertAtPoint(node, worldPoint);
-const details = selection ? resolveCadInsertDetails(node, selection) : null;
+const session = createCadDocumentSession('/api/files/demo/result', {
+  filename: 'demo.dxf',
+});
+const renderNode = getCadDocumentRenderResource(session);
+
+scene.add(renderNode.object);
+const stopChanges = renderNode.onChange(() => requestRender());
+
+const header = await session.headerReady;
+fitCamera(header.bounds);
+
+session.setDisplayContext(displayContext);
+session.setViewportDemand(viewportDemand);
+await session.initialContentReady;
+
+stopChanges();
+scene.remove(renderNode.object);
+session.dispose();
 ```
 
-对于 URL source，V3.3 pack 的 external geometry 与 scene/block annotation 默认会在
-`node.ready` 前完成请求、校验、解码和挂接；不需要标注时可传入
-`{ loadAnnotations: false }`。Product App 若要按视口渐进加载，应先使用
-`ArrayBuffer` 和显式 sidecar 计划，再自行编排 annotation 的加载时机。
+`headerReady` 提供文档边界和图层元数据，`initialContentReady` 表示基础内容已可用。
+通过 `content-appended`、`demand-progress`、`phase-change` 和错误事件可监听后续变化。
 
-上传、任务轮询、文件目录和原始 DXF/DWG 解析不属于此包。
+`CadRenderNode` 是只读渲染资源。选择状态、属性面板、编辑命令和历史记录由产品层维护。
 
-DXB3/DXBS 协议解析和纯数据契约通过稳定的 `/core` 子路径提供。该入口不依赖
-Three.js、DOM、Canvas 或 WebGL，可以在 Worker、Node.js 和 CLI 中独立使用：
+## 其他入口
+
+- `loadGeo()`：简单的 `GeoNode` 增量加载。适合不需要文档会话的 Three.js 集成。
+- `createLoadSession()`：以异步事件流消费 CAD pack，适合自定义渲染器或流量控制。
+- `@nebula-spatial/cad-loader/core`：不依赖 Three.js、DOM 或 WebGL 的协议解析 API，可用于
+  Worker、Node.js 和 CLI。
 
 ```ts
-import { parseBinBounds } from '@nebula-spatial/cad-loader/core';
+import { loadGeo } from '@nebula-spatial/cad-loader';
 
-const bounds = parseBinBounds(buffer);
+const node = loadGeo('/api/files/demo/result');
+scene.add(node);
+node.setViewportSize(canvas.clientWidth, canvas.clientHeight);
+await node.ready;
 ```
 
-默认 Worker 使用包内的 ESM 资源路径。使用非 Vite bundler 或自行托管 Worker
-资源时，可以通过 `LoadGeoOptions.workerUrl` 指定 URL，或通过 `workerFactory`
-接管 Worker 创建。
+默认 Worker 使用包内 ESM 资源路径。使用非 Vite bundler 或自行托管 Worker 资源时，可通过
+`LoadGeoOptions.workerUrl` 或 `workerFactory` 配置 Worker 创建方式。
+
+## 边界
+
+本包不处理上传、任务轮询、文件目录或原始 DXF/DWG 解析。运行时依赖为 `three` peer
+dependency，要求 Node.js 18 或更高版本。
+
+## 开发
+
+```bash
+npm run typecheck --workspace @nebula-spatial/cad-loader
+npm test --workspace @nebula-spatial/cad-loader
+npm run build --workspace @nebula-spatial/cad-loader
+```

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export type { CadExternalVariantFetchSource, CadLoadErrorEvent, CadLoadEvent, Ca
 export { appendExternalVariantDeltaToGeoNode, assertValidSourceOrThrow, loadExternalVariantDeltaFromBuffer, loadGeo, normalizeGeoError, parseBuffer, parseBufferBounds, parseBufferHeader, readBufferExternalAnnotationManifest, readBufferExternalBlockAnnotations, readBufferExternalVariantDependencyPlan, readBufferExternalVariantManifest, } from './loader/geo-loader';
 export type { ExternalVariantDependencyOptions, ExternalVariantDependencyPlan, ExternalVariantFetchSource, LoadExternalVariantDeltaFetchSourceOptions, LoadExternalVariantDeltaOptions, LoadGeoOptions, } from './loader/geo-loader';
 export { GEO_NODE_STRUCTURE_CHANGE, GEO_NODE_VISUAL_CHANGE, GeoNode, } from './loader/internal/geo-node';
-export type { ColorPipelineStatsSnapshot, GeoNodeInternalChange, GeoNodeInternalChangeKind, InsertInstanceMatrix2D, } from './loader/internal/geo-node';
+export type { ColorPipelineStatsSnapshot, GeoNodeChange, GeoNodeChangeKind, GeoNodeChangeListener, GeoNodeInternalChange, GeoNodeInternalChangeKind, InsertInstanceMatrix2D, } from './loader/internal/geo-node';
 export type { LineMemoryStatsSnapshot, LineCanonicalMemoryStats, } from './loader/internal/line-canonical';
 export { readBlockAnnotationSidecar, readSceneAnnotationSidecar, } from './core';
 export type { DecodedAnnotationSidecar, DxbsContainer, DxbsSectionEntry, ParsedHeader, } from './core';
@@ -24,3 +24,11 @@ export type { BlockGeometryKind, VariantGeometry, } from './scene/instancing/blo
 export type { InsertInstanceRecord } from './scene/instancing/insert-instance-table';
 export { cadInsertSelectionEquals, pickCadInsertAtPoint, resolveCadInsertDetails, } from './selection/cad-insert-selection';
 export type { CadInsertDetails, CadInsertPickOptions, CadInsertSelectionId, CadPoint2D, } from './selection/cad-insert-selection';
+export { cadTextSelectionEquals, pickCadTextAtPoint, resolveCadTextDetails, } from './selection/cad-text-selection';
+export type { CadTextDetails, CadTextPickOptions, CadTextSelection, CadTextSelectionId, } from './selection/cad-text-selection';
+export { CAD_SESSION_PHASES } from './session/cad-document-session';
+export { createCadDocumentSession, getCadDocumentRenderResource } from './session/create-cad-document-session';
+export { formatCadInsertId, parseCadInsertId } from './session/cad-insert-id';
+export type { CadDisplayContext, CadDocumentHeader, CadDocumentSession, CadDocumentSessionOptions, CadFontResolver, CadInsertUsageSummary, CadLayerMeta, CadSessionEventMap, CadSessionPhase, CadViewportDemand, CadViewportRect, CadVisibilityFilter, CadWorldBounds, CadWorldPoint, } from './session/cad-document-session';
+export { CAD_RENDER_NODE_EDIT_METHODS, isCadRenderNodeEditMethod } from './render-resource/cad-render-node';
+export type { CadInsertPreviewResource, CadRenderContentChunk, CadRenderNode, } from './render-resource/cad-render-node';