pmtiles-swarm 0.75.0 → 0.77.0

package/CHANGELOG.md

@@ -7,6 +7,73 @@
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 
+## 0.77.0
+### ✨ Features and improvements
+- **A fade can be written in metres of ground.** `featherMetres` on a source says how far to blend
+  it in as a distance, and the merge works out the pixels for each tile it builds -
+  `40075016.686 x cos(latitude) / 2^zoom / tileSize` of them. What a fade has to hide is two sources
+  disagreeing about the height of the same ground, which is a fixed number of metres, while a fade
+  in pixels is a different distance at every zoom.
+
+  It matters because a hillshade reads slope rather than height. `feather: 8` over a 7 m
+  disagreement is a gradient of 0.08 at z12 and 1.28 at z16 - invisible at one end and a saturated
+  band at the other, wider than the cliff it replaced and no less visible. The same 50 m holds 0.14
+  at every zoom, which is ordinary hillside. Below the zoom where the fade is a pixel wide it rounds
+  to nothing, and it is capped at a quarter of the tile - 128 pixels on a 512px grid, which is where
+  the old 64 came from. `featherMeters` is read as well, and the console's fade field now takes a
+  unit rather than always meaning pixels.
+
+- **A tool that measures the step a fade has to hide.** `tools/coast-step.mjs` reports the height
+  difference where one source hands over to another, and says which kind of disagreement it is.
+  Steps that cluster are a vertical datum offset, which one `heightAdjustment` corrects. Steps that
+  scatter are a coarse source averaging land and water together in every cell that straddles a
+  coast - worst at the shore, gone offshore - which no single number corrects and a fade can only
+  hide.
+
+### 🐞 Bug fixes
+- **A mask range was not an edge to fade at.** A source whose only mask was a `maskRange` was told
+  its `feather` had nothing to act on, and refused - while the merge had been fading exactly that
+  edge all along. The recipe validation and the console's own warning both listed `maskValues` and
+  `maskColors` and neither had been taught about the band.
+
+## 0.76.0
+### ✨ Features and improvements
+- **A stopped export stays stopped.** Stopping one left a checkpoint, and a checkpoint says what was
+  in progress but not why it stopped - so the next restart could not tell somebody pressing Stop
+  from a crash, and picked it up again. Stopping now writes a marker beside the checkpoint, and a
+  restart reports what it is holding rather than resuming it. Starting or resuming clears the marker.
+
+  And the work can be thrown away, which it could not be before: `DELETE /api/stacks/:id/bake/work`
+  removes the working directory, which for an abandoned export is hundreds of gigabytes of buffered
+  tiles that previously had to be found by hand. Refused while a merge is running rather than pulled
+  out from under it.
+
+### 🐞 Bug fixes
+- **An edit inside one clock tick went unnoticed.** `stacks.json` is re-read when its modification
+  time changes, and a filesystem's clock is coarser than an edit: on NTFS the tick is about 15 ms,
+  measured here at 36 rapid rewrites in 40 landing on the same timestamp. Two edits that close
+  together left the mtime alone and the second was never read.
+
+  The size is compared as well now, which catches the ones that changed the file's length - most of
+  them - and costs nothing, since the stat was already being made.
+
+  This is also what made the reload test flake, roughly one run in three: it wrote the file twice in
+  quick succession and then depended on how those two writes fell against the clock. It stamps both
+  writes to the same instant now and asserts they really are the same, so it tests whether a change
+  is noticed rather than whether the clock happened to tick.
+- **A stack with a shallow global source served holes above z14.** How far the merge would climb
+  for a source with no tile at this zoom was a fixed six levels. GEBCO is z0-8 and the sea floor has
+  no more detail to give, so a stack serving z16 has to upscale that z8 tile eight levels - and at
+  z15 the climb stopped one short of the only tile that existed. Over open water, where the other
+  source was sparse and had nothing either, no source contributed at all and the stack correctly
+  answered no-tile. A rectangular hole, one tile wide, in the middle of the sea.
+
+  It is derived now rather than fixed: the deepest zoom the stack serves, less the shallowest source
+  under it. Nothing to set and nothing to get wrong - the right answer is computable, and a smaller
+  one would only punch holes. Somebody who wants the merge to stop climbing says so with `maxzoom`,
+  which stops the stack serving that deep at all: the same wish, said where it also stops the work.
+  Never below the old six, so no stack reaches less far than it did.
+
 ## 0.75.0
 ### ✨ Features and improvements
 - **`maskRange`, because nodata is a band and not a number.** `maskValues` and `maskColors` both

package/docs/tile-stacks.md

@@ -50,6 +50,8 @@ of its parts.
   - [Starting one, and watching it](#starting-one-and-watching-it)
   - [What exists now](#what-exists-now)
 - [Clipping a source to a shape](#clipping-a-source-to-a-shape)
+- [What a mask has to match](#what-a-mask-has-to-match)
+- [Feathering a seam](#feathering-a-seam)
 - [Finding a stack](#finding-a-stack)
 - [Syncing a stack to another node](#syncing-a-stack-to-another-node)
 - [What the offline merge got wrong](#what-the-offline-merge-got-wrong)
@@ -233,19 +235,20 @@ it differs from the snake_case rio-rgbify-merge uses.
 
 ### Source fields
 
-| Field                  | Meaning                                                                                                    |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `category`             | Resolve to the newest build in this category.                                                              |
-| `archive`              | Or pin one infohash. Exactly one of the two.                                                               |
-| `required`             | A tile fails rather than being served without this source. Defaults true for the bottom-most, false above. |
-| `encoding`             | `mapbox` or `terrarium`. Elevation space only.                                                             |
-| `baseVal` / `interval` | Mapbox decode offset and step. Default `-10000` and `0.1`.                                                 |
-| `maskValues`           | Decoded heights meaning "no data here". Elevation space only.                                              |
-| `maskRange`            | `[low, high]` in metres, or a list of them. Everything inside is nodata. Elevation space only.             |
-| `heightAdjustment`     | Metres, added **after** masking. Elevation space only.                                                     |
-| `feather`              | Pixels to fade in over at the edge of the source's shape. Needs a `cutline` or `bounds`. Max 64.           |
-| `opacity`              | `0`–`1`, scales the source alpha. RGBA space only.                                                         |
-| `blend`                | `normal`, `multiply`, `screen`, `overlay`, `darken`, `lighten`. RGBA space only.                           |
+| Field                  | Meaning                                                                                                      |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `category`             | Resolve to the newest build in this category.                                                                |
+| `archive`              | Or pin one infohash. Exactly one of the two.                                                                 |
+| `required`             | A tile fails rather than being served without this source. Defaults true for the bottom-most, false above.   |
+| `encoding`             | `mapbox` or `terrarium`. Elevation space only.                                                               |
+| `baseVal` / `interval` | Mapbox decode offset and step. Default `-10000` and `0.1`.                                                   |
+| `maskValues`           | Decoded heights meaning "no data here". Elevation space only.                                                |
+| `maskRange`            | `[low, high]` in metres, or a list of them. Everything inside is nodata. Elevation space only.               |
+| `heightAdjustment`     | Metres, added **after** masking. Elevation space only.                                                       |
+| `feather`              | Pixels to fade in over wherever the source stops: a `cutline`, `bounds`, or the holes a mask leaves. Max 64. |
+| `featherMetres`        | The same fade written as metres of ground, worked out per tile. Usually the one to reach for.                |
+| `opacity`              | `0`–`1`, scales the source alpha. RGBA space only.                                                           |
+| `blend`                | `normal`, `multiply`, `screen`, `overlay`, `darken`, `lighten`. RGBA space only.                             |
 
 `attribution` is not optional in practice. A stack is a derived work of every
 source in it, and the thing that reliably gets lost when tiles are combined is
@@ -1085,8 +1088,8 @@ standing clear of their neighbours, which is the shape this makes.
 
 ## Feathering a seam
 
-_Built for a cutline and for `bounds`. A mask edge is not feathered yet, and
-the last section says what that still needs._
+_Built for a cutline, for `bounds`, and for the holes a mask leaves. A source
+that vanishes at a tile edge is still open, and the last section says why._
 
 Smoothing hides the terracing **inside** an upscaled area. It does nothing about
 the artefact the original discussion actually named — "artefacts at tiles and
@@ -1236,18 +1239,40 @@ lookup rather than a decode — and it is not done.
 
 `feather` on a source, in pixels, `0` and absent meaning the edge is a switch as
 before. It fades that source in over that many pixels measured inward from
-wherever it stops — the holes `maskValues` and `maskColors` leave, and the edge
-of a `cutline` or `bounds`:
+wherever it stops — the holes `maskValues`, `maskRange` and `maskColors` leave,
+and the edge of a `cutline` or `bounds`:
 
 ```json
 { "archive": "swissalti", "maskValues": [0], "feather": 16 }
 ```
 
-The step left at the seam is the height difference divided by the feather, which
-is what makes the number predictable: two sources 40 m apart at the border, faded
-over 16 pixels, step 2.5 m a pixel instead of 40 m at once. Sixty-four is the
-most it takes — past that the ramp does not reach full weight anywhere inside a
-256px tile, and the source is being turned down rather than blended in.
+The step left at the seam is the height difference divided by the feather: two
+sources 40 m apart at the border, faded over 16 pixels, step 2.5 m a pixel
+instead of 40 m at once. Sixty-four is the most it takes — past that the ramp
+does not reach full weight anywhere inside a 256px tile, and the source is being
+turned down rather than blended in.
+
+**A smaller step is not the same as an invisible one**, and that is the thing to
+know before picking a number. A hillshade does not read height, it reads slope:
+the drop divided by the ground underneath it. What decides whether a seam
+disappears is therefore metres per metre rather than metres per pixel — and a
+pixel is a different number of metres at every zoom. The same `feather: 8`, over
+the same 7 m disagreement, at 55°N:
+
+| zoom | m/pixel | gradient |
+| ---- | ------- | -------- |
+| z12  | 11.0    | 0.08     |
+| z13  | 5.5     | 0.16     |
+| z14  | 2.7     | 0.32     |
+| z15  | 1.4     | 0.64     |
+| z16  | 0.7     | 1.28     |
+
+Natural terrain is rarely over about 0.5 and a hillshade saturates around there,
+so a fade that vanishes at z12 is a bright band by z15 — wider than the cliff it
+replaced and no less visible. Widening it does help at any one zoom, since the
+gradient is the drop over the whole fade; the difficulty is that the number
+which works at z16 is eight times the one that works at z13, and a recipe has
+one number.
 
 Three things fall out of the implementation and are worth stating.
 
@@ -1268,22 +1293,52 @@ envelope — linear in the tile's width, and chosen over a chamfer approximation
 because a chamfer's error is largest on diagonals and a national boundary is
 mostly diagonals.
 
-### What it does not do yet
+### A fade in metres
+
+`featherMetres` says the same thing as a distance on the ground, and the merge
+works out the pixels for each tile it builds:
 
-**A mask edge.** `maskValues` and `maskColors` are where most seams actually come
-from, and they are not feathered. The reason is the margin: a cutline is known in
-full, so the ramp beside a tile can be computed by rasterising a few extra rows,
-while a mask edge lives in the source's own pixels and the ramp needs the
-neighbouring tiles to be read and decoded — up to eight of them, for that source,
-on that tile.
-
-That is the piece with a real cost attached, and the one to measure before
-building. Two things make it more tractable than it looks: in a bake the tiles
-are walked in Hilbert order, which is chosen for locality, so a cache of decoded
-source tiles would be hit far more often than missed; and the ramp is smooth by
-construction, so it can be computed from the source's _parent_ at half resolution
-and upscaled, which turns eight reads at this zoom into a handful at the one
-above, shared between four children.
+```json
+{ "archive": "gebco", "maskRange": [-1, 0], "featherMetres": 50 }
+```
+
+Web Mercator makes that arithmetic rather than a lookup: one pixel covers
+`40075016.686 × cos(latitude) / 2^zoom / tileSize` metres, so the conversion
+needs a multiply and the coordinates of the tile being built. `featherMeters` is
+read as well, because a key that quietly does nothing when spelled the other way
+is the failure this feature is most prone to.
+
+Fifty metres, over the same 7 m disagreement, at 55°N on 512px tiles:
+
+| zoom | m/pixel | pixels | ground | gradient |
+| ---- | ------- | ------ | ------ | -------- |
+| z12  | 11.0    | 5      | 55 m   | 0.13     |
+| z13  | 5.5     | 9      | 49 m   | 0.14     |
+| z14  | 2.7     | 18     | 49 m   | 0.14     |
+| z15  | 1.4     | 36     | 49 m   | 0.14     |
+| z16  | 0.7     | 73     | 50 m   | 0.14     |
+
+One number, the same slope at every zoom, and 0.14 is ordinary hillside rather
+than an edge.
+
+It stops being exact at both ends, benignly. Below the zoom where the fade is a
+pixel wide it rounds to nothing — 50 m at z8 is a sixth of a pixel, and the whole
+coastline is inside one pixel there anyway. Above a quarter of the tile it is
+capped, which is 128 pixels on a 512px grid and is where the old 64 came from:
+past that the ramp reaches full weight nowhere inside the tile. At 55°N the cap
+first binds at z17.
+
+**Picking the number.** It is the disagreement being hidden that sets it, not the
+coastline being drawn across. `tools/coast-step.mjs` measures the first against a
+real tile: it reports the step where one source hands over to the other, and
+whether those steps cluster — in which case they are a datum offset and
+`heightAdjustment` is the honest fix — or scatter, in which case nothing corrects
+them and a fade is for hiding what cannot be corrected. Divide the step by the
+gradient wanted: 7 m at 0.15 is about 50 m, and the same step at 0.05 would need
+140 m, which is wide enough to start flattening ground either side of the coast
+that was never wrong.
+
+### What it does not do yet
 
 **A source that vanishes at a tile edge.** A sparse archive simply has no tile
 outside its extent, so the seam lands exactly on a tile boundary — the most

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmtiles-swarm",
-  "version": "0.75.0",
+  "version": "0.77.0",
   "description": "BitTorrent distribution for PMTiles map archives: create torrents, watch folders, publish and subscribe to RSS feeds, and seed through qBittorrent or an embedded client",
   "type": "module",
   "main": "src/index.js",

package/src/api.js

@@ -3303,6 +3303,31 @@ export function createApp({
     }),
   );
 
+  /**
+   * Throws away what a stopped export had done.
+   *
+   * Separate from stopping, and deliberately a second decision. Stopping keeps
+   * the work because an export may be hours in and somebody may want it back;
+   * this is for when they do not, and until now the only way to be rid of
+   * hundreds of gigabytes of buffered tiles was to find the directory by hand.
+   */
+  app.delete(
+    '/api/stacks/:id/bake/work',
+    route(async (req, res) => {
+      if (!bakes) {
+        return res.status(501).json({ error: 'this node does not bake' });
+      }
+      const discarded = await bakes.discard(req.params.id);
+      if (!discarded) {
+        return res.status(409).json({
+          error:
+            'there is no stopped export for that stack, or one is still running',
+        });
+      }
+      return res.json({ discarded: true });
+    }),
+  );
+
   /**
    * Creates or replaces a stack.
    *

package/src/bake-jobs.js

@@ -7,7 +7,11 @@ import {
   bakeStack,
   bakedArchiveName,
   bakedName,
+  clearStopped,
+  discardCheckpoint,
+  markStopped,
   mergeTileFor,
+  wasStopped,
 } from './bake.js';
 import { PixelWorker } from './pixels.js';
 import { outputFormat } from './stack-tile.js';
@@ -124,6 +128,10 @@ export class BakeManager {
   #loadCodec;
   #cutlines;
   #jobs = new Map();
+  // Exports somebody stopped, whose work is still on disk. Kept so the console
+  // can offer to resume or discard them: after a restart there is no job in
+  // memory, only a directory nobody would think to look for.
+  #held = new Map();
 
   /**
    * @param {object} deps - The library, the tile store, the config and the codec probe.
@@ -152,11 +160,36 @@ export class BakeManager {
    */
   get(stackId) {
     const job = this.#jobs.get(stackId);
-    return job ? this.#describe(job) : null;
+    if (job) return this.#describe(job);
+
+    // Nothing running, but work somebody stopped may still be there. Reported
+    // in the same shape so the console has one thing to read.
+    const stopped = this.#held.get(stackId);
+    if (!stopped) return null;
+    return {
+      stackId,
+      phase: 'stopped',
+      written: stopped.written,
+      resumable: true,
+      ...stopped.describe,
+    };
+  }
+
+  /**
+   * Every stack with work waiting that nobody has decided about.
+   * @returns {string[]} - Their ids.
+   */
+  heldStacks() {
+    return [...this.#held.keys()];
   }
 
   /**
-   * Stops a bake, leaving its work where the next run can pick it up.
+   * Stops a bake, leaving its work for somebody to pick up or throw away.
+   *
+   * Marked as stopped on purpose, so the next start leaves it alone. The work
+   * is still there and `resume` takes it up again -- what changes is who
+   * decides, which for a job that may be hours from finishing should be a
+   * person rather than a restart.
    * @param {string} stackId - Which stack.
    * @returns {boolean} - True if there was one to stop.
    */
@@ -164,10 +197,46 @@ export class BakeManager {
     const job = this.#jobs.get(stackId);
     if (!job || job.finishedAt) return false;
     job.cancelling = true;
+    job.stoppedOnPurpose = true;
     job.controller.abort();
+    // Not awaited: the abort has to reach the merge now, and a mark written a
+    // moment later is still written long before anything restarts.
+    markStopped(workDirFor(job, this.#config)).catch(() => {});
     return true;
   }
 
+  /**
+   * Throws away what a stopped export had done.
+   *
+   * The counterpart to stopping. An export that will not be finished leaves
+   * hundreds of gigabytes of buffered tiles behind, and until now the only way
+   * to be rid of them was to find the directory by hand.
+   * @param {string} stackId - Which stack.
+   * @returns {Promise<boolean>} - True if there was work to discard.
+   */
+  async discard(stackId) {
+    const running = this.#jobs.get(stackId);
+    // Refused rather than raced. Removing the directory under a running merge
+    // would have it fail on its next write, reporting a disk problem for
+    // something somebody chose.
+    if (running && !running.finishedAt) return false;
+
+    let found = false;
+    for (const root of this.#workRoots()) {
+      const directory = path.join(root, WORK_DIR, stackId);
+      const there = await fs
+        .access(directory)
+        .then(() => true)
+        .catch(() => false);
+      if (!there) continue;
+      await discardCheckpoint(directory);
+      found = true;
+    }
+    this.#jobs.delete(stackId);
+    this.#held.delete(stackId);
+    return found;
+  }
+
   /**
    * Picks up exports a previous run did not finish.
    *
@@ -203,6 +272,21 @@ export class BakeManager {
         const resolved = resolve(stackId);
         if (!resolved || bakeRevision(resolved) !== state.revision) continue;
 
+        // Somebody stopped this one. It stays where it is until they say
+        // otherwise -- an export begun again by a restart is the opposite of
+        // what pressing Stop meant.
+        if (await wasStopped(path.join(directory, stackId))) {
+          this.#held.set(stackId, {
+            written: state.written ?? 0,
+            describe: state.describe,
+          });
+          console.log(
+            `[bake] ${stackId} was stopped on purpose; leaving its ` +
+              `${state.written ?? 0} tiles for you to resume or discard`,
+          );
+          continue;
+        }
+
         try {
           const job = await this.start({ resolved, ...state.describe });
           started.push(job);
@@ -367,6 +451,12 @@ export class BakeManager {
     const destination = path.join(workDir, job.name);
     const format = outputFormat(resolved);
 
+    // Running again is the answer to having been stopped, so the mark goes.
+    // Left behind, an export somebody restarted by hand would be passed over
+    // by the next restart, which is the same surprise the other way round.
+    await clearStopped(workDir);
+    this.#held.delete(job.stackId);
+
     // Sized with the batch, so every merge in flight has a thread to do its
     // arithmetic on rather than queueing behind one. Only where there is pixel
     // work to move: a passthrough bake hands bytes straight through and would

package/src/bake.js

@@ -42,6 +42,7 @@ const DEFAULT_CONCURRENCY = 4;
 /** What the working directory holds while a bake is in progress. */
 const FILES = Object.freeze({
   state: 'bake-state.json',
+  stopped: 'bake-stopped.json',
   entries: 'bake-entries.bin',
   tiles: 'bake-tiles.bin',
 });
@@ -59,6 +60,64 @@ export function checkpointPaths(workDir) {
   };
 }
 
+/**
+ * Records that an export was stopped on purpose.
+ *
+ * A checkpoint says what was in progress, not why it stopped, so a crash and
+ * somebody pressing Stop look identical on disk -- and the node picks both up
+ * on the next start. That is right for the crash and wrong for the person, who
+ * stopped it and then watched it begin again.
+ *
+ * Written beside the checkpoint rather than into it, so it cannot be lost to a
+ * half-finished write of the state the export is still making.
+ * @param {string} workDir - The bake's working directory.
+ * @returns {Promise<void>} - Resolves once it is written.
+ */
+export async function markStopped(workDir) {
+  await fs
+    .writeFile(
+      path.join(workDir, FILES.stopped),
+      JSON.stringify({ at: new Date().toISOString() }),
+    )
+    .catch(() => {});
+}
+
+/**
+ * Forgets that an export was stopped, because it is running again.
+ * @param {string} workDir - The bake's working directory.
+ * @returns {Promise<void>} - Resolves once it is gone.
+ */
+export async function clearStopped(workDir) {
+  await fs
+    .rm(path.join(workDir, FILES.stopped), { force: true })
+    .catch(() => {});
+}
+
+/**
+ * Whether an export was stopped on purpose rather than interrupted.
+ * @param {string} workDir - The bake's working directory.
+ * @returns {Promise<boolean>} - True when somebody stopped it.
+ */
+export async function wasStopped(workDir) {
+  return fs
+    .access(path.join(workDir, FILES.stopped))
+    .then(() => true)
+    .catch(() => false);
+}
+
+/**
+ * Forgets an export's unfinished work.
+ *
+ * The whole directory, because a checkpoint is only meaningful with the tiles
+ * it names -- leaving either behind is leaving something that will be picked
+ * up and found wanting.
+ * @param {string} workDir - The bake's working directory.
+ * @returns {Promise<void>} - Resolves once it is gone.
+ */
+export async function discardCheckpoint(workDir) {
+  await fs.rm(workDir, { recursive: true, force: true });
+}
+
 /**
  * One entry, as a checkpoint stores it.
  *

package/src/cutline.js

@@ -45,6 +45,31 @@ export function worldY(lat) {
   );
 }
 
+/** The world across the equator, in metres: what a zoom 0 tile spans. */
+const EQUATOR = 40075016.686;
+
+/**
+ * How much ground one pixel of a tile covers, at that tile's latitude.
+ *
+ * Web Mercator holds a pixel to a fixed fraction of the world, so the ground
+ * under it shrinks toward the poles and halves at every zoom. That is why a
+ * fade written in pixels is a different width of ground everywhere it is used,
+ * and this is the conversion that lets one written in metres mean the same
+ * thing. Taken at the middle of the tile: the scale changes across it, but a
+ * tile is a small piece of the world at any zoom where a fade is more than a
+ * pixel wide.
+ * @param {number} z - Zoom.
+ * @param {number} y - Row.
+ * @param {number} size - Pixels per side of the tile.
+ * @returns {number} - Metres per pixel.
+ */
+export function metresPerPixel(z, y, size) {
+  const tiles = 2 ** z;
+  const middle = (y + 0.5) / tiles;
+  const latitude = Math.atan(Math.sinh(Math.PI * (1 - 2 * middle)));
+  return (EQUATOR * Math.cos(latitude)) / (tiles * size);
+}
+
 /**
  * Reads the rings out of GeoJSON, whatever shape it arrived in.
  *

package/src/cutlines.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { fromBounds, fromGeoJSON } from './cutline.js';
+import { fromBounds, fromGeoJSON, metresPerPixel } from './cutline.js';
 
 /**
  * The cutlines a node has, by name.
@@ -101,16 +101,63 @@ export class CutlineStore {
  */
 export const MAX_FEATHER = 64;
 
+/** Past this a fade in metres is a typo rather than a distance. */
+export const MAX_FEATHER_METRES = 100000;
+
+/**
+ * The widest fade a grid of this size will take.
+ *
+ * A quarter of the tile, which is where 64 came from and what it still means on
+ * a 512px one: past that the ramp reaches full weight nowhere inside the tile,
+ * and the source is being turned down rather than blended in. It binds on a
+ * fade in metres, which asks for more pixels at every zoom.
+ * @param {number} size - Pixels per side of the grid the ramp runs on.
+ * @returns {number} - The most pixels a fade may be.
+ */
+function capFor(size) {
+  return Math.max(MAX_FEATHER, Math.round((size ?? 0) / 4));
+}
+
 /**
- * How far a source fades in at the edge of its shape.
+ * How far a source fades in, as metres of ground, if it is written that way.
+ *
+ * Both spellings are read. A recipe key that does nothing when it is spelled
+ * the other way is the failure this whole feature is most prone to, and the
+ * prose here says metres while half the world's config files say meters.
+ * @param {object} recipe - One source out of a recipe.
+ * @returns {number} - Metres, 0 when the fade is not written in them.
+ */
+export function featherMetresFor(recipe) {
+  const asked = Number(recipe?.featherMetres ?? recipe?.featherMeters);
+  return Number.isFinite(asked) && asked > 0 ? asked : 0;
+}
+
+/**
+ * How far a source fades in at the edge of its shape, in this tile's pixels.
  *
  * Zero is the old behaviour and the default: the shape is a switch, and a pixel
  * is either the source or what is underneath it. Anything more makes it a ramp.
- * See docs/tile-stacks.md -- "Feathering a seam".
+ *
+ * A fade in metres is converted here, which is why this wants the tile. What
+ * the fade has to hide is two sources disagreeing about the height of the same
+ * ground, which is a fixed number of metres -- so the same number of pixels is
+ * too wide at one zoom and too steep at the next. See docs/tile-stacks.md --
+ * "Feathering a seam".
  * @param {object} recipe - One source out of a recipe.
+ * @param {object} [tile] - `{z, y, size}` of the tile being built.
  * @returns {number} - Pixels, 0 when it does not fade.
  */
-export function featherFor(recipe) {
+export function featherFor(recipe, tile) {
+  const size = tile?.size > 0 ? tile.size : 256;
+  const metres = featherMetresFor(recipe);
+  if (metres > 0) {
+    // With no tile there is no scale to convert against, and a fade that
+    // guessed one would be a different width from the tiles beside it.
+    if (!Number.isFinite(tile?.z)) return 0;
+    const perPixel = metresPerPixel(tile.z, tile.y ?? 0, size);
+    return Math.min(Math.round(metres / perPixel), capFor(size));
+  }
+
   const asked = Number(recipe?.feather);
   if (!Number.isFinite(asked) || asked <= 0) return 0;
   return Math.min(Math.round(asked), MAX_FEATHER);

package/src/stack-tile.js

@@ -36,9 +36,42 @@ import { TileReadError } from './tiles.js';
  * a tile in an archive or a hole where one is not needed.
  */
 
-/** How far up the pyramid a merge will climb for a source with no tile here. */
+/**
+ * How far up the pyramid a merge will climb for a source with no tile here,
+ * where the stack does not say and nothing can be worked out.
+ */
 const PARENT_LIMIT = 6;
 
+/**
+ * How far this stack has to climb for its shallowest source to keep working.
+ *
+ * A global source is shallow on purpose -- GEBCO is z0-8 and the sea floor has
+ * no more detail to give -- so serving a stack to z16 means upscaling that z8
+ * tile eight levels. A fixed limit truncates exactly the arrangement this
+ * feature is for: at z15 the climb stopped one level short of the only tile
+ * that exists, no source contributed, and the stack answered no-tile over open
+ * water.
+ *
+ * So it is derived from what the stack spans rather than assumed or set: the
+ * right answer is computable, and a recipe naming a smaller one would only
+ * punch holes in itself. Somebody who wants the merge to stop climbing says so
+ * with `maxzoom`, which stops the stack serving that deep at all -- the same
+ * wish, said where it also stops the work.
+ *
+ * Never below the old fixed limit, so no stack reaches less far than it did.
+ * @param {object} resolved - The resolved stack.
+ * @returns {number} - Levels a source may climb.
+ */
+export function parentLimitFor(resolved) {
+  const { maxzoom } = stackCoverage(resolved);
+  const shallowest = resolved.sources
+    .map((source) => source.entry?.pmtiles?.maxZoom)
+    .filter((zoom) => Number.isFinite(zoom));
+  if (!shallowest.length || !Number.isFinite(maxzoom)) return PARENT_LIMIT;
+
+  return Math.max(PARENT_LIMIT, maxzoom - Math.min(...shallowest));
+}
+
 /** The deepest zoom a tile id is defined for. */
 const MAX_ZOOM = 26;
 
@@ -118,7 +151,7 @@ export function clipsFor(resolved, cutlines, z, x, y, size = 256) {
     // The feather reaches inward from the edge, so a tile wholly inside but
     // near it still has a ramp across part of itself and cannot take the cheap
     // answer.
-    const feather = featherFor(recipe);
+    const feather = featherFor(recipe, { z, y, size });
     return {
       shape,
       feather,
@@ -141,8 +174,8 @@ export function clipsFor(resolved, cutlines, z, x, y, size = 256) {
  * @param {object} options - Source, coordinates, the tile store and whether to climb.
  * @returns {Promise<object|null>} - The tile and the zoom it came from.
  */
-async function readFrom({ source, z, x, y, tiles, climb, signal }) {
-  const floor = climb ? Math.max(0, z - PARENT_LIMIT) : z;
+async function readFrom({ source, z, x, y, tiles, climb, signal, limit }) {
+  const floor = climb ? Math.max(0, z - (limit ?? PARENT_LIMIT)) : z;
   for (let at = z; at >= floor; at -= 1) {
     const shift = z - at;
     const tile = await tiles.getTile(
@@ -322,6 +355,7 @@ export function passThroughRead({
  * @returns {Promise<object>} - `{contributors, contributions}` or `{error}`.
  */
 async function readAll({ resolved, z, x, y, tiles, signal, clips }) {
+  const limit = parentLimitFor(resolved);
   return Promise.all(
     resolved.sources.map(async (source, index) => {
       if (!source.entry) return { source, found: null };
@@ -340,6 +374,7 @@ async function readAll({ resolved, z, x, y, tiles, signal, clips }) {
             tiles,
             climb: true,
             signal,
+            limit,
           }),
         };
       } catch (error) {
@@ -489,10 +524,11 @@ async function readMaskEdges({
     contributions.map(async (contribution) => {
       if (!contribution) return;
       const recipe = contribution.source ?? {};
-      const feather = featherFor(recipe);
-      if (!feather || !masksAnything(recipe)) return;
-
+      // On the source's own grid rather than the output's, because that is
+      // what the ramp will be measured on.
       const grid = contribution.raster?.width ?? size;
+      const feather = featherFor(recipe, { z, y, size: grid });
+      if (!feather || !masksAnything(recipe)) return;
       const layout = parentsFor({ z, x, y }, grid, feather);
       if (!layout) return;
 
@@ -577,10 +613,14 @@ async function merge({
     // decides what the pixels inside it weigh. The shape is known in full, so
     // this costs the extra rows and nothing else -- unlike a mask read out of
     // a source's own pixels, which would need its neighbours.
-    const margin = clip.feather ?? 0;
+    //
+    // Asked again rather than taken from the clip: `clipsFor` may have been
+    // given a grid the merge did not end up using, and a fade in metres is a
+    // different number of pixels on each of them.
+    const margin = featherFor(contribution.source, { z, y, size: grid });
     const mask = rasterizeTile(clip.shape, z, x, y, grid, margin);
     contribution.coverage = cropMask(
-      featherMask(mask, grid + margin * 2, clip.feather ?? 0),
+      featherMask(mask, grid + margin * 2, margin),
       grid,
       margin,
     );
@@ -694,7 +734,8 @@ export async function answerStackTile(options) {
   // 256 where the request did not say, which is the cautious guess: the
   // margin is in pixels of the output grid, so assuming a smaller grid makes
   // it wider on the ground, and too wide only costs a rasterise that was not
-  // needed while too narrow misses a ramp.
+  // needed while too narrow misses a ramp. A fade in metres does not mind
+  // either way -- fewer pixels each covering more ground is the same ground.
   const clips = clipsFor(resolved, cutlines, z, x, y, size);
   const format = options.format ?? outputFormat(resolved);
   const rgba = resolved.stack.space === 'rgba';

package/src/stacks.js

@@ -8,7 +8,11 @@ import {
   isResampling,
   parseColor,
 } from './elevation.js';
-import { MAX_FEATHER } from './cutlines.js';
+import {
+  MAX_FEATHER,
+  MAX_FEATHER_METRES,
+  featherMetresFor,
+} from './cutlines.js';
 import { normalizeCategories } from './catalog.js';
 import { BLEND_MODES, isBlendMode } from './rgba.js';
 
@@ -42,6 +46,8 @@ import { BLEND_MODES, isBlendMode } from './rgba.js';
  * @property {number} [heightAdjustment] - Metres, added after masking.
  * @property {number} [feather] - Pixels to fade in over at the edge of the
  *   source's shape. 0, the default, makes the edge a switch.
+ * @property {number} [featherMetres] - Metres of ground to fade in over
+ *   instead, worked out per tile. `featherMeters` is read as well.
  * @property {number} [opacity] - 0-1, scales source alpha. RGBA only.
  * @property {string} [blend] - Blend operator. RGBA only.
  * @typedef {object} Stack
@@ -159,6 +165,18 @@ export function validateStack(stack) {
         );
       }
     }
+    const metres = source?.featherMetres ?? source?.featherMeters;
+    if (metres !== undefined) {
+      // Loose, because the pixel cap is what actually bounds the ramp at any
+      // one zoom. This only has to catch a number nobody meant to type.
+      const width = Number(metres);
+      if (!Number.isFinite(width) || width < 0 || width > MAX_FEATHER_METRES) {
+        problems.push(
+          `sources[${index}].featherMetres must be between 0 and ` +
+            `${MAX_FEATHER_METRES}`,
+        );
+      }
+    }
     // A fade with no edge to fade at. Refused rather than ignored: it reads as
     // a source that blends into what is under it, and it does nothing at all.
     // A mask is an edge as much as a cutline is -- the hole it leaves is where
@@ -167,8 +185,9 @@ export function validateStack(stack) {
       source?.cutline ||
       source?.bounds ||
       source?.maskValues?.length ||
-      source?.maskColors?.length;
-    if (source?.feather && !fades) {
+      source?.maskColors?.length ||
+      source?.maskRange?.length;
+    if ((source?.feather || featherMetresFor(source)) && !fades) {
       problems.push(
         `sources[${index}].feather needs a cutline, bounds, or a mask to fade at`,
       );
@@ -528,6 +547,7 @@ export class StackStore {
   #stacks = new Map();
   #problems = new Map();
   #mtime = null;
+  #size = null;
   #checkedAt = 0;
 
   /**
@@ -552,10 +572,13 @@ export class StackStore {
     let raw;
     try {
       raw = JSON.parse(await fs.readFile(this.#file, 'utf8'));
-      this.#mtime = (await fs.stat(this.#file)).mtimeMs;
+      const stat = await fs.stat(this.#file);
+      this.#mtime = stat.mtimeMs;
+      this.#size = stat.size;
     } catch (error) {
       if (error.code === 'ENOENT') {
         this.#mtime = null;
+        this.#size = null;
         return;
       }
       throw error;
@@ -588,9 +611,15 @@ export class StackStore {
     if (now - this.#checkedAt < 1000) return false;
     this.#checkedAt = now;
 
+    // Size as well as the timestamp. A filesystem's clock is coarser than an
+    // edit: on NTFS the tick is about 15 ms, so two writes in quick succession
+    // land on the same mtime and the second would never be seen. Comparing the
+    // length as well catches the ones that changed it, which is most of them --
+    // and it costs nothing, since the stat was made anyway.
     const stat = await fs.stat(this.#file).catch(() => null);
     const mtime = stat?.mtimeMs ?? null;
-    if (mtime === this.#mtime) return false;
+    const size = stat?.size ?? null;
+    if (mtime === this.#mtime && size === this.#size) return false;
     await this.load();
     return true;
   }
@@ -676,6 +705,8 @@ export class StackStore {
 `,
     );
     await fs.rename(temp, this.#file);
-    this.#mtime = (await fs.stat(this.#file)).mtimeMs;
+    const written = await fs.stat(this.#file);
+    this.#mtime = written.mtimeMs;
+    this.#size = written.size;
   }
 }

package/src/web/index.html

@@ -1905,18 +1905,21 @@
         );
 
       /**
-       * A mask range as the field shows it.
+       * One end of a mask range, for the box that shows it.
        *
-       * One pair is written plainly; a recipe carrying several is shown as
-       * JSON, because the editor offers one band and the file may hold more
-       * than the editor can draw.
+       * A recipe may hold several bands where the editor offers one. The first
+       * is what the boxes show, and the row says how many more there are --
+       * silently dropping them would be worse than saying the editor cannot
+       * draw them.
        * @param {*} range - What the recipe says.
+       * @param {number} which - 0 for the low end, 1 for the high.
        * @returns {string} - What to put in the box.
        */
-      const rangeText = (range) => {
+      const rangeEdge = (range, which) => {
         if (!Array.isArray(range) || range.length === 0) return '';
-        if (Array.isArray(range[0])) return JSON.stringify(range);
-        return range.slice(0, 2).join(', ');
+        const first = Array.isArray(range[0]) ? range[0] : range;
+        const edge = first[which];
+        return Number.isFinite(Number(edge)) ? String(edge) : '';
       };
 
       /**
@@ -7542,6 +7545,18 @@ Every piece is hashed against the ` +
        */
       const renderDraftSource = (source, index, rgba) => {
         const last = index === stackDraft.sources.length - 1;
+        // A fade is written in one unit or the other, never both: the box
+        // shows whichever the recipe used and the choice beside it says which.
+        const featherMetres = source.featherMetres ?? source.featherMeters;
+        const featherUnit =
+          featherMetres === undefined && source.feather ? 'px' : 'm';
+        const featherWidth = featherMetres ?? source.feather ?? '';
+        const fadesAt =
+          source.cutline ||
+          source.bounds ||
+          (source.maskValues ?? []).length ||
+          (source.maskColors ?? []).length ||
+          (source.maskRange ?? []).length;
         const role =
           stackDraft.sources.length === 1
             ? ''
@@ -7635,11 +7650,23 @@ Every piece is hashed against the ` +
                       value="${escapeHtml((source.maskValues ?? []).join(', '))}" />
              </label>
              <label class="choice"
-                    title="Mask every height inside a band, written low, high. Nodata is rarely one number: an archive resampled on its way to being built does not hold what it was authored with, so a sea authored as 0 arrives scattered across -0.9 m to 0 — and masking the two ends of that leaves everything between, standing proud of whatever is underneath. A band says what you mean, and asymmetrically: sea is everything up to zero and nothing above it.">
-               Mask range
-               <input style="width:9rem" placeholder="-1, 0"
-                      data-stack-field="maskRange" data-stack-index="${index}"
-                      value="${escapeHtml(rangeText(source.maskRange))}" /> m
+                    title="Mask every height between these two, inclusive. Separate from Mask heights, which takes values one at a time — nodata is often a band rather than a number, because an archive resampled on its way to being built does not hold what it was authored with. A sea authored as 0 arrives scattered across -0.9 m to 0, and masking the two ends of that leaves everything between, standing proud of whatever is underneath. Leave both empty for no band.">
+               Mask between
+               <input type="number" step="any" style="width:5.5rem" placeholder="low"
+                      data-stack-field="maskRangeLow" data-stack-index="${index}"
+                      value="${rangeEdge(source.maskRange, 0)}" />
+               and
+               <input type="number" step="any" style="width:5.5rem" placeholder="high"
+                      data-stack-field="maskRangeHigh" data-stack-index="${index}"
+                      value="${rangeEdge(source.maskRange, 1)}" /> m
+               ${
+                 Array.isArray(source.maskRange) &&
+                 Array.isArray(source.maskRange[0]) &&
+                 source.maskRange.length > 1
+                   ? `<span class="sub">and ${source.maskRange.length - 1} more,
+                      which editing here replaces</span>`
+                   : ''
+               }
              </label>`;
 
         return `
@@ -7695,19 +7722,23 @@ Every piece is hashed against the ` +
                   : ''
               }
               <label class="choice"
-                     title="Fade this source in over this many pixels wherever it stops — the holes a mask leaves, and the edge of a cutline or box. Where a high-resolution source meets a coarser one the two disagree, by their survey and by their vertical datum, and the step between them reads as a wall under a hillshade. The drop is divided by this: 40 m across an 8 px fade is 5 m a pixel. 0 is a hard edge.">
+                     title="Fade this source in wherever it stops — the holes a mask leaves, and the edge of a cutline or box. Where a high-resolution source meets a coarser one the two disagree, by their survey and by their vertical datum, and the step between them reads as a wall under a hillshade. Metres of ground is usually the one to pick: a hillshade reads slope, so a fade written in pixels is gentle at one zoom and a bright band at the next, while a distance on the ground holds the same slope at every zoom. 50 m suits a coastline where two sources are a few metres apart. 0 is a hard edge.">
                 Fade in
-                <input type="number" min="0" max="64" step="1" style="width:4.5rem"
+                <input type="number" min="0" step="any" style="width:4.5rem"
                        placeholder="0"
                        data-stack-field="feather" data-stack-index="${index}"
-                       value="${source.feather ?? ''}" />
-                <span class="sub">px${
-                  source.feather &&
-                  !source.cutline &&
-                  !source.bounds &&
-                  !(source.maskValues ?? []).length &&
-                  !(source.maskColors ?? []).length
-                    ? ' — nothing to fade at yet: mask something, or clip it'
+                       value="${featherWidth}" />
+                <select data-stack-field="featherUnit" data-stack-index="${index}">
+                  <option value="m"${
+                    featherUnit === 'm' ? ' selected' : ''
+                  }>m of ground</option>
+                  <option value="px"${
+                    featherUnit === 'px' ? ' selected' : ''
+                  }>px</option>
+                </select>
+                <span class="sub">${
+                  featherWidth && !fadesAt
+                    ? 'nothing to fade at yet: mask something, or clip it'
                     : ''
                 }</span>
               </label>
@@ -7761,20 +7792,40 @@ Every piece is hashed against the ` +
             .filter(Boolean);
         } else if (field === 'required') {
           source.required = event.target.checked;
-        } else if (field === 'maskRange') {
-          // Held while it is half-typed, the way the clip box is: four numbers
-          // arrive one keystroke at a time and a field that cleared itself
-          // after the first comma could never be filled in.
-          const numbers = event.target.value
-            .split(',')
-            .map((part) => Number(part.trim()))
-            .filter((n) => Number.isFinite(n));
-          if (numbers.length >= 2) source.maskRange = numbers.slice(0, 2);
-          else if (event.target.value.trim() === '') delete source.maskRange;
-        } else if (field === 'feather') {
-          const pixels = Number(event.target.value);
-          if (event.target.value === '' || !(pixels > 0)) delete source.feather;
-          else source.feather = Math.min(64, Math.round(pixels));
+        } else if (field === 'maskRangeLow' || field === 'maskRangeHigh') {
+          // A band needs both ends, so one on its own is a half-typed thought
+          // rather than a range -- read them together, and write nothing until
+          // there are two numbers to write.
+          const row = event.target.closest('.card');
+          const edge = (name) => {
+            const box = row?.querySelector(`[data-stack-field="${name}"]`);
+            return box && box.value.trim() !== '' ? Number(box.value) : null;
+          };
+          const low = edge('maskRangeLow');
+          const high = edge('maskRangeHigh');
+          if (Number.isFinite(low) && Number.isFinite(high)) {
+            source.maskRange = low <= high ? [low, high] : [high, low];
+          } else if (low === null && high === null) {
+            delete source.maskRange;
+          }
+        } else if (field === 'feather' || field === 'featherUnit') {
+          // The width and its unit are read together and only one key is
+          // written, because a source carrying a fade in both would be asking
+          // the merge a question it has no answer to.
+          const row = event.target.closest('.card');
+          const box = row?.querySelector('[data-stack-field="feather"]');
+          const unit = row?.querySelector('[data-stack-field="featherUnit"]');
+          const width = Number(box?.value);
+          delete source.feather;
+          delete source.featherMetres;
+          delete source.featherMeters;
+          if (box && box.value.trim() !== '' && width > 0) {
+            if (unit?.value === 'px') {
+              source.feather = Math.min(64, Math.round(width));
+            } else {
+              source.featherMetres = width;
+            }
+          }
         } else if (field === 'baseVal' || field === 'interval') {
           // Blank means "the default", not zero -- an interval of 0 would make
           // every height the base value.
@@ -7812,6 +7863,12 @@ Every piece is hashed against the ` +
           renderStackDraft();
           return;
         }
+        // Redrawn so the row's own warning about having nothing to fade at
+        // follows the unit rather than the value it was drawn with.
+        if (event.target.dataset.stackField === 'featherUnit') {
+          renderStackDraft();
+          return;
+        }
         if (event.target.dataset.stackField !== 'encoding') return;
         // Redrawn so the four custom fields appear or disappear with the
         // choice, rather than sitting there meaning nothing.

package/tools/coast-step.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * How far two sources disagree where one hands over to the other.
+ *
+ * A land DEM says its shoreline is about zero. A global bathymetry at 450 m
+ * cells averages land and water together in every cell that straddles a coast,
+ * so its shoreline sits well below that -- and the merge steps between them in
+ * one pixel. Feathering spreads that step without reducing it, and a hillshade
+ * reads slope, so at high zoom a spread step is a wider bright band rather
+ * than a fainter one.
+ *
+ * Two quite different things produce that step and they look identical in a
+ * picture. A vertical datum offset is the same wherever the two meet, and one
+ * `heightAdjustment` fixes it. Averaging is wrong by whatever each cell
+ * happened to cover -- worst at the shore, gone offshore -- and no single
+ * number fixes that; subtracting the median would meet the coast and lift the
+ * open ocean with it.
+ *
+ * They are told apart by how much the steps scatter, which is what this
+ * prints. It is worth knowing that the measurement is taken exactly where a
+ * coarse source is least trustworthy, so a clustered result is evidence and a
+ * scattered one is close to proof.
+ *
+ *   node tools/coast-step.mjs --stack <url> --land <url> [--range -1,0] [--values 0]
+ *
+ * `--stack` is the merged tile and `--land` the source that wins on land, both
+ * at the same z/x/y. The mask arguments are that source's, so the tool knows
+ * which of its pixels are sea.
+ */
+
+import { loadCodec } from '../src/codec.js';
+import { decodeHeights, maskHeights, maskRanges } from '../src/elevation.js';
+
+const args = process.argv.slice(2);
+
+/**
+ * One named option off the command line.
+ * @param {string} name - Its name, without the dashes.
+ * @param {string} [fallback] - What it is when absent.
+ * @returns {string|undefined} - The value.
+ */
+const option = (name, fallback) => {
+  const at = args.indexOf(`--${name}`);
+  return at >= 0 && args[at + 1] ? args[at + 1] : fallback;
+};
+
+const stackUrl = option('stack');
+const landUrl = option('land');
+if (!stackUrl || !landUrl) {
+  console.error(
+    'usage: node tools/coast-step.mjs --stack <url> --land <url> [--range low,high] [--values a,b]',
+  );
+  process.exit(2);
+}
+
+/** The masks the land source is configured with, so its sea can be found. */
+const values = option('values')
+  ? option('values').split(',').map(Number)
+  : undefined;
+const range = option('range')
+  ? option('range').split(',').map(Number)
+  : undefined;
+if (!values && !range) {
+  console.error(
+    'give --values, --range, or both: without them no pixel is sea',
+  );
+  process.exit(2);
+}
+
+const codec = await loadCodec();
+if (!codec) {
+  console.error('this needs sharp: npm install sharp');
+  process.exit(1);
+}
+
+/**
+ * One tile, decoded to metres.
+ * @param {string} url - Where it is.
+ * @returns {Promise<object>} - `{heights, width}`.
+ */
+async function tileAt(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    console.error(`${url} answered ${response.status}`);
+    process.exit(1);
+  }
+  const raster = await codec.decode(Buffer.from(await response.arrayBuffer()), {
+    channels: 3,
+  });
+  return { heights: decodeHeights(raster, {}), width: raster.width };
+}
+
+const merged = await tileAt(stackUrl);
+const land = await tileAt(landUrl);
+if (merged.width !== land.width) {
+  console.error(
+    `different sizes: the stack is ${merged.width}px and the land source ${land.width}px`,
+  );
+  process.exit(1);
+}
+
+// The land source's own idea of where it has nothing, which is where the other
+// source shows through in the merged tile.
+const sea = Float32Array.from(land.heights);
+maskHeights(sea, values);
+maskRanges(sea, range);
+
+const { width } = merged;
+const steps = [];
+for (let row = 1; row < width - 1; row += 1) {
+  for (let column = 1; column < width - 1; column += 1) {
+    const at = row * width + column;
+    // A pixel the land source covers, beside one it does not: the handover,
+    // found from that source rather than guessed from the merged heights.
+    if (Number.isNaN(sea[at])) continue;
+    for (const step of [-1, 1, -width, width]) {
+      if (!Number.isNaN(sea[at + step])) continue;
+      const above = merged.heights[at];
+      const below = merged.heights[at + step];
+      if (Number.isFinite(above) && Number.isFinite(below)) {
+        steps.push(above - below);
+      }
+    }
+  }
+}
+
+if (steps.length === 0) {
+  console.log('no handover in this tile: it is all land, or all sea');
+  process.exit(0);
+}
+
+steps.sort((one, two) => one - two);
+
+/**
+ * A value at a percentile of the sorted steps.
+ * @param {number} share - Where to look, 0 to 1.
+ * @returns {number} - Metres.
+ */
+const at = (share) =>
+  steps[Math.min(steps.length - 1, Math.floor(steps.length * share))];
+
+const median = at(0.5);
+const spread = at(0.75) - at(0.25);
+
+console.log(`${steps.length} pixels where one source hands over to the other`);
+console.log('\n  the step across it, land minus what is underneath:');
+for (const [label, share] of [
+  ['a quarter are under', 0.25],
+  ['half are under', 0.5],
+  ['three quarters under', 0.75],
+  ['the worst', 1],
+]) {
+  console.log(`   ${label.padEnd(24)} ${at(share).toFixed(1).padStart(8)} m`);
+}
+
+console.log(
+  `\n  median ${median.toFixed(1)} m, middle half spread over ${spread.toFixed(1)} m`,
+);
+
+// Whether one number could fix it. A datum offset is the same wherever the two
+// meet, so the steps cluster; a coarse source averaging land and water is wrong
+// by whatever its cell covered, so they scatter.
+if (Math.abs(spread) < Math.abs(median) * 0.5) {
+  console.log(
+    [
+      '',
+      '  -> the steps cluster, so the two disagree by about the same amount',
+      '     wherever they meet. That looks like a datum offset, which one',
+      '     number fixes. On the source underneath, not the land:',
+      '',
+      `       "heightAdjustment": ${median.toFixed(1)}`,
+      '',
+      '     It shifts that source everywhere, so the deep ocean floor moves by',
+      '     the same amount -- against thousands of metres, nothing. Re-run',
+      '     afterwards and the median should come out near zero.',
+      '',
+      '     Worth one check first: this was measured at the coastline, which is',
+      '     the one place a coarse source is guaranteed to be wrong. If its',
+      '     cells are much larger than a pixel here, a clustered result can',
+      '     still be averaging rather than datum -- compare a stretch of steep',
+      '     coast against a flat one, and a real offset will agree.',
+    ].join('\n'),
+  );
+} else {
+  console.log(
+    [
+      '',
+      '  -> the steps scatter more than they cluster, so this is not one offset.',
+      '     A coarse source averages land and water together in the cells that',
+      '     straddle a coast, so how wrong it is depends on what each cell',
+      '     happened to cover: worst at the shore, gone offshore. Subtracting',
+      '     the median would meet the coast and lift the open ocean with it,',
+      '     trading a seam you can see for an error you cannot.',
+      '',
+      '     What helps is a nearshore source that has the detail, or leaving the',
+      '     line alone. At this zoom the coarse source is being asked something',
+      '     its cells cannot answer, and no adjustment invents the answer.',
+    ].join('\n'),
+  );
+}