# mosa

**Repository Path**: openkylin/mosa

## Basic Information

- **Project Name**: mosa
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-07
- **Last Updated**: 2026-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mosa

[English](README.md) | 简体中文

Mosa 使用 **HTML 结构、CSS 样式和 Rust 组件逻辑**构建界面。页面和组件模板统一使用 `.mosa` 后缀，内容是 HTML；状态由普通 Rust 对象持有，通过显式 DOM 操作更新界面。

## 快速开始

需要 Rust 1.91+。桌面核心提供早期预览版：

```toml
[dependencies]
mosa = "0.1.0-alpha.1"
```

预览期间 API 可能变化。运行仓库案例需要 Git，请克隆源码：

```sh
git clone https://gitee.com/openkylin/mosa.git
cd mosa
cargo run -p counter
```

在已有 Rust 项目中使用本地源码：

```toml
[dependencies]
mosa = { path = "../mosa/crates/mosa-desktop" }
```

调整路径以匹配本地仓库位置。各平台工具链与构建依赖见[开发指南](docs/guide.zh-CN.md)和[平台指南](docs/platforms.zh-CN.md)。

## 桌面演示

[计算器案例](examples/calculator/README.md)提供十进制四则运算、键盘操作和会话历史，使用 `.mosa` 模板、CSS 和 Rust 实现。

```sh
cargo run -p calculator --locked
```

## 当前架构

`mosa` 提供桌面、移动端和 Web 共用的文档及组件内核：html5ever/Blitz 解析 HTML，Stylo 处理 CSS，Taffy 计算布局，Parley 排版文字，Blitz Paint / AnyRender / Vello CPU 绘制。

| 平台 | 宿主与呈现 | 案例 |
| --- | --- | --- |
| 桌面 | winit + Softbuffer 原生窗口 | counter、components、overlays、dynamic-children、i18n、download-manager、git-manager |
| Web | Rust 编译为 WebAssembly，Canvas 2D 显示绘制结果 | web-counter |
| iOS | winit/UIKit + Softbuffer | mobile-counter、mobile-git-manager |
| Android | NativeActivity + winit/Softbuffer | android-app → mobile-counter |

Web 使用少量 JavaScript 桥接浏览器输入、输入法、窗口尺寸和画布；业务逻辑仍在 Rust。原生宿主不使用 WebView，也不创建 JavaScript 运行时。当前使用 CPU 绘制，不提供 GPU 后端选项。

## 模板与组件

计数器案例目录：

```text
examples/counter/
├── src/main.rs       # 注册资源、挂载根组件、启动应用
├── src/app.rs        # 根组件及其局部子组件注册
├── src/panel.rs      # 带插槽的容器组件
├── src/counter.rs    # 计数状态和事件处理
└── ui/
    ├── index.mosa    # 完整 HTML 页面和挂载点
    ├── app.mosa      # 根组件片段
    ├── panel.mosa    # 默认/命名插槽
    ├── counter.mosa  # 可复用组件片段
    └── style.css
```

父组件可以直接在模板中嵌套子组件：

```html
<ui-panel title="Counters">
  <p slot="description">Two independent Rust instances.</p>
  <ui-counter title="First" initial="10"></ui-counter>
  <ui-counter title="Second" initial="20"></ui-counter>
</ui-panel>
```

Rust `Component::register` 声明模板直接使用的组件类型，`FromProps` 读取静态 HTML 属性。`@click="increment"` 将点击交给 Rust `action()`；状态改变后通过 `View::set_text` 等方法更新自己的视图。组件可以递归嵌套，同一模板的实例分别持有状态。

目前支持静态 Props、默认/命名插槽、稳定 key 的动态子组件和非阻塞后台任务轮询。`.mosa` 不包含 Rust 脚本块或自动数据绑定；CSS 作用于整个文档，尚无组件样式隔离。声明式数据绑定已列入待办，当前不支持 `{{ count }}`、`v-model` 或动态属性表达式。

## 文档

- [英文开发概览](docs/guide.md)。
- [开发指南](docs/guide.zh-CN.md)：构建、最小组件、资源和案例运行。
- [架构说明](docs/architecture.zh-CN.md)：模块职责、解析/渲染链路与平台边界。
- [组件与模板](docs/html-rust-desktop.zh-CN.md)：嵌套、Props、插槽、事件、动态集合和生命周期。
- [Web 与移动端](docs/platforms.zh-CN.md)：工具链、打包和验证范围。
- [编辑器与 CLI](docs/editor.zh-CN.md)：HTML 服务、Cargo 检查和预览。
- [待办清单](docs/remaining-work.zh-CN.md)：数据绑定、无障碍和设备验收。

## 验证与限制

```sh
cargo test --workspace --locked
cargo test -p mosa --no-default-features --locked
cargo run -p counter -- --smoke
cargo run -p counter -- --snapshot /tmp/mosa-counter.png
```

完整本地检查使用 `python3 scripts/check-framework.py`，附加平台与案例检查见平台指南。CSS、图片和字体资源由应用显式注册，文档内核不自动读取任意磁盘文件或访问网络。HTML 脚本和内联 JavaScript 处理器被拒绝；CSS 支持范围取决于固定版本内核，不等同完整浏览器。

桌面已有 macOS 窗口和 PNG 验证，Web 已完成浏览器交互测试；移动端完整设备交互、无障碍以及 Linux/Windows 实机验收仍需推进。具体记录见平台指南。

源码许可见 [LICENSE](LICENSE)，案例设计与第三方素材说明见 [NOTICE.md](NOTICE.md)。