From 4a0392acca80ea40e030f8e193337a762cfce6b7 Mon Sep 17 00:00:00 2001
From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com>
Date: Wed, 19 Aug 2026 21:12:00 -0400
Subject: [PATCH 1/7] Fix the addon typecheck so template modifiers resolve

`{{on}}` did not typecheck anywhere in `src/`, because two tsconfig settings
disagreed with what Glint needs:

- `moduleResolution: node16` stopped Glint's module augmentations from
  attaching, so `on` stayed the bare `Opaque<"modifier:on">` that
  ember-source declares and no `resolve` overload accepted it.
- `types` named `@glint/ember-tsc`, which is the tool's own API, rather than
  `@glint/ember-tsc/types`, which is the file that carries those
  augmentations.

`types` also read ember-source out of `docs-app/node_modules`. It reads the
addon's own copy now.

With the augmentations attached, a real error appears: `getSignature` returns
`undefined` when a declaration carries no signature, and the union check does
not narrow that away.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 src/browser/typedoc/signature/component.gts | 2 +-
 tsconfig.json                               | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/browser/typedoc/signature/component.gts b/src/browser/typedoc/signature/component.gts
index 0c7d6014..bfe15224 100644
--- a/src/browser/typedoc/signature/component.gts
+++ b/src/browser/typedoc/signature/component.gts
@@ -174,7 +174,7 @@ export const ComponentSignature: TOC<{
               <ComponentDeclaration @signature={{variant}} />
             </div>
           {{/each}}
-        {{else}}
+        {{else if info}}
           <ComponentDeclaration @signature={{info}} />
         {{/if}}
       </div>
diff --git a/tsconfig.json b/tsconfig.json
index 3fba1ce7..fe692255 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -11,11 +11,11 @@
     "isolatedModules": true,
 
     // @tsconfig/node22
-    "module": "node16",
+    "module": "esnext",
     "target": "es2022",
     "esModuleInterop": true,
     "skipLibCheck": true,
-    "moduleResolution": "node16",
+    "moduleResolution": "bundler",
 
     // My options
     "rootDir": "./src",
@@ -33,6 +33,6 @@
     "declaration": true,
     // Compat
     "allowSyntheticDefaultImports": true,
-    "types": ["./docs-app/node_modules/ember-source/types/stable", "unplugin", "@glint/ember-tsc"]
+    "types": ["ember-source/types", "unplugin", "@glint/ember-tsc/types"]
   }
 }

From f3b7e203eb06958248b89db8e6445c3c4df16d0b Mon Sep 17 00:00:00 2001
From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com>
Date: Wed, 19 Aug 2026 21:12:10 -0400
Subject: [PATCH 2/7] Add <Search />: site-wide search as a command palette

`<Search />` is `<CommandPalette>` from ember-primitives, filled in with what
`searcher` ranks. It renders a trigger button and a modal `<dialog>`, and it
needs nothing configured: the `docs()` plugin already wrote every page's
title, headings, and prose into the compiled docs.

The `:trigger` block replaces the button, and is yielded `open` and the
modifier that returns focus to it. The `:result` block replaces the group,
title, and excerpt.

`stripFormatting` now drops inline HTML, keeping the text it wrapped, so an
excerpt reads "press K" rather than "press <kbd>K</kbd>". Lowercase tag names
only, so a component written in prose survives.

The palette's own stylesheet answers frameworks that style a bare `dialog` as
a full-screen box around an `<article>`: `min-width: 100%` outranks any width
the palette sets, and centring the children squashes it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs-app/package.json                         |   2 +-
 docs-app/src/styles/app.css                   |  41 +++
 docs-app/src/templates/application.gts        |  82 +-----
 docs/navigation/meta.json                     |   2 +-
 docs/navigation/search.gjs.md                 | 110 ++++++++
 docs/navigation/search.json                   |   1 +
 package.json                                  |   2 +-
 pnpm-lock.yaml                                | 118 +++++----
 src/browser/components.ts                     |   2 +
 src/browser/components/search.css             | 186 +++++++++++++
 src/browser/components/search.gts             | 246 ++++++++++++++++++
 .../services/search/strip-formatting.test.ts  |  31 +++
 .../services/search/strip-formatting.ts       |  32 ++-
 .../markdown-only/app/routes/application.ts   |   5 +-
 .../app/templates/application.gts             |   3 +-
 test-apps/markdown-only/package.json          |   2 +-
 .../tests/search-component-test.ts            |  90 +++++++
 17 files changed, 799 insertions(+), 156 deletions(-)
 create mode 100644 docs/navigation/search.gjs.md
 create mode 100644 docs/navigation/search.json
 create mode 100644 src/browser/components/search.css
 create mode 100644 src/browser/components/search.gts
 create mode 100644 src/browser/services/search/strip-formatting.test.ts
 create mode 100644 test-apps/markdown-only/tests/search-component-test.ts

diff --git a/docs-app/package.json b/docs-app/package.json
index 6ed0fa70..fb616a1a 100644
--- a/docs-app/package.json
+++ b/docs-app/package.json
@@ -60,7 +60,7 @@
     "ember-eslint": "^0.7.0",
     "ember-modifier": "^4.3.0",
     "ember-page-title": "^9.0.3",
-    "ember-primitives": "^0.61.1",
+    "ember-primitives": "^0.62.0",
     "ember-qunit": "^9.1.0",
     "ember-resolver": "^13.2.0",
     "ember-resources": "^7.1.0",
diff --git a/docs-app/src/styles/app.css b/docs-app/src/styles/app.css
index ca9bb07b..17f55006 100644
--- a/docs-app/src/styles/app.css
+++ b/docs-app/src/styles/app.css
@@ -32,6 +32,47 @@ a[data-search-result]:is(:hover, :focus, :active) {
   text-decoration: none;
 }
 
+/*
+ * <Search /> in pico's colours. The component brings its own layout; these
+ * are the only values it asks for.
+ */
+:root {
+  --kolay-search-bg: var(--pico-background-color);
+  --kolay-search-fg: var(--pico-color);
+  --kolay-search-muted: var(--pico-muted-color);
+  --kolay-search-border: var(--pico-muted-border-color);
+  --kolay-search-accent: var(--pico-primary);
+  --kolay-search-active: color-mix(in oklab, var(--pico-primary), transparent 88%);
+}
+
+/* the palette's results are anchors too, and pico reaches them the same way */
+a.kolay__search__result,
+a.kolay__search__result:is(:hover, :focus, :active) {
+  --pico-color: inherit;
+  --pico-background-color: inherit;
+  color: inherit;
+  text-decoration: none;
+}
+
+/*
+ * The palette's input. Pico reaches every text input through a selector that
+ * carries an attribute, which outranks the component's single class, and
+ * gives it a box and a bottom margin the palette does not want.
+ */
+input.kolay__search__input {
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: none;
+  box-shadow: none;
+}
+
+/* the header's middle column, where the old search form used to sit */
+header .kolay__search__trigger {
+  flex: 1;
+  max-width: 24rem;
+}
+
 /*
  * The shine's colours. Kept as their own names so the sweep can be retuned in
  * one place: the site's primary at the leading edge, running through violet
diff --git a/docs-app/src/templates/application.gts b/docs-app/src/templates/application.gts
index 45b8a298..5f6977ac 100644
--- a/docs-app/src/templates/application.gts
+++ b/docs-app/src/templates/application.gts
@@ -7,9 +7,8 @@ import { pascalCase, sentenceCase } from 'change-case';
 // @ts-expect-error no types for the mobile-menu
 import MenuWrapper from 'ember-mobile-menu/components/mobile-menu-wrapper';
 import { pageTitle } from 'ember-page-title';
-import { Form } from 'ember-primitives/components/form';
 import Route from 'ember-route-template';
-import { GroupNav, PageNav } from 'kolay/components';
+import { GroupNav, PageNav, Search } from 'kolay/components';
 import rememberDocumentScroll from 'memory-scroll/modifiers/remember-document-scroll';
 import { ExternalLink } from 'nvp.ui';
 
@@ -73,83 +72,6 @@ const Menu: TOC<{ Element: SVGElement }> = <template>
     ></path></svg>
 </template>;
 
-class HeaderSearch extends Component<{ Args: Record<string, never> }> {
-  @service declare router: RouterService;
-
-  get isSearchRoute() {
-    return this.router.currentRouteName === 'search';
-  }
-
-  submit = (data: { q?: string }) => {
-    const q = data.q ?? '';
-
-    this.router.transitionTo('search', { queryParams: { q } });
-  };
-
-  <template>
-    {{#unless this.isSearchRoute}}
-      <Form data-search @onChange={{this.submit}}>
-        <input aria-label="Search documentation" placeholder="Search docs" name="q" />
-        <button type="submit" aria-label="Search">
-          <svg aria-hidden="true" viewBox="0 0 24 24"><circle cx="11" cy="11" r="6.5"></circle><path
-              d="m16 16 5 5"
-            ></path></svg>
-        </button>
-      </Form>
-    {{/unless}}
-
-    <style scoped>
-      [data-search] {
-        flex: 1;
-        display: flex;
-        max-width: 24rem;
-        margin: 0;
-        input {
-          min-width: 0;
-          width: 100%;
-          margin: 0;
-          padding: 0.5rem 1rem;
-          line-height: 1rem;
-          height: auto;
-          border-radius: 0.35rem 0 0 0.35rem;
-        }
-
-        button {
-          display: inline-flex;
-          width: auto;
-          align-items: center;
-          justify-content: center;
-          margin: 0;
-          padding: 0.4rem 0.65rem;
-          border-radius: 0 0.35rem 0.35rem 0;
-        }
-
-        svg {
-          width: 1rem;
-          height: 1rem;
-          fill: none;
-          stroke: currentColor;
-          stroke-linecap: round;
-          stroke-linejoin: round;
-          stroke-width: 2;
-        }
-      }
-
-      @media (width < 1000px) {
-        [data-search] {
-          max-width: 18rem;
-        }
-      }
-
-      @media (width < 600px) {
-        [data-search] {
-          max-width: none;
-        }
-      }
-    </style>
-  </template>
-}
-
 const SideNav: TOC<{ Element: HTMLElement }> = <template>
   <aside>
     <PageNav ...attributes>
@@ -202,7 +124,7 @@ export default Route(
             <mmw.Toggle><Menu /></mmw.Toggle>
             <GroupNav />
           </div>
-          <HeaderSearch />
+          <Search />
           <div>
             <ExternalLink href="https://github.com/universal-ember/kolay">GitHub</ExternalLink>
           </div>
diff --git a/docs/navigation/meta.json b/docs/navigation/meta.json
index ed6dea57..0dd8fc13 100644
--- a/docs/navigation/meta.json
+++ b/docs/navigation/meta.json
@@ -1,3 +1,3 @@
 {
-  "order": ["is-active", "group-nav", "page-nav", "handle-potential-index-visit"]
+  "order": ["is-active", "group-nav", "page-nav", "search", "handle-potential-index-visit"]
 }
diff --git a/docs/navigation/search.gjs.md b/docs/navigation/search.gjs.md
new file mode 100644
index 00000000..8a186cc5
--- /dev/null
+++ b/docs/navigation/search.gjs.md
@@ -0,0 +1,110 @@
+# `<Search />`
+
+Site-wide search, as a command palette. The <kbd>⌘</kbd><kbd>K</kbd> in this site's header is this component.
+
+```gjs
+import { Search } from 'kolay/components';
+
+<template>
+  <Search />
+</template>
+```
+
+There is nothing to index and nothing to configure. The `docs()` plugin already wrote every page's title, headings, and prose into the compiled docs; this renders what [`searcher`](/Runtime/utilities/search.md) ranks.
+
+Put it in your application template, next to your nav. It renders a button; the palette itself is a `<dialog>`, so it does not matter where in the layout it sits.
+
+## What it is
+
+`<CommandPalette>` from [ember-primitives](https://ember-primitives.pages.dev/5-floaty-bits/command-palette), filled in with kolay's index:
+
+- The `<dialog>` handles the layer, the focus trap, and returning focus to whatever opened it.
+- `aria-activedescendant` handles the keyboard, so <kbd>ArrowUp</kbd> and <kbd>ArrowDown</kbd> move the selection while the caret stays where the reader is typing.
+- <kbd>Enter</kbd> clicks the active result, which is a real link, so the router navigates and <kbd>⌘</kbd>-click still opens a new tab.
+- <kbd>Esc</kbd>, and a click outside, close it.
+
+Excerpts come from `stripFormatting`, and the query is marked inside them with `highlightSearch`. Both are documented under [`searcher`](/Runtime/utilities/search.md).
+
+## Arguments
+
+| argument       | default                                   | what it does                                                                        |
+| :------------- | :---------------------------------------- | :---------------------------------------------------------------------------------- |
+| `@hotkey`      | `"mod+k"`                                 | Opens the palette from anywhere. `mod` is <kbd>⌘</kbd> on macOS, <kbd>Ctrl</kbd> elsewhere. Pass `""` to install no listener. |
+| `@minLength`   | `3`                                       | How much the reader types before the index is consulted.                            |
+| `@limit`       | `20`                                      | How many results to render.                                                          |
+| `@placeholder` | `"Search titles, headings, and prose…"`   | The input's placeholder.                                                             |
+
+## Your own trigger
+
+The `:trigger` block is yielded `open`, and the modifier that returns focus to your button when the palette closes.
+
+```gjs
+import { on } from '@ember/modifier';
+import { Search } from 'kolay/components';
+
+<template>
+  <Search>
+    <:trigger as |open focusOnClose|>
+      <button type="button" class="my-search-button" {{focusOnClose}} {{on "click" open}}>
+        🔍
+      </button>
+    </:trigger>
+  </Search>
+</template>
+```
+
+Leave the block empty to render no trigger at all, and open the palette with the hotkey alone.
+
+## Your own result
+
+The `:result` block replaces the group, title, and excerpt, and is yielded the result and the query.
+
+```gjs
+import { Search } from 'kolay/components';
+import { stripFormatting } from 'kolay';
+
+<template>
+  <Search>
+    <:result as |result|>
+      <strong>{{result.title}}</strong>
+      <small>{{result.score}}</small>
+    </:result>
+  </Search>
+</template>
+```
+
+A result carries everything `searcher` produces: `path`, `title`, `groupName`, `headings`, `score`, `text`, and `excerptRange`.
+
+## Styling
+
+Default styles ship in `kolay.css`, which you already import. The colours are variables. Set them on `:root` and the palette follows your site rather than the other way around.
+
+```css
+:root {
+  --kolay-search-bg: var(--my-surface);
+  --kolay-search-fg: var(--my-text);
+  --kolay-search-muted: var(--my-muted);
+  --kolay-search-border: var(--my-border);
+  --kolay-search-accent: var(--my-link);
+  --kolay-search-active: color-mix(in oklab, var(--my-link), transparent 88%);
+  --kolay-search-backdrop: rgb(0 0 0 / 0.45);
+  --kolay-search-width: 40rem;
+  --kolay-search-radius: 0.75rem;
+}
+```
+
+Every rule is a single class (`.kolay__search`, `.kolay__search__result`, and friends), so replacing one takes one class of your own.
+
+The active result is `[data-active="true"]`, set by the pointer and the keyboard alike. Style that, not `:hover`. One selector covers both inputs, and the two can never disagree about what <kbd>Enter</kbd> will do.
+
+## A search page as well
+
+`<Search />` is for looking something up and leaving. For a page a reader can link to and scroll through, keep the query in the URL and render the results yourself with [`searcher`](/Runtime/utilities/search.md). This site has both.
+
+## API Reference
+
+<ComponentSignature
+  @package='kolay'
+  @name='Search'
+  @module='declarations/browser/components'
+/>
diff --git a/docs/navigation/search.json b/docs/navigation/search.json
new file mode 100644
index 00000000..d3125374
--- /dev/null
+++ b/docs/navigation/search.json
@@ -0,0 +1 @@
+{ "title": "<Search />" }
diff --git a/package.json b/package.json
index c4fb7199..147c4ac5 100644
--- a/package.json
+++ b/package.json
@@ -105,7 +105,7 @@
     "content-tag": "^4.2.0",
     "decorator-transforms": "^2.4.0",
     "ember-modifier": "^4.3.0",
-    "ember-primitives": "^0.61.1",
+    "ember-primitives": "^0.62.0",
     "ember-repl": "^8.2.3",
     "ember-resources": "^7.1.0",
     "globby": "^16.2.3",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 06226114..84bf5b9b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -49,8 +49,8 @@ importers:
         specifier: ^4.3.0
         version: 4.3.0(@babel/core@7.29.6)
       ember-primitives:
-        specifier: ^0.61.1
-        version: 0.61.1(8ebab09bb361a1033c0d4670f0156827)
+        specifier: ^0.62.0
+        version: 0.62.0(8ebab09bb361a1033c0d4670f0156827)
       ember-repl:
         specifier: ^8.2.3
         version: 8.2.3(cc964920021e60069048b56ff774fc52)
@@ -113,7 +113,7 @@ importers:
         version: 5.1.0
       unplugin:
         specifier: ^3.3.0
-        version: 3.3.0(7bea9b67325345ecdaa4c5da97bc2602)
+        version: 3.3.0(2bcaf34f2946ad27a1ea5746ff858f48)
     devDependencies:
       '@arethetypeswrong/cli':
         specifier: ^0.18.5
@@ -147,7 +147,7 @@ importers:
         version: 2.7.0(cc8cad6b2644672ec8a53791bfc61df2)
       '@nullvoxpopuli/eslint-configs':
         specifier: ^6.0.0
-        version: 6.0.0(2623b96bd8796ff1dda85df06e0fbf20)
+        version: 6.0.0(f9ce830858153860498460c073f55162)
       '@rollup/plugin-babel':
         specifier: ^7.1.0
         version: 7.1.0(@babel/core@7.29.6)(rollup@4.62.4)
@@ -228,10 +228,10 @@ importers:
         version: 11.0.5
       vite:
         specifier: ^8.2.1
-        version: 8.2.1(f346081349e9d9bec3a079188f40de5d)
+        version: 8.2.1(f58fd458f9113fad7d7cd427a12c2777)
       vitest:
         specifier: ^4.1.10
-        version: 4.1.10(25d100c67c69e508113a54c50d05bf90)
+        version: 4.1.10(0458184e56ee698c03dbd913aa3fd20f)
 
   docs-app:
     dependencies:
@@ -354,8 +354,8 @@ importers:
         specifier: ^9.0.3
         version: 9.0.3
       ember-primitives:
-        specifier: ^0.61.1
-        version: 0.61.1(8ebab09bb361a1033c0d4670f0156827)
+        specifier: ^0.62.0
+        version: 0.62.0(8ebab09bb361a1033c0d4670f0156827)
       ember-qunit:
         specifier: ^9.1.0
         version: 9.1.0(4775d7173e4509504349392d113639b7)
@@ -668,8 +668,8 @@ importers:
         specifier: 2.4.0
         version: 2.4.0(@babel/core@7.29.6)
       ember-primitives:
-        specifier: ^0.61.1
-        version: 0.61.1(8ebab09bb361a1033c0d4670f0156827)
+        specifier: ^0.62.0
+        version: 0.62.0(8ebab09bb361a1033c0d4670f0156827)
       ember-source:
         specifier: 7.2.0
         version: 7.2.0(@glimmer/component@2.1.1)
@@ -4738,6 +4738,23 @@ packages:
       '@glint/template':
         optional: true
 
+  ember-primitives@0.62.0:
+    resolution: {integrity: sha512-olo9BdIyXkKleEKjQGq6Ya94iM7+Dr6TtT4+QLFyAzFQtHTENgy5rbEqFnbjw4qQmnibXR2s+jXxSDyPAQczhA==}
+    hasBin: true
+    peerDependencies:
+      '@ember/test-helpers': '>= 3.2.0'
+      '@ember/test-waiters': ^4.0.0
+      '@glimmer/component': ^2.0.0
+      '@glint/template': 1.8.0
+      ember-modifier: '>= 4.1.0'
+      ember-resources: '>= 6.1.0'
+      ember-source: '*'
+    peerDependenciesMeta:
+      '@ember/test-helpers':
+        optional: true
+      '@glint/template':
+        optional: true
+
   ember-qunit@9.1.0:
     resolution: {integrity: sha512-dE32lSODyv4em0ACBS8PDzrAIPKR75hhSpn/au0qFBlzbdmNA/VVsgv2aoFAVRdlQ0zYJ8EiNPFqsBFciIeXVA==}
     peerDependencies:
@@ -11153,32 +11170,6 @@ snapshots:
 
   '@npmcli/redact@4.0.0': {}
 
-  '@nullvoxpopuli/eslint-configs@6.0.0(2623b96bd8796ff1dda85df06e0fbf20)':
-    dependencies:
-      '@babel/core': 7.29.6
-      '@eslint/js': 9.39.5
-      '@typescript-eslint/parser': 8.67.0(a22af7cc2a9b4f923a2a857083e694fc)
-      cosmiconfig: 9.0.2(typescript@5.9.3)
-      ember-eslint: 0.7.0(567c781055764c0d2ffe0fcac674a2ab)
-      eslint: 9.39.2(jiti@2.7.0)
-      eslint-import-resolver-typescript: 4.4.5(c1fa6aa5ee024590b3a7706b3b6c9c93)
-      eslint-plugin-decorator-position: 6.1.1(1ec773deb7e2e87d2c67a69422e3dfea)
-      eslint-plugin-import: 2.32.0(c2ef3f53fd8ace59b3819fe0f037a792)
-      eslint-plugin-json: 4.0.1
-      eslint-plugin-n: 18.3.0(a22af7cc2a9b4f923a2a857083e694fc)
-      eslint-plugin-simple-import-sort: 13.0.0(eslint@9.39.2(jiti@2.7.0))
-      globals: 17.11.0
-      prettier-plugin-ember-template-tag: 2.1.7(prettier@3.9.6)
-    optionalDependencies:
-      '@babel/eslint-parser': 7.29.7(9fedd61231ed2bbbb4b975830aad6a5d)
-      prettier: 3.9.6
-    transitivePeerDependencies:
-      - eslint-import-resolver-webpack
-      - eslint-plugin-import-x
-      - supports-color
-      - ts-declaration-location
-      - typescript
-
   '@nullvoxpopuli/eslint-configs@6.0.0(f9ce830858153860498460c073f55162)':
     dependencies:
       '@babel/core': 7.29.6
@@ -11906,13 +11897,13 @@ snapshots:
       chai: 6.2.2
       tinyrainbow: 3.1.1
 
-  '@vitest/mocker@4.1.10(7f4a007e935d794cd6bc9555a6d64a29)':
+  '@vitest/mocker@4.1.10(51f1405c57abfc2aa30268e0bbea060d)':
     dependencies:
       '@vitest/spy': 4.1.10
       estree-walker: 3.0.3
       magic-string: 0.30.21
     optionalDependencies:
-      vite: 8.2.1(f346081349e9d9bec3a079188f40de5d)
+      vite: 8.2.1(f58fd458f9113fad7d7cd427a12c2777)
 
   '@vitest/pretty-format@4.1.10':
     dependencies:
@@ -13867,6 +13858,32 @@ snapshots:
       - '@babel/core'
       - supports-color
 
+  ember-primitives@0.62.0(8ebab09bb361a1033c0d4670f0156827):
+    dependencies:
+      '@babel/runtime': 7.28.6
+      '@ember/test-waiters': 4.1.2
+      '@embroider/addon-shim': 1.10.3
+      '@floating-ui/dom': 1.8.0
+      '@glimmer/component': 2.1.1
+      decorator-transforms: 2.3.2(@babel/core@7.29.6)
+      ember-element-helper: 0.8.8
+      ember-modifier: 4.3.0(@babel/core@7.29.6)
+      ember-resources: 7.1.0(7f20696a54e097830a4f237bc043d1a2)
+      ember-source: 7.2.0(@glimmer/component@2.1.1)
+      form-data-utils: 0.6.0
+      reactiveweb: 1.9.3(ba3a0abfb45c8ed92868e82388658d5d)
+      should-handle-link: 1.3.0
+      tabster: 8.8.0
+      tracked-built-ins: 4.1.2(@babel/core@7.29.6)
+      tracked-toolbox: 3.0.0(@babel/core@7.29.6)
+      which-heading-do-i-need: 0.4.1
+    optionalDependencies:
+      '@ember/test-helpers': 5.4.3(@babel/core@7.29.6)
+      '@glint/template': 1.8.0
+    transitivePeerDependencies:
+      - '@babel/core'
+      - supports-color
+
   ember-qunit@9.1.0(4775d7173e4509504349392d113639b7):
     dependencies:
       '@ember/test-helpers': 5.4.3(@babel/core@7.29.6)
@@ -18646,7 +18663,7 @@ snapshots:
       picomatch: 4.0.5
       webpack-virtual-modules: 0.6.2
 
-  unplugin@3.3.0(7bea9b67325345ecdaa4c5da97bc2602):
+  unplugin@3.3.0(2bcaf34f2946ad27a1ea5746ff858f48):
     dependencies:
       '@jridgewell/remapping': 2.3.5
       picomatch: 4.0.5
@@ -18654,7 +18671,7 @@ snapshots:
     optionalDependencies:
       rolldown: 1.2.4
       rollup: 4.62.4
-      vite: 8.2.1(f346081349e9d9bec3a079188f40de5d)
+      vite: 8.2.1(f58fd458f9113fad7d7cd427a12c2777)
 
   unrs-resolver@1.12.2:
     dependencies:
@@ -18751,19 +18768,6 @@ snapshots:
     dependencies:
       vite: 8.2.1(f58fd458f9113fad7d7cd427a12c2777)
 
-  vite@8.2.1(f346081349e9d9bec3a079188f40de5d):
-    dependencies:
-      lightningcss: 1.33.0
-      picomatch: 4.0.5
-      postcss: 8.5.26
-      rolldown: 1.2.4
-      tinyglobby: 0.2.17
-    optionalDependencies:
-      '@types/node': 26.2.0
-      fsevents: 2.3.3
-      jiti: 2.7.0
-      yaml: 2.9.0
-
   vite@8.2.1(f58fd458f9113fad7d7cd427a12c2777):
     dependencies:
       lightningcss: 1.33.0
@@ -18778,10 +18782,10 @@ snapshots:
       terser: 5.50.0
       yaml: 2.9.0
 
-  vitest@4.1.10(25d100c67c69e508113a54c50d05bf90):
+  vitest@4.1.10(0458184e56ee698c03dbd913aa3fd20f):
     dependencies:
       '@vitest/expect': 4.1.10
-      '@vitest/mocker': 4.1.10(7f4a007e935d794cd6bc9555a6d64a29)
+      '@vitest/mocker': 4.1.10(51f1405c57abfc2aa30268e0bbea060d)
       '@vitest/pretty-format': 4.1.10
       '@vitest/runner': 4.1.10
       '@vitest/snapshot': 4.1.10
@@ -18798,11 +18802,11 @@ snapshots:
       tinyexec: 1.3.0
       tinyglobby: 0.2.17
       tinyrainbow: 3.1.1
-      vite: 8.2.1(f346081349e9d9bec3a079188f40de5d)
+      vite: 8.2.1(f58fd458f9113fad7d7cd427a12c2777)
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 26.2.0
-      jsdom: 25.0.1
+      jsdom: 26.1.0
     transitivePeerDependencies:
       - msw
 
diff --git a/src/browser/components.ts b/src/browser/components.ts
index 25116870..d0f78c64 100644
--- a/src/browser/components.ts
+++ b/src/browser/components.ts
@@ -2,3 +2,5 @@ export { GroupNav } from './components/group-nav.gts';
 export { Logs } from './components/logs.gts';
 export { Page } from './components/page.gts';
 export { PageNav } from './components/page-nav.gts';
+export type { SearchSignature } from './components/search.gts';
+export { Search } from './components/search.gts';
diff --git a/src/browser/components/search.css b/src/browser/components/search.css
new file mode 100644
index 00000000..3f4cefc0
--- /dev/null
+++ b/src/browser/components/search.css
@@ -0,0 +1,186 @@
+/*
+ * <Search /> — the command palette.
+ *
+ * Colors come from these variables, so a host app can theme the palette
+ * without restating its layout. Set them on :root or any ancestor.
+ * Defaults are light-dark() aware.
+ *
+ *   --kolay-search-bg          the palette's surface
+ *   --kolay-search-fg          its text
+ *   --kolay-search-muted       the group label, the excerpt, the status line
+ *   --kolay-search-border      the rules between its parts
+ *   --kolay-search-active      the active result's background
+ *   --kolay-search-accent      the result title, and the query highlight
+ *   --kolay-search-backdrop    behind the modal
+ *   --kolay-search-radius      the palette's corners
+ *   --kolay-search-width       its width, capped to the viewport
+ *
+ * Every rule here is a single class, so overriding one takes a single class
+ * of your own — no specificity ladder to climb.
+ */
+
+.kolay__search {
+  --_bg: var(--kolay-search-bg, light-dark(#fff, #16181d));
+  --_fg: var(--kolay-search-fg, light-dark(#16181d, #f2f3f5));
+  --_muted: var(--kolay-search-muted, light-dark(#5c6370, #9aa1ad));
+  --_border: var(--kolay-search-border, light-dark(#e3e5e9, #2b2f37));
+  --_active: var(--kolay-search-active, light-dark(#f2f4f7, #23262d));
+  --_accent: var(--kolay-search-accent, light-dark(#0b5fd0, #79b8ff));
+
+  width: min(92vw, var(--kolay-search-width, 40rem));
+  max-height: min(70vh, 40rem);
+  margin-block-start: 10vh;
+  margin-inline: auto;
+  padding: 0;
+  overflow: hidden;
+  border: 1px solid var(--_border);
+  border-radius: var(--kolay-search-radius, 0.75rem);
+  background: var(--_bg);
+  color: var(--_fg);
+  /* the results scroll, not the palette */
+  display: flex;
+  flex-direction: column;
+  /*
+   * Some CSS frameworks style a bare `dialog` as a full-screen box that
+   * centres an `<article>` card inside it. The palette is the card, so those
+   * rules have to be answered here: `min-width: 100%` outranks any width, and
+   * centring the children squashes the input and the results.
+   */
+  min-width: 0;
+  min-height: 0;
+  height: auto;
+  align-items: stretch;
+  justify-content: flex-start;
+}
+
+.kolay__search::backdrop {
+  background: var(--kolay-search-backdrop, rgb(0 0 0 / 0.45));
+}
+
+/* the query, and the marks <Search /> puts on it inside each excerpt */
+::highlight(search-query) {
+  background: color-mix(in oklab, var(--kolay-search-accent, #79b8ff), transparent 70%);
+  text-decoration: underline;
+}
+
+.kolay__search__field {
+  display: flex;
+  gap: 0.6rem;
+  align-items: center;
+  flex: 0 0 auto;
+  padding: 0.85rem 1rem;
+  border-block-end: 1px solid var(--_border);
+  color: var(--_muted);
+}
+
+.kolay__search__icon {
+  width: 1.15rem;
+  height: 1.15rem;
+  flex: 0 0 auto;
+}
+
+.kolay__search__input {
+  width: 100%;
+  min-width: 0;
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: none;
+  color: inherit;
+  font: inherit;
+  font-size: 1.05rem;
+  color: var(--_fg);
+}
+
+.kolay__search__input:focus-visible {
+  outline: none;
+}
+
+.kolay__search__results {
+  flex: 1 1 auto;
+  overflow-y: auto;
+  padding: 0.4rem;
+}
+
+/* the result is the link: one target, and the whole card is it */
+.kolay__search__result {
+  display: block;
+  position: relative;
+  padding: 0.6rem 0.75rem;
+  border-radius: 0.5rem;
+  color: inherit;
+  text-decoration: none;
+  cursor: pointer;
+}
+
+/*
+ * The pointer and the keyboard set the same active result, so this one
+ * selector covers both — and they can never disagree about what Enter does.
+ * Do not add :hover.
+ */
+.kolay__search__result[data-active="true"] {
+  background: var(--_active);
+}
+
+.kolay__search__result__group {
+  margin: 0;
+  color: var(--_muted);
+  font-size: 0.7rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.kolay__search__result__title {
+  margin: 0.15rem 0 0.2rem;
+  color: var(--_accent);
+  font-size: 1rem;
+  line-height: 1.25;
+}
+
+.kolay__search__result[data-active="true"] .kolay__search__result__title {
+  text-decoration: underline;
+}
+
+.kolay__search__result__excerpt {
+  /* the clamp is a maximum; holding it as a minimum too keeps every card the
+     same height, whatever its excerpt turned out to be */
+  display: -webkit-box;
+  overflow: hidden;
+  min-height: 2lh;
+  max-height: 2lh;
+  margin: 0;
+  color: var(--_muted);
+  font-size: 0.875rem;
+  line-height: 1.4;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+}
+
+.kolay__search__status {
+  flex: 0 0 auto;
+  margin: 0;
+  padding: 0.6rem 1rem;
+  border-block-start: 1px solid var(--_border);
+  color: var(--_muted);
+  font-size: 0.8rem;
+}
+
+.kolay__search__trigger {
+  display: inline-flex;
+  gap: 0.5rem;
+  align-items: center;
+  padding: 0.4rem 0.7rem;
+  border: 1px solid var(--kolay-search-border, light-dark(#e3e5e9, #2b2f37));
+  border-radius: 0.5rem;
+  background: none;
+  color: inherit;
+  font: inherit;
+  font-size: 0.9rem;
+  cursor: pointer;
+}
+
+.kolay__search__trigger .kolay__search__icon {
+  width: 1rem;
+  height: 1rem;
+  opacity: 0.7;
+}
diff --git a/src/browser/components/search.gts b/src/browser/components/search.gts
new file mode 100644
index 00000000..9c129cc9
--- /dev/null
+++ b/src/browser/components/search.gts
@@ -0,0 +1,246 @@
+import './search.css';
+
+import Component from '@glimmer/component';
+import { cached, tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+
+import { CommandPalette } from 'ember-primitives/components/command-palette';
+import { Modal } from 'ember-primitives/components/dialog';
+import { KeyCombo } from 'ember-primitives/components/keys';
+import { getPromiseState } from 'reactiveweb/get-promise-state';
+
+import { searcher } from '../services/search.ts';
+import { highlightSearch } from '../services/search/highlight.ts';
+import { stripFormatting } from '../services/search/strip-formatting.ts';
+
+import type { SearchResult } from '../../types.ts';
+import type { TOC } from '@ember/component/template-only';
+import type { ModifierLike } from '@glint/template';
+
+const DEFAULT_HOTKEY = 'mod+k';
+const DEFAULT_MIN_LENGTH = 3;
+const DEFAULT_LIMIT = 20;
+
+/**
+ * The keys of a hotkey, as `<KeyCombo>` wants them. `mod` is a different key
+ * on macOS than everywhere else, so it is spelled twice.
+ */
+function keysFor(hotkey: string, mod: string) {
+  return hotkey
+    .split('+')
+    .map((key) => key.trim())
+    .map((key) => (key.toLowerCase() === 'mod' ? mod : key.toUpperCase()));
+}
+
+const MagnifyingGlass: TOC<{ Element: SVGElement }> = <template>
+  <svg
+    class='kolay__search__icon'
+    aria-hidden='true'
+    viewBox='0 0 24 24'
+    fill='none'
+    stroke='currentColor'
+    stroke-width='2'
+    stroke-linecap='round'
+    ...attributes
+  ><circle cx='11' cy='11' r='6.5' /><path d='m16 16 5 5' /></svg>
+</template>;
+
+export interface SearchSignature {
+  Args: {
+    /**
+     * The key combination that opens the palette from anywhere on the page.
+     *
+     * Defaults to `"mod+k"` -- <kbd>⌘</kbd><kbd>K</kbd> on macOS and
+     * <kbd>Ctrl</kbd><kbd>K</kbd> everywhere else. Pass an empty string to
+     * install no global listener at all.
+     */
+    hotkey?: string;
+    /**
+     * How much the reader has to type before the index is consulted.
+     *
+     * Defaults to 3. One or two characters match most of a docs site, which
+     * is the same as matching none of it.
+     */
+    minLength?: number;
+    /**
+     * How many results to render.
+     *
+     * Defaults to 20. Ranking already puts the answer near the top, and a
+     * palette that renders every page of a large site renders mostly noise.
+     */
+    limit?: number;
+    /**
+     * The input's placeholder.
+     */
+    placeholder?: string;
+  };
+  Blocks: {
+    /**
+     * Replaces the default "Search docs" button. Yielded `open`, and the
+     * modifier that returns focus to the trigger when the palette closes.
+     * Render nothing in the block to drive the palette with the hotkey alone.
+     */
+    trigger?: [open: () => void, focusOnClose: ModifierLike<{ Element: HTMLElement }>];
+    /**
+     * Replaces the default result: the group, the title, and the excerpt.
+     * Yielded the result, and the query that found it.
+     */
+    result?: [result: SearchResult, query: string];
+  };
+}
+
+/**
+ * Site-wide search, as a command palette.
+ *
+ * There is nothing to index and nothing to configure: the `docs()` plugin
+ * already wrote every page's title, headings, and prose into the compiled
+ * docs, and this renders what [`searcher`](/Runtime/utilities/search.md)
+ * ranks.
+ *
+ * ```gjs
+ * import { Search } from 'kolay/components';
+ *
+ * <template>
+ *   <Search />
+ * </template>
+ * ```
+ *
+ * The palette is `<CommandPalette>` from `ember-primitives`: a `<dialog>`
+ * for the layer and the focus, and `aria-activedescendant` for the keyboard.
+ */
+export class Search extends Component<SearchSignature> {
+  @tracked query = '';
+
+  get hotkey() {
+    return this.args.hotkey ?? DEFAULT_HOTKEY;
+  }
+
+  get minLength() {
+    return this.args.minLength ?? DEFAULT_MIN_LENGTH;
+  }
+
+  get limit() {
+    return this.args.limit ?? DEFAULT_LIMIT;
+  }
+
+  get hotkeyKeys() {
+    return keysFor(this.hotkey, 'Ctrl');
+  }
+
+  get hotkeyMacKeys() {
+    return keysFor(this.hotkey, '⌘');
+  }
+
+  get trimmed() {
+    return this.query.trim();
+  }
+
+  /**
+   * `@cached` so the search runs once per query rather than once per access:
+   * `getPromiseState` keys its state off the promise it is handed, and a new
+   * promise each time would mean a new pending state each time.
+   */
+  @cached
+  get search(): Promise<SearchResult[]> {
+    if (this.trimmed.length < this.minLength) return Promise.resolve([]);
+
+    return searcher(this).search(this.query);
+  }
+
+  get state() {
+    return getPromiseState(this.search);
+  }
+
+  get total() {
+    return this.state.resolved?.length ?? 0;
+  }
+
+  get results() {
+    return this.state.resolved?.slice(0, this.limit) ?? [];
+  }
+
+  /**
+   * What the listbox is doing, in words -- the part of a combobox a screen
+   * reader is not told by the options themselves.
+   */
+  get status() {
+    if (!this.trimmed) return 'Search every guide, reference page, heading, and paragraph.';
+
+    if (this.trimmed.length < this.minLength) {
+      return `Type at least ${this.minLength} characters.`;
+    }
+
+    if (this.state.isLoading) return 'Searching…';
+    if (this.total === 0) return `No results for “${this.trimmed}”.`;
+    if (this.total > this.limit) return `Showing ${this.limit} of ${this.total} results.`;
+
+    return this.total === 1 ? '1 result.' : `${this.total} results.`;
+  }
+
+  setQuery = (query: string) => {
+    this.query = query;
+  };
+
+  excerpt = (result: SearchResult) => stripFormatting(result.text, result.excerptRange);
+
+  <template>
+    <Modal as |m|>
+      {{#if (has-block 'trigger')}}
+        {{yield m.open m.focusOnClose to='trigger'}}
+      {{else}}
+        <button
+          type='button'
+          class='kolay__search__trigger'
+          {{m.focusOnClose}}
+          {{on 'click' m.open}}
+        >
+          <MagnifyingGlass />
+          <span>Search docs</span>
+          {{#if this.hotkey}}
+            <KeyCombo @keys={{this.hotkeyKeys}} @mac={{this.hotkeyMacKeys}} />
+          {{/if}}
+        </button>
+      {{/if}}
+
+      <m.Dialog class='kolay__search'>
+        <CommandPalette
+          @hotkey={{this.hotkey}}
+          @onOpen={{m.open}}
+          @onSelect={{m.close}}
+          @onQueryChange={{this.setQuery}}
+          as |c|
+        >
+          <div class='kolay__search__field'>
+            <MagnifyingGlass />
+            <c.Input
+              class='kolay__search__input'
+              aria-label='Search docs'
+              placeholder={{if @placeholder @placeholder 'Search titles, headings, and prose…'}}
+            />
+          </div>
+
+          <c.List class='kolay__search__results' as |l|>
+            {{#each this.results key='path' as |result|}}
+              <l.LinkItem class='kolay__search__result' @href={{result.path}}>
+                {{#if (has-block 'result')}}
+                  {{yield result this.query to='result'}}
+                {{else}}
+                  <p class='kolay__search__result__group'>{{result.groupName}}</p>
+                  <h2 class='kolay__search__result__title'>{{result.title}}</h2>
+                  <p
+                    class='kolay__search__result__excerpt'
+                    {{highlightSearch this.query}}
+                  >{{this.excerpt result}}</p>
+                {{/if}}
+              </l.LinkItem>
+            {{/each}}
+          </c.List>
+
+          <p class='kolay__search__status' role='status'>{{this.status}}</p>
+        </CommandPalette>
+      </m.Dialog>
+    </Modal>
+  </template>
+}
+
+export default Search;
diff --git a/src/browser/services/search/strip-formatting.test.ts b/src/browser/services/search/strip-formatting.test.ts
new file mode 100644
index 00000000..bac0be2a
--- /dev/null
+++ b/src/browser/services/search/strip-formatting.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, test } from 'vitest';
+
+import { stripFormatting } from './strip-formatting.ts';
+
+const whole = (text: string) => stripFormatting(text, { start: 0, end: text.length });
+
+describe('stripFormatting', () => {
+  test('drops emphasis and code marks', () => {
+    expect(whole('**bold** and `code` and _quiet_')).toBe('bold and code and quiet');
+  });
+
+  test('keeps the text of a link', () => {
+    expect(whole('read [the guide](/guides/one.md) first')).toBe('read the guide first');
+  });
+
+  test('drops list and blockquote markers', () => {
+    expect(whole('- one\n- two\n> quoted')).toBe('one two quoted');
+  });
+
+  test('drops inline HTML, keeping the text it wrapped', () => {
+    expect(whole('press <kbd>K</kbd> to search')).toBe('press K to search');
+  });
+
+  test('keeps a component written in prose', () => {
+    expect(whole('the <Search /> component')).toBe('the <Search /> component');
+  });
+
+  test('leaves a lone angle bracket alone', () => {
+    expect(whole('when a < b')).toBe('when a < b');
+  });
+});
diff --git a/src/browser/services/search/strip-formatting.ts b/src/browser/services/search/strip-formatting.ts
index 4bac1654..30d8041d 100644
--- a/src/browser/services/search/strip-formatting.ts
+++ b/src/browser/services/search/strip-formatting.ts
@@ -11,17 +11,23 @@ export function stripFormatting(
   text: string | null,
   range: { start: number; end: number }
 ): string {
-  return (text ?? '')
-    .slice(range.start, range.end)
-    .replaceAll(/^\s*(?:[-*+]|\d+[.)])\s+/gm, '') // list markers
-    .replaceAll(/^\s*>\s?/gm, '') // blockquote markers
-    .replaceAll(/^\s*\[\^[^\]]+\]:\s*/gm, '') // the label a footnote is defined under
-    .replaceAll(/\[\^[^\]]+\]/g, '') // and the references to it
-    .replaceAll(/!?\[([^\]]*)\]\([^)]*\)/g, '$1') // links and images: their text
-    .replaceAll(/!?\[([^\]]*)\]\[[^\]]*\]/g, '$1') // and the same for reference links
-    .replaceAll(/\s*\|\s*/g, ' ') // table cell walls
-    .replaceAll(/:?-{3,}:?/g, ' ') // and the rule under its header row
-    .replaceAll(/[`*_~]/g, '') // emphasis and code marks
-    .replaceAll(/\s+/g, ' ')
-    .trim();
+  return (
+    (text ?? '')
+      .slice(range.start, range.end)
+      .replaceAll(/^\s*(?:[-*+]|\d+[.)])\s+/gm, '') // list markers
+      .replaceAll(/^\s*>\s?/gm, '') // blockquote markers
+      .replaceAll(/^\s*\[\^[^\]]+\]:\s*/gm, '') // the label a footnote is defined under
+      .replaceAll(/\[\^[^\]]+\]/g, '') // and the references to it
+      .replaceAll(/!?\[([^\]]*)\]\([^)]*\)/g, '$1') // links and images: their text
+      .replaceAll(/!?\[([^\]]*)\]\[[^\]]*\]/g, '$1') // and the same for reference links
+      .replaceAll(/\s*\|\s*/g, ' ') // table cell walls
+      .replaceAll(/:?-{3,}:?/g, ' ') // and the rule under its header row
+      .replaceAll(/[`*_~]/g, '') // emphasis and code marks
+      // Inline HTML, keeping the text it wrapped. Lowercase names only: every
+      // HTML element has one, and a component written in prose does not, so
+      // `<Search />` survives and `<kbd>` does not.
+      .replaceAll(/<\/?[a-z][a-z0-9-]*(?:\s[^>]*?)?\/?>/g, '')
+      .replaceAll(/\s+/g, ' ')
+      .trim()
+  );
 }
diff --git a/test-apps/markdown-only/app/routes/application.ts b/test-apps/markdown-only/app/routes/application.ts
index 965f55e3..b3bf0d4f 100644
--- a/test-apps/markdown-only/app/routes/application.ts
+++ b/test-apps/markdown-only/app/routes/application.ts
@@ -1,9 +1,12 @@
 import Route from "@ember/routing/route";
 
+import { setupTabster } from "ember-primitives/tabster";
 import { setupKolay } from "kolay/setup";
 
 export default class ApplicationRoute extends Route {
   async model() {
-    await setupKolay(this, {});
+    // <CommandPalette>, behind <Search />, needs a focus manager, the same
+    // way <Menu> does
+    await Promise.all([setupKolay(this, {}), setupTabster(this)]);
   }
 }
diff --git a/test-apps/markdown-only/app/templates/application.gts b/test-apps/markdown-only/app/templates/application.gts
index b8894424..416fac1a 100644
--- a/test-apps/markdown-only/app/templates/application.gts
+++ b/test-apps/markdown-only/app/templates/application.gts
@@ -1,4 +1,4 @@
-import { GroupNav, PageNav } from "kolay/components";
+import { GroupNav, PageNav, Search } from "kolay/components";
 
 import type { TOC } from "@ember/component/template-only";
 import type { Page } from "kolay";
@@ -39,6 +39,7 @@ const SideNav: TOC<{ Element: HTMLElement }> = <template>
 <template>
   <header style="display: flex; align-items: baseline; gap: 1rem;">
     <GroupNav />
+    <Search />
   </header>
 
   <div class="big-layout">
diff --git a/test-apps/markdown-only/package.json b/test-apps/markdown-only/package.json
index 8960097a..9082d6d8 100644
--- a/test-apps/markdown-only/package.json
+++ b/test-apps/markdown-only/package.json
@@ -39,7 +39,7 @@
     "@embroider/router": "3.0.6",
     "@glimmer/component": "^2.1.1",
     "decorator-transforms": "2.4.0",
-    "ember-primitives": "^0.61.1",
+    "ember-primitives": "^0.62.0",
     "ember-source": "7.2.0",
     "ember-strict-application-resolver": "0.1.1"
   },
diff --git a/test-apps/markdown-only/tests/search-component-test.ts b/test-apps/markdown-only/tests/search-component-test.ts
new file mode 100644
index 00000000..63bd7f3e
--- /dev/null
+++ b/test-apps/markdown-only/tests/search-component-test.ts
@@ -0,0 +1,90 @@
+import {
+  click,
+  currentURL,
+  fillIn,
+  find,
+  triggerKeyEvent,
+  visit,
+  waitFor,
+  waitUntil,
+} from "@ember/test-helpers";
+import { module, test } from "qunit";
+import { setupApplicationTest } from "ember-qunit";
+
+const START = "/Docs/sub-folder/ember-primitives.md";
+
+/**
+ * `mod` is Meta on macOS and Control everywhere else -- the same split
+ * <Search /> renders in its trigger.
+ */
+const MOD = navigator.userAgent.includes("Mac OS") ? { metaKey: true } : { ctrlKey: true };
+
+module("<Search />", function (hooks) {
+  setupApplicationTest(hooks);
+
+  test("the trigger opens a combobox over the docs", async function (assert) {
+    await visit(START);
+
+    assert.dom("dialog.kolay__search").doesNotHaveAttribute("open");
+
+    await click(".kolay__search__trigger");
+
+    assert.dom("dialog.kolay__search").hasAttribute("open");
+    assert.dom(".kolay__search__input").hasAttribute("role", "combobox");
+    assert.dom(".kolay__search__status").hasText(/Search every guide/);
+  });
+
+  test("typing finds a page, and Enter goes to it", async function (assert) {
+    await visit(START);
+    await click(".kolay__search__trigger");
+
+    await fillIn(".kolay__search__input", "resources");
+    // a plain .md page's text is fetched outside the run loop, so settling
+    // isn't enough -- the results render once that fetch resolves
+    await waitFor(".kolay__search__result", { timeout: 5000 });
+
+    assert.dom(".kolay__search__result__title").hasText("ember resources");
+    assert.dom(".kolay__search__result").hasAttribute("role", "option");
+
+    // nothing arrowed: Enter takes the best result
+    await triggerKeyEvent(".kolay__search__input", "keydown", "Enter");
+
+    assert.strictEqual(currentURL(), "/Docs/sub-folder/ember-resources.md");
+    assert.dom("dialog.kolay__search").doesNotHaveAttribute("open");
+  });
+
+  test("a query too short to be useful is not run", async function (assert) {
+    await visit(START);
+    await click(".kolay__search__trigger");
+
+    await fillIn(".kolay__search__input", "re");
+
+    assert.dom(".kolay__search__result").doesNotExist();
+    assert.dom(".kolay__search__status").hasText("Type at least 3 characters.");
+  });
+
+  test("a query that matches nothing says so", async function (assert) {
+    await visit(START);
+    await click(".kolay__search__trigger");
+
+    await fillIn(".kolay__search__input", "zzzznotathinginthedocs");
+    // the status says "Searching…" until every page's text has been fetched
+    await waitUntil(() => !find(".kolay__search__status")?.textContent?.includes("Searching"), {
+      timeout: 5000,
+    });
+
+    assert.dom(".kolay__search__result").doesNotExist();
+    assert.dom(".kolay__search__status").hasText(/No results/);
+  });
+
+  test("the hotkey opens it from anywhere", async function (assert) {
+    await visit(START);
+
+    assert.dom("dialog.kolay__search").doesNotHaveAttribute("open");
+
+    await triggerKeyEvent(document.body, "keydown", "K", MOD);
+
+    assert.dom("dialog.kolay__search").hasAttribute("open");
+    assert.dom(".kolay__search__input").isFocused();
+  });
+});

From 4a0f67f60ac89699c8e5af5b82b2b65e3ec7415f Mon Sep 17 00:00:00 2001
From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com>
Date: Wed, 26 Aug 2026 17:21:21 -0400
Subject: [PATCH 3/7] Make the search trigger and its key hints fit the header

The trigger replaced an `<input>` and did not match its size. Its height came
from the key hints, which frameworks draw as a filled block in the body's own
colour: right for a keystroke named in prose, and far too loud for a hint on a
button. It ran 51px against the input's 42px and read as the loudest thing in
the header.

The keys are drawn as keys now, quiet and outlined, and sit at the far end of
the button with the label at the near end. The palette's own input also takes
`height: auto`, since a framework's fixed input height was making the field
98px tall for one line of text.

The docs app gets back the two width breakpoints the old header search had.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs-app/src/styles/app.css       | 15 ++++++++++++-
 src/browser/components/search.css | 37 +++++++++++++++++++++++++++++--
 src/browser/components/search.gts |  4 +++-
 3 files changed, 52 insertions(+), 4 deletions(-)

diff --git a/docs-app/src/styles/app.css b/docs-app/src/styles/app.css
index 17f55006..eeaa1fe2 100644
--- a/docs-app/src/styles/app.css
+++ b/docs-app/src/styles/app.css
@@ -60,6 +60,7 @@ a.kolay__search__result:is(:hover, :focus, :active) {
  * gives it a box and a bottom margin the palette does not want.
  */
 input.kolay__search__input {
+  height: auto;
   margin: 0;
   padding: 0;
   border: none;
@@ -67,12 +68,24 @@ input.kolay__search__input {
   box-shadow: none;
 }
 
-/* the header's middle column, where the old search form used to sit */
+/* the header's middle column */
 header .kolay__search__trigger {
   flex: 1;
   max-width: 24rem;
 }
 
+@media (width < 1000px) {
+  header .kolay__search__trigger {
+    max-width: 18rem;
+  }
+}
+
+@media (width < 600px) {
+  header .kolay__search__trigger {
+    max-width: none;
+  }
+}
+
 /*
  * The shine's colours. Kept as their own names so the sweep can be retuned in
  * one place: the site's primary at the leading edge, running through violet
diff --git a/src/browser/components/search.css b/src/browser/components/search.css
index 3f4cefc0..419c2056 100644
--- a/src/browser/components/search.css
+++ b/src/browser/components/search.css
@@ -82,13 +82,15 @@
 .kolay__search__input {
   width: 100%;
   min-width: 0;
+  /* frameworks tend to give an input a fixed height; this one is one line */
+  height: auto;
   margin: 0;
   padding: 0;
   border: none;
   background: none;
-  color: inherit;
   font: inherit;
   font-size: 1.05rem;
+  line-height: 1.4;
   color: var(--_fg);
 }
 
@@ -169,16 +171,47 @@
   display: inline-flex;
   gap: 0.5rem;
   align-items: center;
-  padding: 0.4rem 0.7rem;
+  padding: 0.4rem 0.5rem 0.4rem 0.7rem;
   border: 1px solid var(--kolay-search-border, light-dark(#e3e5e9, #2b2f37));
   border-radius: 0.5rem;
   background: none;
   color: inherit;
   font: inherit;
   font-size: 0.9rem;
+  line-height: 1.4;
   cursor: pointer;
 }
 
+/* the label sits at one end of the button and the shortcut at the other */
+.kolay__search__trigger__hint {
+  display: inline-flex;
+  gap: 0.25em;
+  align-items: center;
+  margin-inline-start: auto;
+  padding-inline-start: 0.75em;
+  font-size: 0.8em;
+}
+
+/*
+ * A key, drawn as a key. Frameworks tend to give `kbd` a filled block in the
+ * body's own colour, which is right for a keystroke named in prose and far
+ * too loud for a hint on a button: it doubles the button's height and reads
+ * as the most important thing in the header.
+ */
+.kolay__search__trigger kbd {
+  display: inline-block;
+  min-width: 1.5em;
+  padding: 0.1em 0.4em;
+  border: 1px solid var(--kolay-search-border, light-dark(#e3e5e9, #2b2f37));
+  border-radius: 0.3em;
+  background: var(--kolay-search-active, light-dark(#f2f4f7, #23262d));
+  color: inherit;
+  font: inherit;
+  font-size: 1em;
+  line-height: 1.4;
+  text-align: center;
+}
+
 .kolay__search__trigger .kolay__search__icon {
   width: 1rem;
   height: 1rem;
diff --git a/src/browser/components/search.gts b/src/browser/components/search.gts
index 9c129cc9..0dbe09a1 100644
--- a/src/browser/components/search.gts
+++ b/src/browser/components/search.gts
@@ -197,7 +197,9 @@ export class Search extends Component<SearchSignature> {
           <MagnifyingGlass />
           <span>Search docs</span>
           {{#if this.hotkey}}
-            <KeyCombo @keys={{this.hotkeyKeys}} @mac={{this.hotkeyMacKeys}} />
+            <span class='kolay__search__trigger__hint'>
+              <KeyCombo @keys={{this.hotkeyKeys}} @mac={{this.hotkeyMacKeys}} />
+            </span>
           {{/if}}
         </button>
       {{/if}}

From c714d99c63f2bc5bcb3144cf63b2aee63d058803 Mon Sep 17 00:00:00 2001
From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com>
Date: Wed, 26 Aug 2026 19:04:42 -0400
Subject: [PATCH 4/7] Align the palette's field, and stop the host ring from
 clipping

Three things were wrong inside the modal.

The site's `header div:first-child` rule reached into the `<dialog>`, because
`<Modal>` renders it where it is written. It laid the field out on the
baseline with a 1rem gap, so the icon sat above the input's centre. That rule
only ever meant the header's own nav group, so it takes a child combinator
now, and the field's rule is qualified by the dialog so no host descendant
rule can lay it out again.

The input carried the site's focus ring, which the dialog clipped: the field
runs the full width, out to a rounded corner and `overflow: hidden`. Focus
never leaves that input while the palette is open, so the ring was permanent
decoration rather than a signal. It is suppressed, specifically enough to
outrank a framework's own input focus styles.

The icon, each result, and the status line now share one left edge, held in
a single custom property rather than restated four times.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs-app/src/templates/application.gts |  4 +++-
 src/browser/components/search.css      | 25 ++++++++++++++++++++-----
 2 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/docs-app/src/templates/application.gts b/docs-app/src/templates/application.gts
index 5f6977ac..113b0fb6 100644
--- a/docs-app/src/templates/application.gts
+++ b/docs-app/src/templates/application.gts
@@ -154,7 +154,9 @@ export default Route(
         justify-content: space-between;
         gap: 1rem;
 
-        div:first-child {
+        /* the nav group, not every div under the header: <Search /> puts its
+           <dialog> here too, and a descendant rule reaches inside it */
+        > div:first-child {
           display: flex; gap: 1rem;
           align-items: baseline;
         }
diff --git a/src/browser/components/search.css b/src/browser/components/search.css
index 419c2056..9e0bdaa9 100644
--- a/src/browser/components/search.css
+++ b/src/browser/components/search.css
@@ -26,6 +26,8 @@
   --_border: var(--kolay-search-border, light-dark(#e3e5e9, #2b2f37));
   --_active: var(--kolay-search-active, light-dark(#f2f4f7, #23262d));
   --_accent: var(--kolay-search-accent, light-dark(#0b5fd0, #79b8ff));
+  /* the left edge every column lines up on: the icon, each result, the status */
+  --_inset: 1.15rem;
 
   width: min(92vw, var(--kolay-search-width, 40rem));
   max-height: min(70vh, 40rem);
@@ -63,12 +65,17 @@
   text-decoration: underline;
 }
 
-.kolay__search__field {
+/*
+ * Qualified by the dialog, not because the class needs it, but because the
+ * `<dialog>` sits wherever it was written -- often inside a header, whose own
+ * descendant rules would otherwise reach in and lay this row out.
+ */
+.kolay__search .kolay__search__field {
   display: flex;
   gap: 0.6rem;
   align-items: center;
   flex: 0 0 auto;
-  padding: 0.85rem 1rem;
+  padding: 0.85rem var(--_inset);
   border-block-end: 1px solid var(--_border);
   color: var(--_muted);
 }
@@ -94,8 +101,16 @@
   color: var(--_fg);
 }
 
-.kolay__search__input:focus-visible {
+/*
+ * No ring on the input. Focus never leaves it while the palette is open, so a
+ * ring is permanent decoration rather than a signal, and the dialog clips it:
+ * the field runs the full width, out to a rounded corner and `overflow:
+ * hidden`. Specific enough to outrank a framework's own input focus styles.
+ */
+.kolay__search input.kolay__search__input:is(:focus, :focus-visible) {
   outline: none;
+  border: none;
+  box-shadow: none;
 }
 
 .kolay__search__results {
@@ -108,7 +123,7 @@
 .kolay__search__result {
   display: block;
   position: relative;
-  padding: 0.6rem 0.75rem;
+  padding: 0.6rem calc(var(--_inset) - 0.4rem);
   border-radius: 0.5rem;
   color: inherit;
   text-decoration: none;
@@ -161,7 +176,7 @@
 .kolay__search__status {
   flex: 0 0 auto;
   margin: 0;
-  padding: 0.6rem 1rem;
+  padding: 0.6rem var(--_inset);
   border-block-start: 1px solid var(--_border);
   color: var(--_muted);
   font-size: 0.8rem;

From 3f0bfa577dfe7f04a6e3a88f4ac085136f943f11 Mon Sep 17 00:00:00 2001
From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com>
Date: Wed, 26 Aug 2026 19:21:55 -0400
Subject: [PATCH 5/7] Drop <Search />'s configuration arguments

The docstring said there was nothing to configure while the signature
exposed four knobs, each behind its own `?? DEFAULT` getter. The hotkey is
fixed at mod+k, and the rest are constants: how much to type before the index
is consulted, how many results to render, and the placeholder.

The two blocks stay. They replace markup rather than tune behaviour.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs/navigation/search.gjs.md     | 11 +---
 src/browser/components/search.gts | 94 +++++++------------------------
 2 files changed, 21 insertions(+), 84 deletions(-)

diff --git a/docs/navigation/search.gjs.md b/docs/navigation/search.gjs.md
index 8a186cc5..3ac2f46f 100644
--- a/docs/navigation/search.gjs.md
+++ b/docs/navigation/search.gjs.md
@@ -25,15 +25,6 @@ Put it in your application template, next to your nav. It renders a button; the
 
 Excerpts come from `stripFormatting`, and the query is marked inside them with `highlightSearch`. Both are documented under [`searcher`](/Runtime/utilities/search.md).
 
-## Arguments
-
-| argument       | default                                   | what it does                                                                        |
-| :------------- | :---------------------------------------- | :---------------------------------------------------------------------------------- |
-| `@hotkey`      | `"mod+k"`                                 | Opens the palette from anywhere. `mod` is <kbd>⌘</kbd> on macOS, <kbd>Ctrl</kbd> elsewhere. Pass `""` to install no listener. |
-| `@minLength`   | `3`                                       | How much the reader types before the index is consulted.                            |
-| `@limit`       | `20`                                      | How many results to render.                                                          |
-| `@placeholder` | `"Search titles, headings, and prose…"`   | The input's placeholder.                                                             |
-
 ## Your own trigger
 
 The `:trigger` block is yielded `open`, and the modifier that returns focus to your button when the palette closes.
@@ -53,7 +44,7 @@ import { Search } from 'kolay/components';
 </template>
 ```
 
-Leave the block empty to render no trigger at all, and open the palette with the hotkey alone.
+Leave the block empty to render no trigger at all. <kbd>⌘</kbd><kbd>K</kbd> still opens the palette.
 
 ## Your own result
 
diff --git a/src/browser/components/search.gts b/src/browser/components/search.gts
index 0dbe09a1..ee566b27 100644
--- a/src/browser/components/search.gts
+++ b/src/browser/components/search.gts
@@ -17,20 +17,16 @@ import type { SearchResult } from '../../types.ts';
 import type { TOC } from '@ember/component/template-only';
 import type { ModifierLike } from '@glint/template';
 
-const DEFAULT_HOTKEY = 'mod+k';
-const DEFAULT_MIN_LENGTH = 3;
-const DEFAULT_LIMIT = 20;
-
-/**
- * The keys of a hotkey, as `<KeyCombo>` wants them. `mod` is a different key
- * on macOS than everywhere else, so it is spelled twice.
- */
-function keysFor(hotkey: string, mod: string) {
-  return hotkey
-    .split('+')
-    .map((key) => key.trim())
-    .map((key) => (key.toLowerCase() === 'mod' ? mod : key.toUpperCase()));
-}
+const HOTKEY = 'mod+k';
+/* the same combination, spelled for each platform's own key */
+const KEYS = ['Ctrl', 'K'];
+const MAC_KEYS = ['⌘', 'K'];
+/* one or two characters match most of a docs site, which is the same as
+   matching none of it */
+const MIN_LENGTH = 3;
+/* ranking puts the answer near the top; rendering every page renders noise */
+const LIMIT = 20;
+const PLACEHOLDER = 'Search titles, headings, and prose…';
 
 const MagnifyingGlass: TOC<{ Element: SVGElement }> = <template>
   <svg
@@ -46,34 +42,6 @@ const MagnifyingGlass: TOC<{ Element: SVGElement }> = <template>
 </template>;
 
 export interface SearchSignature {
-  Args: {
-    /**
-     * The key combination that opens the palette from anywhere on the page.
-     *
-     * Defaults to `"mod+k"` -- <kbd>⌘</kbd><kbd>K</kbd> on macOS and
-     * <kbd>Ctrl</kbd><kbd>K</kbd> everywhere else. Pass an empty string to
-     * install no global listener at all.
-     */
-    hotkey?: string;
-    /**
-     * How much the reader has to type before the index is consulted.
-     *
-     * Defaults to 3. One or two characters match most of a docs site, which
-     * is the same as matching none of it.
-     */
-    minLength?: number;
-    /**
-     * How many results to render.
-     *
-     * Defaults to 20. Ranking already puts the answer near the top, and a
-     * palette that renders every page of a large site renders mostly noise.
-     */
-    limit?: number;
-    /**
-     * The input's placeholder.
-     */
-    placeholder?: string;
-  };
   Blocks: {
     /**
      * Replaces the default "Search docs" button. Yielded `open`, and the
@@ -111,26 +79,6 @@ export interface SearchSignature {
 export class Search extends Component<SearchSignature> {
   @tracked query = '';
 
-  get hotkey() {
-    return this.args.hotkey ?? DEFAULT_HOTKEY;
-  }
-
-  get minLength() {
-    return this.args.minLength ?? DEFAULT_MIN_LENGTH;
-  }
-
-  get limit() {
-    return this.args.limit ?? DEFAULT_LIMIT;
-  }
-
-  get hotkeyKeys() {
-    return keysFor(this.hotkey, 'Ctrl');
-  }
-
-  get hotkeyMacKeys() {
-    return keysFor(this.hotkey, '⌘');
-  }
-
   get trimmed() {
     return this.query.trim();
   }
@@ -142,7 +90,7 @@ export class Search extends Component<SearchSignature> {
    */
   @cached
   get search(): Promise<SearchResult[]> {
-    if (this.trimmed.length < this.minLength) return Promise.resolve([]);
+    if (this.trimmed.length < MIN_LENGTH) return Promise.resolve([]);
 
     return searcher(this).search(this.query);
   }
@@ -156,7 +104,7 @@ export class Search extends Component<SearchSignature> {
   }
 
   get results() {
-    return this.state.resolved?.slice(0, this.limit) ?? [];
+    return this.state.resolved?.slice(0, LIMIT) ?? [];
   }
 
   /**
@@ -166,13 +114,13 @@ export class Search extends Component<SearchSignature> {
   get status() {
     if (!this.trimmed) return 'Search every guide, reference page, heading, and paragraph.';
 
-    if (this.trimmed.length < this.minLength) {
-      return `Type at least ${this.minLength} characters.`;
+    if (this.trimmed.length < MIN_LENGTH) {
+      return `Type at least ${MIN_LENGTH} characters.`;
     }
 
     if (this.state.isLoading) return 'Searching…';
     if (this.total === 0) return `No results for “${this.trimmed}”.`;
-    if (this.total > this.limit) return `Showing ${this.limit} of ${this.total} results.`;
+    if (this.total > LIMIT) return `Showing ${LIMIT} of ${this.total} results.`;
 
     return this.total === 1 ? '1 result.' : `${this.total} results.`;
   }
@@ -196,17 +144,15 @@ export class Search extends Component<SearchSignature> {
         >
           <MagnifyingGlass />
           <span>Search docs</span>
-          {{#if this.hotkey}}
-            <span class='kolay__search__trigger__hint'>
-              <KeyCombo @keys={{this.hotkeyKeys}} @mac={{this.hotkeyMacKeys}} />
-            </span>
-          {{/if}}
+          <span class='kolay__search__trigger__hint'>
+            <KeyCombo @keys={{KEYS}} @mac={{MAC_KEYS}} />
+          </span>
         </button>
       {{/if}}
 
       <m.Dialog class='kolay__search'>
         <CommandPalette
-          @hotkey={{this.hotkey}}
+          @hotkey={{HOTKEY}}
           @onOpen={{m.open}}
           @onSelect={{m.close}}
           @onQueryChange={{this.setQuery}}
@@ -217,7 +163,7 @@ export class Search extends Component<SearchSignature> {
             <c.Input
               class='kolay__search__input'
               aria-label='Search docs'
-              placeholder={{if @placeholder @placeholder 'Search titles, headings, and prose…'}}
+              placeholder={{PLACEHOLDER}}
             />
           </div>
 

From 8d1b2206090bf4e90c8b2e7222ef1aada98edfbb Mon Sep 17 00:00:00 2001
From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com>
Date: Wed, 26 Aug 2026 19:46:52 -0400
Subject: [PATCH 6/7] Say how to close the palette, and give the pointer a way
 to clear it

The footer carries both: what the listbox is doing on one side, and "press
Esc to close" on the other, the way nvp.ui's menu says it.

Clearing the query was a keyboard-only move. A button appears beside the
input once there is something to clear, and hands the caret back so the
reader can carry on typing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 src/browser/components/search.css             | 38 ++++++++++++++++--
 src/browser/components/search.gts             | 40 ++++++++++++++++++-
 .../tests/search-component-test.ts            | 24 +++++++++++
 3 files changed, 97 insertions(+), 5 deletions(-)

diff --git a/src/browser/components/search.css b/src/browser/components/search.css
index 9e0bdaa9..73af4f9d 100644
--- a/src/browser/components/search.css
+++ b/src/browser/components/search.css
@@ -173,15 +173,46 @@
   -webkit-line-clamp: 2;
 }
 
-.kolay__search__status {
+.kolay__search__footer {
+  display: flex;
+  gap: 1rem;
+  align-items: baseline;
+  justify-content: space-between;
   flex: 0 0 auto;
-  margin: 0;
   padding: 0.6rem var(--_inset);
   border-block-start: 1px solid var(--_border);
   color: var(--_muted);
   font-size: 0.8rem;
 }
 
+.kolay__search__status,
+.kolay__search__hint {
+  margin: 0;
+}
+
+/* the way out, said once, quietly */
+.kolay__search__hint {
+  flex: 0 0 auto;
+  font-size: 0.9em;
+}
+
+/* the pointer's way to clear the query; the keyboard already has one */
+.kolay__search__clear {
+  display: inline-flex;
+  flex: 0 0 auto;
+  padding: 0.2rem;
+  border: none;
+  border-radius: 0.3rem;
+  background: none;
+  color: inherit;
+  cursor: pointer;
+}
+
+.kolay__search__clear:hover {
+  background: var(--_active);
+  color: var(--_fg);
+}
+
 .kolay__search__trigger {
   display: inline-flex;
   gap: 0.5rem;
@@ -213,7 +244,8 @@
  * too loud for a hint on a button: it doubles the button's height and reads
  * as the most important thing in the header.
  */
-.kolay__search__trigger kbd {
+.kolay__search__trigger kbd,
+.kolay__search kbd {
   display: inline-block;
   min-width: 1.5em;
   padding: 0.1em 0.4em;
diff --git a/src/browser/components/search.gts b/src/browser/components/search.gts
index ee566b27..ddc5fcc3 100644
--- a/src/browser/components/search.gts
+++ b/src/browser/components/search.gts
@@ -2,11 +2,12 @@ import './search.css';
 
 import Component from '@glimmer/component';
 import { cached, tracked } from '@glimmer/tracking';
+import { fn } from '@ember/helper';
 import { on } from '@ember/modifier';
 
 import { CommandPalette } from 'ember-primitives/components/command-palette';
 import { Modal } from 'ember-primitives/components/dialog';
-import { KeyCombo } from 'ember-primitives/components/keys';
+import { Key, KeyCombo } from 'ember-primitives/components/keys';
 import { getPromiseState } from 'reactiveweb/get-promise-state';
 
 import { searcher } from '../services/search.ts';
@@ -41,6 +42,19 @@ const MagnifyingGlass: TOC<{ Element: SVGElement }> = <template>
   ><circle cx='11' cy='11' r='6.5' /><path d='m16 16 5 5' /></svg>
 </template>;
 
+const Cross: TOC<{ Element: SVGElement }> = <template>
+  <svg
+    class='kolay__search__icon'
+    aria-hidden='true'
+    viewBox='0 0 24 24'
+    fill='none'
+    stroke='currentColor'
+    stroke-width='2'
+    stroke-linecap='round'
+    ...attributes
+  ><path d='m6 6 12 12M18 6 6 18' /></svg>
+</template>;
+
 export interface SearchSignature {
   Blocks: {
     /**
@@ -131,6 +145,15 @@ export class Search extends Component<SearchSignature> {
 
   excerpt = (result: SearchResult) => stripFormatting(result.text, result.excerptRange);
 
+  /** Clearing is for carrying on typing, so the caret goes back to the input. */
+  clear = (setQuery: (query: string) => void, event: MouseEvent) => {
+    setQuery('');
+
+    const button = event.currentTarget as HTMLElement;
+
+    button.parentElement?.querySelector('input')?.focus();
+  };
+
   <template>
     <Modal as |m|>
       {{#if (has-block 'trigger')}}
@@ -165,6 +188,14 @@ export class Search extends Component<SearchSignature> {
               aria-label='Search docs'
               placeholder={{PLACEHOLDER}}
             />
+            {{#if c.query}}
+              <button
+                type='button'
+                class='kolay__search__clear'
+                aria-label='Clear search'
+                {{on 'click' (fn this.clear c.setQuery)}}
+              ><Cross /></button>
+            {{/if}}
           </div>
 
           <c.List class='kolay__search__results' as |l|>
@@ -184,7 +215,12 @@ export class Search extends Component<SearchSignature> {
             {{/each}}
           </c.List>
 
-          <p class='kolay__search__status' role='status'>{{this.status}}</p>
+          <div class='kolay__search__footer'>
+            <p class='kolay__search__status' role='status'>{{this.status}}</p>
+            <p class='kolay__search__hint'>press
+              <Key>Esc</Key>
+              to close</p>
+          </div>
         </CommandPalette>
       </m.Dialog>
     </Modal>
diff --git a/test-apps/markdown-only/tests/search-component-test.ts b/test-apps/markdown-only/tests/search-component-test.ts
index 63bd7f3e..28fb529c 100644
--- a/test-apps/markdown-only/tests/search-component-test.ts
+++ b/test-apps/markdown-only/tests/search-component-test.ts
@@ -77,6 +77,30 @@ module("<Search />", function (hooks) {
     assert.dom(".kolay__search__status").hasText(/No results/);
   });
 
+  test("the palette says how to leave it", async function (assert) {
+    await visit(START);
+    await click(".kolay__search__trigger");
+
+    assert.dom(".kolay__search__hint").hasText("press Esc to close");
+  });
+
+  test("the clear button empties the query and gives the caret back", async function (assert) {
+    await visit(START);
+    await click(".kolay__search__trigger");
+
+    assert.dom(".kolay__search__clear").doesNotExist();
+
+    await fillIn(".kolay__search__input", "resources");
+    await waitFor(".kolay__search__result", { timeout: 5000 });
+
+    await click(".kolay__search__clear");
+
+    assert.dom(".kolay__search__input").hasValue("");
+    assert.dom(".kolay__search__input").isFocused();
+    assert.dom(".kolay__search__result").doesNotExist();
+    assert.dom(".kolay__search__clear").doesNotExist();
+  });
+
   test("the hotkey opens it from anywhere", async function (assert) {
     await visit(START);
 

From fbec15d6b87ff0ee243d11070ae444c5d61cb618 Mon Sep 17 00:00:00 2001
From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com>
Date: Thu, 27 Aug 2026 11:59:21 -0400
Subject: [PATCH 7/7] Give the pointer a way out, and collapse the empty
 palette

There was no way to close it without a keyboard. The footer's hint is a
button now, reading "Close" beside the key it names, and the dialog carries
`closedby="any"`, so a click outside dismisses it the way the platform does.

The palette was 665px tall with nothing in it. A modal `<dialog>` is anchored
top and bottom, so an auto height fills the viewport rather than the content;
releasing the bottom anchor lets it be as tall as its results and no taller.
The empty state is 122px now. The results box collapses with it, rather than
holding a strip of padding open.

Frameworks give buttons a bottom margin. None of these want one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs/navigation/search.gjs.md                 |  2 +-
 src/browser/components/search.css             | 37 +++++++++++++++++--
 src/browser/components/search.gts             | 13 +++++--
 .../tests/search-component-test.ts            | 28 +++++++++++++-
 4 files changed, 69 insertions(+), 11 deletions(-)

diff --git a/docs/navigation/search.gjs.md b/docs/navigation/search.gjs.md
index 3ac2f46f..7e0f45cb 100644
--- a/docs/navigation/search.gjs.md
+++ b/docs/navigation/search.gjs.md
@@ -21,7 +21,7 @@ Put it in your application template, next to your nav. It renders a button; the
 - The `<dialog>` handles the layer, the focus trap, and returning focus to whatever opened it.
 - `aria-activedescendant` handles the keyboard, so <kbd>ArrowUp</kbd> and <kbd>ArrowDown</kbd> move the selection while the caret stays where the reader is typing.
 - <kbd>Enter</kbd> clicks the active result, which is a real link, so the router navigates and <kbd>⌘</kbd>-click still opens a new tab.
-- <kbd>Esc</kbd>, and a click outside, close it.
+- <kbd>Esc</kbd>, a click outside, and the footer's Close button all close it.
 
 Excerpts come from `stripFormatting`, and the query is marked inside them with `highlightSearch`. Both are documented under [`searcher`](/Runtime/utilities/search.md).
 
diff --git a/src/browser/components/search.css b/src/browser/components/search.css
index 73af4f9d..5c8974c4 100644
--- a/src/browser/components/search.css
+++ b/src/browser/components/search.css
@@ -30,6 +30,13 @@
   --_inset: 1.15rem;
 
   width: min(92vw, var(--kolay-search-width, 40rem));
+  /*
+   * A modal `<dialog>` is anchored top and bottom, so an auto height fills the
+   * viewport rather than the content. Releasing the bottom anchor lets the
+   * palette be as tall as its results and no taller, with the margin holding
+   * it below the top of the page.
+   */
+  inset-block-end: auto;
   max-height: min(70vh, 40rem);
   margin-block-start: 10vh;
   margin-inline: auto;
@@ -119,6 +126,11 @@
   padding: 0.4rem;
 }
 
+/* nothing found, nothing to show: no strip of padding pretending otherwise */
+.kolay__search__results[data-has-results="false"] {
+  padding: 0;
+}
+
 /* the result is the link: one target, and the whole card is it */
 .kolay__search__result {
   display: block;
@@ -185,21 +197,37 @@
   font-size: 0.8rem;
 }
 
-.kolay__search__status,
-.kolay__search__hint {
+.kolay__search__status {
   margin: 0;
 }
 
-/* the way out, said once, quietly */
-.kolay__search__hint {
+/* the way out, for the pointer as well as the key it names */
+.kolay__search__close {
+  display: inline-flex;
+  gap: 0.4em;
+  align-items: center;
   flex: 0 0 auto;
+  margin: 0;
+  padding: 0.15rem 0.4rem;
+  border: none;
+  border-radius: 0.3rem;
+  background: none;
+  color: inherit;
+  font: inherit;
   font-size: 0.9em;
+  cursor: pointer;
+}
+
+.kolay__search__close:hover {
+  background: var(--_active);
+  color: var(--_fg);
 }
 
 /* the pointer's way to clear the query; the keyboard already has one */
 .kolay__search__clear {
   display: inline-flex;
   flex: 0 0 auto;
+  margin: 0;
   padding: 0.2rem;
   border: none;
   border-radius: 0.3rem;
@@ -217,6 +245,7 @@
   display: inline-flex;
   gap: 0.5rem;
   align-items: center;
+  margin: 0;
   padding: 0.4rem 0.5rem 0.4rem 0.7rem;
   border: 1px solid var(--kolay-search-border, light-dark(#e3e5e9, #2b2f37));
   border-radius: 0.5rem;
diff --git a/src/browser/components/search.gts b/src/browser/components/search.gts
index ddc5fcc3..bca7f0e3 100644
--- a/src/browser/components/search.gts
+++ b/src/browser/components/search.gts
@@ -173,7 +173,7 @@ export class Search extends Component<SearchSignature> {
         </button>
       {{/if}}
 
-      <m.Dialog class='kolay__search'>
+      <m.Dialog class='kolay__search' closedby='any'>
         <CommandPalette
           @hotkey={{HOTKEY}}
           @onOpen={{m.open}}
@@ -198,7 +198,11 @@ export class Search extends Component<SearchSignature> {
             {{/if}}
           </div>
 
-          <c.List class='kolay__search__results' as |l|>
+          <c.List
+            class='kolay__search__results'
+            data-has-results='{{if this.results.length "true" "false"}}'
+            as |l|
+          >
             {{#each this.results key='path' as |result|}}
               <l.LinkItem class='kolay__search__result' @href={{result.path}}>
                 {{#if (has-block 'result')}}
@@ -217,9 +221,10 @@ export class Search extends Component<SearchSignature> {
 
           <div class='kolay__search__footer'>
             <p class='kolay__search__status' role='status'>{{this.status}}</p>
-            <p class='kolay__search__hint'>press
+            <button type='button' class='kolay__search__close' {{on 'click' m.close}}>
+              Close
               <Key>Esc</Key>
-              to close</p>
+            </button>
           </div>
         </CommandPalette>
       </m.Dialog>
diff --git a/test-apps/markdown-only/tests/search-component-test.ts b/test-apps/markdown-only/tests/search-component-test.ts
index 28fb529c..2f0bbfab 100644
--- a/test-apps/markdown-only/tests/search-component-test.ts
+++ b/test-apps/markdown-only/tests/search-component-test.ts
@@ -77,11 +77,35 @@ module("<Search />", function (hooks) {
     assert.dom(".kolay__search__status").hasText(/No results/);
   });
 
-  test("the palette says how to leave it", async function (assert) {
+  test("the pointer can close it, and the button names the key too", async function (assert) {
     await visit(START);
     await click(".kolay__search__trigger");
 
-    assert.dom(".kolay__search__hint").hasText("press Esc to close");
+    assert.dom(".kolay__search__close").hasText("Close Esc");
+    // a click outside is the platform's, off the same attribute
+    assert.dom("dialog.kolay__search").hasAttribute("closedby", "any");
+
+    await click(".kolay__search__close");
+
+    assert.dom("dialog.kolay__search").doesNotHaveAttribute("open");
+    assert.dom(".kolay__search__trigger").isFocused();
+  });
+
+  test("the results collapse when there are none", async function (assert) {
+    await visit(START);
+    await click(".kolay__search__trigger");
+
+    assert.dom(".kolay__search__results").hasAttribute("data-has-results", "false");
+
+    const results = find(".kolay__search__results") as HTMLElement;
+
+    assert.strictEqual(results.getBoundingClientRect().height, 0, "no empty box to scroll");
+
+    await fillIn(".kolay__search__input", "resources");
+    await waitFor(".kolay__search__result", { timeout: 5000 });
+
+    assert.dom(".kolay__search__results").hasAttribute("data-has-results", "true");
+    assert.ok(results.getBoundingClientRect().height > 0, "the results have room");
   });
 
   test("the clear button empties the query and gives the caret back", async function (assert) {