@dropins/mcp 0.1.0

package/dist/registry/docs/get-started.json

@@ -0,0 +1,85 @@
+{
+  "section": "get-started",
+  "label": "Getting Started",
+  "pageCount": 13,
+  "pages": [
+    {
+      "path": "get-started",
+      "title": "Storefront developer guide",
+      "description": "Learn what Adobe Commerce Storefront is on Edge Delivery, how the boilerplate and drop-ins fit together, and where to go next from first preview through launch.",
+      "content": "## What is Adobe Commerce Storefront?\n\nAdobe Commerce Storefront helps you build a fast online store on Adobe Commerce without treating speed and brand fit as opposites: you can pursue strong web performance scores while you shape layout and shopping flows for your brand.\n\nPages are served by Edge Delivery Services (Adobe's hosting and delivery infrastructure that turns authored documents into fast HTML pages served from servers close to the shopper. You push code to GitHub; Edge Delivery Services builds and publishes automatically.) (EDS), Adobe's global delivery network that turns merchant-authored documents into HTML near shoppers around the world. Merchants keep editing in a document-style workflow while you own the storefront code, so content changes and code changes stay out of each other's way.\n\nYour job as a developer is to connect Commerce data to the page. You start from the Commerce boilerplate, a Git repository that already contains a working storefront. Then you add drop-in components (NPM packages that provide core Commerce storefront features such as cart, checkout, product details, and account flows.) for the Commerce experiences you need, such as cart, checkout, product details, search, and accounts. Drop-ins call Adobe Commerce GraphQL (A query language that drop-in components use to request and update data from Adobe Commerce APIs. Catalog Service, Live Search, and the core Commerce API all expose GraphQL endpoints.) APIs from the shopper's browser, so cart and catalog data stay current without you building that UI on the Commerce server. You customize how drop-ins look and behave instead of writing every Commerce screen from scratch.\n\nMany developers have a working storefront preview in less than a day.\n\n> **About drop-in licensing**\n>\nDrop-in components are included with an Adobe Commerce as a Cloud Service or Adobe Commerce Optimizer license. Commerce PaaS by itself does not license drop-ins unless your organization adds Adobe Commerce Optimizer. Read [Backend options](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/) to match your backend type to prerequisites, and [Licensing requirements](https://experienceleague.adobe.com/developer/commerce/storefront/licensing/) for who can use drop-ins.\n\n\n## New here? Start here.\n\nYou can start with [Create a storefront](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/create-storefront/) if your team already has accounts and a chosen backend. If not, most early problems come from missing Commerce access, the wrong backend checklist, or storefront services that drop-ins need. The numbered path below closes that gap.\n\n<Callouts columnCount={1}>\n1. [Before you start](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/before-you-start/) — Gather your tools, accounts, and Commerce access before you open Site Creator.\n1. [Storefront Architecture](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/architecture/) — Five short topics: how pages load, what blocks and drop-ins are, how drop-ins coordinate, and how Commerce services connect. Build your mental model before you build code.\n1. [Backend options](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/) — Identify your Commerce backend (Commerce PaaS, Adobe Commerce as a Cloud Service, or Adobe Commerce Optimizer) and confirm what you need before you create a site.\n1. [Create a storefront](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/create-storefront/) — Provision your repo and preview URL with Site Creator in DA.live. This is where your first working preview comes from.\n1. [Boilerplate getting started](https://experienceleague.adobe.com/developer/commerce/storefront/boilerplate/getting-started/) — Run the Commerce boilerplate on your machine after which you will have a locally running storefront with Commerce blocks already connected.\n1. [Boilerplate configuration](https://experienceleague.adobe.com/developer/commerce/storefront/boilerplate/configuration/) — `config.json`, headers, and paths that match your production environment.\n1. [Introduction to drop-ins](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/introduction/) and [Using drop-ins](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/quick-start/) — What drop-in components are, the initializer import pattern, slots, styling, and labels. Read these before you customize any Commerce UI.\n1. [Storefront configuration](https://experienceleague.adobe.com/developer/commerce/storefront/setup/configuration/commerce-configuration/) — Connect the storefront to Commerce endpoints and services.\n1. [Get to know SEO](https://experienceleague.adobe.com/developer/commerce/storefront/setup/seo/) — Connect Edge Delivery SEO and GEO guidance with Commerce storefront indexing, metadata, and launch checks.\n1. [Launch checklist](https://experienceleague.adobe.com/developer/commerce/storefront/setup/launch/) — Steps to finish before you treat the site as production-ready.\n</Callouts>\n\nIf you already know your task, use the sidebar for the full catalog (Commerce Boilerplate, Working with Drop-Ins, Storefront configuration, Go live, Playgrounds, and reference groups). When preview or local builds misbehave, read [Storefront Architecture](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/architecture/) first so you split issues into authoring, Edge Delivery, or Commerce instead of searching only under `blocks/`.\n\n## Reference and recipes\n\nWhen you need APIs, props, slots, events, or version notes for Adobe's shipped drop-ins, open the matching drop-in under B2C Drop-Ins or B2B Drop-Ins in the sidebar.\n\nMost storefront projects extend those shipped drop-ins (styling, slots, labels, and behavior). That work lives in [Working with Drop-Ins](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/introduction/) and each drop-in's reference pages. The Drop-ins SDK section is for a smaller set of cases: developers who author new drop-in packages or integrate with the mounting and lifecycle framework—not typical customization of Adobe's packages.\n\nThe Recipes (How-Tos) section provides step-by-step pages for common tasks such as federated search, Luma Bridge, cart, checkout, and user account flows."
+    },
+    {
+      "path": "get-started/architecture",
+      "title": "Storefront Architecture",
+      "description": "A visual map and plain-language definitions for documents, blocks, drop-ins, the Commerce boilerplate, and Adobe Commerce APIs on Edge Delivery Services.",
+      "content": "These short topics give you a working map of documents, delivery, blocks, drop-ins, events, and Commerce services. You will also see which layer to check first when a block will not render, a drop-in shows no data, or Commerce calls fail.\n\n## How the pieces fit together\n\nMerchants create pages as documents. Edge Delivery Services (Adobe's hosting and delivery infrastructure that turns authored documents into fast HTML pages served from servers close to the shopper. You push code to GitHub; Edge Delivery Services builds and publishes automatically.) turns those documents into HTML. Your Git repository runs JavaScript in the shopper's browser to load the right Commerce UI for each block on the page. Drop-in components (NPM packages that provide core Commerce storefront features such as cart, checkout, product details, and account flows.) inside those blocks call Adobe Commerce APIs to load real product, cart, and account data.\n\nIf you are new to this stack, think of it in three layers: an authoring layer (how merchants create pages), a delivery and logic layer (how pages load and run code), and a data layer (where live Commerce information comes from). The diagram below shows all three at once.\n\n<Diagram type=\"mermaid\" code={`\n%%{init: {'flowchart': {'rankSpacing': 45, 'nodeSpacing': 30}}}%%\nflowchart TB\n    Doc[\"Document\"]\n    EDS[\"Edge Delivery Services\"]\n    Doc -->|\"published by\"| EDS\n    EDS -->|\"HTML blocks\"| ContentPath[\"Content block\"]\n    EDS -->|\"HTML blocks\"| CommercePath[\"Commerce block\"]\n    CommercePath -->|\"loads\"| DropIn[\"Drop-in component\"]\n    DropIn -->|\"calls\"| API[\"Commerce APIs\"]\n    Repo[\"Commerce boilerplate\"]\n    CommercePath -.->|\"connects to\"| Repo\n    Repo -.->|\"configures\"| DropIn\n    classDef eds fill:#e8f5e9,stroke:#4caf50\n    classDef commerce fill:#e3f2fd,stroke:#2196f3\n    classDef api fill:#fff3e0,stroke:#ff9800\n    class Doc,EDS,ContentPath eds\n    class CommercePath,DropIn,Repo commerce\n    class API api\n`} caption=\"Merchants create documents that Edge Delivery Services converts into HTML blocks. Content blocks display text and media. Commerce blocks load drop-in components, which call Adobe Commerce APIs for live cart, product, and account data. The Commerce boilerplate (your Git repository) is the code that connects blocks to drop-ins.\" />\n\n> **How this differs from a classic Commerce storefront**\n>\nIn a classic storefront, Adobe Commerce often builds shopper-facing pages with PHP. On this storefront, Edge Delivery Services delivers the HTML and JavaScript. Drop-in components call Commerce APIs from the shopper's browser when they need live cart, product, or account data. The Commerce Admin, catalog, and order tools stay on the server. You change how the storefront page is assembled, not how Commerce stores data.\n\n\n## Key concepts\n\n### Edge Delivery Services\n\nEdge Delivery Services (EDS) is Adobe's cloud delivery network for storefront pages. It turns authored documents into HTML and serves those pages from servers close to the shopper, so pages load fast. You do not manage servers or deployments. When you push code to GitHub, EDS builds and publishes automatically.\n\n### Document Authoring and DA.live\n\nDocument Authoring is the way merchants create and update storefront pages without writing code. Pages are written as documents in Google Docs, SharePoint, or directly in  (Document Author). Tables in those documents define the blocks on the page. Site Creator (App in Document Author (DA.live) that creates and initializes a storefront by setting up content, optional code, theme choice, and storefront configuration values.), the tool you use to set up a new storefront, also runs inside DA.live.\n\n### Content blocks\n\nA content block is a named section of a page that displays layout and marketing content, such as heroes, card rows, columns, headers, or footers. Merchants create them as document tables. EDS converts each table into a `div` with a matching class name. Your repository holds the JavaScript and CSS that renders that `div` on the page. Content blocks do not call Adobe Commerce APIs.\n\n### Commerce blocks\n\nA Commerce block is a named page region for interactive Commerce experiences such as cart, checkout, product detail, sign-in, and account. Merchants create Commerce blocks the same way as content blocks, using a table in a document. The difference is what runs in the browser. The block's JavaScript loads a drop-in component and initializes it with your Commerce endpoint and configuration.\n\n### Commerce boilerplate\n\nThe Commerce boilerplate is a starter template for your storefront repository. It starts from Adobe's  and holds everything your storefront needs to run: block decorators (one JavaScript file per block under `blocks/`), initializer scripts that configure each drop-in (`scripts/initializers/`), styles, and your storefront configuration file. This is the code you own, customize, and push to GitHub.\n\n### Drop-in components\n\nA drop-in component is an npm package (`@dropins/storefront-*`) that ships a ready-made interactive slice of the Commerce UI, such as cart, checkout, sign-in, or product details. In the diagram above, drop-ins sit between Commerce blocks and Adobe Commerce APIs. A Commerce block loads its drop-in first, then that drop-in calls the APIs for live data. You install drop-ins with npm, configure them in `scripts/initializers/`, and extend or style them when the defaults are not enough.\n\n### Adobe Commerce APIs\n\nAdobe Commerce APIs are the endpoints that drop-in components use to read and write live Commerce data like product details, cart contents, orders, account information, and so on. They include GraphQL and REST. Adobe also provides hosted Commerce Services, including Catalog Service, Live Search, and Product Recommendations. These services return catalog data to the storefront faster than the core GraphQL APIs alone.\n\n## Quick reference\n\n\n| Piece | One-line job | Where to find it |\n|---|---|---|\n| Document | Where merchants create and edit pages | Google Docs, SharePoint, DA.live, or  (a visual editor for rendered pages) |\n| Edge Delivery Services | Turns documents into fast HTML pages | Adobe-hosted; see  for how it builds and deploys pages |\n| Content block (Edge Delivery Services blocks used for non-commerce page content and layout, such as cards, columns, headers, and footers.) | Displays text and media layout on a page | `blocks/<name>/<name>.js` in your repo |\n| Commerce block (JavaScript blocks that integrate drop-in components into Edge Delivery Services pages to power storefront commerce experiences.) | Loads a drop-in for interactive Commerce UI | `blocks/<name>/<name>.js` in your repo |\n| Commerce boilerplate (Pre-configured storefront with the components and services you need to get started.) | Starter code for your storefront GitHub repository that connects blocks to drop-ins |  |\n| Drop-in component (NPM packages that provide core Commerce storefront features such as cart, checkout, product details, and account flows.) | Ready-made Commerce UI package | `@dropins/storefront-*` on npm |\n| Adobe Commerce APIs | Endpoints drop-ins call for live Commerce data | Your Commerce backend — Commerce PaaS, Adobe Commerce as a Cloud Service, or Adobe Commerce Optimizer |\n\n\n## Go deeper\n\nRead in order the first time through. Each topic builds on the previous one. After you have run the boilerplate once, you can jump ahead for lookup. If you open [Events](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/events/) on day one with no context, it can feel out of order; the architecture pages above prepare you for that topic."
+    },
+    {
+      "path": "get-started/architecture/blocks-and-repo",
+      "title": "Blocks and the repository",
+      "description": "For new storefront developers—how documents, blocks, your Git repo, and drop-ins fit together, how content blocks differ from Commerce blocks, and which boilerplate folders to open first.",
+      "content": "This page shows where your Git repository sits between merchant-authored documents and shopper cart, checkout, or product flows. It also explains how content blocks differ from Commerce blocks and which boilerplate folders hold the wiring. `blocks/` and `scripts/initializers/` are not sample folders. They are the files you edit when a Commerce region on the page breaks or shows the wrong data.\n\n[How a page loads](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/architecture/how-a-page-loads/) shows the timeline from document to API call.\n\nThis page focuses on ownership: authors work in documents, EDS converts tables into block `div`s, and your repository provides decorators, initializers, styles, and configurations so Commerce blocks load the correct drop-ins.\n\n## Comparing blocks and drop-in components\n\nEach document table becomes a block `div` that EDS and your JavaScript identify. Your repo connects Commerce blocks to drop-ins through decorators, `scripts/initializers/`, styles, and storefront configuration, then pushes to GitHub to drive Edge Delivery builds.\n\nAuthoring references: , [Document Authoring](https://experienceleague.adobe.com/developer/commerce/storefront/merchants/quick-start/document-authoring/) and [Universal Editor](https://experienceleague.adobe.com/developer/commerce/storefront/merchants/quick-start/universal-editor/) Quick Starts, , . For packages and shared vocabulary, see [Drop-ins at a glance](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/architecture/drop-ins-at-a-glance/) and [Boilerplate getting started](https://experienceleague.adobe.com/developer/commerce/storefront/boilerplate/getting-started/).\n\n\n| | Content blocks | Commerce blocks | Drop-in components |\n|---|----------------|-----------------|---------------------|\n| Role | Layout and marketing UI (cards, heroes, columns, headers, footers) | Interactive Commerce experiences (cart, checkout, account, PDP, …) | Packaged UI and logic that Commerce blocks load and initialize |\n| Where it comes from | Block Collection and custom blocks in `blocks/` | Commerce blocks in `blocks/`, mapped in the boilerplate | npm (Node's package manager. You use it to install drop-in packages — for example, `npm install @dropins/storefront-cart` — in your storefront repository.) packages such as `@dropins/storefront-cart` |\n| Authored as document tables | Yes | Yes | No — developers add packages and wire initializers in code |\n| Typical tie to Adobe Commerce | None — no Commerce GraphQL for most blocks | Yes — GraphQL, REST, and services through the boilerplate | Direct — Commerce API calls (GraphQL, REST, services) are built into each package |\n| Learn more |  | [Key files and folders](#key-files-and-folders) · [Blocks reference](https://experienceleague.adobe.com/developer/commerce/storefront/boilerplate/blocks-reference/) | [Drop-ins introduction](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/introduction/) |\n\n\n### Commerce Storefront SDK\n\nDrop-in components are built on shared Commerce Storefront SDK (The Drop-in SDK used to build custom drop-ins and related integration logic.) patterns (initialization, rendering, slots, and extension hooks) so behavior and structure stay consistent across cart, checkout, product discovery, and the rest of the set.\n\n- [Commerce Storefront SDK](https://experienceleague.adobe.com/developer/commerce/storefront/sdk/) — Reference for APIs, design components, and utilities used across drop-in components  \n- [Drop-ins introduction](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/introduction/) — Full map of B2C and B2B drop-in components and how they install into the boilerplate  \n\n### Content blocks and Commerce blocks\n\nBoth kinds are document tables EDS turns into HTML. The split is what runs next. Content blocks are layout and marketing (cards, columns, headers, footers from the ). They contain no drop-ins or Commerce GraphQL. Commerce blocks load interactive cart, checkout, account, PDP, and similar flows via initializers and `@dropins/*` calling Commerce GraphQL and related APIs. Prefer plain JavaScript for Commerce blocks. React can make achieving a top Lighthouse score hard. See [Libraries](https://experienceleague.adobe.com/developer/commerce/storefront/troubleshooting/faq/#libraries) and the boilerplate blocks as patterns.\n\n### Key files and folders\n\nThe  is your project's Git repository. It separates core AEM block delivery from Commerce-specific code (`scripts/commerce.js`, `scripts/initializers/`, and storefront configuration) so both sides stay maintainable independently.\n\nHere is what the top-level layout looks like when you clone the boilerplate.\n\n```\naem-boilerplate-commerce/\n├── blocks/\n│   ├── commerce-cart/\n│   │   ├── commerce-cart.js      # block decorator — loads and mounts the Cart drop-in\n│   │   └── commerce-cart.css\n│   └── commerce-checkout/\n│       ├── commerce-checkout.js  # block decorator — loads and mounts the Checkout drop-in\n│       └── commerce-checkout.css\n├── scripts/\n│   ├── scripts.js                # page orchestration (eager, lazy, delayed phases)\n│   ├── commerce.js               # Commerce-specific loading and configuration\n│   └── initializers/\n│       ├── cart.js               # sets the GraphQL endpoint and labels for the Cart drop-in\n│       └── checkout.js           # sets the GraphQL endpoint and labels for the Checkout drop-in\n├── styles/\n└── config.json                   # storefront configuration (endpoints, locale, and so on)\n```\n\nThe table below explains each key file or folder in detail. For the full  and `blocks/`:\n\n\n| File/Folder | Role |\n|-------------|------|\n| `scripts/scripts.js` | Page load, block decoration, fonts, and orchestration of eager, lazy, and delayed loading phases. Imports from `scripts/aem.js` and `scripts/commerce.js`. Also the extension point for global DOM decorators, third-party plugins (such as experimentation tools), and any code that must run eagerly on page load. |\n| `scripts/commerce.js` | Commerce-specific loading, templates, page type detection, Adobe Client Data Layer (ACDL) initialization, and storefront configuration. ACDL is a JavaScript library that captures shopper behavior for analytics — you will see it again when you read about drop-in coordination and analytics. Centralizes all commerce features and keeps them distinct from core AEM logic. |\n| `scripts/initializers/` | One file per drop-in. Each initializer (A JavaScript module that configures a drop-in when imported, such as setting endpoints, registering dictionaries, and preparing runtime behavior.) sets the GraphQL endpoint, loads UI string translations, and registers the drop-in for rendering. All of that runs at import time, before any block decorates. See [Using drop-ins](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/quick-start/) for the code pattern. |\n| `blocks/` | Commerce and content blocks. See [Content blocks and Commerce blocks](#content-blocks-and-commerce-blocks) above and [Getting started](https://experienceleague.adobe.com/developer/commerce/storefront/boilerplate/getting-started/) for the repo layout. |\n\n\nCustomize and connect: [Blocks reference](https://experienceleague.adobe.com/developer/commerce/storefront/boilerplate/blocks-reference/), [Blocks configuration](https://experienceleague.adobe.com/developer/commerce/storefront/boilerplate/configuration/), [Storefront configuration](https://experienceleague.adobe.com/developer/commerce/storefront/setup/configuration/commerce-configuration/).\n\n## What's next\n\n[Drop-ins at a glance](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/architecture/drop-ins-at-a-glance/) explains packages, browser runtime, and npm install."
+    },
+    {
+      "path": "get-started/architecture/commerce-services-and-backends",
+      "title": "Commerce services and backends",
+      "description": "How Edge Delivery Services, the boilerplate, your Commerce backend, and hosted Commerce services fit together, with links to prerequisites and to Luma Bridge or backend topology when you move over in phases.",
+      "content": "Shoppers get pages from Edge Delivery Services. Drop-ins call Adobe Commerce for cart, checkout, and account. Optional hosted services accelerate catalog reads.\n\nThe diagram shows the full stack. Without that picture, Catalog Service, Live Search, or the Storefront Compatibility package can feel like surprise add-ons. [Backend options](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/) lists them for Commerce PaaS so you can plan installs in the right order.\n\nStart by configuring your Commerce connection in [Commerce configuration](https://experienceleague.adobe.com/developer/commerce/storefront/setup/configuration/commerce-configuration/). Then check [Backend options](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/) to confirm your setup is supported.\n\n## Coming from Luma or a classic Commerce theme?\n\nIf you know Luma or another Adobe Commerce theme, focus on one idea: who builds the page the shopper sees. In the classic model, Commerce builds storefront pages with PHP. In this model, Edge Delivery Services sends HTML and JavaScript, and drop-ins call Adobe Commerce APIs from the shopper's browser. You are not replacing the Commerce Admin, catalog, or order tools. You are choosing a different way to assemble the shopper-facing experience.\n\nIf you still run Luma while you move content and marketing to Edge Delivery, use [Luma Bridge](https://experienceleague.adobe.com/developer/commerce/storefront/setup/discovery/luma-bridge/). It is a PHP module that shares the shopper's cart and sign-in session between Luma and EDS drop-ins so both storefronts stay in sync during the migration. For diagrams that include Luma Bridge and the Adobe Commerce Optimizer Connector, read [Backend topology](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/#backend-topology). Those topics cover phased migration.\n\n## How the pieces connect\n\nCommerce blocks, drop-ins, the boilerplate, your backend, and shared Commerce Services all work together on the page.\n\nThe storefront uses GraphQL (A query language that drop-in components use to request and update data from Adobe Commerce APIs. Catalog Service, Live Search, and the core Commerce API all expose GraphQL endpoints.) for both reads and writes.\n\nCommerce Services include Catalog Service (Adobe's fast, read-only GraphQL API for product data. Drop-ins call it instead of core Commerce GraphQL for product pages, search results, and category listings — up to ten times faster.), Live Search (Adobe's AI-powered search service. It returns results instantly as shoppers type and adjusts rankings and facets based on browsing and click signals in the current session.), Product Recommendations, and core GraphQL on your instance for carts, checkout, accounts, and other flows not covered by the hosted catalog layer.\n\nAll three backend options—Commerce PaaS, Adobe Commerce as a Cloud Service, and Adobe Commerce Optimizer—connect to these services. To compare them, see [Backend options](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/).\n\n<Diagram type=\"mermaid\" code={`\ngraph TB\n    EDS[\"<b>Edge Delivery Services</b>\nHosting & CDN\"]\n    AEMBlocks[\"<b>Content blocks</b>\nCards, columns, headers\"]\n    CommerceBlocks[\"<b>Commerce blocks</b>\nAuthor in DA.live\"]\n    EDS --> AEMBlocks\n    EDS --> CommerceBlocks\n    CommerceBlocks --> B2CGroup[\"<b>B2C Drop-ins</b>\nCart, Checkout, Account, and more\"]\n    CommerceBlocks --> B2BGroup[\"<b>B2B Drop-ins</b>\nCompany, Quote, PO, and more\"]\n    B2CGroup --> Boilerplate[\"<b>Commerce boilerplate</b>\nStorefront configuration + API clients\"]\n    B2BGroup --> Boilerplate\n    Boilerplate --> BackendChoice\n    BackendChoice --> CloudService[\"<b>Adobe Commerce as a Cloud Service</b>\nFully managed\"]\n    BackendChoice --> Optimizer[\"<b>Adobe Commerce Optimizer</b>\nFully managed SaaS\"]\n    BackendChoice --> PaaS[\"<b>Commerce PaaS</b>\nYour Adobe Commerce instance\"]\n    subgraph Services[\"Commerce Services\"]\n        direction TB\n        CS[\"<b>Catalog Service</b>\"]\n        LS[\"<b>Live Search</b>\"]\n        PR[\"<b>Product Recommendations</b>\"]\n        GraphQL[\"<b>Core GraphQL</b>\"]\n    end\n    CloudService -.-> Services\n    Optimizer -.-> Services\n    PaaS -.-> Services\n    style Services fill:#FFF9C4,stroke:#827717,stroke-width:2px\n    classDef storefront fill:#e8f5e9,stroke:#4caf50\n    classDef cloudService fill:#f3e5f5,stroke:#9c27b0\n    classDef optimizer fill:#fff3e0,stroke:#ff9800\n    classDef paas fill:#fce4ec,stroke:#e91e63\n    classDef commerceSvcBlock fill:#EDE7F6,stroke:#7E57C2\n    class EDS,AEMBlocks,CommerceBlocks,Boilerplate storefront\n    class CloudService cloudService\n    class Optimizer optimizer\n    class PaaS paas\n    class CS,LS,PR,GraphQL commerceSvcBlock\n`} caption=\"Commerce blocks load drop-ins through the boilerplate, which connects to your backend — Commerce PaaS, Adobe Commerce as a Cloud Service, or Adobe Commerce Optimizer — and shared Commerce Services. See [Backend options](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/) for prerequisites and differences between backend types.\" />\n\n> **API Mesh (advanced)**\n>\n is an option when your project needs to combine multiple backend sources behind a single GraphQL endpoint. Most new storefronts do not need it. You can add it later if the requirement arises.\n\n\n<a id=\"commerce-services\"></a>\n\n## Commerce Services and integrations\n\nThis section covers the services and packages that connect your storefront to Commerce data, hosted Adobe services, and other Adobe platforms. Most rows below describe calls that go from the storefront into Adobe: drop-in components call hosted services or core GraphQL to get or update Commerce data. Data Connection (An optional Commerce extension that sends storefront and order event data to Adobe Experience Platform for use in personalization, segmentation, and cross-channel campaigns.), later on this page, is different. It sends shopper event data from your storefront out to Adobe Experience Platform.\n\nNot all of these are required for every project. What you need depends on your backend and which drop-ins you use. For a checklist of prerequisites (especially on Commerce PaaS), use [Backend options](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/#prerequisites-by-backend) and [PaaS: required packages and services](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/#paas-required-packages-and-services).\n\n### Services Connector\n\nThe Services Connector links your Commerce instance to the hosted catalog and search services in this section: Catalog Service, Live Search, and Product Recommendations. On Commerce PaaS, you configure that link once in the Commerce Admin using production and sandbox API keys from your Commerce license owner. All three services share the same key pair and data space after you save that configuration.\n\nOn Adobe Commerce as a Cloud Service and Adobe Commerce Optimizer, Adobe sets up the hosted side of those services for you as part of the managed model in [Backend options](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/). You do not repeat the same manual Commerce Services Connector steps that Commerce PaaS administrators use in the Admin. The Experience League topic in the quick reference table below still explains how API keys and data spaces work if you need the full background for PaaS or for troubleshooting.\n\n### Catalog Service\n\nCatalog Service gives your storefront fast, read-only access to product data through a dedicated GraphQL API. Instead of querying your Commerce application each time a shopper opens a product page or browses a category, drop-in components call this API, which Adobe designed specifically for storefront reads. It is built to return catalog reads faster than routing every read through the core Commerce GraphQL API alone. The Product Details drop-in requires Catalog Service, and the Product Discovery drop-in uses it for search results and category pages.\n\n### Live Search\n\nLive Search replaces the default Commerce catalog search with an AI-powered experience. When a shopper types in the search field, Live Search returns results instantly and adjusts facets and ranking based on what shoppers are browsing and clicking in that session. It powers the Product Discovery drop-in, which gives you customizable search and product listing pages with filtering. For storefronts that do not use the classic PHP theme, Live Search needs storefront events so it can learn what shoppers click and view. You need to turn on event collection before the AI models have data to work with. See [Analytics](https://experienceleague.adobe.com/developer/commerce/storefront/setup/analytics/instrumentation/) for details.\n\n### Product Recommendations\n\nProduct Recommendations uses Adobe Sensei, Adobe's AI engine, to show shoppers products they are likely to want. Examples include units like \"Customers who bought this also bought\" and \"Most viewed.\" You configure and place recommendation units in the Commerce Admin, and they can appear on product pages, the cart page, or anywhere else on your site. A storefront can run without Product Recommendations, but Adobe recommends turning it on when you want AI-driven merchandising blocks on the site.\n\nWithout the classic PHP theme, Product Recommendations needs the same storefront event collection as Live Search before models have signal. See [Analytics](https://experienceleague.adobe.com/developer/commerce/storefront/setup/analytics/instrumentation/).\n\n### Core GraphQL\n\nCore GraphQL is the GraphQL API on your Adobe Commerce backend (the address you set in the boilerplate for drop-ins). Cart, checkout, account, orders, and many other reads and writes still go here. Hosted services such as Catalog Service sit beside that API and speed up specific product reads. They do not remove core GraphQL from your architecture.\n\nAdobe Commerce as a Cloud Service can offer one combined GraphQL layer that merges core Commerce fields with the hosted service fields storefronts need. When you run Adobe Commerce yourself, whether on Adobe-managed cloud infrastructure or on your own servers (on-premises), you use the long-standing core and service schemas described in Adobe's web API documentation. For a full overview, see the  on developer.adobe.com.\n\n### Data Connection\n\nData Connection sends shopper behavior and order data from your storefront to the Adobe Experience Platform, where other Adobe tools can use it for personalization and segmentation. For example, Adobe Journey Optimizer (a cross-channel marketing automation tool) can use that data to trigger an abandoned cart email. This service is optional for most storefront builds. You only need it if your project uses Adobe Experience Platform features like real-time audience segmentation or cross-channel personalization. According to the  on Experience League, the Data Connection extension applies to Adobe Commerce on cloud infrastructure and on-premises projects. It does not apply to Adobe Commerce as a Cloud Service (the fully managed SaaS product), where integrations with Experience Platform follow a different model.\n\nThe drawing below shows only this optional path so it does not compete with the main stack diagram above. Data Connection is a Commerce extension on your Adobe Commerce instance. It receives storefront activity from the shopper session (for example, through the Adobe Client Data Layer) and back office events from the Commerce application, then forwards compatible data to Experience Platform. For installation and configuration, see the  on Experience League.\n\n<Diagram type=\"mermaid\" code={`\nflowchart TB\n    Storefront[\"<b>Storefront</b>\nEdge Delivery + browser\"]\n    DC[\"<b>Adobe Commerce</b>\nData Connection extension\"]\n    AEP[\"<b>Adobe Experience Platform</b>\"]\n    Storefront -->|\"Storefront events\"| DC\n    DC -->|\"Forwarded data\"| AEP\n    classDef storefront fill:#e8f5e9,stroke:#4caf50\n    classDef commerce fill:#fff3e0,stroke:#ff9800\n    classDef platform fill:#e3f2fd,stroke:#2196f3\n    class Storefront storefront\n    class DC commerce\n    class AEP platform\n`} caption=\"Optional outbound path for self-managed Adobe Commerce: storefront events reach Commerce, the Data Connection extension adds back office data, then compatible payloads go to Adobe Experience Platform.\" />\n\n### Storefront Compatibility package\n\nThe Storefront Compatibility package extends the Commerce GraphQL schema with the reads and writes that cart, checkout, account, and order drop-ins require. Without it on the Commerce deployment that serves those flows, the drop-ins cannot talk to your backend as they expect. On Adobe Commerce as a Cloud Service and on Adobe Commerce Optimizer, Adobe manages this package for you as part of the fully managed model in [Backend options](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/). On Commerce PaaS (your own Adobe Commerce on cloud infrastructure or on-premises instance), you install it manually on that instance before you finish storefront settings in your GitHub project.\n\n## Quick reference\n\n\n| Service | One-line job | Where to find it |\n|---|---|---|\n| Services Connector | On Commerce PaaS, connects Catalog Service, Live Search, and Product Recommendations using Admin API keys. On Adobe Commerce as a Cloud Service and Adobe Commerce Optimizer, Adobe sets up the hosted side for you (see [Backend options](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/)). |  |\n| Catalog Service | Fast read-only catalog data for product pages, list pages, search, and navigation; required by the Product Details drop-in. |  |\n| Live Search | AI-powered search that powers the Product Discovery drop-in. It needs storefront event collection when you do not use the classic PHP theme. |  |\n| Product Recommendations | Optional (recommended). Adobe Sensei units in the Commerce Admin. It needs storefront event collection when you do not use the classic PHP theme. |  \n  |\n| Core GraphQL | Required. GraphQL API on your Commerce instance for cart, checkout, account, orders, and other flows; hosted catalog services do not replace it. |  |\n| Data Connection | Optional. Sends storefront and order event data to Adobe Experience Platform for personalization. Applies to Adobe Commerce on cloud infrastructure or on-premises, not Adobe Commerce as a Cloud Service. |  |\n| Storefront Compatibility package (A PHP package you install on Commerce PaaS that extends the GraphQL schema so cart, checkout, account, and order drop-ins can communicate with your backend as expected.) | Required on Commerce PaaS (manual install on your Commerce instance). Managed automatically on Adobe Commerce as a Cloud Service and Adobe Commerce Optimizer. | [Install page](https://experienceleague.adobe.com/developer/commerce/storefront/setup/configuration/storefront-compatibility/install/) |\n\n\n> **Adobe Commerce Services on Experience League**\n>\nFor a complete list of merchandising services for your Adobe Commerce storefront, see the  on Experience League. The table above links to the services you will use most often with this storefront.\n\n\n## What's next\n\n[Backend options](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/) explains how to confirm your backend type, required installations, and service connections before configuring your storefront."
+    },
+    {
+      "path": "get-started/architecture/drop-ins-at-a-glance",
+      "title": "Drop-ins at a glance",
+      "description": "A short introduction to drop-in components for new storefront developers—what they are, where they run, how you add them, and where to read next.",
+      "content": "A drop-in is a packaged piece of UI and logic for one Commerce job, such as cart, checkout, or sign-in. It loads Commerce data through APIs, often GraphQL.\n\nTo use a drop-in, you need three things: the npm package, initializer settings in your repo, and a mount point on the page.\n\nFor setup steps, see [Using drop-ins](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/quick-start/).  \nFor a full package map, see [Drop-ins introduction](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/introduction/).\n\n## One drop-in: what you provide and what it does\n\nIn this model, your project provides the npm package, initializer configuration, and DOM mount point. The drop-in then renders the UI and calls Commerce APIs from the browser. For the full path from document to mount, see [How a page loads](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/architecture/how-a-page-loads/).\n\n<small>@dropins/storefront-*</small>\"]\n        cfg[\"Initializer settings\n<small>GraphQL endpoint, language labels</small>\"]\n        dom[\"Mount target\n<small>Commerce block region in the DOM</small>\"]\n    end\n    di[\"Drop-in component\n<small>Packaged UI and logic for one Commerce job (cart, checkout, sign-in, ...)</small>\"]\n    subgraph outcomes[\"At runtime\"]\n        ui[\"Shopper-facing UI\n<small>Interactive areas for that job</small>\"]\n        api[\"Commerce traffic\n<small>GraphQL and related calls from this browser only</small>\"]\n    end\n    npm --> di\n    cfg --> di\n    dom --> di\n    di --> ui\n    di --> api\n    style di fill:#dbeafe,stroke:#1d4ed8,stroke-width:4px\n    style provides fill:#f8fafc,stroke:#64748b,stroke-width:1px\n    style outcomes fill:#fffbeb,stroke:#d97706,stroke-width:1px\n    style npm fill:#f1f5f9,stroke:#475569,stroke-width:2px\n    style cfg fill:#f1f5f9,stroke:#475569,stroke-width:2px\n    style dom fill:#f1f5f9,stroke:#475569,stroke-width:2px\n    style ui fill:#fff7ed,stroke:#ea580c,stroke-width:2px\n    style api fill:#fff7ed,stroke:#ea580c,stroke-width:2px\n`} caption=\"Your project provides three things: the npm package, the initializer settings (GraphQL endpoint and language labels), and a mount point in the DOM. The drop-in component uses all three to render the shopper-facing UI and send Commerce API calls from the browser.\" />\n\n## Where drop-ins run\n\nAfter load, drop-ins run in the browser. EDS delivers HTML, CSS, and JS. Commerce requests go straight from the drop-in to your endpoints, not through EDS in the middle.\n\n> **If data never loads in the cart or checkout**\n>\nIf your Commerce environment is only reachable on a VPN or a strict IP allow list, remember that the shopper's device must be able to reach the same endpoints you configured. A setup that works for your laptop behind VPN may still fail for a shopper on a normal network.\n\n\n## How you add drop-ins to a project\n\nInstall the drop-in via npm (Node's package manager. You use it to install drop-in packages — for example, `npm install @dropins/storefront-cart` — in your storefront repository.) (for example, `@dropins/storefront-cart`). Packages are published on npm. Adobe publishes source for many packages in public repositories under `github.com/adobe-commerce`.\n\nCommerce blocks and `scripts/initializers/` load each drop-in using your configured endpoint and labels.\n\nFor setup steps, see [Using drop-ins](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/quick-start/).  \nFor a reference implementation, see the .  \nTo go deeper, see [Extending drop-ins](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/extending/).\n\n## How much can you customize?\n\nMore than you might expect. Each drop-in exposes several customization layers so you can change behavior without editing the package source.\n\n- CSS variables and stylesheet overrides control colors, spacing, typography, and layout.\n- Label overrides change UI text (button labels, errors, placeholders) without opening the package code.\n- Slots add custom content (for example, a banner or promo message) in named regions of the drop-in layout.\n- Extension hooks replace logic for specific actions, such as what runs when a shopper clicks `Add to cart`.\n\nMost projects stop at CSS and labels. Slots and hooks are there when configuration alone is not enough. See [Extending drop-ins](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/extending/) for patterns and examples.\n\n## B2C, B2B, and the package list\n\nB2C means business-to-consumer (a typical shopper storefront). B2B means business-to-business (accounts, quotes, purchase orders, and similar flows).\n\nThe [Drop-ins introduction](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/introduction/) lists B2C and shared packages. If you build B2B experiences, you will use extra packages and pages under [Drop-ins B2B](https://experienceleague.adobe.com/developer/commerce/storefront/dropins-b2b/) (company, quotes, purchase orders, requisition lists, and related topics).\n\nThese names show the pattern for consumer-facing drop-ins. Treat the per-drop-in install pages as the source of truth if a name or version changes. B2B installs are covered in [Drop-ins B2B](https://experienceleague.adobe.com/developer/commerce/storefront/dropins-b2b/).\n\n- `@dropins/storefront-account`\n- `@dropins/storefront-auth`\n- `@dropins/storefront-cart`\n- `@dropins/storefront-checkout`\n- `@dropins/storefront-order`\n- `@dropins/storefront-payment-services`\n- `@dropins/storefront-pdp`\n- `@dropins/storefront-recommendations`\n- `@dropins/storefront-wishlist`\n- `@dropins/storefront-personalization`\n- `@dropins/storefront-product-discovery`\n\n## What's next\n\n[How drop-ins coordinate on a page](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/architecture/drop-ins-on-a-page/) explains how multiple drop-ins work together using a shared event bus."
+    },
+    {
+      "path": "get-started/architecture/drop-ins-on-a-page",
+      "title": "How drop-ins coordinate on a page",
+      "description": "How multiple drop-in components on the same storefront page communicate through the shared event bus—and how that differs from analytics instrumentation.",
+      "content": "Multiple drop-ins on one page (for example, Cart and Auth) share a single event bus (A shared in-memory channel that lets drop-in components on the same page publish and subscribe to events without depending directly on each other.) (`@dropins/tools/event-bus.js`). They publish and listen for small messages so each package can react without importing the others directly. Read this page before you rely on [Events](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/events/) alone. Otherwise it is easy to mix up in-page bus messages with analytics data or calls to Commerce services.\n\n> **Same tab and document**\n>\nThe bus is an in-memory channel for one loaded HTML document in one tab. Code that imports `@dropins/tools/event-bus.js` in that same JavaScript context can emit and listen together. A full navigation to another URL, a new tab, or a separate cross-origin iframe loads a different context, so those environments do not share the same bus instance unless you build an explicit bridge (not part of the default Commerce boilerplate pattern).\n\nIf you wondered how cart and checkout work when they are different pages: the next document does not inherit the previous page's bus. Commerce keeps the cart on the server, and storefront bootstrap code loads the cart again on the new page so events such as `cart/initialized` occur in that new context. The full walk-through, with Commerce boilerplate file links, is in [Multiple storefront routes](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/events/) on the [Events](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/events/) page. Patterns such as `getCartDataFromCache` are in [Using drop-ins](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/quick-start/). API details are in the [Event Bus API reference](https://experienceleague.adobe.com/developer/commerce/storefront/sdk/reference/events/).\n\n\nEach colored box is a drop-in package on the same page. Solid arrows show events emitted to the bus; dashed arrows show events consumed from the bus. Pink is your custom code alongside those drop-ins.\n\n<Diagram type=\"mermaid\" code={`\n%%{init: {'theme':'base', 'themeVariables': { 'edgeLabelBackground':'#ffffff'}, 'flowchart': {'nodeSpacing': 72, 'rankSpacing': 96, 'curve': 'basis'}}}%%\nflowchart LR\n    subgraph side [Other emitters]\n        direction TB\n        Auth[Auth drop-in]\n        Order[Order drop-in]\n        YourCode[Your code]\n    end\n    subgraph core [Cart, bus, checkout]\n        direction LR\n        Cart[Cart drop-in]\n        EB[Event Bus]\n        Checkout[Checkout drop-in]\n    end\n\n    Auth -->|\"authenticated\"| EB\n    Order -->|\"order/placed, cart/reset\"| EB\n    YourCode -->|\"locale, authenticated\"| EB\n    Cart -->|\"cart/updated, cart/data\"| EB\n    Checkout -->|\"checkout/updated\"| EB\n\n    EB -.->|\"authenticated\"| Cart\n    EB -.->|\"order/placed\"| Cart\n    EB -.->|\"authenticated\"| Checkout\n    EB -.->|\"cart/updated, cart/data\"| Checkout\n    EB -.->|\"cart/initialized\"| Checkout\n\n    linkStyle 0,1,2,3,4 stroke:#3b82f6,stroke-width:2px\n    linkStyle 5,6,7,8,9 stroke:#6366f1,stroke-width:1.5px,stroke-dasharray:5\n\n    style EB fill:#fef3c7,stroke:#f59e0b,stroke-width:3px\n    style Auth fill:#f3e8ff,stroke:#a855f7,stroke-width:2px\n    style Cart fill:#dbeafe,stroke:#3b82f6,stroke-width:2px\n    style Checkout fill:#e0e7ff,stroke:#6366f1,stroke-width:2px\n    style Order fill:#e0e7ff,stroke:#6366f1,stroke-width:2px\n    style YourCode fill:#fce7f3,stroke:#ec4899,stroke-width:2px\n    style side fill:#fafafa,stroke:#cbd5e1,stroke-width:1px,stroke-dasharray:4\n    style core fill:#f8fafc,stroke:#94a3b8,stroke-width:1px,stroke-dasharray:4\n`} caption=\"Solid arrows: events emitted. Dashed arrows: events consumed. Your storefront code can emit and listen alongside drop-ins.\" />\n\n- `events.on(name, handler, options)` — subscribe. Returns a subscription handle.\n- `events.emit(name, payload)` — publish an event\n- `subscription.off()` — unsubscribe (call on the handle returned from `events.on`)\n\nEach drop-in component documents which events it emits and listens to. See the [event bus API reference](https://experienceleague.adobe.com/developer/commerce/storefront/sdk/reference/events/) and the [drop-in events overview](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/events/) for details.\n\n> **Events vs. analytics**\n>\nThe event bus handles internal communication between drop-in components on the page. It is separate from behavioral data for Adobe Commerce Services (Live Search, Product Recommendations) sent through the Adobe Client Data Layer (a JavaScript library that captures shopper behavior from the storefront for analytics). See [Analytics](https://experienceleague.adobe.com/developer/commerce/storefront/setup/analytics/instrumentation/).\n\n\n## What's next\n\n[Commerce services and backends](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/architecture/commerce-services-and-backends/) explains Edge Delivery, the boilerplate, backends, hosted catalog and search services, and prerequisites."
+    },
+    {
+      "path": "get-started/architecture/how-a-page-loads",
+      "title": "How a page loads",
+      "description": "The sequence from authoring a document to a Commerce API call when a shopper opens a page on Edge Delivery Services.",
+      "content": "The diagram shows six stages from a merchant-authored document to a Commerce API call in the browser. The steps below follow the same order. Use them to decide whether a preview problem comes from authoring, HTML delivery, your block code, or Commerce endpoints instead of assuming every empty UI is only a GraphQL issue.\n\n<small>Creates document</small>\"]\n    B[\"Edge Delivery Services\n<small>Publishes page</small>\"]\n    C[\"Browser\n<small>Loads HTML</small>\"]\n    D[\"Block decorator\n<small>initializer (top level) · decorate(block) · mount UI</small>\"]\n    E[\"Drop-in\n<small>Renders UI</small>\"]\n    F[\"Commerce API\n<small>Data</small>\"]\n    A -->|\"Document\"| B\n    B -->|\"HTML with divs\"| C\n    C -->|\"Decorates blocks\"| D\n    D -->|\"Renders\"| E\n    E -->|\"Fetch\"| F\n    F -->|\"Response\"| E\n    style A fill:#E3F2FD,stroke:#2196F3,stroke-width:2px\n    style B fill:#F3E5F5,stroke:#9C27B0,stroke-width:2px\n    style C fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px\n    style D fill:#E8F5E9,stroke:#4CAF50,stroke-width:2px\n    style E fill:#FFE0B2,stroke:#FF9800,stroke-width:2px\n    style F fill:#FFCDD2,stroke:#F44336,stroke-width:2px\n`} caption=\"Six stages from document to data: the author creates a document, Edge Delivery Services publishes it as HTML, the browser loads the page, the block decorator runs your repository code, the drop-in mounts its UI, and the drop-in fetches live Commerce data.\" />\n\n\n1. The merchant creates a document in DA.live, Google Docs, or SharePoint. In document-based authoring, a table in the document defines a block on the page — for example, a \"Commerce Cart\" table becomes the cart block. In the Universal Editor, the merchant edits blocks visually on the rendered page and no document tables are involved.\n\n1. Edge Delivery Services converts the document into an HTML page. Each table becomes a `div` with a class name that matches the block, for example, ``. EDS serves this HTML from servers close to the shopper, which is what makes pages load fast.\n\n1. The shopper's browser requests and loads that HTML.\n\n1. The block decorator (The JavaScript module that runs for a block after the page loads. It imports the initializer, then calls provider.render() to mount the drop-in UI into the block region of the page.) runs for each block on the page. A block decorator is the JavaScript file in your repository for that block, for example, `blocks/commerce-cart/commerce-cart.js`. Edge Delivery Services finds each block's `div` in the HTML, loads the matching file from your repository, and runs its default export. That file imports the drop-in's initializer (A JavaScript module that configures a drop-in when imported, such as setting endpoints, registering dictionaries, and preparing runtime behavior.) at the top level of the file, outside `decorate(block)`, so the Commerce API endpoint and translated labels are configured before `decorate(block)` runs. Inside `decorate(block)`, your code mounts the shopper-facing UI, such as `provider.render()` to render the cart block UI.\n\n1. The drop-in component renders the shopper-facing UI — the cart, checkout form, product detail page, or whichever Commerce experience that block delivers.\n\n1. The drop-in sends requests to your Commerce API endpoints and renders the data it gets back. For example, the Cart drop-in calls Commerce GraphQL to load the shopper's cart items and totals. This call goes from the shopper's browser directly to Commerce. Edge Delivery Services is not in the middle of it.\n\n\n## What's next\n\n[Blocks and the repository](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/architecture/blocks-and-repo/) compares content and Commerce blocks and points at the repo folders that wire them to drop-ins."
+    },
+    {
+      "path": "get-started/backends",
+      "title": "Backend options",
+      "description": "Identify your Adobe Commerce backend type (PaaS, Adobe Commerce as a Cloud Service, or Adobe Commerce Optimizer) and confirm prerequisites before storefront setup.",
+      "content": "The storefront supports three backend types. Each type has its own prerequisites, so follow only the path that matches your project. Choosing the wrong type can lead to misleading signals—GitHub and DA.live may look healthy while previews or drop-ins fail—and may result in installing packages your license does not require.\n\nFor authoring storefront pages (Document Authoring, Universal Editor), see [Document Authoring Quick Start](https://experienceleague.adobe.com/developer/commerce/storefront/merchants/quick-start/document-authoring/). This page covers the Commerce backend the storefront connects to.\n\nDrop-in components — B2C (business-to-consumer, meaning typical shopper experiences) and B2B (business-to-business, including company accounts, negotiable quotes, and purchase orders) — require an Adobe Commerce as a Cloud Service or Adobe Commerce Optimizer license. PaaS customers who add an Adobe Commerce Optimizer license are covered, and that license includes drop-in usage. There is no separate “B2B backend” type.\r\n\nBackends fall into three categories:\n\n- Commerce PaaS — Existing Adobe Commerce on Cloud infrastructure or on-premises deployment without an Adobe Commerce as a Cloud Service or Adobe Commerce Optimizer license\n- Adobe Commerce as a Cloud Service — Cloud Service deployment whose license includes Storefront\n- Adobe Commerce Optimizer — New Adobe Commerce Optimizer deployment, or an existing PaaS deployment that added Adobe Commerce Optimizer\n\n> **Related documentation**\n>\nThis page covers Commerce backends only. For Adobe Commerce product help (Admin, deployments, merchandising services, integrations), start from  on Experience League.\n\nFor pages and blocks on da.live, see  or [Document Authoring Quick Start](https://experienceleague.adobe.com/developer/commerce/storefront/merchants/quick-start/document-authoring/).\n\n\n## Which backend do you have?\n\n\n| Feature | Commerce PaaS | Adobe Commerce as a Cloud Service | Adobe Commerce Optimizer |\n|---------|---------------|-----------------------------------|--------------------------|\n| License includes Storefront | No | Yes | Yes |\n| Setup | Manual install required | Fully automated | Fully automated |\n| Version | v2.4.7+ (self-managed Commerce) | Commerce managed by Adobe (SaaS) | Optimizer managed by Adobe (SaaS) |\n\n\n{/* TODO: Update Link href when ACO Connector (PaaS-to-ACO) documentation is published. */}\n\n> **PaaS + Adobe Commerce Optimizer Connector**\n>\nThe Adobe Commerce Optimizer Connector (PaaS-to-Adobe Commerce Optimizer) syncs your PaaS catalog and pricing into Adobe Commerce Optimizer. You install a PHP extension on the PaaS platform and configure the Adobe Commerce Optimizer UI. See the  for connector setup.\n\n\n## Backend topology\n\nThis diagram focuses on the backend layer. It adds two optional pieces you might use during a phased move: Luma Bridge (A PHP module on your Commerce instance that reads session cookies from EDS drop-ins, letting Luma pages share the same shopper cart and sign-in session during a phased migration to Edge Delivery Services.) and the Adobe Commerce Optimizer Connector. Luma is Adobe's classic server-side Commerce storefront theme. If you run a Luma (Adobe Commerce's classic server-side storefront theme, built with PHP. If you run a Luma storefront today, Luma Bridge can help share cart and sign-in sessions with EDS drop-ins while you migrate.) storefront today and are moving to Edge Delivery Services, Luma Bridge is a PHP module on Commerce that enables Luma pages and EDS drop-ins to share the same cart and sign-in session during the transition. For the full stack (drop-ins, boilerplate, and how services connect), see [Commerce services and backends](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/architecture/commerce-services-and-backends/).\r\n\n<Diagram type=\"mermaid\" code={`\ngraph TB\n    subgraph Storefronts[\"Storefronts\"]\n        EDS[\"<b>Edge Delivery Services</b>\nDrop-ins, boilerplate\"]\n        Luma[\"<b>Luma / PHP</b>\nCart, checkout, account\nPaaS only\"]\n    end\n    subgraph Bridge[\"Session bridge (optional)\"]\n        LB[\"<b>Luma Bridge</b>\nPHP on Commerce · session only\nSame domain\"]\n    end\n    subgraph Backends[\"Backends\"]\n        PaaS[\"<b>Commerce PaaS</b>\nCatalog, pricing, orders\"]\n        ACCS[\"<b>Adobe Commerce as a Cloud Service</b>\nFully managed, license includes Storefront\"]\n        ACO[\"<b>Adobe Commerce Optimizer</b>\nCatalog Service, merchandising\"]\n    end\n    Connector[\"<b>ACO Connector</b>\nPaaS-to-ACO sync\nCatalog, pricing\"]\n    EDS -->|\"session cookies\"| LB\n    LB <--> Luma\n    EDS --> PaaS\n    EDS --> ACCS\n    EDS --> ACO\n    Luma --> PaaS\n    PaaS -->|\"Manual install\"| Connector\n    Connector --> ACO\n    classDef storefront fill:#e8f5e9,stroke:#4caf50\n    classDef bridge fill:#fff3e0,stroke:#ff9800\n    classDef backend fill:#e3f2fd,stroke:#2196f3\n    classDef connector fill:#f3e5f5,stroke:#9c27b0\n    class EDS,Luma storefront\n    class LB bridge\n    class PaaS,ACCS,ACO backend\n    class Connector connector\n`} caption=\"EDS connects to PaaS, Adobe Commerce as a Cloud Service, or Adobe Commerce Optimizer. EDS drop-in components set session cookies that Luma Bridge (a PHP module on PaaS) reads to share sessions with Luma — independent of Adobe Commerce Optimizer. The Adobe Commerce Optimizer Connector syncs PaaS catalog and pricing into Adobe Commerce Optimizer.\" />\n\n## Prerequisites by backend\n\nOpen only the tab for your backend and read it end to end. Commerce PaaS includes a manual checklist that the two managed backends do not.\n\n<Options label=\"Backend\" numbered=>\n<Option>\n\n### Commerce Platform-as-a-Service (PaaS)\n\n#### Product license\n\nAdobe Commerce on cloud infrastructure or on-premises. The Magento Open Source edition (Adobe's open-source e-commerce platform, which is a separate product from Adobe Commerce) is not supported. A PaaS license alone does not include drop-in components. To use drop-ins on PaaS, you must also hold an Adobe Commerce Optimizer license (see [Adobe Commerce Optimizer](#adobe-commerce-optimizer)).\n\n#### Version\n\nv2.4.7 or later\n\n#### Required packages and services\n\nManual installation is required. See [PaaS: required packages and services](#paas-required-packages-and-services) below for step-by-step instructions.\n\n> **Luma Bridge and Adobe Commerce Optimizer**\n>\nLuma Bridge is a PHP module on Commerce (PaaS). It reads session cookies that EDS drop-ins set, so Luma pages can share cart and sign-in state with EDS. It does not connect directly inside drop-in code. It works with or without Adobe Commerce Optimizer. If you use the Adobe Commerce Optimizer Connector, Luma Bridge can still share sessions while you migrate. See [Luma Bridge](https://experienceleague.adobe.com/developer/commerce/storefront/setup/discovery/luma-bridge/).\n\n\n</Option>\n\n<Option>\n\n### Adobe Commerce as a Cloud Service\n\n#### Product license\n\nAdobe Commerce as a Cloud Service (license includes Storefront)\n\n#### Requirements\n\nAdobe manages all requirements automatically. No manual installation is required.\n\n</Option>\n\n<Option>\n\n### Adobe Commerce Optimizer\n\n#### Product license\n\nAdobe Commerce Optimizer (license includes Storefront)\n\n#### Requirements\n\nAdobe manages all requirements in a fully managed SaaS model. No manual installation is required.\n\n> **Adobe Commerce Optimizer + PaaS**\n>\nIf you are on Commerce PaaS with an existing Luma storefront and add Adobe Commerce Optimizer, you can use [Luma Bridge](https://experienceleague.adobe.com/developer/commerce/storefront/setup/discovery/luma-bridge/) to share sessions between EDS and Luma's cart, checkout, and account pages while content and marketing move to Edge Delivery first.\n\n\n</Option>\n\n</Options>\n\n## PaaS: required packages and services\n\nInstall and configure the following on Commerce PaaS before you create your storefront. Adobe Commerce as a Cloud Service and Adobe Commerce Optimizer manage these automatically. Skip this section if you are not on Commerce PaaS.\n\n### Minimum checklist before you create a storefront\n\nBefore Site Creator (App in Document Author (DA.live) that creates and initializes a storefront by setting up content, optional code, theme choice, and storefront configuration values.), manual configuration, or local preview can rely on Commerce APIs, confirm these items on Commerce PaaS:\n\n1. You are on Adobe Commerce v2.4.7 or later (Magento Open Source is not supported for this storefront path).\n1. You installed the Storefront Compatibility package (A PHP package you install on Commerce PaaS that extends the GraphQL schema so cart, checkout, account, and order drop-ins can communicate with your backend as expected.) ([Install page](https://experienceleague.adobe.com/developer/commerce/storefront/setup/configuration/storefront-compatibility/install/)), which fills gaps in the core Commerce GraphQL schema that drop-ins require.\n1. You connected the storefront services your project needs (at minimum, plan for Services Connector and Catalog Service, then add Live Search, Product Recommendations, and Data Connection per your rollout). Use the [service documentation table](#storefront-services) below for links.\n\n### Storefront Compatibility package\n\nThe Storefront Compatibility package installs on Adobe Commerce with Composer. Your storefront repo still uses npm for JavaScript drop-ins, but these modules run as PHP on the Commerce server. Use [Install the Storefront Compatibility package](https://experienceleague.adobe.com/developer/commerce/storefront/setup/configuration/storefront-compatibility/install/) to pick the branch that matches Adobe Commerce 2.4.7 or 2.4.8, and read [Commerce services](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/architecture/commerce-services-and-backends/#commerce-services) for how Commerce services fit together.\n\n### Storefront services\n\nCatalog Service, Services Connector, Live Search, and Product Recommendations are covered on Experience League and in [Commerce services](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/architecture/commerce-services-and-backends/#commerce-services). Data Connection is optional and separate (Adobe Experience Platform).\n\nHeadless storefronts must send the required  for Live Search and Product Recommendations. Use the Experience League topics in the table for setup and headless data requirements. On Edge Delivery Services, implement storefront events with the Adobe Client Data Layer and .\n\n\n| Service | Documentation |\n|---------|---------------|\n| Data Connection |  |\n| Services Connector |  |\n| Catalog Service |  |\n| Live Search | ;  |\n| Product Recommendations | ;  ·  |\n\n\n> **Multiple stores in one Commerce environment**\n>\nIf you are migrating only one store to Edge Delivery Services in a shared Commerce environment, contact Adobe Commerce Support to ensure that Live Search stays active without disabling Elasticsearch for your other stores.\n\n\n## Next steps\n\nAfter confirming your prerequisites, create your storefront and connect it to Commerce."
+    },
+    {
+      "path": "get-started/before-you-start",
+      "title": "Before you start",
+      "description": "Accounts, Commerce access, GitHub, DA.live, local tooling, the config generator in DA.live, external documentation hubs, and where to continue inside this collection before Site Creator or the manual boilerplate path.",
+      "content": "By the end of this page, you will know what to have ready before you create a storefront, whether you use Site Creator (App in Document Author (DA.live) that creates and initializes a storefront by setting up content, optional code, theme choice, and storefront configuration values.) or the manual GitHub path. If anything here is unfamiliar, follow the link in the table before continuing.\n\nThis page assumes you are comfortable with JavaScript, HTML, CSS, and basic npm workflows. You do not need to know Adobe Commerce, PHP, or React to get started.\n\n## What you need\n\nThese tools help you build and deploy a storefront on Edge Delivery Services (Adobe's hosting and delivery infrastructure that turns authored documents into fast HTML pages served from servers close to the shopper. You push code to GitHub; Edge Delivery Services builds and publishes automatically.) (EDS). EDS is Adobe's hosting and delivery layer: it turns authored documents into fast HTML pages. You will need Adobe accounts, common developer tools, and access to your Commerce environment.\n\n\n| What | Why you need it | How to get it |\n|------|-----------------|---------------|\n| Adobe ID | Document Author (DA.live) and other Adobe experiences in this workflow expect you to sign in with an Adobe ID. | Open , then use the account menu in the header to sign in or create an Adobe ID. |\n| GitHub account | Site Creator creates or links a GitHub repository for your storefront code. |  (personal or enterprise). |\n| Document Author (DA.live) access | Site Creator runs inside DA.live and stores your starter content there. |  and sign in with the Adobe ID from the first row. For workspace and authoring concepts, see . If your organization uses enterprise access, ask your admin for an invitation. |\n| Adobe Commerce backend | Every drop-in component (NPM packages that provide core Commerce storefront features such as cart, checkout, product details, and account flows.) — a ready-made Commerce UI package for cart, checkout, account, or product pages — connects to an Adobe Commerce backend. You need to know which backend type you have before you can configure the storefront. | See [Backend options](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/) to pick Commerce PaaS, Adobe Commerce as a Cloud Service, or Adobe Commerce Optimizer. |\n| Commerce Admin access and API values | Site Creator can read from your Commerce APIs when they are reachable. After the repo exists, [Storefront configuration](https://experienceleague.adobe.com/developer/commerce/storefront/setup/configuration/commerce-configuration/) asks for base URLs, GraphQL endpoints (Commerce's query language for reading and writing data), and credentials for a headless storefront (the storefront UI runs in the shopper's browser, not on the Commerce server). The exact fields depend on your backend. | Work with your Commerce administrator or solution partner to gather values before you paste them into tools. [Backend options](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/) lists services and limits per platform. When you have API access and a repository, the  in DA.live can build a starter storefront configuration from your inputs. Use [Storefront configuration](https://experienceleague.adobe.com/developer/commerce/storefront/setup/configuration/commerce-configuration/) to learn what each field means. |\n| Node.js | You need Node.js before you run the Commerce boilerplate locally (`npm install`, `npm start`, and drop-in updates). Adobe lists which Node.js release to install in the Prerequisites section of . Adobe updates that Prerequisites line when the recommendation changes. The Commerce boilerplate on GitHub does not declare a Node version in `package.json` (there is no `engines` field), so match whatever Prerequisites shows when you read it. | Open Prerequisites on , install the Node.js release listed there from , then run `node -v` to confirm. |\n| npm | The Commerce boilerplate on GitHub uses npm (Node's package manager. You use it to install drop-in packages — for example, `npm install @dropins/storefront-cart` — in your storefront repository.) (Node's package manager) for installs and scripts (`npm install`, `npm start`, `npm run postinstall`). npm ships with Node.js. | Run `npm -v` in a terminal after you install Node.js. |\n| AEM CLI | The boilerplate `start` script runs `aem up`, so local preview uses the AEM command line client. AEM (Adobe Experience Manager) is the platform underlying Edge Delivery Services. Experience League lists the CLI with Node in the storefront prerequisites for . | After Node.js and npm are installed, run `npm install -g @adobe/aem-cli`. See . Run `aem --version` to confirm. |\n| Git | Cloning and pushing to your repository requires Git. | , or run `git --version` to check if it is already installed. |\n\n\n## Extra steps for some teams\n\nThe table above is the common baseline. The sections below only matter when that situation applies to you. If you are not yet sure which backend type you have, read [Backend options](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/) after the Architecture section — it explains the three types (Commerce PaaS, Adobe Commerce as a Cloud Service, and Adobe Commerce Optimizer) and what each one requires.\n\nIf your backend is Adobe Commerce as a Cloud Service or Adobe Commerce Optimizer, you can skip the Commerce PaaS section below. Adobe manages most storefront service requirements for those backends.\n\n### Commerce PaaS backends\n\nIf your backend is Commerce PaaS, you can still use Site Creator or the manual GitHub path to create the repository and starter content in Document Author. Those paths are not reserved for other backend types. The difference is your Commerce instance.\n\nOn Commerce PaaS, finish the [PaaS: required packages and services](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/#paas-required-packages-and-services) checklist so storefront APIs and drop-ins match what the boilerplate expects. That checklist includes the Storefront Compatibility package, Services Connector, Catalog Service, and any other storefront services your rollout needs (for example, Live Search, Product Recommendations, or Data Connection). [Commerce services and backends](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/architecture/commerce-services-and-backends/) explains what each service does.\n\nUntil that Commerce-side work is done, steps that read live data (previewing a product page or running the boilerplate locally) can fail or look incomplete. Install and configure the required pieces on Commerce first, or drop-ins will not work. Adobe Commerce as a Cloud Service and Adobe Commerce Optimizer handle these requirements for you.\n\nUsing drop-in components requires a license that covers drop-ins: Adobe Commerce as a Cloud Service, Adobe Commerce Optimizer, or Commerce PaaS with Adobe Commerce Optimizer added. Read [Licensing requirements](https://experienceleague.adobe.com/developer/commerce/storefront/licensing/) for who can use drop-ins and how access works. If your backend type is Commerce PaaS as defined on [Backend options](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/), confirm your situation against both topics before you invest in drop-in work.\n\n### Site Creator, manual GitHub setup, and enterprise policies\n\nSite Creator walks you through the repository and starter content in the browser. If you skip it and start from the  on GitHub, install the  on that repository. Code Sync redeploys your storefront when you push to `main` and connects Edge Delivery Services to your repo. Follow [Step-by-step setup](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/create-storefront/#step-by-step) for the full GitHub and Code Sync sequence.\n\nSome organizations block repository creation or GitHub App installs until an administrator approves them. If you use the manual path, plan time for that approval, or use Site Creator when your organization allows it.\n\n### Sidekick browser extension\n\nSidekick (Browser extension that helps creators edit, preview, and publish content from a content folder, and helps developers open source documents from published pages.) is the browser extension authors use to preview, publish, and open source documents from a storefront page. You do not need it before you create your first site — Site Creator sets up Sidekick project wiring automatically. Authors install the extension from the Chrome Web Store when they are ready to use the toolbar. For setup details and the Edge browser path, see  on AEM Docs. For a walkthrough that fits this page, see the optional Sidekick step in [Create a storefront](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/create-storefront/#optional-use-sidekick-for-content-editing).\n\n## What you do not need right now\n\nThe table above lists Node.js, npm, and the AEM CLI because you will need them once you clone the repository and run the boilerplate locally. You do not need them yet. You do not need a code editor, a cloned repository, or a local server to create a storefront. Site Creator and DA.live run entirely in the browser. Install and use those tools when you clone the repository and run the boilerplate on your machine. Follow [Create a storefront](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/create-storefront/) for the full sequence (including the  for local preview). Then use [Run it locally](https://experienceleague.adobe.com/developer/commerce/storefront/boilerplate/getting-started/) for day-to-day commands after your site exists.\n\n## Documentation hubs\n\nThese links open related documentation sites outside this storefront collection. You do not read them end to end before you start. Open them when a step names Edge Delivery, Document Authoring, or the Commerce Admin and you want the official reference next to this page.\n\n- Edge Delivery Services (blocks, CDN, redirects, authoring concepts): .\n- Document Authoring (DA.live workspace, tools, admin API): .\n- Adobe Commerce merchant documentation (Admin configuration, catalog, B2B, upgrades): .\n- Adobe Commerce developer documentation (APIs, App Builder, extensibility hub): .\n\n## What's next\n\nWhen every row in the table above is confirmed, you are ready to move on. You should be able to sign in with your Adobe ID, verify your Node.js version, and know which Commerce backend your project uses.\n\n1. [Storefront Architecture](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/architecture/) — learn about pages, blocks, drop-ins, events, and services before you lock backend work or create a site.\n1. [Backend options](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/) — confirm backend type and prerequisites.\n1. [Create a storefront](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/create-storefront/) — use Site Creator in DA.live to create your repository and starter content."
+    },
+    {
+      "path": "get-started/browser-compatibility",
+      "title": "Browser compatibility",
+      "description": "Learn about the supported browsers and devices for Adobe Commerce Storefronts on Edge Delivery Services.",
+      "content": "Supported browsers depend on your boilerplate suite. Open `package.json` and find the `@dropins/tools` line, then match it to a row below before you spend time on layout testing. That way you do not report a storefront bug for a browser this suite never supported.\n\n## Which boilerplate suite do I have?\n\nMatch `@dropins/tools` in `package.json` to the corresponding suite below.\n\n- March 2026 suite: `@dropins/tools@~1.8.0`\n- February 2026 suite: `@dropins/tools@~1.7.0`\n- January 2026 suite: `@dropins/tools@~1.6.0`\n- October 2025 suite: `@dropins/tools@~1.5.0`\n- August 2025 suite: `@dropins/tools@~1.4.0`\n- June 2025 suite: `@dropins/tools@1.3.0`\n- April 2025 suite: `@dropins/tools@0.42.0`\n- December 2024 suite: `@dropins/tools@0.38.0`\n\n## Browser support by suite\n\n### Desktop browsers\n\n\n| Browser | `@dropins/tools` ~1.5.0 and later (October 2025-March 2026 suites) | `@dropins/tools` ~1.4.0 and earlier (August 2025 suite and older) |\n|---------|-------------------------------------------------------------------|---------------------------------------------------------------------|\n| Chrome  | 105 - 141         | 98 - 136                  |\n| Edge    | 105 - 141         | 98 - 136                  |\n| Safari  | 16 - 18.4         | 16 - 18.4                 |\n| Firefox | 110 - 143         | 108 - 138                 |\n| Opera   | 92 - 122          | 85 - 118                  |\n\n\n### Mobile browsers\n\n\n| Platform | Browser          | `@dropins/tools` ~1.5.0+ (Oct 2025-Mar 2026) | `@dropins/tools` ~1.4.0 and earlier |\n|----------|------------------|---------------------------------------------|-------------------------------------|\n| Android  | Chrome           | 141               | 136                       |\n| Android  | Edge             | 141               | 136                       |\n| Android  | Firefox          | 143               | 138                       |\n| Android  | Samsung Internet | 28                | 26                        |\n| Android  | UC Browser       | Not Supported     | Not Supported             |\n| iOS 16+  | Safari           | Default supported version | Default supported version |\n| iOS 16+  | Chrome           | Default supported version | Default supported version |\n\n\n## Known issues\n\nFor the following browsers, the product listing page loads in a single product column and does not support responsiveness:\n\n- Chrome: 100 - 104\n- Firefox: 108 and 109\n- Opera: 91 or less\n\n## Test URL\n\nYou can test browser compatibility using the Commerce boilerplate test site: \n\n## Browser testing recommendations\n\nWhen you test your storefront, try the following:\n\n- Run checks on the oldest supported version of each major browser you care about.\n- Run checks on the newest version of each major browser.\n- Test on real phones and tablets as well as desktop.\n- Resize the window and confirm layouts still make sense at common widths.\n- On product listing pages, confirm multi-column grids render as you expect."
+    },
+    {
+      "path": "get-started/build-with-ai",
+      "title": "Documentation bundles for AI tools",
+      "description": "Published llms.txt and topic bundles give AI editors and agents current Adobe Commerce Storefront documentation to read alongside prompts.",
+      "content": "If you use Cursor, GitHub Copilot, Claude Code, or similar assistants while you learn or change Adobe Commerce Storefront code, this page shows how to load this site's documentation into your editor or agent so that answers follow the same topics as the browser. This page supports learning and building while you read the documentation, not instead of it.\n\nGeneral-purpose AI models often miss the newest storefront APIs, drop-in versions, and Edge Delivery Services-specific guidance, because they learn from older training data rather than the latest published pages. For that reason, this documentation site generates plain-text bundles at build time so editors and agents can load the same storefront topics the browser shows.\n\n## Context files\n\nStart with `llms.txt`. It is the index that lists where to find every bundle. Full exports load the whole documentation set into one file. Files under `_llms-txt/` cover one topic area each, in smaller files for tools that should not pull the entire site. The table lists each filename and a one-line description of what it contains.\n\n\n| File | Purpose |\n|------|---------|\n| [`llms.txt`](https://experienceleague.adobe.com/developer/commerce/storefront/llms.txt) | Index file: overview and links to all documentation sets (full, abridged, and topic bundles under `_llms-txt`). |\n| [`llms-full.txt`](https://experienceleague.adobe.com/developer/commerce/storefront/llms-full.txt) | Complete documentation in one file. |\n| [`llms-small.txt`](https://experienceleague.adobe.com/developer/commerce/storefront/llms-small.txt) | Abridged bundle (same content as the full export except the long-form release changelog page). |\n| `_llms-txt/*.txt` | Smaller topical exports (for example, [drop-ins reference](https://experienceleague.adobe.com/developer/commerce/storefront/_llms-txt/dropins-reference.txt), [tutorials](https://experienceleague.adobe.com/developer/commerce/storefront/_llms-txt/tutorials-reference.txt), [blocks](https://experienceleague.adobe.com/developer/commerce/storefront/_llms-txt/blocks-reference.txt)). All bundle URLs are listed from [`llms.txt`](https://experienceleague.adobe.com/developer/commerce/storefront/llms.txt). |\n\n\nSome of these files are large. Loading a whole file sends a lot of text into the model at once. They are rebuilt every time the site is published, so treat them as a fallback when an AI tool cannot search or fetch the live docs. Whenever possible, browse or search this storefront documentation for the latest edits, navigation, and diagrams.\n\n> **Note**\n>\n  Context files are generated at build time from the documentation source in this project. They may lag brief editorial changes until the next deployment.\n\n\n## How to use context files\n\nEach tool below supports either the public `llms.txt` URL, pasted bundle text, or a built-in documentation index when the feature exists. For agent-based tools, adding the `llms.txt` URL to a project context file such as `AGENTS.md` or `CLAUDE.md` is the most reliable method — the agent fetches the index on demand rather than relying on a pre-built index that may lag recent changes.\n\n### Cursor\n\nCreate or update `AGENTS.md` at your project root and add a section that points to the documentation index:\n\n```\n## Adobe Commerce Storefront Documentation\n\nSee https://experienceleague.adobe.com/developer/commerce/storefront/llms.txt for Adobe Commerce Storefront documentation.\n```\n\nCursor agent mode reads `AGENTS.md` and fetches the index on demand. You can also add this reference to a file under `.cursor/rules/` if you prefer a Cursor-specific location.\n\nIf you still want to use Cursor's built-in indexer, go to **Cursor → Settings → Cursor Settings → Indexing & Docs → Add Doc** and paste the `llms.txt` URL. Keep in mind that the indexed copy may not reflect the latest published changes. Optional: paste `llms-small.txt` or a specific `_llms-txt/*.txt` bundle directly into chat when you need a narrow scope.\n\n### Claude Code (CLI)\n\nCreate or update `CLAUDE.md` at your project root and add a line pointing to the documentation index:\n\n```\nSee https://experienceleague.adobe.com/developer/commerce/storefront/llms.txt for Adobe Commerce Storefront documentation.\n```\n\nClaude Code will fetch the index and linked bundles when the documentation is relevant. In a new chat, ask a question this storefront documentation would answer (for example, about a drop-in). If the reply cites or aligns with those topics, the URL is wired in.\n\n### Other AI tools\n\nOther assistants often accept a documentation URL in settings or in the system prompt.\n\nFor tools that support custom context URLs or \"docs\" sources (GitHub Copilot Chat, Windsurf, and similar): provide the full URL below. Tools that implement the  will follow the index to the relevant bundles automatically.\n\n```\nhttps://experienceleague.adobe.com/developer/commerce/storefront/llms.txt\n```\n\nFor tools that do not support URL-based context, paste the content of `llms-small.txt` (or a relevant `_llms-txt/*.txt` topic bundle) directly into the chat or system prompt.\n\n### Example prompt\n\nAfter this documentation is wired into your assistant, try a concrete question in chat. The sample below is one illustration you can paste or rewrite. In this sample, PDP means product detail page.\n\n```\nUse the Storefront docs. I'm building a PDP page and I want to add a custom 'Add to Wishlist' button in the product details drop-in, below the existing Add to Cart button. I don't want to fork the drop-in. How do I use slots to do this?\n```\n\nAdapt drop-in names or UI labels if your project differs, then verify the reply against the live product drop-in topics before you ship a change.\n\n## Tips\n\n- Many paths, blocks, and drop-in examples in this documentation match the folder layout of the  on GitHub, not a random custom storefront. Open your clone of that repository in your editor while you read so file lists and paths the assistant suggests line up with what you see on disk. If you use a different project, say that in the chat so the assistant does not assume boilerplate folders.\n- After `llms.txt` or a bundle connects this documentation to your assistant, you can paste the web address of the page you are reading into the same chat when you need the reply scoped to that topic. That paste narrows one reply to the page you mean and leaves your `llms.txt` or bundle connection unchanged."
+    },
+    {
+      "path": "get-started/create-storefront",
+      "title": "Create a storefront",
+      "description": "Learn how to create an Adobe Commerce storefront from the boilerplate with GitHub, Code Sync, Commerce config, DA.live, local clone, and go-live pointers.",
+      "content": "By the end of this page, you will have a new GitHub repository from the Commerce boilerplate, the Code Sync app on that repo, a storefront configuration for your Commerce backend, starter content in Document Authoring on DA.live, and a local clone.\n\nUse the [Which backend do you have?](#which-backend-do-you-have) table and finish prerequisites before the tasks below. When Commerce data or services are missing, the fix is usually the backend checklist, not a broken repository.\n\nFor `npm install`, `npm start`, and local preview, use [Boilerplate getting started](https://experienceleague.adobe.com/developer/commerce/storefront/boilerplate/getting-started/). If accounts and tools are not ready, read [Before you start](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/before-you-start/) first.\n\nYou can return later for optional steps such as Sidekick (Browser extension that helps creators edit, preview, and publish content from a content folder, and helps developers open source documents from published pages.) or the Universal Editor.\n\n## Site Creator or this walkthrough\n\nThis page walks through repository creation, Code Sync, configuration, content, and local setup in order. When your organization allows it, use  in  so one flow can create the GitHub repo, add starter content, and fill most storefront configuration. If you cannot use Site Creator, follow GitHub, Code Sync, and the DA.live config generator as separate tasks below.\n\n### Which should you use?\n\nUse Site Creator first when you want the fastest path and your organization allows it.\n\nStay on this page when you need to see how the pieces connect, or when Site Creator is not an option. Typical cases include the following:\n\n- You are new to the stack and want to see what each step does before you run it in a live project.\n- Your organization limits who can create repositories or install GitHub Apps, so you follow an approved process step by step.\n- You are fixing a store that is only partly configured, or you must run steps in a fixed order for automation.\n- You already have a repository and you use Site Creator only to connect content. You may still run some tasks by hand, and the sections below explain what each part is for.\n\n## Big picture\n\nThis tutorial uses Edge Delivery Services (Adobe's hosting and delivery infrastructure that turns authored documents into fast HTML pages served from servers close to the shopper. You push code to GitHub; Edge Delivery Services builds and publishes automatically.) (EDS) to host the storefront, the Commerce boilerplate for code, and Document Authoring (DA.live) for page content. You create a new EDS storefront from the . After you connect your own backend, the same repo holds local preview, demo content, and a path to production.\n\nThe diagram caption and the numbered list below describe the same flow, so you can skim either one first.\n\n<Diagram caption=\"Steps to create and configure your starter storefront.\">\n  ![Steps to create and configure your starter storefront.](images/CreateStorefrontSteps.png)\n</Diagram>\n\n<Callouts columnCount={1}>\n\n1. Create the site repository — Generate a storefront repository from the .\n1. Add the Code Sync app — The app redeploys your storefront when you push to the `main` branch. It connects Edge Delivery Services to your repository so code and content stay aligned, and it sets where your site's content is registered in the Edge Delivery configuration.\n1. Link the repository to Commerce data — Add a storefront `config.json` (or equivalent) in the repo with values for your backend.\n1. Add content — In , use the  app to create or attach a content folder.\n1. (Optional) Universal Editor — Edit content in context on the rendered page.\n1. (Optional) Sidekick — Preview, publish, and open source documents from the live site.\n1. Set up a local environment — Clone the repo, install dependencies, and run the boilerplate on your computer.\n1. Secure the storefront — Tighten access to content, the repository, and the site before production or a wide audience.\n\n</Callouts>\n\n## Which backend do you have?\n\n\n| Scenario | Description | Prerequisites |\n|----------|-------------|---------------|\n| [Commerce PaaS](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/#commerce-platform-as-a-service-paas) | Existing Adobe Commerce on cloud or on-premises without an Adobe Commerce as a Cloud Service or Adobe Commerce Optimizer license (see [Backend options](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/)) | Manual installation: Storefront Compatibility package, Services Connector, Catalog Service, and other storefront services your project needs. See [PaaS: required packages and services](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/#paas-required-packages-and-services). |\n| [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/#adobe-commerce-as-a-cloud-service) | Fully managed Commerce SaaS. License includes Storefront. | Skip the Commerce PaaS storefront install checklist. Adobe runs the Commerce backend and storefront services for your license. See [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/#adobe-commerce-as-a-cloud-service) for details. |\n| [Adobe Commerce Optimizer](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/#adobe-commerce-optimizer) | Fully managed Optimizer SaaS for catalog and merchandising. License includes Storefront. | Skip the Commerce PaaS storefront install checklist. Adobe runs the Optimizer services your license includes. See [Adobe Commerce Optimizer](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/#adobe-commerce-optimizer) for details. |\n\n\nBefore you continue, confirm prerequisites on [Backend options](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/) for whichever scenario in the table above matches your Commerce backend.\n\nOn Commerce PaaS, finish [PaaS: required packages and services](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/backends/#paas-required-packages-and-services) on the Commerce instance first. On Adobe Commerce as a Cloud Service or Adobe Commerce Optimizer, skip the Commerce PaaS storefront install checklist because your licensed environment already includes the services the storefront expects.\n\nThe steps below apply to every backend unless a note says otherwise. Backend-specific detail starts at [Link your repository to Commerce data](#link-your-repository-to-commerce-data).\n\nOn Adobe Commerce as a Cloud Service or Adobe Commerce Optimizer, run [Link your repository to Commerce data](#link-your-repository-to-commerce-data) only after [Commerce services and integrations](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/architecture/commerce-services-and-backends/#commerce-services) shows catalog data in sync. If you are unsure, use [Data export validation](https://experienceleague.adobe.com/developer/commerce/storefront/setup/discovery/data-export-validation/) first.\n\nIf you already have an Edge Delivery site for this Commerce project, skip creating a brand-new site and use the  for code and content.\n\n## Example site\n\nThe CitiSignal demo site was built from the same boilerplate you will set up to develop your own storefront. You can open the full demo site at .\n\n[![CitiSignal demo storefront homepage showing navigation, hero banner, and product categories.](images/citisignal-demo.png)](https://main--citisignal-one--adobedevxsc.aem.live/us/en/)\n\n## Manual setup without Site Creator\n\nThe [Site Creator or this walkthrough](#site-creator-or-this-walkthrough) section explains when to use this long-form path. The tasks below assume you create the GitHub repository from the , install the , and use Site Creator for content (including attaching an existing repository), as in [Before you start](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/before-you-start/). If your organization only allows Site Creator for brand-new sites, work with your administrator, then pick up at the Add content task with the repo Site Creator already created.\n\n## Step-by-step\n\nThe tasks below follow the same order most teams use: GitHub repository, Code Sync, Commerce data, Document Authoring content, optional tooling, local clone, then security. Run them in order unless a note tells you to wait or skip. Open [Storefront Architecture](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/architecture/) or [Before you start](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/before-you-start/) when a label or step does not make sense.\n\n\n### Create the site repository\n\nThis task requires a GitHub account with access to the organization or account where you want to create the new repository. All three backends use the same boilerplate template.\n\n\n**Personal GitHub account:**\n\n\nCreate the repo under your personal account. When you select Owner, choose your username. Install the Code Sync app on the repository in the next step.\n\n\n**GitHub Enterprise (organization):**\n\n\nCreate the repo under your organization. When you select Owner, choose the organization. You may need organization admin approval to install the Code Sync app on a repository. Ensure you have permission to create repositories and install GitHub Apps in the organization.\n\n> **Trouble with organization access?**\n>\nIf you have trouble with your organization access, you can create your repo from a personal account first, then migrate that repo to a  Edge Delivery Services site after you learn more about EDS and repoless.\n\n\n<Diagram caption=\"Create your storefront repo.\">\n  ![Create your storefront repo](images/create-repo.webp)\n</Diagram>\n\n> **Sign in to GitHub first**\n>\n  Sign in to your GitHub account before you open the repository's **Use this template** control. If you are not signed in, that control does not appear.\n\n\n1. Navigate to .\n\n1. Select the **Use this template** button.\n\n1. Select **Create a new repository** when GitHub shows that option. The repository creation form opens.\n\n1. Complete the form with the following details:\n\n   - Repository template: `hlxsites/aem-boilerplate-commerce` (default).\n   - Include all branches: Do not include all branches (default).\n   - Owner: Your organization or account (required).\n   - Repository name: A unique name for your new repo (required). GitHub allows letters, numbers, hyphens, and underscores. For Commerce on Edge Delivery Services, use lowercase letters, numbers, and hyphens only so preview and live URLs match the usual `main--your-repo--your-org` pattern.\n   - Description: A brief description of your repo (optional).\n   - Public or Private: We recommend public (default).\n\n1. Select the Create repository button and watch GitHub create your new storefront repo.\n\n1. After a few seconds, you should be redirected to the home page of your new repo.\n\n\n> **Managed backends**\n>\nAdobe Commerce as a Cloud Service and Adobe Commerce Optimizer use the same repo creation steps above. The only difference is in the next step when you configure the storefront to point to your managed environment.\n\n\n### Add the Code Sync app\n\nInstall the Code Sync app on your repository (it cannot be installed globally on a user or org). It redeploys your storefront site whenever you push or merge changes to the `main` branch. That behavior is the same for every backend in the table above.\n\n<Diagram caption=\"Add AEM Code Sync to your repository.\">\n  ![Add AEM Code Sync to your repository.](images/code-sync.webp)\n</Diagram>\n\n> **Slightly different UIs**\n>\n  A gray background on an organization or account indicates that at least one repository within it\n  has the Code Sync app installed. In such cases, you are redirected to the Code Sync configuration page for that org or account, where you choose which repositories have the app. There are no differences in the steps, but the UI differs slightly from the one shown in the diagram (Install versus Save buttons), which shows the Code Sync page when installing on a repository for the first time.\n\n\n**Personal GitHub account:**\n\n\nSelect your username when choosing where to install. You will see your personal repositories in the selector.\n\n\n**GitHub Enterprise (organization):**\n\n\nSelect your organization. You may need admin approval to install the Code Sync app on repositories. If your organization uses SAML SSO, you may need to authorize the app for SAML SSO access.\n\n\n1. Navigate to the .\n\n1. Select the **Configure** button (top right). GitHub opens the page where you choose which repository receives the app.\n\n1. Select the organization or account that owns the repo you just created.\n\n1. In the form, choose **Only select repositories**.\n\n1. Open the **Select repositories** selector and choose your repo from the list.\n\n1. Select **Install** (or **Save**; see the note above) to install Code Sync on your repository.\n\n1. You should see a success screen if the installation completed without errors. Your repo is now connected to the Edge Delivery Services code bus.\n\n1. (_Optional_) If you return to the , your repo's organization or account will now be gray with **Configure** added. Select your organization or account again to access the Code Sync configuration page, where you can see which repositories have Code Sync installed and add it to more repositories.\n\n\n### Link your repository to Commerce data\n\nTo connect your Commerce backend to the storefront repository, use the . It generates a [storefront configuration](https://experienceleague.adobe.com/developer/commerce/storefront/setup/configuration/commerce-configuration/) file for your site. The file differs by backend type. Follow only the tab for your backend in the config generator and in the reference.\n\nAdd or update the storefront configuration for your project:\n\n\n1. Open the .\n\n1. Select your backend type so the tool generates the correct storefront configuration structure.\n\n1. Enter the values for your project. See the [Storefront configuration reference](https://experienceleague.adobe.com/developer/commerce/storefront/setup/configuration/commerce-configuration/) for field descriptions (select the tab for your backend).\n\n1. Save the generated JSON as `config.json` at the repository root. The storefront runtime requests `/config.json` from your site.\n\n1. The template includes `demo-config.json` as a sample, not a committed `config.json`. After your root `config.json` matches your backend, remove `demo-config.json` or leave it unused so one file stays authoritative.\n\n1. Commit and push the new or updated `config.json` to the repo.\n\n\n### Add content\n\nIn this task, you create and initialize the content side of your storefront in the Document Authoring environment. The steps are the same for all backends.\n\n> **Demo Content**\n>\nIf you do not want demo content, you can create a file in  replacing `` and `` with your own. This reserves the org and site for you to add your own content.\n\n\n1. Open the  in DA.live.\n\n1. Select **Use existing repository**.\n\n1. Copy the GitHub owner and site values into the input fields.\n\n1. Select **Create site**.\n\n1. Follow the prompts until Site Creator finishes copying starter content into your content folder.\n\n1. If prerequisites were incomplete, you may need to preview or publish the content manually.\n\n\n<Diagram caption=\"Initialize your storefront content\">\n  ![Initialize your storefront content](images/site-creator.png)\n</Diagram>\n\n\n### (Optional) Use Universal Editor for content editing\n\nUse this path when authors need in-context editing beyond what Site Creator sets up by default. For workflows and documentation links, see [Using the Universal Editor](https://experienceleague.adobe.com/developer/commerce/storefront/merchants/quick-start/universal-editor/).\n\n\n<a id=\"optional-sidekick-content-editing\"></a>\n\n### (Optional) Use Sidekick for content editing\n\n> **Sidekick setup**\n>\nSite Creator wires your project for Sidekick so the toolbar can recognize preview and live URLs. Authors install the browser extension from the Chrome Web Store, or follow Edge steps on , when they are ready. That page covers install steps, site config, preview, and publish. For prerequisites that line up with this page, see [Before you start](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/before-you-start/#sidekick-browser-extension).\n\n\n### Set up local environment\n\nClone the repository to your computer so you can work on the code and run a local preview. On GitHub, open your storefront repository, select the Code button, and copy the clone URL (HTTPS or SSH). In a terminal, run `git clone` with that URL, then `cd` into the folder GitHub created. For example, if the clone URL is `https://github.com/my-org/my-storefront.git`, you would run:\n\n```bash frame=\"none\"\ngit clone https://github.com/my-org/my-storefront.git\ncd my-storefront\n```\n\nUse your own organization, repository, and folder names from GitHub. The commands for `npm install`, `npm start`, and opening the preview in a browser all live on [Running locally](https://experienceleague.adobe.com/developer/commerce/storefront/boilerplate/getting-started/#running-locally) in Boilerplate getting started so this page stays shorter. That page also explains what to do if a command fails or port `3000` is already in use.\n\n\n### (Optional) Secure your storefront\n\nThe storefront works at this point, but the site is not protected by default. We recommend securing your content, repository, and site access before you deploy to production or share the site with external users. See [Security and access](https://experienceleague.adobe.com/developer/commerce/storefront/setup/launch/#security-and-access) in the Launch checklist for step-by-step instructions.\n\n\n> **What you have now**\n>\n  You have a Commerce storefront project on GitHub, starter content in Document Authoring, and a local clone of the repository. Next, use [Boilerplate getting started](https://experienceleague.adobe.com/developer/commerce/storefront/boilerplate/getting-started/) to run and explore the code, then customize the boilerplate and drop-in components (NPM packages that provide core Commerce storefront features such as cart, checkout, product details, and account flows.) to match your project.\n\n\n## What's next\n\n- [Boilerplate getting started](https://experienceleague.adobe.com/developer/commerce/storefront/boilerplate/getting-started/) — Install paths, `npm` scripts, and a typical local loop after your repository exists.\n- [Boilerplate configuration](https://experienceleague.adobe.com/developer/commerce/storefront/boilerplate/configuration/) — Storefront configuration, `headers.xlsx`, and paths for preview versus production.\n- [Introduction to drop-ins](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/introduction/) and [Using drop-ins](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/quick-start/) — Initializer flow, slots, and styling when you are ready to change Commerce UI.\n- [Launch checklist](https://experienceleague.adobe.com/developer/commerce/storefront/setup/launch/) — Security, performance, and go-live items when you move past learning."
+    },
+    {
+      "path": "get-started/performance",
+      "title": "Performance best practices",
+      "description": "Apply Edge Delivery performance guidance to your Adobe Commerce boilerplate with load phases, fonts, LCP, and links to Keeping it 100 and related docs.",
+      "content": "If your storefront feels slow or your mobile scores look low, start here.\n\nYou'll walk through `delayed.js`, CSS load order, and `head.html` next to , the Edge Delivery guide many teams keep open while they tune loading. After you change how things load, run [Lighthouse audits](#run-lighthouse-audits) for a fresh readout. Before launch, review [Performance and monitoring](https://experienceleague.adobe.com/developer/commerce/storefront/setup/launch/#performance-and-monitoring) on the launch checklist.\n\nWhen you already have the project from [Create a storefront](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/create-storefront/), leave the repo open in your editor so you can open files such as `scripts/delayed.js` and `styles/styles.css` when this page points to them.\n\nThe Commerce boilerplate uses the same Edge Delivery Services (Adobe's hosting and delivery infrastructure that turns authored documents into fast HTML pages served from servers close to the shopper. You push code to GitHub; Edge Delivery Services builds and publishes automatically.) pattern as other Edge storefronts: eager, lazy, and delayed loading, fonts, and LCP (Largest Contentful Paint, how fast the main content shows).\n\npreload</code> and early hints. Read it before you edit <code>head.html</code> or split CSS.\"\n  link=\"https://www.aem.live/developer/keeping-it-100\"\n  rightIcon=\"external\"\n  target=\"_blank\"\n  rel=\"noopener noreferrer\"\n  aria-label=\"Keeping it 100 on AEM.live (opens in a new tab)\"\n/>\n\n## Run Lighthouse audits\n\nPageSpeed Insights runs Lighthouse on Google's hardware instead of on your computer, so you can compare one test run to the next more fairly than if you only tested locally. It reports Web Vitals, Google's standard scores for how fast and stable the page feels. The fix list follows Google's performance guidance. When you change load order or assets, compare those suggestions with  so resource hints, fonts, and load phases still match what Edge Delivery Services expects.\n\n*.aem.live</code>) for accurate results. That hostname sits on CDNs close to your customers, on the edge.\"\n  link=\"https://pagespeed.web.dev/\"\n  rightIcon=\"external\"\n  target=\"_blank\"\n  rel=\"noopener noreferrer\"\n  aria-label=\"PageSpeed Insights (opens in a new tab)\"\n/>\n\n### Step-by-step\n\nThe following steps run a PageSpeed Insights audit on a URL you choose.\n\n\n1. Go to the .\n\n1. Paste your storefront URL into the PageSpeed Insights input field.\n\n1. If you use the default `main` branch pattern on Edge Delivery, typical preview and production hosts look like this (replace `` and `` with your GitHub repository name and owner):\n   - Preview: `https://main----.aem.page/`\n   - Production: `https://main----.aem.live/`\n\n1. Click the **Analyze** button to run the audit.\n\n1. You'll see full Web Vitals reports for mobile and desktop. Scores are often high on tuned Edge Delivery storefronts, but they vary with page content, third-party scripts, and test conditions, so treat the report as a snapshot, not a guarantee of 100 on every run.\n\n\n## Performance in the Commerce boilerplate\n\n### Delayed phase\n\n describes a delayed phase for third-party tags, marketing tooling, extended analytics, consent, chat, and similar scripts. Load them through `delayed.js` so they do not compete with LCP or the rest of the experience.\n\nIn the Commerce boilerplate, implement that path in . Keep it off the eager path. For Adobe Experience Platform and related patterns, see [Adobe Experience Platform analytics](https://experienceleague.adobe.com/developer/commerce/storefront/setup/analytics/adobe-experience-platform/).\n\n### Eager vs lazy styles\n\nKeeping it 100 treats styles in two phases so LCP stays predictable.\n\n#### Eager phase\n\nThe eager phase covers the markup, CSS, and JavaScript that must load first so the main content can appear quickly and your LCP score can settle. Stay within the network and payload limits the Keeping it 100 page describes.\n\n> **Preload and early hints**\n>\nToo many <code>preload</code> tags, early hints, and <code>preconnect</code> entries can steal bandwidth from what the visitor needs first and hurt mobile LCP. Keeping it 100 explains how to stay inside safe limits instead of adding every hint you can think of.\n\n\n#### Lazy phase\n\nThe lazy phase is for styles (and related assets) that can load after the main content and LCP finish so they do not slow the first screen.\n\nIn the Commerce boilerplate, eager, site-wide tokens and styles usually start in . For deferred styles (for example, `lazy-styles.css`), use the folder-and-import patterns in [Branding and styles](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/all/branding/) instead of merging them into the eager file.\n\nAfter your split matches that guidance, align `head.html` and load order with Keeping it 100 so you are not maintaining a second rule set. Keeping it 100 also explains why preloading every web font often backfires. Keep the boilerplate font fallbacks unless you have a clear measurement that says to change them.\n\n> **Related storefront docs**\n>\nFor tips on catalog pages (images, APIs, loading order), see the [FAQ](https://experienceleague.adobe.com/developer/commerce/storefront/troubleshooting/faq#how-can-i-improve-the-performance-of-my-catalog-pages)."
+    }
+  ]
+}

package/dist/registry/docs/how-tos.json

@@ -0,0 +1,19 @@
+{
+  "section": "how-tos",
+  "label": "How-Tos",
+  "pageCount": 2,
+  "pages": [
+    {
+      "path": "how-tos/federated-search",
+      "title": "Federated search",
+      "description": "Learn how to implement federated search that combines content and commerce search results in your storefront.",
+      "content": "A common requirement for storefronts is to provide a unified search experience that returns both content (blog posts, articles, pages) and commerce (products) results from a single search input. This tutorial shows you how to implement a federated search approach that performs parallel searches against a content index and the Adobe Commerce GraphQL API.\n\nIn this tutorial, you'll learn how to create a combined search experience that displays results from content and commerce in a single view, providing shoppers with comprehensive search results across your entire site.\n\n## What You'll Build\n\nBy the end of this tutorial, you'll have:\n\n- A content index configuration that indexes pages, blogs, and other site content\n- A custom search block that performs parallel searches against content and commerce\n- A tabbed interface displaying separate results for content and products\n- A fully functional federated search experience\n\n## Prerequisites\n\nBefore starting this tutorial, make sure you have:\n\n- A working [Commerce storefront](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/create-storefront/) on Edge Delivery Services\n- Basic understanding of JavaScript and asynchronous operations\n- Familiarity with [customizing blocks](https://experienceleague.adobe.com/developer/commerce/storefront/boilerplate/customizing-blocks/) in your code repository\n- Access to configure content indexing for your site (similar to [enrichment configuration](https://experienceleague.adobe.com/developer/commerce/storefront/merchants/content-customizations/enrichment/))\n- Adobe Commerce backend configured with product catalog\n\n## Overview\n\nDeveloping this federated search solution involves:\n\n1. Creating an index for the pages and content of your site\n2. Building a custom search block that fetches both content and commerce data\n3. Implementing a tabbed UI to display results separately\n4. Processing search queries in parallel for optimal performance\n\nThis method keeps content and commerce searches distinct while delivering a unified experience to the user.\n\n> **When to use this strategy**\n>\nThis federated search strategy is ideal for scenarios where you need quick implementation, have straightforward search requirements, or want to maintain separate control over content and commerce search logic.\n\n\n### Step 1: Create the Content Index Configuration\n\nCreate a `helix-query.yaml` file in the root of your repository with this configuration:\n\n```yaml title=\"helix-query.yaml\"\nversion: 1\nindices:\n  content:\n    target: /content-index.json\n    exclude:\n      - '/blog/index'\n    include:\n      - /blog/**\n      - /pages/**\n    properties:\n      title:\n        select: head > meta[property=\"og:title\"]\n        value: |\n          attribute(el, 'content')\n      description:\n        select: head > meta[name=\"description\"]\n        value: |\n          attribute(el, 'content')\n      lastModified:\n        select: none\n        value: |\n          parseTimestamp(headers['last-modified'], 'ddd, DD MMM YYYY hh:mm:ss GMT')\n      content:\n        select: main\n        value: |\n          textContent(el)\n```\n\n**What this does:**\n\nThis configuration tells Edge Delivery Services to automatically index your site's content pages. When you publish pages, the system:\n- Crawls pages matching `/blog/**` and `/pages/**` (excludes `/blog/index`)\n- Extracts metadata (`title`, `description`, `content`) from each page\n- Generates a searchable JSON index at `/content-index.json`\n\n**Key fields:**\n- `select`: CSS selector or metadata to extract\n- `value`: Extraction method (e.g., `attribute()`, `textContent()`)\n- See the  for advanced property configurations\n\nCommit and push `helix-query.yaml`. The index generates automatically when you publish pages.\n\n> **Tip**\n>\n**Alternative: Configuration Service**\n\nInstead of a GitHub file, you can use the Configuration Service API to manage the configuration remotely at:\n```\nhttps://admin.hlx.page/config/[ORG]/sites/[SITE]/content/query.yaml\n```\nReplace `[ORG]` with your GitHub organization and `[SITE]` with your repository name. See the  for authentication details.\n\nIf you already use [enrichment](https://experienceleague.adobe.com/developer/commerce/storefront/merchants/content-customizations/enrichment/), add the `content` index to your existing `query.yaml` file.\n\n\n**Verify:** After publishing pages, access `https://[your-domain]/content-index.json` to see the indexed pages as JSON.\n\n![Content index JSON output showing indexed pages with title, description, and content fields](images/federated-search-content-index.png)\n\n\n### Step 2: Create Sample Content Pages\n\nTo validate your federated search setup, publish content pages that can be indexed. For example, create and publish blog posts in a `/blog` directory.\n\nCreate a few pages such as:\n\n- `/blog/winter-collection`\n- `/blog/summer-sale`\n- `/blog/holiday-shopping-guide`\n\nHere's an example of what your content page might look like:\n\n![Example blog page for Winter Collection](images/federated-search-content-example.png)\n\n> **Content tip**\n>\nInclude relevant keywords in your content that shoppers might search for. Since the content index stores the full text of your pages, well-written and relevant descriptions can significantly improve search results.\n\n\n### Step 3: Create the Combined Search Block\n\nNext, create a custom block to perform the federated search. This block processes both the content and commerce searches using the [Product Discovery drop-in](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/product-discovery/).\n\nCreate a new directory: `blocks/combined-search/`\n\nCreate `blocks/combined-search/combined-search.js`:\n\n> **Full implementation**\n>\nThe code below shows the key concepts. For a complete working example with full rendering logic, see the .\n\n\n```javascript title=\"blocks/combined-search/combined-search.js\"\n/**\n * Combined Search Block\n * Performs parallel searches against content index and commerce search API\n */\n\n// Import the search function from the Product Discovery drop-in\n\nlet contentIndex = null;\n\n/**\n * 1. Fetch and cache the content index\n */\nasync function getContentIndex() {\n  if (contentIndex) return contentIndex;\n\n  const response = await fetch('/content-index.json');\n  const data = await response.json();\n  contentIndex = data.data;\n  return contentIndex;\n}\n\n/**\n * 2. Search the content index (client-side filtering)\n */\nfunction searchContent(query, index) {\n  const searchTerm = query.toLowerCase();\n  return index.filter((item) => {\n    return item.title?.toLowerCase().includes(searchTerm)\n      || item.description?.toLowerCase().includes(searchTerm)\n      || item.content?.toLowerCase().includes(searchTerm);\n  });\n}\n\n/**\n * 3. Search commerce products using the Product Discovery drop-in\n */\nasync function searchProducts(query) {\n  try {\n    const results = await search({\n      phrase: query || '',\n      currentPage: 1,\n      pageSize: 12,\n      filter: [\n        { attribute: 'visibility', in: ['Search', 'Catalog, Search'] }\n      ]\n    });\n\n    return results?.items || [];\n  } catch (error) {\n    console.error('Error searching for products:', error);\n    return [];\n  }\n}\n\n/**\n * 4. Perform parallel searches and render results\n */\nasync function performSearch(query, block) {\n  // Perform both searches in parallel for optimal performance\n  const [contentIndex, products] = await Promise.all([\n    getContentIndex(),\n    searchProducts(query)\n  ]);\n\n  // Filter content results client-side\n  const contentResults = searchContent(query, contentIndex);\n\n  // Render results (implementation details omitted - see reference link)\n  renderContentResults(contentResults, block.querySelector('.content-results'));\n  renderProductResults(products, block.querySelector('.product-results'));\n}\n\n/**\n * 5. Initialize the block\n */\nexport default async function decorate(block) {\n  // Get search query from URL\n  const urlParams = new URLSearchParams(window.location.search);\n  const query = urlParams.get('q') || '';\n\n  // Build the UI with tabs for Products and Content\n  block.innerHTML = `\n    \n      \n        <input type=\"text\" class=\"search-input\" />\n        <button class=\"search-button\">🔍</button>\n      \n\n      \n        <button class=\"tab-button active\" data-tab=\"products\">Products</button>\n        <button class=\"tab-button\" data-tab=\"content\">Content</button>\n      \n\n      \n        \n          \n        \n        \n          \n        \n      \n    \n  `;\n\n  // Safely set the search input value to prevent XSS\n  const searchInput = block.querySelector('.search-input');\n  searchInput.value = query;\n\n  // Setup event listeners for search and tabs (implementation details omitted)\n  setupSearchHandlers(block, performSearch);\n  setupTabs(block);\n\n  // Pre-fetch content index for faster subsequent searches\n  getContentIndex();\n\n  // If there's a query in URL, perform the search\n  if (query) {\n    performSearch(query, block);\n  }\n}\n\n// Helper functions: renderContentResults(), renderProductResults(), setupTabs(), setupSearchHandlers()\n// See reference implementation for complete rendering and UI logic\n```\n\n**Key concepts explained:**\n\n1. **Content index caching** (`getContentIndex`): The content index is fetched once and cached in memory for subsequent searches, improving performance.\n\n2. **Client-side content search** (`searchContent`): Because the content index is a JSON file, we can filter it client-side using the JavaScript `filter()` method. This is fast and doesn't require additional API calls.\n\n3. **Product search** (`searchProducts`): Products are searched using the Commerce [`search()` function](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/product-discovery/functions/#search) from the Product Discovery drop-in, which handles the GraphQL query to Adobe Commerce. The `visibility` filter ensures only searchable products are returned.\n\n4. **Parallel execution** (`performSearch`): Both searches execute in parallel using `Promise.all()`, ensuring that the slower query doesn’t delay the faster one.\n\n5. **Tabbed UI**: Results are organized in separate tabs (Products and Content) for a clean user experience.\n\n> **Customize search behavior**\n>\n- Add additional filters (like category or price range)\n- Adjust pagination with `pageSize`\n- Add sorting options\n- Customize the content search algorithm in `searchContent()`\n- Modify the UI structure to display results differently (for example, in a single list instead of tabs).\n\n\n### Step 4: Add Styling for the Search Block\n\nCreate `blocks/combined-search/combined-search.css` and add the styles from the .\n\n\n### Step 5: Create the Search Results Page\n\nCreate a dedicated page in your project to host the combined search block. Using your content authoring tool (for example, [DA.live](https://experienceleague.adobe.com/developer/commerce/storefront/merchants/quick-start/document-authoring/), Google Docs, SharePoint), add a new page at `/search`.\n\n![Example search page](images/federated-search-search-example.png)\n\nThis addition creates a page that uses your `combined-search` block.\n\n\n### Step 6: Test Your Implementation\n\n**Quick verification:**\n\n1. **Content index**: Visit `https://[your-domain]/content-index.json` and verify that pages are indexed with metadata.\n2. **Product search**: Navigate to `/search?q=winter` and check that the Products tab shows results with images, titles, and prices.\n3. **Content search**: Try `/search?q=blog` and verify that the Content tab displays titles and descriptions.\n4. **Search UI**: Type a query, press Enter, and confirm the URL updates with the `?q=` parameter and the tabs refresh.\n5. **Edge cases**: Test empty results, special characters, and short queries (one to two characters).\n\n**Expected result:**\n\n![Federated search results showing search input, Products and Content tabs, with product cards displayed in the Products tab](images/federated-search-products-tab.png)\n\n\n## Complete Example\n\nHere's a complete example of how the federated search works in practice:\n\n**User Journey:**\n\n1. Shopper types \"winter\" in the search box\n2. System performs parallel searches:\n   - Content search finds blog posts about \"Winter Collection 2024\"\n   - Product search finds products tagged with \"winter\"\n3. Results display in separate tabs:\n   - **Products Tab**: Displays winter jackets, boots, accessories\n   - **Content Tab**: Displays blog posts, buying guides, seasonal content\n\n![Products tab showing winter product results with images and prices](images/federated-search-products-tab.png)\n\n![Content tab showing blog posts and articles related to winter](images/federated-search-content-tab.png)\n\n## Performance Considerations\n\n> **Optimization tips**\n>\n- The content index is fetched once and cached in memory\n- Both searches run in parallel using `Promise.all()` for optimal speed\n- Consider implementing debouncing for search-as-you-type functionality\n- For large content indexes (>1MB), consider pagination or lazy loading\n\n\n## Troubleshooting\n\n### Common Issues\n\n* **Content index returns 404 error**\n\n  > Verify that you've correctly configured the `query.yaml` file and that you've published pages that match your include patterns. The index is only generated after the configuration is in place and pages are published.\n\n* **No products appear in search results**\n\n  > Check that your GraphQL endpoint is correctly configured. In the browser console, verify that the GraphQL query is executing without errors. Ensure your Adobe Commerce instance has products with the searched terms.\n\n* **Content search returns too many irrelevant results**\n\n  > Improve the search algorithm in the `searchContent()` function. Consider implementing:\n  > - Ranking by relevance (title matches weighted higher than content matches)\n  > - Fuzzy matching for better results\n  > - Filtering out pages with `robots: noindex`\n\n* **Search is slow or times out**\n\n  > - Check the size of your content index (should be under 5MB for good performance)\n  > - Ensure you're caching the content index properly (see `getContentIndex()` function)\n  > - Consider using a CDN to cache the content-index.json file\n\n### Getting Help\n\nIf you encounter issues not covered here:\n\n- Check the [FAQ section](https://experienceleague.adobe.com/developer/commerce/storefront/troubleshooting/faq/) for common storefront issues\n- Review the [Blocks Reference](https://experienceleague.adobe.com/developer/commerce/storefront/boilerplate/blocks-reference/) for block development patterns\n- Consult the  for query troubleshooting\n\n## Summary\n\nIn this tutorial, you learned how to:\n\n- ✅ Configure a content index (for example, `helix-query.yaml`) to index pages for your site\n- ✅ Create a custom combined search block that queries both content and commerce\n- ✅ Implement parallel async searches for optimal performance\n- ✅ Build a tabbed interface to organize and display federated search results\n- ✅ Handle edge cases and provide a smooth user experience\n\nYou now have a fully functional federated search solution that combines content and commerce search in your storefront. This approach provides a simple yet effective way to help shoppers discover both products and content across your entire site.\n\nThe implementation is maintainable, performant, and can be extended with additional features like filtering, sorting, and advanced ranking algorithms as your requirements grow."
+    },
+    {
+      "path": "how-tos/search-redirects",
+      "title": "Search redirects",
+      "description": "Learn how to configure search redirects so that specific query terms send shoppers directly to a target page instead of the standard search results.",
+      "content": "Search redirects give your merchandising team direct control over where high-intent shoppers land. When a shopper types an exact match for a configured term, the storefront sends them directly to a destination URL instead of showing search results. Business users manage the mapping in a spreadsheet, so no developer involvement is needed.\n\n## What you'll build\n\nBy the end of this tutorial, you'll have:\n\n- A content spreadsheet (`/search-redirects`) that maps search terms to destination URLs, managed by business users\n- A JavaScript utility module (`scripts/search-redirects.js`) that loads and caches the redirect map\n- An integration in your search results page block that intercepts matching queries before any search API calls are made\n- An optional integration in your header search input that redirects without navigating to `/search` first\n\n## Prerequisites\n\nBefore starting this tutorial, make sure you have:\n\n- A working [Commerce storefront](https://experienceleague.adobe.com/developer/commerce/storefront/get-started/create-storefront/) on Edge Delivery Services\n- A search results page powered by the [Product Discovery drop-in](https://experienceleague.adobe.com/developer/commerce/storefront/dropins/product-discovery/)\n- Access to author and publish content (Document Authoring (DA.live), Google Docs, or SharePoint)\n- Familiarity with [customizing blocks](https://experienceleague.adobe.com/developer/commerce/storefront/boilerplate/customizing-blocks/) in your code repository\n\n## Overview\n\nThe implementation has two layers:\n\n1. **Content layer** — A spreadsheet at the root of your site defines the redirect rules. Business users add, edit, or remove rows without touching code.\n2. **Code layer** — JavaScript in your search block fetches the spreadsheet, then checks the active query against it on every search page load.\n\nTwo entry paths can bring a shopper to a search URL, and both need to be handled:\n\n- **Case A** — Shopper types a term in the header search box and submits. The browser navigates to `/search?q=<term>`.\n- **Case B** — Shopper opens a bookmarked or shared URL such as `/search?q=running`.\n\nStep 3 (required, in your search page block) covers both cases. Step 4 (optional, in your header block) improves the experience for Case A by redirecting before the browser ever navigates to `/search`.\n\n> **Why not the Edge Delivery Services redirect sheet?**\n>\nThe  (`/redirects` spreadsheet) matches only URL paths. It strips query strings before matching, so every URL that starts with `/search` collapses to the same path regardless of the `?q=` value, which makes it impossible to target individual search terms. Search term redirects must be handled client-side, in the browser, where the typed query is available.\n\n\n### Step 1: Create the search-redirects spreadsheet\n\nCreate a new spreadsheet named `search-redirects` at the root of your content folder (the same level as your homepage). Add two column headers in the first row: **Search Term** and **Destination URL**.\n\n\n| Search Term | Destination URL |\n|---|---|\n| login | /customer/login |\n| clothes | /apparel |\n| inexpensive clothes | /apparel?page=1&sort=position_DESC&filter=price%3A0-10 |\n| adobe | https://adobe.com |\n\n\n#### Rules for the spreadsheet\n\n- **Search Term** — The exact term to match. Matches are case-insensitive and ignore leading and trailing spaces, so `\"Running Shoes\"`, `\"running shoes\"`, and `\"  running shoes  \"` all match the same row.\n- **Destination URL** — The full destination path, URL with query parameters, or external URL. It is stored verbatim with no transformation applied. Use root-relative paths (`/page`) for internal pages, paths with query parameters for pre-filtered pages, or full URLs (`https://…`) for external destinations.\n\nPublish the spreadsheet. After publishing, it becomes available at `/search-redirects.json`. Each time you add or change rows, publish the spreadsheet again to update the file. Previewing the spreadsheet does not update the live file.\n\n> **Tip**\n>\nVerify the published output by opening `/search-redirects.json` in your browser. You should see your rows in the `data` array with `\"Search Term\"` and `\"Destination URL\"` keys.\n\n\n### Step 2: Create the redirect utility module\n\nCreate `scripts/search-redirects.js` in your repository. This module fetches the spreadsheet once, caches the result, and exposes two functions to the rest of your code.\n\n```javascript title=\"scripts/search-redirects.js\"\nlet redirectsPromise = null;\n\nfunction normalize(term) {\n  return term.trim().toLowerCase().replace(/\\s+/g, ' ');\n}\n\n/**\n * Fetches and caches the redirect map from /search-redirects.json.\n * Safe to call multiple times — only one network request is made.\n * Returns an empty Map (and does not throw) if the file is missing or malformed.\n */\nexport function preloadSearchRedirects() {\n  if (!redirectsPromise) {\n    redirectsPromise = fetch('/search-redirects.json')\n      .then((res) => {\n        if (!res.ok) return new Map();\n        return res.json();\n      })\n      .then((json) => {\n        if (!Array.isArray(json?.data)) return new Map();\n        return new Map(\n          json.data\n            .filter((row) => row['Search Term'] && row['Destination URL'])\n            .map((row) => [normalize(row['Search Term']), row['Destination URL']]),\n        );\n      })\n      .catch(() => new Map());\n  }\n  return redirectsPromise;\n}\n\n/**\n * Returns the configured destination for a search term, or null if no match.\n * @param  term\n * @returns {Promise<string|null>}\n */\nexport async function getSearchRedirectDestination(term) {\n  if (!term) return null;\n  const map = await preloadSearchRedirects();\n  return map.get(normalize(term)) ?? null;\n}\n```\n\n#### Key design decisions\n\n- **Single fetch, cached promise** — `preloadSearchRedirects()` is safe to call from multiple places. Only one network request is made for the lifetime of the page.\n- **Graceful failure** — If `/search-redirects.json` returns a non-200 status or is malformed, the module returns an empty `Map`. Search continues working normally with no JavaScript errors.\n- **Normalization** — Both the stored terms and the incoming query are lowercased and whitespace-collapsed before comparison, so casing and extra spaces never cause a miss.\n\n\n### Step 3: Integrate into the product-list-page block (required)\n\nOpen `blocks/product-list-page/product-list-page.js`. This block powers both your `/search` page and your category pages. The `config.urlpath` value tells it which role it is in: category pages set `config.urlpath`, and the search page does not. The redirect check uses the same signal to run only on the search page.\n\nAdd the import and the redirect check at the top of `decorate()`, after the `config` and `searchState` variables are initialized. The check must happen before the `search()` call so that a matching query never triggers a Live Search API request.\n\n```javascript title=\"blocks/product-list-page/product-list-page.js\"\n\n// ... existing imports ...\n\nexport default async function decorate(block) {\n  const config = readBlockConfig(block);\n  const searchState = getSearchStateFromUrl(new URL(window.location.href));\n\n  // Only apply redirects on the search page, not category pages.\n  // config.urlpath is set on category pages; its absence means this is the /search page.\n  if (!config.urlpath) {\n    preloadSearchRedirects(); // warm the cache immediately\n\n    if (searchState.phrase) {\n      const destination = await getSearchRedirectDestination(searchState.phrase);\n      if (destination) {\n        window.location.replace(destination);\n        return; // stop — Live Search is never called\n      }\n    }\n  }\n\n  // ... rest of your existing decorate() logic unchanged ...\n}\n```\n\n> **Category pages**\n>\nThe `if (!config.urlpath)` guard prevents the redirect logic from running on category pages. Without it, every category page that uses this block would fetch `search-redirects.json` on load.\n\n\n### Step 4: Integrate into the header block (optional)\n\nThis step improves the shopper experience for Case A. When the shopper submits a redirectable term from the header search box, they go directly to the destination without an intermediate visit to `/search`.\n\nWithout this step, Case A still works correctly via Step 3. The shopper briefly visits `/search` before being redirected. This step eliminates that extra navigation.\n\nOpen `blocks/header/header.js` and make three edits.\n\n#### Edit 1: Add the import\n\nAdd the import near the top of the file with the other imports:\n\n```javascript title=\"blocks/header/header.js\"\n\n```\n\n#### Edit 2: Warm the cache when the panel opens\n\nInside `toggleSearch()`, find the line that calls `withLoadingState()`. Add `preloadSearchRedirects()` on the line immediately before it so the redirect data is fetched as soon as the shopper opens the search panel — before they submit anything.\n\nFind this line:\n\n```javascript title=\"blocks/header/header.js\"\n    await withLoadingState(searchPanel, searchButton, async () => {\n```\n\nAdd the new line directly above it:\n\n```javascript title=\"blocks/header/header.js\"\n    preloadSearchRedirects(); // fetch redirect data as soon as the panel opens\n    await withLoadingState(searchPanel, searchButton, async () => {\n```\n\n#### Edit 3: Replace the submit handler\n\nInside the `withLoadingState()` callback, find the existing `searchForm` submit handler:\n\n```javascript title=\"blocks/header/header.js\"\n      searchForm.addEventListener('submit', (e) => {\n        e.preventDefault();\n        const query = e.target.search.value;\n        if (query.length) {\n          window.location.href = `${rootLink('/search')}?q=${encodeURIComponent(query)}`;\n        }\n      });\n```\n\nReplace it with this async version that checks for a redirect first:\n\n```javascript title=\"blocks/header/header.js\"\n      searchForm.addEventListener('submit', async (e) => {\n        e.preventDefault();\n        // At the time the `submit` event fires, `window.location.search` still reflects the current \n        // page's URL, not the term the shopper just typed. Reading from `e.target.search.value` \n        // gives you the actual input value.\n        const query = e.target.search.value.trim();\n        if (!query.length) return;\n\n        const destination = await getSearchRedirectDestination(query);\n        window.location.href = destination ?? `${rootLink('/search')}?q=${encodeURIComponent(query)}`;\n      });\n```\n\n\n### Step 5: Commit and push your changes\n\nCommit the files you created or edited in Steps 2 through 4 and push them to your GitHub repository.\n\nAfter the push, the Code Sync app picks up the changes and makes them available on your preview URL — the address that follows the pattern `https://main--<repo>--<owner>.aem.page`. You do not need to publish the site to test.\n\nTo confirm the deployment worked, navigate to your `/search` page (for example, `https://main--<repo>--<owner>.aem.page/search?q=test`) and open the Network tab in your browser's developer tools. Because `scripts/search-redirects.js` is imported by `product-list-page.js`, it only loads on the search page — not the homepage. If it shows a 200 status, the file loaded correctly. A 404 status means the file was not found — double-check the file path in your commit.\n\nIf you completed Step 4, the header block imports `search-redirects.js` as well, so opening the search panel on any page will also trigger it in the Network tab.\n\nOnce the files are available, you can test the redirect two ways: type a term from your spreadsheet into the header search bar and press Enter, or navigate directly to `/search?q=<term>` in the address bar. Either way, the browser should go straight to the destination you configured. Step 6 walks through both scenarios and a few others.\n\n\n### Step 6: Test your implementation\n\nUse any of the following scenarios to verify the implementation.\n\n- **Direct URL — matching term:** Navigate to `/search?q=login` (assuming \"login\" is in your spreadsheet). Confirm you are immediately redirected to the configured destination without search results loading.\n\n- **Case-insensitive match:** Navigate to `/search?q=Login` (capitalized). Confirm you reach the same destination as lowercase.\n\n- **Direct URL — non-matching term:** Navigate to `/search?q=running+shoes`. Confirm search results load normally with no redirect.\n\n- **Header search — matching term:** Open the search panel, type a redirectable term, and press Enter. Confirm you go directly to the destination without a `/search` URL appearing in the address bar (only applies if you completed Step 4).\n\n- **Header search — non-matching term:** Type a term not in the spreadsheet and press Enter. Confirm the browser navigates to `/search?q=<term>` normally.\n\n- **Prefetch:** Open browser DevTools → Network, then open the search panel. Confirm that `search-redirects.json` is fetched at that point rather than waiting for a form submit.\n\n- **Graceful failure:** Temporarily rename or 404 your `/search-redirects.json`. Confirm that search still works without JavaScript errors.\n\n\n## User journey walkthrough\n\nWhen a shopper types \"inexpensive clothes\" and submits the search form, `getSearchRedirectDestination` returns the configured destination and the browser navigates directly to the pre-filtered apparel page. Live Search is never called. When the same shopper types \"running shoes\" — a term with no matching rule — the browser navigates to `/search?q=running+shoes` as normal.\n\nThe  shows the full integration in the Commerce storefront. Use it as a working reference when adapting this pattern to your storefront.\n\n> **Zero-results variant**\n>\nIf you only want to redirect when Live Search returns zero results (rather than always redirecting on a term match), call `getSearchRedirectDestination` inside your results handler instead, and only redirect when `totalCount === 0`. The same utility function works for both modes.\n\n\n## Troubleshooting\n\n### Redirect not firing\n\nOpen `/search-redirects.json` and confirm your row is present. The column headers must match exactly: `Search Term` and `Destination URL`. Any extra characters, including spaces, will break the lookup.\n\n### All searches redirect to the same page\n\nYou are likely using the Edge Delivery Services redirect system instead of this client-side implementation. The Edge Delivery Services system strips query strings before matching, so every `/search` path maps to the same rule. Use the client-side approach from this tutorial for search-term routing.\n\n### Redirect fires on category pages\n\nEnsure the `if (!config.urlpath)` guard is in place in your search block. Category pages populate `config.urlpath`; the search page does not. If your shared block does not have this guard, add one that fits your block.\n\n### `search-redirects.json` returns 404\n\nThe file is only generated after you publish the spreadsheet. Confirm the spreadsheet is published (not just previewed) and located at the root of your content tree. If you want to test the redirect functionality without publishing, you can create a local copy of the spreadsheet and place it in the root of your code repository.\n\n## What you built\n\n\n| File | Purpose |\n|---|---|\n| `/search-redirects` spreadsheet | Redirect rules, managed by business users |\n| `scripts/search-redirects.js` | Fetches and caches the redirect map |\n| `blocks/product-list-page/product-list-page.js` | Intercepts queries before Live Search fires |\n| `blocks/header/header.js` | Optional: redirects from the search input directly |"
+    }
+  ]
+}

package/dist/registry/docs/index.json

@@ -0,0 +1,139 @@
+{
+  "totalPages": 467,
+  "totalSections": 22,
+  "priority": "Registry data from dropin source code takes precedence over documentation content when there are conflicts.",
+  "sections": [
+    {
+      "section": "boilerplate",
+      "label": "Boilerplate",
+      "pageCount": 8,
+      "file": "boilerplate.json"
+    },
+    {
+      "section": "dropins-b2b",
+      "label": "B2B Drop-ins",
+      "pageCount": 100,
+      "file": "dropins-b2b.json"
+    },
+    {
+      "section": "dropins/all",
+      "label": "Drop-ins Overview",
+      "pageCount": 15,
+      "file": "dropins-all.json"
+    },
+    {
+      "section": "dropins/cart",
+      "label": "Cart Drop-in",
+      "pageCount": 26,
+      "file": "dropins-cart.json"
+    },
+    {
+      "section": "dropins/checkout",
+      "label": "Checkout Drop-in",
+      "pageCount": 31,
+      "file": "dropins-checkout.json"
+    },
+    {
+      "section": "dropins/order",
+      "label": "Order Drop-in",
+      "pageCount": 22,
+      "file": "dropins-order.json"
+    },
+    {
+      "section": "dropins/payment-services",
+      "label": "Payment Services Drop-in",
+      "pageCount": 11,
+      "file": "dropins-payment-services.json"
+    },
+    {
+      "section": "dropins/personalization",
+      "label": "Personalization Drop-in",
+      "pageCount": 10,
+      "file": "dropins-personalization.json"
+    },
+    {
+      "section": "dropins/product-details",
+      "label": "Product Details Drop-in",
+      "pageCount": 22,
+      "file": "dropins-product-details.json"
+    },
+    {
+      "section": "dropins/product-discovery",
+      "label": "Product Discovery Drop-in",
+      "pageCount": 13,
+      "file": "dropins-product-discovery.json"
+    },
+    {
+      "section": "dropins/recommendations",
+      "label": "Recommendations Drop-in",
+      "pageCount": 10,
+      "file": "dropins-recommendations.json"
+    },
+    {
+      "section": "dropins/user-account",
+      "label": "User Account Drop-in",
+      "pageCount": 19,
+      "file": "dropins-user-account.json"
+    },
+    {
+      "section": "dropins/user-auth",
+      "label": "User Auth Drop-in",
+      "pageCount": 16,
+      "file": "dropins-user-auth.json"
+    },
+    {
+      "section": "dropins/wishlist",
+      "label": "Wishlist Drop-in",
+      "pageCount": 13,
+      "file": "dropins-wishlist.json"
+    },
+    {
+      "section": "get-started",
+      "label": "Getting Started",
+      "pageCount": 13,
+      "file": "get-started.json"
+    },
+    {
+      "section": "how-tos",
+      "label": "How-Tos",
+      "pageCount": 2,
+      "file": "how-tos.json"
+    },
+    {
+      "section": "licensing",
+      "label": "Licensing",
+      "pageCount": 2,
+      "file": "licensing.json"
+    },
+    {
+      "section": "merchants",
+      "label": "Merchants",
+      "pageCount": 86,
+      "file": "merchants.json"
+    },
+    {
+      "section": "resources",
+      "label": "Resources",
+      "pageCount": 1,
+      "file": "resources.json"
+    },
+    {
+      "section": "sdk",
+      "label": "Drop-ins SDK",
+      "pageCount": 22,
+      "file": "sdk.json"
+    },
+    {
+      "section": "setup",
+      "label": "Storefront Setup",
+      "pageCount": 23,
+      "file": "setup.json"
+    },
+    {
+      "section": "troubleshooting",
+      "label": "Troubleshooting",
+      "pageCount": 2,
+      "file": "troubleshooting.json"
+    }
+  ]
+}