@ifc-lite/wasm 1.1.6 → 1.2.0

package/README.md

@@ -1,26 +1,33 @@
-<p align="center">
-  <img src="docs/assets/logo.svg" alt="IFC-Lite Logo" width="120" height="120">
-</p>
-
-<h1 align="center">IFC-Lite</h1>
+<table align="center">
+<tr>
+<td valign="top">
+<img src="https://readme-typing-svg.herokuapp.com?font=JetBrains+Mono&weight=700&size=48&duration=2000&pause=5000&color=FFFFFF&vCenter=true&width=300&height=55&lines=IFClite" alt="IFClite">
+<br>
+<code>Fast</code> · <code>Lightweight</code> · <code>Columnar</code> · <code>Browser-native</code>
+</td>
+<td width="120" align="center" valign="middle">
+<img src="docs/assets/logo.png" alt="" width="100">
+</td>
+</tr>
+</table>
 
 <p align="center">
-  <strong>High-performance browser-native IFC platform</strong>
+  <a href="https://www.ifclite.com/"><img src="https://img.shields.io/badge/🚀_Try_it_Live-ifclite.com-ff6b6b?style=for-the-badge&labelColor=1a1a2e" alt="Try it Live"></a>
 </p>
 
 <p align="center">
-  <a href="https://github.com/louistrue/ifc-lite/actions"><img src="https://img.shields.io/github/actions/workflow/status/louistrue/ifc-lite/ci.yml?branch=main&style=flat-square&logo=github" alt="Build Status"></a>
+  <a href="https://github.com/louistrue/ifc-lite/actions"><img src="https://img.shields.io/github/actions/workflow/status/louistrue/ifc-lite/release.yml?branch=main&style=flat-square&logo=github" alt="Build Status"></a>
   <a href="https://github.com/louistrue/ifc-lite/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MPL--2.0-blue?style=flat-square" alt="License"></a>
   <a href="https://www.npmjs.com/package/@ifc-lite/parser"><img src="https://img.shields.io/npm/v/@ifc-lite/parser?style=flat-square&logo=npm&label=parser" alt="npm parser"></a>
   <a href="https://crates.io/crates/ifc-lite-core"><img src="https://img.shields.io/crates/v/ifc-lite-core?style=flat-square&logo=rust&label=core" alt="crates.io"></a>
 </p>
 
 <p align="center">
-  <a href="#features">Features</a> &bull;
-  <a href="#quick-start">Quick Start</a> &bull;
-  <a href="#documentation">Documentation</a> &bull;
-  <a href="#architecture">Architecture</a> &bull;
-  <a href="#performance">Performance</a> &bull;
+  <a href="#features">Features</a> · 
+  <a href="#quick-start">Quick Start</a> · 
+  <a href="#documentation">Documentation</a> · 
+  <a href="#architecture">Architecture</a> · 
+  <a href="#performance">Performance</a> · 
   <a href="#contributing">Contributing</a>
 </p>
 
@@ -28,48 +35,96 @@
 
 ## Overview
 
-**IFC-Lite** is a next-generation IFC (Industry Foundation Classes) platform built with **Rust + WebAssembly** for parsing, geometry processing, and **WebGPU** for 3D visualization. It's designed to be a **95x smaller** and significantly faster alternative to existing web-based IFC solutions.
+**IFClite** parses, processes, and renders IFC files in the browser using **Rust + WebAssembly** and **WebGPU**. Smaller and faster than the alternatives.
 
 <p align="center">
-  <strong>~86 KB total</strong> &nbsp;•&nbsp; <strong>1.9x faster</strong> &nbsp;•&nbsp; <strong>100% IFC4 schema</strong>
+  <strong>~650 KB WASM (~260 KB gzipped)</strong> &nbsp;•&nbsp; <strong>2.6x faster</strong> &nbsp;•&nbsp; <strong>100% IFC4X3 schema (876 entities)</strong>
 </p>
 
 ## Features
 
 | Feature | Description |
 |---------|-------------|
-| **STEP/IFC Parsing** | Zero-copy tokenization at ~1,259 MB/s with full IFC4 schema support (776 entities) |
-| **Streaming Pipeline** | Progressive geometry processing - first triangles render in 300-500ms |
-| **WebGPU Rendering** | Modern GPU-accelerated 3D visualization with depth testing and frustum culling |
-| **Columnar Storage** | Memory-efficient TypedArray storage with 30% string deduplication |
-| **Zero-Copy GPU** | Direct WASM memory binding to GPU buffers |
+| **Clean DX** | Columnar data structures, TypedArrays, consistent API. Built from scratch for clarity |
+| **STEP/IFC Parsing** | Zero-copy tokenization with full IFC4X3 schema support (876 entities) |
+| **Streaming Pipeline** | Progressive geometry processing. First triangles in 300-500ms |
+| **WebGPU Rendering** | Modern GPU-accelerated 3D with depth testing and frustum culling |
+| **Zero-Copy GPU** | Direct WASM memory to GPU buffers, 60-70% less RAM |
 
 ## Quick Start
 
-### Prerequisites
+### Option 1: Create a New Project (Recommended)
+
+Get started instantly without cloning the repo:
 
-- **Node.js** 18.0+ with **pnpm** 8.0+
-- **Rust** toolchain with wasm32-unknown-unknown target
-- Modern browser with **WebGPU** support (Chrome 113+, Edge 113+, Firefox 127+, Safari 18+)
+```bash
+npx create-ifc-lite my-ifc-app
+cd my-ifc-app
+npm install && npm run parse
+```
 
-### Installation
+Or create a React viewer:
 
 ```bash
-# Clone the repository
-git clone https://github.com/louistrue/ifc-lite.git
-cd ifc-lite
+npx create-ifc-lite my-viewer --template react
+cd my-viewer
+npm install && npm run dev
+```
 
-# Install dependencies
-pnpm install
+### Option 2: Install Packages Directly
 
-# Build all packages
-pnpm build
+Add IFClite to your existing project:
 
-# Run the viewer
-cd apps/viewer
-pnpm dev
+```bash
+npm install @ifc-lite/parser
 ```
 
+```typescript
+import { IfcParser } from '@ifc-lite/parser';
+
+const parser = new IfcParser();
+const result = parser.parse(ifcBuffer);
+
+console.log(`Found ${result.entities.length} entities`);
+```
+
+For full 3D rendering, add geometry and renderer packages:
+
+```bash
+npm install @ifc-lite/parser @ifc-lite/geometry @ifc-lite/renderer
+```
+
+### Option 3: Rust/Cargo
+
+For Rust projects:
+
+```bash
+cargo add ifc-lite-core
+```
+
+```rust
+use ifc_lite_core::parse_ifc;
+
+let result = parse_ifc(&ifc_bytes)?;
+println!("Parsed {} entities", result.entities.len());
+```
+
+### Option 4: Clone the Repo (Contributors)
+
+For contributing or running the full demo app:
+
+```bash
+git clone https://github.com/louistrue/ifc-lite.git
+cd ifc-lite
+pnpm install && pnpm dev
+```
+
+Open http://localhost:5173 and load an IFC file.
+
+> **Note:** Requires Node.js 18+ and pnpm 8+. No Rust toolchain needed - WASM is pre-built.
+> 
+> **📖 Full Guide**: See [Installation](docs/guide/installation.md) for detailed setup options including troubleshooting.
+
 ### Basic Usage
 
 ```typescript
@@ -78,13 +133,13 @@ import { Renderer } from '@ifc-lite/renderer';
 
 // Parse IFC file
 const parser = new IfcParser();
-const result = await parser.parse(ifcArrayBuffer);
+const result = parser.parse(ifcArrayBuffer);
 
 // Access entities
 const walls = result.entities.filter(e => e.type === 'IFCWALL');
 console.log(`Found ${walls.length} walls`);
 
-// Render geometry
+// Render geometry (requires @ifc-lite/renderer)
 const renderer = new Renderer(canvas);
 await renderer.loadGeometry(result.geometry);
 renderer.render();
@@ -94,20 +149,41 @@ renderer.render();
 
 | Resource | Description |
 |----------|-------------|
-| [**User Guide**](https://louistrue.github.io/ifc-lite/) | Complete guide with tutorials and examples |
-| [**API Reference**](https://louistrue.github.io/ifc-lite/api/) | Rustdoc API documentation |
-| [**Architecture**](docs/architecture.md) | System design and data flow |
-| [**Contributing**](CONTRIBUTING.md) | How to contribute to the project |
+| [**Quick Start**](docs/guide/quickstart.md) | Parse your first IFC file in 5 minutes |
+| [**Installation**](docs/guide/installation.md) | Detailed setup for npm, Cargo, and from source |
+| [**User Guide**](https://louistrue.github.io/ifc-lite/) | Complete guides: parsing, geometry, rendering, querying |
+| [**Tutorials**](docs/tutorials/building-viewer.md) | Build a viewer, custom queries, extend the parser |
+| [**Architecture**](docs/architecture/overview.md) | System design with detailed diagrams |
+| [**API Reference**](docs/api/typescript.md) | TypeScript, Rust, and WASM API docs |
+| [**Contributing**](docs/contributing/setup.md) | Development setup and testing guide |
 
 ## Architecture
 
-IFC files flow through three layers:
-
-**Parser** (Rust/WASM) — Zero-copy STEP tokenizer, entity scanner, and geometry processor using nom, earcutr, and nalgebra.
+```mermaid
+flowchart LR
+    IFC[IFC File] --> Tokenize
+    Tokenize --> Scan --> Decode
+    Decode --> Tables[Columnar Tables]
+    Decode --> Graph[Relationship Graph]
+    Tables --> Renderer[WebGPU Renderer]
+    Graph --> Export[glTF / Parquet]
+    
+    style IFC fill:#6366f1,stroke:#312e81,color:#fff
+    style Tokenize fill:#2563eb,stroke:#1e3a8a,color:#fff
+    style Scan fill:#2563eb,stroke:#1e3a8a,color:#fff
+    style Decode fill:#10b981,stroke:#064e3b,color:#fff
+    style Tables fill:#f59e0b,stroke:#7c2d12,color:#fff
+    style Graph fill:#f59e0b,stroke:#7c2d12,color:#fff
+    style Renderer fill:#a855f7,stroke:#581c87,color:#fff
+    style Export fill:#a855f7,stroke:#581c87,color:#fff
+```
 
-**Data** (TypeScript) — Columnar TypedArrays for properties, CSR graph for relationships, GPU-ready geometry buffers.
+IFC files flow through three processing layers. See the [Architecture Documentation](docs/architecture/overview.md) for detailed diagrams including data flow, memory model, and threading.
 
-**Output** — WebGPU renderer, Parquet analytics, glTF/JSON-LD/CSV export.
+> **Deep Dive**: [Data Flow](docs/architecture/data-flow.md) ·
+> [Parsing Pipeline](docs/architecture/parsing-pipeline.md) ·
+> [Geometry Pipeline](docs/architecture/geometry-pipeline.md) ·
+> [Rendering Pipeline](docs/architecture/rendering-pipeline.md)
 
 ## Project Structure
 
@@ -122,6 +198,7 @@ ifc-lite/
 │   ├── parser/                # High-level IFC parser
 │   ├── geometry/              # Geometry bridge (WASM)
 │   ├── renderer/              # WebGPU rendering
+│   ├── cache/                 # Binary cache format
 │   ├── query/                 # Query system
 │   ├── data/                  # Columnar data structures
 │   ├── spatial/               # Spatial indexing
@@ -131,34 +208,44 @@ ifc-lite/
 ├── apps/
 │   └── viewer/                # React web application
 │
-├── docs/                      # Documentation (MkDocs)
-└── plan/                      # Technical specifications
+└── docs/                      # Documentation (MkDocs)
 ```
 
 ## Performance
 
 ### Bundle Size Comparison
 
-| Library | Size | Gzipped |
-|---------|------|---------|
-| **IFC-Lite** | **~86 KB** | **~28 KB** |
-| Traditional WASM | 8+ MB | N/A |
-| **Reduction** | **93%** | - |
+| Library | WASM Size | Gzipped |
+|---------|-----------|---------|
+| **IFClite** | **0.65 MB** | **0.26 MB** |
+| web-ifc | 1.1 MB | 0.4 MB |
+| IfcOpenShell | 15 MB | - |
 
 ### Parse Performance
 
-| Model Size | IFC-Lite | Notes |
+| Model Size | IFClite | Notes |
 |------------|----------|-------|
-| 10 MB | ~800ms | Small models |
-| 50 MB | ~2.7s | Typical models |
-| 100+ MB | ~5s+ | Complex geometry |
+| 10 MB | ~100-200ms | Small models |
+| 50 MB | ~600-700ms | Typical models |
+| 100+ MB | ~1.5-2s | Complex geometry |
+
+*Based on [benchmark results](tests/benchmark/benchmark-results.json) across 67 IFC files.*
+
+### Zero-Copy GPU Pipeline
+
+- **Zero-copy WASM to WebGPU**: Direct memory access from WASM linear memory to GPU buffers
+- **60-70% reduction** in peak RAM usage
+- **74% faster** parse time with optimized data flow
+- **40-50% faster** geometry-to-GPU pipeline
 
 ### Geometry Processing
 
-- **1.9x faster** mesh extraction than traditional solutions
+- **5x faster** overall than web-ifc (median 2.18x, up to 104x on some files)
 - Streaming pipeline with batched processing (100 meshes/batch)
 - First triangles visible in **300-500ms**
 
+*See [full benchmark data](tests/benchmark/benchmark-results.json) for per-file comparisons.*
+
 ## Browser Requirements
 
 | Browser | Minimum Version | WebGPU |
@@ -168,51 +255,70 @@ ifc-lite/
 | Firefox | 127+ | ✅ |
 | Safari | 18+ | ✅ |
 
-## Development
+> **More Info**: See [Browser Requirements](docs/guide/browser-requirements.md) for WebGPU feature detection and fallbacks.
 
-```bash
-# Watch mode for all packages
-pnpm -r dev
+## Development (Contributors)
 
-# Build specific package
-cd packages/parser && pnpm build
+For contributing to IFClite itself:
 
-# Run tests
-pnpm test
+```bash
+git clone https://github.com/louistrue/ifc-lite.git
+cd ifc-lite
+pnpm install
 
-# Build Rust/WASM
-cd rust && cargo build --release --target wasm32-unknown-unknown
+pnpm dev          # Start viewer in dev mode
+pnpm build        # Build all packages
+pnpm test         # Run tests
 
-# Generate Rustdoc
-cd rust && cargo doc --no-deps --open
+# Add a changeset when making changes
+pnpm changeset    # Describe your changes (required for releases)
 
-# Build documentation site
-cd docs && mkdocs serve
+# Rust/WASM development (optional - WASM is pre-built)
+cd rust && cargo build --release --target wasm32-unknown-unknown
+bash scripts/build-wasm.sh  # Rebuild WASM after Rust changes
 ```
 
 ## Packages
 
-| Package | Description | Status |
-|---------|-------------|--------|
-| `@ifc-lite/parser` | STEP tokenizer & entity extraction | ✅ Stable |
-| `@ifc-lite/geometry` | Geometry processing bridge | ✅ Stable |
-| `@ifc-lite/renderer` | WebGPU rendering pipeline | ✅ Stable |
-| `@ifc-lite/query` | Fluent & SQL query system | 🚧 Beta |
-| `@ifc-lite/data` | Columnar data structures | ✅ Stable |
-| `@ifc-lite/spatial` | Spatial indexing & culling | 🚧 Beta |
-| `@ifc-lite/export` | Export (glTF, Parquet, etc.) | 🚧 Beta |
+| Package | Description | Status | Docs |
+|---------|-------------|--------|------|
+| `create-ifc-lite` | Project scaffolding CLI | ✅ Stable | [API](docs/api/typescript.md#create-ifc-lite) |
+| `@ifc-lite/parser` | STEP tokenizer & entity extraction | ✅ Stable | [API](docs/api/typescript.md#parser) |
+| `@ifc-lite/geometry` | Geometry processing bridge | ✅ Stable | [API](docs/api/typescript.md#geometry) |
+| `@ifc-lite/renderer` | WebGPU rendering pipeline | ✅ Stable | [API](docs/api/typescript.md#renderer) |
+| `@ifc-lite/cache` | Binary cache for instant loading | ✅ Stable | [API](docs/api/typescript.md#cache) |
+| `@ifc-lite/query` | Fluent & SQL query system | 🚧 Beta | [API](docs/api/typescript.md#query) |
+| `@ifc-lite/data` | Columnar data structures | ✅ Stable | [API](docs/api/typescript.md#data) |
+| `@ifc-lite/spatial` | Spatial indexing & culling | 🚧 Beta | [API](docs/api/typescript.md#spatial) |
+| `@ifc-lite/export` | Export (glTF, Parquet, etc.) | 🚧 Beta | [API](docs/api/typescript.md#export) |
 
 ## Rust Crates
 
-| Crate | Description | Status |
-|-------|-------------|--------|
-| `ifc-lite-core` | STEP/IFC parsing | ✅ Stable |
-| `ifc-lite-geometry` | Mesh triangulation | ✅ Stable |
-| `ifc-lite-wasm` | WASM bindings | ✅ Stable |
+| Crate | Description | Status | Docs |
+|-------|-------------|--------|------|
+| `ifc-lite-core` | STEP/IFC parsing | ✅ Stable | [docs.rs](https://docs.rs/ifc-lite-core) |
+| `ifc-lite-geometry` | Mesh triangulation | ✅ Stable | [docs.rs](https://docs.rs/ifc-lite-geometry) |
+| `ifc-lite-wasm` | WASM bindings | ✅ Stable | [docs.rs](https://docs.rs/ifc-lite-wasm) |
+
+## Community Projects
+
+Projects built by the community using IFClite (not officially maintained):
+
+| Project | Author | Description |
+|---------|--------|-------------|
+| [bimifc.de](https://bimifc.de/) | [@holg](https://github.com/holg) | Pure Rust/Bevy IFC viewer, no TypeScript needed |
+
+*Built something with IFClite? Open a PR to add it here!*
 
 ## Contributing
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+We welcome contributions!
+
+| Resource | Description |
+|----------|-------------|
+| [**Development Setup**](docs/contributing/setup.md) | Prerequisites, installation, and project structure |
+| [**Testing Guide**](docs/contributing/testing.md) | Running tests, writing tests, CI |
+| [**Release Process**](RELEASE.md) | Versioning and publishing workflow |
 
 ```bash
 # Fork and clone
@@ -224,7 +330,10 @@ git checkout -b feature/my-feature
 # Make changes and test
 pnpm test
 
-# Submit a pull request
+# Add a changeset to describe your changes
+pnpm changeset
+
+# Submit a pull request (include the changeset file)
 ```
 
 ## License

package/package.json

@@ -5,7 +5,7 @@
     "IFC-Lite Contributors"
   ],
   "description": "WebAssembly bindings for IFC-Lite",
-  "version": "1.1.6",
+  "version": "1.2.0",
   "license": "MPL-2.0",
   "repository": {
     "type": "git",
@@ -33,4 +33,4 @@
     "webassembly",
     "aec"
   ]
-}
+}