@humanforest/nuxt-layer 0.1.0

package/packages/ui/src/map/useMapOverlay.ts

@@ -0,0 +1,421 @@
+// Sources, layers and basemap config as data.
+//
+// Mapbox's style spec is already declarative JSON — wrapping it in a component per layer would only
+// add a lossy second dialect. What actually needed owning was three things, and this owns exactly
+// those, passing everything else through untouched:
+//
+//   • PAINT ORDER IS THE ARRAY, not the mount sequence. Layer order in mapbox is insertion order, so
+//     anything that adds and removes layers over their lifetime reshuffles them silently (an 8px
+//     casing landing above its 4px line swallows the line). A layer that leaves and comes back is
+//     re-inserted before the next declared layer present on the map, so the array always wins.
+//   • TOKENS. `token('--ui-primary')` marks a value as token-derived; it is resolved to sRGB on every
+//     apply and re-applied when the colour mode changes. GL rejects the display-p3 that
+//     getComputedStyle returns for a Forest token, and a hand-rolled re-resolve is where this
+//     subsystem has already grown a bug once.
+//   • HIDING USES `visibility`, never remove/add — so nothing reshuffles and tiles stay warm.
+//
+// Out of scope on purpose: sprites/addImage, terrain, fog, lights. Those stay on the raw instance
+// until a second consumer asks, so this does not quietly become a second Mapbox API.
+import { onScopeDispose, watch, type ShallowRef } from 'vue';
+import type { GeoJSONSource, Map } from 'mapbox-gl';
+import { resolveMapColor } from './mapColor';
+import { onTokenModeChange } from './useTokenMode';
+
+const TOKEN = Symbol('forest-map-token');
+type TokenValue = { [TOKEN]: true; expr: string };
+
+/**
+ * Mark a paint/layout/config value as token-derived, e.g. `token('--ui-primary')`.
+ *
+ * A bare custom property is wrapped in `var()`: the resolver sets the value as a CSS `color`, and
+ * `color: --ui-primary` is invalid — it silently falls back to the inherited text colour, so every
+ * layer would come out the same grey.
+ */
+export const token = (expr: string): TokenValue => ({
+  [TOKEN]: true,
+  expr: expr.startsWith('--') ? `var(${expr})` : expr,
+});
+
+const isToken = (v: unknown): v is TokenValue =>
+  !!v && typeof v === 'object' && TOKEN in (v as Record<PropertyKey, unknown>);
+
+/**
+ * WHERE AN OVERLAY LAYER BELONGS, BY WHAT THE LAYER IS.
+ *
+ * Standard's three slots are fixed positions in the imported stack, and Mapbox documents them as:
+ *
+ *   bottom — above the polygons (land, landuse, water)
+ *   middle — above the lines (roads) and BEHIND the 3D buildings
+ *   top    — above the POI labels, behind the place and transit labels
+ *
+ * ★ `middle` IS BEHIND THE 3D BUILDINGS, WHICH IS WHY A MARK MUST NOT LIVE THERE. Standard extrudes
+ * buildings, landmarks and trees, so a mark in `middle` is swallowed by scenery the moment an extrusion
+ * covers its coordinate — worse as the camera pitches, and worst on the dense streets an operator is
+ * most likely to be looking at. A mark is the one thing on the map that can never be hidden: it IS the
+ * data. Ground context can be, and should be, so a zone stays in `bottom`.
+ *
+ * A DOM `<FMarker>` is not affected: it is an element over the canvas, not a GL layer, so no basemap
+ * layer can cover it. Mapbox only fades a DOM marker for 3D TERRAIN (`occludedOpacity`, default 0.2),
+ * which Forest does not enable — buildings never fade one.
+ *
+ * ★ `top` STILL SITS UNDER THE PLACE AND TRANSIT LABELS, so a street name prints over a mark there. That
+ * is a second problem with its own three answers — see `MARK_CLAIMS_SPACE` below.
+ *
+ * A pitched ops map that wants no scenery at all sets `config: { show3dObjects: false }` instead.
+ */
+export const MAP_SLOT = {
+  /** zones and other ground context — under the basemap's labels and under every mark */
+  zone: 'bottom',
+  /** routes and anything else that belongs to the road surface */
+  route: 'middle',
+  /** every mark: vehicles, places, counted bays, clusters, selection rings */
+  mark: 'top',
+} as const;
+
+/**
+ * A MARK THAT A BASEMAP LABEL MUST NOT BE PRINTED OVER.
+ *
+ * Three levers exist, and they are not alternatives to each other — they answer different questions:
+ *
+ * 1. MAKE THE LABEL YIELD (this constant). `icon-allow-overlap: true` keeps marks from hiding each other;
+ *    `icon-ignore-placement: FALSE` is the part that matters — it puts each mark's box in the collision
+ *    index, so a basemap label that collides with a mark is DROPPED rather than drawn on top of it. The
+ *    layer must also be UNSLOTTED — omit `slot` — for two reasons: an unslotted layer paints above every
+ *    layer in the style, and placement runs TOP-DOWN, so the topmost layer claims its space first and
+ *    wins the collision (measured in mapbox-gl 3.24.1: `PauseablePlacement.continuePlacement` starts at
+ *    the last index of the layer order and decrements). In `top` the label layers are above the marks,
+ *    so they are placed first and the mark loses — the flag alone changes nothing.
+ *    ⚠ Unslotted is only sound in mercator. Under the globe projection an unslotted layer lands BELOW
+ *    the labels, so the order swaps silently at world zooms; a city map never reaches them.
+ *    ⚠ NOT MEASURED AT FLEET SCALE. Entering the collision index costs per symbol, so the 30k tier keeps
+ *    `FLEET_SYMBOL_LAYOUT` (which ignores placement) until this is measured on a real fleet.
+ *    ⚠⚠ THE DROP ITSELF IS NOT CONFIRMED ACROSS A STYLE IMPORT. Verified live: the layer does land
+ *    unslotted with `icon-ignore-placement: false`. What is NOT verified is that a colliding basemap
+ *    label then disappears — one probe on the demo map showed the same POI rendering with the flag
+ *    either way, which would mean placement does not collide across the import boundary. The paint-order
+ *    half is certain (unslotted paints above the labels, so nothing prints THROUGH a mark); the yield
+ *    half needs a clean A/B on a mark sitting on a label. Levers 2 and 3 do not depend on it.
+ *
+ * 2. TURN THE FAMILY OFF — `config: { showPlaceLabels: false, showPointOfInterestLabels: false }` on
+ *    `<FMap>`. Free, and the right answer for a dense console where a label would lose every collision
+ *    anyway. It costs the reader their wayfinding, so it is a surface-level decision, not a default.
+ *
+ * 3. HIDE ONE LABEL — Standard's `poi` and `place-labels` featuresets support a `hide` feature state,
+ *    documented for exactly this ("when displaying a custom annotation in place of the hidden symbol"):
+ *      const [f] = map.queryRenderedFeatures({ target: { featuresetId: 'place-labels', importId: 'basemap' } })
+ *      map.setFeatureState(f, { hide: true })
+ *    A scalpel for a surface that replaces a specific basemap symbol with its own mark — a depot standing
+ *    where the basemap draws a POI — not a way to keep marks clear in general.
+ */
+export const MARK_CLAIMS_SPACE = {
+  'icon-allow-overlap': true,
+  'icon-ignore-placement': false,
+} as const;
+
+export interface OverlayLayer {
+  id: string;
+  type: string;
+  source?: string;
+  /** `MAP_SLOT.zone` / `.route` / `.mark` — see MAP_SLOT for what each slot sits above and below */
+  slot?: 'bottom' | 'middle' | 'top';
+  /**
+   * Insert before this existing layer id. For styles with no Standard import, which have no slots:
+   * ordering there has to name a layer. Within the overlay's own layers the ARRAY still decides
+   * order, so this is only for placing the overlay relative to the style underneath it. Mapbox
+   * rejects a beforeId in a different slot, so do not mix the two on one layer.
+   */
+  beforeId?: string;
+  /** false hides via `visibility` — the layer stays in place */
+  visible?: boolean;
+  paint?: Record<string, unknown>;
+  layout?: Record<string, unknown>;
+  /** filter, minzoom, source-layer, … straight through to the style spec */
+  [key: string]: unknown;
+}
+
+/**
+ * A style-spec source object, plus the two keys the live-fleet path needs.
+ *
+ * The whole-collection path (`data`) re-uploads and re-tiles everything on every change, which is the
+ * right thing for a route or a zone and the wrong thing for 30,000 vehicles ticking every few seconds.
+ * `dynamic: true` plus a `patch` diff upserts BY FEATURE ID instead: mapbox touches only the tiles the
+ * moved features live in. A `null` geometry in the diff's `update` list deletes that feature.
+ *
+ * The id contract is `promoteId`: without it a GeoJSON feature has no stable id and there is nothing
+ * for a patch to address, so a dynamic source without `promoteId` (or feature-level `id`s) silently
+ * does nothing.
+ */
+export interface OverlaySource extends Record<string, unknown> {
+  /** the whole collection. The initial upload, and the only path for a non-dynamic source */
+  data?: unknown;
+  /** opt into patch-by-id. Required for `patch` to have any effect */
+  dynamic?: boolean;
+  /**
+   * a GeoJSONSourceDiff — `{ add, update, remove }`. Applied when its identity changes, so hand over a
+   * NEW object per tick (the opposite of `data`, which must stay stable).
+   */
+  patch?: unknown;
+}
+
+export interface OverlaySpec {
+  /**
+   * style-spec source objects, keyed by id. Keep `data` referentially stable (a const or a
+   * computed) — a fresh object every read re-uploads the data on every apply.
+   *
+   * A source that changes on a tick rather than on a user action takes two extra keys instead:
+   * `dynamic: true` and an `update` diff. See the note on `patch` below.
+   */
+  sources?: Record<string, OverlaySource>;
+  layers?: OverlayLayer[];
+  /** basemap config, e.g. { basemap: { colorBuildingSelect: token('--ui-primary') } } */
+  config?: Record<string, Record<string, unknown>>;
+}
+
+// Tokens can sit anywhere, including inside an expression: ['case', c, token('--a'), token('--b')].
+function resolve(value: unknown): unknown {
+  if (isToken(value)) return resolveMapColor(value.expr);
+  if (Array.isArray(value)) return value.map(resolve);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, resolve(v)]));
+  }
+  return value;
+}
+
+function hasToken(value: unknown): boolean {
+  if (isToken(value)) return true;
+  if (Array.isArray(value)) return value.some(hasToken);
+  if (value && typeof value === 'object') return Object.values(value).some(hasToken);
+  return false;
+}
+
+/**
+ * ★ EMISSIVE STRENGTH, APPLIED FOR EVERY OVERLAY THAT NEEDS IT.
+ *
+ * The Forest style is Standard-based and carries 3D lights. `circle`, `fill` and `line` default to
+ * `*-emissive-strength: 0`, which means the renderer SHADES them with the scene lighting — and the night
+ * preset's ambient light is `hsl(217,100%,11%)` at intensity 0.5, a near-black blue. Measured on the published
+ * style at gl 3.24.1:
+ *
+ *     a circle told to paint rgb(0,164,71)     day    rgb(0,163,71)   ΔE   1
+ *                                              dusk   rgb(0, 44,25)   ΔE 129
+ *                                              night  rgb(0, 32,20)   ΔE 142
+ *
+ * At night an unlit overlay paints at about a fifth of its intended luminance. Every ΔE the palette work spent
+ * on separating one state from another is thrown away by the renderer, silently, and only after dark.
+ *
+ * ⚠ SYMBOL LAYERS ARE NOT AFFECTED. Measured: `icon` and `text` paint their exact colour at night with the
+ * property unset. So the vehicle marker was never the problem, and only the three shaded types need this.
+ *
+ * It is injected here rather than published as a constant because a constant is a thing to remember. Every
+ * Forest overlay goes through this seam, and a caller that sets the property itself keeps its own value.
+ */
+const SHADED: Record<string, string> = {
+  circle: 'circle-emissive-strength',
+  fill: 'fill-emissive-strength',
+  line: 'line-emissive-strength',
+};
+
+/** the value: paint the colour that was asked for, and let the basemap be the thing that is lit */
+export const OVERLAY_EMISSIVE = 1;
+
+function withEmissive<T extends { type?: string; paint?: Record<string, unknown> }>(layer: T): T {
+  const key = layer.type ? SHADED[layer.type] : undefined;
+  if (!key) return layer;
+  const paint = layer.paint ?? {};
+  if (key in paint) return layer; // a caller that set it deliberately wins
+  return { ...layer, paint: { ...paint, [key]: OVERLAY_EMISSIVE } };
+}
+
+// Snapshot for diffing. Values are kept by reference on purpose: that is how `data` changes and
+// changed paint values are detected.
+function snapshot(spec: OverlaySpec): OverlaySpec {
+  return {
+    sources: { ...(spec.sources ?? {}) },
+    // ★ Emissive strength is added HERE, in the snapshot, so the diff sees it too — added after the diff it
+    // would look like an external change on every tick and re-set the paint property forever.
+    layers: (spec.layers ?? []).map((l) => {
+      const withEm = withEmissive(l as { type?: string; paint?: Record<string, unknown> }) as typeof l;
+      return { ...withEm, paint: { ...(withEm.paint ?? {}) }, layout: { ...(withEm.layout ?? {}) } };
+    }),
+    config: spec.config,
+  };
+}
+
+export function useMapOverlay(map: ShallowRef<Map | null>, spec: () => OverlaySpec) {
+  let applied: OverlaySpec | null = null;
+  const ours = { sources: new Set<string>(), layers: new Set<string>() };
+  const wired = new WeakSet<Map>();
+
+  function apply(m: Map, next: OverlaySpec) {
+    // Mapbox types paint/layout keys as a union of every known property name. Spec objects here are
+    // authored freely, so the style parser validates them at runtime — these aliases keep the call
+    // sites readable instead of casting at each one.
+    const setPaint = m.setPaintProperty.bind(m) as (id: string, key: string, value: unknown) => void;
+    const setLayout = m.setLayoutProperty.bind(m) as (id: string, key: string, value: unknown) => void;
+
+    // ── sources ──
+    for (const [id, src] of Object.entries(next.sources ?? {})) {
+      const existing = m.getSource(id);
+      if (!existing) {
+        // `patch` is ours, not the style spec's — mapbox would reject the unknown key.
+        const { patch: _patch, ...definition } = src;
+        m.addSource(id, resolve(definition) as never);
+        ours.sources.add(id);
+        continue;
+      }
+      const prev = applied?.sources?.[id];
+      const gj = existing as GeoJSONSource;
+      // A patch beats a whole-collection upload: it is the cheaper of the two and the one a tick wants.
+      if (src.dynamic && src.patch && src.patch !== prev?.patch && 'updateData' in gj) {
+        gj.updateData(src.patch as never);
+      } else if (src.data !== prev?.data && 'setData' in gj) {
+        gj.setData(src.data as never);
+      }
+    }
+
+    // ── layers, in declared order ──
+    // ★ Emissive strength is injected HERE as well as in `snapshot()`, and it has to be both: this is the
+    // path that reaches addLayer, and the snapshot is the path the diff compares against. In one only, either
+    // the property never lands or it is re-set on every tick forever.
+    const declared = (next.layers ?? []).map((l) =>
+      withEmissive(l as { type?: string; paint?: Record<string, unknown> }),
+    ) as typeof next.layers & object[];
+    declared.forEach((layer, i) => {
+      const { visible = true, paint, layout, beforeId, ...rest } = layer;
+      if (!m.getLayer(layer.id)) {
+        // Insert before the next declared layer already on the map, IN THE SAME SLOT: a re-added
+        // layer lands where the array says it belongs, and mapbox rejects a beforeId from a
+        // different slot. `beforeId` is the fallback for a style with no slots — the array still
+        // orders the overlay against itself, so it only decides where the whole overlay sits.
+        const before =
+          declared.slice(i + 1).find((l) => (l.slot ?? null) === (layer.slot ?? null) && m.getLayer(l.id))?.id ??
+          (beforeId && m.getLayer(beforeId) ? beforeId : undefined);
+        // `paint`/`layout` are only passed when present — the style validator rejects the keys set to
+        // undefined ("object expected, undefined found"), which silently drops the whole layer.
+        const definition: Record<string, unknown> = { ...rest };
+        if (paint) definition.paint = resolve(paint);
+        if (layout) definition.layout = resolve(layout);
+        m.addLayer(definition as never, before);
+        // ★ addLayer does NOT throw on an invalid paint expression — mapbox validates, rejects, and
+        // says nothing. The layer is simply absent and the map looks subtly wrong forever. The classic
+        // cause is a zoom `interpolate` nested inside arithmetic, which is only legal at the top level
+        // of a property. Cheap to check, and it turns hours of confusion into one line.
+        if (import.meta.env?.DEV && !m.getLayer(layer.id)) {
+          console.warn(
+            `[useMapOverlay] mapbox rejected layer "${layer.id}" without raising. Usual cause: a zoom ` +
+              'expression nested inside another expression — `interpolate`/`step` on ["zoom"] is only ' +
+              'valid as the whole value of a paint or layout property.',
+            definition,
+          );
+        }
+        ours.layers.add(layer.id);
+      } else {
+        const prev = applied?.layers?.find((l) => l.id === layer.id);
+        // Token values are re-set every apply (the mode may have flipped); plain values only change.
+        for (const [k, v] of Object.entries(paint ?? {})) {
+          if (hasToken(v) || v !== prev?.paint?.[k]) setPaint(layer.id, k, resolve(v));
+        }
+        for (const [k, v] of Object.entries(layout ?? {})) {
+          if (hasToken(v) || v !== prev?.layout?.[k]) setLayout(layer.id, k, resolve(v));
+        }
+        // ★ THE FILTER IS NOT PAINT, and it was silently frozen. A layer's filter is read once at
+        // addLayer and never again, so an overlay whose spec narrowed — a filter chip, an audience
+        // switch — kept drawing the whole source while every count beside it reported the filtered
+        // number. Measured on /maps/scale: the expression said three damage states, the header said
+        // 1,496, and both layers still carried `['literal', true]`.
+        //
+        // Compared by VALUE, not identity: the expression is rebuilt into a new array on every filter
+        // edit, so an identity check re-sets it on every apply — and setFilter is the expensive call
+        // here (measured 325 ms to re-bucket 30,000 features), which is exactly what must not run on
+        // a tick that changed nothing.
+        const nextFilter = (rest as { filter?: unknown }).filter ?? null;
+        if (JSON.stringify(nextFilter) !== JSON.stringify(prev?.filter ?? null)) {
+          m.setFilter(layer.id, nextFilter as never);
+        }
+      }
+      // Guarded: if a layer failed to add, mapbox throws on any property call against it.
+      if (m.getLayer(layer.id)) setLayout(layer.id, 'visibility', visible ? 'visible' : 'none');
+    });
+
+    // ── drop what the spec no longer declares (layers first: a source with layers cannot go) ──
+    for (const id of [...ours.layers]) {
+      if (declared.some((l) => l.id === id)) continue;
+      if (m.getLayer(id)) m.removeLayer(id);
+      ours.layers.delete(id);
+    }
+    for (const id of [...ours.sources]) {
+      if (id in (next.sources ?? {})) continue;
+      if (m.getSource(id)) m.removeSource(id);
+      ours.sources.delete(id);
+    }
+
+    // ── basemap config (token-aware too: colorBuildingSelect and friends) ──
+    for (const [importId, props] of Object.entries(next.config ?? {})) {
+      for (const [k, v] of Object.entries(props)) m.setConfigProperty(importId, k, resolve(v));
+    }
+
+    applied = snapshot(next);
+  }
+
+  let waiting = false;
+
+  function run() {
+    const m = map.value;
+    if (!m) return;
+    // ★ Never wait on `style.load` to catch up. A surface typically hands over the map INSIDE its own
+    // style.load handler (that is when <FMap> emits `ready`), and one microtask later
+    // isStyleLoaded() can still be false because the Standard style is an import that has not
+    // settled — so waiting for style.load again waits for an event that has already fired, forever.
+    // `idle` always comes.
+    if (!m.isStyleLoaded()) {
+      if (waiting) return;
+      waiting = true;
+      // Two triggers on purpose: `styledata` fires as the style settles without needing a frame (so
+      // this still applies in a hidden tab, which never paints), `idle` is the backstop once the map
+      // is actually rendering. Whichever lands first re-runs, and the guard keeps them from stacking.
+      const retry = () => {
+        if (!waiting) return;
+        waiting = false;
+        run();
+      };
+      m.once('styledata', retry);
+      m.once('idle', retry);
+      return;
+    }
+    apply(m, spec());
+  }
+
+  watch(
+    map,
+    (m) => {
+      if (!m) return;
+      applied = null;
+      run();
+      // A later setStyle() wipes our layers — re-apply from scratch when a new style lands.
+      if (!wired.has(m)) {
+        wired.add(m);
+        m.on('style.load', () => {
+          applied = null;
+          run();
+        });
+      }
+    },
+    { immediate: true },
+  );
+
+  watch(spec, run, { deep: true });
+
+  // Colour mode: observe the class LANDING on <html> rather than guessing a frame after a Vue watcher.
+  // See useTokenMode for why a watcher goes one mode behind.
+  const stopModeWatch = onTokenModeChange(run);
+
+  onScopeDispose(() => {
+    stopModeWatch();
+    const m = map.value;
+    if (!m || !m.isStyleLoaded()) return;
+    for (const id of ours.layers) if (m.getLayer(id)) m.removeLayer(id);
+    for (const id of ours.sources) if (m.getSource(id)) m.removeSource(id);
+  });
+
+  return { refresh: run };
+}

package/packages/ui/src/map/useMapTableSelection.ts

@@ -0,0 +1,101 @@
+// The map's selection and the table's, as one thing.
+//
+// Bind `rowSelection` to `<UTable v-model:row-selection>` and clicking a bike ticks its row; ticking a
+// row lights the bike. Neither side owns the selection — `useFeatureSelect` does, and this is a view
+// onto it.
+//
+// ★ A ROW CANNOT BECOME A MAP SELECTION ON ITS OWN. `setFeatureState` addresses a feature by (source,
+// sourceLayer?, id), and a table row carries none of that. So the caller supplies `toFeature(row)`.
+// That is honest rather than awkward — the page has the data — and it is why this is a bridge rather
+// than a two-line computed.
+import { computed, type ComputedRef, type Ref, type ShallowRef, type WritableComputedRef } from 'vue';
+import type { PickedFeature } from './useFeatureSelect';
+import { rowKey, sameSelection, selectedKeys, toRowSelection, type RowSelection } from './selectionModel';
+
+/**
+ * The part of `useFeatureSelect` this needs. Structural, so the real return value satisfies it — and
+ * so a test can drive the bridge without a map, a canvas or WebGL.
+ */
+export interface FeatureSelectionApi {
+  selected: Ref<Set<string | number>>;
+  focused: ShallowRef<PickedFeature | null>;
+  set: (features: PickedFeature[]) => void;
+  clear: () => void;
+}
+
+export interface MapTableSelectionOptions<Row> {
+  /** the rows the table is showing — a `useVisibleFeatures` list, usually */
+  rows: () => readonly Row[];
+  /** ★ must return exactly what the table's `get-row-id` returns, or the two key by different things */
+  rowId: (row: Row) => string | number;
+  /** how to address this row's feature on the map: id, source, and where it is */
+  toFeature: (row: Row) => PickedFeature;
+}
+
+export function useMapTableSelection<Row>(
+  selection: FeatureSelectionApi,
+  options: MapTableSelectionOptions<Row>,
+): {
+  rowSelection: WritableComputedRef<RowSelection>;
+  focusedRow: ComputedRef<Row | null>;
+  isSelected: (row: Row) => boolean;
+  selectRow: (row: Row) => void;
+} {
+  const byKey = () => {
+    const index = new Map<string, Row>();
+    for (const row of options.rows()) index.set(rowKey(options.rowId(row)), row);
+    return index;
+  };
+
+  // Normalised once per selection change rather than per row: `isSelected` is called inside a render
+  // loop, and re-deriving the keys inside it would make painting a list quadratic in its own length.
+  const selectedKeySet = computed(() => {
+    const out = new Set<string>();
+    for (const id of selection.selected.value) out.add(rowKey(id));
+    return out;
+  });
+
+  const rowSelection = computed<RowSelection>({
+    get: () => toRowSelection(selection.selected.value),
+    set(next) {
+      // The guard. Writing back a record that already matches would re-enter through `selected`, and
+      // the two would push each other around for as long as Vue kept flushing.
+      const current = selection.selected.value;
+      if (sameSelection(current, next)) return;
+      // ★ THE ORDER DECIDES THE FOCUS, and the obvious order is the wrong one. `useFeatureSelect.set`
+      // focuses the LAST feature it is handed, and `Object.keys` on a record whose keys look like
+      // integers comes back in ascending NUMERIC order rather than insertion order — so with 4211
+      // selected, ticking row 87 left the callout on 4211, and unticking 4211 slid it onto 87, a row
+      // the reader never touched. Keys already selected keep the order they had; whatever the table
+      // just added goes last, so the callout lands on the row the reader actually ticked.
+      const wanted = new Set(selectedKeys(next));
+      const kept = [...current].map(rowKey).filter((key) => wanted.has(key));
+      const keptSet = new Set(kept);
+      const added = [...wanted].filter((key) => !keptSet.has(key));
+      const index = byKey();
+      const features: PickedFeature[] = [];
+      for (const key of [...kept, ...added]) {
+        // A key with no row is a row the table has since dropped — a filter change, a page turn. It is
+        // skipped rather than treated as an error, because the alternative is a selection that cannot
+        // be cleared.
+        const row = index.get(key);
+        if (row) features.push(options.toFeature(row));
+      }
+      selection.set(features);
+    },
+  });
+
+  return {
+    rowSelection,
+    /** the row behind the one open callout, when it is on this page of rows */
+    focusedRow: computed(() => {
+      const id = selection.focused.value?.id;
+      if (id == null) return null;
+      return byKey().get(rowKey(id)) ?? null;
+    }),
+    /** for a list that is not a UTable. Normalised, so a numeric feature id matches a string row id */
+    isSelected: (row: Row) => selectedKeySet.value.has(rowKey(options.rowId(row))),
+    /** a plain click on a row: this one, and nothing else */
+    selectRow: (row: Row) => selection.set([options.toFeature(row)]),
+  };
+}

package/packages/ui/src/map/useMapUrlState.ts

@@ -0,0 +1,155 @@
+// The camera in the address bar — read once, written on every settle, and never pushed.
+//
+// ★ NOT `hash: true`. GL JS ships a hash sync and it cannot be used in a Vue app: it writes
+// `location.hash` directly, which the router also owns, and it carries the camera and nothing else, so
+// a filter cannot travel with the link. This writes ONE query parameter through `replaceState`,
+// alongside whatever else the page keeps in the URL.
+import { nextTick, onScopeDispose, ref, shallowRef, watch, type ShallowRef } from 'vue';
+import type { Map } from 'mapbox-gl';
+import { decodeCamera, encodeCamera, patchQuery, readQuery, type MapCamera } from './mapUrl';
+
+/** Where the URL lives. Swapped for a router in an app that has one, and for a fake in a test. */
+export interface MapUrlAdapter {
+  /** the current query string, `?` and all */
+  read(): string;
+  /** put this query string in place of it — WITHOUT adding a history entry */
+  replace(search: string): void;
+}
+
+export interface MapUrlStateOptions {
+  /** the query key the camera takes. Give each map on a page its own */
+  param?: string;
+  /** anything else that belongs in the link — a filter, a selected id. `null` removes the key */
+  state?: () => Record<string, string | null | undefined>;
+  /**
+   * The other parameters, handed back once, when the map arrives. The camera has already been applied
+   * by then; this is where a surface restores its own filter from the link.
+   *
+   * ★ RETURN THE PROMISE if the restore is asynchronous — a fetch, a store action, anything that lands
+   * on a later tick. Writing is suppressed until it settles, and without it the first write happens
+   * while the surface is still restoring: `state()` still answers `null` for the key it is about to
+   * fill, and the parameter is erased from the very link it came from.
+   */
+  onRestore?: (params: Record<string, string>, camera: MapCamera | null) => void | Promise<unknown>;
+  adapter?: MapUrlAdapter;
+}
+
+/**
+ * The default: the real address bar.
+ *
+ * ★ `history.state` is passed straight back through. vue-router keeps its own object there — scroll
+ * position, the navigation's place in the stack — and replacing it with `null` breaks the router's
+ * back button in a way that shows up two pages later and looks like anything but a map bug.
+ */
+function browserUrl(): MapUrlAdapter {
+  return {
+    read: () => (typeof window === 'undefined' ? '' : window.location.search),
+    replace(search: string) {
+      if (typeof window === 'undefined') return;
+      const { pathname, hash } = window.location;
+      window.history.replaceState(window.history.state, '', `${pathname}${search}${hash}`);
+    },
+  };
+}
+
+export function useMapUrlState(map: ShallowRef<Map | null>, options: MapUrlStateOptions = {}) {
+  const key = options.param ?? 'map';
+  const adapter = options.adapter ?? browserUrl();
+  /** the full link, for a copy button. Tracks the camera, so it is always what the reader sees */
+  const href = ref('');
+  /** the camera that came out of the link, or null if there was none. For a "shared view" hint */
+  const restored = shallowRef<MapCamera | null>(null);
+
+  // Writes are suppressed until the restore has settled. Without this a surface that applies the
+  // link's filter asynchronously — a watcher, a fetch — gets one `moveend` from the restoring jump
+  // FIRST, and that write erases the very filter it is still applying.
+  let live = false;
+  let wired: Map | null = null;
+
+  const cameraOf = (m: Map): MapCamera => {
+    const c = m.getCenter();
+    return { center: [c.lng, c.lat], zoom: m.getZoom(), bearing: m.getBearing(), pitch: m.getPitch() };
+  };
+
+  function write() {
+    const m = map.value;
+    if (!m || !live) return;
+    const search = patchQuery(adapter.read(), {
+      ...(options.state?.() ?? {}),
+      [key]: encodeCamera(cameraOf(m)),
+    });
+    adapter.replace(search);
+    href.value =
+      typeof window === 'undefined'
+        ? search
+        : `${window.location.origin}${window.location.pathname}${search}${window.location.hash}`;
+  }
+
+  // ★ NOT `useMapReady`. That one INJECTS the enclosing map and takes no instance, which is right for
+  // a component nested inside <FMap> and wrong here — this takes the ref, like every other composable
+  // in this directory, so it works from a page that holds the map itself.
+  //
+  // ★ And not `style.load` either. The camera needs the instance, not the style, and restoring before
+  // the first tiles arrive is what makes a shared link open ON the shared view rather than panning to
+  // it in front of the reader.
+  function restore(m: Map) {
+    const params = readQuery(adapter.read());
+    const camera = decodeCamera(params[key]);
+    restored.value = camera;
+    // ★ `jumpTo`, never `flyTo`. An opening flight from the default view to the shared one is
+    // animation nobody asked for, and each frame of it would report a camera to `moveend` — the link
+    // being restored would be overwritten by the journey towards it.
+    if (camera) m.jumpTo(camera);
+
+    const rest = { ...params };
+    delete rest[key];
+    const restoring = options.onRestore?.(rest, camera);
+
+    m.on('moveend', write);
+    wired = m;
+    // Settle, THEN write. `wired === m` because the map can be swapped out while an asynchronous
+    // restore is still in flight, and enabling writes for an instance nobody is looking at would put
+    // its stale camera in the address bar.
+    const enable = () => {
+      if (wired !== m) return;
+      live = true;
+      write();
+    };
+    // A synchronous restore keeps the one-tick timing it always had; only a caller that returns a
+    // promise pays for the extra hops. Adding them unconditionally would move the first write for
+    // every surface, which is the kind of change that breaks something two pages away.
+    if (typeof (restoring as Promise<unknown> | undefined)?.then === 'function') {
+      void (restoring as Promise<unknown>).then(() => nextTick()).then(enable);
+    } else {
+      void nextTick(enable);
+    }
+  }
+
+  watch(
+    map,
+    (m) => {
+      // ★ A map is not for life. <FMap> creates a new instance on remount — a route change, a `v-if`,
+      // a style swap — and the old guard (`if (m && !wired)`) latched on the FIRST one for ever: the
+      // second instance was never restored, never wired, and the URL froze on the dead map's last
+      // camera while the copy-link button went on advertising it.
+      if (wired && wired !== m) {
+        wired.off('moveend', write);
+        wired = null;
+        live = false;
+      }
+      if (m && !wired) restore(m);
+    },
+    { immediate: true },
+  );
+
+  // The camera is not the only thing in the link, and the other things change without the map moving.
+  // Stringified because `state()` returns a fresh object every call, which no shallow watcher can tell
+  // from a changed one; the objects are a handful of short strings, so this costs nothing.
+  watch(() => JSON.stringify(options.state?.() ?? {}), write);
+
+  onScopeDispose(() => {
+    wired?.off('moveend', write);
+  });
+
+  return { href, restored, /** force a write — for state that changes outside `state()` */ write };
+}