MoUI is a multi-platform MoonBit GUI framework

moui

gui

framework

Download zip

Author

wzzc-dev

Version

0.1.5

License

Apache-2.0

Repository

github.com/wzzc-dev/MoUI.git

Last updated

3 months ago

Downloads

#MoUI

MoUI is a multi-platform MoonBit GUI framework prototype 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. The recommended mainline is native Skia raster plus the single Web wasm-gc + window/web + browser WebGPU hostimports path; native WGPU remains available as an experimental diagnostic route while the MoonBit WGPU ecosystem matures.

The runtime pipeline is explicit:

View[Msg] -> internal view tree -> ElementTree -> LayoutTree -> RenderTree -> DrawCommand -> renderer

Current P0/P1 foundations include component state subscriptions, keyed component-scoped effects with cleanup, scoped saveable string/bool/int state, an advanced custom child layout delegate, environment accessibility signals, gesture/action command primitives, a typed host-service bridge, Linux backend readiness tracking, and app-framework helpers for routing, forms, and devtool snapshots.

Detailed notes live in:

The example suite is intentionally small: Showcase is the visual catalog and now contains the Counter and Todo interaction patterns, Design Systems is the separate moui_theme addon diagnostic preview/parity sampler, the WYSIWYG Markdown editor remains a practical editing demo, and PDF Workbench exercises document reading/light editing on the native Skia route with a lightweight UI shell, a separate pdflite adapter package for real PDF model/writeback checks, and a native-only PDFium adapter for real page bitmap rasterization. The root website/ workspace is the MoUI-built bilingual homepage and Web demo surface.

#Screenshots

#Project Shape

core/ owns the platform-neutral runtime, state, layout, input, semantics, draw command model, typed events, Program, Effect, and Subscription.
The root moui facade exposes common core types plus neutral default/light/dark/custom theme builders directly; there is no separate style package.
views/ exposes public view constructors returning opaque @core.View[Msg].
moui_theme/ is an optional repo-local addon workspace member for shared source-mapped design-system models, package-local Material/Carbon/Primer/Fluent entrypoints, and custom theme builders; core MoUI apps do not need it.
backend/host/ defines shared host contracts; platform backends normalize window and input events into HostEvent.
backend/<platform>/skia selects the native Skia raster mainline provider; backend/<platform>/wgpu keeps the native WGPU experimental provider available for diagnostics. Host-core packages do not import concrete renderer implementations.
render/ provides the renderer facade, with native Skia raster, WebGPU adapter, and experimental native wgpu implementations under render/skia/, render/webgpu_adapter/, and render/wgpu/.
examples/*/app/ contains shared app logic, while platform subpackages are thin entrypoints. examples/showcase stays independent of moui_theme; examples/design_systems is the dedicated addon diagnostic example that exercises the official-system entrypoint packages on Web wasm-gc plus macOS, Windows, and Linux Skia entrypoints.
website/ is a root workspace member for the MoUI homepage, with shared app logic in website/app/ and a Web wasm-gc entrypoint in website/web_wasm/.

#Quick Start

Refresh registry packages, verify the repo-local moui_skia workspace, then run the bounded development check:

moon update
sh scripts/check-local-deps.sh
sh scripts/dev-check.sh

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

MoUI resolves wzzc-dev/window from the MoonBit registry as wzzc-dev/window@0.5.1-0.1.4; moon.work does not include a local window checkout. The dependency check verifies that package version, the absence of a repo-local window workspace member, and the moui_skia binding workspace's platform status and native capability contracts via moui_skia/scripts/verify-platform-status.sh and moui_skia/scripts/verify-native-capability-contract.sh. The MoonBit package ecosystem is still maturing, so unexplained build or smoke failures may come from registry cache state or dependency package regressions; include moon update and package-version inspection in the first pass of debugging. Those Skia guards prove the provider lock, fallback parity, FFI ownership/borrow metadata, native smoke marker coverage, and binding-level evidence wiring are present; renderer pixels and platform runtime behavior still come from the opt-in Skia smoke or matching-host example runs.

For current-host backend/provider evidence, run:

sh scripts/dev-check.sh --platform-examples-test
sh scripts/conformance-check.sh --platform-services

--platform-services also writes and validates artifacts/conformance/platform-runtime-evidence.json, the schema v2 matching-host evidence contract for Web, macOS, Windows, and Linux runtime claims. Entries start as pending until a matching host records passed or failed observations before a preview handoff. The checked-in manifest currently marks macOS status=passed from local matching-host AppKit/Skia artifacts with every runtime and native IME observation set to yes plus skiaEvidence.status=passed; a non-skipped manual GitHub Actions dispatch also recorded the macOS platform runtime evidence with github-actions provenance and uploaded the matching artifact bundle. Windows and Linux remain pending until their matching hosts record equivalent platform-runtime artifacts. Native passed entries include the wzzc-dev/window@0.5.1-0.1.4 package smoke monitor/cursor probe as monitorCursor=yes; Web browser-session evidence may leave that field pending because CDP does not prove native monitor/current-monitor or cursor behavior. A passed entry must carry provenance from either a non-skipped successful GitHub Actions job/run, including run URL, workflow, job, runner, and uploaded artifacts, or a local matching-host artifact bundle. For Web, the fold derives this from the browser-session presentation manifest and the environment that performed the fold. Skipped CI jobs, build-only/package-only jobs, and provider/preflight checks cannot be used as passed runtime evidence. See docs/release-readiness.md for the recorded GitHub Actions macOS-only evidence run, the latest all-green MoUI CI run, and their head-SHA boundaries.

For release-oriented screenshot and benchmark handoffs, use sh scripts/conformance-check.sh --golden and sh scripts/conformance-check.sh --bench; these write validated capture manifests under artifacts/conformance/. The benchmark handoff also validates the static Web runtime delivery chain for Showcase and Markdown Editor with node scripts/validate-web-runtime-handoff.mjs, while browser WebGPU/canvas presentation evidence is collected separately with node scripts/record-web-runtime-presentation.mjs and validated with node scripts/validate-web-runtime-presentation-manifest.mjs. A passed artifacts/conformance/web-runtime-presentation.json proves the named browser session reached WebGPU startup, wasm app startup, sized canvas, resize/input event-bridge delivery, Markdown Editor text input, clean target close, clean console, and nonblank screenshot thresholds. Fold the browser artifact into artifacts/conformance/platform-runtime-evidence.json with node scripts/record-platform-evidence-manifest.mjs artifacts/conformance/platform-runtime-evidence.json web --web-presentation-manifest artifacts/conformance/web-runtime-presentation.json so Web platform claims cite one validated evidence manifest and browser-session artifact provenance. A failed browser manifest records failed Web platform evidence; a missing browser manifest keeps the Web platform entry pending.

#Web Wasm-GC

Build and serve the MoUI homepage:

moon build website/web_wasm --target wasm-gc
python3 -m http.server 8080 --bind 127.0.0.1

Open:

http://127.0.0.1:8080/website/web_wasm/index.html

Build and serve the visual showcase:

moon build examples/showcase/web_wasm --target wasm-gc
python3 -m http.server 8080 --bind 127.0.0.1

Open:

http://127.0.0.1:8080/examples/showcase/web_wasm/index.html

Build and serve the WYSIWYG Markdown editor:

moon build examples/markdown_editor/web_wasm --target wasm-gc
python3 -m http.server 8080 --bind 127.0.0.1

Open:

http://127.0.0.1:8080/examples/markdown_editor/web_wasm/index.html

#macOS Native

Native macOS examples use the platform window backend; the recommended mainline entrypoints select the native Skia raster provider. Cold builds can be noticeably slower than package tests or Web wasm-gc example builds, so they are kept out of the default development check.

For macOS moon run linker errors, see Platform notes.

Build the visual showcase on the Skia mainline:

moon build examples/showcase/macos_skia --target native

The examples/showcase/macos_wgpu and examples/showcase/macos_wgpu_cosmic entrypoints remain available as native WGPU diagnostics:

moon build examples/showcase/macos_wgpu --target native
moon build examples/showcase/macos_wgpu_cosmic --target native

Build and run the WYSIWYG Markdown editor on the Skia mainline:

moon build examples/markdown_editor/macos_skia --target native
./_build/native/debug/build/examples/markdown_editor/macos_skia/macos_skia.exe

Build and run PDF Workbench on the Skia mainline:

MOUI_PDFIUM_DISABLE_PREBUILD_PDFIUM=1 moon test examples/pdf_workbench/app --target native
MOUI_PDFIUM_DISABLE_PREBUILD_PDFIUM=1 moon test examples/pdf_workbench/pdflite_adapter --target native
moon test examples/pdf_workbench/pdfium_adapter --target native
moon build examples/pdf_workbench/macos_skia --target native
./_build/native/debug/build/examples/pdf_workbench/macos_skia/macos_skia.exe

The WGPU Markdown editor entrypoint is still available for diagnostics:

moon build examples/markdown_editor/macos_wgpu --target native
./_build/native/debug/build/examples/markdown_editor/macos_wgpu/macos_wgpu.exe

Wrap a native example as a local .app bundle:

sh scripts/package-macos-app.sh \
  --package examples/showcase/macos_skia \
  --name "MoUI Showcase" \
  --bundle-id dev.wzzc.moui.showcase \
  --version 0.1.0

The bundle includes and validates a schema version 1 moui-package.json manifest under Contents/Resources.

#Windows Native

Windows native examples use the MSVC toolchain and vcpkg zlib:x64-windows. The recommended mainline entrypoints select native Skia raster. Native WGPU entrypoints still use wgpu_mbt dynamic mode with the official MSVC wgpu_native.dll release, but they are experimental diagnostics rather than the default validation route.

Setup, build, and package the default Showcase:

winget install --id Microsoft.VisualStudio.2022.BuildTools -e
powershell -ExecutionPolicy Bypass -File .\scripts\windows\setup_msvc_deps.ps1 -InstallZlib
powershell -ExecutionPolicy Bypass -File .\scripts\windows\build_windows_msvc.ps1 `
  -Package examples/showcase/windows_skia `
  -BuildOnly
powershell -ExecutionPolicy Bypass -File .\scripts\windows\package_windows_app_msvc.ps1 `
  -Package examples/showcase/windows_skia `
  -AppName MoUIShowcase `
  -Version 0.1.0

The Showcase also has Windows WGPU/Cosmic diagnostic entrypoints:

powershell -ExecutionPolicy Bypass -File .\scripts\windows\build_windows_msvc.ps1 `
  -Package examples/showcase/windows_wgpu `
  -BuildOnly
powershell -ExecutionPolicy Bypass -File .\scripts\windows\build_windows_msvc.ps1 `
  -Package examples/showcase/windows_wgpu_cosmic `
  -BuildOnly

Build the WYSIWYG Markdown editor with the same MSVC helper:

powershell -ExecutionPolicy Bypass -File .\scripts\windows\build_windows_msvc.ps1 `
  -Package examples/markdown_editor/windows_skia `
  -BuildOnly

The WGPU Markdown editor entrypoint remains available for diagnostics:

powershell -ExecutionPolicy Bypass -File .\scripts\windows\build_windows_msvc.ps1 `
  -Package examples/markdown_editor/windows_wgpu `
  -BuildOnly

To run a Windows entrypoint directly, import the MSVC environment in the same PowerShell process. The helper routes .c native stubs through C11 atomics and keeps Skia .cpp stubs on their own C++ standard flags:

powershell -ExecutionPolicy Bypass -Command "& { . .\scripts\windows\msvc_env.ps1; moon run examples/showcase/windows_skia --target native }"
powershell -ExecutionPolicy Bypass -Command "& { . .\scripts\windows\msvc_env.ps1; moon run examples/markdown_editor/windows_skia --target native }"

The MSVC package is written under dist\windows-msvc\MoUIShowcase and includes run.cmd and the vcpkg zlib runtime DLL. WGPU diagnostic packages additionally include wgpu_native.dll, WGPU release metadata, and a run.cmd wrapper that sets MBT_WGPU_NATIVE_ROOT to the bundled WGPU release. When Visual Studio's bundled vcpkg refuses direct classic installs, run the setup helper from the repository root; it creates an ignored manifest workspace under .tools\vcpkg-msvc and installs zlib:x64-windows there.

#Linux Native

Linux native examples use the wzzc-dev/window@0.5.1-0.1.4 Wayland backend. The recommended mainline entrypoints select native Skia raster and present CPU pixel frames through Wayland wl_shm. Run them on a Linux host with a Wayland compositor and configured real Skia link flags:

moon run examples/showcase/linux_skia --target native
moon run examples/markdown_editor/linux_skia --target native

The examples/showcase/linux_wgpu and examples/showcase/linux_wgpu_cosmic entrypoints remain available as native WGPU diagnostics when a Vulkan/WGPU stack is configured.

For headless validation, use a compositor such as Weston headless and set WAYLAND_DISPLAY to its socket before running the examples. The WGPU Linux text path composes the fontconfig/FreeType provider with Moon Cosmic fallback; that provider currently has a narrow native color-emoji path for explicit emoji family runs, while general text still falls back to Cosmic. linux_wgpu_cosmic selects Moon Cosmic directly.

Effect

source

using @wzzc-dev/moui/core { type Effect }

Environment

source

using @wzzc-dev/moui/core { type Environment }

Runtime environment snapshot. Carries the user's theme_spec (intent), the current system_scheme (host-reported), and the resolved theme derived from both. Changing system_scheme rebuilds the full theme via with_system_scheme; the legacy with_color_scheme (which only flipped a flag and left the palette stale) is removed.

Program

source

using @wzzc-dev/moui/core { type Program }

Subscription

source

using @wzzc-dev/moui/core { type Subscription }

Theme

source

using @wzzc-dev/moui/core { type Theme }

Resolved, drawable theme. A Theme is the output of resolve_theme(spec,system_scheme): it carries the full palette, all scale tiers, and a first-class components aggregate. Controls read ctx.environment.theme.components.<control> at paint time; style? on a control constructor is a one-shot override.

View

source

using @wzzc-dev/moui/core { type View }

ViewEnvironment

source

using @wzzc-dev/moui/core { type ViewEnvironment }

Source Files

moui.mbt

Site source Report issue Packages Build queue Skills Statistics

moui

#MoUI

#Screenshots

#Project Shape

#Quick Start

#Web Wasm-GC

#macOS Native

#Windows Native

#Linux Native

#Effect

#Environment

#Program

#Subscription

#Theme

#View

#ViewEnvironment

Source Files

Effect

Environment

Program

Subscription

Theme

View

ViewEnvironment