Skip to content

The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.

JavaScript

Open KML, KMZ, GeoJSON and GPX layers, and turn or crop proof images (#82)

OsintMeThat240f26009d58
diff --git a/docs/IMAGERY_PROVIDERS.md b/docs/IMAGERY_PROVIDERS.md
index 5b7c031..946c9ca 100644
--- a/docs/IMAGERY_PROVIDERS.md
+++ b/docs/IMAGERY_PROVIDERS.md
@@ -413,20 +413,32 @@ That is also one request where tiles would be a dozen.
Every published release of World Imagery stays online under its own number
(`engine/wayback.py`). Same imagery, same terms and same attribution as the
default basemap, and no key. Three services, all asked only after the analyst
-picks the basemap or opens its picker:
+picks the basemap or opens its picker — and the walk follows the map from that
+first open, so an analyst reading a place through time never reads the history
+of where they were before:
| Service | What it answers | Notes |
|---|---|---|
| `waybackconfig.json` (S3) | every release: number, title with its date, metadata service | read once per 6 h; numbers are not in date order, so the date sorts. Only metadata services on `metadata.maptiles.arcgis.com` are followed |
-| `MapServer/tilemap/{release}/{z}/{row}/{col}` | `select`: the release that tile was really published in | walking it backwards from the newest lists a point's changes, one small request per change |
+| `MapServer/tilemap/{release}/{z}/{row}/{col}` | `select`: the release that tile was really published in | walking it backwards from the newest shortlists a point's changes, one small request per candidate |
+| `WMTS/.../tile/{release}/{z}/{y}/{x}` | the pixels themselves | one tile per candidate, read 8 at a time, to settle the shortlist |
| `World_Imagery_Metadata_*/MapServer/{layer}/query` | `SRC_DATE2` (epoch ms), provider, satellite | layer = 23 − zoom, capped at 13. Slow, a couple of seconds each, so a walk asks up to 12 at once |
-What the tilemap calls a change is a change of bytes. Esri republishes pictures
-often, so two filters run over the walk, both keeping the older release: equal
-tile sizes are compared by hash, and neighbours stating the same acquisition day
-and satellite are one picture (observed 2026-09 in Mariupol: three releases over
-one GE01 acquisition of 2023-10-04, re-coloured). A tile or a metadata answer
-that cannot be read is an unknown and never merges anything.
+What the tilemap calls a change is a change of bytes, and Esri republishes a
+picture far more often than the ground under it moves. So the pixels settle it:
+each candidate's tile is reduced to a 32×32 grey thumbnail and standardised, so
+a re-encoding or a new colour balance over one acquisition compares equal to it,
+and two releases are one picture when under 0.5% of the thumbnail differs by
+more than 0.7 of the tile's own spread. Measured against re-encoding, sharpening
+and a hard gamma, none of which reaches half of that, and a roof an eighth of
+the tile across, which passes it three times over. The metadata then merges what
+is left: neighbours stating the same acquisition day and satellite are one
+picture (observed 2026-09 in Mariupol: three releases over one GE01 acquisition
+of 2023-10-04, re-coloured). Both filters keep the older release, and a tile or
+a metadata answer that cannot be read is an unknown that never merges anything.
+
+The walk runs at the view zoom, so what counts as a change scales with it: at
+z19 a tile is some 75 m across and the smallest change seen is a few metres.
A tile asked of a release it did not change answers `301` to the release that
did; the proxy follows it and caches under the release asked for. The variant id
diff --git a/docs/ONTOLOGY.md b/docs/ONTOLOGY.md
index e490765..1cb8dce 100644
--- a/docs/ONTOLOGY.md
+++ b/docs/ONTOLOGY.md
@@ -184,6 +184,7 @@ answer by omission (`tests/test_entities.py`).
| `post` | document | deliverable | ✅ | post-composer | `draft` (json) | yes |
| `inspect-session` | document | annex | ✅ | inspect | `spec` (json) | yes |
| `compare-session` | document | annex | ✅ | compare | `spec` (json) | yes |
+| `map-layer` | document | annex | ✅ | map layers | `spec` (json), `format`, `source_url?` | yes (spec + snapshot + icons) |
| `note` | document | annex | ✅ | notebook | `path`, `folder?` | yes (Markdown) |
| `sheet` | document | annex | ✅ | sheet | `path` (csv) | yes (CSV + sidecar) |
| `bookmark` | document | attestation | ✅ | capture extension | `url`, `fetched_at?`, `archive_url?`, `reliability?` | no (a URL) |
@@ -213,6 +214,14 @@ Three modelling calls the table alone does not show:
minting the day a value turns up without its object.
- **`registration` and `icao24` belong to an airframe; a callsign belongs to a
flight**, which is a dated statement rather than an attribute.
+- **A `map-layer` is a source the case consults, not a source it quotes.** It is
+ `annex` beside `note` and `sheet` rather than `attestation`, because an
+ attestation folds into the edge carrying its provenance and a layer that nothing
+ links to would fold into nothing. Its `source` is a path *or* a URL, which is
+ what makes a dropped KMZ and a followed My Maps one type instead of two. Its
+ features never enter the graph: they are what somebody else claims, and the day
+ one of them becomes a `place` of this case (SPEC §6) the layer is what that
+ place cites — which is the reason it is an entity at all.
Retired: `event` (replaced by the claim node), `alias` (see above), and `panorama`
(Inspect's auto-stitch export is a derived `media`). Still coming from the roadmap,
@@ -786,7 +795,10 @@ subject removes it transitively.
(`satellite.placements`, `GET /entities/{id}/placement`): a video reaches its
capture three hops away, through the proof that composed a frame of it. Only
`capture` and `proof` carry a point, and **the artifact carrying one ends the
- walk**. Points deduplicate on the exact pair, never a rounded one, and the nearest
+ walk**. It **only crosses material** — media, capture, proof
+ (`satellite.PLACEMENT_THROUGH`). A document that collects files is reached and
+ goes no further: a post publishing two clips joined them end to end, and each
+ landed on the other's geolocation. Points deduplicate on the exact pair, never a rounded one, and the nearest
hop wins a repeat. A proof reports every point it states, so the footage behind a
three-point proof answers for all three. Bounded at four hops, 200 entities read
and 15 points reported, each with the entity it was read off; a `capture` reports
@@ -889,8 +901,11 @@ the moment somebody commits to it. That moment is the proof.
can delete. Its **material** is the narrower question — a media reaching a place is
one claim among several about that file — so only the two roads that pose a proof's
point are restated there (`satellite.POINT_ROADS`), and an edge stated by hand in
- Details or proposed by import enrichment stays. A point another proof still
- concludes on keeps its material. A place the proof let go of that nothing else
+ Details or proposed by import enrichment stays. The material is reconciled by
+ difference too, **read off the place rather than off the chain**
+ (`satellite._sweep_point`): a proof re-composed on another clip keeps its point, so
+ nothing withdraws it, and walking what the proof rests on now never reaches the clip
+ it dropped. A point another proof still concludes on keeps its material. A place the proof let go of that nothing else
holds is **offered for deletion, never swept**: it is on the map, and dropping it
is the analyst's call.
- **The material the proof composes states the same point**, over the derivation
diff --git a/docs/SPEC.md b/docs/SPEC.md
index 7e60427..8730cd2 100644
--- a/docs/SPEC.md
+++ b/docs/SPEC.md
@@ -61,6 +61,7 @@ azimut/ # everything Azimut owns; the rest of the folder is yours
.compare/ # saved Compare session specs
.analysis/ # Detect areas, watches, runs and the frames behind their results
.search/ # saved Grid Search state
+ .layers/ # added map layers: spec + source as received + its icons; .cache/ is derived
.trash/ # recoverable artifact payloads, in numbered slots
```
@@ -155,6 +156,7 @@ proof for publication.
| ✅ **Imported proofs** | Turns a published post into a composed proof: every picture a panel, its text read for a position, the addresses it points at fetched as material, and nothing filed before the preview is approved. |
| ✅ **Import origin** | States one origin for a whole import, offers it to a batch that landed without one, and corrects any file later from Details. |
| ✅ **Drawing on a proof** | Stamps a fixed set of marks, fills boxes and ellipses at a chosen opacity, keeps every shape tool in hand, and recolours, restyles, nudges, drags or deletes a picked family at once. |
+| ✅ **Proof image transforms** | Turns or crops a panel or proof-owned overlay without changing its source, while keeping attached annotations on the same pixels. |
| ✅ **A proof of several points** | States every place a proof argues — each panel's own included, none of them overwritten — optionally named, one of them the camera's, any of them moved on a map rather than typed; files them as places under one title and carries them into the tweet and onto the exported picture. |
| ✅ **What a proof says about itself** | Carries an optional sentence, which is its notes and what a post is written from, and an optional date for when its material was taken — never pre-filled, cleared in one press, and shown on the Timeline. |
| ✅ **A date that reaches the footage** | A dated proof states that date for the sources it rests on — the original, never the frame cut from it or a capture — as one cited statement per proof, restated on every save and never written over the file's own clock. |
@@ -168,6 +170,7 @@ proof for publication.
| ✅ **Point menu** | Right-clicking the ground copies that point in every format, looks it up, saves, measures, reads the sky or opens its imagery history from it, and links it out. |
| ✅ **Map windows** | Opens the map in several tabs with the view in the URL, links map tabs and extension panels on other sites to one camera, and syncs saved points, grids and sweeps live to every tab and extension panel. |
| ✅ **Map layers** | Stacks key-less overlays (borders, roads, railways, power lines, sea marks, GPS traces), NASA FIRMS fires and VIIRS night lights for a chosen day, and filters drawn pins by kind and folder. |
+| ✅ **Added map layers** | Opens a KML, KMZ, GeoJSON or GPX file, or follows a public My Maps or map URL refreshed only while enabled, and draws it with its own colours, optionally its own icons composed once at import, a legend that filters and a search that goes to one feature — read, cited and never adopted into the case. |
| ✅ **Media on the map** | Draws the case's located photos and videos where a relation, a GPS reading or a proof puts them, opens the Map panel, the home map and the extension on them, and plays the stack in the panel beside the imagery. |
| ✅ **Imagery Wayback** | Browses every Esri World Imagery release, narrowed to the ones that changed the point, and dates the pixels apart from the release. |
| ✅ **Satellite Compare** | Aligns and annotates two dated views, assists matched-product change reading, saves editable sessions and files or exports attributed PNG/GIF outputs. |
@@ -199,7 +202,7 @@ Each version delivers one complete daily workflow. Firm ideas move here from
| **Capture graticule** | The rest of what a plate states about itself: a latitude/longitude grid over app and extension captures, beside the scale bar and north arrow that already ship. |
| **Image Compare** | Overlay two images with opacity, swipe and pixel diff. Assist satellite-to-screen alignment without presenting a verdict. |
| **Georeferenced overlay** | Pins an image to the ground by three or four matching points: a commercial satellite shot from a post, a drone frame, an old plan. It draws under the map's own marks with an opacity slider, reprojects as the map pans, and is saved in the case with its control points so the fit can be checked. |
-| **Subscribed map layers** | Follows a public My Maps, KML/KMZ or GeoJSON URL and refreshes it automatically only while enabled, while keeping the last snapshot available offline and never rewriting evidence already saved from it. Local KML/KMZ, GeoJSON and GPX files open as fixed case layers. |
+| **Adopt a feature** | Turns a feature of an added layer into a `place` of the case, carrying the layer and the feature it came from as provenance. |
| **GeoConfirmed layer** | Queries GeoConfirmed for a chosen conflict, date or viewport only when enabled, opens each event's original sources and lets selected events enter the case. |
| **Source directory** | Keeps the accounts, channels and pages worth following for this case, searchable by platform, area and topic, with notes and source reliability; monitoring remains a later opt-in workflow. |
| **Metadata follow-up** | Explains which common image/video fields were stripped and proposes events from capture times. |
@@ -402,7 +405,33 @@ stops making sense.
link-local address on the first hop and on every redirect; a hostname that
resolves to one is not looked up to find out, and what such a hop could learn is
"this port answered" and never a body. An imported workbook is bounded on its
- compressed bytes and on the size its own directory declares once unzipped. The map's search bar answers from
+ compressed bytes and on the size its own directory declares once unzipped. An
+ added map layer is the second untrusted archive and the first untrusted XML: a
+ KML is parsed by `defusedxml`, which refuses an external entity and an expansion
+ bomb, under bounds on size, feature count and nesting depth, and a KMZ is a zip
+ checked for an escaping member name, its uncompressed total and its compression
+ ratio before a byte of it is read. The browser never sees any of it — it is
+ handed the parsed GeoJSON, with every description stripped of markup at the
+ boundary rather than rendered. A layer's own icons are the one thing it can ask
+ a third-party host for, on an explicit tick at import and never afterwards, and
+ the accepted risk is bounded on both ends: what goes out is a per-image GET
+ under a count, a size and a total cap, and what comes back is decoded, tinted,
+ resized and **re-encoded here**, so an SVG carrying a script, a file pretending
+ to be a PNG and a thumbnail that unpacks into a gigabyte are one refusal rather
+ than three checks. The browser only ever loads PNGs this process produced, from
+ localhost, keyed by content hash. Following a public Google My Maps uses
+ `google.com/maps/d/kml?mid=…`, the KMZ rather than the `forcekml=1` conversion
+ beside it: both carry the same placemarks, but the archive bundles the
+ creator's actual icons as members of itself, while the conversion throws the
+ pictograms away and points every style at one of three blank Google
+ containers. It is undocumented, and is an
+ accepted risk recorded here rather than one taken silently: SPEC §2 refuses the
+ unofficial key-less endpoints of keyed services (the `mt1.google.com` case), and
+ the distinction drawn is that this is the sharing mechanism the map's own
+ creator switched on, not a way around a quota. It is fetched only when the
+ analyst subscribes, presses Refresh, or opens a case holding an enabled layer
+ that asked to be re-read; a shape it stops answering in fails with a sentence
+ rather than drawing nothing. The map's search bar answers from
a bundled gazetteer and never reaches out on a keystroke; its geocoder layer
waits for a pause, and a request the one-per-second pace cannot take is dropped
rather than queued. Two things reach out on mount and no
diff --git a/docs/UI.md b/docs/UI.md
index 025fd55..1890876 100644
--- a/docs/UI.md
+++ b/docs/UI.md
@@ -1188,8 +1188,11 @@ remote ids in provenance instead of appending them to the visible name.
slots and loads tiles only after a source or a starting pair is chosen. Each
side keeps its provider, Wayback release, Sentinel-2 day and reference layers.
The source cards and mode controls use the application's shared theme, buttons
-and spacing. Both Layers buttons open the same A/B sheet, including each side's
-FIRMS period, VIIRS night and saved case work.
+and spacing. On a card the date is a chip beside the provider, reading the same
+for Wayback and for Sentinel-2, so the card's layers icon means one thing. The
+cards are as wide as the maps under them, so the split between A and B is one
+line down the tool. Both Layers buttons open the same A/B sheet, including each
+side's FIRMS period, VIIRS night and saved case work.
The mode dock holds two kinds of choice, separated by a rule. Left of it, how the
pair is *read*: side by side, through a swipe, with B faded over A, or as
@@ -1291,11 +1294,13 @@ scenes rather than synthetic ones: rough sea under glint, a dense anchorage unde
cumulus, oil fires and wildfires, bright roofs, a construction site across seven
months, dry-season pastures. Vessels stand out from their own patch of sea in near
*and* short-wave infrared, which a breaking wave does not, and a candidate joined to
-bulk land is a coast. Fires take the published short-wave ratios on B8A, which
+bulk land is a coast. What counts as sea comes from the water index or from the
+classification, either one is enough: under sun glint the index alone read a whole
+strait as dry. Fires take the published short-wave ratios on B8A, which
shares B12's grid. Construction is ground that moved the same way in every band
while its vegetation held; a small spot changed while the ring of ground around it
did not, that ring read with a hole in its middle so the spot cannot sit in its own
-background; a burn has to end dark, which a dried pasture does not.
+background and over measured ground only, so a granule edge raises nothing; a burn has to end dark, which a dried pasture does not.
**Small**, **Medium**, **Large** and **All** under the analyzer set the target
size as a whole: floor and ceiling area, cleanup and grouping together, since a
@@ -1367,10 +1372,12 @@ offers for its own rails are left out rather than shown dead.
updates its rendered media preview in My work (PNG, or GIF for blink). A preview
used by a derived proof is preserved when a later save creates new pixels.
**Open** restores the sources, layers, camera, reading mode, blink speed, detection
-settings and annotations; Detect is a place to work rather than a way to read the
-pair, so a session saved from it reopens side by side and its runs stay in the case. Export writes an attributed PNG, blink GIF or divider-sweep GIF
-to the shared Views destination; Copy current PNG uses the clipboard. Exports
-include projected annotations, a scale bar and north arrow. Tile captures wait
+settings, annotations and the optional export frame; Detect is a place to work rather
+than a way to read the pair, so a session saved from it reopens side by side and its runs
+stay in the case. Export writes an attributed PNG, blink GIF or divider-sweep GIF to the
+shared Views destination; an optional ground-anchored frame cuts any of the three to the
+chosen area, while Full view remains the default. Copy current PNG uses the clipboard.
+Exports include projected annotations, a scale bar and north arrow. Tile captures wait
for loaded frames and reject incomplete tiles. Google Maps JS uses the
user-triggered Azimut Capture extension and retains its on-map credits.
@@ -1385,8 +1392,18 @@ nothing parses or geocodes the raw text the way the plain box always did. A city
lands at zoom 12 and a street at 15; a saved item reopens at its own view and
bearing. Picks are remembered locally and offered back when the bar is empty.
+**The right-hand panel has two halves, and one tab strip across its top.**
+**Layers** is what is drawn over the imagery; **Saved** is what the case holds.
+They used to be one scroll, with a list of external maps wedged between them and
+a header that named only the third of the three. It opens on **Layers**, because
+that is what this panel is for on the surface it is docked to: the case's own
+work is also reachable from the sidebar and the Board, while what is switched on
+over the imagery is reachable from nowhere else. Each section states its own
+count, so the strip carries none — folded shut, the panel shows the active half's
+name and its number.
+
Saved work — places, captures and screenshots filed by the extension — lives in
-one right-hand **Saved** panel, grouped by geography rather than by date. The
+the **Saved** half, grouped by geography rather than by date. The
tree's depth follows the case: one country opens straight on its regions, a
worldwide case opens on continents. A filter and a `Media / Places / Captures`
switch stay pinned above it; a screenshot counts as a capture. The panel opens on
@@ -1402,7 +1419,8 @@ that place wears a dot and a count instead.
carries no coordinates of its own, so the position is read off the graph, by
every road that states it: a `located-at` or `depicts` edge to a place, the point
enrichment proposed from the file's own GPS, and the derivation chain, which puts
-a video where the proof that composed a frame of it stands. A file recorded on a
+a video where the proof that composed a frame of it stands. That chain runs
+through material only: two clips published in one post keep their own points. A file recorded on a
roof and showing the street below is a row at each, and roads that agree on a
point are one row that names them all (`Recorded here · Shows this place · Via
Roofline`). A file nothing places is not listed, and neither is anything the case
@@ -1481,13 +1499,19 @@ which it is (`lib/map/tools.js`) rather than adding a button somewhere.
railways, power lines, sea marks, GPS traces, active fires, night lights, the
case's saved work, and the points another tool handed over (a sheet's
coordinate column, a Timeline window). None of them changes what the
- pointer does, so none takes a rail seat: they are a list in the Saved panel,
- each with its own switch. A handoff appears in the list when it arrives and
- leaves when it is closed, and keeps a Close beside its switch, since hiding a
- layer and being done with it are two different things. A layer that is a
- question answers it under its own switch rather than in a card floating over
- the map: a fixed handful of answers as a row of chips under its own label, an
- open-ended one — the folders the analyst named — as a list.
+ pointer does, so none takes a rail seat: they are a list in the panel beside
+ the map, each with its own switch. A handoff appears in the list when it
+ arrives and leaves when it is closed, and keeps a Close beside its switch,
+ since hiding a layer and being done with it are two different things. A layer
+ that is a question answers it under its own switch rather than in a card
+ floating over the map: a fixed handful of answers as a row of chips under its
+ own label, an open-ended one — the folders the analyst named — as a list.
+- **Added layers** — a second section under that list, with its own `+ Add a
+ layer`. The line between the two is *who chose it*: the stack above is the
+ app's, this one is the analyst's. A row here carries four things a curated row
+ has no use for — where it came from, how fresh what is drawn actually is, a
+ legend that filters, and Refresh, Reveal file and Remove. See
+ **Added map layers** below.
- **The picture** — the provider, the Sentinel-2 layer and date, when the pixels
were taken, the eco and usage pills, and the compass — belongs to the
*surface*, in its own top-right corner. Which imagery is on screen is a
@@ -1543,6 +1567,77 @@ yesterday, since today's pass is still being processed. It sits lowest in the
stack, slightly see-through so the lit street can be named, and the row says
that cloud hides lights too.
+**Added map layers** are somebody else's map over this one: a KML, KMZ, GeoJSON
+or GPX file opened from the computer, or a public My Maps or map URL followed.
+Both land in the same section, because the question the row answers is who put
+this on my map. **A layer is drawn and never adopted** — clicking a feature opens
+what the source says about it, its name, its group and its description, with
+nothing to confirm and no way from there into the case. A description written as
+columns is drawn as columns, one label and its value per row, because a My Maps
+keeps its fields in a table and a table flattened into a paragraph is unreadable.
+Addresses in it are links, and they open in a new tab: a feature sourced from a
+post is read by opening the post.
+
+The row states five things:
+
+- **Where it came from** — the filename, the host, or Google My Maps. A followed
+ map is a page somebody publishes, so this is a link to it: the one thing on the
+ row that leaves the app, and it leaves on a click.
+- **How fresh what is drawn is.** A file says when it was opened and nothing
+ more: it is exactly what was dropped in. A followed map says when it was last
+ read, and says *stale* when that was long enough ago to matter — before the
+ marks are read, not after.
+- **Both counts.** `3 200 features · 412 shown` whenever a group is switched
+ off. The number drawn never passes for the number loaded.
+- **Its legend, which is the filter.** One row per group with its colour and its
+ count; clicking one hides exactly those features and keeps them loaded. A KML's
+ groups are its folders, which is how a My Maps is built; a GPX's are waypoints,
+ tracks and routes; a GeoJSON states none, so the file is one group named after
+ itself rather than a grouping guessed out of whichever property looked like one.
+- **A search, in the legend's own slot.** Typing puts the matches where the
+ groups were, and the two are never on screen at once: the legend is the filter
+ the case keeps, the search is a way of looking that leaves nothing behind. The
+ counts above it do not move while somebody types. Names and groups are read,
+ never descriptions, which on a layer of a hundred thousand features would be
+ the most expensive thing in the app for a gain nobody asked for. Picking a
+ match takes the map to that feature and opens the card a click on it opens. A
+ match from a group that is switched off is listed all the same, marked, and
+ going there switches it back on. The box is offered while the layer is drawn;
+ one that is switched off has nowhere to send anybody.
+
+**The source's own colours are always honoured; its icons are, if asked.** The
+add dialog carries one tick per half, *Use the map's own icons* — off for a file,
+on for a followed address, which is the same line the rest of the app draws:
+following a pasted link already reaches the network, opening a file off this
+machine does not. It is asked there and not on the row because there is the
+moment the request would be made.
+
+Ticked, each distinct icon is read once — out of the KMZ, or off the web by the
+backend — tinted the colour its style asked for, held to one size **measured on
+what is painted rather than on the image around it**, and stored in the case.
+What the map loads is a picture from this machine; **the browser never asks the
+source's host for anything.** A My Maps draws in its creator's own pictograms,
+and it draws offline, and it draws the same after a bundle import; a followed My
+Maps carries its icons inside the file it is fetched as, so most of them cost no
+request at all.
+
+Unticked, or when an icon cannot be read, the pictogram is the app's own: a pin,
+a line or an area, each with a **white edge**, since a colour picked against
+somebody else's basemap has no reason to read against this case's imagery. That
+is also the fallback, per icon rather than per layer — one image that will not
+load costs its own marks their picture and nothing else, so there is no switch to
+find when something looks wrong. Nothing in the
+layer is labelled on the map; a feature's name is in the hover and in the card.
+Far out, where the marks would be a solid mat, the map keeps only those that fit
+and draws the rest as dots, so a dense layer never looks emptier than it is.
+
+**Refresh, Reveal file and Remove** sit under the row. A followed map is re-read
+when it is added, when Refresh is pressed, and when a case opens holding it
+enabled — never on a timer, and never while it is switched off. A read that finds
+nothing new rewrites nothing, a read that fails leaves the last copy on the map,
+and the copy the layer was drawn from is kept in the case, so it draws offline and
+travels in the bundle. Removing a layer takes that copy with it, to the trash.
+
A date is picked from a calendar the app draws, in the panel rather than over
it. The browser's own opens at its own size, in its own locale, and half
outside a panel docked to this edge — and a field reading `12/09/2026` in an app
@@ -1614,20 +1709,30 @@ holds something Save has not taken, since the panel opens on what the case holds
**Esri Wayback is a basemap of every World Imagery release.** Picking it puts a
chip beside the provider naming the release on screen, and the chip opens a
slider through time, oldest left, with a step either way and the list under it.
-The list opens on **Changes here**: only the releases that brought a new picture
-of the tile under the crosshair. Esri's tilemap says which release a tile really
-comes from, and walking it backwards finds each change; a picture Esri published
-again, re-encoded or re-coloured, is folded into its first publication by
-comparing the tile's bytes and the acquisition date and satellite its metadata
-states. Each row carries its release date and, beside it, when the picture was
-taken; the pill under the chip dates the pixels on screen the same way. Narrowed
-to changes, the newest release is named by the change it shows rather than by a
-date no row carries. **Every release** lists all of them, where neighbours
-often look identical because nothing changed there. The history is read when the
-picker opens, takes some seconds (Esri's metadata service is slow), and is read
-again once the map settles in another tile; until it arrives, and when it
-fails, every release stays on offer. The release rides on the provider id
-(`esri-wayback~64776`), so tiles are cached and captures credited under it.
+The list opens on **Changes here**, and so does the slider: only the releases
+that brought a new picture of the tile under the crosshair. Esri's tilemap says
+which release a tile really comes from, and walking it backwards shortlists the
+candidates; a picture Esri published again, re-encoded or re-coloured, is folded
+into its first publication by comparing the tiles themselves, then the
+acquisition date and satellite their metadata states. Each row carries its
+release date and, beside it, when the picture was taken; the pill under the chip
+dates the pixels on screen the same way. Narrowed to changes, the newest release
+is named by the change it shows rather than by a date no row carries. **Every
+release** lists all of them, where neighbours often look identical because
+nothing changed there.
+
+**Opening the picker once makes the history follow the map.** Every view that
+settles over another tile reads that tile's history from then on, picker open or
+shut — gating that on the picker *staying* open was the bug behind a picker that
+re-opened on wherever the analyst had been before. A tile already read costs
+nothing, and a tile Esri refused is left alone until **Refresh** is pressed, so
+panning never hammers a service that is down. A first history takes some seconds
+(Esri's metadata service is slow) and the picker offers nothing while it comes,
+since every release is not what *Changes here* was asked for; the changes it
+already has stay on the slider while the next tile's are read. A history that
+fails falls back to every release, which is the honest answer to not knowing.
+The release rides on the provider id (`esri-wayback~64776`), so tiles are cached
+and captures credited under it.
**Right-click the ground** and a menu acts on that point rather than on the
centre: copy it in every coordinate format, the analyst's own first; ask what
@@ -1638,6 +1743,20 @@ its own (a search-grid cell) stays that shape's. The menu flips away from the
map's edges, walks with the arrow keys, and closes on Escape, a press outside,
or a zoom that moves the ground from under it.
+**Open in…** is the one row that opens a list, and it opens it *beside* the
+menu. A list unfolding inside would make the menu taller, and a menu already
+placed against the frame's edge answers that by moving — which slides the next
+row out from under the cursor that was about to press it. So the menu is placed
+once, from its measured size, and never again: the submenu flies out to the
+right (to the left where that would leave the map), pushed up rather than clipped
+when the row it hangs from is near the bottom, and anything else arriving late —
+the answer to *What is here?* — scrolls inside a menu that stays put. `→` opens
+it, `←` closes it, Escape leaves the submenu before it leaves the menu.
+
+Those external maps are **only** here. They used to be listed in the panel as
+well, at the map's centre; the same list on the point you actually clicked is
+strictly better, and two of them was the same thing said twice.
+
**The map opens in as many tabs as there are screens.** `⧉` beside the title
opens this map again in a tab of its own, on the view it is showing — a tab
rather than a pop-up window, because a tab can be torn onto the second screen
@@ -1784,6 +1903,24 @@ shape never reshuffles the buttons above them.
thickness, drawn inset so the layout does not shift. A frame is decoration: it
stays out of the legend, which is still built from annotation colours alone.
+**Panel and overlay transforms.** Selecting either image shows a round knob on a
+short stem above it — the one Collage turns its pieces by — for a free turn, with
+quarter turns as gentle snap points. The turn is carried by the image rather than
+burnt into its pixels, so the selection frame, the crop marks, the border and the
+annotations all stay on the picture's own edges however far it comes round, and
+turning one never resizes it: the page reserves the upright room the turned
+picture needs.
+
+A double-click enters crop mode on the canvas itself: eight black edge and corner
+marks frame the kept pixels, as in a slide editor, over the whole source shown
+shaded outside them — so an earlier crop is there to be taken back, not only
+undone. The crop button in the image row opens the same mode, and closes it. The
+marks pull both ways until you leave crop mode, so a corner taken too far comes
+back in the same pass; clicking off the image, that button again, or saving keeps
+the box, and Escape drops it. The source file stays untouched: the proof stores
+the crop rectangle and the angle, and the export draws through them. Reset crop
+restores the full source while preserving the turn.
+
**Drawing.** A tool in hand holds the canvas alone. Nothing already drawn answers
the pointer, so a stroke started inside a box draws a new element instead of
dragging the old one, and while the tool is held the colour and width you pick set
diff --git a/extension/README.md b/extension/README.md
index 33c3bcb..6f44176 100644
--- a/extension/README.md
+++ b/extension/README.md
@@ -299,6 +299,9 @@ The filling runs in the page's own world, which is the only place a composer
accepts what it is given. That needs Firefox 128 or later; on an older Firefox
this one flow reports that it could not run, and everything else works as before.
+Attachments cross from the local case in small pieces. Videos can therefore
+reach the app's 512 MB hand-off ceiling without one oversized browser message.
+
If the site has changed its markup, or a file is too large to hand over, it
fills what it can and says so. Each post is read back after it is typed, and one
the composer will not take cleanly is left empty rather than half-written. The
diff --git a/extension/background.js b/extension/background.js
index 49c39b8..8f271dd 100644
--- a/extension/background.js
+++ b/extension/background.js
@@ -104,33 +104,56 @@ async function ingest(blob, meta) {
// would be two answers to one question, and the pair that disagrees is the one
// nobody can find.
-/** What a thread's attachment may weigh.
+/**
+ * Put one case attachment into the composer page a slice at a time.
*
- * Lower than the app's own ceiling, and the one place in this file that keeps a
- * size of its own rather than repeating the app's. It is a different limit, not
- * a second copy: a composer's files are *pushed* into the page whole, as one
- * injected payload, so the base64 is held on both sides at once. A reference
- * window pulls its file a chunk at a time and answers to the app's number
- * alone. */
-const MAX_COMPOSER_BYTES = 48 * 1024 * 1024;
-
-/** One handed-over file, fetched from the app and carried as base64: what
- * crosses into the page is a string, and the page turns it back into a file.
- * Base64 rather than a `data:` URL because the page rebuilds it with `atob` —
- * a fetch over there answers to the site's CSP, and X refuses that one. */
-async function fetchAttachment(backendUrl, token, caseId, path) {
- const url = fileUrl(backendUrl, caseId, path);
- const r = await fetch(url, { headers: { "X-Azimut-Token": token } });
- // Gone, too big, refused: the file is skipped and counted, never fatal. It is
- // in the case, and attaching it by hand is what the analyst did before.
- if (!r.ok) return null;
- const blob = await r.blob();
- if (blob.size > MAX_COMPOSER_BYTES) return null;
- return {
- name: path.split("/").pop(),
- type: blob.type || "application/octet-stream",
- data: await base64(blob),
- };
+ * `executeScript` still needs a serializable string, but the string is now one
+ * 4 MB slice rather than the whole video. The page decodes each slice at once
+ * and keeps only byte arrays for the final `File`, so a long clip answers to the
+ * app's 512 MB hand-off ceiling rather than an extension-only 48 MB ceiling.
+ * The page itself never fetches the local URL, which keeps this path independent
+ * of X's and Bluesky's content-security policies.
+ */
+async function streamAttachment(target, backendUrl, token, caseId, path, id) {
+ let offset = 0;
+ while (true) {
+ const part = await fileChunk(backendUrl, token, caseId, path, offset);
+ await api.scripting.executeScript({
+ target,
+ world: "MAIN",
+ func: (fileId, type, data) => {
+ const thread = window.__AZIMUT_HANDOFF__;
+ const file = thread?.posts
+ ?.flatMap((post) => post.files ?? [])
+ .find((candidate) => candidate.id === fileId);
+ if (!file) throw new Error("handed-over file disappeared");
+ const binary = atob(data);
+ const bytes = new Uint8Array(binary.length);
+ for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+ file.type = type || file.type;
+ file.parts.push(bytes);
+ },
+ args: [id, part.type, part.data],
+ });
+ if (part.next === null) return;
+ if (part.next <= offset) throw new Error("Azimut returned an empty file slice");
+ offset = part.next;
+ }
+}
+
+/** Leave no partial file in the page when one of its slices was refused. */
+async function discardAttachment(target, id) {
+ await api.scripting.executeScript({
+ target,
+ world: "MAIN",
+ func: (fileId) => {
+ const thread = window.__AZIMUT_HANDOFF__;
+ for (const post of thread?.posts ?? []) {
+ post.files = (post.files ?? []).filter((file) => file.id !== fileId);
+ }
+ },
+ args: [id],
+ });
}
/** One case attachment, addressed. */
@@ -141,13 +164,7 @@ function fileUrl(backendUrl, caseId, path) {
);
}
-/** A blob as base64. What crosses into a page is a string: a message carries no
- * blob, and both sides rebuild the file from this. */
-async function base64(blob) {
- return encode(new Uint8Array(await blob.arrayBuffer()));
-}
-
-/** The same, for bytes already in hand. */
+/** Bytes as base64, in bounded pieces that can cross an injection boundary. */
function encode(bytes) {
let binary = "";
const CHUNK = 0x8000; // fromCharCode takes an argument list: chunk it or blow the stack
@@ -157,6 +174,11 @@ function encode(bytes) {
return btoa(binary);
}
+/** A small blob as base64. Large files go through `fileChunk` instead. */
+async function base64(blob) {
+ return encode(new Uint8Array(await blob.arrayBuffer()));
+}
+
/** Resolve once the tab has finished loading, so the injection lands on a page. */
function tabLoaded(tabId, timeoutMs = 20000) {
return new Promise((resolve) => {
@@ -197,31 +219,27 @@ async function handOff(payload) {
}
async function fillComposer(payload, backendUrl, token) {
- let skipped = 0;
- const posts = [];
- for (const post of payload.posts ?? []) {
- const files = [];
- for (const path of post.files ?? []) {
- const file = await fetchAttachment(backendUrl, token, payload.caseId, path);
- if (file) files.push(file);
- else skipped += 1;
- }
- posts.push({ text: post.text ?? "", files });
- }
- if (skipped) {
- notify(
- "Azimut hand-off",
- `${skipped} file${skipped > 1 ? "s" : ""} could not be handed over. Attach ${skipped > 1 ? "them" : "it"} from the case.`
- );
- }
-
const tab = await api.tabs.create({ url: payload.url, active: true });
await tabLoaded(tab.id);
// Both injections run in the page's own world, which is the only place a
// composer accepts what we make (see handoff.js). Nothing over there can call
- // an extension API, so the thread goes in on a global and the report comes back
- // as the script's return value.
+ // an extension API, so the thread goes in on a global, its file parts follow,
+ // and the report comes back as the script's return value.
const target = { tabId: tab.id };
+ const plans = [];
+ const posts = (payload.posts ?? []).map((post, postIndex) => ({
+ text: post.text ?? "",
+ files: (post.files ?? []).map((path, fileIndex) => {
+ const id = `${postIndex}:${fileIndex}`;
+ plans.push({ id, path });
+ return {
+ id,
+ name: path.split("/").pop(),
+ type: "application/octet-stream",
+ parts: [],
+ };
+ }),
+ }));
await api.scripting.executeScript({
target,
world: "MAIN",
@@ -230,6 +248,23 @@ async function fillComposer(payload, backendUrl, token) {
},
args: [{ posts }],
});
+
+ let skipped = 0;
+ for (const plan of plans) {
+ try {
+ await streamAttachment(target, backendUrl, token, payload.caseId, plan.path, plan.id);
+ } catch {
+ skipped += 1;
+ await discardAttachment(target, plan.id).catch(() => {});
+ }
+ }
+ if (skipped) {
+ notify(
+ "Azimut hand-off",
+ `${skipped} file${skipped > 1 ? "s" : ""} could not be handed over. Attach ${skipped > 1 ? "them" : "it"} from the case.`
+ );
+ }
+
const [done] = await api.scripting.executeScript({
target,
world: "MAIN",
@@ -536,8 +571,8 @@ async function mapImage(msg) {
*
* The whole point of the number: base64 of *this* is the biggest string either
* side ever holds, whatever the file weighs. A phone's clip of a street is
- * hundreds of megabytes and the window that holds it up against the imagery is
- * the reason the panel is open, so the file cannot be the unit. */
+ * hundreds of megabytes; both the composer and a map reference need the file
+ * without making the file itself the unit. */
const FILE_CHUNK_BYTES = 4 * 1024 * 1024;
/** The end and the total of a `Content-Range`, or null when the app answered with
@@ -548,24 +583,20 @@ function ranged(header) {
}
/**
- * One slice of one of the case's files, for a reference window (`mapref.js`).
+ * One slice of one of the case's files, for a composer or reference window.
*
* Not `mapApi`: that one parses what comes back as JSON, and this is bytes. The
* route is written in rather than allowlisted — the panel may ask for a file
* from the case it has open and for nothing else, and the app's own fence
* (`api/ingest.py`, ``handoff_file``) is what says which files those are.
*
- * It answers a slice rather than a file because the panel is often holding a
- * video up, and a video is not 48 MB. `Range` is what `FileResponse` already
- * serves, so nothing over there had to be built for this: the page asks again
- * from `next` until `next` is null and glues the pieces into one blob. A slice
- * short of the chunk size is not the signal — a file whose length divides evenly
- * would end on a 416 — so the total in `Content-Range` is.
+ * `Range` is what `FileResponse` already serves, so nothing over there had to be
+ * built for this: the consumer asks again from `next` until `next` is null and
+ * glues the pieces into one file. A slice short of the chunk size is not the
+ * signal — a file whose length divides evenly would end on a 416 — so the total
+ * in `Content-Range` is.
*/
-async function mapFile(caseId, path, offset = 0) {
- const { backendUrl, token } = await settings();
- if (!token) throw new Error("not paired. Open the extension options and paste the token from Azimut Settings");
- if (!caseId) throw new Error("no case open");
+async function fileChunk(backendUrl, token, caseId, path, offset = 0) {
const start = Number(offset) || 0;
let r;
try {
@@ -593,6 +624,13 @@ async function mapFile(caseId, path, offset = 0) {
};
}
+async function mapFile(caseId, path, offset = 0) {
+ const { backendUrl, token } = await settings();
+ if (!token) throw new Error("not paired. Open the extension options and paste the token from Azimut Settings");
+ if (!caseId) throw new Error("no case open");
+ return fileChunk(backendUrl, token, caseId, path, offset);
+}
+
/** Why the app would not hand a file over, in its own words where it gave any —
* the size ceiling is stated there, and a second copy of the number here is a
* number that goes stale. */
diff --git a/extension/handoff.js b/extension/handoff.js
index 4ee0276..9bee4b0 100644
--- a/extension/handoff.js
+++ b/extension/handoff.js
@@ -428,13 +428,17 @@
/**
* Rebuild a handed-over file on this side.
*
- * It crosses as base64 rather than as a `data:` URL for one reason: this runs
- * in the page's world, so a read over the network answers to the page's own
- * CSP — and X allows no connection to `data:`. Every attachment came back
- * "Failed to fetch" and took the rest of the thread down with it. `atob` asks
- * the network for nothing, so there is nothing left to refuse.
- */
+ * A large file arrives as decoded byte-array parts, one bounded injection at
+ * a time. `data` remains as the compatibility path for an older worker and
+ * small test fixtures. Neither road fetches from the page: that would answer
+ * to the site's own CSP, which is exactly what X refuses.
+ */
function toFile(file) {
+ if (Array.isArray(file.parts)) {
+ const parts = file.parts;
+ file.parts = []; // the File owns the bytes now; do not retain a second reference
+ return new File(parts, file.name, { type: file.type });
+ }
const binary = atob(file.data ?? "");
const bytes = new Uint8Array(binary.length);
for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
diff --git a/frontend/e2e/app.fixture.js b/frontend/e2e/app.fixture.js
index ce2d485..2b2c5ff 100644
--- a/frontend/e2e/app.fixture.js
+++ b/frontend/e2e/app.fixture.js
@@ -1061,6 +1061,9 @@ export async function installAppFixture(page, options = {}) {
return json(route, overview);
}
const caseId = fixtureCases.find((item) => path.startsWith(`/api/cases/${item.id}/`))?.id;
+ if (caseId && path === `/api/cases/${caseId}/map-layers` && request.method() === 'GET') {
+ return json(route, []);
+ }
if (caseId && path === `/api/cases/${caseId}/analysis-views`) {
if (request.method() === 'GET') {
return json(route, {
@@ -1997,10 +2000,11 @@ export async function installAppFixture(page, options = {}) {
/**
* Put the Saved panel, and the layer drawing from it, on one position.
*
- * The panel opens on **Media**, so a spec about places or captures asks for its
- * own position rather than assuming the one it used to open on.
+ * The map panel opens on its Layers tab and Saved opens on **Media**, so a spec
+ * about the case's own work asks for both rather than assuming either.
*/
export async function showSaved(page, kind) {
+ await page.getByRole('tablist', { name: 'Map panel' }).getByRole('tab', { name: 'Saved' }).click();
await page
.getByRole('group', { name: 'What this panel lists' })
.getByRole('button', { name: kind, exact: true })
diff --git a/frontend/e2e/compare.spec.js b/frontend/e2e/compare.spec.js
index 3574843..da390fd 100644
--- a/frontend/e2e/compare.spec.js
+++ b/frontend/e2e/compare.spec.js
@@ -70,6 +70,39 @@ test('linked maps keep annotations on the ground through pan, modes and save', a
expect(errors).toEqual([]);
});
+test('an export frame can be drawn across every overlaid reading mode', async ({ page }) => {
+ const { errors, saved } = await openCompare(page);
+
+ for (const mode of ['Fade', 'Swipe', 'Blink']) {
+ await page.getByRole('button', { name: mode, exact: true }).click();
+ await page.getByRole('button', { name: 'Export', exact: true }).click();
+ const dialog = page.getByRole('dialog', { name: 'Export a copy' });
+ await dialog.getByRole('button', { name: /^(Draw|Redraw)…$/ }).click();
+
+ const stage = await page.locator('.compare-stage').boundingBox();
+ const overlay = page.locator('.compare-stage > .export-frame.drawing');
+ await expect(overlay).toBeVisible();
+ const frame = await overlay.boundingBox();
+ expect(frame.x).toBeCloseTo(stage.x, 0);
+ expect(frame.width).toBeCloseTo(stage.width, 0);
+ await page.mouse.move(stage.x + stage.width * 0.2, stage.y + stage.height * 0.2);
+ await page.mouse.down();
+ await page.mouse.move(stage.x + stage.width * 0.8, stage.y + stage.height * 0.75, { steps: 5 });
+ await page.mouse.up();
+
+ await expect(dialog).toBeVisible();
+ await expect(dialog.locator('.destination-actions').getByRole('button')).toHaveText(['Redraw…', 'Clear']);
+ await dialog.getByRole('button', { name: 'Close', exact: true }).click();
+ }
+
+ await page.getByRole('button', { name: 'Save comparison', exact: true }).click();
+ await page.getByRole('dialog', { name: 'Save comparison' })
+ .getByRole('button', { name: 'Save comparison', exact: true }).click();
+ await expect.poll(() => saved.length).toBe(1);
+ expect(saved[0].spec.frame.points).toHaveLength(2);
+ expect(errors).toEqual([]);
+});
+
test('spectral frames are requested only by Run, including after reopening and moving', async ({ page }) => {
await installAppFixture(page);
const errors = [];
diff --git a/frontend/e2e/proof-canvas.spec.js b/frontend/e2e/proof-canvas.spec.js
index 74a34ee..7d611af 100644
--- a/frontend/e2e/proof-canvas.spec.js
+++ b/frontend/e2e/proof-canvas.spec.js
@@ -1,6 +1,225 @@
import { test, expect } from '@playwright/test';
import { installAppFixture, openProofWithPanel } from './app.fixture.js';
+test('a panel rotates from its round handle and crops in place on double-click', async ({ page }) => {
+ const fixture = await installAppFixture(page);
+ await openProofWithPanel(page);
+
+ await page.locator('.panel-thumb').click();
+ await expect(page.getByRole('button', { name: /Rotate panel/ })).toHaveCount(0);
+
+ const canvas = page.locator('.konva canvas').first();
+ const canvasBox = await canvas.boundingBox();
+ expect(canvasBox).not.toBeNull();
+ const rotation = await page.evaluate(() => {
+ const stage = window.Konva.stages[0];
+ const transformer = stage.find((node) => node.getClassName() === 'Transformer')[0];
+ const node = transformer.nodes()[0];
+ const handle = transformer.findOne('.rotater');
+ return {
+ centre: node.getAbsolutePosition(),
+ handle: handle.getAbsolutePosition(),
+ round: handle.cornerRadius() >= handle.width() / 2,
+ };
+ });
+ expect(rotation.round).toBe(true);
+ const radius = Math.hypot(
+ rotation.handle.x - rotation.centre.x,
+ rotation.handle.y - rotation.centre.y,
+ );
+ await page.mouse.move(canvasBox.x + rotation.handle.x, canvasBox.y + rotation.handle.y);
+ await page.mouse.down();
+ await page.mouse.move(
+ canvasBox.x + rotation.centre.x + radius * 0.5,
+ canvasBox.y + rotation.centre.y - radius * 0.866,
+ { steps: 8 },
+ );
+ await page.mouse.up();
+
+ // A turn re-flows the layout around the bigger box, so the panel moves after
+ // the release. Aim once it has stopped, or a fast runner clicks where it was.
+ let lastCentre = null;
+ await expect.poll(async () => {
+ const centre = await page.evaluate(() => {
+ const stage = window.Konva.stages[0];
+ const transformer = stage.find((node) => node.getClassName() === 'Transformer')[0];
+ const node = transformer.nodes()[0];
+ return node && Math.abs(node.rotation()) > 5 ? node.getAbsolutePosition() : null;
+ });
+ const settled = centre && lastCentre
+ && Math.abs(centre.x - lastCentre.x) < 0.5 && Math.abs(centre.y - lastCentre.y) < 0.5;
+ lastCentre = centre;
+ return settled;
+ }, { intervals: [100] }).toBe(true);
+ const panelCentre = lastCentre;
+ await page.mouse.dblclick(canvasBox.x + panelCentre.x, canvasBox.y + panelCentre.y);
+ await expect.poll(() => page.evaluate(() => (
+ window.Konva.stages[0].findOne('#proof-crop-handles').find('.crop-anchor').length
+ ))).toBe(8);
+
+ const northWest = await page.evaluate(() => {
+ const group = window.Konva.stages[0].findOne('#proof-crop-handles');
+ return group.find('.crop-anchor').find((node) => node.getAttr('cropKey') === 'nw').getAbsolutePosition();
+ });
+ await page.mouse.move(canvasBox.x + northWest.x, canvasBox.y + northWest.y);
+ await page.mouse.down();
+ await page.mouse.move(canvasBox.x + northWest.x + 45, canvasBox.y + northWest.y + 35, { steps: 8 });
+ await page.mouse.up();
+
+ await page.getByRole('button', { name: 'Save proof', exact: true }).click();
+ await expect.poll(() => fixture.proofSaves.length).toBe(1);
+ const transformed = fixture.proofSaves[0].spec.panels[0];
+ expect(transformed.natural).toEqual([640, 360]); // source pixels stay intact
+ expect(Math.abs(transformed.rotation)).toBeGreaterThan(5);
+ expect(transformed.crop.w).toBeGreaterThan(0);
+ expect(transformed.crop.h).toBeGreaterThan(0);
+ expect(transformed.crop.w).toBeLessThan(640);
+
+ // The reset takes the crop and leaves the turn: they are two statements.
+ await page.getByRole('button', { name: 'Reset panel crop' }).click();
+ await page.getByRole('button', { name: 'Save proof', exact: true }).click();
+ await expect.poll(() => fixture.proofSaves.length).toBe(2);
+ expect(fixture.proofSaves[1].spec.panels[0]).not.toHaveProperty('crop');
+ expect(Math.abs(fixture.proofSaves[1].spec.panels[0].rotation)).toBeGreaterThan(5);
+ fixture.expectNoUnexpectedRequests();
+});
+
+/** Where the one panel sits on the canvas, selected or not. */
+const panelRect = (page) => page.evaluate(() => (
+ window.Konva.stages[0].findOne((node) => node.id()?.startsWith('pg-')).getClientRect()
+));
+
+/** Put the crop marks up on the one panel, the way an analyst does. */
+async function openCropMode(page, canvasBox) {
+ const rect = await panelRect(page);
+ await page.mouse.dblclick(
+ canvasBox.x + rect.x + rect.width / 2,
+ canvasBox.y + rect.y + rect.height / 2,
+ );
+ await expect.poll(() => cropAnchorCount(page)).toBe(8);
+}
+
+const cropAnchorCount = (page) => page.evaluate(() => (
+ window.Konva.stages[0].findOne('#proof-crop-handles').find('.crop-anchor').length
+));
+
+/** The box the black marks currently frame, in stage pixels. */
+const cropFrame = (page) => page.evaluate(() => {
+ const border = window.Konva.stages[0].findOne('.crop-border');
+ return { w: Math.round(border.width()), h: Math.round(border.height()) };
+});
+
+const cropAnchorAt = (page, key) => page.evaluate((wanted) => (
+ window.Konva.stages[0]
+ .findOne('#proof-crop-handles')
+ .find('.crop-anchor')
+ .find((node) => node.getAttr('cropKey') === wanted)
+ .getAbsolutePosition()
+), key);
+
+async function dragCropAnchor(page, canvasBox, key, dx, dy) {
+ const from = await cropAnchorAt(page, key);
+ await page.mouse.move(canvasBox.x + from.x, canvasBox.y + from.y);
+ await page.mouse.down();
+ await page.mouse.move(canvasBox.x + from.x + dx, canvasBox.y + from.y + dy, { steps: 8 });
+ await page.mouse.up();
+}
+
+// The marks are a draft until crop mode is left: pulling a corner too far is
+// undone by pulling it back, and the whole session lands as one crop. Committing
+// on each release instead would bury the pixels the next pull needs.
+test('crop marks pull both ways, land once on the way out, and Escape drops them', async ({ page }) => {
+ const fixture = await installAppFixture(page);
+ await openProofWithPanel(page);
+
+ const canvasBox = await page.locator('.konva canvas').first().boundingBox();
+ expect(canvasBox).not.toBeNull();
+ await openCropMode(page, canvasBox);
+
+ const full = await cropFrame(page);
+ await dragCropAnchor(page, canvasBox, 'nw', 70, 45);
+ const pulledIn = await cropFrame(page);
+ expect(pulledIn.w).toBeLessThan(full.w);
+ expect(pulledIn.h).toBeLessThan(full.h);
+
+ // Back out: the pixels are still there, because nothing was cut yet.
+ await dragCropAnchor(page, canvasBox, 'nw', -40, -25);
+ const pulledBack = await cropFrame(page);
+ expect(pulledBack.w).toBeGreaterThan(pulledIn.w);
+ expect(pulledBack.h).toBeGreaterThan(pulledIn.h);
+
+ // Escape unwinds the draft, like every other draft in this tool.
+ await page.keyboard.press('Escape');
+ await expect.poll(() => cropAnchorCount(page)).toBe(0);
+ await page.getByRole('button', { name: 'Save proof', exact: true }).click();
+ await expect.poll(() => fixture.proofSaves.length).toBe(1);
+ expect(fixture.proofSaves[0].spec.panels[0]).not.toHaveProperty('crop');
+
+ // A press off the image is what keeps it, and three pulls land as one crop.
+ await openCropMode(page, canvasBox);
+ await dragCropAnchor(page, canvasBox, 'nw', 60, 40);
+ await dragCropAnchor(page, canvasBox, 'se', -50, -30);
+ await dragCropAnchor(page, canvasBox, 'e', -20, 0);
+ const rect = await panelRect(page);
+ await page.mouse.click(
+ canvasBox.x + Math.max(3, rect.x - 10),
+ canvasBox.y + Math.max(3, rect.y - 10),
+ );
+ await expect.poll(() => cropAnchorCount(page)).toBe(0);
+
+ await page.getByRole('button', { name: 'Save proof', exact: true }).click();
+ await expect.poll(() => fixture.proofSaves.length).toBe(2);
+ const saved = fixture.proofSaves[1].spec.panels[0];
+ expect(saved.natural).toEqual([640, 360]); // the source file is untouched
+ expect(saved).not.toHaveProperty('rotation');
+ expect(saved.crop.w).toBeLessThan(640);
+ expect(saved.crop.h).toBeLessThan(360);
+ fixture.expectNoUnexpectedRequests();
+});
+
+// The row button is the way in and out that needs no aim, so it toggles.
+test('the row crop button opens the marks and a second press keeps the box', async ({ page }) => {
+ const fixture = await installAppFixture(page);
+ await openProofWithPanel(page);
+
+ const canvasBox = await page.locator('.konva canvas').first().boundingBox();
+ const cropButton = page.getByRole('button', { name: 'Crop panel' });
+ await cropButton.click();
+ await expect.poll(() => cropAnchorCount(page)).toBe(8);
+
+ await dragCropAnchor(page, canvasBox, 'se', -55, -35);
+ await cropButton.click();
+ await expect.poll(() => cropAnchorCount(page)).toBe(0);
+
+ await page.getByRole('button', { name: 'Save proof', exact: true }).click();
+ await expect.poll(() => fixture.proofSaves.length).toBe(1);
+ const saved = fixture.proofSaves[0].spec.panels[0];
+ expect(saved.crop.w).toBeLessThan(640);
+ fixture.expectNoUnexpectedRequests();
+});
+
+// Reaching for a pen is the other way out of crop mode, and it runs from inside
+// the effect that watches the tool, where the commit writes to the document.
+test('a tool picked up mid-crop keeps the box the marks framed', async ({ page }) => {
+ const fixture = await installAppFixture(page);
+ await openProofWithPanel(page);
+ const errors = [];
+ page.on('pageerror', (error) => errors.push(error.message));
+
+ const canvasBox = await page.locator('.konva canvas').first().boundingBox();
+ await openCropMode(page, canvasBox);
+ await dragCropAnchor(page, canvasBox, 'nw', 60, 40);
+
+ await page.getByTitle('Box (r)').click();
+ await expect.poll(() => cropAnchorCount(page)).toBe(0);
+ expect(errors).toEqual([]);
+
+ await page.getByRole('button', { name: 'Save proof', exact: true }).click();
+ await expect.poll(() => fixture.proofSaves.length).toBe(1);
+ expect(fixture.proofSaves[0].spec.panels[0].crop.w).toBeLessThan(640);
+ fixture.expectNoUnexpectedRequests();
+});
+
test('a real Konva panel remains interactive after click and drag', async ({ page }) => {
const fixture = await installAppFixture(page);
await openProofWithPanel(page);
diff --git a/frontend/e2e/saved-media.spec.js b/frontend/e2e/saved-media.spec.js
index fc2d214..aae3522 100644
--- a/frontend/e2e/saved-media.spec.js
+++ b/frontend/e2e/saved-media.spec.js
@@ -57,7 +57,9 @@ test('opens on the case’s located files, with the layer already drawing them',
await page.goto('/#satellite');
await awaitMapReady(page);
- // no switch was pressed: the panel opens on Media and the layer is on
+ // the layer is on before the panel is looked at, and Saved opens on Media
+ await expect(page.locator('.saved-mark')).toHaveCount(1);
+ await page.getByRole('tablist', { name: 'Map panel' }).getByRole('tab', { name: 'Saved' }).click();
await expect(panel(page).getByText('roadside photo')).toBeVisible();
await expect(panel(page).getByText('Recorded here')).toBeVisible();
await expect(page.locator('.saved-mark')).toHaveCount(1);
diff --git a/frontend/src/lib/composer.js b/frontend/src/lib/composer.js
index 5f7b615..43a706b 100644
--- a/frontend/src/lib/composer.js
+++ b/frontend/src/lib/composer.js
@@ -6,6 +6,9 @@
*/
import { formatCoords as renderCoords } from './coords.js';
+import {
+ normalizeSourceCrop, normalizeSurfaceAngle, surfaceImageSize,
+} from './proofSurface.js';
export const PANEL_H = 720;
export const PAD = 20;
@@ -211,6 +214,24 @@ export function panelHeight(p) {
return PANEL_H * (p.scale ?? 1);
}
+/** The pixels a panel draws — its crop when it has one, else its whole source. */
+const panelImage = (p) => surfaceImageSize(p.sourceNatural ?? p.natural, p.crop);
+
+/**
+ * How a panel's own pixels map to doc pixels. Its height is applied to the
+ * image and never to the upright box a turned image sits in, or turning a photo
+ * would shrink it to keep that growing box the same height.
+ */
+export function panelScale(p) {
+ return panelHeight(p) / panelImage(p)[1];
+}
+
+/** The upright room a panel occupies, scaled: its own box, turn included. */
+function panelBox(p) {
+ const scale = panelScale(p);
+ return { scale, w: p.natural[0] * scale, h: p.natural[1] * scale };
+}
+
/**
* Panel layout boxes in doc space: [{x, y, w, h, scale, baseScale, row}] aligned
* with the input `panels`. In the default `grid` layout panels are grouped by
@@ -249,9 +270,9 @@ function layoutPanelsGrid(panels, captionSize = CAPTION_SIZE, space) {
let h = 0;
const inRow = panels.filter((p) => (p.row ?? 0) === r);
inRow.forEach((p, k) => {
- const ph = panelHeight(p);
- h = Math.max(h, ph);
- w += p.natural[0] * (ph / p.natural[1]) + (k ? gap : 0);
+ const box = panelBox(p);
+ h = Math.max(h, box.h);
+ w += box.w + (k ? gap : 0);
});
rowWidth.set(r, w);
rowHeight.set(r, h);
@@ -268,12 +289,10 @@ function layoutPanelsGrid(panels, captionSize = CAPTION_SIZE, space) {
const cursor = new Map(rows.map((r) => [r, pad + (contentW - rowWidth.get(r)) / 2]));
return panels.map((p) => {
const r = p.row ?? 0;
- const ph = panelHeight(p);
- const scale = ph / p.natural[1];
- const baseScale = PANEL_H / p.natural[1];
- const w = p.natural[0] * scale;
- const y = rowTop.get(r) + (rowHeight.get(r) - ph); // bottom-align within row
- const box = { x: cursor.get(r), y, w, h: ph, scale, baseScale, row: r };
+ const { scale, w, h } = panelBox(p);
+ const baseScale = PANEL_H / panelImage(p)[1];
+ const y = rowTop.get(r) + (rowHeight.get(r) - h); // bottom-align within row
+ const box = { x: cursor.get(r), y, w, h, scale, baseScale, row: r };
cursor.set(r, cursor.get(r) + w + gap);
return box;
});
@@ -298,15 +317,14 @@ export function layoutPanelsFree(panels, captionSize = CAPTION_SIZE, space) {
const dx = pad - Math.min(...pos.map((q) => q.x));
const dy = pad - Math.min(...pos.map((q) => q.y));
return panels.map((p, i) => {
- const ph = panelHeight(p);
- const scale = ph / p.natural[1];
+ const { scale, w, h } = panelBox(p);
return {
x: pos[i].x + dx,
y: pos[i].y + dy,
- w: p.natural[0] * scale,
- h: ph,
+ w,
+ h,
scale,
- baseScale: PANEL_H / p.natural[1],
+ baseScale: PANEL_H / panelImage(p)[1],
row: p.row ?? 0,
};
});
@@ -336,7 +354,7 @@ export function panelsBlockHeight(panels, captionSize = CAPTION_SIZE, space) {
for (const r of rows) {
const inRow = panels.filter((p) => (p.row ?? 0) === r);
const band = rowHasCaption(panels, r) ? captionBand(captionSize) : 0;
- total += Math.max(...inRow.map(panelHeight)) + band;
+ total += Math.max(...inRow.map((p) => panelBox(p).h)) + band;
}
return total + (rows.length - 1) * rowGap;
}
@@ -1071,6 +1089,17 @@ export function clampPaste(paste, docW, docH) {
};
}
+/**
+ * An image's crop and turn, left out of the spec when it has neither. Both are
+ * read against the source size, which is what the spec's `natural` holds.
+ */
+function surfaceGeometry(surface) {
+ const source = surface.sourceNatural ?? surface.natural;
+ const crop = normalizeSourceCrop(surface.crop, source);
+ const rotation = normalizeSurfaceAngle(surface.rotation);
+ return { ...(crop ? { crop } : {}), ...(rotation ? { rotation } : {}) };
+}
+
/** Serializable spec from runtime state (drops live image objects). */
export function toSpec(proof) {
return {
@@ -1148,20 +1177,24 @@ export function toSpec(proof) {
scale: p.scale ?? 1, // per-panel size multiplier (1 = default PANEL_H)
x: p.x ?? null, // free-layout doc position; null → grid fallback
y: p.y ?? null,
- natural: p.natural,
+ // Runtime `natural` is the upright box the turned image occupies. The
+ // spec keeps the source size, which the crop and turn are read against.
+ natural: p.sourceNatural ?? p.natural,
meta: p.meta ?? {},
frame: normalizeFrame(p.frame), // decorative border; null → none
+ ...surfaceGeometry(p), // crop and turn, absent when there are neither
})),
// Pasted images, front→back. They have no `src`: the case holds nothing for
// them beyond the file in the proof's own assets folder.
pastes: (proof.pastes ?? []).map((p) => ({
id: p.id, // kept so shapes stay bound to their paste on reload
asset: p.asset,
- natural: p.natural,
+ natural: p.sourceNatural ?? p.natural,
x: p.x ?? 0,
y: p.y ?? 0,
scale: clampPasteScale(p.scale),
frame: normalizeFrame(p.frame),
+ ...surfaceGeometry(p),
})),
shapes: proof.shapes.map((s) => ({ ...s })),
};
diff --git a/frontend/src/lib/composer.test.js b/frontend/src/lib/composer.test.js
index 65b2472..93752a9 100644
--- a/frontend/src/lib/composer.test.js
+++ b/frontend/src/lib/composer.test.js
@@ -2,7 +2,7 @@ import { describe, it, expect } from 'vitest';
import {
PAD, PANEL_H, GAP, ROW_GAP, FOOTER_H, LEGEND_LINE_H,
layoutPanels, layoutPanelsFree, freeNormalizeDelta, panelsBottom,
- panelsBlockHeight, panelHeight, captionBand, legendLineHeight, footerBand,
+ panelsBlockHeight, panelHeight, panelScale, captionBand, legendLineHeight, footerBand,
docSize, legendColumns, legendRowCount, toSpec, offsetShape, copyShapeSpec, autoLayoutRows, TWEET_GUIDES,
autoCoords, formatCoords, resolveSourceUrls, autoSource, autoSourceUrls,
normalizeSources, statedSources,
@@ -80,6 +80,17 @@ describe('layoutPanels — stacked rows', () => {
});
describe('layoutPanels — per-panel scale', () => {
+ it('turning a panel does not shrink it: the size is the image\'s, not the box\'s', () => {
+ // The box a turned photo needs is bigger than the photo. Reading the panel's
+ // height off that box is what made every turn shrink the picture inside it.
+ const upright = { natural: [400, 200], sourceNatural: [400, 200] };
+ const turned = { natural: [200, 400], sourceNatural: [400, 200], rotation: 90 };
+ expect(panelScale(turned)).toBe(panelScale(upright));
+
+ const [a, b] = layoutPanels([upright, turned], 0, 'grid');
+ expect([a.w, a.h]).toEqual([b.h, b.w]); // the room swapped, the image did not
+ });
+
it('panelHeight is PANEL_H times the panel scale (default 1)', () => {
expect(panelHeight({ natural: [1, 1] })).toBe(PANEL_H);
expect(panelHeight({ natural: [1, 1], scale: 0.5 })).toBe(PANEL_H * 0.5);
@@ -409,6 +420,35 @@ describe('toSpec — persistence of layout', () => {
};
expect(toSpec(proof).panels.map((p) => p.scale)).toEqual([1.5, 1]);
});
+
+ it('persists a panel crop and turn against the untouched source size', () => {
+ const proof = {
+ title: 'T',
+ panels: [{
+ id: 'p1', src: 'a.png',
+ natural: [500, 300], // the upright box the turned crop occupies
+ sourceNatural: [1200, 800],
+ crop: { x: 100, y: 200, w: 500, h: 300 },
+ rotation: 37.5,
+ }],
+ shapes: [],
+ };
+ expect(toSpec(proof).panels[0]).toMatchObject({
+ natural: [1200, 800],
+ crop: { x: 100, y: 200, w: 500, h: 300 },
+ rotation: 37.5,
+ });
+ });
+
+ it('leaves both out of a panel that was neither cropped nor turned', () => {
+ const spec = toSpec({
+ title: 'T',
+ panels: [{ id: 'p1', src: 'a.png', natural: [640, 360] }],
+ shapes: [],
+ });
+ expect(spec.panels[0]).not.toHaveProperty('crop');
+ expect(spec.panels[0]).not.toHaveProperty('rotation');
+ });
});
describe('toSpec — layout mode + free positions', () => {
@@ -1773,6 +1813,31 @@ describe('pasted images', () => {
expect(spec.shapes[0].panel).toBe('x1');
});
+ it('persists an overlay crop and turn without replacing its source dimensions', () => {
+ const spec = toSpec({
+ title: 'x', panels: [], shapes: [], notes: {},
+ pastes: [paste({
+ natural: [300, 200],
+ sourceNatural: [800, 400],
+ crop: { x: 50, y: 25, w: 300, h: 200 },
+ rotation: -32,
+ })],
+ });
+ expect(spec.pastes[0]).toMatchObject({
+ natural: [800, 400],
+ crop: { x: 50, y: 25, w: 300, h: 200 },
+ rotation: -32,
+ });
+ });
+
+ it('drops a crop that covers the whole overlay: that is no crop at all', () => {
+ const spec = toSpec({
+ title: 'x', panels: [], shapes: [], notes: {},
+ pastes: [paste({ natural: [400, 300], crop: { x: 0, y: 0, w: 400, h: 300 } })],
+ });
+ expect(spec.pastes[0]).not.toHaveProperty('crop');
+ });
+
it('a proof with no pastes still writes an empty list, so reloads are uniform', () => {
expect(toSpec({ title: 'x', panels: [], shapes: [], notes: {} }).pastes).toEqual([]);
});
diff --git a/frontend/src/lib/extension.test.js b/frontend/src/lib/extension.test.js
index 4aec873..432697b 100644
--- a/frontend/src/lib/extension.test.js
+++ b/frontend/src/lib/extension.test.js
@@ -384,25 +384,42 @@ describe('handOff: filling a composer the app prepared', () => {
// paths become one token-bearing read each, against the app, not the page
expect(fetchImpl).toHaveBeenCalledWith(
'http://127.0.0.1:8477/api/ingest/file?case_id=case-1&path=proofs%2Fstrike.png',
- { headers: { 'X-Azimut-Token': 'tok-123' } }
+ {
+ headers: {
+ 'X-Azimut-Token': 'tok-123',
+ Range: `bytes=0-${4 * 1024 * 1024 - 1}`,
+ },
+ }
);
expect(chrome.tabs.create).toHaveBeenCalledWith({ url: payload.url, active: true });
// Both injections in the page's own world: an editor ignores what an
// extension's world makes, and there is no extension API on that side — so
// the thread goes in on a global and the report comes back as a return value.
- const [setter, filler] = chrome.scripting.executeScript.mock.calls
+ const injected = chrome.scripting.executeScript.mock.calls
.map(([one]) => one)
.filter((call) => call.world === 'MAIN');
+ const setter = injected.find((call) => call.args?.[0]?.posts);
+ const chunk = injected.find((call) => call.args?.[0] === '0:0');
+ const filler = injected.find((call) => call.files?.includes('handoff.js'));
expect(setter.world).toBe('MAIN');
- // The file crosses as plain base64, never as a `data:` URL: the page rebuilds
- // it with atob, because a fetch on that side answers to the site's own CSP —
- // and X allows no connection to `data:`, so every attachment came back
- // "Failed to fetch" and took the rest of the thread with it.
+ // The thread starts with an empty byte-parts list. Each bounded slice then
+ // crosses as plain base64 and is decoded into that list in the page, never
+ // fetched there through a URL that would answer to the site's CSP.
const [{ posts }] = setter.args;
expect(posts).toHaveLength(2);
expect(posts[0].files).toEqual([
- { name: 'strike.png', type: 'image/png', data: btoa('\x01\x02\x03') },
+ {
+ id: '0:0',
+ name: 'strike.png',
+ type: 'application/octet-stream',
+ parts: [],
+ },
]);
+ expect(chunk.args).toEqual(['0:0', 'image/png', btoa('\x01\x02\x03')]);
+ globalThis.window = { __AZIMUT_HANDOFF__: { posts } };
+ chunk.func(...chunk.args);
+ expect([...posts[0].files[0].parts[0]]).toEqual([1, 2, 3]);
+ delete globalThis.window;
expect(filler).toEqual({ target: { tabId: 7 }, world: 'MAIN', files: ['handoff.js'] });
});
@@ -431,35 +448,53 @@ describe('handOff: filling a composer the app prepared', () => {
// and it says so, because a picture missing from a published thread is not
// something to discover after posting
await settle(() => expect(chrome.notifications.create).toHaveBeenCalled());
+ const injected = chrome.scripting.executeScript.mock.calls.map(([one]) => one);
+ const setter = injected.find((call) => call.args?.[0]?.posts);
+ const discard = injected.find((call) => call.args?.length === 1 && call.args[0] === '0:0');
+ globalThis.window = { __AZIMUT_HANDOFF__: setter.args[0] };
+ discard.func(...discard.args);
+ expect(setter.args[0].posts[0].files).toEqual([]);
+ delete globalThis.window;
});
- it('skips an attachment too heavy to push into the page, where a window would take it', async () => {
- // The app's ceiling is the one a reference window answers to, and that one
- // pulls its file a chunk at a time. A thread's files go the other way — the
- // whole payload is injected at once — so this side keeps a lower number.
+ it('streams a composer attachment in slices instead of keeping the old 48 MB ceiling', async () => {
+ // The real slices are 4 MB. Tiny stand-ins make the boundary visible without
+ // allocating a large video in the unit suite.
const chrome = fillingChrome();
- const fetchImpl = vi.fn(async () => ({
- ok: true,
- blob: async () => ({
- type: 'video/mp4',
- size: 64 * 1024 * 1024,
- arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer,
- }),
- }));
+ let offset = 0;
+ const fetchImpl = vi.fn(async () => {
+ const start = offset;
+ offset += 3;
+ const response = {
+ ok: true,
+ status: 206,
+ headers: { get: () => `bytes ${start}-${start + 2}/6` },
+ blob: async () => ({
+ type: 'video/mp4',
+ arrayBuffer: async () => new Uint8Array(start ? [4, 5, 6] : [1, 2, 3]).buffer,
+ }),
+ };
+ return response;
+ });
const { handOff } = load({ chrome, fetchImpl });
chrome.scripting.executeScript = vi.fn(async () => [{ result: { filled: 2 } }]);
await handOff(payload);
- await settle(() =>
- expect(chrome.notifications.create).toHaveBeenCalledWith(
- expect.objectContaining({ message: expect.stringContaining('could not be handed over') })
- )
- );
- const [setter] = chrome.scripting.executeScript.mock.calls
+ await settle(() => expect(fetchImpl).toHaveBeenCalledTimes(2));
+ expect(source).not.toContain('MAX_COMPOSER_BYTES');
+ expect(fetchImpl.mock.calls.map(([, init]) => init.headers.Range)).toEqual([
+ `bytes=0-${4 * 1024 * 1024 - 1}`,
+ `bytes=3-${3 + 4 * 1024 * 1024 - 1}`,
+ ]);
+ const chunks = chrome.scripting.executeScript.mock.calls
.map(([one]) => one)
- .filter((call) => call.world === 'MAIN');
- expect(setter.args[0].posts[0].files).toEqual([]);
+ .filter((call) => call.args?.[0] === '0:0');
+ expect(chunks.map((call) => call.args[2])).toEqual([
+ btoa('\x01\x02\x03'),
+ btoa('\x04\x05\x06'),
+ ]);
+ expect(chrome.notifications.create).not.toHaveBeenCalled();
});
it('says what the fill could not do, since the app was answered long before', async () => {
diff --git a/frontend/src/lib/extensionHandoff.test.js b/frontend/src/lib/extensionHandoff.test.js
index 82ff092..d390285 100644
--- a/frontend/src/lib/extensionHandoff.test.js
+++ b/frontend/src/lib/extensionHandoff.test.js
@@ -637,10 +637,27 @@ describe('filling a thread', () => {
expect(report.pastes).toEqual([]);
});
- it('builds each file from base64, because a fetch here answers to the site', async () => {
+ it('builds one file from the byte-array slices the worker streamed in', async () => {
+ const streamed = {
+ name: 'clip.mp4',
+ type: 'video/mp4',
+ parts: [new Uint8Array([1, 2]), new Uint8Array([3, 4])],
+ };
+ const report = await run({
+ posts: [{ text: '', files: [streamed] }],
+ html: `${BOX(0)}${FILE_INPUT(0)}`,
+ });
+
+ const file = report.attached[0].files[0];
+ expect(file).toEqual(expect.objectContaining({ name: 'clip.mp4', type: 'video/mp4' }));
+ expect(file.parts.map((part) => [...part])).toEqual([[1, 2], [3, 4]]);
+ expect(streamed.parts).toEqual([]); // the descriptor no longer pins a second copy
+ });
+
+ it('keeps the base64 path for an older worker without fetching through the site', async () => {
// It runs in the page's world, so `fetch('data:…')` is a connection the site
- // decides on — and X allows none to `data:`. Every attachment came back
- // "Failed to fetch", which took the whole thread down with it.
+ // decides on — and X allows none to `data:`. The compatibility path decodes
+ // the old payload directly instead.
expect(source).not.toMatch(/\bfetch\s*\(/);
const report = await run({
diff --git a/frontend/src/lib/map/addedLayer.js b/frontend/src/lib/map/addedLayer.js
new file mode 100644
index 0000000..92ecbdc
--- /dev/null
+++ b/frontend/src/lib/map/addedLayer.js
@@ -0,0 +1,702 @@
+/**
+ * One added layer on the map: a GeoJSON source and the GL layers over it.
+ *
+ * **Not DOM markers.** The case's own pins are one `div` each (`surface.js`),
+ * which is right for a few hundred rich, draggable, hoverable marks and caps out
+ * around a thousand or two. A layer somebody else made holds tens of thousands,
+ * and none of them is interactive beyond a read-only card — so it is a source
+ * with `circle`, `symbol`, `line` and `fill` layers, which MapLibre paints in
+ * one pass and culls to the viewport for free. Nothing here filters by viewport
+ * or truncates the data: the engine already does the first and the second would
+ * be a map lying about what it read.
+ *
+ * Three things this has to do that the curated overlays do not:
+ *
+ * - **Decluttering is collision, not a cap.** At low zoom the symbols would be a
+ * solid mat, and a cap taken in file order clumps badly — a KML is ordered by
+ * folder or by creation, never by geography. `icon-allow-overlap: false` lets
+ * MapLibre drop a symbol that overlaps one already placed, which gives an
+ * evenly spread map that densifies as you zoom in, for nothing.
+ * - **Icons are registered at runtime.** The engine deliberately loads no style
+ * URL, no sprite and no glyphs (`engine.js`), and this must not be the reason
+ * it starts. Each pictogram is drawn to a canvas here and handed to
+ * `map.addImage` as an **SDF**, which is what lets one image per shape be
+ * tinted to any colour a source asked for — the alternative is one registered
+ * image per (shape × colour) pair, which explodes on a map with twenty groups.
+ * - **A source's own icons are a second symbol layer, not a second option on the
+ * first.** They arrive as real PNGs the backend composed
+ * (`engine/maplayers.py`), which means non-SDF, which means no `icon-color`
+ * and no `icon-halo-*` — the colour is already in the pixels. Mixing SDF and
+ * non-SDF images in one symbol layer is not something MapLibre renders
+ * reliably, so the points split by whether their icon loaded: the ones that
+ * did draw the source's picture, the ones that did not draw our tinted shape.
+ * That split is also the fallback. An icon that 404s, decodes badly or never
+ * arrives costs its features nothing beyond the pictogram they would have had.
+ * - **No map labels.** `text-field` needs real glyphs, which the engine does not
+ * load and which this feature will not make it load. A feature's name lives in
+ * the hover reading and in the card, both resolved through the engine's own
+ * hit testing.
+ */
+import { Popup } from 'maplibre-gl';
+import { paths } from '../../components/Icon.svelte';
+import { categoryColour } from './addedLayers.js';
+
+/** The pictogram per geometry kind. Three shapes is the whole vocabulary, and
+ * what every feature falls back to when the source drew no icon of its own. */
+const GLYPHS = { point: 'pin', line: 'line', area: 'polygon' };
+
+/** How big an icon is drawn into its own image, before the engine scales it. */
+const ICON_PIXELS = 64;
+
+/**
+ * Empty pixels kept around the glyph inside that image.
+ *
+ * The outline is drawn *outside* the shape, so a glyph filling its own image
+ * would have its outline cut off at the edge — worst at the pin's tip, which is
+ * the part that names the point.
+ */
+const ICON_PAD = 10;
+
+/**
+ * How far from the edge the distance field still means something.
+ *
+ * The outline can only be as wide as the field can measure, so this is what
+ * bounds `icon-halo-width` below: too small and the outline is clipped into a
+ * hard ring, which looks worse than none.
+ */
+const ICON_SPREAD = 8;
+
+/** …and how much of that is shown. An added layer sits under the case's own
+ * marks in weight as well as in stacking order. */
+const ICON_SCALE = 0.4;
+
+/**
+ * …and the weight a source's own icon is drawn at.
+ *
+ * The backend composes every one of them to one painted weight (`ICON_SIDE`),
+ * which is what makes a single number right here: a 16px road sign and a 512px
+ * badge come out of the same door, so a My Maps cannot have one group towering
+ * over another just because its creator uploaded a bigger PNG.
+ *
+ * Lower than the pictogram above it, because a real icon is a filled picture
+ * where ours is a stroked outline: at equal size the picture reads heavier, and
+ * these are somebody else's marks sitting under the case's own.
+ */
+const SOURCE_ICON_SCALE = 0.28;
+
+/**
+ * The white edge around every mark.
+ *
+ * A foreign layer is drawn in the source's own colours, and a source picks them
+ * against its own basemap — never against this case's imagery. A dark green pin
+ * on a field and a pale one on concrete both disappear. The outline is what
+ * makes the colour readable wherever the analyst happens to be looking, and it
+ * costs nothing: `icon-halo-*` only works on SDF icons, which is already the
+ * format chosen so the source's colour could tint our pictogram.
+ */
+const ICON_OUTLINE = '#fff';
+/** Enough to lift the mark off the ground under it, and no more: past about a
+ * pixel the edge starts reading as the mark and the colour as its filling. */
+const ICON_OUTLINE_WIDTH = 0.8;
+
+/**
+ * The frame a searched-for feature is shown in.
+ *
+ * A pin has no extent at all, so the box collapses to a point and the ceiling is
+ * what decides the zoom; a district frames itself. One rule for all three kinds,
+ * and the same numbers the map's other handoffs travel by (`Satellite.svelte`).
+ */
+const REVEAL_PADDING = [48, 48];
+const REVEAL_ZOOM = 17;
+
+/**
+ * How far off its point a card hangs.
+ *
+ * A pin stands above the ground it claims — its image is `ICON_PIXELS` tall,
+ * shown at `ICON_SCALE`, and pulled back down by the padding under its tip — so
+ * a card opened at the point itself would cover the mark that was clicked. An
+ * edge or an area is clicked where it is, and takes the smaller gap.
+ */
+const PIN_CARD_OFFSET = Math.round((ICON_PIXELS - ICON_PAD) * ICON_SCALE);
+const EDGE_CARD_OFFSET = 12;
+
+let layers = 0; // one id prefix per layer, so two of them never collide
+
+/** The card a feature opens, dressed like every other card on this map
+ * (`lib/map/engine.css`) and closed the same two ways: its own cross, or the
+ * next click anywhere. */
+function defaultPopup(offset) {
+ return new Popup({
+ className: 'added-layer-card',
+ closeOnClick: true,
+ focusAfterOpen: false,
+ maxWidth: '320px',
+ offset,
+ });
+}
+
+/** The image `addImage` knows a pictogram by. Shared: they are SDFs, so one
+ * copy serves every layer and every colour. */
+export function iconName(kind) {
+ return `azimut-layer-${kind}`;
+}
+
+/**
+ * …and the one it knows a source's own icon by.
+ *
+ * Shared between layers too, and safely: the key is the backend's content hash
+ * of what the icon *is* — its address, its colour, its scale, its anchor — so
+ * two layers naming the same key are asking for the same pixels. Two My Maps
+ * that both use Google's red pin register it once.
+ */
+export function sourceIconName(key) {
+ return `azimut-source-${key}`;
+}
+
+/** One composed icon, fetched from the case folder and decoded by the engine. */
+async function defaultLoadIcon(map, url) {
+ const loaded = await map.loadImage(url);
+ return loaded?.data ?? null;
+}
+
+/**
+ * A pictogram as a signed-distance-field image.
+ *
+ * SDF is the whole reason the colour rule works: MapLibre tints an SDF icon with
+ * `icon-color`, so the source's own colour paints our shape. A plain image would
+ * have to be re-registered per colour.
+ *
+ * The field is crude — inside the stroke is opaque, outside falls off over a few
+ * pixels — which is all a 48px pictogram needs, and it keeps this to a canvas
+ * and no dependency.
+ */
+export function iconImage(kind, size = ICON_PIXELS, make = defaultCanvas) {
+ const canvas = make(size, size);
+ const context = canvas.getContext('2d');
+ if (!context) return null;
+ context.clearRect(0, 0, size, size);
+ // inset, so the outline drawn outside the shape has pixels to live in
+ const scale = (size - ICON_PAD * 2) / 24;
+ context.setTransform(scale, 0, 0, scale, ICON_PAD, ICON_PAD);
+ context.strokeStyle = '#fff';
+ context.fillStyle = '#fff';
+ context.lineWidth = 2.4;
+ context.lineJoin = 'round';
+ context.lineCap = 'round';
+ const path = new Path2D(paths[GLYPHS[kind] ?? 'pin']);
+ if (kind === 'point') context.fill(path);
+ context.stroke(path);
+ context.setTransform(1, 0, 0, 1, 0, 0);
+
+ const pixels = context.getImageData(0, 0, size, size);
+ return { width: size, height: size, data: sdf(pixels.data, size, ICON_SPREAD) };
+}
+
+function defaultCanvas(width, height) {
+ const canvas = document.createElement('canvas');
+ canvas.width = width;
+ canvas.height = height;
+ return canvas;
+}
+
+/**
+ * Alpha → the distance field MapLibre reads.
+ *
+ * MapLibre treats an SDF's alpha channel as distance from the shape's edge, with
+ * 0.5 the edge itself. Drawn opaque, a pictogram already says inside from
+ * outside; this spreads that boundary over a few pixels so the icon has an edge
+ * to antialias rather than a cliff.
+ */
+function sdf(data, size, spread = ICON_SPREAD) {
+ const out = new Uint8ClampedArray(data.length);
+ const inside = (x, y) =>
+ x >= 0 && y >= 0 && x < size && y < size && data[(y * size + x) * 4 + 3] > 127;
+ for (let y = 0; y < size; y += 1) {
+ for (let x = 0; x < size; x += 1) {
+ const index = (y * size + x) * 4;
+ let distance = spread;
+ for (let radius = 0; radius <= spread && distance === spread; radius += 1) {
+ // the first ring at which this pixel disagrees with the one it is in
+ for (let dy = -radius; dy <= radius; dy += 1) {
+ for (let dx = -radius; dx <= radius; dx += 1) {
+ if (inside(x + dx, y + dy) !== inside(x, y)) {
+ distance = Math.min(distance, Math.hypot(dx, dy));
+ }
+ }
+ }
+ }
+ const signed = inside(x, y) ? distance : -distance;
+ out[index] = out[index + 1] = out[index + 2] = 255;
+ out[index + 3] = Math.round(((signed / spread) * 0.5 + 0.5) * 255);
+ }
+ }
+ return out;
+}
+
+/** Register the three pictograms once on a map, if they are not there already. */
+export function registerIcons(map, build = iconImage) {
+ for (const kind of Object.keys(GLYPHS)) {
+ const name = iconName(kind);
+ if (map.hasImage?.(name)) continue;
+ const image = build(kind);
+ if (image) map.addImage(name, image, { sdf: true });
+ }
+}
+
+/**
+ * What a category is painted, as one expression over the whole layer.
+ *
+ * Built as a `match` on the category name rather than resolved per feature into
+ * the data: the colour a legend row shows and the colour the map draws are then
+ * the same value read from the same place, and switching one cannot leave the
+ * other behind.
+ */
+export function colourExpression(categories = []) {
+ if (!categories.length) return categoryColour(null, 0);
+ const match = ['match', ['get', 'category']];
+ categories.forEach((category, index) => {
+ match.push(category.name, categoryColour(category, index));
+ });
+ match.push(categoryColour(null, 0));
+ return match;
+}
+
+/** Which features are drawn: everything, minus the categories switched off. */
+export function visibilityFilter(hidden = []) {
+ if (!hidden.length) return null;
+ return ['!', ['in', ['get', 'category'], ['literal', [...hidden]]]];
+}
+
+/**
+ * @param {object} engine the façade from `engine.js`
+ * @param {object} [opts]
+ * @param {(feature: object) => HTMLElement} [opts.card] the read-only popup's body
+ * @param {(offset: number) => object} [opts.popup] the card itself, swappable so
+ * the click path can be read off a test without standing up the engine's own popup
+ * @param {(key: string) => string} [opts.iconUrl] where this case keeps the
+ * source's composed icons. Absent — a layer added without the box ticked, or one
+ * whose icons could not be made — and every point draws the app's own pictogram.
+ * @param {(map: object, url: string) => Promise<object|null>} [opts.loadIcon]
+ */
+export function createAddedLayer(
+ engine,
+ { card, popup = defaultPopup, iconUrl = null, loadIcon = defaultLoadIcon } = {}
+) {
+ const map = engine.impl;
+ const prefix = `added-${++layers}`;
+ const SOURCE = `${prefix}-src`;
+ const FILL = `${prefix}-fill`;
+ const LINE = `${prefix}-line`;
+ const DOT = `${prefix}-dot`;
+ const MARK = `${prefix}-mark`;
+ const OWN = `${prefix}-own`;
+ const PAINTED = [FILL, LINE, DOT, MARK, OWN];
+
+ let built = false;
+ let shown = true;
+ let categories = [];
+ let collection = null; // what was last drawn, so a feature can be found by number
+ let open = null; // the read-only card, so it can be closed by name
+ let releaseClicks = null;
+ // Bumped by every `set` and by `destroy`, so a set whose icons were still
+ // loading when the layer moved on lands nowhere.
+ let generation = 0;
+ const listeners = [];
+
+ function build(attribution) {
+ if (built) return;
+ built = true;
+ registerIcons(map);
+ map.addSource(SOURCE, {
+ type: 'geojson',
+ data: { type: 'FeatureCollection', features: [] },
+ // the credit line the source is owed, picked up by the engine's own
+ // attribution control exactly as a curated overlay's is
+ attribution,
+ });
+ const colour = ['to-color', ['get', '$colour']];
+ map.addLayer({
+ id: FILL,
+ type: 'fill',
+ source: SOURCE,
+ filter: ['==', ['geometry-type'], 'Polygon'],
+ paint: { 'fill-color': colour, 'fill-opacity': 0.18 },
+ });
+ map.addLayer({
+ id: LINE,
+ type: 'line',
+ source: SOURCE,
+ filter: ['!=', ['geometry-type'], 'Point'],
+ layout: { 'line-cap': 'round', 'line-join': 'round' },
+ paint: { 'line-color': colour, 'line-width': 2, 'line-opacity': 0.9 },
+ });
+ // Under the symbols, and only while they are being dropped: far out, the
+ // collision below hides most of a dense layer, and a dot per feature is what
+ // keeps the map honest about how much is really there. Close in, every
+ // symbol is placed, so the same dot is just a bead stuck under each pin —
+ // it fades out over the zooms where that changes.
+ map.addLayer({
+ id: DOT,
+ type: 'circle',
+ source: SOURCE,
+ filter: ['==', ['geometry-type'], 'Point'],
+ paint: {
+ 'circle-radius': ['interpolate', ['linear'], ['zoom'], 11, 2.5, 14, 0],
+ 'circle-color': colour,
+ 'circle-opacity': 0.85,
+ },
+ });
+ map.addLayer({
+ id: MARK,
+ type: 'symbol',
+ source: SOURCE,
+ filter: ['all', ['==', ['geometry-type'], 'Point'], ['!', ['has', '$own']]],
+ layout: {
+ 'icon-image': ['get', '$icon'],
+ 'icon-size': ICON_SCALE,
+ 'icon-anchor': 'bottom',
+ // The decluttering, and the whole of it: MapLibre hides a symbol that
+ // overlaps one already placed, so the map spreads evenly and densifies
+ // as it is zoomed into. A cap in file order would clump.
+ 'icon-allow-overlap': false,
+ 'icon-ignore-placement': false,
+ // …and who wins a contested spot. File order, so the answer is at least
+ // the same one twice running.
+ 'symbol-sort-key': ['get', 'index'],
+ },
+ paint: {
+ 'icon-color': colour,
+ 'icon-opacity': 0.95,
+ 'icon-halo-color': ICON_OUTLINE,
+ 'icon-halo-width': ICON_OUTLINE_WIDTH,
+ 'icon-halo-blur': 0.2,
+ // The anchor is the image's bottom edge, and the padding that gives the
+ // outline room to draw sits between that edge and the pin's tip. Without
+ // this the pin floats its own padding above the ground, which reads as
+ // the dot underneath having come loose from it.
+ 'icon-translate': [0, ICON_PAD * ICON_SCALE],
+ },
+ });
+ // The source's own pictures, which is a separate layer rather than a second
+ // `icon-image` on the one above: these are plain PNGs, the ones above are
+ // SDFs, and MapLibre does not reliably render both out of one symbol layer.
+ // Everything SDF buys — the tint, the white outline — is already in these
+ // pixels, composed by the backend, so there is nothing to paint here.
+ map.addLayer({
+ id: OWN,
+ type: 'symbol',
+ source: SOURCE,
+ filter: ['all', ['==', ['geometry-type'], 'Point'], ['has', '$own']],
+ layout: {
+ 'icon-image': ['get', '$own'],
+ 'icon-size': SOURCE_ICON_SCALE,
+ // The anchor is the middle because the backend padded each image until
+ // the pixel the source anchors it by *was* the middle — a pin's tip
+ // lands on the ground without a per-feature offset to carry.
+ 'icon-anchor': 'center',
+ 'icon-allow-overlap': false,
+ 'icon-ignore-placement': false,
+ 'symbol-sort-key': ['get', 'index'],
+ },
+ paint: { 'icon-opacity': 0.95 },
+ });
+ bindHandlers();
+ if (!shown) applyVisibility();
+ }
+
+ /**
+ * The card, and the only thing a feature answers.
+ *
+ * Read-only by construction: it is given what the source states and offers no
+ * way out of itself. Nothing in an added layer enters the case.
+ */
+ function bindHandlers() {
+ const bind = (type, handler) => {
+ map.on(type, PAINTED, handler);
+ listeners.push([type, PAINTED, handler]);
+ };
+ bind('click', (event) => {
+ const feature = event.features?.[0];
+ if (!feature) return;
+ showCard(feature, event.lngLat);
+ });
+ bind('mouseenter', () => {
+ map.getCanvas().style.cursor = 'pointer';
+ });
+ bind('mouseleave', () => {
+ map.getCanvas().style.cursor = '';
+ });
+ releaseClicks = engine.claimClicks?.(PAINTED) ?? null;
+ }
+
+ /**
+ * Open the card on a feature, hung off the feature's own point.
+ *
+ * Not off the cursor: a pin is clicked on its head, a good twenty pixels above
+ * the ground it claims, and the two are then the same *ground* distance apart
+ * at every zoom — which shows on screen as the card sliding away from its own
+ * mark the further you zoom in. A point states where it is, so that is what
+ * the card is pinned to; an edge or an area has no one point, and is read
+ * where it was touched.
+ */
+ function showCard(feature, at) {
+ if (!card) return;
+ closeCard();
+ const point = feature.geometry?.type === 'Point' ? feature.geometry.coordinates : null;
+ open = popup(point ? PIN_CARD_OFFSET : EDGE_CARD_OFFSET)
+ .setLngLat(point ?? at)
+ .setDOMContent(card(feature.properties ?? {}))
+ .addTo(map);
+ open.on('close', () => {
+ open = null;
+ });
+ }
+
+ function closeCard() {
+ open?.remove();
+ open = null;
+ }
+
+ /**
+ * Register every source icon these features ask for, and say which arrived.
+ *
+ * The whole of the fallback, and the reason it needs no switch on the panel:
+ * a key that is not in the returned set is a key no feature is routed by, so
+ * an icon that 404s, decodes badly or times out leaves its features drawing
+ * the app's own pictogram in the source's colour. One layer being undressed is
+ * not a map that stopped working.
+ *
+ * All of them at once rather than in turn: they are a few dozen small files
+ * off localhost, and doing them serially would show as the icons appearing
+ * one by one.
+ */
+ async function registerSourceIcons(features) {
+ const arrived = new Set();
+ if (!iconUrl) return arrived;
+ const keys = new Set();
+ for (const feature of features) {
+ const key = feature?.properties?.icon;
+ if (key) keys.add(key);
+ }
+ await Promise.all(
+ [...keys].map(async (key) => {
+ const name = sourceIconName(key);
+ if (map.hasImage?.(name)) {
+ arrived.add(key);
+ return;
+ }
+ try {
+ const image = await loadIcon(map, iconUrl(key));
+ if (!image) return;
+ // checked again: two layers sharing an icon can both be loading it
+ if (!map.hasImage?.(name)) map.addImage(name, image);
+ arrived.add(key);
+ } catch {
+ /* this key's features keep the pictogram they already had */
+ }
+ })
+ );
+ return arrived;
+ }
+
+ function applyVisibility() {
+ for (const layer of PAINTED) {
+ if (map.getLayer(layer)) {
+ map.setLayoutProperty(layer, 'visibility', shown ? 'visible' : 'none');
+ }
+ }
+ }
+
+ return {
+ /**
+ * Put a parsed collection on the map. Every feature, every time: the source
+ * is the whole layer and the engine culls what is off screen.
+ */
+ async set(data, { categories: groups = [], hidden = [], attribution } = {}) {
+ build(attribution);
+ categories = groups;
+ collection = data;
+ const mine = ++generation;
+ // Before the data, not after: a feature is only routed to the source-icon
+ // layer once its image is registered, so there is no frame in which a
+ // point asks for a picture the map does not have and draws nothing.
+ const ready = await registerSourceIcons(data?.features ?? []);
+ if (mine !== generation || !built) return;
+
+ const colour = colourExpression(groups);
+ const features = (data?.features ?? []).map((feature) => ({
+ ...feature,
+ properties: {
+ ...feature.properties,
+ // Resolved into the data rather than expressed per layer, because the
+ // icon has to be chosen per feature and the colour has to fall back
+ // per feature when the source painted only some of them.
+ $icon: iconName(kindOf(feature.geometry)),
+ ...(ready.has(feature.properties?.icon)
+ ? { $own: sourceIconName(feature.properties.icon) }
+ : null),
+ },
+ }));
+ map.getSource(SOURCE)?.setData({ type: 'FeatureCollection', features });
+ for (const layer of PAINTED) {
+ if (layer === OWN || !map.getLayer(layer)) continue;
+ const property = layer === MARK ? 'icon-color' : layer === FILL ? 'fill-color' : layer === DOT ? 'circle-color' : 'line-color';
+ map.setPaintProperty(layer, property, featureColour(colour));
+ }
+ this.filter(hidden);
+ },
+
+ /**
+ * Hide exactly the categories named, and nothing else.
+ *
+ * A filter rather than a second source: the features stay loaded, so the row
+ * can keep saying how many there are while saying how many are drawn.
+ */
+ filter(hidden = []) {
+ if (!built) return;
+ const rule = visibilityFilter(hidden);
+ const base = {
+ [FILL]: ['==', ['geometry-type'], 'Polygon'],
+ [LINE]: ['!=', ['geometry-type'], 'Point'],
+ [DOT]: ['==', ['geometry-type'], 'Point'],
+ // The two symbol layers split the points between them on the one
+ // question of whether this feature's own icon is registered.
+ [MARK]: ['all', ['==', ['geometry-type'], 'Point'], ['!', ['has', '$own']]],
+ [OWN]: ['all', ['==', ['geometry-type'], 'Point'], ['has', '$own']],
+ };
+ for (const layer of PAINTED) {
+ if (!map.getLayer(layer)) continue;
+ map.setFilter(layer, rule ? ['all', base[layer], rule] : base[layer]);
+ }
+ closeCard();
+ },
+
+ /**
+ * Frame one feature and open its card — what picking a search result does.
+ *
+ * The second way into this layer, and deliberately the same one: it ends at
+ * the card a click ends at, which states what the source says and offers no
+ * route out of itself. Finding a feature is not adopting it.
+ *
+ * False when the number names nothing here, which is what a card opened on
+ * the wrong feature would otherwise be.
+ */
+ reveal(index) {
+ const feature = featureAt(collection, index);
+ const extent = feature && featureExtent(feature.geometry);
+ if (!extent) return false;
+ engine.fitBounds(extent, {
+ padding: REVEAL_PADDING,
+ maxZoom: REVEAL_ZOOM,
+ animate: true,
+ });
+ showCard(feature, [(extent.west + extent.east) / 2, (extent.south + extent.north) / 2]);
+ return true;
+ },
+
+ /** Keep the features, take them off the map (or put them back). */
+ visible(on) {
+ shown = on;
+ if (!built) return;
+ applyVisibility();
+ if (!on) closeCard();
+ },
+
+ /** What the legend is painting, so a caller can read it back. */
+ categories() {
+ return categories;
+ },
+
+ destroy() {
+ closeCard();
+ collection = null;
+ generation += 1;
+ releaseClicks?.();
+ releaseClicks = null;
+ for (const [type, on, handler] of listeners) map.off(type, on, handler);
+ listeners.length = 0;
+ if (built) {
+ for (const layer of PAINTED) {
+ if (map.getLayer(layer)) map.removeLayer(layer);
+ }
+ if (map.getSource(SOURCE)) map.removeSource(SOURCE);
+ }
+ built = false;
+ },
+ };
+}
+
+/**
+ * The source's own colour where it stated one, the category's where it did not.
+ *
+ * Per feature, because a My Maps often paints half a folder and leaves the rest
+ * on the default — and a legend row saying one colour while half its marks draw
+ * another is exactly the kind of quiet lie this feature must not tell.
+ */
+function featureColour(fallback) {
+ return ['case', ['!=', ['get', 'colour'], ''], ['to-color', ['get', 'colour']], fallback];
+}
+
+/**
+ * The feature the backend numbered `index`, or nothing.
+ *
+ * The number *is* the position — `_collection` writes it while it fills the
+ * array — so the hit is direct. The scan behind it costs nothing on the miss
+ * that cannot happen, and what it rules out is a card opened on the wrong
+ * feature, which on a map somebody makes decisions from is the failure worth
+ * two lines to refuse.
+ */
+export function featureAt(collection, index) {
+ const features = collection?.features ?? [];
+ const at = features[index];
+ if (at?.properties?.index === index) return at;
+ return features.find((feature) => feature?.properties?.index === index) ?? null;
+}
+
+/**
+ * Where one feature is, as a box to frame the camera on.
+ *
+ * A point gives a box with no extent, which the façade answers by clamping to
+ * the ceiling it was given — so a pin, a road and a district are one rule here
+ * rather than three. Nothing is materialised: a traced coastline is half a
+ * million points, and the four numbers are all that is wanted from them.
+ */
+export function featureExtent(geometry) {
+ let north = -Infinity;
+ let south = Infinity;
+ let east = -Infinity;
+ let west = Infinity;
+ eachCoordinate(geometry, (lon, lat) => {
+ west = Math.min(west, lon);
+ east = Math.max(east, lon);
+ south = Math.min(south, lat);
+ north = Math.max(north, lat);
+ });
+ return west > east ? null : { north, south, east, west };
+}
+
+/** Mirrors the backend's `_coordinates`: every position, however nested. */
+function eachCoordinate(geometry, visit) {
+ if (geometry?.type === 'GeometryCollection') {
+ for (const child of geometry.geometries ?? []) eachCoordinate(child, visit);
+ return;
+ }
+ walk(geometry?.coordinates, visit);
+}
+
+function walk(node, visit) {
+ if (!Array.isArray(node)) return;
+ if (node.length >= 2 && typeof node[0] === 'number' && typeof node[1] === 'number') {
+ visit(node[0], node[1]);
+ return;
+ }
+ for (const child of node) walk(child, visit);
+}
+
+/** Mirrors the backend's `_kind`: three shapes, and nothing finer. */
+export function kindOf(geometry) {
+ const type = String(geometry?.type ?? '');
+ if (type.includes('Point')) return 'point';
+ if (type.includes('Line')) return 'line';
+ return 'area';
+}
diff --git a/frontend/src/lib/map/addedLayer.test.js b/frontend/src/lib/map/addedLayer.test.js
new file mode 100644
index 0000000..66b965c
--- /dev/null
+++ b/frontend/src/lib/map/addedLayer.test.js
@@ -0,0 +1,577 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from 'vitest';
+import {
+ colourExpression,
+ createAddedLayer,
+ featureAt,
+ featureExtent,
+ iconName,
+ kindOf,
+ registerIcons,
+ visibilityFilter,
+} from './addedLayer.js';
+import { PALETTE } from './addedLayers.js';
+
+/**
+ * Read off a stubbed map, because what this module has to get right is *which
+ * MapLibre primitives a foreign layer becomes*: a GL source with style layers
+ * rather than a DOM marker each, a filter rather than a second source, and an
+ * icon registered at runtime rather than a sprite the engine would have to load.
+ */
+
+function stubMap() {
+ const sources = new Map();
+ const layers = new Map();
+ const images = new Set();
+ const handlers = [];
+ return {
+ sources,
+ layers,
+ images,
+ handlers,
+ addSource: (id, spec) => sources.set(id, { ...spec, data: spec.data }),
+ getSource: (id) =>
+ sources.has(id)
+ ? { setData: (data) => sources.set(id, { ...sources.get(id), data }) }
+ : undefined,
+ removeSource: (id) => sources.delete(id),
+ addLayer: (layer) => layers.set(layer.id, { ...layer }),
+ getLayer: (id) => layers.get(id),
+ removeLayer: (id) => layers.delete(id),
+ setFilter: (id, filter) => layers.set(id, { ...layers.get(id), filter }),
+ setPaintProperty: (id, key, value) =>
+ layers.set(id, { ...layers.get(id), paint: { ...layers.get(id).paint, [key]: value } }),
+ setLayoutProperty: (id, key, value) =>
+ layers.set(id, { ...layers.get(id), layout: { ...layers.get(id).layout, [key]: value } }),
+ hasImage: (name) => images.has(name),
+ addImage: (name) => images.add(name),
+ getCanvas: () => ({ style: {} }),
+ on: (type, on, handler) => handlers.push([type, on, handler]),
+ off: (type, on, handler) => {
+ const index = handlers.findIndex((entry) => entry[2] === handler);
+ if (index >= 0) handlers.splice(index, 1);
+ },
+ };
+}
+
+function stubEngine() {
+ const map = stubMap();
+ return { impl: map, claimClicks: vi.fn(() => vi.fn()), fitBounds: vi.fn(), map };
+}
+
+/** The card, caught rather than drawn: what it was handed and where it was hung. */
+function stubCard() {
+ const popup = {
+ setLngLat: (at) => ((popup.at = at), popup),
+ setDOMContent: (node) => ((popup.body = node), popup),
+ addTo: () => popup,
+ on: () => popup,
+ remove: () => ((popup.gone = true), popup),
+ };
+ const card = vi.fn((properties) => {
+ const element = document.createElement('div');
+ element.textContent = properties.name;
+ return element;
+ });
+ return { card, popup, opts: { card, popup: (offset) => ((popup.offset = offset), popup) } };
+}
+
+const COLLECTION = {
+ type: 'FeatureCollection',
+ features: [
+ {
+ type: 'Feature',
+ geometry: { type: 'Point', coordinates: [2.35, 48.85] },
+ properties: { name: 'North gate', category: 'Checkpoints', colour: '#ff0000', index: 0 },
+ },
+ {
+ type: 'Feature',
+ geometry: { type: 'Polygon', coordinates: [[[2, 48], [2.1, 48], [2.1, 48.1], [2, 48]]] },
+ properties: { name: 'Warehouse', category: 'Damage', colour: '', index: 1 },
+ },
+ ],
+};
+
+const CATEGORIES = [
+ { name: 'Checkpoints', count: 1, colour: '#ff0000' },
+ { name: 'Damage', count: 1, colour: '' },
+];
+
+/** The same layer, with the backend saying its point has a pictogram of its own. */
+const DRESSED = {
+ type: 'FeatureCollection',
+ features: [
+ {
+ ...COLLECTION.features[0],
+ properties: { ...COLLECTION.features[0].properties, icon: 'abc123' },
+ },
+ COLLECTION.features[1],
+ ],
+};
+
+/** Which symbol layer is which, told apart by the image each one draws. */
+function symbolLayers(engine) {
+ const symbols = [...engine.map.layers.values()].filter((layer) => layer.type === 'symbol');
+ const drawing = (property) =>
+ symbols.find((layer) => layer.layout['icon-image']?.[1] === property);
+ return { own: drawing('$own'), fallback: drawing('$icon') };
+}
+
+describe('the translation to MapLibre', () => {
+ it('puts a category colour in one expression rather than into every feature', () => {
+ // the legend row and the marks then read the same value from the same place
+ expect(colourExpression(CATEGORIES)).toEqual([
+ 'match',
+ ['get', 'category'],
+ 'Checkpoints',
+ '#ff0000',
+ 'Damage',
+ PALETTE[1],
+ PALETTE[0],
+ ]);
+ });
+
+ it('turns hidden categories into a filter and nothing into no filter at all', () => {
+ expect(visibilityFilter([])).toBeNull();
+ expect(visibilityFilter(['Damage'])).toEqual([
+ '!',
+ ['in', ['get', 'category'], ['literal', ['Damage']]],
+ ]);
+ });
+
+ it('knows three shapes and nothing finer, as the backend does', () => {
+ expect(kindOf({ type: 'MultiPoint' })).toBe('point');
+ expect(kindOf({ type: 'LineString' })).toBe('line');
+ expect(kindOf({ type: 'MultiPolygon' })).toBe('area');
+ });
+});
+
+describe('the icons', () => {
+ it('registers one image per shape, as an SDF so a colour can tint it', () => {
+ const map = stubMap();
+ const added = [];
+ map.addImage = (name, image, options) => {
+ map.images.add(name);
+ added.push([name, options]);
+ };
+
+ registerIcons(map, () => ({ width: 1, height: 1, data: new Uint8ClampedArray(4) }));
+
+ expect(added.map(([name]) => name)).toEqual([
+ iconName('point'),
+ iconName('line'),
+ iconName('area'),
+ ]);
+ // without `sdf`, honouring a source's colour would mean one registered
+ // image per (shape × colour) pair
+ expect(added.every(([, options]) => options.sdf)).toBe(true);
+ });
+
+ it('registers each image once, however many layers ask for it', () => {
+ const map = stubMap();
+ const build = vi.fn(() => ({ width: 1, height: 1, data: new Uint8ClampedArray(4) }));
+
+ registerIcons(map, build);
+ registerIcons(map, build);
+
+ expect(build).toHaveBeenCalledTimes(3);
+ });
+});
+
+/**
+ * The source's own pictograms, which the backend already composed into PNGs.
+ *
+ * What this side has to get right is the routing and the fallback: a point whose
+ * icon arrived draws it out of a non-SDF layer, a point whose icon did not draws
+ * the app's tinted shape, and neither decision can be made before the image is
+ * registered — a symbol asking for an image the map does not hold draws nothing.
+ */
+describe("a source's own icons", () => {
+ const source = (url = '/icons') => ({
+ iconUrl: (key) => `${url}/${key}`,
+ loadIcon: vi.fn(async () => ({ width: 8, height: 8, data: new Uint8ClampedArray(256) })),
+ });
+
+ it('asks this server for the icon, by the key the feature carries', async () => {
+ const engine = stubEngine();
+ const opts = source('/api/cases/c1/map-layers/roads/icons');
+
+ await createAddedLayer(engine, opts).set(DRESSED, { categories: CATEGORIES });
+
+ expect(opts.loadIcon).toHaveBeenCalledTimes(1);
+ expect(opts.loadIcon.mock.calls[0][1]).toBe(
+ '/api/cases/c1/map-layers/roads/icons/abc123'
+ );
+ });
+
+ it('registers it without the SDF flag, because the colour is already in it', async () => {
+ const engine = stubEngine();
+ const added = [];
+ engine.map.addImage = (name, image, options) => {
+ engine.map.images.add(name);
+ added.push([name, options]);
+ };
+
+ await createAddedLayer(engine, source()).set(DRESSED, { categories: CATEGORIES });
+
+ const [, options] = added.find(([name]) => name.includes('abc123'));
+ expect(options).toBeUndefined();
+ });
+
+ it('routes the point to the layer that draws pictures, not the tinted one', async () => {
+ const engine = stubEngine();
+
+ await createAddedLayer(engine, source()).set(DRESSED, { categories: CATEGORIES });
+
+ const [stored] = [...engine.map.sources.values()];
+ const [point] = stored.data.features;
+ expect(point.properties.$own).toBe('azimut-source-abc123');
+ const { own } = symbolLayers(engine);
+ expect(own.layout['icon-anchor']).toBe('center');
+ });
+
+ it('leaves a point whose icon never arrived on the app pictogram', async () => {
+ const engine = stubEngine();
+ const opts = { iconUrl: (key) => `/icons/${key}`, loadIcon: vi.fn(async () => null) };
+
+ await createAddedLayer(engine, opts).set(DRESSED, { categories: CATEGORIES });
+
+ const [stored] = [...engine.map.sources.values()];
+ expect(stored.data.features[0].properties.$own).toBeUndefined();
+ expect(stored.data.features[0].properties.$icon).toBe(iconName('point'));
+ });
+
+ it('survives an icon that throws, which is what a 404 arrives as', async () => {
+ const engine = stubEngine();
+ const opts = {
+ iconUrl: (key) => `/icons/${key}`,
+ loadIcon: vi.fn(async () => {
+ throw new Error('404');
+ }),
+ };
+
+ await createAddedLayer(engine, opts).set(DRESSED, { categories: CATEGORIES });
+
+ const [stored] = [...engine.map.sources.values()];
+ expect(stored.data.features).toHaveLength(2);
+ expect(stored.data.features[0].properties.$own).toBeUndefined();
+ });
+
+ it('asks for nothing at all when the layer stored no icons', async () => {
+ const engine = stubEngine();
+ const loadIcon = vi.fn();
+
+ await createAddedLayer(engine, { loadIcon }).set(DRESSED, { categories: CATEGORIES });
+
+ expect(loadIcon).not.toHaveBeenCalled();
+ const [stored] = [...engine.map.sources.values()];
+ expect(stored.data.features[0].properties.$own).toBeUndefined();
+ });
+
+ it('fetches one icon once, however many features wear it', async () => {
+ const engine = stubEngine();
+ const opts = source();
+ const crowd = {
+ type: 'FeatureCollection',
+ features: [0, 1, 2, 3].map((index) => ({
+ type: 'Feature',
+ geometry: { type: 'Point', coordinates: [index, 48] },
+ properties: { category: 'Checkpoints', colour: '', icon: 'abc123', index },
+ })),
+ };
+
+ await createAddedLayer(engine, opts).set(crowd, { categories: CATEGORIES });
+
+ expect(opts.loadIcon).toHaveBeenCalledTimes(1);
+ });
+
+ it('keeps the two symbol layers apart under a category filter', async () => {
+ const engine = stubEngine();
+ const layer = createAddedLayer(engine, source());
+ await layer.set(DRESSED, { categories: CATEGORIES });
+
+ layer.filter(['Damage']);
+
+ const { own, fallback } = symbolLayers(engine);
+ expect(JSON.stringify(own.filter)).toContain('"$own"');
+ expect(JSON.stringify(fallback.filter)).toContain('"!"');
+ // and both still drop the hidden group
+ expect(JSON.stringify(own.filter)).toContain('Damage');
+ expect(JSON.stringify(fallback.filter)).toContain('Damage');
+ });
+
+ it('lands nowhere when the layer was torn down while its icons loaded', async () => {
+ const engine = stubEngine();
+ let release;
+ const layer = createAddedLayer(engine, {
+ iconUrl: (key) => `/icons/${key}`,
+ loadIcon: () => new Promise((resolve) => (release = resolve)),
+ });
+
+ const pending = layer.set(DRESSED, { categories: CATEGORIES });
+ layer.destroy();
+ release({ width: 8, height: 8, data: new Uint8ClampedArray(256) });
+ await pending;
+
+ expect(engine.map.sources.size).toBe(0);
+ });
+});
+
+describe('an added layer on the map', () => {
+ it('is one GeoJSON source with style layers, not a marker per feature', async () => {
+ const engine = stubEngine();
+ await createAddedLayer(engine).set(COLLECTION, { categories: CATEGORIES });
+
+ expect(engine.map.sources.size).toBe(1);
+ // Two symbol layers, because a source's own icons are plain PNGs and ours
+ // are SDFs, and MapLibre does not render both out of one.
+ expect([...engine.map.layers.values()].map((layer) => layer.type).sort()).toEqual([
+ 'circle',
+ 'fill',
+ 'line',
+ 'symbol',
+ 'symbol',
+ ]);
+ });
+
+ it('loads every feature and lets the engine cull, rather than truncating', async () => {
+ const engine = stubEngine();
+ await createAddedLayer(engine).set(COLLECTION, { categories: CATEGORIES });
+
+ const [source] = [...engine.map.sources.values()];
+ expect(source.data.features).toHaveLength(COLLECTION.features.length);
+ });
+
+ it('declutters by collision rather than by a cap taken in file order', async () => {
+ // a KML is ordered by folder or by creation, never by geography, so a cap
+ // would clump; MapLibre dropping an overlapping symbol spreads evenly
+ const engine = stubEngine();
+ await createAddedLayer(engine).set(COLLECTION, { categories: CATEGORIES });
+
+ const marks = [...engine.map.layers.values()].find((layer) => layer.type === 'symbol');
+ expect(marks.layout['icon-allow-overlap']).toBe(false);
+ expect(marks.layout['symbol-sort-key']).toEqual(['get', 'index']);
+ });
+
+ it('draws no text, because the engine loads no glyphs and will not start', async () => {
+ const engine = stubEngine();
+ await createAddedLayer(engine).set(COLLECTION, { categories: CATEGORIES });
+
+ for (const layer of engine.map.layers.values()) {
+ expect(layer.layout?.['text-field']).toBeUndefined();
+ }
+ });
+
+ it('carries the source its credit line, as a curated overlay does', async () => {
+ const engine = stubEngine();
+ await createAddedLayer(engine).set(COLLECTION, {
+ categories: CATEGORIES,
+ attribution: 'Sightings — Google My Maps',
+ });
+
+ const [source] = [...engine.map.sources.values()];
+ expect(source.attribution).toBe('Sightings — Google My Maps');
+ });
+
+ it('hides exactly the category named, and keeps the features loaded', async () => {
+ const engine = stubEngine();
+ const layer = createAddedLayer(engine);
+ await layer.set(COLLECTION, { categories: CATEGORIES });
+
+ layer.filter(['Damage']);
+
+ for (const drawn of engine.map.layers.values()) {
+ expect(JSON.stringify(drawn.filter)).toContain('Damage');
+ }
+ const [source] = [...engine.map.sources.values()];
+ expect(source.data.features).toHaveLength(2);
+ });
+
+ it('puts the filter back when the category is switched on again', async () => {
+ const engine = stubEngine();
+ const layer = createAddedLayer(engine);
+ await layer.set(COLLECTION, { categories: CATEGORIES });
+ layer.filter(['Damage']);
+
+ layer.filter([]);
+
+ for (const drawn of engine.map.layers.values()) {
+ expect(JSON.stringify(drawn.filter)).not.toContain('Damage');
+ }
+ });
+
+ it('keeps the features and takes them off the map when switched off', async () => {
+ const engine = stubEngine();
+ const layer = createAddedLayer(engine);
+ await layer.set(COLLECTION, { categories: CATEGORIES });
+
+ layer.visible(false);
+
+ for (const drawn of engine.map.layers.values()) {
+ expect(drawn.layout.visibility).toBe('none');
+ }
+ expect(engine.map.sources.size).toBe(1);
+ });
+
+ it('drops its source and its layers when it is removed', async () => {
+ const engine = stubEngine();
+ const layer = createAddedLayer(engine);
+ await layer.set(COLLECTION, { categories: CATEGORIES });
+
+ layer.destroy();
+
+ expect(engine.map.sources.size).toBe(0);
+ expect(engine.map.layers.size).toBe(0);
+ expect(engine.map.handlers).toHaveLength(0);
+ });
+
+ it('opens a read-only card and offers no way into the case from it', async () => {
+ const engine = stubEngine();
+ const card = vi.fn((properties) => {
+ const element = document.createElement('div');
+ element.textContent = properties.name;
+ return element;
+ });
+ const popup = {
+ setLngLat: () => popup,
+ setDOMContent: (node) => ((popup.body = node), popup),
+ addTo: () => popup,
+ on: () => popup,
+ remove: () => popup,
+ };
+ await createAddedLayer(engine, { card, popup: () => popup }).set(COLLECTION, {
+ categories: CATEGORIES,
+ });
+
+ const [, , click] = engine.map.handlers.find(([type]) => type === 'click');
+ click({ lngLat: [2.35, 48.85], features: [COLLECTION.features[0]] });
+
+ expect(card).toHaveBeenCalledWith(COLLECTION.features[0].properties);
+ // nothing to confirm, nothing to save, no path out of it into the case
+ expect(popup.body.querySelectorAll('button, a, input, form')).toHaveLength(0);
+ });
+
+ it('pins the card to the point, not to the spot on the pin that was clicked', async () => {
+ // A pin is clicked on its head, twenty-odd pixels above the ground it claims
+ // — and that gap, taken as a lngLat, is the same *ground* distance at every
+ // zoom. Anchored on the click, the card slides off its own mark as the map
+ // is zoomed in, which is the bug this is here to keep fixed.
+ const engine = stubEngine();
+ const { popup, opts } = stubCard();
+ await createAddedLayer(engine, opts).set(COLLECTION, { categories: CATEGORIES });
+ const [, , click] = engine.map.handlers.find(([type]) => type === 'click');
+
+ click({ lngLat: [2.3502, 48.8504], features: [COLLECTION.features[0]] });
+
+ expect(popup.at).toEqual([2.35, 48.85]);
+ // and hung off it by the pin's own drawn height, or it opens over the mark
+ expect(popup.offset).toBe(22);
+
+ // an area has no one point, so it is read where it was touched
+ click({ lngLat: [2.05, 48.05], features: [COLLECTION.features[1]] });
+
+ expect(popup.at).toEqual([2.05, 48.05]);
+ expect(popup.offset).toBeLessThan(22);
+ });
+});
+
+/**
+ * Going to one feature, which is what picking a search result does.
+ *
+ * The rule under all of it: finding a feature ends where clicking one ends — at
+ * the read-only card. There is no second, richer thing a search can open.
+ */
+describe('going to one feature', () => {
+ it('boxes a point, a line and an area by one rule', () => {
+ // a point has no extent, so the box collapses and the zoom ceiling decides
+ expect(featureExtent({ type: 'Point', coordinates: [2.35, 48.85] })).toEqual({
+ west: 2.35,
+ east: 2.35,
+ south: 48.85,
+ north: 48.85,
+ });
+ expect(
+ featureExtent({ type: 'LineString', coordinates: [[2, 48], [3, 49], [2.5, 47]] })
+ ).toEqual({ west: 2, east: 3, south: 47, north: 49 });
+ expect(featureExtent(COLLECTION.features[1].geometry)).toEqual({
+ west: 2,
+ east: 2.1,
+ south: 48,
+ north: 48.1,
+ });
+ });
+
+ it('reaches into a MultiPolygon and a GeometryCollection alike', () => {
+ expect(
+ featureExtent({
+ type: 'GeometryCollection',
+ geometries: [
+ { type: 'Point', coordinates: [1, 1] },
+ { type: 'MultiPolygon', coordinates: [[[[5, 5], [6, 5], [6, 6], [5, 5]]]] },
+ ],
+ })
+ ).toEqual({ west: 1, east: 6, south: 1, north: 6 });
+ });
+
+ it('has no box for a geometry with no positions in it', () => {
+ expect(featureExtent({ type: 'Polygon', coordinates: [] })).toBe(null);
+ expect(featureExtent(null)).toBe(null);
+ });
+
+ it('finds a feature by the number the backend gave it, not by luck', () => {
+ // the number is the position, so the hit is direct…
+ expect(featureAt(COLLECTION, 1)).toBe(COLLECTION.features[1]);
+ // …and a collection that arrived in another order still answers correctly,
+ // because a card opened on the wrong feature is the failure to refuse
+ const shuffled = { features: [...COLLECTION.features].reverse() };
+ expect(featureAt(shuffled, 0)).toBe(COLLECTION.features[0]);
+ expect(featureAt(COLLECTION, 7)).toBe(null);
+ });
+
+ it('frames the feature and opens the same card a click opens', async () => {
+ const engine = stubEngine();
+ const { card, popup, opts } = stubCard();
+ const layer = createAddedLayer(engine, opts);
+ await layer.set(COLLECTION, { categories: CATEGORIES });
+
+ expect(layer.reveal(1)).toBe(true);
+
+ expect(engine.fitBounds).toHaveBeenCalledWith(
+ { west: 2, east: 2.1, south: 48, north: 48.1 },
+ expect.objectContaining({ maxZoom: 17, animate: true })
+ );
+ expect(card).toHaveBeenCalledWith(COLLECTION.features[1].properties);
+ // nothing to confirm, nothing to save: a found feature is not an adopted one
+ expect(popup.body.querySelectorAll('button, a, input, form')).toHaveLength(0);
+ });
+
+ it('hangs the card off the pin itself when the feature is a point', async () => {
+ const engine = stubEngine();
+ const { popup, opts } = stubCard();
+ const layer = createAddedLayer(engine, opts);
+ await layer.set(COLLECTION, { categories: CATEGORIES });
+
+ layer.reveal(0);
+
+ expect(popup.at).toEqual([2.35, 48.85]);
+ });
+
+ it('goes nowhere at all for a number that names no feature', async () => {
+ const engine = stubEngine();
+ const { card, opts } = stubCard();
+ const layer = createAddedLayer(engine, opts);
+ await layer.set(COLLECTION, { categories: CATEGORIES });
+
+ expect(layer.reveal(9)).toBe(false);
+
+ expect(engine.fitBounds).not.toHaveBeenCalled();
+ expect(card).not.toHaveBeenCalled();
+ });
+
+ it('has nothing to go to before the features have landed', () => {
+ const engine = stubEngine();
+
+ expect(createAddedLayer(engine, stubCard().opts).reveal(0)).toBe(false);
+ expect(engine.fitBounds).not.toHaveBeenCalled();
+ });
+});
diff --git a/frontend/src/lib/map/addedLayers.js b/frontend/src/lib/map/addedLayers.js
new file mode 100644
index 0000000..8a8b4c3
--- /dev/null
+++ b/frontend/src/lib/map/addedLayers.js
@@ -0,0 +1,250 @@
+/**
+ * The layers the analyst added themselves, as the panel reads them.
+ *
+ * The curated stack in `tools.js` is what Azimut chose; this is what the analyst
+ * chose — a KMZ somebody sent them, a My Maps they follow. That is the line
+ * between the panel's two sections, not local versus remote: both halves of this
+ * feature land in the same list, because the question a row answers is "who put
+ * this on my map".
+ *
+ * Everything here is arithmetic over what the backend returned, so the rules the
+ * row states — how fresh it is, how many of its features are drawn, what colour
+ * a legend line is — are read off a test rather than off a map
+ * (`addedLayers.test.js`). The MapLibre side is `addedLayer.js`; the fetching and
+ * parsing are the backend's (`engine/maplayers.py`), and the browser never sees
+ * a byte of KML.
+ */
+import { timeAgo } from '../analysisViews.js';
+import { matchesTerms } from '../folderBrowse.js';
+
+/**
+ * Colours for a category whose source painted it nothing.
+ *
+ * A My Maps creator groups by colour far more than by icon, so an honoured
+ * colour is the meaning; this is only what fills in for a source that stated
+ * none. Picked to stay apart from each other and off the case's own marks, which
+ * are the accent — a foreign layer must never read as this case's work.
+ */
+export const PALETTE = [
+ '#5ac8fa',
+ '#ffcc66',
+ '#a0e57a',
+ '#ff8fa3',
+ '#c58af9',
+ '#6fd3c7',
+ '#f3a26d',
+ '#9aa7ff',
+];
+
+/** Past this a snapshot is old enough that the row says so before it redraws. */
+export const FRESH_FOR_HOURS = 24;
+
+/**
+ * The colour a category is drawn in: what the source said, else the palette.
+ *
+ * Keyed by position rather than by name so two layers holding a "Checkpoints"
+ * each do not come out the same colour — the index is within one layer.
+ */
+export function categoryColour(category, index) {
+ return category?.colour || PALETTE[index % PALETTE.length];
+}
+
+/** The legend, which is also the filter: one row per category, in the source's
+ * own order of weight. `on` is what the eye beside it shows. */
+export function legend(layer) {
+ const hidden = new Set(layer?.hidden ?? []);
+ return (layer?.categories ?? []).map((category, index) => ({
+ name: category.name,
+ count: category.count ?? 0,
+ kinds: category.kinds ?? [],
+ colour: categoryColour(category, index),
+ on: !hidden.has(category.name),
+ }));
+}
+
+/**
+ * What is loaded, and what is drawn — never the one passing for the other.
+ *
+ * Visible means "not filtered out here". It is deliberately *not* what is on
+ * screen: the engine culls to the viewport and drops symbols that collide, so a
+ * screen count would change on every pan and cost a render query per frame to
+ * read. A number that moved while nobody touched anything would be worse than no
+ * number at all.
+ */
+export function counts(layer) {
+ const loaded = layer?.features ?? 0;
+ const hidden = new Set(layer?.hidden ?? []);
+ const dropped = (layer?.categories ?? [])
+ .filter((category) => hidden.has(category.name))
+ .reduce((total, category) => total + (category.count ?? 0), 0);
+ return { loaded, visible: Math.max(0, loaded - dropped) };
+}
+
+/**
+ * `3 200` — grouped, because five digits of features run together otherwise.
+ *
+ * A narrow no-break space (U+202F), so a count never wraps across two lines of a
+ * panel this narrow and reads as two separate numbers.
+ */
+export const GROUP_SPACE = '\u202f';
+
+export function grouped(value) {
+ return String(Math.round(Number(value) || 0)).replace(
+ /\B(?=(\d{3})+(?!\d))/g,
+ GROUP_SPACE
+ );
+}
+
+/** The row's counter, stating both numbers whenever they differ. */
+export function countLabel(layer) {
+ const { loaded, visible } = counts(layer);
+ const features = `${grouped(loaded)} ${loaded === 1 ? 'feature' : 'features'}`;
+ return visible === loaded ? features : `${features} · ${grouped(visible)} shown`;
+}
+
+/**
+ * How fresh what is drawn actually is.
+ *
+ * The worst thing this feature could do is draw week-old data on a map where
+ * decisions get made and say nothing, so a stale subscription says so on the row
+ * — before anyone reads the marks, not after. A file says when it was opened and
+ * nothing more: it is exactly what the analyst dropped in, and it was never
+ * going to change on its own.
+ */
+export function freshness(layer, now = Date.now()) {
+ if (!layer) return '';
+ if (layer.source?.kind !== 'url') {
+ const at = timeAgo(layer.fetched_at, now);
+ return at ? `opened ${at}` : '';
+ }
+ const at = layer.checked_at || layer.fetched_at;
+ const said = timeAgo(at, now);
+ if (!said) return 'never read';
+ return layer.stale ? `stale — last read ${said}` : `read ${said}`;
+}
+
+/** Where a row came from, in the width a row has. */
+export function sourceLabel(layer) {
+ const source = layer?.source ?? {};
+ if (source.kind !== 'url') return source.name || 'a file on this computer';
+ if (source.my_maps) return 'Google My Maps';
+ try {
+ return new URL(source.url).hostname.replace(/^www\./, '');
+ } catch {
+ return source.url || '';
+ }
+}
+
+/**
+ * The credit line a layer owes its source.
+ *
+ * The curated overlays each declare one (`basemap.js`), and a map somebody else
+ * drew is owed the same. A My Maps has an author we cannot read from the feed,
+ * so the map's own title and the platform are what can honestly be stated.
+ */
+export function attribution(layer) {
+ const title = layer?.title || 'Added layer';
+ const source = layer?.source ?? {};
+ if (source.my_maps) return `${title} — Google My Maps`;
+ if (source.kind === 'url') return `${title} — ${sourceLabel(layer)}`;
+ return `${title} — added by the analyst`;
+}
+
+/** Which layers a case open should re-read: enabled, subscribed, and asked to. */
+export function refreshable(layers = []) {
+ return layers.filter(
+ (layer) =>
+ layer.enabled && layer.source?.kind === 'url' && layer.refresh?.on_open !== false
+ );
+}
+
+/** Which layers the map should actually be drawing. */
+export function drawable(layers = []) {
+ return layers.filter((layer) => layer.enabled);
+}
+
+/** One category switched, as the PATCH body expects it: the whole hidden list. */
+export function toggleCategory(layer, name) {
+ const hidden = new Set(layer?.hidden ?? []);
+ if (hidden.has(name)) hidden.delete(name);
+ else hidden.add(name);
+ return [...hidden];
+}
+
+/** What a feature the source never named is called, wherever it is shown. */
+export const UNNAMED = 'Unnamed feature';
+
+/**
+ * How many matches one search lists.
+ *
+ * The panel is 300px wide and a match is a line in it. Past this the list is
+ * something to scroll rather than something to read, so the tally says how many
+ * were found and the search is what narrows them.
+ */
+export const SEARCH_LIMIT = 25;
+
+/**
+ * The features of one layer whose name or group matches what was typed.
+ *
+ * **A finder, not a filter.** The legend beside it is the filter: it is
+ * persisted on the spec and it is what `countLabel` counts. A search is
+ * ephemeral and changes nothing about what the map draws — a row that said
+ * "3 200 features · 412 shown" while somebody typed would be stating a filter
+ * nobody set.
+ *
+ * **Names and groups only, never descriptions.** A description runs to
+ * `MAX_DESCRIPTION` characters and a layer to `MAX_FEATURES` of them
+ * (`engine/maplayers.py`), so reading them on every keystroke would make this
+ * the most expensive thing in the app — for a gain an analyst rarely asks for,
+ * since what anyone remembers of somebody else's map is what it called a place.
+ *
+ * Counted in full and listed in part: the tally is what says to narrow the
+ * search rather than scroll it.
+ */
+export function searchFeatures(collection, query, options = {}) {
+ const { categories = [], hidden = [], limit = SEARCH_LIMIT } = options;
+ const terms = String(query ?? '').trim();
+ if (!terms) return { total: 0, results: [] };
+
+ const colours = new Map(
+ (categories ?? []).map((category, index) => [category.name, categoryColour(category, index)])
+ );
+ const off = new Set(hidden ?? []);
+ const results = [];
+ let total = 0;
+
+ (collection?.features ?? []).forEach((feature, position) => {
+ const properties = feature?.properties ?? {};
+ const category = properties.category ?? '';
+ if (!matchesTerms(`${properties.name ?? ''} ${category}`, terms)) return;
+ total += 1;
+ if (results.length >= limit) return;
+ results.push({
+ // What the backend numbered this feature, so going to it is a lookup
+ // rather than a second copy of the geometry in the panel.
+ index: properties.index ?? position,
+ name: properties.name || UNNAMED,
+ category,
+ // The source's own colour where it painted one, its group's where it did
+ // not — the same rule the marks are drawn by (`addedLayer.js`).
+ colour: properties.colour || colours.get(category) || categoryColour(null, 0),
+ // A match in a group the legend switched off: it is a real feature, it is
+ // simply not on the map until that group comes back.
+ hidden: off.has(category),
+ });
+ });
+ return { total, results };
+}
+
+/**
+ * What the `+` accepts. A pasted address subscribes; anything else is a file.
+ *
+ * Said here so the button and the dialog cannot disagree about which half of the
+ * feature a given input lands in.
+ */
+export function looksLikeUrl(value) {
+ return /^https?:\/\/\S+$/i.test(String(value ?? '').trim());
+}
+
+/** The formats the file picker offers, and the parser accepts. */
+export const ACCEPTS = '.geojson,.json,.kml,.kmz,.gpx';
diff --git a/frontend/src/lib/map/addedLayers.test.js b/frontend/src/lib/map/addedLayers.test.js
new file mode 100644
index 0000000..1cec949
--- /dev/null
+++ b/frontend/src/lib/map/addedLayers.test.js
@@ -0,0 +1,280 @@
+import { describe, expect, it } from 'vitest';
+import {
+ ACCEPTS,
+ attribution,
+ categoryColour,
+ countLabel,
+ counts,
+ drawable,
+ GROUP_SPACE,
+ freshness,
+ legend,
+ looksLikeUrl,
+ PALETTE,
+ refreshable,
+ searchFeatures,
+ SEARCH_LIMIT,
+ sourceLabel,
+ toggleCategory,
+ UNNAMED,
+} from './addedLayers.js';
+
+/**
+ * What a row says about a layer nobody in this case made.
+ *
+ * Two of these rules are the feature's whole honesty: the counter never lets the
+ * number of drawn marks pass for the number of loaded ones, and a subscription
+ * whose snapshot has aged says so on the row rather than after the fact.
+ */
+
+const NOW = Date.parse('2026-09-17T12:00:00Z');
+
+const layer = (over = {}) => ({
+ name: 'Sightings',
+ title: 'Sightings',
+ source: { kind: 'file', name: 'sightings.kml' },
+ enabled: true,
+ hidden: [],
+ features: 3200,
+ categories: [
+ { name: 'Checkpoints', count: 2788, colour: '#ff0000', kinds: ['point'] },
+ { name: 'Damage', count: 412, colour: '', kinds: ['area'] },
+ ],
+ fetched_at: '2026-09-17T10:00:00Z',
+ checked_at: '2026-09-17T10:00:00Z',
+ stale: false,
+ ...over,
+});
+
+describe('the counter states both numbers', () => {
+ it('counts what is loaded and what is not filtered out', () => {
+ expect(counts(layer())).toEqual({ loaded: 3200, visible: 3200 });
+ expect(counts(layer({ hidden: ['Damage'] }))).toEqual({ loaded: 3200, visible: 2788 });
+ });
+
+ it('never lets the drawn count pass for the loaded one', () => {
+ // the whole rule: hiding a group changes what is shown and nothing else
+ expect(countLabel(layer({ hidden: ['Checkpoints'] }))).toBe(`3${GROUP_SPACE}200 features · 412 shown`);
+ });
+
+ it('says one number when nothing is hidden, because two would be noise', () => {
+ expect(countLabel(layer())).toBe(`3${GROUP_SPACE}200 features`);
+ expect(countLabel(layer({ features: 1, categories: [] }))).toBe('1 feature');
+ });
+
+ it('groups the digits, because five of them run together otherwise', () => {
+ expect(countLabel(layer({ features: 41209, categories: [] }))).toBe(`41${GROUP_SPACE}209 features`);
+ });
+
+ it('never goes negative on a hidden group the summary no longer holds', () => {
+ expect(counts(layer({ hidden: ['Gone'] })).visible).toBe(3200);
+ });
+});
+
+describe('the legend is the filter', () => {
+ it('is one row per category, with its colour and its count', () => {
+ expect(legend(layer())).toEqual([
+ { name: 'Checkpoints', count: 2788, kinds: ['point'], colour: '#ff0000', on: true },
+ { name: 'Damage', count: 412, kinds: ['area'], colour: PALETTE[1], on: true },
+ ]);
+ });
+
+ it('marks a hidden category off rather than dropping it from the list', () => {
+ // it is still there to be switched back on, and still counted as loaded
+ expect(legend(layer({ hidden: ['Damage'] })).map((row) => row.on)).toEqual([true, false]);
+ });
+
+ it('honours the source colour and falls back to the palette only without one', () => {
+ expect(categoryColour({ colour: '#ff0000' }, 3)).toBe('#ff0000');
+ expect(categoryColour({ colour: '' }, 0)).toBe(PALETTE[0]);
+ // keyed by position within one layer, so two layers' first groups differ
+ // from their own second, not from each other
+ expect(categoryColour(null, PALETTE.length)).toBe(PALETTE[0]);
+ });
+
+ it('toggles exactly one category, leaving the rest as they were', () => {
+ expect(toggleCategory(layer(), 'Damage')).toEqual(['Damage']);
+ expect(toggleCategory(layer({ hidden: ['Damage', 'Checkpoints'] }), 'Damage')).toEqual([
+ 'Checkpoints',
+ ]);
+ });
+});
+
+describe('how fresh what is drawn actually is', () => {
+ it('says when a subscription was last read', () => {
+ expect(freshness(layer({ source: { kind: 'url', url: 'https://x.test/a.kml' } }), NOW)).toBe(
+ 'read 2 h ago'
+ );
+ });
+
+ it('says a stale snapshot is stale, which is the point of the readout', () => {
+ const stale = layer({
+ source: { kind: 'url', url: 'https://x.test/a.kml' },
+ checked_at: '2026-09-10T10:00:00Z',
+ stale: true,
+ });
+
+ expect(freshness(stale, NOW)).toBe('stale — last read 10 Sep 2026');
+ });
+
+ it('says a subscription nothing has ever read has never been read', () => {
+ const fresh = layer({
+ source: { kind: 'url', url: 'https://x.test/a.kml' },
+ checked_at: '',
+ fetched_at: '',
+ });
+
+ expect(freshness(fresh, NOW)).toBe('never read');
+ });
+
+ it('never calls a file stale: it is what was opened and it does not move', () => {
+ expect(freshness(layer(), NOW)).toBe('opened 2 h ago');
+ });
+});
+
+describe('where a row says it came from', () => {
+ it('names the file, the platform or the host', () => {
+ expect(sourceLabel(layer())).toBe('sightings.kml');
+ expect(
+ sourceLabel(layer({ source: { kind: 'url', url: 'https://www.google.com/maps/d/viewer?mid=x', my_maps: true } }))
+ ).toBe('Google My Maps');
+ expect(sourceLabel(layer({ source: { kind: 'url', url: 'https://www.example.org/a.kml' } }))).toBe(
+ 'example.org'
+ );
+ });
+
+ it('credits the source, as the curated overlays credit theirs', () => {
+ expect(attribution(layer())).toBe('Sightings — added by the analyst');
+ expect(
+ attribution(layer({ source: { kind: 'url', url: 'https://x.test/a.kml', my_maps: true } }))
+ ).toBe('Sightings — Google My Maps');
+ });
+});
+
+describe('what the map draws and what a case open re-reads', () => {
+ it('draws the enabled layers and nothing else', () => {
+ const rows = [layer(), layer({ name: 'Off', enabled: false })];
+
+ expect(drawable(rows).map((row) => row.name)).toEqual(['Sightings']);
+ });
+
+ it('re-reads only a subscription that is enabled and asked to be', () => {
+ // the network boundary, stated as data: a file has nothing to read, a
+ // disabled layer costs nothing, and a subscription can opt out
+ const rows = [
+ layer({ name: 'File' }),
+ layer({ name: 'Off', enabled: false, source: { kind: 'url', url: 'https://x.test/1' } }),
+ layer({
+ name: 'Manual',
+ source: { kind: 'url', url: 'https://x.test/2' },
+ refresh: { on_open: false },
+ }),
+ layer({ name: 'Followed', source: { kind: 'url', url: 'https://x.test/3' } }),
+ ];
+
+ expect(refreshable(rows).map((row) => row.name)).toEqual(['Followed']);
+ });
+});
+
+describe('finding a pin in somebody else’s map', () => {
+ const feature = (name, category, over = {}) => ({
+ type: 'Feature',
+ geometry: { type: 'Point', coordinates: [2, 48] },
+ properties: { name, category, colour: '', description: '', ...over },
+ });
+
+ const COLLECTION = {
+ type: 'FeatureCollection',
+ features: [
+ feature('North gate', 'Checkpoints', { index: 0, colour: '#ff0000' }),
+ feature('South gate', 'Checkpoints', { index: 1 }),
+ feature('Gate house', 'Damage', { index: 2 }),
+ feature('', 'Damage', { index: 3, description: 'a gate, seen from the east' }),
+ ],
+ };
+
+ const find = (query, over = {}) =>
+ searchFeatures(COLLECTION, query, { categories: layer().categories, ...over });
+
+ it('matches a name however it was typed', () => {
+ expect(find('gate').total).toBe(3);
+ expect(find('GATE').results.map((hit) => hit.name)).toEqual([
+ 'North gate',
+ 'South gate',
+ 'Gate house',
+ ]);
+ });
+
+ it('matches a group, so a whole folder can be pulled up by name', () => {
+ expect(find('damage').results.map((hit) => hit.index)).toEqual([2, 3]);
+ });
+
+ it('wants every term, which is what narrowing a search means', () => {
+ expect(find('gate north').results.map((hit) => hit.name)).toEqual(['North gate']);
+ expect(find('gate harbour').total).toBe(0);
+ });
+
+ it('never reads a description, whatever it holds', () => {
+ // the bound this feature is built on: MAX_DESCRIPTION × MAX_FEATURES is not
+ // something to walk on a keystroke, and a name is what anyone remembers
+ expect(find('seen from the east').total).toBe(0);
+ expect(find('gate').results.some((hit) => hit.index === 3)).toBe(false);
+ });
+
+ it('finds nothing at all until something is typed', () => {
+ expect(find('')).toEqual({ total: 0, results: [] });
+ expect(find(' ')).toEqual({ total: 0, results: [] });
+ });
+
+ it('names a feature the source never named', () => {
+ expect(find('damage').results[1].name).toBe(UNNAMED);
+ });
+
+ it('paints a match the colour its own mark is drawn in', () => {
+ // the source's own where it painted one…
+ expect(find('north').results[0].colour).toBe('#ff0000');
+ // …its group's where it did not, and the palette where the group has none
+ expect(find('south').results[0].colour).toBe('#ff0000');
+ expect(find('gate house').results[0].colour).toBe(PALETTE[1]);
+ });
+
+ it('lists a match from a group the legend switched off, and says so', () => {
+ const [hit] = find('gate house', { hidden: ['Damage'] }).results;
+
+ expect(hit.hidden).toBe(true);
+ expect(find('north', { hidden: ['Damage'] }).results[0].hidden).toBe(false);
+ });
+
+ it('counts every match and lists the first few', () => {
+ const many = {
+ features: Array.from({ length: SEARCH_LIMIT + 12 }, (_, index) =>
+ feature(`Gate ${index}`, 'Checkpoints', { index })
+ ),
+ };
+
+ const found = searchFeatures(many, 'gate');
+
+ // the tally is what tells the analyst to narrow the search; a list that
+ // silently stopped at twenty-five would let them read it as all there is
+ expect(found.total).toBe(SEARCH_LIMIT + 12);
+ expect(found.results).toHaveLength(SEARCH_LIMIT);
+ });
+
+ it('carries the number the backend gave a feature, not its own', () => {
+ // what going to a match looks the feature up by
+ expect(find('gate house').results[0].index).toBe(2);
+ });
+});
+
+describe('what the + accepts', () => {
+ it('tells an address from a file, so the button and the dialog agree', () => {
+ expect(looksLikeUrl('https://www.google.com/maps/d/viewer?mid=x')).toBe(true);
+ expect(looksLikeUrl(' http://example.org/a.kml ')).toBe(true);
+ expect(looksLikeUrl('sightings.kmz')).toBe(false);
+ expect(looksLikeUrl('file:///etc/passwd')).toBe(false);
+ });
+
+ it('offers exactly the formats the parser reads', () => {
+ expect(ACCEPTS.split(',')).toEqual(['.geojson', '.json', '.kml', '.kmz', '.gpx']);
+ });
+});
diff --git a/frontend/src/lib/map/compareExport.js b/frontend/src/lib/map/compareExport.js
index 356760b..eb35ddb 100644
--- a/frontend/src/lib/map/compareExport.js
+++ b/frontend/src/lib/map/compareExport.js
@@ -202,9 +202,22 @@ export function composeComparison({
const top = header;
const paneB = side ? a.canvas.width : 0;
+ // A framed export cuts the imagery, not the marks pinned to it, so what
+ // falls outside the pane has to be held there: unclipped, a note anchored
+ // off-frame would be painted over the header band.
+ const clipped = (offsetX, width, height, draw) => {
+ ctx.save();
+ ctx.beginPath();
+ ctx.rect(offsetX, top, width, height);
+ ctx.clip();
+ draw();
+ ctx.restore();
+ };
const markAnnotations = (capture, letter, offsetX) => {
const marks = annotations.filter((mark) => onSide(mark, letter));
- drawAnnotations(ctx, marks, captureProjection(capture, offsetX, top), { scale: s, units });
+ clipped(offsetX, capture.canvas.width, capture.canvas.height, () =>
+ drawAnnotations(ctx, marks, captureProjection(capture, offsetX, top), { scale: s, units })
+ );
};
if (side) {
@@ -253,7 +266,9 @@ export function composeComparison({
ctx.restore();
markAnnotations(a, 'a', 0);
const onlyB = annotations.filter((mark) => mark.side === 'b');
- drawAnnotations(ctx, onlyB, captureProjection(b, 0, top), { scale: s, units });
+ clipped(0, b.canvas.width, b.canvas.height, () =>
+ drawAnnotations(ctx, onlyB, captureProjection(b, 0, top), { scale: s, units })
+ );
drawTag(ctx, `B ${Math.round(opacity)}%`, mapWidth - 12 * s, top + 12 * s, { scale: s, accent: true, align: 'right' });
} else if (mode === 'change') {
if (!change?.canvas?.width || !change?.frame) {
@@ -280,10 +295,13 @@ export function composeComparison({
// Header: what is being compared, then where.
const left = 16 * s;
let line = 0;
+ // Where the written header ends on the row the camera reading would share.
+ let taken = left;
if (title) {
ctx.fillStyle = INK;
ctx.font = `700 ${Math.round(17 * s)}px ${FONT}`;
ctx.fillText(title, left, 25 * s, mapWidth * 0.6);
+ taken = left + Math.min(ctx.measureText(title).width, mapWidth * 0.6);
line = 20 * s;
}
ctx.font = `600 ${Math.round(12 * s)}px ${FONT}`;
@@ -297,6 +315,9 @@ export function composeComparison({
ctx.fillText('B', bx, 24 * s + line);
ctx.fillStyle = INK;
ctx.fillText(labelB, bx + 14 * s, 24 * s + line, mapWidth * 0.3);
+ if (!title) {
+ taken = bx + 14 * s + Math.min(ctx.measureText(labelB).width, mapWidth * 0.3);
+ }
const lat = Number(view?.lat);
const lon = Number(view?.lon);
@@ -304,9 +325,15 @@ export function composeComparison({
if (Number.isFinite(lat) && Number.isFinite(lon)) {
const camera = `${lat.toFixed(5)}, ${lon.toFixed(5)} · z${Math.round(zoom)} · ${Math.round(bearing)}°`;
ctx.font = `${Math.round(11 * s)}px ${MONO}`;
- ctx.fillStyle = MUTED;
const width = ctx.measureText(camera).width;
- ctx.fillText(camera, Math.max(left, mapWidth - width - 16 * s), (title ? 25 : 24) * s);
+ const x = mapWidth - width - 16 * s;
+ // The header keeps its height whatever the export is framed to, so on a
+ // narrow one the camera reading is what goes: the picture can be read
+ // without it, and not without knowing which side is which.
+ if (x > taken + 12 * s) {
+ ctx.fillStyle = MUTED;
+ ctx.fillText(camera, x, (title ? 25 : 24) * s);
+ }
}
// Legend for a change reading, stated as what it is: an assist.
@@ -321,18 +348,24 @@ export function composeComparison({
let x = left;
const y = bottom + 20 * s;
ctx.font = `${Math.round(11 * s)}px ${FONT}`;
+ // On a framed export the legend can outrun the picture: an entry that
+ // would run off the edge is dropped rather than half-written.
for (const [key, text] of entries) {
+ const width = ctx.measureText(text).width;
+ if (x + 15 * s + width > mapWidth - 16 * s) break;
const [r, g, bl] = palette[key];
ctx.fillStyle = `rgb(${r},${g},${bl})`;
ctx.fillRect(x, y - 9 * s, 10 * s, 10 * s);
ctx.fillStyle = INK;
ctx.fillText(text, x + 15 * s, y);
- x += ctx.measureText(text).width + 34 * s;
+ x += width + 34 * s;
}
if (change.summary) {
- ctx.fillStyle = MUTED;
const width = ctx.measureText(change.summary).width;
- ctx.fillText(change.summary, Math.max(x, mapWidth - width - 16 * s), y);
+ if (x + width <= mapWidth - 16 * s) {
+ ctx.fillStyle = MUTED;
+ ctx.fillText(change.summary, mapWidth - width - 16 * s, y);
+ }
}
}
diff --git a/frontend/src/lib/map/compareExport.test.js b/frontend/src/lib/map/compareExport.test.js
index 4c52848..eeeeb2b 100644
--- a/frontend/src/lib/map/compareExport.test.js
+++ b/frontend/src/lib/map/compareExport.test.js
@@ -64,6 +64,12 @@ const BASE = {
makeCanvas: fakeCanvas,
};
+/** A framed export: the capture and its frame are both cut down. */
+const FRAMED = {
+ canvas: { width: 300, height: 300 },
+ frame: { ...FRAME, width: 300, height: 300 },
+};
+
const draws = (out) => out.context.calls.filter(([name]) => name === 'drawImage');
describe('comparison export', () => {
@@ -124,6 +130,36 @@ describe('comparison export', () => {
expect(draws(out).map((call) => call[1])).toEqual([BASE.b.canvas]);
});
+ it('writes the camera reading beside the labels when the width allows', () => {
+ const out = composeComparison({ ...BASE, mode: 'side' });
+ const camera = out.context.calls.find(([name, text]) => name === 'fillText' && String(text).includes('z17'));
+ expect(camera).toBeTruthy();
+ });
+
+ it('drops the camera reading rather than write it over the labels', () => {
+ const out = composeComparison({ ...BASE, a: FRAMED, b: FRAMED, mode: 'blink' });
+ const written = out.context.calls.filter(([name]) => name === 'fillText').map(([, text]) => text);
+ expect(written).toContain('Old');
+ expect(written).toContain('New');
+ expect(written.some((text) => String(text).includes('z17'))).toBe(false);
+ });
+
+ it('holds annotations inside the pane they belong to', () => {
+ const marks = [{ id: 'far', kind: 'text', side: 'a', colour: '#f6a81a',
+ points: [[2.5, 48.9]], text: 'Off frame', font_size: 16, stroke_width: 3, fill_opacity: 0 }];
+ const out = composeComparison({ ...BASE, mode: 'side', annotations: marks });
+ expect(out.context.calls).toContainEqual(['rect', 0, 48, 500, 300]);
+ expect(out.context.calls).toContainEqual(['rect', 500, 48, 500, 300]);
+ });
+
+ it('drops a change legend entry that would run off a framed export', () => {
+ const mask = { canvas: { width: 250, height: 150 }, frame: FRAME, base: 'a', opacity: 55, visible: true };
+ const out = composeComparison({ ...BASE, a: FRAMED, b: FRAMED, mode: 'change', change: mask });
+ const written = out.context.calls.filter(([name]) => name === 'fillText').map(([, text]) => text);
+ expect(written).toContain('Appeared or brighter in B');
+ expect(written).not.toContain('Other change');
+ });
+
it('projects the ground into a high-density capture', () => {
const project = captureProjection(capture('a', 2), 0, 48);
const [x, y] = project([2.3, 48.8]);
diff --git a/frontend/src/lib/map/contextMenu.js b/frontend/src/lib/map/contextMenu.js
index d0f6b8d..828acdd 100644
--- a/frontend/src/lib/map/contextMenu.js
+++ b/frontend/src/lib/map/contextMenu.js
@@ -66,6 +66,15 @@ export function openRows(lat, lon, zoom) {
* It opens down and to the right of the cursor, and flips to the other side of
* the cursor on whichever axis would run past the map's edge, then clamps, so a
* right-click in a corner still shows every row.
+ *
+ * **Asked once, from the measured size, and then left alone.** This used to be
+ * recomputed as the menu's own content changed, which meant opening the list of
+ * external maps — or simply getting an answer back from "What is here?" — made
+ * the whole menu jump out from under the cursor to stay inside the frame. A menu
+ * that moves while it is being read is a menu whose next row lands somewhere
+ * other than where the eye left it. The component freezes this after the first
+ * real measurement, and the two things that could still grow it are handled
+ * where they are: the submenu flies out to the side, and the menu scrolls.
*/
export function placeMenu(point, menu, frame, margin = 8) {
let left = point.x;
@@ -77,6 +86,34 @@ export function placeMenu(point, menu, frame, margin = 8) {
return { left: Math.round(left), top: Math.round(top) };
}
+/**
+ * Where a submenu opens, in the same frame coordinates as its parent.
+ *
+ * Beside the parent, not under the row — which is the whole point: a list that
+ * unfolds inside the menu changes the menu's height, and a menu that has already
+ * been placed against the frame's edge then has to move to stay inside it. To
+ * the side, the parent's box never changes, so nothing under the cursor shifts.
+ *
+ * It opens to the right, flips to the left when that would run past the frame,
+ * and is pushed up rather than clipped when the row it hangs from is near the
+ * bottom — so the last item of a long submenu is always reachable.
+ *
+ * @param {{left: number, top: number, width: number, rowTop: number}} anchor
+ * the parent menu's box and the top of the row this hangs from, both in frame
+ * coordinates
+ */
+export function placeSubmenu(anchor, submenu, frame, margin = 8, gap = 2) {
+ let left = anchor.left + anchor.width + gap;
+ if (left + submenu.width + margin > frame.width) {
+ left = anchor.left - submenu.width - gap;
+ }
+ left = Math.max(margin, Math.min(left, Math.max(margin, frame.width - submenu.width - margin)));
+ let top = anchor.rowTop;
+ top = Math.min(top, frame.height - submenu.height - margin);
+ top = Math.max(margin, top);
+ return { left: Math.round(left), top: Math.round(top) };
+}
+
/**
* The row focus moves to with an arrow key, wrapping at either end, skipping
* rows that are disabled.
diff --git a/frontend/src/lib/map/contextMenu.test.js b/frontend/src/lib/map/contextMenu.test.js
index 7da1039..97fee8b 100644
--- a/frontend/src/lib/map/contextMenu.test.js
+++ b/frontend/src/lib/map/contextMenu.test.js
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest';
-import { ACTIONS, actionsFor, copyRows, nextFocus, openRows, placeMenu } from './contextMenu.js';
+import { ACTIONS, actionsFor, copyRows, nextFocus, openRows, placeMenu, placeSubmenu } from './contextMenu.js';
describe('copying the point', () => {
it('offers every format the app writes, the analyst’s own first', () => {
@@ -69,6 +69,38 @@ describe('where the menu opens', () => {
});
});
+describe('where the submenu opens', () => {
+ const frame = { width: 1000, height: 600 };
+ const parent = { left: 100, top: 80, width: 240, rowTop: 300 };
+ const submenu = { width: 160, height: 260 };
+
+ it('opens beside the row, so the menu it hangs from never moves', () => {
+ // the bug this shape exists for: a list unfolding inside the menu changed
+ // its height, and a menu already placed against an edge then had to move
+ expect(placeSubmenu(parent, submenu, frame)).toEqual({ left: 342, top: 300 });
+ });
+
+ it('flips to the other side when it would run past the right edge', () => {
+ const right = { ...parent, left: 760 };
+
+ expect(placeSubmenu(right, submenu, frame).left).toBe(598);
+ });
+
+ it('is pushed up rather than clipped when the row is near the bottom', () => {
+ // a submenu whose last entry is off the map is a submenu with nine of ten
+ expect(placeSubmenu({ ...parent, rowTop: 560 }, submenu, frame).top).toBe(332);
+ });
+
+ it('overlaps its parent rather than leaving the map it cannot fit beside it', () => {
+ // 240 of menu and 160 of submenu do not both fit in 300: there is no
+ // placement that avoids the overlap, and off the map is the worse answer
+ const at = placeSubmenu(parent, submenu, { width: 300, height: 200 });
+
+ expect(at.left).toBe(8);
+ expect(at.top).toBe(8);
+ });
+});
+
describe('moving through the menu with arrows', () => {
it('wraps at either end', () => {
expect(nextFocus(4, 3, 1)).toBe(0);
diff --git a/frontend/src/lib/map/engine.css b/frontend/src/lib/map/engine.css
index e52cf52..ddad36b 100644
--- a/frontend/src/lib/map/engine.css
+++ b/frontend/src/lib/map/engine.css
@@ -8,10 +8,10 @@
* in a tool's stylesheet.
*
* The popup is here for the same reason and one more: MapLibre draws the card's
- * pointer as a border triangle whose colour depends on which of eight sides the
- * card opened towards. That is eight rules of engine trivia, and no tool should
- * have to know it. A tool names its own card class and sets what is genuinely
- * its own — the width it needs — through `--popup-min-width`.
+ * pointer as a border triangle, built differently for each of the eight sides a
+ * card can open towards. That is eight rules of engine trivia, and no tool
+ * should have to know it. A tool names its own card class and sets what is
+ * genuinely its own — the width it needs — through `--popup-min-width`.
*
* Loaded by `engine.js`, so it arrives with the engine and leaves with it.
*/
@@ -97,8 +97,12 @@
/* The card a mark opens, over imagery: one of the app's surfaces, not the
engine's white bubble. A tool sets `--popup-min-width` for the width its own
- content needs. */
-.maplibregl-popup-content {
+ content needs.
+
+ The selector carries the container so it outweighs the engine's own
+ `.maplibregl-popup-anchor-* .maplibregl-popup-content`, which flattens one
+ corner of the card to seat the wedge replaced below. */
+.maplibregl-popup .maplibregl-popup-content {
min-width: var(--popup-min-width, 0);
padding: 12px 14px;
border: 1px solid var(--border-strong);
@@ -108,33 +112,82 @@
color: var(--text-1);
line-height: 1.4;
}
+
+/* Closing the card, as a chip on its corner rather than a cross inside it: the
+ engine hangs the button over the top-right of the content, which lands it on
+ the first line of whatever the card says — a title, a stack's tally. Out on
+ the corner it has nothing to overlap, whatever a card puts on that line. */
.maplibregl-popup-close-button {
- padding: 4px 7px 0 0;
- color: var(--text-3);
- font-size: 15px;
+ top: -10px;
+ right: -10px;
+ display: grid;
+ place-items: center;
+ width: 20px;
+ height: 20px;
+ padding: 0;
+ border: 1px solid var(--border-strong);
+ border-radius: 50%;
+ background: var(--bg-2);
+ color: var(--text-2);
+ font-size: 13px;
+ line-height: 1;
}
.maplibregl-popup-close-button:hover {
- background: none;
+ background: var(--bg-3);
color: var(--text-1);
}
-/* The pointer is the card's own surface, not its edge: the engine draws it as a
- border triangle, so a border colour is the only thing that reaches it — and
- the edge colour is translucent, which left the pointer all but invisible. */
+
+/* The pointer, as a notch of the card rather than a triangle parked against it.
+ The engine draws a border triangle: unoutlined, filled by whichever of eight
+ border colours matches the side the card opened on, and squared off into a
+ wedge on the four corners. This is one 13 px square turned 45°, wearing the
+ card's own surface and edge and pushed halfway into it — the two sides facing
+ the card are simply not drawn, the two facing the point carry the card's
+ outline on, and the same shape serves all eight sides. */
+.maplibregl-popup .maplibregl-popup-tip {
+ width: 13px;
+ height: 13px;
+ border: 1px solid var(--border-strong);
+ background: var(--bg-1);
+ transform: rotate(45deg);
+}
+/* Which two sides face the point, per side the card opened on. A square turned
+ 45° clockwise points its original bottom-right pair downwards. */
.maplibregl-popup-anchor-top .maplibregl-popup-tip,
.maplibregl-popup-anchor-top-left .maplibregl-popup-tip,
.maplibregl-popup-anchor-top-right .maplibregl-popup-tip {
- border-bottom-color: var(--bg-1);
+ margin-bottom: -7px;
+ border-right: none;
+ border-bottom: none;
}
.maplibregl-popup-anchor-bottom .maplibregl-popup-tip,
.maplibregl-popup-anchor-bottom-left .maplibregl-popup-tip,
.maplibregl-popup-anchor-bottom-right .maplibregl-popup-tip {
- border-top-color: var(--bg-1);
+ margin-top: -7px;
+ border-top: none;
+ border-left: none;
}
.maplibregl-popup-anchor-left .maplibregl-popup-tip {
- border-right-color: var(--bg-1);
+ margin-right: -7px;
+ border-top: none;
+ border-right: none;
}
.maplibregl-popup-anchor-right .maplibregl-popup-tip {
- border-left-color: var(--bg-1);
+ margin-left: -7px;
+ border-bottom: none;
+ border-left: none;
+}
+/* A card opened on a corner is pinned by that corner, so the engine seats the
+ notch right on it, half off the card. Held in far enough to sit on a straight
+ edge instead — the point is a dozen pixels away, and the notch still reads as
+ pointing at it. */
+.maplibregl-popup-anchor-top-left .maplibregl-popup-tip,
+.maplibregl-popup-anchor-bottom-left .maplibregl-popup-tip {
+ margin-left: 12px;
+}
+.maplibregl-popup-anchor-top-right .maplibregl-popup-tip,
+.maplibregl-popup-anchor-bottom-right .maplibregl-popup-tip {
+ margin-right: 12px;
}
/* The Google widget basemap (lib/map/gmaps.js) renders in its own map, under
diff --git a/frontend/src/lib/map/exportFrame.js b/frontend/src/lib/map/exportFrame.js
new file mode 100644
index 0000000..6909ff2
--- /dev/null
+++ b/frontend/src/lib/map/exportFrame.js
@@ -0,0 +1,152 @@
+/**
+ * The rectangle an export is framed to.
+ *
+ * A comparison is read on a whole browser window, but the thing worth showing
+ * is usually a building or a crater in the middle of it. The frame is drawn
+ * once on imagery A and kept as two ground corners, like an annotation: the
+ * camera can move, the window can be resized, the same ground comes out.
+ *
+ * Cropping happens before composition, on the captured canvases: each side is
+ * cut to the same ground box and handed a frame of its own, so the change
+ * mask, the annotations and the scale bar land exactly where they did on the
+ * whole view.
+ */
+
+import { apply, fromMercator, invert, screenToMercator, toMercator } from './groundFrame.js';
+
+/**
+ * The narrowest frame worth exporting, in CSS pixels.
+ *
+ * The composed header holds a title, both dated labels and the camera line at
+ * a fixed height, so below this they start climbing over each other.
+ */
+export const MIN_FRAME = 320;
+
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+
+/** Ground pair → the pixel box of `frame` that covers it. */
+export function screenRect(points, frame) {
+ const toScreen = invert(screenToMercator(frame));
+ const corners = points.map(([lon, lat]) => apply(toScreen, ...toMercator(lon, lat)));
+ const xs = corners.map((point) => point[0]);
+ const ys = corners.map((point) => point[1]);
+ return {
+ x: Math.min(...xs),
+ y: Math.min(...ys),
+ w: Math.max(...xs) - Math.min(...xs),
+ h: Math.max(...ys) - Math.min(...ys),
+ };
+}
+
+/** Pixel box of `frame` → the two ground corners it spans. */
+export function groundRect(rect, frame) {
+ const toGround = screenToMercator(frame);
+ return [
+ fromMercator(...apply(toGround, rect.x, rect.y)),
+ fromMercator(...apply(toGround, rect.x + rect.w, rect.y + rect.h)),
+ ];
+}
+
+/**
+ * A drawn box made exportable: grown to the minimum around its own centre,
+ * then held inside the view. A frame drawn smaller than the view can always
+ * be placed; one drawn on a view narrower than the minimum takes the view.
+ */
+export function boundedRect(rect, frame) {
+ const w = clamp(Math.round(rect.w), Math.min(MIN_FRAME, frame.width), frame.width);
+ const h = clamp(Math.round(rect.h), Math.min(MIN_FRAME, frame.height), frame.height);
+ return {
+ x: Math.round(clamp(rect.x + rect.w / 2 - w / 2, 0, frame.width - w)),
+ y: Math.round(clamp(rect.y + rect.h / 2 - h / 2, 0, frame.height - h)),
+ w,
+ h,
+ };
+}
+
+/** How much ground the frame spans along the current screen axes, in metres. */
+export function frameSpan(points, bearing = 0) {
+ const [first, second] = points.map(([lon, lat]) => toMercator(lon, lat));
+ const shrink = Math.cos((((points[0][1] + points[1][1]) / 2) * Math.PI) / 180);
+ const turn = (bearing * Math.PI) / 180;
+ const cos = Math.cos(turn);
+ const sin = Math.sin(turn);
+ const dx = second[0] - first[0];
+ const dy = second[1] - first[1];
+ return {
+ width: Math.abs(cos * dx - sin * dy) * shrink,
+ height: Math.abs(-sin * dx - cos * dy) * shrink,
+ };
+}
+
+function canvasOf(width, height, makeCanvas) {
+ const canvas = makeCanvas ? makeCanvas() : document.createElement('canvas');
+ canvas.width = Math.max(1, Math.round(width));
+ canvas.height = Math.max(1, Math.round(height));
+ return canvas;
+}
+
+/** Cut one captured surface down to `rect`, and re-centre its frame on the cut. */
+export function cropCapture(capture, rect, makeCanvas) {
+ const pixelScale = capture.canvas.width / capture.frame.width;
+ const canvas = canvasOf(rect.w * pixelScale, rect.h * pixelScale, makeCanvas);
+ const ctx = canvas.getContext('2d');
+ if (!ctx) throw new Error('this browser cannot frame the comparison');
+ ctx.imageSmoothingQuality = 'high';
+ ctx.drawImage(
+ capture.canvas,
+ Math.round(rect.x * pixelScale),
+ Math.round(rect.y * pixelScale),
+ canvas.width,
+ canvas.height,
+ 0,
+ 0,
+ canvas.width,
+ canvas.height
+ );
+ const [lng, lat] = fromMercator(
+ ...apply(screenToMercator(capture.frame), rect.x + rect.w / 2, rect.y + rect.h / 2)
+ );
+ return { canvas, frame: { ...capture.frame, lng, lat, width: rect.w, height: rect.h } };
+}
+
+/**
+ * Both captures cut to the same ground box.
+ *
+ * A is cut first and its box read back off the ground, so B is placed by where
+ * A actually landed rather than by the drawing: the two panes of a side by
+ * side then hold the same extent even if the cameras drifted by a pixel.
+ */
+export function cropSources(sources, frame, makeCanvas) {
+ if (!frame?.points) return sources;
+ const fitted = (rect, captureFrame, size = null) => {
+ const cut = {
+ x: Math.round(rect.x),
+ y: Math.round(rect.y),
+ w: size?.w ?? Math.max(1, Math.round(rect.w)),
+ h: size?.h ?? Math.max(1, Math.round(rect.h)),
+ };
+ if (cut.x < 0 || cut.y < 0 || cut.x + cut.w > captureFrame.width || cut.y + cut.h > captureFrame.height) {
+ throw new Error('the export frame must be fully visible; move or zoom out, then try again');
+ }
+ return cut;
+ };
+ const rectA = fitted(screenRect(frame.points, sources.a.frame), sources.a.frame);
+ const ground = groundRect(rectA, sources.a.frame);
+ const onB = screenRect(ground, sources.b.frame);
+ const rectB = fitted(onB, sources.b.frame, rectA);
+ return {
+ a: cropCapture(sources.a, rectA, makeCanvas),
+ b: cropCapture(sources.b, rectB, makeCanvas),
+ };
+}
+
+/** What a saved session carries: nothing, or two ground corners. */
+export function exportFrameSpec(value) {
+ const points = value?.points;
+ if (!Array.isArray(points) || points.length !== 2) return null;
+ const cleaned = points.map((point) => [Number(point?.[0]), Number(point?.[1])]);
+ if (cleaned.some(([lon, lat]) => !Number.isFinite(lon) || !Number.isFinite(lat))) return null;
+ if (cleaned.some(([lon, lat]) => Math.abs(lon) > 180 || Math.abs(lat) > 90)) return null;
+ if (cleaned[0][0] === cleaned[1][0] && cleaned[0][1] === cleaned[1][1]) return null;
+ return { points: cleaned };
+}
diff --git a/frontend/src/lib/map/exportFrame.test.js b/frontend/src/lib/map/exportFrame.test.js
new file mode 100644
index 0000000..665c79d
--- /dev/null
+++ b/frontend/src/lib/map/exportFrame.test.js
@@ -0,0 +1,175 @@
+import { describe, expect, it } from 'vitest';
+import {
+ MIN_FRAME,
+ boundedRect,
+ cropCapture,
+ cropSources,
+ exportFrameSpec,
+ frameSpan,
+ groundRect,
+ screenRect,
+} from './exportFrame.js';
+import { mercatorPerPixel } from './groundFrame.js';
+
+const FRAME = { lng: 2.3, lat: 48.8, zoom: 17, bearing: 0, width: 1200, height: 800 };
+
+function fakeCanvas() {
+ const drawn = [];
+ return {
+ width: 0,
+ height: 0,
+ drawn,
+ getContext: () => ({
+ imageSmoothingQuality: '',
+ drawImage: (...args) => drawn.push(args),
+ }),
+ };
+}
+
+const capture = (frame = FRAME, pixelScale = 1) => ({
+ canvas: { width: frame.width * pixelScale, height: frame.height * pixelScale },
+ frame,
+});
+
+describe('screenRect / groundRect', () => {
+ it('round-trips a drawn box through the ground', () => {
+ const rect = { x: 320, y: 180, w: 400, h: 260 };
+ const back = screenRect(groundRect(rect, FRAME), FRAME);
+ expect(back.x).toBeCloseTo(rect.x, 6);
+ expect(back.y).toBeCloseTo(rect.y, 6);
+ expect(back.w).toBeCloseTo(rect.w, 6);
+ expect(back.h).toBeCloseTo(rect.h, 6);
+ });
+
+ it('follows the ground when the camera moves', () => {
+ const points = groundRect({ x: 400, y: 300, w: 300, h: 200 }, FRAME);
+ const panned = { ...FRAME, lng: FRAME.lng + 0.001 };
+ const moved = screenRect(points, panned);
+ expect(moved.x).toBeLessThan(400);
+ expect(moved.w).toBeCloseTo(300, 6);
+ });
+
+ it('keeps the same ground box under two frames of the same camera', () => {
+ const points = groundRect({ x: 100, y: 120, w: 500, h: 300 }, FRAME);
+ const wider = { ...FRAME, width: 1600 };
+ const rect = screenRect(points, wider);
+ expect(rect.w).toBeCloseTo(500, 6);
+ expect(rect.x).toBeCloseTo(100 + 200, 6);
+ });
+});
+
+describe('boundedRect', () => {
+ it('holds a frame inside the view', () => {
+ const rect = boundedRect({ x: -80, y: 700, w: 500, h: 400 }, FRAME);
+ expect(rect.x).toBe(0);
+ expect(rect.y).toBe(FRAME.height - 400);
+ });
+
+ it('grows a small drawing to the minimum around its own centre', () => {
+ const rect = boundedRect({ x: 600, y: 400, w: 40, h: 30 }, FRAME);
+ expect(rect.w).toBe(MIN_FRAME);
+ expect(rect.h).toBe(MIN_FRAME);
+ expect(rect.x + rect.w / 2).toBeCloseTo(620, 6);
+ expect(rect.y + rect.h / 2).toBeCloseTo(415, 6);
+ });
+
+ it('never asks for more than the view holds', () => {
+ const narrow = { ...FRAME, width: 200, height: 150 };
+ const rect = boundedRect({ x: 0, y: 0, w: 10, h: 10 }, narrow);
+ expect(rect).toEqual({ x: 0, y: 0, w: 200, h: 150 });
+ });
+});
+
+describe('frameSpan', () => {
+ const equator = { lng: 0, lat: 0, zoom: 12, bearing: 0, width: 800, height: 600 };
+
+ it('reads the frame as ground metres', () => {
+ const span = frameSpan(groundRect({ x: 100, y: 100, w: 400, h: 200 }, equator));
+ expect(span.width).toBeCloseTo(400 * mercatorPerPixel(12), 3);
+ expect(span.height).toBeCloseTo(200 * mercatorPerPixel(12), 3);
+ });
+
+ it('shrinks with the latitude, like the ground itself', () => {
+ const at60 = { ...equator, lat: 60 };
+ const span = frameSpan(groundRect({ x: 100, y: 250, w: 400, h: 100 }, at60));
+ expect(span.width).toBeCloseTo(400 * mercatorPerPixel(12) * Math.cos((60 * Math.PI) / 180), 0);
+ });
+
+ it('reads width and height along a rotated screen', () => {
+ const turned = { ...equator, bearing: 31 };
+ const span = frameSpan(groundRect({ x: 100, y: 100, w: 400, h: 200 }, turned), turned.bearing);
+ expect(span.width).toBeCloseTo(400 * mercatorPerPixel(12), 2);
+ expect(span.height).toBeCloseTo(200 * mercatorPerPixel(12), 2);
+ });
+});
+
+describe('cropCapture', () => {
+ it('cuts the pixels and re-centres the frame on the cut', () => {
+ const cropped = cropCapture(capture(), { x: 400, y: 200, w: 300, h: 200 }, fakeCanvas);
+ expect(cropped.canvas.width).toBe(300);
+ expect(cropped.canvas.height).toBe(200);
+ expect(cropped.canvas.drawn[0].slice(1, 5)).toEqual([400, 200, 300, 200]);
+ expect(cropped.frame.width).toBe(300);
+ expect(cropped.frame.height).toBe(200);
+ expect(cropped.frame.zoom).toBe(FRAME.zoom);
+ // The cut sits left of and above the view centre, so the frame follows.
+ expect(cropped.frame.lng).toBeLessThan(FRAME.lng);
+ expect(cropped.frame.lat).toBeGreaterThan(FRAME.lat);
+ });
+
+ it('reads the crop in captured pixels, not CSS ones', () => {
+ const cropped = cropCapture(capture(FRAME, 2), { x: 400, y: 300, w: 300, h: 200 }, fakeCanvas);
+ expect(cropped.canvas.width).toBe(600);
+ expect(cropped.canvas.drawn[0].slice(1, 5)).toEqual([800, 600, 600, 400]);
+ // Its own frame is still the CSS box it covers, so projections hold.
+ expect(cropped.frame.width).toBe(300);
+ });
+
+ it('leaves a whole-view frame the size it was', () => {
+ const cropped = cropCapture(capture(), { x: 0, y: 0, w: 1200, h: 800 }, fakeCanvas);
+ expect(cropped.frame.lng).toBeCloseTo(FRAME.lng, 9);
+ expect(cropped.frame.lat).toBeCloseTo(FRAME.lat, 9);
+ });
+});
+
+describe('cropSources', () => {
+ const sources = () => ({ a: capture(), b: capture({ ...FRAME, lng: FRAME.lng + 0.00001 }) });
+
+ it('returns the captures untouched with no frame', () => {
+ const whole = sources();
+ expect(cropSources(whole, null, fakeCanvas)).toBe(whole);
+ });
+
+ it('cuts both sides to the same ground box', () => {
+ const frame = { points: groundRect({ x: 300, y: 200, w: 480, h: 320 }, FRAME) };
+ const cut = cropSources(sources(), frame, fakeCanvas);
+ expect(cut.a.frame.width).toBe(480);
+ expect(cut.b.frame.width).toBe(480);
+ // Within the pixel each cut is rounded to: at zoom 17 that is about a metre.
+ expect(cut.a.frame.lng).toBeCloseTo(cut.b.frame.lng, 4);
+ expect(cut.a.frame.lat).toBeCloseTo(cut.b.frame.lat, 4);
+ // B's camera sits a shade east, so that ground has slid left in its
+ // capture and the same box is taken from further left.
+ expect(cut.b.canvas.drawn[0][1]).toBeLessThan(cut.a.canvas.drawn[0][1]);
+ });
+
+ it('refuses to substitute another area when the saved ground is off screen', () => {
+ const frame = { points: groundRect({ x: -40, y: 200, w: 480, h: 320 }, FRAME) };
+ expect(() => cropSources(sources(), frame, fakeCanvas)).toThrow('must be fully visible');
+ });
+});
+
+describe('exportFrameSpec', () => {
+ it('keeps two ground corners', () => {
+ expect(exportFrameSpec({ points: [[2.3, 48.8], [2.31, 48.79]] }))
+ .toEqual({ points: [[2.3, 48.8], [2.31, 48.79]] });
+ });
+
+ it('drops anything that is not a pair of ground points', () => {
+ expect(exportFrameSpec(null)).toBeNull();
+ expect(exportFrameSpec({ points: [[2.3, 48.8]] })).toBeNull();
+ expect(exportFrameSpec({ points: [[2.3, 48.8], [999, 48.8]] })).toBeNull();
+ expect(exportFrameSpec({ points: [[2.3, 48.8], ['x', 48.8]] })).toBeNull();
+ expect(exportFrameSpec({ points: [[2.3, 48.8], [2.3, 48.8]] })).toBeNull();
+ });
+});
diff --git a/frontend/src/lib/map/layerCard.js b/frontend/src/lib/map/layerCard.js
new file mode 100644
index 0000000..e5d81fc
--- /dev/null
+++ b/frontend/src/lib/map/layerCard.js
@@ -0,0 +1,157 @@
+/**
+ * The card a feature of an added layer opens.
+ *
+ * Read-only by construction: it is built from the strings the source stated and
+ * offers no control at all. Nothing in an added layer enters the case.
+ *
+ * Two things it does beyond printing the description:
+ *
+ * - **A labelled line is drawn as a labelled line.** A My Maps carries its
+ * columns as `label: value`, and the backend now keeps one row per line
+ * (`engine/maplayers.py`). Run together in a paragraph they read as prose;
+ * split into a label and its value they read as the table the source wrote.
+ * The split is per line rather than all-or-nothing, so a description that is
+ * half prose and half columns keeps both.
+ * - **An address is a link.** The analyst's next move on a feature sourced from
+ * a tweet is to open the tweet, and selecting a URL out of a popup to paste it
+ * in a bar is a step nothing is gained by. Built as DOM here rather than as
+ * HTML anywhere: the text belongs to whoever made the file, so it only ever
+ * reaches the page as `textContent`, and a link's address is checked to be
+ * http(s) before it becomes one.
+ */
+import { UNNAMED } from './addedLayers.js';
+
+/** Where a URL starts, and how far it runs: to the first space or quote. */
+const URL_PATTERN = /https?:\/\/[^\s<>"'`]+/g;
+/** …minus what is punctuation rather than address. A sentence ending on a link
+ * would otherwise swallow its full stop, and a parenthesised one its bracket. */
+const TRAILING = /[.,;:!?)\]}>'"]+$/;
+
+/** How long a label may be before the line is prose with a colon in it. */
+const MAX_LABEL = 48;
+/** A line the source wrote as `label: value`. The space after the colon is what
+ * keeps `https://x` and `10:30` out of it. */
+const FIELD = /^([^\s:][^:]{0,46}?)\s*:[ \t]+(\S.*)$/;
+
+/**
+ * A description as the blocks it should be drawn in, in the order written.
+ *
+ * @param {string} text
+ * @returns {Array<{ label: string, value: string } | { text: string }>}
+ */
+export function readBlocks(text) {
+ const blocks = [];
+ let prose = [];
+ const flush = () => {
+ const joined = prose.join('\n').trim();
+ if (joined) blocks.push({ text: joined });
+ prose = [];
+ };
+ for (const line of String(text ?? '').split('\n')) {
+ const match = line.trim().match(FIELD);
+ if (match && match[1].length <= MAX_LABEL) {
+ flush();
+ blocks.push({ label: match[1].trim(), value: match[2].trim() });
+ } else {
+ prose.push(line);
+ }
+ }
+ flush();
+ return blocks;
+}
+
+/**
+ * The pieces of one string: its words, and the addresses among them.
+ *
+ * @param {string} text
+ * @returns {Array<{ text: string, href?: string }>}
+ */
+export function readLinks(text) {
+ const out = [];
+ const source = String(text ?? '');
+ let at = 0;
+ for (const match of source.matchAll(URL_PATTERN)) {
+ const url = match[0].replace(TRAILING, '');
+ if (!url) continue;
+ if (match.index > at) out.push({ text: source.slice(at, match.index) });
+ out.push({ text: url, href: url });
+ at = match.index + url.length;
+ }
+ if (at < source.length) out.push({ text: source.slice(at) });
+ return out;
+}
+
+/** Write a string into an element, its addresses as links. */
+export function fillText(element, text) {
+ for (const piece of readLinks(text)) {
+ if (!piece.href) {
+ element.append(document.createTextNode(piece.text));
+ continue;
+ }
+ const link = document.createElement('a');
+ link.href = piece.href;
+ link.textContent = piece.text;
+ link.target = '_blank';
+ link.rel = 'noreferrer noopener';
+ element.append(link);
+ }
+ return element;
+}
+
+/**
+ * The card builder for one layer, which is why the layer's title is bound here:
+ * with three maps over the imagery at once, a card stating a name and a group
+ * says nothing about *whose* map said it. The layer signs the bottom of it.
+ *
+ * @param {string} title
+ * @returns {(properties: Record<string, any>) => HTMLElement}
+ */
+export function layerCard(title) {
+ return (properties = {}) => {
+ const element = document.createElement('div');
+ element.className = 'layer-card';
+
+ const heading = document.createElement('h4');
+ heading.textContent = properties.name || UNNAMED;
+ element.append(heading);
+
+ if (properties.category) {
+ const group = document.createElement('p');
+ group.className = 'layer-card-group';
+ group.textContent = properties.category;
+ element.append(group);
+ }
+
+ const blocks = readBlocks(properties.description);
+ if (blocks.length) {
+ const body = document.createElement('div');
+ body.className = 'layer-card-body';
+ for (const block of blocks) {
+ if (block.text !== undefined) {
+ const paragraph = document.createElement('p');
+ paragraph.className = 'layer-card-text';
+ fillText(paragraph, block.text);
+ body.append(paragraph);
+ continue;
+ }
+ const field = document.createElement('div');
+ field.className = 'layer-card-field';
+ const label = document.createElement('span');
+ label.className = 'layer-card-label';
+ label.textContent = block.label;
+ const value = document.createElement('span');
+ value.className = 'layer-card-value';
+ fillText(value, block.value);
+ field.append(label, value);
+ body.append(field);
+ }
+ element.append(body);
+ }
+
+ const from = document.createElement('p');
+ from.className = 'layer-card-from';
+ from.textContent = title;
+ element.append(from);
+ return element;
+ };
+}
diff --git a/frontend/src/lib/map/layerCard.test.js b/frontend/src/lib/map/layerCard.test.js
new file mode 100644
index 0000000..af8b635
--- /dev/null
+++ b/frontend/src/lib/map/layerCard.test.js
@@ -0,0 +1,112 @@
+// @vitest-environment happy-dom
+import { describe, it, expect } from 'vitest';
+import { readBlocks, readLinks, fillText, layerCard } from './layerCard.js';
+
+describe('readBlocks', () => {
+ it('reads a labelled line as its label and its value', () => {
+ expect(readBlocks('code: UA\nlayer: OLD26')).toEqual([
+ { label: 'code', value: 'UA' },
+ { label: 'layer', value: 'OLD26' },
+ ]);
+ });
+
+ it('keeps prose and columns in the order they were written', () => {
+ expect(readBlocks('Seen at dawn\nName: North gate\nnothing since')).toEqual([
+ { text: 'Seen at dawn' },
+ { label: 'Name', value: 'North gate' },
+ { text: 'nothing since' },
+ ]);
+ });
+
+ it('leaves a sentence with a colon in it alone', () => {
+ // no space after the colon, so an address and a time stay one piece of prose
+ expect(readBlocks('at 10:30 see https://x.com/a/1')).toEqual([
+ { text: 'at 10:30 see https://x.com/a/1' },
+ ]);
+ });
+
+ it('leaves a long lead-in as prose rather than calling it a label', () => {
+ const line = `${'word '.repeat(12)}: value`;
+ expect(readBlocks(line)).toEqual([{ text: line }]);
+ });
+
+ it('is empty for a feature the source said nothing about', () => {
+ expect(readBlocks('')).toEqual([]);
+ expect(readBlocks(undefined)).toEqual([]);
+ });
+});
+
+describe('readLinks', () => {
+ it('splits an address out of the words around it', () => {
+ expect(readLinks('see https://x.com/a/1 now')).toEqual([
+ { text: 'see ' },
+ { text: 'https://x.com/a/1', href: 'https://x.com/a/1' },
+ { text: ' now' },
+ ]);
+ });
+
+ it('leaves the punctuation that ended the sentence out of the address', () => {
+ expect(readLinks('(https://x.com/a/1).')).toEqual([
+ { text: '(' },
+ { text: 'https://x.com/a/1', href: 'https://x.com/a/1' },
+ { text: ').' },
+ ]);
+ });
+
+ it('links nothing in a string with no address', () => {
+ expect(readLinks('north gate')).toEqual([{ text: 'north gate' }]);
+ });
+});
+
+describe('fillText', () => {
+ it('writes an address as a link that opens away from the app', () => {
+ const element = fillText(document.createElement('p'), 'see https://x.com/a/1');
+ const link = element.querySelector('a');
+ expect(link.href).toBe('https://x.com/a/1');
+ expect(link.target).toBe('_blank');
+ expect(link.rel).toBe('noreferrer noopener');
+ });
+
+ it('never lets the source write markup into the page', () => {
+ const element = fillText(document.createElement('p'), '<img src=x onerror=boom>');
+ expect(element.querySelector('img')).toBeNull();
+ expect(element.textContent).toBe('<img src=x onerror=boom>');
+ });
+});
+
+describe('layerCard', () => {
+ const card = layerCard('Ukraine Control Map v2');
+
+ it('states the name, the group and whose map it came from', () => {
+ const element = card({ name: 'Ua Position', category: 'Archives Geos' });
+ expect(element.querySelector('h4').textContent).toBe('Ua Position');
+ expect(element.querySelector('.layer-card-group').textContent).toBe('Archives Geos');
+ expect(element.querySelector('.layer-card-from').textContent).toBe('Ukraine Control Map v2');
+ });
+
+ it('names a feature the source left unnamed', () => {
+ expect(card({}).querySelector('h4').textContent).toBe('Unnamed feature');
+ });
+
+ it('draws the columns the source wrote as rows, and their addresses as links', () => {
+ const element = card({
+ name: 'Ua Position',
+ description: 'Description: shelling https://x.com/a/1\ncode: UA',
+ });
+ const labels = [...element.querySelectorAll('.layer-card-label')].map((n) => n.textContent);
+ expect(labels).toEqual(['Description', 'code']);
+ const values = [...element.querySelectorAll('.layer-card-value')].map((n) => n.textContent);
+ expect(values).toEqual(['shelling https://x.com/a/1', 'UA']);
+ expect(element.querySelector('.layer-card-value a').href).toBe('https://x.com/a/1');
+ });
+
+ it('carries no body at all when the source described nothing', () => {
+ expect(card({ name: 'Ua Position' }).querySelector('.layer-card-body')).toBeNull();
+ });
+
+ it('offers no way out of itself: a card is read, never acted on', () => {
+ const element = card({ name: 'Ua Position', description: 'code: UA' });
+ expect(element.querySelector('button')).toBeNull();
+ expect(element.querySelector('input')).toBeNull();
+ });
+});
diff --git a/frontend/src/lib/proofSurface.js b/frontend/src/lib/proofSurface.js
new file mode 100644
index 0000000..cd9f22a
--- /dev/null
+++ b/frontend/src/lib/proofSurface.js
@@ -0,0 +1,98 @@
+/**
+ * Non-destructive panel and overlay geometry for Geo Proof.
+ *
+ * A crop is a rectangle of the source image and a turn is an angle. Neither is
+ * baked into pixels: the canvas draws the source through them, so the selection
+ * frame, the crop marks and the annotations all sit on the image's own edges
+ * however far it is turned. What the page has to reserve is the upright box a
+ * turned image needs, which is what `surfaceBoxSize` answers — the layout keeps
+ * working in upright boxes and knows nothing about the angle.
+ */
+
+const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+
+/** A safe source size. Image dimensions are positive integers at this boundary. */
+export function sourceSize(natural) {
+ const width = Math.max(1, Math.round(Number(natural?.[0]) || 1));
+ const height = Math.max(1, Math.round(Number(natural?.[1]) || 1));
+ return [width, height];
+}
+
+/** Keep an angle compact while preserving every free-rotation degree. */
+export function normalizeSurfaceAngle(angle) {
+ const value = Number(angle);
+ if (!Number.isFinite(value)) return 0;
+ const normalized = ((value + 180) % 360 + 360) % 360 - 180;
+ return Math.abs(normalized) < 0.01 ? 0 : normalized;
+}
+
+/**
+ * A crop rectangle in source pixels, or null for "the whole image". Null is the
+ * absence of a crop rather than a full-size one, so nothing has to special-case
+ * a rectangle that happens to cover everything.
+ */
+export function normalizeSourceCrop(crop, natural) {
+ if (!crop || typeof crop !== 'object' || Array.isArray(crop)) return null;
+ const [width, height] = sourceSize(natural);
+ const rawX = Number(crop.x);
+ const rawY = Number(crop.y);
+ const rawW = Number(crop.w);
+ const rawH = Number(crop.h);
+ if (![rawX, rawY, rawW, rawH].every(Number.isFinite) || rawW <= 0 || rawH <= 0) return null;
+
+ const x = clamp(Math.round(rawX), 0, width - 1);
+ const y = clamp(Math.round(rawY), 0, height - 1);
+ const right = clamp(Math.round(rawX + rawW), x + 1, width);
+ const bottom = clamp(Math.round(rawY + rawH), y + 1, height);
+ const normalized = { x, y, w: right - x, h: bottom - y };
+ return x === 0 && y === 0 && normalized.w === width && normalized.h === height
+ ? null
+ : normalized;
+}
+
+/** The pixels actually drawn: the crop when there is one, else the source. */
+export function surfaceImageSize(natural, crop) {
+ const source = sourceSize(natural);
+ const kept = normalizeSourceCrop(crop, source);
+ return kept ? [kept.w, kept.h] : source;
+}
+
+/**
+ * The upright box a rectangle needs once it is turned by `angle`. Rounded up,
+ * but off a hair's tolerance: `cos(90°)` is not quite zero in binary, and
+ * without it every quarter turn would hand the box one more pixel to keep.
+ */
+export function rotatedBoxSize(width, height, angle) {
+ const radians = normalizeSurfaceAngle(angle) * Math.PI / 180;
+ const cos = Math.abs(Math.cos(radians));
+ const sin = Math.abs(Math.sin(radians));
+ const ceil = (value) => Math.max(1, Math.ceil(value - 1e-6));
+ return [ceil(width * cos + height * sin), ceil(width * sin + height * cos)];
+}
+
+/** What the page reserves for a surface: its image, turned, boxed upright. */
+export function surfaceBoxSize(natural, crop, rotation) {
+ const [width, height] = surfaceImageSize(natural, crop);
+ return rotatedBoxSize(width, height, rotation);
+}
+
+/**
+ * Move one annotation with its surface's pixels. A crop shifts the origin the
+ * annotations are measured from; a turn moves nothing, because the annotations
+ * are drawn inside the image and turn with it.
+ */
+export function shiftProofShape(shape, dx, dy) {
+ if (!dx && !dy) return shape;
+ if (Array.isArray(shape.points)) {
+ return {
+ ...shape,
+ points: shape.points.map((value, index) => value + (index % 2 ? dy : dx)),
+ };
+ }
+ return { ...shape, x: (shape.x ?? 0) + dx, y: (shape.y ?? 0) + dy };
+}
+
+/** Apply a coordinate edit only to annotations bound to one surface. */
+export function mapSurfaceShapes(shapes, surfaceId, edit) {
+ return (shapes ?? []).map((shape) => (shape.panel === surfaceId ? edit(shape) : shape));
+}
diff --git a/frontend/src/lib/proofSurface.test.js b/frontend/src/lib/proofSurface.test.js
new file mode 100644
index 0000000..a4620a9
--- /dev/null
+++ b/frontend/src/lib/proofSurface.test.js
@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import {
+ mapSurfaceShapes,
+ normalizeSourceCrop,
+ normalizeSurfaceAngle,
+ rotatedBoxSize,
+ shiftProofShape,
+ sourceSize,
+ surfaceBoxSize,
+ surfaceImageSize,
+} from './proofSurface.js';
+
+describe('proof surface geometry', () => {
+ it('keeps arbitrary angles compact', () => {
+ expect([normalizeSurfaceAngle(-450), normalizeSurfaceAngle(450)]).toEqual([-90, 90]);
+ expect(normalizeSurfaceAngle(42.5)).toBe(42.5);
+ expect(normalizeSurfaceAngle('bad')).toBe(0);
+ });
+
+ it('reads a crop in source pixels and clamps it there', () => {
+ expect(normalizeSourceCrop({ x: -4, y: 10, w: 80, h: 200 }, [100, 80]))
+ .toEqual({ x: 0, y: 10, w: 76, h: 70 });
+ expect(sourceSize([0, -3])).toEqual([1, 1]);
+ });
+
+ it('calls a crop that covers everything no crop at all', () => {
+ // Null is the absence of a box, so nothing downstream has to recognise a
+ // full-size one: the image draws its source and the reset control goes away.
+ expect(normalizeSourceCrop({ x: 0, y: 0, w: 100, h: 80 }, [100, 80])).toBeNull();
+ expect(normalizeSourceCrop(null, [100, 80])).toBeNull();
+ expect(normalizeSourceCrop({ x: 0, y: 0, w: 0, h: 10 }, [100, 80])).toBeNull();
+ });
+
+ it('draws the crop when there is one, and the source otherwise', () => {
+ expect(surfaceImageSize([100, 80], { x: 10, y: 5, w: 40, h: 30 })).toEqual([40, 30]);
+ expect(surfaceImageSize([100, 80], null)).toEqual([100, 80]);
+ });
+
+ it('boxes a turned rectangle upright, which is what the page reserves', () => {
+ expect(rotatedBoxSize(100, 50, 0)).toEqual([100, 50]);
+ expect(rotatedBoxSize(100, 50, 90)).toEqual([50, 100]);
+ expect(rotatedBoxSize(100, 50, -90)).toEqual([50, 100]);
+ // a free turn needs more room than either side of the rectangle
+ const [width, height] = rotatedBoxSize(100, 50, 45);
+ expect(width).toBeGreaterThan(100);
+ expect(height).toBeGreaterThan(50);
+ });
+
+ it('boxes the crop rather than the source once both apply', () => {
+ expect(surfaceBoxSize([400, 300], { x: 20, y: 20, w: 200, h: 100 }, 90)).toEqual([100, 200]);
+ expect(surfaceBoxSize([400, 300], null, 0)).toEqual([400, 300]);
+ });
+});
+
+describe('annotations follow their surface', () => {
+ it('travels with the crop corner they are measured from', () => {
+ expect(shiftProofShape({ x: 20, y: 30 }, -5, 8)).toMatchObject({ x: 15, y: 38 });
+ expect(shiftProofShape({ points: [0, 0, 10, 4] }, -5, 8).points).toEqual([-5, 8, 5, 12]);
+ });
+
+ it('is left alone by a turn, which the group they are drawn in carries', () => {
+ const shape = { kind: 'rect', x: 10, y: 20, rotation: 15 };
+ expect(shiftProofShape(shape, 0, 0)).toBe(shape);
+ });
+
+ it('leaves annotations on the other surfaces untouched', () => {
+ const other = { id: 'b', panel: 'p2', x: 1, y: 2 };
+ const result = mapSurfaceShapes(
+ [{ id: 'a', panel: 'p1', x: 5, y: 6 }, other],
+ 'p1',
+ (shape) => shiftProofShape(shape, 10, 10),
+ );
+ expect(result[0]).toMatchObject({ x: 15, y: 16 });
+ expect(result[1]).toBe(other);
+ });
+});
diff --git a/frontend/src/lib/trash.js b/frontend/src/lib/trash.js
index 918b544..6295d97 100644
--- a/frontend/src/lib/trash.js
+++ b/frontend/src/lib/trash.js
@@ -31,6 +31,7 @@ export const FILE_BACKED = new Set([
'analysis-run',
'note',
'sheet',
+ 'map-layer',
]);
/**
diff --git a/frontend/src/tools/Compare.render.test.js b/frontend/src/tools/Compare.render.test.js
index 2b77bad..b0066ac 100644
--- a/frontend/src/tools/Compare.render.test.js
+++ b/frontend/src/tools/Compare.render.test.js
@@ -31,6 +31,7 @@ const SESSION = {
divider: 61,
opacity: 44,
change_assist: { sensitivity: 60, opacity: 75 },
+ frame: { points: [[5.35, 43.25], [5.45, 43.35]] },
annotations: [
{ id: 'before', kind: 'text', colour: '#f6a81a', points: [[5.4, 43.3]], text: 'Before' },
],
@@ -245,9 +246,19 @@ describe('Compare', () => {
target.querySelector('.compare-bar').compareDocumentPosition(target.querySelector('.source-bar')) &
Node.DOCUMENT_POSITION_FOLLOWING
).toBeTruthy();
+ // The cards are as wide as the maps they describe, so the seam between A and
+ // B is one line: the annotation rail beside the stage narrows both together.
+ const column = target.querySelector('.stage-column');
+ expect(target.querySelector('.source-bar').parentElement).toBe(column);
+ expect(target.querySelector('.compare-stage').parentElement).toBe(column);
+ expect(target.querySelector('.annotation-toolbar').parentElement).toBe(column.parentElement);
// One camera, so one compass in the bar and none on either surface.
expect(target.querySelectorAll('button[aria-label="Reset to north"]')).toHaveLength(1);
expect(target.querySelector('.surface-shell button[aria-label="Reset to north"]')).toBeNull();
+ // local-first: Wayback names its releases once it is on screen, but nothing
+ // walks this point's history until the analyst opens the picker
+ expect(get).toHaveBeenCalledWith('/api/satellite/wayback/releases');
+ expect(get.mock.calls.some(([path]) => path.includes('/wayback/changes'))).toBe(false);
});
it('keeps the cameras together and exposes the swipe and opacity controls', async () => {
@@ -271,6 +282,8 @@ describe('Compare', () => {
expect(target.querySelector('.compare-stage').classList.contains('swipe')).toBe(true);
expect(target.querySelector('input[aria-label="Swipe divider"]')).toBeNull();
const divider = target.querySelector('button[aria-label="Swipe divider on imagery"]');
+ expect(divider.querySelectorAll('.swipe-handle svg')).toHaveLength(2);
+ expect(divider.textContent).not.toContain('↔');
divider.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }));
flushSync();
expect(target.querySelector('.compare-stage').style.getPropertyValue('--divider')).toBe('52%');
@@ -458,6 +471,73 @@ describe('Compare', () => {
expect(output.textContent).toContain('Export copy');
});
+ it('frames an export on the ground and keeps the frame with the comparison', async () => {
+ await open();
+ await add('A');
+ await add('B');
+
+ button('Export', target).click();
+ await settle();
+ expect(document.querySelector('[role="dialog"]').textContent).toContain('Full view');
+
+ button('Draw', document.querySelector('[role="dialog"]')).click();
+ flushSync();
+ // The stage has to be reachable while the frame is drawn, so the modal goes.
+ expect(document.querySelector('[role="dialog"]')).toBeNull();
+ const overlay = target.querySelector('.export-frame.drawing');
+ overlay.getBoundingClientRect = () => ({ left: 0, top: 0, width: 1000, height: 600 });
+ for (const [type, x, y] of [['pointerdown', 10, 5], ['pointermove', 410, 365], ['pointerup', 410, 365]]) {
+ overlay.dispatchEvent(new MouseEvent(type, { bubbles: true, clientX: x, clientY: y }));
+ flushSync();
+ }
+
+ // Back in the export, stated as ground rather than pixels.
+ const output = document.querySelector('[role="dialog"]');
+ expect(output.getAttribute('aria-label')).toBe('Export a copy');
+ expect(output.textContent).not.toContain('Full view');
+ expect([...output.querySelectorAll('.destination-actions button')].map((entry) => entry.textContent.trim()))
+ .toEqual(['Redraw…', 'Clear']);
+ expect(target.querySelectorAll('.export-frame')).toHaveLength(2);
+ expect(target.querySelectorAll('.export-frame.readonly')).toHaveLength(1);
+
+ output.querySelector('button[aria-label="Close"]').click();
+ button('Save comparison', target).click();
+ flushSync();
+ button('Save comparison', document.querySelector('[role="dialog"]')).click();
+ await settle();
+ expect(post).toHaveBeenCalledWith(
+ '/api/cases/case-a/compare/sessions',
+ expect.objectContaining({
+ spec: expect.objectContaining({ frame: { points: [[10, 5], [410, 365]] } }),
+ })
+ );
+ button('New', target).click();
+ flushSync();
+ expect(target.querySelector('.export-frame')).toBeNull();
+ });
+
+ it.each(['Swipe', 'Fade', 'Blink'])(
+ 'draws one export frame across the complete %s stage',
+ async (label) => {
+ await open();
+ await add('A');
+ await add('B');
+ button(label, target).click();
+ flushSync();
+
+ button('Export', target).click();
+ await settle();
+ button('Draw', document.querySelector('[role="dialog"]')).click();
+ flushSync();
+
+ const overlay = target.querySelector('.export-frame.drawing');
+ expect(overlay.parentElement).toBe(target.querySelector('.compare-stage'));
+ window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }));
+ flushSync();
+ expect(document.querySelector('[role="dialog"]').getAttribute('aria-label')).toBe('Export a copy');
+ }
+ );
+
it('adds a note over the comparison and keeps it in the editable state', async () => {
await open();
await add('A');
@@ -575,6 +655,7 @@ describe('Compare', () => {
expect(target.querySelector('input[aria-label="Comparison name"]').value).toBe('Harbour change');
expect(target.querySelector('.compare-stage').classList.contains('swipe')).toBe(true);
expect(target.querySelector('.compare-stage').style.getPropertyValue('--divider')).toBe('61%');
+ expect(target.querySelector('.compare-stage > .export-frame')).not.toBeNull();
expect(target.querySelectorAll('.surface-shell')).toHaveLength(2);
expect(engines.at(-1).camera()).toEqual(expect.objectContaining({ lat: 43.3, lon: 5.4, zoom: 18 }));
});
diff --git a/frontend/src/tools/Compare.svelte b/frontend/src/tools/Compare.svelte
index 9c7a3d9..a8f5a0c 100644
--- a/frontend/src/tools/Compare.svelte
+++ b/frontend/src/tools/Compare.svelte
@@ -49,6 +49,8 @@
canFill,
comparisonAnnotations,
} from '../lib/map/compareAnnotations.js';
+ import { cropSources, exportFrameSpec, frameSpan } from '../lib/map/exportFrame.js';
+ import { formatDistance } from '../lib/measure.js';
import { captureTab, extensionVersion } from '../lib/extBridge.js';
import {
CASE_FOLDER_LABEL,
@@ -93,6 +95,7 @@
import LayerPane from './compare/LayerPane.svelte';
import AnnotationCanvas from './compare/AnnotationCanvas.svelte';
import AnnotationToolbar from './compare/AnnotationToolbar.svelte';
+ import ExportFrame from './compare/ExportFrame.svelte';
import { createSavedState } from './satellite/state/saved.svelte.js';
import PlaceSearch from './satellite/PlaceSearch.svelte';
import { createImageryState, FALLBACK_PROVIDER } from './satellite/state/imagery.svelte.js';
@@ -121,6 +124,11 @@
let grabbing = $state(false);
let captureSide = $state(null); // surface visible during an extension frame
let exportKind = $state('png'); // 'png' | 'blink' | 'slide'
+ // What an export is cut to, as two ground corners, and whether one is being
+ // drawn right now. No frame means the whole view, which is the default.
+ let exportFrame = $state(null);
+ let framing = $state(false);
+ let blinkPausedBeforeFraming = null;
let exportDestination = $state(null);
let exportPicker = $state(false);
let sessionName = $state('Comparison');
@@ -663,16 +671,20 @@
$effect(() => {
if (b.ready && shownB.provider?.id === WAYBACK_ID) wbb.loadReleases();
});
+ // Once a side's picker has been opened, its history follows the map, picker
+ // open or not: both surfaces share one view, so both walk the same tile.
$effect(() => {
- if (!wba.menuOpen || shownA.provider?.id !== WAYBACK_ID || !wba.stale) return;
+ if (!wba.watching || shownA.provider?.id !== WAYBACK_ID) return;
+ wba.here;
clearTimeout(wbaChangesTimer);
- wbaChangesTimer = setTimeout(() => wba.loadChanges(), 900);
+ wbaChangesTimer = setTimeout(() => wba.follow(), 900);
return () => clearTimeout(wbaChangesTimer);
});
$effect(() => {
- if (!wbb.menuOpen || shownB.provider?.id !== WAYBACK_ID || !wbb.stale) return;
+ if (!wbb.watching || shownB.provider?.id !== WAYBACK_ID) return;
+ wbb.here;
clearTimeout(wbbChangesTimer);
- wbbChangesTimer = setTimeout(() => wbb.loadChanges(), 900);
+ wbbChangesTimer = setTimeout(() => wbb.follow(), 900);
return () => clearTimeout(wbbChangesTimer);
});
@@ -803,6 +815,7 @@
blink: { interval: blinkInterval },
change_assist: changeSettings(changeOptions),
annotations: comparisonAnnotations(annotations),
+ frame: exportFrame,
a: sideSpec(a, s2a, wba),
b: sideSpec(b, s2b, wbb),
};
@@ -916,6 +929,7 @@
changeOptions = changeSettings(spec.change_assist);
blinkInterval = spec.blink?.interval ?? 800;
annotations = comparisonAnnotations(spec.annotations);
+ exportFrame = exportFrameSpec(spec.frame);
resetAnnotationHistory();
applySide(a, s2a, wba, spec.a);
applySide(b, s2b, wbb, spec.b);
@@ -996,6 +1010,9 @@
annotations = [];
annotationTool = 'select';
resetAnnotationHistory();
+ exportFrame = null;
+ framing = false;
+ blinkPausedBeforeFraming = null;
sessionName = 'Comparison';
openedSession = null;
savedSignature = null;
@@ -1467,6 +1484,40 @@
}
}
+ /** The captured surfaces as the export shows them: whole, or cut to the frame. */
+ async function exportSources() {
+ return cropSources(await sourceCanvases(), exportFrame);
+ }
+
+ /** The frame stated as the ground it covers, which no camera can change. */
+ function frameLabel(value) {
+ const span = frameSpan(value.points, bearing);
+ return `${formatDistance(span.width, prefs.units)} × ${formatDistance(span.height, prefs.units)}`;
+ }
+
+ function startFraming() {
+ rightPanel = null;
+ framing = true;
+ if (mode === 'blink') {
+ blinkPausedBeforeFraming = blinkPaused;
+ blinkPaused = true;
+ }
+ }
+
+ function finishFraming() {
+ framing = false;
+ if (blinkPausedBeforeFraming !== null) {
+ blinkPaused = blinkPausedBeforeFraming;
+ blinkPausedBeforeFraming = null;
+ }
+ rightPanel = 'export';
+ }
+
+ function setExportFrame(next) {
+ exportFrame = next;
+ finishFraming();
+ }
+
function compose(
sources,
{ renderMode = captureMode, renderBlinkB = blinkB, renderChangeMap = changeResult } = {}
@@ -1500,7 +1551,7 @@
clearTimeout(changeTimer);
await refreshChangeAssist({ fetch: changeFrames !== '' });
}
- const sources = await sourceCanvases();
+ const sources = await exportSources();
if (mode === 'change' && (changeRenderedKey !== changeKey() || !changeResult)) {
throw new Error('Run Difference for this view before exporting');
}
@@ -1511,7 +1562,7 @@
async function saveWorkingPreview(caseId, name) {
const form = new FormData();
if (mode === 'blink') {
- const sources = await sourceCanvases();
+ const sources = await exportSources();
const frameA = await canvasBlob(compose(sources, { renderMode: 'blink', renderBlinkB: false }));
const frameB = await canvasBlob(compose(sources, { renderMode: 'blink', renderBlinkB: true }));
form.append('image_a', frameA, 'comparison-a.png');
@@ -1568,7 +1619,7 @@
outputBusy = 'gif';
try {
const owner = await ensureCase();
- const sources = await sourceCanvases();
+ const sources = await exportSources();
const frameA = await canvasBlob(compose(sources, { renderMode: 'blink', renderBlinkB: false }));
const frameB = await canvasBlob(compose(sources, { renderMode: 'blink', renderBlinkB: true }));
const form = new FormData();
@@ -1695,23 +1746,6 @@
{/each}
</div>
{/if}
- <!-- Detect owns the imagery while it is on, so the cards would be a second
- place to choose the same thing. One choice, one place. -->
- {#if (a.present || b.present) && !detecting}
- <div class="source-bar" aria-label="Compared imagery">
- {#if a.present}
- <SourceCard letter="A" {imagery} bind:providerId={a.providerId} s2={s2a} wayback={wba}
- shown={shownA} dated={a.dated} layerCount={a.overlays.length} layersOpen={rightPanel === 'layers'}
- onlayers={() => toggleRightPanel('layers')} onremove={() => remove('a')} />
- {:else}<button class="source-add" onclick={() => (picking = 'a')}>A · Add imagery</button>{/if}
- {#if b.present}
- <SourceCard letter="B" {imagery} bind:providerId={b.providerId} s2={s2b} wayback={wbb}
- shown={shownB} dated={b.dated} align="right" layerCount={b.overlays.length} layersOpen={rightPanel === 'layers'}
- onlayers={() => toggleRightPanel('layers')} onremove={() => remove('b')} />
- {:else}<button class="source-add" onclick={() => (picking = 'b')}>B · Add imagery</button>{/if}
- </div>
- {/if}
-
<div class="compare-workspace">
{#if both && !detecting}
<AnnotationToolbar
@@ -1738,6 +1772,28 @@
count={annotations.length}
/>
{/if}
+
+ <!-- The cards ride over the stage, not over the tool: the annotation rail on
+ the left and a computing panel on the right both narrow the stage, and a
+ full-width bar put the seam between the cards tens of pixels away from
+ the seam between the maps.
+ Detect owns the imagery while it is on, so the cards would be a second
+ place to choose the same thing. One choice, one place. -->
+ <div class="stage-column">
+ {#if (a.present || b.present) && !detecting}
+ <div class="source-bar" aria-label="Compared imagery">
+ {#if a.present}
+ <SourceCard letter="A" {imagery} bind:providerId={a.providerId} s2={s2a} wayback={wba}
+ shown={shownA} dated={a.dated} layerCount={a.overlays.length} layersOpen={rightPanel === 'layers'}
+ onlayers={() => toggleRightPanel('layers')} onremove={() => remove('a')} />
+ {:else}<button class="source-add" onclick={() => (picking = 'a')}>A · Add imagery</button>{/if}
+ {#if b.present}
+ <SourceCard letter="B" {imagery} bind:providerId={b.providerId} s2={s2b} wayback={wbb}
+ shown={shownB} dated={b.dated} align="right" layerCount={b.overlays.length} layersOpen={rightPanel === 'layers'}
+ onlayers={() => toggleRightPanel('layers')} onremove={() => remove('b')} />
+ {:else}<button class="source-add" onclick={() => (picking = 'b')}>B · Add imagery</button>{/if}
+ </div>
+ {/if}
<div
class="compare-stage"
class:overlay={both && stageMode !== 'side'}
@@ -1818,6 +1874,12 @@
style:width={`${changeResult.frame.width}px`} style:height={`${changeResult.frame.height}px`}
style:transform={changeTransform.a} />
{/if}
+ <!-- Side by side has two coordinate spaces, so A owns the editable
+ frame and B shows the matching ground read-only. -->
+ {#if both && !grabbing && !detecting && stageMode === 'side' && (framing || exportFrame)}
+ <ExportFrame engine={a.engine} frame={exportFrame} drawing={framing} units={prefs.units} {bearing}
+ onframe={setExportFrame} oncancel={finishFraming} />
+ {/if}
{#if both && !grabbing && !detecting}
<AnnotationCanvas bind:this={canvasA} {annotations} engine={a.engine} letter="a" units={prefs.units}
active={uiState.tool === 'compare'} bind:tool={annotationTool} bind:selectedId={selectedAnnotationId}
@@ -1913,6 +1975,9 @@
style:width={`${changeResult.frame.width}px`} style:height={`${changeResult.frame.height}px`}
style:transform={changeTransform.b} />
{/if}
+ {#if both && !grabbing && !detecting && stageMode === 'side' && exportFrame}
+ <ExportFrame engine={b.engine} frame={exportFrame} readonly={true} units={prefs.units} {bearing} />
+ {/if}
{#if both && !grabbing && !detecting}
<AnnotationCanvas bind:this={canvasB} {annotations} engine={b.engine} letter="b" units={prefs.units}
active={uiState.tool === 'compare'} bind:tool={annotationTool} bind:selectedId={selectedAnnotationId}
@@ -1956,7 +2021,21 @@
onpointerup={stopSwipe}
onpointercancel={stopSwipe}
onkeydown={keySwipe}
- ><span>↔</span></button>
+ >
+ <span class="swipe-handle" aria-hidden="true">
+ <Icon name="chevronLeft" size={12} stroke={2.4} />
+ <i></i>
+ <Icon name="chevronRight" size={12} stroke={2.4} />
+ </span>
+ </button>
+ {/if}
+
+ <!-- Fade, Swipe, Blink and the single-image Difference layouts stack both
+ maps in one coordinate space. Their frame therefore sits above the
+ complete stage, where neither B nor the swipe clip can block it. -->
+ {#if both && !grabbing && !detecting && stageMode !== 'side' && (framing || exportFrame)}
+ <ExportFrame engine={a.engine} frame={exportFrame} drawing={framing} units={prefs.units} {bearing}
+ onframe={setExportFrame} oncancel={finishFraming} />
{/if}
{#if both && mode === 'change'}
@@ -1969,6 +2048,7 @@
{/if}
</div>
+ </div>
<!-- The two computing modes share this column, so where their settings live
never depends on which one is on: the stage narrows, the maps stay whole
@@ -2016,6 +2096,17 @@
</label>
</div>
+ <div class="destination">
+ <span class="field-label">Frame</span>
+ <strong>{exportFrame ? frameLabel(exportFrame) : 'Full view'}</strong>
+ <span class="destination-actions">
+ <button type="button" class="link" onclick={startFraming}>{exportFrame ? 'Redraw…' : 'Draw…'}</button>
+ {#if exportFrame}
+ <button type="button" class="link muted" onclick={() => (exportFrame = null)}>Clear</button>
+ {/if}
+ </span>
+ </div>
+
<div class="destination">
<span class="field-label">Destination</span>
<strong title={exportDestination || CASE_FOLDER_LABEL}>
@@ -2232,6 +2323,9 @@
.mode-footer { display: flex; justify-content: center; padding: 6px; background: var(--bg-1); }
.presets { display: flex; justify-content: center; gap: 8px; padding: 8px; }
.compare-workspace { display: flex; min-height: 0; flex: 1; }
+ /* The cards and the maps they describe share one width, so the split between
+ A and B is one line down the whole tool. */
+ .stage-column { display: flex; flex-direction: column; flex: 1; min-width: 0; min-height: 0; }
.compare-stage {
position: relative;
flex: 1;
@@ -2360,6 +2454,8 @@
bottom: 0;
left: var(--divider);
width: 2px;
+ padding: 0;
+ border: 0;
transform: translateX(-1px);
background: rgba(255,255,255,.92);
cursor: ew-resize;
@@ -2371,20 +2467,42 @@
position: absolute;
inset: 0 -12px;
}
- .swipe-line:focus-visible span { outline: 2px solid var(--accent); outline-offset: 2px; }
- .swipe-line span {
+ .swipe-line:focus-visible { outline: none; }
+ .swipe-line:focus-visible .swipe-handle {
+ box-shadow: 0 0 0 2px var(--accent), 0 4px 14px rgba(0,0,0,.45);
+ }
+ .swipe-handle {
position: absolute;
top: 50%;
left: 50%;
- display: grid;
- place-items: center;
- width: 32px;
- height: 32px;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ gap: 3px;
+ width: 40px;
+ height: 30px;
transform: translate(-50%, -50%);
- border-radius: 50%;
- color: #181818;
- background: #f2f2f2;
- box-shadow: var(--shadow-2);
+ border: 1px solid rgba(255,255,255,.38);
+ border-radius: 9px;
+ color: #f8fafc;
+ background: rgba(24,24,24,.88);
+ backdrop-filter: blur(6px);
+ box-shadow: 0 4px 14px rgba(0,0,0,.45);
+ pointer-events: none;
+ transition: background 120ms ease, border-color 120ms ease, transform 120ms ease;
+ }
+ .swipe-handle i {
+ width: 1px;
+ height: 14px;
+ background: rgba(255,255,255,.28);
+ }
+ .swipe-line:hover .swipe-handle {
+ border-color: rgba(255,255,255,.62);
+ background: rgba(12,12,12,.94);
+ transform: translate(-50%, -50%) scale(1.04);
+ }
+ .swipe-line:active .swipe-handle {
+ transform: translate(-50%, -50%) scale(.98);
}
.rotate-pivot {
position: absolute;
@@ -2460,7 +2578,10 @@
.destination { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: 5px 10px; align-items: center; padding-top: 13px; border-top: 1px solid var(--border); }
.destination .field-label { grid-column: 1 / -1; }
.destination strong { overflow: hidden; color: var(--text-2); font-size: var(--fs-xs); text-overflow: ellipsis; white-space: nowrap; }
+ .destination-actions { display: flex; align-items: center; justify-content: flex-end; gap: 12px; }
.link { color: var(--accent); font-size: var(--fs-xs); }
+ .link.muted { color: var(--text-3); }
+ .link.muted:hover { color: var(--text-1); }
.panel-note,
.panel-intro { margin: 0; color: var(--text-3); font-size: var(--fs-xs); line-height: 1.45; }
.panel-intro { padding: 0 0 12px; }
diff --git a/frontend/src/tools/ProofComposer.svelte b/frontend/src/tools/ProofComposer.svelte
index fcf1d15..60280ea 100644
--- a/frontend/src/tools/ProofComposer.svelte
+++ b/frontend/src/tools/ProofComposer.svelte
@@ -35,7 +35,7 @@
ANNO_COLORS, PAD, GAP, ROW_GAP, PANEL_H, TWEET_GUIDES,
CAPTION_SIZE, LEGEND_SIZE, FOOTER_SIZE,
BG, TEXT_MAIN, normSpace, textColors,
- layoutPanels, panelsBottom, freeNormalizeDelta, legendLineHeight, footerBand,
+ layoutPanels, panelsBottom, panelScale, freeNormalizeDelta, legendLineHeight, footerBand,
attributionLine, docSize, offsetShape, autoLayoutRows,
autoCoords, formatCoords, autoSourceUrls, proofSource, statedSources,
specPoints, statePanelPoint, footerLines, coordsPostLines, proofCoordsLines, MAX_POINTS,
@@ -67,6 +67,15 @@
textBoxPad,
viewCentrePoint,
} from '../lib/proofEdits.js';
+ import {
+ mapSurfaceShapes,
+ normalizeSourceCrop,
+ normalizeSurfaceAngle,
+ shiftProofShape,
+ sourceSize,
+ surfaceBoxSize,
+ surfaceImageSize,
+ } from '../lib/proofSurface.js';
import {
ICON_BOX, ICON_SIZE_MIN, PROOF_ICONS,
glyphInk, iconByName, iconOrigin, iconSizeFor, isSolidIcon,
@@ -81,6 +90,9 @@
import { pollWhile } from '../lib/poll.js';
const SCALE_STEP = 0.05;
+ // Canvas handles are drawn, not styled, so the one accent has to be spelled
+ // out here. Keep it equal to --accent in app.css.
+ const ACCENT = '#e8a33d';
const DRAW_TOOLS = [
{ id: 'select', icon: 'cursor', label: 'Select / move', shortcut: 'v' },
@@ -141,6 +153,8 @@
}
let advancedOpen = $state(false);
let collapsed = $state({ panels: false, overlays: false, annotations: false, elements: false });
+ let cropSurfaceId = $state(null);
+ let cropDraft = $state(null); // crop rectangle in the selected surface's pixels
// Saved proof slug, or null before the first save.
let savedName = $state(null);
let dirty = $state(false);
@@ -294,6 +308,32 @@
let histBusy = false; // plain (untracked): suppresses capture while restoring
let histTimer = null;
+ /**
+ * Attach a source image to a spec surface. `natural` becomes the upright box
+ * the turned image occupies, because that is what the page lays out; the
+ * source size it was read from is kept beside it.
+ */
+ function hydratedSurface(surface, img) {
+ const sourceNatural = sourceSize(surface.sourceNatural ?? surface.natural);
+ const hydrated = {
+ ...surface,
+ sourceNatural,
+ crop: normalizeSourceCrop(surface.crop, sourceNatural),
+ rotation: normalizeSurfaceAngle(surface.rotation),
+ img,
+ };
+ refreshSurface(hydrated);
+ return hydrated;
+ }
+
+ /** Re-measure one hydrated surface after its crop or turn changes. */
+ function refreshSurface(surface) {
+ surface.natural = surfaceBoxSize(surface.sourceNatural, surface.crop, surface.rotation);
+ }
+
+ /** The pixels a surface draws: its crop, or the whole source. */
+ const imageSizeOf = (surface) => surfaceImageSize(surface.sourceNatural, surface.crop);
+
const docSnapshot = () => JSON.stringify(toSpec(proof));
function syncHist() {
@@ -353,18 +393,20 @@
proof.notes = spec.notes ?? {};
proof.legendOrder = spec.legendOrder ?? [];
proof.templateId = typeof spec.templateId === 'string' ? spec.templateId : null;
- proof.panels = spec.panels.map((p) => ({ ...p, img: imgCache.get(p.src) ?? null }));
- proof.pastes = (spec.pastes ?? []).map((p) => ({
- ...p,
- img: pasteAssets.get(p.asset)?.img ?? null,
- }));
+ proof.panels = spec.panels.map((p) => {
+ const img = imgCache.get(p.src);
+ return img ? hydratedSurface(p, img) : hydratedSurface(p, null);
+ });
+ proof.pastes = (spec.pastes ?? []).map((p) => {
+ return hydratedSurface(p, pasteAssets.get(p.asset)?.img ?? null);
+ });
proof.shapes = spec.shapes ?? [];
// a panel image missing from the cache (shouldn't happen) reloads async
for (const p of proof.panels.filter((x) => !x.img)) {
loadImage(fileUrl(caseState.current?.id, p.src))
.then((img) => {
imgCache.set(p.src, img);
- p.img = img;
+ Object.assign(p, hydratedSurface(p, img));
})
.catch(() => {});
}
@@ -399,7 +441,8 @@
// ---- konva ------------------------------------------------------------------
let containerEl = $state();
- let stage, docLayer, uiLayer, transformer, endHandles, guideGroup, panelCtrls;
+ let stage, docLayer, uiLayer, transformer, cropHandles, endHandles, guideGroup, panelCtrls;
+ let rotateKnob;
let canvasRenderGate;
let drawing = null; // {panel, node, start, box, kind}
let pathDraft = null; // {panel, box, node, points:[]} — multi-click curve in progress
@@ -427,6 +470,9 @@
stage.add(docLayer, uiLayer);
transformer = new Konva.Transformer({
rotateEnabled: false,
+ rotateAnchorOffset: 28,
+ rotationSnaps: [0, 90, 180, 270],
+ rotationSnapTolerance: 5,
flipEnabled: false,
anchorSize: 11,
anchorCornerRadius: 3,
@@ -435,10 +481,23 @@
borderStroke: '#e8a33d',
borderDash: [4, 3],
ignoreStroke: true,
+ // The turn knob reads like Collage's: a dark disc ringed in the accent,
+ // on a short accent stem, rather than the square corner anchors.
+ anchorStyleFunc: (anchor) => {
+ if (!anchor.hasName('rotater')) return;
+ anchor.cornerRadius(anchor.width() / 2);
+ anchor.fill('rgba(22, 22, 22, 0.92)');
+ anchor.stroke(ACCENT);
+ anchor.strokeWidth(1.5);
+ },
});
guideGroup = new Konva.Group({ listening: false });
uiLayer.add(guideGroup);
uiLayer.add(transformer);
+ rotateKnob = new Konva.Group({ name: 'rotate-knob', listening: false });
+ uiLayer.add(rotateKnob);
+ cropHandles = new Konva.Group({ id: 'proof-crop-handles' });
+ uiLayer.add(cropHandles);
endHandles = new Konva.Group();
uiLayer.add(endHandles);
panelCtrls = new Konva.Group();
@@ -549,6 +608,7 @@
tool; // the tool alone: the document has its own rebuild below
untrack(() => {
if (!stage) return;
+ if (tool !== 'select' && cropSurfaceId) endSurfaceCrop();
syncCanvasListening();
if (proofHasContent) refreshCanvasUi();
});
@@ -558,8 +618,14 @@
// and gets a lightweight refresh below, without recreating every image node.
$effect(() => {
JSON.stringify([
- proof.panels.map((p) => [p.src, p.caption, p.row, p.scale, p.x, p.y, p.frame]),
- proof.pastes.map((p) => [p.asset, p.x, p.y, p.scale, p.frame, !!p.img]),
+ proof.panels.map((p) => [
+ p.src, p.caption, p.row, p.scale, p.x, p.y, p.frame,
+ p.crop, p.rotation, p.natural, !!p.img,
+ ]),
+ proof.pastes.map((p) => [
+ p.asset, p.x, p.y, p.scale, p.frame,
+ p.crop, p.rotation, p.natural, !!p.img,
+ ]),
proof.shapes,
proof.notes,
proof.legendOrder,
@@ -611,6 +677,7 @@
proof.title = freshTitle();
proof.panels = [];
proof.pastes = [];
+ discardSurfaceCrop();
proof.shapes = [];
proof.notes = {};
proof.legendOrder = [];
@@ -748,6 +815,7 @@
}
function selectSig(which) {
+ endSurfaceCrop();
selectedSig = which;
selectedIds = [];
selectedPanelId = null;
@@ -756,6 +824,7 @@
function selectPaste(id) {
if (tool !== 'select') return;
+ if (cropSurfaceId && cropSurfaceId !== id) endSurfaceCrop();
selectedPasteId = id;
selectedIds = [];
selectedPanelId = null;
@@ -764,6 +833,7 @@
function selectPanel(id) {
if (tool !== 'select' || marqueeEnded) return;
+ if (cropSurfaceId && cropSurfaceId !== id) endSurfaceCrop();
selectedPanelId = id;
selectedPasteId = null;
selectedIds = [];
@@ -781,6 +851,7 @@
*/
function pickShapeRow(id, additive = false) {
tool = 'select';
+ endSurfaceCrop();
pickShape(id, additive);
}
@@ -788,6 +859,7 @@
function pickPanelRow(id) {
tool = 'select';
marqueeEnded = false;
+ if (cropSurfaceId !== id || selectedPanelId === id) endSurfaceCrop();
selectedPanelId = selectedPanelId === id ? null : id;
selectedPasteId = null;
selectedIds = [];
@@ -796,6 +868,7 @@
function pickPasteRow(id) {
tool = 'select';
+ if (cropSurfaceId !== id || selectedPasteId === id) endSurfaceCrop();
selectedPasteId = selectedPasteId === id ? null : id;
selectedPanelId = null;
selectedIds = [];
@@ -981,7 +1054,7 @@
: proof.panels.length
? Math.max(...proof.panels.map((p) => p.row ?? 0))
: 0;
- const panel = {
+ const panel = hydratedSurface({
id: newId('p'),
src: item.src,
// captionsEnabled off → new panels start caption-less (you can still add
@@ -991,8 +1064,7 @@
scale: 1,
natural: [img.naturalWidth, img.naturalHeight],
meta: item.meta ?? {},
- img,
- };
+ }, img);
// what the proof answers with today, read before the panel can change it
const answered = displayedCoords;
// grid: append (rightmost / bottom row); free: a new panel lands in front
@@ -1092,16 +1164,29 @@
stage.position({ x: stage.x() - dx * stage.scaleX(), y: stage.y() - dy * stage.scaleY() });
}
- // Fold a finished panel drag / corner-resize back into the document.
+ // Fold a finished panel move/resize/rotation back into the document. Image
+ // groups are centred so the round rotation handle turns around their centre.
function commitPanelNode(panel, node, { resized = false } = {}) {
- materializeFreePositions();
- if (resized) {
- panel.scale = scaleFromNode(node.scaleX(), panel.natural[1]);
+ const free = proof.layout === 'free';
+ if (free) materializeFreePositions();
+ // The group sits on the image's middle, so this is where the picture is —
+ // the one point that has to survive a turn, which changes the box around it.
+ const centre = node.position();
+ // The node's scale is the image's, so the panel's own height reads off the
+ // image too — the box around a turned one is bigger and is not what was sized.
+ if (resized) panel.scale = scaleFromNode(node.scaleX(), imageSizeOf(panel)[1]);
+ const turned = applySurfaceRotation(panel, node.rotation());
+ if (free) {
+ const k = panelScale(panel);
+ panel.x = centre.x - panel.natural[0] * k / 2;
+ panel.y = centre.y - panel.natural[1] * k / 2;
+ normalizeFree();
}
- panel.x = node.x();
- panel.y = node.y();
- normalizeFree();
dirty = true;
+ // The grid re-flows around the new bounds, so a resize refits the page. A
+ // turn does not: the page it needs grows as the picture comes round, and
+ // rescaling the view under the hand mid-gesture reads as the photo shrinking.
+ if (!free && !turned) requestAnimationFrame(fit);
}
function setLayoutMode(mode) {
@@ -1142,6 +1227,7 @@
function removePanel(index) {
const panel = proof.panels[index];
+ if (cropSurfaceId === panel?.id) discardSurfaceCrop(); // it is leaving anyway
proof.shapes = proof.shapes.filter((s) => s.panel !== panel.id);
proof.panels.splice(index, 1);
normalizeRows();
@@ -1200,13 +1286,12 @@
const natural = [img.naturalWidth, img.naturalHeight];
const scale = pasteInsertScale(natural, width);
const centre = viewCentre();
- const paste = newPaste(name, natural, {
+ const paste = hydratedSurface(newPaste(name, natural, {
x: centre.x - (natural[0] * scale) / 2,
y: centre.y - (natural[1] * scale) / 2,
scale,
- });
+ }), img);
Object.assign(paste, clampPaste(paste, width, height));
- paste.img = img;
proof.pastes.unshift(paste); // newest lands in front
tool = 'select';
selectPaste(paste.id);
@@ -1276,6 +1361,7 @@
function removePaste(index) {
const paste = proof.pastes[index];
if (!paste) return;
+ if (cropSurfaceId === paste.id) discardSurfaceCrop(); // it is leaving anyway
proof.shapes = proof.shapes.filter((s) => s.panel !== paste.id);
proof.pastes.splice(index, 1);
selectedIds = [];
@@ -1291,6 +1377,144 @@
dirty = true;
}
+ /**
+ * Change a surface's pixel geometry without making it jump in free layout.
+ * Grid panels deliberately reflow; free panels and overlays keep their visual
+ * centre, then return inside the document if their new bounds cross an edge.
+ */
+ function withSurfaceCentrePreserved(item, edit) {
+ const panelIndex = proof.panels.findIndex((panel) => panel.id === item.id);
+ const pasteIndex = proof.pastes.findIndex((paste) => paste.id === item.id);
+ let before = null;
+
+ if (panelIndex >= 0 && proof.layout === 'free') {
+ materializeFreePositions();
+ before = boxesOf()[panelIndex];
+ } else if (pasteIndex >= 0) {
+ before = pasteBoxes([item])[0];
+ }
+
+ edit();
+
+ if (panelIndex >= 0) {
+ if (proof.layout === 'free' && before) {
+ const after = boxesOf()[panelIndex];
+ item.x += (before.w - after.w) / 2;
+ item.y += (before.h - after.h) / 2;
+ normalizeFree();
+ return; // the centre held: refitting here would throw the zoom away
+ }
+ requestAnimationFrame(fit);
+ return;
+ }
+
+ if (pasteIndex >= 0 && before) {
+ const after = pasteBoxes([item])[0];
+ item.x += (before.w - after.w) / 2;
+ item.y += (before.h - after.h) / 2;
+ const { width, height } = measureDoc();
+ Object.assign(item, clampPaste(item, width, height));
+ }
+ }
+
+ /**
+ * Turn a surface. The angle rides on the group that holds the image and its
+ * annotations, so nothing is redrawn into new pixels and no coordinate moves:
+ * the image, its border, its marks and its notes all turn as one.
+ */
+ function applySurfaceRotation(item, angle) {
+ const turned = normalizeSurfaceAngle(angle);
+ if (turned === (item.rotation ?? 0)) return false;
+ item.rotation = turned;
+ refreshSurface(item);
+ return true;
+ }
+
+ const surfaceById = (id) => (id
+ ? proof.panels.find((panel) => panel.id === id)
+ ?? proof.pastes.find((paste) => paste.id === id)
+ ?? null
+ : null);
+
+ /**
+ * The on-canvas crop mode, opened by a double-click or the side control. Both
+ * toggle: asking again for the image already under the marks is how you say
+ * you are done with it, without reaching for the canvas.
+ */
+ function beginSurfaceCrop(item) {
+ if (!item?.img) return;
+ if (cropSurfaceId) {
+ const same = cropSurfaceId === item.id;
+ endSurfaceCrop();
+ if (same) return;
+ }
+ tool = 'select';
+ cropSurfaceId = item.id;
+ // The whole source comes back into view, shaded outside the box it already
+ // keeps, so what an earlier crop cut off can be taken back in this pass.
+ cropDraft = item.crop
+ ? { ...item.crop }
+ : { x: 0, y: 0, w: item.sourceNatural[0], h: item.sourceNatural[1] };
+ if (proof.panels.includes(item)) selectPanel(item.id);
+ else selectPaste(item.id);
+ requestAnimationFrame(() => { if (stage) { rebuild(); refreshCanvasUi(); } });
+ }
+
+ /**
+ * Leave crop mode, keeping what the marks frame. They move freely until then,
+ * in both directions, so a corner pulled too far comes back in the same pass
+ * and the whole session lands as one box.
+ */
+ function endSurfaceCrop() {
+ const item = surfaceById(cropSurfaceId);
+ const selection = cropDraft;
+ discardSurfaceCrop();
+ if (item && selection) applySurfaceCrop(item, selection);
+ }
+
+ /** Leave crop mode and drop the draft: the image keeps the pixels it had. */
+ function discardSurfaceCrop() {
+ const hadMarks = !!cropSurfaceId;
+ cropSurfaceId = null;
+ cropDraft = null;
+ cropHandles?.destroyChildren();
+ cropHandles?.getLayer()?.batchDraw();
+ if (hadMarks) requestAnimationFrame(() => { if (stage) { rebuild(); refreshCanvasUi(); } });
+ }
+
+ /** Commit the box the marks frame, in source pixels. */
+ function applySurfaceCrop(item, selection) {
+ const kept = normalizeSourceCrop(selection, item.sourceNatural);
+ const before = item.crop;
+ if (JSON.stringify(kept) === JSON.stringify(before ?? null)) return;
+ // Annotations are measured from the crop's own corner, so they travel by
+ // whatever that corner moved. Their own angles never change: the turn is on
+ // the group they are drawn in.
+ const dx = (before?.x ?? 0) - (kept?.x ?? 0);
+ const dy = (before?.y ?? 0) - (kept?.y ?? 0);
+ withSurfaceCentrePreserved(item, () => {
+ proof.shapes = mapSurfaceShapes(proof.shapes, item.id, (s) => shiftProofShape(s, dx, dy));
+ item.crop = kept;
+ refreshSurface(item);
+ });
+ dirty = true;
+ }
+
+ /** Expand the source back to full size and restore annotation coordinates. */
+ function resetSurfaceCrop(item) {
+ if (!item?.crop) return;
+ const { x: dx, y: dy } = item.crop;
+ withSurfaceCentrePreserved(item, () => {
+ proof.shapes = mapSurfaceShapes(proof.shapes, item.id, (s) => shiftProofShape(s, dx, dy));
+ item.crop = null;
+ refreshSurface(item);
+ });
+ if (cropSurfaceId === item.id) {
+ cropDraft = { x: 0, y: 0, w: item.sourceNatural[0], h: item.sourceNatural[1] };
+ }
+ dirty = true;
+ }
+
/**
* The decorative border of a panel or a pasted image. `patch` of null removes
* it, `{}` adds it at the default colour and thickness, and a width of 0
@@ -1316,6 +1540,7 @@
x: (containerEl.clientWidth - width * k) / 2,
y: (containerEl.clientHeight - height * k) / 2,
});
+ if (cropSurfaceId) drawCropHandles();
stage.batchDraw();
}
@@ -1335,6 +1560,7 @@
drawGuide(width, height);
}
drawPanelMoveControls(boxesOf()); // keep the arrow bar screen-sized
+ if (cropSurfaceId) drawCropHandles();
stage.batchDraw();
}
@@ -1420,6 +1646,13 @@
// Select it cleared the selection and opened a marquee.
if ((e.evt.button ?? 0) > 0) return;
if (tool === 'select') {
+ if (cropSurfaceId) {
+ const group = docLayer.findOne(`#pg-${cropSurfaceId}`);
+ const insideSurface = e.target === group || group?.isAncestorOf(e.target);
+ const insideCrop = e.target === cropHandles || cropHandles?.isAncestorOf(e.target);
+ const insideTransformer = e.target === transformer || transformer?.isAncestorOf(e.target);
+ if (!insideSurface && !insideCrop && !insideTransformer) endSurfaceCrop();
+ }
dragMoved = false;
marqueeEnded = false;
const add = e.evt.shiftKey;
@@ -1757,9 +1990,11 @@
// Fold a drag or a corner-resize of a pasted image back into its stored
// position and scale, then hold it inside the document.
function commitPasteNode(paste, node, { resized = false } = {}) {
+ const centre = node.position();
if (resized) paste.scale = clampPasteScale(node.scaleX());
- paste.x = node.x();
- paste.y = node.y();
+ applySurfaceRotation(paste, node.rotation());
+ paste.x = centre.x - paste.natural[0] * paste.scale / 2;
+ paste.y = centre.y - paste.natural[1] * paste.scale / 2;
const { width, height } = measureDoc();
Object.assign(paste, clampPaste(paste, width, height));
node.scale({ x: paste.scale, y: paste.scale });
@@ -1784,12 +2019,68 @@
// ---- rebuild canvas from state ------------------------------------------------------
+ /**
+ * What a surface draws. Ordinarily its crop, straight out of the source with
+ * no intermediate canvas. Under the crop marks it is the whole source instead,
+ * shifted so the kept box does not move and shaded outside it — the pixels an
+ * earlier crop cut off are there to be taken back.
+ */
+ function surfaceImageNode(item, image) {
+ if (cropSurfaceId !== item.id) {
+ const group = new Konva.Group({
+ clip: { x: 0, y: 0, width: image[0], height: image[1] },
+ listening: false,
+ });
+ group.add(new Konva.Image({
+ image: item.img, width: image[0], height: image[1], listening: false,
+ ...(item.crop
+ ? { crop: { x: item.crop.x, y: item.crop.y, width: item.crop.w, height: item.crop.h } }
+ : {}),
+ }));
+ return group;
+ }
+ const [sw, sh] = item.sourceNatural;
+ const originX = -(item.crop?.x ?? 0);
+ const originY = -(item.crop?.y ?? 0);
+ const ghost = new Konva.Group({ name: 'crop-ghost', listening: false });
+ ghost.add(new Konva.Image({
+ image: item.img, x: originX, y: originY, width: sw, height: sh, listening: false,
+ }));
+ for (let index = 0; index < 4; index++) {
+ ghost.add(new Konva.Rect({ name: 'crop-shade', fill: 'rgba(0, 0, 0, 0.55)', listening: false }));
+ }
+ shadeCropGhost(ghost, item);
+ return ghost;
+ }
+
+ /** Lay the four shaded bands over everything the crop box leaves out. */
+ function shadeCropGhost(ghost, item) {
+ if (!ghost || !cropDraft) return;
+ const [sw, sh] = item.sourceNatural;
+ const left = -(item.crop?.x ?? 0);
+ const top = -(item.crop?.y ?? 0);
+ const boxLeft = left + cropDraft.x;
+ const boxTop = top + cropDraft.y;
+ const boxRight = boxLeft + cropDraft.w;
+ const boxBottom = boxTop + cropDraft.h;
+ const bands = ghost.find('.crop-shade');
+ bands[0]?.setAttrs({ x: left, y: top, width: sw, height: Math.max(0, boxTop - top) });
+ bands[1]?.setAttrs({ x: left, y: boxBottom, width: sw, height: Math.max(0, top + sh - boxBottom) });
+ bands[2]?.setAttrs({
+ x: left, y: boxTop, width: Math.max(0, boxLeft - left), height: cropDraft.h,
+ });
+ bands[3]?.setAttrs({
+ x: boxRight, y: boxTop, width: Math.max(0, left + sw - boxRight), height: cropDraft.h,
+ });
+ }
+
function rebuild() {
docLayer.destroyChildren();
// A template can be selected before any panels are chosen. Keep its style
// in state, but do not render a background, footer, logo, or handle yet.
if (!hasProofCanvasContent(proof)) {
transformer.nodes([]);
+ cropHandles.destroyChildren();
endHandles.destroyChildren();
panelCtrls.destroyChildren();
guideGroup.destroyChildren();
@@ -1817,9 +2108,17 @@
const box = boxes[i];
// Outer group is NOT clipped so an element can be dragged across panels;
// only the image itself is clipped to the panel box (inner group).
+ const image = imageSizeOf(panel);
+ // The group's own space is the image's pixels and it carries the turn, so
+ // the frame, the marks and the annotations all sit on the image's edges.
+ // The box around it is the upright room the page reserved for it.
const group = new Konva.Group({
id: `pg-${panel.id}`,
- x: box.x, y: box.y,
+ x: box.x + box.w / 2,
+ y: box.y + box.h / 2,
+ offsetX: image[0] / 2,
+ offsetY: image[1] / 2,
+ rotation: panel.rotation ?? 0,
scaleX: box.scale, scaleY: box.scale,
draggable: free,
});
@@ -1828,7 +2127,7 @@
// select-clicks — and, in free mode, drags. Added first so shapes stay
// on top for hit-testing.
group.add(new Konva.Rect({
- x: 0, y: 0, width: panel.natural[0], height: panel.natural[1],
+ x: 0, y: 0, width: image[0], height: image[1],
fill: 'transparent', listening: true, name: 'panel-hit',
}));
bindPanelPointerLifecycle(group, {
@@ -1838,28 +2137,14 @@
onSelect: () => selectPanel(panel.id),
onDragEnd: free ? () => commitPanelNode(panel, group) : null,
});
- if (free) {
- group.on('transformend', () => commitPanelNode(panel, group, { resized: true }));
- } else {
- // grid: corner-drag only changes the panel's scale — the grid decides
- // where it sits, so the row re-flows around the new size
- group.on('transformend', () => {
- panel.scale = scaleFromNode(group.scaleX(), panel.natural[1]);
- dirty = true;
- requestAnimationFrame(fit);
- });
- }
- if (panel.img) {
- const imgClip = new Konva.Group({
- clip: { x: 0, y: 0, width: panel.natural[0], height: panel.natural[1] },
- listening: false,
- });
- imgClip.add(new Konva.Image({
- image: panel.img, width: panel.natural[0], height: panel.natural[1], listening: false,
- }));
- group.add(imgClip);
- }
- if (panel.frame) group.add(frameNode(panel.frame, panel.natural));
+ group.on('transformend', () => commitPanelNode(panel, group, { resized: true }));
+ group.on('dblclick dbltap', (event) => {
+ if (tool !== 'select') return;
+ event.cancelBubble = true;
+ beginSurfaceCrop(panel);
+ });
+ if (panel.img) group.add(surfaceImageNode(panel, image));
+ if (panel.frame) group.add(frameNode(panel.frame, image));
for (const s of proof.shapes.filter((x) => x.panel === panel.id)) {
group.add(makeShapeNode(s, box));
}
@@ -1922,16 +2207,21 @@
for (let i = proof.pastes.length - 1; i >= 0; i--) {
const paste = proof.pastes[i];
const box = pasteBox[i];
+ const image = imageSizeOf(paste);
const group = new Konva.Group({
id: `pg-${paste.id}`,
- x: box.x, y: box.y,
+ x: box.x + box.w / 2,
+ y: box.y + box.h / 2,
+ offsetX: image[0] / 2,
+ offsetY: image[1] / 2,
+ rotation: paste.rotation ?? 0,
scaleX: box.scale, scaleY: box.scale,
draggable: false,
});
// same invisible hit target as a panel: the image never listens, so a
// drawing tool passes through to the stage, but a click still selects.
group.add(new Konva.Rect({
- x: 0, y: 0, width: paste.natural[0], height: paste.natural[1],
+ x: 0, y: 0, width: image[0], height: image[1],
fill: 'transparent', listening: true, name: 'panel-hit',
}));
bindPanelPointerLifecycle(group, {
@@ -1940,12 +2230,13 @@
onDragEnd: () => commitPasteNode(paste, group),
});
group.on('transformend', () => commitPasteNode(paste, group, { resized: true }));
- if (paste.img) {
- group.add(new Konva.Image({
- image: paste.img, width: paste.natural[0], height: paste.natural[1], listening: false,
- }));
- }
- if (paste.frame) group.add(frameNode(paste.frame, paste.natural));
+ group.on('dblclick dbltap', (event) => {
+ if (tool !== 'select') return;
+ event.cancelBubble = true;
+ beginSurfaceCrop(paste);
+ });
+ if (paste.img) group.add(surfaceImageNode(paste, image));
+ if (paste.frame) group.add(frameNode(paste.frame, image));
for (const s of proof.shapes.filter((x) => x.panel === paste.id)) {
group.add(makeShapeNode(s, box));
}
@@ -2054,9 +2345,9 @@
}
// Selection is keyed on the shape's kind, not the Konva node's class name,
// since a framed/backgrounded text renders as a Group rather than a Text.
- // A whole panel can be selected instead (both modes): corner anchors only
- // (aspect locked, elements scale along), never rotated. In grid mode the
- // resize keeps only the scale — the grid re-flows the position.
+ // A whole panel can be selected instead (both modes): corner anchors keep
+ // its aspect, and the round handle rotates its pixels and annotations. In
+ // grid mode the grid re-flows the resulting bounds.
const selectedNodes = selectedIds
.map((id) => docLayer.findOne(`#${id}`))
.filter(Boolean);
@@ -2096,17 +2387,20 @@
// Several annotations at once get the border and nothing else: dragging any
// one of them drags the rest (Konva moves every node the transformer holds),
// while resizing and rotating a family stays out of this first pass.
+ // Crop mode owns the image: two sets of handles over one picture is a pair
+ // of frames to aim at, so the selection frame steps aside until it is over.
transformer.nodes(
- !handles
+ !handles || cropSurfaceId
? []
: selectedNodes.length
? selectedNodes
: panelNode ? [panelNode] : pasteNode ? [pasteNode] : sigNode ? [sigNode] : []
);
const selKind = selectedShape?.kind;
- transformer.keepRatio(!!sigNode || !!pasteNode || selKind === 'icon');
+ transformer.keepRatio(!!sigNode || !!panelNode || !!pasteNode || selKind === 'icon');
transformer.rotateEnabled(
- selKind === 'text' || selKind === 'rect' || selKind === 'ellipse' || selKind === 'icon'
+ !!panelNode || !!pasteNode
+ || selKind === 'text' || selKind === 'rect' || selKind === 'ellipse' || selKind === 'icon'
|| selKind === 'freehand'
);
// A symbol gets corners only: the side handles are what would let it be
@@ -2125,14 +2419,184 @@
if (handles) {
drawEndHandles(surfacesOf());
drawPanelMoveControls(boxes);
+ drawCropHandles();
} else {
endHandles.destroyChildren();
panelCtrls.destroyChildren();
+ cropHandles.destroyChildren();
}
+ drawRotateKnob();
drawGuide(width, height); // the tweet crop is a view, not a handle: it stays
uiLayer.batchDraw();
}
+ /**
+ * The stem Collage hangs its turn knob off, drawn from the middle of the top
+ * edge out to the anchor. Decoration only: the anchor is what the pointer
+ * grabs, and it is styled into the same dark disc by `anchorStyleFunc`.
+ */
+ function drawRotateKnob() {
+ rotateKnob.destroyChildren();
+ const anchor = transformer.nodes().length && transformer.rotateEnabled()
+ ? transformer.findOne('.rotater')
+ : null;
+ if (!anchor) return;
+ const screenScale = stage.scaleX();
+ const toLocal = rotateKnob.getAbsoluteTransform().copy().invert();
+ const knob = toLocal.point(anchor.getAbsolutePosition());
+ // The stem runs from the middle of the frame's top edge, which is where the
+ // anchor hangs off however the selection is turned.
+ const edge = toLocal.point(
+ transformer.getAbsoluteTransform().point({ x: transformer.width() / 2, y: 0 }),
+ );
+ rotateKnob.add(new Konva.Line({
+ points: [edge.x, edge.y, knob.x, knob.y],
+ stroke: ACCENT, strokeWidth: 1.5 / screenScale, listening: false,
+ }));
+ }
+
+ /**
+ * The selected surface's group, and the two ways between source pixels and the
+ * screen. The group carries the turn, so a box drawn through this stays on the
+ * image's own edges however far it is turned.
+ */
+ function cropFrameOf() {
+ const item = surfaceById(cropSurfaceId);
+ const group = item && docLayer.findOne(`#pg-${item.id}`);
+ if (!group) return null;
+ const originX = item.crop?.x ?? 0;
+ const originY = item.crop?.y ?? 0;
+ return {
+ item,
+ group,
+ angle: group.getAbsoluteRotation(),
+ scale: group.getAbsoluteScale().x,
+ toScreen: (x, y) => group.getAbsoluteTransform().point({ x: x - originX, y: y - originY }),
+ toSource: (point) => {
+ const local = group.getAbsoluteTransform().copy().invert().point(point);
+ return { x: local.x + originX, y: local.y + originY };
+ },
+ };
+ }
+
+ /**
+ * PowerPoint-style crop marks: eight black edge and corner marks turned onto
+ * the image's own edges. They are drawn on the ui layer so they keep their
+ * screen size at any zoom; the shading behind them rides with the image.
+ */
+ function drawCropHandles() {
+ cropHandles.destroyChildren();
+ if (!cropSurfaceId || !cropDraft || tool !== 'select') return;
+ const frame = cropFrameOf();
+ if (!frame) return;
+
+ const screenScale = stage.scaleX();
+ const lineWidth = 3 / screenScale;
+ const haloWidth = 5 / screenScale;
+ const arm = 16 / screenScale;
+ const hit = 24 / screenScale;
+
+ cropHandles.add(new Konva.Line({
+ name: 'crop-border', closed: true,
+ stroke: '#111111', strokeWidth: 1 / screenScale, listening: false,
+ }));
+
+ const points = {
+ nw: [0, arm, 0, 0, arm, 0],
+ n: [-arm / 2, 0, arm / 2, 0],
+ ne: [-arm, 0, 0, 0, 0, arm],
+ e: [0, -arm / 2, 0, arm / 2],
+ se: [0, -arm, 0, 0, -arm, 0],
+ s: [-arm / 2, 0, arm / 2, 0],
+ sw: [arm, 0, 0, 0, 0, -arm],
+ w: [0, -arm / 2, 0, arm / 2],
+ };
+
+ for (const [key, mark] of Object.entries(points)) {
+ const handle = new Konva.Group({
+ name: 'crop-anchor',
+ draggable: true,
+ rotation: frame.angle, // the mark sits square on the turned image
+ cropKey: key,
+ });
+ handle.add(new Konva.Rect({
+ x: -hit / 2, y: -hit / 2, width: hit, height: hit,
+ fill: 'transparent', name: 'crop-hit',
+ }));
+ handle.add(new Konva.Line({
+ points: mark, stroke: '#ffffff', strokeWidth: haloWidth,
+ lineCap: 'square', lineJoin: 'miter', listening: false,
+ }));
+ handle.add(new Konva.Line({
+ points: mark, stroke: '#111111', strokeWidth: lineWidth,
+ lineCap: 'square', lineJoin: 'miter', listening: false,
+ }));
+ let start = null;
+ handle.on('dragstart', (event) => {
+ event.cancelBubble = true;
+ start = { ...cropDraft };
+ });
+ handle.on('dragmove', (event) => {
+ event.cancelBubble = true;
+ updateCropFromHandle(frame, key, handle.getAbsolutePosition(), start);
+ positionCropHandles(frame);
+ });
+ // The mark follows the pointer past where the box stopped, so put it back
+ // on the corner it actually framed. The crop itself waits for the exit.
+ handle.on('dragend', (event) => {
+ event.cancelBubble = true;
+ positionCropHandles(frame);
+ });
+ cropHandles.add(handle);
+ }
+ positionCropHandles(frame);
+ }
+
+ /** Move one edge or corner of the draft, in the source's own pixels. */
+ function updateCropFromHandle(frame, key, screenPoint, start) {
+ if (!start) return;
+ const [width, height] = frame.item.sourceNatural;
+ const min = Math.min(width, height, Math.max(1, 16 / frame.scale));
+ const point = frame.toSource(screenPoint);
+ const px = Math.max(0, Math.min(width, point.x));
+ const py = Math.max(0, Math.min(height, point.y));
+ let left = start.x;
+ let top = start.y;
+ let right = start.x + start.w;
+ let bottom = start.y + start.h;
+ if (key.includes('w')) left = Math.min(px, right - min);
+ if (key.includes('e')) right = Math.max(px, left + min);
+ if (key.includes('n')) top = Math.min(py, bottom - min);
+ if (key.includes('s')) bottom = Math.max(py, top + min);
+ cropDraft = { x: left, y: top, w: right - left, h: bottom - top };
+ }
+
+ function positionCropHandles(frame) {
+ if (!cropDraft) return;
+ const { x, y, w, h } = cropDraft;
+ const corners = {
+ nw: [x, y], n: [x + w / 2, y], ne: [x + w, y],
+ e: [x + w, y + h / 2], se: [x + w, y + h], s: [x + w / 2, y + h],
+ sw: [x, y + h], w: [x, y + h / 2],
+ };
+ for (const handle of cropHandles.find('.crop-anchor')) {
+ const [sx, sy] = corners[handle.getAttr('cropKey')];
+ handle.rotation(frame.angle);
+ handle.setAbsolutePosition(frame.toScreen(sx, sy));
+ }
+ const border = cropHandles.findOne('.crop-border');
+ if (border) {
+ const toLocal = cropHandles.getAbsoluteTransform().copy().invert();
+ border.points(['nw', 'ne', 'se', 'sw'].flatMap((key) => {
+ const point = toLocal.point(frame.toScreen(...corners[key]));
+ return [point.x, point.y];
+ }));
+ }
+ shadeCropGhost(frame.group.findOne('.crop-ghost'), frame.item);
+ frame.group.getLayer()?.batchDraw();
+ cropHandles.getLayer()?.batchDraw();
+ }
+
// Tweet centre-crop preview: X displays a single image with object-fit: cover
// into a box of the chosen aspect, so it crops whatever falls outside the
// largest centred rect of that aspect. We dim that outside region and outline
@@ -2725,6 +3189,13 @@
docLayer.batchDraw();
return;
}
+ // Escape unwinds here as everywhere else: the marks go and the image keeps
+ // its pixels. Clicking away or saving is what keeps the box instead.
+ if (e.key === 'Escape' && cropSurfaceId) {
+ discardSurfaceCrop();
+ refreshCanvasUi();
+ return;
+ }
// clipboard / undo / save chords
if (e.ctrlKey || e.metaKey) {
const k = e.key.toLowerCase();
@@ -2802,6 +3273,12 @@
// ---- persistence -------------------------------------------------------------------------
function exportPng() {
+ // A box still under its crop marks belongs to the document, not to the view:
+ // saving or copying from inside crop mode keeps it, like clicking away does.
+ if (cropSurfaceId) {
+ endSurfaceCrop();
+ rebuild();
+ }
const { width, height } = measureDoc();
const { pixelRatio } = proofExportOptions(width, height);
const prevScale = stage.scale();
@@ -3203,7 +3680,11 @@
const img = await loadImage(fileUrl(caseState.current.id, p.src));
if (run !== openRun) return;
imgCache.set(p.src, img);
- proof.panels.push({ ...p, id: p.id ?? newId('p'), row: p.row ?? 0, img });
+ proof.panels.push(hydratedSurface({
+ ...p,
+ id: p.id ?? newId('p'),
+ row: p.row ?? 0,
+ }, img));
} catch {
if (run !== openRun) return;
toast(`Missing panel image: ${p.src}`, 'warn');
@@ -3222,7 +3703,7 @@
);
if (run !== openRun) return;
pasteAssets.set(p.asset, { img, data: null, pending: false });
- proof.pastes.push({ ...p, id: p.id ?? newId('x'), img });
+ proof.pastes.push(hydratedSurface({ ...p, id: p.id ?? newId('x') }, img));
} catch {
if (run !== openRun) return;
toast('An overlay of this proof is missing', 'warn');
@@ -3944,6 +4425,8 @@
{openPicker}
{movePanelZ}
{scalePanel}
+ openCrop={beginSurfaceCrop}
+ resetCrop={resetSurfaceCrop}
{removePanel}
{movePasteZ}
{removePaste}
diff --git a/frontend/src/tools/ProofComposer.test.js b/frontend/src/tools/ProofComposer.test.js
index 6715132..040ba5e 100644
--- a/frontend/src/tools/ProofComposer.test.js
+++ b/frontend/src/tools/ProofComposer.test.js
@@ -526,8 +526,9 @@ describe('Proof Composer frames', () => {
// the legend is built from shape colours; frames are not shapes
expect(source).toContain('orderedFeatureColors(proof.shapes');
expect(source).not.toContain('orderedFeatureColors([...proof.shapes');
- expect(source).toContain('if (panel.frame) group.add(frameNode(panel.frame, panel.natural))');
- expect(source).toContain('if (paste.frame) group.add(frameNode(paste.frame, paste.natural))');
+ // …and it frames the image, not the upright box a turned image sits in
+ expect(source).toContain('if (panel.frame) group.add(frameNode(panel.frame, image))');
+ expect(source).toContain('if (paste.frame) group.add(frameNode(paste.frame, image))');
});
it('draws the border inset so it cannot move the layout', () => {
@@ -537,6 +538,87 @@ describe('Proof Composer frames', () => {
});
});
+describe('Proof Composer panel and overlay transforms', () => {
+ it('hydrates a spec surface into its crop, its turn and its upright box', () => {
+ const body = bodyOfFn('hydratedSurface');
+ expect(body).toContain('crop: normalizeSourceCrop(surface.crop, sourceNatural)');
+ expect(body).toContain('rotation: normalizeSurfaceAngle(surface.rotation)');
+ expect(bodyOfFn('refreshSurface'))
+ .toContain('surfaceBoxSize(surface.sourceNatural, surface.crop, surface.rotation)');
+ expect(source).toContain("proof.panels.push(hydratedSurface({");
+ expect(source).toContain("proof.pastes.push(hydratedSurface({ ...p, id: p.id ?? newId('x') }, img))");
+ });
+
+ it('turns nothing but the group, so no pixel and no annotation is rewritten', () => {
+ // The image, its border, its marks and its notes are one group that turns.
+ // Baking the angle into pixels is what put the selection frame and the crop
+ // marks on a transparent box bigger than the picture.
+ const body = bodyOfFn('applySurfaceRotation');
+ expect(body).toContain('item.rotation = turned');
+ expect(body).not.toContain('mapSurfaceShapes');
+ expect(source).toContain('rotation: panel.rotation ?? 0');
+ expect(source).toContain('rotation: paste.rotation ?? 0');
+ expect(source).not.toContain('renderSurfaceImage');
+ });
+
+ it('crops in source pixels and walks annotations by the corner they moved', () => {
+ const body = bodyOfFn('applySurfaceCrop');
+ expect(body).toContain('normalizeSourceCrop(selection, item.sourceNatural)');
+ expect(body).toContain('shiftProofShape(s, dx, dy)');
+ expect(body).toContain('item.crop = kept');
+ });
+
+ it('shows the whole source under the marks, so a crop can be taken back', () => {
+ const body = bodyOfFn('surfaceImageNode');
+ expect(body).toContain("name: 'crop-ghost'");
+ expect(body).toContain('width: sw, height: sh'); // the source, not the crop
+ expect(bodyOfFn('beginSurfaceCrop')).toContain('cropDraft = item.crop');
+ // …and the marks clamp to the source, which is what lets them pull back out
+ expect(bodyOfFn('updateCropFromHandle')).toContain('frame.item.sourceNatural');
+ });
+
+ it('enters crop mode on the canvas by double-click and draws eight marks', () => {
+ expect(source).toContain('openCrop={beginSurfaceCrop}');
+ expect(source.match(/beginSurfaceCrop\((panel|paste)\)/g)).toHaveLength(2);
+ expect(source).toContain("cropHandles = new Konva.Group({ id: 'proof-crop-handles' })");
+ expect(source).toContain("group.on('dblclick dbltap'");
+ expect(source).toContain('for (const [key, mark] of Object.entries(points))');
+ expect(source).not.toContain('ProofCropDialog');
+ });
+
+ it('holds the crop box as a draft until crop mode is left', () => {
+ // Committing on each handle released would bury the pixels the next pull
+ // needs, and would write one operation per nudge into the saved spec.
+ expect(bodyOfFn('endSurfaceCrop')).toContain('applySurfaceCrop(item, selection)');
+ expect(bodyOfFn('applySurfaceCrop')).not.toContain('cropDraft =');
+ expect(bodyOfFn('discardSurfaceCrop')).not.toContain('applySurfaceCrop');
+ // saving or copying the picture keeps a box still under its marks…
+ expect(bodyOfFn('exportPng')).toContain('endSurfaceCrop();');
+ // …and Escape drops it, like every other draft in this tool
+ expect(source).toMatch(/Escape' && cropSurfaceId\) \{\s*\n\s*discardSurfaceCrop\(\);/);
+ // a surface on its way out of the proof takes its draft with it
+ expect(bodyOfFn('removePanel')).toContain('discardSurfaceCrop()');
+ expect(bodyOfFn('removePaste')).toContain('discardSurfaceCrop()');
+ });
+
+ it('dresses the turn knob the way Collage dresses its own', () => {
+ expect(source).toContain('rotateAnchorOffset: 28');
+ expect(source).toContain('!!panelNode || !!pasteNode');
+ // A disc on a stem, and nothing inside it: a glyph at anchor size is a
+ // smudge rather than a symbol.
+ const knob = bodyOfFn('drawRotateKnob');
+ expect(knob).toContain('stroke: ACCENT');
+ expect(knob).not.toContain('Konva.Path');
+ expect(source).toContain("anchor.fill('rgba(22, 22, 22, 0.92)')");
+ expect(source).toContain('anchor.stroke(ACCENT)');
+ expect(source).not.toContain("anchor.fill('#1473e6')");
+ });
+
+ it('puts the selection frame away while the crop marks are up', () => {
+ expect(source).toContain('!handles || cropSurfaceId');
+ });
+});
+
describe('POV', () => {
it('asks what the point means, since the composition cannot say', () => {
// recorded-at and shows are independent: a rooftop shot is recorded
diff --git a/frontend/src/tools/Satellite.svelte b/frontend/src/tools/Satellite.svelte
index f33847b..511c8cd 100644
--- a/frontend/src/tools/Satellite.svelte
+++ b/frontend/src/tools/Satellite.svelte
@@ -8,6 +8,7 @@
import MapSurface from './satellite/MapSurface.svelte';
import { createSentinelState } from './satellite/state/sentinel.svelte.js';
import { createWaybackState } from './satellite/state/wayback.svelte.js';
+ import { createAddedLayersState } from './satellite/state/addedLayers.svelte.js';
import { createSavedState } from './satellite/state/saved.svelte.js';
import { createImageryState, FALLBACK_PROVIDER } from './satellite/state/imagery.svelte.js';
import { createMeasureState, HINTS as MEASURE_HINT } from './satellite/state/measure.svelte.js';
@@ -29,7 +30,6 @@
import {
caseState, uiState, ensureCase, reloadCase, toast, prefs, fmtCoords, prefsReady,
} from '../lib/state.svelte.js';
- import { mapLinks } from '../lib/maplinks.js';
import { markerGeometry, markerSvg } from '../lib/mapMarkers.js';
import { startRectDrag, startRotateDrag } from '../lib/map/gestures.js';
import { panelWidth } from '../lib/panelWidth.js';
@@ -81,6 +81,9 @@
import EntityDetails from '../components/EntityDetails.svelte';
import RefViewer from './RefViewer.svelte';
import MapRail from './satellite/MapRail.svelte';
+ import AddedLayers from './satellite/AddedLayers.svelte';
+ import AddedLayersOverlay from './satellite/AddedLayersOverlay.svelte';
+ import AddLayerDialog from './satellite/AddLayerDialog.svelte';
import MapLayers from './satellite/MapLayers.svelte';
import MapContextMenu from './satellite/MapContextMenu.svelte';
import MapStatusBar from './satellite/MapStatusBar.svelte';
@@ -145,6 +148,15 @@
// The case's saved work — both indexes, the panel's filter and the Locate
// pass — is its own store (state/saved.svelte.js).
const savedWork = createSavedState({ api, notify: toast, assignFolder, reloadCase });
+ // The layers the analyst added themselves: a file they opened, a map they
+ // follow. Its own store, because it owns the one network rule this feature
+ // has — a feed is read on case open, on Refresh, and never otherwise.
+ const addedLayers = createAddedLayersState({
+ api,
+ notify: toast,
+ ensureCase,
+ reloadCase,
+ });
let savedSearchOpen = $state(false);
// Map layer: on from the start, on the Media position, so a case opens on its
// footage already placed. Session-only: the tool stays mounted across tabs, so a
@@ -384,11 +396,29 @@
units: () => prefs.units,
});
- // External-maps quick links, in the SAVED panel (item 6).
- let linksOpen = $state(false);
- // …and the layers list above them, open by default: it is what the panel
- // says about the map itself.
+ /**
+ * Which half of the panel is showing.
+ *
+ * The panel used to stack three unrelated things in one scroll — what is drawn
+ * over the imagery, a list of external maps, and the case's own work — under a
+ * header that named only the last of them and counted only its rows. Two tabs
+ * because there are two questions: *what am I looking at* and *what have I
+ * got*. The external maps went entirely: the right-click menu already offers
+ * them, and it offers them on the point that was clicked rather than on the
+ * map's centre.
+ *
+ * Opens on Layers, because that is what the panel is *for* on the surface it
+ * is docked to: the map is read first and browsed second, and the case's own
+ * work is also reachable from the sidebar and the Board while what is drawn
+ * over the imagery is reachable from nowhere else.
+ */
+ let panelTab = $state('layers');
+ const PANEL_TABS = { layers: 'Layers', saved: 'Saved' };
+ // The layers list, open by default: it is what the tab says about the map.
let layersOpen = $state(true);
+ // The added layer a Remove is asking about. Its snapshot goes with it, and for
+ // a subscription that is the only copy of what was last served.
+ let removingLayer = $state(null);
// --- Grid Search (spec §5): overlay a metric grid on an area of interest and
// sweep it cell by cell, marking each cleared or flagged. The grids a case
@@ -598,13 +628,14 @@
if (mapReady && shown.provider?.id === WAYBACK_ID) wb.loadReleases();
});
- // While its picker is open, a pan that settles in another tile reads that
- // tile's history. Debounced, and answered from memory for a tile already read.
+ // Once the picker has been opened, the history follows the map: a view that
+ // settles over another tile reads that tile's history, picker open or not.
+ // Debounced, and answered from memory for a tile already read.
$effect(() => {
- if (!wb.menuOpen || shown.provider?.id !== WAYBACK_ID) return;
- if (!wb.stale) return;
+ if (!wb.watching || shown.provider?.id !== WAYBACK_ID) return;
+ wb.here; // the tile under the map: a new one is a new history
clearTimeout(wbChangesTimer);
- wbChangesTimer = setTimeout(() => wb.loadChanges(), 900);
+ wbChangesTimer = setTimeout(() => wb.follow(), 900);
return () => clearTimeout(wbChangesTimer);
});
let wbChangesTimer;
@@ -1160,6 +1191,18 @@
: []),
]);
+ /**
+ * The number beside the active tab's name, which is that tab's own.
+ *
+ * Everything switched on for Layers — the curated stack and the analyst's own
+ * together, since the tab is one question — and the rows on screen for Saved.
+ */
+ const panelCount = $derived(
+ panelTab === 'layers'
+ ? layerRows.filter((row) => row.on && !row.disabled).length + addedLayers.drawn.length
+ : savedWork.shownRows.length
+ );
+
/** A rail seat was pressed: a mode is armed (and every other closed), an
* action just runs. */
function pickTool(id) {
@@ -1172,9 +1215,6 @@
if (measure.setMode(mode)) capture.disarm();
}
- // --- external map links (item 6) ---
- const externalLinks = $derived(mapLinks(displayCoords.lat, displayCoords.lon, center.zoom));
-
// fly the map to a capture's recorded point (item 7)
/** Open one saved item: fly the map to it, or — for a screenshot of a site we
* cannot embed, filed without coordinates — reopen the page it came from. */
@@ -1182,6 +1222,8 @@
async function openMedia(items, index = 0) {
if (!items?.length) return;
mediaView = { items, index };
+ // a file plays in the case's own half of the panel, whichever half was up
+ panelTab = 'saved';
if (capturesCollapsed) {
capturesCollapsed = false;
await tick();
@@ -1266,7 +1308,14 @@
mediaView = null;
footprint.cancel();
}
- return savedWork.load(id);
+ const stopSaved = savedWork.load(id);
+ // Reads what is on disk. The only thing that then reaches out is a
+ // subscription that is enabled and asked to be re-read on open.
+ const stopLayers = addedLayers.load(id);
+ return () => {
+ stopSaved?.();
+ stopLayers?.();
+ };
});
// The media index, read the first time that position is opened.
@@ -1297,6 +1346,7 @@
if (!row) return;
uiState.focusCapture = null;
capturesCollapsed = false;
+ panelTab = 'saved';
savedWork.kind = 'captures';
savedWork.query = '';
revealSavedId = row.id;
@@ -2051,6 +2101,18 @@
<!-- Both handoff layers can be on at once. Neither carries a card of its
own any more: what they are and what to do with them is a row in the
Layers list, with every other layer. -->
+ <!-- Somebody else's map over this one. GL sources rather than the DOM
+ markers the case's own pins use: a foreign layer can hold tens of
+ thousands of features, which is an order of magnitude past what a
+ `div` each can carry. -->
+ <AddedLayersOverlay
+ engine={mapReady ? engine : null}
+ caseId={caseState.current?.id ?? ''}
+ layers={addedLayers.drawn}
+ drawing={addedLayers.drawing}
+ picked={addedLayers.picked}
+ />
+
{#if sheetPoints && sheetShown}
<SheetPointsOverlay engine={mapReady ? engine : null} points={sheetPoints.points} />
{/if}
@@ -2320,23 +2382,75 @@
onkeydown={onSavedResizeKey}
></button>
{/if}
- <button
- type="button"
- class="cap-head"
- onclick={toggleCaptures}
- title={capturesCollapsed ? 'Show saved work' : 'Hide saved work'}
- >
- <Icon name={capturesCollapsed ? 'chevronLeft' : 'chevronRight'} size={15} />
- <span class="label" style="margin:0">Saved</span>
- <!-- what the panel is listing, which is what its position says: the
- count on a header that reads Media must not be the places index -->
- <span class="count">{savedWork.shownRows.length}</span>
- </button>
{#if capturesCollapsed}
- <!-- collapsed: header acts as the toggle back to the list -->
+ <!-- collapsed: the header is the way back, and names what it will open on -->
+ <button
+ type="button"
+ class="cap-head"
+ onclick={toggleCaptures}
+ title="Show the panel"
+ >
+ <Icon name="chevronLeft" size={15} />
+ <span class="label" style="margin:0">{PANEL_TABS[panelTab]}</span>
+ <span class="count">{panelCount}</span>
+ </button>
{:else}
+ <!-- Two tabs, because the panel answers two questions: what is drawn
+ over the imagery, and what this case holds. They used to be one
+ scroll under a header that named only the second of them. -->
+ <div class="cap-head">
+ <button
+ type="button"
+ class="cap-collapse"
+ onclick={toggleCaptures}
+ title="Hide the panel"
+ aria-label="Hide the panel"
+ >
+ <Icon name="chevronRight" size={15} />
+ </button>
+ <!-- The two halves share the width evenly, and carry no count: each
+ section under them states its own, and a header repeating
+ "LAYERS 2" thirty pixels above "LAYERS 2" says nothing twice. -->
+ <div class="tabs" role="tablist" aria-label="Map panel">
+ {#each Object.entries(PANEL_TABS) as [id, label] (id)}
+ <button
+ type="button"
+ class="tab"
+ class:on={panelTab === id}
+ role="tab"
+ aria-selected={panelTab === id}
+ onclick={() => (panelTab = id)}
+ >{label}</button>
+ {/each}
+ </div>
+ </div>
+
<div class="panel-scroll">
- {#if mediaView}
+ {#if panelTab === 'layers'}
+ <!-- What is drawn over the imagery. One list: the labels and the saved
+ pins used to be buttons in the toolbox, and the handoffs floating
+ cards over the map. -->
+ <MapLayers rows={layerRows} bind:open={layersOpen} />
+
+ <!-- …and under it, what the analyst put there themselves. Two
+ sections rather than one list: the line is who chose the layer,
+ and an added one carries a source, a freshness and a Remove that
+ a curated one has no use for. -->
+ <AddedLayers
+ rows={addedLayers.rows}
+ busy={addedLayers.busy}
+ bind:open={addedLayers.open}
+ search={addedLayers.search}
+ ontoggle={(row) => addedLayers.toggle(caseState.current?.id, row)}
+ oncategory={(row, name) =>
+ addedLayers.toggleCategory(caseState.current?.id, row, name)}
+ onrefresh={(row) => addedLayers.refresh(caseState.current?.id, row)}
+ onremove={(row) => (removingLayer = row)}
+ onreveal={(row) => addedLayers.reveal(caseState.current?.id, row)}
+ onpick={(row, hit) => addedLayers.pick(caseState.current?.id, row, hit)}
+ onadd={() => (addedLayers.adding = true)}
+ />
+ {:else if mediaView}
<!-- A located file, played in place of the list rather than over the
map it is being compared with. Closing it brings the list back as
it was left. -->
@@ -2351,53 +2465,6 @@
onproof={openProofByName}
/>
{:else}
- <!-- What is drawn over the imagery. One list, above the case's own
- work: the labels and the saved pins used to be buttons in the
- toolbox, and the handoffs floating cards over the map. -->
- <MapLayers rows={layerRows} bind:open={layersOpen} />
-
- <!-- External maps: quick jumps to maps we can't embed in-tool, at the
- current target coordinates (item 6) -->
- <button type="button" class="sub-head" onclick={() => (linksOpen = !linksOpen)}>
- <Icon name={linksOpen ? 'chevronDown' : 'chevronRight'} size={12} />
- <Icon name="external" size={13} />
- <span>Open in…</span>
- <span class="count">{externalLinks.length}</span>
- </button>
- {#if linksOpen}
- <div class="links-grid">
- {#each externalLinks as l (l.id)}
- <a
- class="ext-link"
- class:disabled={fullscreen}
- href={fullscreen ? undefined : l.url}
- target="_blank"
- rel="noreferrer"
- aria-disabled={fullscreen}
- title={leavesFullscreen ?? l.url}
- >
- <Icon name="globe" size={13} />
- <span>{l.label}</span>
- <Icon name="external" size={12} />
- </a>
- {/each}
- </div>
- <div class="links-note mono">{readout}</div>
- <!-- the way back: the capture extension files what you find over
- there straight into the case, coordinates parsed from the URL -->
- <button type="button" class="links-advert" onclick={() => {
- uiState.settingsTab = 'extension';
- uiState.tool = 'settings';
- }}>
- <Icon name="crop" size={12} />
- <span>
- {extensionVersion()
- ? 'Capture these sites into the case with the browser extension'
- : 'Get the capture extension to file these sites into the case'}
- </span>
- </button>
- {/if}
-
<SavedTree
rows={savedWork.shownRows}
folders={caseState.current?.folders ?? []}
@@ -2427,6 +2494,34 @@
</div>
</div>
+{#if addedLayers.adding}
+ <AddLayerDialog
+ busy={addedLayers.saving}
+ onclose={() => (addedLayers.adding = false)}
+ onfile={(file, icons) => addedLayers.addFile(file, icons)}
+ onurl={(url, icons) => addedLayers.subscribe(url, icons)}
+ />
+{/if}
+
+<!-- Removing a layer takes the snapshot with it, which for a subscription is
+ the only copy of what was last served. -->
+{#if removingLayer}
+ <ConfirmDialog
+ title="Remove this layer?"
+ message={`“${removingLayer.title}” will be taken off the map and out of the case.`}
+ detail="Moves the layer and the copy it was drawn from to the case trash."
+ restorable={RESTORABLE}
+ confirmLabel="Remove"
+ tone="default"
+ busy={addedLayers.busy === removingLayer.name}
+ onconfirm={async () => {
+ await addedLayers.remove(caseState.current?.id, removingLayer);
+ removingLayer = null;
+ }}
+ oncancel={() => (removingLayer = null)}
+ />
+{/if}
+
<!-- delete confirm: a capture drops its image file, a place its entity -->
{#if deleteTarget}
<ConfirmDialog
@@ -2809,69 +2904,62 @@
display: flex;
flex-direction: column;
}
- /* `.sub-head` is in app.css: the Layers list writes its own heading, and the
- two have to read as one panel. */
- .links-grid {
- display: grid;
- grid-template-columns: 1fr 1fr;
- gap: 4px;
- padding: 4px 2px 6px;
- }
- .ext-link {
+ /* `.sub-head` is in app.css: each section writes its own heading, and they
+ have to read as one panel. */
+
+ /* The two halves of the panel, in its header: one track split evenly, so the
+ pair reads as one control rather than as two buttons that happen to be
+ adjacent. Full width because there are exactly two and they are the whole
+ of what this panel can be showing. */
+ .tabs {
display: flex;
- align-items: center;
- gap: 6px;
- padding: 6px 8px;
+ flex: 1;
+ gap: 3px;
+ padding: 3px;
border: 1px solid var(--border);
- border-radius: var(--radius-1);
- background: var(--bg-2);
- color: var(--text-2);
- font-size: var(--fs-xs);
- text-decoration: none;
- overflow: hidden;
+ border-radius: var(--r-lg);
+ background: var(--bg-0);
}
- .ext-link span {
+ .tab {
flex: 1;
- overflow: hidden;
- text-overflow: ellipsis;
- white-space: nowrap;
- }
- .ext-link:hover:not(.disabled) {
- color: var(--accent);
- border-color: var(--accent);
- }
- /* fullscreen: leaving for another tab would drop the map anyway (see
- leavesFullscreen) */
- .ext-link.disabled {
- opacity: 0.45;
- cursor: not-allowed;
- }
- .ext-link :global(svg:last-child) {
+ padding: 5px 10px;
+ border: none;
+ border-radius: var(--r-md);
+ background: none;
color: var(--text-3);
- flex-shrink: 0;
+ font: inherit;
+ font-size: var(--fs-sm);
+ font-weight: 500;
+ line-height: 1.2;
+ cursor: pointer;
+ transition: background 0.12s var(--ease), color 0.12s var(--ease);
}
- .links-note {
- padding: 0 4px 6px;
- font-size: var(--fs-xs);
- color: var(--text-3);
+ .tab:hover:not(.on) {
+ color: var(--text-1);
+ background: var(--bg-3);
}
- /* the capture-extension pointer under the external links — quiet, one line */
- .links-advert {
- display: flex;
- align-items: center;
- gap: 6px;
- width: 100%;
- padding: 4px;
- margin: 0 0 6px;
+ .tab.on {
+ background: var(--bg-3);
+ color: var(--text-1);
+ box-shadow: var(--shadow-1);
+ }
+ /* The collapse is a window control, not a third tab: sized down and kept in
+ the gutter the section chevrons below it already occupy. */
+ .cap-collapse {
+ display: grid;
+ place-items: center;
+ flex: none;
+ width: 22px;
+ height: 22px;
border: none;
+ border-radius: var(--r-md);
background: none;
- font-size: var(--fs-xs);
color: var(--text-3);
- text-align: left;
cursor: pointer;
}
- .links-advert:hover {
- color: var(--accent);
+ .cap-collapse:hover {
+ color: var(--text-1);
+ background: var(--bg-3);
}
diff --git a/frontend/src/tools/Satellite.test.js b/frontend/src/tools/Satellite.test.js
index 34d5a04..03300ad 100644
--- a/frontend/src/tools/Satellite.test.js
+++ b/frontend/src/tools/Satellite.test.js
@@ -52,7 +52,13 @@ describe('Satellite saved work', () => {
});
it('loads and drops every index with the case, through the store', () => {
- expect(source).toContain('return savedWork.load(id);');
+ // Two stores read the case now — its saved work and the layers the analyst
+ // added — and both hand back a teardown, so a response arriving after the
+ // case changed lands nowhere.
+ expect(source).toContain('const stopSaved = savedWork.load(id);');
+ expect(source).toContain('const stopLayers = addedLayers.load(id);');
+ expect(source).toContain('stopSaved?.();');
+ expect(source).toContain('stopLayers?.();');
expect(source).toContain('savedWork.loadMode(caseState.current?.id, caseState.rev)');
});
@@ -118,8 +124,13 @@ describe('Satellite saved work', () => {
});
describe('Capture extension settings handoff', () => {
- it('opens the extension section from both Satellite entry points', () => {
- expect(source.match(/uiState\.settingsTab = 'extension'/g)).toHaveLength(2);
+ it('opens the extension section from the gate that needs it', () => {
+ // There were two: this one, and a line under the panel's list of external
+ // maps. That list is gone — the right-click menu already offers those, on
+ // the point that was clicked rather than on the map's centre — and the
+ // advert went with it rather than being refiled somewhere it reads as an ad.
+ expect(source.match(/uiState\.settingsTab = 'extension'/g)).toHaveLength(1);
+ expect(source).toContain('<ExtensionGate');
});
});
@@ -731,9 +742,10 @@ describe('Esri Wayback', () => {
expect(source).toContain('if (mapReady && shown.provider?.id === WAYBACK_ID) wb.loadReleases();');
});
- it('reads a point’s history only while its picker is open', () => {
- const effect = source.slice(source.indexOf('if (!wb.menuOpen || shown.provider?.id !== WAYBACK_ID) return;'));
- expect(effect.slice(0, 300)).toContain('wb.loadChanges()');
+ it('reads no history until the picker has been opened, and follows the map after', () => {
+ const effect = source.slice(source.indexOf('if (!wb.watching || shown.provider?.id !== WAYBACK_ID) return;'));
+ expect(effect.slice(0, 300)).toContain('wb.here;');
+ expect(effect.slice(0, 300)).toContain('wb.follow()');
});
it('puts the release on the id every tile and capture keys on', () => {
diff --git a/frontend/src/tools/compare/ExportFrame.svelte b/frontend/src/tools/compare/ExportFrame.svelte
new file mode 100644
index 0000000..0b67be4
--- /dev/null
+++ b/frontend/src/tools/compare/ExportFrame.svelte
@@ -0,0 +1,151 @@
+<script>
+ /**
+ * The rectangle an export is framed to, drawn over the compared imagery.
+ *
+ * The frame is held on the ground, so it stays on the same roofs when the
+ * camera moves. In Side by side, B shows the same box read-only. In an
+ * overlaid mode, one stage-level frame spans whichever pixels are visible.
+ */
+ import { boundedRect, frameSpan } from '../../lib/map/exportFrame.js';
+ import { formatDistance } from '../../lib/measure.js';
+
+ let { engine, frame = null, drawing = false, readonly = false, units = 'metric', bearing = 0,
+ onframe = () => {}, oncancel = () => {} } = $props();
+
+ let root = $state();
+ let revision = $state(0);
+ let draft = $state(null); // { from: [x, y], to: [x, y] } while the pointer is down
+
+ $effect(() => {
+ if (!engine) return;
+ const refresh = () => revision++;
+ const release = engine.on('view-move', refresh);
+ const observer = new ResizeObserver(refresh);
+ if (root) observer.observe(root);
+ return () => { release(); observer.disconnect(); };
+ });
+
+ const project = ([lon, lat]) => {
+ revision;
+ const at = engine?.latLngToContainerPoint({ lon, lat });
+ return [at?.x ?? 0, at?.y ?? 0];
+ };
+
+ const box = (first, second) => ({
+ x: Math.min(first[0], second[0]),
+ y: Math.min(first[1], second[1]),
+ w: Math.abs(second[0] - first[0]),
+ h: Math.abs(second[1] - first[1]),
+ });
+
+ const rect = $derived.by(() => {
+ if (draft) return box(draft.from, draft.to);
+ if (!frame?.points || !engine) return null;
+ return box(project(frame.points[0]), project(frame.points[1]));
+ });
+ const span = $derived(frame?.points && !draft ? frameSpan(frame.points, bearing) : null);
+
+ function at(event) {
+ const bounds = root?.getBoundingClientRect();
+ if (!bounds?.width) return null;
+ return [
+ Math.max(0, Math.min(bounds.width, event.clientX - bounds.left)),
+ Math.max(0, Math.min(bounds.height, event.clientY - bounds.top)),
+ ];
+ }
+
+ function ground([x, y]) {
+ const point = engine?.containerPointToLatLng({ x, y });
+ return point ? [point.lon, point.lat] : null;
+ }
+
+ function begin(event) {
+ if (!drawing || event.button > 0) return;
+ const start = at(event);
+ if (!start) return;
+ event.preventDefault();
+ event.stopPropagation();
+ draft = { from: start, to: start };
+ root.setPointerCapture?.(event.pointerId);
+ }
+
+ function move(event) {
+ if (!draft) return;
+ const now = at(event);
+ if (now) draft = { ...draft, to: now };
+ }
+
+ function finish(event) {
+ if (!draft) return;
+ move(event);
+ root.releasePointerCapture?.(event.pointerId);
+ const drawn = box(draft.from, draft.to);
+ draft = null;
+ // A click is not a frame. A small but deliberate drawing grows around its
+ // own centre here, so the rectangle kept on screen is exactly what the
+ // export later cuts to.
+ if (drawn.w < 24 || drawn.h < 24) return oncancel();
+ const bounds = root.getBoundingClientRect();
+ const cut = boundedRect(drawn, { width: bounds.width, height: bounds.height });
+ const corners = [ground([cut.x, cut.y]), ground([cut.x + cut.w, cut.y + cut.h])];
+ if (corners.every(Boolean)) onframe({ points: corners });
+ else oncancel();
+ }
+
+ function keydown(event) {
+ if (event.key !== 'Escape' || !drawing) return;
+ event.stopPropagation();
+ draft = null;
+ oncancel();
+ }
+</script>
+
+<svelte:window onkeydown={keydown} />
+
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div
+ class="export-frame"
+ class:drawing
+ class:readonly
+ bind:this={root}
+ onpointerdown={begin}
+ onpointermove={move}
+ onpointerup={finish}
+ onpointercancel={finish}
+>
+ {#if rect}
+ <svg class="frame-shape" aria-hidden="true">
+ {#if drawing}
+ <path class="dim" fill-rule="evenodd"
+ d={`M0,0 H99999 V99999 H0 Z M${rect.x},${rect.y} h${rect.w} v${rect.h} h${-rect.w} Z`} />
+ {/if}
+ <rect class="edge" x={rect.x + 0.5} y={rect.y + 0.5} width={Math.max(0, rect.w - 1)} height={Math.max(0, rect.h - 1)} />
+ </svg>
+ {#if !readonly}
+ <span class="frame-tag" style:left={`${rect.x}px`} style:top={`${rect.y}px`}>
+ {#if span}Export frame · {formatDistance(span.width, units)} × {formatDistance(span.height, units)}
+ {:else}{Math.round(rect.w)} × {Math.round(rect.h)}{/if}
+ </span>
+ {/if}
+ {:else if drawing}
+ <div class="frame-hint">Drag over the area to export. Escape to cancel.</div>
+ {/if}
+</div>
+
+<style>
+ .export-frame { position: absolute; inset: 0; z-index: 530; pointer-events: none; overflow: hidden; }
+ .export-frame.drawing { z-index: 600; pointer-events: auto; cursor: crosshair; touch-action: none; }
+ .frame-shape { position: absolute; inset: 0; width: 100%; height: 100%; }
+ .dim { fill: rgba(9, 11, 14, .55); }
+ .edge { fill: none; stroke: #e8a33d; stroke-width: 2; stroke-dasharray: 7 5; }
+ .readonly .edge { stroke: rgba(232, 163, 61, .6); stroke-dasharray: 4 6; }
+ .frame-tag {
+ position: absolute; transform: translateY(-100%); margin-top: -4px;
+ padding: 3px 7px; border-radius: 5px; background: rgba(9, 11, 14, .85);
+ color: #f3f4f6; font-size: 11px; font-weight: 600; white-space: nowrap;
+ }
+ .frame-hint {
+ position: absolute; inset: 0; display: flex; align-items: center; justify-content: center;
+ background: rgba(9, 11, 14, .45); color: #f3f4f6; font-size: 13px; font-weight: 600;
+ }
+</style>
diff --git a/frontend/src/tools/compare/ExportFrame.test.js b/frontend/src/tools/compare/ExportFrame.test.js
new file mode 100644
index 0000000..c748168
--- /dev/null
+++ b/frontend/src/tools/compare/ExportFrame.test.js
@@ -0,0 +1,104 @@
+// @vitest-environment happy-dom
+/**
+ * The export frame drawn over imagery A.
+ *
+ * What matters here is that the rectangle is kept on the ground rather than on
+ * the screen: an export framed before a pan must cut the same roofs after it.
+ */
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+import { flushSync, mount, unmount } from 'svelte';
+
+const { default: ExportFrame } = await import('./ExportFrame.svelte');
+
+globalThis.ResizeObserver = class { observe() {} disconnect() {} };
+
+let live, target, handlers, origin;
+
+/** Ten pixels to the degree, shifted by wherever the camera has been panned. */
+function fakeEngine() {
+ handlers = {};
+ origin = { x: 0, y: 0 };
+ return {
+ on: (name, handler) => { handlers[name] = handler; return () => delete handlers[name]; },
+ latLngToContainerPoint: ({ lon, lat }) => ({ x: lon * 10 - origin.x, y: lat * 10 - origin.y }),
+ containerPointToLatLng: ({ x, y }) => ({ lon: (x + origin.x) / 10, lat: (y + origin.y) / 10 }),
+ };
+}
+
+function press(node, type, x, y) {
+ node.dispatchEvent(new MouseEvent(type, { bubbles: true, clientX: x, clientY: y }));
+ flushSync();
+}
+
+function stage(props) {
+ live = mount(ExportFrame, { target, props: { engine: fakeEngine(), ...props } });
+ flushSync();
+ const root = target.querySelector('.export-frame');
+ root.getBoundingClientRect = () => ({ left: 0, top: 0, width: 400, height: 300 });
+ return root;
+}
+
+const edge = () => target.querySelector('.edge');
+
+beforeEach(() => { target = document.createElement('div'); document.body.append(target); });
+afterEach(() => { if (live) unmount(live); target.remove(); });
+
+it('hands back the ground the drag covered', () => {
+ const onframe = vi.fn();
+ const root = stage({ drawing: true, onframe });
+
+ press(root, 'pointerdown', 20, 0);
+ press(root, 'pointermove', 380, 300);
+ press(root, 'pointerup', 380, 300);
+
+ expect(onframe).toHaveBeenCalledWith({ points: [[2, 0], [38, 30]] });
+});
+
+it('keeps the frame on its ground when the camera moves', () => {
+ stage({ frame: { points: [[5, 4], [25, 19]] } });
+ expect(edge().getAttribute('x')).toBe('50.5');
+
+ origin.x = 120;
+ handlers['view-move']();
+ flushSync();
+ expect(edge().getAttribute('x')).toBe('-69.5');
+ expect(edge().getAttribute('width')).toBe('199');
+});
+
+it('treats a press that barely travels as a click, not a frame', () => {
+ const onframe = vi.fn();
+ const oncancel = vi.fn();
+ const root = stage({ drawing: true, onframe, oncancel });
+
+ press(root, 'pointerdown', 50, 40);
+ press(root, 'pointerup', 56, 44);
+
+ expect(onframe).not.toHaveBeenCalled();
+ expect(oncancel).toHaveBeenCalled();
+});
+
+it('gives up the drawing on Escape', () => {
+ const oncancel = vi.fn();
+ stage({ drawing: true, oncancel });
+
+ window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }));
+ flushSync();
+ expect(oncancel).toHaveBeenCalled();
+});
+
+it('reads the frame as the ground it covers', () => {
+ stage({ frame: { points: [[5, 4], [25, 19]] } });
+ expect(target.querySelector('.frame-tag').textContent).toContain('Export frame');
+ expect(target.querySelector('.frame-tag').textContent).toMatch(/km|m/);
+});
+
+it('shows B the same box without letting it be drawn on', () => {
+ const onframe = vi.fn();
+ const root = stage({ frame: { points: [[5, 4], [25, 19]] }, readonly: true, onframe });
+ expect(root.classList.contains('readonly')).toBe(true);
+ expect(target.querySelector('.frame-tag')).toBeNull();
+
+ press(root, 'pointerdown', 50, 40);
+ press(root, 'pointerup', 250, 190);
+ expect(onframe).not.toHaveBeenCalled();
+});
diff --git a/frontend/src/tools/compare/SourceCard.svelte b/frontend/src/tools/compare/SourceCard.svelte
index 49fb1b7..66b2d00 100644
--- a/frontend/src/tools/compare/SourceCard.svelte
+++ b/frontend/src/tools/compare/SourceCard.svelte
@@ -31,7 +31,7 @@
<div class="source-card cmp-glass" class:right={align === 'right'} aria-label={`Imagery ${letter}`}>
<span class="cmp-letter {lower}">{letter}</span>
<div class="chips">
- <ImageryChip {imagery} bind:providerId s2={s2} {wayback} {shown} />
+ <ImageryChip {imagery} bind:providerId s2={s2} {wayback} {shown} dateChip />
</div>
{#if showsDate}
<span class="dated cmp-mono" title={dated.source ? `Acquired around this date (${dated.source})` : 'Acquired around this date'}>
diff --git a/frontend/src/tools/compare/SourceCard.test.js b/frontend/src/tools/compare/SourceCard.test.js
new file mode 100644
index 0000000..6631ecb
--- /dev/null
+++ b/frontend/src/tools/compare/SourceCard.test.js
@@ -0,0 +1,107 @@
+import { describe, expect, it, vi } from 'vitest';
+import { render } from 'svelte/server';
+import SourceCard from './SourceCard.svelte';
+import { paths } from '../../components/Icon.svelte';
+
+const PROVIDERS = [
+ { id: 'sentinel2', label: 'Sentinel-2 (Copernicus)' },
+ { id: 'esri-wayback', label: 'Esri Wayback' },
+ { id: 'esri-world-imagery', label: 'Esri World Imagery' },
+];
+
+const imagery = {
+ providers: PROVIDERS,
+ find: (id) => PROVIDERS.find((entry) => entry.id === id),
+ pill: () => '',
+};
+
+const sentinel = (over = {}) => ({
+ menuOpen: false,
+ layer: 'TRUE_COLOR',
+ layers: [],
+ layerHint: '',
+ layersSource: 'instance',
+ date: '',
+ latest: '',
+ maxcc: 100,
+ month: '2026-05',
+ passes: {},
+ passesBusy: false,
+ passesNote: '',
+ stale: false,
+ verifyingDate: '',
+ dateStatus: () => undefined,
+ filtered: () => false,
+ toggleMenu: vi.fn(),
+ ...over,
+});
+
+const release = (over = {}) => ({
+ menuOpen: false,
+ date: '',
+ position: -1,
+ visible: [],
+ releases: [],
+ listNote: '',
+ changesOnly: false,
+ changesBusy: false,
+ changesNote: '',
+ stale: false,
+ changes: null,
+ picture: () => null,
+ toggleMenu: vi.fn(),
+ step: vi.fn(),
+ pick: vi.fn(),
+ setChangesOnly: vi.fn(),
+ ...over,
+});
+
+function props(over = {}) {
+ return {
+ letter: 'A',
+ imagery,
+ providerId: 'sentinel2',
+ s2: sentinel(),
+ wayback: release(),
+ shown: { fallenBack: false, blocked: false, provider: imagery.find('sentinel2') },
+ ...over,
+ };
+}
+
+const layerIcons = (body) => body.split(paths.layers).length - 1;
+
+describe('SourceCard', () => {
+ it('dates Sentinel-2 on its own chip, leaving one layers icon on the card', () => {
+ const { body } = render(SourceCard, {
+ props: props({ s2: sentinel({ date: '2025-04-11' }) }),
+ });
+ expect(body).toContain('2025-04-11');
+ // The card's own Layers button is the only thing wearing that icon: a second
+ // one on the date picker said nothing about which of the two held the date.
+ expect(layerIcons(body)).toBe(1);
+ });
+
+ it('dates Wayback and Sentinel-2 the same way', () => {
+ const { body } = render(SourceCard, {
+ props: props({
+ providerId: 'esri-wayback',
+ wayback: release({ date: '2022-03-16' }),
+ shown: { fallenBack: false, blocked: false, provider: imagery.find('esri-wayback') },
+ }),
+ });
+ expect(body).toContain('2022-03-16');
+ expect(layerIcons(body)).toBe(1);
+ });
+
+ it('shows the acquisition date beside a provider that has no picker', () => {
+ const { body } = render(SourceCard, {
+ props: props({
+ providerId: 'esri-world-imagery',
+ shown: { fallenBack: false, blocked: false, provider: imagery.find('esri-world-imagery') },
+ dated: { date: '2023-08-02', source: 'Maxar' },
+ }),
+ });
+ expect(body).toContain('2023-08-02');
+ expect(body).toContain('Acquired around this date (Maxar)');
+ });
+});
diff --git a/frontend/src/tools/proof/ProofLayersPanel.svelte b/frontend/src/tools/proof/ProofLayersPanel.svelte
index 40edde2..c2bbca6 100644
--- a/frontend/src/tools/proof/ProofLayersPanel.svelte
+++ b/frontend/src/tools/proof/ProofLayersPanel.svelte
@@ -28,6 +28,8 @@
openPicker,
movePanelZ,
scalePanel,
+ openCrop,
+ resetCrop,
removePanel,
movePasteZ,
removePaste,
@@ -91,6 +93,28 @@
</div>
{/snippet}
+<!-- The crop button is the keyboard-accessible counterpart to double-clicking
+ an image. Rotation lives on the canvas as the round selection handle. -->
+{#snippet transformControl(item, label)}
+ <div class="transform-ctl">
+ <button
+ class="btn btn-ghost btn-sm"
+ class:active={!!item.crop}
+ title={`Crop ${label}`}
+ aria-label={`Crop ${label}`}
+ onclick={() => openCrop(item)}
+ ><Icon name="crop" size={13} /></button>
+ {#if item.crop}
+ <button
+ class="btn btn-ghost btn-sm"
+ title={`Reset ${label} crop`}
+ aria-label={`Reset ${label} crop`}
+ onclick={() => resetCrop(item)}
+ ><Icon name="reset" size={12} /></button>
+ {/if}
+ </div>
+{/snippet}
+
<div class="side-title-row" style="margin-top: 14px">
<button class="side-title collapsible" onclick={() => (collapsed.panels = !collapsed.panels)}>
<span>
@@ -137,6 +161,7 @@
onchange={markDirty}
/>
<div class="panel-actions">
+ {@render transformControl(panel, 'panel')}
{#if proof.layout === 'free'}
<button
class="btn btn-ghost btn-sm"
@@ -205,6 +230,7 @@
<span class="row-badge" title="Z1 is the foreground">Z{index + 1}</span>
</button>
<div class="panel-actions">
+ {@render transformControl(paste, 'overlay')}
<button
class="btn btn-ghost btn-sm"
disabled={index === 0}
@@ -458,6 +484,14 @@
.panel-actions { display: flex; flex-wrap: wrap; align-items: center; gap: 2px; row-gap: 4px; }
.remove-panel { margin-left: auto; }
.frame-ctl { display: flex; align-items: center; gap: 3px; }
+ .transform-ctl {
+ display: flex;
+ align-items: center;
+ gap: 1px;
+ padding-right: 3px;
+ border-right: 1px solid var(--border);
+ }
+ .transform-ctl .active { color: var(--accent); background: var(--accent-soft); }
.frame-width {
width: 44px;
padding: 2px 4px;
diff --git a/frontend/src/tools/proof/ProofLayersPanel.test.js b/frontend/src/tools/proof/ProofLayersPanel.test.js
index 569985f..02c36bc 100644
--- a/frontend/src/tools/proof/ProofLayersPanel.test.js
+++ b/frontend/src/tools/proof/ProofLayersPanel.test.js
@@ -42,3 +42,25 @@ describe('the rows and the canvas agree about what is picked', () => {
expect(source).not.toContain('$bindable');
});
});
+
+describe('panel and overlay transforms', () => {
+ it('offers the same crop control on both image kinds without arrow buttons', () => {
+ expect(source).toContain('{#snippet transformControl(item, label)}');
+ expect(source.match(/\{@render transformControl\(/g)).toHaveLength(2);
+ expect(source).toContain('onclick={() => openCrop(item)}');
+ expect(source).not.toContain('rotateSurface');
+ expect(source).not.toContain('rotateLeft');
+ expect(source).not.toContain('rotateRight');
+ });
+
+ it('shows a separate reset only after a crop exists', () => {
+ expect(source).toContain('{#if item.crop}');
+ expect(source).toContain('onclick={() => resetCrop(item)}');
+ expect(source).toContain('class:active={!!item.crop}');
+ });
+
+ it('thumbs the overlay from its own image, which is now the untouched source', () => {
+ expect(source).toContain('<img src={paste.img?.src} alt="" />');
+ expect(source).not.toContain('sourceImg');
+ });
+});
diff --git a/frontend/src/tools/satellite/AddLayerDialog.render.test.js b/frontend/src/tools/satellite/AddLayerDialog.render.test.js
new file mode 100644
index 0000000..4931a08
--- /dev/null
+++ b/frontend/src/tools/satellite/AddLayerDialog.render.test.js
@@ -0,0 +1,93 @@
+// @vitest-environment happy-dom
+/**
+ * The `+` dialog, and the one decision it is the right place for.
+ *
+ * Whether to draw a map in its own pictograms is asked here because here is the
+ * moment the request would be made: the icons are read once, at import, and
+ * served out of the case folder from then on. What is asserted is the default on
+ * each half — off for a file, on for an address — because that is the local-first
+ * line, and a pre-ticked box on a file import would cross it quietly.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { flushSync, mount, unmount } from 'svelte';
+import AddLayerDialog from './AddLayerDialog.svelte';
+
+let held = null;
+
+function show(props = {}) {
+ held = mount(AddLayerDialog, {
+ target: document.body,
+ props: { busy: false, ...props },
+ });
+ flushSync();
+ return document.body;
+}
+
+afterEach(() => {
+ if (held) unmount(held);
+ held = null;
+ document.body.innerHTML = '';
+});
+
+const ticks = () => [...document.body.querySelectorAll('input[type="checkbox"]')];
+const button = (label) =>
+ [...document.body.querySelectorAll('button')].find(
+ (node) => node.textContent.trim() === label
+ );
+
+describe('the add-a-layer dialog', () => {
+ it('offers the choice once per half, and nowhere else', () => {
+ show();
+
+ expect(ticks()).toHaveLength(2);
+ });
+
+ it('leaves a file alone and dresses an address', () => {
+ show();
+ const [file, url] = ticks();
+
+ expect(file.checked).toBe(false);
+ expect(url.checked).toBe(true);
+ });
+
+ it('says what ticking it will do to a file, rather than after the fact', () => {
+ show();
+ const [file] = ticks();
+
+ expect(document.body.textContent).toContain('Nothing leaves this machine.');
+ file.checked = true;
+ file.dispatchEvent(new Event('change', { bubbles: true }));
+ flushSync();
+
+ expect(document.body.textContent).toContain('fetched once, now');
+ });
+
+ it('hands the answer to the caller with the address', () => {
+ const onurl = vi.fn();
+ show({ onurl });
+ const input = document.body.querySelector('input[type="url"]');
+ input.value = 'https://www.google.com/maps/d/viewer?mid=XyZ';
+ input.dispatchEvent(new Event('input', { bubbles: true }));
+ flushSync();
+
+ button('Subscribe').click();
+
+ expect(onurl).toHaveBeenCalledWith('https://www.google.com/maps/d/viewer?mid=XyZ', true);
+ });
+
+ it('hands it over untouched when the box was cleared', () => {
+ const onurl = vi.fn();
+ show({ onurl });
+ const [, url] = ticks();
+ url.checked = false;
+ url.dispatchEvent(new Event('change', { bubbles: true }));
+ const input = document.body.querySelector('input[type="url"]');
+ input.value = 'https://example.test/roads.kml';
+ input.dispatchEvent(new Event('input', { bubbles: true }));
+ flushSync();
+
+ button('Subscribe').click();
+
+ expect(onurl).toHaveBeenCalledWith('https://example.test/roads.kml', false);
+ });
+});
diff --git a/frontend/src/tools/satellite/AddLayerDialog.svelte b/frontend/src/tools/satellite/AddLayerDialog.svelte
new file mode 100644
index 0000000..ce75213
--- /dev/null
+++ b/frontend/src/tools/satellite/AddLayerDialog.svelte
@@ -0,0 +1,136 @@
+<script>
+ /**
+ * The `+` behind the added-layers section: a file, or an address.
+ *
+ * Two halves of one feature, so one dialog. A file is read here and nothing
+ * leaves the machine; an address is fetched by the backend, which is the only
+ * thing in this feature that reaches out at all — said on the dialog, because
+ * a local-first app owes the analyst that sentence before the request, not in
+ * a settings page afterwards.
+ *
+ * Nothing here parses anything. The bytes go to the backend whole
+ * (`engine/maplayers.py`), which is what keeps somebody else's XML out of the
+ * browser.
+ */
+ import Modal from '../../components/Modal.svelte';
+ import { ACCEPTS, looksLikeUrl } from '../../lib/map/addedLayers.js';
+
+ let { busy = false, onclose, onfile, onurl } = $props();
+
+ let url = $state('');
+ let picker = $state(null);
+
+ /**
+ * Whether to draw the map in its own pictograms, decided here and not later.
+ *
+ * Here because it is the moment the request would be made: the icons are read
+ * once, at import, and served from the case folder from then on. A switch on
+ * the row afterwards would be a switch over bytes already fetched, which is
+ * the wrong thing to be asking about.
+ *
+ * Off for a file and on for an address, which is the same line the rest of the
+ * app draws: following a link the analyst pasted already reaches the network,
+ * opening a file off this machine does not.
+ */
+ let fileIcons = $state(false);
+ let urlIcons = $state(true);
+
+ const ready = $derived(looksLikeUrl(url));
+
+ function pick(event) {
+ const file = event.currentTarget.files?.[0];
+ if (file) onfile?.(file, fileIcons);
+ }
+</script>
+
+<Modal title="Add a layer" {onclose} width="460px">
+ <p class="lead">
+ A KML, KMZ, GeoJSON or GPX file, or a public map to follow. Its features are
+ drawn and filtered here; nothing in it joins the case.
+ </p>
+
+ <section>
+ <h4>From this computer</h4>
+ <button class="btn" disabled={busy} onclick={() => picker?.click()}>
+ {busy ? 'Reading…' : 'Choose a file'}
+ </button>
+ <input
+ bind:this={picker}
+ type="file"
+ accept={ACCEPTS}
+ hidden
+ onchange={pick}
+ />
+ <label class="tick">
+ <input type="checkbox" bind:checked={fileIcons} />
+ <span>Use the map's own icons</span>
+ </label>
+ <p class="note">
+ {fileIcons
+ ? "Icons inside a KMZ are read from the file. Icons at web addresses are fetched once, now."
+ : 'Nothing leaves this machine.'}
+ </p>
+ </section>
+
+ <section>
+ <h4>Follow a public map</h4>
+ <input
+ class="input"
+ type="url"
+ bind:value={url}
+ placeholder="https://www.google.com/maps/d/viewer?mid=…"
+ aria-label="Map address"
+ onkeydown={(event) => event.key === 'Enter' && ready && onurl?.(url.trim(), urlIcons)}
+ />
+ <label class="tick">
+ <input type="checkbox" bind:checked={urlIcons} />
+ <span>Use the map's own icons</span>
+ </label>
+ <button class="btn" disabled={!ready || busy} onclick={() => onurl?.(url.trim(), urlIcons)}>
+ {busy ? 'Reading…' : 'Subscribe'}
+ </button>
+ <!-- The one sentence this feature owes before it fetches: what it will ask
+ for, when, and what it will not do on its own. -->
+ <p class="note">
+ A My Maps share link, or any KML or GeoJSON address. It is read now, when
+ you press Refresh, and when this case opens — never on a timer, and never
+ while the layer is off.
+ </p>
+ </section>
+</Modal>
+
+<style>
+ .lead {
+ margin: 0 0 14px;
+ color: var(--text-2);
+ font-size: var(--fs-sm);
+ }
+ section + section {
+ margin-top: 16px;
+ padding-top: 14px;
+ border-top: 1px solid var(--border);
+ }
+ h4 {
+ margin: 0 0 8px;
+ color: var(--text-1);
+ font-size: var(--fs-sm);
+ }
+ .input {
+ width: 100%;
+ margin-bottom: 8px;
+ }
+ .note {
+ margin: 8px 0 0;
+ color: var(--text-3);
+ font-size: var(--fs-xs);
+ }
+ .tick {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+ margin: 8px 0 0;
+ color: var(--text-2);
+ font-size: var(--fs-xs);
+ cursor: pointer;
+ }
+</style>
diff --git a/frontend/src/tools/satellite/AddedLayers.render.test.js b/frontend/src/tools/satellite/AddedLayers.render.test.js
new file mode 100644
index 0000000..349b952
--- /dev/null
+++ b/frontend/src/tools/satellite/AddedLayers.render.test.js
@@ -0,0 +1,318 @@
+// @vitest-environment happy-dom
+/**
+ * The panel section for layers the analyst added.
+ *
+ * What is asserted here is what the row *says*, because that is where this
+ * feature can quietly lie: a count that hides how much was filtered out, a
+ * subscription drawing week-old marks without a word, a legend that decorates
+ * instead of filtering.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { flushSync, mount, unmount } from 'svelte';
+import AddedLayers from './AddedLayers.svelte';
+import { GROUP_SPACE } from '../../lib/map/addedLayers.js';
+
+let held = null;
+
+function show(props = {}) {
+ held = mount(AddedLayers, {
+ target: document.body,
+ props: { rows: [], busy: '', ...props },
+ });
+ flushSync();
+ return document.body;
+}
+
+afterEach(() => {
+ if (held) unmount(held);
+ held = null;
+ document.body.innerHTML = '';
+});
+
+const text = () => document.body.textContent ?? '';
+const rows = (selector) => [...document.body.querySelectorAll(selector)];
+const byText = (selector, label) =>
+ rows(selector).find((node) => node.textContent.trim().startsWith(label));
+
+const LAYER = {
+ name: 'Sightings',
+ title: 'Sightings',
+ source: { kind: 'file', name: 'sightings.kml' },
+ enabled: true,
+ hidden: [],
+ features: 3200,
+ categories: [
+ { name: 'Checkpoints', count: 2788, colour: '#ff0000', kinds: ['point'] },
+ { name: 'Damage', count: 412, colour: '', kinds: ['area'] },
+ ],
+ fetched_at: new Date().toISOString(),
+ stale: false,
+};
+
+const followed = (over = {}) => ({
+ ...LAYER,
+ name: 'Roadblocks',
+ title: 'Roadblocks',
+ source: { kind: 'url', url: 'https://example.test/r.kml', my_maps: true },
+ ...over,
+});
+
+describe('before anything is added', () => {
+ it('is an empty section with a way to fill it, not an absent one', () => {
+ show();
+
+ expect(text()).toContain('Added layers');
+ expect(text()).toContain('Nothing added yet.');
+ expect(byText('button', 'Add a layer')).toBeTruthy();
+ });
+
+ it('counts nothing rather than borrowing the curated list’s number', () => {
+ show();
+
+ expect(document.querySelector('.count').textContent).toBe('0');
+ });
+});
+
+describe('a row', () => {
+ it('renders from state, with where it came from and how fresh it is', () => {
+ show({ rows: [LAYER] });
+
+ expect(text()).toContain('Sightings');
+ expect(text()).toContain('sightings.kml');
+ expect(text()).toContain('opened');
+ });
+
+ it('states what is loaded and what is drawn, separately', () => {
+ show({ rows: [{ ...LAYER, hidden: ['Damage'] }] });
+
+ // never the drawn count passing for the loaded one
+ expect(text()).toMatch(/3.200 features · 2.788 shown/);
+ });
+
+ it('links a followed map back to the page it was published on', () => {
+ show({ rows: [followed()] });
+
+ const link = document.querySelector('.from');
+ expect(link.getAttribute('href')).toBe('https://example.test/r.kml');
+ expect(link.textContent).toContain('Google My Maps');
+ // it leaves the app, so it leaves in its own tab and carries no referrer
+ expect(link.getAttribute('target')).toBe('_blank');
+ expect(link.getAttribute('rel')).toBe('noreferrer');
+ });
+
+ it('leaves a file as plain text, having nowhere to send anybody', () => {
+ show({ rows: [LAYER] });
+
+ expect(document.querySelector('.from')).toBeNull();
+ expect(text()).toContain('sightings.kml');
+ });
+
+ it('says a stale snapshot is stale, and marks it for the eye', () => {
+ show({ rows: [followed({ stale: true, checked_at: '2020-01-01T00:00:00Z' })] });
+
+ expect(text()).toContain('stale');
+ expect(document.querySelector('.stale')).toBeTruthy();
+ });
+
+ it('offers Refresh only to a layer that has somewhere to refresh from', () => {
+ show({ rows: [LAYER] });
+ expect(byText('button', 'Refresh')).toBeFalsy();
+
+ unmount(held);
+ held = null;
+ document.body.innerHTML = '';
+
+ show({ rows: [followed()] });
+ expect(byText('button', 'Refresh')).toBeTruthy();
+ });
+
+ it('owns its layer the way a curated row does not: Remove and Reveal', () => {
+ show({ rows: [LAYER] });
+
+ expect(byText('button', 'Remove')).toBeTruthy();
+ expect(byText('button', 'Reveal file')).toBeTruthy();
+ });
+
+ it('counts only what is being drawn in the section head', () => {
+ show({ rows: [LAYER, followed({ enabled: false })] });
+
+ expect(document.querySelector('.count').textContent).toBe('1');
+ });
+});
+
+describe('the legend is the filter', () => {
+ it('opens to one row per category, with its colour and its count', () => {
+ show({ rows: [LAYER] });
+
+ byText('.legend-head', '2 groups').click();
+ flushSync();
+
+ const cats = rows('.cat');
+ expect(cats.map((node) => node.textContent.replace(/\s+/g, ' ').trim())).toEqual([
+ 'Checkpoints 2788',
+ 'Damage 412',
+ ]);
+ expect(cats[0].querySelector('.swatch').getAttribute('style')).toContain('#ff0000');
+ });
+
+ it('reports a hidden category as off rather than dropping it from the legend', () => {
+ show({ rows: [{ ...LAYER, hidden: ['Damage'] }] });
+ byText('.legend-head', '2 groups').click();
+ flushSync();
+
+ expect(rows('.cat').map((node) => node.getAttribute('aria-pressed'))).toEqual([
+ 'true',
+ 'false',
+ ]);
+ });
+
+ it('asks for exactly the category that was clicked', () => {
+ const oncategory = vi.fn();
+ show({ rows: [LAYER], oncategory });
+ byText('.legend-head', '2 groups').click();
+ flushSync();
+
+ rows('.cat')[1].click();
+
+ expect(oncategory).toHaveBeenCalledWith(LAYER, 'Damage');
+ });
+});
+
+/**
+ * The search shares the legend's slot, and the point of the sharing is that the
+ * two never speak at once: one is the filter the case keeps, the other is a way
+ * of looking that leaves nothing behind.
+ */
+describe('finding a pin', () => {
+ const HITS = [
+ { index: 4, name: 'North gate', category: 'Checkpoints', colour: '#ff0000', hidden: false },
+ { index: 9, name: 'Gate house', category: 'Damage', colour: '#5ac8fa', hidden: false },
+ ];
+
+ const finder = (found) => vi.fn(() => found);
+
+ function type(what) {
+ const box = document.querySelector('.find input');
+ box.value = what;
+ box.dispatchEvent(new Event('input'));
+ flushSync();
+ return box;
+ }
+
+ function opened(props = {}) {
+ show({ rows: [LAYER], ...props });
+ byText('.legend-head', '2 groups').click();
+ flushSync();
+ }
+
+ it('offers the box under the groups, on a layer that is being drawn', () => {
+ opened({ search: finder({ total: 0, results: [], ready: true }) });
+
+ expect(document.querySelector('.find input')).toBeTruthy();
+ });
+
+ it('offers nothing to search on a layer that is switched off', () => {
+ // a match is somewhere to go, and a layer nobody is drawing has nowhere
+ show({ rows: [{ ...LAYER, enabled: false }], search: finder(null) });
+ byText('.legend-head', '2 groups').click();
+ flushSync();
+
+ expect(document.querySelector('.find input')).toBeNull();
+ expect(rows('.cat')).toHaveLength(2);
+ });
+
+ it('shows the matches in place of the legend, and the legend again after', () => {
+ opened({ search: finder({ total: 2, results: HITS, ready: true }) });
+
+ type('gate');
+ expect(rows('.cat').map((node) => node.textContent.replace(/\s+/g, ' ').trim())).toEqual([
+ 'North gate Checkpoints',
+ 'Gate house Damage',
+ ]);
+
+ type('');
+ expect(rows('.cat').map((node) => node.textContent.replace(/\s+/g, ' ').trim())).toEqual([
+ 'Checkpoints 2788',
+ 'Damage 412',
+ ]);
+ });
+
+ it('never lets a search pass for a filter on the row above it', () => {
+ // the invariant the shared slot exists to protect: typing changes what is
+ // listed, and states nothing about what the map is drawing
+ opened({ search: finder({ total: 1, results: [HITS[0]], ready: true }) });
+
+ type('gate');
+
+ expect(text()).toContain(`3${GROUP_SPACE}200 features`);
+ expect(text()).not.toContain('shown');
+ });
+
+ it('says how many were found and how many are listed', () => {
+ opened({ search: finder({ total: 412, results: HITS, ready: true }) });
+
+ type('gate');
+
+ expect(document.querySelector('.search-count').textContent).toBe('412');
+ expect(text()).toContain('First 2 of 412.');
+ });
+
+ it('says when nothing matches', () => {
+ opened({ search: finder({ total: 0, results: [], ready: true }) });
+
+ type('gate');
+
+ expect(text()).toContain('No pin matches that.');
+ });
+
+ it('does not call that nothing while the features are still on their way', () => {
+ opened({ search: finder({ total: 0, results: [], ready: false }) });
+
+ type('gate');
+
+ expect(text()).toContain('Reading…');
+ expect(text()).not.toContain('No pin matches that.');
+ });
+
+ it('lists a match from a hidden group, marked, and still goes to it', () => {
+ const onpick = vi.fn();
+ const hit = { ...HITS[1], hidden: true };
+ opened({ search: finder({ total: 1, results: [hit], ready: true }), onpick });
+
+ type('gate');
+ const [match] = rows('.cat');
+
+ expect(match.className).toContain('off');
+ expect(match.title).toBe('Show this group and go there');
+ match.click();
+ expect(onpick).toHaveBeenCalledWith(LAYER, hit);
+ });
+});
+
+describe('the acts', () => {
+ it('reports the switch, the refresh, the reveal and the remove', () => {
+ const handlers = {
+ ontoggle: vi.fn(),
+ onrefresh: vi.fn(),
+ onreveal: vi.fn(),
+ onremove: vi.fn(),
+ onadd: vi.fn(),
+ };
+ show({ rows: [followed()], ...handlers });
+
+ document.querySelector('.eye').click();
+ byText('button', 'Refresh').click();
+ byText('button', 'Reveal file').click();
+ byText('button', 'Remove').click();
+ byText('button', 'Add a layer').click();
+
+ for (const handler of Object.values(handlers)) expect(handler).toHaveBeenCalled();
+ });
+
+ it('says a refresh is running on the row it is running on', () => {
+ show({ rows: [followed()], busy: 'Roadblocks' });
+
+ expect(byText('button', 'Reading…')).toBeTruthy();
+ expect(byText('button', 'Reading…').disabled).toBe(true);
+ });
+});
diff --git a/frontend/src/tools/satellite/AddedLayers.svelte b/frontend/src/tools/satellite/AddedLayers.svelte
new file mode 100644
index 0000000..3fd63bb
--- /dev/null
+++ b/frontend/src/tools/satellite/AddedLayers.svelte
@@ -0,0 +1,398 @@
+<script>
+ /**
+ * The second section of the Layers panel: what the analyst put there.
+ *
+ * The list above it is Azimut's own stack, and it is untouched. The line
+ * between the two is *who chose it* — not local versus remote, which is why a
+ * dropped KMZ and a followed My Maps are rows of one list.
+ *
+ * A row here carries four things a curated row does not, and each is a failure
+ * this feature would otherwise have:
+ *
+ * - **where it came from**, because a layer with no stated source is a claim
+ * with no provenance;
+ * - **how fresh it is**, said before the marks are read rather than after —
+ * week-old data drawn silently on a map where decisions get made is the
+ * worst thing this could do;
+ * - **its legend, which is the filter**, one row per category with its colour
+ * and its count, clicking one hides exactly those features;
+ * - **Remove, Refresh and Reveal**, because the analyst owns this layer in a
+ * way they do not own the borders overlay.
+ *
+ * Everything a row states is computed in `lib/map/addedLayers.js`, so the
+ * rules are read off a test rather than off a screen.
+ *
+ * The legend and the search share one slot under the chevron, and never show
+ * at once. They are the two ways into the same features and they are not the
+ * same act: the legend is the filter, persisted on the spec and counted on the
+ * row above; the search is a finder, ephemeral, and it changes nothing about
+ * what the map draws. One slot is also what keeps a row this tall from growing
+ * a third thing to unfold.
+ */
+ import Icon from '../../components/Icon.svelte';
+ import SearchInput from '../../components/SearchInput.svelte';
+ import {
+ countLabel,
+ freshness,
+ grouped,
+ legend,
+ sourceLabel,
+ } from '../../lib/map/addedLayers.js';
+
+ let {
+ /** The rows as the backend returned them. */
+ rows = [],
+ /** The layer an act is running on, so its buttons can say so. */
+ busy = '',
+ open = $bindable(true),
+ /** `(layer, query) => { total, results, ready }`, over features already in
+ * memory. Nothing here fetches. */
+ search,
+ ontoggle,
+ oncategory,
+ onrefresh,
+ onremove,
+ onreveal,
+ onpick,
+ onadd,
+ } = $props();
+
+ const live = $derived(rows.filter((row) => row.enabled).length);
+
+ /** Expanded legends, by layer name. A layer's categories are its own list and
+ * three of them open at once would push the case's own panel off screen. */
+ let expanded = $state(new Set());
+
+ /** What is typed in each layer's box, by layer name. Kept while a row is
+ * folded away: it costs nothing, since a search draws nothing. */
+ let queries = $state({});
+
+ function toggleLegend(name) {
+ const next = new Set(expanded);
+ if (next.has(name)) next.delete(name);
+ else next.add(name);
+ expanded = next;
+ }
+</script>
+
+<button type="button" class="sub-head" onclick={() => (open = !open)}>
+ <Icon name={open ? 'chevronDown' : 'chevronRight'} size={12} />
+ <Icon name="compass" size={13} />
+ <span>Added layers</span>
+ <span class="count">{live}</span>
+</button>
+
+{#if open}
+ {#if !rows.length}
+ <p class="empty">Nothing added yet.</p>
+ {/if}
+ <ul class="layers">
+ {#each rows as row (row.name)}
+ <li>
+ <div class="row">
+ <button
+ type="button"
+ class="eye"
+ class:on={row.enabled}
+ aria-pressed={row.enabled}
+ aria-label={row.title}
+ title={row.enabled ? 'Stop drawing this layer' : 'Draw this layer'}
+ onclick={() => ontoggle?.(row)}
+ >
+ <Icon name="eye" size={13} />
+ </button>
+ <span class="name" class:off={!row.enabled}>{row.title}</span>
+ </div>
+ <p class="meta">
+ <!-- A followed map is a page somebody publishes, so where it came
+ from is a way of getting there: this is the one thing on the row
+ that leaves the app, and it leaves on a click rather than on a
+ render. A file has no such address and stays plain text. -->
+ {#if row.source?.kind === 'url' && row.source.url}
+ <a
+ class="from"
+ href={row.source.url}
+ target="_blank"
+ rel="noreferrer"
+ title="Open this map at its source"
+ >{sourceLabel(row)} <Icon name="external" size={9} /></a>
+ {:else}
+ <span>{sourceLabel(row)}</span>
+ {/if}
+ <!-- A stale subscription says so here, in its own colour, before
+ anyone reads a single mark it drew. -->
+ <span class:stale={row.stale}>{freshness(row)}</span>
+ </p>
+ <!-- Both numbers, always: what is loaded and what is drawn, never the
+ one passing for the other. -->
+ <p class="meta counts">{countLabel(row)}</p>
+
+ {#if row.categories.length}
+ <button
+ type="button"
+ class="legend-head"
+ aria-expanded={expanded.has(row.name)}
+ onclick={() => toggleLegend(row.name)}
+ >
+ <Icon name={expanded.has(row.name) ? 'chevronDown' : 'chevronRight'} size={11} />
+ <span>{row.categories.length} {row.categories.length === 1 ? 'group' : 'groups'}</span>
+ </button>
+ {#if expanded.has(row.name)}
+ {@const query = (queries[row.name] ?? '').trim()}
+ <!-- Only on a layer being drawn: a match is somewhere to go, and a
+ layer switched off has nowhere. -->
+ {@const found = row.enabled && query ? search?.(row, query) : null}
+ {#if row.enabled}
+ <div class="find">
+ <SearchInput
+ bind:value={
+ () => queries[row.name] ?? '',
+ (typed) => (queries[row.name] = typed)
+ }
+ placeholder="Find a pin"
+ width="100%"
+ count={found?.ready ? grouped(found.total) : null}
+ />
+ </div>
+ {/if}
+
+ {#if found}
+ {#if !found.ready}
+ <p class="empty">Reading…</p>
+ {:else if !found.total}
+ <p class="empty">No pin matches that.</p>
+ {:else}
+ <ul class="legend">
+ {#each found.results as hit (hit.index)}
+ <li>
+ <!-- A match in a group the legend switched off is listed
+ all the same, marked, and going to it turns the group
+ back on. -->
+ <button
+ type="button"
+ class="cat"
+ class:off={hit.hidden}
+ title={hit.hidden ? 'Show this group and go there' : 'Go to this pin'}
+ onclick={() => onpick?.(row, hit)}
+ >
+ <span class="swatch" style="--swatch: {hit.colour}"></span>
+ <span class="cat-name">{hit.name}</span>
+ {#if hit.category}<span class="cat-group">{hit.category}</span>{/if}
+ </button>
+ </li>
+ {/each}
+ </ul>
+ {#if found.total > found.results.length}
+ <p class="empty">First {found.results.length} of {grouped(found.total)}.</p>
+ {/if}
+ {/if}
+ {:else}
+ <ul class="legend">
+ {#each legend(row) as entry (entry.name)}
+ <li>
+ <button
+ type="button"
+ class="cat"
+ class:off={!entry.on}
+ aria-pressed={entry.on}
+ title={entry.on ? 'Hide this group' : 'Show this group'}
+ onclick={() => oncategory?.(row, entry.name)}
+ >
+ <span class="swatch" style="--swatch: {entry.colour}"></span>
+ <span class="cat-name">{entry.name}</span>
+ <span class="cat-count">{entry.count}</span>
+ </button>
+ </li>
+ {/each}
+ </ul>
+ {/if}
+ {/if}
+ {/if}
+
+ <nav class="acts" aria-label={row.title}>
+ {#if row.source?.kind === 'url'}
+ <button
+ class="btn btn-sm"
+ disabled={busy === row.name}
+ onclick={() => onrefresh?.(row)}
+ >{busy === row.name ? 'Reading…' : 'Refresh'}</button>
+ {/if}
+ <button class="btn btn-sm quiet" onclick={() => onreveal?.(row)}>Reveal file</button>
+ <button class="btn btn-sm quiet" onclick={() => onremove?.(row)}>Remove</button>
+ </nav>
+ </li>
+ {/each}
+ </ul>
+ <button type="button" class="add" onclick={() => onadd?.()}>
+ <Icon name="plus" size={12} />
+ <span>Add a layer</span>
+ </button>
+{/if}
+
+<style>
+ .layers {
+ margin: 0;
+ padding: 0 4px;
+ list-style: none;
+ }
+ .layers > li {
+ padding-bottom: 6px;
+ }
+ .row {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ min-height: 26px;
+ }
+ .eye {
+ display: grid;
+ place-items: center;
+ width: 22px;
+ height: 22px;
+ border-radius: var(--radius-1);
+ color: var(--text-3);
+ cursor: pointer;
+ }
+ .eye:hover {
+ color: var(--text-1);
+ background: var(--bg-3);
+ }
+ .eye.on {
+ color: var(--accent);
+ }
+ .name {
+ flex: 1;
+ font-size: var(--fs-sm);
+ color: var(--text-1);
+ }
+ .name.off {
+ color: var(--text-3);
+ }
+ .meta {
+ display: flex;
+ gap: 6px;
+ margin: 0;
+ padding-left: 30px;
+ font-size: 10px;
+ color: var(--text-3);
+ }
+ .meta > * + *::before {
+ content: '· ';
+ }
+ .from {
+ display: inline-flex;
+ align-items: center;
+ gap: 3px;
+ color: inherit;
+ text-decoration: none;
+ }
+ .from:hover {
+ color: var(--text-1);
+ text-decoration: underline;
+ }
+ .counts {
+ font-variant-numeric: tabular-nums;
+ }
+ /* The one thing on this row that is allowed to shout. */
+ .stale {
+ color: var(--warn, #ffcc66);
+ }
+ .legend-head {
+ display: flex;
+ align-items: center;
+ gap: 4px;
+ padding: 3px 0 2px 26px;
+ color: var(--text-3);
+ font-size: 10px;
+ cursor: pointer;
+ }
+ .legend-head:hover {
+ color: var(--text-1);
+ }
+ .legend {
+ margin: 0;
+ padding: 0 0 2px 30px;
+ list-style: none;
+ }
+ .cat {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+ width: 100%;
+ padding: 2px 4px;
+ border-radius: var(--r-sm);
+ color: var(--text-2);
+ font-size: 11px;
+ text-align: left;
+ cursor: pointer;
+ }
+ .cat:hover {
+ background: var(--bg-3);
+ color: var(--text-1);
+ }
+ .cat.off {
+ color: var(--text-3);
+ }
+ .swatch {
+ flex: none;
+ width: 9px;
+ height: 9px;
+ border-radius: 2px;
+ background: var(--swatch);
+ }
+ .cat.off .swatch {
+ background: none;
+ box-shadow: inset 0 0 0 1px var(--swatch);
+ }
+ .cat-name {
+ flex: 1;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ }
+ .cat-count {
+ font-variant-numeric: tabular-nums;
+ color: var(--text-3);
+ }
+ /* Which group a match came from, since the list is no longer sorted into
+ them. Capped, so a long group name never squeezes out the pin's own. */
+ .cat-group {
+ flex: none;
+ max-width: 40%;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ color: var(--text-3);
+ }
+ .find {
+ padding: 2px 4px 4px 30px;
+ }
+ .acts {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 4px;
+ padding: 4px 0 0 30px;
+ }
+ .empty {
+ margin: 0;
+ padding: 2px 0 4px 30px;
+ font-size: 10px;
+ color: var(--text-3);
+ }
+ .add {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+ margin: 0 4px 10px 30px;
+ padding: 4px 8px;
+ border: 1px dashed var(--border);
+ border-radius: var(--r-sm);
+ color: var(--text-3);
+ font-size: 11px;
+ cursor: pointer;
+ }
+ .add:hover {
+ border-color: var(--accent);
+ color: var(--accent);
+ }
+</style>
diff --git a/frontend/src/tools/satellite/AddedLayersOverlay.svelte b/frontend/src/tools/satellite/AddedLayersOverlay.svelte
new file mode 100644
index 0000000..15710e1
--- /dev/null
+++ b/frontend/src/tools/satellite/AddedLayersOverlay.svelte
@@ -0,0 +1,162 @@
+<script>
+ /**
+ * The added layers on the map, one GL source each.
+ *
+ * Thin on purpose: `lib/map/addedLayer.js` owns the engine side, this owns the
+ * lifecycle — which layers are drawn right now, which have to be torn down,
+ * and what a click on one of their features opens.
+ *
+ * That card is **read-only, by construction rather than by restraint**: it is
+ * built from the strings the source stated and offers no control at all. There
+ * is no route from a feature into the case, because a feature here is somebody
+ * else's claim and the case is this analyst's work. How it is laid out lives in
+ * `lib/map/layerCard.js`; only its lifecycle lives here.
+ */
+ import { createAddedLayer } from '../../lib/map/addedLayer.js';
+ import { attribution } from '../../lib/map/addedLayers.js';
+ import { layerCard } from '../../lib/map/layerCard.js';
+
+ let {
+ engine = null,
+ caseId = '',
+ layers = [],
+ drawing,
+ /** The search result the panel sent here: `{ name, index, at }`, or null. */
+ picked = null,
+ } = $props();
+
+ /** name → { layer, sha } so a refreshed snapshot redraws and nothing else does. */
+ const live = new Map();
+
+ /**
+ * Where this layer's own icons are, or nothing when it has none.
+ *
+ * Always a path on this server. The source's addresses were followed once, by
+ * the backend, at the moment the analyst ticked the box; what is left of them
+ * here is a content hash per image, so the browser asks localhost for a
+ * picture rather than Google for the one a My Maps pointed at.
+ */
+ function iconUrlFor(row) {
+ if (!row.icons) return null;
+ const base = `/api/cases/${caseId}/map-layers/${row.name}/icons`;
+ return (key) => `${base}/${key}`;
+ }
+
+ function drop(name) {
+ live.get(name)?.layer.destroy();
+ live.delete(name);
+ }
+
+ $effect(() => {
+ if (!engine || !caseId) return;
+ const wanted = new Set(layers.map((row) => row.name));
+ for (const name of [...live.keys()]) {
+ if (!wanted.has(name)) drop(name);
+ }
+ for (const row of layers) {
+ const existing = live.get(row.name);
+ if (existing && existing.sha === row.sha256) {
+ // already drawn from these bytes: only the legend can have moved
+ existing.layer.filter(row.hidden);
+ continue;
+ }
+ if (existing) drop(row.name);
+ const layer = createAddedLayer(engine, {
+ card: layerCard(row.title),
+ iconUrl: iconUrlFor(row),
+ });
+ live.set(row.name, { layer, sha: row.sha256 });
+ drawing(caseId, row.name)
+ .then((collection) => {
+ // the layer may have been switched off while its features were loading
+ if (live.get(row.name)?.layer !== layer) return;
+ layer.set(collection, {
+ categories: row.categories,
+ hidden: row.hidden,
+ attribution: attribution(row),
+ });
+ })
+ .catch(() => drop(row.name));
+ }
+ });
+
+ /**
+ * A match picked in the panel, framed and opened on the map.
+ *
+ * Declared after the effect above on purpose: switching a group back on runs
+ * that one, and it closes whatever card is open. Opening ours first would
+ * hand it straight back.
+ */
+ let went = 0;
+ $effect(() => {
+ if (!picked || picked.at === went) return;
+ went = picked.at;
+ live.get(picked.name)?.layer.reveal(picked.index);
+ });
+
+ $effect(() => () => {
+ for (const name of [...live.keys()]) drop(name);
+ });
+</script>
+
+<style>
+ /* The card is built outside this component's markup, so its rules are global.
+ Only what is inside it: the card's own surface is the one every mark on this
+ map opens on, and it is dressed once in `lib/map/engine.css`.
+
+ Deliberately plain — it states what the source says and nothing else. */
+ :global(.layer-card h4) {
+ margin: 0;
+ color: var(--text-1);
+ font-size: var(--fs-sm);
+ }
+ :global(.layer-card-group) {
+ margin: 2px 0 0;
+ color: var(--text-3);
+ font-size: 10px;
+ }
+ :global(.layer-card-body) {
+ margin: 6px 0 0;
+ max-height: 220px;
+ overflow-y: auto;
+ color: var(--text-2);
+ font-size: var(--fs-xs);
+ }
+ :global(.layer-card-text) {
+ margin: 0 0 6px;
+ white-space: pre-wrap;
+ }
+ /* A labelled line, drawn as the row the source wrote: the label above its
+ value, because a popup is 320px wide and a two-column row would leave the
+ values a few words each. */
+ :global(.layer-card-field) {
+ display: flex;
+ flex-direction: column;
+ margin-bottom: 6px;
+ }
+ :global(.layer-card-label) {
+ color: var(--text-3);
+ font-size: 10px;
+ }
+ :global(.layer-card-value) {
+ white-space: pre-wrap;
+ overflow-wrap: anywhere;
+ }
+ /* The app's own link colour, underlined: a foreign address inside a wall of
+ the source's text has to read as clickable before it is hovered. */
+ :global(.layer-card-body a) {
+ text-decoration: underline;
+ overflow-wrap: anywhere;
+ }
+ :global(.layer-card-body > :last-child) {
+ margin-bottom: 0;
+ }
+ /* Whose map this came from, signed in the corner: quiet, because it answers a
+ question the analyst only asks when several layers are drawn at once. */
+ :global(.layer-card-from) {
+ margin: 8px 0 0;
+ color: var(--text-3);
+ font-size: 10px;
+ text-align: right;
+ }
+</style>
diff --git a/frontend/src/tools/satellite/ImageryChip.svelte b/frontend/src/tools/satellite/ImageryChip.svelte
index 0e36bba..28bb599 100644
--- a/frontend/src/tools/satellite/ImageryChip.svelte
+++ b/frontend/src/tools/satellite/ImageryChip.svelte
@@ -36,6 +36,9 @@
wayback = null,
/** What it is actually showing — a billed base steps aside when paused. */
shown,
+ /** Open the Sentinel-2 picker from a dated chip, as Wayback's already is.
+ * Compare asks for it: its card has a layers button of its own. */
+ dateChip = false,
} = $props();
let menuOpen = $state(false);
@@ -103,6 +106,7 @@
<SentinelPicker
bind:menuEl={s2MenuEl}
{s2}
+ {dateChip}
{maxccLabel}
{monthLabel}
{monthGrid}
@@ -195,7 +199,9 @@
position: absolute;
top: calc(100% + 6px);
right: 0;
- z-index: 20;
+ /* the same layer as the date pickers beside it: lower, and Compare's
+ annotation rail drew straight over the open list */
+ z-index: 700;
/* wide enough for the longest basemap name on one line: the list is read
by shape as much as by word, and a wrapped row breaks the column */
min-width: 244px;
diff --git a/frontend/src/tools/satellite/MapContextMenu.svelte b/frontend/src/tools/satellite/MapContextMenu.svelte
index 83e0f11..360fc97 100644
--- a/frontend/src/tools/satellite/MapContextMenu.svelte
+++ b/frontend/src/tools/satellite/MapContextMenu.svelte
@@ -7,9 +7,16 @@
* screen grab. The list and the placement are `lib/map/contextMenu.js`; the
* acts are the tool's, reported through `onpick`.
*/
- import { onMount } from 'svelte';
+ import { onMount, tick } from 'svelte';
import Icon from '../../components/Icon.svelte';
- import { ACTIONS, copyRows, nextFocus, openRows, placeMenu } from '../../lib/map/contextMenu.js';
+ import {
+ ACTIONS,
+ copyRows,
+ nextFocus,
+ openRows,
+ placeMenu,
+ placeSubmenu,
+ } from '../../lib/map/contextMenu.js';
let {
/** `{ lat, lon, x, y }`: the point, and where it was clicked in the map. */
@@ -31,22 +38,93 @@
} = $props();
let menuEl = $state();
+ let subEl = $state();
+ let openRowEl = $state();
let width = $state(0);
let height = $state(0);
+ let subWidth = $state(0);
+ let subHeight = $state(0);
let linksOpen = $state(false);
const copies = $derived(copyRows(at.lat, at.lon, format));
const links = $derived(openRows(at.lat, at.lon, zoom));
- // Measured once drawn; until then a typical size keeps the first frame inside.
+
+ /**
+ * Placed once, from the real measurement, and then never again.
+ *
+ * Until it is measured a typical size keeps the first frame inside the map.
+ * After that the answer is frozen: this used to be recomputed from the menu's
+ * live height, so anything that made the menu taller — an answer coming back
+ * from "What is here?", the external maps unfolding — slid the whole thing out
+ * from under the cursor.
+ */
+ let fixed = $state(null);
const place = $derived(
- placeMenu(at, { width: width || 236, height: height || 320 }, frame)
+ fixed ?? placeMenu(at, { width: width || 236, height: height || 320 }, frame)
+ );
+ $effect(() => {
+ if (!fixed && width && height) fixed = placeMenu(at, { width, height }, frame);
+ });
+
+ /**
+ * The submenu's own box, in the same frame coordinates as the parent's.
+ *
+ * A sibling rather than a child: the parent scrolls when its content outgrows
+ * the map, and an overflow that scrolls also clips, so a flyout drawn inside
+ * it would be cut off at its edge. The two elements answer as one menu instead
+ * — one outside-click, one arrow walk, one keyboard handler across both.
+ */
+ const sub = $derived(
+ linksOpen
+ ? placeSubmenu(
+ {
+ left: place.left,
+ top: place.top,
+ width: width || 236,
+ rowTop: place.top + (openRowEl?.offsetTop ?? 0),
+ },
+ { width: subWidth || 168, height: subHeight || 300 },
+ frame
+ )
+ : null
);
function items() {
- return [...(menuEl?.querySelectorAll('[role="menuitem"]') ?? [])];
+ const rows = (element) => [...(element?.querySelectorAll('[role="menuitem"]') ?? [])];
+ return [...rows(menuEl), ...rows(subEl)];
+ }
+
+ /** Open the external maps and step into them, as a submenu does. */
+ async function openLinks() {
+ linksOpen = true;
+ await tick();
+ subEl?.querySelector('[role="menuitem"]')?.focus();
+ }
+
+ function closeLinks() {
+ linksOpen = false;
+ openRowEl?.focus();
}
function onkeydown(event) {
+ const inSub = Boolean(subEl?.contains(document.activeElement));
+ if (event.key === 'ArrowRight' && document.activeElement === openRowEl) {
+ event.preventDefault();
+ openLinks();
+ return;
+ }
+ if (event.key === 'ArrowLeft' && inSub) {
+ event.preventDefault();
+ closeLinks();
+ return;
+ }
+ if (event.key === 'Escape' && linksOpen) {
+ // the submenu is what Escape leaves first, as it is everywhere else
+ event.preventDefault();
+ event.stopPropagation();
+ closeLinks();
+ return;
+ }
const rows = items();
const current = rows.indexOf(document.activeElement);
const move = { ArrowDown: 1, ArrowUp: -1 }[event.key];
@@ -70,7 +148,9 @@
onMount(() => {
items()[0]?.focus();
const outside = (event) => {
- if (menuEl && !menuEl.contains(event.target)) onclose();
+ const inside =
+ menuEl?.contains(event.target) || subEl?.contains(event.target);
+ if (menuEl && !inside) onclose();
};
document.addEventListener('mousedown', outside, true);
return () => document.removeEventListener('mousedown', outside, true);
@@ -119,40 +199,63 @@
<div class="rule" role="separator"></div>
+ <!-- A submenu, not a fold: the list opens beside the menu so the menu itself
+ never changes size, and nothing the cursor is resting on moves. -->
<button
+ bind:this={openRowEl}
class="item"
+ class:open={linksOpen}
role="menuitem"
+ aria-haspopup="menu"
aria-expanded={linksOpen}
- onclick={() => (linksOpen = !linksOpen)}
+ onclick={() => (linksOpen ? closeLinks() : openLinks())}
>
<Icon name="external" size={13} />
<span>Open in…</span>
- <Icon name={linksOpen ? 'chevronDown' : 'chevronRight'} size={12} />
+ <Icon name="chevronRight" size={12} />
</button>
- {#if linksOpen}
- <div class="links">
- {#each links as link (link.id)}
- <a
- class="item link"
- role="menuitem"
- href={fullscreen ? undefined : link.url}
- target="_blank"
- rel="noreferrer"
- aria-disabled={fullscreen}
- title={fullscreen ? 'Exit fullscreen first. This leaves the map' : link.url}
- onclick={() => !fullscreen && onclose()}
- >{link.label}</a>
- {/each}
- </div>
- {/if}
</div>
+{#if sub}
+ <div
+ bind:this={subEl}
+ bind:offsetWidth={subWidth}
+ bind:offsetHeight={subHeight}
+ class="ctx card sub"
+ role="menu"
+ tabindex="-1"
+ aria-label="Open this point in"
+ style:left={`${sub.left}px`}
+ style:top={`${sub.top}px`}
+ {onkeydown}
+ oncontextmenu={(event) => event.preventDefault()}
+ >
+ {#each links as link (link.id)}
+ <a
+ class="item link"
+ role="menuitem"
+ href={fullscreen ? undefined : link.url}
+ target="_blank"
+ rel="noreferrer"
+ aria-disabled={fullscreen}
+ title={fullscreen ? 'Exit fullscreen first. This leaves the map' : link.url}
+ onclick={() => !fullscreen && onclose()}
+ >{link.label}</a>
+ {/each}
+ </div>
+{/if}
+
<style>
.ctx {
position: absolute;
z-index: 800;
min-width: 220px;
max-width: 300px;
+ /* Bounded by the map it opens in, so content arriving late — the answer to
+ "What is here?" — scrolls inside a menu that stays where it was put,
+ rather than growing past the frame and having to be moved. */
+ max-height: calc(100% - 16px);
+ overflow-y: auto;
padding: 4px;
display: flex;
flex-direction: column;
@@ -161,6 +264,19 @@
box-shadow: var(--shadow-2);
outline: none;
}
+ /* A sibling of the menu, placed against the same frame. One notch above it,
+ and therefore above the status bar the menu already outranks — a submenu
+ hanging off a low row would otherwise have its last entries covered by the
+ bar floating at the bottom of the map. */
+ .sub {
+ z-index: 801;
+ min-width: 150px;
+ max-height: none;
+ }
+ .item.open {
+ background: var(--bg-3);
+ color: var(--text-1);
+ }
.item {
display: flex;
align-items: center;
@@ -212,11 +328,6 @@
.answer.warn {
color: var(--warn, #e2a03f);
}
- .links {
- display: flex;
- flex-direction: column;
- padding-left: 21px;
- }
.link {
font-size: var(--fs-xs);
}
diff --git a/frontend/src/tools/satellite/MapContextMenu.test.js b/frontend/src/tools/satellite/MapContextMenu.test.js
index e307929..97c0f52 100644
--- a/frontend/src/tools/satellite/MapContextMenu.test.js
+++ b/frontend/src/tools/satellite/MapContextMenu.test.js
@@ -49,6 +49,15 @@ describe('the right-click menu', () => {
expect(body).not.toContain('Google Earth');
});
+ it('says the links are a submenu, not a fold, so the menu cannot change size', () => {
+ // opening them used to grow the menu, which a menu already placed against
+ // the frame's edge answered by moving out from under the cursor
+ const { body } = render(MapContextMenu, { props: props() });
+
+ expect(body).toContain('aria-haspopup="menu"');
+ expect(body).not.toContain('chevronDown');
+ });
+
it('states the lookup where it was asked, while it runs and once it answered', () => {
expect(
render(MapContextMenu, { props: props({ lookup: { busy: true } }) }).body
diff --git a/frontend/src/tools/satellite/SentinelPicker.svelte b/frontend/src/tools/satellite/SentinelPicker.svelte
index bb6d810..2385fff 100644
--- a/frontend/src/tools/satellite/SentinelPicker.svelte
+++ b/frontend/src/tools/satellite/SentinelPicker.svelte
@@ -4,8 +4,26 @@
/** `s2` is the store from `state/sentinel.svelte.js`: what has been asked,
* what came back, and what is still in flight. The label helpers are pure
* (`lib/sentinel.js`) and are handed over so this stays a view. */
- let { menuEl = $bindable(), s2, maxccLabel, monthLabel, monthGrid, cloudClass, cloudLabel } =
- $props();
+ let {
+ menuEl = $bindable(),
+ s2,
+ maxccLabel,
+ monthLabel,
+ monthGrid,
+ cloudClass,
+ cloudLabel,
+ /**
+ * Open from a dated chip rather than a layers icon, the way the Wayback
+ * picker beside it does. Compare's source card carries its own layers
+ * button, and two identical icons in one card said nothing about which of
+ * them held the date.
+ */
+ dateChip = false,
+ } = $props();
+
+ // What the tiles are dated: the pinned pass, or the one "most recent" resolved
+ // to. Blank only while that lookup is out, or where no pass came back at all.
+ const chipDate = $derived(s2.date || s2.latest || '');
// The readout tracks the drag; the ceiling only moves on release. Every step
// in between would be a provider id of its own, and Sentinel-2 tiles are
@@ -15,13 +33,27 @@
</script>
<div class="s2-wrap" bind:this={menuEl}>
- <button
- class="btn btn-icon"
- class:on={s2.menuOpen}
- onclick={s2.toggleMenu}
- title="Sentinel-2 layer and date"
- aria-label="Sentinel-2 layer and date"
- ><Icon name="layers" size={14} /></button>
+ {#if dateChip}
+ <button
+ class="chip"
+ class:on={s2.menuOpen}
+ onclick={s2.toggleMenu}
+ title={s2.date ? `Sentinel-2 pass of ${s2.date}` : 'Sentinel-2 layer and date'}
+ aria-label="Sentinel-2 layer and date"
+ aria-expanded={s2.menuOpen}
+ >
+ <Icon name="clock" size={13} />
+ <span class="mono">{chipDate || 'Most recent'}</span>
+ </button>
+ {:else}
+ <button
+ class="btn btn-icon"
+ class:on={s2.menuOpen}
+ onclick={s2.toggleMenu}
+ title="Sentinel-2 layer and date"
+ aria-label="Sentinel-2 layer and date"
+ ><Icon name="layers" size={14} /></button>
+ {/if}
{#if s2.menuOpen}
<div class="s2-menu card">
<div class="menu-row">
@@ -70,7 +102,7 @@
<div class="menu-row">
<span class="menu-label">Date</span>
<div class="chips">
- <button class="chip" class:on={!s2.date} onclick={s2.clearDate}>Most recent</button>
+ <button class="chip-opt" class:on={!s2.date} onclick={s2.clearDate}>Most recent</button>
</div>
</div>
@@ -141,6 +173,23 @@
<style>
.s2-wrap { position: relative; display: flex; }
+ /* the same trigger as the Wayback picker, so one date reads like the other */
+ .chip {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+ height: 30px;
+ padding: 0 8px;
+ border-radius: var(--radius-1);
+ font-size: var(--fs-xs);
+ color: var(--text-1);
+ background: rgba(24, 24, 24, 0.88);
+ backdrop-filter: blur(6px);
+ box-shadow: 0 0 0 1px var(--border);
+ cursor: pointer;
+ }
+ .chip:hover,
+ .chip.on { color: var(--accent); }
/* Down and to the left of its button, because the picker now rides in the
surface's own top-right corner: opening upwards put a calendar off the top
of the map, where the surface clips it. The height is capped for the same
@@ -168,7 +217,7 @@
.menu-row { display: flex; align-items: center; gap: 10px; justify-content: space-between; }
.menu-label { font-size: var(--fs-xs); color: var(--text-3); font-weight: 600; }
.chips { display: flex; gap: 4px; flex-wrap: wrap; justify-content: flex-end; }
- .chip {
+ .chip-opt {
padding: 4px 9px;
border-radius: var(--r-sm);
border: 1px solid var(--border);
@@ -179,8 +228,8 @@
cursor: pointer;
transition: border-color 0.12s, color 0.12s, background 0.12s;
}
- .chip:hover { color: var(--text-1); border-color: var(--border-strong); }
- .chip.on { border-color: var(--accent); background: var(--accent-soft); color: var(--accent); }
+ .chip-opt:hover { color: var(--text-1); border-color: var(--border-strong); }
+ .chip-opt.on { border-color: var(--accent); background: var(--accent-soft); color: var(--accent); }
.cc { display: flex; align-items: center; gap: 6px; }
.cc input[type='range'] { width: 96px; accent-color: var(--accent); cursor: pointer; }
.cc-value { font-size: 10px; color: var(--text-2); min-width: 52px; text-align: right; }
diff --git a/frontend/src/tools/satellite/SentinelPicker.test.js b/frontend/src/tools/satellite/SentinelPicker.test.js
index b325b4e..116bb61 100644
--- a/frontend/src/tools/satellite/SentinelPicker.test.js
+++ b/frontend/src/tools/satellite/SentinelPicker.test.js
@@ -13,6 +13,7 @@ function props({ s2 = {}, ...overrides } = {}) {
layerHint: '',
layersSource: 'instance',
date: '',
+ latest: '',
maxcc: 100,
month: '2026-05',
passes: { '2026-05-11': { cloud: 4, granules: 1 } },
@@ -90,3 +91,34 @@ describe('SentinelPicker date safety', () => {
expect(body).toContain('Checking imagery for 2026-05-11');
});
});
+
+describe('SentinelPicker trigger', () => {
+ it('is a layers icon on a map surface, which has no layers button of its own', () => {
+ const { body } = render(SentinelPicker, { props: props({ s2: { menuOpen: false } }) });
+ expect(body).toMatch(/<button[^>]*class="btn btn-icon[^"]*"/);
+ expect(body).not.toContain('Most recent');
+ });
+
+ it('carries the pinned pass as a dated chip when Compare asks for one', () => {
+ const { body } = render(SentinelPicker, {
+ props: props({ s2: { menuOpen: false, date: '2025-04-11' }, dateChip: true }),
+ });
+ expect(body).toMatch(/<button[^>]*class="chip[^"]*"/);
+ expect(body).toContain('2025-04-11');
+ expect(body).toContain('Sentinel-2 pass of 2025-04-11');
+ });
+
+ it('dates the chip by the pass "most recent" resolved to', () => {
+ const { body } = render(SentinelPicker, {
+ props: props({ s2: { menuOpen: false, date: '', latest: '2025-03-28' }, dateChip: true }),
+ });
+ expect(body).toContain('2025-03-28');
+ });
+
+ it('says "Most recent" while no pass has come back', () => {
+ const { body } = render(SentinelPicker, {
+ props: props({ s2: { menuOpen: false }, dateChip: true }),
+ });
+ expect(body).toContain('Most recent');
+ });
+});
diff --git a/frontend/src/tools/satellite/WaybackPicker.svelte b/frontend/src/tools/satellite/WaybackPicker.svelte
index a0d4044..ffc4d10 100644
--- a/frontend/src/tools/satellite/WaybackPicker.svelte
+++ b/frontend/src/tools/satellite/WaybackPicker.svelte
@@ -46,46 +46,48 @@
{:else if !wb.releases.length}
<div class="menu-hint dim">Reading the release list…</div>
{:else}
- <div class="step-row">
- <button
- class="nav"
- onclick={() => wb.step(1)}
- disabled={wb.position >= list.length - 1}
- aria-label="Older release"
- title="Older release"
- ><Icon name="chevronLeft" size={13} /></button>
- <span class="current mono">{sliderDate}</span>
- <button
- class="nav"
- onclick={() => wb.step(-1)}
- disabled={wb.position <= 0}
- aria-label="Newer release"
- title="Newer release"
- ><Icon name="chevronRight" size={13} /></button>
- </div>
- <input
- class="slider"
- type="range"
- min="0"
- max={last}
- step="1"
- value={sliderValue}
- disabled={list.length < 2}
- oninput={(event) => (dragging = Number(event.currentTarget.value))}
- onchange={(event) => {
- const picked = list[last - Number(event.currentTarget.value)];
- dragging = null;
- if (picked) wb.pick(picked.release);
- }}
- aria-label="Release"
- />
+ {#if !wb.reading}
+ <div class="step-row">
+ <button
+ class="nav"
+ onclick={() => wb.step(1)}
+ disabled={wb.position >= list.length - 1}
+ aria-label="Older release"
+ title="Older release"
+ ><Icon name="chevronLeft" size={13} /></button>
+ <span class="current mono">{sliderDate}</span>
+ <button
+ class="nav"
+ onclick={() => wb.step(-1)}
+ disabled={wb.position <= 0}
+ aria-label="Newer release"
+ title="Newer release"
+ ><Icon name="chevronRight" size={13} /></button>
+ </div>
+ <input
+ class="slider"
+ type="range"
+ min="0"
+ max={last}
+ step="1"
+ value={sliderValue}
+ disabled={list.length < 2}
+ oninput={(event) => (dragging = Number(event.currentTarget.value))}
+ onchange={(event) => {
+ const picked = list[last - Number(event.currentTarget.value)];
+ dragging = null;
+ if (picked) wb.pick(picked.release);
+ }}
+ aria-label={wb.changesOnly ? 'Change' : 'Release'}
+ />
+ {/if}
<div class="chips">
<button
class="chip-opt"
class:on={wb.changesOnly}
onclick={() => wb.setChangesOnly(true)}
- title="Only releases whose pixels differ at the crosshair"
+ title="Only releases showing a different picture at the crosshair"
>Changes here</button>
<button
class="chip-opt"
@@ -111,26 +113,28 @@
{/if}
{/if}
- <ul class="releases" aria-label="Releases">
- {#each list as entry, index (entry.release)}
- {@const shot = wb.picture(entry.release)}
- <li>
- <button
- class="row mono"
- class:on={index === onScreen}
- onclick={() => wb.pick(entry.release)}
- title={shot?.source ? `Taken by ${shot.source}` : undefined}
- >
- <span>{entry.date}</span>
- {#if shot?.acquired}<span class="taken">taken {shot.acquired}</span>{/if}
- </button>
- </li>
- {/each}
- </ul>
+ {#if !wb.reading}
+ <ul class="releases" aria-label="Releases">
+ {#each list as entry, index (entry.release)}
+ {@const shot = wb.picture(entry.release)}
+ <li>
+ <button
+ class="row mono"
+ class:on={index === onScreen}
+ onclick={() => wb.pick(entry.release)}
+ title={shot?.source ? `Taken by ${shot.source}` : undefined}
+ >
+ <span>{entry.date}</span>
+ {#if shot?.acquired}<span class="taken">taken {shot.acquired}</span>{/if}
+ </button>
+ </li>
+ {/each}
+ </ul>
- <div class="menu-hint dim">
- Release dates are Esri's; “taken” and the pill under the chip date the pixels.
- </div>
+ <div class="menu-hint dim">
+ Release dates are Esri's; “taken” and the pill under the chip date the pixels.
+ </div>
+ {/if}
{/if}
</div>
{/if}
diff --git a/frontend/src/tools/satellite/WaybackPicker.test.js b/frontend/src/tools/satellite/WaybackPicker.test.js
index 3567c01..8a5aa0a 100644
--- a/frontend/src/tools/satellite/WaybackPicker.test.js
+++ b/frontend/src/tools/satellite/WaybackPicker.test.js
@@ -22,6 +22,7 @@ function props(wb = {}) {
changesBusy: false,
changesNote: '',
stale: false,
+ reading: false,
visible: [RELEASES[1], RELEASES[2]],
position: 0,
toggleMenu: vi.fn(),
@@ -62,6 +63,20 @@ describe('the picker', () => {
expect(body).not.toMatch(/<button[^>]*disabled[^>]*aria-label="Older release"/);
});
+ it('offers nothing while this point’s first history is coming', () => {
+ // every release is not what "Changes here" was asked for, and a list about
+ // to shrink to a quarter of itself is one the analyst reads and acts on
+ const { body } = render(
+ WaybackPicker,
+ { props: props({ reading: true, changesBusy: true, changes: null, visible: RELEASES }) }
+ );
+ expect(body).toContain("Reading this point's history");
+ expect(body).not.toContain('type="range"');
+ expect(body).not.toContain('2014-02-20');
+ // …and the way out of the wait stays on offer
+ expect(body).toContain('Every release');
+ });
+
it('says a history is being read, has failed, or belongs to somewhere else', () => {
expect(render(WaybackPicker, { props: props({ changesBusy: true }) }).body).toContain(
"Reading this point's history"
diff --git a/frontend/src/tools/satellite/state/addedLayers.svelte.js b/frontend/src/tools/satellite/state/addedLayers.svelte.js
new file mode 100644
index 0000000..9637e84
--- /dev/null
+++ b/frontend/src/tools/satellite/state/addedLayers.svelte.js
@@ -0,0 +1,313 @@
+/**
+ * The layers the analyst added to this case, as the Map's panel works them.
+ *
+ * Holds the list, the acts that change it, and the one thing that decides
+ * whether this feature is honest about the network: **nothing here fetches on
+ * mount.** Opening a case reads the layers already on disk, and only then, only
+ * for subscriptions that are enabled and asked to, does `refreshOnOpen` reach
+ * out. A disabled layer never costs a request, and a case opened offline draws
+ * every snapshot it holds.
+ *
+ * The parsed GeoJSON is kept here rather than in the overlay component so that
+ * switching a layer off and on again does not re-read a file the browser already
+ * has, and so the count on the row and the marks on the map come from one copy.
+ *
+ * @param {object} deps
+ * @param {object} deps.api the app's fetch wrapper
+ * @param {(message: string, kind?: string, ms?: number) => void} deps.notify
+ * @param {() => Promise<object>} deps.ensureCase the case to add into, made if needed
+ * @param {() => Promise<any>} deps.reloadCase
+ */
+import {
+ drawable,
+ refreshable,
+ searchFeatures,
+ toggleCategory,
+} from '../../../lib/map/addedLayers.js';
+
+export function createAddedLayersState({ api, notify, ensureCase, reloadCase }) {
+ let rows = $state([]);
+ let open = $state(true);
+ let busy = $state(''); // the layer name an act is running on
+ let adding = $state(false); // the + dialog is up
+ let saving = $state(false); // …and it is reading a file or an address
+
+ /** name → the parsed collection, once something has asked to draw it. */
+ const drawings = new Map();
+ /** …and which of them are in hand, as state, because a search box already open
+ * has to fill the moment its layer's features land. The collections
+ * themselves stay out of it: they run to a hundred thousand features and
+ * nothing reactive needs to look inside one. */
+ let held = $state(new Set());
+ /** The search result the map is being sent to, if any. Counted rather than
+ * timed, so picking the same result twice is twice. */
+ let picked = $state(null);
+ let picks = 0;
+ let loadedFor = null; // the case every row was read for
+
+ function reset() {
+ rows = [];
+ drawings.clear();
+ held = new Set();
+ picked = null;
+ }
+
+ /** Drop a layer's features, which is what a new snapshot and a removal both do. */
+ function forget(name) {
+ drawings.delete(name);
+ if (!held.has(name)) return;
+ const next = new Set(held);
+ next.delete(name);
+ held = next;
+ }
+
+ function replace(row) {
+ const index = rows.findIndex((entry) => entry.name === row.name);
+ if (index < 0) rows = [row, ...rows];
+ else rows = rows.map((entry) => (entry.name === row.name ? row : entry));
+ }
+
+ /**
+ * Read this case's layers. Disk only — the network boundary is `refreshOnOpen`.
+ *
+ * Returns the teardown that makes a response arriving after the case changed
+ * land nowhere, as the other panel indexes do.
+ */
+ function load(caseId) {
+ if (loadedFor !== caseId) {
+ loadedFor = caseId;
+ reset();
+ }
+ if (!caseId) return () => {};
+ let live = true;
+ api
+ .get(`/api/cases/${caseId}/map-layers`)
+ .then((list) => {
+ if (!live) return;
+ rows = Array.isArray(list) ? list : [];
+ refreshOnOpen(caseId);
+ })
+ .catch(() => {
+ if (live) rows = [];
+ });
+ return () => {
+ live = false;
+ };
+ }
+
+ /**
+ * Re-read the feeds a case open is allowed to re-read, and only those.
+ *
+ * One request per layer, all of them failing silently: a subscription that
+ * cannot be reached is not an error worth a toast on every case open — the row
+ * already says how old what it is drawing is.
+ */
+ async function refreshOnOpen(caseId) {
+ for (const layer of refreshable(rows)) {
+ try {
+ const row = await api.post(`/api/cases/${caseId}/map-layers/${layer.name}/refresh`);
+ if (loadedFor !== caseId) return;
+ if (row.sha256 !== layer.sha256) forget(row.name);
+ replace(row);
+ } catch {
+ /* the snapshot stays on the map, and the row says when it was last read */
+ }
+ }
+ }
+
+ /** The parsed collection for one layer, read once and kept. */
+ async function drawing(caseId, name) {
+ if (drawings.has(name)) return drawings.get(name);
+ const data = await api.get(`/api/cases/${caseId}/map-layers/${name}/data`);
+ drawings.set(name, data);
+ held = new Set(held).add(name);
+ return data;
+ }
+
+ async function act(name, run) {
+ busy = name;
+ try {
+ return await run();
+ } finally {
+ busy = '';
+ }
+ }
+
+ /**
+ * Both halves of the `+`, which differ only in what they post.
+ *
+ * A refusal is a toast and an open dialog, not a closed one: the reason the
+ * backend gave — a KMZ with no KML in it, a My Maps that was never shared — is
+ * something to act on, and closing the dialog would take the input away with it.
+ */
+ async function add(post, fallback) {
+ const kase = await ensureCase();
+ if (!kase) return null;
+ saving = true;
+ try {
+ const row = await post(kase.id);
+ replace(row);
+ adding = false;
+ await reloadCase();
+ notify(`${row.title} added`, 'ok');
+ return row;
+ } catch (error) {
+ notify(error?.message || fallback, 'error');
+ return null;
+ } finally {
+ saving = false;
+ }
+ }
+
+ /**
+ * `icons` is the analyst's own tick, and it is the only thing on this path
+ * that can reach out for a file: a KMZ carries its pictograms inside itself,
+ * but a KML points at somebody else's server, and following that is a request
+ * the dialog asks for rather than assumes.
+ */
+ function addFile(file, icons = false) {
+ const body = new FormData();
+ body.append('file', file);
+ body.append('icons', String(Boolean(icons)));
+ return add(
+ (caseId) => api.post(`/api/cases/${caseId}/map-layers/upload`, body),
+ 'That file could not be read'
+ );
+ }
+
+ function subscribe(url, icons = true) {
+ return add(
+ (caseId) => api.post(`/api/cases/${caseId}/map-layers`, { url, icons }),
+ 'That address could not be read'
+ );
+ }
+
+ async function patch(caseId, name, body) {
+ const row = await api.patch(`/api/cases/${caseId}/map-layers/${name}`, body);
+ replace(row);
+ return row;
+ }
+
+ return {
+ get rows() {
+ return rows;
+ },
+ get drawn() {
+ return drawable(rows);
+ },
+ get open() {
+ return open;
+ },
+ set open(value) {
+ open = value;
+ },
+ get busy() {
+ return busy;
+ },
+ get adding() {
+ return adding;
+ },
+ set adding(value) {
+ adding = value;
+ },
+ get saving() {
+ return saving;
+ },
+ /** The match the map is being sent to, read by the overlay and nothing else. */
+ get picked() {
+ return picked;
+ },
+ load,
+ drawing,
+ addFile,
+ subscribe,
+
+ /**
+ * The features of one layer that match what was typed.
+ *
+ * Memory and nothing else: the collection was fetched to draw the layer, so
+ * a keystroke costs no request — not to a server, not to this one. `ready`
+ * is what tells "nothing matches that" apart from "the features are still on
+ * their way", which are two different things to say to somebody searching.
+ */
+ search(layer, query) {
+ const name = layer?.name ?? '';
+ if (!held.has(name)) return { total: 0, results: [], ready: false };
+ return {
+ ...searchFeatures(drawings.get(name), query, {
+ categories: layer.categories,
+ hidden: layer.hidden,
+ }),
+ ready: true,
+ };
+ },
+
+ /**
+ * Send the map to one match, and open the card the source wrote for it.
+ *
+ * A match in a group the legend switched off is listed all the same, so
+ * picking it turns that group back on first: framing a feature that is not
+ * drawn would be the map travelling somewhere to show nothing.
+ */
+ async pick(caseId, layer, result) {
+ if (result?.hidden) {
+ await patch(caseId, layer.name, {
+ hidden: toggleCategory(layer, result.category),
+ }).catch(() => {});
+ }
+ picks += 1;
+ picked = { name: layer.name, index: result.index, at: picks };
+ },
+
+ /** The eye on the row. Off costs nothing and asks for nothing. */
+ toggle(caseId, layer) {
+ return patch(caseId, layer.name, { enabled: !layer.enabled }).catch(() => {});
+ },
+
+ /** One legend row, which hides exactly its own features. */
+ toggleCategory(caseId, layer, name) {
+ return patch(caseId, layer.name, { hidden: toggleCategory(layer, name) }).catch(
+ () => {}
+ );
+ },
+
+ /** The explicit press. The second of this feature's three network calls. */
+ refresh(caseId, layer) {
+ return act(layer.name, async () => {
+ try {
+ const row = await api.post(`/api/cases/${caseId}/map-layers/${layer.name}/refresh`);
+ if (row.sha256 !== layer.sha256) forget(row.name);
+ replace(row);
+ notify(
+ row.sha256 === layer.sha256 ? 'Unchanged since last read' : `${row.title} updated`,
+ 'ok'
+ );
+ } catch (error) {
+ notify(error?.message || 'That source could not be reached', 'error');
+ }
+ });
+ },
+
+ async remove(caseId, layer) {
+ return act(layer.name, async () => {
+ try {
+ await api.del(`/api/cases/${caseId}/map-layers/${layer.name}`);
+ forget(layer.name);
+ rows = rows.filter((entry) => entry.name !== layer.name);
+ await reloadCase();
+ } catch (error) {
+ notify(error?.message || 'That layer could not be removed', 'error');
+ }
+ });
+ },
+
+ /** What a hidden folder owes the analyst: where the bytes actually are. */
+ async reveal(caseId, layer) {
+ try {
+ await api.post(`/api/cases/${caseId}/map-layers/${layer.name}/reveal`);
+ } catch (error) {
+ notify(error?.message || 'That folder could not be opened', 'error');
+ }
+ },
+ };
+}
diff --git a/frontend/src/tools/satellite/state/addedLayers.svelte.test.js b/frontend/src/tools/satellite/state/addedLayers.svelte.test.js
new file mode 100644
index 0000000..13dd974
--- /dev/null
+++ b/frontend/src/tools/satellite/state/addedLayers.svelte.test.js
@@ -0,0 +1,422 @@
+// @vitest-environment happy-dom
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createAddedLayersState } from './addedLayers.svelte.js';
+
+/**
+ * The store that owns this feature's one network rule.
+ *
+ * Asserted **both ways**, because either half failing is a different failure: a
+ * case that will not open offline, or an app that quietly polls somebody else's
+ * server every time a tab is switched.
+ */
+
+const FILE_LAYER = {
+ name: 'Sightings',
+ title: 'Sightings',
+ source: { kind: 'file', name: 'sightings.kml' },
+ enabled: true,
+ hidden: [],
+ features: 3,
+ categories: [{ name: 'Checkpoints', count: 3, colour: '#f00' }],
+ sha256: 'aaa',
+};
+
+const followed = (over = {}) => ({
+ ...FILE_LAYER,
+ name: 'Roadblocks',
+ title: 'Roadblocks',
+ source: { kind: 'url', url: 'https://example.test/roadblocks.kml' },
+ sha256: 'bbb',
+ ...over,
+});
+
+let api;
+let calls;
+let notify;
+let reloadCase;
+let rows;
+let collection;
+
+function store() {
+ return createAddedLayersState({
+ api,
+ notify,
+ ensureCase: async () => ({ id: 'c1' }),
+ reloadCase,
+ });
+}
+
+/** Let the store's own promise chain settle — `load` is deliberately not awaited. */
+const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+beforeEach(() => {
+ calls = [];
+ rows = [FILE_LAYER];
+ collection = { type: 'FeatureCollection', features: [] };
+ notify = vi.fn();
+ reloadCase = vi.fn(async () => {});
+ api = {
+ get: vi.fn(async (path) => {
+ calls.push(['GET', path]);
+ if (path.endsWith('/data')) return collection;
+ return rows;
+ }),
+ post: vi.fn(async (path) => {
+ calls.push(['POST', path]);
+ if (path.endsWith('/refresh')) return { ...followed(), sha256: 'ccc' };
+ return followed();
+ }),
+ patch: vi.fn(async (path, body) => {
+ calls.push(['PATCH', path, body]);
+ return { ...rows[0], ...body };
+ }),
+ del: vi.fn(async (path) => calls.push(['DELETE', path])),
+ };
+});
+
+describe('opening a case', () => {
+ it('reads what is on disk and nothing else when every layer is a file', async () => {
+ const layers = store();
+ layers.load('c1');
+ await settle();
+
+ expect(calls).toEqual([['GET', '/api/cases/c1/map-layers']]);
+ expect(layers.rows).toEqual([FILE_LAYER]);
+ });
+
+ it('re-reads a followed map that is enabled and asked to be', async () => {
+ rows = [followed()];
+ const layers = store();
+ layers.load('c1');
+ await settle();
+
+ expect(calls).toEqual([
+ ['GET', '/api/cases/c1/map-layers'],
+ ['POST', '/api/cases/c1/map-layers/Roadblocks/refresh'],
+ ]);
+ });
+
+ it('leaves a disabled subscription alone — an off layer costs nothing', async () => {
+ rows = [followed({ enabled: false })];
+ const layers = store();
+ layers.load('c1');
+ await settle();
+
+ expect(calls).toEqual([['GET', '/api/cases/c1/map-layers']]);
+ });
+
+ it('leaves one alone that asked not to be read on open', async () => {
+ rows = [followed({ refresh: { on_open: false } })];
+ const layers = store();
+ layers.load('c1');
+ await settle();
+
+ expect(calls).toEqual([['GET', '/api/cases/c1/map-layers']]);
+ });
+
+ it('draws the last snapshot when the feed cannot be reached', async () => {
+ // a case opened offline is a case that still works
+ rows = [followed()];
+ api.post = vi.fn(async () => {
+ throw new Error('network down');
+ });
+ const layers = store();
+ layers.load('c1');
+ await settle();
+
+ expect(layers.drawn.map((row) => row.name)).toEqual(['Roadblocks']);
+ expect(notify).not.toHaveBeenCalled();
+ });
+});
+
+describe('drawing', () => {
+ it('reads a layer once and keeps it, however often it is switched', async () => {
+ const layers = store();
+ layers.load('c1');
+ await settle();
+
+ await layers.drawing('c1', 'Sightings');
+ await layers.drawing('c1', 'Sightings');
+
+ expect(calls.filter(([, path]) => path.endsWith('/data'))).toHaveLength(1);
+ });
+
+ it('re-reads it only when a refresh actually moved the bytes', async () => {
+ rows = [followed({ refresh: { on_open: false } })];
+ const layers = store();
+ layers.load('c1');
+ await settle();
+ await layers.drawing('c1', 'Roadblocks');
+ const reads = () => calls.filter(([, path]) => path.endsWith('/data')).length;
+
+ // same sha: the browser already holds exactly these features
+ api.post = vi.fn(async () => followed());
+ await layers.refresh('c1', layers.rows[0]);
+ await layers.drawing('c1', 'Roadblocks');
+ expect(reads()).toBe(1);
+
+ // a different sha is a different layer, and the cached copy is dropped
+ api.post = vi.fn(async () => followed({ sha256: 'ccc' }));
+ await layers.refresh('c1', layers.rows[0]);
+ await layers.drawing('c1', 'Roadblocks');
+ expect(reads()).toBe(2);
+ });
+
+ it('draws only what is enabled', async () => {
+ rows = [FILE_LAYER, followed({ enabled: false, refresh: { on_open: false } })];
+ const layers = store();
+ layers.load('c1');
+ await settle();
+
+ expect(layers.drawn.map((row) => row.name)).toEqual(['Sightings']);
+ });
+});
+
+describe('the acts on a row', () => {
+ it('switches a layer off without asking anyone for anything', async () => {
+ const layers = store();
+ layers.load('c1');
+ await settle();
+ calls.length = 0;
+
+ await layers.toggle('c1', layers.rows[0]);
+
+ expect(calls).toEqual([
+ ['PATCH', '/api/cases/c1/map-layers/Sightings', { enabled: false }],
+ ]);
+ });
+
+ it('hides one category by sending the whole list back', async () => {
+ const layers = store();
+ layers.load('c1');
+ await settle();
+ calls.length = 0;
+
+ await layers.toggleCategory('c1', layers.rows[0], 'Checkpoints');
+
+ expect(calls).toEqual([
+ ['PATCH', '/api/cases/c1/map-layers/Sightings', { hidden: ['Checkpoints'] }],
+ ]);
+ });
+
+ it('says so when a refresh found nothing new', async () => {
+ rows = [followed()];
+ api.post = vi.fn(async () => followed()); // same sha
+ const layers = store();
+ layers.load('c1');
+ await settle();
+ notify.mockClear();
+
+ await layers.refresh('c1', layers.rows[0]);
+
+ expect(notify).toHaveBeenCalledWith('Unchanged since last read', 'ok');
+ });
+
+ it('says why when a refresh failed, and keeps the row', async () => {
+ rows = [followed({ refresh: { on_open: false } })];
+ const layers = store();
+ layers.load('c1');
+ await settle();
+ api.post = vi.fn(async () => {
+ throw new Error('that source answered 503');
+ });
+
+ await layers.refresh('c1', layers.rows[0]);
+
+ expect(notify).toHaveBeenCalledWith('that source answered 503', 'error');
+ expect(layers.rows).toHaveLength(1);
+ });
+
+ it('takes a removed layer off the list and out of what is drawn', async () => {
+ const layers = store();
+ layers.load('c1');
+ await settle();
+
+ await layers.remove('c1', layers.rows[0]);
+
+ expect(calls).toContainEqual(['DELETE', '/api/cases/c1/map-layers/Sightings']);
+ expect(layers.rows).toEqual([]);
+ expect(layers.drawn).toEqual([]);
+ });
+});
+
+describe('adding', () => {
+ it('posts a file as multipart and closes the dialog on success', async () => {
+ const layers = store();
+ layers.adding = true;
+
+ await layers.addFile(new File(['{}'], 'x.geojson'));
+
+ expect(api.post).toHaveBeenCalledWith(
+ '/api/cases/c1/map-layers/upload',
+ expect.any(FormData)
+ );
+ expect(layers.adding).toBe(false);
+ expect(layers.rows).toHaveLength(1);
+ });
+
+ it('leaves the dialog open when the source was refused, with the reason', async () => {
+ // the backend's sentence is something to act on, and closing the dialog
+ // would take the input away with it
+ api.post = vi.fn(async () => {
+ throw new Error('this KMZ holds no KML file');
+ });
+ const layers = store();
+ layers.adding = true;
+
+ await layers.addFile(new File(['x'], 'x.kmz'));
+
+ expect(notify).toHaveBeenCalledWith('this KMZ holds no KML file', 'error');
+ expect(layers.adding).toBe(true);
+ expect(layers.rows).toEqual([]);
+ });
+
+ it('subscribes to a pasted address', async () => {
+ const layers = store();
+
+ await layers.subscribe('https://example.test/roadblocks.kml');
+
+ expect(api.post).toHaveBeenCalledWith('/api/cases/c1/map-layers', {
+ url: 'https://example.test/roadblocks.kml',
+ // on for an address, because following one already reaches the network
+ icons: true,
+ });
+ });
+
+ it('leaves the source icons off for a file unless they were asked for', async () => {
+ const layers = store();
+
+ await layers.addFile(new File(['x'], 'x.kmz'));
+ const [, sent] = api.post.mock.calls[0];
+
+ expect(sent.get('icons')).toBe('false');
+ });
+
+ it('asks for them when the dialog says so', async () => {
+ const layers = store();
+
+ await layers.addFile(new File(['x'], 'x.kmz'), true);
+ const [, sent] = api.post.mock.calls[0];
+
+ expect(sent.get('icons')).toBe('true');
+ });
+});
+
+describe('switching case', () => {
+ it('drops the previous case, rather than drawing its layers over the new one', async () => {
+ const layers = store();
+ layers.load('c1');
+ await settle();
+ expect(layers.rows).toHaveLength(1);
+
+ rows = [];
+ layers.load('c2');
+ expect(layers.rows).toEqual([]);
+ });
+});
+
+/**
+ * Searching a layer's features, which is this feature's second network rule and
+ * the easy one to get wrong: the collection is already in hand, so a keystroke
+ * must cost nothing — not a remote request, not a local one.
+ */
+describe('finding a pin', () => {
+ const GATES = {
+ type: 'FeatureCollection',
+ features: [
+ {
+ type: 'Feature',
+ geometry: { type: 'Point', coordinates: [2, 48] },
+ properties: { name: 'North gate', category: 'Checkpoints', colour: '', index: 0 },
+ },
+ {
+ type: 'Feature',
+ geometry: { type: 'Point', coordinates: [3, 49] },
+ properties: { name: 'Warehouse', category: 'Damage', colour: '', index: 1 },
+ },
+ ],
+ };
+
+ it('has nothing to search until the features are in hand, and says so', async () => {
+ collection = GATES;
+ const layers = store();
+ layers.load('c1');
+ await settle();
+
+ // not "no match": the layer has not been read yet, which is a different
+ // thing to tell somebody who is typing
+ expect(layers.search(FILE_LAYER, 'gate')).toEqual({ total: 0, results: [], ready: false });
+
+ await layers.drawing('c1', 'Sightings');
+
+ expect(layers.search(FILE_LAYER, 'gate').ready).toBe(true);
+ });
+
+ it('costs no request at all, however much is typed', async () => {
+ collection = GATES;
+ const layers = store();
+ layers.load('c1');
+ await settle();
+ await layers.drawing('c1', 'Sightings');
+ const reads = calls.length;
+
+ for (const query of ['g', 'ga', 'gat', 'gate', 'gate n']) layers.search(FILE_LAYER, query);
+
+ expect(calls).toHaveLength(reads);
+ expect(layers.search(FILE_LAYER, 'gate').results.map((hit) => hit.index)).toEqual([0]);
+ });
+
+ it('forgets the features when a refresh replaces the snapshot', async () => {
+ // the parsed copy is derived from bytes that just moved, so a search over it
+ // would be answering about a map nobody is drawing any more
+ rows = [followed()];
+ collection = GATES;
+ const layers = store();
+ layers.load('c1');
+ await settle();
+ await layers.drawing('c1', 'Roadblocks');
+
+ // a feed that had not moved: the features in hand are still the right ones
+ await layers.refresh('c1', layers.rows[0]);
+ expect(layers.search(layers.rows[0], 'gate').ready).toBe(true);
+
+ api.post = vi.fn(async () => ({ ...followed(), sha256: 'ddd' }));
+ await layers.refresh('c1', layers.rows[0]);
+
+ expect(layers.search(layers.rows[0], 'gate').ready).toBe(false);
+ });
+
+ it('names the match the map is to be sent to, and counts each picking', async () => {
+ const layers = store();
+ layers.load('c1');
+ await settle();
+
+ await layers.pick('c1', FILE_LAYER, { index: 4, category: 'Checkpoints', hidden: false });
+ expect(layers.picked).toEqual({ name: 'Sightings', index: 4, at: 1 });
+
+ await layers.pick('c1', FILE_LAYER, { index: 4, category: 'Checkpoints', hidden: false });
+ // picking the same match twice is twice, or the map would go once and
+ // ignore the second ask
+ expect(layers.picked.at).toBe(2);
+ expect(calls.filter(([verb]) => verb === 'PATCH')).toHaveLength(0);
+ });
+
+ it('turns a hidden group back on before sending the map to it', async () => {
+ const layers = store();
+ layers.load('c1');
+ await settle();
+
+ await layers.pick(
+ 'c1',
+ { ...FILE_LAYER, hidden: ['Damage'] },
+ { index: 9, category: 'Damage', hidden: true }
+ );
+
+ expect(calls).toContainEqual([
+ 'PATCH',
+ '/api/cases/c1/map-layers/Sightings',
+ { hidden: [] },
+ ]);
+ expect(layers.picked).toEqual({ name: 'Sightings', index: 9, at: 1 });
+ });
+});
diff --git a/frontend/src/tools/satellite/state/wayback.svelte.js b/frontend/src/tools/satellite/state/wayback.svelte.js
index e5890a5..57fbdc4 100644
--- a/frontend/src/tools/satellite/state/wayback.svelte.js
+++ b/frontend/src/tools/satellite/state/wayback.svelte.js
@@ -5,9 +5,13 @@
*
* - **The release list is read once**, the first time the basemap is shown or
* its picker opened, never on mount.
- * - **The change list is read while the picker is open**, for the tile under
- * the crosshair. A pan inside that tile has the same history and asks
- * nothing; a pan out of it marks the list stale until it is read again.
+ * - **The change list follows the map from the first time the picker is
+ * opened**, and not before: opening it is the analyst saying they are reading
+ * this place through time, and from then on a view that settles over another
+ * tile reads that tile's history, picker open or not. Gating it on the picker
+ * *staying* open was the bug: the map moved, the picker was shut, and it
+ * re-opened on the history of wherever the analyst had been before. A pan
+ * inside the same tile has the same history and asks nothing.
* - **A failed read is said, not hidden.** An empty change list means the point
* never changed; a failed one means we do not know, and the picker falls back
* to every release rather than claiming there is nothing to see.
@@ -32,6 +36,7 @@ export function createWaybackState({ api, place }) {
let listing = null; // the one in-flight read of the list
let release = $state(null); // null = the newest
let menuOpen = $state(false);
+ let watching = $state(false); // the picker has been opened: the history follows the map
let changesOnly = $state(true);
let changes = $state(null); // [release] for `changesFor`, null when unknown
let pictures = $state({}); // release → { acquired, source } for those changes
@@ -39,6 +44,7 @@ export function createWaybackState({ api, place }) {
let changesBusy = $state(false);
let changesNote = $state('');
let changesRequest = 0;
+ let asked = ''; // the tile whose history was last read, answered or refused
const changesCache = new Map();
const hereKey = () => {
@@ -71,6 +77,7 @@ export function createWaybackState({ api, place }) {
async function loadChanges() {
const key = hereKey();
+ asked = key;
if (changesCache.has(key)) {
keep(changesCache.get(key));
changesFor = key;
@@ -129,10 +136,28 @@ export function createWaybackState({ api, place }) {
get changesNote() {
return changesNote;
},
+ /** The analyst opened the history once, so it follows the map from here. */
+ get watching() {
+ return watching;
+ },
+ /** The tile the map is over. What a tool watches to keep the history here. */
+ get here() {
+ return hereKey();
+ },
/** The point moved out of the tile the change list describes. */
get stale() {
return Boolean(changesFor) && changesFor !== hereKey();
},
+ /**
+ * Narrowed to changes, with this tile's history still coming.
+ *
+ * The picker offers nothing rather than the whole release list: a list
+ * about to be replaced by a quarter of itself is one the analyst reads and
+ * acts on, and it is not what they asked for.
+ */
+ get reading() {
+ return changesOnly && changes === null && changesBusy;
+ },
/** What the provider id carries (`lib/wayback.js` `waybackId`). */
get variant() {
return { release };
@@ -145,7 +170,7 @@ export function createWaybackState({ api, place }) {
* the picker highlights, rather than by a date no row carries.
*/
get date() {
- if (release == null && changesOnly && changes?.length && !this.stale) {
+ if (release == null && changesOnly && changes?.length) {
return releaseDate(releases, changes[0]);
}
return releaseDate(releases, release);
@@ -154,9 +179,16 @@ export function createWaybackState({ api, place }) {
picture(number) {
return pictures[number] ?? null;
},
- /** The releases the picker offers. Every release until the changes are known. */
+ /**
+ * The releases the picker offers. Every release until the changes are known.
+ *
+ * A map that left the tile keeps the list it had while the next one is
+ * read: the walk takes seconds, and swapping four rows for two hundred
+ * under the cursor and back is worse than a list the hint already calls
+ * stale.
+ */
get visible() {
- return visibleReleases(releases, changes, changesOnly && !this.stale);
+ return visibleReleases(releases, changes, changesOnly);
},
get position() {
return positionOf(this.visible, releases, release);
@@ -165,16 +197,31 @@ export function createWaybackState({ api, place }) {
loadReleases,
loadChanges,
+ /**
+ * The map settled: read this tile's history unless it is the one we hold.
+ *
+ * A tile already answered costs nothing — the answer is kept for the
+ * session — and a tile Esri refused is not asked again until the analyst
+ * presses Refresh, so a service that is down is not hammered by panning.
+ */
+ follow() {
+ if (!watching || hereKey() === asked) return undefined;
+ return loadChanges();
+ },
+
toggleMenu() {
menuOpen = !menuOpen;
if (!menuOpen) return;
+ watching = true;
loadReleases();
loadChanges();
},
setChangesOnly(value) {
changesOnly = Boolean(value);
- if (changesOnly && !changes) loadChanges();
+ // …and a history of the tile the map has left is read again, not kept:
+ // asking for changes here is asking about here.
+ if (changesOnly && (!changes || this.stale)) loadChanges();
},
/** Show one release. The newest is stored as null so the id stays plain. */
diff --git a/frontend/src/tools/satellite/state/wayback.svelte.test.js b/frontend/src/tools/satellite/state/wayback.svelte.test.js
index 5400fcd..9c54a5f 100644
--- a/frontend/src/tools/satellite/state/wayback.svelte.test.js
+++ b/frontend/src/tools/satellite/state/wayback.svelte.test.js
@@ -68,14 +68,84 @@ describe('asking Esri', () => {
expect(get.mock.calls.filter(([path]) => path.includes('/changes'))).toHaveLength(1);
});
- it('marks the history stale once the map leaves its tile, and offers every release meanwhile', async () => {
+ it('marks the history stale once the map leaves its tile, and keeps the changes meanwhile', async () => {
const wb = store();
await wb.loadReleases();
await wb.loadChanges();
at = { lat: 48.85, lon: 2.29, zoom: 15 };
expect(wb.stale).toBe(true);
- // a history of somewhere else must not narrow what is offered here
- expect(wb.visible).toHaveLength(4);
+ // the walk takes seconds: the bar stays a bar of changes rather than
+ // flipping to every release and back
+ expect(wb.visible.map((entry) => entry.release)).toEqual([64776, 10]);
+ });
+
+ it('reads the history again when changes are re-asked for after the map moved', async () => {
+ const wb = store();
+ await wb.loadChanges();
+ at = { lat: 48.85, lon: 2.29, zoom: 15 };
+ wb.setChangesOnly(false);
+ wb.setChangesOnly(true);
+ await vi.waitFor(() => expect(wb.stale).toBe(false));
+ expect(get.mock.calls.filter(([path]) => path.includes('/changes'))).toHaveLength(2);
+ });
+});
+
+describe('following the map', () => {
+ it('asks nothing until the picker has been opened once', async () => {
+ const wb = store();
+ at = { lat: 48.85, lon: 2.29, zoom: 15 };
+ expect(wb.follow()).toBeUndefined();
+ expect(get).not.toHaveBeenCalled();
+ });
+
+ it('reads the new tile’s history once the picker has been opened, shut or not', async () => {
+ const wb = store();
+ wb.toggleMenu();
+ await vi.waitFor(() => expect(wb.changes).toEqual([64776, 10]));
+ wb.toggleMenu(); // shut again: the history still follows the map
+ expect(wb.menuOpen).toBe(false);
+ at = { lat: 48.85, lon: 2.29, zoom: 15 };
+ await wb.follow();
+ expect(get).toHaveBeenLastCalledWith(
+ '/api/satellite/wayback/changes?lat=48.85&lon=2.29&zoom=15'
+ );
+ expect(wb.stale).toBe(false);
+ });
+
+ it('asks once per tile, however often the map settles over it', async () => {
+ const wb = store();
+ wb.toggleMenu();
+ await vi.waitFor(() => expect(wb.changes).toEqual([64776, 10]));
+ const asked = get.mock.calls.filter(([path]) => path.includes('/changes')).length;
+ at = { lat: 50.4501, lon: 30.5101, zoom: 15 }; // a nudge inside the same tile
+ await wb.follow();
+ await wb.follow();
+ expect(get.mock.calls.filter(([path]) => path.includes('/changes'))).toHaveLength(asked);
+ });
+
+ it('leaves a tile Esri refused alone until Refresh is pressed', async () => {
+ get = vi.fn(async (path) => {
+ if (path.includes('/releases')) return { releases: RELEASES };
+ throw new Error('offline');
+ });
+ const wb = store();
+ wb.toggleMenu();
+ await vi.waitFor(() => expect(wb.changesNote).toContain('offline'));
+ const refused = get.mock.calls.filter(([path]) => path.includes('/changes')).length;
+ await wb.follow(); // panning must not hammer a service that is down
+ expect(get.mock.calls.filter(([path]) => path.includes('/changes'))).toHaveLength(refused);
+ await wb.loadChanges(); // …but the analyst can ask again
+ expect(get.mock.calls.filter(([path]) => path.includes('/changes'))).toHaveLength(refused + 1);
+ });
+
+ it('offers nothing while the first history of a point is coming', async () => {
+ const wb = store();
+ await wb.loadReleases();
+ expect(wb.reading).toBe(false);
+ const coming = wb.loadChanges();
+ expect(wb.reading).toBe(true);
+ await coming;
+ expect(wb.reading).toBe(false);
});
});
diff --git a/pyproject.toml b/pyproject.toml
index c0ce3b0..ab71e61 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -65,6 +65,12 @@ dependencies = [
# Windows, which has no system tz database.
"tzfpy>=1.3,<2",
"tzdata>=2024.1,<2027",
+ # Reading a KML, a KMZ or a GPX somebody sent (engine/maplayers.py). Those
+ # are untrusted XML, and the stdlib parser expands entities: one file can
+ # read a local path through an external entity, or exhaust memory through a
+ # nested one. This is the small pure-Python answer — no build step, same
+ # parser in all three binaries — and it arrives through fpdf2 already.
+ "defusedxml>=0.7,<1",
# Whole-bundle AES-GCM encryption. Intel macOS lost its wheels in version 49
# and has had none since, so it stays under that line rather than building
# from source. The other release targets follow the current major.
diff --git a/src/azimut/api/compare.py b/src/azimut/api/compare.py
index 2e0e1d6..f3efdae 100644
--- a/src/azimut/api/compare.py
+++ b/src/azimut/api/compare.py
@@ -175,6 +175,26 @@ class CompareBlink(BaseModel):
interval: int = Field(default=800, ge=200, le=4000)
+class CompareFrame(BaseModel):
+ """What an export is cut to: two opposite corners of a ground rectangle.
+
+ Held on the ground like an annotation, so a comparison reopened on another
+ screen still exports the same roofs rather than the same pixels.
+ """
+
+ #: ``[lon, lat]`` pairs, in the order they were drawn.
+ points: list[tuple[float, float]] = Field(min_length=2, max_length=2)
+
+ @model_validator(mode="after")
+ def _ground(self) -> "CompareFrame":
+ for lon, lat in self.points:
+ if not (-180 <= lon <= 180 and -90 <= lat <= 90):
+ raise ValueError("frame corners must be WGS84 longitude and latitude")
+ if self.points[0] == self.points[1]:
+ raise ValueError("an export frame needs two distinct corners")
+ return self
+
+
class CompareSpec(BaseModel):
version: Literal[2] = 2
camera: CompareCamera
@@ -184,6 +204,8 @@ class CompareSpec(BaseModel):
blink: CompareBlink = Field(default_factory=CompareBlink)
change_assist: CompareChangeAssist = Field(default_factory=CompareChangeAssist)
annotations: list[CompareAnnotation] = Field(default_factory=list, max_length=200)
+ #: Absent or null when the export takes the whole view.
+ frame: CompareFrame | None = None
a: CompareSide
b: CompareSide
@@ -219,6 +241,8 @@ def _validated_spec(spec: CompareSpec) -> dict[str, Any]:
assist["classes"] = list(dict.fromkeys(assist["classes"]))
for mark in cleaned["annotations"]:
mark["points"] = [list(point) for point in mark["points"]]
+ if cleaned["frame"]:
+ cleaned["frame"]["points"] = [list(point) for point in cleaned["frame"]["points"]]
if cleaned["mode"] == "change":
reason = change_refusal(cleaned["a"], cleaned["b"], assist["method"])
if reason:
diff --git a/src/azimut/api/ingest.py b/src/azimut/api/ingest.py
index 19b47dc..01cd716 100644
--- a/src/azimut/api/ingest.py
+++ b/src/azimut/api/ingest.py
@@ -749,15 +749,11 @@ def mark_grid(body: GridMarksIn) -> dict[str, Any]:
HANDOFF_DIRS = ("media", "proofs")
#: Ceiling for one handed-over file. The extension reads it back a chunk at a
-#: time (``Range``, which ``FileResponse`` answers), so what either side holds is
-#: one chunk and never the file — the number is about what is worth carrying into
-#: someone else's page at all, not about the message. A reference window on a
-#: foreign map is meant to reach the same clip the Satellite tab opens, and that
-#: tab streams from disk with no ceiling of its own.
-#:
-#: The composer keeps a smaller one of its own (``MAX_COMPOSER_BYTES`` in
-#: ``extension/background.js``): a thread's attachments are pushed into the page
-#: whole, in one injected payload, so there the string really is the limit.
+#: time (``Range``, which ``FileResponse`` answers), so the base64 message is one
+#: chunk and never the file. The composer rebuilds those chunks as one browser
+#: ``File``; a reference window rebuilds them as a ``Blob``. The number is about
+#: what is worth carrying into someone else's page at all, not message size. The
+#: Satellite tab itself streams from disk and has no ceiling of its own.
MAX_HANDOFF_BYTES = 512 * 1024 * 1024
diff --git a/src/azimut/api/maplayers.py b/src/azimut/api/maplayers.py
new file mode 100644
index 0000000..47bd71d
--- /dev/null
+++ b/src/azimut/api/maplayers.py
@@ -0,0 +1,237 @@
+"""REST API for the layers an analyst adds to a case's map.
+
+Two ways in — a file opened from the computer, and a URL subscribed to — and one
+kind of thing out. Everything a layer is parsed from is read in Python
+(`engine/maplayers.py`): the browser gets JSON, never XML, never a zip, and never
+the remote host's address.
+
+**The network boundary is the part to keep honest.** Nothing here polls. A fetch
+happens when a subscription is created, when Refresh is pressed, and when a case
+is opened holding an enabled layer that asked to refresh on open — and that last
+one is a route the frontend calls deliberately, not something a mount does.
+Listing layers, drawing them and toggling a category all read the snapshot
+already on disk, offline included.
+
+The source's own icons ride on those same three acts and nowhere else. They are
+composed once, at the moment the analyst ticks the box, and served from the case
+folder from then on: the browser asks localhost for a PNG this app made, never
+Google for the one it pointed at.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Form, HTTPException, UploadFile
+from fastapi.responses import FileResponse, Response
+from pydantic import BaseModel, Field
+
+from .. import layout
+from ..engine import artifacts as artifact_engine
+from ..engine import maplayers as layer_engine
+from ..engine import reveal as reveal_engine
+from ..workspace import CaseError
+from .cases import delete_by_path, get_case
+
+router = APIRouter(prefix="/api/cases", tags=["map-layers"])
+
+#: A source file is read into memory to be parsed, so the upload is bounded by
+#: the same number the parser refuses at. One more than the limit is enough to
+#: know the limit was passed.
+MAX_UPLOAD = layer_engine.MAX_SOURCE_BYTES
+
+
+class SubscribeIn(BaseModel):
+ url: str = Field(min_length=1, max_length=4000)
+ title: str | None = Field(default=None, max_length=200)
+ #: Whether opening the case re-reads the feed. Off leaves a layer that only
+ #: moves when Refresh is pressed.
+ on_open: bool = True
+ #: Whether to compose the map's own pictograms. On by default here and off on
+ #: the upload: following a pasted address already reaches the network, and
+ #: opening a file off this machine does not.
+ icons: bool = True
+
+
+class UpdateIn(BaseModel):
+ enabled: bool | None = None
+ #: Category names the legend has switched off, which is the whole of the
+ #: filter: a hidden category is not drawn and not counted as visible.
+ hidden: list[str] | None = Field(default=None, max_length=2000)
+ on_open: bool | None = None
+ title: str | None = Field(default=None, max_length=200)
+
+
+def _refused(exc: layer_engine.LayerError) -> HTTPException:
+ """A source that will not draw, said in one sentence the panel can show."""
+ status = 502 if isinstance(exc, layer_engine.LayerFetchError) else 422
+ return HTTPException(status_code=status, detail=str(exc))
+
+
[email protected]("/{case_id}/map-layers")
+def list_layers(case_id: str) -> list[dict[str, Any]]:
+ """Every layer this case holds. Reads disk only — never the network."""
+ return layer_engine.listing(get_case(case_id))
+
+
[email protected]("/{case_id}/map-layers/upload")
+async def upload_layer(
+ case_id: str,
+ file: UploadFile,
+ title: str = Form(default="", max_length=200),
+ icons: bool = Form(default=False),
+) -> dict[str, Any]:
+ """A GeoJSON, KML, KMZ or GPX file opened as a layer of this case.
+
+ `icons` is the only thing on this route that can reach out, and only for a
+ file whose pictograms live at web addresses rather than inside it. Off unless
+ the analyst ticked it.
+ """
+ case = get_case(case_id)
+ data = await file.read(MAX_UPLOAD + 1)
+ try:
+ return layer_engine.add_file(
+ case,
+ data,
+ filename=file.filename or "layer",
+ title=title or None,
+ icons=icons,
+ )
+ except layer_engine.LayerError as exc:
+ raise _refused(exc) from exc
+ except CaseError as exc:
+ raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
[email protected]("/{case_id}/map-layers")
+def subscribe_layer(case_id: str, body: SubscribeIn) -> dict[str, Any]:
+ """Follow a public map: a My Maps share link, or any KML/GeoJSON URL.
+
+ The first of this feature's three network calls, and the one the analyst
+ started by pasting an address.
+ """
+ case = get_case(case_id)
+ try:
+ return layer_engine.subscribe(
+ case, body.url, title=body.title, on_open=body.on_open, icons=body.icons
+ )
+ except layer_engine.LayerError as exc:
+ raise _refused(exc) from exc
+ except CaseError as exc:
+ raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
[email protected]("/{case_id}/map-layers/{name}/refresh")
+def refresh_layer(case_id: str, name: str) -> dict[str, Any]:
+ """Read the feed again. The snapshot is replaced only if the bytes moved."""
+ case = get_case(case_id)
+ try:
+ return layer_engine.refresh(case, _stem(name))
+ except layer_engine.LayerError as exc:
+ raise _refused(exc) from exc
+
+
[email protected]("/{case_id}/map-layers/{name}")
+def read_layer(case_id: str, name: str) -> dict[str, Any]:
+ try:
+ return layer_engine.read(get_case(case_id), _stem(name))
+ except layer_engine.LayerError as exc:
+ raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+
[email protected]("/{case_id}/map-layers/{name}/data")
+def layer_data(case_id: str, name: str) -> FileResponse:
+ """The parsed GeoJSON the map draws, rebuilt from the snapshot if need be."""
+ case = get_case(case_id)
+ try:
+ path = layer_engine.drawing(case, _stem(name))
+ except layer_engine.LayerError as exc:
+ raise HTTPException(status_code=404, detail=str(exc)) from exc
+ return FileResponse(path, media_type="application/geo+json")
+
+
[email protected]("/{case_id}/map-layers/{name}/icons/{key}")
+def layer_icon(case_id: str, name: str, key: str) -> Response:
+ """One of the source's own pictograms, as the PNG this app composed for it.
+
+ Reads a zip in the case folder and nothing else — the address the source gave
+ was followed once, when the layer was added, and never from here. Cached hard
+ because the key is a content hash: a different icon is a different URL.
+ """
+ case = get_case(case_id)
+ try:
+ png = layer_engine.icon(case, _stem(name), key)
+ except layer_engine.LayerError as exc:
+ raise HTTPException(status_code=404, detail=str(exc)) from exc
+ except CaseError as exc:
+ raise HTTPException(status_code=403, detail=str(exc)) from exc
+ return Response(
+ content=png,
+ media_type="image/png",
+ headers={"Cache-Control": "public, max-age=31536000, immutable"},
+ )
+
+
[email protected]("/{case_id}/map-layers/{name}")
+def update_layer(case_id: str, name: str, body: UpdateIn) -> dict[str, Any]:
+ """The switch, the legend and the refresh policy. Touches no network."""
+ case = get_case(case_id)
+ try:
+ return layer_engine.update(
+ case,
+ _stem(name),
+ enabled=body.enabled,
+ hidden=body.hidden,
+ on_open=body.on_open,
+ title=body.title,
+ )
+ except layer_engine.LayerError as exc:
+ raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+
[email protected]("/{case_id}/map-layers/{name}/reveal")
+def reveal_layer(case_id: str, name: str) -> dict[str, str]:
+ """Show the saved copy in the file manager.
+
+ What a hidden folder owes the analyst: the bytes are theirs, and the row is
+ the only place that says where they are.
+ """
+ case = get_case(case_id)
+ stem = _stem(name)
+ try:
+ layer_engine.read(case, stem)
+ target = case.resolve_inside(layout.layer_snapshot_rel(stem))
+ except layer_engine.LayerError as exc:
+ raise HTTPException(status_code=404, detail=str(exc)) from exc
+ except CaseError as exc:
+ raise HTTPException(status_code=403, detail=str(exc)) from exc
+ try:
+ reveal_engine.reveal(target)
+ except reveal_engine.RevealError as exc:
+ raise HTTPException(status_code=422, detail=str(exc)) from exc
+ return {"path": str(target)}
+
+
[email protected]("/{case_id}/map-layers/{name}")
+def delete_layer(case_id: str, name: str) -> dict[str, Any]:
+ """Through the chokepoint, so the layer goes to the Trash like everything else."""
+ case = get_case(case_id)
+ rel = layout.layer_spec_rel(_stem(name))
+ try:
+ case.resolve_inside(rel)
+ except CaseError as exc:
+ raise HTTPException(status_code=403, detail=str(exc)) from exc
+ result = delete_by_path(case, rel)
+ if not result["deleted"]: # never filed as an entity: drop the files anyway
+ artifact_engine.delete(case, {"type": layer_engine.ENTITY_TYPE, "attrs": {"spec": rel}})
+ return result
+
+
+def _stem(name: str) -> str:
+ """The name a save made, asked for the way the save named it.
+
+ Mirrors `api/inspect.delete_session`: the client sends the visible name and
+ the file is found by running it through the same rule that wrote it, rather
+ than by trusting the string as a path.
+ """
+ return layout.slugify(name, "Layer")
diff --git a/src/azimut/config.py b/src/azimut/config.py
index 3e2a161..2bc067c 100644
--- a/src/azimut/config.py
+++ b/src/azimut/config.py
@@ -33,6 +33,7 @@ import re
import sys
import tempfile
import threading
+import time
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Callable
@@ -259,7 +260,7 @@ def write_pointer(root: Path) -> None:
handle.flush()
os.fsync(handle.fileno())
_restrict(tmp_path, 0o600)
- os.replace(tmp_path, path)
+ _replace(tmp_path, path)
_restrict(path, 0o600)
finally:
tmp_path.unlink(missing_ok=True)
@@ -472,6 +473,23 @@ def ensure_workspace() -> None:
save_settings(migrate_settings(raw))
+def _replace(src: Path, dst: Path) -> None:
+ """``os.replace`` that waits out a scanner holding the fresh file.
+
+ On Windows a virus scanner or the search indexer can open a file the moment
+ it is written, and a rename onto it fails with access denied until they let
+ go, a few milliseconds later. POSIX never refuses, so the loop is a no-op there.
+ """
+ for attempt in range(20):
+ try:
+ os.replace(src, dst)
+ return
+ except PermissionError:
+ if attempt == 19:
+ raise
+ time.sleep(0.01)
+
+
def _restrict(path: Path, mode: int) -> None:
"""chmod, ignoring platforms/filesystems that don't support it."""
try:
@@ -700,7 +718,7 @@ def save_settings(settings: dict[str, Any]) -> None:
handle.flush()
os.fsync(handle.fileno())
_restrict(tmp_path, 0o600)
- os.replace(tmp_path, path)
+ _replace(tmp_path, path)
# Holds the user's API keys and pairing token — owner-read/write only.
_restrict(path, 0o600)
finally:
@@ -812,7 +830,7 @@ def save_templates(templates: dict[str, Any]) -> None:
handle.flush()
os.fsync(handle.fileno())
_restrict(tmp_path, 0o600)
- os.replace(tmp_path, path)
+ _replace(tmp_path, path)
_restrict(path, 0o600)
finally:
tmp_path.unlink(missing_ok=True)
diff --git a/src/azimut/engine/analyzers.py b/src/azimut/engine/analyzers.py
index 3d9d5ba..db1edb9 100644
--- a/src/azimut/engine/analyzers.py
+++ b/src/azimut/engine/analyzers.py
@@ -118,6 +118,12 @@ VESSEL_EXCESS = 0.01
# Non-water this big is land, and a candidate touching it is a coastline or an
# island. The largest ship in the calibration scenes was 1.3 ha of non-water.
LAND_M2 = 50_000
+# How far below zero the water index may sit and the classification still be
+# believed when it says water, as the byte the product carries. Glint drags the
+# index onto zero without crossing this: over the Bab-el-Mandeb 99% of the sea
+# stayed above it. Dry ground is well under — bare sand reads about -0.2 and
+# vegetation -0.8 — so ground the classification mistakes for water stays land.
+WATER_INDEX_FLOOR = 108 # NDWI -0.15
# --- Hotspots ----------------------------------------------------------------
# Below this short-wave reflectance there is no fire to discuss, whatever the
@@ -606,7 +612,18 @@ def _vessels(product: Any, inside: Any, blocked: Any, metres: float,
nir = product[:, :, 0].astype(np.float64)
swir = product[:, :, 1].astype(np.float64)
data = product[:, :, 0] > 0
- wet = product[:, :, 2] > 127
+ # NDWI alone cannot be asked what is sea. Sun glint adds the same
+ # reflectance to every band, so over the Bab-el-Mandeb in September it put
+ # near-infrared at 0.075 and left the index sitting on zero: two thirds of
+ # open water read as dry, the sea became one component of "land", and the
+ # sweep returned nothing. The classification is the second opinion, and it
+ # called that whole strait water. It is believed where the index is merely
+ # weak, never where the index plainly says dry ground: Sen2Cor calls deep
+ # shadow and dark ground water, and taking its word there would put vessel
+ # candidates on land.
+ index = product[:, :, 2]
+ wet = (index > 127) | (((product[:, :, 3] & 15) == SCL_WATER)
+ & (index > WATER_INDEX_FLOOR))
water = wet & data & ~blocked
# Land is non-water in bulk. A hull is non-water too, but a small one.
land = components_over(data & ~wet, metres * metres, LAND_M2)
@@ -665,7 +682,7 @@ def _changes(before: Any, after: Any, valid: Any) -> tuple[Any, Any]:
return stacked, stacked.mean(-1)
-def _spots(before: Any, after: Any, metres: float, threshold: float,
+def _spots(before: Any, after: Any, valid: Any, metres: float, threshold: float,
options: Parameters) -> tuple[Any, Any, Any]:
"""Change against the change around it, and whether the surroundings held.
@@ -673,6 +690,11 @@ def _spots(before: Any, after: Any, metres: float, threshold: float,
hole wide enough to hold the target: a median box the size of the target
takes the target itself for background, and a 90 m mark in the Yemeni desert
then measured 3.5% where it had really moved 7%.
+
+ Only pixels the sweep can measure feed that ring. Where a granule ends or a
+ cloud sits, one date has ground and the other has nothing, and letting that
+ difference into the background raised every neighbour it reached: a quiet
+ tile cut in half by a granule edge produced a candidate the size of the cut.
"""
import cv2
import numpy as np
@@ -682,17 +704,17 @@ def _spots(before: Any, after: Any, metres: float, threshold: float,
guard = odd(SPOT_GUARD * largest, 5, 41)
ring = odd(SPOT_RING * largest, guard + 4, 81)
wide = odd(4 * largest, 15, 61)
- everywhere = np.ones(before.shape[:2], bool)
residual, moved = [], []
for old, new in zip(_reflectance(before), _reflectance(after)):
delta = (new - old).astype(np.float64)
- mean, _, share = ring_statistics(delta, everywhere, ring, guard)
+ mean, _, share = ring_statistics(delta, valid, ring, guard)
residual.append(np.where(share > 0, delta - mean, 0.0))
# The passes' overall shift in light is not the neighbourhood changing.
- shift = float(np.median(delta))
+ shift = float(np.median(delta[valid])) if valid.any() else 0.0
moved.append(delta - max(-MAX_SHIFT, min(MAX_SHIFT, shift)))
spot = np.stack(residual, -1)
- changed = (np.sqrt((np.stack(moved, -1) ** 2).mean(-1)) >= threshold * GROW).astype(np.float32)
+ changed = ((np.sqrt((np.stack(moved, -1) ** 2).mean(-1)) >= threshold * GROW)
+ & valid).astype(np.float32)
share = cv2.blur(changed, (wide, wide))
return np.sqrt((spot ** 2).mean(-1)), spot.mean(-1), share < SPOT_SHARE
@@ -752,7 +774,7 @@ def detect(pictures: tuple[Any, Any], products: tuple[Any, Any], mask: Any, body
# a new roof on sand.
threshold = _scale(options.sensitivity, 0.02, 0.2)
if method == "spots":
- stat, signed, state = _spots(before, after, metres, threshold, options)
+ stat, signed, state = _spots(before, after, valid, metres, threshold, options)
measures = {"signed": (signed * 100, "mean")}
else:
deltas, signed = _changes(before, after, valid)
diff --git a/src/azimut/engine/artifacts.py b/src/azimut/engine/artifacts.py
index 11e718d..5d0407a 100644
--- a/src/azimut/engine/artifacts.py
+++ b/src/azimut/engine/artifacts.py
@@ -30,6 +30,11 @@ from typing import TYPE_CHECKING, Any, ClassVar
from .. import layout
from ..workspace import CaseError
from . import media as media_engine
+from .thumbnails import THUMB_DIR
+
+#: Where the one shared cache lives, so `_drop_cache` can tell it from a cache
+#: derived from a single artifact.
+_THUMBS = f"media/{THUMB_DIR}/"
if TYPE_CHECKING:
from ..workspace import Case
@@ -70,6 +75,20 @@ class Named(Companion):
return self.build(PurePosixPath(main).stem)
+@dataclass(frozen=True)
+class Derived(Named):
+ """A companion the tool rebuilds from one that travels.
+
+ A map layer's parsed GeoJSON is the case: the snapshot beside it is the
+ bytes as received, and parsing them again is the whole of what it takes to
+ get this file back. So it is dropped on delete and left out of the bundle,
+ and every reader has to be able to rebuild it — which is what keeps the
+ snapshot, not this, the thing the case actually holds.
+ """
+
+ travels: ClassVar[bool] = False
+
+
@dataclass(frozen=True)
class SharedThumb(Companion):
"""The cached thumbnail a media's sidecar records.
@@ -119,6 +138,18 @@ KINDS: dict[str, Kind] = {
"analysis-run": Kind(path_attr="spec", companions=(Named(layout.analysis_assets_rel),)),
"note": Kind(path_attr="path"),
"sheet": Kind(path_attr="path", companions=(Named(layout.sheet_meta_rel),)),
+ # A layer the analyst added: its settings, the bytes it was built from, the
+ # source's own pictograms, and the parsed copy the map draws. The icons
+ # travel where the parsed copy does not — a My Maps' came off Google's
+ # servers, so a case restored offline could not rebuild them.
+ "map-layer": Kind(
+ path_attr="spec",
+ companions=(
+ Named(layout.layer_snapshot_rel),
+ Named(layout.layer_icons_rel),
+ Derived(layout.layer_cache_rel),
+ ),
+ ),
}
#: Types with no intrinsic main artifact, and why. Supported entities can still
@@ -259,7 +290,13 @@ def caches(case: "Case", entity: dict[str, Any]) -> list[str]:
def _drop_cache(case: "Case", rel: str) -> None:
- if any(item.get("thumbnail") == rel for item in case.list_media_items()):
+ # Only a thumbnail can belong to more than one entity, because only a
+ # thumbnail is content-addressed. A cache derived from one artifact — a map
+ # layer's parsed GeoJSON — goes with it, and asking the media index about it
+ # would be a listing walked for a question it cannot answer.
+ if rel.startswith(_THUMBS) and any(
+ item.get("thumbnail") == rel for item in case.list_media_items()
+ ):
return # another media still shows this thumbnail
path = _resolve(case, rel)
if path is not None:
diff --git a/src/azimut/engine/bundles.py b/src/azimut/engine/bundles.py
index 6962dae..c106c34 100644
--- a/src/azimut/engine/bundles.py
+++ b/src/azimut/engine/bundles.py
@@ -81,9 +81,14 @@ BUNDLED_ROOTS = frozenset(
#: exported. Format 2 never uses these, so this set dies with format 1.
IMPORTABLE_ROOTS = BUNDLED_ROOTS | {"case.db", "exports", "inspect", "search"}
NOT_BUNDLED = {
- ".trash": "deleted artifacts do not travel",
+ layout.TRASH_DIR: "deleted artifacts do not travel",
"media/.thumbs": "content-addressed thumbnails are rebuilt",
"media/.dl": "in-progress downloads belong to this machine",
+ # The snapshot beside it is what the case holds; this is one parse away from
+ # it, and an import rebuilds it the first time the layer is drawn.
+ f"{layout.LAYERS_DIR}/{layout.LAYER_CACHE_DIR}": (
+ "a map layer's parsed copy is rebuilt from its snapshot"
+ ),
}
#: Extensions whose bytes are already compressed. Deflating them burns CPU on
@@ -299,11 +304,9 @@ def _require_export_space(target: Path, total_size: int) -> None:
def _included(rel: str) -> bool:
- if rel == ".trash" or rel.startswith(".trash/"):
+ if rel == layout.TRASH_DIR or rel.startswith(layout.TRASH_DIR + "/"):
return False
- if rel in {"media/.thumbs", "media/.dl"}:
- return False
- if rel.startswith("media/.thumbs/") or rel.startswith("media/.dl/"):
+ if any(rel == left or rel.startswith(left + "/") for left in NOT_BUNDLED):
return False
return PurePosixPath(rel).parts[0] in BUNDLED_ROOTS
diff --git a/src/azimut/engine/entities.py b/src/azimut/engine/entities.py
index 4c536b7..3ce71e3 100644
--- a/src/azimut/engine/entities.py
+++ b/src/azimut/engine/entities.py
@@ -565,6 +565,14 @@ ENTITY_TYPES: tuple[EntityType, ...] = (
hint="an analyzer, its areas and a date rule, rerun on demand"),
EntityType("analysis-run", "Analysis run", DOCUMENT, "changes", ANNEX,
hint="candidate detections with frozen inputs and review decisions"),
+ # Somebody else's map, drawn over this one. `ANNEX` for the reason a sheet is
+ # one: it is consulted, and no path through the case runs across it. It is
+ # deliberately not an attestation — an attestation folds into the edge that
+ # carries its provenance, and a layer nothing links to would fold into
+ # nothing. Nothing in it enters the graph: a feature drawn here is the
+ # source's claim, not the case's.
+ EntityType("map-layer", "Map layer", DOCUMENT, "compass", ANNEX,
+ hint="a map file or feed the analyst added, drawn but never adopted"),
# The page a claim rests on. `url` and `fetched_at` are written by whatever
# filed it — the extension is on the page, so the server stamps the moment it
# was seen — and are not declared here: a declared attr is a field an analyst
diff --git a/src/azimut/engine/maplayers.py b/src/azimut/engine/maplayers.py
new file mode 100644
index 0000000..e5b0bd7
--- /dev/null
+++ b/src/azimut/engine/maplayers.py
@@ -0,0 +1,1953 @@
+"""Reading a map file somebody else made, into something the map can draw.
+
+Three formats arrive in an analyst's inbox — GeoJSON, KML and its zipped form
+KMZ, and GPX off a handset — and one shape comes out: a GeoJSON
+FeatureCollection whose every feature carries the four things a foreign layer is
+worth drawing for.
+
+ name what the source calls this feature
+ description what the source says about it, as plain text
+ category which group it belongs to, and therefore its legend row
+ colour what the source painted it, honoured rather than replaced
+ icon which of the source's own pictograms it asked for, if any
+
+**The browser never sees the original.** KML is untrusted XML and KMZ is an
+untrusted zip, so both are read here, bounded here, and handed on as JSON the
+frontend can parse with `JSON.parse` and nothing else. That is also what keeps
+one parser rather than one per format: `parse` sniffs, dispatches, and every
+path returns through `_collection`.
+
+Where a category comes from, because the legend is the filter and a source
+rarely states one outright:
+
+- **KML/KMZ** — the enclosing `<Folder>`. That is how a My Maps is built (its
+ layers *are* folders), and how anyone organising a KML by hand does it.
+ Nested folders join with a slash; a Placemark under no folder falls back to
+ the document's own name.
+- **GPX** — what the element is: a waypoint, a track or a route.
+- **GeoJSON** — the file is one category, named after itself. A plain
+ FeatureCollection states no grouping, and inventing one out of whichever
+ property happens to look categorical would make the legend lie about the
+ source.
+
+**The browser never fetches an icon either.** A My Maps points its placemarks at
+Google-hosted PNGs, and letting the map follow those hrefs would be one
+third-party request per icon on every render, from the analyst's own browser. So
+the whole of it happens here, once, and only when the analyst ticked the box:
+each distinct icon is read (out of the KMZ, or off the web), decoded, tinted the
+colour its style asked for, resized, re-encoded as a PNG *this* process produced,
+and stored beside the snapshot. What the map loads is a file on localhost.
+
+A layer added without that box, or one whose icons could not be read, draws the
+app's own pictogram per geometry kind
+(`frontend/src/lib/map/addedLayer.js`) in the source's colour — which is most of
+the meaning either way, since creators group by colour far more than by icon.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import zipfile
+from collections import Counter
+from datetime import datetime, timedelta, timezone
+from io import BytesIO
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Iterator
+from urllib.parse import unquote
+
+import httpx
+from PIL import Image
+
+# The parser is `defusedxml`'s; `Element` is only the type its tree is made of,
+# and the stdlib is where that name lives.
+from defusedxml.ElementTree import ParseError, fromstring as parse_xml
+from xml.etree.ElementTree import Element
+
+from .. import layout
+from .tiles import USER_AGENT
+
+if TYPE_CHECKING: # pragma: no cover - typing only
+ from ..workspace import Case
+
+# -- what will not be read ---------------------------------------------------
+#
+# Every bound is here rather than at the call sites, and every one of them is
+# refused with a sentence rather than a truncation: a layer that silently drew
+# the first ten thousand of forty thousand features would be a map making a
+# claim about a place it had only partly read.
+
+#: The largest source file that will be read at all. A My Maps export of a few
+#: thousand placemarks is well under a megabyte; this leaves room for a national
+#: dataset somebody dropped in by mistake to be refused rather than swallowed.
+MAX_SOURCE_BYTES = 64 * 1024 * 1024
+
+#: Features in one layer. The GL renderer is comfortable far past this — the
+#: limit is about the case, not the frame rate: past this it is a dataset, and a
+#: dataset belongs behind a service rather than snapshotted into a case folder.
+MAX_FEATURES = 100_000
+
+#: Points in one geometry, which is what a traced coastline arrives as.
+MAX_GEOMETRY_POINTS = 500_000
+
+#: How deep the XML may nest. KML folders nest a handful deep in practice; this
+#: is the stack guard, not a modelling opinion.
+MAX_XML_DEPTH = 100
+
+#: KMZ is a zip, and a zip is three separate lies it can tell.
+MAX_ZIP_MEMBERS = 2_000
+MAX_UNCOMPRESSED_BYTES = 256 * 1024 * 1024
+MAX_COMPRESSION_RATIO = 200
+
+#: How much description survives. A My Maps description can hold a whole article
+#: with markup; the popup shows what the source says, not a web page.
+MAX_DESCRIPTION = 4_000
+MAX_NAME = 300
+#: The longest icon address that will be read at all.
+MAX_HREF = 2_000
+
+#: How many distinct pictograms one layer stores. A source declares one style per
+#: (icon, colour) pair its creator used, which is a couple of dozen for a busy My
+#: Maps. Past this the rest fall back to the app's own shapes rather than the
+#: layer being refused: the marks are the map, the icons are how it was dressed.
+MAX_ICONS = 64
+
+#: What one icon may weigh on the wire, and what a layer's icons may weigh
+#: together. Both are checked as the bytes arrive, because a server is free to
+#: lie about either.
+MAX_ICON_BYTES = 512 * 1024
+MAX_ICONS_BYTES = 8 * 1024 * 1024
+
+#: …and how many pixels one may decode to, which is the bound a small file that
+#: expands to a large bitmap has to answer.
+MAX_ICON_AREA = 4096 * 4096
+
+#: How much *painted* pictogram is stored, before the padding that centres its
+#: hotspot, and the floor and ceiling a source's own `<scale>` is held between.
+#: Every icon's ink coming out the same size is what lets the map draw them all
+#: at one `icon-size` and get one visual weight, rather than a 26px glyph beside
+#: a 64px square.
+ICON_SIDE = 64
+MIN_ICON_SIDE = 16
+MAX_ICON_SIDE = 128
+
+#: …and the widest the image around that ink may get. An icon is mostly its own
+#: transparency in a My Maps archive, and scaling the ink up scales the sheet it
+#: floats in with it.
+MAX_ICON_CANVAS = 256
+
+#: How much an icon's *fill* is allowed to say about its size.
+#:
+#: The bounding box is not the weight. A My Maps container set holds a square
+#: filled corner to corner beside a disc that paints 80% of its box and a star
+#: that paints under half of one — so sizing them all by the box draws the square
+#: with nearly twice the ink of the disc next to it, which is what "the squares
+#: look bigger" is. 0 is the box alone; 0.5 holds the painted area itself equal,
+#: which blows a sparse star out to half again its neighbours. This sits between.
+ICON_FILL_WEIGHT = 0.35
+
+#: …and the emptiest an icon is taken to be, so a thin arrow is not stretched
+#: across the map in the name of matching a disc's ink.
+MIN_ICON_FILL = 0.4
+
+#: How long one icon may take. Shorter than a feed's timeout on purpose: a slow
+#: icon host must not hold up a layer that is otherwise ready to draw.
+ICON_TIMEOUT = 15
+
+#: How much of the descriptor's hash names the stored image. Long enough that two
+#: different icons cannot collide into one, short enough to read in a URL.
+ICON_KEY_LENGTH = 16
+
+#: What a layer is named when the source names nothing.
+UNTITLED = "Untitled layer"
+#: …and the category a feature lands in when its source states no grouping.
+UNGROUPED = "Features"
+
+
+class LayerError(ValueError):
+ """A source that will not be drawn, with the reason an analyst reads."""
+
+
+# ---------------------------------------------------------------------------
+# Sniffing
+# ---------------------------------------------------------------------------
+
+#: The formats, and the extensions that suggest each. The suffix is a hint the
+#: bytes then confirm or overrule: files arrive renamed, and a `.geojson` that
+#: is really a KML should draw rather than fail on its first brace.
+FORMATS = ("geojson", "kml", "kmz", "gpx")
+
+_SUFFIXES = {
+ ".geojson": "geojson",
+ ".json": "geojson",
+ ".kml": "kml",
+ ".kmz": "kmz",
+ ".gpx": "gpx",
+}
+
+_ZIP_MAGIC = b"PK\x03\x04"
+
+
+def sniff(data: bytes, filename: str = "") -> str:
+ """Which of `FORMATS` these bytes are, whatever the name promised."""
+ if data[:4] == _ZIP_MAGIC:
+ return "kmz"
+ head = data[:4096].lstrip()
+ if head[:1] in (b"{", b"["):
+ return "geojson"
+ if head[:1] == b"<":
+ lowered = head.lower()
+ if b"<gpx" in lowered:
+ return "gpx"
+ if b"<kml" in lowered or b"<placemark" in lowered or b"<document" in lowered:
+ return "kml"
+ raise LayerError("this XML file is neither KML nor GPX")
+ suffix = _SUFFIXES.get(_suffix(filename))
+ if suffix:
+ return suffix
+ raise LayerError("unrecognised file: expected GeoJSON, KML, KMZ or GPX")
+
+
+def _suffix(filename: str) -> str:
+ name = str(filename or "").rsplit("/", 1)[-1].rsplit("\\", 1)[-1]
+ return f".{name.rsplit('.', 1)[-1].lower()}" if "." in name else ""
+
+
+# ---------------------------------------------------------------------------
+# The one entry point
+# ---------------------------------------------------------------------------
+
+
+def parse(data: bytes, *, filename: str = "", title: str = "") -> dict[str, Any]:
+ """Bytes as received → `{geojson, summary, icons}`, or `LayerError` with a reason.
+
+ Pure: it reads no file, reaches no network and writes nothing. A caller
+ stores the bytes it was given and can rebuild this result from them at any
+ time, which is what makes the parsed form a cache rather than a record.
+
+ `icons` is the *descriptions* of the pictograms the source asked for — an
+ address, a colour, a scale, an anchor — and never an image. Turning those
+ into pixels is what may reach out, so it lives in `icon_images` behind the
+ analyst's own tick, and this stays something that can be run on anything.
+ """
+ if not data:
+ raise LayerError("the file is empty")
+ if len(data) > MAX_SOURCE_BYTES:
+ raise LayerError(
+ f"the file is {_megabytes(len(data))} — the limit is "
+ f"{_megabytes(MAX_SOURCE_BYTES)}"
+ )
+ fmt = sniff(data, filename)
+ if fmt == "kmz":
+ data, inner = _kml_out_of_kmz(data)
+ if len(data) > MAX_SOURCE_BYTES:
+ raise LayerError(
+ f"the KML inside this KMZ is over {_megabytes(MAX_SOURCE_BYTES)}"
+ )
+ filename = inner or filename
+ fmt = "kml"
+ source_format = "kmz"
+ else:
+ source_format = fmt
+
+ icons: dict[str, dict[str, Any]] = {}
+ if fmt == "geojson":
+ features, name = _from_geojson(data, filename)
+ elif fmt == "kml":
+ features, name, icons = _from_kml(data)
+ else:
+ features, name = _from_gpx(data)
+
+ if not features:
+ raise LayerError("the file holds no points, lines or areas")
+ return _collection(
+ features, title=title or name or _stem(filename), fmt=source_format, icons=icons
+ )
+
+
+def digest(data: bytes) -> str:
+ """The snapshot's sha256, as a media's is — what says two fetches agreed."""
+ return hashlib.sha256(data).hexdigest()
+
+
+def _megabytes(size: int) -> str:
+ return f"{size / (1024 * 1024):.0f} MB"
+
+
+def _stem(filename: str) -> str:
+ name = str(filename or "").rsplit("/", 1)[-1].rsplit("\\", 1)[-1]
+ return name.rsplit(".", 1)[0] if "." in name else name
+
+
+# ---------------------------------------------------------------------------
+# The normalised shape
+# ---------------------------------------------------------------------------
+
+def _collection(
+ features: list[dict[str, Any]],
+ *,
+ title: str,
+ fmt: str,
+ icons: dict[str, dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+ """The FeatureCollection plus the summary the panel row is built from.
+
+ The summary is what the legend is: one row per category, with its colour,
+ its count and which pictograms it draws.
+ """
+ categories: dict[str, dict[str, Any]] = {}
+ for index, feature in enumerate(features):
+ properties = feature["properties"]
+ name = properties["category"]
+ entry = categories.setdefault(
+ name, {"name": name, "count": 0, "colours": Counter(), "kinds": set()}
+ )
+ entry["count"] += 1
+ entry["kinds"].add(_kind(feature["geometry"]))
+ if properties["colour"]:
+ entry["colours"][properties["colour"]] += 1
+ # A feature that drew the short straw in a contested spot is one whose
+ # neighbours arrived first. Sorting by file order at least makes that
+ # deterministic, which "whichever the engine placed" is not.
+ feature["id"] = index
+ properties["index"] = index
+
+ # Only the icons something actually draws: a KML commonly declares styles for
+ # shapes it no longer holds, and fetching one nothing asked for would be a
+ # request made on nobody's behalf.
+ used = {feature["properties"]["icon"] for feature in features}
+ ordered = [
+ {
+ "name": entry["name"],
+ "count": entry["count"],
+ # What this group is painted in the source, where a group is painted
+ # one colour at all: the commonest wins, and a group the source left
+ # unstyled comes back blank for the renderer's own palette.
+ "colour": _dominant(entry["colours"]),
+ "kinds": sorted(entry["kinds"]),
+ }
+ for entry in sorted(categories.values(), key=lambda e: (-e["count"], e["name"]))
+ ]
+ return {
+ "geojson": {"type": "FeatureCollection", "features": features},
+ "summary": {
+ "title": (title or UNTITLED)[:MAX_NAME],
+ "format": fmt,
+ "features": len(features),
+ "categories": ordered,
+ "bbox": _bbox(features),
+ },
+ "icons": {
+ key: descriptor for key, descriptor in (icons or {}).items() if key in used
+ },
+ }
+
+
+def _dominant(colours: "Counter[str]") -> str:
+ if not colours:
+ return ""
+ best = max(colours.values())
+ return sorted(colour for colour, count in colours.items() if count == best)[0]
+
+
+def _kind(geometry: dict[str, Any]) -> str:
+ """The pictogram family: a point, a line or an area. Nothing finer.
+
+ The renderer registers one image per kind, so this is the whole vocabulary
+ the legend and the GL layers share.
+ """
+ type_ = str(geometry.get("type") or "")
+ if "Point" in type_:
+ return "point"
+ if "Line" in type_:
+ return "line"
+ return "area"
+
+
+def _bbox(features: list[dict[str, Any]]) -> list[float] | None:
+ """Where the layer is, so adding one can move the map to it."""
+ west = south = float("inf")
+ east = north = float("-inf")
+ for feature in features:
+ for lon, lat in _coordinates(feature["geometry"]):
+ west, east = min(west, lon), max(east, lon)
+ south, north = min(south, lat), max(north, lat)
+ if west > east:
+ return None
+ return [west, south, east, north]
+
+
+def _coordinates(geometry: dict[str, Any]) -> Iterator[tuple[float, float]]:
+ def walk(node: Any) -> Iterator[tuple[float, float]]:
+ if isinstance(node, (list, tuple)):
+ if node and isinstance(node[0], (int, float)) and len(node) >= 2:
+ yield float(node[0]), float(node[1])
+ return
+ for child in node:
+ yield from walk(child)
+
+ if geometry.get("type") == "GeometryCollection":
+ for child in geometry.get("geometries") or []:
+ yield from _coordinates(child)
+ return
+ yield from walk(geometry.get("coordinates"))
+
+
+def _properties(
+ *,
+ name: str = "",
+ description: str = "",
+ category: str = "",
+ colour: str = "",
+ icon: str = "",
+) -> dict[str, Any]:
+ """The five fields every feature carries, whatever it was read from.
+
+ `icon` names a stored pictogram rather than holding an address: the browser
+ is told which image to draw, never where the source kept it.
+ """
+ return {
+ "name": _text(name, MAX_NAME),
+ "description": _rich_text(description, MAX_DESCRIPTION),
+ "category": _text(category, MAX_NAME) or UNGROUPED,
+ "colour": colour or "",
+ "icon": icon or "",
+ }
+
+
+_HEX = re.compile(r"^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$")
+
+
+def _hex(value: Any) -> str:
+ """A CSS colour a source wrote, as `#rrggbb`, or nothing.
+
+ Only hex is read. A source that named a colour in words or in `rgb()` is
+ rare enough, and the cost of getting it wrong — a legend row painted a
+ colour the source never used — is worse than a row painted from our own
+ palette and honest about it.
+ """
+ text = str(value or "").strip()
+ match = _HEX.match(text)
+ if not match:
+ return ""
+ digits = match.group(1).lower()
+ if len(digits) == 3:
+ digits = "".join(digit * 2 for digit in digits)
+ return f"#{digits}"
+
+
+_TAGS = re.compile(r"<[^>]+>")
+_SPACES = re.compile(r"[ \t\r\f\v]+")
+_BLANK_LINES = re.compile(r"\n{3,}")
+
+#: Where one line of a description ends. A My Maps writes its columns as a
+#: table, and a table stripped of its tags is one run-on sentence — the labels
+#: the source wrote are only labels while the rows they head are still lines.
+_HTML_BREAK = re.compile(r"(?i)<br\s*/?>|</(?:p|div|tr|li|h[1-6]|table|blockquote)\s*>")
+#: …and where a row's label ends and its value begins.
+_HTML_CELL = re.compile(r"(?i)</t[dh]\s*>\s*<t[dh]\b[^>]*>")
+#: A link, which is worth more than the words it was written under: the popup
+#: shows text, so an address that lives only in an `href` would be lost.
+_HTML_LINK = re.compile(
+ r"(?is)<a\b[^>]*\bhref\s*=\s*[\"']([^\"']+)[\"'][^>]*>(.*?)</a\s*>"
+)
+
+
+def _text(value: Any, limit: int) -> str:
+ """A source's own words, as text.
+
+ A KML description is arbitrary HTML — a My Maps writes tables, images and
+ links into it — and the popup shows what the source says rather than
+ rendering someone else's markup inside the app. Tags are dropped here, at
+ the boundary, so nothing downstream has to decide whether a string is safe.
+ """
+ if value is None:
+ return ""
+ text = _TAGS.sub(" ", str(value))
+ text = (
+ text.replace("&lt;", "<")
+ .replace("&gt;", ">")
+ .replace("&quot;", '"')
+ .replace("&#39;", "'")
+ .replace("&nbsp;", " ")
+ .replace("&amp;", "&")
+ )
+ text = _SPACES.sub(" ", text)
+ text = _BLANK_LINES.sub("\n\n", text)
+ text = "\n".join(line.strip() for line in text.splitlines()).strip()
+ return text[:limit]
+
+
+def _rich_text(value: Any, limit: int) -> str:
+ """The same, for a description — the one field a source writes markup into.
+
+ Tags still go, but not before what they *said* is written down as text: a
+ row becomes a line, the two cells of a row become `label: value`, and a
+ link keeps the address it pointed at. Stripping the markup first turns a My
+ Maps table into one run-on paragraph with the URLs missing, which is the
+ popup in the screenshot nobody could read.
+
+ Kept apart from `_text` because a name and a category are one line each and
+ must stay that way; only a description is allowed to arrive shaped.
+ """
+ if value is None:
+ return ""
+ text = _HTML_LINK.sub(_link_text, str(value))
+ text = _HTML_CELL.sub(": ", text)
+ text = _HTML_BREAK.sub("\n", text)
+ return _text(text, limit)
+
+
+def _link_text(match: "re.Match[str]") -> str:
+ """An anchor as text: its words, plus its address when they are not it."""
+ href = _TAGS.sub(" ", match.group(1)).replace("&amp;", "&").strip()
+ words = _TAGS.sub(" ", match.group(2)).strip()
+ if not href:
+ return words
+ if not words or href in words:
+ return href
+ return f"{words} {href}"
+
+
+# ---------------------------------------------------------------------------
+# GeoJSON
+# ---------------------------------------------------------------------------
+
+_GEOMETRY_TYPES = frozenset(
+ {
+ "Point", "MultiPoint", "LineString", "MultiLineString",
+ "Polygon", "MultiPolygon", "GeometryCollection",
+ }
+)
+
+#: Properties a GeoJSON commonly carries the feature's own name under. Read in
+#: order, first hit wins — unlike the category, a name is not a grouping, so
+#: guessing wrong costs a popup heading rather than a wrong legend.
+_NAME_KEYS = ("name", "title", "Name", "NAME", "label")
+_DESCRIPTION_KEYS = ("description", "Description", "desc", "comment", "notes")
+
+
+def _from_geojson(data: bytes, filename: str) -> tuple[list[dict[str, Any]], str]:
+ try:
+ document = json.loads(data.decode("utf-8-sig"))
+ except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+ raise LayerError(f"this is not valid JSON: {exc}") from exc
+ if not isinstance(document, dict):
+ raise LayerError("a GeoJSON file is an object, not a list")
+
+ type_ = document.get("type")
+ if type_ == "FeatureCollection":
+ raw = document.get("features")
+ if not isinstance(raw, list):
+ raise LayerError("this FeatureCollection has no features array")
+ elif type_ == "Feature":
+ raw = [document]
+ elif type_ in _GEOMETRY_TYPES:
+ raw = [{"type": "Feature", "geometry": document, "properties": {}}]
+ else:
+ raise LayerError(f"unsupported GeoJSON type '{type_}'")
+
+ category = _text(document.get("name") or _stem(filename), MAX_NAME) or UNGROUPED
+ features: list[dict[str, Any]] = []
+ for entry in raw:
+ if not isinstance(entry, dict):
+ continue
+ geometry = _geometry(entry.get("geometry"))
+ if geometry is None:
+ continue
+ _bound(features)
+ source = entry.get("properties")
+ source = source if isinstance(source, dict) else {}
+ features.append(
+ {
+ "type": "Feature",
+ "geometry": geometry,
+ "properties": _properties(
+ name=_first(source, _NAME_KEYS),
+ description=_first(source, _DESCRIPTION_KEYS),
+ category=category,
+ # simplestyle-spec, which is what every tool that writes a
+ # styled GeoJSON — geojson.io included — puts the colour in
+ colour=_hex(source.get("marker-color") or source.get("stroke")
+ or source.get("fill")),
+ ),
+ }
+ )
+ return features, _text(document.get("name"), MAX_NAME)
+
+
+def _first(source: dict[str, Any], keys: tuple[str, ...]) -> str:
+ for key in keys:
+ value = source.get(key)
+ if isinstance(value, str) and value.strip():
+ return value
+ return ""
+
+
+def _geometry(geometry: Any) -> dict[str, Any] | None:
+ """A geometry we will draw, or None for one we will not.
+
+ Null geometry is legal GeoJSON and common in exports — a row with attributes
+ and no position. It is not an error; there is simply nothing to put on a map.
+ """
+ if not isinstance(geometry, dict):
+ return None
+ type_ = geometry.get("type")
+ if type_ not in _GEOMETRY_TYPES:
+ return None
+ if type_ == "GeometryCollection":
+ children = []
+ for entry in geometry.get("geometries") or []:
+ drawn = _geometry(entry)
+ if drawn is not None:
+ children.append(drawn)
+ return {"type": "GeometryCollection", "geometries": children} if children else None
+ coordinates = geometry.get("coordinates")
+ if not isinstance(coordinates, list) or not coordinates:
+ return None
+ points = sum(1 for _ in _coordinates(geometry))
+ if points > MAX_GEOMETRY_POINTS:
+ raise LayerError(
+ f"one shape in this file has {points:,} points — the limit is "
+ f"{MAX_GEOMETRY_POINTS:,}"
+ )
+ return {"type": type_, "coordinates": coordinates}
+
+
+def _bound(features: list[dict[str, Any]]) -> None:
+ if len(features) >= MAX_FEATURES:
+ raise LayerError(
+ f"this file holds more than {MAX_FEATURES:,} features — past that it "
+ "is a dataset, not a layer"
+ )
+
+
+# ---------------------------------------------------------------------------
+# KML, and the KMZ it may arrive zipped in
+# ---------------------------------------------------------------------------
+
+
+def _kml_out_of_kmz(data: bytes) -> tuple[bytes, str]:
+ """The one KML inside a KMZ, with the zip's three lies checked first.
+
+ Nothing is written to disk — the member is read into memory — so zip-slip is
+ not a file-writing risk here. The names are still refused, because a member
+ called `../doc.kml` says the archive was built to escape something, and an
+ archive that lies about where its files go is not one to read the contents of.
+ """
+ try:
+ archive = zipfile.ZipFile(BytesIO(data))
+ except zipfile.BadZipFile as exc:
+ raise LayerError("this KMZ is not a readable zip archive") from exc
+
+ with archive:
+ entries = archive.infolist()
+ if len(entries) > MAX_ZIP_MEMBERS:
+ raise LayerError(f"this KMZ holds more than {MAX_ZIP_MEMBERS:,} files")
+ total = 0
+ for entry in entries:
+ if _escapes(entry.filename):
+ raise LayerError(f"this KMZ names a file outside itself: {entry.filename}")
+ total += entry.file_size
+ if total > MAX_UNCOMPRESSED_BYTES:
+ raise LayerError(
+ f"this KMZ unpacks to more than {_megabytes(MAX_UNCOMPRESSED_BYTES)}"
+ )
+ if entry.compress_size and entry.file_size / entry.compress_size > MAX_COMPRESSION_RATIO:
+ raise LayerError("this KMZ is compressed far past anything a map file needs")
+
+ member = _main_kml(entries)
+ if member is None:
+ raise LayerError("this KMZ holds no KML file")
+ with archive.open(member) as handle:
+ return handle.read(MAX_SOURCE_BYTES + 1), member.filename
+
+
+def _escapes(name: str) -> bool:
+ """Whether a zip member name climbs out of its own archive."""
+ cleaned = name.replace("\\", "/")
+ if cleaned.startswith("/") or re.match(r"^[A-Za-z]:", cleaned):
+ return True
+ return any(part == ".." for part in cleaned.split("/"))
+
+
+def _main_kml(entries: list[zipfile.ZipInfo]) -> zipfile.ZipInfo | None:
+ """`doc.kml` by convention, else the first KML at the shallowest depth."""
+ candidates = [
+ entry
+ for entry in entries
+ if not entry.is_dir() and entry.filename.lower().endswith(".kml")
+ ]
+ if not candidates:
+ return None
+ for entry in candidates:
+ if entry.filename.lower() == "doc.kml":
+ return entry
+ return min(candidates, key=lambda e: (e.filename.count("/"), e.filename))
+
+
+_KML_NS = re.compile(r"^\{[^}]*\}")
+
+
+def _tag(element: Element) -> str:
+ return _KML_NS.sub("", element.tag)
+
+
+def _child(element: Element, name: str) -> Element | None:
+ for child in element:
+ if _tag(child) == name:
+ return child
+ return None
+
+
+def _child_text(element: Element, name: str) -> str:
+ child = _child(element, name)
+ return child.text or "" if child is not None else ""
+
+
+def _xml(data: bytes) -> Element:
+ """Parse untrusted XML with the entity machinery switched off.
+
+ `defusedxml` is what refuses the external entity and the expansion bomb; the
+ depth walk below is what refuses the third shape, a document nested deep
+ enough to exhaust the stack of whatever walks it.
+ """
+ try:
+ root = parse_xml(data)
+ except ParseError as exc:
+ raise LayerError(f"this XML will not parse: {exc}") from exc
+ except ValueError as exc: # defusedxml raises its own refusals as these
+ raise LayerError(f"this file was refused: {exc}") from exc
+ _check_depth(root)
+ return root
+
+
+def _check_depth(root: Element) -> None:
+ stack = [(root, 1)]
+ while stack:
+ element, depth = stack.pop()
+ if depth > MAX_XML_DEPTH:
+ raise LayerError(f"this file nests deeper than {MAX_XML_DEPTH} levels")
+ for child in element:
+ stack.append((child, depth + 1))
+
+
+def _from_kml(data: bytes) -> tuple[list[dict[str, Any]], str, dict[str, dict[str, Any]]]:
+ root = _xml(data)
+ inner = _child(root, "Document") if _tag(root) == "kml" else None
+ document = root if inner is None else inner
+ styles = _kml_styles(root)
+ title = _text(_child_text(document, "name"), MAX_NAME)
+
+ features: list[dict[str, Any]] = []
+ #: key → what that pictogram is, in the order the file first asks for it, so
+ #: the cap below falls on the groups a creator added last.
+ icons: dict[str, dict[str, Any]] = {}
+ _walk_kml(document, [], styles, features, title, icons)
+ return features, title, icons
+
+
+def _walk_kml(
+ element: Element,
+ folders: list[str],
+ styles: dict[str, dict[str, Any]],
+ features: list[dict[str, Any]],
+ title: str,
+ icons: dict[str, dict[str, Any]],
+) -> None:
+ """Depth-first, carrying the folder path that names each placemark's category."""
+ for child in element:
+ tag = _tag(child)
+ if tag in ("Folder", "Document"):
+ name = _text(_child_text(child, "name"), MAX_NAME)
+ _walk_kml(
+ child,
+ [*folders, name] if name else folders,
+ styles,
+ features,
+ title,
+ icons,
+ )
+ elif tag == "Placemark":
+ _placemark(child, folders, styles, features, title, icons)
+ elif tag in ("kml", "GroundOverlay", "NetworkLink", "ScreenOverlay"):
+ continue
+
+
+def _placemark(
+ element: Element,
+ folders: list[str],
+ styles: dict[str, dict[str, Any]],
+ features: list[dict[str, Any]],
+ title: str,
+ icons: dict[str, dict[str, Any]],
+) -> None:
+ geometries = list(_kml_geometries(element))
+ if not geometries:
+ return
+ name = _text(_child_text(element, "name"), MAX_NAME)
+ description = _child_text(element, "description")
+ if not description:
+ description = _kml_extended_data(element)
+ style = _kml_style(element, styles)
+ colour = str(style.get("colour") or "")
+ icon = _icon_of(style)
+ key = ""
+ if icon is not None:
+ key, descriptor = icon
+ icons.setdefault(key, descriptor)
+ category = " / ".join(folders) if folders else (title or UNGROUPED)
+ for geometry in geometries:
+ _bound(features)
+ features.append(
+ {
+ "type": "Feature",
+ "geometry": geometry,
+ "properties": _properties(
+ name=name,
+ description=description,
+ category=category,
+ colour=colour,
+ # only a point draws a pictogram; a line and an area are
+ # drawn by their own stroke and fill
+ icon=key if _kind(geometry) == "point" else "",
+ ),
+ }
+ )
+
+
+def _kml_extended_data(element: Element) -> str:
+ """A My Maps puts its columns here rather than in the description."""
+ data = _child(element, "ExtendedData")
+ if data is None:
+ return ""
+ rows = []
+ for child in data:
+ if _tag(child) != "Data":
+ continue
+ label = child.get("name") or ""
+ value = _child_text(child, "value")
+ if label and value:
+ rows.append(f"{label}: {value}")
+ return "\n".join(rows)
+
+
+def _kml_styles(root: Element) -> dict[str, dict[str, Any]]:
+ """`#styleId` → what that style draws, following one level of StyleMap.
+
+ A My Maps writes a StyleMap per placemark with a normal and a highlight
+ pair; the normal one is what the map draws, so that is the one read.
+ """
+ direct: dict[str, dict[str, Any]] = {}
+ maps: dict[str, str] = {}
+ for element in root.iter():
+ tag = _tag(element)
+ identifier = element.get("id")
+ if not identifier:
+ continue
+ if tag == "Style":
+ style = _style(element)
+ if style:
+ direct[identifier] = style
+ elif tag == "StyleMap":
+ for pair in element:
+ if _tag(pair) != "Pair" or _child_text(pair, "key").strip() != "normal":
+ continue
+ target = _child_text(pair, "styleUrl").strip().lstrip("#")
+ if target:
+ maps[identifier] = target
+ for identifier, target in maps.items():
+ if target in direct:
+ direct[identifier] = direct[target]
+ return direct
+
+
+def _style(style: Element) -> dict[str, Any]:
+ """A style as the two things it can say: a colour, and a pictogram.
+
+ Empty when it says neither, so a `<Style>` holding only a label size does not
+ take precedence over the one a StyleMap points at.
+ """
+ icon_style = _child(style, "IconStyle")
+ read = {
+ "colour": _style_colour(style),
+ "href": _icon_href(icon_style),
+ "scale": _icon_scale(icon_style),
+ "hotspot": _hotspot(icon_style),
+ }
+ return read if read["colour"] or read["href"] else {}
+
+
+def _style_colour(style: Element) -> str:
+ """A style's colour, preferring what fills a mark over what outlines a shape."""
+ for name in ("IconStyle", "PolyStyle", "LineStyle", "LabelStyle"):
+ child = _child(style, name)
+ if child is None:
+ continue
+ colour = _kml_abgr(_child_text(child, "color"))
+ if colour:
+ return colour
+ return ""
+
+
+def _icon_href(icon_style: Element | None) -> str:
+ """Where the source keeps this pictogram — an address, or a name in a KMZ.
+
+ Read as a string and nothing more. Whether it is worth following, and whether
+ following it is allowed at all, is `icon_images`' question.
+ """
+ if icon_style is None:
+ return ""
+ icon = _child(icon_style, "Icon")
+ href = _child_text(icon, "href").strip() if icon is not None else ""
+ return href[:MAX_HREF]
+
+
+def _icon_scale(icon_style: Element | None) -> float:
+ """How much bigger than usual the source drew this one. 1 when it said nothing."""
+ if icon_style is None:
+ return 1.0
+ try:
+ scale = float(_child_text(icon_style, "scale").strip() or 1.0)
+ except ValueError:
+ return 1.0
+ return scale if 0 < scale < 100 else 1.0
+
+
+def _hotspot(icon_style: Element | None) -> tuple[float, float, str, str] | None:
+ """The pixel of the image the source anchors it by, in the units it gave.
+
+ Resolved no further here: `x=32 pixels` only means something once the image
+ it measures has been read, and reading it is a later act than parsing.
+ """
+ if icon_style is None:
+ return None
+ spot = _child(icon_style, "hotSpot")
+ if spot is None:
+ return None
+ try:
+ x, y = float(spot.get("x", "")), float(spot.get("y", ""))
+ except ValueError:
+ return None
+ return x, y, spot.get("xunits", "fraction"), spot.get("yunits", "fraction")
+
+
+def _icon_of(style: dict[str, Any]) -> tuple[str, dict[str, Any]] | None:
+ """A style's pictogram, keyed by everything that decides what it looks like.
+
+ The key is the content hash of the description, so two styles that would
+ compose to the same pixels are one stored image — which is what keeps a My
+ Maps with one style per placemark down to one icon per *look*.
+ """
+ href = str(style.get("href") or "")
+ if not href:
+ return None
+ descriptor = {
+ "href": href,
+ "colour": str(style.get("colour") or ""),
+ "scale": float(style.get("scale") or 1.0),
+ "hotspot": list(style["hotspot"]) if style.get("hotspot") else None,
+ }
+ seed = json.dumps(descriptor, sort_keys=True).encode("utf-8")
+ return hashlib.sha256(seed).hexdigest()[:ICON_KEY_LENGTH], descriptor
+
+
+def _kml_abgr(value: str) -> str:
+ """KML writes `aabbggrr`; CSS wants `#rrggbb`, and the alpha is dropped.
+
+ Opacity is the layer's to set — a source that painted a fill at 40% did so
+ against its own basemap, not against whatever imagery this case is on.
+ """
+ text = str(value or "").strip().lstrip("#")
+ if len(text) != 8 or not re.fullmatch(r"[0-9a-fA-F]{8}", text):
+ return ""
+ return f"#{text[6:8]}{text[4:6]}{text[2:4]}".lower()
+
+
+def _kml_style(element: Element, styles: dict[str, dict[str, Any]]) -> dict[str, Any]:
+ """What this placemark draws: the style it points at, else the one inside it."""
+ url = _child_text(element, "styleUrl").strip().lstrip("#")
+ if url and url in styles:
+ return styles[url]
+ inline = _child(element, "Style")
+ return _style(inline) if inline is not None else {}
+
+
+def _kml_geometries(element: Element) -> Iterator[dict[str, Any]]:
+ for child in element:
+ tag = _tag(child)
+ if tag == "Point":
+ point = _kml_points(_child_text(child, "coordinates"))
+ if point:
+ yield {"type": "Point", "coordinates": point[0]}
+ elif tag in ("LineString", "LinearRing"):
+ points = _kml_points(_child_text(child, "coordinates"))
+ if len(points) >= 2:
+ yield {"type": "LineString", "coordinates": points}
+ elif tag == "Polygon":
+ rings = list(_kml_rings(child))
+ if rings:
+ yield {"type": "Polygon", "coordinates": rings}
+ elif tag == "Track":
+ # Google Earth's own track: timestamped `<gx:coord>lon lat alt</gx:coord>`
+ # rather than a coordinates string. The times are not drawn, so what
+ # is left of it is the path.
+ track = [
+ fix
+ for coord in child
+ if _tag(coord) == "coord" and (fix := _gx_coord(coord.text)) is not None
+ ]
+ if len(track) >= 2:
+ yield {"type": "LineString", "coordinates": track}
+ elif tag == "MultiGeometry":
+ yield from _kml_geometries(child)
+
+
+def _kml_rings(polygon: Element) -> Iterator[list[list[float]]]:
+ """Outer boundary first, then the holes — the order GeoJSON reads them in."""
+ for name in ("outerBoundaryIs", "innerBoundaryIs"):
+ for child in polygon:
+ if _tag(child) != name:
+ continue
+ ring = _child(child, "LinearRing")
+ if ring is None:
+ continue
+ points = _kml_points(_child_text(ring, "coordinates"))
+ if len(points) < 4:
+ continue
+ if points[0] != points[-1]:
+ points.append(points[0])
+ yield points
+
+
+def _kml_points(text: str) -> list[list[float]]:
+ """`lon,lat[,alt]` tuples, whitespace-separated. Altitude is dropped."""
+ points: list[list[float]] = []
+ for chunk in str(text or "").split():
+ parts = chunk.split(",")
+ if len(parts) < 2:
+ continue
+ try:
+ lon, lat = float(parts[0]), float(parts[1])
+ except ValueError:
+ continue
+ if not _on_earth(lon, lat):
+ continue
+ points.append([lon, lat])
+ if len(points) > MAX_GEOMETRY_POINTS:
+ raise LayerError(
+ f"one shape in this file has more than {MAX_GEOMETRY_POINTS:,} points"
+ )
+ return points
+
+
+def _gx_coord(text: str | None) -> list[float] | None:
+ parts = str(text or "").split()
+ if len(parts) < 2:
+ return None
+ try:
+ lon, lat = float(parts[0]), float(parts[1])
+ except ValueError:
+ return None
+ return [lon, lat] if _on_earth(lon, lat) else None
+
+
+def _on_earth(lon: float, lat: float) -> bool:
+ return -180 <= lon <= 180 and -90 <= lat <= 90
+
+
+# ---------------------------------------------------------------------------
+# GPX
+# ---------------------------------------------------------------------------
+
+#: What a GPX states about its own contents, which is the whole of its grouping.
+_GPX_CATEGORIES = {"wpt": "Waypoints", "trk": "Tracks", "rte": "Routes"}
+
+
+def _from_gpx(data: bytes) -> tuple[list[dict[str, Any]], str]:
+ root = _xml(data)
+ features: list[dict[str, Any]] = []
+ title = ""
+ metadata = _child(root, "metadata")
+ if metadata is not None:
+ title = _text(_child_text(metadata, "name"), MAX_NAME)
+
+ for child in root:
+ tag = _tag(child)
+ category = _GPX_CATEGORIES.get(tag)
+ if category is None:
+ continue
+ name = _text(_child_text(child, "name"), MAX_NAME)
+ description = _child_text(child, "desc") or _child_text(child, "cmt")
+ if tag == "wpt":
+ point = _gpx_point(child)
+ if point is None:
+ continue
+ _bound(features)
+ features.append(
+ {
+ "type": "Feature",
+ "geometry": {"type": "Point", "coordinates": point},
+ "properties": _properties(
+ name=name, description=description, category=category
+ ),
+ }
+ )
+ continue
+ for points in _gpx_paths(child, tag):
+ if len(points) < 2:
+ continue
+ _bound(features)
+ features.append(
+ {
+ "type": "Feature",
+ "geometry": {"type": "LineString", "coordinates": points},
+ "properties": _properties(
+ name=name, description=description, category=category
+ ),
+ }
+ )
+ return features, title
+
+
+def _gpx_paths(element: Element, tag: str) -> Iterator[list[list[float]]]:
+ """A track's segments, or a route's single run of points."""
+ if tag == "rte":
+ yield [
+ point for child in element
+ if _tag(child) == "rtept" and (point := _gpx_point(child)) is not None
+ ]
+ return
+ for segment in element:
+ if _tag(segment) != "trkseg":
+ continue
+ yield [
+ point for child in segment
+ if _tag(child) == "trkpt" and (point := _gpx_point(child)) is not None
+ ]
+
+
+def _gpx_point(element: Element) -> list[float] | None:
+ try:
+ lon, lat = float(element.get("lon", "")), float(element.get("lat", ""))
+ except ValueError:
+ return None
+ return [lon, lat] if _on_earth(lon, lat) else None
+
+
+# ---------------------------------------------------------------------------
+# The source's own pictograms
+# ---------------------------------------------------------------------------
+#
+# Only ever reached through the tick the analyst put on the add dialog, which is
+# what makes this defensible at all: a KMZ carries its icons inside itself and
+# costs nothing, but a KML — a My Maps above all — points at somebody else's
+# server, and following that is a request the app must be *asked* to make.
+#
+# Nothing a host sent is handed on. Every image is decoded here, tinted, resized
+# and re-encoded, so what the browser loads is a PNG this process produced. That
+# is one answer to three separate things: an SVG with a script in it, a file
+# pretending to be an image, and a thumbnail that unpacks into a gigabyte.
+#
+# No failure here refuses a layer. An icon that will not load leaves its features
+# drawing the app's own shape in the source's colour, which is a map that still
+# says what is where.
+
+
+def icon_images(
+ descriptors: dict[str, dict[str, Any]], *, source: bytes = b""
+) -> dict[str, bytes]:
+ """key → the PNG to store for it, skipping every one that could not be made.
+
+ `source` is the original bytes, which is how a KMZ's own icons are found: its
+ hrefs name members of the archive the layer was read from.
+ """
+ if not descriptors:
+ return {}
+ archive = _icon_archive(source)
+ out: dict[str, bytes] = {}
+ total = 0
+ try:
+ for key in list(descriptors)[:MAX_ICONS]:
+ descriptor = descriptors[key]
+ raw = _icon_bytes(descriptor, archive)
+ if not raw:
+ continue
+ png = _compose_icon(raw, descriptor)
+ if png is None:
+ continue
+ total += len(png)
+ if total > MAX_ICONS_BYTES:
+ break
+ out[key] = png
+ finally:
+ if archive is not None:
+ archive.close()
+ return out
+
+
+def _icon_archive(source: bytes) -> zipfile.ZipFile | None:
+ """The KMZ the layer came out of, when it came out of one."""
+ if source[:4] != _ZIP_MAGIC:
+ return None
+ try:
+ return zipfile.ZipFile(BytesIO(source))
+ except zipfile.BadZipFile:
+ return None
+
+
+def _icon_bytes(
+ descriptor: dict[str, Any], archive: zipfile.ZipFile | None
+) -> bytes:
+ """The image a descriptor points at: out of the archive, or off the web."""
+ href = str(descriptor.get("href") or "")
+ if href.lower().startswith(("http://", "https://")):
+ return _fetch_icon(href)
+ return _zipped_icon(archive, href) if archive is not None else b""
+
+
+def _zipped_icon(archive: zipfile.ZipFile, href: str) -> bytes:
+ """A KMZ member named by a relative href, matched the way a zip stores names.
+
+ Case-insensitively, because a KML written on Windows regularly disagrees with
+ its own archive about capitalisation, and the analyst would read that as the
+ icons simply not working.
+ """
+ name = unquote(href.split("?", 1)[0].split("#", 1)[0]).replace("\\", "/")
+ name = name.removeprefix("./")
+ if not name or _escapes(name):
+ return b""
+ for entry in archive.infolist():
+ if entry.is_dir() or entry.filename.replace("\\", "/").lower() != name.lower():
+ continue
+ if entry.file_size > MAX_ICON_BYTES:
+ return b""
+ with archive.open(entry) as handle:
+ return handle.read(MAX_ICON_BYTES + 1)
+ return b""
+
+
+def _fetch_icon(href: str) -> bytes:
+ """One image off the web, bounded, and never a reason to refuse the layer."""
+ try:
+ with httpx.stream(
+ "GET",
+ href,
+ timeout=ICON_TIMEOUT,
+ follow_redirects=True,
+ headers={"User-Agent": USER_AGENT},
+ ) as response:
+ response.raise_for_status()
+ declared = response.headers.get("content-length")
+ if declared and declared.isdigit() and int(declared) > MAX_ICON_BYTES:
+ return b""
+ chunks: list[bytes] = []
+ total = 0
+ for chunk in response.iter_bytes():
+ total += len(chunk)
+ if total > MAX_ICON_BYTES:
+ return b""
+ chunks.append(chunk)
+ return b"".join(chunks)
+ except (httpx.HTTPError, ValueError):
+ return b""
+
+
+def _compose_icon(raw: bytes, descriptor: dict[str, Any]) -> bytes | None:
+ """Somebody else's image → the PNG this app will serve for it.
+
+ The order is the whole of it. The hotspot is read first, against the size the
+ source measured it in — `x=32 pixels` means the middle of a 64px icon and
+ nothing at all once that icon has been resized. Then tint, because the colour
+ is applied at full detail; then resize, so every icon comes out one size; and
+ pad last, which is what puts the anchor on the centre.
+ """
+ try:
+ with Image.open(BytesIO(raw)) as opened:
+ if opened.width * opened.height > MAX_ICON_AREA:
+ return None
+ opened.load()
+ image = opened.convert("RGBA")
+ except (OSError, ValueError, Image.DecompressionBombError):
+ return None
+ if not image.width or not image.height:
+ return None
+ anchor = _hotspot_fraction(descriptor.get("hotspot"), image.width, image.height)
+ image = _tint(image, str(descriptor.get("colour") or ""))
+ image = _resize_icon(image, float(descriptor.get("scale") or 1.0))
+ image = _centre_on(image, anchor)
+ buffer = BytesIO()
+ image.save(buffer, format="PNG", optimize=True)
+ return buffer.getvalue()
+
+
+def _tint(image: "Image.Image", colour: str) -> "Image.Image":
+ """`<color>` over the image, which in KML means a multiply.
+
+ The step the whole feature turns on. A My Maps' stock pictograms are *white*
+ silhouettes — the shape is in the PNG and the colour is in the style — so an
+ untinted one is a white blob on white imagery, and honouring the href without
+ honouring the colour would look like a bug rather than a map.
+ """
+ rgb = _rgb(colour)
+ if rgb is None:
+ return image
+ red, green, blue, alpha = image.split()
+ bands = [
+ band.point([level * value // 255 for level in range(256)])
+ for band, value in zip((red, green, blue), rgb)
+ ]
+ return Image.merge("RGBA", (*bands, alpha))
+
+
+def _rgb(colour: str) -> tuple[int, int, int] | None:
+ text = _hex(colour)
+ if not text:
+ return None
+ return int(text[1:3], 16), int(text[3:5], 16), int(text[5:7], 16)
+
+
+def _ink(image: "Image.Image") -> tuple[int, float] | None:
+ """The box a pictogram actually paints in, and how much of that box it fills.
+
+ Both read off the opaque core rather than off every pixel the source's own
+ antialiasing left a trace in: a soft edge is not part of what the eye
+ measures a mark by, and counting it would make a blurry icon read as a
+ bigger one.
+ """
+ solid = image.split()[3].point(lambda level: 255 if level > 128 else 0)
+ box = solid.getbbox()
+ if box is None:
+ return None
+ width, height = box[2] - box[0], box[3] - box[1]
+ if width <= 0 or height <= 0:
+ return None
+ painted = solid.crop(box).histogram()[255]
+ return max(width, height), max(MIN_ICON_FILL, min(1.0, painted / (width * height)))
+
+
+def _resize_icon(image: "Image.Image", scale: float) -> "Image.Image":
+ """Every icon to one weight, measured on its **ink** rather than its canvas.
+
+ Two separate lies the canvas tells. A My Maps archive holds a 56px square
+ painted edge to edge next to a 26px glyph floating in a 56px sheet of
+ transparency, so holding the *sheets* to one size draws the second at a
+ third of the first. And once the boxes match, a square that fills its box
+ still carries nearly twice the ink of the disc beside it. So what is held
+ equal is the painted extent, discounted by how densely it is painted, with
+ the source's own `<scale>` riding on top.
+ """
+ ink = _ink(image)
+ if ink is None:
+ return image
+ extent, fill = ink
+ side = max(MIN_ICON_SIDE, min(MAX_ICON_SIDE, round(ICON_SIDE * scale)))
+ # A glyph lost in a large sheet would scale that whole sheet up with it, so
+ # the canvas is held to its own ceiling — the ink then comes out a little
+ # under `side`, which is the right way round: too small beats a texture the
+ # size of a photograph.
+ factor = min(
+ side / (extent * fill**ICON_FILL_WEIGHT),
+ MAX_ICON_CANVAS / max(image.width, image.height),
+ )
+ size = (max(1, round(image.width * factor)), max(1, round(image.height * factor)))
+ # Lanczos is the right filter for shrinking and the wrong one for growing: it
+ # rings, and a ring in the alpha channel of a glyph blown up four times is a
+ # visible halo around the mark. Bicubic on the way up has none.
+ filter_ = Image.Resampling.LANCZOS if factor < 1 else Image.Resampling.BICUBIC
+ return image.resize(size, filter_)
+
+
+def _centre_on(
+ image: "Image.Image", anchor: tuple[float, float] | None
+) -> "Image.Image":
+ """Pad the image so the pixel the source anchors it by sits at its centre.
+
+ Baked into the pixels rather than carried as a per-feature offset: the map
+ then draws every icon the same way — centred, one layout — and a pin whose
+ tip is its meaning puts that tip on the ground rather than its own middle.
+ The padding is transparent, so it costs almost nothing once compressed.
+ """
+ if anchor is None:
+ return image
+ across, down = anchor[0] * image.width, anchor[1] * image.height
+ width = max(image.width, round(2 * max(across, image.width - across)))
+ height = max(image.height, round(2 * max(down, image.height - down)))
+ if (width, height) == (image.width, image.height):
+ return image
+ padded = Image.new("RGBA", (width, height), (0, 0, 0, 0))
+ padded.paste(image, (round(width / 2 - across), round(height / 2 - down)))
+ return padded
+
+
+def _hotspot_fraction(
+ hotspot: list[float] | tuple[float, ...] | None, width: int, height: int
+) -> tuple[float, float] | None:
+ """A KML hotSpot as fractions from the top-left, or None for a centred one.
+
+ Three unit systems and two origins: KML measures `y` up from the bottom,
+ except for `insetPixels`, which measures down from the top — and that is the
+ one My Maps writes.
+ """
+ if not hotspot or len(hotspot) != 4 or width <= 0 or height <= 0:
+ return None
+ x, y, xunits, yunits = hotspot[0], hotspot[1], str(hotspot[2]), str(hotspot[3])
+ across = float(x) if xunits == "fraction" else float(x) / width
+ if xunits == "insetPixels":
+ across = 1.0 - across
+ down = float(y) if yunits == "fraction" else float(y) / height
+ if yunits != "insetPixels":
+ down = 1.0 - down
+ across = min(max(across, 0.0), 1.0)
+ down = min(max(down, 0.0), 1.0)
+ if abs(across - 0.5) < 1e-6 and abs(down - 0.5) < 1e-6:
+ return None
+ return across, down
+
+
+# ---------------------------------------------------------------------------
+# A layer in a case
+# ---------------------------------------------------------------------------
+#
+# Four files, because the layer does four different things and each has its
+# own answer to "does this travel?":
+#
+# .layers/<name>.json the spec — where it came from, how it
+# refreshes, which categories are hidden
+# .layers/<name>.src the bytes as received, plus their sha256
+# .layers/<name>.icons the source's pictograms, composed here
+# .layers/.cache/<name>.geojson what the browser draws, derived
+#
+# The icons travel, unlike the parsed copy, and for the reason that decides all
+# of this: they cannot be rebuilt offline. A KMZ's are in the snapshot, but a My
+# Maps' came off Google's servers, and a case restored on a machine with no
+# network would quietly lose half of what its map looked like. So they are stored
+# as a companion the bundle carries, not as a cache.
+#
+# The snapshot is the original rather than a normalised GeoJSON on purpose: it
+# hashes like a media, and "never rewriting evidence already saved from it" is
+# then true by construction rather than by care. The parsed form is a cache in
+# the strict sense — dropped on delete, never carried in a bundle, and rebuilt
+# here the moment something asks for it.
+#
+# Nothing in this file adopts a feature into the case. A layer is drawn, filtered
+# and consulted; the graph knows it as one `map-layer` entity and nothing else.
+
+#: The spec's own version, so a later shape can be told from this one.
+SPEC_VERSION = 1
+
+#: Which parser wrote a cached copy.
+#:
+#: The cache is derived, and *which code derived it* is part of what it is: a
+#: layer added from a file is never re-read — nothing about it changes — so
+#: without this stamp it would draw the output of whichever parser was current
+#: the day it was dropped in, for as long as the case lives. Bumped whenever a
+#: change here would give the same bytes a different reading; the next request
+#: for that layer reparses the snapshot already on disk.
+PARSE_VERSION = 2
+
+#: Where that stamp is written. A GeoJSON object may carry members it does not
+#: define, and this one is written first so the check reads the head of the file
+#: rather than the twenty megabytes behind it.
+PARSE_KEY = "azimut_parse"
+
+#: What the entity type is called wherever the graph names it.
+ENTITY_TYPE = "map-layer"
+
+#: How long a fetched snapshot is treated as current. Past it the row says the
+#: layer is stale *before* it redraws, which is the whole point of the readout:
+#: a layer silently drawing week-old data on a map where decisions get made is
+#: this feature's worst failure.
+FRESH_FOR_HOURS = 24
+
+#: What a remote source may weigh, checked against the declared length before a
+#: byte is read and again as it arrives — a server is free to lie about both.
+MAX_FETCH_BYTES = MAX_SOURCE_BYTES
+
+FETCH_TIMEOUT = 30
+
+#: The only feed a Google My Maps has. It is undocumented and Google may change
+#: it, so a shape that no longer parses fails with a sentence rather than
+#: drawing nothing (SPEC §9 records why this one unofficial endpoint ships).
+#:
+#: **The KMZ, not the `forcekml=1` conversion beside it.** Both carry the same
+#: placemarks, and the difference is everything the map was drawn with: the KMZ
+#: bundles the creator's actual icons as archive members, while `forcekml=1`
+#: throws the pictograms away and points every style at one of three *blank*
+#: Google containers — `503-wht-blank_maps.png`, `961-wht-square-blank.png`,
+#: `960-wht-star-blank.png`. A map of forty hand-picked symbols comes back as
+#: coloured blanks. The archive is also a quarter of the size on the wire, and
+#: its icons need no third-party request at all.
+MY_MAPS_FEED = "https://www.google.com/maps/d/kml?mid={mid}"
+
+#: Every form a My Maps share link arrives in — the viewer, the editor, the
+#: short `u/0/` variant, and the feed itself pasted back in.
+_MY_MAPS = re.compile(
+ r"^https?://(?:www\.)?google\.[^/]+/maps/d/(?:u/\d+/)?"
+ r"(?:viewer|edit|embed|kml)?\?[^#]*\bmid=([A-Za-z0-9_\-]+)",
+ re.IGNORECASE,
+)
+
+
+class LayerFetchError(LayerError):
+ """A source that could not be read this time, which is not the same as one
+ that will never be readable: the last snapshot stays on the map."""
+
+
+def my_maps_mid(url: str) -> str:
+ """The map id out of any My Maps link, or "" when it is not one."""
+ match = _MY_MAPS.match(str(url or "").strip())
+ return match.group(1) if match else ""
+
+
+def feed_url(url: str) -> str:
+ """What is actually fetched for a pasted address.
+
+ A My Maps link is turned into its KML feed — that is the sharing mechanism
+ the map's own creator switched on, and there is no other way to read one. Any
+ other URL is fetched as given.
+ """
+ mid = my_maps_mid(url)
+ return MY_MAPS_FEED.format(mid=mid) if mid else str(url or "").strip()
+
+
+def _now() -> str:
+ return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _read_spec(case: "Case", name: str) -> dict[str, Any]:
+ path = case.resolve_inside(layout.layer_spec_rel(name))
+ try:
+ spec = json.loads(path.read_text(encoding="utf-8"))
+ except OSError as exc:
+ raise LayerError("this layer is not in the case") from exc
+ except json.JSONDecodeError as exc:
+ raise LayerError("this layer's settings will not parse") from exc
+ if not isinstance(spec, dict) or "azimut_layer" not in spec:
+ raise LayerError("this file is not a map layer")
+ return spec
+
+
+def _write_spec(case: "Case", name: str, spec: dict[str, Any]) -> None:
+ case.subdir(layout.LAYERS_DIR)
+ path = case.resolve_inside(layout.layer_spec_rel(name))
+ path.write_text(json.dumps(spec, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def _free_name(case: "Case", title: str) -> str:
+ """A stem no other layer holds. Two files called `Roads` are two layers."""
+ case.subdir(layout.LAYERS_DIR)
+ base = layout.slugify(title, "Layer")
+ name, counter = base, 1
+ while case.resolve_inside(layout.layer_spec_rel(name)).exists():
+ suffix = f"-{counter}"
+ name = f"{base[: layout.MAX_SLUG - len(suffix)]}{suffix}"
+ counter += 1
+ return name
+
+
+def _store(
+ case: "Case", name: str, data: bytes, parsed: dict[str, Any], *, icons: bool
+) -> dict[str, Any]:
+ """Write the snapshot, its pictograms and its derived cache.
+
+ The one place `icons` decides anything: false and no href is read, off the
+ web or out of the archive, and the map draws the app's own shapes. The spec
+ is the caller's to write.
+ """
+ case.subdir(layout.LAYERS_DIR)
+ case.resolve_inside(layout.layer_snapshot_rel(name)).write_bytes(data)
+ _write_cache(case, name, parsed["geojson"])
+ return {
+ "sha256": digest(data),
+ "bytes": len(data),
+ "at": _now(),
+ "icons": _write_icons(case, name, parsed["icons"] if icons else {}, source=data),
+ }
+
+
+def _write_icons(
+ case: "Case", name: str, descriptors: dict[str, dict[str, Any]], *, source: bytes
+) -> int:
+ """Compose what a source asked for into one zip, and say how many landed.
+
+ Built whole in memory before anything is written, so a fetch that dies
+ halfway leaves the layer with the icons it had rather than half a set. Stored
+ rather than deflated: a PNG is already compressed, and a zip of them is a
+ directory that happens to be one file.
+ """
+ path = case.resolve_inside(layout.layer_icons_rel(name))
+ images = icon_images(descriptors, source=source)
+ if not images:
+ path.unlink(missing_ok=True)
+ return 0
+ buffer = BytesIO()
+ with zipfile.ZipFile(buffer, "w", zipfile.ZIP_STORED) as archive:
+ for key, png in images.items():
+ archive.writestr(f"{key}.png", png)
+ path.write_bytes(buffer.getvalue())
+ return len(images)
+
+
+_ICON_KEY = re.compile(r"[0-9a-f]{1,32}")
+
+
+def icon(case: "Case", name: str, key: str) -> bytes:
+ """One stored pictogram, by the key the features that draw it name it with."""
+ if not _ICON_KEY.fullmatch(str(key or "")):
+ raise LayerError("that is not an icon of this layer")
+ path = case.resolve_inside(layout.layer_icons_rel(name))
+ try:
+ with zipfile.ZipFile(path) as archive:
+ return archive.read(f"{key}.png")
+ except (OSError, KeyError, zipfile.BadZipFile) as exc:
+ raise LayerError("this layer has no such icon") from exc
+
+
+def _write_cache(case: "Case", name: str, geojson: dict[str, Any]) -> Path:
+ path = case.resolve_inside(layout.layer_cache_rel(name))
+ path.parent.mkdir(parents=True, exist_ok=True)
+ stamped = {PARSE_KEY: PARSE_VERSION, **geojson}
+ path.write_text(json.dumps(stamped, ensure_ascii=False), encoding="utf-8")
+ return path
+
+
+def _cache_is_current(path: Path) -> bool:
+ """Whether this cached copy came from the parser running now.
+
+ Read from the head of the file: these run to tens of megabytes, and the
+ question is answered by the first line of one.
+ """
+ try:
+ with path.open("rb") as handle:
+ head = handle.read(64).decode("utf-8", "replace")
+ except OSError:
+ return False
+ return f'"{PARSE_KEY}": {PARSE_VERSION}' in head
+
+
+def drawing(case: "Case", name: str) -> Path:
+ """The parsed GeoJSON to serve, rebuilt from the snapshot when it is gone.
+
+ Which is the normal case after a restore from the Trash or an import: the
+ cache is the one of the three files that never travels, so every caller has
+ to be able to live without it. Rebuilding is one parse of bytes already on
+ disk — and the same parse is what an older stamp asks for, so a layer added
+ from a file is read by the parser running now rather than by the one that was
+ current the day it was added.
+ """
+ spec = _read_spec(case, name)
+ path = case.resolve_inside(layout.layer_cache_rel(name))
+ if path.is_file() and _cache_is_current(path):
+ return path
+ snapshot = case.resolve_inside(layout.layer_snapshot_rel(name))
+ try:
+ data = snapshot.read_bytes()
+ except OSError as exc:
+ raise LayerError("this layer's saved copy is missing") from exc
+ parsed = parse(data, filename=_source_name(spec), title=spec.get("title", ""))
+ return _write_cache(case, name, parsed["geojson"])
+
+
+def _source_name(spec: dict[str, Any]) -> str:
+ source = spec.get("source") or {}
+ return str(source.get("name") or source.get("url") or "")
+
+
+def add_file(
+ case: "Case",
+ data: bytes,
+ *,
+ filename: str,
+ title: str | None = None,
+ icons: bool = False,
+) -> dict[str, Any]:
+ """A file the analyst opened, as a layer of this case.
+
+ Reaches no network unless `icons` was ticked *and* the file points its
+ pictograms at web addresses — which is why the tick defaults to off here and
+ on for a subscription: opening a file off this machine does not inherently
+ need the network, and following a link does.
+ """
+ parsed = parse(data, filename=filename, title=title or "")
+ summary = parsed["summary"]
+ name = _free_name(case, title or summary["title"])
+ spec = {
+ "azimut_layer": SPEC_VERSION,
+ "title": summary["title"],
+ "source": {"kind": "file", "name": filename, "format": summary["format"]},
+ "enabled": True,
+ "hidden": [],
+ # What the analyst asked for at import, kept so a refresh composes the
+ # same layer again rather than a differently dressed one.
+ "source_icons": bool(icons),
+ "created_at": _now(),
+ "updated_at": _now(),
+ "summary": summary,
+ "snapshot": _store(case, name, data, parsed, icons=bool(icons)),
+ }
+ _write_spec(case, name, spec)
+ _file_entity(case, name, spec)
+ return row(name, spec)
+
+
+def subscribe(
+ case: "Case",
+ url: str,
+ *,
+ title: str | None = None,
+ on_open: bool = True,
+ icons: bool = True,
+) -> dict[str, Any]:
+ """A URL the analyst followed. The one place this feature reaches out."""
+ address = str(url or "").strip()
+ if not address.lower().startswith(("http://", "https://")):
+ raise LayerError("a subscribed layer needs an http or https address")
+ data, filename = fetch(address)
+ parsed = parse(data, filename=filename, title=title or "")
+ summary = parsed["summary"]
+ name = _free_name(case, title or summary["title"])
+ spec = {
+ "azimut_layer": SPEC_VERSION,
+ "title": summary["title"],
+ "source": {
+ "kind": "url",
+ "url": address,
+ "feed": feed_url(address),
+ "name": filename,
+ "format": summary["format"],
+ "my_maps": bool(my_maps_mid(address)),
+ },
+ # Refreshing on case open is what "subscribed" means; turning it off
+ # leaves a layer that only moves when the analyst presses Refresh.
+ "refresh": {"on_open": bool(on_open)},
+ "enabled": True,
+ "hidden": [],
+ "source_icons": bool(icons),
+ "created_at": _now(),
+ "updated_at": _now(),
+ "summary": summary,
+ "snapshot": _store(case, name, data, parsed, icons=bool(icons)),
+ }
+ _write_spec(case, name, spec)
+ _file_entity(case, name, spec)
+ return row(name, spec)
+
+
+def refresh(case: "Case", name: str) -> dict[str, Any]:
+ """Fetch a subscribed layer again and replace its snapshot if it moved.
+
+ An unchanged feed rewrites nothing: same bytes, same sha256, and the row
+ only learns that it was checked. A fetch that fails leaves the last snapshot
+ exactly where it was — the layer stays on the map, saying how old it is.
+ """
+ spec = _read_spec(case, name)
+ source = spec.get("source") or {}
+ if source.get("kind") != "url":
+ raise LayerError("this layer came from a file, so there is nothing to refresh")
+
+ data, _ = fetch(str(source.get("url") or ""))
+ snapshot = spec.get("snapshot") or {}
+ now = _now()
+ if digest(data) == snapshot.get("sha256"):
+ spec["snapshot"] = {**snapshot, "checked_at": now}
+ else:
+ parsed = parse(data, filename=_source_name(spec), title=spec.get("title", ""))
+ spec["summary"] = parsed["summary"]
+ spec["snapshot"] = {
+ **_store(case, name, data, parsed, icons=bool(spec.get("source_icons"))),
+ "checked_at": now,
+ }
+ # A category the source has since dropped is no longer a thing to hide.
+ live = {entry["name"] for entry in parsed["summary"]["categories"]}
+ spec["hidden"] = [name_ for name_ in spec.get("hidden") or [] if name_ in live]
+ spec["updated_at"] = now
+ _write_spec(case, name, spec)
+ return row(name, spec)
+
+
+def update(
+ case: "Case",
+ name: str,
+ *,
+ enabled: bool | None = None,
+ hidden: list[str] | None = None,
+ on_open: bool | None = None,
+ title: str | None = None,
+) -> dict[str, Any]:
+ """What the analyst set on the row: the switch, the legend, the policy."""
+ spec = _read_spec(case, name)
+ if enabled is not None:
+ spec["enabled"] = bool(enabled)
+ if hidden is not None:
+ live = {entry["name"] for entry in (spec.get("summary") or {}).get("categories", [])}
+ spec["hidden"] = sorted({str(entry) for entry in hidden} & live)
+ if on_open is not None and (spec.get("source") or {}).get("kind") == "url":
+ spec["refresh"] = {**(spec.get("refresh") or {}), "on_open": bool(on_open)}
+ if title:
+ spec["title"] = _text(title, MAX_NAME) or spec["title"]
+ spec["updated_at"] = _now()
+ _write_spec(case, name, spec)
+ if title:
+ entity = case.find_entity(attr="spec", value=layout.layer_spec_rel(name))
+ if entity:
+ case.update_entity(entity["id"], {"label": spec["title"]})
+ return row(name, spec)
+
+
+def listing(case: "Case") -> list[dict[str, Any]]:
+ """Every layer this case holds, newest first."""
+ rows = []
+ for path in sorted(case.subdir(layout.LAYERS_DIR).glob("*.json")):
+ try:
+ rows.append(row(path.stem, _read_spec(case, path.stem)))
+ except LayerError:
+ continue
+ rows.sort(key=lambda entry: entry.get("created_at") or "", reverse=True)
+ return rows
+
+
+def read(case: "Case", name: str) -> dict[str, Any]:
+ return row(name, _read_spec(case, name))
+
+
+def row(name: str, spec: dict[str, Any]) -> dict[str, Any]:
+ """One layer as the panel reads it.
+
+ Freshness is computed rather than stored: a snapshot does not become stale by
+ being written to, it becomes stale by sitting there.
+ """
+ snapshot = spec.get("snapshot") or {}
+ summary = spec.get("summary") or {}
+ source = spec.get("source") or {}
+ at = str(snapshot.get("checked_at") or snapshot.get("at") or "")
+ return {
+ "name": name,
+ "title": spec.get("title") or name,
+ "source": source,
+ "enabled": bool(spec.get("enabled", True)),
+ "hidden": list(spec.get("hidden") or []),
+ "refresh": spec.get("refresh") or {},
+ "features": int(summary.get("features") or 0),
+ "categories": summary.get("categories") or [],
+ "bbox": summary.get("bbox"),
+ "format": summary.get("format") or source.get("format") or "",
+ # How many of the source's own pictograms are stored, which is also what
+ # tells the map whether to ask for any: zero and it draws its own shapes.
+ "icons": int(snapshot.get("icons") or 0),
+ "sha256": snapshot.get("sha256") or "",
+ "bytes": int(snapshot.get("bytes") or 0),
+ "fetched_at": snapshot.get("at") or "",
+ "checked_at": at,
+ "stale": source.get("kind") == "url" and _stale(at),
+ "created_at": spec.get("created_at") or "",
+ "updated_at": spec.get("updated_at") or "",
+ "spec": layout.layer_spec_rel(name),
+ }
+
+
+def _stale(stamp: str) -> bool:
+ """Whether a subscribed snapshot is old enough that the row must say so.
+
+ A local file is never stale: it is exactly what the analyst opened, and it
+ was never going to change on its own.
+ """
+ if not stamp:
+ return True
+ try:
+ at = datetime.strptime(stamp, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+ except ValueError:
+ return True
+ return datetime.now(timezone.utc) - at > timedelta(hours=FRESH_FOR_HOURS)
+
+
+def _file_entity(case: "Case", name: str, spec: dict[str, Any]) -> str:
+ """The layer in the graph: one node, no edges.
+
+ It is an entity so that the Trash, the bundle and the artifact registry
+ answer for it the way they answer for everything else a case holds. It states
+ nothing about the case, which is why nothing links to it.
+ """
+ rel = layout.layer_spec_rel(name)
+ existing = case.find_entity(attr="spec", value=rel)
+ if existing:
+ case.update_entity(existing["id"], {"label": spec["title"]})
+ return str(existing["id"])
+ source = spec.get("source") or {}
+ attrs = {"spec": rel, "format": spec.get("summary", {}).get("format", "")}
+ if source.get("kind") == "url":
+ attrs["source_url"] = source.get("url", "")
+ return str(case.add_entity(ENTITY_TYPE, spec["title"], attrs=attrs, by="map-layers")["id"])
+
+
+# ---------------------------------------------------------------------------
+# The one network call
+# ---------------------------------------------------------------------------
+
+
+def fetch(url: str) -> tuple[bytes, str]:
+ """Read a remote source, bounded, and say what it was called.
+
+ Nothing here runs on a timer. This is reached from adding a subscription,
+ from pressing Refresh, and from opening a case that holds an enabled layer
+ set to refresh on open — three acts, all of them the analyst's.
+ """
+ address = feed_url(url)
+ if not address.lower().startswith(("http://", "https://")):
+ raise LayerFetchError("a subscribed layer needs an http or https address")
+ try:
+ with httpx.stream(
+ "GET",
+ address,
+ timeout=FETCH_TIMEOUT,
+ follow_redirects=True,
+ headers={"User-Agent": USER_AGENT},
+ ) as response:
+ response.raise_for_status()
+ declared = response.headers.get("content-length")
+ if declared and declared.isdigit() and int(declared) > MAX_FETCH_BYTES:
+ raise LayerFetchError(
+ f"that source is {_megabytes(int(declared))} — the limit is "
+ f"{_megabytes(MAX_FETCH_BYTES)}"
+ )
+ chunks: list[bytes] = []
+ total = 0
+ for chunk in response.iter_bytes():
+ total += len(chunk)
+ if total > MAX_FETCH_BYTES:
+ raise LayerFetchError(
+ f"that source is over {_megabytes(MAX_FETCH_BYTES)}"
+ )
+ chunks.append(chunk)
+ name = _filename(response.headers.get("content-disposition"), address)
+ return b"".join(chunks), name
+ except httpx.HTTPStatusError as exc:
+ raise LayerFetchError(_status_reason(exc, address)) from exc
+ except httpx.HTTPError as exc:
+ raise LayerFetchError(f"could not reach that source: {exc}") from exc
+
+
+def _status_reason(exc: "httpx.HTTPStatusError", address: str) -> str:
+ """Why it failed, in the words the analyst can act on.
+
+ My Maps is the case worth spelling out: a map that is not shared publicly
+ answers exactly like a map that does not exist, and "404" would send someone
+ looking for a typo instead of at the sharing settings.
+ """
+ code = exc.response.status_code
+ if MY_MAPS_FEED.split("?", 1)[0] in address and code in (401, 403, 404):
+ return (
+ "Google would not serve that map. It has to be shared publicly — "
+ "open it in My Maps, then Share, then anyone with the link."
+ )
+ return f"that source answered {code}"
+
+
+def _filename(disposition: str | None, address: str) -> str:
+ """What to call what came back, for the format sniff's benefit only."""
+ match = re.search(r'filename\*?=(?:UTF-8\'\')?"?([^";]+)', str(disposition or ""))
+ if match:
+ return match.group(1).strip()
+ path = str(address).split("?", 1)[0].rstrip("/")
+ return path.rsplit("/", 1)[-1] if "/" in path else ""
diff --git a/src/azimut/engine/satellite.py b/src/azimut/engine/satellite.py
index 00ffc2f..f4d88a9 100644
--- a/src/azimut/engine/satellite.py
+++ b/src/azimut/engine/satellite.py
@@ -310,6 +310,34 @@ def _drop_stated(
case.remove_link(link["id"])
+def _sweep_point(
+ case: Case, proof_id: str, place_id: str, keep: list[dict[str, Any]]
+) -> None:
+ """Take the point off everything a save posed on it, bar the material named.
+
+ **Read from the point, not from the chain.** The material is what the proof
+ rests on *now*, so walking it reaches nothing a previous save posed and this
+ one dropped: swapping the footage for another clip left the old one standing
+ on the place, and the map went on showing a video the proof no longer rests
+ on. What a re-save has to undo is read off the place, where the edges are.
+
+ Scoped the way :func:`_drop_stated` is — only the roads a proof files by, so a
+ camera's EXIF and the analyst's own hand keep their answer — and only ever
+ called for a point no other proof concludes on, since the composition speaks
+ for itself alone. The proof's own edge is not this sweep's to take: withdrawing
+ it is the caller's decision, restating it is unconditional.
+ """
+ held = {entity["id"] for entity in keep} | {proof_id}
+ stale: list[str] = []
+ for link in case.links_of(place_id):
+ if link["to"] != place_id or link["type"] not in PLACE_VERBS:
+ continue
+ if link["from"] not in held and link["from"] not in stale:
+ stale.append(link["from"])
+ for entity_id in stale:
+ _drop_stated(case, entity_id, place_id, PLACE_VERBS, POINT_ROADS)
+
+
def _withdraw_point(
case: Case, proof_id: str, place_id: str, material: list[dict[str, Any]]
) -> None:
@@ -318,8 +346,7 @@ def _withdraw_point(
_drop_stated(case, proof_id, place_id, PLACE_VERBS, None)
if shared:
return
- for entity in material:
- _drop_stated(case, entity["id"], place_id, PLACE_VERBS, POINT_ROADS)
+ _sweep_point(case, proof_id, place_id, [])
def _state_point(
@@ -374,11 +401,19 @@ def _state_point(
and an audio file drops the edge ``shows`` would refuse. A point another proof
still concludes on is left alone (:func:`_other_proof_states`) — the answer
being restated is this proof's, and it does not speak for that one.
+
+ **And the material is restated too, not only its verb** (:func:`_sweep_point`).
+ Swapping the footage for another clip keeps the point, so nothing here withdraws
+ it — and the chain this walks no longer holds the old video, so nothing here
+ reached it either. It stayed on the map, under a proof that had stopped resting
+ on it.
"""
verb = links.LOCATED_AT if pov else links.DEPICTS
kinds = ("image", "video", "audio") if pov else ("image", "video")
shared = _other_proof_states(case, place_id, proof_id)
case.add_link(proof_id, place_id, links.DEPICTS, by=by, unique=True)
+ if not shared:
+ _sweep_point(case, proof_id, place_id, material)
for entity in material:
wanted: str | None = None
if entity["type"] == "capture":
@@ -1106,6 +1141,16 @@ PLACEMENT_NODES = 200
#: Points one entity reports. Fifteen distinct placements is a case already
#: contradicting itself; past that the panel is a wall rather than a reading.
PLACEMENT_LIMIT = 15
+#: The types a point travels *through*: the material itself, and the proof composed
+#: from it. Everything else in the chain is a document that **collects** files rather
+#: than one the pixels pass through — a post publishing two clips, a note citing
+#: three, an Inspect session holding a morning's work. Two videos in one post were
+#: published together, which says nothing about where either was filmed, so walking
+#: through it put each on the other's geolocation and the map counted two.
+#:
+#: Nothing is lost by stopping there: the two types that carry a point inside a chain
+#: are the capture and the proof (:func:`_entity_points`), and both are on this list.
+PLACEMENT_THROUGH = ("media", "capture", "proof")
def _point(lat: Any, lon: Any) -> dict[str, float] | None:
@@ -1165,6 +1210,12 @@ def placements(
Stopping there is also what keeps a video to its own argument: the capture behind
its proof is reached, the second proof that happens to reuse that capture is not.
+ **And the walk only crosses material** (:data:`PLACEMENT_THROUGH`). A post that
+ published two clips, a note citing three, an Inspect session holding a morning's
+ work: the chain runs through them, but being collected together says nothing
+ about where either file was filmed. Crossed anyway, each clip landed on the
+ other's geolocation and the map drew two.
+
Points are deduplicated on the exact pair, never on a rounded one: two captures
of the same roof are metres apart, and merging them would assert they are one
place, which is the analyst's call and not a rounding. The nearest hop wins a
@@ -1220,6 +1271,8 @@ def placements(
continue # this artifact is the placement; what it was made from is not
if depth == PLACEMENT_DEPTH:
continue
+ if node["id"] != entity_id and node.get("type") not in PLACEMENT_THROUGH:
+ continue # a document collects files; it does not carry a point across them
for link in case.links_of(node["id"]):
if link["type"] not in links.CHAIN_TYPES:
continue
diff --git a/src/azimut/engine/wayback.py b/src/azimut/engine/wayback.py
index 0382d1d..7e3ec2d 100644
--- a/src/azimut/engine/wayback.py
+++ b/src/azimut/engine/wayback.py
@@ -9,9 +9,10 @@ picks the basemap or opens its picker (local-first):
- **The release list** (`CONFIG_URL`), one JSON document naming every release,
its publication date and its metadata service.
- **The tilemap**, which answers for one tile and one release which release
- that tile's pixels were actually published in. Walking it backwards is how
- the releases that changed a point are found without downloading a tile per
- release, the same walk Esri's own Wayback app makes.
+ that tile's pixels were actually published in. Walking it backwards shortlists
+ the releases that touched a point without reading every release, the same walk
+ Esri's own Wayback app makes. It answers in bytes, not in ground, so the
+ shortlist is then settled on the pixels: one tile per candidate, compared.
- **The metadata service** of each release, which says when the pixels under a
point were acquired and by which sensor. A release date is when Esri
published the mosaic, which can be years after the picture was taken.
@@ -25,6 +26,7 @@ Release tiles never change once published, which is why caching them is safe.
from __future__ import annotations
import hashlib
+import io
import re
import threading
import time
@@ -34,6 +36,8 @@ from datetime import datetime, timezone
from typing import Any, Callable
import httpx
+import numpy as np
+from PIL import Image
BASE_ID = "esri-wayback"
VARIANT_SEP = "~"
@@ -67,9 +71,29 @@ _METADATA_MAX_ZOOM = 23
_METADATA_LAST_LAYER = 13
# How many metadata questions go out side by side during a walk.
METADATA_WORKERS = 12
+# …and how many tiles, which the walk reads one per candidate release.
+TILE_WORKERS = 8
# Tiles are asked for at the view zoom, and World Imagery is offered to z19.
MAX_ZOOM = 19
+# A tile is compared as a 32x32 grey thumbnail: eight pixels of the tile to a
+# cell, which is past JPEG's own noise and still fine enough to see a building.
+_THUMB_SIDE = 32
+# The cells are standardised — mean nought, spread one — before they are
+# compared, so a release that only re-toned one acquisition compares equal to
+# it. What is left is structure, and these two say how much of it may differ
+# and still be the same picture: a cell counts as unchanged within this much of
+# the tile's own spread…
+_CELL_TOLERANCE = 0.7
+# …and this much of the thumbnail may exceed it. Five cells of 1024 is a patch
+# some 7% of the tile across — at the zoom a walk runs at, a roof. Measured
+# against re-encoding, sharpening and a hard gamma over one acquisition, none
+# of which reaches half of it, and a new roof, which passes it twice over.
+_CHANGED_CELLS = 0.005
+# Below this spread a tile carries no structure — open sea, cloud, no data —
+# and standardising it would stretch sensor noise into structure.
+_FLAT_SPREAD = 4.0
+
@dataclass(frozen=True)
class Release:
@@ -171,6 +195,40 @@ class Change:
source: str | None
+@dataclass(frozen=True)
+class _Picture:
+ """One release's tile at the walked point, in the forms it is compared in."""
+
+ digest: str
+ cells: np.ndarray | None # the standardised thumbnail, None when it will not decode
+
+
+def _thumbnail(content: bytes) -> np.ndarray | None:
+ """A tile as a standardised grey thumbnail, or None when it will not decode."""
+ try:
+ with Image.open(io.BytesIO(content)) as image:
+ grey = image.convert("L").resize(
+ (_THUMB_SIDE, _THUMB_SIDE), Image.Resampling.BILINEAR
+ )
+ cells = np.asarray(grey, dtype=np.float32)
+ except Exception:
+ return None
+ spread = max(float(cells.std()), _FLAT_SPREAD)
+ return (cells - float(cells.mean())) / spread
+
+
+def _same_picture(one: _Picture | None, other: _Picture | None) -> bool:
+ """Whether two releases published the same picture of this point."""
+ if one is None or other is None:
+ return False # a tile that could not be read is never a twin
+ if one.digest == other.digest:
+ return True
+ if one.cells is None or other.cells is None:
+ return False
+ apart = np.abs(one.cells - other.cells) > _CELL_TOLERANCE
+ return float(apart.mean()) <= _CHANGED_CELLS
+
+
def local_changes(
lat: float,
lon: float,
@@ -183,11 +241,12 @@ def local_changes(
Starts from the newest release and asks the tilemap which release that
tile really comes from, then continues from the release before that one,
until a release has no tile there. What the tilemap calls a change is a
- change of bytes, and Esri republishes the same picture often: re-encoded
- (neighbours of equal size, compared by content) or re-processed (a new
- colour balance over the same acquisition, compared by the date and sensor
- each release's metadata states). Either way the release that first
- published the picture is the one kept.
+ change of bytes, and Esri republishes the same picture far more often than
+ the ground under it moves: re-encoded, or re-processed under a new colour
+ balance. So the pixels themselves settle it — every candidate's tile is
+ read and compared with the one kept before it — and the metadata each
+ release states (the acquisition date and the sensor) merges what is left.
+ Either way the release that first published the picture is the one kept.
One pooled connection carries the whole walk: a fresh TLS handshake per
step made a ten-change point take most of a minute.
@@ -220,7 +279,7 @@ def _walk_changes(lat: float, lon: float, zoom: int, fetch: Callable[..., Any])
if key in _changes:
return _changes[key]
- found: list[tuple[int, int]] = []
+ found: list[int] = []
current = listed[0].number
for _ in range(MAX_STEPS):
response = fetch(TILEMAP_URL.format(release=current, z=z, row=row, col=col))
@@ -233,49 +292,36 @@ def _walk_changes(lat: float, lon: float, zoom: int, fetch: Callable[..., Any])
chosen = int(select[0]) if select and str(select[0]).isdigit() else current
if chosen not in order:
break # a release the list does not know: stop rather than guess its date
- size = answer.get("size") or [0]
- if not found or found[-1][0] != chosen:
- found.append((chosen, int(size[0] or 0)))
+ if not found or found[-1] != chosen:
+ found.append(chosen)
following = order[chosen] + 1
if following >= len(listed):
break
current = listed[following].number
- def read_digest(number: int) -> str | None:
- """The tile's hash, or None when it cannot be read: an unknown is never
- a twin, so a dropped connection keeps a change rather than losing it."""
+ def read_picture(number: int) -> _Picture | None:
+ """The release's tile here, or None when it cannot be read: an unknown is
+ never a twin, so a dropped connection keeps a change rather than losing it."""
for _attempt in (1, 2):
try:
reply = fetch(tiles.tile_url(tile_url(number), z, col, row))
reply.raise_for_status()
- return hashlib.sha256(reply.content).hexdigest()
+ return _Picture(hashlib.sha256(reply.content).hexdigest(), _thumbnail(reply.content))
except Exception:
continue
return None
- # Only a run of neighbours sharing one size is ever compared, so those
- # tiles are read up front and side by side rather than one per comparison.
- twins = {
- found[i][0]
- for i in range(len(found))
- for j in (i - 1, i + 1)
- if 0 <= j < len(found) and found[i][1] and found[i][1] == found[j][1]
- }
- with ThreadPoolExecutor(max_workers=6) as pool:
- digests = dict(zip(twins, pool.map(read_digest, twins)))
-
- def twin(one: int, other: int) -> bool:
- for number in (one, other):
- if number not in digests:
- digests[number] = read_digest(number)
- return digests[one] is not None and digests[one] == digests[other]
+ # Every candidate is compared by its pixels, so all of them are read up
+ # front and side by side rather than one per comparison.
+ with ThreadPoolExecutor(max_workers=TILE_WORKERS) as pool:
+ pictures = dict(zip(found, pool.map(read_picture, found)))
- distinct: list[tuple[int, int]] = []
- for number, size in reversed(found): # oldest first, so the older twin stays
+ distinct: list[int] = []
+ for number in reversed(found): # oldest first, so the older twin stays
previous = distinct[-1] if distinct else None
- if previous and size and previous[1] == size and twin(previous[0], number):
+ if previous is not None and _same_picture(pictures[previous], pictures[number]):
continue
- distinct.append((number, size))
+ distinct.append(number)
# What each picture is, asked at the middle of the tile the walk read, so
# every point of that tile gets the same answer the cache will give it.
@@ -292,14 +338,13 @@ def _walk_changes(lat: float, lon: float, zoom: int, fetch: Callable[..., Any])
continue
return {} # unknown, which never merges two pictures
- numbers = [number for number, _ in distinct]
# The metadata service is the slow one, a couple of seconds a question, so
# a whole history is asked at once rather than six at a time.
with ThreadPoolExecutor(max_workers=METADATA_WORKERS) as pool:
- described = list(pool.map(describe, numbers))
+ described = list(pool.map(describe, distinct))
kept: list[tuple[Change, tuple[str, str] | None]] = []
- for number, attrs in zip(numbers, described): # still oldest first
+ for number, attrs in zip(distinct, described): # still oldest first
acquired = _day(attrs.get("SRC_DATE2"))
sensor = str(attrs.get("SRC_DESC") or "")
picture = (acquired, sensor) if acquired else None
diff --git a/src/azimut/layout.py b/src/azimut/layout.py
index 960a880..34771d9 100644
--- a/src/azimut/layout.py
+++ b/src/azimut/layout.py
@@ -58,6 +58,13 @@ COMPARE_DIR = ".compare"
ANALYSIS_DIR = ".analysis"
#: Saved Grid Search state.
SEARCH_DIR = ".search"
+#: Map layers the analyst added themselves: a file they opened, or a URL they
+#: subscribed to. Hidden because they did not author the data — the row in the
+#: Layers panel is where it is worked with, and it offers to reveal the file.
+LAYERS_DIR = ".layers"
+#: The parsed GeoJSON a layer is drawn from. Derived from the snapshot beside
+#: it, so it is dropped on delete and rebuilt on demand rather than carried.
+LAYER_CACHE_DIR = ".cache"
#: Machinery that belongs to a visible sibling: `media/.meta/` holds sidecars,
#: `proofs/.meta/` holds the editable specs and pasted assets.
META_DIR = ".meta"
@@ -82,6 +89,7 @@ CASE_SUBDIRS = (
COMPARE_DIR,
ANALYSIS_DIR,
SEARCH_DIR,
+ LAYERS_DIR,
)
#: Deleted artifacts wait here, hidden at the case root. Outside `CASE_SUBDIRS`
@@ -473,6 +481,38 @@ def grid_rel(name: str) -> str:
return f"{SEARCH_DIR}/{name}.json"
+def layer_spec_rel(name: str) -> str:
+ """What a map layer is: where it came from, how it refreshes, how it draws."""
+ return f"{LAYERS_DIR}/{name}.json"
+
+
+def layer_snapshot_rel(name: str) -> str:
+ """The bytes as they arrived, under one extension whatever the format.
+
+ The original filename and media type are recorded in the spec instead. A
+ snapshot named after its source would collide with the spec the moment a
+ GeoJSON arrived as `.json`, and the suffix is the one thing about the file
+ that nothing reads: the format is sniffed from the bytes.
+ """
+ return f"{LAYERS_DIR}/{name}.src"
+
+
+def layer_icons_rel(name: str) -> str:
+ """The source's own pictograms, composed once and stored beside the snapshot.
+
+ A zip rather than a directory: a layer owns one more path whatever the number
+ of icons in it, so the Trash moves one thing, the bundle carries one thing,
+ and a My Maps with forty styles costs the path budget the same as one with
+ two.
+ """
+ return f"{LAYERS_DIR}/{name}.icons"
+
+
+def layer_cache_rel(name: str) -> str:
+ """The parsed GeoJSON the browser consumes, rebuilt from the snapshot."""
+ return f"{LAYERS_DIR}/{LAYER_CACHE_DIR}/{name}.geojson"
+
+
def content_dirs(root: Path) -> tuple[Path, ...]:
"""Every directory a case is born with.
@@ -486,6 +526,9 @@ def content_dirs(root: Path) -> tuple[Path, ...]:
media(root) / META_DIR,
subdir(root, "proofs") / META_DIR,
subdir(root, "sheets") / META_DIR,
+ # Born for the same reason: a derived cache created on first use would
+ # otherwise be one path an emptied case holds and a new one does not.
+ subdir(root, LAYERS_DIR) / LAYER_CACHE_DIR,
]
return tuple(dirs)
diff --git a/src/azimut/server.py b/src/azimut/server.py
index 93be4a7..f77710c 100644
--- a/src/azimut/server.py
+++ b/src/azimut/server.py
@@ -287,9 +287,9 @@ def create_app() -> FastAPI:
)
from .api import (
- analysis_views, analyzers, cases, compare, drafts, events, files, folders, ingest, inspect, media,
- notes, plates, proofimports, proofs, satellite, settings, sheetproofs, sheets,
- templates,
+ analysis_views, analyzers, cases, compare, drafts, events, files, folders, ingest, inspect,
+ maplayers, media, notes, plates, proofimports, proofs, satellite, settings, sheetproofs,
+ sheets, templates,
)
from .engine import sheets as sheet_engine
@@ -306,6 +306,7 @@ def create_app() -> FastAPI:
app.include_router(compare.router)
app.include_router(analyzers.router)
app.include_router(satellite.router)
+ app.include_router(maplayers.router)
app.include_router(proofs.router)
app.include_router(proofimports.router)
app.include_router(drafts.router)
diff --git a/tests/analyzerfixture.py b/tests/analyzerfixture.py
index bd704c0..cfbda38 100644
--- a/tests/analyzerfixture.py
+++ b/tests/analyzerfixture.py
@@ -136,6 +136,24 @@ def sea(rng_seed=3):
return bands
+def glinted_sea(rng_seed=3):
+ """Sea under sun glint, as the Bab-el-Mandeb read on 2026-09-16.
+
+ Glint adds the same reflectance to every band, so near and short-wave
+ infrared sit near 0.08 and NDWI collapses onto zero. The classification
+ still calls all of it water.
+ """
+ rng = np.random.default_rng(rng_seed)
+ bands = np.zeros((EDGE, EDGE, 4), np.uint8)
+ bands[:, :, 0] = np.clip(np.round((0.075 + rng.normal(0, 0.004, (EDGE, EDGE)))
+ * 255 * sentinel.BAND_GAIN), 1, 255)
+ bands[:, :, 1] = np.clip(np.round((0.086 + rng.normal(0, 0.004, (EDGE, EDGE)))
+ * 255 * sentinel.BAND_GAIN), 0, 255)
+ bands[:, :, 2] = rng.integers(118, 134, (EDGE, EDGE), dtype=np.uint8) # NDWI ≈ 0
+ bands[:, :, 3] = WATER
+ return bands
+
+
def hull(bands, px, py, width, height, swir=True):
"""A target on the sea. Without short-wave infrared it is a breaking wave."""
region = bands[at(px, py, width, height)]
diff --git a/tests/fullcase.py b/tests/fullcase.py
index efb9626..e26154b 100644
--- a/tests/fullcase.py
+++ b/tests/fullcase.py
@@ -18,6 +18,7 @@ from __future__ import annotations
import base64
import hashlib
import io
+import zipfile
from dataclasses import dataclass, field
from pathlib import Path
@@ -31,6 +32,39 @@ def _png(size: tuple[int, int] = (80, 60), color: tuple[int, int, int] = (120, 6
return buf.getvalue()
+def _kml() -> bytes:
+ """A small KML with one folder, which is one legend category and two marks.
+
+ Its mark points at an icon beside it, so the KMZ below has pictograms of its
+ own to compose — which is what puts a `.icons` companion in the full case
+ without any gate needing the network.
+ """
+ return (
+ '<?xml version="1.0" encoding="UTF-8"?>'
+ '<kml xmlns="http://www.opengis.net/kml/2.2"><Document><name>Checkpoints</name>'
+ '<Style id="red"><IconStyle><color>ff0000ff</color>'
+ "<Icon><href>images/gate.png</href></Icon>"
+ '<hotSpot x="0.5" xunits="fraction" y="0" yunits="fraction"/>'
+ "</IconStyle></Style>"
+ "<Folder><name>Roadblocks</name>"
+ "<Placemark><name>North gate</name><styleUrl>#red</styleUrl>"
+ "<Point><coordinates>2.3522,48.8566,0</coordinates></Point></Placemark>"
+ "<Placemark><name>Riverside</name>"
+ "<LineString><coordinates>2.30,48.85 2.32,48.86</coordinates></LineString>"
+ "</Placemark></Folder></Document></kml>"
+ ).encode()
+
+
+def _kmz() -> bytes:
+ """The same map, zipped with the icon it names. The whole of a layer's
+ pictograms without a byte leaving the machine."""
+ buf = io.BytesIO()
+ with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as archive:
+ archive.writestr("doc.kml", _kml())
+ archive.writestr("images/gate.png", _png((24, 24), (255, 255, 255)))
+ return buf.getvalue()
+
+
@dataclass
class FullCase:
"""What was planted, so a gate can name it rather than rediscover it."""
@@ -56,6 +90,11 @@ class FullCase:
sheet_meta: str = "" # the sidecar beside it
place_id: str = ""
grid: str = ""
+ layer_id: str = ""
+ layer: str = "" # the spec, which is what the entity points at
+ layer_snapshot: str = "" # the bytes as received, which travel with it
+ layer_icons: str = "" # the source's own pictograms, which travel too
+ layer_cache: str = "" # the parsed copy, which does not
person_id: str = ""
org_id: str = ""
entity_photo_id: str = ""
@@ -419,6 +458,27 @@ def build_full_case(client, name: str = "Full case") -> FullCase:
assert grid.status_code == 200, grid.text
full.grid = f".search/{grid.json()['name']}.json"
+ # -- a map layer: somebody else's file, drawn over the case's own map ------
+ # Four files with two different answers to "does this travel?", which is why
+ # it is here: the spec, the snapshot and the composed icons are the case's,
+ # the parsed copy is a cache the gates must see dropped rather than carried.
+ # A KMZ rather than a KML so the icons are real without a fetch.
+ layer = client.post(
+ f"/api/cases/{case_id}/map-layers/upload",
+ files={"file": ("checkpoints.kmz", io.BytesIO(_kmz()), "application/vnd.google-earth.kmz")},
+ data={"title": "Checkpoints", "icons": "true"},
+ )
+ assert layer.status_code == 200, layer.text
+ assert layer.json()["icons"] == 1, "the KMZ's own pictogram was composed"
+ layer_name = layer.json()["name"]
+ full.layer = layout.layer_spec_rel(layer_name)
+ full.layer_snapshot = layout.layer_snapshot_rel(layer_name)
+ full.layer_icons = layout.layer_icons_rel(layer_name)
+ full.layer_cache = layout.layer_cache_rel(layer_name)
+ full.layer_id = client.get(
+ f"/api/cases/{case_id}/entities/lookup", params={"attr": "spec", "value": full.layer}
+ ).json()["entity"]["id"]
+
# -- the graph as the analyst arranged it ---------------------------------
# Not an artifact and not an assertion: where a node was dragged to, in one
# reading. Planted here so the trash and bundle gates cover it — a pin has to
diff --git a/tests/legacy_case.py b/tests/legacy_case.py
index 33350df..034d9b6 100644
--- a/tests/legacy_case.py
+++ b/tests/legacy_case.py
@@ -168,7 +168,7 @@ def _rewind_hidden_layout(case: Case) -> None:
#: Content directories the layout gained after the `azimut/` wrapper shipped. They
#: postdate every unwrapped checkpoint, so a rewind removes them rather than putting
#: them at the case root where they never were.
-POST_WRAPPER_DIRS = frozenset({"sheets", ".compare", ".analysis"})
+POST_WRAPPER_DIRS = frozenset({"sheets", ".compare", ".analysis", ".layers"})
def rewind_case(case: Case, schema: int) -> None:
diff --git a/tests/test_analyzers.py b/tests/test_analyzers.py
index de85e5d..9f8b7d5 100644
--- a/tests/test_analyzers.py
+++ b/tests/test_analyzers.py
@@ -33,6 +33,7 @@ from analyzerfixture import (
code,
fire_frame,
flame,
+ glinted_sea,
hull,
index_byte,
index_frame,
@@ -427,6 +428,46 @@ def test_a_coastline_is_not_a_vessel(client, copernicus):
assert run(client, copernicus, body)["count"] == 0
+def test_glint_does_not_turn_the_sea_into_land(client, copernicus):
+ """Glint puts every band near 0.08 and leaves NDWI on zero, so an index read
+ alone called two thirds of the Bab-el-Mandeb dry and the strait became one
+ component of land. The classification is asked too, and either saying water
+ is enough."""
+ body = sentinel_input("boats")
+ water = glinted_sea()
+ hull(water, 200, 200, 8, 4)
+ seed(body, after=water)
+ saved = run(client, copernicus, body)
+ assert saved["status"] == "ready", saved
+ assert saved["count"] == 1, [r["coordinates"] for r in saved["results"]]
+
+
+def test_sediment_flattens_the_index_and_the_classification_carries_it(client, copernicus):
+ """Suspended matter does to the index what glint does: pushes it onto zero.
+
+ The rule is not "this one scene", it is that a weak index is not a dry one.
+ """
+ body = sentinel_input("boats")
+ water = sea()
+ water[:, :, 2] = 120 # NDWI ≈ -0.06, still water
+ hull(water, 250, 250, 8, 4)
+ seed(body, after=water)
+ assert run(client, copernicus, body)["count"] == 1
+
+
+def test_ground_the_classification_calls_water_is_still_ground(client, copernicus):
+ """Sen2Cor calls deep shadow and dark ground water, and taking its word
+ there would put vessel candidates on land. It is believed where the index is
+ weak, never where the index plainly says dry."""
+ body = sentinel_input("boats")
+ desert = surface(0.30, 0.35, 0.30, WATER) # the classification is wrong
+ desert[:, :, 2] = 40 # the index is not: NDWI ≈ -0.7
+ roof = desert[at(250, 250, 8, 4)]
+ roof[:, :, 0], roof[:, :, 1] = 255, 255 # something bright out there
+ seed(body, after=desert)
+ assert run(client, copernicus, body)["count"] == 0
+
+
def test_vessel_sweep_asks_for_one_date_and_never_for_a_reference(client, copernicus):
body = sentinel_input("boats")
water = sea()
@@ -535,6 +576,37 @@ def test_small_spots_are_found_where_everything_around_them_held_still(client, c
assert row["area"] < 500
+def test_a_granule_edge_is_not_a_spot(client, copernicus):
+ """One date ends mid-tile, and that is not a change in the ground.
+
+ The spot test measures a change against the change around it, so the ring
+ it reads has to hold only pixels the sweep can measure. With nodata in it,
+ a quiet tile cut by a granule edge produced a candidate the size of the cut.
+ """
+ before, after = surface(0.20, 0.30, 0.30), surface(0.20, 0.30, 0.30)
+ after[:, 300:] = 0 # the granule stops here
+ after[at(100, 100, 3, 3)] = code(0.05, 0.08, 0.08) # a real mark beside it
+ # Size All, so nothing is dropped for being too big to be a spot: the point
+ # is that the seam raises no candidate at all, not that one is filtered out.
+ body = sentinel_input("impacts", **SIZES["spots"]["all"])
+ seed(body, before, after)
+ saved = run(client, copernicus, body)
+ assert saved["status"] == "ready", saved
+ assert saved["count"] == 1, [(r["coordinates"], r["area"]) for r in saved["results"]]
+ assert saved["results"][0]["area"] < 500
+
+
+def test_a_cloud_edge_is_not_a_spot(client, copernicus):
+ """A masked cloud is missing ground, exactly as nodata is."""
+ before, after = surface(0.20, 0.30, 0.30), surface(0.20, 0.30, 0.30)
+ after[:, 300:] = code(0.75, 0.80, 0.70, CLOUD)
+ body = sentinel_input("impacts", **SIZES["spots"]["all"])
+ seed(body, before, after)
+ saved = run(client, copernicus, body)
+ assert saved["status"] == "ready", saved
+ assert saved["count"] == 0, [(r["coordinates"], r["area"]) for r in saved["results"]]
+
+
def test_a_mark_wider_than_its_window_still_reads_its_own_contrast(client, copernicus):
"""A median box the size of the target takes the target for its background.
diff --git a/tests/test_compare_api.py b/tests/test_compare_api.py
index 8814081..4e73652 100644
--- a/tests/test_compare_api.py
+++ b/tests/test_compare_api.py
@@ -177,6 +177,9 @@ def test_compare_session_roundtrip_rename_and_sidebar_delete(client):
lambda spec: spec.update(annotations=[{
"id": "x", "kind": "text", "colour": "#ffffff", "points": [[2, 48]], "text": " ",
}]),
+ lambda spec: spec.update(frame={"points": [[2, 48]]}),
+ lambda spec: spec.update(frame={"points": [[2, 48], [2, 48]]}),
+ lambda spec: spec.update(frame={"points": [[2, 48], [200, 48]]}),
lambda spec: spec.update(change_assist={"method": "ratio"}),
],
)
@@ -198,6 +201,16 @@ def test_compare_session_keeps_google_maps_js_as_a_reopenable_source(client):
assert loaded["spec"]["b"]["provider"] == "google-js"
+def test_compare_session_keeps_an_optional_export_frame_on_the_ground(client):
+ cid = _case(client, "Compare frame")
+ spec = _spec()
+ spec["frame"] = {"points": [[2.2945, 48.8584], [2.2961, 48.8572]]}
+
+ assert _save(client, cid, "Framed reading", spec).status_code == 200
+ loaded = client.get(f"/api/cases/{cid}/compare/sessions/Framed reading").json()
+ assert loaded["spec"]["frame"] == spec["frame"]
+
+
# -- which pairs a pixel reading is fair on --------------------------------------
diff --git a/tests/test_graph.py b/tests/test_graph.py
index 2dfbae7..f6f2046 100644
--- a/tests/test_graph.py
+++ b/tests/test_graph.py
@@ -169,7 +169,7 @@ def test_a_reading_of_the_case_leaves_out_what_the_analyst_wrote():
readings with no edit here."""
filing = entity_engine.types_with_role(entity_engine.ANNEX, entity_engine.DELIVERABLE)
assert filing == {"note", "sheet", "inspect-session", "compare-session", "post",
- "analysis-zones", "analysis-follow-up", "analysis-run"}
+ "analysis-zones", "analysis-follow-up", "analysis-run", "map-layer"}
for lens_id in ("all", "subjects", "ground", "claims"):
assert set(graph_engine.lens(lens_id).hides) == filing, lens_id
diff --git a/tests/test_layout.py b/tests/test_layout.py
index f0d69df..c834030 100644
--- a/tests/test_layout.py
+++ b/tests/test_layout.py
@@ -99,6 +99,10 @@ def _tool_relative(slug: int, media: int) -> dict[str, int]:
"session": len(layout.session_rel(longest_name)),
"compare session": len(layout.compare_session_rel(longest_name)),
"grid": len(layout.grid_rel(longest_name)),
+ "map layer spec": len(layout.layer_spec_rel(longest_name)),
+ "map layer snapshot": len(layout.layer_snapshot_rel(longest_name)),
+ "map layer icons": len(layout.layer_icons_rel(longest_name)),
+ "map layer cache": len(layout.layer_cache_rel(longest_name)),
"trash slot": len(f"{layout.TRASH_DIR}/") + TRASH_GROUP_ID + 1 + TRASH_SLOT,
}
@@ -228,11 +232,14 @@ def test_content_dirs_covers_every_subdir_and_its_meta(tmp_path: Path) -> None:
root = tmp_path / "a-case"
born = layout.content_dirs(root)
assert [d.name for d in born[: len(CASE_SUBDIRS)]] == list(CASE_SUBDIRS)
- # the `.meta/` directories are born too, so an emptied case matches a new one
+ # The `.meta/` directories are born too, and so is the one derived cache a
+ # tool keeps inside its own folder — an emptied case has to match a new one,
+ # and a directory created on first use would be one path apart.
assert set(born[len(CASE_SUBDIRS) :]) == {
layout.media(root) / layout.META_DIR,
layout.subdir(root, "proofs") / layout.META_DIR,
layout.subdir(root, "sheets") / layout.META_DIR,
+ layout.subdir(root, layout.LAYERS_DIR) / layout.LAYER_CACHE_DIR,
}
assert layout.trash(root).name not in CASE_SUBDIRS
diff --git a/tests/test_map_layers.py b/tests/test_map_layers.py
new file mode 100644
index 0000000..a7a07ae
--- /dev/null
+++ b/tests/test_map_layers.py
@@ -0,0 +1,998 @@
+"""Layers the analyst adds to a case's map.
+
+Three things this has to get right, and they are what the tests are grouped by:
+
+- **every format lands on one shape**, so the renderer never learns what a KML
+ is;
+- **a hostile file is refused with a sentence**, because the input is somebody
+ else's XML and somebody else's zip;
+- **the network boundary holds both ways** — it fetches when the analyst asks,
+ and it does not fetch on a listing, on a disabled layer, or when the snapshot
+ already on disk answers.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import zipfile
+
+import pytest
+from PIL import Image, ImageDraw
+
+import fullcase
+from azimut import layout
+from azimut.engine import artifacts, maplayers
+from azimut.workspace import Case
+
+# ---------------------------------------------------------------------------
+# Sources, small enough to read
+# ---------------------------------------------------------------------------
+
+KML = (
+ '<?xml version="1.0" encoding="UTF-8"?>'
+ '<kml xmlns="http://www.opengis.net/kml/2.2"><Document><name>Sightings</name>'
+ '<Style id="red"><IconStyle><color>ff0000ff</color></IconStyle></Style>'
+ '<StyleMap id="pair"><Pair><key>normal</key><styleUrl>#red</styleUrl></Pair>'
+ "<Pair><key>highlight</key><styleUrl>#other</styleUrl></Pair></StyleMap>"
+ "<Folder><name>Checkpoints</name>"
+ "<Placemark><name>North gate</name><description>&lt;b&gt;Seen&lt;/b&gt; twice</description>"
+ '<styleUrl>#pair</styleUrl><Point><coordinates>2.3522,48.8566,12</coordinates></Point>'
+ "</Placemark>"
+ "<Placemark><name>Wall</name>"
+ "<LineString><coordinates>2.30,48.85 2.32,48.86</coordinates></LineString></Placemark>"
+ "</Folder>"
+ "<Folder><name>Damage</name>"
+ "<Placemark><name>Warehouse</name><Polygon><outerBoundaryIs><LinearRing>"
+ "<coordinates>2.1,48.1 2.2,48.1 2.2,48.2 2.1,48.1</coordinates>"
+ "</LinearRing></outerBoundaryIs></Polygon></Placemark>"
+ "</Folder></Document></kml>"
+).encode()
+
+GEOJSON = json.dumps(
+ {
+ "type": "FeatureCollection",
+ "name": "Harbour",
+ "features": [
+ {
+ "type": "Feature",
+ "geometry": {"type": "Point", "coordinates": [2.35, 48.85]},
+ "properties": {"name": "Quay 4", "description": "Loading", "marker-color": "#f00"},
+ },
+ {
+ "type": "Feature",
+ "geometry": {"type": "LineString", "coordinates": [[2.3, 48.8], [2.4, 48.9]]},
+ "properties": {"title": "Approach"},
+ },
+ ],
+ }
+).encode()
+
+GPX = (
+ '<gpx version="1.1"><metadata><name>Patrol</name></metadata>'
+ '<wpt lat="48.10" lon="2.10"><name>Start</name><desc>First light</desc></wpt>'
+ '<trk><name>Run</name><trkseg><trkpt lat="48.10" lon="2.10"/>'
+ '<trkpt lat="48.20" lon="2.20"/></trkseg></trk></gpx>'
+).encode()
+
+
+def png(size: tuple[int, int] = (32, 32), colour: tuple[int, int, int] = (255, 255, 255)) -> bytes:
+ """A flat square. White by default, which is what a My Maps pictogram is:
+ the shape is in the file and the colour is in the style."""
+ buffer = io.BytesIO()
+ Image.new("RGBA", size, (*colour, 255)).save(buffer, "PNG")
+ return buffer.getvalue()
+
+
+def icon_kml(
+ href: str = "images/pin.png",
+ hotspot: str = '<hotSpot x="16" xunits="pixels" y="32" yunits="insetPixels"/>',
+ colour: str = "ff0000ff",
+) -> bytes:
+ """One placemark pointing at one pictogram, the way a My Maps writes it."""
+ return (
+ '<?xml version="1.0" encoding="UTF-8"?>'
+ '<kml xmlns="http://www.opengis.net/kml/2.2"><Document><name>Dressed</name>'
+ f'<Style id="pin"><IconStyle><color>{colour}</color><scale>1</scale>'
+ f"<Icon><href>{href}</href></Icon>{hotspot}</IconStyle></Style>"
+ "<Folder><name>Checkpoints</name>"
+ '<Placemark><name>North gate</name><styleUrl>#pin</styleUrl>'
+ "<Point><coordinates>2.35,48.85</coordinates></Point></Placemark>"
+ '<Placemark><name>Wall</name><styleUrl>#pin</styleUrl>'
+ "<LineString><coordinates>2.30,48.85 2.32,48.86</coordinates></LineString>"
+ "</Placemark></Folder></Document></kml>"
+ ).encode()
+
+
+def kmz(kml: bytes = KML, name: str = "doc.kml", extra: dict[str, bytes] | None = None) -> bytes:
+ buffer = io.BytesIO()
+ with zipfile.ZipFile(buffer, "w", zipfile.ZIP_DEFLATED) as archive:
+ archive.writestr(name, kml)
+ for member, data in (extra or {}).items():
+ archive.writestr(member, data)
+ return buffer.getvalue()
+
+
+def case_id(client) -> str:
+ return client.post("/api/cases", json={"name": "Layers"}).json()["id"]
+
+
+def add(
+ client, case_id: str, data: bytes, filename: str, title: str = "", icons: bool = False
+) -> dict:
+ response = client.post(
+ f"/api/cases/{case_id}/map-layers/upload",
+ files={"file": (filename, io.BytesIO(data), "application/octet-stream")},
+ data={"title": title, "icons": str(icons).lower()},
+ )
+ assert response.status_code == 200, response.text
+ return response.json()
+
+
+# ---------------------------------------------------------------------------
+# One shape out of four formats
+# ---------------------------------------------------------------------------
+
+
+ "data, filename",
+ [(KML, "s.kml"), (kmz(), "s.kmz"), (GEOJSON, "h.geojson"), (GPX, "p.gpx")],
+)
+def test_every_format_parses_to_the_same_normalised_shape(data, filename):
+ """Whatever it arrived as, a feature carries the same four fields and the
+ summary is the legend: one row per category, with a colour and a count."""
+ parsed = maplayers.parse(data, filename=filename)
+ summary = parsed["summary"]
+
+ assert parsed["geojson"]["type"] == "FeatureCollection"
+ assert summary["features"] == len(parsed["geojson"]["features"]) > 0
+ assert sum(entry["count"] for entry in summary["categories"]) == summary["features"]
+ assert summary["bbox"] and len(summary["bbox"]) == 4
+ for feature in parsed["geojson"]["features"]:
+ assert set(feature["properties"]) >= {"name", "description", "category", "colour"}
+ assert feature["geometry"]["type"] in {"Point", "LineString", "Polygon"}
+
+
+def test_a_kml_folder_is_a_legend_category():
+ """The whole of the grouping rule: a My Maps' layers *are* its folders, so a
+ folder is a legend row and hiding it hides exactly its features."""
+ summary = maplayers.parse(KML, filename="s.kml")["summary"]
+
+ assert [entry["name"] for entry in summary["categories"]] == ["Checkpoints", "Damage"]
+ assert [entry["count"] for entry in summary["categories"]] == [2, 1]
+ assert summary["categories"][0]["kinds"] == ["line", "point"]
+
+
+def test_a_kml_colour_is_honoured_through_its_style_map():
+ """`aabbggrr` with the alpha dropped, and the *normal* half of a StyleMap —
+ which is the one Google writes and the one the map draws."""
+ features = maplayers.parse(KML, filename="s.kml")["geojson"]["features"]
+
+ assert features[0]["properties"]["colour"] == "#ff0000"
+ assert maplayers.parse(GEOJSON, filename="h.geojson")["geojson"]["features"][0][
+ "properties"
+ ]["colour"] == "#ff0000"
+
+
+def test_a_description_arrives_as_text_rather_than_as_markup():
+ """A KML description is arbitrary HTML. The popup shows what the source says;
+ it does not render somebody else's markup inside the app."""
+ features = maplayers.parse(KML, filename="s.kml")["geojson"]["features"]
+
+ assert features[0]["properties"]["description"] == "Seen twice"
+
+
+def test_a_my_maps_table_keeps_one_row_per_line():
+ """A My Maps writes its columns as an HTML table. Stripped of its tags that
+ is one run-on sentence; kept as lines the popup can draw the labels the
+ source wrote."""
+ kml = _kml_with_description(
+ "&lt;table&gt;&lt;tr&gt;&lt;td&gt;code&lt;/td&gt;&lt;td&gt;UA&lt;/td&gt;&lt;/tr&gt;"
+ "&lt;tr&gt;&lt;td&gt;layer&lt;/td&gt;&lt;td&gt;OLD26&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;"
+ )
+ features = maplayers.parse(kml, filename="s.kml")["geojson"]["features"]
+
+ assert features[0]["properties"]["description"] == "code: UA\nlayer: OLD26"
+
+
+def test_a_link_keeps_the_address_it_pointed_at():
+ """The popup shows text, so an address living only in an `href` would be
+ lost — and the address is what the analyst opens next."""
+ kml = _kml_with_description(
+ "shelling &lt;a href=\"https://example.org/a/1\"&gt;source&lt;/a&gt;"
+ )
+ features = maplayers.parse(kml, filename="s.kml")["geojson"]["features"]
+
+ assert features[0]["properties"]["description"] == "shelling source https://example.org/a/1"
+
+
+def test_a_name_stays_one_line_whatever_markup_it_held():
+ """Only a description is allowed to arrive shaped: a name is a popup heading
+ and a category is a legend row."""
+ kml = _kml_with_description("x", name="North&lt;br&gt;gate")
+ features = maplayers.parse(kml, filename="s.kml")["geojson"]["features"]
+
+ assert features[0]["properties"]["name"] == "North gate"
+
+
+def _kml_with_description(description: str, name: str = "North gate") -> bytes:
+ return (
+ '<?xml version="1.0" encoding="UTF-8"?>'
+ '<kml xmlns="http://www.opengis.net/kml/2.2"><Document><name>Sightings</name>'
+ f"<Placemark><name>{name}</name><description>{description}</description>"
+ "<Point><coordinates>2.3522,48.8566</coordinates></Point>"
+ "</Placemark></Document></kml>"
+ ).encode()
+
+
+def test_a_geojson_is_one_category_named_after_itself():
+ """A plain FeatureCollection states no grouping, and guessing one out of
+ whichever property looks categorical would make the legend lie."""
+ summary = maplayers.parse(GEOJSON, filename="h.geojson")["summary"]
+
+ assert [entry["name"] for entry in summary["categories"]] == ["Harbour"]
+
+
+def test_a_gpx_is_grouped_by_what_its_elements_are():
+ summary = maplayers.parse(GPX, filename="p.gpx")["summary"]
+
+ assert sorted(entry["name"] for entry in summary["categories"]) == ["Tracks", "Waypoints"]
+
+
+def test_the_format_is_read_off_the_bytes_rather_than_the_extension():
+ """Files arrive renamed. A KML called `.geojson` draws rather than failing
+ on its first angle bracket."""
+ assert maplayers.sniff(KML, "sightings.geojson") == "kml"
+ assert maplayers.sniff(GEOJSON, "harbour.kml") == "geojson"
+ assert maplayers.sniff(kmz(), "whatever") == "kmz"
+
+
+# ---------------------------------------------------------------------------
+# What will not be read
+# ---------------------------------------------------------------------------
+
+
+def test_an_external_entity_is_refused_rather_than_resolved():
+ """The XXE: the stdlib parser would read the named file into the document."""
+ hostile = (
+ '<?xml version="1.0"?>'
+ '<!DOCTYPE kml [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>'
+ '<kml xmlns="http://www.opengis.net/kml/2.2"><Document><Placemark>'
+ "<name>&xxe;</name><Point><coordinates>1,1</coordinates></Point>"
+ "</Placemark></Document></kml>"
+ ).encode()
+
+ with pytest.raises(maplayers.LayerError) as refused:
+ maplayers.parse(hostile, filename="x.kml")
+ assert str(refused.value)
+
+
+def test_an_expansion_bomb_is_refused_before_it_expands():
+ """Billion laughs: ten nested entities, each ten copies of the last."""
+ entities = "".join(
+ f'<!ENTITY e{index} "{"&e" + str(index - 1) + ";" * 1 if index else "lol"}">'
+ for index in range(10)
+ )
+ hostile = (
+ f'<?xml version="1.0"?><!DOCTYPE kml [{entities}]>'
+ f"<kml><Document><Placemark><name>&e9;</name>"
+ f"<Point><coordinates>1,1</coordinates></Point></Placemark></Document></kml>"
+ ).encode()
+
+ with pytest.raises(maplayers.LayerError):
+ maplayers.parse(hostile, filename="x.kml")
+
+
+def test_a_file_over_the_size_limit_is_refused_with_the_limit_in_the_message():
+ oversized = b"{" + b" " * (maplayers.MAX_SOURCE_BYTES + 1)
+
+ with pytest.raises(maplayers.LayerError, match="limit"):
+ maplayers.parse(oversized, filename="big.geojson")
+
+
+def test_more_features_than_the_cap_is_refused_rather_than_truncated(monkeypatch):
+ """Never truncated: a layer drawing the first half of a file would be a map
+ making a claim about a place it had only partly read."""
+ monkeypatch.setattr(maplayers, "MAX_FEATURES", 3)
+ crowd = json.dumps(
+ {
+ "type": "FeatureCollection",
+ "features": [
+ {
+ "type": "Feature",
+ "geometry": {"type": "Point", "coordinates": [index / 100, 48]},
+ "properties": {},
+ }
+ for index in range(10)
+ ],
+ }
+ ).encode()
+
+ with pytest.raises(maplayers.LayerError, match="dataset"):
+ maplayers.parse(crowd, filename="crowd.geojson")
+
+
+def test_a_kmz_naming_a_file_outside_itself_is_refused():
+ """Zip-slip. Nothing is extracted to disk, but an archive built to escape
+ something is not one to read the contents of."""
+ with pytest.raises(maplayers.LayerError, match="outside itself"):
+ maplayers.parse(kmz(name="../../doc.kml"), filename="evil.kmz")
+
+
+def test_a_kmz_that_unpacks_far_past_its_size_is_refused(monkeypatch):
+ monkeypatch.setattr(maplayers, "MAX_COMPRESSION_RATIO", 2)
+ with pytest.raises(maplayers.LayerError, match="compressed"):
+ maplayers.parse(kmz(extra={"pad.bin": b"\0" * 100_000}), filename="bomb.kmz")
+
+
+def test_a_kmz_holding_no_kml_says_so():
+ with pytest.raises(maplayers.LayerError, match="no KML"):
+ maplayers.parse(kmz(name="readme.txt"), filename="x.kmz")
+
+
+def test_a_file_with_nothing_to_draw_is_refused_rather_than_drawn_empty():
+ empty = json.dumps({"type": "FeatureCollection", "features": []}).encode()
+
+ with pytest.raises(maplayers.LayerError, match="no points"):
+ maplayers.parse(empty, filename="empty.geojson")
+
+
+def test_something_that_is_not_a_map_file_at_all_names_the_formats():
+ with pytest.raises(maplayers.LayerError, match="GeoJSON, KML, KMZ or GPX"):
+ maplayers.parse(b"\x89PNG\r\n\x1a\n", filename="photo.png")
+
+
[email protected]("data, filename", [(b"{oops", "x.geojson"), (b"<kml><", "x.kml")])
+def test_a_malformed_file_is_refused_with_a_readable_reason(data, filename):
+ with pytest.raises(maplayers.LayerError) as refused:
+ maplayers.parse(data, filename=filename)
+ assert "not valid JSON" in str(refused.value) or "will not parse" in str(refused.value)
+
+
+def test_the_upload_route_answers_a_refused_file_with_its_reason(client, case_id):
+ response = client.post(
+ f"/api/cases/{case_id}/map-layers/upload",
+ files={"file": ("photo.png", io.BytesIO(b"\x89PNG\r\n\x1a\n"), "image/png")},
+ )
+
+ assert response.status_code == 422
+ assert "GeoJSON" in response.json()["detail"]
+
+
+# ---------------------------------------------------------------------------
+# A layer in a case
+# ---------------------------------------------------------------------------
+
+
+def test_adding_a_file_files_three_files_and_one_entity(client, case_id):
+ row = add(client, case_id, KML, "sightings.kml", title="Sightings")
+ case = Case.open(case_id)
+
+ assert row["features"] == 3
+ assert row["source"] == {"kind": "file", "name": "sightings.kml", "format": "kml"}
+ for rel in (
+ layout.layer_spec_rel(row["name"]),
+ layout.layer_snapshot_rel(row["name"]),
+ layout.layer_cache_rel(row["name"]),
+ ):
+ assert case.resolve_inside(rel).is_file(), rel
+ # The snapshot is the bytes as received, which is what makes it hashable
+ # like a media and what the parsed copy is rebuilt from.
+ assert case.resolve_inside(layout.layer_snapshot_rel(row["name"])).read_bytes() == KML
+ assert row["sha256"] == maplayers.digest(KML)
+
+ entity = client.get(
+ f"/api/cases/{case_id}/entities/lookup",
+ params={"attr": "spec", "value": layout.layer_spec_rel(row["name"])},
+ ).json()["entity"]
+ assert entity["type"] == "map-layer"
+ assert entity["label"] == "Sightings"
+
+
+def test_two_files_of_the_same_name_are_two_layers(client, case_id):
+ first = add(client, case_id, KML, "sightings.kml", title="Sightings")
+ second = add(client, case_id, GEOJSON, "sightings.geojson", title="Sightings")
+
+ assert first["name"] != second["name"]
+ assert len(client.get(f"/api/cases/{case_id}/map-layers").json()) == 2
+
+
+def test_the_drawn_copy_is_rebuilt_when_the_cache_is_gone(client, case_id):
+ """Which is the normal state after a restore or an import: the cache is the
+ one of the three files that never travels."""
+ row = add(client, case_id, KML, "sightings.kml")
+ case = Case.open(case_id)
+ cache = case.resolve_inside(layout.layer_cache_rel(row["name"]))
+ cache.unlink()
+
+ drawn = client.get(f"/api/cases/{case_id}/map-layers/{row['name']}/data")
+
+ assert drawn.status_code == 200
+ assert cache.is_file()
+ assert len(drawn.json()["features"]) == 3
+
+
+def test_a_category_toggle_is_stored_and_bounded_to_the_categories_there_are(
+ client, case_id
+):
+ row = add(client, case_id, KML, "sightings.kml")
+
+ updated = client.patch(
+ f"/api/cases/{case_id}/map-layers/{row['name']}",
+ json={"hidden": ["Damage", "Invented"]},
+ ).json()
+
+ assert updated["hidden"] == ["Damage"]
+ assert updated["features"] == 3, "hiding a category never changes what is loaded"
+
+
+def test_the_switch_and_the_legend_survive_a_reload(client, case_id):
+ row = add(client, case_id, KML, "sightings.kml")
+ client.patch(
+ f"/api/cases/{case_id}/map-layers/{row['name']}",
+ json={"enabled": False, "hidden": ["Damage"]},
+ )
+
+ reopened = client.get(f"/api/cases/{case_id}/map-layers").json()[0]
+
+ assert reopened["enabled"] is False
+ assert reopened["hidden"] == ["Damage"]
+
+
+def test_a_local_file_is_never_stale(client, case_id):
+ """It is exactly what the analyst opened, and it was never going to change."""
+ row = add(client, case_id, KML, "sightings.kml")
+
+ assert row["stale"] is False
+
+
+def test_a_copy_an_older_parser_wrote_is_read_again(client, case_id):
+ """A layer added from a file is never re-read, so without this it would draw
+ the output of whichever parser was current the day it was dropped in."""
+ row = add(client, case_id, KML, "sightings.kml")
+ case = Case.open(case_id)
+ cache = case.resolve_inside(layout.layer_cache_rel(row["name"]))
+ cache.write_text(
+ json.dumps({maplayers.PARSE_KEY: 0, "type": "FeatureCollection", "features": []}),
+ encoding="utf-8",
+ )
+
+ drawn = client.get(f"/api/cases/{case_id}/map-layers/{row['name']}/data")
+
+ assert len(drawn.json()["features"]) == 3
+ assert json.loads(cache.read_text())[maplayers.PARSE_KEY] == maplayers.PARSE_VERSION
+
+
+def test_deleting_a_layer_takes_its_snapshot_and_its_cache(client, case_id):
+ row = add(client, case_id, KML, "sightings.kml")
+ case = Case.open(case_id)
+
+ response = client.delete(f"/api/cases/{case_id}/map-layers/{row['name']}")
+
+ assert response.status_code == 200
+ assert not case.resolve_inside(layout.layer_cache_rel(row["name"])).exists()
+ client.delete(f"/api/cases/{case_id}/trash")
+ assert not case.resolve_inside(layout.layer_snapshot_rel(row["name"])).exists()
+
+
+def test_the_registry_carries_the_spec_and_the_snapshot_but_not_the_cache(client):
+ """The three files' three different answers to "does this travel?", read off
+ the registry the Trash and the bundle both consult."""
+ full = fullcase.build_full_case(client)
+ case = Case.open(full.case_id)
+ entity = case.get_entity(full.layer_id)
+
+ assert set(artifacts.owned(case, entity)) == {
+ full.layer,
+ full.layer_snapshot,
+ full.layer_icons,
+ }
+ assert artifacts.caches(case, entity) == [full.layer_cache]
+
+
+def test_restoring_a_layer_brings_back_what_travels_and_rebuilds_the_rest(client):
+ full = fullcase.build_full_case(client)
+ case = Case.open(full.case_id)
+
+ deleted = client.delete(f"/api/cases/{full.case_id}/entities/{full.layer_id}")
+ assert deleted.status_code == 200
+ group = deleted.json().get("trash")
+ assert group, "a layer is restorable, like everything else the case holds"
+ assert not case.resolve_inside(full.layer).exists()
+
+ restored = client.post(f"/api/cases/{full.case_id}/trash/{group}/restore")
+ assert restored.status_code == 200, restored.text
+ assert case.resolve_inside(full.layer).is_file()
+ assert case.resolve_inside(full.layer_snapshot).is_file()
+ # The icons come back rather than being rebuilt: a My Maps' came off Google's
+ # servers, so a case restored offline could not make them again.
+ assert case.resolve_inside(full.layer_icons).is_file()
+ assert not case.resolve_inside(full.layer_cache).exists(), "a cache is not restored"
+
+ name = full.layer.rsplit("/", 1)[-1].removesuffix(".json")
+ assert client.get(f"/api/cases/{full.case_id}/map-layers/{name}/data").status_code == 200
+
+
+# ---------------------------------------------------------------------------
+# The network boundary, both ways
+# ---------------------------------------------------------------------------
+
+
+def no_network(monkeypatch):
+ """Anything reaching out during a test that uses this is the failure."""
+
+ def refuse(*args, **kwargs):
+ raise AssertionError("this route reached the network")
+
+ monkeypatch.setattr(maplayers.httpx, "stream", refuse)
+
+
+def test_adding_and_drawing_a_local_file_never_reaches_the_network(
+ client, case_id, no_network
+):
+ row = add(client, case_id, KML, "sightings.kml")
+ client.get(f"/api/cases/{case_id}/map-layers")
+ client.get(f"/api/cases/{case_id}/map-layers/{row['name']}/data")
+ client.patch(f"/api/cases/{case_id}/map-layers/{row['name']}", json={"enabled": True})
+
+
+def test_listing_a_subscribed_layer_reads_the_snapshot_rather_than_the_feed(
+ client, case_id, monkeypatch
+):
+ """The half that is easy to get wrong: a case full of subscriptions must open
+ offline, drawing what it last saw."""
+ calls = []
+ monkeypatch.setattr(maplayers, "fetch", lambda url: (calls.append(url), (KML, "s.kml"))[1])
+ row = client.post(
+ f"/api/cases/{case_id}/map-layers", json={"url": "https://example.test/s.kml"}
+ ).json()
+ assert calls == ["https://example.test/s.kml"]
+
+ client.get(f"/api/cases/{case_id}/map-layers")
+ client.get(f"/api/cases/{case_id}/map-layers/{row['name']}/data")
+ client.patch(f"/api/cases/{case_id}/map-layers/{row['name']}", json={"enabled": False})
+
+ assert len(calls) == 1, "only the subscription itself fetched"
+
+
+def test_refreshing_replaces_the_snapshot_only_when_the_bytes_moved(
+ client, case_id, monkeypatch
+):
+ served = [KML]
+ monkeypatch.setattr(maplayers, "fetch", lambda url: (served[0], "s.kml"))
+ row = client.post(
+ f"/api/cases/{case_id}/map-layers", json={"url": "https://example.test/s.kml"}
+ ).json()
+ first = row["fetched_at"]
+
+ unchanged = client.post(f"/api/cases/{case_id}/map-layers/{row['name']}/refresh").json()
+ assert unchanged["sha256"] == row["sha256"]
+ assert unchanged["fetched_at"] == first, "unchanged bytes rewrite nothing"
+
+ served[0] = GEOJSON
+ moved = client.post(f"/api/cases/{case_id}/map-layers/{row['name']}/refresh").json()
+ assert moved["sha256"] == maplayers.digest(GEOJSON)
+ assert moved["features"] == 2
+ assert Case.open(case_id).resolve_inside(
+ layout.layer_snapshot_rel(row["name"])
+ ).read_bytes() == GEOJSON
+
+
+def test_a_failed_refresh_leaves_the_last_snapshot_on_the_map(client, case_id, monkeypatch):
+ monkeypatch.setattr(maplayers, "fetch", lambda url: (KML, "s.kml"))
+ row = client.post(
+ f"/api/cases/{case_id}/map-layers", json={"url": "https://example.test/s.kml"}
+ ).json()
+
+ def fail(url):
+ raise maplayers.LayerFetchError("that source answered 503")
+
+ monkeypatch.setattr(maplayers, "fetch", fail)
+ failed = client.post(f"/api/cases/{case_id}/map-layers/{row['name']}/refresh")
+
+ assert failed.status_code == 502
+ assert "503" in failed.json()["detail"]
+ assert client.get(f"/api/cases/{case_id}/map-layers/{row['name']}/data").json()["features"]
+
+
+def test_a_file_layer_has_nothing_to_refresh(client, case_id, no_network):
+ row = add(client, case_id, KML, "sightings.kml")
+
+ response = client.post(f"/api/cases/{case_id}/map-layers/{row['name']}/refresh")
+
+ assert response.status_code == 422
+ assert "came from a file" in response.json()["detail"]
+
+
+# ---------------------------------------------------------------------------
+# My Maps
+# ---------------------------------------------------------------------------
+
+
+ "link, mid",
+ [
+ ("https://www.google.com/maps/d/viewer?mid=1AbC_dEf-9&ll=48,2&z=9", "1AbC_dEf-9"),
+ ("https://www.google.com/maps/d/u/0/edit?mid=XyZ&usp=sharing", "XyZ"),
+ ("https://www.google.com/maps/d/kml?mid=XyZ&forcekml=1", "XyZ"),
+ ("https://example.org/data.kml", ""),
+ ],
+)
+def test_a_my_maps_share_link_gives_up_its_map_id(link, mid):
+ assert maplayers.my_maps_mid(link) == mid
+
+
+def test_a_my_maps_link_is_fetched_through_the_one_feed_it_has():
+ """Undocumented and breakable, and the only way to read a My Maps at all —
+ recorded in SPEC §9 rather than left to be discovered here."""
+ feed = maplayers.feed_url("https://www.google.com/maps/d/viewer?mid=XyZ&ll=1,2")
+
+ assert feed == "https://www.google.com/maps/d/kml?mid=XyZ"
+ # anything else is fetched exactly as it was pasted
+ assert maplayers.feed_url("https://example.org/d.kml") == "https://example.org/d.kml"
+
+
+def test_the_archive_is_asked_for_rather_than_the_kml_beside_it():
+ """`forcekml=1` answers the same placemarks and throws away what the map was
+ drawn with: every style comes back pointing at one of three *blank* Google
+ containers, so a map of forty hand-picked symbols draws as coloured blanks.
+ The KMZ bundles the creator's real icons as members of itself."""
+ assert "forcekml" not in maplayers.MY_MAPS_FEED
+ assert maplayers.feed_url(
+ "https://www.google.com/maps/d/kml?mid=XyZ&forcekml=1"
+ ) == "https://www.google.com/maps/d/kml?mid=XyZ"
+
+
+def test_a_my_maps_that_is_not_shared_says_what_to_do_about_it(client, case_id, monkeypatch):
+ """404 on this feed means "not shared publicly" far more often than it means
+ "no such map", and the difference is where the analyst goes looking."""
+
+ def refuse(url):
+ raise maplayers.LayerFetchError(
+ maplayers._status_reason(
+ _status_error(url, 404), maplayers.feed_url(url)
+ )
+ )
+
+ monkeypatch.setattr(maplayers, "fetch", refuse)
+ response = client.post(
+ f"/api/cases/{case_id}/map-layers",
+ json={"url": "https://www.google.com/maps/d/viewer?mid=XyZ"},
+ )
+
+ assert response.status_code == 502
+ assert "shared publicly" in response.json()["detail"]
+
+
+def test_an_address_that_is_not_http_is_refused_before_anything_is_read(
+ client, case_id, no_network
+):
+ response = client.post(
+ f"/api/cases/{case_id}/map-layers", json={"url": "file:///etc/passwd"}
+ )
+
+ assert response.status_code == 422
+ assert "http" in response.json()["detail"]
+
+
+# ---------------------------------------------------------------------------
+# The source's own pictograms
+# ---------------------------------------------------------------------------
+
+
+def dressed_kmz(**kwargs) -> bytes:
+ return kmz(icon_kml(**kwargs), extra={"images/pin.png": png()})
+
+
+def test_a_placemarks_icon_is_described_by_parsing_and_fetched_by_nobody():
+ """The split the whole feature rests on: parsing says what an icon *is*,
+ turning that into pixels is a separate act that may reach out."""
+ parsed = maplayers.parse(dressed_kmz(), filename="s.kmz")
+ [descriptor] = parsed["icons"].values()
+
+ assert descriptor["href"] == "images/pin.png"
+ assert descriptor["colour"] == "#ff0000"
+ assert descriptor["hotspot"] == [16.0, 32.0, "pixels", "insetPixels"]
+
+
+def test_only_a_point_carries_an_icon():
+ """A line and an area are drawn by their own stroke and fill. A pictogram
+ stuck on the middle of a border would be a mark the source never made."""
+ features = maplayers.parse(dressed_kmz(), filename="s.kmz")["geojson"]["features"]
+
+ assert features[0]["geometry"]["type"] == "Point" and features[0]["properties"]["icon"]
+ assert features[1]["geometry"]["type"] == "LineString"
+ assert features[1]["properties"]["icon"] == ""
+
+
+def test_a_kmz_composes_its_own_icons_without_reaching_the_network(
+ client, case_id, no_network
+):
+ """The free half of this feature: the pictograms are already in the file the
+ analyst dropped in, so honouring them costs one decode."""
+ row = add(client, case_id, dressed_kmz(), "s.kmz", icons=True)
+
+ assert row["icons"] == 1
+ assert Case.open(case_id).resolve_inside(layout.layer_icons_rel(row["name"])).is_file()
+
+
+def test_the_style_colour_is_multiplied_onto_the_icon():
+ """The step this turns on. A My Maps' stock pictograms are *white* — the
+ shape is in the PNG, the colour is in the style — so an untinted one is a
+ white blob, and honouring the href without the colour looks like a bug."""
+ parsed = maplayers.parse(dressed_kmz(), filename="s.kmz")
+ [image] = maplayers.icon_images(parsed["icons"], source=dressed_kmz()).values()
+
+ composed = Image.open(io.BytesIO(image)).convert("RGBA")
+ assert composed.getpixel((composed.width // 2, composed.height // 4)) == (255, 0, 0, 255)
+
+
+def test_a_hotspot_is_padded_into_the_middle_of_the_image():
+ """So the map can anchor every icon the same way — centred — and a pin whose
+ tip is its meaning still puts that tip on the ground.
+
+ The source anchors this one at the bottom of a square, so the composed image
+ is twice as tall as it is wide, with the picture in the upper half.
+ """
+ source = dressed_kmz()
+ parsed = maplayers.parse(source, filename="s.kmz")
+ [image] = maplayers.icon_images(parsed["icons"], source=source).values()
+
+ composed = Image.open(io.BytesIO(image))
+ assert composed.height == composed.width * 2
+ assert composed.convert("RGBA").getpixel((composed.width // 2, 2))[3] == 255
+ assert composed.convert("RGBA").getpixel((composed.width // 2, composed.height - 2))[3] == 0
+
+
+def test_icons_are_sized_on_their_ink_rather_than_on_their_canvas():
+ """The canvas is not the icon. A My Maps archive holds a square painted edge
+ to edge beside a small glyph floating in a sheet of transparency, and sizing
+ the *sheets* alike draws the second at a fraction of the first — which reads
+ as broken icons rather than as a source honoured.
+ """
+ full = Image.new("RGBA", (56, 56), (255, 255, 255, 255))
+ lost = Image.new("RGBA", (56, 56), (0, 0, 0, 0))
+ lost.paste(Image.new("RGBA", (14, 14), (255, 255, 255, 255)), (21, 21))
+
+ def stored(image):
+ buffer = io.BytesIO()
+ image.save(buffer, "PNG")
+ source = kmz(icon_kml(hotspot=""), extra={"images/pin.png": buffer.getvalue()})
+ parsed = maplayers.parse(source, filename="s.kmz")
+ [png] = maplayers.icon_images(parsed["icons"], source=source).values()
+ # The opaque core, not every pixel resampling left a trace in: a soft
+ # edge is not part of what the eye measures the mark by.
+ composed = Image.open(io.BytesIO(png)).convert("RGBA")
+ box = composed.split()[3].point(lambda level: 255 if level > 128 else 0).getbbox()
+ return max(box[2] - box[0], box[3] - box[1])
+
+ # the same size to within a pixel or two, rather than four times apart
+ assert abs(stored(full) - stored(lost)) <= 4
+ assert abs(stored(lost) - maplayers.ICON_SIDE) <= 4
+
+
+def test_a_solid_shape_is_not_drawn_heavier_than_the_hollow_one_beside_it():
+ """The second lie the bounding box tells. A My Maps container set holds a
+ square filled corner to corner next to a disc painting 79% of its own box, so
+ matching the *boxes* still leaves the square carrying nearly twice the ink —
+ which is what reads on the map as the squares being too big."""
+ square = Image.new("RGBA", (56, 56), (255, 255, 255, 255))
+ disc = Image.new("RGBA", (56, 56), (0, 0, 0, 0))
+ ImageDraw.Draw(disc).ellipse((0, 0, 55, 55), fill=(255, 255, 255, 255))
+
+ def painted(image):
+ buffer = io.BytesIO()
+ image.save(buffer, "PNG")
+ source = kmz(icon_kml(hotspot=""), extra={"images/pin.png": buffer.getvalue()})
+ parsed = maplayers.parse(source, filename="s.kmz")
+ [png] = maplayers.icon_images(parsed["icons"], source=source).values()
+ alpha = Image.open(io.BytesIO(png)).convert("RGBA").split()[3]
+ return alpha.point(lambda level: 255 if level > 128 else 0).histogram()[255]
+
+ # the square still paints more than the disc — a square *is* denser — but
+ # nothing like the 1.8x the raw bounding box would have given it
+ assert painted(square) / painted(disc) < 1.25
+
+
+def test_a_glyph_lost_in_a_huge_sheet_does_not_scale_the_sheet_with_it():
+ """Sizing on the ink means the transparency around it scales too, so the
+ canvas needs its own ceiling or one icon becomes a texture."""
+ sheet = Image.new("RGBA", (1024, 1024), (0, 0, 0, 0))
+ sheet.paste(Image.new("RGBA", (4, 4), (255, 255, 255, 255)), (510, 510))
+ buffer = io.BytesIO()
+ sheet.save(buffer, "PNG")
+ source = kmz(icon_kml(hotspot=""), extra={"images/pin.png": buffer.getvalue()})
+ parsed = maplayers.parse(source, filename="s.kmz")
+
+ [png] = maplayers.icon_images(parsed["icons"], source=source).values()
+
+ assert max(Image.open(io.BytesIO(png)).size) <= maplayers.MAX_ICON_CANVAS
+
+
+def test_a_centred_hotspot_is_not_padded_at_all():
+ source = kmz(icon_kml(hotspot=""), extra={"images/pin.png": png()})
+ parsed = maplayers.parse(source, filename="s.kmz")
+ [image] = maplayers.icon_images(parsed["icons"], source=source).values()
+
+ composed = Image.open(io.BytesIO(image))
+ assert composed.width == composed.height
+
+
+def test_two_styles_that_would_compose_alike_are_one_stored_icon():
+ """A My Maps writes a style per placemark. Keying on what an icon *looks
+ like* rather than on the style's id is what keeps that down to one image."""
+ twice = (
+ '<?xml version="1.0" encoding="UTF-8"?>'
+ '<kml xmlns="http://www.opengis.net/kml/2.2"><Document><name>Pair</name>'
+ '<Style id="a"><IconStyle><color>ff0000ff</color>'
+ "<Icon><href>images/pin.png</href></Icon></IconStyle></Style>"
+ '<Style id="b"><IconStyle><color>ff0000ff</color>'
+ "<Icon><href>images/pin.png</href></Icon></IconStyle></Style>"
+ '<Placemark><styleUrl>#a</styleUrl><Point><coordinates>2,48</coordinates></Point>'
+ "</Placemark>"
+ '<Placemark><styleUrl>#b</styleUrl><Point><coordinates>3,48</coordinates></Point>'
+ "</Placemark></Document></kml>"
+ ).encode()
+
+ parsed = maplayers.parse(kmz(twice, extra={"images/pin.png": png()}), filename="s.kmz")
+
+ assert len(parsed["icons"]) == 1
+
+
+def test_an_icon_style_a_feature_never_uses_is_never_read(monkeypatch):
+ """A KML commonly declares styles for shapes it no longer holds. Fetching one
+ would be a request made on nobody's behalf."""
+ orphan = (
+ '<?xml version="1.0" encoding="UTF-8"?>'
+ '<kml xmlns="http://www.opengis.net/kml/2.2"><Document><name>Orphan</name>'
+ '<Style id="unused"><IconStyle>'
+ "<Icon><href>https://example.test/never.png</href></Icon></IconStyle></Style>"
+ "<Placemark><name>Plain</name><Point><coordinates>2,48</coordinates></Point>"
+ "</Placemark></Document></kml>"
+ ).encode()
+
+ assert maplayers.parse(orphan, filename="s.kml")["icons"] == {}
+
+
+def test_a_file_added_without_the_tick_composes_nothing(client, case_id, no_network):
+ """The default for a file, and the local-first line: opening something off
+ this machine does not inherently need the network, so it does not touch it."""
+ row = add(client, case_id, dressed_kmz(), "s.kmz")
+
+ assert row["icons"] == 0
+ assert not Case.open(case_id).resolve_inside(layout.layer_icons_rel(row["name"])).exists()
+
+
+def test_a_remote_href_is_read_once_at_import_and_never_again(client, case_id, monkeypatch):
+ """What the browser must never do: the address is followed here, once, and
+ what the map loads from then on is a file in the case folder."""
+ calls = []
+
+ def serve(href):
+ calls.append(href)
+ return png()
+
+ monkeypatch.setattr(maplayers, "_fetch_icon", serve)
+ monkeypatch.setattr(
+ maplayers, "fetch", lambda url: (icon_kml(href="https://icons.test/p.png"), "s.kml")
+ )
+ row = client.post(
+ f"/api/cases/{case_id}/map-layers", json={"url": "https://example.test/s.kml"}
+ ).json()
+ assert calls == ["https://icons.test/p.png"]
+
+ client.get(f"/api/cases/{case_id}/map-layers")
+ client.get(f"/api/cases/{case_id}/map-layers/{row['name']}/data")
+ key = client.get(f"/api/cases/{case_id}/map-layers/{row['name']}/data").json()[
+ "features"
+ ][0]["properties"]["icon"]
+ served = client.get(f"/api/cases/{case_id}/map-layers/{row['name']}/icons/{key}")
+
+ assert row["icons"] == 1
+ assert served.status_code == 200
+ assert served.headers["content-type"] == "image/png"
+ assert len(calls) == 1, "only the import read the source's own address"
+
+
+def test_a_subscription_without_the_tick_reads_the_feed_and_no_icon(
+ client, case_id, monkeypatch
+):
+ def refuse(href):
+ raise AssertionError("an icon was fetched without being asked for")
+
+ monkeypatch.setattr(maplayers, "_fetch_icon", refuse)
+ monkeypatch.setattr(
+ maplayers, "fetch", lambda url: (icon_kml(href="https://icons.test/p.png"), "s.kml")
+ )
+ row = client.post(
+ f"/api/cases/{case_id}/map-layers",
+ json={"url": "https://example.test/s.kml", "icons": False},
+ ).json()
+
+ assert row["icons"] == 0
+
+
+def test_an_icon_that_cannot_be_read_costs_its_layer_nothing(client, case_id, no_network):
+ """The fallback, and the reason the panel needs no switch for it: the layer
+ draws, its features draw, and they wear the app's own shape."""
+ row = add(client, case_id, kmz(icon_kml(href="images/missing.png")), "s.kmz", icons=True)
+
+ assert row["icons"] == 0
+ assert row["features"] == 2
+
+
+def test_something_that_is_not_an_image_is_refused_rather_than_stored(
+ client, case_id, no_network
+):
+ """Nothing a source sent is passed on: every icon is decoded and re-encoded
+ here, so a file pretending to be a PNG never reaches the browser."""
+ hostile = kmz(
+ icon_kml(),
+ extra={"images/pin.png": b'<svg xmlns="http://www.w3.org/2000/svg"><script/></svg>'},
+ )
+
+ assert add(client, case_id, hostile, "s.kmz", icons=True)["icons"] == 0
+
+
+def test_an_icon_naming_a_file_outside_the_archive_is_refused():
+ escaping = kmz(icon_kml(href="../../../etc/passwd"), extra={"images/pin.png": png()})
+ parsed = maplayers.parse(escaping, filename="s.kmz")
+
+ assert maplayers.icon_images(parsed["icons"], source=escaping) == {}
+
+
+def test_more_icons_than_the_cap_leaves_the_rest_on_the_pictogram(monkeypatch):
+ """Never a refusal: the marks are the map, the icons are how it was dressed."""
+ monkeypatch.setattr(maplayers, "MAX_ICONS", 1)
+ many = (
+ '<?xml version="1.0" encoding="UTF-8"?>'
+ '<kml xmlns="http://www.opengis.net/kml/2.2"><Document><name>Many</name>'
+ + "".join(
+ f'<Style id="s{index}"><IconStyle><color>ff0000{index:02x}</color>'
+ f"<Icon><href>images/pin.png</href></Icon></IconStyle></Style>"
+ f'<Placemark><styleUrl>#s{index}</styleUrl>'
+ f"<Point><coordinates>{index},48</coordinates></Point></Placemark>"
+ for index in range(4)
+ )
+ + "</Document></kml>"
+ ).encode()
+ source = kmz(many, extra={"images/pin.png": png()})
+ parsed = maplayers.parse(source, filename="s.kmz")
+
+ assert len(parsed["icons"]) == 4
+ assert len(maplayers.icon_images(parsed["icons"], source=source)) == 1
+
+
+def test_an_icon_is_asked_for_by_key_rather_than_by_path(client, case_id, no_network):
+ """The key is a content hash, so there is nothing in the URL to traverse
+ with — and anything that is not one is refused before a file is opened."""
+ row = add(client, case_id, dressed_kmz(), "s.kmz", icons=True)
+
+ for key in ("../../case.json", "nope", "ZZZZ"):
+ refused = client.get(f"/api/cases/{case_id}/map-layers/{row['name']}/icons/{key}")
+ assert refused.status_code == 404, key
+
+
+def test_a_refresh_composes_the_icons_the_layer_was_added_with(client, case_id, monkeypatch):
+ """The tick is answered once and remembered: a feed that moved comes back
+ dressed the same way, without asking again."""
+ served = [dressed_kmz()]
+ monkeypatch.setattr(maplayers, "fetch", lambda url: (served[0], "s.kmz"))
+ row = client.post(
+ f"/api/cases/{case_id}/map-layers", json={"url": "https://example.test/s.kmz"}
+ ).json()
+ assert row["icons"] == 1
+
+ served[0] = kmz(icon_kml(colour="ff00ff00"), extra={"images/pin.png": png()})
+ moved = client.post(f"/api/cases/{case_id}/map-layers/{row['name']}/refresh").json()
+
+ assert moved["sha256"] != row["sha256"]
+ assert moved["icons"] == 1
+
+
+def _status_error(url: str, code: int) -> "maplayers.httpx.HTTPStatusError":
+ request = maplayers.httpx.Request("GET", maplayers.feed_url(url))
+ response = maplayers.httpx.Response(code, request=request)
+ return maplayers.httpx.HTTPStatusError("refused", request=request, response=response)
diff --git a/tests/test_media_map_index.py b/tests/test_media_map_index.py
index 439c695..60a84b9 100644
--- a/tests/test_media_map_index.py
+++ b/tests/test_media_map_index.py
@@ -202,6 +202,37 @@ def test_a_video_stands_where_the_proof_using_its_frame_concludes(client, sat_ti
assert video_row["linked_proofs"][0]["title"] == "Roofline"
+def test_two_clips_one_post_collected_stay_on_their_own_geolocation(client, sat_tiles):
+ """A post publishing two clips is not a claim that they were filmed together.
+
+ The walk crosses the chain in both directions, so a document holding several
+ files joined them end to end: each clip reached the other's proof and stood on
+ its point. Two geolocations became four rows, and the map drew a 2 on each.
+ """
+ cid = _new_case(client)
+ north = _upload(client, cid, "north.png")
+ south = _upload(client, cid, "south.png", color=(30, 30, 200))
+ _save_proof(
+ client, cid, "North",
+ [_frame_of(cid, north, "n.png"), _sat(client, cid, 50.4501, 30.5234)],
+ coords={"lat": 50.4501, "lon": 30.5234},
+ )
+ _save_proof(
+ client, cid, "South",
+ [_frame_of(cid, south, "s.png"), _sat(client, cid, 48.8584, 2.2945)],
+ coords={"lat": 48.8584, "lon": 2.2945},
+ )
+
+ case = Case.open(cid)
+ post = case.add_entity("post", "The thread", {}, by="user")
+ for path in (north, south):
+ case.add_link(post["id"], _id(cid, path=path), "derived-from", by="user")
+
+ rows = _index(client, cid)
+ assert _points(rows, north) == [(50.4501, 30.5234)]
+ assert _points(rows, south) == [(48.8584, 2.2945)]
+
+
def test_roads_that_agree_on_a_point_are_one_row(client, sat_tiles):
"""The composer poses the proof's point on its material as `depicts`, and the
same file reaches that proof along the chain. One file on one metre is one mark,
diff --git a/tests/test_proofs_api.py b/tests/test_proofs_api.py
index 201217f..2eaf7cc 100644
--- a/tests/test_proofs_api.py
+++ b/tests/test_proofs_api.py
@@ -785,6 +785,50 @@ def test_clearing_the_coordinates_withdraws_the_point(client):
assert saved["orphans"] == [{"id": filed["id"], "label": filed["label"]}]
+def test_swapping_the_footage_takes_the_point_off_the_clip_it_dropped(client):
+ """The point stays, the material under it does not: a proof re-composed on another
+ clip must stop saying the old one was filmed there.
+
+ Read off the chain alone, nothing reached the dropped clip — the point was kept,
+ so it was never withdrawn, and the walk that restates it only ever visits the
+ material the proof rests on *now*. The video stayed on the map under a proof that
+ no longer rested on it, and the mark counted two.
+ """
+ cid = client.post("/api/cases", json={"name": "Proofs"}).json()["id"]
+ old = _video(cid)
+ new = _video(cid, "angle.mp4")
+ _save(client, cid, "Roof match", _with_coords("50.4501, 30.5234", None, "media/clip.mp4"))
+ place = _places(cid)[0]
+ assert old["id"] in {lk["from"] for lk in _depicts(cid) if lk["to"] == place["id"]}
+
+ _save(client, cid, "Roof match", _with_coords("50.4501, 30.5234", None, "media/angle.mp4"))
+
+ posed = {lk["from"] for lk in _depicts(cid) if lk["to"] == place["id"]}
+ assert new["id"] in posed
+ assert old["id"] not in posed
+ assert len(_places(cid)) == 1 # the point itself was kept, not re-filed
+
+
+def test_footage_dropped_as_the_point_moves_is_left_on_neither(client):
+ """The same save corrects the coordinates and swaps the clip. The withdrawal walked
+ the material the proof rests on now, so the clip it had just dropped kept its edge —
+ and held the abandoned point alive, which is worse than a stale mark: nothing owned
+ it any more, and it was never offered for deletion."""
+ cid = client.post("/api/cases", json={"name": "Proofs"}).json()["id"]
+ old = _video(cid)
+ new = _video(cid, "angle.mp4")
+ _save(client, cid, "Roof match", _with_coords("50.4501, 30.5234", None, "media/clip.mp4"))
+ left = _places(cid)[0]
+
+ saved = _save(client, cid, "Roof match", _with_coords("48.8584, 2.2945", None, "media/angle.mp4"))
+
+ assert [lk["from"] for lk in _depicts(cid) if lk["to"] == left["id"]] == []
+ assert saved["orphans"] == [{"id": left["id"], "label": left["label"]}]
+ moved = _place_by_lat(cid, 48.8584)
+ assert new["id"] in {lk["from"] for lk in _depicts(cid) if lk["to"] == moved["id"]}
+ assert old["id"] not in {lk["from"] for lk in _depicts(cid)}
+
+
def test_a_point_another_proof_still_concludes_on_keeps_its_material(client):
cid = client.post("/api/cases", json={"name": "Proofs"}).json()["id"]
video = _video(cid)
diff --git a/tests/test_updates.py b/tests/test_updates.py
index 2d42b90..94cc5ad 100644
--- a/tests/test_updates.py
+++ b/tests/test_updates.py
@@ -139,7 +139,7 @@ def test_update_endpoint_with_check_queries_github(client, monkeypatch):
# shipped file really changes, set the manifest to the current __version__ and
# record the new digest here (the failing test prints it).
EXTENSION_VERSION = "0.3.0"
-EXTENSION_PAYLOAD = "9c890067aa7271ca97e30ce999bf600a97fe261ef8a43316d021541aa4798c65"
+EXTENSION_PAYLOAD = "207f769e50979032a6052386396ece5972de7ce0f267c60e39e25e78806d5dca"
# The digest itself lives in engine/extinstall.py, because the update button
# compares the same number: what the app ships against what the installed folder
diff --git a/tests/test_wayback.py b/tests/test_wayback.py
index e068427..ee97905 100644
--- a/tests/test_wayback.py
+++ b/tests/test_wayback.py
@@ -7,8 +7,12 @@ is how the app reads them.
from __future__ import annotations
+import io
+
import httpx
+import numpy as np
import pytest
+from PIL import Image
from azimut.engine import tiles, wayback
@@ -169,12 +173,11 @@ def test_listing_the_basemaps_asks_esri_nothing(client, monkeypatch):
# -- the walk ----------------------------------------------------------------------
-def _walk(select_by_release, sizes=None, tiles_by_release=None, seen=None, pictures=None):
+def _walk(select_by_release, tiles_by_release=None, seen=None, pictures=None):
"""A stub for the tilemap, the tiles and the metadata. `select_by_release[r]`
is the release the tilemap names when asked at `r`; None means no tile
there. `pictures[r]` is `(epoch ms, sensor)` or None for no metadata; by
default every release was taken on a different day."""
- sizes = sizes or {}
tiles_by_release = tiles_by_release or {}
pictures = pictures if pictures is not None else {}
@@ -188,7 +191,7 @@ def _walk(select_by_release, sizes=None, tiles_by_release=None, seen=None, pictu
chosen = select_by_release.get(release)
if chosen is None:
return Reply({"data": [0], "valid": True})
- return Reply({"data": [1], "select": [chosen], "size": [sizes.get(chosen, 100)]})
+ return Reply({"data": [1], "select": [chosen]})
if url.split("?")[0].endswith("/query"):
suffix = url.split("World_Imagery_Metadata_")[1].split("/")[0]
release = next(int(k) for k, v in CONFIG.items() if v["metadataLayerUrl"].endswith(f"_{suffix}/MapServer"))
@@ -208,7 +211,7 @@ def _releases(changes):
def test_the_walk_names_each_release_that_changed_the_point_newest_first():
- get = _walk({26334: 64776, 25982: 10, 10: 10}, sizes={64776: 300, 10: 200})
+ get = _walk({26334: 64776, 25982: 10, 10: 10})
assert _releases(wayback.local_changes(50.45, 30.52, 15, get=get)) == [64776, 10]
@@ -222,32 +225,18 @@ def test_a_release_the_list_does_not_know_ends_the_walk_rather_than_guessing():
assert wayback.local_changes(50.45, 30.52, 15, get=get) == []
-def test_two_neighbours_with_the_same_pixels_are_one_change_and_the_older_stays():
+def test_two_neighbours_with_the_same_bytes_are_one_change_and_the_older_stays():
same = b"identical jpeg"
- get = _walk(
- {26334: 64776, 25982: 10, 10: 10},
- sizes={64776: 14, 10: 14},
- tiles_by_release={64776: same, 10: same},
- )
+ get = _walk({26334: 64776, 25982: 10, 10: 10}, tiles_by_release={64776: same, 10: same})
assert _releases(wayback.local_changes(50.45, 30.52, 15, get=get)) == [10]
-def test_equal_sizes_with_different_pixels_are_still_two_changes():
- get = _walk(
- {26334: 64776, 25982: 10, 10: 10},
- sizes={64776: 5, 10: 5},
- tiles_by_release={64776: b"aaaaa", 10: b"bbbbb"},
- )
- assert _releases(wayback.local_changes(50.45, 30.52, 15, get=get)) == [64776, 10]
-
-
def test_a_picture_published_again_is_one_change_dated_by_its_first_release():
# Mariupol, 2026-09: three releases re-processed one GE01 acquisition, and
# the tilemap counts each as a change because its bytes differ
taken = (1_696_377_600_000, "GE01") # 2023-10-04
get = _walk(
{26334: 26334, 64776: 25982, 10: 10},
- sizes={26334: 300, 25982: 200, 10: 100},
pictures={26334: taken, 25982: taken, 10: (1_648_512_000_000, "WV03")},
)
changes = wayback.local_changes(50.45, 30.52, 15, get=get)
@@ -259,18 +248,13 @@ def test_a_picture_published_again_is_one_change_dated_by_its_first_release():
def test_the_same_day_from_another_satellite_is_another_picture():
get = _walk(
{26334: 64776, 25982: 10, 10: 10},
- sizes={64776: 300, 10: 200},
pictures={64776: (1_696_377_600_000, "GE01"), 10: (1_696_377_600_000, "WV02")},
)
assert _releases(wayback.local_changes(50.45, 30.52, 15, get=get)) == [64776, 10]
def test_a_release_without_metadata_is_never_merged_into_its_neighbour():
- get = _walk(
- {26334: 64776, 25982: 10, 10: 10},
- sizes={64776: 300, 10: 200},
- pictures={64776: None, 10: None},
- )
+ get = _walk({26334: 64776, 25982: 10, 10: 10}, pictures={64776: None, 10: None})
changes = wayback.local_changes(50.45, 30.52, 15, get=get)
assert _releases(changes) == [64776, 10]
assert changes[0].acquired is None
@@ -279,7 +263,6 @@ def test_a_release_without_metadata_is_never_merged_into_its_neighbour():
def test_a_tile_that_cannot_be_read_keeps_its_change_rather_than_failing_the_walk():
flaky = _walk(
{26334: 64776, 25982: 10, 10: 10},
- sizes={64776: 5, 10: 5},
tiles_by_release={64776: b"same!", 10: b"same!"},
)
@@ -306,6 +289,87 @@ def test_the_walk_asks_at_the_view_zoom_but_never_past_the_basemap():
assert "/tilemap/26334/19/" in seen[0]
+# -- the same picture, published again ---------------------------------------------
+#
+# The tilemap answers in bytes: Esri re-encodes and re-tones a tile far more
+# often than the ground under it moves, and every one of those used to reach the
+# picker as a change the analyst stepped through for nothing.
+
+
+def _ground(seed: int):
+ """A 256 px tile with structure in it: a coarse random field, blown up smoothly."""
+ field = np.random.default_rng(seed).integers(20, 235, size=(16, 16), dtype=np.uint8)
+ return np.asarray(Image.fromarray(field).resize((256, 256), Image.Resampling.BICUBIC))
+
+
+def _jpeg(pixels, quality: int = 85) -> bytes:
+ buffer = io.BytesIO()
+ Image.fromarray(pixels).save(buffer, format="JPEG", quality=quality)
+ return buffer.getvalue()
+
+
+def test_the_same_picture_re_encoded_is_one_change_however_its_bytes_differ():
+ ground = _ground(7)
+ get = _walk(
+ {26334: 64776, 25982: 10, 10: 10},
+ tiles_by_release={64776: _jpeg(ground, 92), 10: _jpeg(ground, 55)},
+ )
+ assert _releases(wayback.local_changes(50.45, 30.52, 15, get=get)) == [10]
+
+
+def test_the_same_picture_under_a_new_colour_balance_is_one_change():
+ ground = _ground(11)
+ toned = np.clip(ground * 0.7 + 50, 0, 255).astype(np.uint8)
+ get = _walk(
+ {26334: 64776, 25982: 10, 10: 10},
+ tiles_by_release={64776: _jpeg(toned), 10: _jpeg(ground)},
+ )
+ assert _releases(wayback.local_changes(50.45, 30.52, 15, get=get)) == [10]
+
+
+def test_the_same_picture_re_processed_under_a_hard_gamma_is_one_change():
+ ground = _ground(11)
+ lifted = (255 * ((ground / 255) ** 0.55)).astype(np.uint8)
+ get = _walk(
+ {26334: 64776, 25982: 10, 10: 10},
+ tiles_by_release={64776: _jpeg(lifted), 10: _jpeg(ground)},
+ )
+ assert _releases(wayback.local_changes(50.45, 30.52, 15, get=get)) == [10]
+
+
+def test_something_built_on_the_ground_is_still_a_change():
+ ground = _ground(3)
+ built = ground.copy()
+ built[100:132, 100:132] = 250 # a roof over an eighth of the tile across
+ get = _walk(
+ {26334: 64776, 25982: 10, 10: 10},
+ tiles_by_release={64776: _jpeg(built), 10: _jpeg(ground)},
+ )
+ assert _releases(wayback.local_changes(50.45, 30.52, 15, get=get)) == [64776, 10]
+
+
+def test_another_picture_of_the_same_place_is_still_a_change():
+ get = _walk(
+ {26334: 64776, 25982: 10, 10: 10},
+ tiles_by_release={64776: _jpeg(_ground(1)), 10: _jpeg(_ground(2))},
+ )
+ assert _releases(wayback.local_changes(50.45, 30.52, 15, get=get)) == [64776, 10]
+
+
+def test_a_run_of_republications_collapses_onto_the_release_that_first_showed_it():
+ ground = _ground(5)
+ get = _walk(
+ {26334: 26334, 64776: 64776, 25982: 25982, 10: 10},
+ tiles_by_release={
+ 26334: _jpeg(ground, 90),
+ 64776: _jpeg(np.clip(ground * 1.1, 0, 255).astype(np.uint8)),
+ 25982: _jpeg(ground, 60),
+ 10: _jpeg(_ground(6)),
+ },
+ )
+ assert _releases(wayback.local_changes(50.45, 30.52, 15, get=get)) == [25982, 10]
+
+
# -- when the pixels were taken ----------------------------------------------------
diff --git a/tests/test_workspace_pointer.py b/tests/test_workspace_pointer.py
index 8d349e3..e8d3cf0 100644
--- a/tests/test_workspace_pointer.py
+++ b/tests/test_workspace_pointer.py
@@ -103,6 +103,39 @@ def test_writing_the_pointer_replaces_it_atomically(tmp_path):
assert leftovers == []
+def test_a_scanner_holding_the_fresh_pointer_is_waited_out(monkeypatch, tmp_path):
+ """Windows refuses a rename onto a file a virus scanner or the indexer has
+ just opened. That lasts milliseconds, and failed a workspace move at the
+ switch in CI, so the write waits it out instead of giving up."""
+ real_replace = config.os.replace
+ refusals = []
+
+ def held_twice(src, dst):
+ if len(refusals) < 2:
+ refusals.append(dst)
+ raise PermissionError(5, "Access is denied")
+ real_replace(src, dst)
+
+ monkeypatch.setattr(config.os, "replace", held_twice)
+ monkeypatch.setattr(config.time, "sleep", lambda _: None)
+ config.write_pointer(tmp_path / "moved")
+
+ assert len(refusals) == 2
+ assert config.read_pointer() == tmp_path / "moved"
+
+
+def test_a_pointer_that_stays_held_still_fails_loudly(monkeypatch, tmp_path):
+ def always_held(src, dst):
+ raise PermissionError(5, "Access is denied")
+
+ monkeypatch.setattr(config.os, "replace", always_held)
+ monkeypatch.setattr(config.time, "sleep", lambda _: None)
+ with pytest.raises(PermissionError):
+ config.write_pointer(tmp_path / "moved")
+ leftovers = [p.name for p in config.pointer_path().parent.iterdir() if p.name.endswith(".tmp")]
+ assert leftovers == []
+
+
def test_a_home_relative_pointer_is_expanded(tmp_path):
config.pointer_path().parent.mkdir(parents=True, exist_ok=True)
config.pointer_path().write_text("~/Somewhere\n", encoding="utf-8")
diff --git a/uv.lock b/uv.lock
index 0c24f3f..910200c 100644
--- a/uv.lock
+++ b/uv.lock
@@ -97,6 +97,7 @@ source = { editable = "." }
dependencies = [
{ name = "cryptography", version = "48.0.1", source = { registry = "https://pypi.org/simple" }, marker = "platform_machine == 'x86_64' and sys_platform == 'darwin'" },
{ name = "cryptography", version = "50.0.0", source = { registry = "https://pypi.org/simple" }, marker = "platform_machine != 'x86_64' or sys_platform != 'darwin'" },
+ { name = "defusedxml" },
{ name = "fastapi" },
{ name = "fpdf2" },
{ name = "gallery-dl" },
@@ -141,6 +142,7 @@ release = [
requires-dist = [
{ name = "cryptography", marker = "platform_machine != 'x86_64' or sys_platform != 'darwin'", specifier = ">=45,<51" },
{ name = "cryptography", marker = "platform_machine == 'x86_64' and sys_platform == 'darwin'", specifier = ">=45,<49" },
+ { name = "defusedxml", specifier = ">=0.7,<1" },
{ name = "fastapi", specifier = ">=0.111,<1.0" },
{ name = "fpdf2", specifier = ">=2.8,<3" },
{ name = "gallery-dl", specifier = ">=1.27" },