@humanforest/nuxt-layer 0.1.0

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

@@ -0,0 +1,284 @@
+// One filter, three renderings — and the reason they cannot be written separately.
+//
+// A console filters a fleet in three places at once: the GL layer (30,000 features, filtered on the
+// GPU), the list beside it (JavaScript, over the same features), and the link somebody pastes into
+// Slack (a string). Write those by hand and they drift — the map hides a bike the count still counts,
+// and nobody can see why. This file is the single rule; the three are renderings of it.
+//
+// ★ AND ACROSS AXES, OR WITHIN ONE. `{ groups: ['functional'], battery: ['LOW', 'CRITICAL'] }` is
+// "functional bikes that are flat", which is what a dispatcher means by setting two filters. An absent
+// or empty axis is not a constraint, so `{}` matches the whole fleet.
+//
+// The axes are `vehicle.ts`'s own — state, battery, offline, rental — plus two conveniences: `groups`
+// expands through STATE_GROUP, and `available` is the derived rule.
+import {
+  AVAILABLE_BATTERY,
+  AVAILABLE_STATES,
+  STATE_GROUP,
+  type BatteryLevel,
+  type RentalState,
+  type StateGroup,
+  type VehicleFacts,
+  type VehicleState,
+} from './vehicle';
+
+export interface VehicleFilter {
+  /** exact states. Unions with `groups` — both narrow the same axis */
+  states?: readonly VehicleState[];
+  /** state groups, expanded to their states. The vocabulary the group toggles speak */
+  groups?: readonly StateGroup[];
+  battery?: readonly BatteryLevel[];
+  rental?: readonly RentalState[];
+  /** true = only offline, false = only online. Absent = either */
+  offline?: boolean;
+  /** the derived rule across all four axes. Absent = either */
+  available?: boolean;
+}
+
+/** Which feature property carries each axis. Defaults are what the fleet fixture writes. */
+export interface VehicleFilterProps {
+  state?: string;
+  battery?: string;
+  offline?: string;
+  rental?: string;
+}
+
+const DEFAULT_PROPS: Required<VehicleFilterProps> = {
+  state: 'state',
+  battery: 'battery',
+  offline: 'offline',
+  rental: 'rental',
+};
+
+/** Every axis, in the order a filter reads. Exported so a control can iterate without a second list. */
+export const VEHICLE_FILTER_AXES = ['states', 'groups', 'battery', 'rental', 'offline', 'available'] as const;
+export type VehicleFilterAxis = (typeof VEHICLE_FILTER_AXES)[number];
+
+/** The axes that hold a list of values — the ones a chip row toggles into. */
+export const VEHICLE_FILTER_LIST_AXES = ['states', 'groups', 'battery', 'rental'] as const;
+export type VehicleFilterListAxis = (typeof VEHICLE_FILTER_LIST_AXES)[number];
+
+/**
+ * The state axis, resolved: exact states unioned with every state in the chosen groups.
+ *
+ * ★ Groups resolve to STATES rather than filtering a `group` property, even though the fixture writes
+ * one. A precomputed property is an assumption about the caller's data, and a wrong assumption here
+ * fails silently — the layer filters on a property that is not there and hides the whole fleet. Fifteen
+ * strings in an `in` list cost nothing next to the re-tile the filter change triggers anyway.
+ */
+export function filterStates(filter: VehicleFilter): VehicleState[] {
+  const out = new Set<VehicleState>(filter.states ?? []);
+  if (filter.groups?.length) {
+    const wanted = new Set<StateGroup>(filter.groups);
+    for (const [state, group] of Object.entries(STATE_GROUP) as [VehicleState, StateGroup][]) {
+      if (wanted.has(group)) out.add(state);
+    }
+  }
+  return [...out];
+}
+
+/** How many axes actually bite — the number on a "Clear" button. */
+export function activeAxisCount(filter: VehicleFilter): number {
+  let n = 0;
+  if (filter.states?.length || filter.groups?.length) n++;
+  if (filter.battery?.length) n++;
+  if (filter.rental?.length) n++;
+  if (filter.offline !== undefined) n++;
+  if (filter.available !== undefined) n++;
+  return n;
+}
+
+export const isEmptyVehicleFilter = (filter: VehicleFilter): boolean => activeAxisCount(filter) === 0;
+
+const oneOf = (property: string, values: readonly string[]): unknown[] => [
+  'in',
+  ['get', property],
+  ['literal', [...values]],
+];
+
+/**
+ * `offline` as a boolean, with a missing property meaning ONLINE.
+ *
+ * ★ `['!', ['get', 'offline']]` is not this. `get` on a property a feature does not carry returns
+ * null, and `!` on null is an evaluation error rather than `true` — the layer then drops the feature
+ * with a console warning nobody reads. Coalesce first, always.
+ */
+const offlineFlag = (property: string): unknown[] => ['coalesce', ['get', property], false];
+
+/**
+ * `rental`, with a missing property meaning AVAILABLE — matching `isAvailable`'s `v.rental ?? 'AVAILABLE'`.
+ *
+ * ★ THE DIVERGENCE THIS FILE EXISTS TO PREVENT, and it is one operator wide. The 31,602/31,602
+ * agreement with the platform's own `available` flag was measured on a snapshot carrying no rental
+ * data at all; drop the coalesce and every one of those features becomes unavailable in the expression
+ * while staying available in the predicate.
+ */
+const rentalValue = (property: string): unknown[] => ['coalesce', ['get', property], 'AVAILABLE'];
+
+/** The availability rule as an expression — `isAvailable`, operator for operator. */
+export function availableExpression(props: VehicleFilterProps = {}): unknown[] {
+  const p = { ...DEFAULT_PROPS, ...props };
+  return [
+    'all',
+    ['!', offlineFlag(p.offline)],
+    ['==', rentalValue(p.rental), 'AVAILABLE'],
+    oneOf(p.state, AVAILABLE_STATES),
+    oneOf(p.battery, AVAILABLE_BATTERY),
+  ];
+}
+
+/**
+ * The filter as a style-spec expression, for `layer.filter`.
+ *
+ * An unconstrained filter is `['literal', true]` rather than an empty `all`: it reads as "no filter"
+ * in a style dump, and it is what the layer would have carried before any filter existed.
+ */
+export function vehicleFilterExpression(filter: VehicleFilter, props: VehicleFilterProps = {}): unknown[] {
+  const p = { ...DEFAULT_PROPS, ...props };
+  const clauses: unknown[][] = [];
+
+  const states = filterStates(filter);
+  if (states.length) clauses.push(oneOf(p.state, states));
+  if (filter.battery?.length) clauses.push(oneOf(p.battery, filter.battery));
+  if (filter.rental?.length) clauses.push(['in', rentalValue(p.rental), ['literal', [...filter.rental]]]);
+  if (filter.offline !== undefined) {
+    clauses.push(filter.offline ? offlineFlag(p.offline) : ['!', offlineFlag(p.offline)]);
+  }
+  if (filter.available !== undefined) {
+    const rule = availableExpression(props);
+    clauses.push(filter.available ? rule : ['!', rule]);
+  }
+
+  return clauses.length ? ['all', ...clauses] : ['literal', true];
+}
+
+/**
+ * The same filter as a predicate, for the list and the counts beside the map.
+ *
+ * Returns a function rather than taking the vehicle directly: the sets are built once and reused
+ * across the whole fleet, which is the difference between a linear scan and a quadratic one.
+ */
+export function vehicleFilterMatch(filter: VehicleFilter): (vehicle: VehicleFacts) => boolean {
+  const states = filterStates(filter);
+  const stateSet = states.length ? new Set<VehicleState>(states) : null;
+  const batterySet = filter.battery?.length ? new Set<BatteryLevel>(filter.battery) : null;
+  const rentalSet = filter.rental?.length ? new Set<RentalState>(filter.rental) : null;
+  const available = filter.available;
+  const offline = filter.offline;
+
+  return (vehicle: VehicleFacts): boolean => {
+    if (stateSet && !stateSet.has(vehicle.state)) return false;
+    if (batterySet && !batterySet.has(vehicle.battery)) return false;
+    // The predicate's own `?? 'AVAILABLE'` — the same default the expression coalesces to.
+    if (rentalSet && !rentalSet.has(vehicle.rental ?? 'AVAILABLE')) return false;
+    if (offline !== undefined && !!vehicle.offline !== offline) return false;
+    if (available !== undefined) {
+      const is =
+        !vehicle.offline &&
+        (vehicle.rental ?? 'AVAILABLE') === 'AVAILABLE' &&
+        AVAILABLE_STATES.includes(vehicle.state) &&
+        AVAILABLE_BATTERY.includes(vehicle.battery);
+      if (is !== available) return false;
+    }
+    return true;
+  };
+}
+
+// ── The link ────────────────────────────────────────────────────────────────────────────────────
+//
+// `g:functional,damage;b:LOW;o:1` — one key per axis, values comma-separated. Compact enough to sit
+// beside the camera in a query string, and legible enough that a person can see what a link filters
+// before they open it.
+
+const AXIS_KEY: Record<VehicleFilterListAxis | 'offline' | 'available', string> = {
+  states: 's',
+  groups: 'g',
+  battery: 'b',
+  rental: 'r',
+  offline: 'o',
+  available: 'a',
+};
+
+const KNOWN_STATES = new Set(Object.keys(STATE_GROUP));
+const KNOWN_GROUPS = new Set(Object.values(STATE_GROUP));
+const KNOWN_BATTERY = new Set(['HIGH', 'MEDIUM', 'LOW', 'CRITICAL']);
+const KNOWN_RENTAL = new Set(['AVAILABLE', 'RESERVATION', 'DRIVING', 'PARKING', 'DELIVERED']);
+
+export function encodeVehicleFilter(filter: VehicleFilter): string {
+  const parts: string[] = [];
+  const list = (key: string, values?: readonly string[]) => {
+    if (values?.length) parts.push(`${key}:${values.join(',')}`);
+  };
+  list(AXIS_KEY.states, filter.states);
+  list(AXIS_KEY.groups, filter.groups);
+  list(AXIS_KEY.battery, filter.battery);
+  list(AXIS_KEY.rental, filter.rental);
+  if (filter.offline !== undefined) parts.push(`${AXIS_KEY.offline}:${filter.offline ? 1 : 0}`);
+  if (filter.available !== undefined) parts.push(`${AXIS_KEY.available}:${filter.available ? 1 : 0}`);
+  return parts.join(';');
+}
+
+/**
+ * The reverse. A URL is user input, so every value is checked against the vocabulary and anything
+ * unrecognised is DROPPED rather than carried through.
+ *
+ * ★ Dropped, not rejected. A link made by an older build can name a state this one no longer has; the
+ * reader should get the rest of their filter, not an empty map and no explanation. An axis left with
+ * no valid values falls out entirely, which is the same thing as never having been set.
+ */
+export function decodeVehicleFilter(text: string | null | undefined): VehicleFilter {
+  const filter: VehicleFilter = {};
+  if (!text) return filter;
+
+  const keep = (values: string[], known: Set<string>) => {
+    const out = values.map((v) => v.trim()).filter((v) => known.has(v));
+    return out.length ? out : undefined;
+  };
+
+  for (const part of text.split(';')) {
+    const at = part.indexOf(':');
+    if (at < 0) continue;
+    const key = part.slice(0, at).trim();
+    const raw = part.slice(at + 1).split(',');
+    switch (key) {
+      case AXIS_KEY.states:
+        filter.states = keep(raw, KNOWN_STATES) as VehicleState[] | undefined;
+        break;
+      case AXIS_KEY.groups:
+        filter.groups = keep(raw, KNOWN_GROUPS) as StateGroup[] | undefined;
+        break;
+      case AXIS_KEY.battery:
+        filter.battery = keep(raw, KNOWN_BATTERY) as BatteryLevel[] | undefined;
+        break;
+      case AXIS_KEY.rental:
+        filter.rental = keep(raw, KNOWN_RENTAL) as RentalState[] | undefined;
+        break;
+      // A flag is 1 or 0. Anything else — including the empty string a stray `o:` leaves — is not a
+      // third state, it is a broken link, and the axis goes unset.
+      case AXIS_KEY.offline:
+        if (raw[0] === '1' || raw[0] === '0') filter.offline = raw[0] === '1';
+        break;
+      case AXIS_KEY.available:
+        if (raw[0] === '1' || raw[0] === '0') filter.available = raw[0] === '1';
+        break;
+    }
+  }
+
+  // `keep` returns undefined for an all-invalid axis, which assignment above turns into an explicit
+  // `states: undefined` key. Strip those so the result equals a filter that was never given the axis.
+  for (const axis of VEHICLE_FILTER_LIST_AXES) if (filter[axis] === undefined) delete filter[axis];
+  return filter;
+}
+
+/** Add or remove one value on a list axis, returning a new filter. The verb a chip row calls. */
+export function toggleVehicleFilter<K extends VehicleFilterListAxis>(
+  filter: VehicleFilter,
+  axis: K,
+  value: NonNullable<VehicleFilter[K]>[number],
+): VehicleFilter {
+  const current = (filter[axis] ?? []) as readonly string[];
+  const next = current.includes(value) ? current.filter((v) => v !== value) : [...current, value];
+  const out = { ...filter, [axis]: next } as VehicleFilter;
+  if (!next.length) delete out[axis];
+  return out;
+}

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

@@ -0,0 +1,155 @@
+// The key to a vehicle mark — one section per axis, because the axes are independent.
+//
+// ★ THIS IS THE SHAPE THE MARK FORCES. `vehicle.ts` opens by saying a vehicle is three independent
+// axes and not one status enum, and that collapsing them is what every surface gets wrong first. A
+// legend can make that same mistake: 6 state groups × 3 charge bands × 2 connectivity states is 36
+// combinations, and a flat list of any subset of them reads as one enum with 36 values.
+//
+// So: a section per axis, and WITHIN a section exactly one channel moves. Charge rows hold the state
+// still so the ring is the only difference; state rows pass no charge at all, so no ring is drawn and
+// the disc is the only difference. A reader can then attribute what they see to the thing it means.
+//
+// ★ THE ROWS DESCRIBE A MARK, NOT A COLOUR. Each row carries the props to draw a real <FVehicleMark>,
+// which needs no map and renders at natural size. The key shows the artwork the map draws rather than
+// a square approximating it — and the artwork is the only honest swatch for a disc that carries a
+// glyph inside a ring.
+import {
+  BATTERY_RING_BAND,
+  STATE_GROUP,
+  labelOf,
+  type BatteryLevel,
+  type BatteryRingBand,
+  type StateGroup,
+  type VehicleState,
+} from './vehicle';
+
+/** Which axis a section reads. Named for the axes in `vehicle.ts`, not for the channel that paints them. */
+export type VehicleLegendAxis = 'state' | 'charge' | 'connectivity';
+
+/** One row: what to draw, and what it means. */
+export interface VehicleLegendRow {
+  key: string;
+  label: string;
+  /** props for <FVehicleMark> — the row draws the real mark rather than a swatch standing in for it */
+  mark: { state: VehicleState; battery?: BatteryLevel; offline?: boolean };
+}
+
+export interface VehicleLegendSection {
+  axis: VehicleLegendAxis;
+  label: string;
+  rows: VehicleLegendRow[];
+  /**
+   * What an ABSENT mark means, where absence is the common case.
+   *
+   * ★ It cannot be a row. The mark encodes only exceptions — 80% of the fleet is online and paints no
+   * dot at all — so the usual case has no swatch to put beside a label. Stating it is the only way to
+   * say it, and leaving it unsaid is what makes a reader think the dot is decoration.
+   */
+  note?: string;
+}
+
+/**
+ * One state per group, standing for the group.
+ *
+ * ★ A row draws one mark, and a mark needs a STATE — there is no such thing as drawing a group. The
+ * test holds each of these to its group in STATE_GROUP, so a state that is regrouped later cannot
+ * leave a row painting a disc that contradicts its own label. The glyph is the representative state's
+ * own, which is why rows are labelled by GROUP and the glyph table stays on the component's page.
+ */
+const GROUP_SPECIMEN: Record<StateGroup, VehicleState> = {
+  functional: 'FUNCTIONAL',
+  damage: 'SERVICE_ON_SITE',
+  hold: 'MAINTENANCE',
+  parked: 'SERVICE_WORKSHOP',
+  lost: 'LOST',
+  retired: 'RETIRED',
+};
+
+/**
+ * Reading order: the normal case, then the ways it goes wrong, then the ways it leaves.
+ *
+ * Not the declaration order and not the colour ramp — a reader opens a key to place what they are
+ * looking at, and 74% of the fleet is functional.
+ */
+const GROUP_ORDER: readonly StateGroup[] = [
+  'functional',
+  'damage',
+  'hold',
+  'parked',
+  'lost',
+  'retired',
+];
+
+/** A level that lands in each band, so the row draws the ring it names. */
+const BAND_SPECIMEN: Record<BatteryRingBand, BatteryLevel> = {
+  OK: 'HIGH',
+  LOW: 'LOW',
+  CRITICAL: 'CRITICAL',
+};
+
+const BAND_ORDER: readonly BatteryRingBand[] = ['OK', 'LOW', 'CRITICAL'];
+
+/**
+ * The state every non-state section draws.
+ *
+ * Holding it at FUNCTIONAL is what makes those sections readable: the disc and glyph stay put, so the
+ * ring or the dot is the only thing a reader has to account for.
+ */
+const HELD = 'FUNCTIONAL' as const;
+
+const SECTION_LABEL: Record<VehicleLegendAxis, string> = {
+  state: 'State',
+  charge: 'Charge',
+  connectivity: 'Connectivity',
+};
+
+const DEFAULT_AXES: readonly VehicleLegendAxis[] = ['state', 'charge', 'connectivity'];
+
+/**
+ * The legend for a vehicle mark, one section per axis.
+ *
+ * Pass the axes a surface actually paints. A surface that omits `battery` on its marks draws no ring,
+ * so a charge section would explain a channel that is not there.
+ */
+export function vehicleLegendSections(
+  axes: readonly VehicleLegendAxis[] = DEFAULT_AXES,
+): VehicleLegendSection[] {
+  const wanted = new Set(axes);
+
+  return DEFAULT_AXES.filter((axis) => wanted.has(axis)).map((axis) => {
+    if (axis === 'state') {
+      return {
+        axis,
+        label: SECTION_LABEL[axis],
+        rows: GROUP_ORDER.map((group) => ({
+          key: group,
+          label: labelOf(group),
+          // No charge: the ring would be a second variable in a section about the disc.
+          mark: { state: GROUP_SPECIMEN[group] },
+        })),
+      };
+    }
+
+    if (axis === 'charge') {
+      return {
+        axis,
+        label: SECTION_LABEL[axis],
+        rows: BAND_ORDER.map((band) => ({
+          key: band,
+          label: labelOf(band),
+          mark: { state: HELD, battery: BAND_SPECIMEN[band] },
+        })),
+      };
+    }
+
+    return {
+      axis,
+      label: SECTION_LABEL[axis],
+      rows: [{ key: 'offline', label: 'Offline', mark: { state: HELD, offline: true } }],
+      note: 'No dot means the vehicle is reporting.',
+    };
+  });
+}
+
+/** Re-exported so a caller can hold a row's group against the source of truth. */
+export { STATE_GROUP, BATTERY_RING_BAND };

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

@@ -0,0 +1,192 @@
+// What is on screen — the arithmetic, without the map.
+//
+// A source query is a superset of the answer: one copy of a feature PER TILE for anything on a seam,
+// and features outside the viewport because a tile extends past the edge of it. So the list a reader
+// sees comes out of three steps in this order — dedupe, keep what the viewport holds, cap — and each
+// of them is a place a hand-rolled version goes wrong.
+
+export interface ViewBox {
+  west: number;
+  south: number;
+  east: number;
+  north: number;
+}
+
+export interface VisibleFeature {
+  /** stable across tiles and across reads — what a keyed `v-for` and a table row id use */
+  key: string;
+  id: string | number | undefined;
+  feature: GeoJSON.Feature;
+  /** the point it sits at, or the centre of its extent for a line or a polygon */
+  at: [number, number];
+  props: Record<string, unknown>;
+}
+
+export interface CollectOptions {
+  /** feature property to key by, when the feature carries no id of its own */
+  idBy?: string;
+  /** how many to publish. The rest are counted, not returned */
+  limit?: number;
+  /** keep cluster features. Off, because "40 bikes" is not a row anyone can act on */
+  clusters?: boolean;
+}
+
+/** 500 rows is already more than a person reads; 30,000 is a page that does not paint. */
+export const VISIBLE_LIMIT = 500;
+
+/**
+ * Longitude compared on a CIRCLE rather than on a line.
+ *
+ * ★ MAPBOX DOES NOT RETURN A west > east BOX. `Transform.getBounds()` builds its LngLatBounds through
+ * `extend`, which takes `Math.min`/`Math.max` of the corners, so `getWest() <= getEast()` always. What
+ * it returns when the reader drags past the antimeridian is an UNWRAPPED box — `{ west: 359.85, east:
+ * 360.15 }` — because `renderWorldCopies` draws the world again and the camera is genuinely over copy
+ * +1. Every feature is still at lng ≈ -0.1, so a straight comparison excludes the entire source and
+ * the list empties while the canvas shows the whole fleet.
+ *
+ * So longitudes are brought into the box's own turn before they are compared. That handles the
+ * unwrapped box, the exactly-straddling box, and a hand-built west > east box (which this module still
+ * accepts, because a caller assembling a ViewBox by hand may well write one).
+ */
+function lngWithin(box: ViewBox, lng: number): boolean {
+  const east = box.east >= box.west ? box.east : box.east + 360;
+  // A box spanning a whole turn or more holds every longitude — and the shift below would be
+  // meaningless for it.
+  if (east - box.west >= 360) return true;
+  const shifted = box.west + ((((lng - box.west) % 360) + 360) % 360);
+  return shifted <= east;
+}
+
+/** Whether a box holds a point. Edges count as inside. */
+export function boxContains(box: ViewBox, [lng, lat]: [number, number]): boolean {
+  if (lat < box.south || lat > box.north) return false;
+  return lngWithin(box, lng);
+}
+
+/** Every coordinate in a geometry, flattened. GeometryCollection included, because a source can hold one. */
+function* coordinatesOf(geometry: GeoJSON.Geometry): Generator<[number, number]> {
+  if (geometry.type === 'GeometryCollection') {
+    for (const g of geometry.geometries) yield* coordinatesOf(g);
+    return;
+  }
+  const walk = (value: unknown): void => {
+    if (!Array.isArray(value)) return;
+    if (typeof value[0] === 'number' && typeof value[1] === 'number') {
+      out.push([value[0], value[1]]);
+      return;
+    }
+    for (const inner of value) walk(inner);
+  };
+  const out: [number, number][] = [];
+  walk((geometry as { coordinates?: unknown }).coordinates);
+  yield* out;
+}
+
+/** The point a feature is listed at: its own, or the centre of what it covers. Null if it covers nothing. */
+export function featureAnchor(feature: GeoJSON.Feature): [number, number] | null {
+  const geometry = feature.geometry;
+  if (!geometry) return null;
+  if (geometry.type === 'Point') return geometry.coordinates as [number, number];
+  let west = Infinity;
+  let south = Infinity;
+  let east = -Infinity;
+  let north = -Infinity;
+  for (const [lng, lat] of coordinatesOf(geometry)) {
+    west = Math.min(west, lng);
+    east = Math.max(east, lng);
+    south = Math.min(south, lat);
+    north = Math.max(north, lat);
+  }
+  if (!Number.isFinite(west)) return null;
+  return [(west + east) / 2, (south + north) / 2];
+}
+
+/**
+ * Whether a feature is in view. A point is in view when the box holds it; anything else when its
+ * extent OVERLAPS the box — a zone the reader is standing inside covers the whole viewport and
+ * contains no vertex in it, so testing its coordinates one at a time would drop the one zone that
+ * matters most.
+ */
+export function featureInBox(box: ViewBox, feature: GeoJSON.Feature): boolean {
+  const geometry = feature.geometry;
+  if (!geometry) return false;
+  if (geometry.type === 'Point') return boxContains(box, geometry.coordinates as [number, number]);
+  let west = Infinity;
+  let south = Infinity;
+  let east = -Infinity;
+  let north = -Infinity;
+  for (const [lng, lat] of coordinatesOf(geometry)) {
+    west = Math.min(west, lng);
+    east = Math.max(east, lng);
+    south = Math.min(south, lat);
+    north = Math.max(north, lat);
+  }
+  if (!Number.isFinite(west)) return false;
+  if (north < box.south || south > box.north) return false;
+  const boxEast = box.east >= box.west ? box.east : box.east + 360;
+  if (boxEast - box.west >= 360) return true;
+  // The feature's span, moved by whole turns until its centre is nearest the box's — the copy of the
+  // world the reader is actually looking at. Same unwrapped-bounds problem as `lngWithin`, but an
+  // interval rather than a point, so it is shifted rather than folded.
+  const shift = Math.round(((box.west + boxEast) / 2 - (west + east) / 2) / 360) * 360;
+  return east + shift >= box.west && west + shift <= boxEast;
+}
+
+/** The key a feature is deduped and listed by. */
+export function featureKey(feature: GeoJSON.Feature, idBy?: string): string {
+  const props = (feature.properties ?? {}) as Record<string, unknown>;
+  if (props.cluster_id != null) return `c${props.cluster_id}`;
+  const own = feature.id ?? (idBy ? props[idBy] : undefined);
+  // Falling back to the geometry is not elegant, and it is better than dropping the feature: a source
+  // without ids still lists, it just cannot be selected — and selection is the thing that needs an id.
+  return String(own ?? JSON.stringify(feature.geometry));
+}
+
+/**
+ * The three steps, in the order that makes them correct.
+ *
+ * `count` is what is in view; `items` is what fits under the limit. A surface that shows only
+ * `items.length` tells the reader there are 500 bikes in a viewport holding 1,284 — so both come back,
+ * and `capped` says which sentence to write.
+ */
+export function collectVisible(
+  features: Iterable<GeoJSON.Feature>,
+  box: ViewBox,
+  options: CollectOptions = {},
+): { items: VisibleFeature[]; count: number; capped: boolean } {
+  const limit = options.limit ?? VISIBLE_LIMIT;
+  const seen = new Set<string>();
+  const items: VisibleFeature[] = [];
+  let count = 0;
+
+  for (const feature of features) {
+    const props = (feature.properties ?? {}) as Record<string, unknown>;
+    if (props.cluster && !options.clusters) continue;
+    // ★ THE VIEWPORT TEST COMES FIRST, and the order is load-bearing. The copies of a feature that
+    // `querySourceFeatures` returns are one per tile, and for anything that is not a Point they are
+    // tile FRAGMENTS — each carries only that tile's clipped portion of the geometry. Deduping first
+    // lets whichever fragment the query happens to yield first decide membership for the whole
+    // feature, and the tile order is not viewport order: a zone whose fragment in the neighbouring
+    // tile lies in that tile's off-screen skirt would claim the key, fail the box test, and take the
+    // on-screen fragment down with it. The zone is painted and absent from the list.
+    if (!featureInBox(box, feature)) continue;
+    // Deduping after it still collapses the copies that matter — two in-view fragments of one zone,
+    // or the identical copies of a point on a seam — because they share a key.
+    //
+    // ⚠ Except when the source carries no ids: `featureKey` then falls back to the geometry, which
+    // DIFFERS per fragment, so one zone lists once per tile it touches. That is the honest limit of
+    // what a client can do without an id, and it is why `idBy` exists.
+    const key = featureKey(feature, options.idBy);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    // The anchor is resolved before the count, not after the limit: a feature counted but never
+    // listable would make `capped` true on a list that is not actually short of anything.
+    const at = featureAnchor(feature);
+    if (!at) continue;
+    count++;
+    if (items.length >= limit) continue;
+    items.push({ key, id: feature.id ?? (options.idBy ? (props[options.idBy] as string | number) : undefined), feature, at, props });
+  }
+
+  return { items, count, capped: count > items.length };
+}