@orderlyshop/web-components 0.1.0-build.7066 → 0.1.0-build.7068

package/AGENTS.md

@@ -5,29 +5,19 @@ Use this package as a headless storefront component library. Prefer native custo
 ## Agent Operating Contract
 
 - These instructions are optimized for GPT-5.5-class coding agents and other modern LLMs. Work from the user's requested storefront outcome, choose the package-owned component or CLI that owns that outcome, and keep edits scoped to that path.
-- Read stable package context before shop-specific files: `README.md`, `DESIGN.md`, component docs, then `custom-elements.json` or `html-custom-data.json` for exact API names. Inspect the consuming shop after that.
 - Prefer package configuration, typed properties, declarative templates, semantic tokens, and package CLI tools over copying component internals into a shop.
 - Do not infer attribute names, event names, template slots, or CSS hooks from memory. Use the docs and metadata in this package as the source of truth.
-- Stop when the requested behavior is implemented and verified with the nearest relevant script. If validation needs data, account ids, credentials, or a running backend, report the exact missing prerequisite.
+- Stop only when the behavior is implemented, verified with the nearest relevant script, and visually inspected in a browser when available. If validation needs data, account ids, credentials, a browser, or a running backend, report the exact missing prerequisite.
 
-## Discovery
+## Required Reading and Intake
 
-- Read `README.md` for setup and package-wide concepts.
-- Read `DESIGN.md` before changing the visual theme. It defines the semantic design tokens that should be changed first.
-- Read `docs/components/README.md` for component APIs.
-- Read `docs/components/product-rail.md` and `docs/components/product-grid.md` before implementing product listing UI.
-- Read `custom-elements.json` for machine-readable custom element metadata.
-- Read `html-custom-data.json` when generating vanilla HTML or configuring editor autocomplete.
-- Inspect `examples/shop` for a complete vanilla TypeScript shop that customizes the defaults without replacing package logic.
-- When creating a new shop from scratch, run `npx orderly-init-shop` first. It scaffolds the vanilla HTML/TypeScript/Vite structure that the package expects, including `src/includes/head.html`, `src/navigation.ts`, `src/shop-query.ts`, page templates, and package scripts.
-
-## New Shop Intake
-
-- Ask the user for the Orderly account id so `src/shop-query.ts` can tenant-scope the default `SearchQuery`.
-- Ask the user for a reference website URL for the desired visual style. If they do not have one, ask for a short description of the target look.
-- Use the reference website as design direction only: extract palette, density, radius, typography feel, spacing, and navigation patterns into semantic Orderly tokens and shop CSS. Do not copy proprietary assets, text, logos, or brand marks unless the user confirms they own or may use them.
-- Put the resulting theme in `src/style.css` or the consuming shop stylesheet, starting with `DESIGN.md` tokens before adding component-specific selectors.
-- After scaffolding, run the nearest local dev/build command and visually compare the shop against the requested reference at desktop and mobile widths when a browser is available.
+- Read `README.md`, `DESIGN.md`, `docs/shop-best-practices.md`, `docs/components/README.md`, then `custom-elements.json` or `html-custom-data.json` before shop-specific edits. Read `docs/components/product-rail.md` and `docs/components/product-grid.md` before product listing work.
+- Use `docs/shop-best-practices.md` as the completion checklist for branded shop work. A finished shop must not look like the default scaffold with minor token changes.
+- For new shops, run `npx orderly-init-shop` first. Ask for the Orderly account id and a reference website URL; if no reference exists, ask for a short style description.
+- Use the account id for tenant-scoped `src/shop-query.ts`. Use the reference, catalog inspection, and online research as design direction for `src/style.css`; never copy proprietary assets, text, logos, or brand marks without user confirmation.
+- Build the first version around catalog-driven content: homepage sections, category introductions, product context, useful navigation, and a visual system based on `DESIGN.md` tokens plus scoped CSS.
+- Aim for current premium frontend craft: responsive art direction, strong imagery, clear interaction states, appropriate motion, performance, and accessibility.
+- Before reporting completion, run the local dev/build command and visually inspect homepage, category, product, basket, and checkout on desktop and mobile when a browser is available.
 
 ## Query Rules
 
@@ -50,27 +40,25 @@ Use this package as a headless storefront component library. Prefer native custo
 
 ## Implementation Defaults
 
-- Keep components headless. Add behavior and default light-DOM markup, not bundled theme CSS.
-- Start theme work from the semantic tokens in `DESIGN.md`. Use component-local selectors and hooks only for deliberate exceptions after the shared tokens are set.
+- Keep components headless. Prefer configuration, typed properties, templates, slots, semantic tokens, and scoped shop CSS over copying package internals.
+- Start theme work from `DESIGN.md`. Visual differentiation is part of the first implementation, not later polish.
+- Add shop-owned editorial sections around package components. Preserve package-owned product tiles, checkout, product detail behavior, image viewers, structured data, accessibility, and generated URLs unless the user explicitly asks for a different structure.
 - Built-in UI copy defaults to Danish. Use `configureShop({ uiLanguage: "EN" })` for English shops, and prefer shop attributes/templates for wording that is unique to one storefront.
-- Preserve template override support through `data-orderly-template`, `data-orderly-bind`, `data-orderly-slot`, and `data-orderly-action`.
-- Put shop-wide templates in a shared document-level registry, for example template files included from `body-start.html`, using `data-orderly-template` plus `data-orderly-for`.
-- Keep browser-only package code free of Node HTTP modules.
-- Do not store tokens, API keys, OAuth responses, or cookie values.
-- Treat localStorage basket and checkout profile data as user-owned state. Do not add secret persistence.
+- Preserve `data-orderly-template`, `data-orderly-bind`, `data-orderly-slot`, and `data-orderly-action`. Put shared templates in a document-level registry using `data-orderly-for`.
+- Keep browser code free of Node HTTP modules. Do not store tokens, API keys, OAuth responses, cookie values, or other secrets.
+- Use `configureShop({ consent })` before enabling optional analytics, marketing, personalization, or shop-owned cookies. Use `setOrderlyCookie()` or `hasCookieConsent()` for optional browser state.
+- Treat localStorage basket and checkout profile data as user-owned state.
 - Product images should default to `fit="contain"`, white background, and square aspect ratio in product tiles.
+- Use `orderly-stored-image` for package/product images when possible and set the appropriate `image-role` (`product-tile`, `product-detail`, `thumbnail`, `basket-line`, `checkout-line`, or `fullsize`) so image URLs reuse configured CDN dimensions.
 - Product grids should support continuation-token based dynamic paging without requiring a visible load-more button.
-- Use `orderly-home-page` for default storefront homepages instead of generating product rails in app code.
-- Use `orderly-category-page` for category routes. Default category links should use `/categories/<category-path>/` so builds can generate and hydrate server-rendered category pages. Use `/category.html#id=<encoded-category-path-or-slug>` only for shops that explicitly opt into hash routing.
-- Keep `orderly-navigation` sticky by default. Use `sticky="false"` only when a shop intentionally wants navigation to scroll away.
-- Use `orderly-checkout-page` for checkout pages instead of wiring `orderly-checkout` and `orderly-basket` manually in app code.
+- Use `orderly-home-page` for default storefront homepages instead of generating product rails in app code. Set `basket-mode="inline-desktop"` when the design needs a package-owned desktop basket rail instead of custom portal glue.
+- Use `orderly-category-page` for category routes. Default category links should use `/categories/<category-path>/` so builds can generate and hydrate server-rendered category pages. Use `/category.html#id=<encoded-category-path-or-slug>` only for shops that explicitly opt into hash routing. Prefer navigation `heroImage`, `heroLayout: "covers"`, `heroCoverCount`, and category `description` before replacing the category hero template.
+- Keep `orderly-navigation` sticky by default. Use `sticky="false"` only when a shop intentionally wants navigation to scroll away. Use `persist-state state-key="main-menu"` for vertical desktop menus that should remember open branches, and use `slot="menu-before"`/`slot="menu-after"` for store finder, campaign, volunteer, or other menu promo links.
+- Use package-owned basket and checkout surfaces first: `<orderly-basket-icon href="/checkout.html" placement="mobile-fixed" hide-when-empty>`, `basket-mode="inline-desktop"`, and `orderly-checkout-page`.
 - Use `orderly-product-detail-page` for full product routes. Set `share-url` to the product `SearchObject.ShareURL.URL`; the component loads the product through `SearchQuery.ShareUrl`.
 - Keep category page generation in the normal shop build. Use `orderly-build-category-pages` without `--no-hydrate` so homepage/category pages get initial HTML for SEO and less visible loading shift. Pass `--base-url` or set `VITE_ORDERLY_BASE_URL` to override the default `https://service.orderly.shop` snapshot backend.
 - For real product URLs on traditional hosting, use the package-owned helpers in `server/`: Apache `.htaccess`, Nginx rewrite config, PHP product renderer, and optional Node product snapshot endpoint. Do not copy this logic into example-shop.
-- Use `navigation.ts` for shop category/navigation structure. Export `navigationDefinitions: NavigationDefinition[]`.
-- Use `npx orderly-init-navigation` to create the default file or `npx orderly-init-navigation --suggest --account-id <account-id>` to dump sampled product data for agent-assisted navigation design.
-- Navigation definitions are recursive but should stay at most two category levels deep for normal shops. Each item must include `label` and a stable globally unique `slug`, and can include optional `heroImage`, optional `description`, optional `query`, and optional `children`.
-- Use plain `SearchQueryInput` objects in navigation definitions, for example `query: { query: "sko sneakers", tags: ["sko"] }`.
+- Use `navigation.ts` for category/navigation structure. Run `npx orderly-init-navigation --suggest --account-id <account-id>` when sampling helps, then export `navigationDefinitions: NavigationDefinition[]` with stable unique slugs, at most two levels, optional hero/content fields, and plain `SearchQueryInput` values such as `query: { query: "sko sneakers", tags: ["sko"] }`.
 
 ## Common Patterns
 

package/README.md

@@ -17,39 +17,24 @@ Inputs:
 - Orderly account id: ASK
 - Visual style reference: ASK
 - Deployment target: ASK
-
-Use any provided input above without asking again. Ask only for values that are still `ASK`.
-
-Install and setup:
-1. Install @orderlyshop/core-client and @orderlyshop/web-components if they are not already installed.
-2. Read node_modules/@orderlyshop/web-components/AGENTS.md, DESIGN.md, README.md, and docs/components/README.md before changing shop files.
-3. Run npx orderly-init-shop for a new shop. Pass --account-id when the Orderly account id is provided. Preserve existing files unless I explicitly approve overwrite.
-
-Navigation:
-4. Use the Orderly account id to tenant-scope src/shop-query.ts.
-5. Run npx orderly-init-navigation --suggest --account-id <account-id> when product sampling is possible.
-6. Build src/navigation.ts manually from navigation-products.json with at most two category levels, stable unique slugs, and plain SearchQueryInput objects.
-
-Visual style:
-7. Use the visual style reference as design direction for palette, radius, spacing, density, typography feel, product tiles, navigation, checkout, and page rhythm.
-8. Start src/style.css from DESIGN.md semantic tokens. Add component-specific selectors only for details that tokens cannot express.
-9. Do not copy proprietary assets, text, logos, or brand marks from the reference unless I explicitly confirm they may be used.
-
-Pages and behavior:
-10. Use package-owned components and configuration: orderly-home-page, orderly-category-page, orderly-product-detail-page, orderly-checkout-page, configureShop(...), templates, and the generated Vite setup.
-11. Keep product/category SSR and generated category URLs working unless the deployment target requires a different routing approach.
-
-Deployment:
-12. Configure the build/publish flow for the deployment target.
-    - For static hosting, use npm run build and document the dist upload.
-    - For FTP, use npx orderly-publish-site --target ftp.
-    - For Apache/PHP or Nginx/PHP, keep the package-generated server renderers and document the required server helper files.
-    - For any other target, document the exact build output and any remaining deployment assumptions.
-
-Validation:
-13. Run the nearest relevant build/test command.
-14. Start the dev server when useful and inspect desktop and mobile layouts.
-15. Report what changed, what was verified, and any missing backend, credential, or deployment prerequisite.
+- Google Tag Manager container id: NONE
+- Google Tag Manager data layer name: dataLayer
+- Analytics consent categories: statistics
+- Cookie policy URL: /information/cookies/
+
+Use any provided input above without asking again. Ask only for values that are still `ASK`. Treat Google Tag Manager container id `NONE` or an empty value as an explicit choice to leave GTM/analytics disabled.
+
+Workflow:
+1. Install @orderlyshop/core-client and @orderlyshop/web-components if needed. Run npx orderly-init-shop for a new shop, pass --account-id when available, and preserve existing files unless I approve overwrite.
+2. Read node_modules/@orderlyshop/web-components/AGENTS.md, DESIGN.md, README.md, docs/components/README.md, and docs/shop-best-practices.md before changing shop files. Treat docs/shop-best-practices.md as a completion checklist, not optional inspiration.
+3. Scope the shop with the Orderly account id in src/shop-query.ts. When product sampling is possible, run npx orderly-init-navigation --suggest --account-id <account-id>, then build src/navigation.ts manually with stable unique slugs, at most two category levels, and plain SearchQueryInput objects.
+4. Use package-owned components and configuration first: orderly-home-page, orderly-category-page, orderly-product-detail-page, orderly-checkout-page, configureShop(...), templates, generated Vite setup, generated category URLs, and package SSR helpers.
+5. Use the visual style reference as design direction, not as copy material. Start src/style.css from DESIGN.md semantic tokens, then add scoped component selectors only where tokens are insufficient.
+6. Do not ship the package default look and feel with minor color changes. Inspect the catalog, research the reference site and comparable modern shops, and create homepage/category/product context that is visually and editorially specific to this shop.
+7. Aim for premium modern frontend craft: strong art direction, responsive composition, high-quality imagery, clear interaction states, appropriate motion, performance, and accessibility. Do not copy proprietary assets, text, logos, or brand marks unless I explicitly confirm they may be used.
+8. Google Tag Manager is optional. Treat Google Tag Manager container id `NONE` or an empty value as an explicit choice to leave GTM/analytics disabled. If a container id is provided and is not `ASK`, wire it through `VITE_ORDERLY_GOOGLE_TAG_MANAGER_ID` and package config rather than raw GTM snippets. Use `configureShop({ consent, analytics })`, Cookie policy URL, Google Tag Manager data layer name, and Analytics consent categories from the inputs.
+9. Configure the build/publish flow for the deployment target: npm run build for static hosting, npx orderly-publish-site --target ftp for FTP, package server helpers for Apache/PHP or Nginx/PHP, or explicit documented assumptions for other targets.
+10. Run the nearest relevant build/test command. Start the dev server when a browser is available and visually inspect homepage, category, product, basket, and checkout on desktop and mobile before declaring the shop done. Report command and visual verification plus any missing backend, credential, research, analytics, browser, or deployment prerequisite.
 ```
 
 ## Install
@@ -74,7 +59,7 @@ Agents and developers should use `npx orderly-init-shop` before hand-writing sho
 npx orderly-init-shop --account-id 00000000-0000-0000-0000-000000000000
 ```
 
-For agent-assisted shop creation, ask for both the Orderly account id and a reference website URL for visual style before customizing the scaffold. Use the account id for `src/shop-query.ts`; use the reference website to choose semantic design tokens, radius, spacing, navigation treatment, and component-level exceptions in `src/style.css`. Treat the reference as design direction, not as permission to copy proprietary assets, text, logos, or brand marks.
+For agent-assisted shop creation, ask for both the Orderly account id and a reference website URL for visual style before customizing the scaffold. Use the account id for `src/shop-query.ts`, use the reference website and catalog research to shape `src/style.css`, and follow [`docs/shop-best-practices.md`](./docs/shop-best-practices.md) as the completion checklist. The first pass should already feel visually distinct, editorially useful, and technically polished; it should not look like the default package scaffold with small token changes.
 
 Re-running `npx orderly-init-shop` in an existing shop is non-destructive by default. Existing scaffold files are left unchanged with warnings, while missing new scaffold files are added. Use `--force` only when you explicitly want scaffold files overwritten.
 
@@ -82,7 +67,7 @@ The scaffold uses Vite for local development and static builds, but Vite is adde
 
 ## Browser Standalone Bundle
 
-The package build also emits browser-ready standalone bundles with `@orderlyshop/core-client`, Connect, and protobuf runtime code included. These files are shipped in the npm package and are what the `unpkg` and `jsdelivr` package fields point at.
+The package build emits optimized ESM output and browser-ready standalone bundles with `@orderlyshop/core-client`, Connect, and protobuf runtime code included. JavaScript output is minified, and `npm run build` writes `.br` and `.gz` files next to every generated `dist/**/*.js` file for hosts that can serve precompressed assets. The standalone browser files are shipped in the npm package and are what the `unpkg` and `jsdelivr` package fields point at.
 
 Use the configurable bundle when a vanilla HTML site needs to set shop options before registering elements:
 
@@ -118,23 +103,86 @@ Use the auto-register bundle for the built-in default shop or pages that configu
 
 The normal package entrypoints remain ESM for bundlers. The standalone files are classic browser scripts and expose `window.OrderlyWebComponents`.
 
-`configureShop()` is the recommended one-call setup for HTML head scripts. Its parameter is strongly typed as `ShopConfig`, so VS Code/TypeScript can provide completions directly on the object literal. All fields are optional: `uiLanguage`, `defaultShop`, `storefrontRouter`, `pageLayout`, `responsiveTemplates`, `shopFooter`, `storedImageUrls`, and `components`. It applies configuration first and then registers custom elements. The built-in SPA storefront router is enabled by default; pass `storefrontRouter: { enabled: false }` only when a shop needs traditional full-page navigation for every internal link. Pass `components: false` only when elements are registered elsewhere.
+`configureShop()` is the recommended one-call setup for HTML head scripts. Its parameter is strongly typed as `ShopConfig`, so VS Code/TypeScript can provide completions directly on the object literal. All fields are optional: `uiLanguage`, `defaultShop`, `storefrontRouter`, `pageLayout`, `responsiveTemplates`, `shopFooter`, `storedImageUrls`, `consent`, `analytics`, and `components`. It applies configuration first and then registers custom elements. The built-in SPA storefront router is enabled by default; pass `storefrontRouter: { enabled: false }` only when a shop needs traditional full-page navigation for every internal link. Pass `components: false` only when elements are registered elsewhere.
 
 Built-in component copy is Danish by default (`uiLanguage: "DA"`). Set `uiLanguage: "EN"` to switch built-in labels, empty states, checkout copy, navigation controls, and page defaults to English. Shop-specific attributes, templates, and `defaultShop` label fields still take precedence over language defaults.
 
+## Cookie Consent
+
+Use `configureShop({ consent })` when the shop uses optional cookies, local storage identifiers, Google Tag Manager, analytics, campaign measurement, personalization, or similar tracking. The package-owned consent runtime gives visitors a first-layer banner with accept, reject, and customize actions, optional categories that are off by default, a persistent "Cookieindstillinger" button, versioned localStorage persistence, and first-party cookie cleanup when consent is rejected or withdrawn:
+
+```ts
+configureShop({
+  consent: {
+    enabled: true,
+    version: "2026-04-30",
+    policyHref: "/information/cookies/",
+    managedCookies: [
+      {
+        name: "_ga",
+        category: "statistics",
+        provider: "Google Analytics",
+        purpose: "Skelner mellem besøgende i statistikmåling.",
+        duration: "Typisk op til 2 år"
+      },
+      {
+        name: "_ga_*",
+        category: "statistics",
+        provider: "Google Analytics",
+        purpose: "Bevarer sessionsstatus for statistikmåling.",
+        duration: "Typisk op til 2 år"
+      }
+    ]
+  }
+});
+```
+
+Default categories are `necessary`, `preferences`, `statistics`, and `marketing`. `necessary` is always on; all other categories require an affirmative choice. Override `categories` and `texts` when a shop needs different purpose wording, and change `version` when purposes, vendors, or the cookie policy materially change so visitors are asked again. `managedCookies` accepts exact first-party cookie names or simple wildcard patterns such as `_ga_*`; include `provider`, `purpose`, and `duration` so the preferences layer can disclose the cookies it manages.
+
+Programmatic helpers are exported for custom code: `hasCookieConsent(category)`, `currentCookieConsent()`, `saveCookieConsent(categories)`, `openCookieConsentPreferences()`, `setOrderlyCookie(name, value, { category })`, `deleteOrderlyCookie(name)`, and `clearCookiesForCategory(category)`. Use `setOrderlyCookie` for shop-owned optional cookies so they are only written when the category has consent.
+
+The package can enforce consent for package-owned browser behavior, analytics hooks, and configured first-party cookies. The shop owner still has to keep the cookie policy/vendor list accurate, configure any server-side or third-party deletion outside the package, and ensure any custom scripts also check consent before reading or writing optional cookies.
+
+## Analytics And Google Tag Manager
+
+Use `configureShop({ analytics })` to install Google Tag Manager and publish GA4-compatible navigation and ecommerce events to `dataLayer`:
+
+```ts
+configureShop({
+  consent: {
+    enabled: true,
+    policyHref: "/information/cookies/"
+  },
+  analytics: {
+    googleTagManagerId: import.meta.env.VITE_ORDERLY_GOOGLE_TAG_MANAGER_ID,
+    defaultCurrency: "DKK",
+    affiliation: "My Shop"
+  }
+});
+```
+
+When `googleTagManagerId` is set, the package initializes `dataLayer` and injects the GTM script. The generated starter shop wires this to `VITE_ORDERLY_GOOGLE_TAG_MANAGER_ID`; omit the env var to leave tracking off. When package cookie consent is configured, analytics defaults to requiring the `statistics` category before GTM loads or package analytics events are pushed. Set `analytics.consentCategories` to another category, an array such as `["statistics", "marketing"]`, or `false` only when the shop handles consent outside the package.
+
+With package cookie consent enabled, analytics also queues Google Consent Mode v2 `default` and `update` commands. The default command denies optional storage until the visitor has chosen; the update command is pushed immediately when the visitor saves or changes consent.
+
+The analytics integration listens to package-owned DOM events and pushes these GA4 event names: `page_view`, `view_item_list`, `select_item`, `view_item`, `add_to_cart`, `remove_from_cart`, `view_cart`, `begin_checkout`, `add_shipping_info`, `add_payment_info`, and `purchase`. Ecommerce events clear the previous `ecommerce` object before pushing the new event, so GTM GA4 tags can read the current event payload cleanly. Purchase tracking fires from `orderly-payment-success-page` with `transaction_id`; configure the GA4 tag in GTM to use the data layer ecommerce object and avoid also firing a separate duplicate purchase tag on the same page.
+
+For custom analytics, keep `analytics.enabled: true` without `googleTagManagerId` to use the same hooks with an existing GTM/dataLayer install, or pass `onEvent` to forward package events to another destination.
+
 ## API Discovery
 
 Developers and coding agents should start with these package-owned docs:
 
 - [`DESIGN.md`](./DESIGN.md) defines the package-wide design tokens and the recommended theming workflow for consistent styling across all components.
 - [`docs/components/README.md`](./docs/components/README.md) lists every custom element, common attributes, typed properties, events, and template hooks.
+- [`docs/shop-best-practices.md`](./docs/shop-best-practices.md) is the practical checklist for turning the package scaffold into a branded, editorial storefront without replacing package-owned component behavior.
 - [`docs/components/product-grid.md`](./docs/components/product-grid.md) documents search loading, sorting, paging, default query merging, and declarative query markup.
 - [`docs/components/product-rail.md`](./docs/components/product-rail.md) documents homepage/category rails and their query configuration.
 - [`AGENTS.md`](./AGENTS.md) gives coding agents the conventions for building shops with this package.
 - [`custom-elements.json`](./custom-elements.json) is the Custom Elements Manifest for tools that understand web component metadata.
 - [`html-custom-data.json`](./html-custom-data.json) is VS Code compatible custom data for HTML autocomplete and hover docs.
 
-These docs are written for GPT-5.5-class coding agents as well as humans: start with the outcome the shop needs, use the package-owned API surface, and verify with the nearest package or shop script before changing broader app structure.
+These docs are written for GPT-5.5-class coding agents as well as humans: start with the outcome the shop needs, use the package-owned API surface, follow `docs/shop-best-practices.md` as the shop quality bar, and verify with both the nearest package/shop script and visual browser inspection before calling a shop finished.
 
 Enable HTML editor hints in a consuming project by adding the package custom data file to `.vscode/settings.json`:
 
@@ -359,19 +407,17 @@ npx orderly-init-navigation --path src/navigation.ts
 
 Agent workflow for a new shop:
 
-1. Ask the user for the new shop's Orderly account id.
-2. Ask the user for a reference website URL for the desired visual style, or a short style description when no reference site exists.
-3. Run the navigation helper to dump sampled product information:
+1. Ask for the Orderly account id and a reference website URL for the desired visual style, or a short style description when no reference site exists.
+2. Run the navigation helper when product sampling is possible:
 
 ```sh
 npx orderly-init-navigation --suggest --account-id <account-id>
 ```
 
-4. Read the generated `navigation-products.json`. The helper does not infer categories. It writes sampled product records with `title`, `brand`, and `tags` only, plus sampling metadata.
-5. Create `navigation.ts` manually from the dump. Export `navigationDefinitions: NavigationDefinition[]`. Each entry must have `label` and a stable, globally unique `slug`, and can also have optional `heroImage`, optional `description`, optional `query`, and optional recursive `children`. Use plain `SearchQueryInput` objects for `query`, such as `{ query: "sko sneakers", tags: ["sko"] }`.
-6. Keep navigation to at most two category levels. Categories should be reasonably granular, but avoid empty categories or categories backed by only a few products.
-7. Configure the shop scope with a Core `SearchQuery` and pass it to `configureShop({ defaultShop: { defaultQuery } })`.
-8. Translate the reference website into `src/style.css` by setting `DESIGN.md` semantic tokens first, then add scoped component selectors only for visual details the tokens cannot express.
+3. Create `navigation.ts` manually from `navigation-products.json`. Export `navigationDefinitions: NavigationDefinition[]`; each item needs `label`, a globally unique `slug`, optional hero/content fields, optional `children`, and plain `SearchQueryInput` values such as `{ query: "sko sneakers", tags: ["sko"] }`. Keep navigation to at most two category levels and avoid empty or tiny categories.
+4. Configure shop scope with a Core `SearchQuery` through `configureShop({ defaultShop: { defaultQuery } })`.
+5. Read and follow `docs/shop-best-practices.md`, translate the reference into `DESIGN.md` tokens plus scoped CSS, and add homepage/category content from catalog and research.
+6. Run the dev server when a browser is available and visually inspect homepage, category, product, basket, and checkout on desktop and mobile. Fix visible issues before reporting completion; visual QA is required for finished shop work.
 
 The helper is intentionally an explicit tool for developers and coding agents. It is not a postinstall action. Agents should keep user-owned navigation edits, ask before overwriting files, and treat the product dump as source material for human-reviewable navigation.
 
@@ -399,7 +445,7 @@ Navigation data has three layers:
 
 - `NavigationDefinition` is the authored data in `navigation.ts`. It is the only type most shops need to write. Every item needs an explicit stable `slug`; labels are display text and can change without changing URLs.
 - `ResolvedNavigationItem` is created by `createCategoryNavigation()` and consumed by default page components. It adds stable ids, hrefs, normalized Core `SearchQuery` values, and derived metadata.
-- `NavigationMetadata` contains those derived page values: slug, parent id, path segments, normalized query, search text, description, hero image, and page root.
+- `NavigationMetadata` contains those derived page values: slug, parent id, path segments, normalized query, search text, description, hero image, hero layout, hero cover count, and page root.
 
 The older `CategoryDefinition`, `CategoryNavigationItem`, and `CategoryMetadata` names remain as compatibility aliases only.
 
@@ -431,7 +477,7 @@ Build with generated category pages and then clean the generated source files. S
 npx orderly-build-category-pages
 ```
 
-`orderly-build-category-pages` also hydrates the built `dist/index.html` and generated `dist/categories/**/index.html` pages with SEO-friendly fallback HTML. The hydration step embeds semantic product cards per category using `SearchService.Search`; it reads `--base-url`, `VITE_ORDERLY_BASE_URL`, or `ORDERLY_BASE_URL`, and otherwise uses the default `https://service.orderly.shop` backend. Live web components read the semantic fallback as initial state, hide it, and then continue as normal client components.
+`orderly-build-category-pages` also hydrates the built `dist/index.html` and generated `dist/categories/**/index.html` pages with SEO-friendly fallback HTML. The hydration step embeds semantic product cards per category using `SearchService.Search`; it reads `--base-url`, `VITE_ORDERLY_BASE_URL`, or `ORDERLY_BASE_URL`, and otherwise uses the default `https://service.orderly.shop` backend. Live web components read the semantic fallback as initial visible state, hide the raw fallback markup, and then continue as normal client components. Product grids still run their first live `SearchService.Search()` after hydration when a client or backend URL is configured, so fallback products are replaced by current backend data and continuation-token paging starts from the live result set.
 
 Hydrate an already-built site manually, for example in a nightly job:
 
@@ -443,6 +489,20 @@ Use `--skip-products` for metadata-only hydration, `--strict-products` when a ni
 
 The category generator expects `src/navigation.ts` or `src/navigation.js` to export `navigationDefinitions` and the template page to contain `<orderly-category-page></orderly-category-page>`. TypeScript navigation files use the current shop project's `typescript` dependency for one-off transpilation. Useful options include `--navigation`, `--template`, `--categories-dir`, `--site-title`, `--component-tag`, and `--export`. The older `--taxonomy` flag and `categoryDefinitions` export are still accepted as compatibility aliases.
 
+## Static Vanilla Deployment
+
+For static hosting, keep the generated shop as a normal Vite site and upload the built `dist` directory, not `src` or `node_modules`.
+
+Recommended path-based setup:
+
+1. Keep `productUrlMode: "path"` or configure `storefrontRouter.product.mode = "path"` when the host can serve `/products/.../` through the provided server helper or a static fallback.
+2. Use real category URLs by exporting `navigationDefinitions` and running `npx orderly-build-category-pages` from the shop project. This generates `src/categories/**/index.html` during build, hydrates `dist/index.html` plus `dist/categories/**/index.html`, and cleans generated source files afterwards.
+3. Upload every file in `dist`, including hashed assets under `dist/assets` and precompressed `.br`/`.gz` files when the host supports them.
+4. Configure the host to serve `index.html`, generated category `index.html` files, checkout/payment callback pages, and product fallback routing. Apache/PHP, Nginx/PHP-FPM, and Node helpers live in `node_modules/@orderlyshop/web-components/server`.
+5. Use hash product URLs only when the deployment target cannot route unknown product paths. Hash URLs still work with the SPA router, but path URLs are clearer for static/server-rendered SEO entry points.
+
+For local dry runs use `npm run build`, then the host's static preview command or `npm run preview` from the generated shop. For one-off publish flows, use `npx orderly-publish-site --target local --dir published-site` or `npx orderly-publish-site --target ftp`.
+
 ## Local SSR Dev Mode
 
 Scaffolded shops use SSR in dev mode by default through the package Vite middleware:
@@ -502,7 +562,7 @@ npm run build
 npx orderly-generate-server-renderers --site-title "My Shop"
 ```
 
-Scaffolded shops run that generator from `npm run build` by default. It writes `dist/product.php`, `dist/category.php`, `dist/.htaccess`, and `dist/orderly-ssr-manifest.json`. The PHP renderers call `SearchService.Search` over gRPC-web, inject semantic HTML into the built `product.html` or `category.html`, and preserve the normal web-component scripts and styles.
+Scaffolded shops run that generator from `npm run build` by default. It writes `dist/product.php`, `dist/category.php`, `dist/.htaccess`, and `dist/orderly-ssr-manifest.json`. The PHP renderers call `SearchService.Search` over gRPC-web, inject semantic HTML into the built `product.html` or `category.html`, and preserve the normal web-component scripts and styles. The generated `.htaccess` sets long immutable cache headers for fingerprinted static assets and keeps HTML/PHP revalidatable; configure equivalent cache headers manually when deploying to hosts that ignore `.htaccess`.
 
 Runtime options:
 
@@ -511,7 +571,7 @@ Runtime options:
 - `ORDERLY_SSR_HEADERS` can add internal server-side request headers. Do not expose API keys or bearer tokens to browser JavaScript.
 - `ORDERLY_SSR_MANIFEST` can point PHP to a manifest outside the web root.
 
-The semantic fallback uses real headings, links, images, schema.org Product/Offer metadata, and small `data-orderly-*` attributes only for behavior-critical values. Components hydrate from that HTML, then hide the fallback and continue as normal interactive web components. Generated SSR output keeps the same HTML for users and crawlers, hides fallback visibility for normal browser hydration, and serves a visible fallback layout to Googlebot. See [`server/README.md`](./server/README.md) for details.
+The semantic fallback uses real headings, links, images, schema.org Product/Offer metadata, and small `data-orderly-*` attributes only for behavior-critical values. Components hydrate from that HTML, then hide the fallback and continue as normal interactive web components. Product grids treat fallback products as temporary visual content and replace them with the first live search result when a backend client is available; without a live search target, the fallback remains visible. Generated SSR output keeps the same HTML for users and crawlers, hides fallback visibility for normal browser hydration, and serves a visible fallback layout to Googlebot. See [`server/README.md`](./server/README.md) for details.
 
 ## Define Elements
 
@@ -520,7 +580,14 @@ import { configureShop } from "@orderlyshop/web-components";
 
 configureShop({
   responsiveTemplates: { mobileMediaQuery: "(max-width: 860px)" },
-  storedImageUrls: { baseUrl: "https://static.example-cdn.com/" }
+  storedImageUrls: {
+    baseUrl: "https://static.example-cdn.com/",
+    roles: {
+      "product-tile": { width: 500, height: 500 },
+      "product-detail": { width: 900, height: 900 },
+      fullsize: false
+    }
+  }
 });
 ```
 
@@ -548,7 +615,7 @@ style.textContent = ORDERLY_LAZY_LOAD_CSS;
 document.head.append(style);
 ```
 
-`defineOrderlyWebComponents()` installs the same lazy-load CSS at runtime as a fallback, but head inclusion is what prevents raw slotted links from flashing before JavaScript has loaded. The default component CSS is exported as `ORDERLY_DEFAULT_CSS` and installed automatically by `defineOrderlyWebComponents()`.
+`defineOrderlyWebComponents()` installs the same lazy-load CSS at runtime as a fallback, but head inclusion is what prevents raw slotted links from flashing before JavaScript has loaded. The optional hydration fade is one-shot: it runs only for the first rendered component tree after a real page load, then the package removes `data-orderly-hydration-fade` so SPA navigation, browser back, product overlays, and other later renders do not fade or visually re-layout. The default component CSS is exported as `ORDERLY_DEFAULT_CSS` and installed automatically by `defineOrderlyWebComponents()`.
 
 ## Global Templates
 
@@ -611,25 +678,38 @@ collection.client = client;
 collection.query = searchQuery;
 ```
 
+## Content and Brand Cookbook
+
+The package defaults are a foundation, not the desired finished look for a branded shop. Start with the reference website and catalog, then make deliberate content and layout choices before replacing package templates.
+
+For a fuller real-shop checklist, read [Shop Best Practices](./docs/shop-best-practices.md) before the first implementation pass.
+
+- Homepage: combine `orderly-home-page` or product rails with shop-owned editorial sections, seasonal/category rails, trust copy, store context, and strong imagery from the catalog or approved brand assets.
+- Category pages: use `NavigationDefinition.description`, `heroImage`, `heroLayout: "covers"` or `heroLayout: "split"`, and `heroCoverCount` to create category headers with context and product-cover previews before adding custom HTML.
+- Product pages: use `defaultShop.productDetail.trustNote`, `secondaryCta`, and detail slots for store visits, secondhand curation notes, return policy, pickup information, or other shop-specific confidence builders.
+- Navigation: use `slot="menu-before"` and `slot="menu-after"` for store finder, donation, volunteer, campaign, or brand links; use `persist-state` for vertical desktop menus with nested categories.
+- Basket: use `basket-mode="inline-desktop"` on `orderly-home-page`, `orderly-category-page`, or `orderly-product-detail-page` when the desktop design needs a right rail that only appears after products are added. Use `<orderly-basket-icon href="/checkout.html" placement="mobile-fixed" hide-when-empty>` for a package-owned mobile cart/checkout button with count.
+- Checkout: keep platform copy out of the user-facing flow. Configure labels through `defaultShop.checkoutLabels` and `basketLabels`, then use scoped CSS and the checkout responsive override rules rather than replacing the checkout template.
+
 ## Components
 
 - `orderly-page-layout` provides reusable page regions for header, header actions, responsive primary navigation placement, left/right sidebars, content, footer, and overlay content. It includes a default logo image using `https://orderly.shop/home/App_Icon.svg`; override it with `logo-src`, `logo-alt`, and `logo-href`. Use `primary-nav-mobile-placement="header"` for the common mobile header burger pattern without a duplicate mobile layout template.
-- `orderly-home-page` composes page layout, responsive primary navigation, one product rail per top-level category, basket icon, basket drawer, product detail dialog, and footer. Configure it with `configureShop({ defaultShop })` plus attributes such as `title`, `eyebrow`, `rail-cta-label`, and `product-href`. The product dialog expand link follows the configured product URL mode, and compact `https://orderly.shop/...` product URLs are preserved when it builds hash or path routes.
-- `orderly-category-page` composes page layout, navigation, search, product grid, product detail, basket icon, and basket around a navigation category. Without properties it uses the package default shop configuration. Override with `configureShop({ defaultShop })` once per shop, set `base-url` or `product-href` in markup, or assign `category`, `navigationItems`, `sortOptions`, `client`, `defaultQuery`, and `basketController` from JavaScript for advanced cases. Configure `defaultShop.navigationLayout` or top-level `navigationLayout` to switch the package-owned category page from desktop side navigation to top horizontal category navigation while keeping the mobile burger in the header. The product dialog expand link uses the configured product URL mode and still supports explicit per-page `product-href` overrides when a shop wants a different physical product page URL.
+- `orderly-home-page` composes page layout, responsive primary navigation, one product rail per top-level category, basket icon, basket drawer, optional inline desktop basket rail, product detail dialog, and footer. Configure it with `configureShop({ defaultShop })` plus attributes such as `title`, `eyebrow`, `rail-cta-label`, `product-href`, and `basket-mode="inline-desktop"`. The product dialog is fullscreen on mobile, keeps a bounded image column on desktop through `--orderly-product-dialog-image-size`, and pushes a same-URL history entry when opened, so browser back closes the overlay before leaving the homepage. The expand link follows the configured product URL mode, and compact `https://orderly.shop/...` product URLs are preserved when it builds hash or path routes.
+- `orderly-category-page` composes page layout, navigation, search, product grid, product detail, basket icon, and basket around a navigation category. Without properties it uses the package default shop configuration. Override with `configureShop({ defaultShop })` once per shop, set `base-url` or `product-href` in markup, or assign `category`, `navigationItems`, `sortOptions`, `client`, `defaultQuery`, and `basketController` from JavaScript for advanced cases. Configure `defaultShop.navigationLayout` or top-level `navigationLayout` to switch the package-owned category page from desktop side navigation to top horizontal category navigation while keeping the mobile burger in the header. Set `basket-mode="inline-desktop"` when the desktop category page should show a right basket rail only after the basket has lines. The product dialog is fullscreen on mobile, keeps a bounded image column on desktop through `--orderly-product-dialog-image-size`, and pushes a same-URL history entry when opened, so browser back closes the overlay before leaving the category. The expand link uses the configured product URL mode and still supports explicit per-page `product-href` overrides when a shop wants a different physical product page URL.
 - `orderly-checkout-page` composes page layout, responsive primary navigation, checkout form, basket order summary, footer, shared basket state, delivery loading, and order-created cleanup. Delivery methods render as radio cards after address entry, service points render as radio-card pickup choices when required, and delivery changes verify the draft so totals update. If a persisted draft already contains a complete address, delivery methods are restored on mount; if it also contains a delivery choice, the draft is verified so the basket summary can show backend shipping and total prices. Configure copy through `configureShop({ defaultShop: { checkoutPageTitle, checkoutPageDescription, checkoutOrderTitle, checkoutTermsHref, checkoutLabels, basketLabels } })`, or assign `client`, `basketController`, `navigationItems`, `checkoutLabels`, and `basketLabels` from JavaScript.
-- `orderly-product-detail-page` composes page layout, navigation, product detail, basket drawer, and footer for a product route. Set `share-url`, the `shareUrl` property, or pass `#url=<encoded-share-url>` in the page URL; compact Orderly slugs are restored to `https://orderly.shop/...` before it calls `SearchService.Search` with `SearchQuery.ShareUrl` and renders the resolved `SearchObject`. It forwards `details-before`, `purchase-note`, `secondary-cta`, and `details-after` slots to the nested product page. Shops can tune outer gutters with `--orderly-product-detail-page-padding`, `--orderly-product-detail-page-mobile-padding`, `--orderly-product-detail-page-inline-padding`, and `--orderly-product-detail-page-mobile-inline-padding`.
-- `orderly-stored-image` accepts `image: StoredImage`, resolves image URLs from the configured prefix, and applies `RotationDeg`, crop, and full-size metadata in the browser.
+- `orderly-product-detail-page` composes page layout, navigation, product detail, basket drawer, optional inline desktop basket rail, and footer for a product route. Set `share-url`, the `shareUrl` property, or pass `#url=<encoded-share-url>` in the page URL; compact Orderly slugs are restored to `https://orderly.shop/...` before it calls `SearchService.Search` with `SearchQuery.ShareUrl` and renders the resolved `SearchObject`. It forwards `details-before`, `purchase-note`, `secondary-cta`, and `details-after` slots to the nested product page. Set `basket-mode="inline-desktop"` when a product page should keep the basket visible as a desktop right rail after add-to-basket. Shops can tune outer gutters with `--orderly-product-detail-page-padding`, `--orderly-product-detail-page-mobile-padding`, `--orderly-product-detail-page-inline-padding`, and `--orderly-product-detail-page-mobile-inline-padding`.
+- `orderly-stored-image` accepts `image: StoredImage`, resolves image URLs from the configured prefix, and applies `RotationDeg`, crop, fit, and role-based CDN sizing in the browser. Default roles include `product-tile` 500x500, `product-detail` 900x900, 180x180 thumbnails, and `fullsize` without size params.
 - `orderly-credit` accepts `credit: Credit` or declarative `amount` and `currency` attributes, then renders stylable money markup. DKK values are formatted as `kr. <pris>`, for example `kr. 100,00`.
-- `orderly-product-tile` accepts `product: SearchObject` and emits `orderly-product-selected`, `orderly-add-to-basket`, and `orderly-remove-from-basket`. Templates can bind the product share URL with `data-orderly-bind="share-url"`; anchors without an existing `href` keep the raw share URL, while anchors that already point at a product page are rewritten to the configured physical product route using hash or path mode. Default tiles and statically hydrated category tiles include `schema.org/Product` and `schema.org/Offer` microdata for name, image, URL, description, SKU, brand, price, currency, and in-stock availability when those fields are present. When a `BasketController` is assigned through `basketController`, the default action button toggles between add and remove, using an icon-only button next to the price. Keyboard focus is indicated on the product title instead of a frame around the whole tile; custom tile templates should keep a title element with `data-orderly-bind="title"` or `.orderly-product-tile__title`.
-- `orderly-product-page` accepts `product: SearchObject`, renders all product image thumbnails, switches the selected image on thumbnail click, and exposes product details plus add-to-basket behavior. Product-page templates bind `title`, `description`, `brand`, `size`, `color`, `condition`, `price`, `image`, `addLabel`, and `closeLabel`; they also support `basket-action-label`, `basket-action-icon`, and `basket-action-state` so product-page add-to-basket markup can share the same binding names as product tiles. The default product template has extension slots `details-before`, `purchase-note`, `secondary-cta`, and `details-after`; use these for shop-specific notices or links without replacing the whole product template. For simple default content, configure `defaultShop.productDetail.trustNote` and `defaultShop.productDetail.secondaryCta`. The fullscreen image viewer is package-owned, so custom product templates only need inline image markup plus optional thumbnail markup; the overlay, click/wheel zoom behavior, labels, focus handling, square image viewport, and overlay thumbnails are injected by the component itself unless `image-viewer="false"` is set. When opened inside an existing product dialog, the viewer is portaled into that open `<dialog>` so it stays above the product overlay; otherwise it is portaled to `document.body`. Main image frame styling lives on the default wrapper, not the inner `orderly-stored-image`, and shops can tune spacing/image framing with `--orderly-product-page-gap`, `--orderly-product-page-mobile-gap`, `--orderly-product-page-media-gap`, `--orderly-product-page-padding`, `--orderly-product-page-mobile-padding`, `--orderly-product-page-details-padding`, `--orderly-product-page-mobile-details-padding`, `--orderly-product-page-image-border`, `--orderly-product-page-image-radius`, `--orderly-product-page-image-background`, and `--orderly-product-page-thumbnail-border`.
+- `orderly-product-tile` accepts `product: SearchObject` and emits `orderly-product-selected`, `orderly-add-to-basket`, and `orderly-remove-from-basket`. Templates can bind the product share URL with `data-orderly-bind="share-url"`; anchors without an existing `href` keep the raw share URL, while anchors that already point at a product page are rewritten to the configured physical product route using hash or path mode. Default tiles, generated starter-shop tile templates, and statically hydrated category tiles include `schema.org/Product`, nested `schema.org/Brand`, and `schema.org/Offer` microdata for Google product snippets: name, image, URL, description, SKU, brand, price, currency, and in-stock availability are emitted when those fields are present. Custom tile templates should preserve the `data-orderly-bind="schema-*"` placeholders plus the `data-orderly-schema-brand` and `data-orderly-schema-offer` wrappers. When a `BasketController` is assigned through `basketController`, the default action button toggles between add and remove, using an icon-only button next to the price. Keyboard focus is indicated on the product title instead of a frame around the whole tile; custom tile templates should keep a title element with `data-orderly-bind="title"` or `.orderly-product-tile__title`.
+- `orderly-product-page` accepts `product: SearchObject`, renders all product image thumbnails, switches the selected image on thumbnail click, and exposes product details plus add-to-basket behavior. It emits `orderly-product-viewed` once per displayed product, so analytics integrations can track `view_item` without replacing the template. Product-page templates bind `title`, `description`, `brand`, `size`, `color`, `condition`, `price`, `image`, `addLabel`, and `closeLabel`; they also support `basket-action-label`, `basket-action-icon`, and `basket-action-state` so product-page add-to-basket markup can share the same binding names as product tiles. The default product template has extension slots `details-before`, `purchase-note`, `secondary-cta`, and `details-after`; use these for shop-specific notices or links without replacing the whole product template. For simple default content, configure `defaultShop.productDetail.trustNote` and `defaultShop.productDetail.secondaryCta`. The fullscreen image viewer is package-owned, so custom product templates only need inline image markup plus optional thumbnail markup; the overlay, click/wheel zoom behavior, labels, focus handling, square image viewport, and overlay thumbnails are injected by the component itself unless `image-viewer="false"` is set. When opened inside an existing product dialog, the viewer is portaled into that open `<dialog>` so it stays above the product overlay; otherwise it is portaled to `document.body`. Main image frame styling lives on the default wrapper, not the inner `orderly-stored-image`, and shops can tune spacing/image framing with `--orderly-product-page-gap`, `--orderly-product-page-mobile-gap`, `--orderly-product-page-media-gap`, `--orderly-product-page-padding`, `--orderly-product-page-mobile-padding`, `--orderly-product-page-details-padding`, `--orderly-product-page-mobile-details-padding`, `--orderly-product-page-image-border`, `--orderly-product-page-image-radius`, `--orderly-product-page-image-background`, and `--orderly-product-page-thumbnail-border`.
 - `orderly-search-box` binds to a target `orderly-product-grid`. Use `mode="textbox"` for an inline search input or `mode="icon"` for a header icon that opens a full-page search overlay. Icon mode searches automatically with a 500ms debounce and renders matching product tiles below the search field. Default home and category pages use icon mode next to the basket icon.
 - `orderly-product-grid` accepts `query: SearchQuery`, merges the configured shop query scope, calls `SearchService.Search`, renders its own sort control from `sortOptions`, supports opaque `ContinuationToken` paging, manual paging, dynamic/infinite scroll, and default loading placeholders while the first page is pending.
 - `orderly-product-rail` accepts `query: SearchQuery`, title, CTA label, and CTA href, then renders the search as a horizontal scroll list by composing `orderly-product-grid`. It is useful for homepages and editorial rows where several category searches should be stacked vertically.
-- `orderly-collection-page` accepts `query: SearchQuery`, title, description, and hero image, then delegates fetching to `orderly-product-grid`.
+- `orderly-collection-page` accepts `query: SearchQuery`, title, description, hero image, `hero-layout`, and `hero-cover-count`, then delegates fetching to `orderly-product-grid`. Use `hero-layout="covers"` to show product-cover previews from the loaded category products without custom category header HTML.
 - `orderly-shop-footer` renders configurable logo, about text, address, contact information, opening hours, and information links.
-- `orderly-basket-icon` and `orderly-basket` share a `BasketController` backed by `DraftOrder` persistence. Basket state events such as `orderly-basket-open`, `orderly-basket-change`, and `orderly-basket-verified` use the current `DraftOrder` directly as `event.detail`, so consumers can derive counts and totals from Core contracts instead of an internal basket data shape. `orderly-basket` renders an item overview, verifies non-empty persisted drafts on load plus later basket mutations through `OrderService.VerifyDraft` when a client or `base-url` is configured, includes a configurable checkout link through `checkout-href` and `checkout-label`, and only exposes quantity selection for lines where `MaxQuantity > 1`. Summary rows now render only backend-provided `DraftOrder` values, never local subtotal/total math, and the component renders both `DraftOrder.Errors` and `DraftOrderLine.Errors`. Custom basket templates can project order-level errors through `data-orderly-slot="errors"`.
+- `orderly-basket-icon` and `orderly-basket` share a `BasketController` backed by `DraftOrder` persistence. Basket state events such as `orderly-basket-open`, `orderly-basket-change`, and `orderly-basket-verified` use the current `DraftOrder` directly as `event.detail`, so consumers can derive counts and totals from Core contracts instead of an internal basket data shape. `orderly-basket-icon` can also render a checkout/cart link with `href`, `placement="mobile-fixed"`, and `hide-when-empty` for a package-owned mobile button with count. `orderly-basket-checkout` includes `{ draft, count, href }` when the checkout action is triggered. `orderly-basket` renders an item overview, verifies non-empty persisted drafts on load plus later basket mutations through `OrderService.VerifyDraft` when a client or `base-url` is configured, includes a configurable checkout link through `checkout-href` and `checkout-label`, and only exposes quantity selection for lines where `MaxQuantity > 1`. Summary rows now render only backend-provided `DraftOrder` values, never local subtotal/total math, and the component renders both `DraftOrder.Errors` and `DraftOrderLine.Errors`. Custom basket templates can project order-level errors through `data-orderly-slot="errors"`.
 - `orderly-checkout` persists checkout contact and address fields directly on `DraftOrder.Transport`, defaults the phone country picker to `+45`, validates email and phone values with built-in component logic, looks up Danish city names from the entered postal code through Dataforsyningen's `https://api.dataforsyningen.dk/postnumre/{postnr}` endpoint, loads delivery methods and service points, verifies the draft, and calls `OrderService.Create`. On mount it restores delivery methods for a persisted complete address and verifies a persisted delivery/service-point choice once, so shared basket summaries receive backend shipping and total prices without waiting for another address edit.
-- `orderly-navigation` uses `NavigationController` and can be subclassed with site-specific `NavigationItem[]`. It is sticky by default, including when placed in `left`, `right`, or `primary-nav`; set `sticky="false"` to opt out. Use `layout="vertical"` for disclosure side navigation, `layout="horizontal"` for the tiered desktop bar, or `layout="burgermenu"` for an icon trigger that expands into the same nested disclosure menu inside a floating panel. Use `layout-desktop="horizontal" layout-mobile="burgermenu"` with `orderly-page-layout primary-nav-mobile-placement="header"` for desktop horizontal nav plus inline mobile burger.
+- `orderly-navigation` uses `NavigationController` and can be subclassed with site-specific `NavigationItem[]`. It is sticky by default, including when placed in `left`, `right`, or `primary-nav`; set `sticky="false"` to opt out. Use `layout="vertical"` for disclosure side navigation, `layout="horizontal"` for the tiered desktop bar, or `layout="burgermenu"` for an icon trigger that expands into the same nested disclosure menu inside a floating panel. Use `layout-desktop="horizontal" layout-mobile="burgermenu"` with `orderly-page-layout primary-nav-mobile-placement="header"` for desktop horizontal nav plus inline mobile burger. Add `persist-state state-key="main-menu"` to remember expanded category branches across navigation, and use `slot="menu-before"`/`slot="menu-after"` for shop-owned links such as store finder, campaigns, or volunteer pages.
 - `orderly-search-box`, `orderly-sort-select`, `orderly-filter-panel`, and `orderly-load-more` bind to `orderly-product-grid`.
 
 ## Navigation Patterns
@@ -667,6 +747,33 @@ configureShop({
 </orderly-page-layout>
 ```
 
+## Basket Layout And Count
+
+Use the package basket primitives before writing custom state glue:
+
+```html
+<orderly-category-page basket-mode="inline-desktop"></orderly-category-page>
+<orderly-basket-icon href="/checkout.html" placement="mobile-fixed" hide-when-empty label="Kurv"></orderly-basket-icon>
+```
+
+`basket-mode="inline-desktop"` is supported by `orderly-home-page`, `orderly-category-page`, and `orderly-product-detail-page`. It keeps the existing drawer behavior on mobile, but on desktop it shows a right rail only when `BasketController.count > 0`.
+
+Basket count contract:
+
+- `BasketController.count` is derived from `DraftOrder.OrderLines[].Quantity`.
+- `orderly-basket-icon`, `orderly-basket`, product tiles/grids/rails, product pages, and checkout should share the same `BasketController` instance.
+- `orderly-basket-change` and `orderly-basket-verified` expose the current `DraftOrder` as `event.detail`; custom UI can derive counts from that draft without copying package state.
+- Verified and persisted drafts still use the same `DraftOrder`; backend-provided prices and errors are rendered by `orderly-basket`.
+
+## Checkout Responsive Overrides
+
+When customizing checkout layout, do not override the package mobile collapse accidentally:
+
+- Keep desktop-only grid changes inside `@media (min-width: 768px)` or the same breakpoint configured through `configureShop({ responsiveTemplates })`.
+- Avoid global `grid-template-columns` overrides on `.orderly-checkout-page__grid`, `.orderly-checkout__field-grid`, `.orderly-checkout__delivery-grid`, and `.orderly-checkout__option-grid--delivery` without a matching mobile reset.
+- Prefer CSS variables and scoped spacing/color rules on `.orderly-checkout-page`, `.orderly-checkout-page__card`, `.orderly-checkout`, and `.orderly-checkout__option`.
+- Keep `.orderly-checkout-page__card--summary` as a normal layout container; the package moves submit/terms controls there for the responsive checkout summary.
+
 ## Rendering And Styling
 
 The package ships baseline default CSS and uses light DOM. Default markup uses stable `orderly-*` class names and CSS variables, so host CSS can style or replace the default look directly.
@@ -885,7 +992,7 @@ Stored images can be rendered directly:
 productImage.image = searchObject.Images[0];
 ```
 
-`orderly-stored-image` uses `DEFAULT_IMAGE_BASE_URL`, currently `https://orderlyproduction.azureedge.net/`, when no custom image URL configuration is supplied. `configureStoredImageUrls({ baseUrl })` maps normal product images to `baseUrl/thumbnails/<StoredImage.Name>` and full/object variants to `baseUrl/objects/<StoredImage.Name>`. The component also supports `ImageDataBase64`, absolute URLs, and a custom resolver through `configureStoredImageUrls({ resolver })`.
+`orderly-stored-image` uses `DEFAULT_IMAGE_BASE_URL`, currently `https://orderlyproduction.azureedge.net/`, when no custom image URL configuration is supplied. `configureStoredImageUrls({ baseUrl })` maps normal product images to `baseUrl/thumbnails/<StoredImage.Name>` and full/object variants to `baseUrl/objects/<StoredImage.Name>`. The component also supports `ImageDataBase64`, absolute URLs, and a custom resolver through `configureStoredImageUrls({ resolver })`. Image URLs use configured roles rather than runtime layout measurement: default roles are `product-tile` 500x500, `product-detail` 900x900, `thumbnail`, `basket-line`, and `checkout-line` 180x180, and `fullsize` with no `width`/`height` parameters. Set `image-role` on the component, pass `{ role }` to `storedImageUrl()`, or override role sizes with `configureShop({ storedImageUrls: { roles } })`. Custom resolvers receive `{ variant, role, width, height }` as the second argument and should preserve those dimensions in the returned URL when the target CDN supports resizing. Use `loading`, `decoding`, and `fetchpriority` on custom image templates when a shop knows which image is above the fold; the default product detail main image is eager/high priority, while normal stored images stay lazy by default.
 
 By default, `orderly-stored-image` does not render a frame border. Add the boolean `border` attribute when a bordered image is wanted: