@tanqory/dev-mcp 0.0.0-stage → 0.1.0

package/bundled/theme-conformance/docs/storefront-tier.md

@@ -0,0 +1,250 @@
+# Storefront-ready tier and budgets tier
+
+`theme-conformance run <theme-dir> --tier storefront` checks that a theme **works like a full storefront**:
+a shopper can pick a variant, add to the cart, change and remove lines, reach checkout, sort, filter, page,
+search, switch market and language, use a keyboard, and the merchant can live-edit it in the editor.
+`--tier budgets` checks size budgets and a lab approximation of the mobile performance and accessibility
+scores. `--tier security` (the default) is the nine ABI suites and is unchanged. `--tier all` runs all three.
+
+```
+theme-conformance run ./dist --tier storefront   # → ./storefront-report.json
+theme-conformance run ./dist --tier all --evidence ./evidence --storefront-out ./reports/storefront.json
+```
+
+The storefront tier is **theme-agnostic**. It never reads a class name or the markup of a particular
+theme. It relies only on:
+
+1. the ABI contract (`theme-abi-v2.md`): route kinds, `ctx.data`, `/_tq/data/*`, `/_tq/actions/*`,
+   the CSRF meta tag, `data-tq-form`, `data-tq-slot="account"`, `data-tq-node`, `?variant=`, `?country=`,
+   `?locale=`, the editor's canvas protocol;
+2. the theme's `manifest.json` (routes, components, presets, capabilities, forms);
+3. semantic HTML and ARIA (roles, accessible names, `aria-expanded`, `disabled`);
+4. the theme's **own locale strings** (`locales/<lang>.json`), found by key patterns (§4);
+5. optional `data-tq-*` hooks (§5) — a theme that emits them is found exactly; a theme that does not is
+   found through 1–4.
+
+## 1. How it runs
+
+- The theme's `server/entry.mjs` runs under **workerd** with the conformance harness shim, in storefront mode
+  (`job.storefront: true`): data answers depend on their arguments (sort, filters, cursors, `page`, search
+  query) and cart actions keep real state (versions, conflicts, `checkoutUrl`). The nine security suites
+  never use this mode; their behaviour and their report are unchanged.
+- A **gateway** in the runner plays the platform edge for headless Chromium (one browser): route
+  resolution (§2.1), templates (`templateSuffix` → `routes[kind]` → platform minimal page), market and
+  language from `?country=` / `?locale=` remembered for the session, the cart cookie, the native form POST
+  decision order (§1), `/_tq/data/*`, `/_tq/actions/*` (the `x-tq-csrf` header is required), `/_tq/csrf`,
+  the CSRF meta tag and hidden form fields, the platform CSP, `/checkout*` interception (the hand-off URL
+  is recorded), and the preview channel (`/_tq/editor-bridge.js`, `?tq_section_preview=`).
+- Nothing leaves the machine: DNS and every connection are locked down (as suite 5), and every request is
+  answered by the gateway.
+- **Fixture store** (`tq-storefront-fixture/1`, generated by `src/storefront/fixture.ts`): 60 products in
+  `all` (more than one page of 50), collection `linen`, two vendors (`Atelier North`, `Field & Co`), a hero
+  product `linen-shirt` with option `Colour` = Ivory 37.50 (in stock), Charcoal 52.25 (3 left), Moss 44.75
+  (sold out), each with its own image; markets `m_us` USD (default), `m_th` THB (2 decimals), `m_jp` JPY
+  (0 decimals); languages `en` (default) and `th`; page `about`, blog `journal` with two articles, two
+  policies, menus `main-menu` and `footer`; consent unknown (a banner is required) for consent checks.
+- Viewports: desktop 1280×900, mobile 390×844 (DPR 2, touch).
+
+## 2. Checks
+
+Status per check: `pass`, `fail`, `warn` (reported, never fails the tier), `not_applicable`, `incomplete`
+(the runner could not perform it; fails the tier). Every non-pass check carries a `fixHint`.
+
+| Group | Check id | Passes when |
+|---|---|---|
+| templates | `templates:home` `…:collection` `…:product` `…:search` `…:cart` `…:page` `…:blog` `…:article` | the theme maps the route kind and renders `200 text/html` with the fixture |
+| templates | `templates:404` | `routes.not_found` renders with status 404 |
+| templates | `templates:404-missing-resource` | `/products/no-such-product` answers 404 |
+| templates | `templates:password` | always `not_applicable`: the password gate is platform-owned in ABI v2 |
+| templates | `templates:account-slot` | `/account` holds `<iframe data-tq-slot="account" src="<data.customer.accountUrl()>" sandbox="allow-scripts allow-forms allow-same-origin">` (server HTML or after hydration), or the theme has no `routes.customer` (the platform shell holds it) |
+| seo | `seo:title`, `seo:meta-description` | every page has a `<title>`; home/product/collection/page/article have a meta description |
+| seo | `seo:canonical` | exactly one canonical link, equal to `ctx.route.canonical` (no query) — also with `?variant=` / `?sort=` |
+| seo | `seo:hreflang` | home, product and collection link every published language (`<link rel="alternate" hreflang>` with absolute same-origin hrefs) |
+| seo | `seo:product-jsonld` | exactly one Product JSON-LD, valid JSON, `name`, offers with a real variant price, `priceCurrency` of the market, a schema.org availability URL |
+| seo | `seo:sitemap-robots` | no custom route claims `/sitemap*.xml` or `/robots.txt` |
+| product | `product:variant-url-ssr` | `?variant=<Charcoal id>` shows Charcoal's price in the server HTML (JS off) |
+| product | `product:variant-price` | choosing Charcoal shows its price in the product section |
+| product | `product:variant-image` | after choosing Charcoal the largest visible product image is Charcoal's |
+| product | `product:variant-stock` | choosing the sold-out Moss shows a sold-out state (sold-out string, disabled add) or the option itself is disabled |
+| product | `product:oos-disables-add` | with `?variant=<Moss id>` the add control is disabled/absent and sends no cart action |
+| cart | `cart:add` | the add control adds the selected variant (browser `cart.create`/`cart.addLines`, or a declared form post that calls `ctx.actions.cart`) |
+| cart | `cart:totals` | text that appears after the add (a drawer) or `/cart` shows the line title and the cart total |
+| cart | `cart:quantity` | setting the quantity to 2 on `/cart` updates the cart and shows the new total |
+| cart | `cart:checkout-handoff` | the checkout control loads exactly `Cart.checkoutUrl` |
+| cart | `cart:remove` | the remove control empties the cart and the page no longer shows the line |
+| collection | `collection:sort` | some sort choice yields a product list that is correctly sorted (price, title, date or best-selling, either direction) and differs from the default |
+| collection | `collection:filter` | choosing vendor `Field & Co` narrows the list to that vendor (facets behind ARIA disclosures are opened) |
+| collection | `collection:pagination` | products beyond the first page are reachable (`?page=2` link, `rel=next`, load-more, infinite scroll), or all 60 are on the first page |
+| search | `search:results` | `/search?q=linen` links the three linen products |
+| search | `search:predictive` | `not_applicable` unless `capabilities.browser` has `data:search`; then typing `lin` makes a `catalog.predictive`/`catalog.search` call and a "Linen Shirt" option/link appears |
+| i18n | `i18n:locales` | `locales/en.json` and `locales/th.json` exist |
+| i18n | `i18n:keys` | (warn) every en key exists in th |
+| i18n | `i18n:hardcoded-text` | no visible string is identical in en and th unless it is store data, merchant content (the theme's defaults/presets), a number/price/punctuation, a language/country name, or identical in both locale files |
+| i18n | `i18n:html-lang` | `<html lang>` follows `?locale=` |
+| i18n | `i18n:currency` | the hero price shows in USD (2 decimals), THB (2) and JPY (0 decimals) with a currency mark |
+| i18n | `i18n:market-selector` | from the UI the shopper reaches `?country=JP` and prices switch to JPY |
+| a11y | `a11y:axe` | axe-core (wcag2a/aa, wcag21a/aa, wcag22aa) reports no serious/critical violation on home, product, collection, cart (with a line), search, 404 — desktop and mobile |
+| a11y | `a11y:keyboard-desktop` `a11y:keyboard-mobile` | Tab from the top focuses the cart control and the menu within 80 presses |
+| a11y | `a11y:touch-targets` | on mobile every standalone interactive element's real hit area (hit-tested, so stretched links count) covers 44×44 CSS px; links inside running text and targets with a large-enough equivalent link to the same href are exempt |
+| editor | `editor:data-tq-node` | every section of the page document has a `data-tq-node` element in the live DOM |
+| editor | `editor:live-edit` | framed by an editor page on the editor origin, the platform bridge forwards `tanqory-preview-update-section` (then `tq:set-content`) and the section shows the new text without a reload (rendered text, compared case-insensitively, so CSS `text-transform` does not matter) |
+| editor | `editor:section-preview` | every addable section (role ≠ block, with `presets[0]`) renders with height > 0 under `?tq_section_preview=<type>` (on home, or on a page whose template ships it) |
+| editor | `editor:preview-hides-consent` | the consent banner shown on a live first visit does not show on the preview channel |
+| consent | `consent:banner` | (warn) a consent banner shows when `consent.get` answers `bannerRequired: true` |
+| ai | `ai:profile` | (warn) `manifest["x-tanqory-ai"]` is declared and valid (§7) |
+
+## 3. Budgets tier
+
+| Check id | Measures | Budget |
+|---|---|---|
+| `budgets:client-initial` | gzip -9 of the client manifest entry + its `imports` + `css` (the same set suite 4 measures as `clientInitialGzipBytes`); JS and CSS reported separately | ABI §8 `clientInitialGzipBytes.budget` (256,000) |
+| `budgets:ssr-entry` | gzip of `server/entry.mjs` | `ssrEntryGzipBytes.budget` |
+| (measurement) `clientInitialTransferredGzipBytes` | script/style the browser fetched before the home page settled | reported |
+| `budgets:performance` | lab performance score, mobile, min over home and product | ≥ 85 |
+| `budgets:accessibility` | lab accessibility score, mobile, min over home and product | ≥ 95 |
+
+**What is approximated (exactly).** Lighthouse is not run: its own navigation would bypass the gateway
+that answers every request in-process. The runner measures in its own Chromium instead:
+- mobile 390×844 DPR 2; CPU slowed 4× relative to the **uncontended** host (see "Busy hosts" below);
+  every response delayed by 150 ms + (bytes on the wire × 8 / 1638.4 kbps) by the gateway, text counted
+  gzipped (Lighthouse's "slow 4G" figures applied per response, not a simulated connection pool);
+- FCP, LCP and CLS from `PerformanceObserver`; TBT = Σ(long task − 50 ms) after FCP over load + 3 s;
+- **Speed Index is not measured** (no filmstrip); it is taken as (FCP + LCP) / 2;
+- the score uses Lighthouse's mobile log-normal curves and weights (FCP 10, SI 10, LCP 25, TBT 30, CLS 25);
+- the accessibility score is the share of applicable axe-core rules that pass, all rules weighted equally
+  (Lighthouse weights its audits individually).
+
+Both scores are labelled `lab-approximation` in the report and are not Lighthouse scores.
+
+**Busy hosts (host calibration).** `Emulation.setCPUThrottlingRate` slows the renderer relative to the machine
+it runs on, so on a machine whose cores are busy with other work the page is slowed by the throttle *and* by
+the contention: the same theme scored 96–99 on a quiet 6-core host and 76–83 at load 50–240. The runner
+therefore measures and removes the contention instead of letting it count against the theme:
+
+1. *Before* each lab run it times a fixed busy loop in the page's renderer, unthrottled: wall-clock ÷ the main
+   thread's CPU time (`Performance.getMetrics` `ThreadTime`) is the host contention, 1.0 on an idle core. The
+   CDP rate is `4 ÷ contention`, never below 1.
+2. *During* the run it records a `toplevel` trace. Σ wall ÷ Σ CPU time (`dur` / `tdur`) of the renderer main
+   thread's tasks is the contention the measured page actually saw (the throttle burns CPU on that thread,
+   so it cancels out). `effectiveSlowdown = rate × that factor` is the slowdown the page really got.
+3. A run *decides* the verdict when its effective slowdown is 4× within ×1.25 (3.2–5×). A run slowed more
+   than that still proves a **pass** (the theme passed under a harsher device); a run slowed less still
+   proves a **fail**. A run off the target is repeated with the rate corrected by its own measured contention,
+   kept strictly between the highest rate that slowed the page too little and the lowest that slowed it too
+   much (the contention depends on the rate: a heavily throttled renderer burns CPU and is scheduled like a
+   batch job, a lightly throttled one stays interactive, so a plain correction can overshoot the band).
+4. One run per page is enough when it decides and is ≥ 5 points from the budget; otherwise up to four.
+   The page score is the lower median of its deciding runs; the check is the minimum over the pages.
+5. If a page has no deciding run (every run was over-slowed and below 85, or under-slowed and above it) and
+   no decided page failed, `budgets:performance` is **`warn`** with `inconclusive: this host was too busy…`
+   and the measured factors — not a failure, and not a pass of the theme. Re-run on a quieter machine.
+
+On a quiet host the contention is ~1.0, the rate stays 4× and the result is what it was before calibration.
+The busy-loop is not an absolute reference device: throttling stays relative to the machine's own idle
+speed, as before, so a quiet fast machine and a quiet slow one judge a theme exactly as they did. Every run's
+`hostFactor`, `cpuRate`, `windowFactor` and `effectiveSlowdown` is in the check's `evidence.details.pages[].runs`,
+and the maxima in the `performanceScoreMobile` measurement note.
+
+## 4. Locale-key patterns (the semantic fallback)
+
+When no hook is present, a control is a button/link (by ARIA role) whose accessible name equals one of the
+theme's own `locales/en.json` values whose key matches the pattern (last key segment or whole key,
+case-insensitive; `{placeholder}` matches anything):
+
+| Control | Key pattern |
+|---|---|
+| add to cart | `add[._-]?to[._-]?(cart\|bag\|basket)`, `addtocart` |
+| sold out | `sold[._-]?out`, `out[._-]?of[._-]?stock`, `unavailable` |
+| checkout | `check[._-]?out`, `proceed[._-]?to[._-]?checkout` |
+| remove line | `remove`, `delete`, `remove[._-]?(item\|line\|product)` |
+| increase quantity | `increase`, `increment`, `plus`, `increase[._-]?quantity` |
+| cart control | `cart`, `bag`, `basket`, `cart[._-]?count`, `open[._-]?cart`, `view[._-]?cart` |
+| menu | `menu`, `open[._-]?menu`, `main[._-]?menu`, `navigation` |
+| search | `search`, `open[._-]?search` |
+| sort | `sort`, `sort[._-]?by` |
+| filter | `filter(s)`, `show[._-]?filters` |
+| apply / update | `apply`, `show[._-]?results`, `done`, `update`, `save`, `confirm` |
+| next page | `next`, `next[._-]?page`, `load[._-]?more`, `show[._-]?more` |
+| country / market | `country`, `country[._-]?region`, `region`, `market`, `currency`, `region[._-]?language` |
+| empty cart | `cart[._-]?empty`, `empty`, `your[._-]?cart[._-]?is[._-]?empty` |
+| consent | accept: `accept`, `accept[._-]?all`, `allow`, `agree`; reject: `reject`, `decline`, `necessary[._-]?only` |
+
+Platform semantics used without any key: a link to `/cart`, links inside `<nav>`, `a[href*="country="]`,
+`select[name="country"]`, `a[href*="sort="]`, `a[rel~=next]`, `a[href*="page=2"]`, `input[type=search]`,
+`input[name=q]`, ARIA `searchbox`/`combobox`/`spinbutton`/`radio`/`option`, `aria-expanded="false"`
+disclosures and `<details>`, a link whose href is `Cart.checkoutUrl`, links to `/products/<handle>`.
+
+## 5. Hooks — `tq-storefront-hooks/1`
+
+All optional, all plain data attributes, no styling meaning. Each costs one attribute on an element the
+theme already renders. A theme that emits a hook is found by it first; the hook does not change what a
+check requires.
+
+| Hook | On | Meaning |
+|---|---|---|
+| `data-tq-action="cart:add"` | the add-to-cart `<button>` (or `<input type=submit>`) | adds the selected variant |
+| `data-tq-action="cart:checkout"` | the checkout link/button | hands off to `Cart.checkoutUrl` |
+| `data-tq-action="cart:remove"` | a line's remove control | removes that line |
+| `data-tq-action="cart:increment"` | a line's "+" control | quantity + 1 |
+| `data-tq-action="cart:open"` | the header cart link/button | opens the cart (drawer or page) |
+| `data-tq-action="menu:open"` | the menu button (mobile) | opens the main menu |
+| `data-tq-quantity` | a line's quantity `<input>`/`<select>` | the line quantity |
+| `data-tq-price` | the element showing the selected variant's price | updated on variant change |
+| `data-tq-variant-picker` | the container of the option controls | scope for option values |
+| `data-tq-sort` | the sort `<select>`, a container holding it, or the container of sort links | sort choices |
+| `data-tq-filter` | the container of facet controls | facet values |
+| `data-tq-pagination` | the container of the next-page / load-more control | paging |
+| `data-tq-localization` | the container of the market/language selector | `?country=` / `?locale=` |
+| `data-tq-search` | the search `<input>` | predictive search |
+| `data-tq-consent-banner` | the consent banner root | shown when `bannerRequired` |
+
+The hooks are versioned by `hooksVersion` in the report. A new hook is additive (same version); changing
+the meaning of one is a new version.
+
+## 6. The live-edit protocol (what the check sends)
+
+The check uses the platform's own canvas bridge (vendored byte-for-byte from storefront-edge
+`core/editor-bridge.client.mjs`, `src/storefront/vendor/`), injected on the preview channel exactly as the
+edge does. The bridge hands each editor message to the page as a window `CustomEvent('tq:canvas',
+{detail: message})`:
+
+- `{type: 'tanqory-preview-update-section', sectionId, settings, blocks?, order?}` — the check sends this
+  first, with one text setting of a home section set to a new value;
+- `{type: 'tq:set-content', doc: [{id, type, settings}]}` — sent if the first did not apply.
+
+A theme applies the message to the section in place and announces what it applies with
+`window.dispatchEvent(new CustomEvent('tq:canvas-live', {detail: {types: [...]}}))` (again whenever it
+receives `tq:canvas-bridge`). The bridge reports the announced types to the editor in `tq:ready.live`;
+the check records them.
+
+## 7. `x-tanqory-ai` profile (draft v0, warn only)
+
+`manifest["x-tanqory-ai"]` names which of the theme's own sections and settings play the roles Tanqory AI
+fills. Schema: `schema/x-tanqory-ai.v0.schema.json`. Draft; the AI-compat work owns the final shape.
+
+```json
+"x-tanqory-ai": {
+  "version": 0,
+  "roles": {
+    "hero": [{ "component": "hero", "heading": "heading", "subheading": "subheading", "image": "backgroundImage", "button": "buttonLabel", "link": "buttonLink" }],
+    "headerMenu": { "component": "header", "setting": "menu" },
+    "footerMenus": [{ "component": "footer", "block": "footer-menu", "setting": "menu" }],
+    "footerBrand": { "component": "footer", "block": "footer-brand" }
+  }
+}
+```
+
+Beyond the schema, every `component`/`block` must exist in `manifest.components` and every setting it names
+must exist with a matching type (`menu` for menus; `collection`/`product` for `productGrid.setting`; text
+types for headings; `image` for images).
+
+## 8. Report
+
+`storefront-report.json`, format `tanqory-storefront-report/1`, schema
+`schema/storefront-report.v1.schema.json`. Each check: `id`, `tier`, `group`, `title`, `status`, and when
+relevant `message`, `route`, `locale`, `viewport`, `evidence` (`selector`, `screenshot` relative to the
+`--evidence` directory, `url`, `details`) and `fixHint`. `measurements` hold the budgets. The security
+tier's `conformance-report.json` (format 2) is not changed by this tier.
+
+The default output is `./storefront-report.json` in the working directory — never inside the theme
+directory, whose files are digested.