4.9 KiB
CLAUDE.md
Flutter plugin (Linux, Android, Windows) embedding a CesiumJS globe, and
a plain web page (WebBrowserView) in the same native web views. The
package is meant to be imported by other apps: keep the public API in
lib/cesiumjs.dart small and stable; everything else stays in lib/src/.
example/ is the test/demo app, not part of the package.
Commands
flutter pub get && flutter analyze && flutter test # package (root)
cd example && flutter build linux --debug # compiles the native plugin
cd example && flutter build apk --debug # compiles the Kotlin plugin
cd example && flutter run -d linux --dart-define-from-file=cesium_ion.json
Native build needs libwebkit2gtk-4.1-dev. Native code is only compiled
through the example app — after changing linux/cesiumjs_plugin.cc or
android/, always run the matching flutter build in example/.
windows/cesiumjs_plugin.cpp cannot be built from Linux (needs MSVC); it
compiles with /W4 /WX, so avoid unused parameters, shadowed names and
narrowing.
Android test emulator: AVD cesium_test (API 35, x86_64), lives in
~/.config/.android/avd → start with
ANDROID_AVD_HOME=~/.config/.android/avd ~/Android/Sdk/emulator/emulator -avd cesium_test.
Architecture
All platforms share the cesiumjs/webview channel protocol (create
eagerly builds the web view keyed by a Dart id; other calls address it by id).
NativeWebViewHost(native_web_view.dart, internal) owns one native view: renders a placeholder, reports its global rect after each paint (_RenderRectReporter) →setRectover thecesiumjs/webviewmethod channel, and hides the view (desktop) whenvisibleis false, tickers are muted or its route isn't current (dialog/menu on top).CesiumViewerandWebBrowserVieware thin wrappers around it.createtakes eitherhtml(Cesium page, served from the virtual origin) orurl(browser view: network page, links opening a window load in place instead of going to the system browser, no black background).linux/cesiumjs_plugin.cccreates oneWebKitWebViewper viewer inside aGtkOverlaythat holds theFlView;get-child-positionplaces it at the reported rect. Methods:create,setRect,runJavaScript,loadUrl,reload,openInspector,dispose,disposeAll(called once per isolate so hot restart doesn't leave orphan views). Events back to Dart:onMessage,onError.- Android (
android/…/CesiumjsPlugin.kt):createbuilds anandroid.webkit.WebView; the widget then shows it with anAndroidView(view typecesiumjs/webview, creation paramid).setRectis a no-op. Flutter widgets can paint over the globe here. - Windows (
windows/cesiumjs_plugin.cpp): WebView2 in a host child window, sibling of the Flutter view, placed atrect * scale(Dart sendsdevicePixelRatioasscale). Page served fromhttps://cesium.localhost/viaWebResourceRequested. WebView2 SDK downloaded from NuGet by CMake. - JS → Dart:
CesiumChannel.postMessage→window.webkit.messageHandlers.cesium(Linux),window.CesiumAndroid.postMessage(Android),window.chrome.webview.postMessage(Windows). Messages are JSON with atypefield →CesiumMessage. - HTML is generated in
lib/src/cesium_html.dartand loaded withload_html+ base URIhttps://cesium.localhost/; CesiumJS comes from jsDelivr (cesiumVersion). JS helperscesiumViewer/cesiumLayerslive onwindow.
Gotchas — do not regress
- Overlay creation: the stock runner realizes the
FlView(starting the engine's GL surface) before plugins register. A plaingtk_container_remove/addunrealizes it and Flutter fails with "Could not determine GL version".ensure_overlay()uses the deprecatedgtk_widget_reparent()via a temporary realized window to keep it realized. on_view_realize→gdk_window_ensure_native()must stay: without a native child window, GTK3 composites WebKit with the FlView GL surface and only ~0.2 frames/s reach the screen (Cesium's own FPS counter still says 60 — measure presented frames with ffmpeg x11grab + mpdecimate instead).- Linux/Windows: Flutter widgets cannot paint over the globe; use
visible: false. runJavaScriptcannot return a Promise as the last expression; scripts that return nothing should end withundefined;.- Controller internals (
attach,detach,handleMessage) are@internal.
Conventions
- Never commit a Cesium ion token. The example reads
CESIUM_ION_TOKENvia--dart-define-from-file=cesium_ion.json(git-ignored). - New controller features: add a Dart method in
cesium_controller.dartthat callsrunJavaScript(JSON-encode string arguments withjsonEncode), plus a JS helper incesium_html.dartif it is more than a few lines. - Update
README.mdAPI tables andCHANGELOG.mdwhen the public API changes.