pmtiles-swarm 0.76.0 → 0.78.0

package/CHANGELOG.md

@@ -7,6 +7,66 @@
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 
+## 0.78.0
+### ✨ Features and improvements
+- **Somewhere to clear the caches and the files nothing is waiting for.** A merged tile cache with
+  no way to empty it is a directory somebody eventually finds by hand, and a temporary file a crash
+  left behind is one nobody finds at all. Settings has a **Storage** tab now: what this node is
+  holding, what each thing costs to lose, and a button per row.
+
+  Five things — merged stack tiles, left-over temporary files, stopped exports, traffic history and
+  the tile counters. `GET /api/storage` reports them, `DELETE /api/storage/:what` lets go of one.
+  Everything on the list is derived and can be rebuilt, which is what makes a button reasonable:
+  none of it asks whether you meant it, because none of it is the only copy of anything.
+
+  The archives are deliberately not on it, and neither is the resume data beside them. Both look
+  like housekeeping and neither is: retiring an archive is a decision made from its own panel with
+  what it seeds in view, and resume data thrown away is a rehash of every byte on disk.
+
+  A sweep picks files by name and by age together, because either alone is wrong: `*.tmp` and
+  `pmtiles-write-*`, untouched for an hour. Every write that uses one renames within milliseconds,
+  so the margin is not for slowness — it is because this runs while the node is serving, and a sweep
+  with none at all could take the file a catalog write is halfway through renaming into place.
+  `torrents-data` is skipped outright, being terabytes of payload with no working files in it.
+
+  Stopped exports are read off the disk rather than from what the process remembers, so one left by
+  a stack somebody has since deleted is found as well. A running export is left alone: removing the
+  directory under a running merge would have it fail on its next write, reporting a disk problem for
+  something somebody chose. This is also the first way to discard one without finding the directory
+  by hand — the API for it shipped in 0.76.0 with nothing calling it.
+
+### 🐞 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

package/README.md

@@ -786,6 +786,8 @@ which the endpoint answers 501.
 | `GET` `POST` `DELETE`  | `/api/tokens`, `/api/tokens/:id`                            | Mint, list and revoke access tokens                                                                                                                                                                                                                                                                                                        |
 | `GET` `POST`           | `/api/restart`                                              | What a restart would do, and doing it                                                                                                                                                                                                                                                                                                      |
 | `GET` `DELETE`         | `/api/stats`                                                | What this node has served — per-archive counters and the last N requests; `DELETE` clears them                                                                                                                                                                                                                                             |
+| `GET`                  | `/api/storage`                                              | What this node is holding that it could let go of — merged tiles, left-over temporary files, stopped exports, traffic history, tile counters                                                                                                                                                                                               |
+| `DELETE`               | `/api/storage/:what`                                        | Lets go of one of them. Everything listed is derived and can be rebuilt; the archives are not on the list                                                                                                                                                                                                                                  |
 | `GET`                  | `/api/traffic`                                              | Upload and download speed per archive over time, from `stats.db`; `infoHash`, `hours` and `buckets` narrow it, and `totals` ranks archives by bytes moved                                                                                                                                                                                  |
 | `GET` `PATCH`          | `/api/config`                                               | Read and change settings                                                                                                                                                                                                                                                                                                                   |
 | `POST`                 | `/api/login`, `/api/logout`                                 | Console sign-in                                                                                                                                                                                                                                                                                                                            |

package/docs/internals.md

@@ -33,6 +33,7 @@ Operator-facing documentation is elsewhere — see [publishing](publishing.md),
 - [Retiring old builds](#retiring-old-builds)
 - [Prewarming a freshly joined archive](#prewarming-a-freshly-joined-archive)
 - [Named save locations](#named-save-locations)
+- [Storage](#storage)
 
 ## Marking incomplete archives
 
@@ -884,3 +885,60 @@ moving several hundred gigabytes is not something a settings screen should do as
 a side effect. A move checks free space before the engine is disturbed, since
 running out halfway through costs an hour, a partial file to clean up, and an
 archive that has to be put back.
+
+## Storage
+
+A merged tile cache with no way to empty it is a directory somebody eventually
+finds by hand, and a temporary file a crash left behind is one nobody finds at
+all. `GET /api/storage` reports what a node is holding that it could let go of;
+`DELETE /api/storage/:what` lets go of one of them. The console draws it as the
+Storage tab under Settings.
+
+Five things, and what each costs to lose:
+
+| What                      | Where              | Clearing it costs                                              |
+| ------------------------- | ------------------ | -------------------------------------------------------------- |
+| Merged stack tiles        | `stack-cache/`     | The merge again: an archive read per source, and a decode each |
+| Left-over temporary files | the data directory | Nothing — nobody is waiting for a file a crashed write left    |
+| Stopped exports           | the archive's disk | The hours already spent, which is what resuming would use      |
+| Traffic history           | `stats.db`         | The graphs go back to empty                                    |
+| Tile counters             | memory             | The count starts again; frees nothing                          |
+
+Everything on that list is derived and can be rebuilt, which is what makes a
+button reasonable — none of it asks whether the operator meant it, because none
+of it is the only copy of anything.
+
+### What is deliberately not on it
+
+**The archives**, and the resume data beside them. Both look like housekeeping
+and neither is. An archive is the data this node exists to serve, and retiring
+one is a decision made from its own panel with what it seeds in view. Resume
+data thrown away is a rehash of every byte on disk — and worse than useless as
+a repair, since a _stale partial_ resume file is the thing that cancels seed
+mode, which is a diagnosis rather than a sweep.
+
+### Which files a sweep is willing to touch
+
+By name and by age together, because either alone is wrong: the name says what
+a file was for and the age says whether anything still cares.
+
+The names are `*.tmp` and `pmtiles-write-*`, which is what the write-then-rename
+in `catalog.js`, `stacks.js`, `dht-state.js`, `stack-cache.js` and
+`pmtiles-write.js` leaves behind when a process stops between the two steps. The
+age is an hour. Every one of those renames happens within milliseconds, so an
+hour is far past generous — the margin is not for slowness, it is because this
+runs while the node is serving and a sweep with no margin could delete the file
+a catalog write is halfway through renaming into place.
+
+`torrents-data/` is skipped outright. It is terabytes of payload, nothing in it
+is a working file, and a sweep that walks it is a sweep that spends minutes
+finding nothing.
+
+### The bake working directories are read from disk
+
+Not from what the process remembers. A working directory outlives the run that
+made it, and one belonging to a stack somebody has since deleted is exactly the
+kind nobody thinks to look for. Whether an export is _running_ is memory's to
+say, and that is the only thing that decides whether it may be discarded —
+removing the directory under a running merge would have it fail on its next
+write, reporting a disk problem for something somebody chose.

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,60 @@ 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
+{ "category": "planet-bathymetry", "maskRange": [-1, 0], "featherMetres": 50 }
+```
+
+That is the source **on top** — the one whose mask leaves the hole. A weight
+says how much of what is underneath shows through, so it goes on the layer with
+the edge and not on the one filling the hole: a fade on the bathymetry
+underneath is read by nothing, because `paintHeights` takes the first layer that
+contributes whole and only consults a weight from the second onward. See "A
+feathered layer over a hole stands alone" above, which is the same rule seen
+from the other side.
+
+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.76.0",
+  "version": "0.78.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

@@ -37,6 +37,7 @@ import { SUMMARY_VERSION } from './pmtiles-probe.js';
 import { TileReadError } from './tiles.js';
 import { loadCodec } from './codec.js';
 import { answerStackTile, outputFormat, outputSize } from './stack-tile.js';
+import { clearStorage, storageReport } from './storage.js';
 import {
   isPinned,
   needsCodec,
@@ -790,6 +791,38 @@ export function createApp({
     }),
   );
 
+  // What this node is holding that it could let go of. Separate from the
+  // settings it sits beside in the console: a setting says what to do next and
+  // this says what to do about what was already done.
+  app.get(
+    '/api/storage',
+    route(async (_req, res) => {
+      res.setHeader('cache-control', 'no-store');
+      res.json(
+        await storageReport({ config, stackCache, stats, traffic, bakes }),
+      );
+    }),
+  );
+
+  app.delete(
+    '/api/storage/:what',
+    route(async (req, res) => {
+      const gone = await clearStorage(req.params.what, {
+        config,
+        stackCache,
+        stats,
+        traffic,
+        bakes,
+      });
+      if (!gone) {
+        return res
+          .status(404)
+          .json({ error: 'nothing here is called that, or it is turned off' });
+      }
+      return res.json(gone);
+    }),
+  );
+
   // Settings. Everything read per request takes effect immediately because the
   // running config object is the one being mutated; everything bound at startup
   // is written to the file and reported back as needing a restart, rather than

package/src/bake-jobs.js

@@ -205,6 +205,34 @@ export class BakeManager {
     return true;
   }
 
+  /**
+   * Every export with work still on disk, and where it is.
+   *
+   * Read from the filesystem rather than from what this process remembers: a
+   * working directory outlives the run that made it, and one belonging to a
+   * stack somebody has since deleted is exactly the kind nobody thinks to look
+   * for. Whether it is running is what decides if it may be discarded, and
+   * that is memory's to say.
+   * @returns {Promise<object[]>} - `{stackId, directory, running, stopped}`.
+   */
+  async heldWork() {
+    const found = [];
+    for (const root of this.#workRoots()) {
+      const base = path.join(root, WORK_DIR);
+      const names = await fs.readdir(base).catch(() => []);
+      for (const stackId of names) {
+        const job = this.#jobs.get(stackId);
+        found.push({
+          stackId,
+          directory: path.join(base, stackId),
+          running: Boolean(job && !job.finishedAt),
+          stopped: this.#held.has(stackId),
+        });
+      }
+    }
+    return found;
+  }
+
   /**
    * Throws away what a stopped export had done.
    *

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-cache.js

@@ -207,6 +207,25 @@ export class StackCache {
     }
   }
 
+  /**
+   * Throws away every tile it is holding.
+   *
+   * The hit and miss counters are left alone: they say what the cache has been
+   * doing since the process started, which emptying it does not unmake. The
+   * files go one at a time and forgivingly -- one that vanished underneath is
+   * one fewer to remove.
+   * @returns {Promise<number>} - How many tiles went.
+   */
+  async clear() {
+    const keys = [...this.#entries.keys()];
+    this.#entries.clear();
+    this.#bytes = 0;
+    for (const key of keys) {
+      await fs.rm(this.#pathFor(key), { force: true }).catch(() => {});
+    }
+    return keys.length;
+  }
+
   /**
    * What the cache is holding, for the console and for tests.
    * @returns {object} - entries, bytes, maxBytes, hits, misses.

package/src/stack-tile.js

@@ -151,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,
@@ -524,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;
 
@@ -612,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,
     );
@@ -729,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';