Maps Component

Manuel Gozalbes

@elena @andreslopez @rca @Sonia @Eulàlia Mesalles @Enric Tartera

The Museu de Prehistòria de València has the opportunity to develop the maps component for Dédalo. Two years ago, the University of Cádiz carried out significant development work for the Wondercoins project, resulting in a fully functional implementation within Dédalo. However, some adjustments remain pending to achieve 100% integration into Dédalo's architecture. The repositories are published on GitHub:

The following table outlines the functionalities currently offered by the component:

Functionality	Description
Object Viewer	Visualization, hiding and navigation of vector objects from the collection
1m² Polygons	Automatic creation of 1m² polygons over existing markers
Cadastre	Search for cadastral parcels and loading as WMS layers
Centroids & Uncertainty	Adding centroids and uncertainty areas to objects
Administrative Units	Selection of municipalities, provinces and autonomous communities
Roman Empire (Pleiades)	Search and loading of historical archaeological data (amphitheatres, circuses, etc.)
Roman Empire (Dare)	Query of historical databases with advanced filters
File Upload	Import of Shapefile, GeoJSON, KML with projection management
Projections	Default EPSG support (IGN) + custom projections
Image Overlay	PNG upload with editable positioning, opacity and z-index
GeoTIFF Support	Import/export of georeferenced images
Map Export	Download in GeoTIFF, PNG, JPG, GIF and WebP formats
Layer Management (z-index)	Visual hierarchy control between overlapping objects

A preliminary consensus would be valuable to determine which components could be integrated straightforwardly into Dédalo's architecture and which might present greater technical challenges. Comments from the University of Cádiz, based on their experience with the Wondercoins project, would help clarify whether the developments are fully operational and whether any parts should be revised or discarded before proceeding with full integration.
Thank you

Alex

This is fantastic news for the community!

For me the most important thing could be the layer data import from QGIS or other editors, because most researches use QGIS to draw archeological things and it could be great if Dédalo could handle this information.

The Leaftlet library has a lots of plugins, that can help.

Best

Eulàlia Mesalles

Alex

Wonderful news, indeed!

I was thinking too about the QGIS to draw arhaeological things!

Enric Tartera

Nice thing to do

Ask us if you think we can help to do something

sergiofg

@Manuel Gozalbes

Hello everyone,

We're the team that will continue expanding this tool and its implementation. Our goal isn't just to get the map working, but to bring this to a real PR against the official Dédalo repository — so it ends up as a supported tool, not a fork or a custom install that breaks with every version update. We've audited both repositories linked in the original message and tested the tool on a real Dédalo installation to confirm what's actually built and what it would take to reach an acceptable PR.

Tool functionalities

#	Functionality	Description
1	Place search	Search for place names that centers and adjusts the map zoom to the selected result
2	Scale bar	Graphic reference scale visible on the map
3	Object console	Selecting any element on the map shows its information (coordinates, elevation, area/radius, layer hierarchy), lets you edit its style, mark centroid and uncertainty, manage custom properties, attach images with a gallery, and download the geometry (GeoJSON, ESRI Shapefile or KML). Properties can be exported to PDF and attached images support JPG, JPEG and PNG. On an already-uploaded image it lets you view it, reposition it, and adjust its opacity and layer order
4	Object viewer	Lists the vector and raster objects in the collection, with the option to show/hide them and center the map on any of them
5	Base map services (XYZ)	Adds custom base maps by specifying URL, name, attribution and zoom range, with OSM, ArcGIS and Google Maps already preconfigured
6	WMS services	Adds any WMS server as a layer from its URL
7	1m² polygons	Automatically creates a 1-meter-radius polygon centered on an existing marker
8	Cadastre	Search for cadastral parcels by reference and display of their official geometry as a WMS layer
9	Administrative units	Selection of municipality, province and autonomous community as an IGN WMS layer
10	Map export	Download the map as an image, with a configurable file name, in GeoTIFF, PNG, JPG, GIF or WebP
11	File upload	Import of vector files (ZIP/Shapefile, GeoJSON, KML) and georeferenced images/overlays (TIFF, JPG, JPEG, PNG), with source projection selection (default or custom EPSG)
12	Legend	Map legend editor, organizable into columns, with the option to show or hide it
13	Geolocation	Centers the map on the device's location
14	Roman Empire	Search for ancient-world places and historical data on the Roman Empire via Pleiades, Pelagios and imperium.ahlfeldt.se (DARE)
15	CAD / GeoPackage (to be developed)	Import of AutoCAD drawings (`.dxf`) and export to GeoPackage (`.gpkg`)

All of them are always available except for these exceptions:

Cadastre (functionality 8) and Administrative Units (functionality 9) — only on records in Spanish, Catalan or Basque.
Roman Empire (functionality 14) — only on numismatic-type records.
CAD / GeoPackage (functionality 15) — still under development, not available yet.

Auditing the code in depth, we also found a few minor details, handled differently case by case:

The base map dropdown (functionality 5) shows "OSM" duplicated when the custom base maps control is enabled — looks like an initialization bug, we'll fix it.
The "Pelagios D.A.R.E" search panel (functionality 14) actually only searches Pelagios; the real DARE query with advanced filters is a separate panel — we'll fix the labeling.
The place search and the scale bar (functionalities 1-2) can silently disappear if their external library fails to load in time — we'll change this to a visible failure instead of a silent one.
The GeoTIFF export (functionality 10) assigns the coordinate system instead of reprojecting — to be reviewed before considering this format support closed.
The object viewer (functionality 4) has no edit function, only show/hide — noting it as a known limitation.
The place search (functionality 1) doesn't go through the translation system and always stays in English, regardless of the record's language — a limitation of the library it uses.
The place search and the tool's own geolocation control (functionalities 1 and 13) duplicate functionality already built into the Dédalo core — open for discussion on whether to keep them or remove them from the tool to avoid duplicating the interface.
"Upload image as a map layer" (functionality 11) and "attach an image to an object" (inside functionality 3) are two different things that share a similar name — we'll make this clearer in the final interface.

Path to an official PR

We're starting from tool_leaflet_special_tools, not leaflet.control.SpecialTools: the latter directly modifies a Dédalo core component (component_geolocation.js), which breaks the rule of not touching /core/ and wouldn't be acceptable in a PR. tool_leaflet_special_tools, on the other hand, is already built as a real tool — it hooks into the map via the component's public API and persists data using the same mechanism the rest of Dédalo uses. We're starting from this repository.

The path we see toward an acceptable PR:

Rename the tool to the tool_ + institution/acronym + function convention (it's currently called tool_leaflet_special_tools, after the library, not institution+function — something like tool_uca_maps would fit better, but we'd like your input before deciding the name).
Complete the register.json, including multi-language labels and window properties.
Replace the real-time translation via Google Translate with Dédalo's own label system — the biggest piece of adaptation work, but essential for this to be a "real" tool and not depend on an unofficial external service.
Move the configuration persistence (base maps and WMS layers saved by the user) to the ontology/DB, as the rest of the tools do.
Add real control cleanup when the tool is closed, so nothing stays stuck on the map.
Harden the backend: sanitize URLs, file paths and parameters used in the geospatial conversions.
External dependency detection (GDAL, Python3, Imagick) with graceful degradation if they're not available.
Trim down the repo before the PR, removing build tooling not run in production from the distributed package.
Commit history following Dédalo's convention since v6 (Conventional Commits with its own prefixes: feat, fix, refactor, security, deprecate, remove, etc. — we'll use security: for the hardening work and deprecate/remove for retiring Google Translate), fork + own branch + PR against upstream.

None of this is an architectural change — it's adaptation work to your quality standard, which we'd rather make explicit here up front than discover halfway through a PR.

Points where we'd really like your input before investing the work:

v7 compatibility — we're developing and testing this against Dédalo 6.8. We don't know how big the jump to v7 will be or when it's landing: can you give us a sense of whether it'll mean a lot of changes for a tool like this, and whether it's worth aiming the PR at the current branch with confidence, or if you'd rather we think about this with v7 in mind already?
Tool name — any preference or unwritten convention we should follow beyond tool_ + institution + function?
Optional server dependencies (GDAL/Imagick) — acceptable with graceful degradation, or would you rather this stay out of scope for a "core-adjacent" tool?
Functionalities that only make sense in certain languages — Cadastre and Administrative Units, for example, only apply to Spain (they depend on services like the Spanish Cadastre or the IGN's WMS-INSPIRE) and today they're activated by checking the record's language. Is there an official approach for this (activate by language, by region, some specific configuration property), or does each tool solve this condition on its own?
License — the repo's LICENSE says GPL-3.0, but the header of tool_leaflet_special_tools.js declares AGPL-3.0. Your own documentation states Dédalo is AGPL-3.0, so the tool's header is probably the correct one, but we need someone from Universidad de Cádiz/hispanicode to formally confirm this before we redistribute anything.
Expected quality bar — is there an established checklist or review criteria for a PR this size (tests, CI, etc.) we should know about beforehand?

Thank you for reading all of this, and for keeping Dédalo such an active project. We're open to any suggestion, correction or nuance on the above.

Images

tool_leaflet_special_tools registered and active in Dédalo's tools list.

The tool's launch button on the map component.

The tool loaded on the map, with its full icon menu on the left.

Alex

Hi sergiofg

Thanks for the thorough proposal, the functionality table, the honest minor-details list, and the explicit "this is adaptation work, not architecture" framing are exactly the right starting posture. The plan is accepted in principle. There is one point that shapes everything below: I'm thinking that the PR must target v7, not the 6.8 (PHP) line you developed against.

The v6 → v7 reality for this tool.

Dédalo v7 is not a version bump; it is a from-scratch TypeScript/Bun rewrite in which the PHP engine is decommissioned and the TS engine is the single engine and sole writer. For your tool that means: the map engine (all 15 features, client-side Leaflet in vanilla JS) ports almost verbatim; the integration layer (runtime, register.json, persistence, server logic) must be rewritten in TS. Your stated goal , "a supported tool, not a fork that breaks every version update", is only reachable by targeting v7.

But this is just my opinion. You can target the version you want! Version 6 is still in use, and the transition to version 7 will begin in September. The transition will take several months, as implementing a major version with a new core engine takes time. This technology transition is challenging, The transition from PHP to TypeScript is not a simple update, it is necessary but difficult. Therefore, the version 6 version of the tool is entirely feasible.

Concrete facts that should reassure you:

As you mentioned, core changes are totally unacceptable. If a tool requires a feature that isn't implemented, you can create a discussion thread to discourage it. However, a tool cannot independently change the core. We need a solid foundation, and tools must extend the core to add specific features. The main idea is that a tool is an isolated piece of code that can be plugged in or not. Tools can access or use core features but never implement core changes on their own.
The format of the register.json file has been changed. Version 7 introduces a new matrix schema with a different data organization. Therefore, the register.json file for version 6 needs to be updated with version 7. We have implemented a compatible register, but it's better if you update your developer installation. This will update your matrix tables and your tool developer register, allowing you to export the new register in the same way as version 6. Keep in mind that version 7 can read version 6, but version 6 cannot read version 7.
In v7 the tool runtime is defined by contract. Tools live in tools/tool_/ with a register.json (flat authoring schema validated by zod: name, label as a lg- lang map, developer, affected_models, show_in_component, active, config), js/, css/, and an optional TS server/ dir. Client code is vanilla JS against an exact wire contract, attached via tool_common.js open_tool and the component's public API , never by editing /core/.

Your six input points, answered:

v7 compatibility. The change is large for the integration layer and near-zero for the Leaflet layer. Worth aiming the PR at v7 with confidence , it is where the project is going, and a 6.8 PR would land on a branch being actively decommissioned and be re-reviewed from scratch anyway. Aim at v7 now.
Tool name. Every v7 tool is function-named (tool_cataloging, tool_indexation, tool_diffusion, tool_export, tool_time_machine, tool_transcription, etc.); library-named tool_leaflet_special_tools is the outlier. tool_uca_maps fits the schema regex ^tool_[a-z0-9_]+$. Note the rename must land in the same PR that fills the ghost row, updating the client tool-list test and the geolocation sample payload references.
GDAL / Imagick optional dependencies. Acceptable, with precedent: the engine already wraps external binaries behind a strict spawn discipline (src/core/media/engine/spawn.ts, argv arrays, no shell, timeouts, nice). GDAL fits that pattern exactly, with graceful degradation when the binary is absent. One flag: nothing in v7 invokes Python3 today, a Python wrapper would draw the most review attention; prefer the GDAL binary directly.
Language-gated features (Cadastre, Administrative Units). There is no official activate-by-language/region mechanism, the request language is scoped per request (currentApplicationLang / currentDataLang) and available to tools, but there is no config property for it. Gate inside the tool on the record's data language, as you already do, and document it; do not invent a new config key in this PR.
License. The repo's own License.md is AGPL-3.0, so the tool header is the consistent one and the repo LICENSE file is the outlier. Still, only the copyright holder (hispasonicode / Universidad de Cádiz) can formally confirm before redistribution, your diligence here is correct and necessary.
Quality bar. register.json must pass the zod authoring schema; add a serving test plus unit tests (scratch-write hygiene, never touch real records); biome + tsc --noEmit clean; no /core/ edits (you already respect this). Commits follow Conventional Commits, note the security hardening prefix in practice is fix(security):, not a bare security:.

If you have questions don't hesitate to ask.

Thanks to implementing new tools ( ...or reviving old ones 🙂 )

Best
Alex

Clare

wow! To be able to export an image would be amazing - if we could have it as a high resolution, to be able to include it in publications, that would be great. Some publishers in the UK, for example, require maps to be 1200dpi, so if we could include resolutions up to that size as an option it would be very very useful.

Manuel Gozalbes

For us is OK to make the development for version 7.

sergiofg

Hi @Alex,

I'm writing about the v7 port of the University of Cádiz mapping tool (tool_leaflet_special_tools
in v6), which we have named tool_uca_maps in v7. First, what has been done and where, so you
can review it. Then, the three features that do not fully work yet. All three depend on core
pieces we would rather not touch without your judgement.

The tool is implemented and we have validated it by hand, feature by feature. It attaches to
component_geolocation (its only affected_models) and adds to the map a toolbar with one button
and one panel per feature:

object console (measurements, elevation, Geoman editing, centroid, uncertainty, hierarchy,
properties with PDF export, styles and associated images);
object viewer;
1x1 reference point;
XYZ basemaps;
WMS services;
Catastro parcels;
IGN administrative units;
upload of vector files (KML, GeoJSON, Shapefile) and georeferenceable images;
map download as an image;
place search (Nominatim);
browser geolocation;
manual legend;
historical Roman Empire data (Pleiades, Pelagios and DARE);
scale bar.

All of the tool's code lives in tools/tool_uca_maps/**, so the change can be reviewed in one
place and does not collide with your work when we rebase:

Path	What it is
`tools/tool_uca_maps/register.json`, `img/icon.svg`	The tool's registration and its icon
`tools/tool_uca_maps/server/` (19 TS modules)	The tool's actions (`server/index.ts`), each with its declared permission. They reach public services (Nominatim, Catastro, IGN, open-elevation, Pleiades, DARE) through `fetchGuardedText`. GDAL, ImageMagick and Poppler run through `runBinary` from `src/core/media/engine/spawn.ts`. Uploaded images enter as Images records (`rsc170`) through the normal ingest path.
`tools/tool_uca_maps/js/` (38 modules)	The client: one logic file and one render file per feature, plus the shared toolbar (`js/toolbar.js`)
`tools/tool_uca_maps/js/lib/`	Two third-party libraries, copied in: `dom-to-image-more` and `Leaflet.ImageOverlay.Rotated`. We know `engineering/VENDORING.md` sends them to `package.json`, as was done with `tool_qr`; that will go in a separate message.
`tools/tool_uca_maps/css/`	The `.less` sheet and its compiled `.css`
`tools/tool_uca_maps/gazetteers/provision.ts`	A maintenance script that downloads the Pleiades and Pelagios data (₂₀ MB) into a directory the installation chooses. The data does not go into the repository.

Outside that folder there are only tests, because the engine only runs them from there:

test/unit/tool_uca_maps_*.test.ts — 18 files, one per server action (215 tests). All of them
use the generic test TLD and build their own situation.
client/dedalo/test/client/js/test_tool_uca_maps.js — the client suite (251 tests).
client/dedalo/test/client/js/test_registry.js — a single line, to register that suite.

We have not touched anything under src/core/, client/dedalo/core/, engineering/ or docs/.
After today's rebase, typecheck and test:client pass. The tripwires still red are due to tool
contracts that have just landed and to shared counters. I'll cover those separately, since they
do not affect what follows.

My questions:

1. Third-party tiles: the CSP blocks them on screen and in the export

This is the underlying problem, and a single decision could close both sides.

On screen (img-src). src/core/api/static_asset.ts:207 allows a fixed list of five tile
domains. Several features exist precisely to load tiles from other servers:

WMS (any server the user types in);
XYZ basemaps (any server outside that list);
Catastro (ovc.catastro.meh.es);
administrative units (www.ign.es).

We have checked it in the browser with IGN and Catastro. The server-side request works, the
layers are listed and the parcels and polygons are created, but the browser blocks every
GetMap tile and the map shows the container's blue background. In v6 the IGN administrative
units layer does show, with its zones and names. No fixed list can cover "whatever server the
user chooses".

In the export (connect-src). Downloading the map as an image uses dom-to-image-more. To
avoid leaving the canvas tainted, that library downloads every <img> again over XHR and
inlines it as a data URL, and that download is governed by connect-src (static_asset.ts:210),
not img-src. The result: the exported image never has a basemap, even with the five allowed
domains. Polygons (inline SVG) and uploaded images (same origin) do come out. It also fails
silently: when blocked, the library throws no error, sets src = null, and the download
"succeeds" empty.

The options we see:

(a) Let each installation add trusted domains through configuration (a key read with
readEnv). It fixes the screen, but not the export. Putting third-party domains in
connect-src goes against what static_asset.ts itself argues about that directive, so we do
not propose it.
(b) Serve the tiles through our own server. It closes both sides at once, because
img-src 'self' and connect-src 'self' already cover them, and it stops depending on lists.
For the export no new HTTP route is needed: dom-to-image-more accepts a
requestInterceptor (which may return a promise), and a tool action that returns the bytes is
enough.

This is where we need your judgement. A tile is bytes, and none of the three outbound doors in
engineering/OUTBOUND_SPEC.md fits today:

fetchGuardedText always decodes to text (src/core/security/ssrf_guard.ts:1145), which
destroys a PNG.
harvestFetch returns bytes, but enforces at least 3 s between requests to the same origin
(src/core/harvest/pacing.ts, MIN_INTERVAL_MS). A map view asks for dozens of tiles at once.
Copying the guard into the tool is explicitly forbidden, and rightly so (CARRY-14).

2. Google Maps: domain outside img-src, and an unofficial endpoint

v6 ships "Google Maps" among its built-in basemaps, and we have kept it as is. Its tiles come from
mt1.google.com, which is not in img-src, so it shows blue on every installation. There is
also a nuance: that endpoint is not Google's official API (maps.googleapis.com). It is an
undocumented use that v6 already made, and we don't know whether Dédalo wants to inherit it.

3. Where a tool keeps its own data

Three features store configuration: the added XYZ and WMS layers, and the legend. In v6 they were
written to a server-side file per section_tipo, so they were shared by every record of that
section and by all users. In v7 today they only last for the session: they are lost on reload
or when switching records.

We expected that declaring "ontology" in register.json would make the engine create the tool's
section, but src/core/tools/register.ts:201-202 only stores that array in the dd1334 column of
matrix_tools, and nothing in the core reads it to create nodes. The only precedent we found,
dd1781 from tool_export, is a section that already existed.

The three features share the same mechanism, so a single solution works for all three.

Thanks in advance. Whatever you decide on these three points, we will implement it ourselves
inside the tool. If any solution involves touching the core, we would rather you define that change.

Sergio

Alex

Hi sergiofg

Thanks for the proposal.

We agree that (a) fixes the screen but not the export, and third-party domains don't belong in connect-src. So we'll proxy the tiles, with these constraints:

Build it in core, as its own route, not as a tool action. component_geolocation uses tiles on its own, so this isn't only the tool's concern. Once tiles come from our own origin, dom-to-image-more already reaches them under connect-src self, so the requestInterceptor isn't needed. When it's in place, the five hardcoded domains come out of img-src (static_asset.ts:207).
It must never be an open proxy. A request carries an id that points to a stored layer definition (see point 3), plus z/x/y or the WMS bbox/params. It never carries a URL. The server reads the stored source, checks that the user has read permission on it, and builds the upstream URL itself. It also requires an authenticated session.
The outbound door. You're right that none of the three fits as they stand today. But a tile is the same kind of request as fetchGuardedText: one vetted, pinned call to a known endpoint, redirects refused. It just needs the bytes back instead of text. readBytesCapped already sits under it, so the plan is a fetchGuardedBytes that shares the same transport and differs only in skipping the text decoding at the end. It is not a fourth door and not a copy of the guard. It needs:
- an edit to engineering/OUTBOUND_SPEC.md;
- a reasoned row in ssrf_one_guard_tripwire;
- the pin and body-cap legs of guarded_text_pin_native run against it.
  
  We'll handle the spec side; please don't copy the guard into the tool (CARRY-14 still applies).
Pacing: a per-origin cap on concurrent requests, not harvest's 3 s interval. That interval is for scraping a site the way a person would; a tile server is an API built for bursts.

A side benefit: visitors' IPs are no longer sent to third-party tile servers.

Google Maps → don't inherit it

mt1.google.com is not an endpoint Google documents, and fetching tiles that way bypasses the official APIs, which Google's terms prohibit. Dédalo shouldn't ship that by default, so please remove it from the built-in basemaps. If an institution wants Google, the route is the official Map Tiles API with the institution's own key. The key would be a documented config key read with readEnv, kept on the server and used only by the proxy. That can come later; it's not part of this work.

Where the tool keeps its data → in the component's data, not a new section

You're right that the ontology array in register.json is inert: it's stored in dd1334 and nothing reads it. We won't create a section for the tool. That field will be removed, and a tripwire added.

The layers go into component_geolocation's own data (the geo column in BD). They then live with the record: time machine, duplicate, export, import and diffusion all carry them with no extra work. The shape matters:

lib_data stays pure GeoJSON. Several places assume each item is {layer_id, layer_data: FeatureCollection}: the import validator (conformGeoLibData in import_conform.ts), append_merge.ts, the client's fn_geometry_positions / bounds code, export and the geo search. A WMS or XYZ source has no features, so it must not go in there.
Legend: a key on the lib_data item, next to user_layer_name:
{ "layer_id": 1, "layer_data": { "type": "FeatureCollection", "features": [] }, "user_layer_name": "layer_1", "legend": { } }
XYZ/WMS sources: a sibling key on the entry:
{ "id": 3, "lat": 0, "lon": 0, "zoom": 17, "lib_data": [], "sources": [ { "id": 1, "type": "wms", "url": "…", "params": { }, "attribution": "…" } ] }
Shared defaults per section: v6 shared layers per section_tipo; in this design they belong to each record. When every record of a section should show the same source (e.g. Catastro), put it in the component's ontology properties (for example properties.map_sources). Those are defaults an admin sets once, and the record's own sources add to them.

Core owns the data shape; the tool only edits it. Once it's in geo, it's the component's wire contract and has to outlive the tool. So:

add an engineering/wire_contract/ entry for the new keys;
extend conformGeoLibData (the import validator) and decide how append_merge treats them;
decide whether diffusion publishes source URLs;
save through the normal component save path, with no tool-only writer.

This also closes point 1. A proxy request names either a stored source (section_tipo, section_id, component_tipo, source_id) where source_id is the id of an item in the entry's sources array (unique across the component's value, never reused after a delete), or an ontology default, {component_tipo, default_id}, the id of an item in properties.map_sources. The server resolves either one against the user's read permission and fetches only the URL it stores; the tile cache is keyed by that upstream URL, not by the id. Anyone who can edit the component can therefore choose which public host the server fetches from. The guard refuses private addresses, and edit permission limits the rest.

One design covers all three: sources stored in the component → proxy → same-origin tiles. That fixes the screen, the export and persistence together.

It makes sense for you?

And do you want to implement the core part? We can do it... but if you want to, and you're clear on the implementation, you can do it yourself (we will review it before merge of course... 🙂)

Best

sergiofg

@Alex

Hi Alex,

Thanks. Yes, the design makes sense to us: it fixes the screen, the export and persistence in one go, and the data travels with the record. Point by point:

1. Tile proxy. Thanks for the offer, but we'd rather leave the core part to you if you are ok with it. The guard, the CSP and the component's contract are areas you know far better than we do, and we'd prefer not to touch them. Once it's in, we'll adapt the tool: when the user adds an XYZ or WMS layer, the tool saves the component and requests the tiles from the proxy. We accept that a new layer won't show until it's saved, even though in v6 it showed immediately.

2. Google Maps. We'll remove it from the tool's basemaps.

3. Data in the component. Agreed that core defines the shape. For it to fit the tool, here is what you need to know:

Built-in layers. Catastro (ovc.catastro.meh.es), IGN administrative units (www.ign.es/wms-inspire/unidades-administrativas) and DARE are built into the tool, and so are the OSM, Carto and ArcGIS basemaps. They are neither a source stored in the record nor an ontology default. How should they go through the proxy? A third kind of id, "built-in"?
Per record or per section. In v6, an added WMS or XYZ layer was stored per section_tipo: every record of that section and every user saw it. In your design it belongs to each record, and what is common to the section is set by an admin in properties.map_sources. Which one do you think is right?
Legend. In v6 it belongs to the whole map (a title plus groups of symbols), not to a layer, and it is also stored per section_tipo. Hanging it on a lib_data item doesn't fit: which layer does it hang on when there are several, or none? Also, its icons are data: URIs of up to 2 MB each, which would bloat geo.
Permission on a default. {component_tipo, default_id} carries no section_tipo, and permission in Dédalo is section_tipo + tipo.
WMS parameters the tool uses (Leaflet tileLayer.wms): service, request=GetMap, version, layers, styles, format, transparent, width, height, srs, bbox.

Best,
Sergio

sergiofg

Hi @Alex

We're finishing the implementation of tool_uca_maps and preparing everything for the PR.
Before we open it, six questions are still pending: in each one the tool's code depends on your
answer, so we'd rather ask than guess. They are independent of the tile proxy / data-shape thread
from 7 October.

All paths are relative to the repository root and checked against master as of 21 October.
The tool lives in tools/tool_uca_maps/.

A Beerware-licensed browser library
-----------------------------------------------------------------------------------------------

Today. The tool vendors two browser libraries under tools/tool_uca_maps/js/lib/:

dom-to-image-more 3.10.2 (MIT), used by js/map_image_download.js to export the map as an
image;
Leaflet.ImageOverlay.Rotated 0.1.4 (https://github.com/IvanSanchez/Leaflet.ImageOverlay.Rotated),
used by js/image_upload.js (loaded at :90, called at :631). It places a georeferenced image
by three corner points instead of a bounding box: a GeoTIFF reprojected to WGS84 is a
slightly rotated, skewed quadrilateral, and L.imageOverlay(url, bounds) would stretch it.

Plan. Following engineering/VENDORING.md §1 and the existing rows in
src/core/client_libs/registry.ts (qrcode, geoman), both move to exact npm pins (no ^) plus a
registry row each. That also clears dependency_integrity_tripwire and
client_idempotency_tripwire, and about 312 of the tool's lint:browser warnings.

The problem. Leaflet.ImageOverlay.Rotated is Beerware: "as long as you retain this notice you
can do whatever you want with this stuff" - as permissive as MIT, with no other condition. But
Beerware is not in LICENCE_SPDX_IDS (scripts/vendor_verify.ts:169: MIT, ISC, BSD-2/3-Clause,
Apache-2.0, GPL/LGPL, MPL-2.0), and adding it is a core decision.

Question. Is Beerware acceptable for a pinned dependency served to browsers (i.e. would you add
it to LICENCE_SPDX_IDS)? If not, we'll drop the library and reimplement its ₆₀ lines of logic
(the affine CSS transform from three corners) inside the tool, with its own tests.

Which outbound door for five third-party API lookups
-----------------------------------------------------------------------------------------------

Today. Five server modules of the tool call fixed public APIs with fetchGuardedText:

tools/tool_uca_maps/server/place_search.ts -> https://nominatim.openstreetmap.org/search
tools/tool_uca_maps/server/roman_empire.ts -> https://imperium.ahlfeldt.se/api/geojson.php (DARE)
tools/tool_uca_maps/server/catastro.ts -> https://ovc.catastro.meh.es/Cartografia/WMS/ServidorWMS.aspx
(GetFeatureInfo) and https://ovc.catastro.meh.es/INSPIRE/wfsCP.aspx (WFS)
tools/tool_uca_maps/server/administrative_units.ts -> https://www.ign.es/wms-inspire/unidades-administrativas
tools/tool_uca_maps/server/elevation.ts -> https://api.open-elevation.com/api/v1/lookup
Each one is a single interactive request triggered by a user action (a click on the map, a
keystroke in a search box), and v6 made the same calls with the same fixed endpoints.

The problem. Since 1 October, engineering/OUTBOUND_SPEC.md §2 (table row at :52) says
fetchGuardedText is "engine code only - never a tool", and test/unit/ssrf_one_guard_tripwire.test.ts
is red on exactly these five files. The door left to a tool, harvestFetch, cannot carry them:

it honours robots.txt, and Nominatim's robots.txt disallows /search for *, so the place
search would stop working;
it paces >= 3 s per origin (src/core/harvest/pacing.ts:36, MIN_INTERVAL_MS), which turns a
Catastro click into ₄-7 s and DARE's autocomplete into ₆-7 s.
And by the spec's own rule ("the request's KIND chooses the door") these are API calls, not
harvesting. What a user points the tool at (WMS GetCapabilities in server/wms.ts, linked images
in server/external_image.ts, the gazetteer dumps in gazetteers/provision.ts) already goes through
harvestFetch, and stays there. We won't copy the guard into the tool (CARRY-14).

Questions.
a. Where should these calls live: a per-service engine module like
src/core/tools/translation.ts, something under src/external/, or another place?
b. Fixed endpoints as in v6, or operator-configured?
c. Pacing: is the per-origin concurrency cap you designed for the tile proxy the right one
here? Nominatim's usage policy asks for <= 1 request/s and an identifying User-Agent.
As with the proxy, we'd leave the engine side to you and adapt the tool to whatever door you
provide.

Who shows a tool's refusal to the user
-----------------------------------------------------------------------------------------------

Today. When the tool refuses something (a .zip without a .shp, a file GDAL cannot convert, a
target it cannot process), its server throws a public DedaloError - request.invalid_options,
tool.unsupported_target, media.file_not_found or media.upload_rejected - with the concrete
reason as publicMessage. 18 of the tool's 46 throws carry one. Then, on the client:

client/dedalo/core/common/js/data_manager.js:798 publishes every api_error, so the page
shows its notice (top right);
that notice uses error_text() in client/dedalo/core/common/js/render_api_error.js:75, which
shows the code's label from master.json - the generic one ("Invalid request options"),
since tool codes are generic by design (src/core/errors/registry.ts:2470);
so the tool also writes its own line in the panel the user is working in
(tools/tool_uca_maps/js/tool_error_text.js, REASON_CODES): a translated lead ("The file
could not be uploaded") plus the concrete reason, which is English because publicMessage has
no translation path.
The user sees two notices for one refusal, and only the tool's says what happened.

What we can't do in the tool. data_manager has notices:'caller' (:524, :825) for a caller that
renders its own notices, but nothing equivalent for a failure; registering the codes as silent
would mute them page-wide. And a concrete, translated message would need either new codes with
master.json labels or a label coming from the tool's register.json - both are core decisions.

Question. Do you want core to be the one that shows a tool's refusal, with a translated text
that says what happened (and the tool to drop its own line)? Or which approach do you prefer?
Whatever you choose, we'll map the tool's 18 reasons to it.

A retryable failure on a read ends as "outcome unknown"
-----------------------------------------------------------------------------------------------

What the user sees. They click a parcel while Catastro is in maintenance and, instead of
"Catastro is not responding", they read idempotency.outcome_unknown: "The first attempt failed
after it may already have been applied" - on a lookup that writes nothing.

Why it happens.

Some codes are retryable in src/core/errors/registry.ts: security.outbound_failed (thrown
by the guard when the remote server fails), rate.limited, external.http_status. On those,
data_manager retries automatically with the same idempotency_key (default 5 retries).
Every tool action goes through tool_request, classed mutating in
src/core/api/dispatch.ts:390 because it is a polymorphic door - the right fail-safe for
writes.
When a mutating action throws, runIdempotentLeader (src/core/api/dispatch.ts:933, catch at
:968-982) keeps the key marked ambiguous, so every retry gets idempotency.outcome_unknown
instead of the real error.
A tool cannot opt out: tool_request in client/dedalo/core/tools_common/js/tool_common.js
(request at :662) forwards no retries option to data_manager.request.

Effect on the tool's code. To avoid it, the tool answers a non-2xx from a provider with
tool.action_failed (not retryable) instead of the code the registry intends,
external.http_status (server/wms.ts:73, server/roman_empire.ts:357, server/external_image.ts:123).
But security.outbound_failed is thrown by the guard itself, so with Catastro, IGN or Nominatim
down the user does get the misleading message, in normal use.

Question. Should a thrown retryable failure be stored as a replayable answer (so the retry gets
the real error), or should a tool action be able to declare itself read-only - or pass
retries through tool_request? With either, we'd switch those three files to
external.http_status / external.not_found.

The tool's colour tokens don't reach its panels
-----------------------------------------------------------------------------------------------

Today. scripts/tool_colors.ts:270 emits each tool's four tokens (--tool_edge, --tool_fill,
--tool_fill_hover, --tool_on_fill) under .tool_header.<tool>, .wrapper_tool.<tool> only
(generated into client/dedalo/core/tools_common/css/tool_colors.less, :440-447 for this tool),
and since 83394ab5ae the checkbox/radio accent keys off the same selector pair.

The problem. tool_uca_maps works on component_geolocation's map: its modal is only a launcher
that closes itself once the tool's controls are on the map, and every panel hangs off the map container, outside
any .wrapper_tool. There the tokens don't exist, so:

test/unit/tool_color_contrast_tripwire.test.ts is red;
the panels can't use the shared .tool_action_button() mixin
(client/dedalo/core/tools_common/css/tool_mixins.less:16) - it has no colours there - so
the tool keeps its own mixins with the same pixels (only the hover differs).
Giving each panel the .wrapper_tool class drags in page layout from
client/dedalo/core/tools_common/css/tool_common.less:33-41 (contain:content, display:flex,
flex-wrap, min-height:inherit), and copying the token values into the tool's stylesheet would
fork what the generator owns.

Question. Would you add a box-free scope to the generator, e.g. [data-tool="<tool>"], used by
both the token rule and the checkbox accent? We'd put that attribute on each panel and switch
the buttons to .tool_action_button().

Which languages a tool should ship
-----------------------------------------------------------------------------------------------

Today. tools/tool_uca_maps/register.json carries its labels (about 434) in lg-eng and lg-spa
only. Most tools ship the same ten (lg-cat, lg-deu, lg-ell, lg-eng, lg-eus, lg-fra, lg-ita,
lg-nep, lg-por, lg-spa), some add lg-ara and lg-vlca; a missing lang falls back down
resolve/lang_fallback.ts. We can review lg-spa, lg-cat and lg-vlca ourselves; any other lang
would be machine-translated.

Question. Is there a minimum set of languages a tool must ship for the PR? And for the langs no
one on our side can review, do you prefer machine translations or leaving them to the fallback?

Best,
Sergio