@shop-on/create-theme 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shop-on/create-theme",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Scaffolds a Shop-On storefront theme: `npm create @shop-on/theme <dir>`.",
   "license": "SEE LICENSE IN dist/LICENSE.md",
   "bin": {

package/template/.claude/skills/theme-dev/recipes/customer-auth.md

@@ -11,13 +11,13 @@ rather than reimplementing the package surface.
 
 ## The package surface (already built — consume, don't reimplement)
 
-| Subpath                                  | Gives you                                                                                                                                                                                                                                                                                                                                            |
-| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@shop-on/theme-server/customer-session` | `read/write/clearCustomerSession` — encrypted `customer_session` cookie (HMAC label `"customer"` off `STOREFRONT_CUSTOMER_SESSION_SECRET`). **Reads never throw** (missing secret / bad cookie → `undefined` = anonymous); writes fail loudly                                                                                                        |
-| `@shop-on/theme-server/customer`         | `probeCurrentCustomer()` (3-branch: authoritative null → clears cookie; valid → returns customer, NO cookie rewrite; thrown → preserves cookie, null) + `revokeCustomerSession()`                                                                                                                                                                    |
-| `@shop-on/theme-server/customer-handoff` | `consumeCustomerHandoff(nonce)` — consumes the one-time `customer_session_handoff` nonce, cross-shop-guards on `STORE_SLUG`, writes the cookie. A thrown internal call degrades to `{ok:false, reason:"consume_error"}` — never lets an API blip error the landing page                                                                              |
-| `@shop-on/theme-server/account`          | `getAccountRedirectUrl({subpath?, returnToPath?})` (validated + absolutized return_to), `normalizeReturnToPath`, `handleCustomerLogoutPost(request)` (the ENTIRE logout POST: Origin gate → revoke → clear both cookies → auto-submit form), `renderLogoutForm`                                                                                      |
-| `@shop-on/theme-server/cart-customer`    | `resolveCartForCustomer({session, customerToken, locale?})` (own cart as-is / attach anonymous cart / claim stale-or-fresh-device cart) + `mintOrClaimCart({session, customerToken?})` (claim-before-create; anonymous = straight mint). Transient transport failures PRESERVE the guest-cart cookie — only authoritative API answers claim or clear |
+| Subpath                                  | Gives you                                                                                                                                                                                                                                                                                                                                                                                |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@shop-on/theme-server/customer-session` | `read/write/clearCustomerSession` — encrypted `customer_session` cookie (HMAC label `"customer"` off `STOREFRONT_CUSTOMER_SESSION_SECRET`). **Reads never throw** (missing secret / bad cookie → `undefined` = anonymous); writes fail loudly                                                                                                                                            |
+| `@shop-on/theme-server/customer`         | `probeCurrentCustomer()` (3-branch: authoritative null → clears cookie; valid → returns customer, NO cookie rewrite; thrown → preserves cookie, null) + `revokeCustomerSession()`                                                                                                                                                                                                        |
+| `@shop-on/theme-server/customer-handoff` | `consumeCustomerHandoff(nonce, state)` — checks `state` (the URL's `?state=`) against the `account_state` cookie `getAccountRedirectUrl` set, then consumes the one-time `customer_session_handoff` nonce, cross-shop-guards on `STORE_SLUG`, writes the cookie. A thrown internal call degrades to `{ok:false, reason:"consume_error"}` — never lets an API blip error the landing page |
+| `@shop-on/theme-server/account`          | `getAccountRedirectUrl({subpath?, returnToPath?})` (validated + absolutized return_to, with a fresh `state` bound to the `account_state` cookie), `normalizeReturnToPath`, `handleCustomerLogoutPost(request)` (the ENTIRE logout POST: Origin gate → revoke → clear both cookies → auto-submit form), `renderLogoutForm`                                                                |
+| `@shop-on/theme-server/cart-customer`    | `resolveCartForCustomer({session, customerToken, locale?})` (own cart as-is / attach anonymous cart / claim stale-or-fresh-device cart) + `mintOrClaimCart({session, customerToken?})` (claim-before-create; anonymous = straight mint). Transient transport failures PRESERVE the guest-cart cookie — only authoritative API answers claim or clear                                     |
 
 Env: `STORE_SLUG` + `STOREFRONT_CUSTOMER_SESSION_SECRET` (injected by the platform
 in prod; `.env` in dev, copied from `.env.example`). No new theme deps — `@shop-on/customer-runtime`
@@ -41,7 +41,8 @@ rides inside theme-server.
    `return handleCustomerLogoutPost(request)` (dynamic import).
 4. **Root route** — `validateSearch` gains `customer_handoff` +
    `clear_customer_session` (string passthrough); `beforeLoad` consumes the
-   nonce then redirect-replaces to the stripped URL (use the RAW
+   nonce, passing `location.search.state` beside it (without it the handoff is
+   dropped unconsumed and the buyer lands signed out), then redirect-replaces to the stripped URL (use the RAW
    `location.searchStr` so child-route params survive); loader starts
    `probeCurrentCustomerFn()` in wave 1 and **chains the cart off the probe**
    (`customerPromise.then(c => resolveCartFn({customerId: c?.id ?? null}))`) so
@@ -50,8 +51,12 @@ rides inside theme-server.
    `resolveCart` branches anonymous-read vs `resolveCartForCustomer`;
    cookie-less adds go through `mintOrClaimCart({session, customerToken})`
    (handles anonymous too); forward `customerToken` into every shared op.
-   Checkout: pass `{customerToken}` to `startCheckoutHandoff` so the API folds
-   the buyer into the handoff.
+   Checkout: the `/checkout` route reads `checkout_state` in `validateSearch`
+   and passes it to `startCheckoutHandoff({ state, customerToken })` (`state`
+   is a required key). Without a state it returns checkout's `/begin`, which
+   binds the browser and comes back with one; with it, it mints (the token lets
+   the API fold the buyer into the handoff). Checkout rejects a handoff minted
+   without the state.
 6. **Header UI** — an `AccountControl` snippet: anonymous = icon-link to
    `/account?return_to=…`; signed-in = **lazy** dropdown chunk (keep the menu
    primitive out of the anonymous bundle). Merchant `account_menu` `link_list`

package/template/package.json

@@ -17,14 +17,14 @@
   },
   "dependencies": {
     "@bprogress/core": "1.3.4",
-    "@shop-on/i18n": "^0.2.0",
-    "@shop-on/theme-contract": "^0.2.0",
-    "@shop-on/theme-loader": "^0.2.0",
-    "@shop-on/theme-react": "^0.2.0",
-    "@shop-on/theme-routes": "^0.2.0",
-    "@shop-on/theme-runtime": "^0.2.0",
-    "@shop-on/theme-server": "^0.2.0",
-    "@shop-on/theme-system": "^0.2.0",
+    "@shop-on/i18n": "^0.3.0",
+    "@shop-on/theme-contract": "^0.3.0",
+    "@shop-on/theme-loader": "^0.3.0",
+    "@shop-on/theme-react": "^0.3.0",
+    "@shop-on/theme-routes": "^0.3.0",
+    "@shop-on/theme-runtime": "^0.3.0",
+    "@shop-on/theme-server": "^0.3.0",
+    "@shop-on/theme-system": "^0.3.0",
     "@tailwindcss/vite": "4.3.3",
     "@tanstack/react-router": "1.170.45",
     "@tanstack/react-start": "1.169.3",
@@ -35,8 +35,8 @@
     "tailwindcss": "4.3.3"
   },
   "devDependencies": {
-    "@shop-on/theme-config": "^0.2.0",
-    "@shop-on/theme-dev-host": "^0.2.0",
+    "@shop-on/theme-config": "^0.3.0",
+    "@shop-on/theme-dev-host": "^0.3.0",
     "@spiriit/vite-plugin-svg-spritemap": "7.2.0",
     "@types/node": "26.6.5",
     "@types/react": "19.3.0",

package/template/src/route-adapter.tsx

@@ -19,6 +19,7 @@ import {
 } from "@/src/lib/listing-search";
 import { isPreviewSearch, paginatedPath, templateSeoHead } from "@/src/lib/seo-head";
 import { getAccountRedirectUrlFn } from "@/src/server/customer";
+import { startCheckoutFn } from "@/src/server/checkout-redirect";
 import {
   getArticleTemplateFn,
   getBlogPageTemplateFn,
@@ -70,6 +71,7 @@ export const routeAdapter: ThemeRouteAdapter = {
     parseBlogSearch,
   },
   account: { getAccountRedirectUrlFn },
+  checkout: { startCheckoutFn },
   // Add a `Wrapper` here if sections need to know they're in a picker preview.
   preview: { Unavailable: PreviewUnavailable },
 };

package/template/src/routeTree.gen.ts

@@ -19,6 +19,7 @@ import { Route as AnalyticsVisitsRouteImport } from './routes/analytics.visits'
 import { Route as Char123LocaleChar125IndexRouteImport } from './routes/{-$locale}/index'
 import { Route as Char123LocaleChar125404RouteImport } from './routes/{-$locale}/404'
 import { Route as Char123LocaleChar125CartRouteImport } from './routes/{-$locale}/cart'
+import { Route as Char123LocaleChar125CheckoutRouteImport } from './routes/{-$locale}/checkout'
 import { Route as Char123LocaleChar125PasswordRouteImport } from './routes/{-$locale}/password'
 import { Route as Char123LocaleChar125SearchRouteImport } from './routes/{-$locale}/search'
 import { Route as Char123LocaleChar125AccountIndexRouteImport } from './routes/{-$locale}/account/index'
@@ -87,6 +88,12 @@ const Char123LocaleChar125CartRoute =
     path: '/cart',
     getParentRoute: () => Char123LocaleChar125Route,
   } as any)
+const Char123LocaleChar125CheckoutRoute =
+  Char123LocaleChar125CheckoutRouteImport.update({
+    id: '/checkout',
+    path: '/checkout',
+    getParentRoute: () => Char123LocaleChar125Route,
+  } as any)
 const Char123LocaleChar125PasswordRoute =
   Char123LocaleChar125PasswordRouteImport.update({
     id: '/password',
@@ -190,6 +197,7 @@ export interface FileRoutesByFullPath {
   '/analytics/visits': typeof AnalyticsVisitsRoute
   '/{-$locale}/404': typeof Char123LocaleChar125404Route
   '/{-$locale}/cart': typeof Char123LocaleChar125CartRoute
+  '/{-$locale}/checkout': typeof Char123LocaleChar125CheckoutRoute
   '/{-$locale}/password': typeof Char123LocaleChar125PasswordRoute
   '/{-$locale}/search': typeof Char123LocaleChar125SearchRoute
   '/{-$locale}/': typeof Char123LocaleChar125IndexRoute
@@ -216,6 +224,7 @@ export interface FileRoutesByTo {
   '/analytics/visits': typeof AnalyticsVisitsRoute
   '/{-$locale}/404': typeof Char123LocaleChar125404Route
   '/{-$locale}/cart': typeof Char123LocaleChar125CartRoute
+  '/{-$locale}/checkout': typeof Char123LocaleChar125CheckoutRoute
   '/{-$locale}/password': typeof Char123LocaleChar125PasswordRoute
   '/{-$locale}/search': typeof Char123LocaleChar125SearchRoute
   '/{-$locale}': typeof Char123LocaleChar125IndexRoute
@@ -244,6 +253,7 @@ export interface FileRoutesById {
   '/analytics/visits': typeof AnalyticsVisitsRoute
   '/{-$locale}/404': typeof Char123LocaleChar125404Route
   '/{-$locale}/cart': typeof Char123LocaleChar125CartRoute
+  '/{-$locale}/checkout': typeof Char123LocaleChar125CheckoutRoute
   '/{-$locale}/password': typeof Char123LocaleChar125PasswordRoute
   '/{-$locale}/search': typeof Char123LocaleChar125SearchRoute
   '/{-$locale}/': typeof Char123LocaleChar125IndexRoute
@@ -273,6 +283,7 @@ export interface FileRouteTypes {
     | '/analytics/visits'
     | '/{-$locale}/404'
     | '/{-$locale}/cart'
+    | '/{-$locale}/checkout'
     | '/{-$locale}/password'
     | '/{-$locale}/search'
     | '/{-$locale}/'
@@ -299,6 +310,7 @@ export interface FileRouteTypes {
     | '/analytics/visits'
     | '/{-$locale}/404'
     | '/{-$locale}/cart'
+    | '/{-$locale}/checkout'
     | '/{-$locale}/password'
     | '/{-$locale}/search'
     | '/{-$locale}'
@@ -326,6 +338,7 @@ export interface FileRouteTypes {
     | '/analytics/visits'
     | '/{-$locale}/404'
     | '/{-$locale}/cart'
+    | '/{-$locale}/checkout'
     | '/{-$locale}/password'
     | '/{-$locale}/search'
     | '/{-$locale}/'
@@ -426,6 +439,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof Char123LocaleChar125CartRouteImport
       parentRoute: typeof Char123LocaleChar125Route
     }
+    '/{-$locale}/checkout': {
+      id: '/{-$locale}/checkout'
+      path: '/checkout'
+      fullPath: '/{-$locale}/checkout'
+      preLoaderRoute: typeof Char123LocaleChar125CheckoutRouteImport
+      parentRoute: typeof Char123LocaleChar125Route
+    }
     '/{-$locale}/password': {
       id: '/{-$locale}/password'
       path: '/password'
@@ -537,6 +557,7 @@ declare module '@tanstack/react-router' {
 interface Char123LocaleChar125RouteChildren {
   Char123LocaleChar125404Route: typeof Char123LocaleChar125404Route
   Char123LocaleChar125CartRoute: typeof Char123LocaleChar125CartRoute
+  Char123LocaleChar125CheckoutRoute: typeof Char123LocaleChar125CheckoutRoute
   Char123LocaleChar125PasswordRoute: typeof Char123LocaleChar125PasswordRoute
   Char123LocaleChar125SearchRoute: typeof Char123LocaleChar125SearchRoute
   Char123LocaleChar125IndexRoute: typeof Char123LocaleChar125IndexRoute
@@ -558,6 +579,7 @@ interface Char123LocaleChar125RouteChildren {
 const Char123LocaleChar125RouteChildren: Char123LocaleChar125RouteChildren = {
   Char123LocaleChar125404Route: Char123LocaleChar125404Route,
   Char123LocaleChar125CartRoute: Char123LocaleChar125CartRoute,
+  Char123LocaleChar125CheckoutRoute: Char123LocaleChar125CheckoutRoute,
   Char123LocaleChar125PasswordRoute: Char123LocaleChar125PasswordRoute,
   Char123LocaleChar125SearchRoute: Char123LocaleChar125SearchRoute,
   Char123LocaleChar125IndexRoute: Char123LocaleChar125IndexRoute,

package/template/src/routes/__root.tsx

@@ -70,9 +70,12 @@ export const Route = createRootRouteWithContext<RouterContext>()({
     const search = location.search as {
       customer_handoff?: string;
       clear_customer_session?: string;
+      state?: string;
     };
     if (search.customer_handoff) {
-      await consumeCustomerHandoffFn({ data: { nonce: search.customer_handoff } });
+      await consumeCustomerHandoffFn({
+        data: { nonce: search.customer_handoff, state: search.state },
+      });
     }
     if (!search.customer_handoff && !search.clear_customer_session) return;
 

package/template/src/routes/{-$locale}/checkout.tsx

@@ -0,0 +1,12 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { checkoutRouteOptions } from "@shop-on/theme-routes";
+import { routeAdapter } from "@/src/route-adapter";
+
+// The cart → checkout bounce, via checkout's `/begin` on the first visit. See
+// docs/theme-cart.md#checkout-handoff.
+const { validateSearch, beforeLoad } = checkoutRouteOptions(routeAdapter.checkout);
+
+export const Route = createFileRoute("/{-$locale}/checkout")({
+  validateSearch,
+  beforeLoad,
+});

package/template/src/server/checkout-redirect.ts

@@ -0,0 +1,21 @@
+// Server-side cart→checkout bounce. The cart-cookie read + `cartCheckout` call
+// + result mapping live in the shared `@shop-on/theme-server/checkout` helper;
+// this forwards the buyer token so a signed-in checkout arrives prefilled
+// (anonymous buyers forward nothing). The node-only helpers are dynamic-
+// imported inside the handler so this module stays safe to import from the
+// client-side `/checkout` route.
+import { createServerFn } from "@tanstack/react-start";
+import type { CheckoutHandoffResult } from "@shop-on/theme-server/checkout";
+
+export type { CheckoutHandoffResult };
+
+// `state` is the `checkout_state` checkout's `/begin` sent back; without one the
+// result is the `/begin` URL itself (what a browser-side caller gets).
+export const startCheckoutFn = createServerFn({ method: "POST" })
+  .validator((data: { state?: string } | undefined) => ({ state: data?.state }))
+  .handler(async ({ data }): Promise<CheckoutHandoffResult> => {
+    const { readCustomerSession } = await import("@shop-on/theme-server/customer-session");
+    const { startCheckoutHandoff } = await import("@shop-on/theme-server/checkout");
+    const session = await readCustomerSession();
+    return startCheckoutHandoff({ state: data.state, customerToken: session?.token });
+  });

package/template/src/server/customer.ts

@@ -32,10 +32,10 @@ export const probeCurrentCustomerFn = createServerFn({ method: "GET" }).handler(
 // Consume a `customer_session_handoff` nonce (root `beforeLoad`), writing the
 // `customer_session` cookie. Cross-shop-guarded against `STORE_SLUG`.
 export const consumeCustomerHandoffFn = createServerFn({ method: "POST" })
-  .validator((data: { nonce: string }) => data)
+  .validator((data: { nonce: string; state?: string }) => data)
   .handler(async ({ data }): Promise<ConsumeCustomerHandoffResult> => {
     const { consumeCustomerHandoff } = await import("@shop-on/theme-server/customer-handoff");
-    return consumeCustomerHandoff(data.nonce);
+    return consumeCustomerHandoff(data.nonce, data.state);
   });
 
 // Build the central account-app URL the `/account/*` bouncers redirect to,