# Lampo

[English README](README.mbt.md)

Lampo 是 **MoonBit for WeChat MiniApp Skyline**。

作者用纯 Elm 风格的 MoonBit 写业务逻辑；Lampo 将其生成/下沉为可审查的 Skyline
小程序产物与生成 JS 桥。

用户侧编程模型是 pure Elm-style：

```text
Model + Msg -> update -> Model
Model -> view
Cmd -> Msg
```

运行时内部可以使用 mutable cell、缓存、命令队列、生成 metadata、JavaScript
bridge 和 batch。普通应用作者应该写 MoonBit struct、enum、模式匹配和纯
`update` 函数，而不是手动接入 `Signal`、renderer patch、直接 `setData`
或生命周期 dispose。

## 定位

完整定稿：[`docs/positioning.md`](docs/positioning.md)。

产品流水线是：

```text
pure Elm-style MoonBit authoring
-> component-scoped runtime state
-> MiniApp runtime commands
-> generated Skyline MiniApp artifacts
-> generated JavaScript bridge
-> setData and wx.* adapters
```

运行规则是：

- 产品面为微信小程序 Skyline
- 支持的样式生成使用 TailwindCSS utility class
- MoonBit 拥有应用行为
- 生成的 MiniApp JavaScript 拥有 `setData` 和 `wx.*` 等 host bridge 调用
- runtime 内部的 signal、queue、metadata、cache 不是默认用户 API
- 不是跨端 JavaScript 框架；不提供 React/Vue 兼容 runtime API

参考边界（不是 Lampo 产品）：Luna（runtime）、Rabbita（authoring）、
weapp-vite（MiniApp 工程）。

## 能力扩展：微信 AI

下一阶段主要**能力扩展**：对接微信小程序 **AI 开发模式（内测）**——把业务逻辑
暴露为 Agent 可调用的 **SKILL**（`SKILL.md` + `mcp.json` + 原子 API / 原子
组件），同时仍以 Skyline 生成产物为交付面。产品口号保持
**MoonBit for WeChat MiniApp Skyline**。

Lampo 已把意图隔离在 `Model` / `Msg` / `update`、类型化 capability 阶段 /
diagnostics，以及可审查生成物中，天然适合 schema 驱动的原子 API 与页面
handoff。会话换票与支付签名等必须走后端的边界，在 Agent 可能代下单时更要
写清楚。

方向与官方版图：[`docs/wechat_ai_direction.md`](docs/wechat_ai_direction.md)。
**不在 `0.1.0`：** 尚未生成 `agent.skills` / `mcp.json` / SKILL 包。微信 AI
接入本身仍处平台内测。

## 为什么选择 Skyline 和 TailwindCSS

传统小程序和 Skyline 小程序仍然共享可见的产物形态：app/page JSON、WXML、
WXSS 和 JavaScript。Skyline 为 Lampo 提供统一的现代 MiniApp renderer 边界，
从而聚焦生成 WXML/WXSS/JS、`setData` batching、page lifecycle、payload
budget、`wx.*` adapter、runtime bridge diagnostics 和 release gate。

TailwindCSS 加 `weapp-tailwindcss` 让样式更容易审查。MoonBit view code 输出
class token；`weapp-tailwindcss` 把这些 token 降级成 MiniApp-compatible WXSS，
包括转义 class name 和 arbitrary value。相比把手写 semantic WXSS 当成 Lampo
公共样式系统，这条路径更安全。

## 版本策略

Lampo 产品版本为 **`0.1.0`**，以 `moon.mod` 与 `CHANGELOG.md`（`main`）为准。
不使用版本 git tag。

发布 gate 是 `vp run check:mvp`。单个维护脚本通过
`vp run script -- scripts/<name>.mjs` 运行（VitePlus/`vp` 入口；底层
JavaScript 脚本运行时仍为 Bun）。本地 `lampo` CLI 覆盖面向作者的
init/build 类工作流。

`package.json` 为 `private`、无 `version` 的本地 JS 工具壳（scripts 与
`lampo` bin），不是 npm 发布目标，也不是产品版本源。

MoonBit 包分发目标为 **mooncakes.io**（`moon publish`）。比赛源码审查可直接使用
本仓库；只有审查 registry 分发路径时才需要 mooncakes。日常开发下，`lampo init`
仍会把新 app 写进本仓库本地 `moon.work`，使 `lampclaw/lampo@0.1.0` 从
workspace 源码解析。registry 分发路径审查需要先发布 `lampclaw/lampo@0.1.0`，
再让评委路径从 mooncakes 解析 `lampo`（init 双模式实现放在 publish 同一批；
见 `docs/contest_submission.md`）。

当前 `0.x` 工作聚焦 MoonBit authoring、生成 WeChat MiniApp Skyline artifacts、
Bun-backed generation/check scripts，以及可审查的 release diagnostics。后续
minor release 应用于 generator、runtime bridge、SDK adapter 或 authoring
surface 的实质变化；patch release 应保持当前 MiniApp contract。

比赛提交清单：`docs/contest_submission.md`。

## 当前事实

已经实现：

- Elm 风格作者面到生成式 Skyline 小程序产物与 JavaScript 桥（`setData` /
  类型化 `wx.*` adapters）。
- 本地 `lampo` CLI 与发布门禁 `vp run check:mvp`（fixtures、fake-host、page
  smoke、capability/payment 边界、release summaries）。
- 起步与 fixtures：能力面 `examples/miniapp_counter` 是主要已验证 DevTools
  证据；`examples/miniapp_profile_app` 是推荐的源码/app-shape companion；
  `examples/miniapp_minimal_app` 是最小 app 形态。Counter 另有 fake-host
  对应物，仓库也保留单独的 JS runtime bridge spike。
- 内部包：`tea_runtime`、`ui_dsl`、`renderer_miniapp` /
  `renderer_miniapp_js`，以及默认用户 API 背后的 signal/patch 基础设施。
- 可审查生成输出：manifests、diagnostics、smoke checklists、release parity
  summaries。

本快照明确不承诺的项（详见 `docs/positioning.md`）：

- 微信开发者工具 CI 自动化
- npm 发布（`package.json` 仍为 private 工具壳）
- 无业务后端时的支付 real-host 验证
- profile/counter 的 export-backed `lampoRuntimeApi`（需更稳定的 JS exports
  解锁 promotion checklist 之后）
- 生成微信 AI 的 `agent.skills` / `mcp.json` / SKILL 包（仅方向文档：
  `docs/wechat_ai_direction.md`）

## 目录结构

```text
src/
  signal_core/          # internal signal runtime
  ui_dsl/               # typed UI AST DSL and metadata extraction
  tea_runtime/          # Elm-style runtime plus MiniApp command primitives
  patch_graph/          # predecessor typed patch queues, retained internally
  renderer_miniapp/     # fake-host MiniApp setData runtime
  renderer_miniapp_js/  # JavaScript MiniApp fake bridge
  cmd/main/             # root runnable entrypoint
examples/
  miniapp_profile_app/ # single-directory app authoring reference
  miniapp_counter/      # generated MiniApp fixture
  miniapp_counter_fake/ # fake-host MiniApp runtime coverage example
  miniapp_js_runtime_bridge_spike/ # MoonBit JS runtime bridge spike
docs/
  positioning.md
  wechat_ai_direction.md
  architecture.md
  miniapp_only_architecture.md
  compile_model.md
  mvp.md
  miniapp_quickstart.md
  miniapp_renderer.md
  js_runtime_bridge.md
  renderer_protocol.md
  roadmap.md
```

根模块在 `moon.mod` 中设置 `options(source: "src")`，因此 public package import
仍保持在 `lampclaw/lampo/...` 下。

## 验证

运行当前 MVP 验证路径：

```bash
vp run check:mvp
```

该命令会验证 root MoonBit tests、JS target tests、MiniApp fixture consistency、
generated MiniApp page smoke path、MoonBit JS runtime bridge spikes 和 MiniApp
fake-host example。

从 MoonBit 源码到生成 MiniApp project 的首次使用路径记录在
`docs/miniapp_quickstart.md`。生成 MiniApp fixture 的手动微信开发者工具验证记录
在 `docs/miniapp_devtools_validation.md`。

评委也可以直接导入仓库中已提交的示例 `dist/` 项目，不需要先运行
`vp run check:mvp`。4 个示例小程序的逐项导入步骤和预期展示效果记录在
[`docs/miniapp_examples_devtools_guide.md`](docs/miniapp_examples_devtools_guide.md)。
主要 counter fixture 的微信开发者工具截图证据记录在
[`docs/miniapp_devtools_screenshots.md`](docs/miniapp_devtools_screenshots.md)。
只有 Counter fixture 声明已在微信开发者工具中人工验证；其他已提交的 `dist/`
项目是由本地门禁覆盖的 generated review companion。
只有在需要从源码复现生成与验证门禁时，才需要运行 `vp run check:mvp`。

## 评审格式门禁

生成的 MoonBit source files 必须在 MoonBit formatter 下保持稳定。任何写入生成
`.mbt` 文件的脚本，尤其是 `*.generated.mbt`，都应该在 drift 或 parity 检查比较
之前格式化写出的文件。JavaScript 生成器应使用 `scripts/io/moonbit_format.mjs` 中的
`formatMoonBitFile(outputFile)`。

当 drift 或 parity 检查需要临时生成 `.mbt` 文件时，应把临时文件放在对应 MoonBit
package 内，或确保它使用与真实生成文件相同的 package context。这样
`moon fmt <file>` 的行为会与已提交产物一致。

评审、提交或 release handoff 前，这些命令必须通过：

```bash
moon fmt --check
moon check --deny-warn
moon info
git diff --exit-code
moon test --deny-warn
vp run check:mvp
```

当前 MoonBit 工具链下，`moon fmt` 和 `moon info` 不接受 `--deny-warn`。
通过 `moon check --deny-warn` 与 `moon test --deny-warn` 把 warning 视为错误。
`moon info` 必须保持 worktree clean；MiniApp generators 运行后，`moon fmt --check`
也必须通过。

## GitHub 语言统计

仓库保留 `examples/*/dist/` 下生成的微信小程序 project，以及
`examples/*/generated/` 下生成的 diagnostics，方便评审直接检查和导入真实产物。
这些路径在 `.gitattributes` 中标记为 `linguist-generated`，因为它们是 build
output，不是维护中的 JavaScript source。

同样标记为 `linguist-generated` 的是非产品资产（不是“JS 已迁到 MoonBit”）：

- `scripts/archive/` — 已归档的 spike
- 列出的 `scripts/check_support/` scenario / expected / fixture-table 文件 —
  在 Slimdown harness KPI 之外的检查 fixture 资产
- `**/*.mbti` — `moon info` 生成的包表面

`scripts/` 下的生产 glue、`scripts/check_*.mjs` 编排脚本，以及小型 assert
helpers（例如 `harness_assert.mjs`、`fixture_assert.mjs`）会保持对 Linguist
可见，直到真正的框架语义落在 MoonBit。JavaScript 应保留为 CLI glue、文件系统
编排、VitePlus/Bun 集成、Tailwind/MiniApp tooling 集成和 host bridge output；
MoonBit 应拥有产品语义、metadata model、runtime command model 和核心 MiniApp
生成逻辑。

GitHub 语言条可能需要 push 后重新索引才会更新。本地 LOC 代理只是近似占比。

## 创建和构建 MiniApp 应用

使用 Lampo CLI 可以创建 MoonBit-authored MiniApp 应用，并生成可导入微信开发者
工具的微信小程序 project。推荐脚本入口是 VitePlus/vp，底层 JavaScript 脚本运行
时是 Bun：

```bash
vp run script -- scripts/lampo.mjs init examples/my_profile_app --template profile
vp run script -- scripts/lampo.mjs build examples/my_profile_app
```

`lampo init` 会从模板创建一个新的 app 目录。`profile` 模板最适合作为评审展示
starter；它展示 `Model`、`Msg`、`update`、`view`、app metadata、lifecycle
message、form input、keyed-list rendering 和 typed MiniApp capability commands。
更小的 `minimal` 模板可用于最短 app 形态：

```bash
vp run script -- scripts/lampo.mjs init examples/my_minimal_app --template minimal
```

`lampo build` 会读取 app 目录或 `miniapp.lampo.json` 文件，并生成 MiniApp 产物：

```bash
vp run script -- scripts/lampo.mjs build examples/my_profile_app
vp run script -- scripts/lampo.mjs build examples/my_profile_app/miniapp.lampo.json
vp run script -- scripts/lampo.mjs build --config examples/my_profile_app/miniapp.lampo.json
```

生成后的评审 surface 是：

```text
examples/my_profile_app/src/        # 应用作者维护的 MoonBit source
examples/my_profile_app/_lampo/     # Lampo-owned build specs
examples/my_profile_app/generated/  # generated metadata, diagnostics, summaries
examples/my_profile_app/dist/       # 可导入微信开发者工具的 MiniApp project
```

将 `examples/my_profile_app/dist` 导入微信开发者工具，即可检查生成的 Skyline
MiniApp project。使用 `--mode dev` 生成开发输出，或使用 `--mode release` 生成
面向 release 的默认输出：

```bash
vp run script -- scripts/lampo.mjs build examples/my_profile_app --mode dev
vp run script -- scripts/lampo.mjs build examples/my_profile_app --mode release
```

不要提交本地 command shim、编辑器状态或依赖管理器输出，例如 `.bin/`、
`.vite-hooks/`、`.vscode/`、`.tmp/`、`.mooncakes/`、`node_modules/`。仓库支持的
CLI 路径是上面这些 `vp run script -- scripts/lampo.mjs ...` 命令。

## 裁判审查流程

比赛或评审场景建议按下面顺序查看。这个顺序先展示用户侧 MoonBit 源码，
再展示生成物，最后进入真实 host 导入路径。

GitHub 语言统计已配置为排除 `examples/*/dist/` 和 `examples/*/generated/` 下提交的
MiniApp build output。剩余的 `scripts/` JavaScript 是维护中的 tooling glue，不是
被隐藏的生成代码。

1. 查看主要 app-authoring MoonBit source：

   ```text
   examples/miniapp_profile_app/src/miniapp_profile_app.mbt
   ```

   这是最有 source-level 展示价值的文件。它包含 pure `Model`、`Msg`、`update`、
   `view`、`app`、page lifecycle messages、form input、keyed-list rendering，
   以及 `wx.login`、`wx.getStorage`、`wx.getLocation`、`wx.chooseMedia` 的 typed
   MiniApp capability commands。

2. 查看 MoonBit metadata command：

   ```text
   examples/miniapp_profile_app/src/cmd/metadata/main.mbt
   ```

   它输出 generator 消费的 app/page/component/capability metadata，所以评委可以
   看到 reusable app shape 来自 MoonBit-authored metadata，而不是手写 MiniApp
   project files。

3. 查看覆盖面最广的 smoke fixture source：

   ```text
   examples/miniapp_counter_fake/src/miniapp_counter_fake.mbt
   ```

   这个 fixture 覆盖 counter events、keyed-list operations、lifecycle behavior，
   以及 DevTools fixture 使用的 generated `wx.*` adapter metadata。

4. 运行本地 validation gates：

   ```bash
   vp install
   vp config
   vp run check:scripts
   vp run check:mvp
   ```

5. 重新生成并检查 MiniApp projects：

   ```bash
   vp run miniapp:generate
   vp run script -- scripts/lampo.mjs build examples/miniapp_profile_app
   ```

   然后查看：

   ```text
   examples/miniapp_counter/dist
   examples/miniapp_counter/generated/manifest.json
   examples/miniapp_counter/generated/diagnostics.json
   examples/miniapp_counter/generated/release_summary.json
   examples/miniapp_profile_app/dist
   examples/miniapp_profile_app/generated/manifest.json
   examples/miniapp_profile_app/generated/diagnostics.json
   examples/miniapp_profile_app/generated/release_summary.json
   ```

6. 导入主要 DevTools project：

   ```text
   examples/miniapp_counter/dist
   ```

   这是最适合裁判查看 runtime 覆盖面的单个微信开发者工具导入目录。评委可以直接
   导入已提交的 `dist/`；先运行 `vp run check:mvp` 是可选项，仅用于复现本地生成
   门禁。4 个已提交 MiniApp 示例的详细导入步骤和预期 UI 行为见
   [`docs/miniapp_examples_devtools_guide.md`](docs/miniapp_examples_devtools_guide.md)。
   主要 counter fixture 的微信开发者工具截图证据见
   [`docs/miniapp_devtools_screenshots.md`](docs/miniapp_devtools_screenshots.md)。
   只有 Counter fixture 声明已在 DevTools 中人工验证；其他已提交示例是由本地
   门禁覆盖的 generated review companion。

7. 可选导入 app-shape starter：

   ```text
   examples/miniapp_profile_app/dist
   ```

   这是最适合配合源码审查的 DevTools companion。它展示 single-directory app
   starter 形态，其中 MoonBit source 拥有 `Model/update/view`、app metadata、
   lifecycle、form input 和 capability declarations。

## 近期工作

下一阶段应集中完成：

1. 用 generated MoonBit metadata 驱动 reusable app adapter，替换当前 counter
   behavior adapter。generation entrypoint 已经通过 `miniapp.lampo.json` 选择
   adapter。
2. 将当前 `lampoRuntimeApi` v1 implementation 从 generated wrapper code 移到
   compiler/export-supported MoonBit JS runtime APIs。
3. 扩展 generated `wx.*` capability adapters 和 diagnostics。
4. 围绕 diagnostics、smoke checklist、payload data 和手动 DevTools status 增加
   release-summary automation。
5. 增加 real-host validation automation。