leaflet-city-mapper 0.0.0-stage → 0.0.2

package/src/utils/traffic.js

@@ -0,0 +1,315 @@
+import * as createMeshApi from './createMesh.js';
+import * as disposeMesh from './disposeMesh.js';
+import * as setHighlight from './setHighlight.js';
+import * as showFeature from './showFeature.js';
+import { update as updateScene } from './update.js';
+import { along } from './along.js';
+import { build } from './build.js';
+import { computeBounds } from './computeBounds.js';
+import { routeGeometry } from './routeGeometry.js';
+import { toLanes } from './toLanes.js';
+import { tripsAt } from './tripsAt.js';
+import { underEntry } from './underEntry.js';
+import { getElevation } from './getElevation.js';
+
+export function trafficNow(state) {
+  let control = { live: true };
+  state.layer._map?.eachLayer(other => { if (other.control?.time) control = other.control; });
+  return { live: control.live, time: control.live ? new Date() : control.time };
+}
+
+export function createTrafficMesh(state, data, featureFaces, material, usage = 0) {
+  const result = createMeshApi.createMesh(state.layer, data, material, usage);
+  result.extras.featureFaces = featureFaces;
+  return result;
+}
+
+export function disposeTrafficObject(state, object) {
+  if (!object) return;
+  if (state.layer.highlightedFeature?.mesh === object) {
+    setHighlight.setHighlight(state.layer, null);
+    state.layer.hoveredFeature = null;
+    showFeature.showFeature(state.layer, null);
+  };
+  disposeMesh.disposeMesh(state.layer, object);
+}
+
+export function failTraffic(state, error) {
+  state.status.textContent = `Error: ${error.message}`;
+  state.status.setAttribute('role', 'alert');
+  console.error('Traffic layer', error);
+}
+
+export function groundTraffic(state) {
+  const { layer, lanes } = state;
+  const terrain = layer._map._terrain3D?._terrainReady && layer._map._terrain3D, base = layer.root.position[1];
+  for (const lane of lanes) lane.points.forEach((point, i) => {
+    const elevation = terrain && (lane.elevation ?? getElevation(terrain, lane.latlngs[i]));
+    point[2] = Number.isFinite(elevation) && Number.isFinite(base) ? elevation - base : 0;
+  });
+  state.lanesDirty = true;
+  state.nextCheck = -Infinity;
+}
+
+export function prepareTraffic(state) {
+  const { layer, lanes } = state;
+  const crs = layer._map.options.crs, origin = crs.project(layer.location);
+  const metres = Math.cos(layer.location.lat * Math.PI / 180);
+  for (const lane of lanes) {
+    lane.points = lane.latlngs.map(([lat, lng]) => {
+      const point = crs.project(new L.LatLng(lat, lng));
+      return [(point.x - origin.x) * metres, -(point.y - origin.y) * metres, 0];
+    });
+    lane.lengths = [0];
+    for (let i = 1; i < lane.points.length; i++) {
+      lane.lengths.push(lane.lengths[i - 1] + Math.hypot(lane.points[i][0] - lane.points[i - 1][0], lane.points[i][1] - lane.points[i - 1][1]));
+    }
+    lane.length = lane.lengths.at(-1);
+  }
+  groundTraffic(state);
+  disposeTrafficObject(state, state.route);
+  state.route = null;
+  state.tripsKey = null;
+}
+
+export function drawTrafficRoute(state) {
+  state.route = createTrafficMesh(state, routeGeometry(state.lanes), [], { emissive: [0.03, 0.25, 0.3] });
+}
+
+export function rebuildTrafficMesh(state) {
+  const { trips, model, vertices } = state;
+  disposeTrafficObject(state, state.mesh);
+  state.mesh = null;
+  if (!trips.length) return;
+  const color = trips.flatMap((trip, i) => build(model(i)).color), count = color.length / 3;
+  state.mesh = createTrafficMesh(state, { position: color.map(() => 0), normal: color.map(() => 0), color },
+    trips.map((trip, i) => ({
+      id: trip.id, properties: trip.properties, faceStart: i * vertices / 3, faceEnd: (i + 1) * vertices / 3,
+      vertexStart: i * vertices, vertexEnd: (i + 1) * vertices
+    })), {}, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC);
+  state.mesh.geometry.drawRange.count = count;
+  trafficBounds(state);
+}
+
+export function trafficBounds(state) {
+  const extent = { attributes: { position: { data: state.lanes.flatMap(lane => lane.points.flatMap(([x, z, y]) => [x - 20, y, z - 20, x + 20, y + 5, z + 20])) } } };
+  computeBounds(extent);
+  state.mesh.geometry.bounds = extent.bounds;
+}
+
+export function destroyTrafficGpu(state) {
+  for (const buffer of [state.gpu?.params, state.gpu?.template, state.gpu?.points, state.gpu?.vehicles]) buffer?.destroy();
+  state.gpu = null;
+}
+
+export function trafficStorage(device, data) {
+  const buffer = device.createBuffer({ size: Math.max(16, data.byteLength), usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+  device.queue.writeBuffer(buffer, 0, data);
+  return buffer;
+}
+
+export function rebaseTraffic(state) {
+  const { device } = state.layer.renderer;
+  if (state.gpu?.device !== device) {
+    destroyTrafficGpu(state);
+    state.gpu = {
+      device,
+      pipeline: device.createComputePipeline({ layout: 'auto', compute: { module: device.createShaderModule({ code: state.shader }), entryPoint: 'main' } }),
+      params: device.createBuffer({ size: 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST }),
+      template: trafficStorage(device, new Float32Array([...state.template.position, ...state.template.normal])),
+    };
+    state.lanesDirty = true;
+  }
+  if (state.lanesDirty) {
+    const data = new Float32Array(state.lanes.reduce((count, lane) => count + lane.points.length, 0) * 4);
+    let offset = 0;
+    for (const lane of state.lanes) {
+      lane.start = offset / 4;
+      lane.points.forEach((point, i) => { data.set([point[0], point[1], point[2], lane.lengths[i]], offset); offset += 4; });
+    }
+    state.gpu.points?.destroy();
+    state.gpu.points = trafficStorage(device, data);
+    state.lanesDirty = false;
+  }
+  const data = new Float32Array(state.trips.length * 4), index = new Uint32Array(data.buffer);
+  state.trips.forEach((trip, i) => {
+    index[i * 4] = trip.lane.start;
+    index[i * 4 + 1] = trip.lane.points.length;
+    data[i * 4 + 2] = trip.distance;
+    data[i * 4 + 3] = trip.speed;
+    state.mesh.extras.featureFaces[i].properties = trip.properties;
+  });
+  if (state.gpu.vehicles?.size >= data.byteLength) device.queue.writeBuffer(state.gpu.vehicles, 0, data);
+  else {
+    state.gpu.vehicles?.destroy();
+    state.gpu.vehicles = trafficStorage(device, data);
+  }
+  const { position, normal } = state.mesh.geometry.attributes;
+  state.gpu.bindGroup = device.createBindGroup({
+    layout: state.gpu.pipeline.getBindGroupLayout(0),
+    entries: [state.gpu.params, state.gpu.template, state.gpu.points, state.gpu.vehicles, position.buffer, normal.buffer]
+      .map((buffer, binding) => ({ binding, resource: { buffer } })),
+  });
+}
+
+export function moveTraffic(state, seconds) {
+  const { device } = state.gpu;
+  state.paramFloats[0] = state.elapsed = seconds;
+  state.paramFloats[1] = state.side;
+  state.paramInts[2] = state.vertices;
+  state.paramInts[3] = state.trips.length * state.vertices;
+  device.queue.writeBuffer(state.gpu.params, 0, state.params);
+  const encoder = device.createCommandEncoder(), pass = encoder.beginComputePass();
+  pass.setPipeline(state.gpu.pipeline);
+  pass.setBindGroup(0, state.gpu.bindGroup);
+  pass.dispatchWorkgroups(Math.ceil(state.paramInts[3] / 64));
+  pass.end();
+  device.queue.submit([encoder.finish()]);
+  state.stale = true;
+}
+
+export function locateTraffic(state, trip) {
+  const { points, lengths, length } = trip.lane;
+  let distance = trip.distance + state.elapsed * trip.speed;
+  distance -= length * Math.floor(distance / length);
+  const { x, y, z, dx, dz } = along(points, lengths, distance);
+  return { x: x - dz * state.side, y, z: z + dx * state.side, dx, dz };
+}
+
+export function placeTraffic(state) {
+  if (!state.mesh || !state.stale) return;
+  state.stale = false;
+  const { position, normal } = state.mesh.geometry.attributes;
+  state.trips.forEach((trip, i) => {
+    const { x: cx, y, z: cz, dx, dz } = locateTraffic(state, trip);
+    for (let k = 0, o = i * state.stride; k < state.stride; k += 3, o += 3) {
+      const lx = state.template.position[k], lz = state.template.position[k + 2], nx = state.template.normal[k], nz = state.template.normal[k + 2];
+      position.data[o] = cx - lx * dz - lz * dx;
+      position.data[o + 1] = y + state.template.position[k + 1];
+      position.data[o + 2] = cz + lx * dx - lz * dz;
+      normal.data[o] = -nx * dz - nz * dx;
+      normal.data[o + 1] = state.template.normal[k + 1];
+      normal.data[o + 2] = nx * dx - nz * dz;
+    }
+  });
+}
+
+export function tickTraffic(state) {
+  state.frame = undefined;
+  if (!state.ready || !state.layer._map) return;
+  if (!state.layer.renderer) { state.frame = requestAnimationFrame(state.tick); return; }
+  if (state.mesh && !(state.mesh.geometry.attributes.position.buffer.usage & GPUBufferUsage.STORAGE)) {
+    state.tripsKey = null;
+    state.nextCheck = -Infinity;
+  }
+  const { live, time } = trafficNow(state), ms = time?.getTime(), valid = Number.isFinite(ms);
+  let changed = false;
+  if (!live || !valid || !(ms >= state.rebasedAt && ms < state.nextCheck)) {
+    let text;
+    try {
+      state.trips = valid ? tripsAt(time, state.lanes, state.velocity) : [];
+      text = !valid ? 'Select a valid simulation date' : !state.loaded ? 'Loading…' :
+        `${state.trips.length} vehicle${state.trips.length === 1 ? '' : 's'}${state.loaded.note ? ` · ${state.loaded.note}` : ''}`;
+    } catch (error) { return failTraffic(state, error); }
+    state.rebasedAt = ms;
+    state.nextCheck = ms + 1000;
+    const key = state.trips.map(trip => trip.id).join();
+    changed = key !== state.tripsKey || (state.outline && !state.route && state.lanes.length);
+    if (state.outline && !state.route && state.lanes.length) drawTrafficRoute(state);
+    if (key !== state.tripsKey) { rebuildTrafficMesh(state); state.tripsKey = key; }
+    if (state.mesh) rebaseTraffic(state);
+    if (state.status.textContent !== text) state.status.textContent = text;
+    state.status.removeAttribute('role');
+  }
+  if (state.mesh) moveTraffic(state, (ms - state.rebasedAt) / 1000);
+  if (state.mesh && state.lights && (!live || !(performance.now() - state.litAt < 100))) {
+    state.litAt = performance.now();
+    state.mesh.extras.lights = state.trips.flatMap(trip => {
+      const { x, y, z, dx, dz } = locateTraffic(state, trip);
+      return state.lights.map(({ position: [lx, ly, lz], ...light }) => ({ ...light, position: [x - lx * dz - lz * dx, y + ly, z + lx * dx - lz * dz] }));
+    });
+  }
+  if (state.mesh || changed) updateScene(state.layer);
+  if (live && valid) state.frame = requestAnimationFrame(state.tick);
+}
+
+export async function fetchTrafficLanes(state, time, signal) {
+  const href = new URL(state.url, document.baseURI).href;
+  if (/\.m?js(?:[?#]|$)/i.test(state.url)) return (await import(href)).default(time, state.layer, signal);
+  if (!state.file) {
+    const response = await fetch(href, { signal });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    state.file = await response.json();
+  }
+  return state.file;
+}
+
+export function loadedTrafficLanes(state, signal, data) {
+  if (signal.aborted || !state.layer._map || data === state.loaded) return;
+  state.loaded = data;
+  state.lanes = toLanes(data);
+  prepareTraffic(state);
+  if (!state.frame) state.tick();
+}
+
+export function failedTrafficLoad(state, error) {
+  if (error.name !== 'AbortError') failTraffic(state, error);
+}
+
+export function loadTraffic(state) {
+  const { time } = trafficNow(state);
+  if (!Number.isFinite(time?.getTime())) return;
+  state.request?.abort();
+  const { signal } = state.request = new AbortController();
+  fetchTrafficLanes(state, time, signal).then(
+    loadedTrafficLanes.bind(null, state, signal),
+    failedTrafficLoad.bind(null, state),
+  );
+}
+
+export function updateTraffic(state, event) {
+  if (event?.layer === state.layer) return;
+  cancelAnimationFrame(state.frame);
+  loadTraffic(state);
+  state.tick();
+}
+
+export function updateTrafficTerrain(state) {
+  if (!state.lanes.length) return;
+  groundTraffic(state);
+  disposeTrafficObject(state, state.route);
+  state.route = null;
+  if (state.mesh) trafficBounds(state);
+  if (!state.frame) state.tick();
+}
+
+export function startTraffic(state) {
+  state.layer._map.off('simulationtimechange layerremove', state.update).on('simulationtimechange layerremove', state.update);
+  state.layer._map.off('terrainchange', state.terrain).on('terrainchange', state.terrain);
+  underEntry(state.layer, state.status);
+  state.update();
+}
+
+export function readyTraffic(state) {
+  state.ready = true;
+  if (state.layer._map) startTraffic(state);
+}
+
+export function addTraffic(state) {
+  if (state.ready) startTraffic(state);
+}
+
+export function removeTraffic(state) {
+  state.request?.abort();
+  cancelAnimationFrame(state.frame);
+  state.frame = undefined;
+  state.layer._map.off('simulationtimechange layerremove', state.update).off('terrainchange', state.terrain);
+  disposeTrafficObject(state, state.mesh);
+  disposeTrafficObject(state, state.route);
+  state.mesh = state.route = null;
+  delete state.layer._beforeRaycast;
+  destroyTrafficGpu(state);
+  state.lanes = [];
+  state.trips = [];
+  state.tripsKey = state.loaded = null;
+}

package/src/utils/traverse.js

@@ -0,0 +1,6 @@
+/** Depth-first walk; a truthy callback result skips that node's descendants. */
+
+export function traverse(node, callback) {
+  if (callback(node)) return;
+  for (const child of node.children) traverse(child, callback);
+}

package/src/utils/treeGeometry.js

@@ -0,0 +1,45 @@
+import { parseColor } from "./parseColor.js";
+
+/** Low-poly tree, sharing the source block's buffers, picking and terrain offset. */
+
+export function treeGeometry(point, style, addTriangle) {
+  const { top, bottom = 0, trunkRadius, crownRadius, crownBottom, crownShape = 'round' } = style;
+  if (![trunkRadius, crownRadius, crownBottom].every(Number.isFinite) ||
+    trunkRadius <= 0 || crownRadius < trunkRadius || crownBottom <= bottom || crownBottom >= top ||
+    !['round', 'cone'].includes(crownShape)) {
+    throw new Error('Invalid tree dimensions or crown shape');
+  }
+  const trunk = parseColor(style.trunkColor ?? 0x72513a);
+  const crown = parseColor(style.color ?? 0x4f823b);
+  const ring = radius => Array.from({ length: 8 }, (_, i) => ({
+    x: point.x + Math.cos(i * Math.PI / 4) * radius,
+    y: point.y + Math.sin(i * Math.PI / 4) * radius,
+    ground: point.ground,
+  }));
+  const surface = (lowRadius, low, highRadius, high, color) => {
+    const lower = ring(lowRadius), upper = ring(highRadius);
+    for (let i = 0; i < 8; i++) {
+      const next = (i + 1) % 8;
+      const angle = (i + 0.5) * Math.PI / 4;
+      const slope = (lowRadius - highRadius) / (high - low);
+      const length = Math.hypot(1, slope);
+      const nx = Math.cos(angle) / length, ny = slope / length, nz = -Math.sin(angle) / length;
+      if (lowRadius) addTriangle(lower[i], low, lower[next], low, upper[next], high, nx, ny, nz, color);
+      if (highRadius) addTriangle(lower[i], low, upper[next], high, upper[i], high, nx, ny, nz, color);
+    }
+  };
+  surface(trunkRadius, bottom, trunkRadius, crownBottom + (top - crownBottom) * 0.25, trunk);
+  if (crownShape === 'cone') {
+    const base = ring(crownRadius);
+    for (let i = 0; i < 8; i++) addTriangle(point, crownBottom, base[i], crownBottom,
+      base[(i + 1) % 8], crownBottom, 0, -1, 0, crown);
+    surface(crownRadius, crownBottom, 0, top, crown);
+  } else {
+    const profile = [[0, 0], [0.35, 0.8], [0.6, 1], [0.85, 0.7], [1, 0]];
+    for (let i = 1; i < profile.length; i++) {
+      const [low, lr] = profile[i - 1], [high, hr] = profile[i];
+      surface(lr * crownRadius, crownBottom + low * (top - crownBottom),
+        hr * crownRadius, crownBottom + high * (top - crownBottom), crown);
+    }
+  }
+}

package/src/utils/triangulate.js

@@ -0,0 +1,100 @@
+import { isClockWise } from "./isClockWise.js";
+
+/**
+ * Triangulates a polygon given as `{x, y}` points.
+ * Rings omit the repeated closing point; winding is normalized internally.
+ * Vertex indices remain relative to the original inputs after duplicate/collinear
+ * cleanup. Hole bridges duplicate endpoints, not source vertices.
+ * @param {Object[]} contour Outer boundary.
+ * @param {Object[][]} [holes] Interior boundaries.
+ *
+ * @returns {number[][]} Triangles as indices in `[...contour, ...holes.flat()]`.
+ */
+
+export function triangulate(contour, holes = []) {
+  const points = [contour, ...holes].flat();
+  if (points.some(p => !Number.isFinite(p.x) || !Number.isFinite(p.y))) throw new Error('Invalid polygon coordinates');
+  // Translate near the origin to avoid cancellation with geographic coordinates.
+  const vertices = points.map((p, index) => ({ x: p.x - contour[0].x, y: p.y - contour[0].y, index }));
+  const cross = (a, b, c) => (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
+  const equal = (a, b) => a.x === b.x && a.y === b.y;
+  // Remove zero-area corners before connecting holes; keep original vertex indices.
+  const clean = ring => {
+    let changed = true;
+    while (changed && ring.length > 3) {
+      changed = false;
+      for (let i = 0; i < ring.length; i++) {
+        const a = ring[(i + ring.length - 1) % ring.length], b = ring[i], c = ring[(i + 1) % ring.length];
+        if (equal(a, b) || Math.abs(cross(a, b, c)) < 1e-10) {
+          ring.splice(i, 1); changed = true; break;
+        }
+      }
+    }
+    if (ring.length < 3) throw new Error('Degenerate polygon ring');
+    return ring;
+  };
+  let offset = 0;
+  const rings = [contour, ...holes].map((path, index) => {
+    const ring = clean(vertices.slice(offset, offset += path.length));
+    if (isClockWise(ring) !== Boolean(index)) ring.reverse();
+    return ring;
+  });
+  const inside = (point, ring) => {
+    let result = false;
+    for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+      const a = ring[i], b = ring[j];
+      if ((a.y > point.y) !== (b.y > point.y) &&
+        point.x < (b.x - a.x) * (point.y - a.y) / (b.y - a.y) + a.x) result = !result;
+    }
+    return result;
+  };
+  const intersects = (a, b, c, d) => {
+    if (equal(a, c) || equal(a, d) || equal(b, c) || equal(b, d)) return false;
+    const abC = cross(a, b, c), abD = cross(a, b, d), cdA = cross(c, d, a), cdB = cross(c, d, b);
+    const on = (p, q, r) => Math.min(p.x, q.x) <= r.x && r.x <= Math.max(p.x, q.x) &&
+      Math.min(p.y, q.y) <= r.y && r.y <= Math.max(p.y, q.y);
+    return abC * abD < 0 && cdA * cdB < 0 ||
+      abC === 0 && on(a, b, c) || abD === 0 && on(a, b, d) ||
+      cdA === 0 && on(c, d, a) || cdB === 0 && on(c, d, b);
+  };
+  let polygon = rings[0].slice();
+  // A bridge must stay inside the outer boundary, outside every hole, and cross no edge.
+  // ponytail: quadratic ear clipping for building footprints; use spatial indexing for large rings.
+  for (const hole of rings.slice(1).sort((a, b) => Math.min(...a.map(p => p.x)) - Math.min(...b.map(p => p.x)))) {
+    let bridge, distance = Infinity;
+    for (let h = 0; h < hole.length; h++) for (let p = 0; p < polygon.length; p++) {
+      const a = hole[h], b = polygon[p], d = (a.x - b.x) ** 2 + (a.y - b.y) ** 2;
+      if (d >= distance) continue;
+      const mid = { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 };
+      if (!inside(mid, rings[0]) || rings.slice(1).some(r => inside(mid, r))) continue;
+      if ([polygon, ...rings.slice(1)].some(r => r.some((c, i) => intersects(a, b, c, r[(i + 1) % r.length])))) continue;
+      bridge = [h, p]; distance = d;
+    }
+    if (!bridge) throw new Error('Unable to connect polygon hole');
+    const [h, p] = bridge;
+    polygon = [...polygon.slice(0, p + 1), ...hole.slice(h), ...hole.slice(0, h + 1),
+    polygon[p], ...polygon.slice(p + 1)];
+  }
+  // Clip a convex corner only when no other vertex is inside/on its triangle.
+  const result = [];
+  while (polygon.length > 3) {
+    let clipped = false;
+    for (let i = 0; i < polygon.length; i++) {
+      const a = polygon[(i + polygon.length - 1) % polygon.length], b = polygon[i], c = polygon[(i + 1) % polygon.length];
+      if (cross(a, b, c) <= 1e-10) continue;
+      if (polygon.some(p => !equal(p, a) && !equal(p, b) && !equal(p, c) &&
+        cross(a, b, p) >= 0 && cross(b, c, p) >= 0 && cross(c, a, p) >= 0)) continue;
+      result.push([a.index, b.index, c.index]); polygon.splice(i, 1); clipped = true; break;
+    }
+    if (!clipped) throw new Error('Unable to triangulate polygon: invalid or self-intersecting rings');
+  }
+  if (cross(...polygon) > 1e-10) result.push(polygon.map(p => p.index));
+  const area = ring => Math.abs(ring.reduce((sum, p, i) => {
+    const q = ring[(i + 1) % ring.length]; return sum + p.x * q.y - q.x * p.y;
+  }, 0)) / 2;
+  // Reject incomplete coverage instead of silently emitting a partial roof.
+  const expected = area(rings[0]) - rings.slice(1).reduce((sum, ring) => sum + area(ring), 0);
+  const actual = result.reduce((sum, triangle) => sum + cross(...triangle.map(i => vertices[i])) / 2, 0);
+  if (expected <= 0 || Math.abs(actual - expected) > Math.max(1e-7, expected * 1e-8)) throw new Error('Polygon triangulation area mismatch');
+  return result;
+}

package/src/utils/tripsAt.js

@@ -0,0 +1,16 @@
+import { vehicleOffsets } from "./vehicleOffsets.js";
+import { scheduledTrips } from "./scheduledTrips.js";
+
+// A lane with a `timetable` runs scheduled trips end to end; one with a `flow` (vehicles/h) loops evenly spaced vehicles.
+
+export const tripsAt = (time, lanes, velocity) => lanes.flatMap((lane, l) => {
+  const { timetable, flow = 0 } = lane.properties;
+  if (!lane.length) return [];
+  if (timetable) return scheduledTrips(time, timetable).map(trip => ({
+    id: `${l}-${trip.id}`, lane, distance: trip.progress * lane.length, speed: lane.length / (timetable.duration * 60),
+    properties: { ...lane.properties, departure: trip.departure },
+  }));
+  const travelled = time / 1000 * velocity;
+  return (lane.offsets ||= vehicleOffsets(lane.length, flow, velocity))
+    .map((offset, k) => ({ id: `${l}-${k}`, lane, distance: (offset + travelled) % lane.length, speed: velocity, properties: lane.properties }));
+});

package/src/utils/types.js

@@ -0,0 +1,8 @@
+export const types = {
+  5120: Int8Array,
+  5121: Uint8Array,
+  5122: Int16Array,
+  5123: Uint16Array,
+  5125: Uint32Array,
+  5126: Float32Array,
+};

package/src/utils/underEntry.js

@@ -0,0 +1,17 @@
+/**
+ * Keeps `element` right under `layer`'s entry in the map's layers control while the layer is on the map.
+ * Returns false when no layers control lists the layer.
+ */
+export function underEntry(layer, element) {
+  const map = layer._map;
+  const place = () => {
+    const input = [...map.getContainer().querySelectorAll('.leaflet-control-layers-selector')].find(input => input.layerId === L.Util.stamp(layer));
+    input?.closest('label').after(element);
+    return Boolean(input);
+  };
+  // Leaflet rebuilds the list after 'layeradd'/'layerremove' (on the layer's own 'add'/'remove'): re-place afterwards.
+  const replace = () => queueMicrotask(() => map.hasLayer(layer) && place());
+  map.on('layeradd layerremove', replace);
+  layer.once('remove', () => { map.off('layeradd layerremove', replace); element.remove(); });
+  return place();
+}

package/src/utils/update.js

@@ -0,0 +1,18 @@
+import { render } from "./render.js";
+
+/** Scene graph, shared camera and frame rendering. */
+/** Content changes: render once on the next animation frame. */
+
+export function update(backend) {
+  const shared = backend._shared;
+  if (!shared) return backend;
+  if (shared !== backend) {
+    update(shared);
+    return backend;
+  }
+  backend._frame ||= requestAnimationFrame(() => {
+    backend._frame = null;
+    if (backend._shared === backend && backend.renderer) render(backend);
+  });
+  return backend;
+}

package/src/utils/updateArea.js

@@ -0,0 +1,40 @@
+import { pump } from "./pump.js";
+import { releaseArea } from "./releaseArea.js";
+
+/** Cover the visible ground bounds and one bordering block, clipped to the archive. */
+
+export function updateArea(backend) {
+  if (!backend._map || !backend._shared) return;
+  if (backend._geojson) {
+    if (!backend._areas.has('geojson')) {
+      backend._areas.set('geojson', { request: new AbortController() });
+    }
+    pump(backend);
+    return;
+  }
+  if (!backend.header) return;
+  const z = backend.header.minZoom;
+  const center = backend._map.project(backend._map.getCenter(), z).divideBy(256).floor();
+  const bounds = backend._map.getBounds();
+  const nw = backend._map.project(bounds.getNorthWest(), z).divideBy(256).floor();
+  const se = backend._map.project(bounds.getSouthEast(), z).divideBy(256).floor();
+  const archiveNW = backend._map.project([backend.header.maxLat, backend.header.minLon], z).divideBy(256).floor();
+  const archiveSE = backend._map.project([backend.header.minLat, backend.header.maxLon], z).divideBy(256).floor();
+  const wanted = new Map();
+  for (let x = Math.max(0, nw.x - 1, archiveNW.x); x <= Math.min(2 ** z - 1, se.x + 1, archiveSE.x); x++) {
+    for (let y = Math.max(0, nw.y - 1, archiveNW.y); y <= Math.min(2 ** z - 1, se.y + 1, archiveSE.y); y++) {
+      wanted.set(`${x}/${y}`, { z, x, y });
+    }
+  }
+  for (const [key, area] of backend._areas) {
+    if (!wanted.has(key)) {
+      releaseArea(backend, area);
+      backend._areas.delete(key);
+    }
+  }
+  // Load the nearest new blocks first without rebuilding retained geometry.
+  for (const [key, coords] of [...wanted].sort(([, a], [, b]) => Math.hypot(a.x - center.x, a.y - center.y) - Math.hypot(b.x - center.x, b.y - center.y))) {
+    if (!backend._areas.has(key)) backend._areas.set(key, { coords, request: new AbortController() });
+  }
+  pump(backend);
+}

package/src/utils/updateCamera.js

@@ -0,0 +1,32 @@
+/** Orthonormal view basis plus perspective matrices, refreshed before projecting/drawing. */
+
+const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+
+export function updateCamera(camera) {
+  const z = camera.position.map((v, i) => v - camera.target[i]);
+  const zLength = Math.hypot(...z) || 1;
+  for (let i = 0; i < 3; i++) {
+    z[i] /= zLength;
+  }
+  const x = cross(camera.up, z), xLength = Math.hypot(...x) || 1;
+  for (let i = 0; i < 3; i++) {
+    x[i] /= xLength;
+  }
+  const y = cross(z, x);
+  const view = new DOMMatrix([x[0], x[1], x[2], 0, y[0], y[1], y[2], 0, z[0], z[1], z[2], 0, ...camera.position, 1]).inverse().toFloat64Array();
+  if (![...view].every(Number.isFinite)) {
+    throw new Error('Singular 3D transform');
+  }
+  for (let i = 0; i < 16; i++) {
+    camera.viewMatrix[i] = view[i];
+  }
+  const f = 1 / Math.tan(camera.fov * Math.PI / 360), n = camera.near, r = camera.far;
+  const projection = [f / camera.aspect, 0, 0, 0, 0, f, 0, 0, 0, 0, r / (n - r), -1, 0, 0, r * n / (n - r), 0];
+  for (let i = 0; i < 16; i++) {
+    camera.projectionMatrix[i] = projection[i];
+  }
+  const projectionView = new DOMMatrix(camera.projectionMatrix).multiply(new DOMMatrix(camera.viewMatrix)).toFloat64Array();
+  for (let i = 0; i < 16; i++) {
+    camera.projectionViewMatrix[i] = projectionView[i];
+  }
+}

package/src/utils/updatePointLights.js

@@ -0,0 +1,38 @@
+import { lightGrid } from './lightGrid.js';
+import { traverse } from './traverse.js';
+import { worldLights } from './worldLights.js';
+import { destroyTexture } from './destroyTexture.js';
+import { bindSunlight } from './bindSunlight.js';
+
+/** A cached spatial grid limits fragment lighting to nearby lamps, without dropping dense cells. */
+
+export function updatePointLights(backend) {
+  const { device, sunlight: sun } = backend.renderer;
+  const meshes = [];
+  for (const layer of backend._layers) {
+    if (!layer.options.nightLight || !layer.root.visible) continue;
+    traverse(layer.root, mesh => {
+      if (!mesh.visible) return true;
+      if (mesh.extras?.lights) meshes.push(mesh);
+    });
+  }
+  if (sun.lightMeshes?.length === meshes.length && meshes.every((mesh, i) => sun.lightMeshes[i].mesh === mesh &&
+    sun.lightMeshes[i].lights === mesh.extras.lights && mesh.worldMatrix.every((v, j) => v === sun.lightMeshes[i].matrix[j]))) return;
+  // Per mesh, world-space [x, y, z, radius, r, g, b, intensity] per light: re-packed only when its lights or matrix change.
+  const packed = meshes.map(mesh => {
+    const cache = mesh._worldLights, m = mesh.worldMatrix, lights = mesh.extras.lights;
+    if (cache?.lights === lights && m.every((v, j) => v === cache.matrix[j])) return cache.data;
+    const values = worldLights(lights, m);
+    mesh._worldLights = { lights, matrix: [...m], data: values };
+    return values;
+  });
+  const { data, count } = lightGrid(packed, device.limits.maxStorageBufferBindingSize);
+  if (sun.lights.size < data.byteLength) {
+    destroyTexture(backend, sun.lights);
+    sun.lights = device.createBuffer({ size: data.byteLength, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+    bindSunlight(backend);
+  }
+  device.queue.writeBuffer(sun.lights, 0, data);
+  sun.lightCount = count;
+  sun.lightMeshes = meshes.map(mesh => ({ mesh, lights: mesh.extras.lights, matrix: [...mesh.worldMatrix] }));
+}