Maps Provider Operations

Wavemap currently uses the Google Maps JavaScript API as its basemap, projection, and camera provider. Wavemap owns the public Venue projection, custom markers and clusters, summaries, controls, localized content, publication policy, and fallback behavior.

Use Maps for the application architecture. This page owns the environment and release posture around the third-party provider.

Configuration Ownership

Build input	Classification	Purpose
`NEXT_PUBLIC_GOOGLE_MAPS_API_KEY`	Restricted public	Browser key for the Maps JavaScript API.
`NEXT_PUBLIC_GOOGLE_MAPS_MAP_ID`	Restricted public	Environment-owned JavaScript map ID used by Advanced Markers.
`NEXT_PUBLIC_GOOGLE_PLACES_API_KEY`	Restricted public	Browser key for supported Places provider requests.

These values are embedded in browser-delivered frontend code. They cannot be secret at runtime. Wavemap still routes them through the non-logged restricted-public build-input lane so they are not committed, copied into routine workflow summaries, or confused with GitHub deploy-bootstrap values.

Local values belong in the developer environment. Deployed values belong to the environment-owned Pulumi secret/config and frontend-build-input contract. Pulumi writes the three Development values as SecureString parameters under /wavemap/dev/build/frontend/; the sanitized deployment contract carries only their paths and value kind. After OIDC authentication, each frontend delivery lane reads those exact paths, masks the values, and writes them to the job environment immediately before the image build. Use separate reviewed configuration per development, preview, and production origin.

Pre-Activation Checklist

Complete these checks in Google Cloud and the deployed browser before enabling maps publicly:

Restrict the browser key with the Websites application restriction and list only the exact authorized HTTP/HTTPS origins, including scheme and any non-default port used by a development environment.
Restrict the key to the Maps JavaScript API and only the additional APIs deliberately used through that same key. Prefer another key when a separate app or platform has a different restriction or quota boundary.
Confirm the expected billing account, Maps JavaScript API enablement, and environment-specific map ID.
Inspect usage by credential and API before tightening an already-used key so legitimate traffic is understood.
Load Venue Index and Venue Details from the deployed origin. Confirm provider readiness, tiles, custom markers, controls, appearance variants, and visible attribution.
Force or simulate provider failure. Confirm Venue content and grid/list discovery remain usable and the failure stays inside the map region.
Complete the CSP and privacy/consent gates below.

Google’s current Maps Platform security guidance recommends both application and API restrictions and separate keys where app boundaries differ. Treat browser key visibility as expected client configuration, not permission to leave it unrestricted.

Quota, Billing, And Alerts

Before public activation:

Record the expected map-load volume for each environment.
Set credential/API usage dashboards and metric-threshold alerts.
Set billing budgets and forecast/actual-cost alerts for the owning project.
Review Maps JavaScript API quotas and configure enough headroom for normal peaks without making an abusive spike unbounded.
Assign an operator owner for alert response and key restriction review.

Budget alerts notify; they do not stop charges by themselves. Quota limits can stop service, so a hard cap is also an availability decision. Follow current Google guidance in Maps Platform Monitoring and Manage Google Maps Platform Costs rather than copying a dated price or quota value into Wavemap docs.

Attribution And Policy

Provider attribution is provider-owned UI. Wavemap controls and summaries must reserve visible space for it and must not hide, obscure, restyle, move, or intercept it. Verify this at every supported breakpoint and after summary-card/sheet layout changes.

Publicly accessible Terms of Use and Privacy Policy surfaces must incorporate the applicable provider requirements before launch. Recheck the current Maps JavaScript API policies and attribution requirements when provider content, styling, Places data, photos, reviews, or deployment geography changes.

Wavemap does not persist provider camera, marker, cluster, overlay, or inferred location data as domain truth. Ordinary Venue reads use persisted Wavemap coordinates and do not call Google.

CSP And Privacy

The local Venue route did not emit a Content-Security-Policy header during the 2026-08-21 M4 evidence capture. CSP is therefore a deployed activation gate, not a completed property inferred from a successful local map.

Use a report-only rollout first, capture violations from the deployed origin, and follow Google’s current Maps JavaScript API CSP guide. Google recommends a nonce-based strict CSP. An allowlist policy requires continued review of provider domains and release notes; do not freeze a copied domain list in this page and assume it remains complete.

Map consumers load third-party scripts, tiles, fonts, telemetry/probes, and related requests. Before public launch:

Inventory provider requests from a clean browser on each supported map surface.
Update the public privacy and terms surfaces with reviewed provider disclosure.
Decide whether regional consent, opt-in loading, or another jurisdiction-specific treatment is required.
Confirm that declining or blocking provider loading leaves ordinary Venue content and grid/list discovery useful.

Policy or consent decisions require the appropriate product/legal review. A frontend implementation pass cannot close that gate by assertion.

Provider Smoke

The repository owns an opt-in clean-Chromium smoke:

PLAYWRIGHT_ENABLE_GOOGLE_MAPS_PROVIDER_SMOKE=true \
  pnpm -C apps/wavemap-front-end exec playwright test \
  test/e2e/maps/google-maps-provider.e2e.test.ts --project=chromium --reporter=list

It verifies provider readiness, light/dark provider recreation with camera continuity, clustered map rendering, attribution presence through screenshots, and mounted-canvas alignment at desktop, tablet, and mobile sizes. Run it from a reviewed local environment or against an explicitly selected deployment. Do not put a live provider credential into ordinary CI merely to make this test automatic.

Also capture a warmed production-build measurement before launch. Local development compilation and provider-network variability make a dev-server navigation time unsuitable as a production SLO.

Incident Triage

`ERR_BLOCKED_BY_CLIENT` On `gen_204?csp_test=true`

This status means the browser client intercepted Google’s CSP probe; it does not identify a specific extension and does not, by itself, prove that the map failed.

Check the app-owned runtime state and whether tiles, controls, markers, and attribution became visible.
Reproduce in the repository Playwright Chromium or a fresh browser profile with extensions disabled.
Re-enable extensions one at a time if the problem exists only in the regular profile.
Treat it as an application incident only when clean-profile map readiness or required provider resources also fail.

Authorization Or Key Errors

Use the browser console and Google’s current Maps JavaScript API error messages. Check the deployed request origin, Website restriction, Maps JavaScript API restriction, enabled API, billing account, map ID, and which key was embedded into the exact frontend revision. Never paste the key into an issue or routine log.

Map Ready But Visually Blank

Measure the map runtime, provider wrapper, and provider canvas rectangles. A provider can be ready while a nested percentage-height canvas remains smaller than its flex-grown parent. Confirm non-zero aligned width/height before changing credentials, queries, or clustering.

Quota Or Provider Outage

Confirm the provider error, credential/API usage metrics, and quota state. Keep the failure isolated to the map region and direct users to grid/list discovery. Do not bypass restrictions or silently swap in inferred coordinates as an incident workaround.

Attribution Obscured

Remove or resize the app-owned overlap. Recalculate visible camera insets for controls and summary surfaces; do not move or cover provider legal UI.

Current Gate Status

Gate	M4 status
Environment-owned restricted-public inputs	Repository contract and delivery resolution present; live values and contract publication still require operator activation.
Clean-browser provider integration	Locally proven on 2026-08-21.
Provider failure isolation	Deterministic component/browser proof present.
Responsive attribution and canvas containment	Locally proven at desktop, tablet, and mobile sizes.
Google Cloud origin and API restrictions	Must be verified per deployed environment.
Billing, quota headroom, and alerts	Must be verified per Google Cloud project.
Deployed CSP	Pending report-only design and deployed-origin proof.
Public privacy/terms and regional consent	Pending product/legal review.
Production-build loading and payload telemetry	Pending a representative deployment and real-media corpus.

Do not describe maps as publicly activated until every environment-relevant gate is complete.

What Makes This Page Stale

Review this page when the provider, browser key, map ID, frontend-build-input ownership, public origin, provider APIs, CSP posture, privacy/consent decision, quota policy, or provider smoke changes.