#moobile

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

⚠️ 还没正式发布到 mooncakes.io，但 moon publish --dry-run 已通过 （服务端 202 Accepted：接受了包名 XiLaiTL/moobile 与版本 0.1.0，且制品自检 0 错误）。 现在想试用，走 §1.1 的本地工作区方式。

怎么读这份文档：使用者看 §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.1.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",
      "exports": [ "start", "snapshot", "subscribe", "element" ],
    },
  },
)

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"]) ],
  )
}

pub fn start() -> @moobile.Mount { @moobile.mount(init, update, view) }
pub fn snapshot() -> Int { /* Mount::snapshot */ }
pub fn subscribe(f : (Int) -> Unit) -> () -> Unit { /* Mount::subscribe */ }
pub fn element() -> @moobile.JsValue { /* Mount::element */ }

为什么四件套要应用自己写：导出的函数必须是单态的，而 mount 对 Model/Msg 泛型。 样板见 demo/main.mbt（30 行）。

#1.3 JS 侧：30 行宿主

import * as Bridge from './myapp.js';

globalThis.MOBILE_HOST = {
  react: React,
  components: { View, Text, Pressable, TextInput, ScrollView },  // 必须恰好提供这 5 个
  scheduleTask,   // 微任务
  scheduleFrame,  // rAF（RN 里没有 window）
};

Bridge.start();

export default function App() {
  useSyncExternalStore(Bridge.subscribe, Bridge.snapshot);
  return Bridge.element();
}

#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. 文档导航