vim-web 1.0.0-beta.2 → 1.0.0-beta.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +106 -106
  2. package/dist/style.css +2107 -2107
  3. package/dist/vim-web.d.ts +6 -0
  4. package/dist/vim-web.iife.js +42 -7
  5. package/dist/vim-web.iife.js.map +1 -1
  6. package/dist/vim-web.js +42 -7
  7. package/dist/vim-web.js.map +1 -1
  8. package/package.json +1 -1
package/README.md CHANGED
@@ -1,106 +1,106 @@
1
- # VIM Web
2
-
3
- React-based 3D viewers for VIM files with BIM (Building Information Modeling) support. VIM files are optimized 3D building models that contain both geometry and rich BIM metadata (elements, properties, categories, etc.).
4
-
5
- ## Getting Started
6
-
7
- ```bash
8
- npm install
9
- npm run dev # Dev server at localhost:5173
10
- npm run build # Production build (vite + tsc declarations + rollup d.ts bundles)
11
- npm run eslint # Lint
12
- npm run documentation # TypeDoc generation
13
- ```
14
-
15
- ### Build Pipeline
16
-
17
- `npm run build` runs three steps in sequence:
18
-
19
- 1. **Vite build** — bundles `vim-web.js` (ESM) and `vim-web.iife.js` (IIFE) into `dist/`
20
- 2. **TypeScript declarations** (`tsc -p tsconfig.types.json`) — emits individual `.d.ts` files to `dist/types/`
21
- 3. **Rollup d.ts bundling** — produces two self-contained type bundles:
22
- - `dist/vim-web.d.ts` — full library API (3,300+ lines), referenced by `"types"` in package.json
23
- - `dist/vim-bim.d.ts` — standalone BIM data types from `vim-format` (1,900+ lines)
24
-
25
- ### Type Bundles & AI Tooling
26
-
27
- The bundled `.d.ts` files serve a dual purpose:
28
-
29
- **`vim-web.d.ts`** is the package's type entry point. It inlines types from `ste-signals`, `ste-events`, and `ste-core` so consumers get full type information without needing those packages. Types from `three`, `react`, `deepmerge`, and `vim-format` remain external imports.
30
-
31
- **`vim-bim.d.ts`** bundles all BIM data interfaces (`IElement`, `ICategory`, `IRoom`, `VimDocument`, etc.) from `vim-format` into a single self-contained file. This is designed as an **AI-readable reference** — an LLM can read this one file to understand the complete BIM data model without needing access to the `vim-format` package source. It is not imported by the library itself.
32
-
33
- Both files have semantic namespace names (e.g., `Core_Webgl`, `React_Ultra`) instead of the opaque `index_d$1` names that `rollup-plugin-dts` generates by default. This makes them readable by both humans and AI tools. The rollup configs (`rollup.dts.config.mjs`, `rollup.bim-dts.config.mjs`) handle the namespace renaming and various fixups.
34
-
35
- ## Architecture Overview
36
-
37
- ### Dual Viewer System
38
-
39
- | Viewer | Use Case | Rendering |
40
- |--------|----------|-----------|
41
- | **WebGL** | Small-medium models | Local Three.js rendering |
42
- | **Ultra** | Large models | Server-side streaming via WebSocket RPC |
43
-
44
- ### Layer Separation
45
-
46
- ```
47
- src/vim-web/
48
- ├── core-viewers/ # Framework-agnostic (no React)
49
- │ ├── webgl/ # Local Three.js rendering
50
- │ │ ├── loader/ # VIM parsing, mesh building, scene, data model
51
- │ │ │ ├── progressive/ # Geometry loading & mesh construction
52
- │ │ │ └── materials/ # Shader materials
53
- │ │ └── viewer/ # Camera, raycaster, rendering, gizmos
54
- │ ├── ultra/ # RPC client for streaming server
55
- │ └── shared/ # Common interfaces (IVim, Selection, Input)
56
- └── react-viewers/ # React UI layer
57
- ├── webgl/ # Full UI (BIM tree, context menu, gizmos)
58
- ├── ultra/ # Minimal UI
59
- └── helpers/ # StateRef, hooks, utilities
60
- ```
61
-
62
- ### Import Discipline
63
-
64
- - **Core files** (`core-viewers/`): Import directly from source files, never through barrel files
65
- - **React layer** (`react-viewers/`): Import through barrel files (`import * as Core from '../../core-viewers'`)
66
-
67
- ## Key Concepts
68
-
69
- - **Element3D**: Primary object representing a BIM element. Controls visibility, color, outline, and provides access to BIM metadata.
70
- - **Selection**: Observable selection state with multi-select, events, and bounding box queries.
71
- - **Camera**: Fluent API with `snap()` (instant) and `lerp(duration)` (animated) for framing, orbiting, and zooming.
72
- - **Gizmos**: Section box, measurement tool, and markers.
73
- - **StateRef/FuncRef**: Observable state and callable function references used in the React layer for customization.
74
- - **ViewerApi**: The root API handle returned by `createViewer()`. Provides `load()`, `open()`, `unload()`, and access to all subsystems (isolation, sectionBox, controlBar, etc.).
75
-
76
- ## Customization
77
-
78
- The React viewer exposes customization points for:
79
- - **Control bar**: Add/replace toolbar buttons via `viewer.controlBar.customize()`
80
- - **Context menu**: Add custom menu items via `viewer.contextMenu.customize()`
81
- - **BIM info panel**: Modify displayed data or override rendering at any level
82
- - **Settings panel**: Add/remove settings items via `viewer.settings.customize()`
83
- - **Floating panels**: Modify section box offset and isolation render settings fields
84
-
85
- ## Documentation
86
-
87
- - **[CLAUDE.md](./CLAUDE.md)** — Detailed API reference, code examples, architecture details, and patterns. This is the primary reference for both developers and AI tools.
88
- - **[.claude/docs/INPUT.md](./.claude/docs/INPUT.md)** — Input system architecture, coordinate systems, override patterns
89
- - **[.claude/docs/optimization.md](./.claude/docs/optimization.md)** — Loading pipeline performance and profiling
90
- - **[.claude/docs/RENDERING_OPTIMIZATIONS.md](./.claude/docs/RENDERING_OPTIMIZATIONS.md)** — Shader material architecture and rendering patterns
91
-
92
- ## Tech Stack
93
-
94
- - **TypeScript 6**, **React 18.3/19**, **Vite 8**
95
- - **Three.js 0.183**, semantic CSS with design tokens (`--c-` prefix)
96
- - **@headless-tree/react** + **@tanstack/react-virtual** for the BIM tree
97
- - **ste-signals/ste-simple-events** for typed events, **vim-format** for BIM data
98
- - **Rollup** + **rollup-plugin-dts** for type bundle generation
99
-
100
- ## Code Style
101
-
102
- - No semicolons, trailing commas, single quotes
103
- - Index files control module exports
104
- - No test framework — build pass is the verification
105
- - No linter or formatter — TypeScript compiler is the only gate
106
- - No deprecated code or backwards-compatibility shims
1
+ # VIM Web
2
+
3
+ React-based 3D viewers for VIM files with BIM (Building Information Modeling) support. VIM files are optimized 3D building models that contain both geometry and rich BIM metadata (elements, properties, categories, etc.).
4
+
5
+ ## Getting Started
6
+
7
+ ```bash
8
+ npm install
9
+ npm run dev # Dev server at localhost:5173
10
+ npm run build # Production build (vite + tsc declarations + rollup d.ts bundles)
11
+ npm run eslint # Lint
12
+ npm run documentation # TypeDoc generation
13
+ ```
14
+
15
+ ### Build Pipeline
16
+
17
+ `npm run build` runs three steps in sequence:
18
+
19
+ 1. **Vite build** — bundles `vim-web.js` (ESM) and `vim-web.iife.js` (IIFE) into `dist/`
20
+ 2. **TypeScript declarations** (`tsc -p tsconfig.types.json`) — emits individual `.d.ts` files to `dist/types/`
21
+ 3. **Rollup d.ts bundling** — produces two self-contained type bundles:
22
+ - `dist/vim-web.d.ts` — full library API (3,300+ lines), referenced by `"types"` in package.json
23
+ - `dist/vim-bim.d.ts` — standalone BIM data types from `vim-format` (1,900+ lines)
24
+
25
+ ### Type Bundles & AI Tooling
26
+
27
+ The bundled `.d.ts` files serve a dual purpose:
28
+
29
+ **`vim-web.d.ts`** is the package's type entry point. It inlines types from `ste-signals`, `ste-events`, and `ste-core` so consumers get full type information without needing those packages. Types from `three`, `react`, `deepmerge`, and `vim-format` remain external imports.
30
+
31
+ **`vim-bim.d.ts`** bundles all BIM data interfaces (`IElement`, `ICategory`, `IRoom`, `VimDocument`, etc.) from `vim-format` into a single self-contained file. This is designed as an **AI-readable reference** — an LLM can read this one file to understand the complete BIM data model without needing access to the `vim-format` package source. It is not imported by the library itself.
32
+
33
+ Both files have semantic namespace names (e.g., `Core_Webgl`, `React_Ultra`) instead of the opaque `index_d$1` names that `rollup-plugin-dts` generates by default. This makes them readable by both humans and AI tools. The rollup configs (`rollup.dts.config.mjs`, `rollup.bim-dts.config.mjs`) handle the namespace renaming and various fixups.
34
+
35
+ ## Architecture Overview
36
+
37
+ ### Dual Viewer System
38
+
39
+ | Viewer | Use Case | Rendering |
40
+ |--------|----------|-----------|
41
+ | **WebGL** | Small-medium models | Local Three.js rendering |
42
+ | **Ultra** | Large models | Server-side streaming via WebSocket RPC |
43
+
44
+ ### Layer Separation
45
+
46
+ ```
47
+ src/vim-web/
48
+ ├── core-viewers/ # Framework-agnostic (no React)
49
+ │ ├── webgl/ # Local Three.js rendering
50
+ │ │ ├── loader/ # VIM parsing, mesh building, scene, data model
51
+ │ │ │ ├── progressive/ # Geometry loading & mesh construction
52
+ │ │ │ └── materials/ # Shader materials
53
+ │ │ └── viewer/ # Camera, raycaster, rendering, gizmos
54
+ │ ├── ultra/ # RPC client for streaming server
55
+ │ └── shared/ # Common interfaces (IVim, Selection, Input)
56
+ └── react-viewers/ # React UI layer
57
+ ├── webgl/ # Full UI (BIM tree, context menu, gizmos)
58
+ ├── ultra/ # Minimal UI
59
+ └── helpers/ # StateRef, hooks, utilities
60
+ ```
61
+
62
+ ### Import Discipline
63
+
64
+ - **Core files** (`core-viewers/`): Import directly from source files, never through barrel files
65
+ - **React layer** (`react-viewers/`): Import through barrel files (`import * as Core from '../../core-viewers'`)
66
+
67
+ ## Key Concepts
68
+
69
+ - **Element3D**: Primary object representing a BIM element. Controls visibility, color, outline, and provides access to BIM metadata.
70
+ - **Selection**: Observable selection state with multi-select, events, and bounding box queries.
71
+ - **Camera**: Fluent API with `snap()` (instant) and `lerp(duration)` (animated) for framing, orbiting, and zooming.
72
+ - **Gizmos**: Section box, measurement tool, and markers.
73
+ - **StateRef/FuncRef**: Observable state and callable function references used in the React layer for customization.
74
+ - **ViewerApi**: The root API handle returned by `createViewer()`. Provides `load()`, `open()`, `unload()`, and access to all subsystems (isolation, sectionBox, controlBar, etc.).
75
+
76
+ ## Customization
77
+
78
+ The React viewer exposes customization points for:
79
+ - **Control bar**: Add/replace toolbar buttons via `viewer.controlBar.customize()`
80
+ - **Context menu**: Add custom menu items via `viewer.contextMenu.customize()`
81
+ - **BIM info panel**: Modify displayed data or override rendering at any level
82
+ - **Settings panel**: Add/remove settings items via `viewer.settings.customize()`
83
+ - **Floating panels**: Modify section box offset and isolation render settings fields
84
+
85
+ ## Documentation
86
+
87
+ - **[CLAUDE.md](./CLAUDE.md)** — Detailed API reference, code examples, architecture details, and patterns. This is the primary reference for both developers and AI tools.
88
+ - **[.claude/docs/INPUT.md](./.claude/docs/INPUT.md)** — Input system architecture, coordinate systems, override patterns
89
+ - **[.claude/docs/optimization.md](./.claude/docs/optimization.md)** — Loading pipeline performance and profiling
90
+ - **[.claude/docs/RENDERING_OPTIMIZATIONS.md](./.claude/docs/RENDERING_OPTIMIZATIONS.md)** — Shader material architecture and rendering patterns
91
+
92
+ ## Tech Stack
93
+
94
+ - **TypeScript 6**, **React 18.3/19**, **Vite 8**
95
+ - **Three.js 0.183**, semantic CSS with design tokens (`--c-` prefix)
96
+ - **@headless-tree/react** + **@tanstack/react-virtual** for the BIM tree
97
+ - **ste-signals/ste-simple-events** for typed events, **vim-format** for BIM data
98
+ - **Rollup** + **rollup-plugin-dts** for type bundle generation
99
+
100
+ ## Code Style
101
+
102
+ - No semicolons, trailing commas, single quotes
103
+ - Index files control module exports
104
+ - No test framework — build pass is the verification
105
+ - No linter or formatter — TypeScript compiler is the only gate
106
+ - No deprecated code or backwards-compatibility shims