#wzzc-dev/window

• modules/window: the wzzc-dev/window compatibility library modeled after winit
• modules/windowing: the backend-neutral Milky2018/windowing handle module

#Platform Support

• macOS: supported on the native target through AppKit (wzzc-dev/window/macos)
• Windows: preview support on the native target through Win32 (wzzc-dev/window/windows)
• Linux: preview support on the native target through Wayland + xdg-shell (wzzc-dev/window/linux)
• Web: experimental browser support on the wasm-gc target (wzzc-dev/window/web)
• Android, iOS, HarmonyOS: experimental host-driven adapters on the native target (wzzc-dev/window/<platform>); the host supplies lifecycle, surface, and input events while the package normalizes them as window events
• Placeholder handle types: Xlib and Xcb
• Not supported yet: X11 and other Unix backends

#Windows Support (Preview)

#MSVC

cmd /k "C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64

where.exe cl
moon build modules\window\examples\window_windows --target native
moon run modules\window\examples\window_windows --target native

#Mingw

where.exe gcc
moon build modules\window\examples\window_windows --target native
moon run modules\window\examples\window_windows --target native

#Web Support (Experimental)

moon build modules/window/examples/window_web --target wasm-gc

node modules/window/examples/window_web/serve.mjs

http://127.0.0.1:8000/modules/window/examples/window_web/index.html

_build/wasm-gc/debug/build/examples/window_web/window_web.wasm

• window_web: createWindowWebImports()
• spectest.print_char for MoonBit println
• connectWindowWeb(instance, windowWeb) before calling _start()

#Linux Support (Preview)

sudo apt install libwayland-dev wayland-protocols wayland-scanner pkg-config

moon build modules/window/examples/window_linux --target native
moon run modules/window/examples/window_linux --target native

#Install

moon add wzzc-dev/window

#Quick Start

import {
  "wzzc-dev/window/core",
  "wzzc-dev/window/macos",
}

supported_targets = "native"

options("is-main": true)

///|
struct App {
  mut window : @macos.Window?
}

///|
pub impl @macos.ApplicationHandler for App with can_create_surfaces(
  self,
  event_loop,
) {
  let attrs = @core.WindowAttributes::default().with_title("window demo")
  let window : @macos.Window? = Some(event_loop.try_create_window(attrs)) catch {
    err => {
      println("error creating window: \{err}")
      event_loop.exit()
      None
    }
  }
  self.window = window
}

///|
pub impl @macos.ApplicationHandler for App with window_event(
  self,
  event_loop,
  _id,
  event,
) {
  match event {
    CloseRequested => event_loop.exit()
    SurfaceResized(_) =>
      match self.window {
        Some(window) => window.request_redraw()
        None => ()
      }
    RedrawRequested => println("redraw requested")
    _ => ()
  }
}

///|
fn main {
  let event_loop = @macos.EventLoop::EventLoop()
  event_loop.run_app({ window: None })
}

#Error Model

• EventLoop::try_new() may raise @core.EventLoopError
• Window::set_cursor_position(...) may raise @core.RequestError
• Window::request_ime_update(...) may raise @core.ImeRequestError

#macOS Caveats

• EventLoop must be created and run on the process main thread. EventLoopBuilder::with_any_thread(true) does not relax this AppKit requirement.
• Methods on an existing Window may be called from worker threads. AppKit-backed operations synchronously execute on the process main thread, matching winit's macOS behavior. Do not block the main thread while waiting for a worker that is calling a Window method.
• monitor_ns_screen(...) returns a retained NSScreenHandle snapshot. Keep that handle alive while using objc_handle(), and resolve it again after a display reconfiguration.
• EventLoop::pump_app_events(...) is for host-loop integration, not frame-by-frame rendering. For frame-driven apps, prefer run_app() with ControlFlow::Poll or ControlFlow::WaitUntil.
• Window::set_cursor_grab(@core.CursorGrabMode::Confined) raises @core.RequestError::NotSupported.
• Window::drag_resize_window(...) raises @core.RequestError::NotSupported on macOS.
• Window::show_window_menu(...) currently has no native AppKit implementation.
• @core.CustomCursorSource::Url(...) and animation cursors are not supported on macOS.
• Window::set_prefers_home_indicator_hidden(...), Window::set_prefers_status_bar_hidden(...), and Window::set_preferred_screen_edges_deferring_system_gestures(...) are parity state setters on macOS (no native AppKit effect).

#macOS Renderer Integration

let raw = try! window.window_handle().as_raw()
match raw {
  @windowing.RawWindowHandle::AppKit(handle) => {
    let ns_view = handle.ns_view()
    // Create the renderer surface from ns_view.
  }
  _ => abort("renderer does not support this window backend")
}

• Window::scale_factor() for contentsScale
• Window::surface_size() for physical drawable size
• WindowEvent::SurfaceResized and WindowEvent::ScaleFactorChanged for resize/scale resync
• the content view bounds for the layer frame
• autoresizing or an explicit renderer-side sync step for future view resizes

#API Overview

• @wzzc-dev/window/core: core event/types (WindowEvent, ControlFlow, WindowAttributes, keyboard/mouse/IME data types)
• @wzzc-dev/window/macos: macOS runtime API (EventLoop, ActiveEventLoop, Window, EventLoopProxy, ApplicationHandler)
• @wzzc-dev/window/windows: Windows runtime API (EventLoop, ActiveEventLoop, Window, EventLoopProxy, ApplicationHandler)
• @wzzc-dev/window/linux: Linux Wayland runtime API (EventLoop, ActiveEventLoop, Window, EventLoopProxy, ApplicationHandler) plus Wayland extension APIs exposing display/surface/xdg handles
• @wzzc-dev/window/web: browser wasm-gc runtime API (EventLoop, ActiveEventLoop, Window, EventLoopProxy, ApplicationHandler) plus Web extension APIs for canvas binding and poll strategy selection
• @wzzc-dev/window/android, @wzzc-dev/window/ios, and @wzzc-dev/window/harmonyos: host-driven native event-loop adapters for platform lifecycle, surface, and input event normalization
• @wzzc-dev/window/dpi: logical/physical size and position types
• @Milky2018/windowing: structured raw handles and provider traits

#Web Caveats

• Web support currently targets browser environments with wasm-gc; Node or headless environments without DOM APIs are not the supported runtime.
• run_app/try_run_app/spawn_app register browser callbacks and return instead of blocking the thread.
• ControlFlow::Poll uses requestAnimationFrame by default. Wait responds to DOM/proxy wakeups, and WaitUntil uses browser timers.
• Native-only features such as taskbar integration, native decorations, window levels, system menus, native drag-window, exclusive fullscreen, and precise monitor information are intentionally unsupported or no-op on Web.
• Raw window/display handles return stable placeholder values; use Web extension APIs such as Window::canvas_id() for canvas identity.

#Windows Caveats

• Windows support is preview quality and targets desktop Win32 through the MoonBit native backend.
• Use a working C toolchain before building examples. MSVC users should run vcvarsall.bat; Mingw users should ensure gcc is on PATH.
• Some APIs that are meaningful on macOS or Web may be state-only, no-op, or NotSupported on Windows while parity work continues.

#Linux Caveats

• Linux support currently targets Wayland + xdg-shell; X11 is intentionally left unsupported in this package.
• The first backend attaches a small SHM placeholder buffer so windows map even when the app has not provided a renderer yet.
• Window::present_rgba_pixels(...) presents renderer-owned RGBA pixel frames through Wayland wl_shm for CPU raster renderers such as MoUI Skia.
• Keyboard events currently expose native XKB key codes without text decoding; text input and IME are future work.
• Decorations, taskbar integration, system menus, native drag-window, exclusive fullscreen, precise monitor metadata, custom cursors, and rich raw-handle parity are currently unsupported, no-op, or placeholder behavior.

#Rich Event Matching

///|
pub impl @macos.ApplicationHandler for App with window_event(
  self,
  event_loop,
  _id,
  event,
) {
  match event {
    PointerMoved(_, position, _, _) =>
      println("pointer moved: \{position}")
    DragEntered(paths, position) =>
      println("drag entered at \{position}: \{paths}")
    CloseRequested => event_loop.exit()
    _ => ()
  }
}

#Repository Examples

moon run modules/window/examples/window --target native
moon run modules/window/examples/window_windows --target native
moon build modules/window/examples/window_web --target wasm-gc
moon run modules/window/examples/window_linux --target native

#Validation

scripts/check_ci.sh

RUN_EXAMPLE_TRANSCRIPTS=1 scripts/check_ci.sh