@jasonshimmy/vite-plugin-cer-app 0.22.0 → 0.23.1

package/CHANGELOG.md

@@ -1,6 +1,14 @@
 # Changelog
 
 All notable changes to this project will be documented in this file.
+## [v0.23.1] - 2026-04-17
+
+- fix: fix useContentSearch loading state, debounce, and automatic retry on fetch failure (4d0207a)
+
+## [v0.23.0] - 2026-04-17
+
+- feat: enhance useContentSearch with loading state and update related tests (d1cee0e)
+
 ## [v0.22.0] - 2026-04-16
 
 - feat: add customColors support for jitCss configuration and implement related tests (b8061ef)

package/commits.txt

@@ -1 +1 @@
-- feat: add customColors support for jitCss configuration and implement related tests (b8061ef)
+- fix: fix useContentSearch loading state, debounce, and automatic retry on fetch failure (4d0207a)

package/dist/runtime/composables/use-content-search.d.ts

@@ -5,6 +5,9 @@ import type { ContentSearchResult } from '../../types/content.js';
  * Returns the same Promise on repeated calls — the index is built at most once
  * per session regardless of how many search components are mounted.
  *
+ * If the fetch fails the singleton is cleared so the next search attempt
+ * retries automatically (no page reload required after a transient error).
+ *
  * @internal Exported for unit testing only.
  */
 export declare function loadIndex(): Promise<unknown>;
@@ -13,6 +16,8 @@ export declare function resetIndexSingleton(): void;
 export interface UseContentSearchReturn {
     query: ReactiveState<string>;
     results: ReactiveState<ContentSearchResult[]>;
+    /** `true` from the moment the user starts typing until results (or an error) arrive. `false` when the query is empty or the search is complete. */
+    loading: ReactiveState<boolean>;
 }
 /**
  * Full-text content search composable.
@@ -21,8 +26,10 @@ export interface UseContentSearchReturn {
  * `/_content/search-index.json`. Both MiniSearch and the index are loaded via
  * dynamic import — neither is in the app bundle.
  *
- * Searches `title` and `description` fields. Results are empty until at least
- * 2 characters are entered.
+ * Searches `title` and `description` fields. Input is debounced (200 ms) so
+ * the index is not queried on every keystroke. `loading` becomes `true` as soon
+ * as the user starts typing and returns to `false` once results arrive. Results
+ * are empty when the query is empty.
  *
  * **SSR note**: search is always client-side. In SSR mode the component renders
  * with empty results and hydrates on mount.
@@ -30,10 +37,11 @@ export interface UseContentSearchReturn {
  * @example
  * ```ts
  * component('site-search', () => {
- *   const { query, results } = useContentSearch()
+ *   const { query, results, loading } = useContentSearch()
  *
  *   return html`
  *     <input type="search" :model="${query}" placeholder="Search…" />
+ *     ${loading.value ? html`<p>Searching…</p>` : ''}
  *     ${when(results.value.length > 0, () => html`
  *       <ul>
  *         ${each(results.value, r => html`

package/dist/runtime/composables/use-content-search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-content-search.d.ts","sourceRoot":"","sources":["../../../src/runtime/composables/use-content-search.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sCAAsC,CAAA;AACzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AASjE;;;;;;GAMG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,CAiBlD;AAED,uEAAuE;AACvE,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAID,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC5B,OAAO,EAAE,aAAa,CAAC,mBAAmB,EAAE,CAAC,CAAA;CAC9C;AAmCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,gBAAgB,IAAI,sBAAsB,CAEzD"}
+{"version":3,"file":"use-content-search.d.ts","sourceRoot":"","sources":["../../../src/runtime/composables/use-content-search.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sCAAsC,CAAA;AACzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AASjE;;;;;;;;;GASG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,CAuB5C;AAED,uEAAuE;AACvE,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AA+BD,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC5B,OAAO,EAAE,aAAa,CAAC,mBAAmB,EAAE,CAAC,CAAA;IAC7C,mJAAmJ;IACnJ,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;CAChC;AA4ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,gBAAgB,IAAI,sBAAsB,CAEzD"}

package/dist/runtime/composables/use-content-search.js

@@ -1,4 +1,4 @@
-import { createComposable, ref, useOnConnected, watch, } from '@jasonshimmy/custom-elements-runtime';
+import { createComposable, getCurrentComponentContext, ref, useOnConnected, useOnDisconnected, watch, } from '@jasonshimmy/custom-elements-runtime';
 import { contentSearchIndexUrl } from '../content/client.js';
 // ─── Module-level singleton ───────────────────────────────────────────────────
 // The MiniSearch instance is built lazily on first search from the manifest.
@@ -9,12 +9,15 @@ let _indexPromise = null;
  * Returns the same Promise on repeated calls — the index is built at most once
  * per session regardless of how many search components are mounted.
  *
+ * If the fetch fails the singleton is cleared so the next search attempt
+ * retries automatically (no page reload required after a transient error).
+ *
  * @internal Exported for unit testing only.
  */
-export async function loadIndex() {
+export function loadIndex() {
     if (_indexPromise)
         return _indexPromise;
-    _indexPromise = (async () => {
+    const attempt = (async () => {
         const [{ default: MiniSearch }, raw] = await Promise.all([
             import('minisearch'),
             fetch(contentSearchIndexUrl()).then((r) => {
@@ -29,40 +32,99 @@ export async function loadIndex() {
             idField: '_path',
         });
     })();
-    return _indexPromise;
+    _indexPromise = attempt;
+    // Clear the singleton on failure so the next call retries the fetch.
+    // The === guard ensures a newer concurrent attempt is not accidentally cleared.
+    attempt.catch(() => {
+        if (_indexPromise === attempt)
+            _indexPromise = null;
+    });
+    return attempt;
 }
 /** Resets the module-level singleton. Used in tests only. @internal */
 export function resetIndexSingleton() {
     _indexPromise = null;
 }
+const _STATE_KEY = '_cerSearchDebounce';
+function getDebounceState(ctx) {
+    if (!Object.prototype.hasOwnProperty.call(ctx, _STATE_KEY)) {
+        Object.defineProperty(ctx, _STATE_KEY, {
+            value: { seq: 0, timer: null },
+            writable: false, // object ref is fixed; its properties are still mutable
+            enumerable: false, // invisible to the reactive proxy set-trap
+            configurable: false,
+        });
+    }
+    return ctx[_STATE_KEY];
+}
 const _factory = createComposable(() => {
     const query = ref('');
     const results = ref([]);
-    // Pre-warm index on mount
+    const loading = ref(false);
+    // Debounce state lives on the component context, not in local render-body variables.
+    // Local variables are re-created on every re-render; the context object is stable
+    // for the lifetime of the element.  Storing state here lets the render-body
+    // watch() (see below) pick up the same timer and sequence counter across re-renders
+    // without the watcher accumulation that occurs when watch() is placed inside
+    // useOnConnected() (which runs once per mount but is not registered for cleanup
+    // by the reactive system, leaking watchers on every disconnect + reconnect cycle).
+    const state = getDebounceState(getCurrentComponentContext());
+    // Pre-warm the index on first mount so the first real search is faster.
     useOnConnected(() => {
         loadIndex().catch(() => { });
     });
-    // Monotonic counter to discard stale async results
-    let _seq = 0;
-    watch(query, async (q) => {
-        const seq = ++_seq;
-        if (!q || q.length < 2) {
-            results.value = [];
-            return;
+    // Cancel any in-flight debounce on unmount so stale async work doesn't land
+    // after the component is gone.
+    useOnDisconnected(() => {
+        if (state.timer !== null) {
+            clearTimeout(state.timer);
+            state.timer = null;
         }
-        try {
-            const index = await loadIndex();
-            if (seq !== _seq)
-                return; // stale — a newer query is in flight
-            results.value = index.search(q, { prefix: true });
+        state.seq++; // discard any in-flight async search
+        loading.value = false;
+    });
+    // watch() is in the render body so the reactive system registers it under the
+    // current component and tears it down automatically on re-render and disconnect.
+    // The mutable state (seq / timer) lives on the context (above) and persists
+    // across re-renders — new watcher instances see the same timer and counter,
+    // which is what makes debounce cancellation correct even after a re-render.
+    watch(query, (q) => {
+        if (state.timer !== null) {
+            clearTimeout(state.timer);
+            state.timer = null;
         }
-        catch {
-            if (seq !== _seq)
-                return;
+        if (!q) {
+            // Increment seq so any in-flight async search is discarded when it resolves
+            state.seq++;
+            loading.value = false;
             results.value = [];
+            return;
         }
+        // Signal loading immediately so the UI can respond before the debounce fires
+        loading.value = true;
+        state.timer = setTimeout(async () => {
+            state.timer = null;
+            const seq = ++state.seq;
+            try {
+                const index = await loadIndex();
+                if (seq !== state.seq)
+                    return; // stale — a newer query is in flight
+                results.value = index.search(q, { prefix: true });
+            }
+            catch {
+                if (seq !== state.seq)
+                    return;
+                results.value = [];
+            }
+            finally {
+                // Only clear loading for the most recent search; a newer in-flight search
+                // keeps loading=true until it settles.
+                if (seq === state.seq)
+                    loading.value = false;
+            }
+        }, 200);
     });
-    return { query, results };
+    return { query, results, loading };
 });
 /**
  * Full-text content search composable.
@@ -71,8 +133,10 @@ const _factory = createComposable(() => {
  * `/_content/search-index.json`. Both MiniSearch and the index are loaded via
  * dynamic import — neither is in the app bundle.
  *
- * Searches `title` and `description` fields. Results are empty until at least
- * 2 characters are entered.
+ * Searches `title` and `description` fields. Input is debounced (200 ms) so
+ * the index is not queried on every keystroke. `loading` becomes `true` as soon
+ * as the user starts typing and returns to `false` once results arrive. Results
+ * are empty when the query is empty.
  *
  * **SSR note**: search is always client-side. In SSR mode the component renders
  * with empty results and hydrates on mount.
@@ -80,10 +144,11 @@ const _factory = createComposable(() => {
  * @example
  * ```ts
  * component('site-search', () => {
- *   const { query, results } = useContentSearch()
+ *   const { query, results, loading } = useContentSearch()
  *
  *   return html`
  *     <input type="search" :model="${query}" placeholder="Search…" />
+ *     ${loading.value ? html`<p>Searching…</p>` : ''}
  *     ${when(results.value.length > 0, () => html`
  *       <ul>
  *         ${each(results.value, r => html`

package/dist/runtime/composables/use-content-search.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-content-search.js","sourceRoot":"","sources":["../../../src/runtime/composables/use-content-search.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,GAAG,EACH,cAAc,EACd,KAAK,GACN,MAAM,sCAAsC,CAAA;AAG7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAE5D,iFAAiF;AAEjF,6EAA6E;AAC7E,iFAAiF;AACjF,IAAI,aAAa,GAA4B,IAAI,CAAA;AAEjD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS;IAC7B,IAAI,aAAa;QAAE,OAAO,aAAa,CAAA;IACvC,aAAa,GAAG,CAAC,KAAK,IAAI,EAAE;QAC1B,MAAM,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,GAAG,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACvD,MAAM,CAAC,YAAY,CAAC;YACpB,KAAK,CAAC,qBAAqB,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;gBACxC,IAAI,CAAC,CAAC,CAAC,EAAE;oBAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAA;gBACvE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAA;YACjB,CAAC,CAAC;SACH,CAAC,CAAA;QACF,OAAO,UAAU,CAAC,QAAQ,CAAC,GAAG,EAAE;YAC9B,MAAM,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC;YAChC,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC;YAC9C,OAAO,EAAE,OAAO;SACjB,CAAC,CAAA;IACJ,CAAC,CAAC,EAAE,CAAA;IACJ,OAAO,aAAa,CAAA;AACtB,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,mBAAmB;IACjC,aAAa,GAAG,IAAI,CAAA;AACtB,CAAC;AASD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,GAA2B,EAAE;IAC7D,MAAM,KAAK,GAAG,GAAG,CAAC,EAAE,CAAC,CAAA;IACrB,MAAM,OAAO,GAAG,GAAG,CAAwB,EAAE,CAAC,CAAA;IAE9C,0BAA0B;IAC1B,cAAc,CAAC,GAAG,EAAE;QAClB,SAAS,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAuC,CAAC,CAAC,CAAA;IAClE,CAAC,CAAC,CAAA;IAEF,mDAAmD;IACnD,IAAI,IAAI,GAAG,CAAC,CAAA;IAEZ,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,CAAS,EAAE,EAAE;QAC/B,MAAM,GAAG,GAAG,EAAE,IAAI,CAAA;QAElB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,KAAK,GAAG,EAAE,CAAA;YAClB,OAAM;QACR,CAAC;QAED,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,SAAS,EAA+E,CAAA;YAC5G,IAAI,GAAG,KAAK,IAAI;gBAAE,OAAM,CAAC,qCAAqC;YAC9D,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAA0B,CAAA;QAC5E,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,GAAG,KAAK,IAAI;gBAAE,OAAM;YACxB,OAAO,CAAC,KAAK,GAAG,EAAE,CAAA;QACpB,CAAC;IACH,CAAC,CAAC,CAAA;IAEF,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAA;AAC3B,CAAC,CAAC,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,QAAQ,EAAE,CAAA;AACnB,CAAC"}
+{"version":3,"file":"use-content-search.js","sourceRoot":"","sources":["../../../src/runtime/composables/use-content-search.ts"],"names":[],"mappings":"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"}

package/docs/composables.md

@@ -868,16 +868,17 @@ import { queryContent } from '@jasonshimmy/vite-plugin-cer-app/composables'
 
 ### `useContentSearch()`
 
-Reactive full-text search over the content layer. Loads the MiniSearch index lazily on first use. Returns `query` and `results` refs that update reactively as the user types.
+Reactive full-text search over the content layer. Loads the MiniSearch index lazily on first use. Returns `query`, `results`, and `loading` refs that update reactively as the user types.
 
 Requires `content: {}` in `cer.config.ts`. See [content.md](./content.md) for full documentation.
 
 ```ts
 component('page-search', () => {
-  const { query, results } = useContentSearch()
+  const { query, results, loading } = useContentSearch()
 
   return html`
     <input type="search" :model="${query}" placeholder="Search…" />
+    ${loading.value ? html`<p>Searching…</p>` : ''}
     <ul>
       ${each(results.value, r => html`
         <li><a :href="${r._path}">${r.title}</a></li>
@@ -893,10 +894,11 @@ component('page-search', () => {
 interface UseContentSearchReturn {
   query: Ref<string>                   // bind with :model
   results: Ref<ContentSearchResult[]>  // reactive search results
+  loading: Ref<boolean>                // true while debounce is pending or search is in flight
 }
 ```
 
-Search activates when `query.value.length >= 2`. MiniSearch is loaded once and cached for the lifetime of the page. Searched fields are `title` and `description`.
+Search is debounced (200 ms) so the index is not queried on every keystroke. `loading` is set to `true` as soon as the user starts typing and returns to `false` once results arrive or the query is cleared. An empty query clears results immediately and cancels any in-flight search. MiniSearch is loaded once and cached for the lifetime of the page. Searched fields are `title` and `description`.
 
 If you need it outside auto-imported directories:
 

package/docs/content.md

@@ -473,18 +473,19 @@ Important behavior notes:
 
 **Auto-imported** in pages, layouts, and components.
 
-Returns reactive `query` and `results` refs. The MiniSearch index is loaded once on the client (lazily, the first time the composable is used). Search is debounce-free — results update synchronously on each keypress, but the initial index fetch is async.
+Returns reactive `query`, `results`, and `loading` refs. The MiniSearch index is loaded lazily the first time the component mounts (pre-warmed via `useOnConnected`) and cached for the lifetime of the session. Input is debounced (200 ms) so the index is not queried on every keystroke.
 
 ```ts
-const { query, results } = useContentSearch()
+const { query, results, loading } = useContentSearch()
 ```
 
 ### Return value
 
 ```ts
 interface UseContentSearchReturn {
-  query: Ref<string>               // bind to an <input> value
+  query: Ref<string>                   // bind with :model or @input
   results: Ref<ContentSearchResult[]>  // reactive search results
+  loading: Ref<boolean>                // true from first keystroke until results arrive
 }
 ```
 
@@ -492,10 +493,11 @@ interface UseContentSearchReturn {
 
 ```ts
 component('page-search', () => {
-  const { query, results } = useContentSearch()
+  const { query, results, loading } = useContentSearch()
 
   return html`
     <input type="search" :model="${query}" placeholder="Search…" />
+    ${loading.value ? html`<p>Searching…</p>` : ''}
     <ul>
       ${each(results.value, r => html`
         <li><a :href="${r._path}">${r.title}</a></li>
@@ -505,7 +507,7 @@ component('page-search', () => {
 })
 ```
 
-Search activates when `query.value.length >= 2`. Empty or single-character queries return an empty array.
+`loading` becomes `true` as soon as the user types anything and returns to `false` once results arrive or the query is cleared. An empty query clears results immediately without waiting for the debounce. Search is always client-side — in SSR mode the component renders with empty results and hydrates on mount.
 
 ### Searched fields
 

package/e2e/cypress/e2e/content.cy.ts

@@ -240,14 +240,14 @@ describe('Content search — useContentSearch()', () => {
     cy.get('[data-cy=content-search-input]').should('exist')
   })
 
-  it('shows no results before typing 2 chars', () => {
+  it('shows results after typing a single character', () => {
     cy.visit('/content-search')
     cy.wait('@searchIndex')
     setSearchQuery('H')
-    cy.get('[data-cy=content-search-result]').should('not.exist')
+    cy.get('[data-cy=content-search-result]', { timeout: 8000 }).should('have.length.at.least', 1)
   })
 
-  it('shows results after typing a 2-char query', () => {
+  it('shows results after typing a multi-char query', () => {
     cy.visit('/content-search')
     cy.wait('@searchIndex')
     setSearchQuery('He')
@@ -275,6 +275,26 @@ describe('Content search — useContentSearch()', () => {
     cy.get('[data-cy=content-search-result]', { timeout: 8000 }).first().should('have.attr', 'data-path')
   })
 
+  it('shows loading indicator while search is in flight', () => {
+    cy.visit('/content-search')
+    cy.wait('@searchIndex')
+    setSearchQuery('Hello')
+    // loading indicator appears immediately after typing
+    cy.get('[data-cy=content-search-loading]').should('exist')
+    // loading indicator disappears once results arrive
+    cy.get('[data-cy=content-search-loading]', { timeout: 8000 }).should('not.exist')
+    cy.get('[data-cy=content-search-result]').should('have.length.at.least', 1)
+  })
+
+  it('clears loading indicator when query is cleared', () => {
+    cy.visit('/content-search')
+    cy.wait('@searchIndex')
+    setSearchQuery('Hello')
+    cy.get('[data-cy=content-search-loading]').should('exist')
+    setSearchQuery('')
+    cy.get('[data-cy=content-search-loading]').should('not.exist')
+  })
+
   it('clearing query clears results', () => {
     cy.visit('/content-search')
     cy.wait('@searchIndex')
@@ -283,6 +303,63 @@ describe('Content search — useContentSearch()', () => {
     setSearchQuery('')
     cy.get('[data-cy=content-search-result]').should('not.exist')
   })
+
+  it('shows no-results message for an unmatched query', () => {
+    // Use a query with no underscores — MiniSearch tokenizes on \p{P} which
+    // includes underscores, splitting e.g. "foo_bar" into two tokens that can
+    // accidentally match real content via OR semantics.
+    cy.visit('/content-search')
+    cy.wait('@searchIndex')
+    setSearchQuery('zzznomatch')
+    // Wait for the empty state — implicitly waits for loading to clear first
+    cy.get('[data-cy=content-search-empty]', { timeout: 8000 }).should('exist')
+    cy.get('[data-cy=content-search-result]').should('not.exist')
+    cy.get('[data-cy=content-search-loading]').should('not.exist')
+  })
+
+  it('sequential search: search → clear → search again returns correct results', () => {
+    cy.visit('/content-search')
+    cy.wait('@searchIndex')
+
+    // First search
+    setSearchQuery('Hello')
+    cy.get('[data-cy=content-search-result]', { timeout: 8000 }).should('contain', 'Hello World')
+
+    // Clear — results gone
+    setSearchQuery('')
+    cy.get('[data-cy=content-search-result]').should('not.exist')
+    cy.get('[data-cy=content-search-empty]').should('not.exist')
+
+    // Second search with a different term
+    setSearchQuery('Getting')
+    cy.get('[data-cy=content-search-result]', { timeout: 8000 }).should('contain', 'Getting Started')
+    // First search result must not bleed through
+    cy.get('[data-cy=content-search-result]').each(($el) => {
+      expect($el.text()).not.to.include('Hello World')
+    })
+  })
+
+  it('rapid typing triggers only one search request (debounce)', () => {
+    cy.visit('/content-search')
+    cy.wait('@searchIndex')
+
+    // Type characters in quick succession — each triggers a new watch callback
+    // but only the last one should produce a network request after 200 ms.
+    cy.intercept('GET', '/_content/search-index.json').as('secondIndex')
+    setSearchQuery('G')
+    setSearchQuery('Ge')
+    setSearchQuery('Get')
+    setSearchQuery('Gett')
+    setSearchQuery('Getti')
+    setSearchQuery('Getting')
+
+    // Results arrive for the final query
+    cy.get('[data-cy=content-search-result]', { timeout: 8000 }).should('contain', 'Getting Started')
+
+    // The search index is cached after the first pre-warm fetch (singleton), so
+    // no additional network request should occur for these follow-on searches.
+    cy.get('@secondIndex.all').should('have.length', 0)
+  })
 })
 
 // ─── /content-fallback ────────────────────────────────────────────────────────

package/e2e/kitchen-sink/app/pages/content-search.ts

@@ -1,13 +1,13 @@
 /**
  * Content search page — exercises `useContentSearch()`.
- * Typing 2+ characters into the search box triggers MiniSearch results.
+ * Typing into the search box triggers MiniSearch results (debounced).
  * Route: /content-search
  */
 
 component('page-content-search', () => {
   useHead({ title: 'Content Search — Kitchen Sink' })
 
-  const { query, results } = useContentSearch()
+  const { query, results, loading } = useContentSearch()
 
   return html`
     <div>
@@ -19,6 +19,7 @@ component('page-content-search', () => {
         .value="${query.value}"
         @input="${(e: Event) => { query.value = (e.target as HTMLInputElement).value }}"
       />
+      ${loading.value ? html`<p data-cy="content-search-loading">Searching…</p>` : ''}
       <ul data-cy="content-search-results">
         ${results.value.map(r => html`
           <li data-cy="content-search-result" data-path="${r._path}">
@@ -27,7 +28,7 @@ component('page-content-search', () => {
           </li>
         `)}
       </ul>
-      ${results.value.length === 0 && query.value.length >= 2 ? html`
+      ${results.value.length === 0 && query.value.length > 0 && !loading.value ? html`
         <p data-cy="content-search-empty">No results for "${query.value}".</p>
       ` : ''}
     </div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasonshimmy/vite-plugin-cer-app",
-  "version": "0.22.0",
+  "version": "0.23.1",
   "description": "Nuxt-style meta-framework for @jasonshimmy/custom-elements-runtime",
   "type": "module",
   "keywords": [

package/src/__tests__/runtime/use-content-search-composable.test.ts

@@ -0,0 +1,405 @@
+/**
+ * Tests for the useContentSearch() composable.
+ *
+ * Covers:
+ * - Initial state — empty query, empty results, loading=false
+ * - loading state — true immediately on typing, false after results arrive
+ * - Debounce timing — results are withheld until 200 ms after the last keystroke
+ * - Timer cancellation — a new query before 200 ms resets the debounce clock
+ * - Empty-query path — clears loading + results immediately, cancels pending timer
+ * - Disconnect cleanup — pending timer is cancelled and loading reset on unmount
+ * - Results content — correct items returned for each query
+ *
+ * @jasonshimmy/custom-elements-runtime is mocked so these tests run without a
+ * real DOM or component context. The watch() callback is available immediately
+ * after useContentSearch() is called (it is registered during the render-body
+ * call, not inside useOnConnected), so no triggerConnected() is needed before
+ * simulateType().
+ *
+ * Note: verifying that debounced input triggers exactly one loadIndex() call
+ * is an end-to-end concern exercised in content.cy.ts — the seq-stale guard
+ * discards duplicate search results even when debounce is absent, making the
+ * count indistinguishable at the unit level.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { buildSearchIndex } from '../../plugin/content/search.js'
+import type { ContentItem } from '../../types/content.js'
+
+// ─── Sample content ───────────────────────────────────────────────────────────
+
+const ITEMS: ContentItem[] = [
+  {
+    _path: '/blog/hello',
+    _file: 'blog/hello.md',
+    _type: 'markdown',
+    title: 'Hello World',
+    description: 'A post about hello',
+    body: '<p>Hello</p>',
+    toc: [],
+  },
+  {
+    _path: '/docs/start',
+    _file: 'docs/start.md',
+    _type: 'markdown',
+    title: 'Getting Started',
+    description: 'How to get started',
+    body: '<p>Start</p>',
+    toc: [],
+  },
+]
+
+// ─── Runtime mock ─────────────────────────────────────────────────────────────
+//
+// The mock simulates just enough of the runtime for these unit tests:
+//   _currentMockContext    — fresh plain object each test; receives _cerSearchDebounce
+//   _connectedCallbacks    — useOnConnected callbacks (pre-warm only in new implementation)
+//   _disconnectedCallbacks — useOnDisconnected callbacks (timer cleanup)
+//   _watchCallback         — the single watch(query, cb) handler registered during render
+
+let _currentMockContext: Record<string, unknown> = {}
+let _connectedCallbacks: Array<() => void> = []
+let _disconnectedCallbacks: Array<() => void> = []
+let _watchCallback: ((q: string) => void) | null = null
+
+vi.mock('@jasonshimmy/custom-elements-runtime', () => ({
+  // Run the factory immediately; getCurrentComponentContext() returns the mock context.
+  createComposable: (fn: () => unknown) => () => fn(),
+  // Minimal reactive ref: plain object with getter/setter.
+  ref: (initial: unknown) => {
+    let _val = initial
+    return {
+      get value() { return _val },
+      set value(v: unknown) { _val = v },
+    }
+  },
+  // Capture the single watch() callback registered by the composable.
+  watch: (_state: unknown, cb: (val: string) => void) => {
+    _watchCallback = cb
+  },
+  // Capture useOnConnected callbacks for manual triggering (pre-warm only).
+  useOnConnected: (cb: () => void) => {
+    _connectedCallbacks.push(cb)
+  },
+  // Capture useOnDisconnected callbacks for manual triggering.
+  useOnDisconnected: (cb: () => void) => {
+    _disconnectedCallbacks.push(cb)
+  },
+  // Return the fresh mock context so getDebounceState() can attach _cerSearchDebounce.
+  getCurrentComponentContext: () => _currentMockContext,
+}))
+
+// Static imports resolve AFTER vi.mock hoisting, so the mock is in place when
+// use-content-search.js's module-level createComposable() call executes.
+import { useContentSearch, resetIndexSingleton } from '../../runtime/composables/use-content-search.js'
+import type { UseContentSearchReturn } from '../../runtime/composables/use-content-search.js'
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Flush all useOnConnected callbacks (simulates component mount). */
+function triggerConnected(): void {
+  for (const cb of _connectedCallbacks) cb()
+}
+
+/** Flush all useOnDisconnected callbacks (simulates component unmount). */
+function triggerDisconnected(): void {
+  for (const cb of _disconnectedCallbacks) cb()
+}
+
+/** Simulate the user typing a value into the search input. */
+function simulateType(q: string): void {
+  if (!_watchCallback) throw new Error('watch callback not registered — did you call useContentSearch()?')
+  _watchCallback(q)
+}
+
+// Convenience typed accessor
+type Ref<T> = { value: T }
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('useContentSearch() composable', () => {
+  let result: UseContentSearchReturn
+  let originalFetch: typeof globalThis.fetch
+
+  beforeEach(async () => {
+    // Fresh context object for each test so _cerSearchDebounce doesn't bleed
+    _currentMockContext = {}
+    _connectedCallbacks = []
+    _disconnectedCallbacks = []
+    _watchCallback = null
+
+    // Each test gets a fresh index singleton so loadIndex() re-fetches.
+    resetIndexSingleton()
+
+    originalFetch = globalThis.fetch
+    const indexJson = buildSearchIndex(ITEMS)
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      text: () => Promise.resolve(indexJson),
+    } as unknown as Response)
+
+    // Calling useContentSearch() runs the factory, which calls watch() and
+    // registers useOnConnected/useOnDisconnected callbacks synchronously.
+    result = useContentSearch()
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+    vi.useRealTimers()
+  })
+
+  // ─── Shape ─────────────────────────────────────────────────────────────────
+
+  it('returns query, results, and loading refs', () => {
+    expect(result).toHaveProperty('query')
+    expect(result).toHaveProperty('results')
+    expect(result).toHaveProperty('loading')
+  })
+
+  it('initialises with empty query, empty results, and loading=false', () => {
+    expect((result.query as Ref<string>).value).toBe('')
+    expect((result.results as Ref<unknown[]>).value).toEqual([])
+    expect((result.loading as Ref<boolean>).value).toBe(false)
+  })
+
+  it('registers a watch callback during the render call (not after mount)', () => {
+    // The watch() is in the render body: available immediately after useContentSearch()
+    expect(_watchCallback).not.toBeNull()
+  })
+
+  it('attaches _cerSearchDebounce to the component context', () => {
+    expect(_currentMockContext).toHaveProperty('_cerSearchDebounce')
+    const state = _currentMockContext['_cerSearchDebounce'] as { seq: number; timer: unknown }
+    expect(state.seq).toBe(0)
+    expect(state.timer).toBeNull()
+  })
+
+  it('registers a useOnDisconnected callback for timer cleanup', () => {
+    expect(_disconnectedCallbacks).toHaveLength(1)
+  })
+
+  // ─── loading state ─────────────────────────────────────────────────────────
+
+  it('sets loading=true immediately when a non-empty query is set', () => {
+    vi.useFakeTimers()
+    simulateType('Hello')
+    expect((result.loading as Ref<boolean>).value).toBe(true)
+  })
+
+  it('keeps loading=true while the debounce timer is pending', () => {
+    vi.useFakeTimers()
+    simulateType('Hello')
+    vi.advanceTimersByTime(100) // 100 ms < 200 ms debounce
+    expect((result.loading as Ref<boolean>).value).toBe(true)
+    expect((result.results as Ref<unknown[]>).value).toEqual([])
+  })
+
+  it('sets loading=false once results arrive after the debounce window', async () => {
+    vi.useFakeTimers()
+    simulateType('Hello')
+    await vi.runAllTimersAsync()
+    expect((result.loading as Ref<boolean>).value).toBe(false)
+  })
+
+  it('clears loading immediately when query is reset to empty string', () => {
+    vi.useFakeTimers()
+    simulateType('Hello')
+    expect((result.loading as Ref<boolean>).value).toBe(true)
+    simulateType('')
+    expect((result.loading as Ref<boolean>).value).toBe(false)
+  })
+
+  // ─── Debounce timing ───────────────────────────────────────────────────────
+
+  it('withholds results until 200 ms after the last keystroke', () => {
+    vi.useFakeTimers()
+    simulateType('Hello')
+    vi.advanceTimersByTime(199) // 1 ms before debounce fires
+    expect((result.results as Ref<unknown[]>).value).toEqual([])
+  })
+
+  it('delivers results after the 200 ms debounce window elapses', async () => {
+    vi.useFakeTimers()
+    simulateType('Hello')
+    await vi.runAllTimersAsync()
+    expect((result.results as Ref<unknown[]>).value.length).toBeGreaterThan(0)
+  })
+
+  it('resets the debounce clock when a new query arrives before 200 ms', async () => {
+    vi.useFakeTimers()
+
+    simulateType('Getting')       // timer-A starts at t=0
+    vi.advanceTimersByTime(100)   // t=100 — timer-A still pending (100 < 200)
+    simulateType('Hello')         // cancels timer-A, timer-B starts at t=100
+    vi.advanceTimersByTime(100)   // t=200 — only 100 ms since timer-B started; still pending
+
+    // No results yet — timer-B hasn't fired
+    expect((result.results as Ref<unknown[]>).value).toEqual([])
+
+    await vi.runAllTimersAsync()  // timer-B fires at t=300; search runs with 'Hello'
+
+    const paths = (result.results as Ref<{ _path: string }[]>).value.map(r => r._path)
+    expect(paths).toContain('/blog/hello')       // 'Hello' prefix matched Hello World
+    expect(paths).not.toContain('/docs/start')   // 'Getting' timer was cancelled
+  })
+
+  it('cancels the pending timer and prevents results when query is cleared mid-debounce', async () => {
+    vi.useFakeTimers()
+    simulateType('Hello')         // debounce timer starts
+    vi.advanceTimersByTime(100)   // partway through window
+    simulateType('')              // clears timer; loading + results reset immediately
+
+    expect((result.loading as Ref<boolean>).value).toBe(false)
+    expect((result.results as Ref<unknown[]>).value).toEqual([])
+
+    await vi.runAllTimersAsync()  // advance remaining time — no timer should fire
+    expect((result.results as Ref<unknown[]>).value).toEqual([]) // still empty
+  })
+
+  // ─── Disconnect cleanup ────────────────────────────────────────────────────
+
+  it('cancels the pending timer on disconnect', async () => {
+    vi.useFakeTimers()
+    simulateType('Hello')
+    vi.advanceTimersByTime(100) // timer is pending
+
+    triggerDisconnected()
+
+    // Timer should be cancelled — advancing past the debounce window produces no results
+    await vi.runAllTimersAsync()
+    expect((result.results as Ref<unknown[]>).value).toEqual([])
+  })
+
+  it('resets loading to false on disconnect', () => {
+    vi.useFakeTimers()
+    simulateType('Hello')
+    expect((result.loading as Ref<boolean>).value).toBe(true)
+
+    triggerDisconnected()
+    expect((result.loading as Ref<boolean>).value).toBe(false)
+  })
+
+  // ─── Result shape and content ──────────────────────────────────────────────
+
+  it('result items include _path and title', async () => {
+    vi.useFakeTimers()
+    simulateType('Hello')
+    await vi.runAllTimersAsync()
+    const first = (result.results as Ref<Record<string, unknown>[]>).value[0]
+    expect(first).toHaveProperty('_path')
+    expect(first).toHaveProperty('title')
+  })
+
+  it('searching "Hello" returns Hello World and not Getting Started', async () => {
+    vi.useFakeTimers()
+    simulateType('Hello')
+    await vi.runAllTimersAsync()
+    const paths = (result.results as Ref<{ _path: string }[]>).value.map(r => r._path)
+    expect(paths).toContain('/blog/hello')
+    expect(paths).not.toContain('/docs/start')
+  })
+
+  it('searching "Getting" returns Getting Started and not Hello World', async () => {
+    vi.useFakeTimers()
+    simulateType('Getting')
+    await vi.runAllTimersAsync()
+    const paths = (result.results as Ref<{ _path: string }[]>).value.map(r => r._path)
+    expect(paths).toContain('/docs/start')
+    expect(paths).not.toContain('/blog/hello')
+  })
+
+  it('clears results immediately when query is reset from non-empty to empty', async () => {
+    vi.useFakeTimers()
+    simulateType('Hello')
+    await vi.runAllTimersAsync()
+    expect((result.results as Ref<unknown[]>).value.length).toBeGreaterThan(0)
+
+    simulateType('')
+    expect((result.results as Ref<unknown[]>).value).toEqual([])
+  })
+
+  // ─── Pre-warm ──────────────────────────────────────────────────────────────
+
+  it('registers a useOnConnected callback for index pre-warming', () => {
+    expect(_connectedCallbacks).toHaveLength(1)
+  })
+
+  it('pre-warms the index on mount (triggers a fetch)', async () => {
+    triggerConnected()
+    // fetch is called by the pre-warm (loadIndex inside useOnConnected)
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1)
+  })
+
+  // ─── Re-render stability ───────────────────────────────────────────────────
+  //
+  // The core fix: _seq and _timer live on the component context, not in local
+  // factory-body variables. These tests confirm that calling the factory a second
+  // time (simulating a component re-render) reuses the same state object rather
+  // than resetting it, so a timer set during one render can be cancelled by the
+  // new watcher registered on the next render.
+
+  it('reuses the same debounce state object when the factory runs again with the same context', () => {
+    // First render already called useContentSearch() in beforeEach.
+    const state1 = _currentMockContext['_cerSearchDebounce']
+    expect(state1).toBeDefined()
+
+    // Simulate re-render: reset captured callbacks, call factory again.
+    _connectedCallbacks = []
+    _disconnectedCallbacks = []
+    _watchCallback = null
+    useContentSearch()
+
+    const state2 = _currentMockContext['_cerSearchDebounce']
+
+    // Must be the identical object — not re-created.
+    expect(state2).toBe(state1)
+  })
+
+  it('a new keystroke after re-render cancels the timer that was set in the previous render', () => {
+    vi.useFakeTimers()
+
+    // First render (done in beforeEach). Type something → timer-A starts.
+    simulateType('Getting')
+    const state = _currentMockContext['_cerSearchDebounce'] as {
+      timer: ReturnType<typeof setTimeout> | null
+      seq: number
+    }
+    const timerA = state.timer
+    expect(timerA).not.toBeNull()
+
+    // Simulate re-render: new watch callback registered, same context state.
+    _watchCallback = null
+    useContentSearch()
+
+    // The new watcher fires. It reads state.timer (still timerA) and cancels it,
+    // then starts timer-B.
+    simulateType('Hello')
+
+    expect(state.timer).not.toBeNull()
+    expect(state.timer).not.toBe(timerA) // timer-A was replaced by timer-B
+  })
+
+  it('seq counter is not reset to 0 when the factory runs again (shared state)', async () => {
+    vi.useFakeTimers()
+
+    // First render: type something, let the debounce fire.
+    simulateType('Getting')
+    await vi.runAllTimersAsync() // timer fires → seq incremented to 1
+
+    const state = _currentMockContext['_cerSearchDebounce'] as { seq: number }
+    expect(state.seq).toBe(1)
+
+    // Simulate re-render: fresh callbacks, same context.
+    _connectedCallbacks = []
+    _disconnectedCallbacks = []
+    _watchCallback = null
+    useContentSearch()
+
+    // Type again on the new watcher and let it fire.
+    simulateType('Hello')
+    await vi.runAllTimersAsync() // seq incremented to 2
+
+    // If state were re-initialised on re-render, seq would be 1 again.
+    // Shared state means it continues from where it left off.
+    expect(state.seq).toBe(2)
+  })
+})

package/src/__tests__/runtime/use-content-search.test.ts

@@ -7,9 +7,10 @@
  * - loadIndex() error path — fetch failure rejects cleanly; singleton reset allows retry
  * - loadIndex() returns a searchable MiniSearch instance
  *
- * Note: The full useContentSearch() composable (query reactive state, stale-seq
- * guard, useOnConnected pre-warm) requires a component context provided by the
- * custom-elements-runtime and is exercised by the e2e suite in content.cy.ts.
+ * The full useContentSearch() composable (debounce, loading state, stale-seq
+ * guard) is tested in use-content-search-composable.test.ts, which mocks the
+ * runtime to exercise the watch callback and fake-timer debounce logic directly.
+ * End-to-end behaviour is covered by content.cy.ts.
  */
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import MiniSearch from 'minisearch'
@@ -99,7 +100,7 @@ describe('loadIndex', () => {
     resetIndexSingleton()
 
     const index = await loadIndex() as ReturnType<typeof MiniSearch.loadJSON>
-    const results = index.search('Hello', { prefix: true }) as Array<{ _path: string }>
+    const results = index.search('Hello', { prefix: true }) as unknown as Array<{ _path: string }>
     expect(results.some((r) => r._path === '/blog/hello')).toBe(true)
   })
 
@@ -136,4 +137,27 @@ describe('loadIndex', () => {
     const index = await loadIndex() as ReturnType<typeof MiniSearch.loadJSON>
     expect(index).toBeDefined()
   })
+
+  it('automatically retries after a fetch failure without manual singleton reset', async () => {
+    const { loadIndex, resetIndexSingleton } = await import('../../runtime/composables/use-content-search.js')
+    resetIndexSingleton()
+
+    // First call fails — singleton should be cleared automatically
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 503,
+    } as unknown as Response)
+    await expect(loadIndex()).rejects.toThrow()
+
+    // Second call without resetIndexSingleton — should retry and succeed
+    const indexJson = buildIndex()
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      text: () => Promise.resolve(indexJson),
+    } as unknown as Response)
+    const index = await loadIndex() as ReturnType<typeof MiniSearch.loadJSON>
+    expect(index).toBeDefined()
+    // Confirm the new singleton is cached (second call reuses it)
+    expect(await loadIndex()).toBe(index)
+  })
 })

package/src/runtime/composables/use-content-search.ts

@@ -1,7 +1,9 @@
 import {
   createComposable,
+  getCurrentComponentContext,
   ref,
   useOnConnected,
+  useOnDisconnected,
   watch,
 } from '@jasonshimmy/custom-elements-runtime'
 import type { ReactiveState } from '@jasonshimmy/custom-elements-runtime'
@@ -19,11 +21,14 @@ let _indexPromise: Promise<unknown> | null = null
  * Returns the same Promise on repeated calls — the index is built at most once
  * per session regardless of how many search components are mounted.
  *
+ * If the fetch fails the singleton is cleared so the next search attempt
+ * retries automatically (no page reload required after a transient error).
+ *
  * @internal Exported for unit testing only.
  */
-export async function loadIndex(): Promise<unknown> {
+export function loadIndex(): Promise<unknown> {
   if (_indexPromise) return _indexPromise
-  _indexPromise = (async () => {
+  const attempt = (async () => {
     const [{ default: MiniSearch }, raw] = await Promise.all([
       import('minisearch'),
       fetch(contentSearchIndexUrl()).then((r) => {
@@ -37,7 +42,13 @@ export async function loadIndex(): Promise<unknown> {
       idField: '_path',
     })
   })()
-  return _indexPromise
+  _indexPromise = attempt
+  // Clear the singleton on failure so the next call retries the fetch.
+  // The === guard ensures a newer concurrent attempt is not accidentally cleared.
+  attempt.catch(() => {
+    if (_indexPromise === attempt) _indexPromise = null
+  })
+  return attempt
 }
 
 /** Resets the module-level singleton. Used in tests only. @internal */
@@ -45,44 +56,114 @@ export function resetIndexSingleton(): void {
   _indexPromise = null
 }
 
+// ─── Per-component debounce state ────────────────────────────────────────────
+
+// Stores the debounce timer handle and stale-seq counter directly on the
+// component context object (non-enumerable, same pattern the runtime uses for
+// _hookCallbacks). This makes the values stable across re-renders — the context
+// object is fixed for the lifetime of the element instance — without leaking
+// into the reactive proxy or triggering spurious updates.
+
+interface DebounceState {
+  seq: number
+  timer: ReturnType<typeof setTimeout> | null
+}
+
+const _STATE_KEY = '_cerSearchDebounce'
+
+function getDebounceState(ctx: Record<string, unknown>): DebounceState {
+  if (!Object.prototype.hasOwnProperty.call(ctx, _STATE_KEY)) {
+    Object.defineProperty(ctx, _STATE_KEY, {
+      value: { seq: 0, timer: null } as DebounceState,
+      writable: false,    // object ref is fixed; its properties are still mutable
+      enumerable: false,  // invisible to the reactive proxy set-trap
+      configurable: false,
+    })
+  }
+  return (ctx as Record<string, DebounceState>)[_STATE_KEY]
+}
+
 // ─── Composable ───────────────────────────────────────────────────────────────
 
 export interface UseContentSearchReturn {
   query: ReactiveState<string>
   results: ReactiveState<ContentSearchResult[]>
+  /** `true` from the moment the user starts typing until results (or an error) arrive. `false` when the query is empty or the search is complete. */
+  loading: ReactiveState<boolean>
 }
 
 const _factory = createComposable((): UseContentSearchReturn => {
   const query = ref('')
   const results = ref<ContentSearchResult[]>([])
+  const loading = ref(false)
+
+  // Debounce state lives on the component context, not in local render-body variables.
+  // Local variables are re-created on every re-render; the context object is stable
+  // for the lifetime of the element.  Storing state here lets the render-body
+  // watch() (see below) pick up the same timer and sequence counter across re-renders
+  // without the watcher accumulation that occurs when watch() is placed inside
+  // useOnConnected() (which runs once per mount but is not registered for cleanup
+  // by the reactive system, leaking watchers on every disconnect + reconnect cycle).
+  const state = getDebounceState(getCurrentComponentContext()! as Record<string, unknown>)
 
-  // Pre-warm index on mount
+  // Pre-warm the index on first mount so the first real search is faster.
   useOnConnected(() => {
     loadIndex().catch(() => {/* silently ignore pre-warm errors */})
   })
 
-  // Monotonic counter to discard stale async results
-  let _seq = 0
+  // Cancel any in-flight debounce on unmount so stale async work doesn't land
+  // after the component is gone.
+  useOnDisconnected(() => {
+    if (state.timer !== null) {
+      clearTimeout(state.timer)
+      state.timer = null
+    }
+    state.seq++ // discard any in-flight async search
+    loading.value = false
+  })
 
-  watch(query, async (q: string) => {
-    const seq = ++_seq
+  // watch() is in the render body so the reactive system registers it under the
+  // current component and tears it down automatically on re-render and disconnect.
+  // The mutable state (seq / timer) lives on the context (above) and persists
+  // across re-renders — new watcher instances see the same timer and counter,
+  // which is what makes debounce cancellation correct even after a re-render.
+  watch(query, (q: string) => {
+    if (state.timer !== null) {
+      clearTimeout(state.timer)
+      state.timer = null
+    }
 
-    if (!q || q.length < 2) {
+    if (!q) {
+      // Increment seq so any in-flight async search is discarded when it resolves
+      state.seq++
+      loading.value = false
       results.value = []
       return
     }
 
-    try {
-      const index = await loadIndex() as { search(q: string, opts?: { prefix?: boolean }): ContentSearchResult[] }
-      if (seq !== _seq) return // stale — a newer query is in flight
-      results.value = index.search(q, { prefix: true }) as ContentSearchResult[]
-    } catch {
-      if (seq !== _seq) return
-      results.value = []
-    }
+    // Signal loading immediately so the UI can respond before the debounce fires
+    loading.value = true
+
+    state.timer = setTimeout(async () => {
+      state.timer = null
+      const seq = ++state.seq
+
+      try {
+        const index = await loadIndex() as { search(q: string, opts?: { prefix?: boolean }): ContentSearchResult[] }
+        if (seq !== state.seq) return // stale — a newer query is in flight
+        results.value = index.search(q, { prefix: true }) as ContentSearchResult[]
+      } catch {
+        if (seq !== state.seq) return
+        results.value = []
+      } finally {
+        // Only clear loading for the most recent search; a newer in-flight search
+        // keeps loading=true until it settles.
+        if (seq === state.seq) loading.value = false
+      }
+    }, 200)
   })
 
-  return { query, results }
+  return { query, results, loading }
 })
 
 /**
@@ -92,8 +173,10 @@ const _factory = createComposable((): UseContentSearchReturn => {
  * `/_content/search-index.json`. Both MiniSearch and the index are loaded via
  * dynamic import — neither is in the app bundle.
  *
- * Searches `title` and `description` fields. Results are empty until at least
- * 2 characters are entered.
+ * Searches `title` and `description` fields. Input is debounced (200 ms) so
+ * the index is not queried on every keystroke. `loading` becomes `true` as soon
+ * as the user starts typing and returns to `false` once results arrive. Results
+ * are empty when the query is empty.
  *
  * **SSR note**: search is always client-side. In SSR mode the component renders
  * with empty results and hydrates on mount.
@@ -101,10 +184,11 @@ const _factory = createComposable((): UseContentSearchReturn => {
  * @example
  * ```ts
  * component('site-search', () => {
- *   const { query, results } = useContentSearch()
+ *   const { query, results, loading } = useContentSearch()
  *
  *   return html`
  *     <input type="search" :model="${query}" placeholder="Search…" />
+ *     ${loading.value ? html`<p>Searching…</p>` : ''}
  *     ${when(results.value.length > 0, () => html`
  *       <ul>
  *         ${each(results.value, r => html`