@orderlyshop/web-components 0.1.0-build.7050 → 0.1.0-build.7051

package/AGENTS.md

@@ -5,6 +5,7 @@ Use this package as a headless storefront component library. Prefer native custo
 ## 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/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.
@@ -34,6 +35,7 @@ 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.
 - 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`.

package/README.md

@@ -20,13 +20,15 @@ npm install
 npm run dev
 ```
 
-Agents and developers should use `npx orderly-init-shop` before hand-writing shop files. It creates `src/index.html`, `src/category.html`, `src/product.html`, `src/checkout.html`, `src/includes/head.html`, `src/navigation.ts`, `src/shop-query.ts`, `src/templates/*.html`, `src/style.css`, `vite.config.mjs`, and package scripts. Pass an account id when the shop-wide default query should be tenant-scoped from the start:
+Agents and developers should use `npx orderly-init-shop` before hand-writing shop files. It creates `src/index.html`, `src/category.html`, `src/product.html`, `src/checkout.html`, `src/payment-success.html`, `src/payment-failure.html`, `src/includes/head.html`, `src/navigation.ts`, `src/shop-query.ts`, `src/templates/*.html`, `src/style.css`, `vite.config.mjs`, and package scripts. The payment pages are physical callback URLs for payment providers and use the package `orderly-payment-success-page` and `orderly-payment-failure-page` components. Pass an account id when the shop-wide default query should be tenant-scoped from the start:
 
 ```sh
 npx orderly-init-shop --account-id 00000000-0000-0000-0000-000000000000
 ```
 
-The scaffold uses Vite for local development and static builds, but Vite is added to the generated shop's `devDependencies`. Local development is configured for `http://localhost:61677` because that is the backend CORS development origin. `@orderlyshop/web-components` does not depend on Vite at runtime.
+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.
+
+The scaffold uses Vite for local development and static builds, but Vite is added to the generated shop's `devDependencies`. Consumers should test locally from `http://localhost:61677` or `https://localhost:61677` because those are the expected local development origins for backend CORS. The generated Vite setup defaults to `http://localhost:61677`; if a local reverse proxy or TLS terminator is added, keep the same `localhost:61677` origin over HTTPS. `@orderlyshop/web-components` does not depend on Vite at runtime.
 
 ## Browser Standalone Bundle
 
@@ -66,7 +68,7 @@ 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`, `pageLayout`, `responsiveTemplates`, `shopFooter`, `storedImageUrls`, and `components`. It applies configuration first and then registers custom elements. 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`, 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.
 
@@ -74,6 +76,7 @@ Built-in component copy is Danish by default (`uiLanguage: "DA"`). Set `uiLangua
 
 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/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.
@@ -118,6 +121,82 @@ import "@orderlyshop/web-components/define";
 
 The default backend is `https://service.orderly.shop`. Category links use real `/categories/<category-path>/` URLs by default so production builds can ship server-rendered category HTML. Use `categoryUrlMode: "hash"` only when a shop explicitly wants the older `/category.html#id=<category>` routing.
 
+## SPA Storefront Navigation
+
+SPA-style storefront navigation is the default when a shop calls `configureShop()`. It is implemented as progressive enhancement, not as a replacement for normal URLs:
+
+- Links remain normal same-origin `<a href>` links, so Google, no-JS browsers, new tabs, copied links, and server-rendered entry pages still work.
+- Ordinary left-click navigation between known storefront routes is intercepted in the browser and rendered without a physical reload.
+- The router uses `history.pushState`, `popstate`, scroll restoration, canonical URLs, meta description updates, document title updates, and optional View Transitions.
+- A shared `BasketController` is kept alive across home, category, product, checkout, payment result, and configured static routes.
+- Unknown routes, external links, modified clicks, downloads, `_blank` links, and hash-only links fall back to the browser.
+
+The default route coverage is:
+
+- home: `defaultShop.homeHref`, default `/`
+- categories: real category paths generated from `navigationDefinitions`, default `/categories/<category-path>/`
+- product details: either hash or path product URLs, controlled by `defaultShop.productUrlMode`
+- checkout: `defaultShop.checkoutHref`, default `/checkout.html`
+- payment result pages: `/payment-success.html?orderid=...` and `/payment-failure.html?orderid=...`
+- static pages: routes explicitly supplied in `storefrontRouter.staticRoutes`
+
+The simplest setup needs no router block:
+
+```ts
+configureShop({
+  defaultShop: {
+    homeHref: "/",
+    productHref: "/products/",
+    productUrlMode: "path",
+    productPathRoot: "/products/",
+    checkoutHref: "/checkout.html",
+    navigationDefinitions
+  }
+});
+```
+
+Use `storefrontRouter` only when the shop needs custom static pages, custom page factories, View Transition control, or an explicit opt-out:
+
+```ts
+configureShop({
+  defaultShop: {
+    homeHref: "/",
+    productHref: "/products/",
+    productUrlMode: "path",
+    productPathRoot: "/products/",
+    checkoutHref: "/checkout.html"
+  },
+  storefrontRouter: {
+    product: {
+      mode: "path",
+      pathRoot: "/products/"
+    },
+    staticRoutes: [
+      {
+        path: "/forretningsbetingelser.html",
+        title: "Forretningsbetingelser | Example Shop",
+        description: "Køb, levering, betaling, retur og reklamation.",
+        create: () => document.querySelector("#termsPage")!.cloneNode(true) as HTMLElement
+      }
+    ]
+  }
+});
+```
+
+Disable SPA navigation explicitly when a host application owns routing or when every internal link must perform a full document navigation:
+
+```ts
+configureShop({
+  storefrontRouter: {
+    enabled: false
+  }
+});
+```
+
+If a shop still uses hash-based product URLs, set `productUrlMode: "hash"` or `storefrontRouter.product.mode: "hash"`. The package supports both `#url=<encoded-share-url>` and real product paths; path URLs are preferred for SEO, while hash URLs remain a fallback for shops that cannot add server-side product routing yet.
+
+For SEO, keep physical pages or static generated pages available for every URL the router can render dynamically. The router improves navigation after the first load; it does not remove the need for server/static support for direct requests to category, product, checkout, and content URLs.
+
 Customize the default once per shop from the HTML head:
 
 ```ts
@@ -194,13 +273,15 @@ After installing from the repository workspace, run it with:
 npm run dev --workspace @orderlyshop/example-shop
 ```
 
+Open the local shop from `http://localhost:61677` during normal development, or `https://localhost:61677` when a local TLS proxy is in front of the dev server. Consumers should keep that exact localhost origin because the backend CORS development policy expects it.
+
 Inside an installed package, inspect the same reference implementation at:
 
 ```text
 node_modules/@orderlyshop/web-components/examples/shop
 ```
 
-The example demonstrates how to customize the package default with Danish navigation, shop copy, and declarative home/category/product/checkout pages while exercising the base component renderers directly. It intentionally avoids local CSS and templates while the package default look and feel is developed. Shared component configuration lives in `src/includes/head.html`; the strongly typed navigation data lives in `src/navigation.ts`. It uses the package-level `orderly-generate-category-pages` and `orderly-build-category-pages` commands for simple real-URL category pages. It is included as readable source code and is not exported as part of the runtime API.
+The example demonstrates how to customize the package default with Danish navigation, shop copy, declarative home/category/product/checkout pages, and the default SPA router. Its router config only adds static content routes and page factories; `enabled: true` is not required. It intentionally avoids local CSS and templates while the package default look and feel is developed. Shared component configuration lives in `src/includes/head.html`; the strongly typed navigation data lives in `src/navigation.ts`. It uses the package-level `orderly-generate-category-pages` and `orderly-build-category-pages` commands for simple real-URL category pages. It is included as readable source code and is not exported as part of the runtime API.
 
 ## Navigation Setup
 
@@ -467,27 +548,49 @@ collection.query = searchQuery;
 ## Components
 
 - `orderly-page-layout` provides reusable page regions for header, header actions, 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`.
-- `orderly-home-page` composes page layout, side 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 includes an expand icon link to `product-href#url=<encoded-share-url>`; `https://orderly.shop/` is stripped from Orderly product URLs before encoding.
-- `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 includes an expand icon link built from `SearchObject.ShareURL.URL`, using compact hashes for `https://orderly.shop/...` product URLs.
+- `orderly-home-page` composes page layout, side 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-checkout-page` composes page layout, side 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. 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`.
 - `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-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 receive `href` and other elements receive `share-url`. If an anchor already has `href="/product.html"`, the bound link becomes `/product.html#url=<encoded-share-url>`, using the compact path for `https://orderly.shop/...` product URLs. 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.
+- `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.
 - `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.
 - `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-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 changed drafts 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`.
-- `orderly-checkout` persists checkout profile fields, 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`.
-- `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.
+- `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-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`.
+- `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.
 - `orderly-search-box`, `orderly-sort-select`, `orderly-filter-panel`, and `orderly-load-more` bind to `orderly-product-grid`.
 
 ## Rendering And Styling
 
-The package ships baseline default CSS and uses light DOM. Default markup uses stable `orderly-*` class names and CSS variables such as `--orderly-color-accent`, `--orderly-color-page`, `--orderly-color-surface`, `--orderly-color-text`, `--orderly-color-muted`, and `--orderly-content-max-width`, so host CSS can style or replace the default look directly.
+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.
+
+For consistent theming across the whole package, start with the semantic design contract in [`DESIGN.md`](./DESIGN.md). In practice that means overriding `--orderly-color-primary`, `--orderly-color-primary-soft`, `--orderly-color-primary-contrast`, the `--orderly-action-primary-*` and `--orderly-action-secondary-*` tokens, plus shared tokens such as `--orderly-link-accent-color`, `--orderly-selection-*`, and `--orderly-badge-*`. `--orderly-color-accent` is kept as a compatibility alias, but new themes should treat `--orderly-color-primary` as the source of truth.
+
+Example:
+
+```css
+:root {
+  --orderly-color-primary: #1f7a43;
+  --orderly-color-primary-soft: #e7f4eb;
+  --orderly-color-primary-contrast: #ffffff;
+  --orderly-link-accent-color: var(--orderly-color-primary);
+  --orderly-selection-border: var(--orderly-color-primary);
+  --orderly-selection-background: var(--orderly-color-primary-soft);
+  --orderly-badge-background: var(--orderly-color-primary);
+  --orderly-badge-color: var(--orderly-color-primary-contrast);
+  --orderly-action-primary-background: var(--orderly-color-primary);
+  --orderly-action-primary-border: var(--orderly-color-primary);
+  --orderly-action-primary-color: var(--orderly-color-primary-contrast);
+  --orderly-action-secondary-border: var(--orderly-color-primary);
+  --orderly-action-secondary-color: var(--orderly-color-primary);
+}
+```
 
 Rendering can be replaced with templates:
 
@@ -537,7 +640,7 @@ Rendering can be replaced with templates:
 
 For dynamic paging, `orderly-product-grid` keeps the returned `PageResult.Continuation` as an opaque `ContinuationToken` and sends it as `SearchQuery.Continuation` when the sentinel enters the viewport. Dynamic and infinite paging do not render a load-more button. Use `paging="button"` only when a visible load-more button is desired, `paging="manual"` when another control calls `loadNextPage()`, and `paging="dynamic"` or `paging="infinite"` for automatic loading.
 
-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 galleries use `data-orderly-slot="thumbnails"` and `data-orderly-action="select-image"` for custom thumbnail markup. 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`.
+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 galleries use `data-orderly-slot="thumbnails"` and `data-orderly-action="select-image"` for custom thumbnail markup. 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`.
 
 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">`.
 
@@ -671,15 +774,14 @@ productImage.image = searchObject.Images[0];
 
 ## State And Security
 
-Basket drafts and checkout profile fields are persisted to localStorage by default. Checkout profile data can include PII such as name, address, email, and phone. Provide custom stores to change or disable that behavior. This package never stores tokens, API keys, OAuth responses, or cookie values.
+Basket drafts are persisted to localStorage by default. Checkout contact and address data are stored directly on `DraftOrder.Transport`, so basket items, delivery selection, and checkout form state all share the same persisted draft. That draft can contain PII such as name, address, email, and phone. Provide a custom basket store to change or disable that behavior. This package never stores tokens, API keys, OAuth responses, or cookie values.
 
-Basket persistence uses `LocalStorageBasketStore`. Checkout profile persistence uses `LocalStorageCheckoutProfileStore`. Both can be replaced:
+Persistence uses `LocalStorageBasketStore` and stores the full `DraftOrder`:
 
 ```ts
 import { createBasketController } from "@orderlyshop/web-components";
 
 basket.basketController = createBasketController({ store: myBasketStore });
-checkout.profileStore = myCheckoutProfileStore;
 ```
 
 Authentication remains owned by `@orderlyshop/core-client`. Browser cookie-backed sessions work through the core browser client and credentialed gRPC-web requests.

package/bin/orderly-init-shop.mjs

@@ -32,14 +32,6 @@ if (!skipPackageJson) {
   planned.push("package.json");
 }
 
-const existing = files
-  .filter((file) => !file.skipIfExists)
-  .map((file) => file.path)
-  .filter((file) => existsSync(resolve(targetRoot, file)));
-if (existing.length && !force) {
-  throw new Error(`Refusing to overwrite existing files: ${existing.join(", ")}. Re-run with --force to overwrite scaffold files.`);
-}
-
 if (dryRun) {
   console.log(`Would initialize ${shopName} in ${relative(cwd, targetRoot) || "."}.`);
   for (const file of planned) {
@@ -51,13 +43,15 @@ if (dryRun) {
 mkdirSync(targetRoot, { recursive: true });
 for (const file of files) {
   const target = resolve(targetRoot, file.path);
-  if (file.skipIfExists && existsSync(target) && !force) {
-    console.log(`Skipped existing ${relative(cwd, target)}.`);
+  const relativeTarget = relative(cwd, target);
+  const targetExists = existsSync(target);
+  if (targetExists && !force) {
+    console.warn(`Warning: ${relativeTarget} already exists; leaving it unchanged. Re-run with --force to overwrite.`);
     continue;
   }
   mkdirSync(dirname(target), { recursive: true });
   writeFileSync(target, file.content, "utf8");
-  console.log(`Created ${relative(cwd, target)}.`);
+  console.log(`${targetExists ? "Overwrote" : "Created"} ${relativeTarget}.`);
 }
 
 if (!skipPackageJson) {
@@ -84,6 +78,8 @@ function scaffoldFiles(options) {
     { path: "src/category.html", content: pageSource({ title: `Kategori | ${options.shopName}`, element: "<orderly-category-page></orderly-category-page>" }) },
     { path: "src/product.html", content: pageSource({ title: `Produkt | ${options.shopName}`, element: productDetailElementSource() }) },
     { path: "src/checkout.html", content: pageSource({ title: `Betaling | ${options.shopName}`, element: checkoutElementSource() }) },
+    { path: "src/payment-success.html", content: pageSource({ title: `Tak for din ordre | ${options.shopName}`, element: paymentSuccessElementSource() }) },
+    { path: "src/payment-failure.html", content: pageSource({ title: `Betaling kunne ikke gennemføres | ${options.shopName}`, element: paymentFailureElementSource() }) },
     { path: "src/includes/head.html", content: headIncludeSource(options) },
     { path: "src/includes/body-start.html", content: bodyStartSource() },
     { path: "src/includes/body-end.html", content: "<!-- Add shared body-end snippets here. -->\n" },
@@ -141,6 +137,7 @@ function agentsSource() {
 
 - This shop was scaffolded with \`npx orderly-init-shop\` from \`@orderlyshop/web-components\`.
 - Keep storefront logic in Orderly web components. Customize navigation, content, templates, and CSS instead of replacing package components.
+- Start visual theming from the package \`DESIGN.md\` semantic tokens before using component-local selectors.
 - Configure shop-wide backend, default query, navigation, page layout, and component registration in \`src/includes/head.html\` through \`configureShop(...)\`.
 - Use \`src/navigation.ts\` for category/navigation structure. Every category needs a stable globally unique \`slug\`.
 - Use \`src/shop-query.ts\` for the shop-wide Core \`SearchQuery\`, such as tenant/account scoping.
@@ -164,6 +161,8 @@ npm run build
 npm run preview
 \`\`\`
 
+Test the shop locally from \`http://localhost:61677\` during normal development, or \`https://localhost:61677\` if a local TLS proxy terminates HTTPS in front of the dev server. Keep the origin on \`localhost:61677\`, because the backend CORS development policy expects that local origin.
+
 Override the backend during local development:
 
 \`\`\`sh
@@ -180,6 +179,7 @@ Use \`npm run generate:categories\` when you want to inspect generated source pa
 
 ## Customize
 
+- For consistent theming across all components, start with the semantic token contract in \`node_modules/@orderlyshop/web-components/DESIGN.md\`.
 - \`src/navigation.ts\` defines storefront navigation and category queries.
 - \`src/shop-query.ts\` defines the shop-wide Core \`SearchQuery\`.
 - \`src/includes/head.html\` calls \`configureShop(...)\`.
@@ -444,6 +444,26 @@ function checkoutElementSource() {
     </orderly-checkout-page>`;
 }
 
+function paymentSuccessElementSource() {
+  return `<orderly-payment-success-page>
+      <div slot="utility" class="shop-utility-strip" aria-label="Kundefordele">
+        <span>Hurtig levering</span>
+        <span>Nem retur</span>
+        <span>Sikker betaling</span>
+      </div>
+    </orderly-payment-success-page>`;
+}
+
+function paymentFailureElementSource() {
+  return `<orderly-payment-failure-page>
+      <div slot="utility" class="shop-utility-strip" aria-label="Kundefordele">
+        <span>Hurtig levering</span>
+        <span>Nem retur</span>
+        <span>Sikker betaling</span>
+      </div>
+    </orderly-payment-failure-page>`;
+}
+
 function headIncludeSource(options) {
   return `<!-- Add shared head snippets here, for example analytics, consent, or preconnect tags. -->
 <link rel="icon" href="https://orderly.shop/home/App_Icon.svg" type="image/svg+xml">
@@ -575,7 +595,9 @@ body.orderly-navigation-menu-open {
 orderly-home-page:not(:defined),
 orderly-category-page:not(:defined),
 orderly-product-detail-page:not(:defined),
-orderly-checkout-page:not(:defined) {
+orderly-checkout-page:not(:defined),
+orderly-payment-success-page:not(:defined),
+orderly-payment-failure-page:not(:defined) {
   display: block;
   min-height: 100vh;
   background: #f6f8f9;
@@ -584,7 +606,9 @@ orderly-checkout-page:not(:defined) {
 orderly-home-page:not(:defined)::before,
 orderly-category-page:not(:defined)::before,
 orderly-product-detail-page:not(:defined)::before,
-orderly-checkout-page:not(:defined)::before {
+orderly-checkout-page:not(:defined)::before,
+orderly-payment-success-page:not(:defined)::before,
+orderly-payment-failure-page:not(:defined)::before {
   content: "";
   display: block;
   height: 62px;
@@ -843,9 +867,10 @@ Options:
 
 Agent workflow:
   1. If no shop scaffold exists, run: npx orderly-init-shop
-  2. Ask the user for the shop account id. Re-run with --account-id <id> or edit src/shop-query.ts.
-  3. Customize src/navigation.ts with categories and SearchQuery values.
-  4. Customize src/templates/*.html and src/style.css for the shop look and feel.
+  2. Existing scaffold files are skipped with warnings. Use --force only when the user explicitly wants overwrite.
+  3. Ask the user for the shop account id. Re-run with --account-id <id> or edit src/shop-query.ts.
+  4. Customize src/navigation.ts with categories and SearchQuery values.
+  5. Customize src/templates/*.html and src/style.css for the shop look and feel.
 `);
 }
 

package/custom-elements.json

@@ -130,6 +130,39 @@
             { "name": "orderly-error", "type": { "text": "CustomEvent<{ error: unknown }>" } }
           ]
         },
+        {
+          "kind": "class",
+          "name": "OrderlyPaymentSuccessPageElement",
+          "tagName": "orderly-payment-success-page",
+          "customElement": true,
+          "description": "Payment success callback page that loads a stored order from a base64 encoded protobuf OrderId.",
+          "attributes": [
+            { "name": "order-id", "description": "Base64 encoded protobuf OrderId. Defaults to the orderid URL parameter." },
+            { "name": "brand-label", "description": "Brand text." },
+            { "name": "title", "description": "Page heading." },
+            { "name": "description", "description": "Page intro text." },
+            { "name": "reference-label", "description": "Order reference label." },
+            { "name": "order-title", "description": "Order summary heading." },
+            { "name": "empty-label", "description": "Text shown when the order is not found locally." }
+          ]
+        },
+        {
+          "kind": "class",
+          "name": "OrderlyPaymentFailurePageElement",
+          "tagName": "orderly-payment-failure-page",
+          "customElement": true,
+          "description": "Payment failure callback page that lets the customer retry the stored order payment link.",
+          "attributes": [
+            { "name": "order-id", "description": "Base64 encoded protobuf OrderId. Defaults to the orderid URL parameter." },
+            { "name": "brand-label", "description": "Brand text." },
+            { "name": "title", "description": "Page heading." },
+            { "name": "description", "description": "Page intro text." },
+            { "name": "reference-label", "description": "Order reference label." },
+            { "name": "order-title", "description": "Order summary heading." },
+            { "name": "empty-label", "description": "Text shown when the order is not found locally." },
+            { "name": "retry-label", "description": "Retry payment link label." }
+          ]
+        },
         {
           "kind": "class",
           "name": "OrderlyProductGridElement",
@@ -278,7 +311,7 @@
           "name": "OrderlyProductTileElement",
           "tagName": "orderly-product-tile",
           "customElement": true,
-          "description": "Product tile for SearchObject with product selection and basket toggle behavior.",
+          "description": "Product tile for SearchObject with product selection, basket toggle behavior, and configurable share-url binding for raw share URLs or physical product routes.",
           "attributes": [
             { "name": "add-label", "description": "Add-to-basket accessible label." },
             { "name": "remove-label", "description": "Remove-from-basket accessible label." }
@@ -369,7 +402,7 @@
           "name": "OrderlyBasketElement",
           "tagName": "orderly-basket",
           "customElement": true,
-          "description": "DraftOrder basket overview with persistence, remove actions, quantity display, verification, summary, and checkout link.",
+          "description": "DraftOrder basket overview with persistence, remove actions, quantity display, backend VerifyDraft summary rendering, order-level and line-level errors, and checkout link.",
           "attributes": [
             { "name": "base-url", "description": "Backend URL used when no client property is assigned." },
             { "name": "empty-label", "description": "Empty basket text." },
@@ -423,9 +456,9 @@
           "name": "OrderlyNavigationMenuElement",
           "tagName": "orderly-navigation",
           "customElement": true,
-          "description": "Navigation menu with vertical or horizontal layouts, nested disclosure behavior, desktop tiered navigation support, horizontal overflow scrolling, projected inline content, and selection events.",
+          "description": "Navigation menu with vertical, horizontal, or burgermenu layouts, nested disclosure behavior, desktop tiered horizontal navigation support, horizontal overflow scrolling, projected inline content, and selection events.",
           "attributes": [
-            { "name": "layout", "description": "Navigation layout. Use vertical for a side menu or horizontal for a tiered desktop menu with a scrolling top row, full-width second row, and third-level dropdowns." },
+            { "name": "layout", "description": "Navigation layout. Use vertical for a side menu, horizontal for a tiered desktop menu with a scrolling top row, full-width second row, and third-level dropdowns, or burgermenu for an icon trigger that opens a nested disclosure menu inside a floating panel." },
             { "name": "sticky", "description": "Set to false to opt out of sticky positioning." }
           ],
           "members": [