#moobile

用 MoonBit 写一次 UI，交给 React / React Native 渲染 —— Web 与 Android 一套代码。

✅ 已发布：moon add XiLaiTL/moobile@0.2.0（0.1.0 是 2026-09 首发，仓库 https://github.com/XiLaiTL/moobile）。 也可以按 §1.1 的本地工作区方式用它（开发本库时更方便）。 宿主侧：npm install moobile-host（§1.3）—— 0.1.0 是旧接口，下面的写法对应 0.2.x。

怎么读这份文档：使用者看 §1 → §2；想理解为什么这么设计看 §3；要改这个库看 §4。

#1. 快速上手

#1.1 把库加进来

mkdir myapp && cd myapp
cat > moon.work <<'EOF'
members = [
  "D:/ai_project/interest/moobile",   # ← 本库所在的路径
  "app",
]
EOF

# app/moon.mod
name = "you/myapp"

version = "0.1.0"

preferred_target = "js"

import {
  "XiLaiTL/moobile@0.2.0",   # 版本号在工作区解析时被忽略
}

#1.2 MoonBit 侧：写视图 + 一行入口

// app/moon.pkg
import {
  "XiLaiTL/moobile" @moobile,     // ← 库本体就是模块根包
  "XiLaiTL/moobile/style",
  "XiLaiTL/moobile/html",
  "XiLaiTL/moobile/cmd",
}

options(
  link: {
    "js": {
      "format": "esm",
      // ★ 只有一个导出名（0.1.0 是四个）
      "exports": [ "app" ],
    },
  },
)

fn view(m : Model, emit : @cmd.Emit[Msg]) -> @html.Html {
  @html.div(
    attrs=@html.Attrs::build().styles(
      @style.Style::new().font_size(16.0).padding_horizontal(@style.px(12.0)),
    ),
    [ @html.button(on_click=emit(Bump), ["+1"]) ],
  )
}

/// 唯一入口：交出整张句柄表（start / snapshot / subscribe / element + 诊断）。
/// 0.2 才有 `handlers_with_init`（首帧之前先读本地库）；纯 `Model` 起步用 `handlers`。
pub fn app() -> @moobile.JsValue {
  @moobile.handlers_with_init(init=init_app, update~, view~)
}

为什么库能替应用做这件事（0.1.0 时做不到，所以那时要应用自己写四件套）： 导出的函数必须是单态的，而 mount 对 Model/Msg 泛型 —— 但 Mount 本身是非泛型的具体类型， 泛型只存在于构造那一刻。于是库能把四个入口包成一张表交出去。 完整形状见 demo/main.mbt（一行）。

#1.3 JS 侧：宿主是 npm 包 moobile-host

import { mountApp } from 'moobile-host';
import { app } from './myapp.js';                    // MoonBit 编译产物
import { registry } from './registry.generated.js';  // npx moobile-host regen 生成

export default mountApp(app, { registry });

#1.3b 能力（本地库、以后的相机等）

npm install expo-sqlite          # 加能力 = 装那个包
npx moobile-host regen           # 从 package.json 生成 registry.generated.js

#1.4 跑起来

moon build --target js
cp _build/js/debug/build/app/app.js <你的 Expo 工程>/myapp.js
cd <你的 Expo 工程> && npx expo start --port 8081
# 浏览器 http://localhost:8081 ；模拟器/真机先 `adb reverse tcp:8081 tcp:8081`

#2. 能力边界（上手前先看这张表）

#3. 原理

   你的 MoonBit 应用
   Model / Msg / update / view          ← 与 rabbita 完全同款的 TEA 写法
        │
        │  视图用 @html DSL 写；样式用 @style（类型化，不是 CSS 字符串）
        ▼
┌────────────────────────────────────────┐
│  VNode 树 + Cmd / Sub 运行时            │  vendor 的 rabbita
│  （事件派发、订阅、异步 effect 都在这跑）│  （fork：15 个 patch，见 FORK.md）
└────────────────────────────────────────┘
        │
        │  moobile/render.mbt —— 翻译层，只做三件事：
        │    ① 标签表：42 条 HTML 标签 → RN 组件名（div→View、span→Text…）
        │    ② 事件映射：click→onPress、input→onChangeText…（要结合目标标签判断）
        │    ③ 样式 map → RN 的 style 对象
        ▼
┌────────────────────────────────────────┐
│  React 元素                             │  ← React.createElement(...) 的产物，
│  （不是 DOM 节点，也不是 HTML 字符串）   │     直接交给 React 渲染
└────────────────────────────────────────┘
        │  宿主 host/App.js（约 30 行）把它交给 React
        ├──────────────►  React Native  ──────►  Android / iOS 原生视图
        └──────────────►  react-native-web ──►  浏览器 DOM

#谁负责什么

#四条设计原则（决定了上面这张图的样子）

1. 不实现渲染。 布局、排版、文本引擎全部交给 React / RN。 凡是 RN 已有的能力，moobile 只用不造（设计文档 §10 原则 1）。
2. 只换挂载层。 Cmd / Emit / 订阅 / 异步 effect 仍由 rabbita 自己的运行时执行 —— 所以 on_click=emit(Msg) 这种照抄 yi 的写法可以直接跑。
3. 样式必须走类型化通道。 RN 没有 CSS 类、也不吃 CSS 字符串， 所以样式写成 Attrs::styles(@style.Style::new().font_size(16.0))； "长度必须带单位、无单位量必须是数字"这类规则由类型保证。
4. 事件解码是策略，不是硬编码。 DOM 事件在 RN 上拿不到， 于是把 13 处解码点做成可替换的查表：换掉一张表，on_input 这类处理器就换了语义 —— 换来的是"不崩、可降级"，不是"载荷等价"。

#4. 开发者相关

#4.1 仓库结构

#4.2 开发与验证

bash _tools/vendor_sync.sh --apply     # 拉 rabbita@0.15.4 → 铺开 → 打 patch → 统一行尾

moon check --target js        # 类型检查
./build.sh                    # 产物 → host/moobile.js
cd host && npx expo start     # Web 预览 http://localhost:8081（或手机扫码）

node _verify.js               # Web 端到端 26 项断言（需 Metro 在 8081）
bash _tools/check_external.sh # 外部模块可用性：别的模块能不能依赖这个库
bash _tools/vendor_sync.sh --check   # 断言「工作区 == 上游 + patch」（提交前/CI）
bash _tools/lf_normalize.sh --check  # 行尾检查

#4.3 第三方代码怎么来的（生成式 vendor）

#4.4 许可证与第三方

#5. 文档导航