Testing of the @doc-json output
docs: widget-leaflet extensions design
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+60
+60
docs/plans/2026-03-06-widget-leaflet-extensions-design.md
+60
docs/plans/2026-03-06-widget-leaflet-extensions-design.md
···
1
+
# Widget-Leaflet Extensions Design
2
+
3
+
## Goal
4
+
5
+
Extend the existing leaflet map widget adapter with bounding box drawing, image overlay, and marker support for the tessera geospatial classification workflow.
6
+
7
+
## Architecture
8
+
9
+
All changes are to the JS adapter code embedded in `widget_leaflet.ml`. No changes to the OCaml widget API — the existing `Widget.command` and handler system is sufficient. We add new command names and event types to the adapter.
10
+
11
+
## New Commands
12
+
13
+
### Bounding box drawing
14
+
15
+
- `enableBboxDraw` — enables rectangle drawing mode via mousedown/mousemove/mouseup
16
+
- User drags to draw a rectangle with visual feedback (dashed while dragging, solid green when complete)
17
+
- Drawing a new rectangle replaces the previous one
18
+
- New event `bbox_drawn` fires with `{south, west, north, east}` payload
19
+
20
+
### Image overlay
21
+
22
+
- `addImageOverlay` — takes `{url, bounds: [[south, west], [north, east]], opacity?}`. URL is typically a `data:image/png;base64,...` from tessera-viz-jsoo.
23
+
- `removeImageOverlay` — removes the current overlay
24
+
25
+
### Markers
26
+
27
+
- `addMarker` — takes `{lat, lng, label?, color?}`. Adds a circle marker at the location.
28
+
- `clearMarkers` — removes all markers
29
+
30
+
## Usage from OCaml
31
+
32
+
```ocaml
33
+
(* Enable bbox drawing *)
34
+
Widget.command ~id:"map" "enableBboxDraw" "";
35
+
36
+
(* Handle bbox drawn event *)
37
+
let on_bbox = function
38
+
| Some json -> (* parse {south, west, north, east} *)
39
+
| None -> ()
40
+
in
41
+
Widget.display_managed ~id:"map" ~kind:"leaflet-map" ~config ~handlers:[
42
+
"click", on_click;
43
+
"bbox_drawn", on_bbox;
44
+
]
45
+
46
+
(* Add image overlay *)
47
+
Widget.command ~id:"map" "addImageOverlay"
48
+
{|{"url":"data:image/png;base64,...","bounds":[[52.0,0.0],[52.1,0.2]]}|};
49
+
50
+
(* Add training point markers *)
51
+
Widget.command ~id:"map" "addMarker" {|{"lat":52.05,"lng":0.1,"color":"red"}|};
52
+
```
53
+
54
+
## Implementation approach
55
+
56
+
Custom lightweight rectangle drawing using Leaflet's built-in `L.rectangle` + mouse events (~30 lines JS). No Leaflet.draw plugin dependency — avoids the toolbar UI issues the Python version fights against.
57
+
58
+
## Testing
59
+
60
+
Playwright test with a standalone HTML page that embeds the adapter JS directly, exercises commands, and verifies DOM state.