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

package/AGENTS.md

@@ -5,35 +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.
-
-## Discovery
-
-- 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.
-- 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.
-- 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.
+- 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.
+
+## Required Reading and Intake
+
+- 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
 
@@ -56,32 +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.
-- 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.
+- 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.
-- 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.
+- 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. 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 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 `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"] }`.
+- 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

@@ -24,40 +24,17 @@ Inputs:
 
 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, 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:
-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:
-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:
-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:
-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:
-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.
+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
@@ -82,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`. 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.
+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.
 
@@ -205,7 +182,7 @@ Developers and coding agents should start with these package-owned docs:
 - [`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`:
 
@@ -430,22 +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 `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.
+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.
 
@@ -505,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:
 
@@ -599,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
 

package/dist/browser/orderly-web-components.define.global.js

@@ -4925,7 +4925,7 @@ button.orderly-product-page__image-button:active {
     <span class="orderly-payment-result-page__line-title" data-orderly-bind="title"></span>
     <span class="orderly-payment-result-page__line-quantity" data-orderly-bind="quantity"></span>
     <${e} class="orderly-payment-result-page__line-price" data-orderly-bind="price"></${e}>
-  `,Qe(o,"thumbnail",t.Images[0]),ve(o,"thumbnail",ge(t.Images[0],"thumbnail",aA)),h(o,"title",t.Title??t.SKU?.Value??c("itemFallbackTitle")),h(o,"quantity",`${c("quantityShortLabel")} ${t.Quantity??0}`),ie(o,"price",O(t.Price??t.TotalItemPrice??t.PricePerPiece)),o}function dA(t,e,r){t.querySelectorAll("[data-orderly-order-card]").forEach(o=>{o instanceof HTMLElement&&(o.hidden=!e)}),t.querySelectorAll(".orderly-payment-result-page__empty").forEach(o=>{o instanceof HTMLElement&&(o.hidden=e)}),t.querySelectorAll('[data-orderly-bind="paymentLink"]').forEach(o=>{o instanceof HTMLAnchorElement&&(r?(o.href=r,o.hidden=!1):(o.removeAttribute("href"),o.hidden=!0))})}function og(t){return t?.Reference??t?.Payment?.Reference??t?.Id?.Id?.Value??""}function cA(){return typeof location>"u"?"":new URL(location.href).searchParams.get("orderid")??""}function uA(){return typeof location>"u"?"/":location.pathname}var Ps="orderly-product-tile",Ao=class extends L{static observedAttributes=["base-url","paging","sort-label","clear-search-label","error-label","loading-label","results-label","searching-label",...Ke];currentQuery;currentDefaultQuery;currentProducts=[];continuation;loading=!1;error;observer;totalCount=0;estimatedTotalCount;controller;currentSortOptions=[];currentInitialProducts;initialProductsConsumed=!1;paging="button";productTileTagName=Ps;get defaultQuery(){return this.currentDefaultQuery}set defaultQuery(e){this.currentDefaultQuery=e,this.refresh()}get shopQuery(){return this.defaultQuery}set shopQuery(e){this.defaultQuery=e}get sortOptions(){return[...this.currentSortOptions]}set sortOptions(e){this.currentSortOptions=[...e],this.requestRender()}get sortLabel(){return this.getAttribute("sort-label")??c("sortLabel")}set sortLabel(e){this.setAttribute("sort-label",e)}get clearSearchLabel(){return this.getAttribute("clear-search-label")??c("clearSearchLabel")}set clearSearchLabel(e){this.setAttribute("clear-search-label",e)}get errorLabel(){return this.getAttribute("error-label")??c("productsLoadError")}set errorLabel(e){this.setAttribute("error-label",e)}get loadingLabel(){return this.getAttribute("loading-label")??c("loadingLabel")}set loadingLabel(e){this.setAttribute("loading-label",e)}get resultsLabel(){return this.getAttribute("results-label")??c("productsLabel")}set resultsLabel(e){this.setAttribute("results-label",e)}get searchingLabel(){return this.getAttribute("searching-label")??c("searchingLabel")}set searchingLabel(e){this.setAttribute("searching-label",e)}get basketController(){return this.controller}set basketController(e){this.controller=e,this.requestRender()}get query(){return this.currentQuery}set query(e){this.currentQuery=e,this.refresh()}get products(){return[...this.currentProducts]}set products(e){this.currentProducts=[...e],this.totalCount=e.length,this.estimatedTotalCount=e.length,this.continuation=void 0,this.error=void 0,this.loading=!1,this.initialProductsConsumed=!0,this.requestRender(),F(this,"orderly-results",this.state)}get initialProducts(){return this.currentInitialProducts?[...this.currentInitialProducts]:void 0}set initialProducts(e){this.currentInitialProducts=e?[...e]:void 0,this.initialProductsConsumed=!1}get continuationToken(){return this.continuation}get hasMore(){return Ks(this.continuation)}get state(){return{loading:this.loading,error:this.error,products:this.products,count:this.totalCount,estimatedTotalCount:this.estimatedTotalCount,hasMore:this.hasMore}}connectedCallback(){if(super.connectedCallback(),!this.currentInitialProducts?.length){let e=Lt(this);e.length>0&&(this.currentInitialProducts=e)}this.hasAttribute("paging")&&(this.paging=ng(this.getAttribute("paging"),this.paging)),this.productTileTagName===Ps&&(this.productTileTagName=G(this,"product-grid","product-tile")),!this.currentQuery&&Ne(this)&&this.refresh()}disconnectedCallback(){this.observer?.disconnect(),super.disconnectedCallback()}attributeChangedCallback(e){if(e==="paging"&&(this.paging=ng(this.getAttribute("paging"),this.paging)),Ke.includes(e)){this.isConnected&&this.refresh();return}this.requestRender()}async refresh(){if(!this.resolvedQuery()){this.currentProducts=[],this.continuation=void 0,this.requestRender();return}this.consumeInitialProducts()||(this.currentProducts=[],this.continuation=void 0,await this.fetchPage(!1))}async loadNextPage(){!this.resolvedQuery()||this.loading||!this.hasMore||await this.fetchPage(!0)}async setSort(e){let r=this.resolvedQuery();if(!r)return;let o=K(Y,r);o.OrderBy=[...e],this.currentQuery=o,await this.refresh()}async clearSearch(){let e=this.resolvedQuery();if(!e)return;let r=K(Y,e);r.Query="",this.currentQuery=r,await this.refresh()}render(){let e=Z(this,"layout")??fA();h(e,"status",this.error?this.errorLabel:this.loading?this.loadingLabel:""),_(e,"context",this.renderContext()),_(e,"sort",this.renderSort()),this.configureSortContainer(e),_(e,"items",this.renderProducts()),this.configureLoadMore(e);let r=x(this,e);r.toggleAttribute("aria-busy",this.loading),this.toggleAttribute("data-orderly-loading",this.loading),this.configureInfiniteScroll(r)}renderProducts(){let e=document.createDocumentFragment();if(this.loading&&this.currentProducts.length===0){let r=Z(this,"loading");return e.append(r??bA()),e}if(!this.loading&&!this.error&&this.currentProducts.length===0){let r=Z(this,"empty");e.append(r??gA(c("emptyLabel")))}for(let r of this.currentProducts)e.append(this.renderProduct(r));return e}async fetchPage(e){this.loading=!0,this.error=void 0,this.requestRender();try{let r=Xr(this.resolvedQuery(),this.currentDefaultQuery);e?r.Continuation=this.continuation:r.Continuation=void 0;let o=await this.getClient().services.searchService.search(r),n=sa(o);this.currentProducts=e?[...this.currentProducts,...n]:n,this.continuation=pA(o.Continuation),this.totalCount=o.Count,this.estimatedTotalCount=o.EstimatedTotalCount,F(this,"orderly-results",this.state)}catch(r){this.error=r,F(this,"orderly-error",{error:r})}finally{this.loading=!1,this.requestRender()}}consumeInitialProducts(){return this.initialProductsConsumed||!this.currentInitialProducts?.length?!1:(this.currentProducts=[...this.currentInitialProducts],this.continuation=void 0,this.totalCount=this.currentInitialProducts.length,this.estimatedTotalCount=this.currentInitialProducts.length,this.error=void 0,this.loading=!1,this.initialProductsConsumed=!0,this.hideInitialMarkup(),this.requestRender(),F(this,"orderly-results",this.state),!0)}hideInitialMarkup(){this.querySelectorAll(":scope > [data-orderly-product], :scope > [data-orderly-products], :scope > [data-orderly-ssr-fallback]").forEach(e=>{e instanceof HTMLElement&&(e.hidden=!0)})}renderProduct(e){let r=Z(this,"product");if(r){let n=document.createElement("div");n.append(r),customElements.upgrade(n),lr(n,e);let a=n.querySelector(this.productTileTagName)??n.querySelector(Ps);a&&(a.basketController=this.controller,a.product=e);let i=document.createDocumentFragment();return SA(n),i.append(...n.childNodes),i}let o=document.createElement(this.productTileTagName);return o.className="orderly-product-grid__item",ag(o),o.basketController=this.controller,o.product=e,o}renderSort(){if(this.currentSortOptions.length===0)return;let e=Z(this,"sort")??yA();h(e,"sort-label",this.sortLabel);let r=e.querySelector('[data-orderly-action="sort"]')??e.querySelector("select");if(r instanceof HTMLSelectElement){r.replaceChildren(...this.currentSortOptions.map((n,a)=>{let i=document.createElement("option");return i.value=String(a),i.textContent=n.label,i}));let o=this.selectedSortIndex();o>=0?r.value=String(o):r.selectedIndex=-1,r.disabled=!this.resolvedQuery(),r.addEventListener("change",()=>{let n=this.currentSortOptions[Number(r.value)];n&&this.setSort(n.orderBy)})}return e}renderContext(){let e=Z(this,"context")??hA(),r=this.resolvedQuery(),o=r?.Query?.trim()??"",n=this.estimatedTotalCount??this.totalCount??this.currentProducts.length;return h(e,"resultCount",r?`${n} ${this.resultsLabel}`:""),h(e,"activeQuery",o?`${this.searchingLabel} "${o}"`:""),h(e,"clearSearchLabel",this.clearSearchLabel),h(e,"loadingLabel",this.loading?this.loadingLabel:""),e.querySelectorAll('[data-orderly-action="clear-search"]').forEach(a=>{a instanceof HTMLElement&&(a.hidden=!o,a.addEventListener("click",()=>{this.clearSearch()}))}),e.querySelectorAll("[data-orderly-loading-indicator]").forEach(a=>{a instanceof HTMLElement&&(a.hidden=!this.loading)}),e}selectedSortIndex(){let e=this.resolvedQuery()?.OrderBy??[];return this.currentSortOptions.findIndex(r=>vA(r.orderBy,e))}resolvedQuery(){return this.currentQuery??Ne(this)}configureSortContainer(e){this.currentSortOptions.length>0||e.querySelectorAll("[data-orderly-sort-container]").forEach(r=>r.remove())}configureLoadMore(e){e.querySelectorAll('[data-orderly-action="load-more"]').forEach(r=>{if(r instanceof HTMLElement){if(this.paging!=="button"||!this.hasMore){r.remove();return}r instanceof HTMLButtonElement&&(r.disabled=this.loading),r.addEventListener("click",()=>{this.loadNextPage()})}})}configureInfiniteScroll(e){if(this.observer?.disconnect(),!mA(this.paging)||!this.hasMore||typeof IntersectionObserver>"u")return;let r=e.querySelector("[data-orderly-sentinel]");r&&(this.observer=new IntersectionObserver(o=>{o.some(n=>n.isIntersecting)&&this.loadNextPage()}),this.observer.observe(r))}};function Ks(t){return!!t?.Token}function pA(t){return Ks(t)?t:void 0}function ng(t,e){return t==="dynamic"||t==="infinite"?"infinite":t==="manual"||t==="button"?t:e}function mA(t){return t==="dynamic"||t==="infinite"}function sa(t){return t.data.map(e=>bt(e,un)).filter(e=>!!e)}function gA(t){let e=document.createElement("p");return e.className="orderly-product-grid__message",e.textContent=t,e}function yA(){let t=document.createDocumentFragment(),e=document.createElement("label");return e.className="orderly-product-grid__sort",e.innerHTML=`
+  `,Qe(o,"thumbnail",t.Images[0]),ve(o,"thumbnail",ge(t.Images[0],"thumbnail",aA)),h(o,"title",t.Title??t.SKU?.Value??c("itemFallbackTitle")),h(o,"quantity",`${c("quantityShortLabel")} ${t.Quantity??0}`),ie(o,"price",O(t.Price??t.TotalItemPrice??t.PricePerPiece)),o}function dA(t,e,r){t.querySelectorAll("[data-orderly-order-card]").forEach(o=>{o instanceof HTMLElement&&(o.hidden=!e)}),t.querySelectorAll(".orderly-payment-result-page__empty").forEach(o=>{o instanceof HTMLElement&&(o.hidden=e)}),t.querySelectorAll('[data-orderly-bind="paymentLink"]').forEach(o=>{o instanceof HTMLAnchorElement&&(r?(o.href=r,o.hidden=!1):(o.removeAttribute("href"),o.hidden=!0))})}function og(t){return t?.Reference??t?.Payment?.Reference??t?.Id?.Id?.Value??""}function cA(){return typeof location>"u"?"":new URL(location.href).searchParams.get("orderid")??""}function uA(){return typeof location>"u"?"/":location.pathname}var Ps="orderly-product-tile",Ao=class extends L{static observedAttributes=["base-url","paging","sort-label","clear-search-label","error-label","loading-label","results-label","searching-label",...Ke];currentQuery;currentDefaultQuery;currentProducts=[];continuation;loading=!1;error;observer;totalCount=0;estimatedTotalCount;controller;currentSortOptions=[];currentInitialProducts;initialProductsConsumed=!1;paging="button";productTileTagName=Ps;get defaultQuery(){return this.currentDefaultQuery}set defaultQuery(e){this.currentDefaultQuery=e,this.refresh()}get shopQuery(){return this.defaultQuery}set shopQuery(e){this.defaultQuery=e}get sortOptions(){return[...this.currentSortOptions]}set sortOptions(e){this.currentSortOptions=[...e],this.requestRender()}get sortLabel(){return this.getAttribute("sort-label")??c("sortLabel")}set sortLabel(e){this.setAttribute("sort-label",e)}get clearSearchLabel(){return this.getAttribute("clear-search-label")??c("clearSearchLabel")}set clearSearchLabel(e){this.setAttribute("clear-search-label",e)}get errorLabel(){return this.getAttribute("error-label")??c("productsLoadError")}set errorLabel(e){this.setAttribute("error-label",e)}get loadingLabel(){return this.getAttribute("loading-label")??c("loadingLabel")}set loadingLabel(e){this.setAttribute("loading-label",e)}get resultsLabel(){return this.getAttribute("results-label")??c("productsLabel")}set resultsLabel(e){this.setAttribute("results-label",e)}get searchingLabel(){return this.getAttribute("searching-label")??c("searchingLabel")}set searchingLabel(e){this.setAttribute("searching-label",e)}get basketController(){return this.controller}set basketController(e){this.controller=e,this.requestRender()}get query(){return this.currentQuery}set query(e){this.currentQuery=e,this.refresh()}get products(){return[...this.currentProducts]}set products(e){this.currentProducts=[...e],this.totalCount=e.length,this.estimatedTotalCount=e.length,this.continuation=void 0,this.error=void 0,this.loading=!1,this.initialProductsConsumed=!0,this.requestRender(),F(this,"orderly-results",this.state)}get initialProducts(){return this.currentInitialProducts?[...this.currentInitialProducts]:void 0}set initialProducts(e){this.currentInitialProducts=e?[...e]:void 0,this.initialProductsConsumed=!1}get continuationToken(){return this.continuation}get hasMore(){return Ks(this.continuation)}get state(){return{loading:this.loading,error:this.error,products:this.products,count:this.totalCount,estimatedTotalCount:this.estimatedTotalCount,hasMore:this.hasMore}}connectedCallback(){if(super.connectedCallback(),!this.currentInitialProducts?.length){let e=Lt(this);e.length>0&&(this.currentInitialProducts=e)}this.hasAttribute("paging")&&(this.paging=ng(this.getAttribute("paging"),this.paging)),this.productTileTagName===Ps&&(this.productTileTagName=G(this,"product-grid","product-tile")),!this.currentQuery&&Ne(this)&&this.refresh()}disconnectedCallback(){this.observer?.disconnect(),super.disconnectedCallback()}attributeChangedCallback(e){if(e==="paging"&&(this.paging=ng(this.getAttribute("paging"),this.paging)),Ke.includes(e)){this.isConnected&&this.refresh();return}this.requestRender()}async refresh(){if(!this.resolvedQuery()){this.currentProducts=[],this.continuation=void 0,this.requestRender();return}let r=this.consumeInitialProducts();r&&!this.hasLiveSearchTarget()||(r||(this.currentProducts=[],this.continuation=void 0),await this.fetchPage(!1))}async loadNextPage(){!this.resolvedQuery()||this.loading||!this.hasMore||await this.fetchPage(!0)}async setSort(e){let r=this.resolvedQuery();if(!r)return;let o=K(Y,r);o.OrderBy=[...e],this.currentQuery=o,await this.refresh()}async clearSearch(){let e=this.resolvedQuery();if(!e)return;let r=K(Y,e);r.Query="",this.currentQuery=r,await this.refresh()}render(){let e=Z(this,"layout")??fA();h(e,"status",this.error?this.errorLabel:this.loading?this.loadingLabel:""),_(e,"context",this.renderContext()),_(e,"sort",this.renderSort()),this.configureSortContainer(e),_(e,"items",this.renderProducts()),this.configureLoadMore(e);let r=x(this,e);r.toggleAttribute("aria-busy",this.loading),this.toggleAttribute("data-orderly-loading",this.loading),this.configureInfiniteScroll(r)}renderProducts(){let e=document.createDocumentFragment();if(this.loading&&this.currentProducts.length===0){let r=Z(this,"loading");return e.append(r??bA()),e}if(!this.loading&&!this.error&&this.currentProducts.length===0){let r=Z(this,"empty");e.append(r??gA(c("emptyLabel")))}for(let r of this.currentProducts)e.append(this.renderProduct(r));return e}async fetchPage(e){this.loading=!0,this.error=void 0,this.requestRender();try{let r=Xr(this.resolvedQuery(),this.currentDefaultQuery);e?r.Continuation=this.continuation:r.Continuation=void 0;let o=await this.getClient().services.searchService.search(r),n=sa(o);this.currentProducts=e?[...this.currentProducts,...n]:n,this.continuation=pA(o.Continuation),this.totalCount=o.Count,this.estimatedTotalCount=o.EstimatedTotalCount,F(this,"orderly-results",this.state)}catch(r){this.error=r,F(this,"orderly-error",{error:r})}finally{this.loading=!1,this.requestRender()}}consumeInitialProducts(){return this.initialProductsConsumed||!this.currentInitialProducts?.length?!1:(this.currentProducts=[...this.currentInitialProducts],this.continuation=void 0,this.totalCount=this.currentInitialProducts.length,this.estimatedTotalCount=this.currentInitialProducts.length,this.error=void 0,this.loading=!1,this.initialProductsConsumed=!0,this.hideInitialMarkup(),this.requestRender(),F(this,"orderly-results",this.state),!0)}hasLiveSearchTarget(){return!!(this.client||this.baseUrl||this.getDefaultBaseUrl())}hideInitialMarkup(){this.querySelectorAll(":scope > [data-orderly-product], :scope > [data-orderly-products], :scope > [data-orderly-ssr-fallback]").forEach(e=>{e instanceof HTMLElement&&(e.hidden=!0)})}renderProduct(e){let r=Z(this,"product");if(r){let n=document.createElement("div");n.append(r),customElements.upgrade(n),lr(n,e);let a=n.querySelector(this.productTileTagName)??n.querySelector(Ps);a&&(a.basketController=this.controller,a.product=e);let i=document.createDocumentFragment();return SA(n),i.append(...n.childNodes),i}let o=document.createElement(this.productTileTagName);return o.className="orderly-product-grid__item",ag(o),o.basketController=this.controller,o.product=e,o}renderSort(){if(this.currentSortOptions.length===0)return;let e=Z(this,"sort")??yA();h(e,"sort-label",this.sortLabel);let r=e.querySelector('[data-orderly-action="sort"]')??e.querySelector("select");if(r instanceof HTMLSelectElement){r.replaceChildren(...this.currentSortOptions.map((n,a)=>{let i=document.createElement("option");return i.value=String(a),i.textContent=n.label,i}));let o=this.selectedSortIndex();o>=0?r.value=String(o):r.selectedIndex=-1,r.disabled=!this.resolvedQuery(),r.addEventListener("change",()=>{let n=this.currentSortOptions[Number(r.value)];n&&this.setSort(n.orderBy)})}return e}renderContext(){let e=Z(this,"context")??hA(),r=this.resolvedQuery(),o=r?.Query?.trim()??"",n=this.estimatedTotalCount??this.totalCount??this.currentProducts.length;return h(e,"resultCount",r?`${n} ${this.resultsLabel}`:""),h(e,"activeQuery",o?`${this.searchingLabel} "${o}"`:""),h(e,"clearSearchLabel",this.clearSearchLabel),h(e,"loadingLabel",this.loading?this.loadingLabel:""),e.querySelectorAll('[data-orderly-action="clear-search"]').forEach(a=>{a instanceof HTMLElement&&(a.hidden=!o,a.addEventListener("click",()=>{this.clearSearch()}))}),e.querySelectorAll("[data-orderly-loading-indicator]").forEach(a=>{a instanceof HTMLElement&&(a.hidden=!this.loading)}),e}selectedSortIndex(){let e=this.resolvedQuery()?.OrderBy??[];return this.currentSortOptions.findIndex(r=>vA(r.orderBy,e))}resolvedQuery(){return this.currentQuery??Ne(this)}configureSortContainer(e){this.currentSortOptions.length>0||e.querySelectorAll("[data-orderly-sort-container]").forEach(r=>r.remove())}configureLoadMore(e){e.querySelectorAll('[data-orderly-action="load-more"]').forEach(r=>{if(r instanceof HTMLElement){if(this.paging!=="button"||!this.hasMore){r.remove();return}r instanceof HTMLButtonElement&&(r.disabled=this.loading),r.addEventListener("click",()=>{this.loadNextPage()})}})}configureInfiniteScroll(e){if(this.observer?.disconnect(),!mA(this.paging)||!this.hasMore||typeof IntersectionObserver>"u")return;let r=e.querySelector("[data-orderly-sentinel]");r&&(this.observer=new IntersectionObserver(o=>{o.some(n=>n.isIntersecting)&&this.loadNextPage()}),this.observer.observe(r))}};function Ks(t){return!!t?.Token}function pA(t){return Ks(t)?t:void 0}function ng(t,e){return t==="dynamic"||t==="infinite"?"infinite":t==="manual"||t==="button"?t:e}function mA(t){return t==="dynamic"||t==="infinite"}function sa(t){return t.data.map(e=>bt(e,un)).filter(e=>!!e)}function gA(t){let e=document.createElement("p");return e.className="orderly-product-grid__message",e.textContent=t,e}function yA(){let t=document.createDocumentFragment(),e=document.createElement("label");return e.className="orderly-product-grid__sort",e.innerHTML=`
       <span class="orderly-product-grid__sort-label" data-orderly-bind="sort-label"></span>
       <select class="orderly-product-grid__sort-select" data-orderly-action="sort"></select>
     `,t.append(e),t}function hA(){let t=document.createDocumentFragment(),e=document.createElement("div");return e.className="orderly-product-grid__context",e.innerHTML=`