macOS

Requirements

• macOS 14 or newer
• Xcode command line tools with a Swift 6 toolchain
• Node.js 22 or newer
• pnpm 11

From the repository root:

pnpm install
pnpm build:host:macos
pnpm demo

pnpm demo starts the React Fast Refresh development server. Use pnpm demo:start to open the example once without watching.

The host is a Swift Package Manager executable that opens a real NSWindow and renders SwiftUI views.

Verification

pnpm verify
pnpm verify:kitchen
pnpm verify:embedded
pnpm verify:package

These local suites require a real window session. They use native tree dumps, synthesized events, optimistic edits, and host-rendered PNG files. They do not rely on browser automation.

• pnpm verify covers the base demo and controlled-input stress cases.
• pnpm verify:kitchen exercises app-shell and multi-component workflows through the kitchen-sink app.
• pnpm verify:embedded runs the demo inside the host with JavaScriptCore and no Node process at runtime.
• pnpm verify:package builds and launches the native .app, validates its handshake and tree, then exercises the normal close lifecycle.

The headless macOS CI job builds the Swift host and .app, then validates the bundle layout, metadata, architecture, entry integrity, and license without launching it. It does not run the GUI suites.

Package a macOS application

From the repository root:

pnpm package:demo

The command reads examples/demo/natui.app.json and writes:

examples/demo/dist/package/NatUIDemo.app

The .app contains the native executable, generated Info.plist, bundled JavaScript, and a generated manifest with its SHA-256 digest. The loader validates bundle schema, protocol, minimum host API, architecture, and entry integrity before JavaScriptCore evaluates the application.

When icons.macos is configured, packaging requires an .icns container with complete PNG or JPEG 2000 image payloads, copies it to Contents/Resources/AppIcon.icns, and records CFBundleIconFile in Info.plist.

macOS packaging targets the architecture of the machine performing the build. Build each architecture natively and copy the complete .app directory when moving the application.

The reference packager does not perform code signing or notarization. It also does not create an installer, automatic updater, single-instance coordinator, or multi-window application. See application bundles.