Dart: native views from plain Dart programs, and a view example

- runNativeApp() in nativeapi runs an app on the platform's UI thread without
  Flutter: on macOS it takes over the main thread the Dart VM keeps parked, on
  Windows and Linux it starts a thread of its own, and it pumps the platform
  loop between Dart's timers. Backed by an event loop shim in cnativeapi
  (src/event_loop*), compiled by the build hook. nativeapi_flutter does not
  re-export it.
- examples/dart_view_example: a workbench of native views (sign-in form, task
  list, layout playground, notes, generated avatar) and a second window that
  inspects its view tree and events. `dart run bin/main.dart`.
- Bump core: content-sized containers and the fixes the example needed.
- CI, melos and the docs cover examples/dart_*.

Author: lijy91

.github/workflows/dart-ci.yml

@@ -6,6 +6,7 @@ on:
     paths:
       - "bindings/dart/**"
       - "core"
+      - "examples/dart_*/**"
       - "examples/flutter_*/**"
       - "pubspec.yaml"
       - ".github/workflows/dart-ci.yml"
@@ -14,6 +15,7 @@ on:
     paths:
       - "bindings/dart/**"
       - "core"
+      - "examples/dart_*/**"
       - "examples/flutter_*/**"
       - "pubspec.yaml"
       - ".github/workflows/dart-ci.yml"

AGENTS.md

@@ -12,7 +12,7 @@ bindings/
 ├── csharp/         # the C# binding: src/, tests/, NativeAPI.slnx
 ├── js/             # the JS/TS binding: a Node-API addon (src/) + TypeScript (lib/)
 └── python/         # the Python binding: ctypes package (nativeapi/) + native shim (src/)
-examples/           # every binding's example apps, prefixed flutter_*, rust_*, csharp_*, js_*, python_*
+examples/           # every binding's example apps, prefixed dart_*, flutter_*, rust_*, csharp_*, js_*, python_*
 pubspec.yaml        # pub workspace + melos root: Dart packages and Flutter examples
 Cargo.toml          # cargo workspace root: Rust crates and examples
 tools/codegen/      # in-repo Rust workspace: the code generator
@@ -95,8 +95,8 @@ scenarios for *this project's* examples live in [tools/gui/](tools/gui/README.md
 - `core` tracks `branch = main`. Use `make sync` to fast-forward it; `make status` to see dirty state everywhere; `make bump` to stage its pointer.
 - The leanflutter packages built on nativeapi (`tray_manager`, `window_manager`, `launch_at_startup`, …) live in their own repos under github.com/leanflutter and depend on the published `nativeapi`; they are not part of this repo. To try one against local changes, point a `dependency_overrides` entry in that package at `bindings/dart/nativeapi_flutter` (and `nativeapi`, `cnativeapi`) and never commit the override.
 - Commit workspace submodule pointer updates only when the combination is compatible (a known-good snapshot).
-- Examples live in `examples/<binding>_<name>_example` (`flutter_`, `rust_`, `csharp_`, `js_`, `python_`), not inside the bindings; a new Flutter or Rust example must also be listed in the root `pubspec.yaml` / `Cargo.toml`, a C# one in `bindings/csharp/NativeAPI.slnx`, a JS one in the root `package.json`. A Python example is a standalone uv project whose `pyproject.toml` points `nativeapi` at `../../bindings/python` (`uv run main.py` builds the wheel). Only the pub.dev package examples (`bindings/dart/*/example`) stay inside their package.
-- CI is one workflow per binding (`dart-ci.yml`, `rust-ci.yml`, `csharp-ci.yml`, `js-ci.yml`, `python-ci.yml`), each running only for changes under its `bindings/<lang>/` and its examples (`examples/flutter_*` for Dart, `examples/rust_*`, `examples/csharp_*`, `examples/js_*`, `examples/python_*`). Release tags are per binding: `v*` publishes the Dart packages (`dart-release.yml`), `rust-v*` publishes the crates (`rust-release.yml`), `python-v*` publishes the Python package to PyPI (`python-release.yml`: an sdist carrying core in `cxx_impl/`, and wheels built from it with cibuildwheel; the tag must equal `python-v` + the version in `bindings/python/pyproject.toml`); never push a bare `v*` tag for anything but the Dart packages. Nothing has been published to PyPI yet: the first release needs `nativeapi` set up on PyPI with this workflow and the `pypi` environment as a trusted publisher.
+- Examples live in `examples/<binding>_<name>_example` (`dart_` for plain Dart programs, `flutter_`, `rust_`, `csharp_`, `js_`, `python_`), not inside the bindings; a new Dart, Flutter or Rust example must also be listed in the root `pubspec.yaml` / `Cargo.toml`, a C# one in `bindings/csharp/NativeAPI.slnx`, a JS one in the root `package.json`. A Python example is a standalone uv project whose `pyproject.toml` points `nativeapi` at `../../bindings/python` (`uv run main.py` builds the wheel). Only the pub.dev package examples (`bindings/dart/*/example`) stay inside their package.
+- CI is one workflow per binding (`dart-ci.yml`, `rust-ci.yml`, `csharp-ci.yml`, `js-ci.yml`, `python-ci.yml`), each running only for changes under its `bindings/<lang>/` and its examples (`examples/dart_*` and `examples/flutter_*` for Dart, `examples/rust_*`, `examples/csharp_*`, `examples/js_*`, `examples/python_*`). Release tags are per binding: `v*` publishes the Dart packages (`dart-release.yml`), `rust-v*` publishes the crates (`rust-release.yml`), `python-v*` publishes the Python package to PyPI (`python-release.yml`: an sdist carrying core in `cxx_impl/`, and wheels built from it with cibuildwheel; the tag must equal `python-v` + the version in `bindings/python/pyproject.toml`); never push a bare `v*` tag for anything but the Dart packages. Nothing has been published to PyPI yet: the first release needs `nativeapi` set up on PyPI with this workflow and the `pypi` environment as a trusted publisher.
 - The Dart packages `cnativeapi`, `nativeapi` and `nativeapi_flutter` share one version: a release bumps all three pubspecs and CHANGELOGs, because pub.dev's automated publishing matches the tag `v<version>` against each package's own version. `cnativeapi` and `nativeapi` are plain Dart (no Flutter dependency; a build hook compiles core); `nativeapi_flutter` is the Flutter-facing package, holding the widgets, the `dart:ui` conversions and `windowing.dart`, and re-exporting `nativeapi` minus the names that clash with Flutter's.
 - Never commit in a submodule while on a detached HEAD — check out `main` first (`./codegen sync` enforces this).
 - Do not add Co-Authored-By trailers to commits.

bindings/dart/README-ZH.md

@@ -92,9 +92,39 @@ window?.isAlwaysOnTop = true;
 
 所有窗口共用一个 engine 和一个 isolate，窗口之间直接通过普通 Dart 对象通信——不需要改 runner，也不需要消息通道。Flutter 的多窗口 API 仍是实验性的、属于框架内部接口，因此这个桥接单独放在 `package:nativeapi_flutter/windowing.dart` 里。它针对 **stable** channel 编写（已在 3.47.5 上验证）；stable 不提供 `flutter config --enable-windowing`，所以示例在 `main()` 里直接打开 Flutter 内部的 `isWindowingEnabled`。子窗口的完整例子见 [`floating_toolbar_example`](../../examples/flutter_floating_toolbar_example)，另见 [`browser_tabs_example`](../../examples/flutter_browser_tabs_example) 和 [`detachable_window_example`](../../examples/flutter_detachable_window_example)。
 
+### 在纯 Dart 程序里用窗口和原生视图
+
+不依赖 Flutter 的 Dart 程序也能开窗口。把应用交给 `runNativeApp()`：它让应用跑在平台的 UI 线程上，并在 Dart 的定时器和 future 之间持续驱动平台事件循环：
+
+```dart
+import 'package:nativeapi/nativeapi.dart';
+
+void app() {
+  final window = Window.create()!..title = 'Hello';
+  final root = window.contentView!
+    ..layout = ViewLayout.column
+    ..padding = const EdgeInsets(top: 16, right: 16, bottom: 16, left: 16)
+    ..spacing = 8;
+  final label = Label.create('Not clicked yet')!;
+  var clicks = 0;
+  final button = Button.create('Click me')!
+    ..addListener((event) {
+      if (event is ButtonClickedEvent) label.text = 'Clicked ${++clicks}×';
+    });
+  root
+    ..addSubview(label)
+    ..addSubview(button);
+  window.show();
+}
+
+void main() => runNativeApp(app);
+```
+
+`app` 必须是顶层或静态函数：它跑在单独的 isolate 里。在 macOS 上这个 isolate 位于进程的第一个线程——AppKit 只认这个线程，而 Dart VM 平时让它闲置。应用退出（`Application.instance.quit()`、Cmd+Q）时进程结束。用这种方式写的完整应用见 [`dart_view_example`](../../examples/dart_view_example)。
+
 ## 示例
 
-示例是仓库 [`examples/`](../../examples) 下的 `flutter_*` 目录，每个目录是对应一个模块的 Flutter 应用，依赖通过仓库根目录的 pub workspace 解析：
+示例是仓库 [`examples/`](../../examples) 下的 `flutter_*` 目录，外加纯 Dart 程序 [`dart_view_example`](../../examples/dart_view_example)（`dart run bin/main.dart`）。每个 Flutter 示例是对应一个模块的应用，依赖通过仓库根目录的 pub workspace 解析：
 
 ```bash
 flutter pub get          # 在仓库根目录执行

bindings/dart/README.md

@@ -92,9 +92,39 @@ window?.isAlwaysOnTop = true;
 
 All windows share one engine and one isolate, so they talk to each other through ordinary Dart objects — no runner changes, no message channels. Flutter's multi-window API is experimental and internal to the framework, which is why the bridge lives in its own library, `package:nativeapi_flutter/windowing.dart`. It is written against the **stable** channel (checked with 3.47.5); stable does not offer `flutter config --enable-windowing`, so the examples set Flutter's internal `isWindowingEnabled` in `main()`. See [`floating_toolbar_example`](../../examples/flutter_floating_toolbar_example) for a child window built this way, and [`browser_tabs_example`](../../examples/flutter_browser_tabs_example) and [`detachable_window_example`](../../examples/flutter_detachable_window_example).
 
+### Windows and native views from plain Dart
+
+A Dart program without Flutter can open windows too. Hand the app to `runNativeApp()`, which runs it on the platform's UI thread and keeps the platform loop turning between Dart's timers and futures:
+
+```dart
+import 'package:nativeapi/nativeapi.dart';
+
+void app() {
+  final window = Window.create()!..title = 'Hello';
+  final root = window.contentView!
+    ..layout = ViewLayout.column
+    ..padding = const EdgeInsets(top: 16, right: 16, bottom: 16, left: 16)
+    ..spacing = 8;
+  final label = Label.create('Not clicked yet')!;
+  var clicks = 0;
+  final button = Button.create('Click me')!
+    ..addListener((event) {
+      if (event is ButtonClickedEvent) label.text = 'Clicked ${++clicks}×';
+    });
+  root
+    ..addSubview(label)
+    ..addSubview(button);
+  window.show();
+}
+
+void main() => runNativeApp(app);
+```
+
+`app` must be a top-level or static function: it runs in an isolate of its own. On macOS that isolate lives on the process's first thread, the only one AppKit accepts, which the Dart VM otherwise keeps parked. The process ends when the app quits (`Application.instance.quit()`, Cmd+Q). See [`dart_view_example`](../../examples/dart_view_example) for a larger app built this way.
+
 ## Examples
 
-The examples are the `flutter_*` directories in the repository's [`examples/`](../../examples). Each is a Flutter app for one module; they resolve through the pub workspace at the repository root:
+The examples are the `flutter_*` directories in the repository's [`examples/`](../../examples), plus [`dart_view_example`](../../examples/dart_view_example), a plain Dart program (`dart run bin/main.dart`). Each Flutter one is an app for one module; they resolve through the pub workspace at the repository root:
 
 ```bash
 flutter pub get          # at the repository root

bindings/dart/cnativeapi/CHANGELOG.md

@@ -1,3 +1,11 @@
+## Unreleased
+
+* Event loop shim for plain Dart programs (`src/event_loop*`, bound in
+  `lib/src/event_loop.dart`): `cnativeapi_run_ui_thread`,
+  `cnativeapi_start_event_loop`, `cnativeapi_pump_event_loop` and
+  `cnativeapi_exit`, compiled into the same library as the core. They back
+  `runNativeApp()` in `nativeapi`.
+
 ## 0.4.0
 
 * `native_view_backend_t` and `native_view_is_backend_supported`,

bindings/dart/cnativeapi/hook/build.dart

@@ -1,5 +1,7 @@
 // Builds the nativeapi core, C ABI included, into the shared library that the
-// `@Native` functions in lib/src/bindings_generated.dart resolve against.
+// `@Native` functions in lib/src/bindings_generated.dart resolve against,
+// together with this package's own event loop shim (src/, bound in
+// lib/src/event_loop.dart).
 //
 // The source lists mirror core/src/CMakeLists.txt; keep the two in step.
 
@@ -28,6 +30,13 @@ void main(List<String> args) async {
       _ => throw UnsupportedError('cnativeapi does not support $targetOS'),
     };
     final apple = targetOS == OS.iOS || targetOS == OS.macOS;
+    final shim = input.packageRoot.resolve('src/');
+    final shimSource = switch (targetOS) {
+      OS.macOS => 'event_loop_macos.mm',
+      OS.windows => 'event_loop_windows.cpp',
+      OS.linux => 'event_loop_linux.cpp',
+      _ => 'event_loop_other.cpp',
+    };
 
     final sources = [
       ..._list(src, '', '.cpp'),
@@ -40,6 +49,7 @@ void main(List<String> args) async {
           r'(menu_winui3|message_dialog_winui3|window_winui3|winui3_runtime|view_winui3)_windows\.cpp$',
         ).hasMatch(path),
       ),
+      shim.resolve(shimSource).toFilePath(),
     ];
 
     final flags = <String>[];
@@ -96,7 +106,7 @@ void main(List<String> args) async {
       name: 'cnativeapi',
       assetName: 'cnativeapi.dart',
       sources: sources,
-      includes: [src.toFilePath()],
+      includes: [src.toFilePath(), shim.toFilePath()],
       frameworks: frameworks,
       libraries: libraries,
       libraryDirectories: libraryDirectories,

bindings/dart/cnativeapi/lib/cnativeapi.dart

@@ -5,3 +5,4 @@
 library;
 
 export 'src/bindings_generated.dart';
+export 'src/event_loop.dart';

bindings/dart/cnativeapi/lib/src/event_loop.dart

@@ -0,0 +1,34 @@
+// Bindings for the event loop shim in src/event_loop.h, which the build hook
+// compiles into the same library as the core. Hand-written: ffigen only reads
+// the core's C API headers. The names follow the C ones, as in
+// bindings_generated.dart.
+
+// ignore_for_file: non_constant_identifier_names
+
+@ffi.DefaultAsset('package:cnativeapi/cnativeapi.dart')
+library;
+
+import 'dart:ffi' as ffi;
+
+/// Calls [entry] on the thread that becomes the UI thread, outside any
+/// isolate; the process ends when it returns. See src/event_loop.h.
+@ffi.Native<
+  ffi.Bool Function(ffi.Pointer<ffi.NativeFunction<ffi.Void Function()>>)
+>()
+external bool cnativeapi_run_ui_thread(
+  ffi.Pointer<ffi.NativeFunction<ffi.Void Function()>> entry,
+);
+
+/// Prepares the platform loop. Once, on the UI thread, before the first pump.
+@ffi.Native<ffi.Void Function()>()
+external void cnativeapi_start_event_loop();
+
+/// Dispatches pending platform events, waiting up to [timeout_ms] for one when
+/// there is none. Returns -1 to keep going, or the exit code to quit with.
+@ffi.Native<ffi.Int Function(ffi.Int)>()
+external int cnativeapi_pump_event_loop(int timeout_ms);
+
+/// Flushes stdio and ends the process with [exit_code], skipping atexit
+/// handlers and static destructors. See src/event_loop.h.
+@ffi.Native<ffi.Void Function(ffi.Int)>()
+external void cnativeapi_exit(int exit_code);

bindings/dart/cnativeapi/src/event_loop.h

@@ -0,0 +1,60 @@
+// Lets a plain Dart program (no Flutter) drive the platform event loop.
+//
+// Application::Run() blocks inside the platform loop, which would stall every
+// Dart timer, future and stream for the life of the app. Instead, runNativeApp()
+// in package:nativeapi calls cnativeapi_pump_event_loop() from a Dart timer:
+// each call dispatches what the platform has queued, waits a few milliseconds
+// for more, and returns, so the Dart event loop keeps turning in between.
+//
+// All of it runs in an isolate of its own on a thread of its own, because the
+// platform's UI objects belong to one thread and the Dart VM moves an isolate
+// between its worker threads as it pleases. cnativeapi_run_ui_thread() provides
+// that thread.
+#pragma once
+
+#include <stdbool.h>
+#include <stdint.h>
+
+#if _WIN32
+#define CNATIVEAPI_EXPORT __declspec(dllexport)
+#else
+#define CNATIVEAPI_EXPORT __attribute__((visibility("default")))
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// Calls `entry` on the thread that becomes the UI thread, outside any isolate,
+// so `entry` must be a NativeCallable.isolateGroupBound. The process ends when
+// `entry` returns. Returns false, calling nothing, if the thread could not be
+// had, or on a second call.
+//
+// - macOS: AppKit only works on the process's first thread, which the
+//   standalone Dart VM keeps parked in Dart_RunLoop() while main() runs on a
+//   worker. That thread is interrupted with a signal and `entry` runs from the
+//   handler, which never returns; the thread holds no lock at that point.
+//   Refused when called on the main thread already (a Flutter app).
+// - Windows, Linux: a new thread, declared the main thread to the core's
+//   dispatcher before `entry` runs. Nothing may have used nativeapi before.
+// - Android, iOS: always refused; the host app owns the UI thread.
+CNATIVEAPI_EXPORT bool cnativeapi_run_ui_thread(void (*entry)(void));
+
+// Prepares the platform loop: finishes launching and activates the app on
+// macOS. Call once, on the main thread, before the first pump.
+CNATIVEAPI_EXPORT void cnativeapi_start_event_loop(void);
+
+// Ends the process with `exit_code` after flushing stdio, without running
+// atexit handlers or static destructors: those race the Dart VM's threads,
+// which are still running. What the core would tear down (windows, tray icons)
+// goes with the process.
+CNATIVEAPI_EXPORT void cnativeapi_exit(int exit_code);
+
+// Dispatches every pending platform event; when there was none, first waits
+// up to `timeout_ms` for one. Returns -1 while the loop should keep running,
+// or the exit code once the platform asked to quit (WM_QUIT on Windows).
+CNATIVEAPI_EXPORT int cnativeapi_pump_event_loop(int timeout_ms);
+
+#ifdef __cplusplus
+}
+#endif

bindings/dart/cnativeapi/src/event_loop_linux.cpp

@@ -0,0 +1,59 @@
+#include "event_loop.h"
+
+#include <atomic>
+#include <cstdio>
+#include <cstdlib>
+#include <thread>
+
+#include <glib.h>
+
+#include "capi/application_c.h"
+#include "foundation/dispatcher.h"
+
+bool cnativeapi_run_ui_thread(void (*entry)(void)) {
+  static std::atomic<bool> started{false};
+  if (entry == nullptr || started.exchange(true)) {
+    return false;
+  }
+  // GTK belongs to the thread that initialises it: any thread can be the UI
+  // thread, as long as it stays the same one.
+  std::thread([entry] {
+    nativeapi::SetMainThread();
+    entry();
+    cnativeapi_exit(0);
+  }).detach();
+  return true;
+}
+
+void cnativeapi_start_event_loop(void) {
+  (void)native_application_is_running();
+}
+
+namespace {
+gboolean WakeUp(gpointer fired) {
+  *static_cast<bool*>(fired) = true;
+  return G_SOURCE_REMOVE;
+}
+}  // namespace
+
+int cnativeapi_pump_event_loop(int timeout_ms) {
+  // GTK dispatches everything, including RunOnMainThread() work, through the
+  // default main context.
+  if (!g_main_context_pending(nullptr)) {
+    bool fired = false;
+    guint timeout = g_timeout_add(static_cast<guint>(timeout_ms), WakeUp, &fired);
+    g_main_context_iteration(nullptr, TRUE);
+    if (!fired) {
+      g_source_remove(timeout);
+    }
+  }
+  while (g_main_context_iteration(nullptr, FALSE)) {
+  }
+  // Application::Quit() ends the process when the loop is not Run()'s own.
+  return -1;
+}
+
+void cnativeapi_exit(int exit_code) {
+  fflush(nullptr);
+  _Exit(exit_code);
+}