@shop-on/create-theme 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shop-on/create-theme",
-  "version": "0.1.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": {
@@ -16,9 +16,9 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@types/node": "26.6.3",
+    "@types/node": "26.6.5",
     "typescript": "7.0.2",
-    "vitest": "5.0.3"
+    "vitest": "5.0.5"
   },
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
@@ -26,6 +26,6 @@
   "scripts": {
     "template": "node scripts/template.mts",
     "check-types": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run --maxWorkers=2"
   }
 }

package/template/.claude/skills/theme-dev/SKILL.md

@@ -260,7 +260,7 @@ A theme change is not finished when it type-checks — the artifact carries a ve
 1. Bump `package.json#version` (semver). Fix → patch; new section, block or setting → minor.
 2. Prepend a `## X.Y.Z` section to `release-notes.md`. The platform stores only the section matching the uploaded version, so each one carries its own notes.
 3. `pnpm build` — postbuild emits `.output/theme.json` at the new version, and fails fast if `theme.config.json#locales` omits `"en"`. Check `theme.config.json#locales` matches the catalogs you ship first: a declared locale with no catalog renders default-language copy.
-4. Package. **Don't improvise the tarball.** Two things a hand-rolled `tar` gets wrong: entries must sit **flat at the tarball root** (`-C .output`, pack `.`), and macOS needs `COPYFILE_DISABLE=1` + `--no-mac-metadata` to keep AppleDouble `._*` entries out (drop `--no-mac-metadata` on GNU tar): `COPYFILE_DISABLE=1 tar -czf ../<name>-X.Y.Z.tar.gz -C .output --exclude='.DS_Store' --no-mac-metadata .`. Uploading a version to the theme store isn't open to third-party developers yet; the tarball is as far as this goes for now.
+4. Package. **Don't hand-roll the tarball**: `npx @shop-on/theme-cli theme pack` writes `<name>-X.Y.Z.tar.gz` in the theme directory (`--out <path>` to put it elsewhere, `--build` to build first). Entries sit flat at the root with no macOS metadata, the same on every OS, and it refuses a build missing a file the theme store requires or older than `package.json`. Uploading a version to the theme store isn't open to third-party developers yet; the tarball is as far as this goes for now.
 
 Write the notes **for the merchant, not the diff**: what changes in their store, in their words. Match the file — plain bullets under the heading, no `### Fixed` subsections, no file names, no component names. "Prices now say when tax is included", not "added `taxIncludedCaption` to the price block".
 

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/.claude/skills/theme-dev/recipes/dynamic-sources.md

@@ -173,7 +173,7 @@ GID is in place before its `${id}Data` resolver runs:
 1. **Fetch metaobject entries** — `loadMetaobjectFieldSources(template, product)`
    collects the union of pinned entry ids (`collectMetaobjectEntryIds`, binding +
    inline forms) and traversed entry ids (`collectTraversedEntryIds(template,
-product.metafields)` — field-bearing `product_metafield` refs), early-returns
+   product.metafields)` — field-bearing `product_metafield` refs), early-returns
    `{}` when none, else batch-fetches (`fetchMetaobject`, deduped + `memoTTL`-
    cached, capped at 50 with a warning) and builds `{ entry: { key: { type, value } } }`.
 2. **Whole-value pass — BEFORE the picker-data resolvers.**

package/template/.claude/skills/theme-dev/recipes/quality.md

@@ -25,7 +25,7 @@ pnpm build                     # postbuild enforces the build lines
 The output is one line per finding, `file:line rule message`, followed by the
 recipe for each rule that fired.
 
-The **audit** lines come from `shop-on theme audit`, in the `@shop-on/cli`
+The **audit** lines come from `shop-on theme audit`, in the `@shop-on/theme-cli`
 package:
 
 ```bash
@@ -41,7 +41,7 @@ missing instead of measuring an empty page. The password template is left
 out, since it only renders while protection is on, and the audit refuses a
 protected store.
 
-`@shop-on/cli` isn't published yet. Until it is, measure the **audit** lines
+`@shop-on/theme-cli` isn't published yet. Until it is, measure the **audit** lines
 by hand, as each one says.
 
 ## Performance

package/template/README.md

@@ -8,16 +8,16 @@ published `@shop-on/theme-*` packages.
 ## Quick start
 
 ```sh
-npx @shop-on/cli theme init my-theme   # scaffold, log in if needed, write .env, install
+npx @shop-on/theme-cli theme init my-theme   # scaffold, log in if needed, write .env, install
 cd my-theme
-npx @shop-on/cli theme dev             # open this theme in your store's theme editor
+npx @shop-on/theme-cli theme dev             # open this theme in your store's theme editor
 ```
 
 The first time, `theme init` opens your browser on your store's admin:
 approve the CLI and pick the store. Your staff role needs **Manage online store**. It then writes
 `.env` with a storefront credential for that store. `.env` holds secrets:
 never commit it. A store holds at most 5 of these credentials;
-`npx @shop-on/cli theme credentials revoke <client-id>` frees one.
+`npx @shop-on/theme-cli theme credentials revoke <client-id>` frees one.
 
 `theme dev` runs the theme behind a `cloudflared` tunnel (install it first)
 and opens the hosted theme editor on a developer preview of it. Confirm the

package/template/package.json

@@ -17,36 +17,36 @@
   },
   "dependencies": {
     "@bprogress/core": "1.3.4",
-    "@shop-on/i18n": "^0.1.0",
-    "@shop-on/theme-contract": "^0.1.0",
-    "@shop-on/theme-loader": "^0.1.0",
-    "@shop-on/theme-react": "^0.1.0",
-    "@shop-on/theme-routes": "^0.1.0",
-    "@shop-on/theme-runtime": "^0.1.0",
-    "@shop-on/theme-server": "^0.1.0",
-    "@shop-on/theme-system": "^0.1.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.41",
-    "@tanstack/react-start": "1.168.60",
-    "dotenv": "18.0.5",
+    "@tanstack/react-router": "1.170.45",
+    "@tanstack/react-start": "1.169.3",
+    "dotenv": "18.0.8",
     "nitro": "3.0.260903-beta",
-    "react": "19.3.0",
-    "react-dom": "19.3.0",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
     "tailwindcss": "4.3.3"
   },
   "devDependencies": {
-    "@shop-on/theme-config": "^0.1.0",
-    "@shop-on/theme-dev-host": "^0.1.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.3",
+    "@types/node": "26.6.5",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
-    "@vitejs/plugin-react": "6.1.1",
-    "gql.tada": "1.11.3",
-    "happy-dom": "20.10.6",
-    "oxfmt": "^0.71.0",
+    "@vitejs/plugin-react": "6.1.2",
+    "gql.tada": "1.11.4",
+    "happy-dom": "21.0.4",
+    "oxfmt": "^0.74.0",
     "typescript": "7.0.2",
-    "vite": "8.3.1",
-    "vitest": "5.0.3"
+    "vite": "8.3.5",
+    "vitest": "5.0.5"
   }
 }

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,