A MoonBit UI runtime for WeChat MiniApp Skyline with pure Elm-style authoring, component-scoped state, and generated MiniApp host commands.

moonbit

elm-architecture

tea

host-runtime

host-commands

component-state

miniapp

skyline

pure-elm

ui-runtime

moon add lampclaw/lampo@0.1.0

Download zip

Author

lampclaw

Version

0.1.0

License

Apache-2.0

Repository

github.com/wenfeizou/lampo

Last updated

last month

Downloads

Dependencies

moonbitlang/async0.20.1
moonbitlang/x0.4.46

README

#Lampo

中文文档

Lampo is MoonBit for WeChat MiniApp Skyline.

Authors write pure Elm-style business logic in MoonBit; Lampo lowers it into reviewable Skyline MiniApp artifacts and a generated JavaScript bridge.

The user-facing programming model is pure Elm-style:

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

The runtime may use mutable cells, caches, command queues, generated metadata, JavaScript bridges, and batching internally. Ordinary application authors should write MoonBit structs, enums, pattern matching, and pure update functions instead of wiring Signal, renderer patches, direct setData, or manual lifecycle disposal.

#Positioning

Full pin: docs/positioning.md.

The product pipeline is:

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

Operating rules:

WeChat MiniApp Skyline product surface
TailwindCSS utility classes for supported style generation
MoonBit owns application behavior
Generated MiniApp JavaScript owns host bridge calls such as setData and wx.*
Runtime internals (signals, queues, metadata, caches) are not the default user API
Not a cross-platform JavaScript framework; not React/Vue-compatible APIs

Reference boundaries (not Lampo products): Luna (runtime), Rabbita (authoring), weapp-vite (MiniApp engineering).

#Capability Expansion: WeChat AI

Primary next capability expansion: WeChat Mini Program AI development mode (beta) — expose app logic as agent-callable SKILLs (SKILL.md + mcp.json + atomic APIs/components) while keeping Skyline generation as the delivery surface. Positioning stays MoonBit for WeChat MiniApp Skyline.

Lampo already isolates intent (Model / Msg / update), typed capability phases/diagnostics, and reviewable generated artifacts — a natural fit for schema-driven atomic APIs and page handoff. Backend-required boundaries (session, payment) stay explicit when an agent may fulfill orders.

Direction and official landscape: docs/wechat_ai_direction.md. Not in 0.1.0: generating agent.skills / mcp.json / SKILL packages. WeChat AI access itself remains platform beta.

#Why Skyline And TailwindCSS

Traditional Mini Program and Skyline projects still share the same visible artifact shape: app/page JSON, WXML, WXSS, and JavaScript. Skyline gives Lampo one modern MiniApp renderer boundary to target, so the framework can focus on generated WXML/WXSS/JS, setData batching, page lifecycle, payload budgets, wx.* adapters, runtime bridge diagnostics, and release gates.

TailwindCSS plus weapp-tailwindcss keeps styles auditable. MoonBit view code emits class tokens; weapp-tailwindcss lowers those tokens into MiniApp-compatible WXSS, including escaped class names and arbitrary values. This is safer than treating handwritten semantic WXSS as Lampo's public style system.

#Version Policy

Lampo product version is 0.1.0, defined by moon.mod and CHANGELOG.md on main. Version git tags are not used.

The release gate is vp run check:mvp. Individual maintenance scripts run through vp run script -- scripts/<name>.mjs (VitePlus/vp entrypoint; Bun remains the JavaScript script runtime). Local lampo CLI covers init/build style workflows for app authors.

package.json is a private, unversioned JS tool shell for local scripts and the lampo bin — not an npm publish target and not the product version source.

MoonBit package distribution targets mooncakes.io (moon publish). Contest source review can use this repository directly; the mooncakes path matters when reviewing registry distribution. Day to day, lampo init still joins apps into this repo's local moon.work so lampclaw/lampo@0.1.0 resolves from workspace sources. A registry-distribution review requires publishing lampclaw/lampo@0.1.0 first, then reviewing an app that resolves lampo from mooncakes (init dual-mode lands with that publish batch; see docs/contest_submission.md).

Current 0.x work keeps the public product scope on MoonBit authoring, generated WeChat MiniApp Skyline artifacts, Bun-backed generation/check scripts, and reviewable release diagnostics. Future minor releases should be used for meaningful generator, runtime bridge, SDK adapter, or authoring surface changes; patch releases should preserve the current MiniApp contract.

Contest pin checklist: docs/contest_submission.md.

#Current Reality

Already implemented:

Elm-style authoring pipeline to generated Skyline MiniApp artifacts and a JavaScript bridge (setData / typed wx.* adapters).
Local lampo CLI plus release gate vp run check:mvp (fixtures, fake-host, page smoke, capability/payment boundaries, release summaries).
Starters and fixtures: capability-dense examples/miniapp_counter is the primary verified DevTools evidence; examples/miniapp_profile_app is the recommended source/app-shape companion; examples/miniapp_minimal_app is the smallest app shape. Counter also has a fake-host counterpart and there is a separate JS runtime bridge spike.
Internal packages: tea_runtime, ui_dsl, renderer_miniapp / renderer_miniapp_js, plus signal/patch infrastructure used behind the default user API.
Reviewable generation outputs: manifests, diagnostics, smoke checklists, and release parity summaries.

Still out of this snapshot's promise (see docs/positioning.md):

WeChat Developer Tools CI automation
npm publish (package.json stays a private tool shell)
payment real-host validation without an app-owned backend
export-backed lampoRuntimeApi for profile/counter until richer stable JS exports unlock the promotion checklist
generating WeChat AI agent.skills / mcp.json / SKILL packages (direction only: docs/wechat_ai_direction.md)

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

The root module sets options(source: "src") in moon.mod, so public package imports remain under lampclaw/lampo/....

#Validation

Run the current MVP validation path:

vp run check:mvp

This validates root MoonBit tests, JS target tests, MiniApp fixture consistency, the generated MiniApp page smoke path, the MoonBit JS runtime bridge spikes, and the MiniApp fake-host example.

The first-run path from MoonBit source to generated MiniApp project is documented in docs/miniapp_quickstart.md. Manual WeChat Developer Tools validation for the generated MiniApp fixture is documented in docs/miniapp_devtools_validation.md.

Judges can also import the committed example dist/ projects directly without running vp run check:mvp first. The per-example DevTools import steps and expected visible behavior are documented in docs/miniapp_examples_devtools_guide.md. DevTools screenshot evidence for the primary counter fixture is documented in docs/miniapp_devtools_screenshots.md. Only the Counter fixture is claimed as manually verified in WeChat Developer Tools; the other committed dist/ projects are generated review companions covered by local gates. Run vp run check:mvp only when reproducing the generation and validation gate from source.

#Reviewer Formatting Gate

Generated MoonBit source files must be stable under MoonBit's formatter. Any script that writes generated .mbt files, especially *.generated.mbt, should format the written file before drift or parity checks compare it. JavaScript generators should use formatMoonBitFile(outputFile) from scripts/io/moonbit_format.mjs.

When a drift or parity check needs a temporary generated .mbt file, place it inside the relevant MoonBit package or otherwise use the same package context as the real generated file. This keeps moon fmt <file> behavior identical to the committed artifact.

Before review, commit, or release handoff, these commands must succeed:

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

moon fmt and moon info do not accept --deny-warn in the current MoonBit toolchain. Treat warnings as errors through moon check --deny-warn and moon test --deny-warn. moon info must leave the worktree clean, and moon fmt --check must pass after the MiniApp generators have run.

#GitHub Language Stats

The repository keeps generated WeChat MiniApp projects under examples/*/dist/ and generated diagnostics under examples/*/generated/ so reviewers can inspect and import the exact artifacts. These paths are marked as linguist-generated in .gitattributes because they are build output, not maintained JavaScript source.

Also marked linguist-generated (non-product assets, not “JS moved to MoonBit”):

scripts/archive/ — archived spikes
listed scripts/check_support/ scenario / expected / fixture-table files — check fixture assets outside the Slimdown harness KPI
**/*.mbti — moon info package surfaces

Production glue under scripts/, scripts/check_*.mjs orchestrators, and small assert helpers (for example harness_assert.mjs, fixture_assert.mjs) stay visible to Linguist until real framework semantics live in MoonBit. JavaScript should stay as CLI glue, file-system orchestration, VitePlus/Bun integration, Tailwind/MiniApp tooling integration, and host bridge output; MoonBit should own the product semantics, metadata model, runtime command model, and core MiniApp generation logic.

GitHub may need a push and reindex before the language bar updates. Local LOC proxies are approximate share only.

#Create And Build MiniApp Apps

Use the Lampo CLI to create a MoonBit-authored MiniApp application and generate the WeChat MiniApp project that can be imported into WeChat Developer Tools. The recommended script entrypoint is VitePlus/vp, with Bun as the underlying JavaScript script runtime:

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 creates a new app directory from a template. The profile template is the best review-oriented starter; it shows Model, Msg, update, view, app metadata, lifecycle messages, form input, keyed-list rendering, and typed MiniApp capability commands. The smaller minimal template is available for the shortest app shape:

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

lampo build reads either an app directory or a miniapp.lampo.json file and generates the MiniApp artifacts:

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

The generated review surface is:

examples/my_profile_app/src/        # MoonBit source owned by the app author
examples/my_profile_app/_lampo/     # Lampo-owned build specs
examples/my_profile_app/generated/  # generated metadata, diagnostics, summaries
examples/my_profile_app/dist/       # WeChat MiniApp project to import

Import examples/my_profile_app/dist into WeChat Developer Tools to inspect the generated Skyline MiniApp project. Use --mode dev for development output or --mode release for the release-oriented default:

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

Do not commit local command shims, editor state, or dependency-manager output such as .bin/, .vite-hooks/, .vscode/, .tmp/, .mooncakes/, or node_modules/. Use the vp run script -- scripts/lampo.mjs ... commands above for the repository-supported CLI path.

#Judge Review Workflow

For a competition or review setting, inspect the project in this order. It shows the author-facing MoonBit source first, then the generated MiniApp artifacts, then the real-host import path.

GitHub language statistics are configured to exclude the committed MiniApp build output under examples/*/dist/ and examples/*/generated/. The remaining JavaScript in scripts/ is maintained tooling glue, not hidden generated code.

Review the main app-authoring MoonBit source:
```
examples/miniapp_profile_app/src/miniapp_profile_app.mbt
```
This is the best source-level showcase. It contains the pure Model, Msg, update, view, app, page lifecycle messages, form input, keyed-list rendering, and typed MiniApp capability commands for wx.login, wx.getStorage, wx.getLocation, and wx.chooseMedia.
Review the MoonBit metadata command:
```
examples/miniapp_profile_app/src/cmd/metadata/main.mbt
```
It emits the app/page/component/capability metadata consumed by the generator, so reviewers can see that the reusable app shape is driven from MoonBit-authored metadata rather than handwritten MiniApp project files.
Review the broad smoke fixture source:
```
examples/miniapp_counter_fake/src/miniapp_counter_fake.mbt
```
This fixture has the widest runtime and capability coverage. It validates counter events, keyed-list operations, lifecycle behavior, and generated wx.* adapter metadata used by the DevTools fixture.

Run the local validation gates:

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

Regenerate and inspect the MiniApp projects:

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

Then inspect:

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

Import the primary DevTools project:
```
examples/miniapp_counter/dist
```
This is the best single WeChat Developer Tools import for judging runtime breadth. Reviewers can import the committed dist/ directly; running vp run check:mvp first is optional and only needed to reproduce the local generation gate. Detailed import steps and expected UI behavior for all four committed MiniApp examples are in docs/miniapp_examples_devtools_guide.md. DevTools screenshot evidence for the primary counter fixture is in docs/miniapp_devtools_screenshots.md. Only the Counter fixture is claimed as manually verified in DevTools; the other committed examples are generated review companions covered by local gates.
Optionally import the app-shape starter:
```
examples/miniapp_profile_app/dist
```
This is the best DevTools companion for source-level review. It shows the single-directory app starter shape where MoonBit source owns Model/update/view, app metadata, lifecycle, form input, and capability declarations.

#Near-Term Work

The next concentrated work should be:

Replace the current counter behavior adapter with a reusable app adapter driven by generated MoonBit metadata. The generation entrypoint already selects adapters through miniapp.lampo.json.
Move the current lampoRuntimeApi v1 implementation from generated wrapper code to compiler/export-supported MoonBit JS runtime APIs.
Expand generated wx.* capability adapters and diagnostics.
Add release-summary automation around diagnostics, smoke checklist, payload data, and manual DevTools status.
Add real-host validation automation.

Site source Report issue Packages Build queue Skills Statistics