commit f0ad8481c455fad98429ada90dc80b114aa18e93 Author: Jiří Stach Date: Mon Oct 12 21:37:22 2026 +0200 Prototype app made by google ai studio diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..c8a8e14 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,13 @@ +node_modules +dist +.git +.gitignore +.gmp_cache +.env +.env.local +.DS_Store +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +.aistudio diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..64d9df3 --- /dev/null +++ b/.env.example @@ -0,0 +1,33 @@ +# GEMINI_API_KEY: Required for Gemini AI API calls. +# AI Studio automatically injects this at runtime from user secrets. +# Users configure this via the Secrets panel in the AI Studio UI. +GEMINI_API_KEY="MY_GEMINI_API_KEY" + +# APP_URL: The URL where this applet is hosted. +# AI Studio automatically injects this at runtime with the Cloud Run service URL. +# Used for self-referential links, OAuth callbacks, and API endpoints. +APP_URL="MY_APP_URL" + +# VITE_GOOGLE_MAPS_API_KEY: Required for Google Maps satellite imagery, +# live GPS hole rangefinding (front/middle/back green distances), and course visualization. +VITE_GOOGLE_MAPS_API_KEY="YOUR_GOOGLE_MAPS_API_KEY" + +# JWT_SECRET: Secret key used to sign session JWT tokens +JWT_SECRET="pinpoint_golf_super_secret_jwt_key_2026" + +# ======================================================== +# OAuth & SSO Configuration (Optional) +# ======================================================== + +# Google OAuth 2.0 Credentials +GOOGLE_CLIENT_ID="" +GOOGLE_CLIENT_SECRET="" + +# Authentik / OIDC Configuration (Self-Hosted Homelab or Enterprise SSO) +AUTHENTIK_ISSUER_URL="https://authentik.company.local/application/o/pinpoint-golf/" +AUTHENTIK_CLIENT_ID="" +AUTHENTIK_CLIENT_SECRET="" + +# GitHub OAuth Credentials +GITHUB_CLIENT_ID="" +GITHUB_CLIENT_SECRET="" diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5a86d2a --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +node_modules/ +build/ +dist/ +coverage/ +.DS_Store +*.log +.env* +!.env.example diff --git a/.gmp_cache/compliance-review.md b/.gmp_cache/compliance-review.md new file mode 100644 index 0000000..f62d6b1 --- /dev/null +++ b/.gmp_cache/compliance-review.md @@ -0,0 +1,162 @@ +--- +name: compliance-review +description: Use this skill to review implementation plans or code that uses Google Maps Platform in order to identify revisions that need to be made based on Google Maps Platform Terms of Service, Acceptable Use Policy, EEA terms, AI terms, and deprecation policies. Use this skill each time there is a significant revision to an implementation plan or code such as a change in the Google Maps Platform products selected or the handling of responses from Google Maps Platform. +license: Apache-2.0 +metadata: + version: 1.1.0 +--- + +# Google Maps Platform: Terms of Service Check Methodology + +This skill provides a step-by-step, methodical procedure for verifying that a +customer application's architectural design and code conform to all applicable +Google Maps Platform and Google Cloud Platform (GCP) terms, policies, and +regional restrictions. + +## Methodical Compliance Review Procedure + +Follow these four steps sequentially to evaluate any Google Maps Platform +proposal, code suggestion, or architectural design. + +### Step 1: Regional & Territory Restriction Check + +Verify whether the application's intended target audience, deployment, or +billing profile conflicts with regional restrictions. + +1. **Prohibited Territories Check:** Confirm the Customer Application is not + distributed, marketed, or functional within any of the prohibited + territories. + * **Prohibited Territories:** China, Crimea, Cuba, Donetsk People's + Republic, Iran, Luhansk People's Republic, North Korea, Syria, and + Vietnam. + * *Reference:* + [Google Maps Platform Prohibited Territories](https://cloud.google.com/maps-platform/terms/maps-prohibited-territories?utm_campaign=gmp_git_agentskills_v1) +2. **Regional Terms Check:** If the customer billing address is in one of the + regions listed in the Regional Terms section of the Google Maps Platform + Terms of Service, those terms supersede the main Google Maps Platform Terms + of Service. + * *Reference:* + [Google Maps Platform Terms of Service](https://cloud.google.com/maps-platform/terms?utm_campaign=gmp_git_agentskills_v1) +3. **European Economic Area (EEA) Check:** Determine if the billing account + address of the customer is within the EEA (EU Member States + Iceland, + Liechtenstein, and Norway). If yes, apply EEA-specific rules: + * **Relaxed Rules:** Under the FCO4 commitment (active until July 8, + 2035), EEA customers are not subject to standard restrictions + prohibiting: + 1. Re-creating Google products/features + 2. Combining Google Maps Platform content with non-Google maps (subject + to specific exceptions) + 3. Using Google Maps Platform in embedded vehicle systems + * **Strict Places API Rules:** Non-geospatial Places data (excluding + lat/lng and place_id) is restricted to the specific permitted use cases + (such as address autocompletion, store finders, social tagging). + * **No Decision-Making:** Results from the Places Aggregate API must not + be used to make decisions impacting individuals' rights (e.g., credit, + housing, employment, or insurance scores). + * *Reference:* + [Google Maps Platform EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea?utm_campaign=gmp_git_agentskills_v1) + * *Reference:* + [Google Maps Platform EEA Service Specific Terms](https://cloud.google.com/terms/maps-platform/eea/maps-service-terms?utm_campaign=gmp_git_agentskills_v1) + * *Reference:* + [Places API EEA Permitted Uses](https://cloud.google.com/terms/maps-platform/eea-places-api-permitted-uses?utm_campaign=gmp_git_agentskills_v1) + +### Step 2: Generative AI & Model Training Check + +Assess whether the project introduces artificial intelligence, machine learning, +or generative model integrations. + +1. **No Derived Content / Training Prohibition:** Ensure that Google Maps + Content (including business names, reviews, coordinates, or elevation + models) is **never** used to train, fine-tune, or improve machine learning + or AI models. +2. **AI Integration Terms:** If the application uses Generative AI (e.g., + Gemini API) alongside Google Maps Platform data, verify compliance with both + AI-specific terms and standard cloud guidelines. + * *Reference:* + [Google Generative AI Additional Terms of Service](https://policies.google.com/terms/generative-ai?utm_campaign=gmp_git_agentskills_v1) + * *Reference:* + [Google Cloud Service Specific Terms (Generative AI Section)](https://cloud.google.com/terms/service-terms?utm_campaign=gmp_git_agentskills_v1) + +For projects involving artificial intelligence and generative content, consider +Grounding products and Agentic UI toolkit listed at +http://developers.google.com/maps/ai. + +### Step 3: Layered Document Checklist (The 5 Pillars) + +Methodically cross-reference the application's features against the five core +governing documents of the Google Maps Platform ecosystem. + +1. **Google Maps Platform Terms of Service (Main ToS):** Check billing + requirements, basic license grants, and general usage rights. + * *Reference:* + [Google Maps Platform Terms of Service](https://cloud.google.com/maps-platform/terms?utm_campaign=gmp_git_agentskills_v1) +2. **Maps Service Specific Terms:** Verify product-specific restrictions: + * **Caching Limits:** Check if caching is permitted. Geospatial data + (lat/lng) is typically limited to **30 consecutive calendar days**. + Check the specific table for environmental APIs (Air Quality, Solar, + Pollen, Weather). + * **No Scraping:** Ensure bulk downloads or indexing of Google Maps + Content is not proposed. + * *Reference:* + [Maps Service Specific Terms](https://cloud.google.com/maps-platform/terms/maps-service-terms?utm_campaign=gmp_git_agentskills_v1) +3. **Google Cloud Platform Terms of Service (Cloud ToS):** Check general GCP + rules, resource quotas, and API credential management. + * *Reference:* + [Google Cloud Platform Terms of Service](https://cloud.google.com/terms?utm_campaign=gmp_git_agentskills_v1) +4. **Google Privacy Policy & End User Terms:** Confirm that the application's + terms explicitly state that it integrates Google Maps features and is + subject to the End User Terms. Verify that location tracking requires + explicit, revocable end-user consent. + * *Reference:* + [Google Maps End User Additional Terms of Service](https://maps.google.com/help/terms_maps/?utm_campaign=gmp_git_agentskills_v1) + * *Reference:* + [Google Privacy Policy](https://policies.google.com/privacy?utm_campaign=gmp_git_agentskills_v1) + * *Reference:* + [Google Controller-Controller Data Protection Terms](https://business.safety.google/controllerterms/?utm_campaign=gmp_git_agentskills_v1) +5. **Google Acceptable Use Policy (AUP):** Ensure that the service is not used + for prohibited use cases: + * **High Risk Activities:** Banned from emergency services, autonomous + vehicle routing, aviation, and nuclear facility control. + * **COPPA:** Banned from child-directed applications. + * **Sensitive Data:** Banned from handling ITAR-regulated or + HIPAA-regulated medical records. + * *Reference:* + [Google Maps Platform Acceptable Use Policy](https://cloud.google.com/maps-platform/terms/aup?utm_campaign=gmp_git_agentskills_v1) + +### Step 4: Lifecycle, SLA, and Deprecation Review + +Identify the support commitments and deprecation risks for all APIs proposed in +the architecture. + +1. **Launch Stages Verification:** Identify if the APIs proposed are General + Availability (GA) or Pre-GA (Preview, Alpha, Beta). + * **Pre-GA Rules:** Pre-GA offerings are provided "as-is", do not qualify + for Service Level Agreements (SLAs), and do not carry technical support + commitments. + * *Reference:* + [Google Cloud Launch Stages](https://cloud.google.com/terms/launch-stages?utm_campaign=gmp_git_agentskills_v1) +2. **Service Level Agreement (SLA):** For GA Core Services, verify the Uptime + SLO (generally 99.9%). + * *Reference:* + [Google Maps Platform SLA](https://cloud.google.com/maps-platform/terms/sla?utm_campaign=gmp_git_agentskills_v1) + * *Reference:* + [Google Maps Platform Core Services Summary](https://cloud.google.com/maps-platform/terms/maps-services?utm_campaign=gmp_git_agentskills_v1) +3. **Deprecation Policy:** GA Core Services are subject to deprecation + protection, requiring a deprecation notice (typically 12 months) before + decommissioning. + * *Reference:* + [Google Cloud Service Specific Terms (Deprecation Policy)](https://cloud.google.com/terms/service-terms?utm_campaign=gmp_git_agentskills_v1) +4. **Open Source Client Library Exception:** Proactively alert developers that + the standard enterprise deprecation policies **do not apply** to + Google-maintained open-source client libraries. These libraries are updated + under semantic versioning and the OSS Library Breaking Change Policy, + meaning breaking changes are signaled via major version bumps (e.g., v1 to + v2) rather than a formal deprecation schedule. + * *Reference:* + [Google Open Source Library Breaking Change Policy](https://opensource.google/documentation/reference/releasing/versioning?utm_campaign=gmp_git_agentskills_v1) + +## Technical Support Guidelines + +* Refer to the + [Technical Support Services Guidelines (TSSG)](https://cloud.google.com/maps-platform/terms/tssg?utm_campaign=gmp_git_agentskills_v1) + to check eligibility for ticket logging, response times, and escalations. diff --git a/.gmp_cache/gmp-framework-react.md b/.gmp_cache/gmp-framework-react.md new file mode 100644 index 0000000..5cf724f --- /dev/null +++ b/.gmp_cache/gmp-framework-react.md @@ -0,0 +1,406 @@ +--- +name: gmp-framework-react +description: This guide serves as the mandatory entry point and architectural router for building Google Maps Platform applications using the **React** framework, specifically leveraging the official `@vis.gl/react-google-maps` SDK and modern API features. The content is rigorously curated to enforce the **Absolute Universal Zero-Legacy Mandate**, ensuring all generated solutions utilize current, future-proof, cost-optimized, and performant APIs. Developers are proactively guided toward modern replacements like `AdvancedMarkerElement`, the `Place` class (Places API New), and the `Route` class (Routes API), strictly forbidding any reliance on deprecated or disabled callback-based services. This router ensures comprehensive coverage of React patterns, from basic initialization to complex data visualization and clustering techniques. +license: Apache-2.0 +metadata: + version: 1.0.69 +--- + +> [!IMPORTANT] **Core Dependency:** This skill requires active context from +> [google-maps-platform/SKILL.md](https://www.gstatic.com/googlemapsplatform-agent-skills/google-maps-platform/SKILL.md). + +# Google Maps Platform for React Developers + +This document details the recommended architectural patterns and reference +implementations for integrating Google Maps Platform into React applications +using the official **@vis.gl/react-google-maps** SDK. All solutions presented +adhere to the zero-legacy mandate, utilizing only modern, promise-based APIs. + +## Architecture and Core Principles + +The Google Maps Platform engineering team mandates the use of +**`@vis.gl/react-google-maps`** for all React implementations. This SDK provides +declarative component wrappers and specialized hooks for managing the map state +and interacting with core libraries. + +**Core Principles for React Development:** + +1. **Modern SDK Only:** Use `@vis.gl/react-google-maps` exclusively. Libraries + like `react-google-maps/api` or `google-map-react` are prohibited. (CF5) +2. **Zero-Legacy Enforcement:** Never use callback-based services + (`DirectionsService`, `PlacesService`, `Marker`). Use the modern, + promise-based equivalents (Routes API, Places API New, + `AdvancedMarkerElement`). +3. **Map ID Requirement:** When using `AdvancedMarkerElement`, a `mapId` (e.g., + `"DEMO_MAP_ID"`) is mandatory on the `` component. (CF9) +4. **Imperative Web Components:** When integrating Google Maps Platform Web + Components (e.g., `PlaceAutocompleteElement`) into React, they must be + mounted imperatively using `useRef` and `useEffect` to ensure complex + objects are passed correctly, avoiding the JSX attribute stringification + trap. (CF8) + +## Table of Contents + +The following references provide detailed, modern implementation patterns for +the React framework: + +### I. Initialization and Core Setup + +Topic | Description | Reference Link +:-------------------------- | :------------------------------------------------------------------------------------------ | :------------- +**Basic Rendering** | Step-by-step guide for basic map initialization and rendering within a React component. | [Basic Initialization and Rendering of Google Maps in React](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_basic.md) +**API Provider Pattern** | Comprehensive pattern for API key loading, context provision, and library loading in React. | [React Wrapper Pattern for Google Maps Platform API Initialization](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_react.md) +**Next.js Integration** | Specific initialization and rendering patterns optimized for Next.js environments. | [Core Initialization and Declarative Map Rendering in Next.js](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_nextjs.md) +**Remix Integration** | Integration and modern SDK patterns tailored for the Remix framework. | [React/Remix Integration and Modern Google Maps Platform SDK Patterns](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_remix.md) +**Multi-Map Sync** | Techniques for synchronizing camera state and viewport across multiple map instances. | [Multi-Map View Synchronization using React Camera State](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_multiple.md) +**Styling & Configuration** | Dynamically changing map options, themes, and styles post-initialization. | [Dynamic Map Styling and Configuration in React Google Maps SDK](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_change.md) +**External Libraries** | Patterns for integrating non-GMP libraries (like Terra Draw) and deferred initialization. | [Patterns for External Library Integration and Deferred Map Initialization using React Hooks](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_terra.md) + +### II. Markers, Clustering, and Data Visualization + +Topic | Description | Reference Link +:----------------------------------- | :------------------------------------------------------------------------------------------------ | :------------- +**Advanced Marker Usage** | Core usage patterns for the modern `AdvancedMarkerElement` and `InfoWindow`. | [Google Maps Platform React Marker and InfoWindow Usage Patterns](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_markers.md) +**Advanced Interaction** | Handling custom interactions, z-index, and anchoring for `AdvancedMarkerElement` and InfoWindows. | [Advanced Marker Interaction, Z-Index Management, and InfoWindow Anchoring](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_advanced.md) +**Advanced Clustering** | High-performance clustering solutions using the official marker clustering library. | [React Google Maps: Advanced Marker Clustering and State Management](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_marker.md) +**Custom Clustering (Supercluster)** | Integrating external clustering logic (Supercluster) with map viewport hooks. | [React Custom Marker Clustering Pattern using Supercluster and `useMapViewport`](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_custom.md) +**Web Worker Clustering** | Offloading heavy clustering logic to web workers for maximum performance. | [React Web Worker Marker Clustering using `useSuperclusterWorker` and Advanced Markers](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_worker.md) +**Deck.gl Overlays** | Integrating high-performance 3D and 2D visualization layers using Deck.gl. | [Integrating Deck.gl Overlays with @vis.gl/react-google-maps](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_deckgl.md) + +### III. Geospatial Services (Routes and Places API New) + +Topic | Description | Reference Link +:------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------- | :------------- +**Modern Routing (Routes API)** | **Mandatory** pattern for calculating and rendering routes using `Route.computeRoutes`. (Legacy `DirectionsService` is prohibited). | [Modern Route Calculation and Rendering in React using `@vis.gl/react-google-maps`](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_directions.md) +**Routes API Patterns** | Detailed integration of the promise-based Routes API library in React. | [Google Maps Platform Routes API Integration Patterns in React](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_routes.md) +**Place Autocomplete** | Implementing address search using the modern, promise-based `AutocompleteSuggestion` and `Place.fetchFields`. | [Modern React Autocomplete Patterns using `AutocompleteSuggestion` and `Place.fetchFields`](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_autocomplete.md) +**Places UI Kit** | Wrapping the Places and 3D UI Kit web components in React for dynamic usage. | [React Wrapper Patterns for Google Maps Platform UI Kit (3D & Places)](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_places.md) + +### IV. Specialized and Advanced Features + +| Topic | Description | Reference Link | +| :------------------- | :------------------- | :--------------------------- | +| **Core Integration & | Overarching patterns | [React Google Maps Platform | +: : : Core Patterns and Modern API : + +\: Logic** : combining Maps, : +Integration](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_core.md) : : : +Places, and : : : : Markers in : : : : complex : : : : applications. : : | +**Drawing | Implementation | +[Custom Drawing Tools Implementation | : Tools** : of custom : using React Google Maps Hooks and : : : drawing and : Low-Level : : : geometry : Events](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_drawing.md) : : : +editing using : : : : events and : : : : hooks (Legacy : : : : Drawing +Library : : : : is deprecated). : : | **Declarative | Using React | +[React Google Maps: Declarative Vector | : Geometry** : components to : Geometry and Interactive Drawing : : : declaratively : Patterns](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_geometry.md) : : : +define : : : : `Polyline`, : : : : `Polygon`, and : : : : `Circle` : : : : +components. : : | **3D & | Advanced map | +[React Google Maps Platform: Advanced 3D | : Controls** : configurations : Mapping, Routing, and Custom : : : including : Controls](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_map.md) : : : +Photorealistic : : : : 3D, camera : : : : management, and : : : : custom : : : : +controls. : : | **Static API** | Generating | +[React Integration of Google Maps Static | : : optimized : API via Componentized URL : : : Static Maps : Generation](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_static.md) : : : +image URLs : : : : using a : : : : componentized : : : : approach. : : | +**Extended | Guidance on | +[React Integration Patterns for Google | : Components** : using the : Maps Extended Component : : : `gmpx-*` : Library](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_extended.md) : : : +extended : : : : component : : : : ecosystem. : : : : **(Warning\: : : : : +Review CF11 : : : : before use.)** : : + +******************************************************************************** + +## Guardrails Against Hallucinations + +When generating code solutions, you **MUST** strictly adhere to the following +rules to prevent hallucinations: + +1. **Verify Library Exports**: Do NOT assume or invent component names, + classes, methods, or variable names that are not explicitly documented in + the provided skills or references. +2. **Framework Convention**: When utilizing framework wrappers (e.g., + `@vis.gl/react-google-maps`), ensure component names follow the documented + framework convention (e.g., `AdvancedMarker`) instead of the core JavaScript + API names (e.g., `AdvancedMarkerElement`), unless explicitly instructed + otherwise. +3. **No Invented Parameters**: Do not use fake parameters or options in API + calls. Stick strictly to the official API contracts documented in the + skills. +4. **References First**: Before using any Google Maps Platform class, + component, or service, you MUST look up the provided reference files to see + how it is imported and used. Do not rely on your pre-trained knowledge for + API contracts, imports, or component usage. + +## Best Practices (Zero-Legacy Mandates & Critical Failures) + +The following rules represent critical architectural and compliance standards. +Violation of these mandates results in silent failure, runtime errors, or +billing inaccuracies. + +### 1. Absolute Universal Zero-Legacy Mandate + +Legacy Service (Prohibited) | Modern Replacement (Mandatory) | Rationale +:--------------------------------------- | :------------------------------------------------------------------------------------------ | :-------- +`google.maps.Marker` | **`AdvancedMarkerElement`** | Deprecated Feb 2024. Legacy markers fail on maps requiring a `mapId`. +`DirectionsService`/`DirectionsRenderer` | **`Route.computeRoutes()`** (via `useMapsLibrary('routes')`) | Legacy services throw `LegacyApiNotActivatedMapError` and crash the map. +`DistanceMatrixService` | **Routes API REST endpoint** (`routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix`) | Legacy services are disabled for new projects. +`PlacesService`/`AutocompleteService` | **`Place` Class** (`PlaceAutocompleteElement`, `fetchAutocompleteSuggestions`) | Legacy Places endpoints return no predictions and will be fully disabled. +Client-side `fetch()` to Maps REST APIs | **Official SDK Wrappers or Server-Side Proxy** | CORS Trap (CF1): Client-side `fetch` is blocked for most modern REST endpoints. + +### 2. Mandatory React Framework Conventions + +* **Required SDK (CF5):** All solutions **MUST** use the official React + wrapper: `@vis.gl/react-google-maps`. +* **Web Component Imperativity (CF8):** When working with GMP Web Components + (like ``), use `useRef` and `useEffect` to set + object properties on the underlying DOM element directly. Do not pass + complex objects as JSX props, as React stringifies them. +* **Map Height (CF2):** The `` component requires explicit CSS styling + (e.g., `height: 100vh` or a sized parent) otherwise it collapses to 0x0 + pixels. +* **`mapId` Requirement (CF9):** If using `AdvancedMarkerElement`, a `mapId` + (Cloud-styled or `"DEMO_MAP_ID"`) is mandatory on the `` component. + +### 3. Usage & Optimization + +* **Cost Awareness:** Always utilize session tokens (e.g., + `AutocompleteSessionToken`) when chaining Autocomplete and Place Details + requests to optimize billing. +* **Attribution ID:** Ensure the attribution ID `gmp_git_agentskills_v1` is + set on the `` or `` component + (`internalUsageAttributionIds={["gmp_git_agentskills_v1"]}`). +* **Locale (CF10):** For non-local requests, explicitly set the `language` and + `region` on the `` to ensure consistent results. + +### Mandatory settings + +For all applications built using the React component framework, the internal +usage attribution ID `gmp_git_agentskills_v1` is a mandatory property required +for accurate usage tracking. This must be applied directly to the primary map +components (`` or ``). + +#### React Prop on `` or `` components + +Apply the required attribution ID using the `internalUsageAttributionIds` array +prop on the main mapping component. + +```jsx +// Used with the standard 2D map component + + {/* Markers rendered here */} + +``` + +```jsx +// Used with the 3D map component + +``` + +## 🚀 Master Orchestration Integration Workflow + +Follow this multi-phase sequential integration checklist to compose features +robustly. For each phase, read the referenced sub-workflow reference file and +satisfy its *Verification Checkpoint* before advancing. + +### 📦 Phase 1: Core Initialization & Base Setup (Primary) + +- [ ] **Step 1.1: Core Setup - React Google Maps Platform Core Patterns and + Modern API Integration** Read + [references/example_core.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_core.md). + *Trigger Condition*: Always active during boilerplate layout or initial + framework loading pass. *Verification Checkpoint*: Ensure the core react + google maps platform core patterns and modern api integration structure is + initialized properly, and verify functionality compiles without errors. + +### 📦 Phase 2: Component Integration & Feature Layers (Supplemental) + +- [ ] **Step 2.1: Feature Layer - React Google Maps: Advanced Marker + Interaction, Z-Index Management, and InfoWindow Anchoring** Read + [references/example_advanced.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_advanced.md). + *Trigger Condition*: Triggered when the user application requires specific + react google maps: advanced marker interaction, z-index management, and + infowindow anchoring features integration. *Verification Checkpoint*: Ensure + the react google maps: advanced marker interaction, z-index management, and + infowindow anchoring elements are rendered correctly, and verify event + callbacks handle data safely. +- [ ] **Step 2.2: Feature Layer - Modern React Autocomplete Patterns using + `AutocompleteSuggestion` and `Place.fetchFields`** Read + [references/example_autocomplete.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_autocomplete.md). + *Trigger Condition*: Triggered when the user application requires specific + modern react autocomplete patterns using `autocompletesuggestion` and + `place.fetchfields` features integration. *Verification Checkpoint*: Ensure + the modern react autocomplete patterns using `autocompletesuggestion` and + `place.fetchfields` elements are rendered correctly, and verify event + callbacks handle data safely. +- [ ] **Step 2.3: Feature Layer - Basic Initialization and Rendering of Google + Maps in React** Read + [references/example_basic.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_basic.md). + *Trigger Condition*: Triggered when the user application requires specific + basic initialization and rendering of google maps in react features + integration. *Verification Checkpoint*: Ensure the basic initialization and + rendering of google maps in react elements are rendered correctly, and + verify event callbacks handle data safely. +- [ ] **Step 2.4: Feature Layer - Dynamic Map Styling and Configuration in + React Google Maps SDK** Read + [references/example_change.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_change.md). + *Trigger Condition*: Triggered when the user application requires specific + dynamic map styling and configuration in react google maps sdk features + integration. *Verification Checkpoint*: Ensure the dynamic map styling and + configuration in react google maps sdk elements are rendered correctly, and + verify event callbacks handle data safely. +- [ ] **Step 2.5: Feature Layer - React Custom Marker Clustering Pattern using + Supercluster and `useMapViewport`** Read + [references/example_custom.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_custom.md). + *Trigger Condition*: Triggered when the user application requires specific + react custom marker clustering pattern using supercluster and + `usemapviewport` features integration. *Verification Checkpoint*: Ensure the + react custom marker clustering pattern using supercluster and + `usemapviewport` elements are rendered correctly, and verify event callbacks + handle data safely. +- [ ] **Step 2.6: Feature Layer - Integrating Deck.gl Overlays with + @vis.gl/react-google-maps** Read + [references/example_deckgl.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_deckgl.md). + *Trigger Condition*: Triggered when the user application requires specific + integrating deck.gl overlays with @vis.gl/react-google-maps features + integration. *Verification Checkpoint*: Ensure the integrating deck.gl + overlays with @vis.gl/react-google-maps elements are rendered correctly, and + verify event callbacks handle data safely. +- [ ] **Step 2.7: Feature Layer - Modern Route Calculation and Rendering in + React using `@vis.gl/react-google-maps`** Read + [references/example_directions.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_directions.md). + *Trigger Condition*: Triggered when the user application requires specific + modern route calculation and rendering in react using + `@vis.gl/react-google-maps` features integration. *Verification Checkpoint*: + Ensure the modern route calculation and rendering in react using + `@vis.gl/react-google-maps` elements are rendered correctly, and verify + event callbacks handle data safely. +- [ ] **Step 2.8: Feature Layer - Custom Drawing Tools Implementation using + React Google Maps Hooks and Low-Level Events** Read + [references/example_drawing.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_drawing.md). + *Trigger Condition*: Triggered when the user application requires specific + custom drawing tools implementation using react google maps hooks and + low-level events features integration. *Verification Checkpoint*: Ensure the + custom drawing tools implementation using react google maps hooks and + low-level events elements are rendered correctly, and verify event callbacks + handle data safely. +- [ ] **Step 2.9: Feature Layer - React Integration Patterns for Google Maps + Extended Component Library** Read + [references/example_extended.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_extended.md). + *Trigger Condition*: Triggered when the user application requires specific + react integration patterns for google maps extended component library + features integration. *Verification Checkpoint*: Ensure the react + integration patterns for google maps extended component library elements are + rendered correctly, and verify event callbacks handle data safely. +- [ ] **Step 2.10: Feature Layer - React Google Maps: Declarative Vector + Geometry and Interactive Drawing Patterns** Read + [references/example_geometry.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_geometry.md). + *Trigger Condition*: Triggered when the user application requires specific + react google maps: declarative vector geometry and interactive drawing + patterns features integration. *Verification Checkpoint*: Ensure the react + google maps: declarative vector geometry and interactive drawing patterns + elements are rendered correctly, and verify event callbacks handle data + safely. +- [ ] **Step 2.11: Feature Layer - React Google Maps Platform: Advanced 3D + Mapping, Routing, and Custom Controls** Read + [references/example_map.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_map.md). + *Trigger Condition*: Triggered when the user application requires specific + react google maps platform: advanced 3d mapping, routing, and custom + controls features integration. *Verification Checkpoint*: Ensure the react + google maps platform: advanced 3d mapping, routing, and custom controls + elements are rendered correctly, and verify event callbacks handle data + safely. +- [ ] **Step 2.12: Feature Layer - React Google Maps: Advanced Marker + Clustering and State Management** Read + [references/example_marker.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_marker.md). + *Trigger Condition*: Triggered when the user application requires specific + react google maps: advanced marker clustering and state management features + integration. *Verification Checkpoint*: Ensure the react google maps: + advanced marker clustering and state management elements are rendered + correctly, and verify event callbacks handle data safely. +- [ ] **Step 2.13: Feature Layer - Google Maps Platform React Marker and + InfoWindow Usage Patterns** Read + [references/example_markers.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_markers.md). + *Trigger Condition*: Triggered when the user application requires specific + google maps platform react marker and infowindow usage patterns features + integration. *Verification Checkpoint*: Ensure the google maps platform + react marker and infowindow usage patterns elements are rendered correctly, + and verify event callbacks handle data safely. +- [ ] **Step 2.14: Feature Layer - Multi-Map View Synchronization using React + Camera State** Read + [references/example_multiple.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_multiple.md). + *Trigger Condition*: Triggered when the user application requires specific + multi-map view synchronization using react camera state features + integration. *Verification Checkpoint*: Ensure the multi-map view + synchronization using react camera state elements are rendered correctly, + and verify event callbacks handle data safely. +- [ ] **Step 2.15: Feature Layer - React Google Maps: Core Initialization and + Declarative Map Rendering in Next.js** Read + [references/example_nextjs.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_nextjs.md). + *Trigger Condition*: Triggered when the user application requires specific + react google maps: core initialization and declarative map rendering in + next.js features integration. *Verification Checkpoint*: Ensure the react + google maps: core initialization and declarative map rendering in next.js + elements are rendered correctly, and verify event callbacks handle data + safely. +- [ ] **Step 2.16: Feature Layer - React Wrapper Patterns for Google Maps + Platform UI Kit (3D & Places)** Read + [references/example_places.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_places.md). + *Trigger Condition*: Triggered when the user application requires specific + react wrapper patterns for google maps platform ui kit (3d & places) + features integration. *Verification Checkpoint*: Ensure the react wrapper + patterns for google maps platform ui kit (3d & places) elements are rendered + correctly, and verify event callbacks handle data safely. +- [ ] **Step 2.17: Feature Layer - React Wrapper Pattern for Google Maps + Platform API Initialization** Read + [references/example_react.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_react.md). + *Trigger Condition*: Triggered when the user application requires specific + react wrapper pattern for google maps platform api initialization features + integration. *Verification Checkpoint*: Ensure the react wrapper pattern for + google maps platform api initialization elements are rendered correctly, and + verify event callbacks handle data safely. +- [ ] **Step 2.18: Feature Layer - React/Remix Integration and Modern Google + Maps Platform SDK Patterns** Read + [references/example_remix.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_remix.md). + *Trigger Condition*: Triggered when the user application requires specific + react/remix integration and modern google maps platform sdk patterns + features integration. *Verification Checkpoint*: Ensure the react/remix + integration and modern google maps platform sdk patterns elements are + rendered correctly, and verify event callbacks handle data safely. +- [ ] **Step 2.19: Feature Layer - Google Maps Platform Routes API Integration + Patterns in React** Read + [references/example_routes.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_routes.md). + *Trigger Condition*: Triggered when the user application requires specific + google maps platform routes api integration patterns in react features + integration. *Verification Checkpoint*: Ensure the google maps platform + routes api integration patterns in react elements are rendered correctly, + and verify event callbacks handle data safely. +- [ ] **Step 2.20: Feature Layer - React Integration of Google Maps Static API + via Componentized URL Generation** Read + [references/example_static.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_static.md). + *Trigger Condition*: Triggered when the user application requires specific + react integration of google maps static api via componentized url generation + features integration. *Verification Checkpoint*: Ensure the react + integration of google maps static api via componentized url generation + elements are rendered correctly, and verify event callbacks handle data + safely. +- [ ] **Step 2.21: Feature Layer - Patterns for External Library Integration + and Deferred Map Initialization using React Hooks** Read + [references/example_terra.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_terra.md). + *Trigger Condition*: Triggered when the user application requires specific + patterns for external library integration and deferred map initialization + using react hooks features integration. *Verification Checkpoint*: Ensure + the patterns for external library integration and deferred map + initialization using react hooks elements are rendered correctly, and verify + event callbacks handle data safely. +- [ ] **Step 2.22: Feature Layer - React Web Worker Marker Clustering using + `useSuperclusterWorker` and Advanced Markers** Read + [references/example_worker.md](https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/references/example_worker.md). + *Trigger Condition*: Triggered when the user application requires specific + react web worker marker clustering using `usesuperclusterworker` and + advanced markers features integration. *Verification Checkpoint*: Ensure the + react web worker marker clustering using `usesuperclusterworker` and + advanced markers elements are rendered correctly, and verify event callbacks + handle data safely. diff --git a/.gmp_cache/index.json b/.gmp_cache/index.json new file mode 100644 index 0000000..27d64ae --- /dev/null +++ b/.gmp_cache/index.json @@ -0,0 +1,222 @@ +[ + { + "name": "address-validation-api-web-api", + "description": "Use this skill when developing an application that needs to verify the deliverability and accuracy of a postal address, standardize input addresses, obtain precise geolocation, or retrieve postal-specific metadata like CASS certification and delivery point details.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/address-validation-api-web-api/SKILL.md" + }, + { + "name": "aerial-view-api-web-api", + "description": "Use this skill when developers need to retrieve a URL for a pre-rendered, photorealistic 3D flyover video of a specified location, or when they require metadata about available aerial views, using the Aerial View API for Google Maps Platform.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/aerial-view-api-web-api/SKILL.md" + }, + { + "name": "air-quality-api-web-api", + "description": "Use this skill when the developer needs to retrieve current, historical (30-day), or forecasted (4-day) air quality data, including the Air Quality Index (AQI), pollutant concentrations, health recommendations, and corresponding visual heatmap tiles for any geographic location via the Google Maps Platform Air Quality API.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/air-quality-api-web-api/SKILL.md" + }, + { + "name": "compliance-review", + "description": "Use this skill to review implementation plans or code that uses Google Maps Platform in order to identify revisions that need to be made based on Google Maps Platform Terms of Service, Acceptable Use Policy, EEA terms, AI terms, and deprecation policies. Use this skill each time there is a significant revision to an implementation plan or code such as a change in the Google Maps Platform products selected or the handling of responses from Google Maps Platform.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/compliance-review/SKILL.md" + }, + { + "name": "consumer-sdk-for-android-android", + "description": "Use this skill when a developer needs to integrate a real-time, customizable map into their Android application to track a trip managed by Fleet Engine, allowing them to display the vehicle location, route polyline, and customize map features and styles for a consumer-facing experience.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/consumer-sdk-for-android-android/SKILL.md" + }, + { + "name": "consumer-sdk-for-ios-ios", + "description": "Use this skill when building native iOS applications that require real-time, customizable trip progress tracking for consumers using Fleet Engine data, including vehicle location, route visualization, and dynamic map styling customizations.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/consumer-sdk-for-ios-ios/SKILL.md" + }, + { + "name": "directions-api-web-api", + "description": "Use this skill when developers need to calculate routes, distance, travel time, and turn-by-turn instructions between two or more geographic points using the Directions API. It supports various travel modes (driving, walking, transit) and optional constraints like avoidance features and optimizing waypoints.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/directions-api-web-api/SKILL.md" + }, + { + "name": "distance-matrix-api-web-api", + "description": "Use this skill when calculating travel distance and time between multiple origins and destinations simultaneously. This capability is fulfilled by the modern Routes API, which replaces the deprecated Distance Matrix API. Users can request a matrix of routes and specify travel modes like driving, transit, or walking.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/distance-matrix-api-web-api/SKILL.md" + }, + { + "name": "driver-sdk-for-android-android", + "description": "Use this skill when implementing a driver application on Android that needs to report real-time vehicle location, route updates, estimated time of arrival (ETA), remaining distance, and waypoint status to the Fleet Engine backend service for efficient fleet management.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/driver-sdk-for-android-android/SKILL.md" + }, + { + "name": "driver-sdk-for-ios-ios", + "description": "Use this skill when developing iOS driver applications that need to communicate real-time vehicle location, route, ETA, and trip progress updates to the Fleet Engine backend service for efficient fleet management and consumer visibility.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/driver-sdk-for-ios-ios/SKILL.md" + }, + { + "name": "elevation-api-web-api", + "description": "Use this skill to retrieve the precise ground elevation (in meters) for specific latitude/longitude coordinates, or to sample elevation data along a defined path for topographical analysis and terrain visualization.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/elevation-api-web-api/SKILL.md" + }, + { + "name": "fleet-engine-service-web-api", + "description": "Use this skill when integrating the Fleet Engine Service via the Web API to manage the entire lifecycle of on-demand transportation vehicles and trips, including provisioning new vehicles, updating vehicle attributes, creating and tracking trip progress, and reporting billable usage metrics.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/fleet-engine-service-web-api/SKILL.md" + }, + { + "name": "geocoding-api-web-api", + "description": "Use this skill when a developer needs to convert addresses into geographic coordinates (geocoding) or convert coordinates back into human-readable addresses (reverse geocoding). It provides precise location data, supports restricting results by region or type, and returns details about building entrances, outlines, and landmark proximity.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/geocoding-api-web-api/SKILL.md" + }, + { + "name": "geolocation-api-web-api", + "description": "Use this skill when needing to determine the physical location (latitude and longitude) of a client device based on surrounding cell tower and Wi-Fi access point data, often serving as a reliable fallback when GPS or HTML5 geolocation is unavailable or slow.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/geolocation-api-web-api/SKILL.md" + }, + { + "name": "gmp-common-api-keys", + "description": "Manage Google Maps Platform API keys, including generation, security, and required authentication mechanisms.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-common-api-keys/SKILL.md" + }, + { + "name": "gmp-common-grounding", + "description": "Use this skill to access rules and specifications for the Google Maps Platform Grounding Lite service and its Model Context Protocol (MCP) tools for AI applications.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-common-grounding/SKILL.md" + }, + { + "name": "gmp-common-pricing", + "description": "Provide comprehensive guidelines on Google Maps Platform pricing, including subscription tiers, pay-as-you-go model, free usage caps, volume discounts, and detailed CPM pricing tables.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-common-pricing/SKILL.md" + }, + { + "name": "gmp-framework-flutter", + "description": "This skill provides the architectural foundation and implementation best practices for developing Google Maps Platform applications using Flutter and the `google_maps_flutter` package. It focuses on the declarative nature of the Flutter SDK, managing map state and objects through widget properties, and handling asynchronous operations via `GoogleMapController`.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-flutter/SKILL.md" + }, + { + "name": "gmp-framework-react", + "description": "This guide serves as the mandatory entry point and architectural router for building Google Maps Platform applications using the **React** framework, specifically leveraging the official `@vis.gl/react-google-maps` SDK and modern API features. The content is rigorously curated to enforce the **Absolute Universal Zero-Legacy Mandate**, ensuring all generated solutions utilize current, future-proof, cost-optimized, and performant APIs. Developers are proactively guided toward modern replacements like `AdvancedMarkerElement`, the `Place` class (Places API New), and the `Route` class (Routes API), strictly forbidding any reliance on deprecated or disabled callback-based services. This router ensures comprehensive coverage of React patterns, from basic initialization to complex data visualization and clustering techniques.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/gmp-framework-react/SKILL.md" + }, + { + "name": "javascript-consumer-sdk-javascript", + "description": "Use this skill when integrating the Fleet Engine trip tracking experience into a JavaScript web application, allowing the user to display real-time route updates, customize map styling (polylines, markers, features), and visualize vehicle or shipment progress accurately for the end consumer.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/javascript-consumer-sdk-javascript/SKILL.md" + }, + { + "name": "map-tiles-api-web-api", + "description": "Accesses the Map Tiles API for low-level image retrieval. Use this skill to fetch 2D raster tiles (roadmap, satellite, terrain) using XYZ coordinates, retrieve URIs for photorealistic 3D tiles (OGC format), and obtain Street View metadata. Always trigger for queries requiring direct tile access, custom map rendering in third-party engines, XYZ coordinates, or applying custom map styling using a Map ID.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/map-tiles-api-web-api/SKILL.md" + }, + { + "name": "maps-3d-sdk-for-android-android", + "description": "Use this skill when developing native Android applications that require highly immersive and interactive photorealistic 3D map experiences. Developers can integrate advanced features like custom 3D markers, complex 3D models, polylines, and polygons, along with fine-grained control over camera movements, animations, and user interactions within the 3D environment.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/maps-3d-sdk-for-android-android/SKILL.md" + }, + { + "name": "maps-3d-sdk-for-ios-ios", + "description": "Use this skill to integrate interactive, photorealistic 3D maps into an iOS application using the Maps 3D SDK. Developers can add custom 3D models, markers, polylines, and polygons, and precisely control the camera movement and available user controls for creating immersive geographic experiences.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/maps-3d-sdk-for-ios-ios/SKILL.md" + }, + { + "name": "maps-datasets-api-web-api", + "description": "Use this skill when managing custom geospatial datasets for visualization and styling on Google Maps Platform. Developers can create new datasets, upload data in CSV, GeoJSON, or KML formats, and retrieve metadata or content for existing datasets using the Maps Datasets API.", + "entrypoint": "https://www.gstatic.com/googlemapsplatform-agent-skills/maps-datasets-api-web-api/SKILL.md" + }, + { + "name": "maps-embed-api-javascript", + "description": "Uses the Maps Embed API to display interactive maps, street view panoramas, directions, or place searches directly on a web page using simple HTML