From 8aaea609a86ae3c09021096f3c1e3099f7b0ffec Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Fri, 20 Mar 2026 02:13:43 +1100
Subject: [PATCH 1/2] fix: update e2e bundle snapshot hash

---
 test/e2e/base.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/e2e/base.test.ts b/test/e2e/base.test.ts
index 95722af3..87aa2792 100644
--- a/test/e2e/base.test.ts
+++ b/test/e2e/base.test.ts
@@ -20,6 +20,6 @@ describe('base', async () => {
     await page.waitForTimeout(500)
     // get content of #script-src
     const text = await page.$eval('#script-src', el => el.textContent)
-    expect(text).toMatchInlineSnapshot(`"/foo/_scripts/assets/6bEy8slcRmYcRT4E2QbQZ1CMyWw9PpHA7L87BtvSs2U.js"`)
+    expect(text).toMatchInlineSnapshot(`"/foo/_scripts/assets/PHzhM8DFXcXVSSJF110cyV3pjg9cp8oWv_f4Dk2ax1w.js"`)
   })
 })

From 55e75bfbd6a93e3b8df1a1d89c7ab61a30a66942 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Fri, 20 Mar 2026 02:42:48 +1100
Subject: [PATCH 2/2] feat: add `<ScriptGoogleMapsOverlayView>` component

Renders arbitrary Vue slot content at a map lat/lng position with full
styling control, solving the limitation of InfoWindow's predefined HTML
structure. Includes anchor-based positioning, map interaction blocking,
and flash prevention.

Closes #657
---
 docs/content/scripts/google-maps.md           |  71 ++++++++++
 .../pages/third-parties/google-maps/sfcs.vue  |  21 +++
 .../ScriptGoogleMapsOverlayView.vue           | 128 ++++++++++++++++++
 3 files changed, 220 insertions(+)
 create mode 100644 src/runtime/components/GoogleMaps/ScriptGoogleMapsOverlayView.vue

diff --git a/docs/content/scripts/google-maps.md b/docs/content/scripts/google-maps.md
index 223e9272..b4d1920e 100644
--- a/docs/content/scripts/google-maps.md
+++ b/docs/content/scripts/google-maps.md
@@ -434,6 +434,7 @@ All Google Maps SFC components must work within a `<ScriptGoogleMaps>`{lang="htm
 - `<ScriptGoogleMapsPolyline>`{lang="html"} - Line paths
 - `<ScriptGoogleMapsRectangle>`{lang="html"} - Rectangular overlays
 - `<ScriptGoogleMapsHeatmapLayer>`{lang="html"} - Heatmap visualization
+- `<ScriptGoogleMapsOverlayView>`{lang="html"} - Render arbitrary Vue content at a lat/lng position
 
 ### Basic Usage
 
@@ -531,6 +532,7 @@ ScriptGoogleMaps (root)
 ├── ScriptGoogleMapsAdvancedMarkerElement
 │   ├── ScriptGoogleMapsPinElement (optional)
 │   └── ScriptGoogleMapsInfoWindow (optional)
+├── ScriptGoogleMapsOverlayView (arbitrary Vue content at a position)
 └── ScriptGoogleMapsCircle / Polygon / Polyline / Rectangle / HeatmapLayer
 ```
 
@@ -550,6 +552,75 @@ All SFC components accept an `options` prop matching their Google Maps API optio
 | `ScriptGoogleMapsPolyline` | `google.maps.PolylineOptions` | |
 | `ScriptGoogleMapsRectangle` | `google.maps.RectangleOptions` | |
 | `ScriptGoogleMapsHeatmapLayer` | `google.maps.visualization.HeatmapLayerOptions` | |
+| `ScriptGoogleMapsOverlayView` | Explicit props (see below) | Renders Vue slot content at a position |
+
+### `<ScriptGoogleMapsOverlayView>`{lang="html"}
+
+Renders arbitrary Vue slot content at a map lat/lng position. Unlike `InfoWindow`, you have full control over HTML structure and styling.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `position` | `google.maps.LatLngLiteral` | (required) | Map anchor point |
+| `anchor` | `OverlayAnchor` | `'bottom-center'` | Which point of the content aligns to the position |
+| `offset` | `{ x: number, y: number }` | - | Pixel fine-tuning after anchor alignment |
+| `pane` | `OverlayPane` | `'floatPane'` | Google Maps pane to render into |
+| `zIndex` | `number` | - | Stack order |
+| `blockMapInteraction` | `boolean` | `true` | Prevents clicks/drags from propagating to the map |
+
+**Popup on marker click:**
+
+```vue
+<script setup>
+const open = ref(false)
+const pos = { lat: -34.397, lng: 150.644 }
+</script>
+
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsAdvancedMarkerElement
+      :options="{ position: pos }"
+      @click="open = true"
+    />
+    <ScriptGoogleMapsOverlayView
+      v-if="open"
+      :position="pos"
+      anchor="bottom-center"
+      :offset="{ x: 0, y: -40 }"
+    >
+      <div class="custom-popup">
+        <button @click="open = false">
+          ×
+        </button>
+        <p>Any Vue content here</p>
+      </div>
+    </ScriptGoogleMapsOverlayView>
+  </ScriptGoogleMaps>
+</template>
+```
+
+**Persistent label:**
+
+```vue
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsOverlayView
+      :position="{ lat: -34.397, lng: 150.644 }"
+      anchor="center"
+      :block-map-interaction="false"
+    >
+      <span style="background: white; padding: 2px 6px; border-radius: 4px;">
+        Label text
+      </span>
+    </ScriptGoogleMapsOverlayView>
+  </ScriptGoogleMaps>
+</template>
+```
+
+::callout
+The `blockMapInteraction` prop (default `true`) calls `google.maps.OverlayView.preventMapHitsAndGesturesFrom()`{lang="ts"} to stop clicks, taps, and drags from propagating through the overlay to the map. Set it to `false` for non-interactive overlays like labels.
+::
 
 ## [`useScriptGoogleMaps()`{lang="ts"}](/scripts/google-maps){lang="ts"}
 
diff --git a/playground/pages/third-parties/google-maps/sfcs.vue b/playground/pages/third-parties/google-maps/sfcs.vue
index cf58f3fb..d5b3f566 100644
--- a/playground/pages/third-parties/google-maps/sfcs.vue
+++ b/playground/pages/third-parties/google-maps/sfcs.vue
@@ -36,6 +36,8 @@ const heatmapLayerData = ref<google.maps.LatLng[]>([])
 
 const isCircleShown = ref(false)
 
+const isOverlayViewShown = ref(false)
+
 const googleMapsRef = useTemplateRef('googleMapsRef')
 
 whenever(() => googleMapsRef.value?.googleMaps, (googleMaps) => {
@@ -191,6 +193,18 @@ whenever(() => googleMapsRef.value?.googleMaps, (googleMaps) => {
         }"
       />
 
+      <ScriptGoogleMapsOverlayView
+        v-if="isOverlayViewShown"
+        :position="{ lat: -33.8688, lng: 151.2093 }"
+        anchor="bottom-center"
+        :offset="{ x: 0, y: -10 }"
+      >
+        <div style="background: white; padding: 8px 12px; border-radius: 8px; box-shadow: 0 2px 6px rgba(0,0,0,0.3); font-family: sans-serif;">
+          <strong>Custom Overlay</strong>
+          <p style="margin: 4px 0 0;">Vue slot content with full reactivity</p>
+        </div>
+      </ScriptGoogleMapsOverlayView>
+
       <ScriptGoogleMapsCircle
         v-if="isCircleShown"
         :options="{
@@ -269,6 +283,13 @@ whenever(() => googleMapsRef.value?.googleMaps, (googleMaps) => {
         {{ `${isHeatmapLayerShown ? 'Hide' : 'Show'} heatmap layer` }}
       </button>
 
+      <button
+        class="bg-[#ffa500] rounded-lg px-2 py-1"
+        @click="isOverlayViewShown = !isOverlayViewShown"
+      >
+        {{ `${isOverlayViewShown ? 'Hide' : 'Show'} overlay view` }}
+      </button>
+
       <button
         class="bg-[#ffa500] rounded-lg px-2 py-1"
         @click="isCircleShown = !isCircleShown"
diff --git a/src/runtime/components/GoogleMaps/ScriptGoogleMapsOverlayView.vue b/src/runtime/components/GoogleMaps/ScriptGoogleMapsOverlayView.vue
new file mode 100644
index 00000000..4cf313ea
--- /dev/null
+++ b/src/runtime/components/GoogleMaps/ScriptGoogleMapsOverlayView.vue
@@ -0,0 +1,128 @@
+<script setup lang="ts">
+import { useTemplateRef, watch } from 'vue'
+import { useGoogleMapsResource } from './useGoogleMapsResource'
+
+type OverlayAnchor = 'center' | 'top-left' | 'top-center' | 'top-right'
+  | 'bottom-left' | 'bottom-center' | 'bottom-right'
+  | 'left-center' | 'right-center'
+
+type OverlayPane = 'mapPane' | 'overlayLayer' | 'markerLayer'
+  | 'overlayMouseTarget' | 'floatPane'
+
+const props = withDefaults(defineProps<{
+  position: google.maps.LatLngLiteral
+  anchor?: OverlayAnchor
+  offset?: { x: number, y: number }
+  pane?: OverlayPane
+  zIndex?: number
+  blockMapInteraction?: boolean
+}>(), {
+  anchor: 'bottom-center',
+  pane: 'floatPane',
+  blockMapInteraction: true,
+})
+
+const ANCHOR_TRANSFORMS: Record<OverlayAnchor, string> = {
+  'center': 'translate(-50%, -50%)',
+  'top-left': 'translate(0, 0)',
+  'top-center': 'translate(-50%, 0)',
+  'top-right': 'translate(-100%, 0)',
+  'bottom-left': 'translate(0, -100%)',
+  'bottom-center': 'translate(-50%, -100%)',
+  'bottom-right': 'translate(-100%, -100%)',
+  'left-center': 'translate(0, -50%)',
+  'right-center': 'translate(-100%, -50%)',
+}
+
+const overlayContent = useTemplateRef('overlay-content')
+
+const overlay = useGoogleMapsResource<google.maps.OverlayView>({
+  ready: () => !!overlayContent.value,
+  create({ mapsApi, map }) {
+    const el = overlayContent.value!
+    let hasDrawn = false
+
+    class CustomOverlay extends mapsApi.OverlayView {
+      override onAdd() {
+        const panes = this.getPanes()
+        if (panes) {
+          panes[props.pane].appendChild(el)
+          if (props.blockMapInteraction)
+            mapsApi.OverlayView.preventMapHitsAndGesturesFrom(el)
+        }
+      }
+
+      override draw() {
+        const projection = this.getProjection()
+        if (!projection)
+          return
+        const pos = projection.fromLatLngToDivPixel(
+          new mapsApi.LatLng(props.position.lat, props.position.lng),
+        )
+        if (!pos)
+          return
+        el.style.position = 'absolute'
+        el.style.left = `${pos.x + (props.offset?.x ?? 0)}px`
+        el.style.top = `${pos.y + (props.offset?.y ?? 0)}px`
+        el.style.transform = ANCHOR_TRANSFORMS[props.anchor]
+        if (props.zIndex !== undefined)
+          el.style.zIndex = String(props.zIndex)
+        if (!hasDrawn) {
+          el.style.visibility = 'visible'
+          hasDrawn = true
+        }
+      }
+
+      override onRemove() {
+        el.parentNode?.removeChild(el)
+      }
+    }
+
+    // Prevent flash: hide until first draw() positions content
+    el.style.visibility = 'hidden'
+
+    const ov = new CustomOverlay()
+    ov.setMap(map)
+    return ov
+  },
+  cleanup(ov) {
+    ov.setMap(null)
+  },
+})
+
+// Reposition on prop changes (draw() is designed to be called repeatedly)
+watch(
+  () => [props.position.lat, props.position.lng, props.offset?.x, props.offset?.y, props.zIndex, props.anchor],
+  () => { overlay.value?.draw() },
+)
+
+// Pane change requires remount (setMap cycles onRemove + onAdd + draw)
+watch(() => props.pane, () => {
+  if (overlay.value) {
+    const map = overlay.value.getMap()
+    overlay.value.setMap(null)
+    if (map)
+      overlay.value.setMap(map as google.maps.Map)
+  }
+})
+
+// blockMapInteraction change requires remount to re-apply preventMapHitsAndGesturesFrom
+watch(() => props.blockMapInteraction, () => {
+  if (overlay.value) {
+    const map = overlay.value.getMap()
+    overlay.value.setMap(null)
+    if (map)
+      overlay.value.setMap(map as google.maps.Map)
+  }
+})
+
+defineExpose({ overlay })
+</script>
+
+<template>
+  <div style="display: none;">
+    <div ref="overlay-content">
+      <slot />
+    </div>
+  </div>
+</template>