@decocms/start 0.39.0 → 0.40.1

package/{.cursor/skills/deco-tanstack-navigation/SKILL.md → .agents/skills/deco-to-tanstack-migration/references/navigation.md}

@@ -1,13 +1,9 @@
----
-name: deco-tanstack-navigation
-description: "Complete guide for migrating Fresh/Deno navigation to TanStack Router in Deco storefronts. Covers: replacing <a href> with <Link>, prefetch strategies for instant navigation, type-safe params, activeProps for menus, search state as URL source of truth, SSR-first SEO architecture, loaderDeps for reactive search params, form submissions via server actions, and programmatic preloading. Use when porting any Deco site from Fresh to TanStack Start."
----
 
 # Deco TanStack Navigation Migration
 
 Complete playbook for replacing Fresh/Deno navigation with TanStack Router in Deco storefronts. Goes beyond simple `<a>` to `<Link>` — covers the full power of the router to build sites that feel like native apps while keeping SSR-first SEO.
 
-## When to Use This Skill
+## When to Use This Reference
 
 - Migrating a Fresh/Deno storefront to TanStack Start
 - Links cause full page reloads instead of SPA transitions
@@ -668,14 +664,3 @@ rg '<form[^>]*action=' src/ --glob '*.tsx' | rg -v 'onSubmit'
 | No prefetch | `preload="intent"` | Data ready before click |
 | `req.url` in loader | `loaderDeps + deps.search` | Reactive to URL changes |
 | `router.push(url)` | `router.preloadRoute + navigate` | Preload then navigate |
-
----
-
-## Related Skills
-
-| Skill | Purpose |
-|-------|---------|
-| `deco-to-tanstack-migration` | Full migration playbook (imports, signals, framework) |
-| `deco-islands-migration` | Eliminating the islands/ directory |
-| `deco-tanstack-storefront-patterns` | Runtime patterns and fixes post-migration |
-| `deco-storefront-test-checklist` | Context-aware QA checklist generation |

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

@@ -0,0 +1,154 @@
+# Platform Hooks Migration
+
+Platform hooks (useCart, useUser, useWishlist) are the most complex migration target because they have real business logic.
+
+## Strategy
+
+All hooks are **site-local**. No Vite alias tricks. No compat layers.
+
+- Active platform hooks (VTEX for this store) -> `~/hooks/useCart.ts` with real implementation
+- Inactive platform hooks (Wake, Shopify, etc.) -> `~/hooks/platform/{name}.ts` with no-op stubs
+- Auth hooks -> `~/hooks/useUser.ts`, `~/hooks/useWishlist.ts`
+
+## VTEX useCart (Real Implementation)
+
+### Why Server Functions Are Required
+
+The storefront domain (e.g., `my-store.deco.site`) differs from the VTEX checkout domain (`account.vtexcommercestable.com.br`). Direct browser `fetch()` calls are blocked by CORS. Additionally, VTEX API credentials (`AppKey`/`AppToken`) must stay server-side.
+
+Use TanStack Start `createServerFn` to create server-side proxy functions that the client hook calls transparently.
+
+### Server Functions (~/lib/vtex-cart-server.ts)
+
+```typescript
+import { createServerFn } from "@tanstack/react-start";
+
+const ACCOUNT = "myaccount";
+const API_KEY = process.env.VTEX_APP_KEY!;
+const API_TOKEN = process.env.VTEX_APP_TOKEN!;
+
+export const getOrCreateCart = createServerFn({ method: "GET" })
+  .validator((orderFormId: string) => orderFormId)
+  .handler(async ({ data: orderFormId }) => {
+    const url = orderFormId
+      ? `https://${ACCOUNT}.vtexcommercestable.com.br/api/checkout/pub/orderForm/${orderFormId}`
+      : `https://${ACCOUNT}.vtexcommercestable.com.br/api/checkout/pub/orderForm`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-VTEX-API-AppKey": API_KEY,
+        "X-VTEX-API-AppToken": API_TOKEN,
+      },
+      body: JSON.stringify({ expectedOrderFormSections: ["items", "totalizers", "shippingData", "clientPreferencesData", "storePreferencesData", "marketingData"] }),
+    });
+    return res.json();
+  });
+
+export const addItemsToCart = createServerFn({ method: "POST" })
+  .validator((data: { orderFormId: string; items: any[] }) => data)
+  .handler(async ({ data }) => {
+    const res = await fetch(
+      `https://${ACCOUNT}.vtexcommercestable.com.br/api/checkout/pub/orderForm/${data.orderFormId}/items`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "X-VTEX-API-AppKey": API_KEY, "X-VTEX-API-AppToken": API_TOKEN },
+        body: JSON.stringify({ orderItems: data.items }),
+      },
+    );
+    return res.json();
+  });
+
+export const updateCartItems = createServerFn({ method: "POST" })
+  .validator((data: { orderFormId: string; items: any[] }) => data)
+  .handler(async ({ data }) => {
+    const res = await fetch(
+      `https://${ACCOUNT}.vtexcommercestable.com.br/api/checkout/pub/orderForm/${data.orderFormId}/items/update`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "X-VTEX-API-AppKey": API_KEY, "X-VTEX-API-AppToken": API_TOKEN },
+        body: JSON.stringify({ orderItems: data.items }),
+      },
+    );
+    return res.json();
+  });
+```
+
+### Hook (~/hooks/useCart.ts)
+
+Key design decisions:
+- **Module-level singleton state** shared across all component instances
+- **Pub/sub pattern** (`_listeners` Set) for notifying React components of changes
+- **Cookie-based session**: reads/writes `checkout.vtex.com__orderFormId` on the **client** side (not VTEX's domain cookie)
+- Returns `cart` and `loading` with `.value` getter/setter for backward compat with Preact-era components
+- Lazy initialization: cart is fetched on first component mount, not on module load
+- Exports `itemToAnalyticsItem` for cart-specific analytics mapping
+
+### Cross-Domain Checkout
+
+The minicart's "Finalizar Compra" button must link to the VTEX checkout domain with the `orderFormId` as a query parameter — the VTEX domain can't read the storefront's cookies:
+
+```typescript
+const checkoutUrl = `https://secure.${STORE_DOMAIN}/checkout/?orderFormId=${orderFormId}`;
+```
+
+### VTEX Types (~/types/vtex.ts)
+
+Site-local types for VTEX-specific structures:
+- `OrderFormItem`, `SimulationOrderForm`, `Sla`, `SKU`, `VtexProduct`
+
+## Inactive Platform Stubs
+
+For non-VTEX platforms, create minimal no-op files:
+
+```typescript
+// ~/hooks/platform/wake.ts
+export function useCart() {
+  return {
+    cart: { value: null },
+    loading: { value: false },
+    addItem: async (_params: any) => {},
+    updateItems: async (_params: any) => {},
+    removeItem: async (_index: any) => {},
+  };
+}
+
+export function useUser() {
+  return {
+    user: { value: null as { email?: string; name?: string } | null },
+    loading: { value: false },
+  };
+}
+
+export function useWishlist() {
+  return {
+    loading: { value: false },
+    addItem: async (_props: any) => {},
+    removeItem: async (_props: any) => {},
+    getItem: (_props: any) => undefined as any,
+  };
+}
+```
+
+Create similar stubs for: `shopify.ts`, `linx.ts`, `vnda.ts`, `nuvemshop.ts`.
+
+Match the return shape to what each platform's AddToCartButton expects (some use `addItem`, others `addItems`).
+
+## Import Rewrites
+
+```bash
+sed -i '' 's|from "apps/vtex/hooks/useCart.ts"|from "~/hooks/useCart"|g'
+sed -i '' 's|from "apps/vtex/hooks/useUser.ts"|from "~/hooks/useUser"|g'
+sed -i '' 's|from "apps/vtex/hooks/useWishlist.ts"|from "~/hooks/useWishlist"|g'
+sed -i '' 's|from "apps/vtex/utils/types.ts"|from "~/types/vtex"|g'
+sed -i '' 's|from "apps/shopify/hooks/useCart.ts"|from "~/hooks/platform/shopify"|g'
+sed -i '' 's|from "apps/wake/hooks/useCart.ts"|from "~/hooks/platform/wake"|g'
+# etc. for all platforms
+```
+
+## Verification
+
+```bash
+grep -r 'from "apps/' src/ --include='*.ts' --include='*.tsx'
+# Should return ZERO matches
+```

package/.agents/skills/deco-to-tanstack-migration/references/react-hooks-patterns.md

@@ -0,0 +1,142 @@
+# React Hooks Patterns
+
+> useEffect anti-patterns, useQuery, useMemo, lazy useState, Rules of Hooks.
+
+
+## 2. useEffect Doesn't Run on Server
+
+Components relying on `useEffect` to populate state will render empty on SSR.
+
+**Fix**: Use TanStack route loaders or section loaders for server-side data.
+
+
+## 33. usePartialSection is a No-Op
+
+**Severity**: HIGH — tab switching, filter toggling, any partial section re-render breaks silently
+
+Deco's `usePartialSection` hook re-renders a section with new props by making a server request for just that section's HTML. In the React port, this mechanism doesn't exist — `usePartialSection` returns empty data attributes.
+
+**Symptom**: Tabbed product shelves only show the first tab. Clicking other tabs does nothing. Filter visibility toggles don't work. Any component using `usePartialSection` for dynamic props appears frozen.
+
+**Fix**: Replace with React `useState` for client-side state switching. If all tab data is already loaded server-side (common for tabbed shelves where the loader fetches all tabs), just switch between the data client-side:
+
+```typescript
+// Before: relies on usePartialSection to re-render with new tabIndex
+<button {...usePartialSection({ props: { tabIndex: i } })}>
+
+// After: React state-driven tab switching
+const [activeTab, setActiveTab] = useState(0);
+<button onClick={() => setActiveTab(i)}>
+// Then render tabs[activeTab].products instead of tabs[tabIndex].products
+```
+
+For filter toggles, replace `usePartialSection({ props: { openFilter: !openFilter } })` with `useState`:
+```typescript
+const [openFilter, setOpenFilter] = useState(true);
+<button onClick={() => setOpenFilter(!openFilter)}>
+```
+
+
+## 46. useEffect for Client-Side Data Fetching → useQuery
+
+**Severity**: LOW (correctness) / MEDIUM (UX) — `useEffect` fetches are error-prone, miss loading/error states, and don't cache results.
+
+`useEffect` is correct ONLY for true side effects (localStorage reads, subscriptions, DOM manipulation). For any data fetch that runs client-side, `@tanstack/react-query` (already installed) is the right tool.
+
+**Pattern to replace**:
+```tsx
+const [loading, setLoading] = useState(true);
+const [error, setError] = useState(false);
+
+useEffect(() => {
+  if (!condition) { setLoading(true); return; }
+  if (dependency) {
+    fetch(...)
+      .then(res => setError(res.error))
+      .catch(console.error)
+      .finally(() => setLoading(false));
+    return;
+  }
+  setLoading(false);
+}, [condition]);
+```
+
+**Replace with**:
+```tsx
+import { useQuery } from "@tanstack/react-query";
+
+const { isFetching, data } = useQuery({
+  queryKey: ["key", dependency],
+  queryFn: () => fetch(...),
+  enabled: condition && !!dependency,
+  staleTime: 0, // use when result should never be cached (e.g. "can user act today?")
+});
+
+const loading = isFetching;
+const error = data?.error ?? false;
+```
+
+**Important distinction**: `useEffect` that reads `localStorage` on mount (once, no fetch) should stay as `useEffect`. Only replace fetches.
+
+**When ops are mixed** (e.g., initial check + later mutation both affect `loading`/`error`): split into separate states:
+- `useQuery` owns check-loading/check-error
+- `useState` owns action-loading/action-error (spin, submit, etc.)
+- Derive the final values: `const loading = canSpinFetching || spinLoading`
+
+**`QueryClientProvider` must be in the tree** — already set in `__root.tsx` via `QueryClient` with `staleTime: 30_000` default.
+
+
+## 47. useEffect Data Fetches That Should NOT Be Replaced with useQuery
+
+**Severity**: LOW — knowing what NOT to touch is as important as knowing what to replace.
+
+After auditing all `useEffect` data fetches in a migrated storefront, three categories resist `useQuery`:
+
+### ❌ DOM Side Effects Mixed With Fetch
+
+```tsx
+// SponsoredBannerHero.tsx — fetch result triggers createRoot + DOM events
+useEffect(() => {
+  invoke.site.loaders.sponsoredTopsort.sponsoredTopsort(params)
+    .then(response => {
+      createRoot(slot).render(<HeroContent banner={hero} />); // imperative DOM
+      root.dispatchEvent(new CustomEvent("sliderGoToIndex", ...));
+    });
+  return () => { createRoot(slot).render(null); }; // cleanup
+}, [query, rootId, ...]);
+```
+
+The effect has cleanup logic and imperative DOM manipulation. `useQuery` only manages data — the DOM side effects still need `useEffect`. Refactoring would require separating fetch from DOM manipulation, which changes the architecture. Leave as-is.
+
+### ❌ Paginated / Accumulating Data
+
+```tsx
+// MyOrdersListPage.tsx — appends pages, doesn't replace
+useEffect(() => {
+  getOrderingOrders(currentCursor); // pushes to existing array
+}, [currentCursor]);
+
+async function getOrderingOrders(cursor) {
+  setOrdersWithStatus(prev => [...prev, ...orders.data.orderingOrders]); // accumulate
+}
+```
+
+`useQuery` replaces data on each fetch. Accumulation requires `useInfiniteQuery`. Converting is a larger refactor and changes the UX (load-more vs infinite scroll semantics). Leave as-is unless doing a full pagination refactor.
+
+### ❌ useReducer State (Complex Orchestration)
+
+```tsx
+// OurStores.tsx — all state managed via dispatch
+useEffect(() => {
+  dispatch({ type: "SET_LOADING", payload: true });
+  invoke.site.actions.getStores()
+    .then(data => dispatch({ type: "SET_ALL_STORES", payload: data }))
+    .finally(() => dispatch({ type: "SET_LOADING", payload: false }));
+}, []);
+```
+
+`useQuery` provides its own loading/data/error state. Integrating it with `useReducer` requires syncing query state → reducer state via another `useEffect`, which defeats the purpose. Options: (1) leave as-is, (2) migrate the whole component from `useReducer` to query + local `useState`.
+
+---
+
+**Rule of thumb**: Replace `useEffect` with `useQuery` only when the ONLY job of the effect is "fetch data → set state". If the effect also mutates the DOM, accumulates into existing state, or is tightly coupled to `useReducer`, leave it alone.

package/.agents/skills/deco-to-tanstack-migration/references/react-signals-state.md

@@ -0,0 +1,72 @@
+# React Signals & State (TanStack Store)
+
+> Signal .value subscriptions, @tanstack/react-store, subscribe() API.
+
+
+## 3. Signal .value in Render Doesn't Re-render
+
+Reading `signal.value` inside React render doesn't create a subscription.
+
+**Fix**: Use `useStore(signal.store)` from `@tanstack/react-store` for reactive reads.
+
+
+## 19. @tanstack/store subscribe() Returns Object, Not Function
+
+**Severity: CRITICAL** -- This causes cascading failures across the entire page.
+
+`@tanstack/store@0.9.x`'s `Store.subscribe()` returns `{ unsubscribe: Function }`, NOT a plain function. React's `useSyncExternalStore` (and `useEffect` cleanup) expect the subscribe callback to return a bare unsubscribe function. Passing the object through causes:
+
+1. "TypeError: destroy_ is not a function" (non-minified) / "TypeError: J is not a function" (minified)
+2. Which cascades into React #419 (hydration failure)
+3. Which cascades into React #130 (undefined component after hydration bailout)
+4. Which makes the entire page non-interactive (0 interactive elements)
+
+**Symptom**: Page SSR renders fine, but client shows "J is not a function" repeating hundreds of times. All interactive elements stop working.
+
+**Fix**: Unwrap the return value in your `Signal.subscribe()` implementation:
+
+```typescript
+subscribe(fn) {
+  const sub = store.subscribe(() => fn());
+  return typeof sub === "function" ? sub : sub.unsubscribe;
+},
+```
+
+
+## 38. Signal Shim Doesn't Auto-Trigger React Re-renders
+
+**Severity**: HIGH — drawers don't open, cart badge doesn't update, any signal-driven UI appears frozen
+
+The Preact-to-React signal compat shim has a pub/sub pattern (`_listeners`), but reading `signal.value` in a React render function creates NO subscription. React components don't re-render when the signal changes.
+
+**Symptom**: Setting `displayCart.value = true` doesn't open the cart drawer. Cart item count badge stays at 0 after adding items. Menu drawer toggle does nothing.
+
+**Root cause**: In Preact, `@preact/signals` automatically tracks signal reads in render and re-renders. The shim just has get/set on `.value` with manual `_listeners` — React has no awareness of it.
+
+**Fix (recommended)**: Use `useStore` from `@tanstack/react-store` for components that need reactive reads:
+
+```typescript
+import { useStore } from "@tanstack/react-store";
+const { displayCart } = useUI();
+const open = useStore(displayCart.store);  // auto re-renders on change
+```
+
+**Fix (interim)**: For components not yet migrated to `useStore`, bridge with `useState` + `useEffect`:
+
+```typescript
+const { displayCart } = useUI();
+const [open, setOpen] = useState(displayCart.value);
+useEffect(() => {
+  const unsub = displayCart.subscribe(() => setOpen(displayCart.value));
+  return unsub;
+}, []);
+```
+
+**Fix (DaisyUI drawers)**: Since DaisyUI drawers are checkbox-driven, directly toggle the DOM checkbox as a pragmatic workaround:
+
+```typescript
+const toggleDrawer = (id: string, open: boolean) => {
+  const checkbox = document.getElementById(id) as HTMLInputElement;
+  if (checkbox) checkbox.checked = open;
+};
+```

package/{.cursor/skills/deco-tanstack-search/SKILL.md → .agents/skills/deco-to-tanstack-migration/references/search.md}

@@ -1,13 +1,9 @@
----
-name: deco-tanstack-search
-description: Implement and debug search functionality in Deco storefronts on TanStack Start. Covers the full search data flow from SearchBar to VTEX Intelligent Search API, including URL parameter propagation, CMS page resolution, filter toggling, pagination, and common pitfalls.
----
 
 # Deco TanStack Search
 
 Complete reference for implementing search in Deco storefronts running on TanStack Start / React / Cloudflare Workers.
 
-## When to Use This Skill
+## When to Use This Reference
 
 - Implementing or debugging search (`/s?q=...`) pages
 - Fixing "search returns no results" or "search page shows 404"
@@ -390,14 +386,6 @@ TanStack Router's `search` is a plain `Record<string, string>` — it **cannot r
 
 **Sort** (single key) can safely use `navigate({ search })` since there are no duplicate keys.
 
-## Related Skills
-
-- `deco-tanstack-storefront-patterns` — General runtime patterns for TanStack storefronts
-- `deco-apps-vtex-porting` — Full guide for porting VTEX loaders to apps-start
-- `deco-tanstack-navigation` — Navigation patterns including Link, prefetch, search params
-- `deco-tanstack-hydration-fixes` — Fixing hydration and flash-of-white issues
-- `deco-cms-route-config` — Deep dive into cmsRouteConfig and route helpers
-
 ## Files Reference
 
 | File | Layer | Purpose |

package/.agents/skills/deco-to-tanstack-migration/references/signals/README.md

@@ -0,0 +1,220 @@
+# @preact/signals -> TanStack Store Migration
+
+Two distinct patterns need different handling.
+
+## Pattern A: Component Hooks (useSignal, useComputed)
+
+These are component-local state. Replace with React hooks directly.
+
+### useSignal -> useState
+
+```typescript
+// OLD
+import { useSignal } from "@preact/signals";
+const loading = useSignal(false);
+loading.value = true;          // write
+if (loading.value) { ... }     // read
+
+// NEW
+import { useState } from "react";
+const [loading, setLoading] = useState(false);
+setLoading(true);              // write
+if (loading) { ... }           // read
+```
+
+Setter naming convention: `set` + capitalized variable name.
+
+### useComputed -> useMemo
+
+```typescript
+// OLD
+import { useComputed } from "@preact/signals";
+const isValid = useComputed(() => name.value.length > 0);
+return <div>{isValid.value}</div>;
+
+// NEW
+import { useMemo } from "react";
+const isValid = useMemo(() => name.length > 0, [name]);
+return <div>{isValid}</div>;
+```
+
+### Automation Tips
+
+- `useSignal`/`useComputed` changes are NOT safe for bulk sed (variable names, setter names, `.value` removal all differ per file)
+- Process each file individually: read, identify variable names, transform
+- Watch for: toggle patterns (`x.value = !x.value` -> `setX(prev => !prev)`), object state, conditional assignments
+
+## Pattern B: Module-Level Signals (Global State)
+
+These create shared state across components. Use `@tanstack/store`.
+
+### Create ~/sdk/signal.ts
+
+```typescript
+import { Store } from "@tanstack/store";
+import { useSyncExternalStore, useMemo } from "react";
+
+export interface Signal<T> {
+  readonly store: Store<T>;
+  value: T;
+  peek(): T;
+  subscribe(fn: () => void): () => void;
+}
+
+export function signal<T>(initialValue: T): Signal<T> {
+  const store = new Store<T>(initialValue);
+  return {
+    store,
+    get value() { return store.state; },
+    set value(v: T) { store.setState(() => v); },
+    peek() { return store.state; },
+    subscribe(fn) {
+      // CRITICAL: @tanstack/store@0.9.x returns { unsubscribe: Function },
+      // NOT a plain function. React's useSyncExternalStore and useEffect
+      // cleanup both expect a bare function. Passing the object causes
+      // "TypeError: destroy_ is not a function" at runtime.
+      const sub = store.subscribe(() => fn());
+      return typeof sub === "function" ? sub : sub.unsubscribe;
+    },
+  };
+}
+
+export function useSignal<T>(initialValue: T): Signal<T> {
+  const sig = useMemo(() => signal(initialValue), []);
+  useSyncExternalStore(
+    (cb) => sig.subscribe(cb),
+    () => sig.value,
+    () => sig.value,
+  );
+  return sig;
+}
+
+export function useComputed<T>(fn: () => T): Signal<T> {
+  const sig = useMemo(() => signal(fn()), []);
+  return sig;
+}
+
+export function computed<T>(fn: () => T): Signal<T> {
+  return signal(fn());
+}
+
+export function effect(fn: () => void | (() => void)): () => void {
+  const cleanup = fn();
+  return typeof cleanup === "function" ? cleanup : () => {};
+}
+
+export function batch(fn: () => void): void {
+  fn();
+}
+
+export function useSignalEffect(fn: () => void | (() => void)): void {
+  fn();
+}
+
+export type { Signal as ReadonlySignal };
+```
+
+> **WARNING**: The `subscribe()` unwrapping is the single most critical line in
+> this file. Without it, every component using `useSignal` will crash with
+> "TypeError: J is not a function" (minified) or "TypeError: destroy_ is not a
+> function" (non-minified), which then cascades into React #419 hydration
+> failures and #130 undefined component errors across the entire page.
+
+### Replace Imports
+
+```bash
+# Safe for bulk sed
+sed -i '' 's|from "@preact/signals"|from "~/sdk/signal"|g'
+```
+
+### React Subscriptions
+
+The signal shim's `.value` getter/setter does NOT create automatic React subscriptions. Reading `signal.value` during render won't re-render when the signal changes. This is the #1 source of "it works in Preact but not React" bugs.
+
+Replace manual useEffect+subscribe boilerplate with `useStore`:
+
+```typescript
+// OLD (manual subscription -- works but verbose)
+const { displayCart } = useUI();
+const [open, setOpen] = useState(false);
+useEffect(() => {
+  setOpen(displayCart.value);
+  return displayCart.subscribe(() => setOpen(displayCart.value));
+}, []);
+
+// NEW (useStore from @tanstack/react-store -- recommended)
+import { useStore } from "@tanstack/react-store";
+const { displayCart } = useUI();
+const open = useStore(displayCart.store);
+```
+
+Write-only consumers (event handlers) don't need `useStore`:
+```typescript
+// This still works -- .value setter backed by TanStack Store
+onClick={() => { displayCart.value = true; }}
+```
+
+### DaisyUI Drawer Workaround
+
+DaisyUI drawers use a hidden checkbox to toggle visibility. Since signal changes don't trigger React re-renders, the checkbox `checked` attribute never updates. Pragmatic workaround: directly toggle the DOM checkbox alongside the signal:
+
+```typescript
+// After setting the signal, also toggle the drawer checkbox
+displayCart.value = true;
+const checkbox = document.getElementById("cart-drawer") as HTMLInputElement;
+if (checkbox) checkbox.checked = true;
+```
+
+This is an interim pattern until all signal consumers use `useStore`. The `useStore` approach is the proper fix because it makes the Drawer component re-render, which updates the checkbox `checked` prop through React.
+
+### Global State Hook Pattern (useCart, useUI)
+
+Hooks that manage global state (cart, UI drawers) need module-level singleton state with a subscription mechanism. The pattern:
+
+```typescript
+let _state: CartData | null = null;
+const _listeners = new Set<() => void>();
+
+function notify() { _listeners.forEach((fn) => fn()); }
+
+export function useCart() {
+  const [, forceUpdate] = useState(0);
+
+  useEffect(() => {
+    const listener = () => forceUpdate((n) => n + 1);
+    _listeners.add(listener);
+    return () => { _listeners.delete(listener); };
+  }, []);
+
+  return {
+    cart: {
+      get value() { return _state; },
+      set value(v) { _state = v; notify(); },
+    },
+    // ... methods that update _state and call notify()
+  };
+}
+```
+
+Every component calling `useCart()` subscribes to changes, and state updates trigger re-renders across all subscribers. This replaces the Preact signals global reactivity.
+
+## Signal Type References
+
+If components use `Signal<T>` as a prop type:
+
+```typescript
+// OLD
+import { Signal } from "@preact/signals";
+interface Props { quantity: Signal<number>; }
+
+// NEW
+import type { ReactiveSignal } from "~/sdk/signal";
+interface Props { quantity: ReactiveSignal<number>; }
+```
+
+## Verification
+
+```bash
+grep -r '@preact/signals' src/ --include='*.ts' --include='*.tsx'
+# Should return ZERO matches
+```