---

MoUI is a multi-platform MoonBit GUI framework for building declarative UI apps with shared platform-neutral app logic. Native host cores own windows, events, services, and lifecycle, then receive concrete renderers through platform renderer provider packages.

Contributions are welcome — see CONTRIBUTING.md.

The current mainline is native Skia raster plus the Web wasm-gc + window/web + browser WebGPU host imports path. Native WGPU remains available as an experimental diagnostic route while the MoonBit WGPU ecosystem matures.

Supported platforms (product class)

Platform	Class	Meaning
macOS	committed	Product mainline (L0–L3 evidence)
Web	committed	Product mainline (wasm-gc + WebGPU)
Windows	committed	Product mainline (L0–L3 evidence)
Linux	committed	Product mainline (L0–L3 evidence)
Android	experimental	Window-hosted path compiles; no usability/product commitment yet
iOS	experimental	Same as Android
HarmonyOS	experimental	Same; signed-device full smoke still open

Mobile is not “unwired glue only,” and it is not product-committed. It is experimental: code compiles and host-sim tests pass, but no development/demonstration usability or product commitment is made without matching-device evidence. See platform readiness declaration.

The runtime pipeline is explicit:

View[Msg] -> ElementTree -> LayoutTree -> RenderTree -> DrawCommand -> renderer

Project Shape

• moui/core/ owns platform-neutral contracts, opaque View, typed events, Program, Effect, Subscription, geometry, draw, semantics, and the public message-independent ViewNode extension protocol wrapped by typed View[Msg].
• moui/views/ owns public view constructors and concrete control behavior implemented as @core.ViewNode values and constructed with @core.View::from_node, without adding new core enum variants.
• moui/runtime/ exposes app/host AppRuntime construction entrypoints and owns runtime state, tree/layout/paint, event dispatch, program message drain, effect task, subscription lifecycle, and diagnostics.
• moui/views/ returns app-facing @moui.View[Msg] values for app code.
• moui/backend/ defines shared host contracts; platform backends normalize window and input events into Event.
• moui/backend/<platform>/ owns only the neutral host; applications select moui_skia_renderer or another renderer provider in the composition root.
• moui/render/ provides the renderer facade, with native Skia raster, WebGPU adapter, and experimental native WGPU implementations under moui_skia_renderer/, moui_web_renderer/, and moui_wgpu_renderer/.
• moui_theme/ is an optional addon workspace member for source-mapped Material, Carbon, Primer, and Fluent theme previews plus the first-party Smartisan-inspired Sickle hybrid skeuomorphic/flat theme.
• examples/*/app/ contains shared app logic, while platform subpackages are thin entrypoints.
• website/ is the MoUI homepage and Web demo surface.

Screenshots

Quick Start

Choose the path that matches what you are trying to do.

Playground

Open the browser Playground to edit and run the guided examples without installing a native toolchain. This is the shortest route for learning the view/update model and checking Web behavior.

Independent Project

Install the standalone CLI, then generate a project outside this repository:

moon install wzzc-dev/moui_cli/cmd/moui
moui new my_app
# Optional smaller skeleton: moui new my_app --template hello
cd my_app
moon update
moon check
moon run macos_skia --target native   # or windows_skia / linux_skia on that host

moui new creates shared app logic plus Web and the current desktop entrypoint. Add Android, iOS, or HarmonyOS explicitly with --platform; mobile projects use wzzc-dev/window templates and keep lifecycle, surface, and input in the platform event loop. See Getting started.

This Repository

Use this path when changing MoUI itself or running the full featured examples:

git clone --recurse-submodules https://github.com/wzzc-dev/MoUI.git
cd MoUI
sh scripts/ci-moon-update.sh
sh scripts/check.sh --profile pr
moon test examples/showcase/app --target native

Showcase is the primary scanning and interaction example. Their platform entrypoints are listed under Running Examples.

Framework setup details, including optional submodules and the window/ local-source workflow, live in Development.

The default daily baseline covers the core framework, maintenance baseline ratchets, Web wasm-gc, native Skia mainline contracts, and Showcase. Design Systems is addon diagnostic coverage; run sh scripts/check.sh --profile theme when changing moui_theme or examples/design_systems.

For current-host backend/provider checks, run:

sh scripts/check.sh --profile platform

For release-oriented screenshot and benchmark handoffs, use:

node scripts/conformance-capture-scaffold.mjs --mode golden
node scripts/conformance-capture-scaffold.mjs --mode benchmark

These commands generate local scaffold manifests and logs under artifacts/; release notes should cite the relevant CI run, uploaded artifact, or smoke log instead of committing generated artifacts. artifacts/ is ignored; keep those files as local or CI evidence.

Running Examples

The featured examples — showcase, mo_workbench, and excel — share app logic in examples/<name>/app and expose thin platform entrypoints. Showcase uses web_wasm, desktop renderer-specific entrypoints, and android_window_hosted, ios_window_hosted, and harmonyos_window_hosted mobile entrypoints.

To try Showcase on a mobile platform, follow the platform-specific setup, build, and run instructions for Android, iOS, or HarmonyOS. Standard examples use the matching wzzc-dev/window platform template through moui build.

Windows prerequisite: before building or running any Windows native entrypoint (windows_skia, or the windows_wgpu diagnostic route), initialize the MSVC toolchain in a PowerShell session:

.\scripts\windows\msvc_env.ps1

This sets up the MSVC environment required by the native Skia link step with shared C11 atomics support (/experimental:c11atomics) and pins MOON_CC to an absolute clang-cl.exe. Run it once per shell before moon run ... --target native on Windows. The MoonBit CLI injects /std:c11 into every MSVC-classified stub compile, and cl.exe rejects that together with the /std:c++20 the Skia stubs need (D8016); clang-cl.exe accepts both and is automatically paired with its sibling llvm-lib.exe as the archiver. The windows_wgpu diagnostic route additionally needs C11 mode (/std:c11) for wgpu_mbt‘s <stdatomic.h> stubs — the Windows build/package helpers enable it for WGPU packages automatically; for a direct moon run, dot-source the script and call Enable-MsvcGlobalC11ModeForCOnlyStubs first.

Showcase

Unified Components, Patterns, Platform, and Diagnostics workspaces across desktop, mobile, and Web. Source lives under examples/showcase/app; platform entrypoints are thin.

# Web (wasm-gc)
moon build examples/showcase/web_wasm --target wasm-gc

# macOS Skia
moon run examples/showcase/macos_skia --target native

# Windows Skia (run msvc_env.ps1 first in PowerShell)
.\scripts\windows\msvc_env.ps1
moon run examples/showcase/windows_skia --target native

# Linux Skia
moon run examples/showcase/linux_skia --target native

Markdown Editor

The Typora-style WYSIWYG Markdown editor (MoMark) lives in its own repository, wzzc-dev/MoMark, vendored here as the examples/momark submodule and registered as a moon.work member. It builds on published wzzc-dev/moui and wzzc-dev/moui_richtext packages; see the MoMark README for setup and platform entrypoints.

Mo Workbench

Native-Skia-first desktop agent dogfood app. Only macos_skia is wired today; Linux/Windows/Web entrypoints are reserved. The bobzhang/openseek dependency resolves from mooncakes.io (pinned in examples/mo_workbench/moon.mod); no submodule or workspace member override is required.

moon run examples/mo_workbench/macos_skia --target native

Excel Viewer

MoonBit Excel (moonbitlang/mbtexcel) file renderer using MoUI data table components. Shared app logic is in examples/excel/app; macos_skia is the retained entrypoint.

# macOS Skia
moon run examples/excel/macos_skia --target native

Focused app-package tests for the featured examples:

moon test examples/mo_workbench/app --target native
moon test examples/showcase/app --target native
moon test examples/excel/app --target native

See Showcase, Examples, Markdown Editor, Mo Workbench, and Showcases for package shapes and platform coverage.

Documentation

The source docs live under docs/. The website preview copies those Markdown files into website/web_wasm/docs/ with node scripts/sync-website-docs.mjs.

• Architecture
• Development
• Testing
• API surface
• API surface audit
• Maintenance mainline
• Platform notes
• Renderer capability report
• View catalog
• Views API guide
• Non-render component cookbook
• App templates
• Examples
• Markdown Editor
• Mo Workbench
• AI collaboration
• 2026 roadmap
• Release readiness

Contributing

MoUI is maintained by a single maintainer with AI assistance and is open to external contributions. Pull requests are the primary entry point for changes.

• Contributing guide — setup, package boundaries, PR requirements, DCO
• Governance — decision mechanism, RFC process, maintainer roles, project handover
• Security policy — vulnerability reporting and support scope
• Code of conduct

License

Apache-2.0. See LICENSE.

Third-party dependency and attribution notes are collected in THIRD_PARTY.md.