npm package: @jianghuizhong/wasmux
Description: Wasm-driven next-gen frontend framework with micro-frontend support
Author: jianghuizhong
Latest version: 1.0.2

# WasmUX

<p align="center">
  <img src="https://img.shields.io/badge/Wasm-Rust-000000?logo=rust&logoColor=white" alt="Wasm Rust">
  <img src="https://img.shields.io/badge/TypeScript-4.9+-3178C6?logo=typescript&logoColor=white" alt="TypeScript">
  <img src="https://img.shields.io/badge/Vite-5.0+-646CFF?logo=vite&logoColor=white" alt="Vite">
  <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License">
</p>

<p align="center">
  <strong>下一代微前端框架</strong> - 基于 WebAssembly 的高性能虚拟 DOM Diff 引擎
</p>

## 特性

- ⚡ **极致性能** - WebAssembly 驱动的虚拟 DOM Diff，万级节点渲染 ≤100ms
- 🔄 **双语法支持** - 同时支持 Vue 模板语法和 React JSX 语法
- 🎯 **微前端架构** - 完整的微前端解决方案，支持应用隔离与通信
- 🔒 **安全增强** - 通信加密、跨域校验、四层隔离机制
- 🛠️ **生态兼容** - 无缝集成 React、Vue 现有组件
- 📊 **性能监控** - 内置性能测试套件和调试工具

## 快速开始

> 📖 **5 分钟上手**: 查看 [快速开始指南](docs/QUICK_START.md)

### 安装

```bash
npm install @jianghuizhong/wasmux
# 或
yarn add @jianghuizhong/wasmux
# 或
pnpm add @jianghuizhong/wasmux
```

### 基础用法

#### 1. 创建应用（模板语法）

```typescript
import { WasmUXApp, compile } from '@jianghuizhong/wasmux';

const container = document.getElementById('app')!;
const app = new WasmUXApp(container, {
  root: container,
  syntax: 'template',
});

// 挂载模板
app.mount('<div class="app"><h1>Hello WasmUX!</h1><p>高性能微前端框架</p></div>');
```

#### 2. 使用 JSX

```typescript
import { WasmUXApp, compile } from '@jianghuizhong/wasmux';

const container = document.getElementById('app')!;
const app = new WasmUXApp(container, {
  root: container,
  syntax: 'jsx',
});

const vnode = compile('<div className="app"><h1>Hello WasmUX!</h1></div>', 'jsx');
app.mount(vnode);
```

#### 3. 使用模板语法 + 响应式 data

```typescript
import { WasmUXApp } from '@jianghuizhong/wasmux';

const container = document.getElementById('app')!;
const app = new WasmUXApp(container, {
  root: container,
  syntax: 'template',
  data: () => ({
    title: 'Hello WasmUX!',
    message: '欢迎使用模板语法',
    showMessage: true,
    items: [
      { id: 1, name: 'Item 1' },
      { id: 2, name: 'Item 2' },
    ],
  }),
});

app.mount(`
  <div class="app">
    <h1>{{ title }}</h1>
    <p v-if="showMessage">{{ message }}</p>
    <ul>
      <li v-for="item in items" :key="item.id">{{ item.name }}</li>
    </ul>
  </div>
`);
```

## 微前端使用

### 注册子应用

```typescript
import { registerMicroApps, start } from '@jianghuizhong/wasmux/micro';

registerMicroApps([
  {
    name: 'app1',
    entry: '//localhost:3001',
    container: '#container',
    activeRule: '/app1',
    props: { userId: 123 }
  },
  {
    name: 'app2',
    entry: '//localhost:3002',
    container: '#container',
    activeRule: '/app2'
  }
]);

start();
```

### 使用 Web Component

需先调用 `registerWasmuxMicroAppElement()` 注册自定义元素：

```typescript
import { registerWasmuxMicroAppElement } from '@jianghuizhong/wasmux';
registerWasmuxMicroAppElement();
```

```html
<wasmux-micro-app
  name="app1"
  entry="http://localhost:3001"
  container="#container"
  active-rule="/app1"
  :props='{"userId": 123}'
>
</wasmux-micro-app>
```

### 跨应用通信

```typescript
import { initGlobalState, MicroAppStateActions } from '@jianghuizhong/wasmux/micro';

// 初始化全局状态
const actions: MicroAppStateActions = initGlobalState({
  user: { name: 'John' },
  theme: 'dark'
});

// 主应用监听状态变化
actions.onGlobalStateChange((state, prev) => {
  console.log('State changed:', state);
});

// 子应用修改状态
actions.setGlobalState({ theme: 'light' });
```

## 性能优化

### Wasm Diff（自动启用）

Wasm 虚拟 DOM Diff 引擎会自动加载，无需手动初始化。加载失败时自动降级为 JS Diff。

```typescript
import { WasmUXApp, compile } from '@jianghuizhong/wasmux';

const app = new WasmUXApp(container, { root: container, syntax: 'template' });
app.mount('<div>...</div>');
// Wasm Diff 已在内部自动启用
```

### 大数据传输优化

```typescript
import { sendBigData, receiveBigData, BigDataTransferManager } from '@jianghuizhong/wasmux';

// 使用便捷 API
const channel = new MessageChannel();
await sendBigData(largeDataArray, channel.port1);

// 或使用管理器自定义配置
const manager = new BigDataTransferManager({
  chunkSize: 64 * 1024, // 64KB 分块
  compression: true,
});
await manager.sendBigData(data, target);
```

## 文档

**用户文档**（推荐）：[user/](user/) 目录包含使用者所需的全部文档与示例。

- [用户文档总览](user/README.md) - 文档索引
- [5 分钟快速开始](docs/QUICK_START.md)
- [API 文档](docs/API.md)
- [构建指南](docs/BUILD.md) - Wasm 构建步骤与适用场景
- [参考示例](user/examples/)

## 示例

查看 [examples/](./examples/) 目录获取更多使用示例：

- [基础示例](./examples/basic/) - 快速入门
- [微前端示例](./examples/micro-frontend/) - 微前端架构
- [性能测试](./examples/performance/) - 性能对比
- [Web Components](./examples/web-components/) - 微应用自定义元素
- [路由守卫](./examples/route-guard/) - 路由权限控制

## 浏览器支持

| 浏览器 | 版本 |
|--------|------|
| Chrome | >= 80 |
| Firefox | >= 75 |
| Safari | >= 14 |
| Edge | >= 80 |

## 开发与构建

### Wasm 构建（可选）

Wasm 虚拟 DOM Diff 引擎使用 Rust 编写，需单独构建。**若不构建**，框架会自动降级为 JS 实现，功能不受影响。

**适用场景**：需要极致 Diff 性能（万级节点、高频更新）时，建议启用 Wasm。

```bash
# 安装 Rust 工具链后，构建 Wasm 模块
npm run build:wasm

# 完整构建（Wasm + TS，Wasm 失败不阻塞）
npm run build:full
```

**前置要求**：需安装 [Rust](https://www.rust-lang.org/) 和 [wasm-pack](https://rustwasm.github.io/wasm-pack/)。

```bash
# 安装 wasm-pack
cargo install wasm-pack
```

构建产物输出到 `src/wasm/`，运行时通过 `wasm_diff.js` 动态加载。

### 常规构建

```bash
npm run build    # 仅 TypeScript 构建
npm run test:run # 运行测试
```

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

[MIT](./LICENSE)