create-magic-storefront 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MagicStore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# create-magic-storefront
+
+```bash
+npm create magic-storefront@latest my-shop -- --shop shop.example.uz
+```
+
+Scaffolds the [storefront starter](../../examples/starter) into `my-shop`, pins the SDK to the
+matching release and writes `.env.local` from the answers (`--shop`, `--token`, `--locale`). The
+directory must be new or empty. Without a TTY it asks nothing and uses the flags.
+
+## Checking a storefront
+
+```bash
+npx create-magic-storefront check [directory]
+```
+
+Fails (exit 1, one line per finding) when the storefront uses the SDK outside its public API:
+
+- `DEEP_IMPORT` — an `@magicstoreai/*` import other than `@magicstoreai/storefront-client`,
+  `@magicstoreai/hydrogen`, `@magicstoreai/hydrogen/core`, `/server` or `/seo` (a `src/` or `dist/`
+  path, an unexported subpath, the SDK's sources in this repository);
+- `RAW_API_CALL` — a string that spells out an endpoint (`/api/v2/storefront/…`) instead of calling
+  it through the client. The bare base URL handed to `createStorefrontClient` is fine.
+
+`node_modules`, build output and `.d.ts` files are skipped. In this repository `pnpm guard` runs it on
+`examples/starter` (CI too).

package/dist/index.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { dirname, relative as relative2, resolve as resolve3 } from "path";
+import { createInterface } from "readline/promises";
+import { fileURLToPath } from "url";
+import { parseArgs } from "util";
+
+// src/guard.ts
+import { readdirSync, readFileSync } from "fs";
+import { join, relative, resolve } from "path";
+var PUBLIC_ENTRY_POINTS = [
+  "@magicstoreai/storefront-client",
+  "@magicstoreai/hydrogen",
+  "@magicstoreai/hydrogen/core",
+  "@magicstoreai/hydrogen/server",
+  "@magicstoreai/hydrogen/seo"
+];
+var SOURCE_EXTENSIONS = /\.(?:[cm]?[jt]sx?)$/;
+var SKIPPED_DIRECTORIES = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".next",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  "coverage"
+]);
+var SPECIFIER = /(?:\bfrom\s*|\bimport\s*\(\s*|\bimport\s+|\brequire\s*\(\s*)(['"])([^'"\n]+)\1/g;
+var SDK_PACKAGE = /@magicstoreai\/(?:hydrogen|storefront-client)(?:\/|$)/;
+var SDK_SOURCES = /(?:^|\/)packages\/(?:hydrogen|storefront-client)(?:\/|$)/;
+var RAW_API_PATH = /\/api\/v2\/storefront\/(?:[A-Za-z]|\$\{)/;
+var STRING_LITERAL = /(['"`])(?:\\.|(?!\1)[^\\\n])*\1/g;
+function sourceFiles(directory) {
+  const files = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!SKIPPED_DIRECTORIES.has(entry.name)) {
+        files.push(...sourceFiles(join(directory, entry.name)));
+      }
+    } else if (entry.isFile() && SOURCE_EXTENSIONS.test(entry.name) && !entry.name.endsWith(".d.ts")) {
+      files.push(join(directory, entry.name));
+    }
+  }
+  return files;
+}
+function lineAt(source, index) {
+  return source.slice(0, index).split("\n").length;
+}
+function checkSource(file, source) {
+  const violations = [];
+  for (const match of source.matchAll(SPECIFIER)) {
+    const specifier = match[2];
+    const reachesIn = SDK_PACKAGE.test(specifier) && !PUBLIC_ENTRY_POINTS.includes(specifier) || SDK_SOURCES.test(specifier);
+    if (reachesIn) {
+      violations.push({
+        rule: "DEEP_IMPORT",
+        file,
+        line: lineAt(source, match.index),
+        text: specifier
+      });
+    }
+  }
+  for (const match of source.matchAll(STRING_LITERAL)) {
+    if (RAW_API_PATH.test(match[0])) {
+      violations.push({
+        rule: "RAW_API_CALL",
+        file,
+        line: lineAt(source, match.index),
+        text: match[0]
+      });
+    }
+  }
+  return violations.sort((a, b) => a.line - b.line);
+}
+function checkPublicApi(directory) {
+  const root = resolve(directory);
+  return sourceFiles(root).flatMap(
+    (path) => checkSource(relative(root, path).split("\\").join("/"), readFileSync(path, "utf8"))
+  );
+}
+var EXPLANATIONS = {
+  DEEP_IMPORT: `import only ${PUBLIC_ENTRY_POINTS.join(", ")}`,
+  RAW_API_CALL: "call the API through the storefront client, not by URL"
+};
+function formatViolations(violations) {
+  return violations.map((v) => `${v.file}:${v.line}  ${v.rule}  ${v.text}  \u2014 ${EXPLANATIONS[v.rule]}`).join("\n");
+}
+
+// src/scaffold.ts
+import { cpSync, existsSync, readdirSync as readdirSync2, readFileSync as readFileSync2, renameSync, writeFileSync } from "fs";
+import { basename, join as join2, resolve as resolve2 } from "path";
+function packageName(directory) {
+  const name = basename(resolve2(directory)).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[._-]+|-+$/g, "");
+  return name || "magic-storefront";
+}
+function scaffold(options) {
+  const directory = resolve2(options.directory);
+  if (existsSync(directory) && readdirSync2(directory).length > 0) {
+    throw new Error(`${directory} is not empty \u2014 pick a new directory.`);
+  }
+  cpSync(options.templateDirectory, directory, { recursive: true });
+  if (existsSync(join2(directory, "_gitignore"))) {
+    renameSync(join2(directory, "_gitignore"), join2(directory, ".gitignore"));
+  }
+  const name = packageName(directory);
+  const manifestPath = join2(directory, "package.json");
+  const manifest = JSON.parse(readFileSync2(manifestPath, "utf8"));
+  manifest.name = name;
+  for (const group of [manifest.dependencies, manifest.devDependencies]) {
+    for (const [dependency, version] of Object.entries(group ?? {})) {
+      if (version.startsWith("workspace:")) {
+        const published = options.sdkVersions[dependency];
+        if (!published) {
+          throw new Error(`No published version known for ${dependency}.`);
+        }
+        group[dependency] = `^${published}`;
+      }
+    }
+  }
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`);
+  const example = readFileSync2(join2(directory, ".env.example"), "utf8");
+  writeFileSync(join2(directory, ".env.local"), envFile(example, options));
+  return { directory, name };
+}
+function envFile(example, options) {
+  const answers = {
+    MAGICSTORE_SHOP_DOMAIN: options.shopDomain,
+    NEXT_PUBLIC_MAGICSTORE_STOREFRONT_TOKEN: options.storefrontToken,
+    NEXT_PUBLIC_MAGICSTORE_LOCALE: options.locale
+  };
+  return example.split("\n").map((line) => {
+    const match = /^([A-Z0-9_]+)=/.exec(line);
+    const value = match ? answers[match[1]] : void 0;
+    return match && value !== void 0 ? `${match[1]}=${value}` : line;
+  }).join("\n");
+}
+
+// src/index.ts
+var HELP = `Usage: create-magic-storefront [directory] [options]
+       create-magic-storefront check [directory]
+
+Scaffolds a Next.js storefront on the MagicStore Storefront API v2.
+
+check verifies that a storefront uses the SDK only through its public entry points
+(no deep @magicstoreai/* imports, no hand-written /api/v2/storefront/... calls).
+
+Options:
+  --shop <domain>     the shop's storefront domain (shop.example.uz)
+  --token <token>     a storefront access token that lists this site's origin (optional)
+  --locale <locale>   the language pages render in (default: ru)
+  -h, --help          show this help
+`;
+function check(directory) {
+  const violations = checkPublicApi(directory);
+  if (violations.length > 0) {
+    process.stderr.write(`${formatViolations(violations)}
+`);
+    throw new Error(`${violations.length} use(s) of the SDK outside its public API.`);
+  }
+  process.stdout.write("The storefront uses only the SDK's public API.\n");
+}
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      shop: { type: "string" },
+      token: { type: "string" },
+      locale: { type: "string" },
+      help: { type: "boolean", short: "h" }
+    }
+  });
+  if (values.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+  if (positionals[0] === "check") {
+    check(positionals[1] ?? ".");
+    return;
+  }
+  const interactive = process.stdin.isTTY === true;
+  const ask = async (question, fallback) => {
+    if (!interactive) {
+      return fallback;
+    }
+    const prompt = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = (await prompt.question(`${question} (${fallback || "skip"}): `)).trim();
+    prompt.close();
+    return answer || fallback;
+  };
+  const directory = positionals[0] ?? await ask("Directory", "magic-storefront");
+  const shopDomain = values.shop ?? await ask("Shop domain", "");
+  const root = resolve3(dirname(fileURLToPath(import.meta.url)), "..");
+  const own = JSON.parse(readFileSync3(resolve3(root, "package.json"), "utf8"));
+  const { directory: created } = scaffold({
+    directory,
+    templateDirectory: resolve3(root, "template"),
+    // The SDK is released together with this CLI: same version.
+    sdkVersions: {
+      "@magicstoreai/hydrogen": own.version,
+      "@magicstoreai/storefront-client": own.version
+    },
+    shopDomain: shopDomain || void 0,
+    storefrontToken: values.token,
+    locale: values.locale
+  });
+  const where = relative2(process.cwd(), created) || ".";
+  process.stdout.write(`
+Created ${where}.
+
+  cd ${where}
+  npm install
+  npm run dev
+${shopDomain ? "" : "\nSet MAGICSTORE_SHOP_DOMAIN in .env.local first.\n"}`);
+}
+main().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "create-magic-storefront",
+  "version": "0.1.0",
+  "description": "Scaffold a Next.js storefront on the MagicStore Storefront API v2",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-magic-storefront": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "^5.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/copy-template.mjs && tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/template/.env.example

@@ -0,0 +1,22 @@
+# The shop's storefront domain — the API is https://<domain>/api/v2/storefront.
+MAGICSTORE_SHOP_DOMAIN=shop.example.uz
+
+# Optional. The full API base URL instead — e.g. the mock server from the spec (`pnpm mock` in the
+# SDK repository serves it at http://127.0.0.1:4010).
+MAGICSTORE_API_URL=
+
+# Optional. A storefront access token (Shop settings → Storefront API) that lists this site's
+# origin (e.g. http://localhost:3000). With it the browser calls the API directly; without it,
+# browser calls go through this app's /storefront-api proxy (app/storefront-api/[...path]).
+NEXT_PUBLIC_MAGICSTORE_STOREFRONT_TOKEN=
+
+# Optional. The signing secret of the token's webhook (whsec_…): /api/magicstore/webhook
+# revalidates cached pages when the merchant changes the catalog, pages or home.
+MAGICSTORE_WEBHOOK_SECRET=
+
+# The language pages render in (a locale the shop enables).
+NEXT_PUBLIC_MAGICSTORE_LOCALE=ru
+
+# Optional. This site's public origin for sitemap URLs (https://shop.example.uz); the shop's primary
+# domain when empty.
+SITE_URL=

package/template/AGENTS.md

@@ -0,0 +1,56 @@
+<!-- BEGIN:nextjs-agent-rules -->
+
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->
+
+# MagicStore storefront
+
+A Next.js App Router storefront on the MagicStore Storefront API v2. The shop's data, prices, stock,
+discounts and delivery come from the API; this app renders them. Read `llms.txt` first (in the SDK
+repository: its root) — entry points, credentials, wire rules, the cart → checkout flow and what
+each error code means — then `PAGES.md` for how each page type is built, and
+`node_modules/@magicstoreai/hydrogen/CATALOGUE.md` for every component and hook.
+
+## Rules
+
+- Import the SDK only from `@magicstoreai/storefront-client`, `@magicstoreai/hydrogen`,
+  `@magicstoreai/hydrogen/core`, `/server` and `/seo`. Call the API through client methods, never
+  by `/api/v2/storefront/…` URL. `npx create-magic-storefront check` must pass.
+- Never compute money: render `Money` values with `<Money>` / `formatMoney`, totals from the cart
+  and the checkout.
+- Cart id, checkout id, tokens, OTP codes, phone numbers: never logged, never in a URL.
+- Public reads render on the server through `lib/api.ts` (cached by tag, revalidated by the
+  webhook). Anything personal — cart, customer, wishlist — lives in client components under
+  `MagicStoreProvider` (`app/providers.tsx`).
+- Branch on `MagicStoreError.code`, show `error.detail`.
+- Every page handles its empty, error and not-found states (`orNotFound` turns `NOT_FOUND` into
+  the 404 page).
+
+## Where things go
+
+| Path                           | What                                                                     |
+| ------------------------------ | ------------------------------------------------------------------------ |
+| `app/`                         | Pages (server components) and route handlers                             |
+| `app/error.tsx`                | Error boundary: the API's `detail`, a retry                              |
+| `app/sitemap.ts`               | Sitemap from `GET /sitemap`                                              |
+| `app/page.tsx`                 | Home: renders `GET /home` sections in the merchant's order               |
+| `components/sections/`         | One renderer per home section type; an unknown type renders nothing      |
+| `components/`                  | Shared UI; client components start with `'use client'`                   |
+| `lib/api.ts`                   | The server-side client (`nextCacheFetch`), `orNotFound`                  |
+| `app/providers.tsx`            | `MagicStoreProvider`: customer, cart, wishlist, analytics in the browser |
+| `app/storefront-api/[...path]` | Same-origin proxy for browser calls without a public storefront token    |
+| `app/api/magicstore/webhook`   | Signed webhook → `revalidateTag`                                         |
+
+## Commands
+
+```bash
+npm run dev          # needs MAGICSTORE_SHOP_DOMAIN (or MAGICSTORE_API_URL) in .env.local
+npm run build
+npm run typecheck
+npx create-magic-storefront check   # SDK used only through its public API
+```

package/template/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/template/PAGES.md

@@ -0,0 +1,154 @@
+# Building storefront pages
+
+How each page of a MagicStore storefront is built on the SDK: what it reads, how it is cached, its
+SEO, and the states it must handle. The files named are this starter's — the reference for each page
+type. Read `llms.txt` first for the rules every page follows (entry points, money, credentials,
+errors).
+
+## Two kinds of data
+
+|                 | Public: catalog, content, shop                         | Personal: cart, customer, checkout, orders                  |
+| --------------- | ------------------------------------------------------ | ----------------------------------------------------------- |
+| Where it's read | Server components, through `lib/api.ts`                | Client components, through hooks under `MagicStoreProvider` |
+| Client          | `createStorefrontClient({ fetch: nextCacheFetch() })`  | `useStorefrontClient()`, `useCart()`, `useCustomer()`, …    |
+| Cache           | Tagged by `nextCacheFetch`, revalidated by the webhook | Never cached (`no-store`; a bearer call is never tagged)    |
+| Not found       | `orNotFound(read)` → the `not-found.tsx` page          | Branch on `MagicStoreError.code`, show `detail`             |
+
+`nextCacheFetch` tags every public `GET` by its path (`tagForPath`), and
+`app/api/magicstore/webhook` revalidates the tags of each webhook topic:
+
+| Tag                  | Paths                                                                               | Webhook topic     |
+| -------------------- | ----------------------------------------------------------------------------------- | ----------------- |
+| `magicstore:shop`    | `/shop`, `/contacts`, `/theme/section-schema`                                       | `SHOP_UPDATED`    |
+| `magicstore:home`    | `/home`                                                                             | `HOME_UPDATED`    |
+| `magicstore:pages`   | `/pages*`, `/menus/footer`                                                          | `PAGES_UPDATED`   |
+| `magicstore:catalog` | `/products*`, `/collections*`, other `/menus/*`, `/reels`, `/sitemap`, `/locations` | `CATALOG_UPDATED` |
+| none (`no-store`)    | `/search*`, `/reviews/site`, cart, checkout, customer, orders                       | —                 |
+
+Every page renders per request (`dynamic = 'force-dynamic'` in `app/layout.tsx`): the shop is the
+API's, not the build's. The fetch cache still spares the API.
+
+## Layout — `app/layout.tsx`
+
+- Reads `api.shop()` and the navigation (`api.collectionsIndex` or `api.menusShow({ path: { handle: 'main' } })`).
+- `generateMetadata`: `shop.seo.title || shop.name`, `shop.seo.description ?? shop.description`.
+- Wraps the page in `Providers` (`MagicStoreProvider` with `shop` passed in, so the browser does not
+  load it again).
+
+## Home — `app/page.tsx`, `components/sections/`
+
+`api.home()` answers `{ sections: HomeSection[] }` in the merchant's order. Render each by `type`
+with one component per type; a type the storefront does not know renders **nothing** (the API can
+be newer than the storefront). `GET /theme/section-schema` (`api.themeSectionSchema()`) has the
+JSON Schema of every type's `settings`; the TypeScript types are `Schema<'BannerSection'>` and so
+on. The server drops a section that would show nothing, but a shelf can still come back empty —
+render nothing then.
+
+| `type`                 | Settings                                                         | Data it reads                                               |
+| ---------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------- |
+| `ANNOUNCEMENT_BAR`     | `text`, colours, `animation`                                     | —                                                           |
+| `BANNER`               | `slides[]`: `image`, `link` (product, collection or URL)         | —                                                           |
+| `FEATURED_COLLECTIONS` | —                                                                | `collectionsIndex` with `filter[featured]=true`             |
+| `COLLECTIONS`          | `cardStyle` (a styling hint)                                     | `collectionsIndex` with `filter[root]=true`                 |
+| `COLLECTION_GRID`      | `tiles[]`: `collection`, `image`                                 | —                                                           |
+| `NEW_ARRIVALS`         | `limit`                                                          | `productsIndex` with `sort=-createdAt`                      |
+| `ON_SALE`              | `limit`                                                          | `productsIndex` with `filter[onSale]=true`                  |
+| `TRENDING`             | `limit`                                                          | `productsIndex` with `filter[trending]=true`                |
+| `BESTSELLERS`          | `limit`                                                          | `productsIndex` with `sort=-bestSellers`                    |
+| `PRE_ORDERS`           | `limit`                                                          | `productsIndex` with `filter[preOrder]=true`                |
+| `FOR_YOU`              | `limit`                                                          | Personal: not on a cached page (see below)                  |
+| `COLLECTION_PRODUCTS`  | `collection`, `limit`, `title`                                   | `collectionsProducts` of `collection.handle`                |
+| `FLASH_SALE`           | `collection`, `limit`, `title`, `endsAt`                         | `collectionsProducts` of `collection.handle`                |
+| `DEAL_OF_DAY`          | `product`, `image`, `price`, `compareAtPrice`, `endsAt`, `stock` | — (`stock` is the merchant's "N of M left", not real stock) |
+| `SHOPPABLE_STORIES`    | `stories[]`: `thumbnail`, `title`, `frames[]` (media, `product`) | —                                                           |
+| `STORE_REVIEWS`        | titles, `limit`, `externalRatings`, `recommendPercent`, flags    | `reviewsSite` (`meta.rating` has the average and breakdown) |
+
+`limit: null` means the storefront's own default. `FOR_YOU` has no product-independent endpoint yet
+(`productsRecommendations` with `intent=FOR_YOU` needs a product) and a cached page must not be
+personal; render it in a client component or not at all. A shop with no sections still needs a
+home: show new arrivals.
+
+## Collection — `app/collections/[handle]/page.tsx`
+
+- `api.collectionsShow({ path: { handle } })` and `api.collectionsProducts({ path: { handle }, query: { page, perPage } })`,
+  both through `orNotFound`.
+- Filters and sorts: `api.collectionsFilters` lists the facets; pass them as `filter[…]` and `sort`
+  query parameters. An unknown filter or sort is a `VALIDATION_FAILED`, not ignored.
+- SEO: `pageMeta({ seo: collection.seo, title, description })`, and `breadcrumbJsonLd`.
+- States: an empty collection ("Nothing here yet"), a `page` past the last one (empty list), 404.
+
+## Product — `app/products/[handle]/page.tsx`, `components/buy-box.tsx`
+
+- `api.productsShow({ path: { handle } })` through `orNotFound`. Recommendations:
+  `productsRecommendations` (`intent=RELATED` or `COMPLEMENTARY`); reviews: `productsReviews`
+  (`meta.rating` has the average and breakdown). Both are catalog reads, cached like the product.
+- The buy box is a client component: `useVariantSelection(product)` (or `ProductProvider` +
+  `useProduct`), `useCart().addLine({ productId, variantId, quantity })`, `useWishlist()`, and
+  `useAnalytics().productView(...)`.
+- Price: the selected variant's `price` / `compareAtPrice`, else the product's, with `<Money>`.
+- SEO: `pageMeta({ seo, title, description, images })`, and
+  `jsonLdScript(productJsonLd(product, { url }))` in a `<script type="application/ld+json">`.
+- States: 404; out of stock (`availableForSale` false on the product or the selected variant —
+  disable "add to cart", say "Sold out"); an option value that leads nowhere
+  (`isAvailable(name, value)` false — disable it); a failed add (`CART_LINES_UNAVAILABLE` and others:
+  show `detail`); no images (`<Image fallback>`).
+
+## Search — `app/search/page.tsx`
+
+- `api.search({ query: { q, page, perPage } })` — not cached (no tag). Suggestions while typing:
+  `searchSuggestions({ query: { q } })` from the browser; popular queries: `searchTrending`.
+- Facets: `searchFilters({ query: { q } })`.
+- States: no query yet (show the form only), no results, pagination.
+- Search pages are usually `noindex`; report `useAnalytics().search(q, total)`.
+
+## Cart — `app/cart/page.tsx`
+
+- Client only: `useCart()` — `cart`, `status` (`loading` / `updating` / `idle`), `error`, and the
+  changes (`updateLine`, `removeLine`, `setDiscountCodes`, `setNote`, `setGift`, `setPoints`).
+- Render `cart.cost` as it comes; never add prices up. Each line has `available` and `issues`.
+  Discount codes answer `applicable` and a `reasonCode`.
+- States: loading (the stored cart is being fetched), empty or no cart, a line no longer available,
+  a rejected code, the last failed change (`error`, the cart is already back to the server's).
+- Never put the cart id in a URL.
+
+## Checkout — `app/checkout/page.tsx`
+
+- Client only. `checkoutsStore({ body: { cartId } })` (safe to repeat), then fill what
+  `checkout.missing` lists, in order: `CONTACT` → `DELIVERY_ADDRESS` (or a pickup point from
+  `locationsIndex`) → `DELIVERY_OPTION` (`checkoutsDeliveryOptions`, then select by `id`) →
+  `PAYMENT_METHOD`. Each step's `PUT` answers the updated checkout.
+- `checkoutsCompletion` answers `{ order, payment }`; send the buyer to `payment.redirectUrl` when
+  `PENDING`. On their return, read `ordersPayment` (guest: header `X-Checkout-Id`) — never trust the
+  redirect.
+- States: empty cart, preparing, each step's validation errors (`VALIDATION_FAILED` → per field),
+  `DELIVERY_QUOTE_EXPIRED` (list the options again), `CHECKOUT_NOT_READY`, `CHECKOUT_CLOSED`,
+  `STORE_UNAVAILABLE`, a payment that is still pending.
+- Never put the checkout id in a URL or a log.
+
+## Account — `app/account/page.tsx`
+
+- Client only. Signed out: `useCustomer().requestOtp(phone)` → `verifyOtp(phone, code)`
+  (`OTP_INVALID`: re-type; `OTP_EXPIRED`: ask again), or Telegram / OQ / Click sign-in in those apps.
+  Only offer OTP when `shop.features.otpLogin` is on.
+- Signed in: `customerOrdersIndex`, `customerOrdersShow`, `customerWishlistIndex`, addresses,
+  rewards — through `useStorefrontClient()` (the provider adds the bearer and refreshes it).
+- States: signed out, `UNAUTHENTICATED` (sign in again), no orders yet.
+
+## Content pages, sitemap — `app/pages/[handle]/page.tsx`, `app/sitemap.ts`
+
+- `api.pagesShow({ path: { handle } })` (`magicstore:pages`) through `orNotFound`,
+  `pageMeta({ seo, title })`; `body` is the merchant's HTML (empty until written). The layout links
+  `api.pagesIndex()` in the footer.
+- `app/sitemap.ts` reads `api.sitemap({ query: { page, perPage: 1000 } })` — `{ type, handle,
+updatedAt }` rows — on `SITE_URL` or the shop's `primaryDomain`, at most 50 pages (the protocol's
+  50 000 URLs). Dynamic, like
+  every page.
+
+## Every page
+
+- Import only the SDK's entry points; `npx create-magic-storefront check` passes.
+- Not found → `notFound()`; any other failure shows `describe(error)` (`lib/errors.ts`) or lets
+  `app/error.tsx` catch it (it shows `detail`, and "temporarily closed" on `STORE_UNAVAILABLE`).
+- Images through `<Image>` (intrinsic size, lazy), prices through `<Money>`.
+- Analytics: `PageViews` in `app/providers.tsx` reports each route; product, collection and search
+  views are reported where they render.

package/template/README.md

@@ -0,0 +1,31 @@
+# MagicStore storefront starter
+
+A Next.js (App Router) storefront on the MagicStore Storefront API v2, built only on the public SDK
+(`@magicstoreai/storefront-client`, `@magicstoreai/hydrogen`). The home page from the merchant's
+sections, catalog, collections, search, product with variants, cart, checkout (pickup or delivery,
+payment), OTP sign-in and orders, SEO and JSON-LD, and a webhook that revalidates cached pages.
+
+```bash
+cp .env.example .env.local   # set MAGICSTORE_SHOP_DOMAIN
+npm install
+npm run dev
+```
+
+| Where                          | What                                                                          |
+| ------------------------------ | ----------------------------------------------------------------------------- |
+| `PAGES.md`                     | How each page type is built: data calls, cache tags, SEO, required states.    |
+| `lib/api.ts`                   | The server-side client. Public reads are cached under `magicstore:*` tags.    |
+| `components/sections/`         | One renderer per `GET /home` section type; an unknown type renders nothing.   |
+| `app/providers.tsx`            | `MagicStoreProvider`: customer, cart, wishlist and analytics in the browser.  |
+| `app/storefront-api/[...path]` | Same-origin proxy for browser calls when there is no public storefront token. |
+| `app/api/magicstore/webhook`   | Verifies the platform's webhook and revalidates the tags its topic covers.    |
+
+**Browser calls.** With `NEXT_PUBLIC_MAGICSTORE_STOREFRONT_TOKEN` (a token that lists this site's
+origin) the browser calls the shop's API directly. Without it, calls go through the proxy route,
+which forwards the buyer's address in `X-Forwarded-For`.
+
+**Offline.** `MAGICSTORE_API_URL=http://127.0.0.1:4010` with `pnpm mock` running in the SDK repository
+serves every page from the spec's example data.
+
+**Webhook.** In Shop settings → Storefront API, set the token's webhook to
+`https://<this site>/api/magicstore/webhook` and put its secret in `MAGICSTORE_WEBHOOK_SECRET`.

package/template/_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+.next/
+.env*.local
+next-env.d.ts
+*.tsbuildinfo