@orderlyshop/web-components 0.1.0-build.7063 → 0.1.0-build.7067

package/AGENTS.md

@@ -15,6 +15,7 @@ Use this package as a headless storefront component library. Prefer native custo
 - 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/shop-best-practices.md` before building or heavily customizing a shop. Use it as the checklist for moving from the scaffold to a branded, editorial storefront while preserving package-owned components.
 - 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.
@@ -26,6 +27,11 @@ Use this package as a headless storefront component library. Prefer native custo
 - 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.
+- Do not deliver a shop that mostly looks like the package default with minor token changes. The default scaffold is a functional baseline, not the creative target.
+- Inspect the product catalog and use online research when available to understand the shop, category, product type, audience, competitors, and current visual conventions before committing to a design direction.
+- Build a distinctive first version: homepage and category pages should combine package components with shop-owned editorial sections, catalog-driven product groupings, contextual copy, category storytelling, and imagery or content choices that make the shop feel specific.
+- Use `docs/shop-best-practices.md` as the practical standard for the first version, especially when deciding what belongs in shop CSS/config/slots versus custom component logic.
+- Research current high-end frontend execution before finalizing when network access is available. Aim for the technical polish expected from premium product marketing sites: responsive art direction, strong imagery, smooth interaction states, thoughtful motion where appropriate, performance, and accessibility. Use this as a quality bar, not as permission to copy a specific site.
 - 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.
 
@@ -52,24 +58,29 @@ Use this package as a headless storefront component library. Prefer native custo
 
 - 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.
+- Treat visual differentiation as part of the implementation, not a later polish task. Configure package components, slots, templates, and shop CSS so the first working shop already matches the design target as closely as possible.
+- Prefer shop-owned editorial page sections around package components over replacing package templates wholesale. 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.
+- Use `configureShop({ consent })` before enabling optional analytics, marketing, personalization, or shop-owned cookies. Keep cookie/vendor/purpose/duration text accurate for the specific shop, and use `setOrderlyCookie()` or `hasCookieConsent()` for custom optional browser state instead of writing cookies directly.
 - Treat localStorage basket and checkout profile data as user-owned state. Do not add secret persistence.
 - 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-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 `<orderly-basket-icon href="/checkout.html" placement="mobile-fixed" hide-when-empty>` for a package-owned mobile cart/checkout button with count before building a shop-specific fixed basket badge.
 - Use `orderly-checkout-page` for checkout pages instead of wiring `orderly-checkout` and `orderly-basket` manually in app code.
 - 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`.
+- 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 `heroLayout`, optional `heroCoverCount`, optional `description`, optional `query`, and optional `children`.
 - Use plain `SearchQueryInput` objects in navigation definitions, for example `query: { query: "sko sneakers", tags: ["sko"] }`.
 
 ## Common Patterns

package/README.md

@@ -17,39 +17,47 @@ Inputs:
 - Orderly account id: ASK
 - Visual style reference: ASK
 - Deployment target: ASK
+- 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`.
+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.
 
 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.
+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.
 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.
+4. Google Tag Manager is optional. If Google Tag Manager container id is `NONE` or empty, leave GTM/analytics disabled and do not ask for a container id. If it is provided and is not `ASK`, wire it through `VITE_ORDERLY_GOOGLE_TAG_MANAGER_ID` and package config rather than pasting raw GTM snippets. Use `configureShop({ consent, analytics })`, set `consent.policyHref` from Cookie policy URL, set `analytics.dataLayerName` when Google Tag Manager data layer name is not `dataLayer`, and set `analytics.consentCategories` from Analytics consent categories. Keep package Google Consent Mode enabled unless I explicitly ask for a custom CMP/tag setup.
 
 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.
+5. Use the Orderly account id to tenant-scope src/shop-query.ts.
+6. Run npx orderly-init-navigation --suggest --account-id <account-id> when product sampling is possible.
+7. 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.
+8. Use the visual style reference as design direction for palette, radius, spacing, density, typography feel, product tiles, navigation, checkout, and page rhythm.
+9. Do not ship the package default look and feel with minor color changes. Read the package docs, inspect the catalog, research the reference site and comparable modern shops, then create a distinct visual direction that matches the design target.
+10. Build an editorially useful storefront: make the homepage and category pages visually and textually interesting with catalog-driven product groupings, contextual copy, category storytelling, and researched context for the shop, category, or product type.
+11. Research current high-end frontend patterns when network access is available, and aim for the technical polish of a premium product marketing site: strong art direction, responsive composition, high-quality imagery, smooth interaction states, thoughtful motion where appropriate, and excellent performance/accessibility.
+12. Start src/style.css from DESIGN.md semantic tokens. Add component-specific selectors only for details that tokens cannot express.
+13. Do not copy proprietary assets, text, logos, or brand marks from the reference or research sources 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.
+14. 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.
+15. 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.
+16. 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.
+17. Run the nearest relevant build/test command.
+18. Start the dev server when useful and inspect desktop and mobile layouts.
+19. Report what changed, what was verified, and any missing backend, credential, research, analytics, or deployment prerequisite.
 ```
 
 ## Install
@@ -74,7 +82,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 to choose semantic design tokens, radius, spacing, navigation treatment, and component-level exceptions in `src/style.css`. Do not stop at the package default look and feel with a few token changes. Read the package docs, inspect the catalog, research the reference site and comparable modern shops when network access is available, and create a distinctive visual direction that matches the design target from the first pass. The homepage and category pages should be visually and editorially useful: combine catalog-driven sections with contextual copy, category storytelling, and researched context for the shop, category, or product type. Aim for the level of polish expected from premium product marketing sites, including responsive composition, strong imagery, thoughtful interaction states, appropriate motion, performance, and accessibility. Treat the reference and research as design direction, not as permission to copy proprietary assets, text, logos, or brand marks.
 
 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 +90,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,16 +126,79 @@ 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.
@@ -368,10 +439,13 @@ 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"] }`.
+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 `heroLayout`, optional `heroCoverCount`, 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.
+9. Do not leave the shop looking like the package scaffold. Use the sampled catalog, the visual reference, and online research when available to create a distinct visual and editorial concept for the homepage, category pages, and product context.
+10. Add useful shop-owned content around package components where appropriate: editorial hero sections, curated category introductions, product-context sections, buying guidance, trust content, and category-specific imagery or copy derived from the catalog and research.
+11. Research current high-end frontend execution before finalizing when network access is available. The result should feel technically polished, responsive, and intentional, with strong art direction, smooth interaction states, appropriate motion, performance, and accessibility.
 
 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 +473,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.
 
@@ -443,6 +517,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 +590,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:
 
@@ -520,7 +608,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 +643,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 +706,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. 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`. 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 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
@@ -640,6 +748,19 @@ There are two different mobile navigation patterns:
 - `layout-desktop="horizontal" layout-mobile="burgermenu"` plus `primary-nav-mobile-placement="header"` means desktop horizontal navigation and an inline mobile burger in the page header next to search, basket, or other icon buttons. This is the recommended setup for the common storefront header pattern.
 - Custom `data-orderly-viewport="mobile"` page-layout templates are only needed when a shop replaces the whole page layout and wants manual control over where `data-orderly-slot="primary-nav"` is rendered.
 
+Package-owned home, category, product, checkout, and payment pages read the same pattern from configuration:
+
+```ts
+configureShop({
+  navigationLayout: {
+    primaryNavDesktopPlacement: "primary-nav",
+    primaryNavMobilePlacement: "header",
+    layoutDesktop: "horizontal",
+    layoutMobile: "burgermenu"
+  }
+});
+```
+
 ```html
 <orderly-page-layout primary-nav-mobile-placement="header">
   <a slot="header" href="/">Shop name</a>
@@ -654,6 +775,33 @@ There are two different mobile navigation patterns:
 </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.
@@ -732,6 +880,18 @@ For dynamic paging, `orderly-product-grid` keeps the returned `PageResult.Contin
 
 Every component has a default light-DOM implementation and matching template hooks. Use `data-orderly-bind` for values, `data-orderly-action` for behavior, and `data-orderly-slot` for repeated or projected content. Product tile templates can bind `basket-action-icon`, `basket-action-label`, and `basket-action-state` and use `data-orderly-action="add-to-basket"` for the add/remove toggle. Product page templates keep the existing `addLabel` binding and also support `basket-action-label`, `basket-action-icon`, and `basket-action-state` for the same add-to-basket concept; use `data-orderly-action="add-to-basket"` for the action. Product page galleries use `data-orderly-slot="thumbnails"` and `data-orderly-action="select-image"` for custom thumbnail markup, while the fullscreen viewer overlay stays package-owned; shops can optionally mark a custom trigger with `data-orderly-image-viewer-trigger`, otherwise the inline `data-orderly-bind="image"` element becomes the trigger automatically. The viewer overlay may be moved outside the product-page host while open, either to `document.body` or to the nearest open `<dialog>`, so custom CSS or tests should target `[data-orderly-image-overlay]` instead of assuming the overlay remains inside `orderly-product-page`. Basket templates can add `data-orderly-slot="errors"` to place order-level `DraftOrder.Errors` exactly where a shop wants them. Product rail templates can replace the outer `layout`, inner `grid`, product item, loading state, and empty state. The main template names are `layout`, `grid`, `footer`, `product`, `thumbnail`, `image`, `basket`, `basket-icon`, `line`, `checkout`, `navigation`, `item`, `search-box`, `sort`, `sort-select`, `filter-panel`, `load-more`, `address-line`, `contact-item`, `opening-hour`, and `information-link`.
 
+Use product page detail slots for small shop-specific content without replacing the package product template:
+
+```html
+<orderly-product-detail-page>
+  <section slot="purchase-note">
+    <strong>Kurateret secondhand</strong>
+    <p>Alle varer er udvalgt og pakket i butikken.</p>
+  </section>
+  <a slot="secondary-cta" href="/butik/">Besøg butikken på Nørrebrogade</a>
+</orderly-product-detail-page>
+```
+
 Product sorting belongs to `orderly-product-grid`: assign `grid.sortOptions = [{ label, orderBy }]` or pass sort options through `orderly-collection-page.sortOptions`. The default grid layout renders the sort select above the products. Custom grid layouts should include `data-orderly-slot="sort"` where the control should appear, and custom sort templates can use `data-orderly-template="sort"` with a `<select data-orderly-action="sort">`.
 
 Simple product queries can be declared in markup on `orderly-product-grid`, `orderly-product-rail`, and `orderly-collection-page`:
@@ -860,7 +1020,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: