@decocms/start 2.25.0 → 2.27.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
@@ -1445,3 +1528,64 @@ What's still ahead:
 - **C8 (state persistence between migration phases)**: moderate effort, value mostly in skipping `npm install` on phase-9 retries. Polish.
 - **`vibe-dex/*` orphan branches in apps-start**: ✅ all 5 cleaned this wave.
 - **Apps registry (apps-start#18 + deco-start#81)**: defer until clear consumer.
+
+### Wave 16 (2026-05-02 — baggagio as production canary, stacked-PR pitfall RECURRENCE)
+
+User merged baggagio's PRs B1–B6 to use as guinea pig before applying the same patterns to casaevideo + lebiscuit (which ARE in production). Live validation found a critical fact: **only B1 (the bump) actually reached `main`**. PRs #13–#17 were all merged in GitHub UI but their merge commits ended up on the **previous PR's branch**, never on `main`.
+
+#### What happened (the same pitfall as Wave 8, recurring)
+
+Each PR was opened with `base = previous PR's branch`:
+
+| PR | Title | base | Merge commit landed on |
+|---|---|---|---|
+| #12 | bump 2.10→2.26 + apps 1.7→1.9 | `main` | ✅ `main` |
+| #13 | drop `src/sdk/clx.ts` | `chore/bump-deco-2.26-apps-1.9` | ❌ that branch |
+| #14 | createUseSuggestions factory | `chore/drop-local-clx` | ❌ that branch |
+| #15 | canonical `relative()` | `chore/use-framework-suggestions-factory` | ❌ that branch |
+| #16 | canonical `Picture` | `refactor/use-canonical-relative-url` | ❌ that branch |
+| #17 | drop dead `useUser` stub | `refactor/use-canonical-picture` | ❌ that branch |
+
+Each PR shows `state: MERGED` in GitHub. But the merge commit physically landed on each PR's source-branch tip, not on main. Result: all 5 cleanup PRs were silently orphaned.
+
+Detection method that worked: file-existence check on `git show main:<deleted-file>` — `clx.ts`, `url.ts`, `Picture.tsx`, `useUser.ts` were all still present on main despite their PRs being "merged". Exists/absent is a faster signal than diff browsing.
+
+#### Recovery: PR #18 — single consolidation
+
+The deepest stacked branch (`chore/drop-dead-local-useuser`) cumulatively contained all 5 cleanups (B2–B6) linearly stacked on B1. Opened [`baggagio-tanstack#18`](https://github.com/deco-sites/baggagio-tanstack/pull/18) as `chore/consolidate-b2-b6-to-main` → `main`, replaying the exact contents of #13–#17 in order. Diff vs main: **59 files changed, +70 / −240, 4 files deleted**. Typecheck + build clean. Preview at `pr-18-baggagio-tanstack.deco-cx.workers.dev` rendered identical homepage / PLP / PDP / search to current main with zero new console errors. Merged to main, deploy succeeded.
+
+#### Live validation post-merge (cumulative state on main)
+
+Tested via Playwright (cursor-ide-browser MCP) on `https://baggagio-tanstack.deco-cx.workers.dev/`:
+
+| Surface | Result | Notes |
+|---|---|---|
+| Homepage | ✅ Renders | Banner, categories, product carousel, footer all intact |
+| PLP `/s?q=mochila` | ✅ 927 produtos | Filter + sort UI present, all images load |
+| PDP `/mochila-masculina-executiva-para-notebook-horizonte/p` | ✅ Renders | Image gallery, prices, COMPRAR, frete calc, descrição all present |
+| Search suggestions endpoint | ✅ 200 | Empty `searches[]` confirmed pre-existing (matches www.bagaggio.com.br) |
+| `<picture>` HTML | ✅ 18 picture / 36 source | composable canonical pattern |
+| Console errors (filtered 3rd-party) | ✅ Same as before | `[inline-script polyfill]` + image preload warnings pre-existing on main |
+
+**Bonus discovery**: PR-B5 (canonical Picture) now correctly emits `<link rel="preload" as="image" media="(max-width: 767px)" imageSrcSet="..." fetchPriority="high">` for LCP banners — a real Web Vitals improvement that was NOT visible before the consolidation because Picture.tsx (the local wrapper without preload) was still on main.
+
+#### Each PR's safety verdict (for casaevideo + lebiscuit replay)
+
+| PR | Status | Safe to replay? |
+|---|---|---|
+| B1 — bump 2.x → 2.26 + apps 1.x → 1.9 | ✅ | YES — zero regressions on real site |
+| B2 — drop `src/sdk/clx.ts` | ✅ | YES — pure rewrite, framework export is byte-equivalent |
+| B3 — `createUseSuggestions` factory | ✅ | YES — wiring works end-to-end (200 status, payload reaches store) |
+| B4 — canonical `relative()` with `stripSearchParams` | ✅ | YES — only affects PLPs with `?skuId=` URL params, no functional regression |
+| B5 — canonical `Picture` from apps | ✅ + bonus | YES — adds proper `<link rel="preload" as="image" media>` for LCP |
+| B6 — drop dead `src/hooks/useUser.ts` | ✅ | YES — file had 0 external imports |
+
+**For casaevideo + lebiscuit**: same set of PRs is validated as safe. The replays (`C1`–`C11`, `L1`–`L11`) can proceed on production sites with confidence.
+
+### Wave 16 — discoveries
+
+- **Stacked-PR pitfall recurred even after Wave 8 documented it.** The Wave 8 mitigation ("verify base is main before merging") was not enforced; the user merged B2–B6 with original stacked bases. Stronger mitigation needed: when opening a stacked PR, **default to a single consolidating PR at the end** rather than 5 separate stacked merges. Single PR is one merge button, one CI run, one deploy — not 5 chances to mis-target the base.
+- **File-existence check is the fastest "did the merge actually land on main?" probe.** Faster than reading PR-stats, faster than diffing branches. `git show main:<deleted-file> 2>&1` — empty stderr means the deletion didn't reach main.
+- **Preview deploys via `wrangler versions upload --preview-alias` are cheap, fast (90 s), and PR-scoped.** Used `https://pr-N-baggagio-tanstack.deco-cx.workers.dev` to validate cumulative state BEFORE merging. Should be the default validation step for any consolidation PR.
+- **The canonical Picture component's per-source `<link rel="preload" as="image" media="...">` injection is a real LCP win** — but it only triggers when `<Picture preload={true}>` is set on the call site. Baggagio's `BannerCarousel.tsx` already passes `preload={lcp}` from the CMS config; the local Picture.tsx wrapper just didn't honor it. Migration to canonical IS a perf upgrade, not just a code-cleanup.
+- **Canary-driven validation matters even when the changes are mechanical.** I had high confidence the cumulative state would work (typecheck + build clean), but the live test is what surfaced the "PR-B5 actually emits preload links now" finding. Without the canary loop the perf delta would have been invisible.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.25.0",
+  "version": "2.27.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",
@@ -19,6 +19,10 @@
     "./sdk/useScript": "./src/sdk/useScript.ts",
     "./sdk/signal": "./src/sdk/signal.ts",
     "./sdk/clx": "./src/sdk/clx.ts",
+    "./sdk/cn": "./src/sdk/cn.ts",
+    "./sdk/encoding": "./src/sdk/encoding.ts",
+    "./sdk/http": "./src/sdk/http.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",
@@ -95,7 +99,9 @@
   },
   "dependencies": {
     "@deco-cx/warp-node": "^0.3.16",
+    "clsx": "^2.1.1",
     "fast-json-patch": "^3.1.0",
+    "tailwind-merge": "^3.3.1",
     "tsx": "^4.19.0",
     "ws": "^8.18.0"
   },

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/cn.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { clx, cn } from "./cn";
+
+describe("cn", () => {
+  it("joins strings", () => {
+    expect(cn("a", "b", "c")).toBe("a b c");
+  });
+
+  it("supports conditional objects", () => {
+    expect(cn("a", { b: true, c: false }, "d")).toBe("a b d");
+  });
+
+  it("filters out falsy values", () => {
+    expect(cn("a", null, undefined, false, 0 as any, "b")).toBe("a b");
+  });
+
+  it("merges conflicting Tailwind utilities (last one wins)", () => {
+    expect(cn("p-2", "p-4")).toBe("p-4");
+  });
+
+  it("merges hover variants independently from base utilities", () => {
+    expect(cn("p-2", "hover:p-4")).toBe("p-2 hover:p-4");
+  });
+});
+
+describe("clx (re-exported)", () => {
+  it("filters falsy and joins with single spaces", () => {
+    expect(clx("a", null, "b", undefined, "c")).toBe("a b c");
+  });
+
+  it("does NOT merge conflicting utilities (that's cn's job)", () => {
+    expect(clx("p-2", "p-4")).toBe("p-2 p-4");
+  });
+});

package/src/sdk/cn.ts

@@ -0,0 +1,28 @@
+/**
+ * `cn(...inputs)` — the canonical Tailwind class-name combinator
+ * (clsx + tailwind-merge). Every storefront we audited shipped a
+ * site-local copy of this; we promote it to the framework so sites
+ * can drop the duplicate.
+ *
+ * Behaviour:
+ *   - Accepts the full `clsx` input format (strings, objects, arrays,
+ *     conditionals, falsy values).
+ *   - De-duplicates conflicting Tailwind utilities via `tailwind-merge`
+ *     (e.g. `cn("p-2", "p-4")` → `"p-4"`).
+ *
+ * The simpler `clx` (no tailwind-merge, just `filter+join`) is still
+ * exported from `@decocms/start/sdk/clx` for cases where you want to
+ * keep the literal class string. Re-exported here so a single import
+ * covers both.
+ */
+
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export { clx } from "./clx";
+
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}
+
+export type { ClassValue };

package/src/sdk/cookie.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import {
+  deleteResponseCookie,
+  getCookies,
+  setResponseCookie,
+} from "./cookie";
+
+describe("getCookies", () => {
+  it("returns an empty object when no Cookie header is present", () => {
+    expect(getCookies(new Headers())).toEqual({});
+  });
+
+  it("parses a single cookie", () => {
+    const h = new Headers({ cookie: "session=abc" });
+    expect(getCookies(h)).toEqual({ session: "abc" });
+  });
+
+  it("parses multiple cookies separated by '; '", () => {
+    const h = new Headers({ cookie: "a=1; b=2; c=3" });
+    expect(getCookies(h)).toEqual({ a: "1", b: "2", c: "3" });
+  });
+
+  it("URL-decodes values", () => {
+    const h = new Headers({ cookie: "u=hello%20world" });
+    expect(getCookies(h)).toEqual({ u: "hello world" });
+  });
+
+  it("falls back to the raw value when decoding fails", () => {
+    // Lone '%' is invalid in URL encoding.
+    const h = new Headers({ cookie: "x=100%" });
+    expect(getCookies(h)).toEqual({ x: "100%" });
+  });
+
+  it("ignores entries without an '='", () => {
+    const h = new Headers({ cookie: "garbage; ok=yes" });
+    expect(getCookies(h)).toEqual({ ok: "yes" });
+  });
+
+  it("trims whitespace around names", () => {
+    const h = new Headers({ cookie: " a=1; b=2 " });
+    expect(getCookies(h)).toEqual({ a: "1", b: "2" });
+  });
+});
+
+describe("setResponseCookie", () => {
+  it("appends a Set-Cookie header with the cookie name and value", () => {
+    const h = new Headers();
+    setResponseCookie(h, { name: "session", value: "abc" });
+    expect(h.get("set-cookie")).toBe("session=abc");
+  });
+
+  it("serializes maxAge, path, secure, httpOnly, sameSite, domain", () => {
+    const h = new Headers();
+    setResponseCookie(h, {
+      name: "session",
+      value: "abc",
+      maxAge: 3600,
+      path: "/",
+      domain: "example.com",
+      secure: true,
+      httpOnly: true,
+      sameSite: "Lax",
+    });
+    const value = h.get("set-cookie")!;
+    expect(value).toContain("session=abc");
+    expect(value).toContain("Max-Age=3600");
+    expect(value).toContain("Domain=example.com");
+    expect(value).toContain("Path=/");
+    expect(value).toContain("Secure");
+    expect(value).toContain("HttpOnly");
+    expect(value).toContain("SameSite=Lax");
+  });
+
+  it("serializes expires as a UTC string", () => {
+    const h = new Headers();
+    const date = new Date("2030-01-01T00:00:00Z");
+    setResponseCookie(h, { name: "x", value: "y", expires: date });
+    expect(h.get("set-cookie")).toContain(`Expires=${date.toUTCString()}`);
+  });
+
+  it("appends multiple cookies (does not overwrite the first)", () => {
+    const h = new Headers();
+    setResponseCookie(h, { name: "a", value: "1" });
+    setResponseCookie(h, { name: "b", value: "2" });
+    // Headers.getAll isn't standard; getSetCookie() is the modern API.
+    const all = (h as any).getSetCookie?.() as string[] | undefined;
+    if (all) {
+      expect(all).toEqual(["a=1", "b=2"]);
+    } else {
+      // Fallback: the combined header value should mention both.
+      const v = h.get("set-cookie")!;
+      expect(v).toContain("a=1");
+      expect(v).toContain("b=2");
+    }
+  });
+});
+
+describe("deleteResponseCookie", () => {
+  it("emits a Set-Cookie that expires immediately", () => {
+    const h = new Headers();
+    deleteResponseCookie(h, "session", { path: "/" });
+    const value = h.get("set-cookie")!;
+    expect(value).toContain("session=");
+    expect(value).toContain("Max-Age=0");
+    expect(value).toContain(`Expires=${new Date(0).toUTCString()}`);
+    expect(value).toContain("Path=/");
+  });
+});