Files
cesiumflutter/CLAUDE.md
T
2026-11-07 14:39:59 +01:00

3.1 KiB

CLAUDE.md

Flutter plugin (Linux desktop only) embedding a CesiumJS globe. 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 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, always run flutter build linux in example/.

Architecture

  • CesiumViewer (Dart) renders a black placeholder and reports its global rect after each paint (_RenderRectReporter) → setRect over the cesiumjs/webview method channel.
  • linux/cesiumjs_plugin.cc creates one WebKitWebView per viewer inside a GtkOverlay that holds the FlView; get-child-position places it at the reported rect. Methods: create, setRect, runJavaScript, openInspector, dispose, disposeAll (called once per isolate so hot restart doesn't leave orphan views). Events back to Dart: onMessage, onError.
  • JS → Dart: CesiumChannel.postMessage → window.webkit.messageHandlers.cesium. Messages are JSON with a type field → CesiumMessage.
  • HTML is generated in lib/src/cesium_html.dart and loaded with load_html + base URI https://cesium.localhost/; CesiumJS comes from jsDelivr (cesiumVersion). JS helpers cesiumViewer / cesiumLayers live on window.

Gotchas — do not regress

  • Overlay creation: the stock runner realizes the FlView (starting the engine's GL surface) before plugins register. A plain gtk_container_remove/add unrealizes it and Flutter fails with "Could not determine GL version". ensure_overlay() uses the deprecated gtk_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).
  • Flutter widgets cannot paint over the globe; use visible: false.
  • runJavaScript cannot return a Promise as the last expression; scripts that return nothing should end with undefined;.
  • Controller internals (attach, detach, handleMessage) are @internal.

Conventions

  • Never commit a Cesium ion token. The example reads CESIUM_ION_TOKEN via --dart-define-from-file=cesium_ion.json (git-ignored).
  • New controller features: add a Dart method in cesium_controller.dart that calls runJavaScript (JSON-encode string arguments with jsonEncode), plus a JS helper in cesium_html.dart if it is more than a few lines.
  • Update README.md API tables and CHANGELOG.md when the public API changes.