@meri-imperiumi/signalk-dead-reckoning 0.13.4 → 0.14.0

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-10-18
+
+### Added
+- **The DR webapp hosts chart layers: plotter-extension map overlays (work doc #27, chart-layer phase).** The webapp's plotter-extension host — so far widgets and panels only — gains the surface a map layer needs, with [signalk-livedepth-plugin](https://github.com/night199uk/signalk-livedepth-plugin) as the first consumer: soundings recorded by the LiveDepth plugin draw as a shaded, isobath-contoured depth surface on the DR chart, live-extended while sailing. New host capabilities: `background.iframe` (headless 1×1 sandboxed iframes running extension runtimes off-viewport, torn down with the extension), `overlays.image` (the `overlay.request` → `overlay.frame` cycle — the host sends the viewport's EPSG:3857 extent, bounds, pixel ratio clamped to the overlay's `preferredPixelRatio`, resolution, zoom and `liveInterval`; the runtime answers with a transferred `ImageBitmap` the host composites into a pane above the charts and below the chartwork/vessel, refusing `overlays.superseded` frames and pacing live ones at `overlays.throttled`; frames stay georeferenced through panning via their own extent, and world copies on either side of the antimeridian are covered), `map` (`map.getView`/`map.center`/`map.fitBounds` plus settled `map.view` events), `units` (`units.get` with the preferred depth unit, default `m`), and `buttons` (`mapToolbar` entries rendered into a stack above the bottom-left controls, toggling panels). Layer affordances: a ▤ **Plugin layers** control opens a dialog with per-layer show/hide, opacity, and the layer's settings panel (`configPanel`) — layer state persists in `dr.plotterext.overlays.v1` like the chart layers' own prefs, extensions' `state.get/set`/`state.changed` storage shared with their settings panel, and `events.publish` routing (scope `all`/`extension`). The vendored `signalk-plotterext-bus` moves 0.11.0 → 0.21.0 for the `overlay.*` and `map.view` wire surface (0.12–0.18 lack it). Nothing is needed server-side: LiveDepth registers its own `plotterExtensions` provider, and the host discovers it through the same collection polling; the same `overlays.image` surface is what a future radar-overlay provider would plug into for DR fixes.
+
+### Fixed
+- **The GPS/override bar no longer sits in the middle of a phone screen** (`public/dr-ext-host.js`): on the ≤600 px phone layout the top band stacks vertically, and every `<dr-ext-widget-area>` reserves its full 2×2 widget footprint even while empty — so the empty top-left area inflated the tools column to ~323 px and pushed the GPS status + Engage OVERRIDE panel down to y≈337 of an 844 px viewport, mid-screen. The reservation exists only for the chart context-menu placement hit-test, so it now collapses inside the area's own phone media query; a placed grid still sizes itself through its rows, and placement simply isn't offered on an empty phone area. Phone top band drops from ~656 px to ~260 px with the GPS bar back at the top. `doc/dr-mobile.png` regenerated with the fixed layout.
+
+### Changed
+- **Passage replay gains a blind variant — the GPS-loss backtest the tier-2 circularity demanded** (`tools/replay-passage.js`): the derived tier-2 current is fitted to the very GPS track a replay scores against, so "derived beats everything" over a fully-GPS-fed passage is a tautology, not a result. The new `--blind-from ISO` variant simulates the actual use case — GPS dies mid-passage: fixes stop feeding the derived-current state at the cutoff while snapshots keep being taken, so the shadow boat navigates on the carried EWMA current decaying at its 24 h time constant and lapsing to tier 5 after the TTL, with divergence still scored against the hidden GPS track. First blind run on the Niue→Vava'u passage (2026-09-11→14, 253 nm, GPS lost at hour 24 of 60): DR stayed within ~10 nm of truth through the entire 24 h carry window, then degraded at ~1 nm/h once the current support vanished — 22.5 nm final vs 10.0 nm with GPS live and 38.2 nm cold. Also fixed on the way: the derived-current provider returned no `tier` field, so the §6.2 training gate read every tick as unresolved and the learning variant silently never trained (0 matrix bins, learn ≡ derived); it now stamps `tier: 2`, the leeway-synthetic test's threshold is recalibrated to the post-gate semantics (the old bound was met by the current, not by learning), and the `scudLearn` variant is vestigial by design — the gate deliberately blocks training on model currents.
+
 ## [0.13.4] - 2026-10-16
 
 ### Added

package/README.md

@@ -6,13 +6,14 @@ An offline-first dead reckoning and sensor fusion engine for Signal K that maint
 
 ## Why
 
-Planning for life without GPS is no longer hypothetical: the UK Maritime and Coastguard Agency's Guidance Note 719 ([reported by Yachting Monthly](https://www.yachtingmonthly.com/news/mca-tells-maritime-sector-to-plan-for-life-without-gps-106566), 1 Oct 2025) reports a marked increase in GNSS jamming and spoofing worldwide and asks mariners to review contingency arrangements, maintain resilient navigation practices, and practice navigating without satellite positioning — naming dead reckoning, visual bearings, and celestial fixing as valid methods. This plugin implements exactly that contingency for Signal K vessels: the fallback is always running, and the trusted-GPS period is spent training it.
+Planning for life without GPS is no longer hypothetical: the UK Maritime and Coastguard Agency's [Guidance Note 719](https://www.gov.uk/government/publications/mgn-719-mf-operating-in-gnss-denied-and-degraded-environments/mgn-719-mf-operating-in-gnss-denied-and-degraded-environments) ([reported by Yachting Monthly](https://www.yachtingmonthly.com/news/mca-tells-maritime-sector-to-plan-for-life-without-gps-106566), 1 Oct 2026) reports a marked increase in GNSS jamming and spoofing worldwide and asks mariners to review contingency arrangements, maintain resilient navigation practices, and practice navigating without satellite positioning — naming dead reckoning, visual bearings, and celestial fixing as valid methods. This plugin implements a contingency for Signal K vessels.
 
 ## Requirements
 
 * This plugin installed and configured
 * Some chart source available to Signal K
 * Hand bearing compass and/or sextant
+* A heading source independent of GNSS — a fluxgate or inertial compass feeding `navigation.headingMagnetic`, not a satellite (GNSS) compass. A satellite compass shares the jamming and spoofing failure mode of the position fix, so a vessel whose only heading source is satellite-derived cannot dead-reckon through GNSS denial. Be careful checking this: on N2K networks a single physical device often provides both compass and position data, and display list entries do not necessarily reflect that (a device may publish both PGN 127257 heading and PGN 129029 position under one source)
 
 ## Getting started
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meri-imperiumi/signalk-dead-reckoning",
-  "version": "0.13.4",
+  "version": "0.14.0",
   "description": "Offline-first dead reckoning and sensor fusion engine for Signal K",
   "main": "plugin/index.js",
   "scripts": {

package/public/dr-app.js

@@ -903,7 +903,18 @@ class DrApp extends HTMLElement {
     this.extHost = new PlotterExtHost({
       stream: window.drSignalkStream,
       mount: root,
+      // The chart, once it exists — map overlays composite onto it and
+      // the map capability reads/drives its viewport.
+      getMap: () => this.map?.map ?? null,
     });
+    // The host hooks the Leaflet events itself, but discovery can land
+    // before the chart exists — forward the element's own view-change
+    // event and kick once so the first overlay frames are requested
+    // even without a user pan.
+    this.map?.addEventListener("dr-view-changed", () =>
+      this.extHost.viewChanged(),
+    );
+    setTimeout(() => this.extHost.viewChanged(), 250);
     for (const el of root.querySelectorAll("dr-ext-widget-area")) {
       this.extHost.attachArea(el);
     }

package/public/dr-ext-host-core.js

@@ -20,17 +20,32 @@ export const AREA_ANCHORS = ["top-left", "top-right"];
 export const GRID_COLS = 2;
 export const GRID_ROWS = 2;
 
-/** Capabilities this host advertises (work doc #27 v1 scope). */
+/** Capabilities this host advertises (work doc #27 v1 scope, plus the
+ * chart-layer phase): widgets and panels, headless background runtimes,
+ * image map overlays, the map viewport, and the user's units. `buttons`
+ * covers mapToolbar entries; `signalk.put` is offered but only works
+ * for write-capable sessions. */
 export const HOST_CAPABILITIES = [
   "widgets",
   "panels.iframe",
   "signalk.stream",
   "signalk.put",
+  "background.iframe",
+  "overlays.image",
+  "map",
+  "units",
+  "buttons",
 ];
 
 /** API major version this host implements. */
 export const API_VERSION = "1";
 
+/** Baseline sandbox for every extension iframe: fault containment,
+ * not an adversarial boundary (install time is the trust decision).
+ * Shared by the widget/panel contexts and the headless background
+ * runtimes — one definition so they cannot drift. */
+export const IFRAME_SANDBOX = "allow-scripts allow-same-origin allow-forms";
+
 /**
  * Parses a widget `size` ("<cols>x<rows>") into cell spans.
  *
@@ -66,16 +81,75 @@ export function contributionUsable(entry, kind) {
   return true;
 }
 
+/**
+ * Is a `background[]` runtime entry usable? A headless iframe needs an
+ * id and a page to load; everything else is the runtime's business.
+ *
+ * @param {object} entry - manifest background entry
+ * @returns {boolean}
+ */
+export function backgroundUsable(entry) {
+  return (
+    !!entry &&
+    typeof entry === "object" &&
+    typeof entry.id === "string" &&
+    entry.id !== "" &&
+    typeof entry.url === "string" &&
+    entry.url !== ""
+  );
+}
+
+/** Overlay bands the host composites (above the charts, in manifest
+ * order; `aboveResources` sits above those). */
+export const OVERLAY_BANDS = ["aboveCharts", "aboveResources"];
+
+/**
+ * Is an `overlays[]` entry usable? Only `image` overlays are hosted —
+ * the host composites bitmaps the extension's runtime draws; `data`
+ * overlays (host-drawn MapLibre styles) are a separate capability this
+ * host does not advertise, so they never reach the filter.
+ *
+ * @param {object} entry - manifest overlay entry
+ * @returns {boolean}
+ */
+export function overlayUsable(entry) {
+  if (!entry || typeof entry !== "object") return false;
+  if (typeof entry.id !== "string" || entry.id === "") return false;
+  // Type is optional in the manifest (image was the only kind when the
+  // field was introduced); an explicit non-image type is not hosted.
+  if (entry.type !== undefined && entry.type !== "image") return false;
+  if (entry.band !== undefined && !OVERLAY_BANDS.includes(entry.band)) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Is a `buttons[]` entry usable? This host renders mapToolbar buttons
+ * only; entries for slots it does not have are ignored per the spec.
+ *
+ * @param {object} entry - manifest button entry
+ * @returns {boolean}
+ */
+export function buttonUsable(entry) {
+  if (!entry || typeof entry !== "object") return false;
+  if (typeof entry.id !== "string" || entry.id === "") return false;
+  if (entry.slot !== undefined && entry.slot !== "mapToolbar") return false;
+  return true;
+}
+
 /**
  * Filters a discovered `plotterExtensions` collection down to the
  * extensions this host can offer: manifest `apiVersion` must match,
  * every `requires` capability must be advertised, and contributions
- * are narrowed to usable widget/panel entries (unknown sections are
- * ignored per the spec).
+ * are narrowed to usable widget/panel/overlay/background/button
+ * entries (unknown sections are ignored per the spec).
  *
  * @param {object} collection - `{ [extId]: manifest }`
  * @param {string[]} capabilities
- * @returns {Map<string, {manifest: object, widgets: object[], panels: object[]}>}
+ * @returns {Map<string, {manifest: object, widgets: object[],
+ *   panels: object[], overlays: object[], background: object[],
+ *   buttons: object[]}>}
  */
 export function compatibleExtensions(collection, capabilities) {
   const out = new Map();
@@ -91,8 +165,32 @@ export function compatibleExtensions(collection, capabilities) {
     const panels = (
       Array.isArray(manifest.panels) ? manifest.panels : []
     ).filter((p) => contributionUsable(p, "panels"));
-    if (widgets.length === 0 && panels.length === 0) continue;
-    out.set(extId, { manifest, widgets, panels });
+    const overlays = (
+      Array.isArray(manifest.overlays) ? manifest.overlays : []
+    ).filter(overlayUsable);
+    const background = (
+      Array.isArray(manifest.background) ? manifest.background : []
+    ).filter(backgroundUsable);
+    const buttons = (
+      Array.isArray(manifest.buttons) ? manifest.buttons : []
+    ).filter(buttonUsable);
+    if (
+      widgets.length === 0 &&
+      panels.length === 0 &&
+      overlays.length === 0 &&
+      background.length === 0 &&
+      buttons.length === 0
+    ) {
+      continue;
+    }
+    out.set(extId, {
+      manifest,
+      widgets,
+      panels,
+      overlays,
+      background,
+      buttons,
+    });
   }
   return out;
 }
@@ -293,6 +391,153 @@ export function layoutKey(prefix = "dr.plotterext") {
   return `${prefix}.layout.v1`;
 }
 
+/**
+ * localStorage key for persisted overlay layer state (visibility,
+ * opacity) — saved like the chart layers' own prefs (work doc #27,
+ * chart-layer phase).
+ *
+ * @param {string} [prefix]
+ * @returns {string}
+ */
+export function overlayStateKey(prefix = "dr.plotterext") {
+  return `${prefix}.overlays.v1`;
+}
+
+/** Overlay state defaults per the manifest entry. */
+export const OVERLAY_DEFAULTS = {
+  band: "aboveCharts",
+  visible: true,
+  opacity: 0.85,
+  minZoom: 0,
+};
+
+/**
+ * Merges a manifest overlay entry with the host defaults.
+ *
+ * @param {object} entry - validated overlay manifest entry
+ * @returns {{id: string, title: string, band: string, visible: boolean,
+ *   opacity: number, minZoom: number, configPanel: string|null,
+ *   preferredPixelRatio: number|null, runtime: string|null}}
+ */
+export function overlaySpec(entry) {
+  const opacity =
+    typeof entry.opacity === "number" &&
+    entry.opacity >= 0 &&
+    entry.opacity <= 1
+      ? entry.opacity
+      : OVERLAY_DEFAULTS.opacity;
+  return {
+    id: entry.id,
+    title: entry.title ?? entry.id,
+    band: entry.band ?? OVERLAY_DEFAULTS.band,
+    visible: entry.visible ?? OVERLAY_DEFAULTS.visible,
+    opacity,
+    minZoom:
+      typeof entry.minZoom === "number"
+        ? entry.minZoom
+        : OVERLAY_DEFAULTS.minZoom,
+    configPanel:
+      typeof entry.configPanel === "string" ? entry.configPanel : null,
+    preferredPixelRatio:
+      typeof entry.preferredPixelRatio === "number"
+        ? entry.preferredPixelRatio
+        : null,
+    // The background runtime that draws this overlay's frames.
+    runtime: typeof entry.runtime === "string" ? entry.runtime : null,
+  };
+}
+
+/**
+ * Overlay layer state, persisted per extension+overlay the way the
+ * chart layers' toggles are. Storage is injected so Node tests can
+ * pass a fake; the store holds only user overrides — entries missing
+ * from storage fall back to the manifest defaults.
+ */
+export class OverlayStateStore {
+  /**
+   * @param {{getItem: (k: string) => string|null,
+   *           setItem: (k: string, v: string) => void}} storage
+   */
+  constructor(storage) {
+    this.storage = storage;
+    this.data = this.load();
+  }
+
+  /**
+   * @returns {Record<string, Record<string, {visible?: boolean, opacity?: number}>>}
+   */
+  load() {
+    try {
+      const raw = this.storage.getItem(overlayStateKey());
+      const parsed = raw ? JSON.parse(raw) : null;
+      return parsed && typeof parsed === "object" ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+
+  /**
+   * @returns {void}
+   */
+  save() {
+    this.storage.setItem(overlayStateKey(), JSON.stringify(this.data));
+  }
+
+  /**
+   * Effective state for an overlay: manifest defaults merged with the
+   * user's persisted overrides.
+   *
+   * @param {object} spec - overlaySpec() output (manifest defaults)
+   * @param {string} extId
+   * @returns {{visible: boolean, opacity: number}}
+   */
+  effective(spec, extId) {
+    const saved = this.data[extId]?.[spec.id] ?? {};
+    return {
+      visible: saved.visible ?? spec.visible,
+      opacity:
+        typeof saved.opacity === "number" &&
+        saved.opacity >= 0 &&
+        saved.opacity <= 1
+          ? saved.opacity
+          : spec.opacity,
+    };
+  }
+
+  /**
+   * Persists a user override.
+   *
+   * @param {string} extId
+   * @param {string} overlayId
+   * @param {{visible?: boolean, opacity?: number}} patch
+   * @returns {{visible: boolean, opacity: number}} the new effective
+   *   state (against bare defaults — callers merge with their spec)
+   */
+  set(extId, overlayId, patch) {
+    if (!this.data[extId]) this.data[extId] = {};
+    const ext = this.data[extId];
+    const cur = ext[overlayId] ?? {};
+    if (patch.visible !== undefined) cur.visible = patch.visible;
+    if (patch.opacity !== undefined) cur.opacity = patch.opacity;
+    ext[overlayId] = cur;
+    this.save();
+    return { visible: cur.visible ?? true, opacity: cur.opacity ?? 0.85 };
+  }
+
+  /**
+   * Drops an extension's overrides (extension vanished — the layer UI
+   * goes with it; a returning extension starts from its defaults).
+   *
+   * @param {string} extId
+   * @returns {void}
+   */
+  dropExtension(extId) {
+    if (!(extId in this.data)) return;
+    delete this.data[extId];
+    this.save();
+  }
+}
+
 /**
  * localStorage key for an extension's state scope. Extension scope is
  * shared across contexts; instance scope is keyed by the placement's
@@ -502,3 +747,206 @@ export function newInstanceId() {
   const hex = [...b].map((x) => x.toString(16).padStart(2, "0")).join("");
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 }
+
+// ---- map overlays: geometry and frame cycle ----------------------------
+
+/** Web Mercator world width, in metres (equator = one world copy). */
+export const WEB_MERCATOR_SIZE = 40075016.68557849;
+/** Mercator Y limit (±85.0511° — where the projection diverges). */
+const MERCATOR_LAT_MAX = 85.0511287798066;
+
+/**
+ * Longitude (degrees) to EPSG:3857 X (metres). Values outside
+ * [-180, 180] map onto neighbouring world copies, as on a wrapping
+ * map.
+ *
+ * @param {number} lng
+ * @returns {number}
+ */
+export function lngToX(lng) {
+  return (lng / 360 + 0.5) * WEB_MERCATOR_SIZE;
+}
+
+/**
+ * Latitude (degrees) to EPSG:3857 Y (metres), clamped to the
+ * projection's range.
+ *
+ * @param {number} lat
+ * @returns {number}
+ */
+export function latToY(lat) {
+  const clamped = Math.max(-MERCATOR_LAT_MAX, Math.min(MERCATOR_LAT_MAX, lat));
+  const s = Math.sin((clamped * Math.PI) / 180);
+  return (
+    (0.5 - Math.log((1 + s) / (1 - s)) / (4 * Math.PI)) * WEB_MERCATOR_SIZE
+  );
+}
+
+/**
+ * EPSG:3857 X (metres) to longitude (degrees), normalized to
+ * [-180, 180).
+ *
+ * @param {number} x
+ * @returns {number}
+ */
+export function xToLng(x) {
+  return normalizeLng((x / WEB_MERCATOR_SIZE - 0.5) * 360);
+}
+
+/**
+ * EPSG:3857 Y (metres) to latitude (degrees).
+ *
+ * @param {number} y
+ * @returns {number}
+ */
+export function yToLat(y) {
+  const n = Math.PI - (2 * Math.PI * y) / WEB_MERCATOR_SIZE;
+  return (180 / Math.PI) * Math.atan(0.5 * (Math.exp(n) - Math.exp(-n)));
+}
+
+/**
+ * Normalizes a longitude to [-180, 180).
+ *
+ * @param {number} lng
+ * @returns {number}
+ */
+export function normalizeLng(lng) {
+  return ((((lng + 180) % 360) + 360) % 360) - 180;
+}
+
+/**
+ * Ground resolution at a latitude, in metres per screen (CSS) pixel
+ * at the given zoom — the 256 px-tile convention Leaflet uses.
+ *
+ * @param {number} lat
+ * @param {number} zoom
+ * @returns {number}
+ */
+export function metersPerPixel(lat, zoom) {
+  return (
+    (WEB_MERCATOR_SIZE * Math.cos((lat * Math.PI) / 180)) / (256 * 2 ** zoom)
+  );
+}
+
+/**
+ * The lon/lat `[west, south, east, north]` form of a mercator extent.
+ * A box crossing the antimeridian comes out in the API's form
+ * (west > east); longitudes are in [-180, 180].
+ *
+ * @param {[number, number, number, number]} extent - EPSG:3857 metres
+ * @returns {[number, number, number, number]}
+ */
+export function boundsForExtent(extent) {
+  const spanDeg = ((extent[2] - extent[0]) / WEB_MERCATOR_SIZE) * 360;
+  if (spanDeg >= 360) {
+    return [-180, yToLat(extent[1]), 180, yToLat(extent[3])];
+  }
+  const west = normalizeLng(xToLngRaw(extent[0]));
+  let east = west + spanDeg;
+  if (east > 180) east -= 360; // crossed the antimeridian
+  if (east > 180) east = 180; // degenerate near-world-spanning box
+  return [west, yToLat(extent[1]), east, yToLat(extent[3])];
+}
+
+/**
+ * Raw X→longitude, NOT wrapped (for boundsForExtent's span math).
+ *
+ * @param {number} x
+ * @returns {number}
+ */
+function xToLngRaw(x) {
+  return (x / WEB_MERCATOR_SIZE - 0.5) * 360;
+}
+
+/**
+ * Builds an `overlay.request` payload from the map view. The image
+ * covers the viewport's mercator box, pixels spaced evenly in
+ * mercator, north up (this host's chart does not rotate).
+ *
+ * The extent is the viewport at `resolution` per IMAGE pixel, where
+ * image pixels are CSS pixels times `pixelRatio`; the returned bounds
+ * are the same box as lon/lat.
+ *
+ * @param {{centerLng: number, centerLat: number, zoom: number,
+ *   width: number, height: number}} view - viewport in CSS pixels
+ * @param {{overlayId: string, requestId: string, pixelRatio: number,
+ *   liveInterval?: number}} opts
+ * @returns {object} an OverlayRequestEvent payload
+ */
+export function buildFrameRequest(view, opts) {
+  const mpp = metersPerPixel(view.centerLat, view.zoom);
+  const cx = lngToX(view.centerLng);
+  const cy = latToY(view.centerLat);
+  const halfW = (view.width * mpp) / 2;
+  const halfH = (view.height * mpp) / 2;
+  const extent = [cx - halfW, cy - halfH, cx + halfW, cy + halfH];
+  const req = {
+    overlayId: opts.overlayId,
+    requestId: opts.requestId,
+    extent,
+    bounds: boundsForExtent(extent),
+    width: Math.round(view.width * opts.pixelRatio),
+    height: Math.round(view.height * opts.pixelRatio),
+    pixelRatio: opts.pixelRatio,
+    resolution: mpp / opts.pixelRatio,
+    zoom: view.zoom,
+    rotation: 0,
+  };
+  if (opts.liveInterval !== undefined) req.liveInterval = opts.liveInterval;
+  return req;
+}
+
+/**
+ * Decides whether an incoming `overlay.frame` is drawn. A frame
+ * answering a request is accepted only while that request is still
+ * the newest (otherwise `overlays.superseded`); a live frame (no
+ * `requestId`) is paced against the host's `liveInterval`
+ * (`overlays.throttled`). Mutates the gate — it is per-overlay state.
+ *
+ * @param {{lastRequestId: string|null, lastLiveAt: number,
+ *   liveInterval: number}} gate
+ * @param {{requestId?: string}} params - overlay.frame params
+ * @param {number} now - ms timestamp
+ * @returns {{accepted: boolean, reason?: string}}
+ */
+export function acceptFrame(gate, params, now) {
+  if (params.requestId === undefined || params.requestId === null) {
+    if (now - gate.lastLiveAt < gate.liveInterval) {
+      return { accepted: false, reason: "overlays.throttled" };
+    }
+    gate.lastLiveAt = now;
+    return { accepted: true };
+  }
+  if (params.requestId !== gate.lastRequestId) {
+    return { accepted: false, reason: "overlays.superseded" };
+  }
+  // A requested frame is fresh content too: an immediately following
+  // live frame adds nothing the viewer has not just been shown.
+  gate.lastLiveAt = now;
+  return { accepted: true };
+}
+
+/**
+ * Where a frame's image lands on the current viewport, in CSS pixels:
+ * the image covers `extent` (its own georeferencing), the view has
+ * moved on since — the placement maps the extent into the view now.
+ *
+ * @param {{extent: [number, number, number, number]}} frame
+ * @param {{centerLng: number, centerLat: number, zoom: number,
+ *   width: number, height: number}} view - current viewport, CSS px
+ * @returns {{x: number, y: number, width: number, height: number}}
+ */
+export function framePlacement(frame, view) {
+  const mpp = metersPerPixel(view.centerLat, view.zoom);
+  const cx = lngToX(view.centerLng);
+  const cy = latToY(view.centerLat);
+  const viewMinX = cx - (view.width * mpp) / 2;
+  const viewMaxY = cy + (view.height * mpp) / 2;
+  const [minX, minY, maxX, maxY] = frame.extent;
+  return {
+    x: (minX - viewMinX) / mpp,
+    y: (viewMaxY - maxY) / mpp,
+    width: (maxX - minX) / mpp,
+    height: (maxY - minY) / mpp,
+  };
+}