@tanqory/dev-mcp 0.0.0-stage → 0.1.0-alpha.1

package/bundled/theme-kit/docs/headless-api.md

@@ -0,0 +1,220 @@
+# Headless API (`@tanqory/theme-kit/headless`)
+
+Every storefront function, none of the styling. Your theme owns all markup and CSS; the kit supplies data,
+behaviour and accessible primitives that render semantic HTML carrying the platform's `tq-storefront-hooks/1`
+attributes. Each primitive accepts `className` and most accept render-prop `children` for full control.
+
+The kit ships no CSS. The only class it adds is `visuallyHidden()` (an `sx()` rule). There is never a `style=""`
+attribute: the platform CSP has `style-src-attr 'none'`. Use classes or `sx()` for dynamic values.
+
+```
+@tanqory/theme-kit/headless   hooks, primitives, defineSection / defineBlock / defineTheme, t(), formatMoney, <Seo>, <Image>, ai.*
+@tanqory/theme-kit/server     createRender({ manifest, bundle, storefront: {} })    the ABI render(request, ctx)
+@tanqory/theme-kit/client     hydrate({ bundle })                                   the browser entry; live edit on the editor canvas
+@tanqory/theme-kit/build      buildManifest(...), checkContent, withKitStrings      the manifest from your declarations (Node, pure)
+```
+
+## 1. A theme in four files
+
+```tsx
+// theme.tsx
+import { defineTheme, defineSection, defineBlock, field, ai, useMenu, CartToggle, CartDrawer, ConsentBanner } from '@tanqory/theme-kit/headless'
+
+const header = defineSection({
+  type: 'header', title: 'Header', zone: 'header',
+  settings: { menu: field.resource('menu', 'main-menu', { label: 'Menu' }) },
+  ai: ai.headerMenu('menu'),
+  component: ({ settings }) => {
+    const menu = useMenu(settings.menu)
+    return <header className="mast"><nav aria-label="Main">…{menu?.items…}</nav><CartToggle className="mast__cart" /></header>
+  },
+})
+
+export default defineTheme({
+  name: 'My theme',
+  sections: [header, /* hero, product, collection, cart, search, footer, not-found … */],
+  Layout: ({ children }) => <>{children}<CartDrawer className="drawer">{(cart) => …}</CartDrawer><ConsentBanner className="consent" /></>,
+})
+```
+
+```tsx
+// entry.server.tsx — built into ONE file with no imports
+import { createRender } from '@tanqory/theme-kit/server'
+import { bundle } from './bundle'
+import manifestJson from './generated/manifest.json'
+export const manifest = manifestJson
+export const render = createRender({ manifest, bundle, storefront: { plan: { localization: true } } })
+```
+
+```tsx
+// entry.client.tsx
+import { hydrate } from '@tanqory/theme-kit/client'
+import { bundle } from './bundle'
+hydrate({ bundle })
+```
+
+```ts
+// bundle.ts
+import type { ThemeBundle } from '@tanqory/theme-kit/headless'
+import theme from './theme'
+export const bundle: ThemeBundle = {
+  theme, templates: {}, groups: {}, settings: {}, settingsSchema: {}, customSections: {}, manifest: null,
+  locales: import.meta.glob('./locales/*.json', { eager: true }),
+}
+```
+
+The manifest comes from your declarations: `buildManifest({ name, version, theme, settings, templates, forms })`
+(see §7). `examples/aurora` in this repository is a complete theme built this way.
+
+## 2. `createRender({ storefront })`
+
+`storefront` turns on what the headless API relies on. `storefront: {}` is enough; every member defaults to on.
+Without it, the render is the 2.0.0-alpha.0 one, plus the hreflang alternates every theme gets from 2.0.0-alpha.2 (`createRender({ hreflang: false })` leaves them out).
+
+| Member | Default | Effect |
+|---|---|---|
+| `structuredData` | `true` | BreadcrumbList JSON-LD (product, collection, page, article) and CollectionPage + ItemList on a collection. The product page's single Product JSON-LD is printed in every mode |
+| `merchantStrings` | `true` | Reads the merchant's dashboard wording for your strings (`ctx.data.localization.strings`, one call beside the first round; the data plan keeps the call limit with it) and lets `t()` prefer it |
+| `plan.localization` | `false` | Reads the shopper's country and lists the store's countries (the page then varies on `x-tq-country`). Needed by `<LocalizationForm>`'s country select |
+| `plan.account` | `false` | Reads `request.isSignedIn` (the page then varies on it) for `useCustomer().signedIn` |
+| `plan.recommendations` | `false` | Loads the product's recommendations in the server render (otherwise the browser loads them) |
+| `plan.collections` | `false` | Loads the store's collection list |
+
+The data plan also keeps its section conventions: a `header` or `footer` section with a `showLocale: true`
+setting reads the country, a `header` section reads sign-in state unless `showAccount` is `false`, a
+`product-recommendations` section loads recommendations, and a `collection-list` section loads every
+collection. A section of type `not-found` renders the body of a 404 page.
+
+The render also provides `usePage()` (route kind, handle, params, canonical, languages, assets base, merchant
+strings) and copies it into the hydration state, so the browser renders from the same bytes.
+
+## 3. Declaring sections and blocks
+
+```ts
+defineSection({
+  type: 'hero',                 // persisted: never rename once stores saved it
+  title: 'Hero', description?, category?, zone?: 'header' | 'main' | 'footer',
+  settings: { heading: field.text('After dark', { label: 'Heading' }), image: field.resource('image') },
+  blocks?: [defineBlock({ type: 'slide', title: 'Slide', settings: {…} })],
+  presets?: [{ name: 'Hero', settings?, blocks? }],   // presets[0] is the editor's "Add section" preview
+  requires?: ['product'],       // offered only on templates of these route kinds
+  ai?: ai.hero({ heading: 'heading', image: 'image' }),
+  component: ({ settings, blocks }) => …,
+})
+```
+
+The component receives `settings` resolved against the schema (defaults filled, coerced; a resource setting is
+its handle string) and `blocks` in the merchant's order (`{ type, settings }`). The section renderer wraps every
+section in its `data-tq-node="<id>"` element (`class="tq-node"`; style it `display: contents` to keep it out of
+your layout), and
+on the editor canvas a setting edit re-renders the section in place (`tq:canvas`, announced with
+`tq:canvas-live`). You write nothing for either.
+
+`field.*`: `text`, `textarea`, `richtext`, `url`, `color`, `boolean`, `select(options, default, { optionLabels })`,
+`range(default, min, max, step, { unit })`, `number(…)`, `resource('image' | 'video' | 'menu' | 'collection' |
+'product' | 'page' | 'blog' | 'article', default?)`. Every field takes `{ label, info, placeholder, group }`.
+
+## 4. Data hooks
+
+| Hook | Returns |
+|---|---|
+| `useSettings()` | the theme's global settings: the manifest defaults with the store's saved values over them |
+| `useShop()` | `Shop`: name, logo, contact, social, payment methods, policies, consent banner config |
+| `useMenu(handle)` | `Menu \| null` (items carry `active` for the current route) |
+| `useProduct(handleOrProduct?)` | `{ product, variant, options[{ name, values[{ value, selected, available, variantId }] }], selectOption, selectVariant, price, compareAtPrice, onSale, available, quantityAvailable, image, quantity, setQuantity, unavailable }`. Without an argument: the enclosing `<ProductForm>`'s product, else the route's, opened on `?variant=` in the server render. A variant choice keeps `?variant=` in the URL |
+| `useCollection(handle?)` | `{ collection, products, total, status, facets, selected, price, filtered, toggleFilter, setPrice, clearFilters, sort, sortOptions, setSort, hasMore, loadMore, page, pageHref }`. Inside `<CollectionProvider>` every caller shares one state. The route collection's sort and filters live in the URL (`?sort=`, `?filter.<facet>=`); the server renders `?sort=` and `?page=N`, a change re-asks the data plane |
+| `useSearch()` | `{ query, products, articles, pages, total, sort, sortOptions, href(q, sort?) }` for `/search?q=` |
+| `usePredictiveSearch(query, { limit, debounceMs })` | `{ results: { products[{ handle, title, url, price, image }], collections, queries } \| null, loading }` (browser, `data:search`) |
+| `useCart()` | `{ cart, lines, itemCount, subtotal, total, checkoutUrl, ready, loading, loadError, isOpen, justAdded, open, close, add(variantId, qty), setQuantity, remove, setNote, isBusy(id), hasFailed(id), refusal(id) }` |
+| `useCustomer()` | `{ signedIn: boolean \| null, accountUrl, accountHref }`. Customer data never reaches theme code |
+| `useLocalization()` | `{ country, language, countries[{ code, name, currencyCode, currencySymbol, current }], languages[{ code, name, current }], changeCountry, changeLanguage, href({ country, language }) }` |
+| `useRecommendations()` | `{ products, loading }` for the route's product |
+| `useConsent()` | `{ required, accept, reject, decide, reopen, privacyUrl, text }` (`required` is never true on a preview render) |
+| `usePageContent()` / `useBlog(handle?)` / `useArticle()` / `usePolicy()` | the route's content page `{ title, html }`, blog (with its articles), article (with `contentHtml`), published policy |
+| `usePage()` | `{ kind, handle, params, canonical, language, ui, languages, preview, assetsBase, strings }` |
+
+## 5. Primitives
+
+| Primitive | Renders | Behaviour |
+|---|---|---|
+| `<ProductForm product?>` | `<form data-tq-product-form>` | shares one product state; submit adds the selected variant and quantity (`cart.create` / `cart.addLines`), which opens the cart; a sold-out variant is never sent |
+| `<VariantPicker>` | `<div data-tq-variant-picker>` → `<fieldset><legend>` + a labelled `<input type="radio">` per value (`data-selected`, `data-available` on the label) | selecting updates price, stock, image and `?variant=`; `renderValue` for swatches |
+| `<ProductPrice>` | `<span data-tq-price>`, regular price in `<s>` on a sale | formatted in the market currency |
+| `<ProductQuantity>` | labelled `<input type="number" min="1">` | |
+| `<AddToCart>` | `<button type="submit" data-tq-action="cart:add">` | disabled and "Sold out" when the variant cannot be bought; "Adding…" in flight |
+| `<CartToggle drawer?>` | `<a href="/cart" data-tq-action="cart:open" aria-haspopup="dialog" aria-expanded>` | opens the drawer (plain link without JavaScript) |
+| `<CartDrawer>` | `role="dialog" aria-modal="true"` (+ optional backdrop) while open | focus moves in, Tab is trapped, Escape closes, focus returns to the opener |
+| `<CartLine line>` | `<li data-tq-cart-line>` | gives its controls the line |
+| `<CartLineQuantity>` | labelled `<input type="number" data-tq-quantity>` | saved on Enter or blur; 0 removes; invalid input is put back |
+| `<CartLineIncrement>` / `<CartLineDecrement>` / `<CartLineRemove>` | buttons `data-tq-action="cart:increment"` / `cart:decrement` / `cart:remove` | disabled while the line's request is open |
+| `<CheckoutButton>` | `<a data-tq-action="cart:checkout" href={Cart.checkoutUrl}>` | checkout is the platform's |
+| `<CollectionProvider handle?>` | nothing | one `useCollection()` state for the subtree |
+| `<SortSelect>` | `<form method="get">` + labelled `<select name="sort" data-tq-sort>` | re-sorts in place; without JavaScript the form submits `?sort=` |
+| `<FacetFilters>` | `<div data-tq-filter>` → `<fieldset>` + checkbox per value (`data-active`), price from/to, "Clear filters" | |
+| `<Pagination>` | `<nav data-tq-pagination>` → "Load more" `<a rel="next" href="?page=N">` | appends in place; a real page link without JavaScript |
+| `<SearchForm>` | `<form role="search" action="/search">` + `<input type="search" name="q" data-tq-search>` + polite live region | predictive suggestions as links |
+| `<LocalizationForm>` | `<form method="get" data-tq-localization>` + `<select name="country">` ("Japan (JPY ¥)") + `<select name="locale">` | a choice loads `?country=` / `?locale=` |
+| `<NewsletterForm>` / `<ContactForm>` | `<form method="post" data-tq-form="newsletter\|contact">` + honeypot | native platform post (declare `forms` in the manifest); the gateway's CSRF fields are kept on hydration; status messages after the post |
+| `<ConsentBanner>` | `<section data-tq-consent-banner aria-label>` | only when the platform asks; the merchant's wording wins; never in preview |
+| `<AccountSlot>` | `<iframe data-tq-slot="account" sandbox="allow-scripts allow-forms allow-same-origin">` | the platform's account area on the customer route |
+
+## 6. Platform helpers
+
+- **`t()`**: `const t = useTranslate(); t('product.addToCart')`, `t('cart.cartCount', { count })`. Lookup order:
+  the merchant's dashboard wording → your `locales/<lang>.json` → the kit's words for that language
+  (`KIT_STRINGS`, English and Thai) → English → the key. `withKitStrings(locales)` (build) lays your files over
+  the kit's, so every key the primitives use exists in every locale you ship.
+- **`formatMoney(money, { display, trimZeros })`**: `$37.50`, `¥5,625`, `฿1,312.50`, `1.250 KWD`. The currency's
+  own minor units (`currencyDecimals`), identical on the server and in the browser.
+- **`<Image image alt>`**: `image` is an image from the data or an image setting's URL; `https:` URLs, or `asset:client/<file>` under the artifact's asset base; anything
+  else renders `fallback`. Intrinsic width/height, `loading="lazy"`, `decoding="async"` by default.
+- **`<Seo title description image noindex jsonLd>`**: overrides for this page's head, collected during the
+  server render. Title, description, canonical, Open Graph and the Product/Collection/Breadcrumb
+  JSON-LD are already printed from the data, and so are the hreflang alternates (every theme, `createRender({ hreflang })`, default on); a Product object in `jsonLd` is ignored (exactly one per page).
+- **`<SkipLink>`**: to `#main`, the `<main>` the section renderer wraps the page body in.
+
+## 7. The manifest (`@tanqory/theme-kit/build`)
+
+```js
+import { buildManifest, checkContent, withKitStrings } from '@tanqory/theme-kit/build'
+import { validateManifest, validateFieldValue } from '@tanqory/theme-abi'
+
+const { manifest, problems } = buildManifest({
+  name: '@acme/theme', version: '1.0.0', theme,
+  settings,                          // defineSettings({...}) → settingsSchema, grouped by `group`
+  templates: { index: { route: 'home' }, product: { route: 'product' }, '404': { route: 'not_found' }, … },
+  forms: { newsletter: true, contact: true },
+  capabilities: { server: ['data:inventory'], browser: ['data:inventory'] },
+  checkValue: validateFieldValue,
+})
+```
+
+It derives `components` (sections and blocks with their attributes, regions, children, parents, requires,
+presets), `settingsSchema`, `routes`, `templates`, `regions` (header and footer shared, `main` per template),
+`forms` and `x-tanqory-ai`. Validate the result with `validateManifest` before writing it.
+
+**Capabilities.** The defaults are what the kit's runtime calls (`SERVER_CAPABILITIES`, `BROWSER_CAPABILITIES`).
+`data:shop` is always declared: the platform gives shop data to the browser snapshot only to a theme that
+declares it (decision D6). Add `data:inventory` to show stock counts.
+
+## 8. AI compatibility
+
+Declare which of your sections play the roles Tanqory AI fills; the build prints the profile as
+`manifest["x-tanqory-ai"]` (draft v0) and `checkAiProfile` verifies every component, block and setting it names.
+
+| Helper | Role | Keys (setting types) |
+|---|---|---|
+| `ai.hero({ heading, subheading?, image?, button?, link?, block? })` | `hero` | text / image / text / url |
+| `ai.headerMenu(setting)` | `headerMenu` | a `menu` setting |
+| `ai.footerMenu(setting, { block })` | `footerMenus` | a `menu` setting (usually on a block) |
+| `ai.footerBrand({ block? })` | `footerBrand` | |
+| `ai.productGrid(setting, { heading? })` | `productGrid` | a `collection` or `product` setting |
+| `ai.richText({ heading?, body? })` | `richText` | text settings |
+
+## 9. Storefront hooks emitted (`tq-storefront-hooks/1`)
+
+`data-tq-action="cart:add|cart:open|cart:checkout|cart:remove|cart:increment"`, `data-tq-quantity`,
+`data-tq-price`, `data-tq-variant-picker`, `data-tq-sort`, `data-tq-filter`, `data-tq-pagination`,
+`data-tq-localization`, `data-tq-search`, `data-tq-consent-banner`, plus `data-tq-form`, `data-tq-slot="account"`
+and `data-tq-node` from the platform contract. A menu button for a mobile menu is the theme's own markup: give it
+`data-tq-action="menu:open"`.

package/bundled/theme-kit/generated/kit-strings.json

@@ -0,0 +1,180 @@
+{
+  "en": {
+    "a11y.close": "Close",
+    "a11y.skipToContent": "Skip to content",
+    "account.title": "Account",
+    "breadcrumbs.home": "Home",
+    "cart.cartCount": "Cart ({count})",
+    "cart.checkout": "Check out",
+    "cart.close": "Close cart",
+    "cart.decrease": "Decrease quantity",
+    "cart.empty": "Your cart is empty.",
+    "cart.increase": "Increase quantity",
+    "cart.limitReached": "You can buy up to {max} of this item.",
+    "cart.lineFailed": "This change could not be saved.",
+    "cart.loadError": "We couldn't load your cart. Retrying…",
+    "cart.loading": "Loading your cart…",
+    "cart.openCart": "Cart",
+    "cart.quantity": "Quantity",
+    "cart.remove": "Remove",
+    "cart.subtotal": "Subtotal",
+    "cart.title": "Your cart",
+    "cart.total": "Total",
+    "collection.clearFilters": "Clear filters",
+    "collection.empty": "No products match these filters.",
+    "collection.filter": "Filter",
+    "collection.loadError": "We couldn't load more products.",
+    "collection.loadMore": "Load more",
+    "collection.loading": "Loading…",
+    "collection.pagination": "Pagination",
+    "collection.previous": "Previous page",
+    "collection.priceFrom": "From",
+    "collection.priceTo": "To",
+    "collection.productCount": "{count} products",
+    "collection.sort": "Sort",
+    "consent.accept": "Accept",
+    "consent.body": "We use cookies to run this store and, with your permission, to measure and improve it.",
+    "consent.privacy": "Privacy policy",
+    "consent.reject": "Decline",
+    "consent.title": "Cookies",
+    "contact.done": "Thanks — we'll get back to you soon.",
+    "contact.message": "Message",
+    "contact.name": "Name",
+    "contact.phone": "Phone",
+    "contact.send": "Send message",
+    "filter.available": "Availability",
+    "filter.available.false": "Out of stock",
+    "filter.available.true": "In stock",
+    "filter.price": "Price",
+    "filter.productType": "Product type",
+    "filter.vendor": "Brand",
+    "form.email": "Email",
+    "form.expired": "This page expired. Please submit the form again.",
+    "form.invalidEmail": "Enter a valid email address.",
+    "form.rateLimited": "Too many attempts. Please try again in a minute.",
+    "form.unavailable": "This form isn't available right now. Please try again later.",
+    "form.website": "Website",
+    "localization.country": "Country/region",
+    "localization.language": "Language",
+    "localization.update": "Update",
+    "menu.closeMenu": "Close menu",
+    "menu.menu": "Menu",
+    "newsletter.done": "Thanks — you're on the list.",
+    "newsletter.subscribe": "Subscribe",
+    "product.addFailed": "This item could not be added to your cart.",
+    "product.addToCart": "Add to cart",
+    "product.adding": "Adding…",
+    "product.inStock": "In stock",
+    "product.lowStock": "Only {count} left",
+    "product.quantity": "Quantity",
+    "product.regularPrice": "Regular price",
+    "product.salePrice": "Sale price",
+    "product.soldOut": "Sold out",
+    "product.unavailable": "Unavailable",
+    "search.none": "No results for “{query}”.",
+    "search.placeholder": "Search the store",
+    "search.products": "Products",
+    "search.results": "{count} results for “{query}”",
+    "search.search": "Search",
+    "search.submit": "Search",
+    "search.suggestions": "Suggestions",
+    "sort.best-selling": "Best selling",
+    "sort.created-asc": "Oldest",
+    "sort.created-desc": "Newest",
+    "sort.featured": "Featured",
+    "sort.price-asc": "Price, low to high",
+    "sort.price-desc": "Price, high to low",
+    "sort.relevance": "Relevance",
+    "sort.title-asc": "Name, A–Z",
+    "sort.title-desc": "Name, Z–A"
+  },
+  "th": {
+    "a11y.close": "ปิด",
+    "a11y.skipToContent": "ข้ามไปยังเนื้อหา",
+    "account.title": "บัญชี",
+    "breadcrumbs.home": "หน้าแรก",
+    "cart.cartCount": "ตะกร้า ({count})",
+    "cart.checkout": "ชำระเงิน",
+    "cart.close": "ปิดตะกร้า",
+    "cart.decrease": "ลดจำนวน",
+    "cart.empty": "ตะกร้าของคุณว่างอยู่",
+    "cart.increase": "เพิ่มจำนวน",
+    "cart.limitReached": "ซื้อสินค้านี้ได้สูงสุด {max} ชิ้น",
+    "cart.lineFailed": "บันทึกการเปลี่ยนแปลงนี้ไม่สำเร็จ",
+    "cart.loadError": "โหลดตะกร้าไม่สำเร็จ กำลังลองใหม่…",
+    "cart.loading": "กำลังโหลดตะกร้า…",
+    "cart.openCart": "ตะกร้า",
+    "cart.quantity": "จำนวน",
+    "cart.remove": "นำออก",
+    "cart.subtotal": "ยอดรวมย่อย",
+    "cart.title": "ตะกร้าของคุณ",
+    "cart.total": "ยอดรวม",
+    "collection.clearFilters": "ล้างตัวกรอง",
+    "collection.empty": "ไม่มีสินค้าที่ตรงกับตัวกรองนี้",
+    "collection.filter": "ตัวกรอง",
+    "collection.loadError": "โหลดสินค้าเพิ่มไม่สำเร็จ",
+    "collection.loadMore": "โหลดเพิ่ม",
+    "collection.loading": "กำลังโหลด…",
+    "collection.pagination": "การแบ่งหน้า",
+    "collection.previous": "หน้าก่อนหน้า",
+    "collection.priceFrom": "ตั้งแต่",
+    "collection.priceTo": "ถึง",
+    "collection.productCount": "สินค้า {count} รายการ",
+    "collection.sort": "เรียงตาม",
+    "consent.accept": "ยอมรับ",
+    "consent.body": "เราใช้คุกกี้เพื่อให้ร้านค้าทำงาน และเพื่อวัดผลและปรับปรุงร้านเมื่อคุณอนุญาต",
+    "consent.privacy": "นโยบายความเป็นส่วนตัว",
+    "consent.reject": "ปฏิเสธ",
+    "consent.title": "คุกกี้",
+    "contact.done": "ขอบคุณ เราจะติดต่อกลับโดยเร็ว",
+    "contact.message": "ข้อความ",
+    "contact.name": "ชื่อ",
+    "contact.phone": "โทรศัพท์",
+    "contact.send": "ส่งข้อความ",
+    "filter.available": "สถานะสินค้า",
+    "filter.available.false": "สินค้าหมด",
+    "filter.available.true": "มีสินค้า",
+    "filter.price": "ราคา",
+    "filter.productType": "ประเภทสินค้า",
+    "filter.vendor": "แบรนด์",
+    "form.email": "อีเมล",
+    "form.expired": "หน้านี้หมดอายุแล้ว กรุณาส่งแบบฟอร์มอีกครั้ง",
+    "form.invalidEmail": "กรุณากรอกอีเมลให้ถูกต้อง",
+    "form.rateLimited": "ลองหลายครั้งเกินไป กรุณาลองใหม่ในอีกสักครู่",
+    "form.unavailable": "แบบฟอร์มนี้ใช้งานไม่ได้ในขณะนี้ กรุณาลองใหม่ภายหลัง",
+    "form.website": "เว็บไซต์",
+    "localization.country": "ประเทศ/ภูมิภาค",
+    "localization.language": "ภาษา",
+    "localization.update": "อัปเดต",
+    "menu.closeMenu": "ปิดเมนู",
+    "menu.menu": "เมนู",
+    "newsletter.done": "ขอบคุณ คุณได้สมัครรับข่าวสารแล้ว",
+    "newsletter.subscribe": "สมัครรับข่าวสาร",
+    "product.addFailed": "ไม่สามารถเพิ่มสินค้านี้ลงตะกร้าได้",
+    "product.addToCart": "เพิ่มลงตะกร้า",
+    "product.adding": "กำลังเพิ่ม…",
+    "product.inStock": "มีสินค้า",
+    "product.lowStock": "เหลือเพียง {count} ชิ้น",
+    "product.quantity": "จำนวน",
+    "product.regularPrice": "ราคาปกติ",
+    "product.salePrice": "ราคาลด",
+    "product.soldOut": "สินค้าหมด",
+    "product.unavailable": "ไม่มีจำหน่าย",
+    "search.none": "ไม่พบผลลัพธ์สำหรับ “{query}”",
+    "search.placeholder": "ค้นหาในร้าน",
+    "search.products": "สินค้า",
+    "search.results": "พบ {count} รายการสำหรับ “{query}”",
+    "search.search": "ค้นหา",
+    "search.submit": "ค้นหา",
+    "search.suggestions": "คำแนะนำ",
+    "sort.best-selling": "ขายดี",
+    "sort.created-asc": "เก่าที่สุด",
+    "sort.created-desc": "ใหม่ล่าสุด",
+    "sort.featured": "แนะนำ",
+    "sort.price-asc": "ราคา ต่ำไปสูง",
+    "sort.price-desc": "ราคา สูงไปต่ำ",
+    "sort.relevance": "ความเกี่ยวข้อง",
+    "sort.title-asc": "ชื่อ ก–ฮ",
+    "sort.title-desc": "ชื่อ ฮ–ก"
+  }
+}

package/bundled/theme-kit/types/headless/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `@tanqory/theme-kit/headless` — every storefront function, no styling. A theme supplies all markup and CSS;
+ * the kit supplies the data, the behaviour and accessible, semantic primitives carrying the platform's
+ * `tq-storefront-hooks/1` attributes (`data-tq-action`, `data-tq-price`, `data-tq-variant-picker`, …).
+ *
+ *   declare   defineTheme · defineSection · defineBlock · field · ai.*
+ *   data      useShop · useMenu · useProduct · useCollection · useSearch · usePredictiveSearch · useCart ·
+ *             useCustomer · useLocalization · useRecommendations · useConsent · usePage
+ *   commerce  ProductForm · VariantPicker · ProductPrice · ProductQuantity · AddToCart · CartToggle · CartDrawer ·
+ *             CartLine (+ Quantity / Increment / Decrement / Remove) · CheckoutButton · CollectionProvider ·
+ *             FacetFilters · SortSelect · Pagination · SearchForm · LocalizationForm · NewsletterForm ·
+ *             ContactForm · ConsentBanner · AccountSlot
+ *   platform  Seo · Image · SkipLink · useTranslate (t) · formatMoney · currencyDecimals · sx
+ *
+ * The server entry is `createRender({ manifest, bundle, storefront: {} })` (`@tanqory/theme-kit/server`); the
+ * browser entry is `hydrate({ bundle })` (`@tanqory/theme-kit/client`), which also applies live edits on the
+ * editor canvas. The manifest comes from `buildManifest` (`@tanqory/theme-kit/build`).
+ */
+export { defineTheme, defineSection, defineBlock, type HeadlessThemeDefinition, type SectionDefinition, type SectionComponentProps, type SectionPresetDef, type BlockSchema, type BlockInstance, type HeadlessSection, type SettingsFor } from './theme.js';
+export { ai, aiProfileOf, checkAiProfile, type AiRole, type AiProfile } from './ai.js';
+export { field, defineSchema, resolveSettings, type Field, type Fields, type Schema } from '../sdk/schema.js';
+export { defineSettings, type SettingSpec } from '../sdk/theme.js';
+export { useSettings, useShop, useMenu, useProduct, useProductState, useCollection, useCollectionState, useSearch, usePredictiveSearch, useCart, useCustomer, useLocalization, useRecommendations, useConsent, usePageContent, useBlog, useArticle, usePolicy, initialVariant, optionStates, ProductContext, CollectionContext, COLLECTION_SORTS, SEARCH_SORT_IDS, type ProductState, type OptionValueState, type CollectionState, type CollectionSort, type SearchState, type PredictiveResults, type CartStateHeadless as CartState, type CustomerState, type LocalizationState, type CountryChoice, type LanguageChoice, type ConsentState, } from './hooks.js';
+export { usePage, DETACHED_PAGE, type PageInfo } from './page.js';
+export { ProductForm, VariantPicker, ProductPrice, ProductQuantity, AddToCart, useProductForm, type ProductFormState, type ProductFormProps, type VariantPickerProps, type ProductPriceProps, type ProductQuantityProps, type AddToCartProps } from './primitives/product.js';
+export { CartToggle, CartDrawer, CartLine, CartLineQuantity, CartLineIncrement, CartLineDecrement, CartLineRemove, CheckoutButton, useCartLine, type CartLineState, type CartToggleProps, type CartDrawerProps, type CartLineProps } from './primitives/cart.js';
+export { CollectionProvider, SortSelect, FacetFilters, Pagination, type CollectionProviderProps, type SortSelectProps, type FacetFiltersProps, type PaginationProps } from './primitives/collection.js';
+export { SearchForm, LocalizationForm, NewsletterForm, ContactForm, ConsentBanner, AccountSlot, type SearchFormProps, type LocalizationFormProps, type PlatformFormProps, type PlatformFormState, type FormStatus, type ConsentBannerProps } from './primitives/storefront.js';
+export { Seo, Image, SkipLink, resolveImageUrl, type SeoProps, type ImageProps } from './platform.js';
+export { useTranslate, translate, interpolate, KIT_STRINGS, kitStrings, type Translate, type TranslateVars, type Strings } from './i18n.js';
+export { formatMoney, currencyDecimals, currencySymbol, type MoneyLike, type FormatMoneyOptions } from './money.js';
+export { productJsonLd, collectionJsonLd, breadcrumbJsonLd, type JsonLd, type Crumb } from './structured-data.js';
+export { sx, cx as sxJoin } from '../sdk/sx.js';
+export { visuallyHidden } from './primitives/util.js';
+export type { Shop, Menu, MenuItem, Link, Image as ImageData, Video, Money, Product, ProductVariant, ProductOption, Collection, Facet, FacetValue, SortOption, Cart, CartLine as CartLineData, Article, Blog, Policy, Localization, Market, BreadcrumbItem, SearchResults } from '../sdk/types.js';
+export type { ThemeBundle } from '../runtime/slots.js';

package/bundled/theme-kit/types/headless/theme.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Declaring a headless theme: its sections and blocks with their settings schema, and the theme itself.
+ *
+ *   const hero = defineSection({
+ *     type: 'hero', title: 'Hero', settings: { heading: field.text('After dark', { label: 'Heading' }) },
+ *     presets: [{ name: 'Hero' }],
+ *     ai: ai.hero({ heading: 'heading' }),
+ *     component: ({ settings }) => <section><h1>{settings.heading}</h1></section>,
+ *   })
+ *   export default defineTheme({ name: 'Aurora', sections: [header, hero, footer], Layout })
+ *
+ * A section component receives `{ settings, blocks }`: every setting resolved against its schema (defaults filled,
+ * legacy values mapped, types coerced; a resource setting is its handle, for `useMenu` / `useCollection` /
+ * `useProduct` / `<Image>`), and its blocks in order, each with its own resolved settings. The section renderer
+ * wraps each section in its `data-tq-node` element, and the canvas applies live edits to these props.
+ */
+import type { ComponentType, ReactNode } from 'react';
+import { type Fields, type HandlesOf, type Schema, type SettingsOf } from '../sdk/schema.js';
+import type { SectionZone, ThemeDefinition, ThemeSection } from '../sdk/theme.js';
+import type { AiRole } from './ai.js';
+/** A section's or block's settings as its component receives them. */
+export type SettingsFor<F extends Fields> = SettingsOf<Schema<F>> & HandlesOf<Schema<F>>;
+/** One block of a section, in the merchant's order. */
+export interface BlockInstance {
+    type: string;
+    settings: Record<string, unknown>;
+}
+export interface SectionComponentProps<F extends Fields = Fields> {
+    settings: SettingsFor<F>;
+    blocks: BlockInstance[];
+}
+/** A block definition (`defineBlock`): a settings schema that nests in sections. */
+export type BlockSchema<F extends Fields = Fields> = Schema<F> & {
+    readonly ai?: AiRole | readonly AiRole[];
+};
+/** Declare a block: its persisted type, its settings, and the sections it may be placed in. */
+export declare function defineBlock<const F extends Fields>(def: {
+    type: string;
+    title: string;
+    description?: string;
+    settings: F;
+    parents?: readonly string[];
+    requires?: readonly string[];
+}): BlockSchema<F>;
+export interface SectionPresetDef {
+    name: string;
+    settings?: Record<string, unknown>;
+    blocks?: {
+        type: string;
+        settings?: Record<string, unknown>;
+    }[];
+}
+export interface SectionDefinition<F extends Fields> {
+    /** The persisted section type: never changes once stores have saved it. */
+    type: string;
+    title: string;
+    /** One line for the editor's "Add section" picker. */
+    description?: string;
+    /** The picker group. */
+    category?: string;
+    /** Where the page places it: the header zone, the page body (default), the footer zone. */
+    zone?: SectionZone;
+    settings: F;
+    /** The blocks this section accepts. */
+    blocks?: readonly BlockSchema[];
+    /** "Add section" starting points; `presets[0]` is what the editor previews. */
+    presets?: readonly SectionPresetDef[];
+    /** Route kinds the section needs (`product`, `collection`, `cart`, …): offered only on those templates. */
+    requires?: readonly string[];
+    /** The roles it plays for Tanqory AI (`ai.hero`, `ai.headerMenu`, …). */
+    ai?: AiRole | readonly AiRole[];
+    component: ComponentType<SectionComponentProps<F>>;
+}
+/** A section as the runtime and the build read it. */
+export type HeadlessSection<F extends Fields = Fields> = ThemeSection<SectionComponentProps<F>> & {
+    readonly ai?: AiRole | readonly AiRole[];
+    readonly headless: true;
+};
+/** Declare a section of a headless theme. */
+export declare function defineSection<const F extends Fields>(def: SectionDefinition<F>): HeadlessSection<F>;
+export interface HeadlessThemeDefinition {
+    name: string;
+    /** Every section, in the editor picker's order. A section of type `not-found` renders the 404 body. */
+    sections: readonly HeadlessSection<any>[];
+    /** The page layout around the sections (the runtime renders header zone → `<main id="main">` → footer zone inside it); a place for `<CartDrawer>` and `<ConsentBanner>`. */
+    Layout?: ComponentType<{
+        children: ReactNode;
+    }>;
+    /** Wraps every page and the editor's single-section preview. */
+    Provider?: ThemeDefinition['Provider'];
+    /** Words for the breadcrumb trail; the kit's strings by default. */
+    labels?: ThemeDefinition['labels'];
+    /** External stylesheets every page loads (web fonts). */
+    stylesheets?: readonly string[];
+    /** English words the theme ships in defaults and presets, rendered in the page's language (`copy.*` locale keys). */
+    shippedCopy?: ThemeDefinition['shippedCopy'];
+}
+/** Declare a headless theme. */
+export declare function defineTheme(def: HeadlessThemeDefinition): ThemeDefinition;