@decocms/start 2.22.0 → 2.24.0

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

@@ -43,7 +43,7 @@ Each phase has entry/exit criteria. Follow in order. Automation % indicates how
 | [2](#phase-2--signals--state) | Signals & State | ~50% | `references/signals/` |
 | [3](#phase-3--deco-framework) | Deco Framework Elimination | ~80% | `references/deco-framework/` |
 | [4](#phase-4--commerce--types) | Commerce Types & UI | ~70% | `references/commerce/` |
-| [5](#phase-5--platform-hooks) | Platform Hooks | 0% | `references/platform-hooks/` |
+| [5](#phase-5--platform-hooks) | Platform Hooks (factories, W12+) | template | `references/platform-hooks-factories.md` |
 | [6](#phase-6--islands-elimination) | Islands Elimination | ~60% | `references/islands.md` |
 | [7](#phase-7--section-registry) | Section Registry & Setup | 0% | `references/async-rendering.md` |
 | [8](#phase-8--routes--cms) | Routes & CMS | template | `references/navigation.md` |
@@ -152,14 +152,18 @@ See: `references/commerce/README.md`, `references/vtex-commerce.md`
 
 **Entry**: Phase 4 complete
 
-**Actions** (manual implementation):
-1. Create `src/hooks/useCart.ts` — module-level singleton + listener pattern
-2. Create `src/hooks/useUser.ts`, `src/hooks/useWishlist.ts` (stubs or real)
-3. Wire VTEX API calls via `@decocms/apps` invoke functions
+**Actions (Wave 12+ factory-based — current)**:
+1. `src/hooks/useCart.ts` — 5-line shim around `createUseCart` from `@decocms/apps/vtex/hooks/createUseCart`
+2. `src/hooks/useUser.ts` — 5-line shim around `createUseUser`
+3. `src/hooks/useWishlist.ts` — 5-line shim around `createUseWishlist`
+4. The migration template (`scripts/migrate/templates/hooks.ts`) emits all three for VTEX sites automatically.
+
+For non-VTEX platforms, scaffold no-op stubs using `@decocms/start/sdk/signal` (see factories doc § "Non-VTEX platforms").
 
 **Exit**: Cart add/remove works, no `apps/{platform}/hooks` imports
 
-See: `references/platform-hooks/README.md`
+See: `references/platform-hooks-factories.md` (canonical, Wave 12+).
+Pre-W12 manual approach is preserved at `references/platform-hooks/README.md` for sites that haven't migrated to factories yet.
 
 ---
 
@@ -356,7 +360,8 @@ For sites with 100+ sections:
 | Signals → TanStack Store | `references/signals/` |
 | Deco framework elimination | `references/deco-framework/` |
 | Commerce & widget types | `references/commerce/` |
-| Platform hooks (VTEX) | `references/platform-hooks/` |
+| Platform hooks (VTEX, factories — Wave 12+) | `references/platform-hooks-factories.md` |
+| Platform hooks (manual, legacy pre-W12) | `references/platform-hooks/README.md` |
 | Vite configuration | `references/vite-config/` |
 | Automation commands | `references/codemod-commands.md` |
 | Islands elimination | `references/islands.md` |

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

@@ -1,16 +1,29 @@
-# Platform Hooks Migration
+# Platform Hooks Migration (legacy reference)
 
-Platform hooks (useCart, useUser, useWishlist) are the most complex migration target because they have real business logic.
+> **This document describes the pre-Wave-12 manual approach.** New
+> migrations should follow
+> [`platform-hooks-factories.md`](../platform-hooks-factories.md), which
+> covers the `createUseCart` / `createUseUser` / `createUseWishlist`
+> factories from `@decocms/apps/vtex/hooks`. The factories collapse
+> everything below into a 5-line site shim per hook.
+>
+> This file is kept for sites that scaffolded before the factories
+> existed — typically sites with `src/lib/vtex-cart-server.ts` or
+> hand-rolled `createServerFn` calls to VTEX endpoints inside
+> `src/hooks/useCart.ts`. See the **"Migrating off the manual approach"**
+> section in the new doc for the cleanup playbook.
 
-## Strategy
+---
+
+## Strategy (legacy)
 
 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`
+- 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)
+## VTEX useCart (Manual Implementation)
 
 ### Why Server Functions Are Required
 
@@ -18,7 +31,7 @@ The storefront domain (e.g., `my-store.deco.site`) differs from the VTEX checkou
 
 Use TanStack Start `createServerFn` to create server-side proxy functions that the client hook calls transparently.
 
-### Server Functions (~/lib/vtex-cart-server.ts)
+### Server Functions (`~/lib/vtex-cart-server.ts`)
 
 ```typescript
 import { createServerFn } from "@tanstack/react-start";
@@ -40,50 +53,46 @@ export const getOrCreateCart = createServerFn({ method: "GET" })
         "X-VTEX-API-AppKey": API_KEY,
         "X-VTEX-API-AppToken": API_TOKEN,
       },
-      body: JSON.stringify({ expectedOrderFormSections: ["items", "totalizers", "shippingData", "clientPreferencesData", "storePreferencesData", "marketingData"] }),
+      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)
+> **Don't write code like this in new sites.** The factories already wrap
+> all canonical VTEX action endpoints (cart, session, masterdata,
+> newsletter, checkout) in `@decocms/apps/vtex/actions/*`. The migration
+> template scaffolds `src/server/invoke.gen.ts` which exposes them as
+> typed server functions; `~/server/invoke.ts` then re-exports them
+> under `invoke.vtex.actions.*`. The factory consumes that surface and
+> returns the legacy hook shape.
 
-Key design decisions:
+### Hook (`~/hooks/useCart.ts`)
+
+Key design decisions of the legacy manual hook:
 - **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)
+- **Cookie-based session**: reads/writes `checkout.vtex.com__orderFormId` on the **client** side
 - 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
 
+The factory in `@decocms/apps/vtex/hooks/createUseCart` ships *exactly*
+these semantics — that's the implementation behind the new shim. If your
+site needs to extend behaviour (e.g. extra analytics events, custom
+post-add hooks), prefer wrapping the factory's exports rather than
+forking back to a manual hook; the factory leaves space for that
+without giving up the upgrade path.
+
 ### 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:
@@ -92,10 +101,8 @@ The minicart's "Finalizar Compra" button must link to the VTEX checkout domain w
 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`
+This pattern is unchanged by the factory — it's a UI concern, not a hook
+concern. Implement it in your minicart component as before.
 
 ## Inactive Platform Stubs
 
@@ -130,9 +137,13 @@ export function useWishlist() {
 }
 ```
 
-Create similar stubs for: `shopify.ts`, `linx.ts`, `vnda.ts`, `nuvemshop.ts`.
+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`).
 
-Match the return shape to what each platform's AddToCartButton expects (some use `addItem`, others `addItems`).
+The factory equivalent for non-VTEX sites is documented in
+[`platform-hooks-factories.md` § "Non-VTEX platforms"](../platform-hooks-factories.md#non-vtex-platforms).
+Until each platform has its own factory in `@decocms/apps`, the stub
+shape above is still correct — but use `@decocms/start/sdk/signal`
+instead of hand-rolled `{ value: ... }` objects.
 
 ## Import Rewrites
 
@@ -143,7 +154,6 @@ 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

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

@@ -0,0 +1,186 @@
+# Platform Hooks — Factory Pattern
+
+> **Canonical reference for `createUseCart` / `createUseUser` /
+> `createUseWishlist` from `@decocms/apps/vtex/hooks`.** These factories
+> ship the legacy invoke-based hook semantics that migrated Fresh sites
+> depend on — module-level singleton state, listener-based re-render,
+> awaitable async actions, signal-shaped accessors. Sites consume them
+> as 5-line shims.
+
+This doc replaces the pre-W12 "manual `createServerFn` per VTEX endpoint"
+approach in
+[`platform-hooks/README.md`](./platform-hooks/README.md). If you scaffolded
+a site before Wave 12 (≤ `@decocms/apps@2.x` / `@decocms/start@2.18`), see
+"Migrating off the manual approach" at the bottom.
+
+---
+
+## What the factories own
+
+| Concern | Where it lives |
+|---|---|
+| Module-level singleton state (`cart`, `user`, `wishlist`) | Inside the factory closure |
+| `useEffect` + `forceRender(c => c + 1)` re-render pattern | Factory |
+| Signal-shaped accessors (`cart.value`, `user.value`) | Factory |
+| Awaitable mutations (`await addItem(...)`) | Factory |
+| `itemToAnalyticsItem` helper (cart) | Factory |
+| Wishlist arg swap (`productId` ↔ `productGroupId`) | Factory |
+| **VTEX HTTP calls** | NOT in the factory — provided by the `invoke` proxy you pass in |
+
+The factory only wires state + listeners. The site provides an `invoke`
+object whose shape is structurally typed against
+`CreateUseCartInvoke` / `CreateUseUserInvoke` / `CreateUseWishlistInvoke`
+(exported next to each factory). The migration template generates an
+`invoke` proxy in `src/server/invoke.ts` that meets all three shapes
+without any extra wiring.
+
+---
+
+## Site-local shim (the entire file)
+
+### `src/hooks/useCart.ts`
+
+```ts
+import { createUseCart } from "@decocms/apps/vtex/hooks/createUseCart";
+import { invoke } from "~/server/invoke";
+
+export type { OrderForm, OrderFormItem } from "@decocms/apps/vtex/types";
+
+export const { useCart, resetCart, itemToAnalyticsItem } = createUseCart({
+  invoke,
+});
+```
+
+### `src/hooks/useUser.ts`
+
+```ts
+import { createUseUser } from "@decocms/apps/vtex/hooks/createUseUser";
+import { invoke } from "~/server/invoke";
+
+export type { Person } from "@decocms/apps/vtex/loaders/user";
+
+export const { useUser, resetUser } = createUseUser({ invoke });
+```
+
+### `src/hooks/useWishlist.ts`
+
+```ts
+import { createUseWishlist } from "@decocms/apps/vtex/hooks/createUseWishlist";
+import { invoke } from "~/server/invoke";
+
+export type { WishlistItem } from "@decocms/apps/vtex/loaders/wishlist";
+
+export const { useWishlist, resetWishlist } = createUseWishlist({ invoke });
+```
+
+That's the whole hook — no `createServerFn`, no VTEX URLs, no `AppKey`
+plumbing. `npm run migrate` scaffolds these three files automatically
+when `--platform vtex` is set; if you regenerate, the migration template
+in `scripts/migrate/templates/hooks.ts` is the source of truth.
+
+---
+
+## Why a factory and not a single hook?
+
+> Two reasons that come up repeatedly when reviewing migration PRs.
+
+1. **`useCart` already exists in apps.** The canonical `vtex/hooks/useCart.ts`
+   is built on TanStack Query and exposes the `Minicart` shape — that is
+   the shape new code should target. The factory exists strictly so
+   already-migrated UIs keep working without a rewrite. Both can coexist
+   in one site.
+2. **Singletons can't live in a shared package without leaking across
+   sites.** The factory call instantiates a fresh module-level state per
+   site. Importing `useCart` directly from apps would share state across
+   any sites that ran in the same Worker (matters less in practice, but
+   it's the architectural reason the factory exists).
+
+The factory boundary is also the seam where we'd later wire
+`@tanstack/store` if we wanted to — the API shape is signal-compatible
+already.
+
+---
+
+## Non-VTEX platforms
+
+Sites that target Wake / Shopify / VNDA / Linx / Nuvemshop still need a
+hook surface that AddToCartButtons can consume. Until each platform has
+its own factory in `@decocms/apps`, scaffold a no-op shim:
+
+```ts
+// src/hooks/useCart.ts (custom platform)
+import { signal } from "@decocms/start/sdk/signal";
+
+const cart = signal<unknown>(null);
+const loading = signal(false);
+
+export function useCart() {
+  return {
+    cart,
+    loading,
+    async getCart() {
+      // TODO: call your platform's cart API via ~/server/invoke
+      return null;
+    },
+    async addItems(_items: unknown[]) {
+      // TODO
+    },
+    async updateItems(_items: unknown[]) {
+      // TODO
+    },
+    setCart(next: unknown) {
+      cart.value = next;
+    },
+  };
+}
+
+export default useCart;
+```
+
+`@decocms/start/sdk/signal` (re-exported via `~/sdk/signal` after
+migration) gives you the same `.value` getter/setter the factory uses,
+so AddToCart UI components don't need to know which platform is wired.
+
+The migration template's `generateGenericUseCart()` emits this stub when
+`--platform` is `custom` (or any non-VTEX value).
+
+---
+
+## Migrating off the manual approach (pre-W12 sites)
+
+If your site contains files like `src/lib/vtex-cart-server.ts` or hand-rolled `createServerFn` blocks for VTEX endpoints in `src/hooks/useCart.ts`, the post-cleanup audit will not auto-fix them — the manual code accumulated 6+ months of site-specific edits and the per-site judgment call about "what's still needed?" is real. The mechanical part:
+
+1. Replace the entire body of `src/hooks/useCart.ts` with the 5-line factory shim above.
+2. Delete `src/lib/vtex-cart-server.ts` (the migration template's `src/server/invoke.gen.ts` provides equivalent server functions wrapping `@decocms/apps/vtex/actions/checkout`).
+3. Verify `src/server/invoke.ts` exports the proxy shape the factory needs (cart actions under `invoke.vtex.actions`). The migration template scaffolds this; older sites may need to add the missing entries by hand.
+4. Run `npm run typecheck` — TypeScript will surface any callsites that referenced removed helpers (e.g. local `getOrCreateCart` shims).
+5. Repeat for `useUser` / `useWishlist`.
+
+For `useUser`, the analog of step 2 is removing any local `currentUser` /
+`getUser` server functions in favor of `@decocms/apps/vtex/loaders/user`
+exposed via `invoke.vtex.loaders.user()`. For `useWishlist`, the
+canonical surface is `@decocms/apps/vtex/{actions,loaders}/wishlist`.
+
+If you find yourself wanting to add behaviour to a factory (extra cart
+actions, custom analytics events) rather than ripping out the factory and going back to a manual hook:
+
+- **Extra read paths** → expose a new loader from
+  `@decocms/apps/vtex/loaders/*`, register it in `~/server/invoke.ts`,
+  call from your component (the factory doesn't need to know).
+- **Extra write paths** → ditto for `@decocms/apps/vtex/actions/*`.
+- **Cross-cutting business logic** (e.g. PIX-specific offer pricing) →
+  this is the kind of seam that justifies a parallel `useOffer` factory.
+  Talk to the apps maintainers; opening up a factory's plugin slots is a
+  one-PR change in apps, not a per-site rewrite.
+
+---
+
+## Related
+
+- `scripts/migrate/templates/hooks.ts` — the template that emits the
+  shims above.
+- `apps-start/vtex/hooks/createUseCart.ts` /
+  `createUseUser.ts` / `createUseWishlist.ts` — the factories
+  themselves; each docstring is the authoritative API reference.
+- `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

@@ -18,8 +18,10 @@ npx -p @decocms/start deco-post-cleanup
 
 # Auto-apply mechanical fixes for the safe rules, then report what's left.
 # Safe rules: dead-lib-shims, dead-runtime-shim, local-widgets-types,
-# vtex-shim-regression (swap subset), obsolete-vite-plugins.
-# Other rules stay detect-only — they require human judgment.
+# vtex-shim-regression (swap subset), obsolete-vite-plugins,
+# local-framework-duplicate (auto-fixable subset of the registry).
+# Other rules — and the warn-only entries of local-framework-duplicate —
+# stay detect-only. They require human judgment.
 npx -p @decocms/start deco-post-cleanup --fix
 
 # Combine for CI: auto-fix safe rules, fail (exit 2) if warnings remain.
@@ -29,14 +31,16 @@ npx -p @decocms/start deco-post-cleanup --fix --strict
 npx -p @decocms/start deco-post-cleanup --json
 ```
 
-The audit covers all 7 rules below and prints the exact file path +
+The audit covers all 9 rules below and prints the exact file path +
 suggested fix for each finding. With `--fix`, the safe rules
 auto-apply: `rm` for dead files, regex-anchored import rewrites for
 shadowed shims (`local-widgets-types`, `dead-runtime-shim`), the swap
-subset of `vtex-shim-regression`, and JS-aware removal of obsolete
-inline plugin literals from `vite.config.ts`. The output explicitly
-tags rules that require manual work as `(0 fixed, manual)`, so you
-always know what's left after auto-fix runs.
+subset of `vtex-shim-regression`, JS-aware removal of obsolete
+inline plugin literals from `vite.config.ts`, and rewrite-imports +
+delete for the auto-fixable subset of `local-framework-duplicate`
+(see § 8). The output explicitly tags rules that require manual work
+as `(0 fixed, manual)`, so you always know what's left after auto-fix
+runs.
 
 Real-world signal: on baggagio, `--fix` produced a byte-identical
 diff to the manual cleanup PR a human had just made (45 files,
@@ -398,7 +402,58 @@ In `--strict` mode any residue exits 2 — wire that into CI once a
 site has finished its HTMX rewrite to prevent regressions sneaking
 back in via copy-paste from a Fresh source.
 
-## 8. Search for orphan `TODO: move into framework` comments
+## 8. Drop site-local copies of framework code (`local-framework-duplicate`)
+
+The audit's `local-framework-duplicate` rule encodes a registry of
+files we expect sites to NOT carry locally because the canonical
+implementation already ships in `@decocms/start`. New entries go in
+`scripts/migrate/post-cleanup/rules.ts → FRAMEWORK_DUPLICATES`.
+
+Two kinds of finding:
+
+| Kind | Auto-fix | Example | What you do |
+|---|---|---|---|
+| **Pure dup** (`safeToAutoFix: true`) | YES | `src/sdk/clx.ts` matches `@decocms/start/sdk/clx` byte-for-byte | `--fix` rewrites every `from "~/sdk/clx"` to `from "@decocms/start/sdk/clx"` and deletes the file. Zero behavior change. |
+| **Partial overlap** (`safeToAutoFix: false`) | NO | `src/sdk/useSendEvent.ts` (typed) overlaps `@decocms/start/sdk/analytics → useSendEvent` (permissive) | The rule emits a `warning` with a `reason` explaining the manual judgement: widen the framework export, accept type loss, or fork on purpose. Human picks. |
+
+### How the rule fires
+
+The site file must match every regex in `contentSignature` before
+the rule treats it as the framework dup. This is conservative on
+purpose — sites that genuinely forked the helper (added platform
+logic, wrapped in something else) are skipped automatically.
+
+### Current registry
+
+| Site path | Canonical | Auto-fix? | Reason / status |
+|---|---|---|---|
+| `src/sdk/clx.ts` | `@decocms/start/sdk/clx` | yes | Identical implementation; baggagio's extra `clsx` alias has zero callers. |
+| `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. |
+
+### Adding a new entry
+
+When you spot a site carrying its own copy of code that lives in
+`@decocms/start`, add an entry to `FRAMEWORK_DUPLICATES`:
+
+```ts
+{
+  id: "<short-stable-id>",
+  sitePath: "src/<path>.ts",
+  canonicalImport: "@decocms/start/<path>",
+  contentSignature: [/<regex 1>/, /<regex 2>/],
+  safeToAutoFix: true | false,
+  reason: "<required when not safeToAutoFix>",
+  description: "<one-liner used in finding message>",
+}
+```
+
+Per **D4** in the migration tooling policy, the framework promotion
+itself happens at 3+ sites. This registry is the *enforcement* layer
+once promoted: every other site picks up the convergence
+automatically the next time `deco-post-cleanup --fix` runs.
+
+## 9. Search for orphan `TODO: move into framework` comments
 
 Real sites accumulate `TODO` comments like `// TODO: move into decoVitePlugin
 in next @decocms/start release`. These are roadmap items the framework
@@ -415,7 +470,7 @@ For each hit, decide:
 
 ## Verification checklist
 
-After completing 1-8:
+After completing 1-9:
 
 - [ ] `npm run typecheck` baseline matches pre-cleanup count (no new errors)
 - [ ] `npm run dev` starts and `/`, `/some-pdp/p`, `/s?q=foo` all render