@humanforest/nuxt-layer 0.1.0

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

@@ -0,0 +1,163 @@
+// useMarkerSource — many markers from one clustered GeoJSON source.
+//
+// The source is GL-world (a source plus the layer that makes mapbox tile it), so it is a composable,
+// not a component. It publishes the features currently in view; the page maps those to <FMarker>
+// children, which keeps reconciliation in Vue's keyed v-for: a key leaving the list unmounts its
+// marker and mapbox drops the element. Element count therefore tracks what is ON SCREEN rather than
+// what exists, which is what moves the ceiling from a few hundred markers to a fleet.
+//
+// ★ The anchor layer is not optional. Mapbox only tiles a source that some layer references, and
+// querySourceFeatures reads tiles — measured on a live map: 0 features with no layer, all of them once
+// a zero-opacity circle layer is attached. It paints nothing; it exists so the source is tiled.
+import { computed, onScopeDispose, shallowRef, watch, type ShallowRef } from 'vue';
+import type { GeoJSONSource, Map } from 'mapbox-gl';
+
+let uid = 0;
+
+export interface MarkerSourceOptions {
+  /** the collection to place. Keep the reference stable (a computed) — a new object re-uploads it */
+  data: GeoJSON.FeatureCollection;
+  cluster?: boolean;
+  clusterRadius?: number;
+  clusterMaxZoom?: number;
+  clusterMinPoints?: number;
+  /** supercluster aggregations, e.g. { low: ['+', ['get', 'low']] } — read back off `props` */
+  clusterProperties?: Record<string, unknown>;
+  /** feature property to key markers by. Falls back to the feature's own id */
+  keyBy?: string;
+  /** `idle` re-reads once motion settles (cheap); `move` tracks every frame */
+  refresh?: 'idle' | 'move';
+}
+
+export interface MarkerSourceItem {
+  /** stable key for a v-for — cluster id, or the feature key */
+  key: string;
+  feature: GeoJSON.Feature;
+  at: [number, number];
+  isCluster: boolean;
+  /** members of the cluster; 0 for a single feature */
+  count: number;
+  /** feature properties, or the cluster's aggregated ones */
+  props: Record<string, unknown>;
+}
+
+export function useMarkerSource(map: ShallowRef<Map | null>, options: () => MarkerSourceOptions) {
+  const sourceId = `f-markers-${uid++}`;
+  const anchorId = `${sourceId}-anchor`;
+  const features = shallowRef<{ key: string; feature: GeoJSON.Feature }[]>([]);
+  let attached: Map | null = null;
+  let listening: 'idle' | 'move' = 'idle';
+
+  function read() {
+    const m = attached;
+    if (!m || !m.getSource(sourceId)) return;
+    const { keyBy } = options();
+    // querySourceFeatures returns one copy per tile, so a marker on a seam would double.
+    const seen = new Set<string>();
+    const out: { key: string; feature: GeoJSON.Feature }[] = [];
+    for (const feature of m.querySourceFeatures(sourceId)) {
+      const p = (feature.properties ?? {}) as Record<string, unknown>;
+      const key =
+        p.cluster_id != null
+          ? `c${p.cluster_id}`
+          : String(feature.id ?? (keyBy ? p[keyBy] : undefined) ?? JSON.stringify(feature.geometry));
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({ key, feature });
+    }
+    features.value = out;
+  }
+
+  function attach(m: Map) {
+    if (attached) return;
+    const o = options();
+    attached = m;
+    m.addSource(sourceId, {
+      type: 'geojson',
+      data: o.data,
+      ...(o.keyBy ? { promoteId: o.keyBy } : {}),
+      ...(o.cluster
+        ? {
+            cluster: true,
+            clusterRadius: o.clusterRadius ?? 50,
+            ...(o.clusterMaxZoom != null ? { clusterMaxZoom: o.clusterMaxZoom } : {}),
+            ...(o.clusterMinPoints != null ? { clusterMinPoints: o.clusterMinPoints } : {}),
+            ...(o.clusterProperties ? { clusterProperties: o.clusterProperties } : {}),
+          }
+        : {}),
+    } as never);
+    m.addLayer({
+      id: anchorId,
+      type: 'circle',
+      source: sourceId,
+      // The one layer whose slot carries no meaning: it paints nothing, so nothing can cover it. It is
+      // in `bottom` to stay out of the collision index's way, NOT via MAP_SLOT — the markers this
+      // source feeds are DOM elements over the canvas, which no basemap layer can hide.
+      slot: 'bottom',
+      paint: { 'circle-radius': 0, 'circle-opacity': 0 },
+    } as never);
+    listening = o.refresh === 'move' ? 'move' : 'idle';
+    m.on(listening, read);
+    m.on('sourcedata', read);
+    read();
+  }
+
+  // The style must be ready before addSource. `styledata` fires without needing a frame; `idle` is the
+  // backstop. Waiting on style.load alone deadlocks when the map arrives already loaded.
+  function start() {
+    const m = map.value;
+    if (!m || attached) return;
+    if (m.isStyleLoaded()) {
+      attach(m);
+      return;
+    }
+    m.once('styledata', start);
+    m.once('idle', start);
+  }
+
+  watch(map, start, { immediate: true });
+  watch(
+    () => options().data,
+    (data) => (attached?.getSource(sourceId) as GeoJSONSource | undefined)?.setData(data as never),
+  );
+
+  onScopeDispose(() => {
+    const m = attached;
+    if (!m) return;
+    m.off(listening, read);
+    m.off('sourcedata', read);
+    if (!m.isStyleLoaded()) return;
+    if (m.getLayer(anchorId)) m.removeLayer(anchorId);
+    if (m.getSource(sourceId)) m.removeSource(sourceId);
+  });
+
+  const items = computed<MarkerSourceItem[]>(() =>
+    features.value.map(({ key, feature }) => {
+      const props = (feature.properties ?? {}) as Record<string, unknown>;
+      return {
+        key,
+        feature,
+        at: (feature.geometry as GeoJSON.Point).coordinates as [number, number],
+        isCluster: !!props.cluster,
+        count: Number(props.point_count ?? 0),
+        props,
+      };
+    }),
+  );
+
+  return {
+    /** what is in view right now — feed this to a keyed v-for of <FMarker> */
+    items,
+    sourceId,
+    /** zoom to where a cluster breaks apart. No `essential` — reduced motion is honoured */
+    expand(item: MarkerSourceItem) {
+      const src = attached?.getSource(sourceId) as GeoJSONSource | undefined;
+      const clusterId = item.props.cluster_id as number | undefined;
+      if (!src || clusterId == null) return;
+      src.getClusterExpansionZoom(clusterId, (err, zoom) => {
+        if (!err && zoom != null) attached?.easeTo({ center: item.at, zoom });
+      });
+    },
+    refresh: read,
+  };
+}

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

@@ -0,0 +1,309 @@
+// Region selection — drag a lasso, box or circle over the map and act on everything inside it.
+//
+//   const select = useFeatureSelect(map, () => ({ layers: ['bikes'], multiple: true }))
+//   const region = useRegionSelect(map, select, () => ({ layers: ['bikes'], tool: tool.value }))
+//
+// ★ THE TOOL IS THE ONLY WAY IN, by default. An earlier cut armed on a held modifier instead, and it
+// was wrong twice over: the map had already claimed the keys — ctrl-drag rotates, shift-drag
+// box-zooms — so a modifier drag fired the map's gesture and this one together; and a hidden gesture
+// with no affordance is unreachable on touch, which made the whole feature desktop-only. `modifier`
+// survives as an opt-in for a surface that wants a transient shortcut and has checked what it costs.
+//
+// ★ IT DOES NOT OWN A SELECTION. useFeatureSelect does, and this feeds it — which is the whole reason
+// the two are separate. A second set would have to be reconciled with the first on every click, and
+// the bulk-action bar would have to ask which one to believe.
+//
+// ★ TWO PASSES, AND THE FIRST IS FREE. `queryRenderedFeatures` takes a screen-space BOX, so the box
+// around the drawn path is a native query with no geometry work at all. Only then is the result
+// trimmed against the path itself, and only for a lasso — a box gesture is already its own answer, so
+// it skips the polygon test entirely.
+//
+// ★ THE TRIM IS IN SCREEN SPACE, not lng/lat. A lasso is drawn on the picture, so it should catch what
+// it visually encloses; testing in geographic space would disagree with the drawn shape the moment the
+// map is rotated or pitched.
+import { onScopeDispose, ref, shallowRef, watch, type Ref, type ShallowRef } from 'vue';
+import booleanPointInPolygon from '@turf/boolean-point-in-polygon';
+import { point } from '@turf/helpers';
+import type { Map as MapboxMap } from 'mapbox-gl';
+import type { PickedFeature } from './useFeatureSelect';
+import {
+  applyMode,
+  armsOnPlainDrag,
+  circleBounds,
+  circleFromPath,
+  inCircle,
+  pathBounds,
+  pathPolygon,
+  regionMode,
+  shapeForTool,
+  worthQuerying,
+  type RegionMode,
+  type RegionShape,
+  type RegionTool,
+  type ScreenPoint,
+} from './regionSelect';
+
+export interface RegionSelectOptions {
+  /** layers to catch features from, same ids you gave useFeatureSelect */
+  layers: string[];
+  /**
+   * Which tool the canvas is holding. `off` leaves a drag panning; `lasso` and `box` arm it, so a
+   * PLAIN drag draws a region.
+   *
+   * ★ This is what makes region selection exist on a phone. The modifier below is unreachable there,
+   * so without an armed tool the whole feature would be desktop-only — and once a plain drag can
+   * select, `off` has to be a state a reader can see and choose rather than an implied default.
+   */
+  tool?: RegionTool;
+  /**
+   * A transient shortcut: hold this and drag to draw a region without arming a tool. OFF by default,
+   * and opting in is a deliberate act because the map has already claimed most of the keyboard.
+   *
+   * ★ MEASURED AGAINST GL JS 3.24: `ctrl`+drag is dragRotate (`ctrlKey || button === RIGHT_BUTTON`)
+   * and `shift`+drag is boxZoom (`shiftKey && e.button === 0`). Either would fire the map's gesture
+   * AND this one from the same drag — and since the trim runs in screen space while the camera moves
+   * underneath it, the caught set would be wrong as well as the map spinning. `alt` is the one that
+   * is free for a drag; GL JS only reads it to slow scroll-zoom.
+   *
+   * ★ There is no `'none'`. It used to mean "no modifier required", which is what an armed `tool`
+   * means now — two spellings of one state, and the one that could be set by accident.
+   */
+  modifier?: 'meta' | 'alt' | 'shift';
+  /** A hard stop, for a read-only map. Unlike `tool: 'off'`, the modifier does not work either. */
+  disabled?: boolean;
+}
+
+/** The half of useFeatureSelect this needs. Narrow on purpose: it is a consumer, not a peer. */
+export interface RegionSelectTarget {
+  selected: Ref<Set<string | number>>;
+  set: (features: PickedFeature[]) => void;
+  add: (features: PickedFeature[]) => void;
+  subtract: (ids: Iterable<string | number>) => void;
+}
+
+export function useRegionSelect(
+  map: ShallowRef<MapboxMap | null>,
+  target: RegionSelectTarget,
+  options: () => RegionSelectOptions,
+) {
+  /** the live path, in screen px — what the overlay draws */
+  const path = shallowRef<ScreenPoint[]>([]);
+  const active = ref(false);
+
+  let mode: RegionMode = 'replace';
+  let dragging = false;
+
+  /**
+   * The shape the CURRENT gesture is drawing, fixed at pointerdown.
+   *
+   * ★ Captured rather than read live, for the same reason the modifier is: switching tool mid-drag
+   * would otherwise re-shape a gesture already in flight, so the path drawn and the path tested would
+   * stop being the same path.
+   */
+  const shape = ref<RegionShape>('lasso');
+
+  const heldModifier = (e: PointerEvent): boolean => {
+    const mod = options().modifier;
+    // Nothing configured, no transient path — the tool is the way in.
+    if (!mod) return false;
+    if (mod === 'meta') return e.metaKey || e.ctrlKey;
+    if (mod === 'alt') return e.altKey;
+    return e.shiftKey;
+  };
+
+  // An armed tool selects on a plain drag; with none armed, only the modifier does.
+  const wanted = (e: PointerEvent): boolean =>
+    armsOnPlainDrag(options().tool ?? 'off') || heldModifier(e);
+
+  function canvasPoint(m: MapboxMap, e: PointerEvent): ScreenPoint {
+    const r = m.getCanvas().getBoundingClientRect();
+    return [e.clientX - r.left, e.clientY - r.top];
+  }
+
+  /**
+   * Eat the one `click` a completed drag emits, before GL JS can turn it into a map click.
+   *
+   * ★ Capture phase on the canvas CONTAINER, which is where GL JS binds its own listener. The click's
+   * target is the canvas inside it, so a capture listener on the container runs before the container's
+   * bubble listener — which is the only window in which this can be stopped.
+   *
+   * ★ And a timer, not just `once`, because a drag that ends outside the canvas emits no click at all.
+   * Left armed, the listener would swallow the reader's NEXT genuine click instead.
+   */
+  function swallowNextClick(m: MapboxMap) {
+    const el = m.getCanvasContainer();
+    const eat = (ev: Event) => {
+      ev.stopPropagation();
+      cancel();
+    };
+    const cancel = () => {
+      clearTimeout(timer);
+      el.removeEventListener('click', eat, true);
+    };
+    let timer: ReturnType<typeof setTimeout>;
+    el.addEventListener('click', eat, true);
+    timer = setTimeout(cancel, 300);
+  }
+
+  function onDown(e: PointerEvent) {
+    const m = map.value;
+    if (!m || options().disabled || e.button !== 0 || !wanted(e)) return;
+    // ★ Read the modifiers ONCE, here. A reader who releases shift mid-drag still meant "add".
+    mode = regionMode(e);
+    shape.value = shapeForTool(options().tool ?? 'off');
+    dragging = true;
+    active.value = true;
+    path.value = [canvasPoint(m, e)];
+    // Belt and braces for the modifier path, where panning is still on between gestures.
+    m.dragPan.disable();
+    m.getCanvas().setPointerCapture?.(e.pointerId);
+    e.preventDefault();
+  }
+
+  function onMove(e: PointerEvent) {
+    const m = map.value;
+    if (!dragging || !m) return;
+    const p = canvasPoint(m, e);
+    // A lasso is everything between press and release; a box is its two corners, and a circle its
+    // centre and a point on the rim — both of which only ever need the first point and the current one.
+    path.value = shape.value === 'lasso' ? [...path.value, p] : [path.value[0], p];
+  }
+
+  function onUp(e: PointerEvent) {
+    const m = map.value;
+    if (!dragging || !m) return;
+    dragging = false;
+    active.value = false;
+    // Only hand panning back if no tool is holding it. An armed tool keeps it off between gestures.
+    if (!armsOnPlainDrag(options().tool ?? 'off')) m.dragPan.enable();
+    m.getCanvas().releasePointerCapture?.(e.pointerId);
+
+    const drawn = path.value;
+    path.value = [];
+    // ★ A circle's own path bounds are a QUARTER of it — the drag runs centre to rim, so everything
+    // left of and above the centre would never be queried.
+    const circle = shape.value === 'circle' ? circleFromPath(drawn) : null;
+    const box = circle ? circleBounds(circle.centre, circle.radius) : pathBounds(drawn);
+    // Too small to have been meant — leave the selection alone and let the click handler have it.
+    if (!worthQuerying(box)) return;
+
+    // ★ SWALLOW THE CLICK THIS DRAG IS ABOUT TO PRODUCE, or the selection is destroyed the instant it
+    // is made. A press and release on the same element fire a `click` after `pointerup`, GL JS turns
+    // that into its own map click, and useFeatureSelect's handler treats a plain click as REPLACE — so
+    // it hit-tests the point the pointer happened to stop on, finds nothing, and commits an empty set
+    // over the region's result.
+    //
+    // It is invisible in synthetic tests, which never dispatch click, and it is why the modifier path
+    // appeared to work: a ⌘-click reads as ADDITIVE to that same handler, so it left the result alone
+    // instead of wiping it.
+    swallowNextClick(m);
+
+    const caught = query(m, drawn, box, circle);
+    if (mode === 'replace') target.set(caught);
+    else if (mode === 'add') target.add(caught);
+    else target.subtract(caught.map((f) => f.id));
+  }
+
+  function query(
+    m: MapboxMap,
+    drawn: ScreenPoint[],
+    box: [ScreenPoint, ScreenPoint],
+    circle: { centre: ScreenPoint; radius: number } | null,
+  ): PickedFeature[] {
+    const layers = options().layers.filter((id) => !!m.getLayer(id));
+    if (!layers.length) return [];
+
+    const hits = m.queryRenderedFeatures([box[0], box[1]], { layers });
+    // A box needs no trim — its bounds already are the answer. A circle trims by distance, a lasso
+    // by point-in-polygon.
+    const ring = shape.value === 'lasso' ? pathPolygon(drawn) : null;
+
+    const out: PickedFeature[] = [];
+    const seen = new Set<string | number>();
+    for (const f of hits) {
+      // No source means the feature cannot be painted: setFeatureState addresses one by
+      // (source, sourceLayer?, id), so an id alone is ambiguous across sources. Skipping is right —
+      // selecting something we cannot show as selected is worse than not selecting it.
+      if (f.id == null || !f.source || seen.has(f.id)) continue;
+      const geom = f.geometry;
+      if (geom.type !== 'Point') continue;
+      const at = geom.coordinates as [number, number];
+      // Trim the box down to the drawn shape. Projecting back to screen space keeps the test in the
+      // same space the lasso was drawn in.
+      if (ring || circle) {
+        const p = m.project(at);
+        if (ring && !booleanPointInPolygon(point([p.x, p.y]), ring)) continue;
+        if (circle && !inCircle([p.x, p.y], circle.centre, circle.radius)) continue;
+      }
+      seen.add(f.id);
+      out.push({
+        id: f.id,
+        source: f.source,
+        sourceLayer: f.sourceLayer,
+        at,
+        properties: f.properties ?? {},
+      });
+    }
+    return out;
+  }
+
+  watch(
+    map,
+    (m, _old, onCleanup) => {
+      if (!m) return;
+      const el = m.getCanvasContainer();
+      el.addEventListener('pointerdown', onDown);
+      // move/up on the window: a gesture that leaves the canvas mid-drag must still finish.
+      window.addEventListener('pointermove', onMove);
+      window.addEventListener('pointerup', onUp);
+      onCleanup(() => {
+        el.removeEventListener('pointerdown', onDown);
+        window.removeEventListener('pointermove', onMove);
+        window.removeEventListener('pointerup', onUp);
+      });
+    },
+    { immediate: true },
+  );
+
+  // ★ AN ARMED TOOL HOLDS PANNING OFF FOR AS LONG AS IT IS ARMED, rather than for the duration of a
+  // drag. Disabling it inside pointerdown is a race that cannot be won: GL JS drives dragPan from
+  // `mousedown`, which a real press fires alongside `pointerdown`, and preventDefault on a pointer
+  // event does not reliably suppress the mouse event that follows it. The map panned and the region
+  // never drew — the modifier path only looked fine because ⌘-drag is not a pan to begin with.
+  //
+  // Putting the tool down is how panning comes back, which is the other half of why `off` had to be a
+  // state a reader can choose.
+  watch(
+    [map, () => armsOnPlainDrag(options().tool ?? 'off')],
+    ([m, armed]) => {
+      if (!m) return;
+      // ★ boxZoom and dragRotate stand down too, not just panning. While a tool is armed the drag
+      // belongs to it, and GL JS binds both to modifiers this control also uses: shift-drag is
+      // box-zoom and it is how a region ADDS to the selection, so leaving it on would zoom the map
+      // every time a reader extended their selection. ctrl-drag rotates, for the same collision.
+      for (const h of [m.dragPan, m.boxZoom, m.dragRotate]) {
+        if (armed) h.disable();
+        else h.enable();
+      }
+    },
+    { immediate: true },
+  );
+
+  onScopeDispose(() => {
+    window.removeEventListener('pointermove', onMove);
+    window.removeEventListener('pointerup', onUp);
+    const m = map.value;
+    if (m) for (const h of [m.dragPan, m.boxZoom, m.dragRotate]) h.enable();
+  });
+
+  return {
+    /** the path being drawn, in canvas px — hand to <FMapRegion> */
+    path,
+    /** the shape this gesture is drawing, fixed at pointerdown — hand to <FMapRegion> */
+    shape,
+    /** whether a gesture is in flight */
+    active,
+    /** how many things a bulk action would act on, straight from the selection it feeds */
+    count: target.selected,
+  };
+}

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

@@ -0,0 +1,61 @@
+// The colour-mode seam for anything that RESOLVES a token rather than referencing it.
+//
+// ★ THE ONE-MODE-BEHIND BUG, and the only reliable fix.
+//
+// A CSS variable used as `var(--ui-primary)` needs no help — the browser re-resolves it when the mode
+// class changes. But anything that reads a token's *computed value* (`getComputedStyle`, and therefore
+// `resolveMapColor`) is taking a snapshot, and the snapshot is only correct if it is taken after the
+// mode has actually landed on the document.
+//
+// A Vue watcher on an `isDark` ref does NOT satisfy that. The ref flips first and the class is written
+// to <html> after, so a watcher — or a computed that reads the ref — resolves the mode the page has
+// just LEFT. The symptom is unmistakable and is what sent people looking: the first toggle appears to
+// do nothing, the second toggle works but shows the wrong mode, and it stays one behind forever.
+//
+// So: watch the DOM, not the ref. This ticks when the class actually lands.
+//
+//   const mode = useTokenMode()
+//   const colour = computed(() => { void mode.value; return resolveMapColor('var(--ui-primary)') })
+import { onScopeDispose, shallowRef, type ShallowRef } from 'vue';
+
+/**
+ * A counter that increments whenever the resolved colour mode changes — the class or `data-theme`
+ * landing on `<html>`, or the OS preference flipping under a surface that follows it.
+ *
+ * Read it (`void mode.value`) inside any computed that calls `resolveMapColor`, or watch it to redo
+ * work that baked a token into something immutable — a rasterised sprite, a canvas, a chart's cached
+ * palette.
+ */
+export function useTokenMode(): ShallowRef<number> {
+  const tick = shallowRef(0);
+  if (typeof document === 'undefined') return tick;
+
+  const bump = () => (tick.value += 1);
+  const observer = new MutationObserver(bump);
+  observer.observe(document.documentElement, { attributeFilter: ['class', 'data-theme'] });
+  const media = window.matchMedia('(prefers-color-scheme: dark)');
+  media.addEventListener('change', bump);
+
+  onScopeDispose(() => {
+    observer.disconnect();
+    media.removeEventListener('change', bump);
+  });
+
+  return tick;
+}
+
+/**
+ * The same signal as a callback, for code that is not inside a reactive scope — `useMapOverlay` uses
+ * this to re-apply its resolved paint. Returns a disposer.
+ */
+export function onTokenModeChange(fn: () => void): () => void {
+  if (typeof document === 'undefined') return () => {};
+  const observer = new MutationObserver(fn);
+  observer.observe(document.documentElement, { attributeFilter: ['class', 'data-theme'] });
+  const media = window.matchMedia('(prefers-color-scheme: dark)');
+  media.addEventListener('change', fn);
+  return () => {
+    observer.disconnect();
+    media.removeEventListener('change', fn);
+  };
+}

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

@@ -0,0 +1,131 @@
+// The clock that reads a track.
+//
+// It owns time and nothing else: no map, no camera, no chrome. That is what lets a surface drive other
+// layers from the same `at` — a global time cursor stays a composition rather than a rewrite — and what
+// lets the arithmetic live in track.ts, where a node test can reach it.
+import { computed, onScopeDispose, shallowRef, watch } from 'vue';
+import {
+  advance,
+  fitSpeed,
+  positionAt,
+  progressAt,
+  trackSpan,
+  type Track,
+  type TrackPoint,
+  type TrackSpan,
+} from './track';
+
+export interface TrackPlaybackOptions {
+  track: Track;
+  /** a multiplier, or `fit` to play the whole track in `fitSeconds`. Default `fit` */
+  speed?: number | 'fit';
+  /** how long a `fit` playback takes, whatever the trip's real duration. Default 30 */
+  fitSeconds?: number;
+  maxGapMs?: number;
+}
+
+export function useTrackPlayback(options: () => TrackPlaybackOptions) {
+  const span = computed<TrackSpan>(() => trackSpan(options().track));
+  const at = shallowRef(span.value.start);
+  const playing = shallowRef(false);
+
+  /**
+   * ★ `fit` is the default. A 22-minute rental at 1× is not something anyone watches, and a control
+   * whose default setting nobody uses is a control that opens wrong every time.
+   */
+  const speed = computed(() => {
+    const o = options();
+    return o.speed === undefined || o.speed === 'fit' ? fitSpeed(span.value, o.fitSeconds ?? 30) : o.speed;
+  });
+
+  /**
+   * What was ASKED FOR, as opposed to what it resolved to.
+   *
+   * ★ A control must show this one. `fit` on a 50-minute trip resolves to about 101×, and a speed menu
+   * offering 1/2/4/8 with 101.4 selected shows a value that is in no list and means nothing to a
+   * reader — the setting is `fit`, and that is the word for it.
+   */
+  const mode = computed<number | 'fit'>(() => {
+    const o = options();
+    return o.speed === undefined ? 'fit' : o.speed;
+  });
+
+  const position = computed<TrackPoint | null>(() =>
+    positionAt(options().track, at.value, options().maxGapMs),
+  );
+  const progress = computed(() => progressAt(options().track, at.value));
+
+  let raf = 0;
+  let last = 0;
+
+  function frame(now: number) {
+    const next = advance(at.value, now - last, speed.value, span.value);
+    last = now;
+    at.value = next;
+    if (next >= span.value.end) {
+      playing.value = false;
+      raf = 0;
+      return;
+    }
+    raf = requestAnimationFrame(frame);
+  }
+
+  function play() {
+    // A composable that runs during SSR must not reach for rAF, and a track with no duration has
+    // nothing to play.
+    if (playing.value || !span.value.ms || typeof requestAnimationFrame === 'undefined') return;
+    // Pressing play at the end restarts, which is what the button looks like it should do.
+    if (at.value >= span.value.end) at.value = span.value.start;
+    playing.value = true;
+    last = performance.now();
+    raf = requestAnimationFrame(frame);
+  }
+
+  function pause() {
+    playing.value = false;
+    if (raf) cancelAnimationFrame(raf);
+    raf = 0;
+  }
+
+  /** Seeking mid-playback keeps playing: the operator is moving the playhead, not stopping the clock. */
+  function seek(t: number) {
+    const s = span.value;
+    at.value = Math.min(Math.max(t, s.start), s.end);
+    // Without this, the next frame's delta covers the time spent dragging and the playhead lurches.
+    last = typeof performance === 'undefined' ? 0 : performance.now();
+  }
+
+  const seekProgress = (p: number) =>
+    seek(span.value.start + Math.min(1, Math.max(0, p)) * span.value.ms);
+
+  // A new track is a new clock. Without this the playhead keeps a timestamp from a trip nobody is
+  // looking at any more, and the scrubber opens at a position that means nothing.
+  watch(span, (s) => {
+    pause();
+    at.value = s.start;
+  });
+
+  onScopeDispose(pause);
+
+  return {
+    /** epoch ms of the playhead */
+    at,
+    playing,
+    /** 0–1, linear in TIME — a four-minute halt occupies four minutes of the scrubber */
+    progress,
+    /** where the entity is at `at`, or null for an empty track */
+    position,
+    span,
+    /** the resolved multiplier the clock actually advances by */
+    speed,
+    /** the SETTING — `fit`, or the multiplier that was asked for. This is what a control shows */
+    mode,
+    play,
+    pause,
+    toggle: () => (playing.value ? pause() : play()),
+    seek,
+    seekProgress,
+  };
+}
+
+export type TrackPlayback = ReturnType<typeof useTrackPlayback>;