this repo has no description
docs: tessera-geotessera-jsoo design
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+81
+81
docs/plans/2026-03-06-tessera-geotessera-jsoo-design.md
+81
docs/plans/2026-03-06-tessera-geotessera-jsoo-design.md
···
1
+
# tessera-geotessera-jsoo Design
2
+
3
+
## Goal
4
+
5
+
A thin js_of_ocaml wrapper that provides a browser-compatible synchronous HTTP fetch for `tessera-geotessera`, enabling tile fetching in the OCaml notebook's web worker context.
6
+
7
+
## Architecture
8
+
9
+
The core `tessera-geotessera` library is already parameterised over `fetch:(string -> string)`. This package provides:
10
+
11
+
1. A synchronous XHR-based `fetch` function (works in web workers)
12
+
2. A convenience `fetch_mosaic` that wires the XHR fetch into `Geotessera.fetch_mosaic_sync`
13
+
14
+
Everything else (`bbox`, `tile_coord`, `dequantize`, etc.) comes from the core `Geotessera` module.
15
+
16
+
## API
17
+
18
+
```ocaml
19
+
val fetch : string -> string
20
+
(** Synchronous HTTP GET via XMLHttpRequest. Raises on failure. *)
21
+
22
+
val fetch_mosaic : ?base_url:string -> ?version:string -> year:int ->
23
+
Geotessera.bbox -> Linalg.mat * int * int
24
+
(** Fetch and assemble tiles for a bounding box using browser XHR.
25
+
Convenience wrapper around Geotessera.fetch_mosaic_sync. *)
26
+
```
27
+
28
+
## Package Structure
29
+
30
+
```
31
+
tessera-geotessera-jsoo/
32
+
dune-project
33
+
tessera-geotessera-jsoo.opam
34
+
lib/
35
+
dune
36
+
geotessera_jsoo.ml
37
+
geotessera_jsoo.mli
38
+
test/
39
+
dune
40
+
test_browser.ml # compiled to JS
41
+
test_browser.html # loads the compiled JS
42
+
```
43
+
44
+
## Implementation
45
+
46
+
The `fetch` function uses `js_of_ocaml`'s `XmlHttpRequest` API:
47
+
- Create XHR, open synchronous GET, send
48
+
- Check status = 200, extract response as arraybuffer
49
+
- Convert arraybuffer to OCaml string via `Typed_array.String.of_arrayBuffer`
50
+
- Raise `Failure` on non-200 status
51
+
52
+
Follows the existing pattern from `js_top_worker/lib/jslib.ml` `sync_get`.
53
+
54
+
## Dependencies
55
+
56
+
- `tessera-geotessera` (core library)
57
+
- `js_of_ocaml` (XHR bindings)
58
+
- `js_of_ocaml-ppx` (preprocessor)
59
+
60
+
No Lwt dependency needed for the synchronous approach.
61
+
62
+
## Testing
63
+
64
+
Playwright-based browser testing:
65
+
66
+
1. **Test executable** — OCaml program compiled to JS via `(modes js)` that:
67
+
- Calls `Geotessera_jsoo.fetch` on a known geotessera URL
68
+
- Calls `Geotessera_jsoo.fetch_mosaic` on a small bbox
69
+
- Writes results (shape, values, pass/fail) to the DOM
70
+
71
+
2. **HTML harness** — minimal page that loads the compiled JS
72
+
73
+
3. **Playwright test** — navigates to page served locally, waits for results, asserts expected values
74
+
75
+
4. **Network** — hits dl2.geotessera.org directly (CORS enabled, no auth)
76
+
77
+
## Design Decisions
78
+
79
+
- **Synchronous XHR over async**: The notebook toplevel runs in a web worker where sync XHR is permitted. Avoids Lwt dependency and matches the existing `fetch_mosaic_sync` API. An async variant can be added later.
80
+
- **Raises on failure**: `fetch_mosaic_sync` expects `string -> string` (not option/result), so the fetch function raises on HTTP errors.
81
+
- **No re-export of Geotessera types**: Users `#require` both `tessera-geotessera` and `tessera-geotessera-jsoo`. The jsoo package only adds browser-specific functionality.