Files
cesiumflutter/CLAUDE.md
T

89 lines
4.9 KiB
Markdown
Raw Normal View History

2026-11-07 14:39:59 +01:00
# CLAUDE.md
2026-11-07 19:49:09 +01:00
Flutter **plugin** (Linux, Android, Windows) embedding a CesiumJS globe, and
a plain web page (`WebBrowserView`) in the same native web views. The
2026-11-07 14:39:59 +01:00
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
```sh
flutter pub get && flutter analyze && flutter test # package (root)
cd example && flutter build linux --debug # compiles the native plugin
2026-11-07 15:48:01 +01:00
cd example && flutter build apk --debug # compiles the Kotlin plugin
2026-11-07 14:39:59 +01:00
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
2026-11-07 15:48:01 +01:00
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`.
2026-11-07 14:39:59 +01:00
## Architecture
2026-11-07 15:48:01 +01:00
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).
2026-11-07 19:49:09 +01:00
- `NativeWebViewHost` (`native_web_view.dart`, internal) owns one native
view: renders a placeholder, reports its global rect after each paint
(`_RenderRectReporter`) → `setRect` over the `cesiumjs/webview` method
channel, and hides the view (desktop) when `visible` is false, tickers are
muted or its route isn't current (dialog/menu on top). `CesiumViewer` and
`WebBrowserView` are thin wrappers around it.
- `create` takes either `html` (Cesium page, served from the virtual origin)
or `url` (browser view: network page, links opening a window load in place
instead of going to the system browser, no black background).
2026-11-07 14:39:59 +01:00
- `linux/cesiumjs_plugin.cc` creates one `WebKitWebView` per viewer inside a
`GtkOverlay` that holds the `FlView`; `get-child-position` places it at the
2026-11-07 19:49:09 +01:00
reported rect. Methods: `create`, `setRect`, `runJavaScript`, `loadUrl`,
`reload`, `openInspector`, `dispose`, `disposeAll` (called once per isolate so hot
2026-11-07 14:39:59 +01:00
restart doesn't leave orphan views). Events back to Dart: `onMessage`,
`onError`.
2026-11-07 15:48:01 +01:00
- Android (`android/…/CesiumjsPlugin.kt`): `create` builds an
`android.webkit.WebView`; the widget then shows it with an `AndroidView`
(view type `cesiumjs/webview`, creation param `id`). `setRect` is 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 at `rect * scale` (Dart sends
`devicePixelRatio` as `scale`). Page served from `https://cesium.localhost/`
via `WebResourceRequested`. 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).
2026-11-07 14:39:59 +01:00
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).
2026-11-07 15:48:01 +01:00
- Linux/Windows: Flutter widgets cannot paint over the globe; use `visible: false`.
2026-11-07 14:39:59 +01:00
- `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.