61 lines
3.1 KiB
Markdown
61 lines
3.1 KiB
Markdown
# 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
|
||
|
|
|
||
|
|
```sh
|
||
|
|
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.
|