@volter/twin-googlemaps 0.1.0

package/src/googlemaps-twin.ts

@@ -0,0 +1,1110 @@
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { authenticate, header } from './googlemaps-auth.ts';
+import {
+  allPlaces,
+  countryOf,
+  decodePageToken,
+  deterministicDuration,
+  deterministicElevation,
+  deterministicLatLng,
+  deterministicTimeZone,
+  distanceText,
+  durationText,
+  encodePageToken,
+  encodePolyline,
+  findPlaceById,
+  findPlaceByLatLng,
+  findPlaceByText,
+  geocodeResultFromPlace,
+  haversineMeters,
+  isZeroResultsQuery,
+  localityOf,
+  localizeFormattedAddress,
+  normalizeAddress,
+  openingHoursFor,
+  plusCodeFor,
+  reviewsFor,
+  stableHash,
+  synthGeocodeResult,
+  viewportAround,
+  type CannedPlace,
+} from './googlemaps-data.ts';
+import type { GeocodeResult, GoogleMapsRequest, GoogleMapsResponse, LatLng, MapsStatus } from './googlemaps-types.ts';
+
+const SERVICE = 'googlemaps';
+const FIXED_NOW = '1970-01-01T00:00:00.000Z';
+
+type Body = Record<string, any>;
+
+/** Web-service status envelope (HTTP 200 carrying a `status` field). */
+function maps(status: MapsStatus, extra: Body = {}, errorMessage?: string): GoogleMapsResponse {
+  return { status: 200, body: { status, ...(errorMessage ? { error_message: errorMessage } : {}), ...extra } };
+}
+
+/** google.rpc.Status envelope for the v1 / "New" APIs (real HTTP error codes). */
+function rpc(httpStatus: number, code: number, statusText: string, message: string): GoogleMapsResponse {
+  return { status: httpStatus, body: { error: { code, message, status: statusText } } };
+}
+
+function parseBody(body?: string): Body {
+  if (!body?.trim()) return {};
+  try {
+    const parsed = JSON.parse(body);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function parseLatLng(input: string | null | undefined): LatLng | null {
+  if (!input) return null;
+  const m = input.trim().match(/^(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)$/);
+  if (!m) return null;
+  const lat = Number(m[1]);
+  const lng = Number(m[2]);
+  if (!Number.isFinite(lat) || !Number.isFinite(lng)) return null;
+  if (lat < -90 || lat > 90 || lng < -180 || lng > 180) return null;
+  return { lat, lng };
+}
+
+/** Resolve free text to a geocode result, honoring connector-seeded overrides. */
+function resolveGeocode(address: string, root?: string): GeocodeResult | null {
+  if (isZeroResultsQuery(address)) return null;
+  const override = geocodeOverride(address, root);
+  if (override) return override;
+  const canned = findPlaceByText(address);
+  if (canned) return geocodeResultFromPlace(canned);
+  return synthGeocodeResult(address);
+}
+
+function geocodeOverride(address: string, root?: string): GeocodeResult | null {
+  const key = normalizeAddress(address);
+  const row = projectResources(SERVICE, root).find(
+    (r) => r.type === 'geocode' && (r as Body).normalized === key,
+  ) as Body | undefined;
+  return row ? (row.result as GeocodeResult) : null;
+}
+
+async function recordAudit(req: GoogleMapsRequest, entry: { api: string; status: string; query?: string }): Promise<void> {
+  if (req.readOnly) return;
+  try {
+    const seq = projectResources(SERVICE, req.root).filter((r) => r.type === 'audit').length;
+    const id = `audit_${stableHash({ ...entry, seq, at: req.occurredAt ?? FIXED_NOW })}`;
+    await applyTwinWrite(SERVICE, {
+      operation: 'audit.append',
+      subjectType: 'audit',
+      subjectId: id,
+      fields: { id, ...entry, occurredAt: req.occurredAt ?? FIXED_NOW },
+      occurredAt: req.occurredAt ?? FIXED_NOW,
+      actor: { kind: 'system' },
+    }, req.root);
+  } catch {
+    /* audit is advisory */
+  }
+}
+
+function auditRows(root?: string): Body[] {
+  return projectResources(SERVICE, root)
+    .filter((r) => r.type === 'audit')
+    .map((r) => { const { type: _t, updatedAt: _u, ...rest } = r; return rest as Body; });
+}
+
+// ---- per-API handlers ------------------------------------------------------
+
+/** Parse a `components=country:GB|postal_code:94043` filter into a map. */
+function parseComponents(raw: string | null): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!raw) return out;
+  for (const part of raw.split('|')) {
+    const [k, v] = part.split(':');
+    if (k && v) out[k.trim().toLowerCase()] = v.trim().toLowerCase();
+  }
+  return out;
+}
+
+/** Attach a deterministic plus_code (global + compound) to a geocode result. */
+function withPlusCode(result: GeocodeResult): GeocodeResult {
+  const components = Array.isArray(result.address_components) ? result.address_components : [];
+  const locality = components.find((c) => c.types?.includes('locality'))?.long_name
+    ?? components.find((c) => c.types?.includes('administrative_area_level_1'))?.long_name
+    ?? result.formatted_address;
+  return { ...result, plus_code: plusCodeFor(result.geometry.location, String(locality)) };
+}
+
+/** Parse a `bounds=lat,lng|lat,lng` viewport for biasing. */
+function parseBounds(raw: string | null): { sw: LatLng; ne: LatLng } | null {
+  if (!raw) return null;
+  const [a, b] = raw.split('|');
+  const sw = parseLatLng(a);
+  const ne = parseLatLng(b);
+  return sw && ne ? { sw, ne } : null;
+}
+
+function handleGeocode(url: URL, root: string | undefined): GoogleMapsResponse {
+  const address = url.searchParams.get('address');
+  const componentsRaw = url.searchParams.get('components');
+  const place_id = url.searchParams.get('place_id');
+  const language = url.searchParams.get('language');
+  const bounds = parseBounds(url.searchParams.get('bounds'));
+  const components = parseComponents(componentsRaw);
+  if (!address && !componentsRaw && !place_id) {
+    return maps('INVALID_REQUEST', { results: [] }, 'Invalid request. Missing the `address`, `components`, or `place_id` parameter.');
+  }
+  if (place_id) {
+    const p = findPlaceById(place_id);
+    return p ? maps('OK', { results: [withPlusCode(localizeResult(geocodeResultFromPlace(p), language))] }) : maps('ZERO_RESULTS', { results: [] });
+  }
+  const query = address ?? componentsRaw!;
+  let result = resolveGeocode(query, root);
+  // Component filtering: a `country:` constraint must match the resolved result's
+  // country, otherwise ZERO_RESULTS — faithful to the real components filter.
+  if (result && components.country) {
+    const resolvedCountry = result.address_components.find((c) => c.types.includes('country'))?.short_name?.toLowerCase();
+    const matchedPlace = findPlaceByText(query);
+    const canned = matchedPlace ? countryOf(matchedPlace) : resolvedCountry;
+    if (canned && canned !== components.country) return maps('ZERO_RESULTS', { results: [] });
+  }
+  if (!result) return maps('ZERO_RESULTS', { results: [] });
+  // Bounds biasing: for a synthesized (non-canned) result, snap the location into
+  // the requested viewport so a `bounds` hint demonstrably steers the result.
+  if (bounds && !findPlaceByText(query)) {
+    const loc = result.geometry.location;
+    const biased: LatLng = {
+      lat: Math.round(Math.min(Math.max(loc.lat, bounds.sw.lat), bounds.ne.lat) * 1e7) / 1e7,
+      lng: Math.round(Math.min(Math.max(loc.lng, bounds.sw.lng), bounds.ne.lng) * 1e7) / 1e7,
+    };
+    result = { ...result, geometry: { ...result.geometry, location: biased, viewport: viewportAround(biased) } };
+  }
+  // Localized display names per the `language` parameter.
+  result = localizeResult(result, language);
+  // Plus Codes appear in every geocode result.
+  result = withPlusCode(result);
+  return maps('OK', { results: [result] });
+}
+
+/** Apply the `language` parameter to a geocode result's formatted_address. */
+function localizeResult(result: GeocodeResult, language: string | null | undefined): GeocodeResult {
+  const localized = localizeFormattedAddress(result.formatted_address, language);
+  return localized === result.formatted_address ? result : { ...result, formatted_address: localized };
+}
+
+function handleReverseGeocode(url: URL): GoogleMapsResponse {
+  const latlng = parseLatLng(url.searchParams.get('latlng'));
+  if (!latlng) return maps('INVALID_REQUEST', { results: [] }, 'Invalid request. Missing or invalid `latlng` parameter.');
+  const p = findPlaceByLatLng(latlng);
+  const result: GeocodeResult = {
+    ...geocodeResultFromPlace(p, 'APPROXIMATE'),
+    geometry: { location: latlng, location_type: 'APPROXIMATE', viewport: viewportAround(latlng) },
+  };
+  return maps('OK', { results: [result] });
+}
+
+function handleDistanceMatrix(url: URL): GoogleMapsResponse {
+  const origins = (url.searchParams.get('origins') ?? '').split('|').filter(Boolean);
+  const destinations = (url.searchParams.get('destinations') ?? '').split('|').filter(Boolean);
+  if (origins.length === 0 || destinations.length === 0) {
+    return maps('INVALID_REQUEST', {}, 'Invalid request. Missing the `origins` or `destinations` parameter.');
+  }
+  // The real Distance Matrix caps a request at 100 elements (origins × destinations).
+  if (origins.length * destinations.length > 100) {
+    return maps('MAX_ELEMENTS_EXCEEDED', {}, 'Number of origins and destinations exceeds the per-query limit of 100 elements.');
+  }
+  const metric = url.searchParams.get('units') === 'metric';
+  const modeParam = (url.searchParams.get('mode') ?? 'driving').toLowerCase();
+  const mode = TRAVEL_MODES[modeParam] ?? 'DRIVING';
+  const speed = MODE_SPEED_KMH[mode] ?? 40;
+  const traffic = !!url.searchParams.get('departure_time') && mode === 'DRIVING';
+  const resolveLoc = (q: string): LatLng | null => parseLatLng(q) ?? (isZeroResultsQuery(q) ? null : (findPlaceByText(q)?.location ?? deterministicLatLng(normalizeAddress(q))));
+  const originLocs = origins.map(resolveLoc);
+  const destLocs = destinations.map(resolveLoc);
+  const origin_addresses = origins.map((o) => o);
+  const destination_addresses = destinations.map((d) => d);
+  const rows = originLocs.map((o) => ({
+    elements: destLocs.map((d) => {
+      if (!o || !d) return { status: 'NOT_FOUND' as const };
+      const meters = Math.max(1, haversineMeters(o, d));
+      const secs = Math.max(60, Math.round((meters / 1000 / speed) * 3600));
+      const el: Body = {
+        status: 'OK' as const,
+        duration: { value: secs, text: durationText(secs) },
+        distance: { value: meters, text: distanceText(meters, metric) },
+      };
+      if (traffic) {
+        const t = Math.round(secs * 1.25);
+        el.duration_in_traffic = { value: t, text: durationText(t) };
+      }
+      return el;
+    }),
+  }));
+  return maps('OK', { origin_addresses, destination_addresses, rows });
+}
+
+const TRAVEL_MODES: Record<string, string> = { driving: 'DRIVING', walking: 'WALKING', bicycling: 'BICYCLING', transit: 'TRANSIT' };
+/** Average speed (km/h) per travel mode → deterministic duration scaling. */
+const MODE_SPEED_KMH: Record<string, number> = { DRIVING: 40, WALKING: 5, BICYCLING: 15, TRANSIT: 30 };
+
+function locOf(q: string): LatLng {
+  return parseLatLng(q) ?? findPlaceByText(q)?.location ?? deterministicLatLng(normalizeAddress(q));
+}
+function addrOf(q: string): string {
+  return parseLatLng(q) ? q : (findPlaceByText(q)?.formatted_address ?? q);
+}
+
+function buildLeg(oQ: string, dQ: string, mode: string, metric: boolean, opts: { traffic?: boolean; transit?: boolean } = {}): Body {
+  const oLoc = locOf(oQ);
+  const dLoc = locOf(dQ);
+  const meters = Math.max(1, haversineMeters(oLoc, dLoc));
+  const speed = MODE_SPEED_KMH[mode] ?? 40;
+  const secs = Math.max(60, Math.round((meters / 1000 / speed) * 3600));
+  const step: Body = {
+    travel_mode: mode,
+    distance: { value: meters, text: distanceText(meters, metric) },
+    duration: { value: secs, text: durationText(secs) },
+    start_location: oLoc,
+    end_location: dLoc,
+    html_instructions: `Head toward ${addrOf(dQ)}`,
+    polyline: { points: encodePolyline([oLoc, dLoc]) },
+  };
+  if (opts.transit && mode === 'TRANSIT') {
+    step.transit_details = {
+      arrival_stop: { name: `${addrOf(dQ)} Station`, location: dLoc },
+      departure_stop: { name: `${addrOf(oQ)} Station`, location: oLoc },
+      departure_time: { value: 0, text: '12:00am', time_zone: 'UTC' },
+      arrival_time: { value: secs, text: durationText(secs), time_zone: 'UTC' },
+      headsign: addrOf(dQ),
+      num_stops: Math.max(1, Math.round(meters / 2000)),
+      line: {
+        name: 'Twin Line',
+        short_name: 'TL',
+        vehicle: { name: 'Train', type: 'HEAVY_RAIL', icon: '//twin/rail.png' },
+        agencies: [{ name: 'Twin Transit', url: 'https://twin.local' }],
+      },
+    };
+  }
+  const leg: Body = {
+    distance: { value: meters, text: distanceText(meters, metric) },
+    duration: { value: secs, text: durationText(secs) },
+    start_address: addrOf(oQ),
+    end_address: addrOf(dQ),
+    start_location: oLoc,
+    end_location: dLoc,
+    steps: [step],
+  };
+  if (opts.traffic) {
+    // duration_in_traffic is modeled as ~25% slower than free-flow, deterministic.
+    const trafficSecs = Math.round(secs * 1.25);
+    leg.duration_in_traffic = { value: trafficSecs, text: durationText(trafficSecs) };
+  }
+  return leg;
+}
+
+function buildRoute(points: string[], mode: string, metric: boolean, waypoint_order: number[], opts: { traffic?: boolean; transit?: boolean; warnings?: string[]; summarySuffix?: string }): Body {
+  const legs: Body[] = [];
+  for (let i = 0; i < points.length - 1; i++) {
+    legs.push(buildLeg(points[i]!, points[i + 1]!, mode, metric, opts));
+  }
+  const allLocs = points.map(locOf);
+  const lats = allLocs.map((l) => l.lat);
+  const lngs = allLocs.map((l) => l.lng);
+  const center = { lat: (Math.min(...lats) + Math.max(...lats)) / 2, lng: (Math.min(...lngs) + Math.max(...lngs)) / 2 };
+  return {
+    summary: `${addrOf(points[0]!)} to ${addrOf(points[points.length - 1]!)}${opts.summarySuffix ?? ''}`,
+    legs,
+    overview_polyline: { points: encodePolyline(allLocs) },
+    bounds: viewportAround(center, (Math.max(...lats) - Math.min(...lats)) / 2 + 0.01),
+    copyrights: 'Map data ©2024 (twin)',
+    warnings: opts.warnings ?? [],
+    waypoint_order,
+  };
+}
+
+function handleDirections(url: URL): GoogleMapsResponse {
+  const origin = url.searchParams.get('origin');
+  const destination = url.searchParams.get('destination');
+  if (!origin || !destination) return maps('INVALID_REQUEST', { routes: [] }, 'Invalid request. Missing the `origin` or `destination` parameter.');
+  if (isZeroResultsQuery(origin) || isZeroResultsQuery(destination)) return maps('ZERO_RESULTS', { routes: [] });
+  const metric = url.searchParams.get('units') === 'metric';
+  const modeParam = (url.searchParams.get('mode') ?? 'driving').toLowerCase();
+  const mode = TRAVEL_MODES[modeParam] ?? 'DRIVING';
+
+  // Waypoints (optionally optimize:true → reordered waypoint_order).
+  const wpRaw = url.searchParams.get('waypoints');
+  let waypoints: string[] = [];
+  let optimize = false;
+  if (wpRaw) {
+    let spec = wpRaw;
+    if (/^optimize:true\|/i.test(spec)) { optimize = true; spec = spec.replace(/^optimize:true\|/i, ''); }
+    waypoints = spec.split('|').map((w) => w.replace(/^via:/i, '')).filter(Boolean);
+  }
+  // optimize reorders waypoints by nearest-neighbor from the origin (deterministic).
+  let waypoint_order: number[] = waypoints.map((_w, i) => i);
+  let orderedWaypoints = waypoints;
+  if (optimize && waypoints.length > 1) {
+    const remaining = waypoints.map((w, i) => ({ w, i }));
+    const ordered: { w: string; i: number }[] = [];
+    let cur = locOf(origin);
+    while (remaining.length) {
+      let bestIdx = 0;
+      let bestD = Number.POSITIVE_INFINITY;
+      for (let k = 0; k < remaining.length; k++) {
+        const d = haversineMeters(cur, locOf(remaining[k]!.w));
+        if (d < bestD) { bestD = d; bestIdx = k; }
+      }
+      const chosen = remaining.splice(bestIdx, 1)[0]!;
+      ordered.push(chosen);
+      cur = locOf(chosen.w);
+    }
+    orderedWaypoints = ordered.map((o) => o.w);
+    waypoint_order = ordered.map((o) => o.i);
+  }
+  const points = [origin, ...orderedWaypoints, destination];
+
+  const departureTime = url.searchParams.get('departure_time');
+  const traffic = !!departureTime && mode === 'DRIVING';
+  const transit = mode === 'TRANSIT';
+
+  // avoid=tolls|highways|ferries → recorded as route warnings.
+  const avoid = url.searchParams.get('avoid');
+  const warnings: string[] = [];
+  if (avoid) for (const a of avoid.split('|')) warnings.push(`Route avoids ${a}.`);
+
+  const routes: Body[] = [buildRoute(points, mode, metric, waypoint_order, { traffic, transit, warnings })];
+
+  // alternatives=true → an additional, slightly-longer route variant.
+  if (url.searchParams.get('alternatives') === 'true') {
+    const alt = buildRoute(points, mode, metric, waypoint_order, { traffic, transit, warnings, summarySuffix: ' (alt)' });
+    // Make the alternative deterministically longer so it is distinguishable.
+    for (const leg of alt.legs as Body[]) {
+      leg.duration = { value: Math.round(leg.duration.value * 1.15), text: durationText(Math.round(leg.duration.value * 1.15)) };
+    }
+    routes.push(alt);
+  }
+
+  const geocoded_waypoints = points.map((q) => ({
+    geocoder_status: 'OK',
+    place_id: findPlaceByText(q)?.place_id ?? `ChIJ${stableHash(q)}twin`,
+    types: ['street_address'],
+  }));
+  return maps('OK', { geocoded_waypoints, routes });
+}
+
+function placeToFindCandidate(p: CannedPlace): Body {
+  return {
+    place_id: p.place_id,
+    name: p.name,
+    formatted_address: p.formatted_address,
+    geometry: { location: p.location, viewport: viewportAround(p.location) },
+    types: p.types,
+  };
+}
+
+function handleFindPlace(url: URL): GoogleMapsResponse {
+  const input = url.searchParams.get('input');
+  if (!input) return maps('INVALID_REQUEST', { candidates: [] }, 'Missing the required `input` parameter.');
+  if (isZeroResultsQuery(input)) return maps('ZERO_RESULTS', { candidates: [] });
+  const p = findPlaceByText(input);
+  return maps('OK', { candidates: p ? [placeToFindCandidate(p)] : [placeToFindCandidate(allPlaces()[0]!)] });
+}
+
+/** A deterministic photo block (legacy Places) for a place. */
+function legacyPhotos(p: CannedPlace): Body[] {
+  return [{
+    photo_reference: `twinphoto_${stableHash(p.place_id)}`,
+    height: 1080,
+    width: 1920,
+    html_attributions: [`<a href="https://maps.google.com/">${p.name}</a>`],
+  }];
+}
+
+/**
+ * The twin returns a deterministic, paginated list of nearby places for a query so
+ * next_page_token works faithfully. Build a stable candidate list around a seed.
+ */
+function pagedCandidates(seed: string, anchor: CannedPlace): CannedPlace[] {
+  // First result is the anchor itself (so single-place lookups keep their canonical
+  // place_id); the remaining 22 are deterministic nearby variants for pagination.
+  const out: CannedPlace[] = [anchor];
+  for (let i = 1; i < 23; i++) {
+    out.push({
+      ...anchor,
+      place_id: `ChIJpage${stableHash(`${seed}:${i}`)}`,
+      name: `${anchor.name} POI ${i}`,
+      formatted_address: `${i} ${anchor.formatted_address}`,
+    });
+  }
+  return out;
+}
+
+function handleTextSearchLegacy(url: URL): GoogleMapsResponse {
+  const query = url.searchParams.get('query');
+  const pageToken = url.searchParams.get('pagetoken');
+  if (pageToken) {
+    const decoded = decodePageToken(pageToken);
+    if (!decoded) return maps('INVALID_REQUEST', { results: [] }, 'Invalid `pagetoken`.');
+    const anchor = findPlaceByText(decoded.query) ?? allPlaces()[0]!;
+    const all = pagedCandidates(decoded.query, anchor);
+    const page = all.slice(decoded.offset, decoded.offset + 20);
+    const nextOffset = decoded.offset + 20;
+    const results = page.map((p) => ({ ...placeToFindCandidate(p), rating: 4.4, user_ratings_total: 1280, business_status: 'OPERATIONAL' }));
+    const body: Body = { status: 'OK', results, html_attributions: [] };
+    if (nextOffset < all.length) body.next_page_token = encodePageToken(decoded.query, nextOffset);
+    return { status: 200, body };
+  }
+  if (!query) return maps('INVALID_REQUEST', { results: [] }, 'Missing the required `query` parameter.');
+  if (isZeroResultsQuery(query)) return maps('ZERO_RESULTS', { results: [] });
+  const anchor = findPlaceByText(query) ?? allPlaces()[0]!;
+  const all = pagedCandidates(query, anchor);
+  const page = all.slice(0, 20);
+  const results = page.map((p) => ({ ...placeToFindCandidate(p), rating: 4.4, user_ratings_total: 1280, business_status: 'OPERATIONAL' }));
+  return maps('OK', { results, next_page_token: encodePageToken(query, 20), html_attributions: [] });
+}
+
+function handleNearbySearch(url: URL): GoogleMapsResponse {
+  const pageToken = url.searchParams.get('pagetoken');
+  if (pageToken) {
+    const decoded = decodePageToken(pageToken);
+    if (!decoded) return maps('INVALID_REQUEST', { results: [] }, 'Invalid `pagetoken`.');
+    const anchor = findPlaceByText(decoded.query) ?? allPlaces()[0]!;
+    const all = pagedCandidates(decoded.query, anchor);
+    const page = all.slice(decoded.offset, decoded.offset + 20);
+    const nextOffset = decoded.offset + 20;
+    const results = page.map((p) => ({ ...placeToFindCandidate(p), rating: 4.2, user_ratings_total: 512, vicinity: p.formatted_address }));
+    const body: Body = { status: 'OK', results, html_attributions: [] };
+    if (nextOffset < all.length) body.next_page_token = encodePageToken(decoded.query, nextOffset);
+    return { status: 200, body };
+  }
+  const location = parseLatLng(url.searchParams.get('location'));
+  const radius = url.searchParams.get('radius');
+  const rankby = url.searchParams.get('rankby');
+  if (!location) return maps('INVALID_REQUEST', { results: [] }, 'Missing or invalid `location` parameter.');
+  if (!radius && rankby !== 'distance') return maps('INVALID_REQUEST', { results: [] }, 'You must specify a `radius` or set `rankby=distance`.');
+  const anchor = findPlaceByLatLng(location);
+  const seed = `${location.lat},${location.lng}`;
+  const all = pagedCandidates(seed, anchor);
+  const page = all.slice(0, 20);
+  const results = page.map((p) => ({ ...placeToFindCandidate(p), rating: 4.2, user_ratings_total: 512, vicinity: p.formatted_address }));
+  return maps('OK', { results, next_page_token: encodePageToken(seed, 20), html_attributions: [] });
+}
+
+function handlePlaceDetails(url: URL): GoogleMapsResponse {
+  const placeId = url.searchParams.get('place_id');
+  if (!placeId) return maps('INVALID_REQUEST', {}, 'Missing the required `place_id` parameter.');
+  const p = findPlaceById(placeId);
+  if (!p) return maps('NOT_FOUND', {}, 'The provided `place_id` was not found.');
+  const full: Body = {
+    place_id: p.place_id,
+    name: p.name,
+    formatted_address: p.formatted_address,
+    address_components: p.components,
+    geometry: { location: p.location, viewport: viewportAround(p.location) },
+    types: p.types,
+    url: `https://maps.google.com/?cid=${stableHash(p.place_id)}`,
+    utc_offset: 0,
+    rating: 4.4,
+    user_ratings_total: 1280,
+    business_status: 'OPERATIONAL',
+    opening_hours: openingHoursFor(p),
+    current_opening_hours: openingHoursFor(p),
+    reviews: reviewsFor(p),
+    editorial_summary: { overview: `${p.name} — a notable place.`, language: 'en' },
+    photos: legacyPhotos(p),
+    plus_code: plusCodeFor(p.location, localityOf(p)),
+  };
+  // `fields` parameter masks the response to only the requested top-level fields.
+  const fieldsParam = url.searchParams.get('fields');
+  let result: Body = full;
+  if (fieldsParam) {
+    const wanted = new Set(fieldsParam.split(',').map((f) => f.trim()).filter(Boolean));
+    result = {};
+    for (const key of Object.keys(full)) if (wanted.has(key)) result[key] = full[key];
+  }
+  return maps('OK', { result, html_attributions: [] });
+}
+
+function handlePlacePhoto(url: URL): GoogleMapsResponse {
+  const ref = url.searchParams.get('photo_reference') ?? url.searchParams.get('photoreference');
+  const maxwidth = url.searchParams.get('maxwidth');
+  const maxheight = url.searchParams.get('maxheight');
+  if (!ref) return maps('INVALID_REQUEST', {}, 'Missing the required `photo_reference` parameter.');
+  if (!maxwidth && !maxheight) return maps('INVALID_REQUEST', {}, 'You must specify `maxwidth` or `maxheight`.');
+  // The real endpoint 302-redirects to image bytes on the CDN; the twin returns the
+  // metadata of that redirect (serving deterministic bytes is a filed todo).
+  return {
+    status: 200,
+    body: {
+      contentType: 'image/jpeg',
+      photo_reference: ref,
+      maxwidth: maxwidth ? Number(maxwidth) : undefined,
+      maxheight: maxheight ? Number(maxheight) : undefined,
+      twinNote: 'twin returns photo metadata, not real imagery pixels',
+    },
+  };
+}
+
+function handleAutocomplete(url: URL): GoogleMapsResponse {
+  const input = url.searchParams.get('input');
+  if (!input) return maps('INVALID_REQUEST', { predictions: [] }, 'Missing the required `input` parameter.');
+  if (isZeroResultsQuery(input)) return maps('ZERO_RESULTS', { predictions: [] });
+  const n = normalizeAddress(input);
+  const matches = allPlaces().filter((p) => normalizeAddress(p.name).startsWith(n) || normalizeAddress(p.name).includes(n));
+  const list = (matches.length ? matches : [allPlaces()[0]!]).slice(0, 5);
+  const predictions = list.map((p) => ({
+    description: p.formatted_address,
+    place_id: p.place_id,
+    structured_formatting: { main_text: p.name, secondary_text: p.formatted_address },
+    types: p.types,
+    terms: [{ offset: 0, value: p.name }],
+    matched_substrings: [{ length: input.length, offset: 0 }],
+  }));
+  return maps('OK', { predictions });
+}
+
+function handleQueryAutocomplete(url: URL): GoogleMapsResponse {
+  const input = url.searchParams.get('input');
+  if (!input) return maps('INVALID_REQUEST', { predictions: [] }, 'Missing the required `input` parameter.');
+  const p = findPlaceByText(input) ?? allPlaces()[0]!;
+  return maps('OK', { predictions: [{ description: `${input} near ${p.name}`, place_id: p.place_id, types: ['establishment'] }] });
+}
+
+// ---- Places API (New) — v1, header-key, google.rpc.Status errors -----------
+
+function newPlace(p: CannedPlace): Body {
+  return {
+    id: p.place_id,
+    name: `places/${p.place_id}`,
+    displayName: { text: p.name, languageCode: 'en' },
+    formattedAddress: p.formatted_address,
+    location: { latitude: p.location.lat, longitude: p.location.lng },
+    types: p.types,
+    rating: 4.4,
+    userRatingCount: 1280,
+    businessStatus: 'OPERATIONAL',
+    googleMapsUri: `https://maps.google.com/?cid=${stableHash(p.place_id)}`,
+    photos: [{
+      name: `places/${p.place_id}/photos/twinphoto_${stableHash(p.place_id)}`,
+      widthPx: 1920,
+      heightPx: 1080,
+      authorAttributions: [{ displayName: p.name, uri: 'https://maps.google.com/' }],
+    }],
+  };
+}
+
+/**
+ * Apply an X-Goog-FieldMask to a response object. A mask like
+ * `places.displayName,places.location` retains only those dotted paths; `*`
+ * returns everything. Missing mask on a v1 read is itself an INVALID_ARGUMENT in
+ * the real API for the GET-details path, but for searches an empty mask returns
+ * the full object here (callers that care assert specific retained fields).
+ */
+/** The Places API always returns the resource `name` and `id` regardless of mask. */
+function preserveIdentifiers(target: Body, source: Body): void {
+  if (typeof source.name === 'string') target.name = source.name;
+  if (typeof source.id === 'string') target.id = source.id;
+}
+
+function applyFieldMask<T extends Body>(obj: T, mask: string | undefined): Body {
+  if (!mask || mask.trim() === '*' || !mask.trim()) return obj;
+  const paths = mask.split(',').map((p) => p.trim()).filter(Boolean);
+  const out: Body = {};
+  const setPath = (target: Body, source: Body, parts: string[]): void => {
+    const [head, ...rest] = parts;
+    if (head === undefined) return;
+    if (source[head] === undefined) return;
+    if (rest.length === 0) { target[head] = source[head]; return; }
+    if (Array.isArray(source[head])) {
+      target[head] = (source[head] as Body[]).map((item, i) => {
+        const sub: Body = (target[head] as Body[] | undefined)?.[i] ?? {};
+        setPath(sub, item, rest);
+        preserveIdentifiers(sub, item);
+        return sub;
+      });
+      return;
+    }
+    target[head] = target[head] ?? {};
+    setPath(target[head] as Body, source[head] as Body, rest);
+  };
+  for (const path of paths) setPath(out, obj, path.split('.'));
+  // Top-level identifiers (details endpoint) are always present.
+  preserveIdentifiers(out, obj);
+  return out;
+}
+
+function pagedNewPlaces(seed: string, anchor: CannedPlace): CannedPlace[] {
+  return pagedCandidates(seed, anchor);
+}
+
+function handleNewTextSearch(body: Body, mask: string | undefined): GoogleMapsResponse {
+  const q = typeof body.textQuery === 'string' ? body.textQuery : '';
+  const pageToken = typeof body.pageToken === 'string' ? body.pageToken : undefined;
+  if (pageToken) {
+    const decoded = decodePageToken(pageToken);
+    if (!decoded) return rpc(400, 400, 'INVALID_ARGUMENT', 'Invalid pageToken.');
+    const anchor = findPlaceByText(decoded.query) ?? allPlaces()[0]!;
+    const all = pagedNewPlaces(decoded.query, anchor);
+    const page = all.slice(decoded.offset, decoded.offset + 20).map(newPlace);
+    const out: Body = { places: page };
+    if (decoded.offset + 20 < all.length) out.nextPageToken = encodePageToken(decoded.query, decoded.offset + 20);
+    return { status: 200, body: applyFieldMask(out, mask) };
+  }
+  if (!q.trim()) return rpc(400, 400, 'INVALID_ARGUMENT', 'textQuery must be non-empty.');
+  if (isZeroResultsQuery(q)) return { status: 200, body: {} };
+  // pageSize controls page length; default 20 keeps a single place for simple queries.
+  const pageSize = typeof body.pageSize === 'number' ? body.pageSize : undefined;
+  if (pageSize !== undefined) {
+    const anchor = findPlaceByText(q) ?? allPlaces()[0]!;
+    const all = pagedNewPlaces(q, anchor);
+    const page = all.slice(0, pageSize).map(newPlace);
+    const out: Body = { places: page };
+    if (pageSize < all.length) out.nextPageToken = encodePageToken(q, pageSize);
+    return { status: 200, body: applyFieldMask(out, mask) };
+  }
+  const p = findPlaceByText(q) ?? allPlaces()[0]!;
+  return { status: 200, body: applyFieldMask({ places: [newPlace(p)] }, mask) };
+}
+
+function handleNewNearbySearch(body: Body, mask: string | undefined): GoogleMapsResponse {
+  const center = body.locationRestriction?.circle?.center;
+  if (!center || typeof center.latitude !== 'number' || typeof center.longitude !== 'number') {
+    return rpc(400, 400, 'INVALID_ARGUMENT', 'locationRestriction.circle.center is required.');
+  }
+  const p = findPlaceByLatLng({ lat: center.latitude, lng: center.longitude });
+  return { status: 200, body: applyFieldMask({ places: [newPlace(p)] }, mask) };
+}
+
+function handleNewAutocomplete(body: Body): GoogleMapsResponse {
+  const input = typeof body.input === 'string' ? body.input : '';
+  if (!input.trim()) return rpc(400, 400, 'INVALID_ARGUMENT', 'input must be non-empty.');
+  const n = normalizeAddress(input);
+  const matches = allPlaces().filter((p) => normalizeAddress(p.name).includes(n));
+  const list = (matches.length ? matches : [allPlaces()[0]!]).slice(0, 5);
+  const suggestions = list.map((p) => ({
+    placePrediction: {
+      place: `places/${p.place_id}`,
+      placeId: p.place_id,
+      text: { text: p.formatted_address },
+      structuredFormat: { mainText: { text: p.name }, secondaryText: { text: p.formatted_address } },
+      types: p.types,
+    },
+  }));
+  return { status: 200, body: { suggestions } };
+}
+
+function handleNewPlaceDetails(placeId: string, mask: string | undefined): GoogleMapsResponse {
+  const p = findPlaceById(placeId);
+  if (!p) return rpc(404, 404, 'NOT_FOUND', `Place not found: places/${placeId}`);
+  return { status: 200, body: applyFieldMask(newPlace(p), mask) };
+}
+
+/**
+ * Places API (New) Place Photo media endpoint:
+ *   GET /v1/places/{place_id}/photos/{photo_resource}/media?maxWidthPx=...
+ * Real API returns a photoUri (or binary). The twin returns photo metadata.
+ */
+function handleNewPlacePhotoMedia(url: URL, placeId: string, photoRef: string): GoogleMapsResponse {
+  const maxWidthPx = url.searchParams.get('maxWidthPx');
+  const maxHeightPx = url.searchParams.get('maxHeightPx');
+  if (!maxWidthPx && !maxHeightPx) return rpc(400, 400, 'INVALID_ARGUMENT', 'maxWidthPx or maxHeightPx is required.');
+  const p = findPlaceById(placeId);
+  if (!p) return rpc(404, 404, 'NOT_FOUND', `Place not found: places/${placeId}`);
+  return {
+    status: 200,
+    body: {
+      name: `places/${placeId}/photos/${photoRef}/media`,
+      photoUri: `https://twin.local/places/${placeId}/photos/${photoRef}=s${maxWidthPx ?? maxHeightPx}`,
+      contentType: 'image/jpeg',
+      twinNote: 'twin returns photo metadata, not real imagery pixels',
+    },
+  };
+}
+
+// ---- Roads -----------------------------------------------------------------
+
+function snapPoint(loc: LatLng, originalIndex: number | undefined): Body {
+  return {
+    location: { latitude: loc.lat, longitude: loc.lng },
+    placeId: `ChIJroad${stableHash(`${loc.lat},${loc.lng}`)}`,
+    ...(originalIndex !== undefined ? { originalIndex } : {}),
+  };
+}
+
+function handleSnapToRoads(url: URL): GoogleMapsResponse {
+  const path = url.searchParams.get('path');
+  if (!path) return rpc(400, 400, 'INVALID_ARGUMENT', 'Request must specify a path.');
+  const pts = path.split('|').map(parseLatLng);
+  if (pts.some((p) => p === null)) return rpc(400, 400, 'INVALID_ARGUMENT', 'Invalid lat/lng in path.');
+  const inputs = pts as LatLng[];
+  const interpolate = url.searchParams.get('interpolate') === 'true';
+  if (interpolate && inputs.length >= 2) {
+    // Densify: between each pair of input points, insert one interpolated point.
+    // Original points keep their originalIndex; interpolated points omit it.
+    const snappedPoints: Body[] = [];
+    for (let i = 0; i < inputs.length; i++) {
+      snappedPoints.push(snapPoint(inputs[i]!, i));
+      if (i < inputs.length - 1) {
+        const mid: LatLng = {
+          lat: Math.round(((inputs[i]!.lat + inputs[i + 1]!.lat) / 2) * 1e7) / 1e7,
+          lng: Math.round(((inputs[i]!.lng + inputs[i + 1]!.lng) / 2) * 1e7) / 1e7,
+        };
+        snappedPoints.push(snapPoint(mid, undefined));
+      }
+    }
+    return { status: 200, body: { snappedPoints } };
+  }
+  const snappedPoints = inputs.map((p, i) => snapPoint(p, i));
+  return { status: 200, body: { snappedPoints } };
+}
+
+function handleNearestRoads(url: URL): GoogleMapsResponse {
+  const points = url.searchParams.get('points');
+  if (!points) return rpc(400, 400, 'INVALID_ARGUMENT', 'Request must specify points.');
+  const pts = points.split('|').map(parseLatLng);
+  if (pts.some((p) => p === null)) return rpc(400, 400, 'INVALID_ARGUMENT', 'Invalid lat/lng in points.');
+  const snappedPoints = (pts as LatLng[]).map((p, i) => snapPoint(p, i));
+  return { status: 200, body: { snappedPoints } };
+}
+
+function handleSpeedLimits(url: URL): GoogleMapsResponse {
+  const path = url.searchParams.get('path');
+  const placeIds = url.searchParams.getAll('placeId');
+  if (!path && placeIds.length === 0) return rpc(400, 400, 'INVALID_ARGUMENT', 'Request must specify path or placeId.');
+  const ids = placeIds.length ? placeIds : (path!.split('|').map(parseLatLng).filter((p): p is LatLng => !!p).map((p) => `ChIJroad${stableHash(`${p.lat},${p.lng}`)}`));
+  const speedLimits = ids.map((placeId) => ({ placeId, speedLimit: 45 + (parseInt(stableHash(placeId).slice(0, 2), 16) % 40), units: 'KPH' }));
+  return { status: 200, body: { speedLimits } };
+}
+
+// ---- Time Zone / Elevation / Geolocation -----------------------------------
+
+function handleTimeZone(url: URL): GoogleMapsResponse {
+  const loc = parseLatLng(url.searchParams.get('location'));
+  const ts = url.searchParams.get('timestamp');
+  if (!loc) return maps('INVALID_REQUEST', {}, 'Invalid or missing `location` parameter.');
+  if (ts === null || !Number.isFinite(Number(ts))) return maps('INVALID_REQUEST', {}, 'Invalid or missing `timestamp` parameter.');
+  const z = deterministicTimeZone(loc, Number(ts));
+  return maps('OK', { dstOffset: z.dstOffset, rawOffset: z.rawOffset, timeZoneId: z.timeZoneId, timeZoneName: z.timeZoneName });
+}
+
+function handleElevation(url: URL): GoogleMapsResponse {
+  const locations = url.searchParams.get('locations');
+  const path = url.searchParams.get('path');
+  const samples = url.searchParams.get('samples');
+  if (!locations && !path) return maps('INVALID_REQUEST', { results: [] }, 'Invalid request. Missing `locations` or `path`.');
+  let pts: (LatLng | null)[];
+  if (locations) {
+    pts = locations.split('|').map(parseLatLng);
+  } else {
+    if (!samples || !Number.isFinite(Number(samples))) return maps('INVALID_REQUEST', { results: [] }, '`path` requests require `samples`.');
+    pts = path!.split('|').map(parseLatLng);
+  }
+  if (pts.some((p) => p === null)) return maps('INVALID_REQUEST', { results: [] }, 'Invalid location in request.');
+  const results = (pts as LatLng[]).map((loc) => ({ elevation: deterministicElevation(loc), location: loc, resolution: 4.771975994110107 }));
+  return maps('OK', { results });
+}
+
+function handleGeolocation(body: Body): GoogleMapsResponse {
+  // Geolocation accepts cellTowers / wifiAccessPoints; empty body falls back to a
+  // deterministic location with a low accuracy, faithful to the real API.
+  const seed = JSON.stringify(body?.wifiAccessPoints ?? body?.cellTowers ?? body?.considerIp ?? 'default');
+  const loc = deterministicLatLng(seed);
+  return { status: 200, body: { location: { lat: loc.lat, lng: loc.lng }, accuracy: 1500 } };
+}
+
+// ---- Static Maps / Street View Static (binary surfaces) --------------------
+
+function handleStaticMap(url: URL): GoogleMapsResponse {
+  const center = url.searchParams.get('center');
+  const markers = url.searchParams.get('markers');
+  const size = url.searchParams.get('size');
+  if (!size) return rpc(400, 400, 'INVALID_ARGUMENT', 'Missing the required `size` parameter.');
+  if (!center && !markers && !url.searchParams.get('path')) {
+    return rpc(400, 400, 'INVALID_ARGUMENT', 'Static map requests must include `center` (with `zoom`), `markers`, or `path`.');
+  }
+  // A twin returns image METADATA (incl. parsed styling) rather than real pixels.
+  const maptype = url.searchParams.get('maptype') ?? 'roadmap';
+  const validMaptypes = ['roadmap', 'satellite', 'terrain', 'hybrid'];
+  if (!validMaptypes.includes(maptype)) return rpc(400, 400, 'INVALID_ARGUMENT', `Invalid maptype: ${maptype}`);
+  return {
+    status: 200,
+    body: {
+      contentType: 'image/png',
+      size,
+      center,
+      maptype,
+      markers: url.searchParams.getAll('markers'),
+      path: url.searchParams.getAll('path'),
+      style: url.searchParams.getAll('style'),
+      scale: url.searchParams.get('scale') ? Number(url.searchParams.get('scale')) : 1,
+      twinNote: 'twin returns image metadata, not real imagery pixels',
+    },
+  };
+}
+
+function handleStreetView(url: URL): GoogleMapsResponse {
+  const location = url.searchParams.get('location');
+  const pano = url.searchParams.get('pano');
+  const size = url.searchParams.get('size');
+  if (!size) return rpc(400, 400, 'INVALID_ARGUMENT', 'Missing the required `size` parameter.');
+  if (!location && !pano) return rpc(400, 400, 'INVALID_ARGUMENT', 'Street View requests must include `location` or `pano`.');
+  return { status: 200, body: { contentType: 'image/jpeg', size, twinNote: 'twin returns image metadata, not real imagery pixels' } };
+}
+
+function handleStreetViewMetadata(url: URL): GoogleMapsResponse {
+  const location = url.searchParams.get('location');
+  const pano = url.searchParams.get('pano');
+  if (!location && !pano) return maps('INVALID_REQUEST', {}, 'Street View metadata requires `location` or `pano`.');
+  const loc = parseLatLng(location) ?? deterministicLatLng(location ?? pano ?? '');
+  if (location && isZeroResultsQuery(location)) return maps('ZERO_RESULTS', {});
+  return maps('OK', {
+    copyright: '© Google (twin)',
+    date: '2024-01',
+    location: { lat: loc.lat, lng: loc.lng },
+    pano_id: pano ?? `pano_${stableHash(`${loc.lat},${loc.lng}`)}`,
+  });
+}
+
+// ---- Address Validation (v1, header-key) -----------------------------------
+
+function handleAddressValidation(body: Body): GoogleMapsResponse {
+  const addr = body?.address;
+  const lines: string[] = Array.isArray(addr?.addressLines) ? addr.addressLines : [];
+  if (lines.length === 0) return rpc(400, 400, 'INVALID_ARGUMENT', 'address.addressLines must be non-empty.');
+  const joined = lines.join(', ');
+  const p = findPlaceByText(joined);
+  const loc = p?.location ?? deterministicLatLng(normalizeAddress(joined));
+  const verdict = p
+    ? { inputGranularity: 'PREMISE', validationGranularity: 'PREMISE', geocodeGranularity: 'PREMISE', addressComplete: true, hasUnconfirmedComponents: false }
+    : { inputGranularity: 'ROUTE', validationGranularity: 'ROUTE', geocodeGranularity: 'ROUTE', addressComplete: false, hasUnconfirmedComponents: true };
+  // Per-component confirmationLevel: confirmed for canned places, unconfirmed otherwise.
+  const confirmationLevel = p ? 'CONFIRMED' : 'UNCONFIRMED_BUT_PLAUSIBLE';
+  const sourceComponents = p ? p.components : [
+    { long_name: lines[0] ?? joined, short_name: lines[0] ?? joined, types: ['route'] },
+  ];
+  const addressComponents = sourceComponents.map((c) => ({
+    componentName: { text: c.long_name, languageCode: 'en' },
+    componentType: c.types[0] ?? 'route',
+    confirmationLevel,
+    inferred: false,
+    spellCorrected: false,
+  }));
+  // USPS CASS metadata is only populated for US addresses.
+  const isUS = (p ? countryOf(p) === 'us' : /\b(usa|united states)\b/i.test(joined) || lines.some((l) => /\b[A-Z]{2}\s*\d{5}\b/.test(l)));
+  const uspsData = isUS
+    ? { standardizedAddress: { firstAddressLine: lines[0] ?? joined, cityStateZipAddressLine: 'MOUNTAIN VIEW CA 94043-1351', city: 'MOUNTAIN VIEW', state: 'CA', zipCode: '94043', zipCodeExtension: '1351' }, deliveryPointCode: '99', dpvConfirmation: p ? 'Y' : 'N', carrierRoute: 'C909' }
+    : undefined;
+  return {
+    status: 200,
+    body: {
+      result: {
+        verdict,
+        address: { formattedAddress: p?.formatted_address ?? joined, postalAddress: { addressLines: lines }, addressComponents },
+        geocode: { location: { latitude: loc.lat, longitude: loc.lng }, placeId: p?.place_id ?? `ChIJ${stableHash(joined)}twin` },
+        ...(uspsData ? { uspsData } : {}),
+      },
+      responseId: `resp_${stableHash(joined)}`,
+    },
+  };
+}
+
+// ---- Routes API (New) — v2, header-key, google.rpc.Status errors -----------
+
+/** Resolve a Routes-API waypoint ({location:{latLng}} | {address} | {placeId}) to a LatLng. */
+function routesWaypointLoc(wp: Body | undefined): LatLng | null {
+  if (!wp || typeof wp !== 'object') return null;
+  const latLng = wp.location?.latLng;
+  if (latLng && typeof latLng.latitude === 'number' && typeof latLng.longitude === 'number') {
+    return { lat: latLng.latitude, lng: latLng.longitude };
+  }
+  if (typeof wp.address === 'string' && wp.address.trim()) {
+    if (isZeroResultsQuery(wp.address)) return null;
+    return locOf(wp.address);
+  }
+  if (typeof wp.placeId === 'string') {
+    const p = findPlaceById(wp.placeId);
+    if (p) return p.location;
+    return deterministicLatLng(wp.placeId);
+  }
+  return null;
+}
+
+function handleComputeRoutes(body: Body, mask: string | undefined): GoogleMapsResponse {
+  const oLoc = routesWaypointLoc(body.origin);
+  const dLoc = routesWaypointLoc(body.destination);
+  if (!body.origin || !body.destination) {
+    return rpc(400, 400, 'INVALID_ARGUMENT', 'Both origin and destination are required.');
+  }
+  if (!oLoc || !dLoc) {
+    // A well-formed but unroutable request → 200 with an empty routes set.
+    return { status: 200, body: {} };
+  }
+  const modeEnum = typeof body.travelMode === 'string' ? body.travelMode.toUpperCase() : 'DRIVE';
+  const speedMap: Record<string, number> = { DRIVE: 40, WALK: 5, BICYCLE: 15, TRANSIT: 30, TWO_WHEELER: 35 };
+  const speed = speedMap[modeEnum] ?? 40;
+  const intermediates: LatLng[] = Array.isArray(body.intermediates)
+    ? body.intermediates.map((w: Body) => routesWaypointLoc(w)).filter((l: LatLng | null): l is LatLng => !!l)
+    : [];
+  const pts = [oLoc, ...intermediates, dLoc];
+  let meters = 0;
+  for (let i = 0; i < pts.length - 1; i++) meters += Math.max(1, haversineMeters(pts[i]!, pts[i + 1]!));
+  const secs = Math.max(60, Math.round((meters / 1000 / speed) * 3600));
+  const buildOne = (distM: number, durS: number): Body => ({
+    distanceMeters: distM,
+    duration: `${durS}s`,
+    polyline: { encodedPolyline: encodePolyline(pts) },
+    legs: (() => {
+      const legs: Body[] = [];
+      for (let i = 0; i < pts.length - 1; i++) {
+        const lm = Math.max(1, haversineMeters(pts[i]!, pts[i + 1]!));
+        const ls = Math.max(60, Math.round((lm / 1000 / speed) * 3600));
+        legs.push({
+          distanceMeters: lm,
+          duration: `${ls}s`,
+          polyline: { encodedPolyline: encodePolyline([pts[i]!, pts[i + 1]!]) },
+          startLocation: { latLng: { latitude: pts[i]!.lat, longitude: pts[i]!.lng } },
+          endLocation: { latLng: { latitude: pts[i + 1]!.lat, longitude: pts[i + 1]!.lng } },
+        });
+      }
+      return legs;
+    })(),
+    travelAdvisory: {},
+    routeLabels: [distM === meters ? 'DEFAULT_ROUTE' : 'DEFAULT_ROUTE_ALTERNATE'],
+  });
+  const routes: Body[] = [buildOne(meters, secs)];
+  if (body.computeAlternativeRoutes === true) {
+    routes.push(buildOne(Math.round(meters * 1.1), Math.round(secs * 1.15)));
+  }
+  return { status: 200, body: applyFieldMask({ routes }, mask) };
+}
+
+function handleComputeRouteMatrix(body: Body, mask: string | undefined): GoogleMapsResponse {
+  const origins: Body[] = Array.isArray(body.origins) ? body.origins : [];
+  const destinations: Body[] = Array.isArray(body.destinations) ? body.destinations : [];
+  if (origins.length === 0 || destinations.length === 0) {
+    return rpc(400, 400, 'INVALID_ARGUMENT', 'origins and destinations are required.');
+  }
+  const modeEnum = typeof body.travelMode === 'string' ? body.travelMode.toUpperCase() : 'DRIVE';
+  const speedMap: Record<string, number> = { DRIVE: 40, WALK: 5, BICYCLE: 15, TRANSIT: 30, TWO_WHEELER: 35 };
+  const speed = speedMap[modeEnum] ?? 40;
+  const oLocs = origins.map((o) => routesWaypointLoc(o.waypoint ?? o));
+  const dLocs = destinations.map((d) => routesWaypointLoc(d.waypoint ?? d));
+  const elements: Body[] = [];
+  for (let i = 0; i < oLocs.length; i++) {
+    for (let j = 0; j < dLocs.length; j++) {
+      const o = oLocs[i];
+      const d = dLocs[j];
+      if (!o || !d) {
+        elements.push({ originIndex: i, destinationIndex: j, status: {}, condition: 'ROUTE_NOT_FOUND' });
+        continue;
+      }
+      const m = Math.max(1, haversineMeters(o, d));
+      const s = Math.max(60, Math.round((m / 1000 / speed) * 3600));
+      elements.push({ originIndex: i, destinationIndex: j, status: {}, distanceMeters: m, duration: `${s}s`, condition: 'ROUTE_EXISTS' });
+    }
+  }
+  // computeRouteMatrix returns a bare JSON array (REST). Field mask applies per element.
+  const masked = mask && mask.trim() && mask.trim() !== '*'
+    ? elements.map((e) => applyFieldMask(e, mask))
+    : elements;
+  return { status: 200, body: masked };
+}
+
+// ---- dispatch --------------------------------------------------------------
+
+export async function handleGoogleMapsTwinRequest(req: GoogleMapsRequest): Promise<GoogleMapsResponse> {
+  const method = req.method.toUpperCase();
+  const url = new URL(req.path, 'http://twin.local');
+  let path = url.pathname;
+  // Accept the proxy-prefixed form too.
+  path = path.replace(/^\/api(?=\/)/, '');
+
+  // Legacy web-service APIs gate on `key=`; New/v1/v2 APIs gate on X-Goog-Api-Key.
+  const isV1 = path.startsWith('/v1/') || path.startsWith('/v1:') || path.startsWith('/v1beta') || path.startsWith('/v2:') || path.includes(':computeRoutes') || path.includes(':computeRouteMatrix') || path.includes(':searchText') || path.includes(':searchNearby') || path.includes(':autocomplete');
+  const auth = authenticate(url, req.headers);
+  if (!auth.ok) {
+    if (isV1) return rpc(403, 403, 'PERMISSION_DENIED', auth.message);
+    return maps(auth.status, {}, auth.message);
+  }
+  // Field mask header (Places API New / Routes API): X-Goog-FieldMask.
+  const fieldMask = header(req.headers, 'x-goog-fieldmask');
+
+  // Twin-only inspection surface.
+  if (method === 'GET' && path === '/twin/audit') return { status: 200, body: { entries: auditRows(req.root) } };
+
+  // Twin-only: seed a geocode override (used by the connector / tests).
+  if (method === 'POST' && path === '/twin/geocode') {
+    if (req.readOnly) return { status: 405, body: { error: { code: 405, status: 'METHOD_NOT_ALLOWED', message: 'twin is read-only' } } };
+    const body = parseBody(req.body);
+    const address = String(body.address ?? '');
+    const result = body.result as GeocodeResult | undefined;
+    if (!address || !result) return { status: 400, body: { error: { code: 400, status: 'INVALID_ARGUMENT', message: 'address and result are required' } } };
+    const norm = normalizeAddress(address);
+    const id = `geocode_${stableHash(norm)}`;
+    const row = await applyTwinWrite(SERVICE, {
+      operation: 'geocode.upsert',
+      subjectType: 'geocode',
+      subjectId: id,
+      fields: { id, normalized: norm, address, result },
+      occurredAt: req.occurredAt ?? FIXED_NOW,
+      actor: { kind: 'system' },
+    }, req.root);
+    return { status: 200, body: row };
+  }
+
+  // ----- Legacy Maps web services (maps/api/...) -----
+  if (method === 'GET') {
+    if (path === '/maps/api/geocode/json') {
+      const res = url.searchParams.get('latlng') ? handleReverseGeocode(url) : handleGeocode(url, req.root);
+      await recordAudit(req, { api: 'geocode', status: String((res.body as Body).status), query: url.searchParams.get('address') ?? url.searchParams.get('latlng') ?? '' });
+      return res;
+    }
+    if (path === '/maps/api/distancematrix/json') {
+      const res = handleDistanceMatrix(url);
+      await recordAudit(req, { api: 'distancematrix', status: String((res.body as Body).status) });
+      return res;
+    }
+    if (path === '/maps/api/directions/json') {
+      const res = handleDirections(url);
+      await recordAudit(req, { api: 'directions', status: String((res.body as Body).status) });
+      return res;
+    }
+    if (path === '/maps/api/place/findplacefromtext/json') return handleFindPlace(url);
+    if (path === '/maps/api/place/textsearch/json') return handleTextSearchLegacy(url);
+    if (path === '/maps/api/place/nearbysearch/json') return handleNearbySearch(url);
+    if (path === '/maps/api/place/details/json') return handlePlaceDetails(url);
+    if (path === '/maps/api/place/photo') return handlePlacePhoto(url);
+    if (path === '/maps/api/place/autocomplete/json') return handleAutocomplete(url);
+    if (path === '/maps/api/place/queryautocomplete/json') return handleQueryAutocomplete(url);
+    if (path === '/maps/api/timezone/json') return handleTimeZone(url);
+    if (path === '/maps/api/elevation/json') return handleElevation(url);
+    if (path === '/maps/api/staticmap') return handleStaticMap(url);
+    if (path === '/maps/api/streetview') return handleStreetView(url);
+    if (path === '/maps/api/streetview/metadata') return handleStreetViewMetadata(url);
+    // Roads
+    if (path === '/v1/snapToRoads') return handleSnapToRoads(url);
+    if (path === '/v1/nearestRoads') return handleNearestRoads(url);
+    if (path === '/v1/speedLimits') return handleSpeedLimits(url);
+  }
+
+  if (method === 'POST') {
+    if (path === '/maps/api/geolocation/json' || path === '/geolocation/v1/geolocate') return handleGeolocation(parseBody(req.body));
+    // Places API (New)
+    if (path === '/v1/places:searchText') return handleNewTextSearch(parseBody(req.body), fieldMask);
+    if (path === '/v1/places:searchNearby') return handleNewNearbySearch(parseBody(req.body), fieldMask);
+    if (path === '/v1/places:autocomplete') return handleNewAutocomplete(parseBody(req.body));
+    // Address Validation
+    if (path === '/v1:validateAddress') return handleAddressValidation(parseBody(req.body));
+    // Routes API (New) — v2
+    if (path === '/directions/v2:computeRoutes' || path === '/v2:computeRoutes') return handleComputeRoutes(parseBody(req.body), fieldMask);
+    if (path === '/distanceMatrix/v2:computeRouteMatrix' || path === '/v2:computeRouteMatrix') return handleComputeRouteMatrix(parseBody(req.body), fieldMask);
+  }
+
+  // Place Photo media (New): GET /v1/places/{place_id}/photos/{photo}/media
+  const newPhotoMatch = path.match(/^\/v1\/places\/([^/:]+)\/photos\/([^/:]+)\/media$/);
+  if (method === 'GET' && newPhotoMatch) return handleNewPlacePhotoMedia(url, decodeURIComponent(newPhotoMatch[1]!), decodeURIComponent(newPhotoMatch[2]!));
+
+  // Place Details (New): GET /v1/places/{place_id}
+  const newDetailsMatch = path.match(/^\/v1\/places\/([^/:]+)$/);
+  if (method === 'GET' && newDetailsMatch) return handleNewPlaceDetails(decodeURIComponent(newDetailsMatch[1]!), fieldMask);
+
+  // Unmodeled op fails like the vendor.
+  if (isV1) return rpc(404, 404, 'NOT_FOUND', `Operation not modeled: ${method} ${path}`);
+  return maps('INVALID_REQUEST', {}, `Operation not modeled: ${method} ${path}`);
+}