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

package/AGENTS.md

@@ -2,6 +2,14 @@
 
 Use this package as a headless storefront component library. Prefer native custom elements, light-DOM templates, and normal CSS over framework-specific wrappers unless the user asks for a framework integration.
 
+## 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.
@@ -13,6 +21,14 @@ Use this package as a headless storefront component library. Prefer native custo
 - Inspect `examples/shop` for a complete vanilla TypeScript shop that customizes the defaults without replacing package logic.
 - When creating a new shop from scratch, run `npx orderly-init-shop` first. It scaffolds the vanilla HTML/TypeScript/Vite structure that the package expects, including `src/includes/head.html`, `src/navigation.ts`, `src/shop-query.ts`, page templates, and package scripts.
 
+## New Shop Intake
+
+- Ask the user for the Orderly account id so `src/shop-query.ts` can tenant-scope the default `SearchQuery`.
+- Ask the user for a reference website URL for the desired visual style. If they do not have one, ask for a short description of the target look.
+- Use the reference website as design direction only: extract palette, density, radius, typography feel, spacing, and navigation patterns into semantic Orderly tokens and shop CSS. Do not copy proprietary assets, text, logos, or brand marks unless the user confirms they own or may use them.
+- Put the resulting theme in `src/style.css` or the consuming shop stylesheet, starting with `DESIGN.md` tokens before adding component-specific selectors.
+- After scaffolding, run the nearest local dev/build command and visually compare the shop against the requested reference at desktop and mobile widths when a browser is available.
+
 ## Query Rules
 
 - Use `configureShop({ defaultShop: { defaultQuery } })` for shop-wide query scope. `defaultQuery` is a full Core `SearchQuery`.

package/README.md

@@ -4,6 +4,54 @@ Headless native web components for Orderly storefronts.
 
 The package depends on `@orderlyshop/core-client` and wraps Core contracts such as `SearchObject`, `SearchQuery`, and `DraftOrder` in reusable browser components. Components render practical light-DOM defaults and expose typed properties, events, controllers, stores, and template overrides so host shops keep full control over CSS, layout, routing, and copy.
 
+## Agent Prompt Template
+
+Copy this prompt into a coding agent when you want it to install the package and build a finished Orderly shop. Fill in known values first; if a value is filled in and is not `ASK`, the agent should use it without asking again.
+
+```text
+Build a production-ready Orderly storefront with @orderlyshop/web-components.
+
+Inputs:
+- Project directory: ASK
+- Shop name: ASK
+- Orderly account id: ASK
+- Visual style reference: ASK
+- Deployment target: ASK
+
+Use any provided input above without asking again. Ask only for values that are still `ASK`.
+
+Install and setup:
+1. Install @orderlyshop/core-client and @orderlyshop/web-components if they are not already installed.
+2. Read node_modules/@orderlyshop/web-components/AGENTS.md, DESIGN.md, README.md, and docs/components/README.md before changing shop files.
+3. Run npx orderly-init-shop for a new shop. Pass --account-id when the Orderly account id is provided. Preserve existing files unless I explicitly approve overwrite.
+
+Navigation:
+4. Use the Orderly account id to tenant-scope src/shop-query.ts.
+5. Run npx orderly-init-navigation --suggest --account-id <account-id> when product sampling is possible.
+6. Build src/navigation.ts manually from navigation-products.json with at most two category levels, stable unique slugs, and plain SearchQueryInput objects.
+
+Visual style:
+7. Use the visual style reference as design direction for palette, radius, spacing, density, typography feel, product tiles, navigation, checkout, and page rhythm.
+8. Start src/style.css from DESIGN.md semantic tokens. Add component-specific selectors only for details that tokens cannot express.
+9. Do not copy proprietary assets, text, logos, or brand marks from the reference unless I explicitly confirm they may be used.
+
+Pages and behavior:
+10. Use package-owned components and configuration: orderly-home-page, orderly-category-page, orderly-product-detail-page, orderly-checkout-page, configureShop(...), templates, and the generated Vite setup.
+11. Keep product/category SSR and generated category URLs working unless the deployment target requires a different routing approach.
+
+Deployment:
+12. Configure the build/publish flow for the deployment target.
+    - For static hosting, use npm run build and document the dist upload.
+    - For FTP, use npx orderly-publish-site --target ftp.
+    - For Apache/PHP or Nginx/PHP, keep the package-generated server renderers and document the required server helper files.
+    - For any other target, document the exact build output and any remaining deployment assumptions.
+
+Validation:
+13. Run the nearest relevant build/test command.
+14. Start the dev server when useful and inspect desktop and mobile layouts.
+15. Report what changed, what was verified, and any missing backend, credential, or deployment prerequisite.
+```
+
 ## Install
 
 ```sh
@@ -26,6 +74,8 @@ 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.
+
 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`. Dev mode SSR for product/category URLs is enabled by default, so View Source on local category/product URLs shows semantic server-rendered markup. 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.
@@ -84,6 +134,8 @@ 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.
+
 Enable HTML editor hints in a consuming project by adding the package custom data file to `.vscode/settings.json`:
 
 ```json
@@ -308,16 +360,18 @@ 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. Run the navigation helper to dump sampled product information:
+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:
 
 ```sh
 npx orderly-init-navigation --suggest --account-id <account-id>
 ```
 
-3. 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.
-4. 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. 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.
-6. Configure the shop scope with a Core `SearchQuery` and pass it to `configureShop({ defaultShop: { defaultQuery } })`.
+4. Read the generated `navigation-products.json`. The helper does not infer categories. It writes sampled product records with `title`, `brand`, and `tags` only, plus sampling metadata.
+5. Create `navigation.ts` manually from the dump. Export `navigationDefinitions: NavigationDefinition[]`. Each entry must have `label` and a stable, globally unique `slug`, and can also have optional `heroImage`, optional `description`, optional `query`, and optional recursive `children`. Use plain `SearchQueryInput` objects for `query`, such as `{ query: "sko sneakers", tags: ["sko"] }`.
+6. Keep navigation to at most two category levels. Categories should be reasonably granular, but avoid empty categories or categories backed by only a few products.
+7. Configure the shop scope with a Core `SearchQuery` and pass it to `configureShop({ defaultShop: { defaultQuery } })`.
+8. Translate the reference website into `src/style.css` by setting `DESIGN.md` semantic tokens first, then add scoped component selectors only for visual details the tokens cannot express.
 
 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.
 
@@ -562,7 +616,7 @@ collection.query = searchQuery;
 - `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-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. Configure copy through `configureShop({ defaultShop: { checkoutPageTitle, checkoutPageDescription, checkoutOrderTitle, checkoutTermsHref, checkoutLabels, basketLabels } })`, or assign `client`, `basketController`, `navigationItems`, `checkoutLabels`, and `basketLabels` from JavaScript.
+- `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-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`.
@@ -574,7 +628,7 @@ collection.query = searchQuery;
 - `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 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-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-search-box`, `orderly-sort-select`, `orderly-filter-panel`, and `orderly-load-more` bind to `orderly-product-grid`.
 

package/bin/orderly-init-shop.mjs

@@ -136,8 +136,12 @@ function agentsSource() {
   return `# Agent Guide
 
 - This shop was scaffolded with \`npx orderly-init-shop\` from \`@orderlyshop/web-components\`.
+- These instructions are optimized for GPT-5.5-class coding agents. Work from the requested storefront outcome, keep changes narrow, and verify with the nearest shop script.
+- Read \`node_modules/@orderlyshop/web-components/AGENTS.md\`, \`DESIGN.md\`, and \`docs/components/README.md\` before changing package integration patterns.
+- Ask the user for the Orderly account id and a reference website URL for the desired visual style before customizing the scaffold.
 - 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.
+- Use the reference website as design direction for palette, radius, spacing, density, typography feel, and navigation treatment. Do not copy proprietary assets, text, logos, or brand marks unless the user confirms they own or may use them.
 - 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.
@@ -183,6 +187,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\`.
+- For agent-assisted visual setup, provide a reference website URL. Use it to choose semantic tokens, radius, spacing, and navigation treatment in \`src/style.css\` without copying protected assets or text.
 - \`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(...)\`.
@@ -813,8 +818,9 @@ Agent workflow:
   1. If no shop scaffold exists, run: npx orderly-init-shop
   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.
+  4. Ask the user for a reference website URL for the desired visual style.
+  5. Customize src/navigation.ts with categories and SearchQuery values.
+  6. Translate the reference website into src/style.css with DESIGN.md semantic tokens first.
 `);
 }
 

package/custom-elements.json

@@ -107,7 +107,7 @@
           "name": "OrderlyCheckoutPageElement",
           "tagName": "orderly-checkout-page",
           "customElement": true,
-          "description": "Default checkout page composed from page layout, navigation, checkout form, basket summary, footer, and shared basket state.",
+          "description": "Default checkout page composed from page layout, navigation, checkout form, basket summary, footer, shared basket state, and persisted delivery restore.",
           "attributes": [
             { "name": "base-url", "description": "Backend URL used when no client property is assigned." },
             { "name": "brand-label", "description": "Brand text." },
@@ -439,7 +439,7 @@
           "name": "OrderlyCheckoutElement",
           "tagName": "orderly-checkout",
           "customElement": true,
-          "description": "Checkout form that collects profile data, lists delivery methods and service points, verifies the draft, and creates an order.",
+          "description": "Checkout form that collects profile data, lists delivery methods and service points, restores persisted delivery choices, verifies the draft, and creates an order.",
           "attributes": [
             { "name": "base-url", "description": "Backend URL used when no client property is assigned." },
             { "name": "terms-href", "description": "Terms link URL." },