google-maps-js-3d

name	google-maps-js-3d
description	Use for focused Google Maps JavaScript API 3D Maps work in strava-explorer, including Map3DElement, maps3d importLibrary loading, 3D camera animation and restrictions, Marker3DElement and Marker3DInteractiveElement, PopoverElement, Polyline3DElement and Polygon3DElement, altitude modes, Places widgets on 3D maps, performance, quota, accessibility, and release-channel checks.

Google Maps JavaScript API 3D

Use this repo-local skill when a task changes 3D Maps rendering, interaction, camera behavior, overlays, or 3D-specific Google Maps Platform usage in demos/strava-explorer/.

Quick workflow

1. Read the relevant app files first:
   • demos/strava-explorer/src/gmp.js for loader setup, maps3d imports, map creation, route/photo rendering, elevation, and camera helpers.
   • demos/strava-explorer/src/followCamera.js for route-follow camera animation.
   • demos/strava-explorer/src/index.js for UI orchestration and helper injection.
   • demos/strava-explorer/index.html for map host, sidebar controls, elevation widget, and responsive structure.
2. Check the official docs or the local technical reference before changing 3D API behavior, especially when touching alpha/beta-only APIs.
3. Keep API loading centralized. Do not add duplicate Maps script tags or a second loader.
4. Import 3D classes with await google.maps.importLibrary("maps3d") after the existing loader resolves.
5. Validate code changes with npm run build from demos/strava-explorer/.
6. For visible 3D/camera changes, run the app and capture a screenshot or manual QA note when the environment allows it.

Load detailed 3D guidance when needed

Read references/3d-maps-js-api.md when the task involves:

• Map3DElement, camera options, flyCameraTo, flyCameraAround, or camera restrictions.
• Marker3DElement, Marker3DInteractiveElement, accessible markers, custom markers, collision behavior, or marker performance.
• PopoverElement behavior, marker-attached popovers, coordinate-anchored popovers, or popover accessibility.
• Polyline3DElement, Polygon3DElement, interactive overlays, AltitudeMode, geodesic/extruded drawing, or route visualization.
• Places Autocomplete or Places UI Kit on 3D maps.
• Release-channel decisions, quota/performance risk, or browser/runtime compatibility.

Core rules

• Prefer MapMode.HYBRID/MapMode.SATELLITE constants when available instead of stringly typed modes.
• Treat 3D positions as latitude/longitude/altitude values when altitude matters; document whether altitude is clamped, absolute, or relative.
• Prefer Marker3DInteractiveElement for clickable 3D markers and Marker3DElement for large passive marker sets.
• For Marker3DInteractiveElement custom content, append a PinElement or an HTMLTemplateElement whose direct content is an HTMLImageElement or SVGElement. Do not place a div, span, text node, HTML/CSS card, or other wrapper inside the template; Maps 3D validates the template content type and emits <gmp-marker-3d-interactive>: The content inside the <template> element is not of type HTMLImageElement or SVGElement when the direct child is not an image or SVG.
  • CRITICAL: When using PinElement, you must append the PinElement instance directly (e.g. marker.append(pin)). In modern Maps SDKs, PinElement extends HTMLElement directly. Calling the deprecated .element property or attempting to append a non-DOM object triggers infinite recursion and a RangeError: Maximum call stack size exceeded crash in the custom element observer.
  • CRITICAL: When setting a custom URL or image on a PinElement, use glyphSrc (which natively accepts a URL string) instead of the deprecated glyph property to avoid console deprecation warnings and serialization errors in the WebGL context.
• For terrain-friendly visual callouts, prefer AltitudeMode.RELATIVE_TO_GROUND with a fixed visual offset. Do not add Elevation API terrain altitude to a relative-to-ground marker position.
• Use gmp-click for 3D interactive elements that expose Maps event semantics.
• Use PopoverElement for map-anchored details; include concise accessible content and a meaningful header when practical.
• Use Polyline3DElement or Polygon3DElement for 3D route/area rendering; choose AltitudeMode.CLAMP_TO_GROUND for terrain-following activity routes unless product requirements say otherwise.
• Handle camera animation interruptions quietly; do not show user-facing errors for normal cancellation.
• Respect prefers-reduced-motion for cinematic, auto-follow, orbit, or long camera animations when practical.
• Avoid per-frame network calls and unbounded marker/polyline/popover creation.
• Never log API keys, Strava tokens, precise private routes, or raw OAuth payloads.

Custom marker slot validation

Official Maps JavaScript API 3D docs currently limit custom 3D marker drawing to PinElement, HTMLImageElement, and SVGElement content. If using a template, the template must wrap the image or SVG itself, not an HTML card that contains an image. For remote activity-photo markers, prefer a direct HTMLImageElement template child. The Maps 3D/WebGL renderer still needs the image to be CORS-readable; Strava CloudFront photo URLs do not send Access-Control-Allow-Origin, so deployed marker images should go through the app's same-origin/CORS-enabled photo proxy before being used as marker content. Embedding the remote bitmap as an SVG <image> can render as a generic placeholder in the 3D marker renderer even though the outer SVGElement passes type validation. Plain HTML and CSS marker cards are not supported in the 3D marker renderer yet.

Strava route fly-through guidance

• Default follow-camera smoothing should balance steadiness with tracking accuracy; avoid LERP values so low that the camera visibly trails the target route point.
• Blend current route bearing with multiple look-ahead samples, then apply a frame-rate-aware yaw-rate limit to reduce abrupt heading snaps on switchbacks and dense GPS traces.
• Prefer route stream altitude data when available, then fall back to batched Google Elevation lookups; never perform elevation calls per animation frame.
• Keep camera settings user-adjustable, but make defaults good enough for immediate playback after activity load. Keep default values synchronized across src/followCamera.js, src/index.js, and index.html.
• Scale follow-camera duration by route distance and sample nearby/future terrain elevations around the camera target so default pace and clearance remain comfortable on both short and long routes. Reset filtered heading state when loading or clearing a route.

PR checklist

• Note any release-channel assumption (alpha, beta, weekly, or quarterly).
• List enabled APIs/libraries and browser API-key restrictions affected by the change.
• Document quota-sensitive calls such as Elevation, Places, Routes, or geocoding.
• Include validation commands and any manual browser/API behavior that could not be tested.