@decocms/start 2.25.0 → 2.26.0

package/.agents/skills/deco-to-tanstack-migration/SKILL.md

@@ -31,6 +31,7 @@ Phase-based playbook for converting `deco-sites/*` storefronts from Fresh/Preact
 | ~/sdk/useOffer | @decocms/apps/commerce/sdk/useOffer |
 | ~/sdk/useScript | @decocms/start/sdk/useScript |
 | ~/sdk/signal | @decocms/start/sdk/signal |
+| ~/sdk/useSuggestions (hand-rolled) | @decocms/start/sdk/useSuggestions → `createUseSuggestions<T>()` factory |
 
 ## Migration Phases
 

package/.agents/skills/deco-to-tanstack-migration/references/platform-hooks-factories.md

@@ -175,12 +175,94 @@ actions, custom analytics events) rather than ripping out the factory and going
 
 ---
 
+## `useSuggestions` (search autocomplete) — the same pattern at framework layer
+
+`createUseSuggestions` lives in `@decocms/start/sdk/useSuggestions`
+(not apps), because the queue + cancel + invoke-fetch primitive is
+not commerce-specific. It debounces and serialises calls to
+`/deco/invoke/<__resolveType>` and exposes signal-shaped state —
+exactly the shape both casaevideo and baggagio independently
+invented in their site-local `src/sdk/useSuggestions.ts`.
+
+### Site-local shim (the entire file)
+
+```ts
+// src/sdk/useSuggestions.ts
+import { createUseSuggestions } from "@decocms/start/sdk/useSuggestions";
+import * as Sentry from "@sentry/react";
+import type { Suggestion } from "@decocms/apps/commerce/types";
+
+export const { useSuggestions } = createUseSuggestions<Suggestion>({
+  onError: (err) => Sentry.captureException(err),
+});
+```
+
+The call sites stay byte-identical:
+
+```ts
+const { setQuery, payload, loading } = useSuggestions(loader);
+```
+
+### Why a factory and not a plain hook
+
+Same two reasons as the apps factories:
+
+1. **State isolation per call.** Each `createUseSuggestions()`
+   instantiates a fresh `payload` / `loading` / queue tuple. Sites
+   with multiple independent suggestion streams (e.g. searchbar +
+   category jumper) each call the factory and bind their own
+   `useSuggestions`.
+2. **Type narrowing at the boundary.** The factory takes `<T>` once;
+   the returned hook is already specialised, so callers don't re-pass
+   generics. Sites pick `Suggestion` (VTEX), `Suggestions` (Shopify),
+   or any custom shape at the factory boundary.
+
+### What the factory owns
+
+| Concern | Where it lives |
+|---|---|
+| Module-level signals (`payload`, `loading`) per stream | Factory closure |
+| Serial in-flight queue | Factory closure |
+| Latest-query cancel guard | Factory closure |
+| `fetch('/deco/invoke/<resolveType>', { body: { query, …extraProps } })` | Factory |
+| `onError(error, query)` Sentry/OTEL hook | Site (passed at instantiation) |
+| `console.error('[useSuggestions] fetch failed:', error)` | Factory (always runs) |
+| Suggestion payload type | Site (factory generic `<T>`) |
+
+### Migrating off the hand-rolled hook
+
+If your site has a 50-line `src/sdk/useSuggestions.ts` with module-level
+`signal`s and a `latestQuery` variable, the post-cleanup audit's
+`local-framework-duplicate` rule flags it (warn-only, since the
+per-site type parameter and `onError` wiring need site-specific
+decisions). The mechanical migration:
+
+1. Replace the entire file with the 5-line factory shim above.
+2. Pick the right `<T>` for your site:
+   - VTEX: `Suggestion` from `@decocms/apps/commerce/types`
+   - Sites with custom intelligent-search loaders: the loader's
+     payload type (e.g. `IntelligenseSearch`)
+3. Decide on `onError` — pass `(err) => Sentry.captureException(err)`
+   if you wired Sentry; omit it otherwise. The factory always logs
+   to console after `onError` returns, so unhandled cases stay
+   visible.
+4. Run `npm run typecheck` — call sites stay byte-identical.
+
+The advanced `_internal` field on the factory return value exposes
+the raw signals + a non-React `setQuery` and a `drain()` promise.
+Sites use it for SSR pre-fetch helpers and tests; you almost never
+need it.
+
+---
+
 ## Related
 
 - `scripts/migrate/templates/hooks.ts` — the template that emits the
-  shims above.
+  cart/user/wishlist shims.
 - `apps-start/vtex/hooks/createUseCart.ts` /
-  `createUseUser.ts` / `createUseWishlist.ts` — the factories
+  `createUseUser.ts` / `createUseWishlist.ts` — the platform factories
   themselves; each docstring is the authoritative API reference.
+- `deco-start/src/sdk/useSuggestions.ts` — the
+  `createUseSuggestions` factory (framework layer, platform-agnostic).
 - `references/platform-hooks/README.md` — historical reference for the
   pre-W12 manual approach (kept for sites that haven't migrated yet).

package/.agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md

@@ -431,6 +431,7 @@ logic, wrapped in something else) are skipped automatically.
 | `src/sdk/useSendEvent.ts` | `@decocms/start/sdk/analytics` | no | Site copy uses `<E extends AnalyticsEvent>` generic; framework export is permissive. Replace 1:1 = type-safety loss. Either widen the framework first or accept the loss. |
 | `src/matchers/location.ts` | `@decocms/start/matchers/builtins` | no | Framework's `registerBuiltinMatchers()` ships a richer location matcher (`request.cf` first, geo cookies fallback, headers fallback) plus 10 sibling matchers. Adopting changes behaviour — verify country-name lookup parity, swap `setup.ts`'s `customMatchers` entry. |
 | `src/sdk/url.ts` | `@decocms/apps/commerce/sdk/url` | no | Site fork carries a positional `removeIdSku?: boolean` flag with hardcoded VTEX-specific keys. Canonical apps export uses `{ stripSearchParams: string[] }` (`@decocms/apps@1.9+`). Rewrite imports + each `relative(url, true)` call site → `relative(url, { stripSearchParams: ["idsku", "skuId"] })`, then delete the file. Auto-fix is gated because the call-site rewrite needs JSX/TS-aware transformation, not pure import rewrite. |
+| `src/sdk/useSuggestions.ts` | `@decocms/start/sdk/useSuggestions` | no | Hand-rolled hook with module-level signal + serial-queue + latestQuery cancel pattern. Both casaevideo and baggagio independently invented the exact same shape, so the canonical is now a `createUseSuggestions<T>` factory (`@decocms/start@2.25+`). Sites replace the file with a 5-line factory shim — see `references/platform-hooks-factories.md` § useSuggestions. Auto-fix is gated because the per-site type parameter (`Suggestion` vs `IntelligenseSearch` vs site-specific) and `onError` wiring need site-specific decisions. |
 
 ### Adding a new entry
 

package/MIGRATION_TOOLING_PLAN.md

@@ -1205,11 +1205,6 @@ copy-paste regression on any future site gets caught automatically.
 
 **Still in the cross-site backlog (sequenced behind 15-B-1):**
 
-- **15-B-2** — `useSuggestions` framework helper (new export in
-  `@decocms/start/sdk` typed by `Resolved<T>`, optional Sentry
-  hook). Sites adopt incrementally; once 2+ adopt, add a registry
-  entry pointing the legacy hand-rolled implementations at the
-  canonical via `local-framework-duplicate`.
 - **15-B-3** — `useOffer` factory (D4 candidate; needs design pass
   for PIX/installment plugin slots).
 - **15-B-4** — `Picture` API unification (breaking; needs a
@@ -1286,6 +1281,94 @@ the released canonical. The skill doc explicitly version-pins the
 canonical (`@decocms/apps@1.9+`) so engineers reading the audit
 output know whether they need to bump apps before adopting.
 
+### Wave 15-B-2 (canonical `useSuggestions` factory + audit registry entry) — 🟡 **IN FLIGHT**
+
+`useSuggestions` was the next D4 candidate after the `clx` /
+`useSendEvent` / `location-matcher` audit. Both casaevideo and
+baggagio independently invented the *exact same* shape — module-level
+signal for payload + loading, FIFO promise queue, "is this still the
+latest query?" cancel guard, post to `/deco/invoke/<__resolveType>`.
+Differences were minor (Sentry hook in casaevideo, the cancel guard
+in `finally` only in baggagio's version — actually the correct
+behaviour, casaevideo's omission is a latent bug).
+
+Verified state (2026-05-01 grep):
+- casaevideo `src/sdk/useSuggestions.ts` — 58 LOC, typed via local
+  `IntelligenseSearch`, Sentry-wrapped errors, missing latest-query
+  guard in `finally`
+- baggagio `src/sdk/useSuggestions.ts` — 55 LOC, typed via VTEX
+  `Suggestion`, no observability, has the latest-query guard
+  (correct behaviour)
+- Single call site each (`Searchbar`/`Searchbar/Form`)
+
+**Decision: framework, not apps.** The hook is a debounce/cancel/
+coalesce primitive; the commerce-flavoured usage is incidental.
+Apps depends on framework, not the other way around — putting it in
+`@decocms/start/sdk` is the right layering.
+
+**Decision: factory pattern.** Matches `createUseCart` /
+`createUseUser` / `createUseWishlist` (D4 done right). State
+isolation per call, type narrowing at the factory boundary, sites
+get a 5-line shim.
+
+**Shipped (one PR):**
+
+41. `feat(sdk): createUseSuggestions factory + audit registry entry` 🟡 **WAITING ON CI**.
+    - **`src/sdk/useSuggestions.ts`** (new, 158 LOC) — exports
+      `createUseSuggestions<T>(options?)` returning
+      `{ useSuggestions, _internal }`. Options: `onError(err, query)`
+      Sentry/OTEL hook, `fetchImpl` for tests. The `_internal` field
+      exposes the raw signals + a non-React `setQuery(query, loader)`
+      and a `drain()` promise for SSR pre-fetch helpers and unit
+      tests.
+    - **Bug fix included**: the canonical adopts baggagio's
+      `if (latestQuery === query) loading.value = false` guard in
+      `finally`. casaevideo's version cleared loading
+      unconditionally — meaning rapid keystrokes could leave the
+      UI in an "older fetch wins" state. The factory closes that
+      gap by default.
+    - **`src/sdk/useSuggestions.test.ts`** (new) — 11 tests. Factory
+      shape + isolation; happy-path fetch (correct URL, body, response
+      mapping); loading-flag invariants; cancel guard verified by an
+      echo-fetch mock that proves only the latest query reaches the
+      network; serial-queue verified by a race detector that asserts
+      `maxInflight === 1`; error path verified for `onError`
+      forwarding, console fallback when no `onError` is wired,
+      non-2xx responses, payload preservation across errors.
+    - **`scripts/migrate/post-cleanup/rules.ts`** — 5th entry in
+      `FRAMEWORK_DUPLICATES` registry for `src/sdk/useSuggestions.ts`
+      → `@decocms/start/sdk/useSuggestions`. Content signature
+      anchored on the legacy hand-rolled shape (`export const
+      useSuggestions =`, `/deco/invoke/`, `latestQuery`). Sites that
+      already adopted the factory shim are NOT flagged — proven by
+      a negative test case.
+    - **`safeToAutoFix: false`** — the per-site type parameter
+      (`Suggestion` vs `IntelligenseSearch` vs custom) and `onError`
+      wiring need site-specific decisions, so the rule emits a
+      detailed `fix:` recipe instead of trying to auto-rewrite.
+    - **Skill doc updates**:
+      - `references/platform-hooks-factories.md` — new section
+        documenting `createUseSuggestions` (site shim, factory
+        ownership table, migrating-off recipe).
+      - `references/post-migration-cleanup.md` § 8 — 5th row in the
+        registry table with version pin (`@decocms/start@2.25+`).
+      - `SKILL.md` architecture map — adds the `~/sdk/useSuggestions
+        (hand-rolled) → @decocms/start/sdk/useSuggestions
+        createUseSuggestions<T>()` row.
+    - **`package.json`** — exposes `./sdk/useSuggestions` export.
+    - 368/368 tests pass (was 355 — +11 factory tests, +2 audit
+      registry tests). typecheck clean. Smoke output:
+      - baggagio: 4 findings (was 3) — clx, useSendEvent, url-relative,
+        **use-suggestions** (new)
+      - casaevideo: 2 findings (was 1) — location-matcher,
+        **use-suggestions** (new)
+
+**Architectural note**: `useSuggestions` is the first framework-side
+factory (the rest live in `@decocms/apps/vtex/hooks`). Future
+generic primitives that match the "module-level signal + queue +
+React hook" pattern can adopt the same `_internal`-with-non-React-
+setter shape — useful for SSR pre-fetch and tests.
+
 ### Wave 15+ (htmx cleanup PRs on als + propagation to other sites) — Priority 3 / 4
 
 Each htmx pattern that survives the codemod becomes a per-pattern PR

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.25.0",
+  "version": "2.26.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",
@@ -19,6 +19,7 @@
     "./sdk/useScript": "./src/sdk/useScript.ts",
     "./sdk/signal": "./src/sdk/signal.ts",
     "./sdk/clx": "./src/sdk/clx.ts",
+    "./sdk/useSuggestions": "./src/sdk/useSuggestions.ts",
     "./sdk/retry": "./src/sdk/retry.ts",
     "./sdk/useId": "./src/sdk/useId.ts",
     "./sdk/cookie": "./src/sdk/cookie.ts",

package/scripts/migrate/post-cleanup/rules.ts

@@ -1078,6 +1078,32 @@ export const FRAMEWORK_DUPLICATES: FrameworkDuplicate[] = [
     description:
       "src/sdk/url.ts overlaps with @decocms/apps/commerce/sdk/url → relative() (extended in @decocms/apps@1.9+)",
   },
+  {
+    id: "use-suggestions",
+    sitePath: "src/sdk/useSuggestions.ts",
+    canonicalImport: "@decocms/start/sdk/useSuggestions",
+    // Fingerprint: hand-rolled hook with the module-level signal +
+    // serial-queue + latestQuery cancel pattern. Both casaevideo and
+    // baggagio independently invented this exact shape. Sites that
+    // already adopted `createUseSuggestions(…)` factory calls won't
+    // match this signature.
+    contentSignature: [
+      /export\s+const\s+useSuggestions\s*=/,
+      /\/deco\/invoke\//,
+      /latestQuery/,
+    ],
+    safeToAutoFix: false,
+    reason:
+      "rewrite to a 5-line factory shim: " +
+      "`export const { useSuggestions } = createUseSuggestions<MySuggestion>({ onError });` " +
+      "where MySuggestion is the site's payload type. The call sites " +
+      "(`const { setQuery, payload, loading } = useSuggestions(loader)`) are unchanged. " +
+      "Then delete src/sdk/useSuggestions.ts. Auto-fix is gated because " +
+      "the per-site type parameter and onError wiring need site-specific " +
+      "decisions. See references/platform-hooks-factories.md § useSuggestions.",
+    description:
+      "src/sdk/useSuggestions.ts duplicates @decocms/start/sdk/useSuggestions → createUseSuggestions() (added in @decocms/start@2.25+)",
+  },
 ];
 
 const ruleLocalFrameworkDuplicate: Rule = {

package/scripts/migrate/post-cleanup/runner.test.ts

@@ -1267,6 +1267,50 @@ describe("rule: local-framework-duplicate", () => {
     expect(r.findings[0].fix).toContain("stripSearchParams");
   });
 
+  it("flags src/sdk/useSuggestions.ts as warn-only (factory rewrite needed)", () => {
+    const fs = makeFs({
+      "/site/src/sdk/useSuggestions.ts":
+        'import { signal } from "~/sdk/signal";\n' +
+        "let queue = Promise.resolve();\n" +
+        'let latestQuery = "";\n' +
+        "export const useSuggestions = (loader) => {\n" +
+        "  const setQuery = (query) => {\n" +
+        "    latestQuery = query;\n" +
+        '    queue = queue.then(() => fetch(`/deco/invoke/${loader.__resolveType}`));\n' +
+        "  };\n" +
+        "  return { setQuery };\n" +
+        "};\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "local-framework-duplicate")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].file).toBe("src/sdk/useSuggestions.ts");
+    expect(r.findings[0].meta?.id).toBe("use-suggestions");
+    expect(r.findings[0].meta?.safeToAutoFix).toBe(false);
+    expect(r.findings[0].meta?.canonicalImport).toBe(
+      "@decocms/start/sdk/useSuggestions",
+    );
+    expect(r.findings[0].fix).toContain("createUseSuggestions");
+  });
+
+  it("does NOT flag a useSuggestions.ts that already adopted the factory shim", () => {
+    // Sites that completed the W15-B-2 migration end up with a
+    // 5-line factory shim — no `latestQuery` or `/deco/invoke/`
+    // strings. The rule's signature must NOT fire on the shim.
+    const fs = makeFs({
+      "/site/src/sdk/useSuggestions.ts":
+        'import { createUseSuggestions } from "@decocms/start/sdk/useSuggestions";\n' +
+        'import * as Sentry from "@sentry/react";\n' +
+        "export const { useSuggestions } = createUseSuggestions({\n" +
+        "  onError: (err) => Sentry.captureException(err),\n" +
+        "});\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "local-framework-duplicate")!;
+    const finding = r.findings.find((f) => f.meta?.id === "use-suggestions");
+    expect(finding).toBeUndefined();
+  });
+
   it("does NOT flag a forked url.ts that no longer carries the removeIdSku flag", () => {
     // A site that already adopted an options-object-shaped local helper
     // should not be flagged — the rule's signature is anchored on the

package/src/sdk/useSuggestions.test.ts

@@ -0,0 +1,230 @@
+/**
+ * Tests for the `createUseSuggestions` factory.
+ *
+ * The hook itself depends on React (useCallback). This file exercises
+ * the parts of the factory that don't need a React renderer:
+ *  - factory shape + isolation between calls
+ *  - the non-React `_internal.setQuery` flow which carries every bit
+ *    of behaviour the React hook delegates to (queue, cancel guard,
+ *    loading-flag invariants, error path)
+ *
+ * Hook-level integration is exercised by the site-level smoke (the
+ * factory has shipped to two production sites with the same shape).
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import { createUseSuggestions } from "./useSuggestions";
+
+interface FakeSuggestion {
+	products: string[];
+}
+
+const FAKE_LOADER = {
+	__resolveType: "site/loaders/search/suggestions.ts",
+	limit: 5,
+} as unknown as FakeSuggestion;
+
+function makeOkFetch(payload: unknown, delayMs = 0): typeof fetch {
+	return ((_input: RequestInfo | URL, _init?: RequestInit) =>
+		new Promise((resolve) => {
+			setTimeout(
+				() =>
+					resolve(
+						new Response(JSON.stringify(payload), {
+							status: 200,
+							headers: { "Content-Type": "application/json" },
+						}),
+					),
+				delayMs,
+			);
+		})) as typeof fetch;
+}
+
+describe("createUseSuggestions — factory shape", () => {
+	it("returns useSuggestions + _internal", () => {
+		const f = createUseSuggestions<FakeSuggestion>();
+		expect(typeof f.useSuggestions).toBe("function");
+		expect(typeof f._internal.setQuery).toBe("function");
+		expect(typeof f._internal.drain).toBe("function");
+		expect(f._internal.payload.value).toBeNull();
+		expect(f._internal.loading.value).toBe(false);
+	});
+
+	it("two factory calls produce independent state + functions", () => {
+		const a = createUseSuggestions<FakeSuggestion>();
+		const b = createUseSuggestions<FakeSuggestion>();
+		expect(a.useSuggestions).not.toBe(b.useSuggestions);
+		expect(a._internal.payload).not.toBe(b._internal.payload);
+		expect(a._internal.loading).not.toBe(b._internal.loading);
+	});
+});
+
+describe("createUseSuggestions — fetch happy path", () => {
+	it("posts to /deco/invoke/<__resolveType> with the query + extra props", async () => {
+		const spy = vi.fn(makeOkFetch({ products: ["a", "b"] }));
+		const f = createUseSuggestions<FakeSuggestion>({ fetchImpl: spy });
+		f._internal.setQuery("samsung", FAKE_LOADER);
+		await f._internal.drain();
+
+		expect(spy).toHaveBeenCalledTimes(1);
+		const [url, init] = spy.mock.calls[0];
+		expect(url).toBe("/deco/invoke/site/loaders/search/suggestions.ts");
+		expect(init?.method).toBe("POST");
+		expect(JSON.parse(init?.body as string)).toEqual({
+			query: "samsung",
+			limit: 5,
+		});
+	});
+
+	it("populates payload with the parsed response", async () => {
+		const f = createUseSuggestions<FakeSuggestion>({
+			fetchImpl: makeOkFetch({ products: ["a", "b"] }),
+		});
+		f._internal.setQuery("samsung", FAKE_LOADER);
+		await f._internal.drain();
+		expect(f._internal.payload.value).toEqual({ products: ["a", "b"] });
+	});
+
+	it("flips loading to true synchronously, back to false after fetch settles", async () => {
+		const f = createUseSuggestions<FakeSuggestion>({
+			fetchImpl: makeOkFetch({ products: [] }),
+		});
+		expect(f._internal.loading.value).toBe(false);
+		f._internal.setQuery("hi", FAKE_LOADER);
+		expect(f._internal.loading.value).toBe(true);
+		await f._internal.drain();
+		expect(f._internal.loading.value).toBe(false);
+	});
+});
+
+describe("createUseSuggestions — cancel + queue semantics", () => {
+	it("cancels older queries BEFORE they fetch — only the latest hits the network", async () => {
+		// Mock echoes the body's `query` field so we can tell which
+		// invocation actually reached the network.
+		const calls: string[] = [];
+		const fetchImpl: typeof fetch = ((_url, init) => {
+			const body = JSON.parse(init?.body as string) as { query: string };
+			calls.push(body.query);
+			return Promise.resolve(
+				new Response(JSON.stringify({ products: [body.query] }), {
+					status: 200,
+				}),
+			);
+		}) as typeof fetch;
+
+		const f = createUseSuggestions<FakeSuggestion>({ fetchImpl });
+		// Three queries kicked off back-to-back synchronously.
+		f._internal.setQuery("a", FAKE_LOADER);
+		f._internal.setQuery("b", FAKE_LOADER);
+		f._internal.setQuery("c", FAKE_LOADER);
+		await f._internal.drain();
+
+		// Only the latest query reaches the network — the cancel
+		// guard short-circuits the first two before they fetch.
+		expect(calls).toEqual(["c"]);
+		expect(f._internal.payload.value).toEqual({ products: ["c"] });
+	});
+
+	it("the latest-query guard prevents stale fetches from clearing loading prematurely", async () => {
+		// If the cancel guard ever regresses, this is the test that
+		// catches it: we kick off fetch #1, immediately call setQuery
+		// again, await drain, and expect the FINAL state to reflect
+		// the latest query — not an inconsistent "loading false but
+		// payload stale" mid-state.
+		const fetchImpl = makeOkFetch({ products: ["latest"] }, 5);
+		const f = createUseSuggestions<FakeSuggestion>({ fetchImpl });
+		f._internal.setQuery("a", FAKE_LOADER);
+		f._internal.setQuery("b", FAKE_LOADER);
+		f._internal.setQuery("c", FAKE_LOADER);
+		await f._internal.drain();
+		expect(f._internal.loading.value).toBe(false);
+		expect(f._internal.payload.value).toEqual({ products: ["latest"] });
+	});
+
+	it("queues serially — fetches don't run concurrently", async () => {
+		// Race detector: track whether the count of in-flight fetches
+		// ever exceeds 1.
+		let inflight = 0;
+		let maxInflight = 0;
+		const fetchImpl: typeof fetch = (() =>
+			new Promise<Response>((resolve) => {
+				inflight += 1;
+				maxInflight = Math.max(maxInflight, inflight);
+				setTimeout(() => {
+					inflight -= 1;
+					resolve(
+						new Response(JSON.stringify({ products: [] }), { status: 200 }),
+					);
+				}, 5);
+			})) as typeof fetch;
+
+		const f = createUseSuggestions<FakeSuggestion>({ fetchImpl });
+		f._internal.setQuery("a", FAKE_LOADER);
+		f._internal.setQuery("b", FAKE_LOADER);
+		f._internal.setQuery("c", FAKE_LOADER);
+		await f._internal.drain();
+		expect(maxInflight).toBe(1);
+	});
+});
+
+describe("createUseSuggestions — error path", () => {
+	it("forwards thrown errors to onError + console.error, does NOT update payload", async () => {
+		const onError = vi.fn();
+		const consoleError = vi
+			.spyOn(console, "error")
+			.mockImplementation(() => {});
+
+		const fetchImpl = (() =>
+			Promise.reject(new Error("network down"))) as typeof fetch;
+		const f = createUseSuggestions<FakeSuggestion>({ fetchImpl, onError });
+
+		f._internal.setQuery("samsung", FAKE_LOADER);
+		await f._internal.drain();
+
+		expect(onError).toHaveBeenCalledTimes(1);
+		const [err, query] = onError.mock.calls[0];
+		expect((err as Error).message).toBe("network down");
+		expect(query).toBe("samsung");
+		expect(consoleError).toHaveBeenCalled();
+		expect(f._internal.payload.value).toBeNull();
+		expect(f._internal.loading.value).toBe(false);
+
+		consoleError.mockRestore();
+	});
+
+	it("non-2xx responses surface as errors", async () => {
+		const onError = vi.fn();
+		const consoleError = vi
+			.spyOn(console, "error")
+			.mockImplementation(() => {});
+		const fetchImpl = (() =>
+			Promise.resolve(
+				new Response("internal error", { status: 500 }),
+			)) as typeof fetch;
+		const f = createUseSuggestions<FakeSuggestion>({ fetchImpl, onError });
+
+		f._internal.setQuery("x", FAKE_LOADER);
+		await f._internal.drain();
+
+		expect(onError).toHaveBeenCalledTimes(1);
+		expect((onError.mock.calls[0][0] as Error).message).toContain("500");
+		expect(f._internal.payload.value).toBeNull();
+		expect(f._internal.loading.value).toBe(false);
+
+		consoleError.mockRestore();
+	});
+
+	it("does NOT throw if onError is omitted (still console.errors)", async () => {
+		const consoleError = vi
+			.spyOn(console, "error")
+			.mockImplementation(() => {});
+		const fetchImpl = (() =>
+			Promise.reject(new Error("boom"))) as typeof fetch;
+		const f = createUseSuggestions<FakeSuggestion>({ fetchImpl });
+
+		f._internal.setQuery("x", FAKE_LOADER);
+		await expect(f._internal.drain()).resolves.toBeUndefined();
+		expect(consoleError).toHaveBeenCalled();
+		consoleError.mockRestore();
+	});
+});

package/src/sdk/useSuggestions.ts

@@ -0,0 +1,188 @@
+/**
+ * Search-suggestions hook factory.
+ *
+ * Both casaevideo-storefront and baggagio-tanstack independently
+ * invented the same shape for autocomplete-style suggestions:
+ *
+ *  - module-level signal for the current payload + loading flag
+ *  - serial in-flight queue so older requests can't race past newer ones
+ *  - "is this still the latest query?" cancel guard
+ *  - posts to `/deco/invoke/<__resolveType>` with the loader's
+ *    extra props + the live `query` string
+ *
+ * This factory is the canonical version. Sites instantiate it once
+ * at module load with their concrete suggestion type and (optionally)
+ * an `onError` hook for observability (Sentry / OpenTelemetry / etc.).
+ *
+ * Why a factory and not a plain hook:
+ *  - Each call to `createUseSuggestions()` produces an isolated
+ *    `payload` / `loading` / queue. Keeps the door open for sites
+ *    with multiple independent suggestion streams (e.g. searchbar
+ *    *and* a category-jump suggester) without globally-shared state.
+ *  - Type narrowing happens at the factory boundary, not at hook
+ *    usage — the returned `useSuggestions` is already specialised
+ *    on `T` so callers don't need to re-pass generics.
+ *  - Mirrors the existing `createUseCart` / `createUseUser` /
+ *    `createUseWishlist` factory pattern from
+ *    `@decocms/apps/vtex/hooks/*`. See
+ *    `references/platform-hooks-factories.md`.
+ */
+
+import { useCallback } from "react";
+import type { Resolved } from "../types";
+import { signal, type ReactiveSignal } from "./signal";
+
+/**
+ * Optional dependencies the factory accepts at instantiation time.
+ *
+ * Most are pure observability hooks — the factory itself runs a
+ * `console.error()` after invoking `onError`, so callers don't have
+ * to remember to forward the error to the console themselves.
+ */
+export interface UseSuggestionsOptions {
+	/**
+	 * Called once per failed fetch with the original error and the
+	 * query that triggered it. Use for Sentry / OTEL captures.
+	 *
+	 * The factory still calls `console.error` after this returns so
+	 * sites that don't wire `onError` keep the same console output.
+	 */
+	onError?: (error: unknown, query: string) => void;
+
+	/**
+	 * Override the fetch implementation. Tests pass a stub here; the
+	 * default is the global `fetch`. Production sites have no reason
+	 * to set this.
+	 */
+	fetchImpl?: typeof fetch;
+}
+
+/**
+ * Shape returned by the hook produced by `createUseSuggestions`.
+ *
+ * `loading` and `payload` are reactive signals — subscribe with
+ * `useStore()` from `@tanstack/react-store` (or read `.value`
+ * directly inside an `useEffect`).
+ */
+export interface UseSuggestionsReturn<T> {
+	loading: ReactiveSignal<boolean>;
+	payload: ReactiveSignal<T | null>;
+	/**
+	 * Trigger a suggestion fetch for `query`. Calls coalesce through
+	 * a serial promise queue, and only the *latest* query's result
+	 * is allowed to flip `loading` back to `false` — so rapid keystrokes
+	 * don't leave the UI permanently in a stale loading state.
+	 */
+	setQuery: (query: string) => void;
+}
+
+/**
+ * Returned by {@link createUseSuggestions}.
+ *
+ * `useSuggestions` is the React hook bound to this factory's state.
+ * The `_internal` field exposes the underlying signals and a non-
+ * React `setQuery` for advanced cases (SSR pre-population, unit
+ * tests, server-side warmup). Sites almost never need it.
+ */
+export interface CreateUseSuggestionsReturn<T> {
+	useSuggestions: (loader: Resolved<T | null>) => UseSuggestionsReturn<T>;
+	_internal: {
+		readonly payload: ReactiveSignal<T | null>;
+		readonly loading: ReactiveSignal<boolean>;
+		/**
+		 * Same semantics as `useSuggestions(...).setQuery`, but pure JS —
+		 * no React hook context required. Useful in unit tests and for
+		 * SSR pre-fetch helpers.
+		 */
+		setQuery: (query: string, loader: Resolved<T | null>) => void;
+		/**
+		 * Promise that resolves once every queued fetch has settled.
+		 * Tests await this to assert post-cancellation state.
+		 */
+		readonly drain: () => Promise<unknown>;
+	};
+}
+
+/**
+ * Build a typed `useSuggestions` hook bound to a private
+ * `payload` / `loading` / queue tuple. Call once per stream at
+ * module load.
+ *
+ * @example
+ *   // site/src/sdk/useSuggestions.ts
+ *   import { createUseSuggestions } from "@decocms/start/sdk/useSuggestions";
+ *   import * as Sentry from "@sentry/react";
+ *   import type { Suggestion } from "@decocms/apps/commerce/types";
+ *
+ *   export const { useSuggestions } = createUseSuggestions<Suggestion>({
+ *     onError: (err) => Sentry.captureException(err),
+ *   });
+ */
+export function createUseSuggestions<T>(
+	options: UseSuggestionsOptions = {},
+): CreateUseSuggestionsReturn<T> {
+	const payload = signal<T | null>(null);
+	const loading = signal<boolean>(false);
+	let queue: Promise<unknown> = Promise.resolve();
+	let latestQuery = "";
+
+	const fetchImpl = options.fetchImpl ?? fetch;
+	const onError = options.onError;
+
+	async function doFetch(
+		query: string,
+		resolved: Resolved<T | null>,
+	): Promise<void> {
+		if (latestQuery !== query) return;
+
+		const { __resolveType, ...extraProps } = resolved as {
+			__resolveType: string;
+			[k: string]: unknown;
+		};
+
+		try {
+			const response = await fetchImpl(`/deco/invoke/${__resolveType}`, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ query, ...extraProps }),
+			});
+			if (!response.ok) {
+				throw new Error(`Suggestions invoke failed: ${response.status}`);
+			}
+			payload.value = (await response.json()) as T | null;
+		} catch (error) {
+			onError?.(error, query);
+			console.error("[useSuggestions] fetch failed:", error);
+		} finally {
+			// Only the latest query is allowed to flip the loading flag —
+			// otherwise rapid keystrokes can leave the UI in a stale
+			// "still loading" state because an older fetch resolved last.
+			if (latestQuery === query) loading.value = false;
+		}
+	}
+
+	function setQueryImpl(query: string, loader: Resolved<T | null>): void {
+		loading.value = true;
+		latestQuery = query;
+		queue = queue.then(() => doFetch(query, loader));
+	}
+
+	function useSuggestions(loader: Resolved<T | null>): UseSuggestionsReturn<T> {
+		const setQuery = useCallback(
+			(query: string) => setQueryImpl(query, loader),
+			[loader],
+		);
+
+		return { loading, payload, setQuery };
+	}
+
+	return {
+		useSuggestions,
+		_internal: {
+			payload,
+			loading,
+			setQuery: setQueryImpl,
+			drain: () => queue,
+		},
+	};
+}