diff --git a/.github/prompts/plan-searchButtonDisabledStateTests.prompt.md b/.github/prompts/plan-searchButtonDisabledStateTests.prompt.md
new file mode 100644
index 000000000..2a1d82f7b
--- /dev/null
+++ b/.github/prompts/plan-searchButtonDisabledStateTests.prompt.md
@@ -0,0 +1,49 @@
+## Plan: Search Button Disabled State Tests
+
+Create a test fixture and test file in `test/e2e/core/` to verify the search button's disabled state responds correctly to `<map-link rel="search">` presence/absence in both local and remote layers, including dynamic mutations.
+
+**Steps**
+
+### Phase A — Test Data (parallel)
+1. Create `test/e2e/data/search-layer.mapml` — minimal remote .mapml with `<map-link rel="search" tref="...">` inside a `<map-extent>`. Based on the `dummy-cbmtile-cbmt.mapml` pattern.
+2. Create `test/e2e/data/no-search-layer.mapml` — same structure, no search link.
+
+### Phase B — Test Fixture
+3. Create `test/e2e/core/searchDisabled.html` with `controlslist="search"`, a local (inline) `<map-layer>` with no search link, and a remote `<map-layer src="no-search-layer.mapml">` checked.
+
+### Phase C — Tests
+4. Create `test/e2e/core/searchDisabled.test.js`:
+
+   **Initial state:**
+   - Button has `aria-disabled="true"` when no layer has `map-link[rel=search]`
+
+   **Local layer — dynamic add/remove:**
+   - Enabled (`aria-disabled="false"`) after appending `<map-link rel="search">` to inline layer
+   - Disabled again after removing it
+
+   **Layer checked/unchecked:**
+   - Disabled when the layer with search link is unchecked
+   - Re-enabled when re-checked
+
+   **Remote (src) layer:**
+   - Enabled when remote layer's `src` changes to `search-layer.mapml` (wait for `loadedmetadata`)
+   - Disabled when `src` changes back to `no-search-layer.mapml`
+
+   **Multiple layers:**
+   - Stays enabled if one of two layers has a search link
+   - Disabled only when all search-capable layers are unchecked
+
+**Relevant files**
+- `src/mapml/control/SearchButton.js` — `_hasSearchLayers()`, `_updateDisabled()` under test
+- `test/e2e/data/dummy-cbmtile-cbmt.mapml` — template for new .mapml files
+- `test/e2e/core/mapElement.html` — fixture pattern reference
+- `test/server.js` — already serves `test/e2e/core/` and `test/e2e/data/` statically
+
+**Verification**
+1. `npx playwright test test/e2e/core/searchDisabled.test.js --reporter=list` — all tests pass
+2. `grunt` — build succeeds
+
+**Decisions**
+- Tests in `test/e2e/core/` — this is core control behavior
+- Remote layer test changes `src` dynamically, waits for `loadedmetadata`
+- `hidden` attribute does NOT affect disabled state (per earlier decision)
diff --git a/.github/prompts/plan-searchPhase2-defaultHandler.prompt.md b/.github/prompts/plan-searchPhase2-defaultHandler.prompt.md
new file mode 100644
index 000000000..4e2729df7
--- /dev/null
+++ b/.github/prompts/plan-searchPhase2-defaultHandler.prompt.md
@@ -0,0 +1,89 @@
+
+---
+
+## Plan: Search Phase 2 — Default Handler, Fetch, Events & Formats
+
+Wire `<map-link rel="search">` and `<map-link rel="suggestions">` to the search control. Implement debounced fetch for suggestions on input and search on Enter/click. Dispatch cancelable events (`mapsearch`, `mapsuggestions`) on the viewer element so authors can `preventDefault()` and supply custom rendering. Provide default handlers that render GeoJSON FeatureCollection responses (the format returned by Nominatim `format=geojson` and Photon).
+
+**Steps**
+
+### Phase A — map-link.js: accept `search` and `suggestions` rel values
+
+1. In map-link.js, add `'search'` and `'suggestions'` to the array in the `set rel()` setter.
+2. In `connectedCallback()`, add `case 'search':` and `case 'suggestions':` — no-op (the link is discoverable via DOM query from `SearchButton`).
+3. In `whenReady()`, add `case 'search':` and `case 'suggestions':` that resolve immediately.
+
+### Phase B — SearchButton.js: fetch logic, events, default handlers
+
+4. Add debounced `input` event handler on `this._input` — 300ms debounce, minimum 2 chars, `AbortController` for stale requests → calls `_fetchSuggestions(query)`.
+
+5. Implement `_getSearchLinks()` and `_getSuggestionsLinks()` — query checked layers, look in `layer.shadowRoot` (remote) or `layer` (local) for `map-link[rel=search]` / `map-link[rel=suggestions]`. Return `[{ link, layer }]`. First per layer wins.
+
+6. Implement `_fetchSuggestions(query)`:
+   - Resolve each link's `tref` replacing `{searchTerms}` with `encodeURIComponent(query)`.
+   - Fetch all in parallel via `Promise.allSettled()`.
+   - Dispatch cancelable `mapsuggestions` CustomEvent on `this._mapEl` with `{ detail: { query, responses } }`.
+   - If not prevented → `_defaultSuggestionsHandler(detail)`.
+
+7. Implement `_defaultSuggestionsHandler()`:
+   - Render each GeoJSON feature as a `<button class="mapml-search-result">` in `this._results`.
+   - Display text: `properties.display_name || properties.name`.
+   - Click → `_selectResult(feature, layer)`.
+
+8. Implement search on Enter → `_doSearch(query)`:
+   - Same pattern as suggestions: resolve tref, fetch, dispatch cancelable `mapsearch` event, default handler renders results.
+
+9. Implement `_selectResult(feature, layer)`:
+   - If `feature.bbox` → `map.fitBounds()`.
+   - Else → `map.setView([lat, lon], 14)`.
+   - Close panel.
+
+### Phase C — CSS for results
+
+10. Add styles: `.mapml-search-results` scrollable, `.mapml-search-result` full-width button with hover, ellipsis overflow.
+
+### Phase D — Test data and mock routes
+
+11. Add mock routes in server.js:
+   - `GET /search/suggestions?q=...` → static GeoJSON FeatureCollection (2-3 features).
+   - `GET /search/results?q=...` → static GeoJSON FeatureCollection (1 feature with bbox).
+
+12. Create `test/e2e/data/search-with-tref.mapml` — remote layer with both `<map-link rel="suggestions" tref="...">` and `<map-link rel="search" tref="...">` in `<map-head>`.
+
+### Phase E — Tests
+
+13. Create `test/e2e/core/searchDefault.html` + `searchDefault.test.js`:
+   - Suggestions appear after typing
+   - Search results appear on Enter
+   - Click result → map moves / fits bounds
+   - `mapsuggestions` / `mapsearch` events fire with correct detail
+   - `preventDefault()` suppresses default rendering
+   - No fetch when button is disabled
+
+**Relevant files**
+- SearchButton.js — main target: fetch, events, default handlers
+- map-link.js — `connectedCallback()`, `set rel()`, `whenReady()`
+- mapml.css — result item styles
+- server.js — mock routes
+- search-layer.mapml — existing structure reference
+
+**Verification**
+1. `npx playwright test test/e2e/core/searchDefault.test.js --reporter=list`
+2. `npx playwright test searchDisabled.test.js --reporter=list` — no regressions
+3. `npx playwright test domApi-mapml-viewer.test.js --reporter=list` — no regressions
+4. `grunt` — build succeeds
+
+**Decisions**
+- Default format: **GeoJSON FeatureCollection** — works with Nominatim (`format=geojson`) and Photon out of the box
+- `{searchTerms}` is the only template variable — simple string replace, no `<map-input>` siblings needed
+- `<map-link rel="search|suggestions">` goes in `<map-head>` (remote) or direct child of `<map-layer>` (local) — NOT inside `<map-extent>`
+- Events are cancelable and bubble; `preventDefault()` suppresses default handler
+- One search + one suggestions link per layer (first wins); multiple layers' results are merged
+- Suggestions are optional — if no `rel="suggestions"` link exists, only Enter triggers search
+
+**Further Considerations**
+1. **Nominatim usage policy** — test fixtures use local mock routes, not live API. Authors using Nominatim are responsible for compliance. Should be documented.
+2. **No suggestions link fallback** — typing waits for Enter. Recommendation: this is correct behavior.
+3. **Search vs. suggestions visual distinction** — same treatment in Phase 2; can differentiate in Phase 3.
+
+---
diff --git a/.github/skills/map-link-markup/SKILL.md b/.github/skills/map-link-markup/SKILL.md
index 73692253e..32f648c9f 100644
--- a/.github/skills/map-link-markup/SKILL.md
+++ b/.github/skills/map-link-markup/SKILL.md
@@ -37,6 +37,8 @@ defines several uses of existing and new `rel` keyword values.
 | `zoomout`    | The link `href` is followed automatically by the polyfill when the map is zoomed out by the user to a value less than the minimum value of the zoom range of the current layer.  The referenced map layer resource replaces the current map layer.  The polyfill does not represent this link as a user-visible affordance, it is followed automatically.  If the remote resource does not contain a reciprocal `zoomin` link, the map state change is one-way i.e. the layer is permanently replaced.  |
 | `legend`     | The `legend` link relation designates a link to metadata, typically an image, describing the symbology used by the current layer.  Currently, the polyfill creates a hyperlink for the label of the layer in the layer control, which opens in a new browsing context. |
 | `query`      | The `query` link relation is used in combination with the `tref="..."` attribute to establish a URL template that composes a map query URL based on user map gestures such as click or touch. These URLs are fetched and the response presented on top of the map as a popup. Such queries can return text/html or text/mapml responses. In the latter case, the response may contain more than one feature, in which case a 'paged' popup is generated, allowing the user to cycle through the features' individual metadata. |
+| `search`     | The `search` link relation is used with the `tref="..."` attribute to define a URL template for a search endpoint. The template must contain the `{searchTerms}` variable reference, which is replaced with the user's URL-encoded search query. The search is triggered when the user presses Enter or clicks a suggestion. The response is expected to be a GeoJSON `FeatureCollection` (the default handler format). Only the first `<map-link rel="search">` per `<map-layer>` is honored. The link must be a direct child of `<map-layer>` (for local/inline layers) or placed inside `<map-head>` (for remote `.mapml` layers). The search control is opt-in via `controlslist="search"` on the `<mapml-viewer>` or `<map is="web-map">` element. The search button is disabled when no visible (checked) layer provides a `<map-link rel="search">`. |
+| `suggestions` | The `suggestions` link relation is used with the `tref="..."` attribute to define a URL template for a suggestions/autocomplete endpoint. Like `search`, the template must contain the `{searchTerms}` variable reference. Suggestions are fetched automatically as the user types (debounced, minimum 2 characters). The default handler expects a GeoJSON `FeatureCollection` response, rendering each feature as a clickable result button (using `properties.display_name` or `properties.name`). Only the first `<map-link rel="suggestions">` per `<map-layer>` is honored. Suggestions are optional — if no `rel="suggestions"` link exists, only Enter triggers a search. |
 | `stylesheet` | The link imports a CSS stylesheet from the `href` value. |
 
 
@@ -135,4 +137,206 @@ Projection values [defined by the polyfill](../mapml-viewer#projection) include:
    </map-extent>
    </layer->
 </mapml-viewer>
+```
+
+### Search and Suggestions
+
+The search control is opt-in: add `controlslist="search"` to your `<mapml-viewer>` 
+or `<map is="web-map">` element. A magnifying-glass button appears in the 
+top-left controls. The button is disabled (grayed out, `aria-disabled="true"`)
+when no visible (checked) `<map-layer>` has a descendant `<map-link rel="search">`.
+
+The `{searchTerms}` template variable in `tref` is the only required variable. 
+It is replaced with the user's URL-encoded query string. No sibling 
+`<map-input>` elements are needed for search/suggestions links.
+
+#### Placement rules
+
+- **Inline (local) layers:** place `<map-link rel="search">` and 
+  `<map-link rel="suggestions">` as direct children of `<map-layer>`.
+- **Remote layers (`.mapml` files):** place them inside `<map-head>`.
+- Do **not** place search/suggestions links inside `<map-extent>`.
+- Only the **first** `<map-link rel="search">` and first 
+  `<map-link rel="suggestions">` per `<map-layer>` are honored.
+- Multiple layers may each contribute their own search/suggestions links; 
+  responses are merged.
+
+#### Default handler format (GeoJSON)
+
+The default handler expects a **GeoJSON `FeatureCollection`** response from 
+both search and suggestions endpoints. Each `Feature` should include:
+
+- `geometry` with coordinates (used for `setView` fallback)
+- `bbox` (4-element array `[west, south, east, north]`; used for `fitBounds`)
+- `properties.display_name` or `properties.name` (rendered as button text)
+
+This format is compatible with Nominatim (`format=geojson`) and Photon out of 
+the box. Example minimal response:
+
+```json
+{
+  "type": "FeatureCollection",
+  "features": [
+    {
+      "type": "Feature",
+      "bbox": [-75.76, 45.35, -75.62, 45.46],
+      "geometry": { "type": "Point", "coordinates": [-75.69, 45.42] },
+      "properties": { "display_name": "Ottawa, Ontario, Canada" }
+    }
+  ]
+}
+```
+
+#### Default handler — inline layer example
+
+```html
+<mapml-viewer projection="OSMTILE" zoom="14" lat="45.4" lon="-75.7"
+              controls controlslist="search">
+  <map-layer label="OpenStreetMap" checked>
+    <!-- suggestions fetched as the user types (debounced, min 2 chars) -->
+    <map-link rel="suggestions"
+              tref="https://nominatim.openstreetmap.org/search?q={searchTerms}&format=geojson&limit=5"></map-link>
+    <!-- search fetched on Enter -->
+    <map-link rel="search"
+              tref="https://nominatim.openstreetmap.org/search?q={searchTerms}&format=geojson&limit=10"></map-link>
+    <map-extent units="OSMTILE" checked>
+      <map-input name="z" type="zoom" min="0" max="18"></map-input>
+      <map-input name="x" type="location" units="tilematrix" axis="column"></map-input>
+      <map-input name="y" type="location" units="tilematrix" axis="row"></map-input>
+      <map-link rel="tile" tref="https://tile.openstreetmap.org/{z}/{x}/{y}.png"></map-link>
+    </map-extent>
+  </map-layer>
+</mapml-viewer>
+```
+
+#### Default handler — remote layer example
+
+In the HTML page:
+
+```html
+<mapml-viewer projection="CBMTILE" zoom="5" lat="45.4" lon="-75.7"
+              controls controlslist="search">
+  <map-layer label="Canada Base Map" src="canada.mapml" checked></map-layer>
+</mapml-viewer>
+```
+
+In `canada.mapml`:
+
+```xml
+<mapml->
+  <map-head>
+    <map-meta charset="utf-8"></map-meta>
+    <map-link rel="suggestions" tref="https://geogratis.gc.ca/services/geoname/en/geonames.json?q={searchTerms}*&num=20"></map-link>
+    <map-link rel="search" tref="https://geogratis.gc.ca/services/geoname/en/geonames.json?q={searchTerms}&num=20"></map-link>
+  </map-head>
+  <map-body>
+    <map-extent units="CBMTILE" checked>
+      <map-input name="z" type="zoom" min="0" max="17"></map-input>
+      <map-input name="y" type="location" units="tilematrix" axis="row"></map-input>
+      <map-input name="x" type="location" units="tilematrix" axis="column"></map-input>
+      <map-link rel="tile" tref="https://example.com/tiles/{z}/{y}/{x}.png"></map-link>
+    </map-extent>
+  </map-body>
+</mapml->
+```
+
+#### Custom handler — overriding the default with `preventDefault()`
+
+When the server's response format does not match GeoJSON `FeatureCollection`, 
+use `preventDefault()` on the `mapsuggestions` and/or `mapsearch` events to 
+suppress the default handler and render results yourself.
+
+The polyfill dispatches two cancelable `CustomEvent`s on the `<mapml-viewer>` 
+(or `<map is="web-map">`) element:
+
+| Event             | Fires when                                     | `e.detail` properties             |
+|-------------------|-------------------------------------------------|-----------------------------------|
+| `mapsuggestions`  | Suggestion responses arrive (user is typing)    | `query`, `responses`              |
+| `mapsearch`       | Search responses arrive (user pressed Enter)    | `query`, `responses`              |
+
+`e.detail.responses` is an array of `{ data, link, layer }` objects — one per 
+layer that contributed a link. `data` is the parsed JSON response body; `link` 
+is the `<map-link>` element; `layer` is the `<map-layer>` element.
+
+To render results, query the search panel's results container from the map and 
+append your own HTML. Results should use the class `mapml-search-result` on 
+`<button>` elements for consistent styling.
+
+Example using the geonames.gc.ca API (non-GeoJSON response shape):
+
+```html
+<mapml-viewer projection="CBMTILE" zoom="5" lat="45.4" lon="-75.7"
+              controls controlslist="search">
+  <map-layer label="Geonames Layer" src="geonames-layer.mapml" checked></map-layer>
+</mapml-viewer>
+
+<script>
+  const viewer = document.querySelector('mapml-viewer');
+
+  viewer.addEventListener('mapsuggestions', (e) => {
+    e.preventDefault();
+    // Access the results container via the map's internal DOM
+    const container = viewer._map._container.querySelector('.mapml-search-results');
+    container.innerHTML = '';
+    for (const { data } of e.detail.responses) {
+      if (!data || !data.items) continue;
+      for (const item of data.items) {
+        const btn = document.createElement('button');
+        btn.className = 'mapml-search-result';
+        btn.setAttribute('type', 'button');
+        btn.textContent = item.name;
+        btn.addEventListener('click', () => {
+          if (item.bbox && item.bbox.length === 4) {
+            const [west, south, east, north] = item.bbox;
+            viewer._map.fitBounds([[south, west], [north, east]]);
+          } else {
+            viewer._map.setView([item.latitude, item.longitude], 10);
+          }
+        });
+        container.appendChild(btn);
+      }
+    }
+  });
+
+  viewer.addEventListener('mapsearch', (e) => {
+    e.preventDefault();
+    // Same pattern — parse the non-standard response and render results
+    const container = viewer._map._container.querySelector('.mapml-search-results');
+    container.innerHTML = '';
+    for (const { data } of e.detail.responses) {
+      if (!data || !data.items) continue;
+      for (const item of data.items) {
+        const btn = document.createElement('button');
+        btn.className = 'mapml-search-result';
+        btn.setAttribute('type', 'button');
+        btn.textContent = item.name;
+        btn.addEventListener('click', () => {
+          if (item.bbox && item.bbox.length === 4) {
+            const [west, south, east, north] = item.bbox;
+            viewer._map.fitBounds([[south, west], [north, east]]);
+          } else {
+            viewer._map.setView([item.latitude, item.longitude], 10);
+          }
+        });
+        container.appendChild(btn);
+      }
+    }
+  });
+</script>
+```
+
+#### Search without suggestions
+
+Suggestions are optional. If only `<map-link rel="search">` is provided 
+(no `rel="suggestions"`), the control will not fetch anything as the user 
+types — only pressing Enter will trigger a search request.
+
+```html
+<map-layer label="Search Only" checked>
+  <map-link rel="search"
+            tref="https://nominatim.openstreetmap.org/search?q={searchTerms}&format=geojson&limit=10"></map-link>
+  <map-extent units="OSMTILE" checked>
+    <!-- ... map-inputs and tile link ... -->
+  </map-extent>
+</map-layer>
 ```
\ No newline at end of file
diff --git a/.github/workflows/ci-testing.yml b/.github/workflows/ci-testing.yml
index ee8a5b8ff..9b83dfeca 100644
--- a/.github/workflows/ci-testing.yml
+++ b/.github/workflows/ci-testing.yml
@@ -12,14 +12,20 @@ jobs:
     - name: Use Node.js
       uses: actions/setup-node@v4
       with:
-        node-version: latest
-    - run: sudo apt-get install xvfb
-    - run: npm install
-    - run: npx playwright install  --with-deps
-    - run: npm install -g grunt-cli
-    - run: grunt default
+        node-version: 22
+        cache: npm
+    - run: npm ci --ignore-scripts
+    - name: Cache Playwright browsers
+      id: playwright-cache
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/ms-playwright
+        key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+    - run: npx playwright install --with-deps
+      if: steps.playwright-cache.outputs.cache-hit != 'true'
+    - run: npx playwright install-deps
+      if: steps.playwright-cache.outputs.cache-hit == 'true'
+    - run: npx grunt default
     - run: xvfb-run --auto-servernum -- npx playwright test --grep-invert="popupTabNavigation\.test\.js|layerContextMenuKeyboard\.test\.js"  --workers=1 --retries=3
-#    - run: xvfb-run --auto-servernum -- npx playwright test --grep="popupTabNavigation\.test\.js|layerContextMenuKeyboard\.test\.js" --workers=1 --retries=3
-#    - run: xvfb-run --auto-servernum -- npm run jest
       env:
         CI: true
diff --git a/geonames.json b/geonames.json
new file mode 100644
index 000000000..2c83d0f9c
--- /dev/null
+++ b/geonames.json
@@ -0,0 +1,370 @@
+{
+  "links": {
+    "self": {
+      "href": "https://geogratis.gc.ca/services/geoname/en/geonames?q=o*&num=3"
+    },
+    "alternate": [
+      {
+        "mediatype": "application/json",
+        "href": "https://geogratis.gc.ca/services/geoname/en/geonames.json?q=o*&num=3"
+      },
+      {
+        "mediatype": "text/html",
+        "href": "https://geogratis.gc.ca/services/geoname/en/geonames.html?q=o*&num=3"
+      },
+      {
+        "mediatype": "text/csv",
+        "href": "https://geogratis.gc.ca/services/geoname/en/geonames.csv?q=o*&num=3"
+      },
+      {
+        "mediatype": "application/vnd.google-earth.kml+xml",
+        "href": "https://geogratis.gc.ca/services/geoname/en/geonames.kml?q=o*&num=3"
+      },
+      {
+        "mediatype": "application/gml+xml",
+        "href": "https://geogratis.gc.ca/services/geoname/en/geonames.gml?q=o*&num=3"
+      },
+      {
+        "mediatype": "application/vnd.geo+json",
+        "href": "https://geogratis.gc.ca/services/geoname/en/geonames.geojson?q=o*&num=3"
+      }
+    ]
+  },
+  "items": [
+    {
+      "id": "NAABK",
+      "links": {
+        "self": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/geonames/NAABK"
+        },
+        "feature": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/features/899f2cdaba3611d892e2080020a0f4c9"
+        },
+        "language": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/codes/language/und"
+        },
+        "status": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/codes/status/official"
+        },
+        "concise": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/codes/concise/SEA"
+        },
+        "generic": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/codes/generic/1212"
+        },
+        "province": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/codes/province/73"
+        }
+      },
+      "name": "Arctic Ocean",
+      "language": {
+        "code": "und",
+        "links": {
+          "self": {
+            "href": "https://geogratis.gc.ca/services/geoname/en/codes/language/und"
+          }
+        }
+      },
+      "feature": {
+        "id": "899f2cdaba3611d892e2080020a0f4c9",
+        "links": {
+          "self": {
+            "href": "https://geogratis.gc.ca/services/geoname/en/features/899f2cdaba3611d892e2080020a0f4c9"
+          }
+        }
+      },
+      "category": "P",
+      "status": {
+        "code": "official",
+        "links": {
+          "self": {
+            "href": "https://geogratis.gc.ca/services/geoname/en/codes/status/official"
+          }
+        }
+      },
+      "concise": {
+        "code": "SEA",
+        "links": {
+          "self": {
+            "href": "https://geogratis.gc.ca/services/geoname/en/codes/concise/SEA"
+          }
+        }
+      },
+      "generic": {
+        "code": "1212",
+        "links": {
+          "self": {
+            "href": "https://geogratis.gc.ca/services/geoname/en/codes/generic/1212"
+          }
+        }
+      },
+      "location": null,
+      "province": {
+        "code": "73",
+        "links": {
+          "self": {
+            "href": "https://geogratis.gc.ca/services/geoname/en/codes/province/73"
+          }
+        }
+      },
+      "latitude": 80,
+      "longitude": -140,
+      "map": [
+        "079F11",
+        "079F12",
+        "079F14",
+        "089C04",
+        "089C05",
+        "089C06",
+        "089C07",
+        "089C08",
+        "089C09",
+        "089C10",
+        "089D12",
+        "089D13",
+        "089D14",
+        "089E02",
+        "089E03",
+        "089E04",
+        "089E06",
+        "089E07",
+        "089E08",
+        "089E09",
+        "099A06",
+        "099A07",
+        "099A09",
+        "099A10",
+        "099A15",
+        "099A16",
+        "099D01",
+        "107D12",
+        "107D"
+      ],
+      "relevance": 30000000,
+      "bbox": [-140.02, 79.98, -139.98, 80.02],
+      "accuracy": 100,
+      "position": {
+        "type": "Point",
+        "coordinates": [-140, 80]
+      },
+      "decision": "1983-11-23"
+    },
+    {
+      "id": "NAABI",
+      "links": {
+        "self": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/geonames/NAABI"
+        },
+        "feature": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/features/898da0a9ba3611d892e2080020a0f4c9"
+        },
+        "language": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/codes/language/und"
+        },
+        "status": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/codes/status/official"
+        },
+        "concise": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/codes/concise/SEA"
+        },
+        "generic": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/codes/generic/1212"
+        },
+        "province": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/codes/province/73"
+        }
+      },
+      "name": "Atlantic Ocean",
+      "language": {
+        "code": "und",
+        "links": {
+          "self": {
+            "href": "https://geogratis.gc.ca/services/geoname/en/codes/language/und"
+          }
+        }
+      },
+      "feature": {
+        "id": "898da0a9ba3611d892e2080020a0f4c9",
+        "links": {
+          "self": {
+            "href": "https://geogratis.gc.ca/services/geoname/en/features/898da0a9ba3611d892e2080020a0f4c9"
+          }
+        }
+      },
+      "category": "P",
+      "status": {
+        "code": "official",
+        "links": {
+          "self": {
+            "href": "https://geogratis.gc.ca/services/geoname/en/codes/status/official"
+          }
+        }
+      },
+      "concise": {
+        "code": "SEA",
+        "links": {
+          "self": {
+            "href": "https://geogratis.gc.ca/services/geoname/en/codes/concise/SEA"
+          }
+        }
+      },
+      "generic": {
+        "code": "1212",
+        "links": {
+          "self": {
+            "href": "https://geogratis.gc.ca/services/geoname/en/codes/generic/1212"
+          }
+        }
+      },
+      "location": null,
+      "province": {
+        "code": "73",
+        "links": {
+          "self": {
+            "href": "https://geogratis.gc.ca/services/geoname/en/codes/province/73"
+          }
+        }
+      },
+      "latitude": 43,
+      "longitude": -63,
+      "map": [
+        "010M03",
+        "001K11",
+        "001K12",
+        "001K13",
+        "001K14",
+        "001K15",
+        "001L13",
+        "001L14",
+        "001M03",
+        "001M04",
+        "001M07",
+        "001M12",
+        "001N02",
+        "001N07",
+        "001N10",
+        "001N13",
+        "002C06",
+        "002C13",
+        "002E03",
+        "002E05",
+        "002E07",
+        "002E10",
+        "002E11",
+        "002F12",
+        "002L12",
+        "003D04",
+        "010N16",
+        "010O13",
+        "011B"
+      ],
+      "relevance": 30000000,
+      "bbox": [-63.02, 42.98, -62.98, 43.02],
+      "accuracy": 100,
+      "position": {
+        "type": "Point",
+        "coordinates": [-63, 43]
+      },
+      "decision": "1983-11-23"
+    },
+    {
+      "id": "FEVNT",
+      "links": {
+        "self": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/geonames/FEVNT"
+        },
+        "feature": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/features/f7365c02d05211d892e2080020a0f4c9"
+        },
+        "language": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/codes/language/und"
+        },
+        "status": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/codes/status/official"
+        },
+        "concise": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/codes/concise/CITY"
+        },
+        "generic": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/codes/generic/1"
+        },
+        "province": {
+          "href": "https://geogratis.gc.ca/services/geoname/en/codes/province/35"
+        }
+      },
+      "name": "Ottawa",
+      "language": {
+        "code": "und",
+        "links": {
+          "self": {
+            "href": "https://geogratis.gc.ca/services/geoname/en/codes/language/und"
+          }
+        }
+      },
+      "feature": {
+        "id": "f7365c02d05211d892e2080020a0f4c9",
+        "links": {
+          "self": {
+            "href": "https://geogratis.gc.ca/services/geoname/en/features/f7365c02d05211d892e2080020a0f4c9"
+          }
+        }
+      },
+      "category": "O",
+      "status": {
+        "code": "official",
+        "links": {
+          "self": {
+            "href": "https://geogratis.gc.ca/services/geoname/en/codes/status/official"
+          }
+        }
+      },
+      "concise": {
+        "code": "CITY",
+        "links": {
+          "self": {
+            "href": "https://geogratis.gc.ca/services/geoname/en/codes/concise/CITY"
+          }
+        }
+      },
+      "generic": {
+        "code": "1",
+        "links": {
+          "self": {
+            "href": "https://geogratis.gc.ca/services/geoname/en/codes/generic/1"
+          }
+        }
+      },
+      "location": "Carleton; Russell",
+      "province": {
+        "code": "35",
+        "links": {
+          "self": {
+            "href": "https://geogratis.gc.ca/services/geoname/en/codes/province/35"
+          }
+        }
+      },
+      "latitude": 45.33339,
+      "longitude": -75.58429,
+      "map": [
+        "031G05",
+        "031G12",
+        "031G06",
+        "031G11",
+        "031F08",
+        "031F09",
+        "031G03",
+        "031G04",
+        "031F01",
+        "031B13"
+      ],
+      "relevance": 30000000,
+      "bbox": [-76.3631149, 44.9445516, -75.2324963, 45.544859],
+      "accuracy": 100,
+      "position": {
+        "type": "Point",
+        "coordinates": [-75.58429, 45.33339]
+      },
+      "decision": "2001-01-01"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/index.html b/index.html
index 18f6bf4a3..351808628 100644
--- a/index.html
+++ b/index.html
@@ -117,35 +117,57 @@
   </head>
   <body>
     
-    <mapml-viewer projection="OSMTILE" zoom="14" lat="45.406314" lon="-75.6883335" controls controlslist="geolocation">
-      <map-layer data-testid="osm-layer" label="OpenStreetMap" checked >
-        <map-link rel="license" title="© OpenStreetMap contributors CC BY-SA" href="https://www.openstreetmap.org/copyright"></map-link>
-        <map-extent units="OSMTILE" checked="checked">
-          <map-input name="z" type="zoom" value="18" min="0" max="18"></map-input>
-          <map-input name="x" type="location" units="tilematrix" axis="column" min="0" max="262144"></map-input>
-          <map-input name="y" type="location" units="tilematrix" axis="row" min="0" max="262144"></map-input>
-          <map-link rel="tile" tref="https://tile.openstreetmap.org/{z}/{x}/{y}.png"></map-link>
+    <mapml-viewer lang="en" projection="CBMTILE" controls controlslist="geolocation search" zoom="16" lat="45.406314" lon="-75.6883335">
+      <map-layer label="Canada Base Map - Transportation" checked>
+        <map-link rel="suggestions" tref="https://geogratis.gc.ca/services/geoname/en/geonames.json?q={searchTerms}*&num=20"></map-link>
+        <map-link rel="search" tref="https://geogratis.gc.ca/services/geoname/en/geonames.json?q={searchTerms}&num=20"></map-link>
+        <map-extent checked units="CBMTILE">
+          <map-meta name="extent" content="top-left-easting=-5388605, top-left-northing=7005413, bottom-right-easting=3895643, bottom-right-northing=-4427255"></map-meta>
+          <map-link rel="license" href="https://open.canada.ca/en/open-government-licence-canada" title="Open Government Licence - Canada"></map-link>
+          <map-input name="z" type="zoom" min="0" max="17" value="17"></map-input>
+          <map-input name="y" type="location" units="tilematrix" axis="row"></map-input>
+          <map-input name="x" type="location" units="tilematrix" axis="column"></map-input>
+          <map-link rel="tile" tref="https://geoappext.nrcan.gc.ca/arcgis/rest/services/BaseMaps/CBMT3978/MapServer/tile/{z}/{y}/{x}?m4h=t"></map-link>
         </map-extent>
       </map-layer>
-      <map-layer label="Restaurants" checked="">
-        <map-meta name="extent" content="top-left-easting=-8433179, top-left-northing=5689316, bottom-right-easting=-8420968, bottom-right-northing=5683139"></map-meta>
-        <map-extent units="OSMTILE" checked="">
-           <map-select id="restaurants" name="cusine">
-               <map-option value="restaurants" selected="selected">All cuisines</map-option>
-               <map-option value="african">African</map-option>
-               <map-option value="asian">Asian</map-option>
-               <map-option value="cajun">Cajun</map-option>
-               <map-option value="indian">Indian</map-option>
-               <map-option value="italian">Italian</map-option>
-               <map-option value="mexican">Mexican</map-option>
-           </map-select>
-           <map-link media="(11 < map-zoom <= 18)" tref="https://maps4html.org/experiments/shared/restaurants/{cusine}.mapml" rel="features"></map-link>
+      <map-layer label="Current Conditions" checked>
+        <map-link rel="license" href="https://csw.open.canada.ca/geonetwork/srv/csw?service=CSW&version=2.0.2&request=GetRecordById&outputschema=csw:IsoRecord&elementsetname=full&id=1f864766-7f7f-4be7-8292-295065c65c78" title="TC211 Metadata for Current Conditions"></map-link>
+        <map-link rel="legend" href="https://geo.weather.gc.ca/geomet?version=1.3.0&service=WMS&request=GetLegendGraphic&sld_version=1.1.0&layer=CURRENT_CONDITIONS&format=image/png&STYLE=default" title="default" width="35" height="5"></map-link>
+        <map-extent units="CBMTILE" checked="">
+          <map-input name="xmin" type="location" position="top-left" axis="easting" units="pcrs"></map-input>
+          <map-input name="ymin" type="location" position="bottom-left" axis="northing" units="pcrs"></map-input>
+          <map-input name="xmax" type="location" position="bottom-right" axis="easting" units="pcrs"></map-input>
+          <map-input name="ymax" type="location" position="top-right" axis="northing" units="pcrs"></map-input>
+          <map-input name="w" type="width" min="1" max="10000"></map-input>
+          <map-input name="h" type="height" min="1" max="10000"></map-input>
+          <map-input name="i" type="location" axis="i" units="map"></map-input>
+          <map-input name="j" type="location" axis="j" units="map"></map-input>
+          <map-select id="style-selector" name="style">
+            <map-option value="default" selected="">default</map-option>
+          </map-select>
+          <map-link rel="image" tref="https://geo.weather.gc.ca/geomet/?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetMap&LAYERS=CURRENT_CONDITIONS&WIDTH={w}&HEIGHT={h}&FORMAT=image%2Fpng&TRANSPARENT=TRUE&STYLES={style}&CRS=EPSG:3978&BBOX={xmin},{ymin},{xmax},{ymax}"></map-link>
+          <map-link rel="query" data-query-link="true" tref="https://geo.weather.gc.ca/geomet/?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetFeatureInfo&LAYERS=CURRENT_CONDITIONS&QUERY_LAYERS=CURRENT_CONDITIONS&WIDTH={w}&HEIGHT={h}&FORMAT=image%2Fpng&TRANSPARENT=TRUE&INFO_FORMAT=application%2Fjson&STYLES={style}&CRS=EPSG:3978&BBOX={xmin},{ymin},{xmax},{ymax}&I={i}&J={j}"></map-link>
         </map-extent>
       </map-layer>
+      <map-layer label="Photon Search" checked>
+        <map-meta name="projection" content="CBMTILE"></map-meta>
+        <map-link rel="suggestions" tref="https://photon.komoot.io/api?q={searchTerms}"></map-link>
+        <map-link rel="search" tref="https://photon.komoot.io/api?q={searchTerms}"></map-link>
+      </map-layer>
     </mapml-viewer>
-    <map is="web-map" projection="OSMTILE" zoom="14" lat="45.406314" lon="-75.6883335" controls controlslist="geolocation">
+    <map lang="fr" is="web-map" projection="OSMTILE" zoom="14" lat="45.406314" lon="-75.6883335" controls controlslist="geolocation search">
       <map-layer data-testid="osm-layer" label="OpenStreetMap" checked >
+
         <map-link rel="license" title="© OpenStreetMap contributors CC BY-SA" href="https://www.openstreetmap.org/copyright"></map-link>
+        <!-- Register your own geonames.org account at https://www.geonames.org/login
+             and enable web services at https://www.geonames.org/manageaccount
+             then replace username=demo with your username
+        <map-link rel="search" tref="https://secure.geonames.org/searchJSON?q={searchTerms}&maxRows=25&inclBbox=true&username=prushforth"></map-link>
+        <map-link rel="suggestions" tref="https://secure.geonames.org/searchJSON?name_startsWith={searchTerms}&maxRows=25&inclBbox=true&orderby=relevance&username=prushforth"></map-link>
+         -->
+        <!-- default search handler uses GeoJSON responses that have a quasi-standard 'schema' -->
+        <map-link rel="suggestions" tref="https://photon.komoot.io/api?q={searchTerms}"></map-link>
+        <map-link rel="search" tref="https://photon.komoot.io/api?q={searchTerms}"></map-link>
         <map-extent units="OSMTILE" checked="checked">
           <map-input name="z" type="zoom" value="18" min="0" max="18"></map-input>
           <map-input name="x" type="location" units="tilematrix" axis="column" min="0" max="262144"></map-input>
@@ -169,5 +191,125 @@
         </map-extent>
       </map-layer>
     </map>
+    <script>
+      document.addEventListener('DOMContentLoaded', () => {
+        const viewer = document.querySelector('mapml-viewer');
+
+        function renderResults(container, responses, map) {
+          container.innerHTML = '';
+          for (const r of responses) {
+            const data = r.data;
+            if (!data) continue;
+            // geogratis format (items array)
+            if (data.items) {
+              for (const item of data.items) {
+                const btn = document.createElement('button');
+                btn.className = 'mapml-search-result';
+                btn.setAttribute('type', 'button');
+                btn.textContent = item.name
+                  + (item.concise ? ' (' + item.concise.code + ')' : '')
+                  + (item.province ? ', ' + item.province.code : '');
+                btn.addEventListener('click', () => {
+                  if (item.bbox && item.bbox.length === 4) {
+                    const [west, south, east, north] = item.bbox;
+                    map.fitBounds([[south, west], [north, east]]);
+                  } else {
+                    map.setView([item.latitude, item.longitude], 10);
+                  }
+                  map._container
+                    .querySelector('.mapml-search-panel')
+                    .classList.remove('mapml-search-panel-open');
+                });
+                container.appendChild(btn);
+              }
+            }
+            // GeoJSON format (Photon etc.)
+            if (data.features) {
+              for (const feature of data.features) {
+                const props = feature.properties || {};
+                const parts = [props.name];
+                for (const key of ['city', 'county', 'state', 'country']) {
+                  if (props[key] && props[key] !== props.name) parts.push(props[key]);
+                }
+                const btn = document.createElement('button');
+                btn.className = 'mapml-search-result';
+                btn.setAttribute('type', 'button');
+                btn.textContent = parts.filter(Boolean).join(', ') || 'Unnamed';
+                btn.addEventListener('click', () => {
+                  const bbox = feature.bbox
+                    || (props.extent && props.extent.length === 4 ? props.extent : null);
+                  if (bbox && bbox.length === 4) {
+                    const [west, south, east, north] = bbox;
+                    map.fitBounds([[south, west], [north, east]]);
+                  } else if (feature.geometry && feature.geometry.coordinates) {
+                    const [lon, lat] = feature.geometry.coordinates;
+                    map.setView([lat, lon], props.zoom || 14);
+                  }
+                  map._container
+                    .querySelector('.mapml-search-panel')
+                    .classList.remove('mapml-search-panel-open');
+                });
+                container.appendChild(btn);
+              }
+            }
+          }
+        }
+
+        viewer.addEventListener('mapsuggestions', (e) => {
+          e.preventDefault();
+          const container = viewer._map._container.querySelector('.mapml-search-results');
+          renderResults(container, e.detail.responses, viewer._map);
+        });
+
+        viewer.addEventListener('mapsearch', (e) => {
+          e.preventDefault();
+          const container = viewer._map._container.querySelector('.mapml-search-results');
+          renderResults(container, e.detail.responses, viewer._map);
+        });
+
+        // --- geonames.org custom handler for the <map is="web-map"> element ---
+        // const webMap = document.querySelector('map[is=web-map]');
+
+        // function renderGeonamesOrgResults(container, geonames, map) {
+        //   container.innerHTML = '';
+        //   for (const item of geonames) {
+        //     const btn = document.createElement('button');
+        //     btn.className = 'mapml-search-result';
+        //     btn.setAttribute('type', 'button');
+        //     btn.textContent = item.name
+        //       + (item.adminName1 ? ', ' + item.adminName1 : '')
+        //       + (item.countryName ? ', ' + item.countryName : '');
+        //     btn.addEventListener('click', () => {
+        //       if (item.bbox) {
+        //         map.fitBounds([
+        //           [item.bbox.south, item.bbox.west],
+        //           [item.bbox.north, item.bbox.east]
+        //         ]);
+        //       } else {
+        //         map.setView([parseFloat(item.lat), parseFloat(item.lng)], 10);
+        //       }
+        //       map._container
+        //         .querySelector('.mapml-search-panel')
+        //         .classList.remove('mapml-search-panel-open');
+        //     });
+        //     container.appendChild(btn);
+        //   }
+        // }
+
+        // webMap.addEventListener('mapsuggestions', (e) => {
+        //   e.preventDefault();
+        //   const container = webMap._map._container.querySelector('.mapml-search-results');
+        //   const allGeonames = e.detail.responses.flatMap(r => (r.data && r.data.geonames) || []);
+        //   renderGeonamesOrgResults(container, allGeonames, webMap._map);
+        // });
+
+        // webMap.addEventListener('mapsearch', (e) => {
+        //   e.preventDefault();
+        //   const container = webMap._map._container.querySelector('.mapml-search-results');
+        //   const allGeonames = e.detail.responses.flatMap(r => (r.data && r.data.geonames) || []);
+        //   renderGeonamesOrgResults(container, allGeonames, webMap._map);
+        // });
+      });
+    </script>
   </body>
 </html>
diff --git a/package-lock.json b/package-lock.json
index 3a3810702..68a18a04e 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1012,6 +1012,21 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/fsevents": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
     "node_modules/function-bind": {
       "version": "1.1.2",
       "dev": true,
@@ -1889,7 +1904,7 @@
     },
     "node_modules/mapml-extension": {
       "version": "1.0.0",
-      "resolved": "git+ssh://git@github.com/Maps4HTML/mapml-extension.git#f5fed276bbed7735a50c7501f02ab383430c9c99",
+      "resolved": "git+ssh://git@github.com/Maps4HTML/mapml-extension.git#534fd64c01b736d4ea0383dcf7a0cfefce68026b",
       "dev": true,
       "license": "W3C"
     },
diff --git a/package.json b/package.json
index 1bdae5598..a3020da15 100644
--- a/package.json
+++ b/package.json
@@ -66,10 +66,10 @@
     "rollup": "^3.29.5",
     "serve-static": "^1.15.0"
   },
-    "files": [
-      "dist",
+  "files": [
+    "dist",
     "LICENSE.md",
     "README.md",
     "CONTRIBUTING.md"
-    ]
+  ]
 }
diff --git a/search-implementation-plan.md b/search-implementation-plan.md
new file mode 100644
index 000000000..29f410185
--- /dev/null
+++ b/search-implementation-plan.md
@@ -0,0 +1,108 @@
+---
+
+# Search Feature Implementation Plan
+
+Target: implement a search control for `<mapml-viewer>` / `<map is="web-map">`.  
+Reference design: search.md. Example service response: geonames.json.
+
+---
+
+## Phase 1 — UI Control (no network)
+
+**Goal:** render search button + slide-out panel; wire open/close and controlslist.
+
+**Create:**
+- `src/mapml/control/SearchButton.js`
+  - Extend leaflet `Control`, position `topleft`.
+  - Pattern: follow GeolocationButton.js / `ReloadButton.js`.
+  - Container: `div.mapml-search-control` with `<button>` (magnifying-glass inline SVG).
+  - Panel: `div.mapml-search-panel` (hidden initially, full map height, slides left-to-right over other controls).
+    - `<input type="search">` at top.
+    - `div.mapml-search-results` scrollable container.
+    - Left-pointing close `<button>` vertically centered on panel right edge.
+  - Click/Enter on icon → open panel + focus input.
+  - Escape or close button → close panel + return focus to icon.
+  - Export factory `searchButton(options)`.
+
+**Modify:**
+- mapml-viewer.js
+  - Import `searchButton`.
+  - Add `'search'` to DOMTokenList supported tokens (~line 191).
+  - `_createControls()`: create `this._searchButton` **first** (before zoom).
+  - `_hideControls()` / `_showControls()`: default hidden (opt-in).
+  - controlslist switch: `case 'search'` → show.
+  - `_deleteControls()`: delete `this._searchButton`.
+  - `_setControlsVisibility()` switch: `case 'search'`.
+- web-map.js — equivalent if it duplicates controlslist logic.
+- mapml.css — styles for `.mapml-search-control`, `.mapml-search-panel`, transitions.
+
+**Tests:** `test/e2e/core/searchControl.html` + `.test.js`
+- Button visible with `controlslist="search"`, hidden without.
+- Panel opens on click, input focused.
+- Panel closes on Escape / close button.
+- Panel full map height, overlays controls.
+
+---
+
+## Phase 2 — Default Handler (fetch + canonical formats)
+
+**Goal:** wire `<map-link rel="search|suggestions">` to the control; implement fetch, events, default handler.
+
+**Modify map-link.js:**
+- Add `'search'`, `'suggestions'` to rel allowed values.
+- `connectedCallback()`: store ref on parent layer (`layerEl._searchLink`, `layerEl._suggestionsLink`); only first per layer honored.
+- `disconnectedCallback()`: clear those refs.
+
+**Modify `src/mapml/control/SearchButton.js`:**
+- Disabled state: button has `aria-disabled="true"` and is visually grayed out when no visible layer has a `<map-link rel="search">` descendant. Panel does not open while disabled.
+- Enable/disable logic: listen for layer add/remove/checked/unchecked events; re-evaluate whether any visible layer has `_searchLink`. Update button state accordingly.
+- On debounced input (200ms, min 2 chars):
+  - Collect visible layers with `_suggestionsLink`.
+  - Resolve `tref` replacing `{searchTerms}` with URL-encoded value.
+  - Fetch all parallel (AbortController for stale).
+  - After all resolve → dispatch `mapsuggestions` CustomEvent on `<mapml-viewer>` with `{ cancelable: true, detail: { query, responses: [{response, layer}...], container } }`.
+  - If not `preventDefault()` → run default suggestions handler.
+- On Enter / suggestion click:
+  - Resolve source layer's `_searchLink.tref`.
+  - Fetch → dispatch `mapsearch` CustomEvent with `{ cancelable: true, detail: { query, response, layer, container } }`.
+  - If not `preventDefault()` → run default search handler.
+
+**Canonical formats:**
+- Suggestions: `[{ "text": "Ottawa", "layer": "places" }]`
+- Search: GeoJSON FeatureCollection with `bbox`, `geometry`, `properties.name`, `properties.zoom`, `properties.center`, `properties.layer`.
+
+**Tests:** `test/e2e/core/searchDefault.html` + `.test.js`
+- Mock routes in server.js.
+- Suggestions appear; results appear; click result → map moves; events fire correctly; duplicate rel ignored.
+
+---
+
+## Phase 3 — Custom Handler (geonames.gc.ca)
+
+**Goal:** demonstrate `preventDefault()` override using geonames response shape.
+
+**Create:**
+- `test/e2e/core/searchCustomHandler.html` — fixture with inline `<script>` that listens for `mapsuggestions`/`mapsearch`, calls `preventDefault()`, and parses geonames `items` array (`name`, `latitude`, `longitude`, `bbox`).
+- `test/e2e/core/searchCustomHandler.test.js` — mock route serves geonames.json content.
+  - Custom suggestions render item names.
+  - Default handler does NOT run.
+  - Click result → map moves.
+
+---
+
+## Implementation Notes
+
+- `{searchTerms}` substitution: simple string replace on `tref`.
+- Search icon: second control in top-left (created after zoom).
+- Panel inside shadow DOM → inherits mapml.css, grabs focus from map for scroll behaviour
+
+## Out of Scope
+
+- Viewport/extent search in `<map-extent>`.
+- Streaming/progressive dispatch.
+- Custom module-link declaration mechanism.
+- `type="text/mapml"` support.
+
+---
+
+Want me to write this to `search-implementation-plan.md` in the project root? (File creation is currently restricted on my end — you may need to paste it or enable the tool.)
\ No newline at end of file
diff --git a/search.md b/search.md
new file mode 100644
index 000000000..69b85b637
--- /dev/null
+++ b/search.md
@@ -0,0 +1,67 @@
+# MapML Search Draft
+
+Status: draft notes for agreed direction.
+
+## UI Control Notes
+
+- Search widget is part of map controls.
+- Tentative control placement: first in controls order, above zoom control.
+- Default affordance is a magnifying-glass icon that expands on pointer click or keyboard enter to a text input on a slide out panel.
+- Tentative expanded UI: left-to-right slide-out panel.
+- Panel layout: text input at top, panel height equals map height.
+- Panel close affordance: left-pointing close button/handle at mid-right edge.
+- Control is opt-in via `controlslist="search"` (like geolocation), not shown by default.
+- One control per map; multiple layers may participate in requests.
+- The search button is disabled (`aria-disabled="true"`, grayed out, panel will not open) when no visible `<map-layer>` has a descendant `<map-link rel="search">`. It becomes enabled when at least one visible layer provides a search link. This parallels the reload button being disabled when no movement has occurred.
+- Accessibility note: sliding over other controls may cause conflicts; mitigation remains TBD.
+
+## Markup and API Notes
+
+- Use `<map-link rel="search" ...>` for search endpoints.
+- Use `<map-link rel="suggestions" ...>` for suggestion endpoints.
+- Only the first `<map-link rel="search">` in a `<map-layer>` is honored.
+- Fixed template variable: `{searchTerms}`.
+- Do not require `type="text/mapml"` for this draft.
+
+### Suggestions
+
+- Media type: `application/json`.
+- Response body: array of objects with source-layer identification.
+
+Example:
+
+```json
+[
+  { "text": "kate spade", "layer": "poi" },
+  { "text": "katy perry", "layer": "events" }
+]
+```
+
+- `text` (string, required): suggestion label.
+- `layer` (string, required): source layer identifier/name.
+
+### Search Results
+
+- Preferred media type: `application/geo+json`.
+- Response body: GeoJSON `FeatureCollection`.
+- Each `Feature` must include `geometry` and `bbox`.
+- Required `properties` members:
+  - `zoom` (number)
+  - `center` (`[longitude, latitude]`)
+  - `layer` (string; semantics TBD)
+
+## Design Decisions
+
+1. **Handler rendering:** control passes a container reference via event detail (`e.detail.container`); handler appends HTML directly.
+2. **Fetch behavior:** control always fetches. A default handler supports a canonical JSON response format for each link type. Handler is overridable via `preventDefault()` on the event.
+3. **Multi-layer dispatch:** batched — one event fires after all layer responses arrive. May revisit for progressive dispatch later.
+4. **Search submit scope:** query only the source layer of the selected suggestion, not all layers. TBD empirically.
+
+## TBD
+
+- Final semantics/allowed values for `properties.layer`.
+- Whether `application/geo+json` is required or recommended.
+- Deduping/ranking for merged suggestions/results.
+- Canonical JSON response formats for default suggestion/search handlers.
+- Future enhancement: permit `<map-link rel="search">` in `<map-extent>` for viewport/spatial search.
+- Such enhanced search could use in-scope sibling `<map-input type="location">` variables in `tref` for parameters such as center point or bbox.
diff --git a/src/map-link.js b/src/map-link.js
index a2cfb943d..a2b744d0a 100644
--- a/src/map-link.js
+++ b/src/map-link.js
@@ -64,7 +64,9 @@ export class HTMLLinkElement extends HTMLElement {
         'zoomout',
         'legend',
         'query',
-        'stylesheet'
+        'stylesheet',
+        'search',
+        'suggestions'
       ].includes(val)
     ) {
       this.setAttribute('type', val);
@@ -313,6 +315,10 @@ export class HTMLLinkElement extends HTMLElement {
       case 'license':
         // this._createLicenseLink();
         break;
+      case 'search':
+      case 'suggestions':
+        // no-op: discoverable via DOM query from SearchButton
+        break;
     }
     // the media attribute uses / overrides the disabled attribute to enable or
     // disable the link, so at this point the #hasConnected must be true so
@@ -1113,6 +1119,8 @@ export class HTMLLinkElement extends HTMLElement {
         case 'zoomout':
         case 'legend':
         case 'license':
+        case 'search':
+        case 'suggestions':
           resolve();
           break;
         default:
diff --git a/src/mapml-viewer.js b/src/mapml-viewer.js
index 1aba83ec5..336f7858c 100644
--- a/src/mapml-viewer.js
+++ b/src/mapml-viewer.js
@@ -29,6 +29,7 @@ import { reloadButton } from './mapml/control/ReloadButton.js';
 import { scaleBar } from './mapml/control/ScaleBar.js';
 import { fullscreenButton } from './mapml/control/FullscreenButton.js';
 import { geolocationButton } from './mapml/control/GeolocationButton.js';
+import { searchButton } from './mapml/control/SearchButton.js';
 import { debugOverlay } from './mapml/layers/DebugOverlay.js';
 import { crosshair } from './mapml/layers/Crosshair.js';
 import { featureIndexOverlay } from './mapml/layers/FeatureIndexOverlay.js';
@@ -193,7 +194,8 @@ export class HTMLMapmlViewerElement extends HTMLElement {
             'nozoom',
             'nolayer',
             'noscale',
-            'geolocation'
+            'geolocation',
+            'search'
           ]
         );
 
@@ -500,6 +502,15 @@ export class HTMLMapmlViewerElement extends HTMLElement {
         })
         .addTo(this._map);
     }
+    if (
+      !this._searchButton &&
+      this._controlsList &&
+      this._controlsList.contains('search') &&
+      totalSize + 49 <= mapSize
+    ) {
+      totalSize += 49;
+      this._searchButton = searchButton({ mapEl: this }).addTo(this._map);
+    }
     if (!this._reloadButton && totalSize + 49 <= mapSize) {
       totalSize += 49;
       this._reloadButton = reloadButton().addTo(this._map);
@@ -526,6 +537,7 @@ export class HTMLMapmlViewerElement extends HTMLElement {
   }
 
   _hideControls() {
+    this._setControlsVisibility('search', true);
     this._setControlsVisibility('fullscreen', true);
     this._setControlsVisibility('layercontrol', true);
     this._setControlsVisibility('reload', true);
@@ -534,6 +546,7 @@ export class HTMLMapmlViewerElement extends HTMLElement {
     this._setControlsVisibility('scale', true);
   }
   _showControls() {
+    this._setControlsVisibility('search', true);
     this._setControlsVisibility('fullscreen', false);
     this._setControlsVisibility('layercontrol', false);
     this._setControlsVisibility('reload', false);
@@ -563,6 +576,14 @@ export class HTMLMapmlViewerElement extends HTMLElement {
           case 'geolocation':
             this._setControlsVisibility('geolocation', false);
             break;
+          case 'search':
+            if (!this._searchButton) {
+              this._searchButton = searchButton({ mapEl: this }).addTo(
+                this._map
+              );
+            }
+            this._setControlsVisibility('search', false);
+            break;
           case 'noscale':
             this._setControlsVisibility('scale', true);
             break;
@@ -576,6 +597,7 @@ export class HTMLMapmlViewerElement extends HTMLElement {
 
   // delete the map controls that are private properties of this custom element
   _deleteControls() {
+    delete this._searchButton;
     delete this._layerControl;
     delete this._zoomControl;
     delete this._reloadButton;
@@ -588,6 +610,11 @@ export class HTMLMapmlViewerElement extends HTMLElement {
   _setControlsVisibility(control, hide) {
     let container;
     switch (control) {
+      case 'search':
+        if (this._searchButton) {
+          container = this._searchButton._container;
+        }
+        break;
       case 'zoom':
         if (this._zoomControl) {
           container = this._zoomControl._container;
diff --git a/src/mapml.css b/src/mapml.css
index fbf6003a3..b6a92bf44 100644
--- a/src/mapml.css
+++ b/src/mapml.css
@@ -111,7 +111,7 @@ the browser)' */
   height: 44px !important;
   line-height: 44px !important;
   font-size: 34px !important;
-  font-weight: normal;
+  font-weight: bold;
   text-align: center;
 }
 
@@ -233,7 +233,7 @@ button.mapml-contextmenu-item:disabled {
  */
 
 .leaflet-control-fullscreen a {  
-  background-image: url("data:image/svg+xml,%0A%3Csvg width='26' height='52' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink'%3E%3Cg transform='translate(0 -1000.4)'%3E%3Cuse transform='translate(0 26)' width='100%25' height='100%25' xlink:href='%23a'/%3E%3Cuse transform='translate(0 26)' width='100%25' height='100%25' xlink:href='%23b'/%3E%3Cuse transform='translate(0 26)' width='100%25' height='100%25' xlink:href='%23c'/%3E%3Cuse transform='translate(0 26)' width='100%25' height='100%25' xlink:href='%23d'/%3E%3Cpath id='a' transform='translate(0 1000.4)' d='M5 15v6h6v-2H7v-4z' color='%23000' fill='%23404040'/%3E%3Cpath id='b' transform='translate(0 1000.4)' d='M21 15v6h-6v-2h4v-4z' color='%23000' fill='%23404040'/%3E%3Cpath d='M10 1037.4v4l1 1h4l1-1v-4l-1-1h-4z' color='%23000' fill='%23404040'/%3E%3Cpath id='d' d='M5 1011.4v-6h6v2H7v4z' color='%23000' fill='%23404040'/%3E%3Cpath id='c' d='M21 1011.4v-6h-6v2h4v4z' color='%23000' fill='%23404040'/%3E%3C/g%3E%3C/svg%3E");
+  background-image: url("data:image/svg+xml,%0A%3Csvg width='26' height='52' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink'%3E%3Cg transform='translate(0 -1000.4)'%3E%3Cuse transform='translate(0 26)' width='100%25' height='100%25' xlink:href='%23a'/%3E%3Cuse transform='translate(0 26)' width='100%25' height='100%25' xlink:href='%23b'/%3E%3Cuse transform='translate(0 26)' width='100%25' height='100%25' xlink:href='%23c'/%3E%3Cuse transform='translate(0 26)' width='100%25' height='100%25' xlink:href='%23d'/%3E%3Cpath id='a' transform='translate(0 1000.4)' d='M5 15v6h6v-2H7v-4z' color='%23000' fill='%23000'/%3E%3Cpath id='b' transform='translate(0 1000.4)' d='M21 15v6h-6v-2h4v-4z' color='%23000' fill='%23000'/%3E%3Cpath d='M10 1037.4v4l1 1h4l1-1v-4l-1-1h-4z' color='%23000' fill='%23000'/%3E%3Cpath id='d' d='M5 1011.4v-6h6v2H7v4z' color='%23000' fill='%23000'/%3E%3Cpath id='c' d='M21 1011.4v-6h-6v2h4v4z' color='%23000' fill='%23000'/%3E%3C/g%3E%3C/svg%3E");
   background-repeat: no-repeat;
   background-size: 38px 76px;
   background-position: 3px 3px;
@@ -974,3 +974,110 @@ label.mapml-layer-item-toggle {
 .mapml-tile-group > svg { 
     overflow: visible;
 }
+
+/* Search control */
+.mapml-search-control {
+  z-index: 1000;
+}
+.mapml-search-button {
+  width: 44px;
+  height: 44px;
+  line-height: 44px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  background: #fff;
+  border: none;
+  border-radius: 4px;
+  padding: 0;
+}
+.mapml-search-button:hover {
+  background: #f4f4f4;
+}
+.mapml-search-button[aria-disabled="true"] {
+  cursor: default;
+}
+.mapml-search-button[aria-disabled="true"]:hover {
+  background: #fff;
+}
+.mapml-search-panel[hidden] {
+  display: none !important;
+}
+.mapml-search-panel {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 250px;
+  height: 100%;
+  background: #fff;
+  box-shadow: 2px 0 5px rgba(0,0,0,0.2);
+  display: flex;
+  flex-direction: column;
+  transform: translateX(-100%);
+  transition: transform 0.2s ease-in-out;
+  z-index: 10000;
+}
+.mapml-search-panel-open {
+  transform: translateX(0);
+}
+.mapml-search-input {
+  width: calc(100% - 16px);
+  margin: 8px;
+  padding: 6px 8px;
+  border: 1px solid #ccc;
+  border-radius: 4px;
+  font-size: 14px;
+  box-sizing: border-box;
+}
+.mapml-search-input:focus {
+  outline: 2px solid #4A90D9;
+  border-color: #4A90D9;
+}
+.mapml-search-results {
+  flex: 1;
+  overflow-y: auto;
+  padding: 0 8px 8px;
+}
+.mapml-search-result {
+  display: block;
+  width: 100%;
+  padding: 8px;
+  border: none;
+  border-bottom: 1px solid #eee;
+  background: #fff;
+  text-align: left;
+  font-size: 13px;
+  cursor: pointer;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.mapml-search-result:hover {
+  background: #f0f0f0;
+}
+.mapml-search-result:focus {
+  outline: 2px solid #4A90D9;
+  outline-offset: -2px;
+}
+.mapml-search-close {
+  position: absolute;
+  right: -24px;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 24px;
+  height: 36px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  background: #fff;
+  border: 1px solid #ccc;
+  border-left: none;
+  border-radius: 0 4px 4px 0;
+  box-shadow: 2px 0 3px rgba(0,0,0,0.1);
+  visibility: hidden;
+}
+.mapml-search-panel-open .mapml-search-close {
+  visibility: visible;
+}
diff --git a/src/mapml/control/SearchButton.js b/src/mapml/control/SearchButton.js
new file mode 100644
index 000000000..ba97832e2
--- /dev/null
+++ b/src/mapml/control/SearchButton.js
@@ -0,0 +1,453 @@
+import { Control, DomUtil, DomEvent, latLngBounds } from 'leaflet';
+
+export var SearchButton = Control.extend({
+  options: {
+    position: 'topleft'
+  },
+  _getLocale: function (map) {
+    return map.options.mapEl && map.options.mapEl.locale
+      ? map.options.mapEl.locale
+      : M.options.locale;
+  },
+  onAdd: function (map) {
+    let locale = this._getLocale(map);
+    this._locale = locale;
+    let container = DomUtil.create('div', 'mapml-search-control leaflet-bar');
+
+    let button = DomUtil.create(
+      'button',
+      'mapml-search-button mapml-button',
+      container
+    );
+    button.setAttribute('type', 'button');
+    button.setAttribute('aria-label', locale.btnSearch || 'Search');
+    button.title = locale.btnSearch || 'Search';
+    button.innerHTML =
+      '<svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" height="24" width="24" viewBox="0 0 15 15" fill="currentColor">' +
+      '<path d="M6 0C9.31 0 12 2.69 12 6C12 7.3 11.59 8.5 10.89 9.48L14.71 13.29C15.1 13.68 15.1 14.32 14.71 14.71C14.32 15.1 13.68 15.1 13.29 14.71L9.48 10.89C8.5 11.59 7.3 12 6 12C2.69 12 0 9.31 0 6C0 2.69 2.69 0 6 0ZM6 2C3.79 2 2 3.79 2 6C2 8.21 3.79 10 6 10C8.21 10 10 8.21 10 6C10 3.79 8.21 2 6 2Z"/>' +
+      '</svg>';
+
+    DomEvent.disableClickPropagation(button);
+    DomEvent.on(button, 'click', DomEvent.stop);
+    DomEvent.on(button, 'click', this._openPanel, this);
+    DomEvent.on(
+      button,
+      'keydown',
+      function (e) {
+        if (e.key === 'Enter') {
+          DomEvent.stop(e);
+          this._openPanel();
+        }
+      },
+      this
+    );
+
+    this._button = button;
+
+    let panel = DomUtil.create('div', 'mapml-search-panel');
+    panel.setAttribute('hidden', '');
+    map.getContainer().appendChild(panel);
+    DomEvent.disableClickPropagation(panel);
+    DomEvent.on(panel, 'mouseenter', function () {
+      map.scrollWheelZoom.disable();
+    });
+    DomEvent.on(panel, 'mouseleave', function () {
+      map.scrollWheelZoom.enable();
+    });
+    DomEvent.on(panel, 'wheel', DomEvent.stopPropagation);
+
+    let input = DomUtil.create('input', 'mapml-search-input', panel);
+    input.setAttribute('type', 'search');
+    input.setAttribute('placeholder', locale.searchPlaceholder || 'Search...');
+    input.setAttribute('aria-label', locale.btnSearch || 'Search');
+
+    DomEvent.disableClickPropagation(input);
+    DomEvent.on(
+      input,
+      'keydown',
+      function (e) {
+        if (e.key === 'Escape') {
+          DomEvent.stop(e);
+          this._closePanel();
+        } else if (e.key === 'Enter') {
+          DomEvent.stop(e);
+          if (this._debounceTimer) {
+            clearTimeout(this._debounceTimer);
+            this._debounceTimer = null;
+          }
+          this._doSearch(this._input.value.trim());
+        }
+      },
+      this
+    );
+
+    // Debounced input handler for suggestions
+    this._debounceTimer = null;
+    this._abortController = null;
+    // Track IME composition to avoid searching on intermediate input
+    this._isComposing = false;
+    DomEvent.on(
+      input,
+      'compositionstart',
+      function () {
+        this._isComposing = true;
+      },
+      this
+    );
+    DomEvent.on(
+      input,
+      'compositionend',
+      function () {
+        this._isComposing = false;
+        // Trigger search after composition ends
+        let query = this._input.value.trim();
+        if (query.length < 2) {
+          this._results.innerHTML = '';
+          return;
+        }
+        if (this._debounceTimer) clearTimeout(this._debounceTimer);
+        this._debounceTimer = setTimeout(() => {
+          this._fetchSuggestions(query);
+        }, 300);
+      },
+      this
+    );
+    DomEvent.on(
+      input,
+      'input',
+      function () {
+        if (this._isComposing) return;
+        if (this._debounceTimer) clearTimeout(this._debounceTimer);
+        let query = this._input.value.trim();
+        if (query.length < 2) {
+          this._results.innerHTML = '';
+          return;
+        }
+        this._debounceTimer = setTimeout(() => {
+          this._fetchSuggestions(query);
+        }, 300);
+      },
+      this
+    );
+
+    this._input = input;
+
+    let results = DomUtil.create('div', 'mapml-search-results', panel);
+    this._results = results;
+
+    let closeBtn = DomUtil.create(
+      'button',
+      'mapml-search-close mapml-button',
+      panel
+    );
+    closeBtn.setAttribute('type', 'button');
+    closeBtn.setAttribute(
+      'aria-label',
+      locale.btnSearchClose || 'Close search'
+    );
+    closeBtn.title = locale.btnSearchClose || 'Close search';
+    closeBtn.innerHTML =
+      '<svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" height="18" width="18" viewBox="0 0 24 24" fill="currentColor">' +
+      '<path d="M15.41 16.59L10.83 12l4.58-4.59L14 6l-6 6 6 6 1.41-1.41z"/>' +
+      '</svg>';
+
+    DomEvent.disableClickPropagation(closeBtn);
+    DomEvent.on(closeBtn, 'click', DomEvent.stop);
+    DomEvent.on(closeBtn, 'click', this._closePanel, this);
+
+    this._closeBtn = closeBtn;
+    this._panel = panel;
+
+    this._mapEl = map.options.mapEl;
+
+    // Set up layer observation for disabled state
+    this._onLoadedMetadata = () => this._updateDisabled();
+    this._layerObserver = new MutationObserver((mutations) => {
+      this._updateDisabled();
+      // When new layers are added, listen for their loadedmetadata
+      for (let mutation of mutations) {
+        for (let node of mutation.addedNodes) {
+          if (
+            node.nodeName &&
+            (node.nodeName.toUpperCase() === 'MAP-LAYER' ||
+              node.nodeName.toUpperCase() === 'LAYER-')
+          ) {
+            node.addEventListener('loadedmetadata', this._onLoadedMetadata);
+          }
+        }
+      }
+    });
+    this._layerObserver.observe(this._mapEl, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['checked', 'rel']
+    });
+    // Attach loadedmetadata listener to existing layers
+    this._mapEl
+      .querySelectorAll('map-layer, layer-')
+      .forEach((layer) =>
+        layer.addEventListener('loadedmetadata', this._onLoadedMetadata)
+      );
+
+    this._updateDisabled();
+
+    return container;
+  },
+
+  onRemove: function () {
+    if (this._panel && this._panel.parentNode) {
+      this._panel.parentNode.removeChild(this._panel);
+    }
+    if (this._layerObserver) {
+      this._layerObserver.disconnect();
+    }
+    if (this._mapEl) {
+      this._mapEl
+        .querySelectorAll('map-layer, layer-')
+        .forEach((layer) =>
+          layer.removeEventListener('loadedmetadata', this._onLoadedMetadata)
+        );
+    }
+    DomEvent.off(this._button, 'click', this._openPanel, this);
+    DomEvent.off(this._closeBtn, 'click', this._closePanel, this);
+  },
+
+  _hasSearchLayers: function () {
+    let layers = this._mapEl.querySelectorAll(
+      'map-layer[checked], layer-[checked]'
+    );
+    for (let layer of layers) {
+      let root = layer.src ? layer.shadowRoot : layer;
+      if (root && root.querySelector('map-link[rel=search]')) {
+        return true;
+      }
+    }
+    return false;
+  },
+
+  _updateDisabled: function () {
+    let hasSearch = this._hasSearchLayers();
+    if (hasSearch) {
+      this._button.setAttribute('aria-disabled', 'false');
+    } else {
+      this._button.setAttribute('aria-disabled', 'true');
+      // If panel is open, close it
+      if (!this._panel.hasAttribute('hidden')) {
+        this._closePanel();
+      }
+    }
+  },
+
+  _openPanel: function () {
+    if (this._button.getAttribute('aria-disabled') === 'true') return;
+    this._panel.removeAttribute('hidden');
+    this._input.value = '';
+    this._results.innerHTML = '';
+    setTimeout(() => {
+      this._panel.classList.add('mapml-search-panel-open');
+      this._input.focus();
+    }, 0);
+  },
+
+  _closePanel: function () {
+    this._panel.classList.remove('mapml-search-panel-open');
+    if (this._abortController) {
+      this._abortController.abort();
+      this._abortController = null;
+    }
+    if (this._debounceTimer) {
+      clearTimeout(this._debounceTimer);
+      this._debounceTimer = null;
+    }
+    let onEnd = () => {
+      this._panel.setAttribute('hidden', '');
+      this._button.focus();
+      this._panel.removeEventListener('transitionend', onEnd);
+    };
+    this._panel.addEventListener('transitionend', onEnd);
+    setTimeout(onEnd, 300);
+  },
+
+  _getLinks: function (rel) {
+    let results = [];
+    let layers = this._mapEl.querySelectorAll(
+      'map-layer[checked], layer-[checked]'
+    );
+    for (let layer of layers) {
+      let root = layer.src ? layer.shadowRoot : layer;
+      if (root) {
+        let link = root.querySelector('map-link[rel=' + rel + ']');
+        if (link) {
+          results.push({ link: link, layer: layer });
+        }
+      }
+    }
+    return results;
+  },
+
+  _getSearchLinks: function () {
+    return this._getLinks('search');
+  },
+
+  _getSuggestionsLinks: function () {
+    return this._getLinks('suggestions');
+  },
+
+  _resolveUrl: function (link, query) {
+    let tref = link.getAttribute('tref') || '';
+    let url = tref.replace('{searchTerms}', encodeURIComponent(query));
+    if (link.getBase) {
+      try {
+        return new URL(url, link.getBase()).href;
+      } catch (e) {
+        return url;
+      }
+    }
+    return url;
+  },
+
+  _fetchSuggestions: function (query) {
+    if (this._button.getAttribute('aria-disabled') === 'true') return;
+    let suggestionsLinks = this._getSuggestionsLinks();
+    if (suggestionsLinks.length === 0) return;
+
+    if (this._abortController) this._abortController.abort();
+    this._abortController = new AbortController();
+    let signal = this._abortController.signal;
+
+    let fetches = suggestionsLinks.map(({ link, layer }) => {
+      let url = this._resolveUrl(link, query);
+      return fetch(url, { signal })
+        .then((r) => r.json())
+        .then((data) => ({ data, link, layer }));
+    });
+
+    Promise.allSettled(fetches).then((settled) => {
+      if (signal.aborted) return;
+      let responses = settled
+        .filter((s) => s.status === 'fulfilled')
+        .map((s) => s.value);
+
+      let event = new CustomEvent('mapsuggestions', {
+        bubbles: true,
+        cancelable: true,
+        detail: { query, responses }
+      });
+      let cancelled = !this._mapEl.dispatchEvent(event);
+      if (!cancelled) {
+        this._defaultSuggestionsHandler({ query, responses });
+      }
+    });
+  },
+
+  _doSearch: function (query) {
+    if (!query || this._button.getAttribute('aria-disabled') === 'true') return;
+    let searchLinks = this._getSearchLinks();
+    if (searchLinks.length === 0) return;
+
+    if (this._abortController) this._abortController.abort();
+    this._abortController = new AbortController();
+    let signal = this._abortController.signal;
+
+    let fetches = searchLinks.map(({ link, layer }) => {
+      let url = this._resolveUrl(link, query);
+      return fetch(url, { signal })
+        .then((r) => r.json())
+        .then((data) => ({ data, link, layer }));
+    });
+
+    Promise.allSettled(fetches).then((settled) => {
+      if (signal.aborted) return;
+      let responses = settled
+        .filter((s) => s.status === 'fulfilled')
+        .map((s) => s.value);
+
+      let event = new CustomEvent('mapsearch', {
+        bubbles: true,
+        cancelable: true,
+        detail: { query, responses }
+      });
+      let cancelled = !this._mapEl.dispatchEvent(event);
+      if (!cancelled) {
+        this._defaultSearchHandler({ query, responses });
+      }
+    });
+  },
+
+  _defaultSuggestionsHandler: function ({ query, responses }) {
+    this._renderResults(responses);
+  },
+
+  _defaultSearchHandler: function ({ query, responses }) {
+    this._renderResults(responses);
+  },
+
+  _renderResults: function (responses) {
+    this._results.innerHTML = '';
+    for (let { data, layer } of responses) {
+      if (!data || !data.features) continue;
+      for (let feature of data.features) {
+        let btn = document.createElement('button');
+        btn.className = 'mapml-search-result';
+        btn.setAttribute('type', 'button');
+        btn.textContent = this._formatResultName(feature.properties);
+        btn.addEventListener(
+          'click',
+          (
+            (f, l) => () =>
+              this._selectResult(f, l)
+          )(feature, layer)
+        );
+        this._results.appendChild(btn);
+      }
+    }
+  },
+
+  _formatResultName: function (props) {
+    if (!props) return this._locale?.searchResultWithNoName || 'Unnamed';
+    if (props.display_name) return props.display_name;
+    let parts = [props.name];
+    // Build context from common geocoder properties (Photon, etc.)
+    for (let key of ['city', 'county', 'state', 'country']) {
+      if (props[key] && props[key] !== props.name) parts.push(props[key]);
+    }
+    return (
+      parts.filter(Boolean).join(', ') ||
+      this._locale?.searchResultWithNoName ||
+      'Unnamed'
+    );
+  },
+
+  _selectResult: function (feature, layer) {
+    let map = this._map;
+    // Standard GeoJSON bbox
+    let bbox = feature.bbox;
+    // Photon stores extent in properties.extent [west, south, east, north]
+    if (
+      (!bbox || bbox.length !== 4) &&
+      feature.properties &&
+      feature.properties.extent &&
+      feature.properties.extent.length === 4
+    ) {
+      bbox = feature.properties.extent;
+    }
+    if (bbox && bbox.length === 4) {
+      let [west, south, east, north] = bbox;
+      map.fitBounds(latLngBounds([south, west], [north, east]));
+    } else if (
+      feature.geometry &&
+      feature.geometry.coordinates &&
+      feature.geometry.coordinates.length >= 2
+    ) {
+      let [lon, lat] = feature.geometry.coordinates;
+      let zoom = (feature.properties && feature.properties.zoom) || 14;
+      map.setView([lat, lon], zoom);
+    }
+    this._closePanel();
+  }
+});
+
+export var searchButton = function (options) {
+  return new SearchButton(options);
+};
diff --git a/src/web-map.js b/src/web-map.js
index 6b047b899..e7ab59fb6 100644
--- a/src/web-map.js
+++ b/src/web-map.js
@@ -17,6 +17,7 @@ import { reloadButton } from './mapml/control/ReloadButton.js';
 import { scaleBar } from './mapml/control/ScaleBar.js';
 import { fullscreenButton } from './mapml/control/FullscreenButton.js';
 import { geolocationButton } from './mapml/control/GeolocationButton.js';
+import { searchButton } from './mapml/control/SearchButton.js';
 import { debugOverlay } from './mapml/layers/DebugOverlay.js';
 import { crosshair } from './mapml/layers/Crosshair.js';
 import { featureIndexOverlay } from './mapml/layers/FeatureIndexOverlay.js';
@@ -184,7 +185,8 @@ export class HTMLWebMapElement extends HTMLMapElement {
             'nozoom',
             'nolayer',
             'noscale',
-            'geolocation'
+            'geolocation',
+            'search'
           ]
         );
 
@@ -542,6 +544,15 @@ export class HTMLWebMapElement extends HTMLMapElement {
         })
         .addTo(this._map);
     }
+    if (
+      !this._searchButton &&
+      this._controlsList &&
+      this._controlsList.contains('search') &&
+      totalSize + 49 <= mapSize
+    ) {
+      totalSize += 49;
+      this._searchButton = searchButton({ mapEl: this }).addTo(this._map);
+    }
     if (!this._reloadButton && totalSize + 49 <= mapSize) {
       totalSize += 49;
       this._reloadButton = reloadButton().addTo(this._map);
@@ -568,6 +579,7 @@ export class HTMLWebMapElement extends HTMLMapElement {
   }
 
   _hideControls() {
+    this._setControlsVisibility('search', true);
     this._setControlsVisibility('fullscreen', true);
     this._setControlsVisibility('layercontrol', true);
     this._setControlsVisibility('reload', true);
@@ -576,6 +588,7 @@ export class HTMLWebMapElement extends HTMLMapElement {
     this._setControlsVisibility('scale', true);
   }
   _showControls() {
+    this._setControlsVisibility('search', true);
     this._setControlsVisibility('fullscreen', false);
     this._setControlsVisibility('layercontrol', false);
     this._setControlsVisibility('reload', false);
@@ -605,6 +618,14 @@ export class HTMLWebMapElement extends HTMLMapElement {
           case 'geolocation':
             this._setControlsVisibility('geolocation', false);
             break;
+          case 'search':
+            if (!this._searchButton) {
+              this._searchButton = searchButton({ mapEl: this }).addTo(
+                this._map
+              );
+            }
+            this._setControlsVisibility('search', false);
+            break;
           case 'noscale':
             this._setControlsVisibility('scale', true);
             break;
@@ -618,6 +639,7 @@ export class HTMLWebMapElement extends HTMLMapElement {
 
   // delete the map controls that are private properties of this custom element
   _deleteControls() {
+    delete this._searchButton;
     delete this._layerControl;
     delete this._zoomControl;
     delete this._reloadButton;
@@ -630,6 +652,11 @@ export class HTMLWebMapElement extends HTMLMapElement {
   _setControlsVisibility(control, hide) {
     let container;
     switch (control) {
+      case 'search':
+        if (this._searchButton) {
+          container = this._searchButton._container;
+        }
+        break;
       case 'zoom':
         if (this._zoomControl) {
           container = this._zoomControl._container;
diff --git a/test/e2e/api/domApi-mapml-viewer.test.js b/test/e2e/api/domApi-mapml-viewer.test.js
index c6fccf982..f994dea06 100644
--- a/test/e2e/api/domApi-mapml-viewer.test.js
+++ b/test/e2e/api/domApi-mapml-viewer.test.js
@@ -803,6 +803,75 @@ test.describe('mapml-viewer DOM API Tests', () => {
       expect(geolocation).toEqual(true);
       expect(reloadHidden).toEqual(true);
     });
+    test('controlslist search test', async () => {
+      const viewerHandle = await page.evaluateHandle(() =>
+        document.querySelector('mapml-viewer')
+      );
+
+      // search control should not exist by default (opt-in, lazily created)
+      let searchEl = await page.$(
+        '.leaflet-top.leaflet-left > .mapml-search-control'
+      );
+      expect(searchEl).toBeNull();
+
+      // enable search via controlslist attribute
+      await page.evaluate(
+        (viewer) => viewer.setAttribute('controlslist', 'search'),
+        viewerHandle
+      );
+      let hascontrolslist = await page.evaluate(
+        (viewer) => viewer.getAttribute('controlslist'),
+        viewerHandle
+      );
+      expect(hascontrolslist).toEqual('search');
+
+      let searchHidden = await page.$eval(
+        '.leaflet-top.leaflet-left > .mapml-search-control',
+        (div) => div.hidden
+      );
+      expect(searchHidden).toEqual(false);
+
+      // remove search via controlsList property
+      await page.evaluate(
+        (viewer) => (viewer.controlsList = 'noreload'),
+        viewerHandle
+      );
+      hascontrolslist = await page.evaluate(
+        (viewer) => viewer.getAttribute('controlslist'),
+        viewerHandle
+      );
+      expect(hascontrolslist).toEqual('noreload');
+
+      searchHidden = await page.$eval(
+        '.leaflet-top.leaflet-left > .mapml-search-control',
+        (div) => div.hidden
+      );
+      expect(searchHidden).toEqual(true);
+
+      // enable search via controlsList property
+      await page.evaluate(
+        (viewer) => (viewer.controlsList = 'search'),
+        viewerHandle
+      );
+      searchHidden = await page.$eval(
+        '.leaflet-top.leaflet-left > .mapml-search-control',
+        (div) => div.hidden
+      );
+      expect(searchHidden).toEqual(false);
+
+      // controlsList.supports('search') should be true
+      let searchSupported = await page.evaluate(
+        (viewer) => viewer.controlsList.supports('search'),
+        viewerHandle
+      );
+      expect(searchSupported).toBe(true);
+
+      // reset controlslist for next test
+      await page.evaluate(
+        (viewer) => viewer.removeAttribute('controlslist'),
+        viewerHandle
+      );
+    });
     test('controlslist removeAttribute', async () => {
       const viewerHandle = await page.evaluateHandle(() =>
         document.querySelector('mapml-viewer')
diff --git a/test/e2e/api/domApi-web-map.test.js b/test/e2e/api/domApi-web-map.test.js
index acba1b827..743f01f16 100644
--- a/test/e2e/api/domApi-web-map.test.js
+++ b/test/e2e/api/domApi-web-map.test.js
@@ -782,6 +782,69 @@ test.describe('web-map DOM API Tests', () => {
       expect(geolocation).toEqual(true);
       expect(reloadHidden).toEqual(true);
     });
+    test('controlslist search test', async () => {
+      const mapHandle = await page.evaluateHandle(() =>
+        document.querySelector('map')
+      );
+
+      // search control should not exist by default (opt-in, lazily created)
+      let searchEl = await page.$(
+        '.leaflet-top.leaflet-left > .mapml-search-control'
+      );
+      expect(searchEl).toBeNull();
+
+      // enable search via controlslist attribute
+      await page.evaluate(
+        (map) => map.setAttribute('controlslist', 'search'),
+        mapHandle
+      );
+      let hascontrolslist = await page.evaluate(
+        (map) => map.getAttribute('controlslist'),
+        mapHandle
+      );
+      expect(hascontrolslist).toEqual('search');
+
+      let searchHidden = await page.$eval(
+        '.leaflet-top.leaflet-left > .mapml-search-control',
+        (div) => div.hidden
+      );
+      expect(searchHidden).toEqual(false);
+
+      // remove search via controlsList property
+      await page.evaluate((map) => (map.controlsList = 'noreload'), mapHandle);
+      hascontrolslist = await page.evaluate(
+        (map) => map.getAttribute('controlslist'),
+        mapHandle
+      );
+      expect(hascontrolslist).toEqual('noreload');
+
+      searchHidden = await page.$eval(
+        '.leaflet-top.leaflet-left > .mapml-search-control',
+        (div) => div.hidden
+      );
+      expect(searchHidden).toEqual(true);
+
+      // enable search via controlsList property
+      await page.evaluate((map) => (map.controlsList = 'search'), mapHandle);
+      searchHidden = await page.$eval(
+        '.leaflet-top.leaflet-left > .mapml-search-control',
+        (div) => div.hidden
+      );
+      expect(searchHidden).toEqual(false);
+
+      // controlsList.supports('search') should be true
+      let searchSupported = await page.evaluate(
+        (map) => map.controlsList.supports('search'),
+        mapHandle
+      );
+      expect(searchSupported).toBe(true);
+
+      // reset controlslist for next test
+      await page.evaluate(
+        (map) => map.removeAttribute('controlslist'),
+        mapHandle
+      );
+    });
     test('controlslist removeAttribute', async () => {
       const mapHandle = await page.evaluateHandle(() =>
         document.querySelector('map')
diff --git a/test/e2e/api/events/map-change-event.test.js b/test/e2e/api/events/map-change-event.test.js
index 6f96d0a6b..997a450d0 100644
--- a/test/e2e/api/events/map-change-event.test.js
+++ b/test/e2e/api/events/map-change-event.test.js
@@ -11,7 +11,9 @@ test.describe('Map-change event are only fired when layers/extents are checked o
     page =
       context.pages().find((page) => page.url() === 'about:blank') ||
       (await context.newPage());
-    await page.goto('events/map-change-event.html');
+    await page.goto('events/map-change-event.html', {
+      waitUntil: 'networkidle'
+    });
   });
 
   test.afterAll(async function () {
diff --git a/test/e2e/api/locateApi.test.js b/test/e2e/api/locateApi.test.js
index a2af63e66..0f1cda876 100644
--- a/test/e2e/api/locateApi.test.js
+++ b/test/e2e/api/locateApi.test.js
@@ -79,7 +79,7 @@ test.describe('Locate API Test', () => {
   });
 
   test('Testing API when the button is used', async () => {
-    await page.reload();
+    await page.reload({ waitUntil: 'networkidle' });
     await page.click('body > mapml-viewer');
     await page.getByTitle('Show my location - location tracking off').click();
 
@@ -88,6 +88,7 @@ test.describe('Locate API Test', () => {
     await page.mouse.move(1200, 450, { steps: 5 });
     await page.mouse.up();
     await page.$eval('body > mapml-viewer', (viewer) => viewer.locate());
+    await page.waitForTimeout(1000);
 
     let locateAPI_lat = await page.$eval(
       'body > mapml-viewer',
diff --git a/test/e2e/core/searchCustomHandler.html b/test/e2e/core/searchCustomHandler.html
new file mode 100644
index 000000000..38678d813
--- /dev/null
+++ b/test/e2e/core/searchCustomHandler.html
@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Search Custom Handler Tests</title>
+    <script type="module" src="mapml.js"></script>
+  </head>
+  <body>
+    <mapml-viewer
+      data-testid="viewer"
+      projection="CBMTILE"
+      zoom="5"
+      lat="45.4"
+      lon="-75.7"
+      style="width: 600px; height: 400px;"
+      controls
+      controlslist="search"
+    >
+      <map-layer
+        data-testid="search-layer"
+        label="Geonames Layer"
+        src="search-geonames.mapml"
+        checked
+      ></map-layer>
+    </mapml-viewer>
+    <script>
+      document.addEventListener('DOMContentLoaded', () => {
+        const viewer = document.querySelector('[data-testid=viewer]');
+
+        // Custom suggestions handler — parse geonames items array
+        viewer.addEventListener('mapsuggestions', (e) => {
+          e.preventDefault();
+          const container = viewer._map._container.querySelector(
+            '.mapml-search-results'
+          );
+          container.innerHTML = '';
+          for (const { data } of e.detail.responses) {
+            if (!data || !data.items) continue;
+            for (const item of data.items) {
+              const btn = document.createElement('button');
+              btn.className = 'mapml-search-result';
+              btn.setAttribute('type', 'button');
+              btn.dataset.lat = item.latitude;
+              btn.dataset.lon = item.longitude;
+              if (item.bbox) {
+                btn.dataset.bbox = JSON.stringify(item.bbox);
+              }
+              btn.textContent = item.name;
+              btn.addEventListener('click', () => {
+                if (item.bbox && item.bbox.length === 4) {
+                  const [west, south, east, north] = item.bbox;
+                  viewer._map.fitBounds([
+                    [south, west],
+                    [north, east]
+                  ]);
+                } else {
+                  viewer._map.setView([item.latitude, item.longitude], 10);
+                }
+                // close the panel
+                viewer._map._container
+                  .querySelector('.mapml-search-panel')
+                  .classList.remove('mapml-search-panel-open');
+              });
+              container.appendChild(btn);
+            }
+          }
+        });
+
+        // Custom search handler — parse geonames items array
+        viewer.addEventListener('mapsearch', (e) => {
+          e.preventDefault();
+          const container = viewer._map._container.querySelector(
+            '.mapml-search-results'
+          );
+          container.innerHTML = '';
+          for (const { data } of e.detail.responses) {
+            if (!data || !data.items) continue;
+            for (const item of data.items) {
+              const btn = document.createElement('button');
+              btn.className = 'mapml-search-result';
+              btn.setAttribute('type', 'button');
+              btn.dataset.lat = item.latitude;
+              btn.dataset.lon = item.longitude;
+              if (item.bbox) {
+                btn.dataset.bbox = JSON.stringify(item.bbox);
+              }
+              btn.textContent = item.name;
+              btn.addEventListener('click', () => {
+                if (item.bbox && item.bbox.length === 4) {
+                  const [west, south, east, north] = item.bbox;
+                  viewer._map.fitBounds([
+                    [south, west],
+                    [north, east]
+                  ]);
+                } else {
+                  viewer._map.setView([item.latitude, item.longitude], 10);
+                }
+                viewer._map._container
+                  .querySelector('.mapml-search-panel')
+                  .classList.remove('mapml-search-panel-open');
+              });
+              container.appendChild(btn);
+            }
+          }
+        });
+      });
+    </script>
+  </body>
+</html>
diff --git a/test/e2e/core/searchCustomHandler.test.js b/test/e2e/core/searchCustomHandler.test.js
new file mode 100644
index 000000000..95ed200d5
--- /dev/null
+++ b/test/e2e/core/searchCustomHandler.test.js
@@ -0,0 +1,97 @@
+import { test, expect, chromium } from '@playwright/test';
+
+test.describe('Search custom handler tests', () => {
+  let page;
+  let context;
+  test.beforeAll(async () => {
+    context = await chromium.launchPersistentContext('');
+    page =
+      context.pages().find((page) => page.url() === 'about:blank') ||
+      (await context.newPage());
+    await page.goto('searchCustomHandler.html', { waitUntil: 'networkidle' });
+    await page.waitForTimeout(1000);
+  });
+  test.afterAll(async () => {
+    await context.close();
+  });
+
+  test('Search button is enabled when layer has search link', async () => {
+    let disabled = await page.$eval('.mapml-search-button', (btn) =>
+      btn.getAttribute('aria-disabled')
+    );
+    expect(disabled).toBe('false');
+  });
+
+  test('Custom suggestions handler renders geonames item names', async () => {
+    // Open the panel
+    await page.click('.mapml-search-button');
+    await page.waitForTimeout(400);
+    // Type a query
+    await page.fill('.mapml-search-input', 'Ottawa');
+    // Wait for debounce + fetch + custom handler
+    await page.waitForSelector('.mapml-search-result', { timeout: 5000 });
+    let texts = await page.$$eval('.mapml-search-result', (btns) =>
+      btns.map((b) => b.textContent)
+    );
+    expect(texts).toEqual(['Ottawa', 'Arctic Ocean', 'Atlantic Ocean']);
+  });
+
+  test('Default suggestions handler does NOT run', async () => {
+    // If default handler ran, results would show display_name (GeoJSON format)
+    // Custom handler shows just the name from geonames items
+    let texts = await page.$$eval('.mapml-search-result', (btns) =>
+      btns.map((b) => b.textContent)
+    );
+    // None should contain comma-separated address (default handler pattern)
+    for (let text of texts) {
+      expect(text).not.toContain(',');
+    }
+  });
+
+  test('Clicking a suggestion result with bbox fits bounds', async () => {
+    // Click Ottawa (first result — has bbox)
+    await page.click('.mapml-search-result:first-child');
+    await page.waitForTimeout(500);
+    // Panel should be closed
+    let hasOpenClass = await page.$eval('.mapml-search-panel', (panel) =>
+      panel.classList.contains('mapml-search-panel-open')
+    );
+    expect(hasOpenClass).toBe(false);
+    // Map center should be roughly Ottawa area
+    let center = await page.$eval('[data-testid=viewer]', (viewer) => {
+      let map = viewer._map;
+      return { lat: map.getCenter().lat, lng: map.getCenter().lng };
+    });
+    expect(center.lat).toBeCloseTo(45.24, 0);
+    expect(center.lng).toBeCloseTo(-75.8, 0);
+  });
+
+  test('Custom search handler renders geonames items on Enter', async () => {
+    // Re-open the panel
+    await page.click('.mapml-search-button');
+    await page.waitForTimeout(400);
+    // Type and press Enter for search
+    await page.fill('.mapml-search-input', 'Ottawa');
+    await page.press('.mapml-search-input', 'Enter');
+    // Wait for search results
+    await page.waitForSelector('.mapml-search-result', { timeout: 5000 });
+    await page.waitForTimeout(300);
+    let texts = await page.$$eval('.mapml-search-result', (btns) =>
+      btns.map((b) => b.textContent)
+    );
+    // Search endpoint returns 1 result
+    expect(texts).toEqual(['Ottawa']);
+  });
+
+  test('Clicking a search result moves the map', async () => {
+    await page.click('.mapml-search-result:first-child');
+    await page.waitForTimeout(500);
+    let center = await page.$eval('[data-testid=viewer]', (viewer) => {
+      let map = viewer._map;
+      return { lat: map.getCenter().lat, lng: map.getCenter().lng };
+    });
+    // Ottawa bbox center is roughly (45.24, -75.8)
+    expect(center.lat).toBeCloseTo(45.24, 0);
+    expect(center.lng).toBeCloseTo(-75.8, 0);
+  });
+});
diff --git a/test/e2e/core/searchDefault.html b/test/e2e/core/searchDefault.html
new file mode 100644
index 000000000..e3c1381e7
--- /dev/null
+++ b/test/e2e/core/searchDefault.html
@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Search Default Handler Tests</title>
+    <script type="module" src="mapml.js"></script>
+  </head>
+  <body>
+    <mapml-viewer
+      data-testid="viewer"
+      projection="CBMTILE"
+      zoom="5"
+      lat="45.4"
+      lon="-75.7"
+      style="width: 600px; height: 400px;"
+      controls
+      controlslist="search"
+    >
+      <map-layer
+        data-testid="search-layer"
+        label="Search Layer"
+        src="search-with-tref.mapml"
+        checked
+      ></map-layer>
+    </mapml-viewer>
+  </body>
+</html>
diff --git a/test/e2e/core/searchDefault.test.js b/test/e2e/core/searchDefault.test.js
new file mode 100644
index 000000000..653db1924
--- /dev/null
+++ b/test/e2e/core/searchDefault.test.js
@@ -0,0 +1,170 @@
+import { test, expect, chromium } from '@playwright/test';
+
+test.describe('Search default handler tests', () => {
+  let page;
+  let context;
+  test.beforeAll(async () => {
+    context = await chromium.launchPersistentContext('');
+    page =
+      context.pages().find((page) => page.url() === 'about:blank') ||
+      (await context.newPage());
+    await page.goto('searchDefault.html', { waitUntil: 'networkidle' });
+    await page.waitForTimeout(1000);
+  });
+  test.afterAll(async () => {
+    await context.close();
+  });
+
+  test('Search button is enabled when layer has search link', async () => {
+    let disabled = await page.$eval('.mapml-search-button', (btn) =>
+      btn.getAttribute('aria-disabled')
+    );
+    expect(disabled).toBe('false');
+  });
+
+  test('Typing in search input fetches suggestions after debounce', async () => {
+    // Open the panel
+    await page.click('.mapml-search-button');
+    await page.waitForTimeout(400);
+    // Type a query
+    await page.fill('.mapml-search-input', 'Ottawa');
+    // Wait for debounce + fetch
+    await page.waitForSelector('.mapml-search-result', { timeout: 5000 });
+    let count = await page.$$eval(
+      '.mapml-search-result',
+      (btns) => btns.length
+    );
+    expect(count).toBe(3);
+  });
+
+  test('Suggestion results display correct text', async () => {
+    let texts = await page.$$eval('.mapml-search-result', (btns) =>
+      btns.map((b) => b.textContent)
+    );
+    expect(texts[0]).toBe('Ottawa, Ontario, Canada');
+    expect(texts[1]).toBe('Ottawa River, Canada');
+    expect(texts[2]).toBe('Gatineau, Quebec, Canada');
+  });
+
+  test('Clicking a result with bbox fits bounds and closes panel', async () => {
+    // Click the first result (Ottawa — has bbox)
+    await page.click('.mapml-search-result:first-child');
+    await page.waitForTimeout(500);
+    // Panel should be closed
+    let hasOpenClass = await page.$eval('.mapml-search-panel', (panel) =>
+      panel.classList.contains('mapml-search-panel-open')
+    );
+    expect(hasOpenClass).toBe(false);
+    // Check the map center moved toward Ottawa (lat ~45.4, lon ~-75.65)
+    let center = await page.$eval('[data-testid=viewer]', (viewer) => {
+      let map = viewer._map;
+      return { lat: map.getCenter().lat, lng: map.getCenter().lng };
+    });
+    expect(center.lat).toBeCloseTo(45.4, 0);
+    expect(center.lng).toBeCloseTo(-75.65, 0);
+  });
+
+  test('Pressing Enter in input performs search', async () => {
+    // Re-open the panel
+    await page.click('.mapml-search-button');
+    await page.waitForTimeout(400);
+    // Clear input and type new query
+    await page.fill('.mapml-search-input', 'Ottawa');
+    // Press Enter
+    await page.press('.mapml-search-input', 'Enter');
+    // Wait for search results (search endpoint returns 1 result)
+    await page.waitForSelector('.mapml-search-result', { timeout: 5000 });
+    await page.waitForTimeout(300);
+    let count = await page.$$eval(
+      '.mapml-search-result',
+      (btns) => btns.length
+    );
+    expect(count).toBe(1);
+  });
+
+  test('mapsuggestions event is cancelable', async () => {
+    // Close panel from previous test
+    await page.click('.mapml-search-close');
+    await page.waitForTimeout(400);
+
+    // Add event listener that cancels suggestions
+    await page.evaluate(() => {
+      let viewer = document.querySelector('[data-testid=viewer]');
+      viewer.addEventListener(
+        'mapsuggestions',
+        (e) => {
+          e.preventDefault();
+          viewer._suggestionsDefaultPrevented = true;
+        },
+        { once: true }
+      );
+    });
+    // Open panel and type
+    await page.click('.mapml-search-button');
+    await page.waitForTimeout(400);
+    await page.fill('.mapml-search-input', 'test');
+    // Wait for the event to fire
+    await page.waitForFunction(
+      () =>
+        document.querySelector('[data-testid=viewer]')
+          ._suggestionsDefaultPrevented,
+      { timeout: 5000 }
+    );
+    let prevented = await page.$eval(
+      '[data-testid=viewer]',
+      (viewer) => viewer._suggestionsDefaultPrevented
+    );
+    expect(prevented).toBe(true);
+    // No results rendered (default was prevented, panel was freshly opened)
+    let count = await page.$$eval(
+      '.mapml-search-result',
+      (btns) => btns.length
+    );
+    expect(count).toBe(0);
+  });
+
+  test('mapsearch event is cancelable', async () => {
+    // Add event listener that cancels search
+    await page.evaluate(() => {
+      let viewer = document.querySelector('[data-testid=viewer]');
+      viewer.addEventListener(
+        'mapsearch',
+        (e) => {
+          e.preventDefault();
+          viewer._searchDefaultPrevented = true;
+        },
+        { once: true }
+      );
+    });
+    await page.fill('.mapml-search-input', 'Cancel me');
+    await page.press('.mapml-search-input', 'Enter');
+    // Wait for event
+    await page.waitForFunction(
+      () =>
+        document.querySelector('[data-testid=viewer]')._searchDefaultPrevented,
+      { timeout: 5000 }
+    );
+    let prevented = await page.$eval(
+      '[data-testid=viewer]',
+      (viewer) => viewer._searchDefaultPrevented
+    );
+    expect(prevented).toBe(true);
+    // No search results rendered (default was prevented)
+    let count = await page.$$eval(
+      '.mapml-search-result',
+      (btns) => btns.length
+    );
+    expect(count).toBe(0);
+  });
+
+  test('Closing panel clears pending operations', async () => {
+    // Close panel
+    await page.click('.mapml-search-close');
+    await page.waitForTimeout(400);
+    // Panel should be hidden after transition
+    let hidden = await page.$eval('.mapml-search-panel', (panel) =>
+      panel.hasAttribute('hidden')
+    );
+    expect(hidden).toBe(true);
+  });
+});
diff --git a/test/e2e/core/searchDisabled.html b/test/e2e/core/searchDisabled.html
new file mode 100644
index 000000000..ffba4360f
--- /dev/null
+++ b/test/e2e/core/searchDisabled.html
@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <title>Search Disabled State Test</title>
+  <meta charset="UTF-8">
+  <script type="module" src="mapml.js"></script>
+  <style>
+    html { height: 100% }
+    body { height: inherit; margin: 0; padding: 0; }
+  </style>
+</head>
+<body>
+  <mapml-viewer data-testid="viewer" style="height: 600px; width: 500px;"
+      projection="CBMTILE" zoom="0" lat="47" lon="-92" controls
+      controlslist="search">
+    <map-layer data-testid="local-layer" label="Local Layer" checked>
+      <map-extent units="CBMTILE" checked hidden>
+        <map-input name="z" type="zoom" value="3" min="0" max="3"></map-input>
+        <map-input name="y" type="location" units="tilematrix" axis="row" min="14" max="21"></map-input>
+        <map-input name="x" type="location" units="tilematrix" axis="column" min="14" max="19"></map-input>
+        <map-link rel="tile" tref="/data/cbmt/{z}/c{x}_r{y}.png"></map-link>
+      </map-extent>
+    </map-layer>
+    <map-layer data-testid="remote-layer" label="Remote Layer" src="no-search-layer.mapml" checked>
+    </map-layer>
+  </mapml-viewer>
+</body>
+</html>
diff --git a/test/e2e/core/searchDisabled.test.js b/test/e2e/core/searchDisabled.test.js
new file mode 100644
index 000000000..42c820979
--- /dev/null
+++ b/test/e2e/core/searchDisabled.test.js
@@ -0,0 +1,179 @@
+import { test, expect, chromium } from '@playwright/test';
+
+test.describe('Search button disabled state tests', () => {
+  let page;
+  let context;
+  test.beforeAll(async () => {
+    context = await chromium.launchPersistentContext('');
+    page =
+      context.pages().find((page) => page.url() === 'about:blank') ||
+      (await context.newPage());
+    await page.goto('searchDisabled.html', { waitUntil: 'networkidle' });
+    await page.waitForTimeout(1000);
+  });
+
+  test.afterAll(async function () {
+    await context.close();
+  });
+
+  test('search button disabled when no layer has map-link rel=search', async () => {
+    let ariaDisabled = await page.$eval('.mapml-search-button', (btn) =>
+      btn.getAttribute('aria-disabled')
+    );
+    expect(ariaDisabled).toEqual('true');
+  });
+
+  test.describe('Local layer — dynamic add/remove', () => {
+    test('search button enabled after adding map-link rel=search to local layer', async () => {
+      await page.evaluate(() => {
+        let layer = document.querySelector('[data-testid=local-layer]');
+        let link = document.createElement('map-link');
+        link.setAttribute('rel', 'search');
+        link.dataset.testid = 'local-search-link';
+        layer.appendChild(link);
+      });
+      await page.waitForTimeout(100);
+      let ariaDisabled = await page.$eval('.mapml-search-button', (btn) =>
+        btn.getAttribute('aria-disabled')
+      );
+      expect(ariaDisabled).toEqual('false');
+    });
+
+    test('search button disabled after removing map-link rel=search from local layer', async () => {
+      await page.evaluate(() => {
+        let link = document.querySelector('[data-testid=local-search-link]');
+        link.remove();
+      });
+      await page.waitForTimeout(100);
+      let ariaDisabled = await page.$eval('.mapml-search-button', (btn) =>
+        btn.getAttribute('aria-disabled')
+      );
+      expect(ariaDisabled).toEqual('true');
+    });
+  });
+
+  test.describe('Layer checked/unchecked', () => {
+    test('search button disabled when layer with search link is unchecked', async () => {
+      // Add search link first
+      await page.evaluate(() => {
+        let layer = document.querySelector('[data-testid=local-layer]');
+        let link = document.createElement('map-link');
+        link.setAttribute('rel', 'search');
+        link.dataset.testid = 'local-search-link';
+        layer.appendChild(link);
+      });
+      await page.waitForTimeout(100);
+      // Verify enabled
+      let ariaDisabled = await page.$eval('.mapml-search-button', (btn) =>
+        btn.getAttribute('aria-disabled')
+      );
+      expect(ariaDisabled).toEqual('false');
+
+      // Uncheck the layer
+      await page.evaluate(() => {
+        document
+          .querySelector('[data-testid=local-layer]')
+          .removeAttribute('checked');
+      });
+      await page.waitForTimeout(100);
+      ariaDisabled = await page.$eval('.mapml-search-button', (btn) =>
+        btn.getAttribute('aria-disabled')
+      );
+      expect(ariaDisabled).toEqual('true');
+    });
+
+    test('search button re-enabled when layer with search link is re-checked', async () => {
+      await page.evaluate(() => {
+        document
+          .querySelector('[data-testid=local-layer]')
+          .setAttribute('checked', '');
+      });
+      await page.waitForTimeout(100);
+      let ariaDisabled = await page.$eval('.mapml-search-button', (btn) =>
+        btn.getAttribute('aria-disabled')
+      );
+      expect(ariaDisabled).toEqual('false');
+
+      // Clean up: remove the search link
+      await page.evaluate(() => {
+        let link = document.querySelector('[data-testid=local-search-link]');
+        if (link) link.remove();
+      });
+      await page.waitForTimeout(100);
+    });
+  });
+
+  test.describe('Remote (src) layer', () => {
+    test('search button enabled when remote layer has map-link rel=search', async () => {
+      await page.evaluate(async () => {
+        let layer = document.querySelector('[data-testid=remote-layer]');
+        layer.src = 'search-layer.mapml';
+        await layer.whenReady();
+      });
+      await page.waitForTimeout(200);
+      let ariaDisabled = await page.$eval('.mapml-search-button', (btn) =>
+        btn.getAttribute('aria-disabled')
+      );
+      expect(ariaDisabled).toEqual('false');
+    });
+
+    test('search button disabled when remote layer without search link', async () => {
+      await page.evaluate(async () => {
+        let layer = document.querySelector('[data-testid=remote-layer]');
+        layer.src = 'no-search-layer.mapml';
+        await layer.whenReady();
+      });
+      await page.waitForTimeout(200);
+      let ariaDisabled = await page.$eval('.mapml-search-button', (btn) =>
+        btn.getAttribute('aria-disabled')
+      );
+      expect(ariaDisabled).toEqual('true');
+    });
+  });
+
+  test.describe('Multiple layers', () => {
+    test('search button stays enabled if one of two layers has search link', async () => {
+      // Add search link to local layer
+      await page.evaluate(() => {
+        let layer = document.querySelector('[data-testid=local-layer]');
+        let link = document.createElement('map-link');
+        link.setAttribute('rel', 'search');
+        link.dataset.testid = 'local-search-link';
+        layer.appendChild(link);
+      });
+      await page.waitForTimeout(100);
+      // Remote layer has no search link (no-search-layer.mapml)
+      // But local layer does — button should be enabled
+      let ariaDisabled = await page.$eval('.mapml-search-button', (btn) =>
+        btn.getAttribute('aria-disabled')
+      );
+      expect(ariaDisabled).toEqual('false');
+    });
+
+    test('search button disabled only when all search-capable layers are unchecked', async () => {
+      // Uncheck local layer (the only one with search link)
+      await page.evaluate(() => {
+        document
+          .querySelector('[data-testid=local-layer]')
+          .removeAttribute('checked');
+      });
+      await page.waitForTimeout(100);
+      let ariaDisabled = await page.$eval('.mapml-search-button', (btn) =>
+        btn.getAttribute('aria-disabled')
+      );
+      expect(ariaDisabled).toEqual('true');
+
+      // Re-check it — should be enabled again
+      await page.evaluate(() => {
+        document
+          .querySelector('[data-testid=local-layer]')
+          .setAttribute('checked', '');
+      });
+      await page.waitForTimeout(100);
+      ariaDisabled = await page.$eval('.mapml-search-button', (btn) =>
+        btn.getAttribute('aria-disabled')
+      );
+      expect(ariaDisabled).toEqual('false');
+    });
+  });
+});
diff --git a/test/e2e/core/searchI18n.html b/test/e2e/core/searchI18n.html
new file mode 100644
index 000000000..09dbd2dd8
--- /dev/null
+++ b/test/e2e/core/searchI18n.html
@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="ja">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Search i18n Tests</title>
+    <script type="module" src="mapml.js"></script>
+  </head>
+  <body>
+    <mapml-viewer
+      data-testid="viewer"
+      projection="OSMTILE"
+      zoom="5"
+      lat="35.68"
+      lon="139.69"
+      style="width: 600px; height: 400px;"
+      controls
+      controlslist="search"
+    >
+      <map-layer
+        data-testid="search-layer"
+        label="Japanese Search Layer"
+        src="search-japanese.mapml"
+        checked
+      ></map-layer>
+    </mapml-viewer>
+  </body>
+</html>
diff --git a/test/e2e/core/searchI18n.test.js b/test/e2e/core/searchI18n.test.js
new file mode 100644
index 000000000..9830e232a
--- /dev/null
+++ b/test/e2e/core/searchI18n.test.js
@@ -0,0 +1,71 @@
+import { test, expect, chromium } from '@playwright/test';
+
+test.describe('Search i18n tests (Japanese)', () => {
+  let page;
+  let context;
+  test.beforeAll(async () => {
+    context = await chromium.launchPersistentContext('');
+    page =
+      context.pages().find((page) => page.url() === 'about:blank') ||
+      (await context.newPage());
+    await page.goto('searchI18n.html', { waitUntil: 'networkidle' });
+    await page.waitForTimeout(1000);
+  });
+  test.afterAll(async () => {
+    await context.close();
+  });
+
+  test('Japanese query in suggestions displays CJK results', async () => {
+    await page.click('.mapml-search-button');
+    await page.waitForTimeout(400);
+    // Type Japanese characters directly (simulates committed IME input)
+    await page.fill('.mapml-search-input', '東京');
+    // Wait for debounce + fetch
+    await page.waitForSelector('.mapml-search-result', { timeout: 5000 });
+    let texts = await page.$$eval('.mapml-search-result', (btns) =>
+      btns.map((b) => b.textContent)
+    );
+    expect(texts[0]).toBe('東京都, 日本');
+    expect(texts[1]).toBe('東京タワー, 東京都, 日本');
+    expect(texts[2]).toBe('東京駅, 東京都, 日本');
+  });
+
+  test('Japanese query via Enter performs search', async () => {
+    await page.fill('.mapml-search-input', '東京');
+    await page.press('.mapml-search-input', 'Enter');
+    await page.waitForSelector('.mapml-search-result', { timeout: 5000 });
+    await page.waitForTimeout(300);
+    let texts = await page.$$eval('.mapml-search-result', (btns) =>
+      btns.map((b) => b.textContent)
+    );
+    expect(texts).toEqual(['東京都, 日本']);
+  });
+
+  test('Clicking Japanese result moves map to correct location', async () => {
+    await page.click('.mapml-search-result:first-child');
+    await page.waitForTimeout(500);
+    let center = await page.$eval('[data-testid=viewer]', (viewer) => {
+      let map = viewer._map;
+      return { lat: map.getCenter().lat, lng: map.getCenter().lng };
+    });
+    // Tokyo bbox center is roughly (35.7, 139.4)
+    expect(center.lat).toBeCloseTo(35.7, 0);
+    expect(center.lng).toBeCloseTo(139.4, 0);
+  });
+
+  test('Search query is properly URL-encoded for non-Latin characters', async () => {
+    // Intercept the network request to verify encoding
+    let requestUrl = '';
+    page.on('request', (request) => {
+      if (request.url().includes('/search/ja/suggestions')) {
+        requestUrl = request.url();
+      }
+    });
+    await page.click('.mapml-search-button');
+    await page.waitForTimeout(400);
+    await page.fill('.mapml-search-input', '東京');
+    await page.waitForSelector('.mapml-search-result', { timeout: 5000 });
+    // The query should be percent-encoded
+    expect(requestUrl).toContain(encodeURIComponent('東京'));
+  });
+});
diff --git a/test/e2e/core/searchMultiLayer.html b/test/e2e/core/searchMultiLayer.html
new file mode 100644
index 000000000..f05725b86
--- /dev/null
+++ b/test/e2e/core/searchMultiLayer.html
@@ -0,0 +1,107 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Search Multi-Layer Tests</title>
+    <script type="module" src="mapml.js"></script>
+  </head>
+  <body>
+    <mapml-viewer
+      data-testid="viewer"
+      projection="CBMTILE"
+      zoom="5"
+      lat="45.4"
+      lon="-75.7"
+      style="width: 600px; height: 400px;"
+      controls
+      controlslist="search"
+    >
+      <map-layer
+        data-testid="layer1"
+        label="Geonames Layer 1"
+        src="search-geonames.mapml"
+        checked
+      ></map-layer>
+      <map-layer
+        data-testid="layer2"
+        label="Geonames Layer 2"
+        src="search-geonames2.mapml"
+        checked
+      ></map-layer>
+    </mapml-viewer>
+    <script>
+      document.addEventListener('DOMContentLoaded', () => {
+        const viewer = document.querySelector('[data-testid=viewer]');
+
+        // Custom handler that merges geonames items from all layers
+        // and tags each result with its source layer label
+        viewer.addEventListener('mapsuggestions', (e) => {
+          e.preventDefault();
+          const container = viewer._map._container.querySelector(
+            '.mapml-search-results'
+          );
+          container.innerHTML = '';
+          for (const { data, layer } of e.detail.responses) {
+            if (!data || !data.items) continue;
+            for (const item of data.items) {
+              const btn = document.createElement('button');
+              btn.className = 'mapml-search-result';
+              btn.setAttribute('type', 'button');
+              btn.dataset.layer = layer.getAttribute('label');
+              btn.textContent = item.name;
+              btn.addEventListener('click', () => {
+                if (item.bbox && item.bbox.length === 4) {
+                  const [west, south, east, north] = item.bbox;
+                  viewer._map.fitBounds([
+                    [south, west],
+                    [north, east]
+                  ]);
+                } else {
+                  viewer._map.setView([item.latitude, item.longitude], 10);
+                }
+                viewer._map._container
+                  .querySelector('.mapml-search-panel')
+                  .classList.remove('mapml-search-panel-open');
+              });
+              container.appendChild(btn);
+            }
+          }
+        });
+
+        viewer.addEventListener('mapsearch', (e) => {
+          e.preventDefault();
+          const container = viewer._map._container.querySelector(
+            '.mapml-search-results'
+          );
+          container.innerHTML = '';
+          for (const { data, layer } of e.detail.responses) {
+            if (!data || !data.items) continue;
+            for (const item of data.items) {
+              const btn = document.createElement('button');
+              btn.className = 'mapml-search-result';
+              btn.setAttribute('type', 'button');
+              btn.dataset.layer = layer.getAttribute('label');
+              btn.textContent = item.name;
+              btn.addEventListener('click', () => {
+                if (item.bbox && item.bbox.length === 4) {
+                  const [west, south, east, north] = item.bbox;
+                  viewer._map.fitBounds([
+                    [south, west],
+                    [north, east]
+                  ]);
+                } else {
+                  viewer._map.setView([item.latitude, item.longitude], 10);
+                }
+                viewer._map._container
+                  .querySelector('.mapml-search-panel')
+                  .classList.remove('mapml-search-panel-open');
+              });
+              container.appendChild(btn);
+            }
+          }
+        });
+      });
+    </script>
+  </body>
+</html>
diff --git a/test/e2e/core/searchMultiLayer.test.js b/test/e2e/core/searchMultiLayer.test.js
new file mode 100644
index 000000000..72470eb28
--- /dev/null
+++ b/test/e2e/core/searchMultiLayer.test.js
@@ -0,0 +1,150 @@
+import { test, expect, chromium } from '@playwright/test';
+
+test.describe('Search multi-layer tests', () => {
+  let page;
+  let context;
+  test.beforeAll(async () => {
+    context = await chromium.launchPersistentContext('');
+    page =
+      context.pages().find((page) => page.url() === 'about:blank') ||
+      (await context.newPage());
+    await page.goto('searchMultiLayer.html', { waitUntil: 'networkidle' });
+    await page.waitForTimeout(1000);
+  });
+  test.afterAll(async () => {
+    await context.close();
+  });
+
+  test('Suggestions aggregate results from both layers', async () => {
+    // Open the panel
+    await page.click('.mapml-search-button');
+    await page.waitForTimeout(400);
+    // Type a query
+    await page.fill('.mapml-search-input', 'test');
+    // Wait for results from both layers (5 total)
+    // Use waitForSelector (pierces shadow DOM) then poll count via $$eval
+    await page.waitForSelector('.mapml-search-result', { timeout: 5000 });
+    await page.waitForTimeout(500);
+    let texts = await page.$$eval('.mapml-search-result', (btns) =>
+      btns.map((b) => b.textContent)
+    );
+    // Layer 1 returns 3 items (Ottawa, Arctic Ocean, Atlantic Ocean)
+    // Layer 2 returns 2 items (Toronto, Montreal)
+    expect(texts).toEqual([
+      'Ottawa',
+      'Arctic Ocean',
+      'Atlantic Ocean',
+      'Toronto',
+      'Montreal'
+    ]);
+  });
+
+  test('Suggestion results carry correct layer attribution', async () => {
+    let layers = await page.$$eval('.mapml-search-result', (btns) =>
+      btns.map((b) => b.dataset.layer)
+    );
+    // First 3 from layer 1, last 2 from layer 2
+    expect(layers[0]).toBe('Geonames Layer 1');
+    expect(layers[1]).toBe('Geonames Layer 1');
+    expect(layers[2]).toBe('Geonames Layer 1');
+    expect(layers[3]).toBe('Geonames Layer 2');
+    expect(layers[4]).toBe('Geonames Layer 2');
+  });
+
+  test('Event detail responses array has entries from each layer', async () => {
+    // Close panel from previous test
+    await page.evaluate(() => {
+      const viewer = document.querySelector('[data-testid=viewer]');
+      const panel = viewer.shadowRoot.querySelector('.mapml-search-panel');
+      if (panel) {
+        panel.classList.remove('mapml-search-panel-open');
+        panel.setAttribute('hidden', '');
+      }
+    });
+    await page.waitForTimeout(400);
+
+    await page.evaluate(() => {
+      const viewer = document.querySelector('[data-testid=viewer]');
+      viewer.addEventListener(
+        'mapsuggestions',
+        (e) => {
+          viewer._testResponseCount = e.detail.responses.length;
+          viewer._testLayerLabels = e.detail.responses.map((r) =>
+            r.layer.getAttribute('label')
+          );
+        },
+        { once: true }
+      );
+    });
+
+    await page.click('.mapml-search-button');
+    await page.waitForTimeout(400);
+    await page.fill('.mapml-search-input', 'multi');
+    await page.waitForFunction(
+      () =>
+        document.querySelector('[data-testid=viewer]')._testResponseCount !==
+        undefined,
+      { timeout: 5000 }
+    );
+
+    let responseCount = await page.$eval(
+      '[data-testid=viewer]',
+      (v) => v._testResponseCount
+    );
+    let layerLabels = await page.$eval(
+      '[data-testid=viewer]',
+      (v) => v._testLayerLabels
+    );
+
+    expect(responseCount).toBe(2);
+    expect(layerLabels).toEqual(['Geonames Layer 1', 'Geonames Layer 2']);
+  });
+
+  test('Search (Enter) aggregates results from both layers', async () => {
+    // Clear input and search
+    await page.fill('.mapml-search-input', 'search-multi');
+    await page.press('.mapml-search-input', 'Enter');
+    // Wait for search results
+    await page.waitForSelector('.mapml-search-result', { timeout: 5000 });
+    await page.waitForTimeout(500);
+    let texts = await page.$$eval('.mapml-search-result', (btns) =>
+      btns.map((b) => b.textContent)
+    );
+    expect(texts).toEqual(['Ottawa', 'Toronto']);
+  });
+
+  test('Search results carry correct layer attribution', async () => {
+    let layers = await page.$$eval('.mapml-search-result', (btns) =>
+      btns.map((b) => b.dataset.layer)
+    );
+    expect(layers[0]).toBe('Geonames Layer 1');
+    expect(layers[1]).toBe('Geonames Layer 2');
+  });
+
+  test('Unchecking a layer excludes it from results', async () => {
+    // Uncheck layer 2
+    await page.evaluate(() => {
+      document.querySelector('[data-testid=layer2]').removeAttribute('checked');
+    });
+    await page.waitForTimeout(500);
+
+    // Clear and re-type to trigger new suggestions
+    await page.fill('.mapml-search-input', '');
+    await page.fill('.mapml-search-input', 'filtered');
+    await page.waitForSelector('.mapml-search-result', { timeout: 5000 });
+    await page.waitForTimeout(500);
+
+    let texts = await page.$$eval('.mapml-search-result', (btns) =>
+      btns.map((b) => b.textContent)
+    );
+    // Only layer 1 results (Ottawa, Arctic Ocean, Atlantic Ocean)
+    expect(texts).toEqual(['Ottawa', 'Arctic Ocean', 'Atlantic Ocean']);
+
+    let layers = await page.$$eval('.mapml-search-result', (btns) =>
+      btns.map((b) => b.dataset.layer)
+    );
+    for (let label of layers) {
+      expect(label).toBe('Geonames Layer 1');
+    }
+  });
+});
diff --git a/test/e2e/data/no-search-layer.mapml b/test/e2e/data/no-search-layer.mapml
new file mode 100644
index 000000000..a13037f3b
--- /dev/null
+++ b/test/e2e/data/no-search-layer.mapml
@@ -0,0 +1,13 @@
+<mapml- xmlns="http://www.w3.org/1999/xhtml">
+  <map-head>
+    <map-title>Layer without search</map-title>
+  </map-head>
+  <map-body>
+    <map-extent units="CBMTILE" checked="checked">
+      <map-input name="z" type="zoom" value="17" min="0" max="17"></map-input>
+      <map-input name="y" type="location" units="tilematrix" axis="row" min="29750" max="34475"></map-input>
+      <map-input name="x" type="location" units="tilematrix" axis="column" min="26484" max="32463"></map-input>
+      <map-link rel="tile" tref="dummy/arcgis/rest/services/BaseMaps/CBMT3978/MapServer/tile/{z}/{y}/{x}?m4h=t"></map-link>
+    </map-extent>
+  </map-body>
+</mapml->
diff --git a/test/e2e/data/search-geonames.mapml b/test/e2e/data/search-geonames.mapml
new file mode 100644
index 000000000..b7919fd3b
--- /dev/null
+++ b/test/e2e/data/search-geonames.mapml
@@ -0,0 +1,15 @@
+<mapml- xmlns="http://www.w3.org/1999/xhtml">
+  <map-head>
+    <map-title>Layer with geonames search</map-title>
+    <map-link rel="suggestions" tref="/geonames/suggestions?q={searchTerms}"></map-link>
+    <map-link rel="search" tref="/geonames/search?q={searchTerms}"></map-link>
+  </map-head>
+  <map-body>
+    <map-extent units="CBMTILE" checked="checked">
+      <map-input name="z" type="zoom" value="17" min="0" max="17"></map-input>
+      <map-input name="y" type="location" units="tilematrix" axis="row" min="29750" max="34475"></map-input>
+      <map-input name="x" type="location" units="tilematrix" axis="column" min="26484" max="32463"></map-input>
+      <map-link rel="tile" tref="dummy/arcgis/rest/services/BaseMaps/CBMT3978/MapServer/tile/{z}/{y}/{x}?m4h=t"></map-link>
+    </map-extent>
+  </map-body>
+</mapml->
diff --git a/test/e2e/data/search-geonames2.mapml b/test/e2e/data/search-geonames2.mapml
new file mode 100644
index 000000000..438854e81
--- /dev/null
+++ b/test/e2e/data/search-geonames2.mapml
@@ -0,0 +1,15 @@
+<mapml- xmlns="http://www.w3.org/1999/xhtml">
+  <map-head>
+    <map-title>Second layer with geonames search</map-title>
+    <map-link rel="suggestions" tref="/geonames2/suggestions?q={searchTerms}"></map-link>
+    <map-link rel="search" tref="/geonames2/search?q={searchTerms}"></map-link>
+  </map-head>
+  <map-body>
+    <map-extent units="CBMTILE" checked="checked">
+      <map-input name="z" type="zoom" value="17" min="0" max="17"></map-input>
+      <map-input name="y" type="location" units="tilematrix" axis="row" min="29750" max="34475"></map-input>
+      <map-input name="x" type="location" units="tilematrix" axis="column" min="26484" max="32463"></map-input>
+      <map-link rel="tile" tref="dummy/arcgis/rest/services/BaseMaps/CBMT3978/MapServer/tile/{z}/{y}/{x}?m4h=t"></map-link>
+    </map-extent>
+  </map-body>
+</mapml->
diff --git a/test/e2e/data/search-japanese.mapml b/test/e2e/data/search-japanese.mapml
new file mode 100644
index 000000000..0895c4fdc
--- /dev/null
+++ b/test/e2e/data/search-japanese.mapml
@@ -0,0 +1,14 @@
+<mapml- xmlns="http://www.w3.org/1999/xhtml">
+  <map-head>
+    <map-title>Japanese search layer</map-title>
+    <map-link rel="suggestions" tref="/search/ja/suggestions?q={searchTerms}"></map-link>
+    <map-link rel="search" tref="/search/ja/results?q={searchTerms}"></map-link>
+  </map-head>
+  <map-body>
+    <map-extent units="OSMTILE" checked="checked">
+      <map-input name="z" type="zoom" value="17" min="0" max="17"></map-input>
+      <map-input name="y" type="location" units="tilematrix" axis="row" min="0" max="131071"></map-input>
+      <map-input name="x" type="location" units="tilematrix" axis="column" min="0" max="131071"></map-input>
+    </map-extent>
+  </map-body>
+</mapml->
diff --git a/test/e2e/data/search-layer.mapml b/test/e2e/data/search-layer.mapml
new file mode 100644
index 000000000..83a9fb475
--- /dev/null
+++ b/test/e2e/data/search-layer.mapml
@@ -0,0 +1,14 @@
+<mapml- xmlns="http://www.w3.org/1999/xhtml">
+  <map-head>
+    <map-title>Layer with search</map-title>
+    <map-link rel="search"></map-link>
+  </map-head>
+  <map-body>
+    <map-extent units="CBMTILE" checked="checked">
+      <map-input name="z" type="zoom" value="17" min="0" max="17"></map-input>
+      <map-input name="y" type="location" units="tilematrix" axis="row" min="29750" max="34475"></map-input>
+      <map-input name="x" type="location" units="tilematrix" axis="column" min="26484" max="32463"></map-input>
+      <map-link rel="tile" tref="dummy/arcgis/rest/services/BaseMaps/CBMT3978/MapServer/tile/{z}/{y}/{x}?m4h=t"></map-link>
+    </map-extent>
+  </map-body>
+</mapml->
diff --git a/test/e2e/data/search-with-tref.mapml b/test/e2e/data/search-with-tref.mapml
new file mode 100644
index 000000000..0249d428d
--- /dev/null
+++ b/test/e2e/data/search-with-tref.mapml
@@ -0,0 +1,15 @@
+<mapml- xmlns="http://www.w3.org/1999/xhtml">
+  <map-head>
+    <map-title>Layer with search and suggestions</map-title>
+    <map-link rel="suggestions" tref="/search/suggestions?q={searchTerms}"></map-link>
+    <map-link rel="search" tref="/search/results?q={searchTerms}"></map-link>
+  </map-head>
+  <map-body>
+    <map-extent units="CBMTILE" checked="checked">
+      <map-input name="z" type="zoom" value="17" min="0" max="17"></map-input>
+      <map-input name="y" type="location" units="tilematrix" axis="row" min="29750" max="34475"></map-input>
+      <map-input name="x" type="location" units="tilematrix" axis="column" min="26484" max="32463"></map-input>
+      <map-link rel="tile" tref="dummy/arcgis/rest/services/BaseMaps/CBMT3978/MapServer/tile/{z}/{y}/{x}?m4h=t"></map-link>
+    </map-extent>
+  </map-body>
+</mapml->
diff --git a/test/e2e/elements/map-feature/map-feature-rendering.test.js-snapshots/no-zinger-linux.png b/test/e2e/elements/map-feature/map-feature-rendering.test.js-snapshots/no-zinger-linux.png
index 796a54081..530d80c2d 100644
Binary files a/test/e2e/elements/map-feature/map-feature-rendering.test.js-snapshots/no-zinger-linux.png and b/test/e2e/elements/map-feature/map-feature-rendering.test.js-snapshots/no-zinger-linux.png differ
diff --git a/test/e2e/elements/map-link/map-link-media.test.js-snapshots/default-styled-markers-linux.png b/test/e2e/elements/map-link/map-link-media.test.js-snapshots/default-styled-markers-linux.png
index 306346c49..ecf18de38 100644
Binary files a/test/e2e/elements/map-link/map-link-media.test.js-snapshots/default-styled-markers-linux.png and b/test/e2e/elements/map-link/map-link-media.test.js-snapshots/default-styled-markers-linux.png differ
diff --git a/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-dark-linux.png b/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-dark-linux.png
index dcfc1f92d..1242a6aa6 100644
Binary files a/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-dark-linux.png and b/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-dark-linux.png differ
diff --git a/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-dark-win32.png b/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-dark-win32.png
deleted file mode 100644
index 165797aa4..000000000
Binary files a/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-dark-win32.png and /dev/null differ
diff --git a/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-light-linux.png b/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-light-linux.png
index 7cbe608cd..da08c84e8 100644
Binary files a/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-light-linux.png and b/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-light-linux.png differ
diff --git a/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-light-win32.png b/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-light-win32.png
deleted file mode 100644
index 7cbe608cd..000000000
Binary files a/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-light-win32.png and /dev/null differ
diff --git a/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-local-light-linux.png b/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-local-light-linux.png
index 0f5b58d97..da08c84e8 100644
Binary files a/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-local-light-linux.png and b/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-local-light-linux.png differ
diff --git a/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-local-light-win32.png b/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-local-light-win32.png
deleted file mode 100644
index 30cd09f19..000000000
Binary files a/test/e2e/elements/map-link/pmtiles/map-link-pmtiles-styles.test.js-snapshots/pmtiles-local-light-win32.png and /dev/null differ
diff --git a/test/e2e/elements/map-tile/map-tile.test.js-snapshots/after-adding-tile-linux.png b/test/e2e/elements/map-tile/map-tile.test.js-snapshots/after-adding-tile-linux.png
index e4bb0a5f7..800cee79a 100644
Binary files a/test/e2e/elements/map-tile/map-tile.test.js-snapshots/after-adding-tile-linux.png and b/test/e2e/elements/map-tile/map-tile.test.js-snapshots/after-adding-tile-linux.png differ
diff --git a/test/e2e/elements/map-tile/map-tile.test.js-snapshots/after-src-change-linux.png b/test/e2e/elements/map-tile/map-tile.test.js-snapshots/after-src-change-linux.png
index d662dc99c..93a4c92f0 100644
Binary files a/test/e2e/elements/map-tile/map-tile.test.js-snapshots/after-src-change-linux.png and b/test/e2e/elements/map-tile/map-tile.test.js-snapshots/after-src-change-linux.png differ
diff --git a/test/e2e/elements/map-tile/map-tile.test.js-snapshots/after-tile-removal-linux.png b/test/e2e/elements/map-tile/map-tile.test.js-snapshots/after-tile-removal-linux.png
index 3dd0a7e3b..99c2d2a26 100644
Binary files a/test/e2e/elements/map-tile/map-tile.test.js-snapshots/after-tile-removal-linux.png and b/test/e2e/elements/map-tile/map-tile.test.js-snapshots/after-tile-removal-linux.png differ
diff --git a/test/e2e/elements/map-tile/map-tile.test.js-snapshots/baseline-before-adding-linux.png b/test/e2e/elements/map-tile/map-tile.test.js-snapshots/baseline-before-adding-linux.png
index e4bb0a5f7..800cee79a 100644
Binary files a/test/e2e/elements/map-tile/map-tile.test.js-snapshots/baseline-before-adding-linux.png and b/test/e2e/elements/map-tile/map-tile.test.js-snapshots/baseline-before-adding-linux.png differ
diff --git a/test/e2e/elements/map-tile/map-tile.test.js-snapshots/before-src-change-linux.png b/test/e2e/elements/map-tile/map-tile.test.js-snapshots/before-src-change-linux.png
index e4bb0a5f7..800cee79a 100644
Binary files a/test/e2e/elements/map-tile/map-tile.test.js-snapshots/before-src-change-linux.png and b/test/e2e/elements/map-tile/map-tile.test.js-snapshots/before-src-change-linux.png differ
diff --git a/test/e2e/elements/map-tile/map-tile.test.js-snapshots/before-tile-removal-linux.png b/test/e2e/elements/map-tile/map-tile.test.js-snapshots/before-tile-removal-linux.png
index e4bb0a5f7..800cee79a 100644
Binary files a/test/e2e/elements/map-tile/map-tile.test.js-snapshots/before-tile-removal-linux.png and b/test/e2e/elements/map-tile/map-tile.test.js-snapshots/before-tile-removal-linux.png differ
diff --git a/test/e2e/layers/general/isVisible.js b/test/e2e/layers/general/isVisible.js
index dc34a2431..1c44781cc 100644
--- a/test/e2e/layers/general/isVisible.js
+++ b/test/e2e/layers/general/isVisible.js
@@ -7,7 +7,7 @@ exports.test = (path, zoomIn, zoomOut) => {
     test.beforeAll(async () => {
       context = await chromium.launchPersistentContext('', { slowMo: 250 });
       page = await context.newPage();
-      await page.goto(path);
+      await page.goto(path, { waitUntil: 'networkidle' });
     });
 
     test('isVisible property false when zoomed out of bounds (zooming in)', async () => {
diff --git a/test/e2e/layers/general/zoomLimit.js b/test/e2e/layers/general/zoomLimit.js
index dd21740e3..e9cc1226e 100644
--- a/test/e2e/layers/general/zoomLimit.js
+++ b/test/e2e/layers/general/zoomLimit.js
@@ -7,7 +7,7 @@ exports.test = (path, zoomIn, zoomOut) => {
     test.beforeAll(async () => {
       context = await chromium.launchPersistentContext('', { slowMo: 250 });
       page = await context.newPage();
-      await page.goto(path);
+      await page.goto(path, { waitUntil: 'networkidle' });
       // removes the 2nd layer element in the 1st map
       await page.$eval('xpath=/html/body/map', (controller) =>
         controller.removeChild(controller.children[1])
diff --git a/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-baseline-linux.png b/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-baseline-linux.png
index 314f0192b..ca4061577 100644
Binary files a/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-baseline-linux.png and b/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-baseline-linux.png differ
diff --git a/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-blue-checked-linux.png b/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-blue-checked-linux.png
index 1153d219f..b777388d9 100644
Binary files a/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-blue-checked-linux.png and b/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-blue-checked-linux.png differ
diff --git a/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-dom-reordered-linux.png b/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-dom-reordered-linux.png
index 314f0192b..ca4061577 100644
Binary files a/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-dom-reordered-linux.png and b/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-dom-reordered-linux.png differ
diff --git a/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-features-baseline-linux.png b/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-features-baseline-linux.png
index 314f0192b..ca4061577 100644
Binary files a/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-features-baseline-linux.png and b/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-features-baseline-linux.png differ
diff --git a/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-hierarchy-validation-linux.png b/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-hierarchy-validation-linux.png
index 314f0192b..ca4061577 100644
Binary files a/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-hierarchy-validation-linux.png and b/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-hierarchy-validation-linux.png differ
diff --git a/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-red-unchecked-linux.png b/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-red-unchecked-linux.png
index fc53c2de6..ecec42454 100644
Binary files a/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-red-unchecked-linux.png and b/test/e2e/layers/mixedLayer-zindex-rendering.test.js-snapshots/mixedLayer-red-unchecked-linux.png differ
diff --git a/test/e2e/layers/templatedFeatures.test.js b/test/e2e/layers/templatedFeatures.test.js
index 95257d0f9..bba72897c 100644
--- a/test/e2e/layers/templatedFeatures.test.js
+++ b/test/e2e/layers/templatedFeatures.test.js
@@ -37,7 +37,7 @@ test.describe('Playwright templatedFeatures Layer Tests', () => {
     page =
       context.pages().find((page) => page.url() === 'about:blank') ||
       (await context.newPage());
-    await page.goto('templatedFeatures.html');
+    await page.goto('templatedFeatures.html', { waitUntil: 'networkidle' });
   });
 
   test.afterAll(async function () {
@@ -127,7 +127,7 @@ test.describe('Playwright templatedFeatures Layer Tests', () => {
 
   test.describe('Retreived Features Loading Tests', () => {
     test('Loading in tilematrix cs feature', async () => {
-      await page.waitForTimeout(200);
+      await page.waitForTimeout(500);
       const feature = await page.getByTestId('tilematrixgeometry');
       const pathCoordinates = await feature.evaluate((f) =>
         f._groupEl.querySelector('path').getAttribute('d')
@@ -152,7 +152,7 @@ test.describe('Playwright templatedFeatures Layer Tests', () => {
     });
 
     test('templated features disabled when panned out of bounds', async () => {
-      await page.reload();
+      await page.reload({ waitUntil: 'networkidle' });
       await page.getByTestId('map2').evaluate((map) => {
         map.zoomTo(45.428, -75.346, 14);
       });
diff --git a/test/e2e/layers/templatedPMTilesMVTLayer.test.js b/test/e2e/layers/templatedPMTilesMVTLayer.test.js
index 2f39cb372..7bb371f2d 100644
--- a/test/e2e/layers/templatedPMTilesMVTLayer.test.js
+++ b/test/e2e/layers/templatedPMTilesMVTLayer.test.js
@@ -15,7 +15,9 @@ test.describe('Playwright templatedPMTilesLayer Tests', () => {
   });
 
   test('Test rendered data', async ({ page }) => {
-    await page.goto('templatedPMTilesMVTLayer.html');
+    await page.goto('templatedPMTilesMVTLayer.html', {
+      waitUntil: 'networkidle'
+    });
     await page.waitForTimeout(1000);
     const viewer = page.getByTestId('viewer');
     // seems like a lot of pixels to allow to be different, but missing fonts
@@ -25,6 +27,7 @@ test.describe('Playwright templatedPMTilesLayer Tests', () => {
       maxDiffPixels: 1500
     });
     await viewer.evaluate((v) => v.zoomTo(0, 0, 2));
+    await page.waitForTimeout(2000);
     await expect(viewer).toHaveScreenshot('mvt-light-z2.png', {
       maxDiffPixels: 1500
     });
@@ -35,10 +38,12 @@ test.describe('Playwright templatedPMTilesLayer Tests', () => {
     await page.waitForTimeout(3000);
     const darkLayer = page.getByTestId('dark');
     await darkLayer.evaluate((l) => l.setAttribute('checked', 'checked'));
+    await page.waitForTimeout(1000);
     await expect(viewer).toHaveScreenshot('pmtiles-dark.png', {
       maxDiffPixels: 1500
     });
     await darkLayer.evaluate((l) => l.zoomTo());
+    await page.waitForTimeout(1000);
     await expect(viewer).toHaveScreenshot('pmtiles-dark-z10.png', {
       maxDiffPixels: 1500
     });
@@ -48,7 +53,9 @@ test.describe('Playwright templatedPMTilesLayer Tests', () => {
     page.on('console', async (msg) => {
       for (const arg of msg.args()) messages.push(await arg.jsonValue());
     });
-    await page.goto('templatedPMTilesMVTLayerMissingStyles.html');
+    await page.goto('templatedPMTilesMVTLayerMissingStyles.html', {
+      waitUntil: 'networkidle'
+    });
     await page.waitForTimeout(1000);
     let errorLoadingModule = false;
     let errorFindingRules = false;
@@ -68,7 +75,9 @@ test.describe('Playwright templatedPMTilesLayer Tests', () => {
     // failed
     expect(errorFindingRules).toBe(false);
     messages.length = 0;
-    await page.goto('templatedPMTilesMVTLayerMissingRuleKey.html');
+    await page.goto('templatedPMTilesMVTLayerMissingRuleKey.html', {
+      waitUntil: 'networkidle'
+    });
     await page.waitForTimeout(1000);
     errorLoadingModule = false;
     errorFindingRules = false;
@@ -86,7 +95,9 @@ test.describe('Playwright templatedPMTilesLayer Tests', () => {
     expect(errorFindingRules).toBe(true);
   });
   test('A protomaps map-link in a non-OSMTILE map-extent is never enabled', async () => {
-    await page.goto('templatedPMTilesCBMTILETest.html');
+    await page.goto('templatedPMTilesCBMTILETest.html', {
+      waitUntil: 'networkidle'
+    });
     await page.waitForTimeout(500);
     const viewer = page.getByTestId('viewer');
     const flexProjectionLayer = page.getByTestId('flexible-projection-layer');
@@ -103,7 +114,9 @@ test.describe('Playwright templatedPMTilesLayer Tests', () => {
   test('A protomaps map-link, parent map-extent and ancestor map-layer are disabled when out of bounds', async ({
     page
   }) => {
-    await page.goto('templatedPMTilesMVTLayer.html');
+    await page.goto('templatedPMTilesMVTLayer.html', {
+      waitUntil: 'networkidle'
+    });
     await page.waitForTimeout(1000);
     const viewer = page.getByTestId('viewer');
     const lightLayer = page.getByTestId('light');
@@ -137,7 +150,9 @@ test.describe('Playwright templatedPMTilesLayer Tests', () => {
     page.on('console', async (msg) => {
       for (const arg of msg.args()) messages.push(await arg.jsonValue());
     });
-    await page.goto('templatedPMTilesMVTLayer.html');
+    await page.goto('templatedPMTilesMVTLayer.html', {
+      waitUntil: 'networkidle'
+    });
     const viewer = page.getByTestId('viewer');
     const lightLayer = page.getByTestId('light');
     await lightLayer.evaluate((l) => l.removeAttribute('checked'));
@@ -191,7 +206,9 @@ test.describe('Playwright templatedPMTilesLayer Tests', () => {
     expect(errorNoYInput).toBe(true);
   });
   test('Custom pmtilesRules can render mvt data', async ({ page }) => {
-    await page.goto('templatedPMTilesMVTLayerCustomStyles.html');
+    await page.goto('templatedPMTilesMVTLayerCustomStyles.html', {
+      waitUntil: 'networkidle'
+    });
     await page.waitForTimeout(1000);
     const viewer = page.getByTestId('viewer');
     // seems like a lot of pixels to allow to be different, but missing fonts
diff --git a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-blank-linux.png b/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-blank-linux.png
index d0012071e..45c81c15d 100644
Binary files a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-blank-linux.png and b/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-blank-linux.png differ
diff --git a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-blank-win32.png b/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-blank-win32.png
deleted file mode 100644
index d0012071e..000000000
Binary files a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-blank-win32.png and /dev/null differ
diff --git a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-custom-spearfish-linux.png b/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-custom-spearfish-linux.png
index 75eb0f806..b707a4b8f 100644
Binary files a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-custom-spearfish-linux.png and b/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-custom-spearfish-linux.png differ
diff --git a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-custom-spearfish-win32.png b/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-custom-spearfish-win32.png
deleted file mode 100644
index 37c2f3f9c..000000000
Binary files a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-custom-spearfish-win32.png and /dev/null differ
diff --git a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-light-linux.png b/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-light-linux.png
index a5888716b..5b8dd986d 100644
Binary files a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-light-linux.png and b/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-light-linux.png differ
diff --git a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-light-win32.png b/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-light-win32.png
deleted file mode 100644
index c3832b970..000000000
Binary files a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-light-win32.png and /dev/null differ
diff --git a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-light-z2-linux.png b/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-light-z2-linux.png
index 6b8ed275a..9d18258d1 100644
Binary files a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-light-z2-linux.png and b/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-light-z2-linux.png differ
diff --git a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-light-z2-win32.png b/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-light-z2-win32.png
deleted file mode 100644
index 8615239d9..000000000
Binary files a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/mvt-light-z2-win32.png and /dev/null differ
diff --git a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/pmtiles-dark-linux.png b/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/pmtiles-dark-linux.png
index 7d9945334..6084ea114 100644
Binary files a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/pmtiles-dark-linux.png and b/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/pmtiles-dark-linux.png differ
diff --git a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/pmtiles-dark-win32.png b/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/pmtiles-dark-win32.png
deleted file mode 100644
index bd6e71054..000000000
Binary files a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/pmtiles-dark-win32.png and /dev/null differ
diff --git a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/pmtiles-dark-z10-linux.png b/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/pmtiles-dark-z10-linux.png
index f4bcae849..60f573345 100644
Binary files a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/pmtiles-dark-z10-linux.png and b/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/pmtiles-dark-z10-linux.png differ
diff --git a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/pmtiles-dark-z10-win32.png b/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/pmtiles-dark-z10-win32.png
deleted file mode 100644
index 77f7a6983..000000000
Binary files a/test/e2e/layers/templatedPMTilesMVTLayer.test.js-snapshots/pmtiles-dark-z10-win32.png and /dev/null differ
diff --git a/test/e2e/mapml-viewer/customTCRS.test.js b/test/e2e/mapml-viewer/customTCRS.test.js
index 816ac480d..a38c2e965 100644
--- a/test/e2e/mapml-viewer/customTCRS.test.js
+++ b/test/e2e/mapml-viewer/customTCRS.test.js
@@ -9,7 +9,7 @@ test.describe('Playwright Custom TCRS Tests', () => {
       context.pages().find((page) => page.url() === 'about:blank') ||
       (await context.newPage());
     page = await context.newPage();
-    await page.goto('customTCRS.html');
+    await page.goto('customTCRS.html', { waitUntil: 'networkidle' });
   });
 
   test.afterAll(async function () {
@@ -17,7 +17,7 @@ test.describe('Playwright Custom TCRS Tests', () => {
   });
 
   test('Simple Custom TCRS, tiles load, mismatched layer disabled', async () => {
-    await page.waitForTimeout(500);
+    await page.waitForTimeout(2000);
     const misMatchedLayerDisabled = await page.$eval(
       'body > mapml-viewer:nth-child(1)',
       (map) => map.querySelectorAll('map-layer')[0].hasAttribute('disabled')
diff --git a/test/e2e/mapml-viewer/localization.html b/test/e2e/mapml-viewer/localization.html
index d7a820b2b..5fd06ae4d 100644
--- a/test/e2e/mapml-viewer/localization.html
+++ b/test/e2e/mapml-viewer/localization.html
@@ -4,7 +4,7 @@
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width,initial-scale=1">
     <title>localization.html</title>
-    <template data-testid="map-options"><map-options>{"locale":{"cmBack":"Повернутися назад","cmForward":"Перейти вперед","cmReload":"Перезавантажити","cmToggleControls":"Увімкнути/вимкнути елементи керування","cmCopyCoords":"Копіювати","cmToggleDebug":"Перемкнути на режим діагностики","cmCopyMapML":"Мапа","cmCopyExtent":"Межа екрану","cmCopyLocation":"Місцеположення","cmPasteLayer":"Вставити","cmViewSource":"Переглянути джерело мапи","lmZoomToLayer":"Збільшити до шару","lmCopyLayer":"Копіювати шар","lmLayerSettings":"Налаштування шару","lmRemoveLayer":"Видалити шар","lmZoomToExtent":"Збільшити до підтипу шару","lmCopyExtent":"Копіювати підтип шару","lmExtentSettings":"Налаштування підшару","lmRemoveExtent":"Видалити підшар","lmStyle":"Стиль","lcOpacity":"Прозорість","btnZoomIn":"Збільшити","btnZoomOut":"Зменшити","btnAttribution":"Авторські права","btnFullScreen":"Повноекранний режим","btnExitFullScreen":"Вихід з повноекранного режиму","btnLocTrackOn":"Показувати моє місцезнаходження - відстеження місцезнаходження увімкнено","btnMyLocTrackOn":"Моє поточне місцезнаходження на карті","btnLocTrackOff":"Показувати моє місцезнаходження - відстеження місцезнаходження вимкнено","btnMyLastKnownLocTrackOn":"Моє останнє відоме місцезнаходження на карті","btnLocTrackLastKnown":"Показати моє місцезнаходження - показано останнє відоме місцезнаходження","btnFocusMap":"Карта Фокусування","btnFocusControls":"Елементи Керування Фокусуванням","btnPrevFeature":"Попередня Функція","btnNextFeature":"Наступна Функція","amZoom":"рівень масштабування","amColumn":"стовпчик","amRow":"рядок","amMaxZoom":"На максимальному рівні масштабування наближення вимкнено","amMinZoom":"На мінімальному рівні масштабування зменшення масштабу вимкнено","amZoomedOut":"Збільшення за межами, повернутись до","amDraggedOut":"Розширення за межами, повернутись до","amEastBound":"Досягнуто східного напрямку, панорамування на схід вимкнено","amWestBound":"Досягнуто західного напрямку, панорамування на захід вимкнено","amNorthBound":"Досягнуто північного напрямку, панорамування на північ вимкнено","amSouthBound":"Досягнуто південного напрямку, панорамування на південь вимкнено","kbdShortcuts":"Комбінації клавіш","kbdMovement":"Клавіші переміщення","kbdFeature":"Функціональні клавіші навігації","kbdPanUp":"Переміщення вгору","kbdPanDown":"Переміщення вниз","kbdPanLeft":"Переміщення ліворуч","kbdPanRight":"Переміщення праворуч","kbdPanIncrement":"крок переміщення зображення","kbdZoom":"Збільшення/зменшення на 3 рівні","kbdFocusMap":"Сфокусувати карту","kbdFocusControls":"Сфокусувати елементи керування","kbdPrevFeature":"Попередній об'єкт","kbdNextFeature":"Наступний об'єкт","dfLayer":"Шар","dfExtent":"Підтип шару","dfPastedLayer":"Вставлений шар","dfFeatureCaption":"Об'єкт","popupZoom":"Наблизити сюди","popupPropName":"Назва властивості","popupPropValue":"Значення властивості","fIndexNoFeatures":"Об'єктів не знайдено"}}</map-options></template>
+    <template data-testid="map-options"><map-options>{"locale":{"cmBack":"Повернутися назад","cmForward":"Перейти вперед","cmReload":"Перезавантажити","cmToggleControls":"Увімкнути/вимкнути елементи керування","cmCopyCoords":"Копіювати","cmToggleDebug":"Перемкнути на режим діагностики","cmCopyMapML":"Мапа","cmCopyExtent":"Межа екрану","cmCopyLocation":"Місцеположення","cmPasteLayer":"Вставити","cmViewSource":"Переглянути джерело мапи","lmZoomToLayer":"Збільшити до шару","lmCopyLayer":"Копіювати шар","lmLayerSettings":"Налаштування шару","lmRemoveLayer":"Видалити шар","lmZoomToExtent":"Збільшити до підтипу шару","lmCopyExtent":"Копіювати підтип шару","lmExtentSettings":"Налаштування підшару","lmRemoveExtent":"Видалити підшар","lmStyle":"Стиль","lcOpacity":"Прозорість","btnZoomIn":"Збільшити","btnZoomOut":"Зменшити","btnAttribution":"Авторські права","btnFullScreen":"Повноекранний режим","btnExitFullScreen":"Вихід з повноекранного режиму","btnLocTrackOn":"Показувати моє місцезнаходження - відстеження місцезнаходження увімкнено","btnMyLocTrackOn":"Моє поточне місцезнаходження на карті","btnLocTrackOff":"Показувати моє місцезнаходження - відстеження місцезнаходження вимкнено","btnMyLastKnownLocTrackOn":"Моє останнє відоме місцезнаходження на карті","btnLocTrackLastKnown":"Показати моє місцезнаходження - показано останнє відоме місцезнаходження","btnFocusMap":"Карта Фокусування","btnFocusControls":"Елементи Керування Фокусуванням","btnPrevFeature":"Попередня Функція","btnNextFeature":"Наступна Функція","amZoom":"рівень масштабування","amColumn":"стовпчик","amRow":"рядок","amMaxZoom":"На максимальному рівні масштабування наближення вимкнено","amMinZoom":"На мінімальному рівні масштабування зменшення масштабу вимкнено","amZoomedOut":"Збільшення за межами, повернутись до","amDraggedOut":"Розширення за межами, повернутись до","amEastBound":"Досягнуто східного напрямку, панорамування на схід вимкнено","amWestBound":"Досягнуто західного напрямку, панорамування на захід вимкнено","amNorthBound":"Досягнуто північного напрямку, панорамування на північ вимкнено","amSouthBound":"Досягнуто південного напрямку, панорамування на південь вимкнено","kbdShortcuts":"Комбінації клавіш","kbdMovement":"Клавіші переміщення","kbdFeature":"Функціональні клавіші навігації","kbdPanUp":"Переміщення вгору","kbdPanDown":"Переміщення вниз","kbdPanLeft":"Переміщення ліворуч","kbdPanRight":"Переміщення праворуч","kbdPanIncrement":"крок переміщення зображення","kbdZoom":"Збільшення/зменшення на 3 рівні","kbdFocusMap":"Сфокусувати карту","kbdFocusControls":"Сфокусувати елементи керування","kbdPrevFeature":"Попередній об'єкт","kbdNextFeature":"Наступний об'єкт","dfLayer":"Шар","dfExtent":"Підтип шару","dfPastedLayer":"Вставлений шар","dfFeatureCaption":"Об'єкт","popupZoom":"Наблизити сюди","popupPropName":"Назва властивості","popupPropValue":"Значення властивості","fIndexNoFeatures":"Об'єктів не знайдено","btnSearch":"Пошук","btnSearchClose":"Закрити пошук","searchPlaceholder":"Пошук\u2026","searchResultWithNoName":"Без назви"}}</map-options></template>
     <script>
 // this is the only way to force the browser to  keep the map-options element in
 // the head, where it is looked for by the mapml-viewer...
@@ -42,9 +42,10 @@
     <script type="module" src="./mapml.js"></script>
   </head>
   <body >
-    <mapml-viewer data-testid="french" lang="fr" projection="CBMTILE" zoom="2" lat="56.8" lon="-90" controls controlslist="geolocation" width="500" height="275">
+    <mapml-viewer data-testid="french" lang="fr" projection="CBMTILE" zoom="2" lat="56.8" lon="-90" controls controlslist="geolocation search" width="500" height="275">
       <layer- checked>
         <map-meta name="projection" content="CBMTILE"></map-meta>
+        <map-link rel="search" tref="localization.mapml?q={searchTerms}"></map-link>
         <map-extent units="CBMTILE" checked>
           <map-link rel="query" tref="localization.mapml" ></map-link>
         </map-extent>
@@ -58,9 +59,10 @@
       <layer- src="localization.red.mapml"></layer->
       
     </mapml-viewer>
-    <mapml-viewer data-testid="ukrainian" lang="browser-language" projection="CBMTILE" zoom="2" lat="56.8" lon="-90"  controls controlslist="geolocation" width="500" height="275">
+    <mapml-viewer data-testid="ukrainian" lang="browser-language" projection="CBMTILE" zoom="2" lat="56.8" lon="-90"  controls controlslist="geolocation search" width="500" height="275">
       <layer- checked>
         <map-meta name="projection" content="CBMTILE"></map-meta>
+        <map-link rel="search" tref="localization.mapml?q={searchTerms}"></map-link>
         <map-extent units="CBMTILE" checked>
           <map-link rel="query" tref="localization.mapml" ></map-link>
         </map-extent>
@@ -73,9 +75,10 @@
       </layer->
       <layer- src="localization.red.mapml"></layer->
     </mapml-viewer>
-    <mapml-viewer data-testid="english" lang="en" projection="CBMTILE" zoom="2" lat="56.8" lon="-90"  controls controlslist="geolocation" width="500" height="275">
+    <mapml-viewer data-testid="english" lang="en" projection="CBMTILE" zoom="2" lat="56.8" lon="-90"  controls controlslist="geolocation search" width="500" height="275">
       <layer- checked>
         <map-meta name="projection" content="CBMTILE"></map-meta>
+        <map-link rel="search" tref="localization.mapml?q={searchTerms}"></map-link>
         <map-extent units="CBMTILE" checked>
           <map-link rel="query" tref="localization.mapml" ></map-link>
         </map-extent>
diff --git a/test/e2e/mapml-viewer/localization.test.js b/test/e2e/mapml-viewer/localization.test.js
index ebf25812f..dca0f4419 100644
--- a/test/e2e/mapml-viewer/localization.test.js
+++ b/test/e2e/mapml-viewer/localization.test.js
@@ -17,7 +17,7 @@ test.describe('<mapml-viewer> localization tests', () => {
       context.pages().find((page) => page.url() === 'about:blank') ||
       (await context.newPage());
     page = await context.newPage();
-    await page.goto('localization.html');
+    await page.goto('localization.html', { waitUntil: 'networkidle' });
 
     // fetch locales and check that they are not undefined
     browserLocale = await page.getByTestId('map-options').evaluate((t) => {
@@ -221,6 +221,48 @@ test.describe('<mapml-viewer> localization tests', () => {
     }
   });
 
+  test('Search button and panel messages match the locale key', async () => {
+    for (const [language, locale] of locales) {
+      const map = await page.getByTestId(language);
+
+      // search button title
+      const searchBtn = await map.locator('.mapml-search-button');
+      const searchTitle = await searchBtn.getAttribute('title');
+      expect(searchTitle).toBeTruthy();
+      expect(searchTitle).toBe(locale.btnSearch);
+
+      // search button aria-label
+      const searchAriaLabel = await searchBtn.getAttribute('aria-label');
+      expect(searchAriaLabel).toBe(locale.btnSearch);
+
+      // open the search panel
+      await searchBtn.click();
+      await page.waitForTimeout(400);
+
+      // search input placeholder
+      const searchInput = await map.locator('.mapml-search-input');
+      const placeholder = await searchInput.getAttribute('placeholder');
+      expect(placeholder).toBeTruthy();
+      expect(placeholder).toBe(locale.searchPlaceholder);
+
+      // search input aria-label
+      const inputAriaLabel = await searchInput.getAttribute('aria-label');
+      expect(inputAriaLabel).toBe(locale.btnSearch);
+
+      // close button title and aria-label
+      const closeBtn = await map.locator('.mapml-search-close');
+      const closeTitle = await closeBtn.getAttribute('title');
+      expect(closeTitle).toBeTruthy();
+      expect(closeTitle).toBe(locale.btnSearchClose);
+      const closeAriaLabel = await closeBtn.getAttribute('aria-label');
+      expect(closeAriaLabel).toBe(locale.btnSearchClose);
+
+      // close the panel
+      await closeBtn.click();
+      await page.waitForTimeout(400);
+    }
+  });
+
   test('Hover messages for location tracking matches the locale key', async () => {
     for (const [language, locale] of locales) {
       // select the current map
diff --git a/test/e2e/mapml-viewer/mapml-viewer.test.js b/test/e2e/mapml-viewer/mapml-viewer.test.js
index 1911cfede..34bcd96b0 100644
--- a/test/e2e/mapml-viewer/mapml-viewer.test.js
+++ b/test/e2e/mapml-viewer/mapml-viewer.test.js
@@ -134,6 +134,47 @@ test.describe('Playwright mapml-viewer Element Tests', () => {
         await expect(layerControl).toBeHidden();
       });
     });
+    test.describe('Controls List search Attribute Tests', () => {
+      test('controlslist=search shows search control', async () => {
+        await page.$eval('body > mapml-viewer', (viewer) =>
+          viewer.setAttribute('controlslist', 'search')
+        );
+        let searchControl = await page.locator('.mapml-search-control');
+        await expect(searchControl).toBeVisible();
+      });
+      test('search control hidden when controlslist does not contain search', async () => {
+        await page.$eval('body > mapml-viewer', (viewer) =>
+          viewer.setAttribute('controlslist', 'noreload')
+        );
+        let searchControl = await page.locator('.mapml-search-control');
+        await expect(searchControl).toBeHidden();
+      });
+      test('search control persists after toggling controls', async () => {
+        await page.$eval('body > mapml-viewer', (viewer) =>
+          viewer.setAttribute('controlslist', 'search')
+        );
+        // toggle controls off
+        await page.click('body > mapml-viewer', { button: 'right' });
+        await page.click('.mapml-contextmenu > button:nth-of-type(6)');
+        // toggle controls on
+        await page.click('body > mapml-viewer', { button: 'right' });
+        await page.click('.mapml-contextmenu > button:nth-of-type(6)');
+
+        let searchControl = await page.locator('.mapml-search-control');
+        await expect(searchControl).toBeVisible();
+      });
+      test('controlsList property reflects search token', async () => {
+        let contains = await page.$eval('body > mapml-viewer', (viewer) =>
+          viewer.controlsList.contains('search')
+        );
+        expect(contains).toEqual(true);
+
+        // clean up
+        await page.$eval('body > mapml-viewer', (viewer) =>
+          viewer.removeAttribute('controlslist')
+        );
+      });
+    });
   });
   test('Paste geojson Layer to map using ctrl+v', async () => {
     await page.click('body > textarea#copyGeoJSON');
diff --git a/test/e2e/web-map/map.test.js b/test/e2e/web-map/map.test.js
index 9bd91394c..e28df2682 100644
--- a/test/e2e/web-map/map.test.js
+++ b/test/e2e/web-map/map.test.js
@@ -145,4 +145,46 @@ test.describe('Playwright web-map Element Tests', () => {
     const currPos = await page.$eval('body > map', () => window.pageYOffset);
     expect(currPos).toEqual(0);
   });
+
+  test.describe('Controls List search Attribute Tests', () => {
+    test('controlslist=search shows search control', async () => {
+      await page.$eval('body > map', (map) =>
+        map.setAttribute('controlslist', 'search')
+      );
+      let searchControl = await page.locator('.mapml-search-control');
+      await expect(searchControl).toBeVisible();
+    });
+    test('search control hidden when controlslist does not contain search', async () => {
+      await page.$eval('body > map', (map) =>
+        map.setAttribute('controlslist', 'noreload')
+      );
+      let searchControl = await page.locator('.mapml-search-control');
+      await expect(searchControl).toBeHidden();
+    });
+    test('search control persists after toggling controls', async () => {
+      await page.$eval('body > map', (map) =>
+        map.setAttribute('controlslist', 'search')
+      );
+      // toggle controls off
+      await page.click('body > map', { button: 'right' });
+      await page.click('.mapml-contextmenu > button:nth-of-type(6)');
+      // toggle controls on
+      await page.click('body > map', { button: 'right' });
+      await page.click('.mapml-contextmenu > button:nth-of-type(6)');
+
+      let searchControl = await page.locator('.mapml-search-control');
+      await expect(searchControl).toBeVisible();
+    });
+    test('controlsList property reflects search token', async () => {
+      let contains = await page.$eval('body > map', (map) =>
+        map.controlsList.contains('search')
+      );
+      expect(contains).toEqual(true);
+
+      // clean up
+      await page.$eval('body > map', (map) =>
+        map.removeAttribute('controlslist')
+      );
+    });
+  });
 });
diff --git a/test/server.js b/test/server.js
index 38859ab3e..7f0a036b3 100644
--- a/test/server.js
+++ b/test/server.js
@@ -243,4 +243,191 @@ app.use(
 
 console.log('Running on localhost:' + port);
 
+// Mock search suggestions endpoint for search control tests
+app.get('/search/suggestions', (req, res) => {
+  res.json({
+    type: 'FeatureCollection',
+    features: [
+      {
+        type: 'Feature',
+        properties: { display_name: 'Ottawa, Ontario, Canada', name: 'Ottawa' },
+        geometry: { type: 'Point', coordinates: [-75.6972, 45.4215] },
+        bbox: [-75.9, 45.2, -75.4, 45.6]
+      },
+      {
+        type: 'Feature',
+        properties: {
+          display_name: 'Ottawa River, Canada',
+          name: 'Ottawa River'
+        },
+        geometry: { type: 'Point', coordinates: [-75.5, 45.5] }
+      },
+      {
+        type: 'Feature',
+        properties: {
+          display_name: 'Gatineau, Quebec, Canada',
+          name: 'Gatineau'
+        },
+        geometry: { type: 'Point', coordinates: [-75.7, 45.48] }
+      }
+    ]
+  });
+});
+
+// Mock search results endpoint for search control tests
+app.get('/search/results', (req, res) => {
+  res.json({
+    type: 'FeatureCollection',
+    features: [
+      {
+        type: 'Feature',
+        properties: {
+          display_name: 'Ottawa, Ontario, Canada',
+          name: 'Ottawa'
+        },
+        geometry: { type: 'Point', coordinates: [-75.6972, 45.4215] },
+        bbox: [-75.9, 45.2, -75.4, 45.6]
+      }
+    ]
+  });
+});
+
+// Mock geonames suggestions endpoint (returns geonames-format items array)
+app.get('/geonames/suggestions', (req, res) => {
+  res.json({
+    items: [
+      {
+        id: 'FEVNT',
+        name: 'Ottawa',
+        latitude: 45.33339,
+        longitude: -75.58429,
+        bbox: [-76.3631149, 44.9445516, -75.2324963, 45.544859],
+        concise: { code: 'CITY' },
+        province: { code: '35' }
+      },
+      {
+        id: 'NAABK',
+        name: 'Arctic Ocean',
+        latitude: 80,
+        longitude: -140,
+        bbox: [-140.02, 79.98, -139.98, 80.02],
+        concise: { code: 'SEA' },
+        province: { code: '73' }
+      },
+      {
+        id: 'NAABI',
+        name: 'Atlantic Ocean',
+        latitude: 43,
+        longitude: -63,
+        bbox: [-63.02, 42.98, -62.98, 43.02],
+        concise: { code: 'SEA' },
+        province: { code: '73' }
+      }
+    ]
+  });
+});
+
+// Mock geonames search endpoint (returns geonames-format items array)
+app.get('/geonames/search', (req, res) => {
+  res.json({
+    items: [
+      {
+        id: 'FEVNT',
+        name: 'Ottawa',
+        latitude: 45.33339,
+        longitude: -75.58429,
+        bbox: [-76.3631149, 44.9445516, -75.2324963, 45.544859],
+        concise: { code: 'CITY' },
+        province: { code: '35' }
+      }
+    ]
+  });
+});
+
+// Mock second-layer geonames suggestions endpoint (returns different items)
+app.get('/geonames2/suggestions', (req, res) => {
+  res.json({
+    items: [
+      {
+        id: 'TRNTO',
+        name: 'Toronto',
+        latitude: 43.65107,
+        longitude: -79.347015,
+        bbox: [-79.6393, 43.4034, -79.1153, 43.8554],
+        concise: { code: 'CITY' },
+        province: { code: '35' }
+      },
+      {
+        id: 'MNTRL',
+        name: 'Montreal',
+        latitude: 45.50884,
+        longitude: -73.58781,
+        bbox: [-73.9726, 45.4104, -73.4742, 45.7047],
+        concise: { code: 'CITY' },
+        province: { code: '24' }
+      }
+    ]
+  });
+});
+
+// Mock second-layer geonames search endpoint
+app.get('/geonames2/search', (req, res) => {
+  res.json({
+    items: [
+      {
+        id: 'TRNTO',
+        name: 'Toronto',
+        latitude: 43.65107,
+        longitude: -79.347015,
+        bbox: [-79.6393, 43.4034, -79.1153, 43.8554],
+        concise: { code: 'CITY' },
+        province: { code: '35' }
+      }
+    ]
+  });
+});
+
+// Mock Japanese search suggestions endpoint (GeoJSON format)
+app.get('/search/ja/suggestions', (req, res) => {
+  res.json({
+    type: 'FeatureCollection',
+    features: [
+      {
+        type: 'Feature',
+        properties: { display_name: '東京都, 日本', name: '東京' },
+        geometry: { type: 'Point', coordinates: [139.6917, 35.6895] },
+        bbox: [138.9428, 35.5187, 139.9219, 35.8984]
+      },
+      {
+        type: 'Feature',
+        properties: {
+          display_name: '東京タワー, 東京都, 日本',
+          name: '東京タワー'
+        },
+        geometry: { type: 'Point', coordinates: [139.7454, 35.6586] }
+      },
+      {
+        type: 'Feature',
+        properties: { display_name: '東京駅, 東京都, 日本', name: '東京駅' },
+        geometry: { type: 'Point', coordinates: [139.7671, 35.6812] }
+      }
+    ]
+  });
+});
+
+// Mock Japanese search results endpoint (GeoJSON format)
+app.get('/search/ja/results', (req, res) => {
+  res.json({
+    type: 'FeatureCollection',
+    features: [
+      {
+        type: 'Feature',
+        properties: { display_name: '東京都, 日本', name: '東京' },
+        geometry: { type: 'Point', coordinates: [139.6917, 35.6895] },
+        bbox: [138.9428, 35.5187, 139.9219, 35.8984]
+      }
+    ]
+  });
+});
+
 app.listen(port);