create-magic-storefront 0.2.0 → 0.4.0

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

@@ -0,0 +1,157 @@
+---
+name: theme-section
+description: >-
+  Create or change a theme section — a part of a page the merchant edits in the admin's theme
+  editor (a hero, a size guide, a lookbook, a FAQ). Use whenever a page gets a new block of content,
+  when asked for a "section", or when a section's settings change. Covers the five steps, the setting
+  types a section may use, and a worked example.
+---
+
+# Creating a new section
+
+A section is a file in `theme/sections/`: its schema (`defineSection`) and its React component. The
+backend has no code per section: `theme push` sends the schema, and the admin's editor, the API's
+validation and the merchant's AI tools work for that section at once. **So invent any section the
+design needs** (`size-guide`, `lookbook`, `faq`) — no one touches the backend.
+
+What the backend does not know is a new **setting type**. Compose sections from the types below;
+never invent one. A field no type covers is a contract change in magicbot, made there first.
+
+`GET /home` is optional: the theme builds the home page. Data sections fetch through the catalog
+operations (`productsIndex`, `collectionsProducts`, …), never through `/home`.
+
+## The five steps
+
+1. Create `theme/sections/<type>.tsx` with `defineSection` and the component (`SectionProps<typeof
+section>` types its `settings` and `blocks`).
+2. Register it in `theme/index.ts`: in `sections` of `defineTheme`, and its component in `components`.
+3. Put it in a template (`theme/templates/index.json` or `page.json`) or give it `presets`, so the
+   merchant can add it in the editor.
+4. Every word the buyer sees comes from a setting with a default in `en`, `ru` and `uz` (or from
+   `lib/i18n.ts` through `message()`), so the merchant can change it. Editor labels use `label(en,
+ru, uz)` from `theme/text.ts`. No copy written into the component.
+5. Run `npm run theme:check` (it must pass), then `npm run theme:push`, and bump `version` in
+   `theme/index.ts`. While developing, `npm run dev` with `MAGICSTORE_THEME_TOKEN` set pushes on
+   every change (`theme dev`).
+
+`theme check` fails on a file in `theme/sections/` that is not registered (`SECTION_NOT_REGISTERED`),
+a template that uses an unknown type, and a text setting without a default in every locale; it warns
+on copy in a component (`HARDCODED_COPY`; `// theme-copy-ok` on the line opts out).
+
+## Setting types
+
+The component receives the served value. Ids are camelCase (`^[a-z][a-zA-Z0-9]{0,63}$`); `SELECT`
+values are `UPPER_SNAKE_CASE`; every setting takes `label`, optional `info` and `default`.
+
+| Type              | Extra members                           | The component receives                                    |
+| ----------------- | --------------------------------------- | --------------------------------------------------------- |
+| `TEXT`            | `maxLength` (≤ 500)                     | `string`                                                  |
+| `TEXTAREA`        | `maxLength` (≤ 5 000)                   | `string`                                                  |
+| `RICHTEXT`        | —                                       | sanitised HTML `string` (the only HTML a section renders) |
+| `URL`             | —                                       | `string \| null`                                          |
+| `COLOR`           | —                                       | `#rrggbb` or `null`                                       |
+| `CHECKBOX`        | —                                       | `boolean`                                                 |
+| `NUMBER`          | `min`, `max` (optional)                 | `number \| null`                                          |
+| `RANGE`           | `min`, `max`, `step`, `unit` (optional) | `number`                                                  |
+| `SELECT`          | `options: [{ value, label }]` (≤ 100)   | one option `value`                                        |
+| `IMAGE`           | —                                       | `{ url, altText: null, width, height }` or `null`         |
+| `COLLECTION`      | —                                       | `{ id, handle, title }` or `null`                         |
+| `PRODUCT`         | —                                       | `{ id, handle, title }` or `null`                         |
+| `COLLECTION_LIST` | `limit` (1–50)                          | `{ id, handle, title }[]`                                 |
+| `PRODUCT_LIST`    | `limit` (1–50)                          | `{ id, handle, title }[]`                                 |
+| `HEADER`          | `content` (no `id`)                     | — (a heading in the editor form)                          |
+| `PARAGRAPH`       | `content` (no `id`)                     | — (a note in the editor form)                             |
+
+Text settings are stored per locale and served in the request's; the component only sees a string.
+`IMAGE`, `COLLECTION`, `PRODUCT` and the lists reference shop data, so their default is empty; a
+reference is not a full product — fetch what you show by `handle` through the catalog operations.
+`IMAGE` has no alt text: declare a `TEXT` setting for it. Blocks (`defineBlock`) are repeatable
+children with their own settings: slides, quotes, table rows (`maxBlocks` caps them).
+
+## Example: `size-guide`
+
+A heading and a table of `row` blocks, in `theme/sections/size-guide.tsx`:
+
+```tsx
+import { defineBlock, defineSection, type SectionProps } from '@magicstoreai/hydrogen/theme';
+
+import { label } from '../text';
+
+const row = defineBlock({
+  type: 'row',
+  name: label('Size', 'Размер', "O'lcham"),
+  settings: [
+    { id: 'size', type: 'TEXT', label: label('Size', 'Размер', "O'lcham"), default: '' },
+    { id: 'chest', type: 'TEXT', label: label('Chest', 'Грудь', "Ko'krak"), default: '' },
+    { id: 'waist', type: 'TEXT', label: label('Waist', 'Талия', 'Bel'), default: '' },
+  ],
+});
+
+export const sizeGuide = defineSection({
+  type: 'size-guide',
+  name: label('Size guide', 'Таблица размеров', "O'lchamlar jadvali"),
+  maxBlocks: 30,
+  settings: [
+    {
+      id: 'heading',
+      type: 'TEXT',
+      label: label('Heading', 'Заголовок', 'Sarlavha'),
+      default: { en: 'Size guide', ru: 'Таблица размеров', uz: "O'lchamlar jadvali" },
+    },
+    {
+      id: 'columns',
+      type: 'TEXT',
+      label: label('Column names', 'Названия колонок', 'Ustun nomlari'),
+      info: label('Separated by commas.', 'Через запятую.', 'Vergul bilan.'),
+      default: {
+        en: 'Size, Chest cm, Waist cm',
+        ru: 'Размер, Грудь см, Талия см',
+        uz: "O'lcham, Ko'krak sm, Bel sm",
+      },
+    },
+  ],
+  blocks: [row],
+  presets: [
+    {
+      name: label('Size guide', 'Таблица размеров', "O'lchamlar jadvali"),
+      blocks: [{ type: 'row' }, { type: 'row' }, { type: 'row' }],
+    },
+  ],
+});
+
+/** A size table the merchant fills row by row; nothing shows until a row has a size. */
+export function SizeGuide({ settings, blocks }: SectionProps<typeof sizeGuide>) {
+  const rows = blocks.filter((block) => block.settings.size !== '');
+  if (rows.length === 0) {
+    return null;
+  }
+  return (
+    <section className="stack">
+      <h2>{settings.heading}</h2>
+      <table>
+        <thead>
+          <tr>
+            {settings.columns.split(',').map((name) => (
+              <th key={name}>{name.trim()}</th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map(({ id, settings: cells }) => (
+            <tr key={id}>
+              <td>{cells.size}</td>
+              <td>{cells.chest}</td>
+              <td>{cells.waist}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </section>
+  );
+}
+```
+
+Then in `theme/index.ts`: `import { SizeGuide, sizeGuide } from './sections/size-guide';`, add
+`sizeGuide` to `sections` and `'size-guide': SizeGuide` to `components`. The preset lets the merchant
+add it from the editor; to show it by default, add `"size": { "type": "size-guide" }` to a template's
+`sections` and `"size"` to its `order`. Run `npm run theme:check` and `npm run theme:push`.

package/template/.env.example

@@ -10,8 +10,14 @@ MAGICSTORE_API_URL=
 # browser calls go through this app's /storefront-api proxy (app/storefront-api/[...path]).
 NEXT_PUBLIC_MAGICSTORE_STOREFRONT_TOKEN=
 
+# Optional. The storefront access token (msf_…) the server sends with its reads: the API then serves
+# this storefront's own theme, and theme previews work (they need it). Server-only; when empty, the
+# public token below is used, else the shop is found by its domain.
+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.
+# revalidates cached pages when the merchant changes the catalog, pages or home, and
+# /api/magicstore/preview verifies the theme editor's preview links with it.
 MAGICSTORE_WEBHOOK_SECRET=
 
 # The language pages render in (a locale the shop enables).

package/template/AGENTS.md

@@ -19,10 +19,10 @@ each error code means — then `PAGES.md` for how each page type is built, and
 ## 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. A server component takes only components from
+  `@magicstoreai/hydrogen/core`, `/server`, `/seo` and `/theme`. Call the API through client
+  methods, never by `/api/v2/storefront/…` URL. A server component takes only components from
   `@magicstoreai/hydrogen` (a client module); functions and classes come from `/core`, `/server`,
-  `/seo` or `@magicstoreai/storefront-client`. `npx create-magic-storefront check` must pass.
+  `/seo`, `/theme` or `@magicstoreai/storefront-client`. `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.
@@ -34,6 +34,10 @@ each error code means — then `PAGES.md` for how each page type is built, and
   every language it has (`ru`, `uz`, `en`).
 - Every page handles its empty, error and not-found states (`orNotFound` turns `NOT_FOUND` into
   the 404 page).
+- The storefront also runs as a Telegram Mini App (`PAGES.md`, "Running as a Telegram Mini App").
+  App-wide Telegram behaviour lives in `components/telegram-shell.tsx` only: one automatic
+  `useTelegramSignIn()` there, `{ auto: false }` anywhere else. Never put `initData` in a URL, a log
+  or analytics.
 
 ## Design
 
@@ -51,19 +55,55 @@ screenshot every page type at 390 and 1280px, fix what you see. Interactive UI f
 
 ## Where things go
 
-| Path                           | What                                                                                                              |
-| ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
-| `app/`                         | Pages (server components) and route handlers                                                                      |
-| `app/error.tsx`                | Error boundary: the API's `detail`, a retry                                                                       |
-| `app/blog/`                    | Blog: index, category, author, tag and article pages (`PAGES.md`, Blog)                                           |
-| `app/sitemap.ts`               | Sitemap from `GET /sitemap`                                                                                       |
-| `app/page.tsx`                 | Home: renders `GET /home` sections in the merchant's order. Optional: a custom home composes its own (`PAGES.md`) |
-| `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`                                                                                  |
+| Path                            | What                                                                                                           |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `app/`                          | Pages (server components) and route handlers                                                                   |
+| `app/error.tsx`                 | Error boundary: the API's `detail`, a retry                                                                    |
+| `app/blog/`                     | Blog: index, category, author, tag and article pages (`PAGES.md`, Blog)                                        |
+| `app/sitemap.ts`                | Sitemap from `GET /sitemap`                                                                                    |
+| `app/page.tsx`                  | Home: the theme's `index` template (`loadTemplate` + `ThemeSections`, `PAGES.md`)                              |
+| `theme/`                        | The theme: `sections/` (schema + component), `templates/*.json`, `settings.ts`, registered in `index.ts`       |
+| `components/sections/`          | One renderer per `GET /home` section type (the `platform-home` theme section); an unknown type renders nothing |
+| `components/`                   | Shared UI; client components start with `'use client'`                                                         |
+| `components/telegram-shell.tsx` | Telegram Mini App: theme marks, back arrow, the one automatic Telegram sign-in (`PAGES.md`)                    |
+| `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`                                                                               |
+| `app/api/magicstore/preview`    | Theme editor preview: signed token → draft mode; pages pass `themePreview()` (`lib/preview.ts`) as `preview`   |
+
+## Creating a new section
+
+A page part the merchant edits in the admin is a theme section. Invent any section the design needs
+(`size-guide`, `lookbook`): the backend has no code per section, so a type it has never seen is fine.
+A **setting type** it has never seen is not — compose the types below, never invent one; a missing
+type is a contract change in magicbot. `GET /home` is optional. Full recipe and a worked example
+(`size-guide`): `.claude/skills/theme-section/SKILL.md`.
+
+1. `theme/sections/<type>.tsx`: `defineSection` + the component (`SectionProps<typeof section>`).
+2. Register it in `theme/index.ts` (`sections` and `components`).
+3. Put it in `theme/templates/*.json` or give it `presets`.
+4. Every buyer-facing word comes from a setting with an `en`/`ru`/`uz` default. No copy in the component.
+5. `npm run theme:check`, then `npm run theme:push` (bump `version`); `theme dev` pushes while developing.
+
+| Type              | Extra members                           | The component receives                                    |
+| ----------------- | --------------------------------------- | --------------------------------------------------------- |
+| `TEXT`            | `maxLength` (≤ 500)                     | `string`                                                  |
+| `TEXTAREA`        | `maxLength` (≤ 5 000)                   | `string`                                                  |
+| `RICHTEXT`        | —                                       | sanitised HTML `string` (the only HTML a section renders) |
+| `URL`             | —                                       | `string \| null`                                          |
+| `COLOR`           | —                                       | `#rrggbb` or `null`                                       |
+| `CHECKBOX`        | —                                       | `boolean`                                                 |
+| `NUMBER`          | `min`, `max` (optional)                 | `number \| null`                                          |
+| `RANGE`           | `min`, `max`, `step`, `unit` (optional) | `number`                                                  |
+| `SELECT`          | `options: [{ value, label }]` (≤ 100)   | one option `value`                                        |
+| `IMAGE`           | —                                       | `{ url, altText: null, width, height }` or `null`         |
+| `COLLECTION`      | —                                       | `{ id, handle, title }` or `null`                         |
+| `PRODUCT`         | —                                       | `{ id, handle, title }` or `null`                         |
+| `COLLECTION_LIST` | `limit` (1–50)                          | `{ id, handle, title }[]`                                 |
+| `PRODUCT_LIST`    | `limit` (1–50)                          | `{ id, handle, title }[]`                                 |
+| `HEADER`          | `content` (no `id`)                     | — (a heading in the editor form)                          |
+| `PARAGRAPH`       | `content` (no `id`)                     | — (a note in the editor form)                             |
 
 ## Commands
 
@@ -72,4 +112,6 @@ npm run dev          # needs MAGICSTORE_SHOP_DOMAIN (or MAGICSTORE_API_URL) in .
 npm run build
 npm run typecheck
 npx create-magic-storefront check   # SDK used only through its public API
+npm run theme:check                 # theme sections and templates; npm run build runs it too
+npm run theme:push                  # send the theme to the shop (MAGICSTORE_THEME_TOKEN, mtt_…)
 ```

package/template/PAGES.md

@@ -17,13 +17,15 @@ errors).
 `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*`, `/blog/*`, `/menus/footer`, `/sitemap`                                               | `PAGES_UPDATED`   |
-| `magicstore:catalog` | `/products*`, `/collections*`, other `/menus/*`, `/reels`, `/sitemap` (both tags), `/locations` | `CATALOG_UPDATED` |
-| none (`no-store`)    | `/search*`, `/reviews/site`, cart, checkout, customer, orders                                   | —                 |
+| Tag                          | Paths                                                                                           | Webhook topic                    |
+| ---------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------- |
+| `magicstore:shop`            | `/shop`, `/contacts`, `/theme/section-schema`                                                   | `SHOP_UPDATED`                   |
+| `magicstore:home`            | `/home`                                                                                         | `HOME_UPDATED`                   |
+| `magicstore:pages`           | `/pages*`, `/blog/*`, `/menus/footer`, `/sitemap`                                               | `PAGES_UPDATED`                  |
+| `magicstore:catalog`         | `/products*`, `/collections*`, other `/menus/*`, `/reels`, `/sitemap` (both tags), `/locations` | `CATALOG_UPDATED`                |
+| `magicstore:theme`           | `/theme`, `/theme/settings`, `/templates/*` (both tags)                                         | `THEME_UPDATED`                  |
+| `magicstore:template:<name>` | `/templates/<name>`                                                                             | `TEMPLATE_UPDATED` (`data.name`) |
+| none (`no-store`)            | `/search*`, `/reviews/site`, cart, checkout, customer, orders, theme previews                   | —                                |
 
 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.
@@ -38,26 +40,37 @@ API's, not the build's. The fetch cache still spares the API.
 - Wraps the page in `Providers` (`MagicStoreProvider` with `shop` passed in, so the browser does not
   load it again).
 - Links the blog only when `shop.features.blog` is on (an article is readable in this language).
-
-## Home — `app/page.tsx`, `components/sections/`
-
-The home page belongs to the storefront. `GET /home` is one way to fill it, not a requirement.
-Pick one per project:
-
-- **Merchant-managed** (this starter's default): render `GET /home`, described below. The merchant
-  arranges the page in the admin and the storefront follows.
-- **Custom**: compose the page yourself from any API data — `productsIndex` with its sorts and
-  filters, `collectionsIndex`, `collectionsProducts`, `reviewsSite`, `pagesShow`, `shop.branding` —
-  in whatever layout the design calls for. Not calling `api.home()` at all is fine, and so is
-  taking only some sections from it (the merchant's `BANNER` slides, the `ANNOUNCEMENT_BAR` text)
-  and placing them where the design wants. `components/sections/` can then be deleted.
-
-A custom home is a trade-off: the merchant's home editor in the admin no longer controls the page.
-Tell whoever owns the store. Everything else still holds: data only from the API, nothing invented,
-and the page is revalidated by the tags of what it reads (`magicstore:catalog`, `magicstore:shop`),
-not by `HOME_UPDATED` unless it calls `api.home()`.
-
-### Rendering `GET /home`
+- Telegram: when `shop.features.telegramBot` is on, loads `TELEGRAM_WEB_APP_SCRIPT` (from
+  `@magicstoreai/hydrogen/core` — a plain string a server component may import) with
+  `<Script strategy="beforeInteractive">`; a shop without a bot pays nothing for it. Renders
+  `TelegramShell` (`components/telegram-shell.tsx`) inside `Providers` (see "Running as a Telegram
+  Mini App").
+
+## Home — `app/page.tsx`, `theme/`
+
+The home page belongs to the storefront. This starter is a **theme** (Online Store 2.0 style):
+
+- `theme/sections/<type>.tsx` holds one section: its schema (`defineSection`) next to its component.
+  `theme/index.ts` registers every section (`defineTheme`) and its component (`components`).
+- `theme/templates/index.json` is the home's default content; `theme/templates/page.json` lays out
+  content pages; `theme/settings.ts` holds global settings (the announcement above the header).
+- `create-magic-storefront theme push` sends the theme to the shop, and the merchant edits texts,
+  images, products and the order of sections in the admin's theme editor. `app/page.tsx` reads the
+  merchant's template with `loadTemplate(api, 'index', theme)` and renders it with `ThemeSections`;
+  until the theme is pushed, the bundled `templates/index.json` renders instead.
+- Every buyer-facing string in a section comes from a setting with a default (from `lib/i18n.ts`),
+  so the merchant can change it. `npm run theme:check` flags copy written into a component.
+
+`GET /home` is optional: the default template never calls it. The `platform-home` section renders
+the platform's home editor layout (below) when the merchant adds it in the theme editor. Theme reads
+are cached under `magicstore:theme` and `magicstore:template:<name>` (table above).
+
+A storefront may still drop the theme and compose a **custom** home from any API data —
+`productsIndex` with its sorts and filters, `collectionsIndex`, `collectionsProducts`,
+`reviewsSite`, `pagesShow`, `shop.branding`. The merchant's editor then no longer controls the page:
+tell whoever owns the store. Everything else still holds: data only from the API, nothing invented.
+
+### Rendering `GET /home` — `components/sections/`, the `platform-home` section
 
 `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
@@ -90,6 +103,15 @@ render nothing then.
 personal; render it in a client component or not at all. A shop with no sections still needs a
 home: show new arrivals.
 
+## Creating a new section
+
+A section is one file in `theme/sections/`, registered in `theme/index.ts`, placed in a template or
+given `presets`, with every buyer-facing word in a setting, then `npm run theme:check` and
+`npm run theme:push`. The backend needs nothing for a new section type — only a new setting type is
+a contract change. The steps, the setting types and a worked example (`size-guide`) are in
+`AGENTS.md` and `.claude/skills/theme-section/SKILL.md`; `theme/sections/testimonials.tsx` is a
+section with blocks to copy from.
+
 ## Collection — `app/collections/[handle]/page.tsx`
 
 - `api.collectionsShow({ path: { handle } })` and `api.collectionsProducts({ path: { handle }, query: { page, perPage } })`,
@@ -149,13 +171,68 @@ home: show new arrivals.
 
 ## 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.
+- Client only. Signed out:
+  - Phone: `useCustomer().requestOtp(phone)` → `verifyOtp(phone, code)` (`OTP_INVALID`: re-type;
+    `OTP_EXPIRED`: ask again). On a shop whose sign-in code is off
+    (`shop.features.otpLogin === false`) the same form calls `signInWithPhone(phone)` — no code
+    step.
+  - Inside a Telegram Mini App (`useTelegramWebApp().isTelegram`), above the phone form: "Sign in
+    with Telegram" — `useTelegramSignIn({ auto: false }).signIn()` (the automatic sign-in lives in
+    `components/telegram-shell.tsx`, never here). The hook shares the attempt's state, so this
+    block also shows the shell's automatic attempt: "Signing in…" while it runs, its failure
+    without a tap. `status: 'failed'` with `UNAUTHENTICATED` → the launch data is stale: ask to
+    close the shop and reopen it from the bot; `FORBIDDEN` → the shop has no bot: hide the button.
+    The phone form stays as the fallback.
+  - While `useTelegramWebApp().status` is `unknown` (server render and first paint) on a shop with
+    a bot (`shop.features.telegramBot`), an invisible copy of that block holds its place, so the
+    phone form does not jump down after mount. A shop without a bot gets no gap.
+  - OQ / Click sign-in in those apps.
 - Signed in: `customerOrdersIndex`, `customerOrdersShow`, `customerWishlistIndex`, addresses,
   rewards — through `useStorefrontClient()` (the provider adds the bearer and refreshes it).
+- Phone proof: signed in inside a Mini App with no `customer.phone` (a Telegram-only customer) and
+  `useTelegramWebApp().canRequestContact` (Bot API 6.9+; older clients cannot share) → a
+  "Share phone number" button → `useCustomer().shareTelegramPhone()` (null: the buyer declined —
+  nothing to show). Errors through `describePhoneShare` (`lib/errors.ts`): `CONTACT_EXPIRED` → share
+  again; `CONTACT_INVALID`, `CONTACT_NOT_OWN`, `INVALID_PHONE`, `TAKEN` → the API's message for
+  `telegramContact`. Never offer it to a signed-out visitor (`UNAUTHENTICATED`).
 - States: signed out, `UNAUTHENTICATED` (sign in again), no orders yet.
 
+## Running as a Telegram Mini App
+
+The same app opens inside Telegram when the shop's bot points at it: in BotFather, set the bot's
+Mini App (or menu button) URL to this site's `https://` address. Nothing else changes — same pages,
+same API.
+
+- **Script.** `app/layout.tsx` loads it only for a shop with a bot (above). It defines
+  `window.Telegram.WebApp` and writes `--tg-theme-*` / `--tg-viewport-*` / `--tg-safe-area-*` CSS
+  variables on `<html>`.
+- **Shell.** `components/telegram-shell.tsx` (`'use client'`, renders nothing) holds every
+  app-wide Telegram behaviour:
+  - `useTelegramWebApp({ documentAttributes: true })` marks `<html>` with `data-telegram` and
+    `data-color-scheme`;
+  - `useTelegramBackButton(pathname !== '/', onBack)` shows the header's back arrow off the home
+    page. `onBack` calls `router.back()` while there is app history behind the page, and
+    `router.push('/')` on the history entry the Mini App opened on (a deep link from the bot, the
+    return from a payment page), where the history before it is not the app's. The entry is told by
+    its Navigation API history index, so revisiting the first page through a link still goes back;
+    without that API, by its path;
+  - `useTelegramSignIn()` signs the buyer in with the launch data — the **only** automatic sign-in
+    in the app. A failure keeps them browsing as a guest; `/account` shows it (the hook's state is
+    shared). A referral in the `startapp` parameter is read by the server: pass no `referralCode`
+    and never parse `start_param`.
+- **Theme.** `app/globals.css` maps Telegram's colors onto the starter's tokens under
+  `html[data-telegram]` (`--bg`, `--fg`, `--muted`, `--surface`, `--placeholder`, `--accent`,
+  `--on-accent`, `--danger`), with the web values as fallbacks, and darkens `--line` for
+  `data-color-scheme="dark"`. The merchant's own accent (`brandStyle`, inline on `<html>`) still
+  wins over Telegram's button color. The merchant's `--nav-*` and `--label-*` brand tokens are not
+  overridden in Telegram's dark theme either: brand colors are the merchant's choice.
+- **Viewport.** `body` takes `--tg-viewport-stable-height` (else `100dvh`, never `100vh`) and the
+  safe-area insets; tap targets are at least 44px.
+- **MainButton.** `useTelegramMainButton` exists in the SDK; the starter does not use it.
+- **Credentials.** `initData`, tokens and the cart id never go into a URL, a log or analytics.
+- **Check by hand** with the shop's bot: opened from the bot → signed in, back arrow off the home
+  page, Telegram's colors in light and dark.
+
 ## Blog — `app/blog/`, `components/article-body.tsx`, `components/blog-listing.tsx`
 
 All blog reads are `magicstore:pages`. Rules: the backend's `docs/api/v2/blog.md`.

package/template/README.md

@@ -3,7 +3,8 @@
 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 (or your own composition: `GET /home` is optional), 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.
+payment), OTP sign-in and orders, SEO and JSON-LD, a webhook that revalidates cached pages — and it
+runs as a Telegram Mini App (sign-in from the bot, back button, Telegram's theme, phone sharing).
 
 ```bash
 cp .env.example .env.local   # set MAGICSTORE_SHOP_DOMAIN
@@ -19,13 +20,24 @@ npm run dev
 | `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.    |
+| `app/api/magicstore/preview`   | The admin's theme preview: verifies its token, turns on draft mode.           |
 
 **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`.
 
+**Telegram Mini App.** For a shop with a connected bot, set the bot's Mini App URL in BotFather to
+this site's `https://` address. The layout loads Telegram's script only for such a shop;
+`components/telegram-shell.tsx` signs the buyer in, shows the back arrow and applies Telegram's
+theme. Details: `PAGES.md`, "Running as a Telegram Mini App".
+
 **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`.
+The same secret signs the theme editor's preview links: the admin opens
+`https://<this site>/api/magicstore/preview?token=…&path=/`, which turns on draft mode for ten minutes
+and serves the draft theme to that browser only (`lib/preview.ts`); `?exit=1` ends it. Previews also need
+`MAGICSTORE_STOREFRONT_TOKEN`, the storefront token that webhook belongs to: the API previews only a
+read that names its token.

package/template/_gitignore

@@ -4,3 +4,5 @@ node_modules/
 next-env.d.ts
 *.tsbuildinfo
 .screenshots/
+.magicstore/
+.tmp/