orionplace-nuxt 0.1.3 → 0.2.1

package/README.md

@@ -1,37 +1,71 @@
 # orionplace-nuxt
 
-Set up a Nuxt 4 storefront for your personal Orionplace marketplace API.
-The package includes a Nuxt module, a setup CLI, and commented server source
-that is copied into your project alongside an integration README.
+**A complete Nuxt 4 storefront for your Orionplace marketplace, set up with one command.**
+
+`orionplace-nuxt` creates a server-rendered shop connected to your personal
+marketplace API: catalog and search, product pages, cart and checkout, customer
+account, journal and support, in English and Russian. The package includes a Nuxt module, a
+setup CLI and the full storefront source, so every page and component in your
+project is yours to change.
+
+- **Setup CLI:** `init`, `set backend`, `add frontend`, `set mimic` and `update`.
+- **API gateway:** the browser calls `/api/...` on your own domain; the server
+  forwards it to your marketplace backend with cookies bound to the storefront.
+- **Typed store:** one Application Load request fills it before the first render.
+- **124 storefront components**, each with an English and Russian README
+  ([list](#components)).
+- **Several storefront domains** on one backend, each with its own mapping.
+- **Android app** from the same project with Capacitor 8.
+
+**Contents:** [Quick start](#quick-start-from-zero) ·
+[Existing project](#existing-nuxt-4-project) · [Components](#components) ·
+[Commands](#commands) · [Android app](#android-app) ·
+[Update](#update-an-existing-project)
 
 Requires Node.js 22.12+ and a Node server deployment. Static-only and edge
 hosting are not supported by this filesystem-based integration.
 
-## New project
+## Android app
 
-Your personal backend domain is already provided in your account at
-[orionmarket.place](https://orionmarket.place). You can change it there.
-Use that domain below and the public domain of your own storefront.
+The same project builds as an Android app with Capacitor 8. Set
+`ORIONPLACE_APP_ORIGIN` to your deployed public storefront (HTTPS) for that
+build: the module then makes a client-only build, and every API request goes to
+`<origin>/api/...` through Capacitor's native HTTP with the storefront Origin,
+so your storefront gateway answers it as for the website. With the
+`@capacitor/app` plugin installed, the Android back button closes an open
+dialog, opens the previous page, or leaves the app on the first page. With
+`@capacitor/filesystem` and `@capacitor/share`, a purchased file is saved in
+the app and opened from the Android share sheet. Without
+the variable nothing changes. Setup, build and release steps:
+[Android app guide](https://orionmarket.place/en/sandbox/android-app).
 
 ```bash
-mkdir my-marketplace
-cd my-marketplace
-npm install orionplace-nuxt
-npx orionplace-nuxt set backend your-project.orionplace.app
-npx orionplace-nuxt add frontend shop.example.com
-npm install
-npm run dev
+ORIONPLACE_APP_ORIGIN=https://shop.example.com npx nuxt generate
+npx cap sync android
 ```
 
-The first setup command creates the Nuxt configuration and app if needed.
-The final `npm install` installs the dependencies added to `package.json`.
-The backend command accepts either a hostname or its full HTTPS `/api` URL.
-The frontend command accepts a public hostname or its root HTTPS URL.
+## Asset loading
+
+The starter preloads only the current route's module graph. Navigation assets
+start loading after pointer or keyboard interaction. Closed dialogs and catalog
+content load when opened, while product rows and events below the first screen
+hydrate as they approach the viewport.
+
+Storefront image components emit intrinsic dimensions or a stable aspect ratio
+to reserve layout space. Product cards include the primary image in the initial
+page and add secondary images after hover or keyboard focus.
+
+## Quick start from zero
 
-You can also scaffold before installing:
+Your personal backend domain is already provided in your account at
+[orionmarket.place](https://orionmarket.place). You can change it there.
+Replace `your-project.orionplace.app` below with that domain and
+`shop.example.com` with the public domain of your own storefront.
+With Node.js 22.12+ and npm installed, run this from the parent folder;
+no existing Nuxt project is needed:
 
 ```bash
-npx orionplace-nuxt init my-marketplace
+npx --yes orionplace-nuxt init my-marketplace
 cd my-marketplace
 npm install
 npx orionplace-nuxt set backend your-project.orionplace.app
@@ -39,6 +73,13 @@ npx orionplace-nuxt add frontend shop.example.com
 npm run dev
 ```
 
+The first command creates the Nuxt configuration, app and integration README.
+The first frontend becomes the local MIMIC domain. Open the local URL printed
+by Nuxt (normally http://localhost:3000). The storefront opens after Application Load
+succeeds. If initialization fails, check your domain mapping and backend response.
+The backend command accepts either a hostname or its full HTTPS `/api` URL.
+The frontend command accepts a public hostname or its root HTTPS URL.
+
 ## Existing Nuxt 4 project
 
 ```bash
@@ -46,6 +87,8 @@ npm install orionplace-nuxt
 npx orionplace-nuxt init --dry-run
 npx orionplace-nuxt set backend your-project.orionplace.app
 npx orionplace-nuxt add frontend shop.example.com
+npm install
+npm run dev
 ```
 
 The CLI preserves unrelated Nuxt settings, scripts, and environment variables.
@@ -58,6 +101,211 @@ No install or postinstall hook changes your application. Only explicitly running
 the CLI writes files. Use `--cwd <directory>` to select a project and `--dry-run`
 to inspect planned changes without writing them.
 
+## Nuxt compatibility date
+
+The local setup implementation adds `compatibilityDate: '2025-07-15'` when it is
+missing from `nuxt.config.ts`, including during updates. Existing dates are
+preserved. This retains Nuxt's fallback behavior and prevents `NUXT_B5001`.
+This fix will be available on npm after the next publication.
+
+For an already generated project, add this property inside the existing
+`defineNuxtConfig({ ... })` object and restart development:
+
+```typescript
+compatibilityDate: '2025-07-15',
+```
+
+Keep the other settings. The date controls compatibility behavior, rather than
+tracking today's date; see the [Nuxt configuration reference](https://nuxt.com/docs/4.x/api/nuxt-config#compatibilitydate).
+
+## Import aliases
+
+Use `@/` for application imports. Nuxt resolves it to `app/`, so an import such
+as `@/stores/orionplace` works from any page, composable or component folder.
+Framework imports such as `#imports` keep their own names.
+
+<!-- components:start (generated by scripts/generate-package-readme-components.mjs) -->
+## Components
+
+The starter includes **124 storefront components**, copied into
+`app/components/orionplace/` of your project. Each one has a README in English and Russian
+next to its source that describes its inputs, data and actions.
+
+### Storefront structure
+
+Main pages and the shared storefront frame.
+
+| Component | Name | What it does |
+| --- | --- | --- |
+| **Header** | `StorefrontHeader` | The storefront header and its search, catalog, manufacturer and journal links, locale, currency, account, wishlist and cart controls. |
+| **Storefront logo** | `BrandLogos` | Displays one logo from store.init.logos. |
+| **Product search** | `MainSearch` | A search input with suggestions in the storefront language. |
+| **Language selector** | `MainLanguageSwitcher` | Selects the storefront language and its associated currency and measurement units. |
+| **Currency selector** | `MainCurrencySwitcher` | Selects the current storefront currency from the available options. |
+| **Storefront account** | `StorefrontAccount` | Guest sign-in button and signed-in account menu with profile and wallet actions. |
+| **Wallet balance** | `WalletBalance` | Displays the wallet balance in the selected storefront currency. |
+| **Sign-out page** | `StorefrontLogout` | Session sign-out, failure retry and return to the storefront. |
+| **Wishlist button** | `StorefrontWishlistButton` | Displays the wishlist count and links to the wishlist page. |
+| **Cart button** | `StorefrontCartButton` | Displays the cart count and emits a request to open the cart page. |
+| **Cart preview** | `CartPreview` | A compact dropdown under the header's cart button with cart products, quantities and amounts in the selected currency. |
+| **Catalog menu** | `CatalogHeader` | Category navigation with nested sections and representative product cards. |
+| **Catalog representative** | `CatalogRepresentative` | A compact product card used in the catalog menu, with the same navigation, variant, wishlist and purchase actions. |
+| **Storefront home** | `StorefrontHome` | Banners, the optional Popular categories block, product sections, storefront events and recommendations. |
+| **Storefront banners** | `MainBanner` | A carousel of banner images for the current storefront language, with responsive image formats. |
+| **Popular categories block** | `CategoryGroup` | Optional home-page block of public category tiles. |
+| **Product group** | `ProductGroup` | Displays a collection of product cards with images, prices, variant selection and purchase controls. |
+| **Product card** | `ProductCard` | Combines a product’s image, name, price, variants, wishlist button and purchase controls in one card. |
+| **Product photo viewer** | `HoverImageViewer` | A separate product photo viewer with dot buttons: it switches photos with the pointer, with a swipe and from the keyboard, and a click passes the chosen photo's address to the application. |
+| **Product card title** | `ProductCardTitle` | Displays the localized product name in the card. |
+| **Product card description** | `ProductCardDescription` | Displays the localized short product description as plain text, with HTML tags removed. |
+| **Product card badges** | `ProductCardBadges` | Marks new, popular, good-deal and low-stock products with badges in the card. |
+| **Product card wishlist button** | `ProductCardFavorite` | Requests adding or removing the product from the wishlist; the supplied storefront sends guests to sign-in. |
+| **Seller in the product card** | `ProductCardSeller` | Displays the product seller’s name and rating in the card. |
+| **Product card rating** | `ProductCardRating` | Displays the product’s average rating and review count in the card. |
+| **Product card variants** | `ProductCardVariants` | Selects a primary or secondary product variant. |
+| **Secondary variant selector** | `ProductSecondaryVariantModal` | Shows primary and secondary product choices in a modal and can continue the selected purchase action. |
+| **Product card price** | `ProductCardPrice` | Displays the price in the selected currency and the original price when the product is discounted. |
+| **Low-stock notice** | `ProductCardStockNotice` | Warns that the product will soon run out of stock. |
+| **Product card purchase controls** | `ProductCardActions` | Product-card controls for the cart, quantity, availability notifications and preorder when available. |
+| **Preorder dialog** | `ProductPreorderDialog` | The selected product and contact details for a preorder request. |
+| **Storefront events** | `EventsBlock` | A full-width carousel of layout-event images for the current storefront language, with responsive image formats. |
+| **Event block and promotion enrollment** | `EventEnrollmentDialog` | Displaying the event block and opening promotion enrollment from the selected event. |
+| **Footer** | `StorefrontFooter` | Store identity, navigation, a contact-page link and social links. |
+| **Social links** | `SocialLinks` | Display the store’s published social links and icons. |
+| **Error page** | `StorefrontErrorPage` | Page-not-found (404) and failure (500) page with Home, Catalog and Retry actions. |
+| **Storefront theme** | `OrionplaceThemeProvider` | Applies the selected light or dark storefront theme and optional color overrides to its content. |
+
+### Catalog and discovery
+
+Browse categories, search results and product sources.
+
+| Component | Name | What it does |
+| --- | --- | --- |
+| **Catalog component** | `StorefrontCatalog` | The component shows store categories, subcategories and product links. |
+| **Category page** | `StorefrontCategory` | A category with its breadcrumb path, subcategories, filters and paginated product cards. |
+| **Search results** | `ProductSearchResults` | Filters, products, loading and empty states for search, category, seller and recommendation results. |
+| **Search filters** | `SearchFilters` | Price, discount, rating, review, category, seller, manufacturer and variant facets with selectable values and optional result counts. |
+| **Sellers** | `StorefrontSellers` | Seller directory with filters and sorting, and a seller profile with its products. |
+| **Seller filters** | `SellerFilters` | Seller name, minimum rating and category filters for the seller directory. |
+| **Seller summary** | `SellerSummary` | Seller logo, name, rating, selling-since badge, product count and description. |
+| **Seller photos** | `SellerPhotoGallery` | The seller’s approved photos as a square grid with a photo viewer. |
+| **Stores** | `StorefrontStores` | Store addresses, map, phone numbers, opening hours and products. |
+| **Manufacturers and their products** | `StorefrontManufacturers` | Alphabetical index, letter-based lists and manufacturer details. |
+| **Manufacturer index** | `ManufacturerIndex` | Manufacturer logos and letter groups. |
+
+### Products and shopping
+
+Product details, saved items and the cart.
+
+| Component | Name | What it does |
+| --- | --- | --- |
+| **Product details** | `StorefrontProduct` | Loads and displays a published product or a secret-key preview with images, purchase choices, details and reviews. |
+| **Page path** | `OrionplaceBreadcrumbs` | Linked path from the storefront home page through parent categories to the current page. |
+| **Product characteristics** | `ProductSpecificationsDialog` | Every characteristic of the product in a dialog over the page. |
+| **Product reviews** | `ProductReviews` | Reviews, replies, ratings and the user’s submissions. |
+| **Review form** | `ProductReviewForm` | Rating, text and photos for a review or reply. |
+| **Customer review photos** | `ProductReviewGallery` | Review photos for the selected product. |
+| **Review photo viewer** | `ProductReviewImageViewer` | The photos of one review, shown large on the same page. |
+| **Promo code products** | `PromoProducts` | The products a promo code offer applies to, with the offer’s conditions. |
+| **Wishlist and availability notices** | `StorefrontWishlist` | Saved products and products with availability notifications, shown as standard product cards. |
+| **Cart and checkout** | `StorefrontCart` | Cart items, promo codes, delivery, payment and order creation. |
+| **Cart item** | `CartLineItem` | Item name, image, price, quantity and removal. |
+| **Cart item options** | `CartItemOptions` | Option products as product cards, with text and file attachment for an item. |
+| **Checkout details** | `CartCheckoutDetails` | Delivery address, payment method, recipient and comment. |
+| **Shipment delivery selection** | `CartDeliverySelector` | Delivery methods with icons, pickup points and their map for one shipment. |
+| **Delivery map** | `DeliveryMap` | Selectable locations on Yandex Maps for delivery pickup and the store directory. |
+
+### Customer account
+
+Profile, orders, addresses and account activity.
+
+| Component | Name | What it does |
+| --- | --- | --- |
+| **Account sections** | `AccountSection` | Account navigation and sign-in for private storefront sections. |
+| **Personal profile** | `StorefrontProfile` | Account overview and forms for personal details, verified email, notification preferences, avatar, password and account deletion. |
+| **Profile photo** | `ProfileAvatar` | Upload or remove the current account’s avatar. |
+| **Personal details** | `ProfileDetailsForm` | Edit the account holder’s name and date of birth. |
+| **Email and notifications** | `ProfileEmailSettings` | Verify an email address and choose optional email-notification and email-language preferences. |
+| **Account password** | `ProfilePasswordForm` | Create or change the account password. |
+| **Password field** | `OrionplacePasswordInput` | Password input with a button that shows or hides the entered password. |
+| **Delete account** | `ProfileDeleteAccount` | Delete the signed-in customer's own account. |
+| **Account sign-in** | `ProfileSignIn` | Phone-based account sign-in and registration. |
+| **User promo codes** | `AccountPromocodes` | Available promo codes and applying a selected code to the cart. |
+| **My activity** | `AccountActivity` | The user’s promo codes, reviews and sign-in history. |
+| **Sign-in history** | `SignInHistory` | The user’s sign-in dates, devices, browsers and IP addresses. |
+| **User orders** | `StorefrontOrders` | Order history, purchased items, payment, cancellation and repeat. |
+| **Order details** | `OrderDetails` | Order items, shipments, tracking, purchased content and attachments. |
+| **Order payment selection** | `OrderPaymentForm` | Available payment-method selection for an existing order. |
+| **User addresses** | `StorefrontAddresses` | Saved addresses, address editing and default delivery selection. |
+| **Address form** | `AddressForm` | Address creation and editing with country selection, region search, text suggestions and location lookup. |
+| **Value selector** | `OrionplaceSelect` | Selects one value from a labeled list, with keyboard controls, country flags and option icons. |
+| **Search selector** | `OrionplaceSearchSelect` | Selects one value from options searched as the user types, with a loading spinner and retry. |
+| **Wallet and payments** | `StorefrontWallet` | Payment history, balance top-ups and cancellation of unpaid invoices. |
+| **Wallet top-up form** | `WalletTopUpForm` | Amount, currency and payment-method selection for a wallet top-up. |
+| **Payment panel** | `PaymentPanel` | Opens the payment link and lets the user refresh its status. |
+| **Pagination** | `StorefrontPagination` | Previous and next controls with the current page for a returned list. |
+
+### Subscriptions and support
+
+Plans, active subscriptions and support requests.
+
+| Component | Name | What it does |
+| --- | --- | --- |
+| **Subscription plans** | `StorefrontTariffs` | Plans grouped by subscription, with search, sign-in for guests and subscription purchase. |
+| **Subscription plan details** | `StorefrontTariff` | One public plan with its media, description, features, periods, options and subscription purchase. |
+| **Subscription plans** | `TariffCards` | Plan cards in a responsive grid. |
+| **Subscription plan card** | `TariffCard` | A plan card with its image, trial badge, name, description, the modules and limits of the plan, the option chooser, period prices and subscribe actions. |
+| **Plan image** | `TariffCardImage` | The first small plan image. |
+| **Plan name** | `TariffCardTitle` | The tariff name in its card, in the selected language. |
+| **Plan description** | `TariffCardDescription` | The short plan description without HTML tags, and the full description under Details. |
+| **Plan modules, limits and options** | `TariffCardFeatures` | The modules and limits of a plan from `tariff_variables_json`, each with its explanation, and the chooser of the plan options. |
+| **Information hint** | `OrionplaceInfoHint` | Small information button that explains the term beside it. |
+| **Plan prices** | `TariffCardPrices` | The period switcher, the price for the chosen period and the Subscribe and Try actions. |
+| **Plan purchase** | `TariffSubscriptionModal` | Select an option, enter a promotion code and confirm a subscription purchase. |
+| **My subscriptions** | `StorefrontSubscriptions` | Subscription dates, plan, usage, service details, automatic renewal, renewal payment and support. |
+| **Renewal payment** | `SubscriptionExtendDialog` | The period, the promo code and the amount for extending a subscription. |
+| **Automatic renewal** | `SubscriptionRenewalDialog` | The period that is paid automatically, or turning it off. |
+| **Plan and option change** | `SubscriptionChangeDialog` | The new plan or service option, its period and the amount that is charged. |
+| **Subscription cancellation** | `SubscriptionCancelDialog` | The confirmation that stops automatic renewal and keeps the paid period. |
+| **Plan and usage** | `SubscriptionPlanSummary` | The plan picture, description and parameters with the usage the subscription service reported. |
+| **Subscription service details** | `SubscriptionRemoteDetails` | The identifier, confirmation time and host a subscription service returned. |
+| **Support conversations** | `StorefrontSupport` | Customer support conversations for general questions, sellers, order items and subscriptions. |
+| **Conversation messages** | `TicketConversation` | Messages, attachments, conversation closing and support rating. |
+| **Conversation item** | `TicketItemCard` | The purchased item a conversation is about, with its image, variant or option, quantity and paid amount. |
+| **Subscription of a conversation** | `TicketSubscriptionCard` | The subscription a support conversation is about: plan, number, state, paid-until date and automatic renewal. |
+| **Conversation image** | `TicketImage` | Loading and viewing an image from the user’s conversation. |
+| **Support message form** | `TicketMessageForm` | Message text and images for a new conversation or reply. |
+
+### Content and contact
+
+Journal content and customer contact flows.
+
+| Component | Name | What it does |
+| --- | --- | --- |
+| **Journal** | `StorefrontJournal` | Paged journal of store articles with category and author filters. |
+| **Journal article** | `BlogArticle` | An article, subscription access and its discussion. |
+| **Article comments** | `BlogComments` | Discussion, replies and the user’s own comments. |
+| **Comment form** | `BlogCommentForm` | Text for a new comment, reply or edit. |
+| **Blog posts** | `BlogPostGroup` | Publication previews in a grid, list or layout with a lead card. |
+| **Blog post card** | `BlogPostCard` | Publication image, localized title, plain-text preview and reading time. |
+| **Contact page** | `StorefrontContact` | Company contact and registration details, with a form for messaging the store. |
+| **Contact details** | `AboutPage` | Display the store’s published company and contact information. |
+| **Contact form** | `ContactForm` | Sending a question to the store. |
+| **Unsubscribe from emails** | `EmailUnsubscribe` | Confirming an unsubscribe request from an email link. |
+
+### Shared interface
+
+Small reusable states and identity elements.
+
+| Component | Name | What it does |
+| --- | --- | --- |
+| **Empty state** | `OrionplaceEmptyState` | Line drawing and message shown when a list, history or search result has no items. |
+| **Avatar** | `OrionplaceAvatar` | Round user photo with initials when no photo is available. |
+| **Storefront image** | `OrionplaceImage` | Loads a safe public image lazily and shows an accessible placeholder when the image is missing or fails. |
+| **Measurement unit selector** | `UnitSwitcher` | Selects a weight or length unit from those available in the storefront. |
+
+<!-- components:end -->
+
 ## Commands
 
 ```bash
@@ -93,13 +341,14 @@ change your account, create DNS records, configure TLS, or deploy a VPS.
 | --- | --- |
 | `nuxt.config.ts` | Registers the module; an existing supported config keeps its filename. |
 | `orionplace/runtime/marketplace.mjs` | Commented domain lookup and HTTP transport. |
-| `orionplace/runtime/api.mjs` | Nitro handler registered for `/api/**`. |
+| `orionplace/runtime/api.mjs` | Nitro handler registered for `/api/**` and blog media under `/ps3/blog/**`. |
 | `orionplace/runtime/domain.mjs` | Domain resolution middleware. |
 | `orionplace/README.md` | Your settings, API examples, file explanations, verification and VPS deployment. |
 | `orionplace/settings.json` | Domain values selected by the CLI. |
 | `orionplace/.generated.json` | File hashes used to preserve your edits on subsequent setup. |
 | `sitemaps/shop.example.com.cfg` | One line: `https://your-project.orionplace.app/api`. |
 | `.env` | `MIMIC_FRONT_DOMAIN="shop.example.com"` for localhost. |
+| `.vscode/settings.json` | Tells the editor's CSS checker to accept Tailwind's `@apply`, `@reference` and `@theme`. An existing file is kept. |
 
 The module executes the generated local runtime files. You can read and customize
 them. Later setup runs preserve edited runtime files and the project README,
@@ -161,14 +410,33 @@ Deploy `sitemaps` with the production server, or set an absolute `SITEMAPS_DIR`.
 The production process reads `MIMIC_FRONT_DOMAIN` without rebuilding. Run the
 server from the project root or explicitly point it at the configuration directory.
 
+## Page metadata
+
+Every supplied page sets its title, description and keywords through
+`app/composables/useOrionplacePageSeo.ts` and Nuxt's `useSeoMeta()`.
+The homepage prefers `init.seo`, and category pages prefer their localized SEO
+fields. Empty values fall back to page-specific Russian or English copy in
+`app/utils/orionplace/pageSeo.ts`. Metadata updates with the current locale and
+route data. The homepage retains additional backend Open Graph and Twitter tags
+through `useHead()`. Profile and logout pages remain excluded from indexing;
+search results retain their `noindex, follow` policy.
+
 ## Documentation
 
-- [Create a Nuxt frontend](https://orionmarket.place/sandbox/new-project/nuxt)
-- [Connect your personal backend](https://orionmarket.place/sandbox/backend-domain/nuxt)
-- [Marketplace API documentation](https://orionmarket.place/sandbox/)
+- [Create a Nuxt frontend](https://orionmarket.place/en/sandbox/new-project/nuxt)
+- [Install the Nuxt package and connect your personal backend](https://orionmarket.place/en/sandbox/new-project/nuxt)
+- [Marketplace API documentation](https://orionmarket.place/en/sandbox/)
+- [Android app for your Nuxt storefront](https://orionmarket.place/en/sandbox/android-app)
 
 ## Development
 
+In this repository checkout, the package demo uses its own
+`packages/orionplace-nuxt/.env` and
+`packages/orionplace-nuxt/sitemaps/<storefront-domain>.cfg`.
+Set the storefront's `MIMIC_FRONT_DOMAIN` and personal backend mapping there.
+See [local demo configuration](DEVELOPMENT.md#local-demo-configuration).
+
+
 ```bash
 npm install
 npm test
@@ -178,15 +446,193 @@ npm pack --dry-run
 The published tarball includes only the CLI, module, runtime source, README,
 license, starter templates, and package metadata.
 
-## AppLoad starter
+## Application Load starter
 
-The CLI generates an AppLoad debug `app/app.vue`, an SSR-aware
-`useOrionplaceAppLoad()` composable, validation helpers and the full nested
-TypeScript contract under `app/interfaces/orionplace/`. The first page loads
-`POST /api/appload`, shows request state and section counts, and supports reload.
+The CLI generates global route middleware, a shared Pinia store and the full
+nested TypeScript contract under `app/interfaces/orionplace/`. Middleware awaits
+`POST /api/appload` before page setup. `useOrionplaceStore()` exposes
+initialization, profile and live endpoint discovery to pages and components.
+`useOrionplaceAppLoad()` provides explicit initialize, refresh and reset actions.
+`app.vue` wraps `NuxtLayout` and `NuxtPage` in the shared theme provider and
+renders `NuxtLoadingIndicator`: a thin bar in the header text color
+(`inverseText`) at the top of the window during navigation and storefront
+requests (`useOrionplaceProgress()`).
+`app/layouts/default.vue` renders the storefront header, cart preview, product
+action feedback, preorder dialog and footer on every route; `pages/index.vue`
+displays the home sections. A failed Application Load replaces every page with
+the error page (HTTP 503, Retry reloads the page); unknown addresses keep 404.
+`app/error.vue` renders `StorefrontErrorPage` for unknown addresses and unhandled
+errors, keeping the HTTP status: 404 shows “Page not found” with Home and
+Catalog, other statuses show “Something went wrong” with Retry and Home. Pages
+use `noindex, nofollow`; customers never see error messages or stack traces.
+The not-found page keeps the header and footer when Application Load succeeded;
+otherwise, and for failures, it renders without the layout. See the
+[error page guide](https://orionmarket.place/en/sandbox/components/nuxt/error-page).
+`/product/:id`, `/tariffs/:slug/:id`, `/category/:id`, `/browse`, `/featured`,
+`/journal` and `/journal/:id` load their first data while the server renders
+the page, with
+the visitor's cookies, so the HTML contains product names, prices, article
+links and article text; the browser reuses that data without repeating the
+request (`useOrionplaceServerData()`). An ID that is not a positive integer, or
+a record that `products_search` or `blog_posts_get` does not return, answers 404
+from the server. A failed request keeps the page with its Retry button, and a
+failed server request is loaded again in the browser. Product cards link to
+`/product/:id` through `provideOrionplaceProductLink()` in the default layout,
+while `/product/:id?key=<preview key>` uses `products_preview` and lets anyone
+with the complete seller or staff preview address view the key owner's product
+without signing in.
+Unpublished and option-only products show a preview notice, and the page uses
+`noindex, nofollow`. Category tiles, banners and the category path link to `/category/:id`
+through `provideOrionplaceCategoryLink()`. Products
+attached to a journal article are shown as standard product cards with variants
+and purchase controls.
+The dark header bar combines catalog navigation with Manufacturers and Journal
+links, search hints and borderless currency/language selectors.
+Currency labels and amounts use `symbol_left` and `symbol_right` from Application
+Load. If both are empty, amounts use the uppercase currency code. This formatting
+is shared by selectors, product prices, wallet balances, cart totals and tariffs;
+it does not convert or round amounts.
+Its home link uses `BrandLogos` with `store.init.logos.medium`; contact data is
+not a header dependency. Missing or failed logo images use the shared placeholder.
+Its labels follow the storefront locale (English/Russian). `StorefrontAccount`
+shows guest sign-in or an authenticated profile menu with the selected currency
+wallet balance. Its `signIn`, `signOut`, `selectProfile` and `selectWallet` events are handled
+by the host; the generated layout opens `/profile` for sign-in (with the current
+page in `redirect`, where the user returns after sign-in) and profile
+selection, `/logout` for sign-out and `/wallet` for wallet selection. The component does not
+submit credentials or create payments. Its [EN/RU preview and source downloads](https://orionmarket.place/en/sandbox/appload/nuxt/init/is_authenticated)
+share the maintained package component. `StorefrontWishlistButton` and
+`StorefrontCartButton` display counts from `store.counters`. Their clicks emit
+`selectWishlist` and `selectCart` through the header without changing data;
+the generated layout opens `/wishlist` for the wishlist button and `CartPreview` for
+the cart button. The starter opens `CartPreview` through
+`useOrionplaceCartPreview` and the discovered `cart_guest_modal_get` endpoint.
+The dialog shows product images, translated names, quantities and cart-item
+totals in the selected currency, with loading, empty and retry states. Closing
+it cancels a pending request. Selecting a product in the preview closes it and
+opens `/product/<id>`; selecting the full cart closes it and opens `/cart`.
+Search opens `/browse?q=<query>`, category selection opens `/category/<id>`,
+product selection opens `/product/<id>` and seller selection opens
+`/sellers?seller=<id>`. Variant selection
+replaces the full representative card and loads missing products or secondary choices through the
+shared API client. Cart, wishlist, availability-notification and preorder events
+run the product action controller described below.
+See [the header contract](templates/orionplace/COMPONENTS.md#storefront-header)
+for the supplied slots and integration boundaries.
 It preserves custom apps and edited generated files. Generated instructions in
 `orionplace/README.md` explain how to integrate the composable in an existing app.
 
+### Application Load component library
+
+The starter also supplies `ManufacturerIndex` and its
+`useOrionplaceManufacturerIndex` controller. `/manufacturers` loads the discovered
+manufacturer-index endpoint and renders logo previews and letter groups, with
+alphabet switching, loading, empty and retry states. The home page links to this
+index beside the journal. The page renders `StorefrontManufacturers`, which loads
+the index itself. Letter and manufacturer selections are `ManufacturerIndex`
+events; `StorefrontManufacturers` handles them by loading that letter's or that
+manufacturer's records through `manufactures_manufactures_get`. See the
+[component reference](https://orionmarket.place/en/sandbox/components/nuxt/manufacturer-index)
+for its contract, live preview and source downloads.
+
+The website [Components section](https://orionmarket.place/en/sandbox/components/nuxt)
+sits beside Application Load and documents Header with its child components,
+plus ProductGroup, ProductCard and its parts. Both English and Russian guides provide live
+previews, contracts and physical source downloads.
+
+Storefront components live under `app/components/orionplace/`, grouped by feature.
+The [field and component catalog](templates/orionplace/COMPONENTS.md) maps each
+initialization field to its consumers. Configuration, session flags and shared
+counters have data references with links to the features that use them.
+The catalog is also installed as `orionplace/COMPONENTS.md`.
+
+The [Application Load sandbox](https://orionmarket.place/en/sandbox/appload/nuxt) renders
+these physical components and lets you edit their input locally. Component
+selections emit events; account, cart and subscription requests remain the host
+application's responsibility.
+
+### Locale selector
+
+`app/components/orionplace/locale/MainLanguageSwitcher.vue` renders the language record
+from `store.locales` directly. Import it without a data prop. It accepts a
+`label` (default `Language`), `disabled` (default `false`) and `codeOnly`
+(default `false`). Missing names
+fall back to another translation, then the human name or code. Empty data
+disables the selector. The store initially selects its first available language.
+
+Flags from `flag_img` appear beside the selected language and in every dropdown
+option that has an available image. Missing or failed images leave the language
+name readable. The dropdown uses the shared theme, supports arrow keys and typing
+to find a language, and closes on Escape or an outside click. Press Enter, Space
+or Tab to confirm the highlighted option.
+Options stay on one line. The dropdown expands within the viewport; longer names
+use an ellipsis, with the full name available on hover.
+
+The component gets `selectionStore` from `useOrionplaceSelectionsStore()`.
+Selection calls `selectionStore.setLocale(code)`, updating `selectionStore.localeCode` and the
+language’s default currency and units. It then emits `change` with the locale object. The component does not navigate or change your translation settings;
+connect these events to your application's language handling as needed.
+
+Setup installs Tailwind CSS 4 and its Vite plugin. Upgrade an existing Tailwind 3
+installation first; setup rejects incompatible versions before writing files.
+The module registers
+`app/assets/css/orionplace.css`, which scans the generated components and pages.
+It includes theme variables and utilities without a global CSS reset, preserving
+your application's base styles. An existing Tailwind Vite plugin is reused.
+It requires no Sass or translation plugin. Keyboard focus changes the existing border and background;
+controls do not use outlines. The
+[locale sandbox](https://orionmarket.place/en/sandbox/appload/nuxt/init/locale)
+previews the same component and provides its source and locale types.
+
+### Themes
+
+Define any number of named themes in `app/themes/orionplace.ts`. Components inherit
+semantic colors from the active theme. Setup includes the shared
+[theme guide](templates/orionplace/THEMES.md) as `orionplace/THEMES.md` in the
+customer project; it covers adding themes, selecting the default and applying them.
+
+### Session and CSRF cookies
+
+Application Load establishes the guest/customer session and CSRF cookie through HTTP
+`Set-Cookie` headers, not through `page_data.init`. The browser handles the signed
+HttpOnly `sessionid` cookie; never parse, rewrite, log or store its value in Pinia
+or localStorage. The readable `csrftoken` supplies `X-CSRFToken` for later protected
+requests through the same-origin `/api/` gateway with credentials enabled. Read
+the CSRF cookie again for every action because login can rotate it.
+
+`useOrionplaceApi()` supplies the per-application `OrionplaceApi` client used by
+Application Load and browser requests. It resolves later endpoints from
+current discovery, reads CSRF per request and renews a missing token. A
+CSRF rejection (HTTP 419, or HTTP 403 with `page_data.csrf: false`) renews the
+token for the next action and returns the failed request. The customer must
+submit again; the client never repeats a failed request automatically. Components send discovered requests in the browser. Page data
+that the server render needs goes through `useOrionplaceServerApi()`, the same
+class with the same transport, usually through `useOrionplaceServerData()`.
+The global route middleware passes `to.query.locale` to the first Application
+Load request. Later requests use the selected locale held by the store.
+During SSR the transport sends the incoming cookies plus every cookie the
+backend set earlier in the same render (`app/utils/orionplace/serverCookies.ts`),
+and relays each raw response `Set-Cookie` separately to the browser. That
+cookie list belongs to one render and is never shared between visitors.
+
+Use `POST /api/csrf_renew` with `{}` to renew CSRF, then re-read the cookie.
+The backend signals CSRF rejection with HTTP `419` from Django views, or with
+HTTP `403` and `page_data.csrf: false` from API endpoints; a `403` without that
+flag may mean permissions or origin rejection. Do not automatically
+replay mutations. After confirmed login/logout, reset and refresh Application Load.
+Those store actions update data; they do not authenticate or delete cookies.
+
+HTTP `401` means the request has no signed-in session. When it arrives while
+`store.isAuthenticated` is `true`, the client calls the store's `endSession()`
+once: the profile, wallet, authenticated discovery, cart/wishlist counters and
+account values of known products are removed at once, then Application Load
+reloads for the guest session. The failed request is not repeated and no
+sign-in dialog opens; a guest `401`, `403`, CSRF rejection or network failure
+stays an ordinary request error.
+
+See the [cookie lifecycle and browser example](https://orionmarket.place/en/sandbox/appload/nuxt#session-cookies)
+for exact source references and a copyable component.
+
 ## Update an existing project
 
 After the initial setup, use one command to get the latest package and components:
@@ -225,3 +671,394 @@ npx --yes orionplace-nuxt@latest update
 Updates require the existing `orionplace/settings.json` and `.generated.json`.
 Conflicting untracked files stop the source update before any writes. If dependency
 installation fails after source generation, run `npm install` and retry `update`.
+
+
+## Representative product actions
+
+The Nuxt header forwards cart, wishlist, availability-notification and preorder
+intents. The generated layout binds `useOrionplaceProductActions` to the shared API
+client; confirmed responses update the product and `store.counters`. Controls
+stay visible while disabled, and the catalog stays open. At quantity one the
+trash control removes the confirmed cart item. Secondary variants must be
+selected before confirming an addition, subscription or preorder in the picker.
+Guest preorder collects contact details. Wishlist controls require authentication;
+notifications can request sign-in, and subscription requires profile email. The
+generated storefront supplies sign-in and personal details at `/profile`. Failed mutations retain confirmed
+data; a failed follow-up refresh retries only that read. Components previews
+record actions without changing the reader's cart or session.
+
+### Component compositions and source
+
+The Components overview renders the maintained Header and StorefrontHome.
+Dashed outlines identify children; child guides retain their real parent context.
+Home links to its categories, banners, events and ProductGroup children.
+ProductGroup links to ProductCard and its parts. Component guides finish with a
+Related pages section: links to the parent composition, related controls and
+Application Load fields, each with a short description. This is the last entry
+in the right-hand outline; parent links are not repeated below the page title.
+Links preserve the selected language and framework. AppLoad selector previews
+remain standalone. Source lists contain the selected `.vue` and its primary
+physical interface when one exists; imports remain supplied by the package.
+
+MainSearch owns its input/button styling. Locale and currency `codeOnly`
+controls own their compact layout and hidden accessible labels; Header supplies
+layout and defaults. `OrionplaceSelect.compact` defaults to false.
+
+Header slots `logo`, `search`, `locale`, `currency`, `account`, `wishlist`, `cart`
+and `catalog` preserve surrounding layout. Logo receives the localized home
+`label`. Search receives `label`, `buttonLabel`, `disabled`; selectors receive
+`label`, `codeOnly: true`, `disabled`; account receives `disabled`; wishlist/cart
+receive `disabled` and `compact: true`; catalog receives no props. Slot replacements
+must bind their own events. Replacing `actions` replaces its account, wishlist and
+cart slots.
+Account's `balance` slot receives `label` and `compact: true` at both wallet
+locations, preserving the surrounding wallet action.
+
+## Storefront home sections
+
+`StorefrontHome` follows the header with `MainBanner`, `CategoryGroup`, ordinary
+products, discounts, new products, `EventsBlock` and featured products. Empty sections are
+omitted. Category tiles use public catalog records, localized names and logo
+images. Category count and ordering follow `visual_settings.front_categories_*`:
+`order` sorts public roots by `ordering`, `views` includes public descendants and
+sorts by `c_views`, and `do_not_show` hides the section. Non-shortcut roots are
+preferred; when every public root is a shortcut, all public roots are included.
+Equal values preserve response order; zero count includes all candidates.
+
+`store.homeProductSections` derives four independent blocks. Ordinary products
+exclude discounted, new and featured IDs. Discounts use `discount < 1`; New uses
+`flags.flag_is_new`. A product may appear in both Discounts and New. Featured uses
+only `store.featured` and follows events. Empty blocks are hidden, and source
+order is preserved. Each section passes its own `productIds` to the same cards.
+
+If AppLoad has no new products, the generated home page uses
+`useOrionplaceHomeProducts()` after mounting to call the available `products_search` endpoint with
+`filters: { only_new: true }` and `paginate: { page: 1, pp_items: 20 }`.
+`store.setHomeNewProducts(products, sellers)` stores the confirmed products and IDs.
+A failed request can be retried explicitly. AppLoad refresh/reset clears the
+supplemental IDs and cancels stale results. The home component itself does not
+request products. The [Home guide](https://orionmarket.place/en/sandbox/components/nuxt/home#groups)
+documents the rules and lets readers edit existing products in its preview.
+
+`productLimit` defaults to 12 per section. More reveals the rest of the
+loaded section without a request. Refresh and prop changes restore the
+limit. In the Featured section, More is a link to `/featured`: an ordinary
+click emits `selectFeatured` and the generated page opens that route. `ProductGroup.limit` defaults to 0 (all records). Variant and purchase
+controls remain the supplied ProductCard controls. Home forwards their typed
+events and the generated page binds the existing product controllers. Product
+selection opens `/product/<id>` and seller selection opens `/sellers?seller=<id>`.
+Category tiles, catalog actions and linked banners open `/category/<id>`;
+the category view loads products through the discovered `products_search` endpoint.
+Selecting an event with a `promo` opens `EventEnrollmentDialog`; enrollment is
+sent with `profile_event_subscribe` only after its explicit confirmation. Events
+without `promo` do nothing in the generated page. A guest's selection opens the
+sign-in page at once; it returns to `/?event=<id>`, and the home page then opens
+the dialog for that event.
+
+Banners and events use `format: 'auto'` by default, which follows the window
+width and picks the mobile, tablet, wide or desktop image. An explicit format
+stays fixed.
+MainBanner includes every image in response order, with manual wraparound arrows
+and no autoplay. A missing format falls back to the first non-empty desktop,
+wide, tablet or mobile set. Language, data and format changes reset the slide.
+A null or omitted `category` renders an inert image with a normal cursor. A
+category ID enables the pointer cursor and emits the banner through `select`;
+the host handles the category navigation. Arrow controls only change slides.
+EventsBlock uses the same full-width image frame as MainBanner and keeps the
+image proportions inside its reserved height. One event is visible at a time, in response
+order. Multiple events show a counter and manual wraparound arrows; there is no
+autoplay. Language, format and event-data changes reset to the first event. Arrow
+buttons only change the visible event; clicking its image emits that event object.
+Event images fall back through desktop, wide, tablet, mobile and account.
+Other languages and modal-only events are not substituted into layout sections.
+
+Home slots are `banners`, `categories`, `products` and `events`. The products
+slot receives `section`, `productIds`, `collection`, `disabled` and the current
+`limit`; preserve `productIds` to retain each section’s grouping. The other slots
+receive no props. Slots render only when their section has data. Replacement
+content owns its event bindings. Source and child guides are under
+[Storefront home](https://orionmarket.place/en/sandbox/components/nuxt/home),
+[Categories](https://orionmarket.place/en/sandbox/components/nuxt/categories),
+[Banners](https://orionmarket.place/en/sandbox/components/nuxt/banners) and
+[Events](https://orionmarket.place/en/sandbox/components/nuxt/events), with matching
+Russian routes. They show the physical components in their parent with dashed
+highlights and link back to Application Load.
+
+### Visual settings, search filters and blog previews
+
+[Visual settings](https://orionmarket.place/en/sandbox/appload/nuxt/init/visual_settings)
+are consumed by the supplied Nuxt components:
+
+- [CatalogHeader](https://orionmarket.place/en/sandbox/components/nuxt/catalog)
+  uses `menu_image` for shortcut thumbnails and `catalog_menu_image` inside its catalog panel.
+- [ProductGroup](https://orionmarket.place/en/sandbox/components/nuxt/product-group)
+  becomes a swipeable row on a narrow screen. `mobile_show_arrows` controls its previous/next
+  buttons when the row overflows. Desktop grids and promotion carousels are unaffected.
+  Optional `productIds` resolves an ordered set through `productStore.getProduct`; an omitted
+  value uses the AppLoad collection, and an empty array displays no cards.
+- [SearchFilters](https://orionmarket.place/en/sandbox/components/nuxt/search-filters)
+  uses `show_filter_counters` for counts supplied in `selects` and `variants`.
+  `browseStore.preserveSearchFacets(page_data)` retains the initial options and price
+  bounds from `products_search`; `browseStore.setSearchFacets` explicitly replaces them
+  for a new scope or editor. Selection updates `browseStore.searchFilters` before
+  `change` emits copied ID arrays and scalar fields. Subsequent narrowed responses
+  update products, leaving the original selectors available. `disabled` prevents
+  selection; there are no slots.
+- `single_seller_mode` hides
+  [ProductCardSeller](https://orionmarket.place/en/sandbox/components/nuxt/productCardSeller)
+  and seller filters; manufacturer options remain visible.
+- [BlogPostGroup](https://orionmarket.place/en/sandbox/components/nuxt/blog) uses
+  `blog_view_type`: `EBlogViewType.PORTRAIT` is a grid, `EBlogViewType.LIST` is a list,
+  and `EBlogViewType.CUSTOM` starts with a lead card, followed by groups of up to
+  three posts. Unknown values fall back to portrait; numeric strings are accepted.
+  `store.setBlogPosts(page_data.posts.data)` supplies previews from `blog_posts_get`.
+  [BlogPostCard](https://orionmarket.place/en/sandbox/components/nuxt/blog-post) takes
+  `postId` and `layout` (portrait by default, list or hero), reads the post from
+  the store, and shows its localized title, plain-text preview, first ordered image
+  and reading time. The group forwards its `select` event with `IBlogPostPreview`.
+  The application opens the article; neither component loads content or changes access.
+  The group has no props; neither component has slots. Empty collections show an empty state.
+
+AppLoad refresh and reset clear search facets, selected filters and blog posts.
+The generated `/browse?q=...` and `/browse?view=blog` pages load public responses
+through endpoint discovery, handle pending/error/retry states and pagination.
+Search requires at least three characters. Search connects the shared product action and variant handlers; article and
+product-detail navigation remain host responsibilities.
+The component guides include editable settings, real components and their maintained
+source/downloads in English and Russian. Blog previews start empty when the backend
+has no posts; the JSON editor accepts `IBlogPostPreview[]`.
+
+## Category page
+
+`app/components/orionplace/categories/StorefrontCategory.vue` renders a public
+category resolved by `categoryId`, its breadcrumb path, immediate public children,
+search filters and the supplied result IDs. Names and plain-text descriptions use
+localized catalog fields; a missing/private category shows the not-found state.
+
+`app/pages/category/[id].vue` binds it to `/category/:id`. Home tiles, catalog
+category actions and linked banners open that route. The shared
+`app/layouts/default.vue` retains the header and purchase feedback across routes;
+`useOrionplaceStorefront()` supplies its product-action and variant controllers.
+A missing/private category opens the storefront error page (`app/error.vue`)
+with HTTP 404; a failed Application Load opens it with HTTP 503 and Retry.
+
+The category page loads the first result page during the server render with
+`loadProductSearchSnapshot()` and passes it to `useOrionplaceCategoryProducts()`,
+which shows it without another request. Later pages and filters call
+`products_search` in the browser, with `filters.categories` fixed to the
+selected category and its public descendants. Category changes, filter reset and AppLoad refresh
+clear filters and restart page 1. Filter changes also restart page 1. Defined
+pagination fields merge with the previous result; omitted metadata is retained.
+Pagination scrolls to the top. Requests are cancelled on replacement/unmount, and
+late responses cannot replace current results. Errors expose an explicit retry.
+Search products are cached with `setProduct`; AppLoad collections stay unchanged.
+
+The component accepts `categoryId`, `productIds` (empty by default), `page` (1),
+optional `pages` and `total`, plus `hasNext`, `pending`, `failed`, `loaded` and
+`productActionsDisabled` (all false by default). It does not issue requests or
+replace missing search results with home products. It emits `selectHome`,
+`selectCategory`, `changeFilters`, `clearFilters`, `changePage`, `retry` and the
+same typed product events as the home composition. There are no slots.
+
+`CategoryGroup.parentId` shows immediate public children in catalog order;
+omitting it preserves the home category settings. `SearchFilters.hideCategories`
+is false by default and hides the category facet for a fixed category scope.
+`ProductGroup.layout` defaults to `responsive` (desktop grid/mobile swipe row).
+The category uses `grid`, which stays a vertical grid on a narrow screen and
+shows no horizontal scroll arrows. Filters collapse behind a button in a narrow
+result container; category navigation remains available while products load.
+
+The [Category page guide](https://orionmarket.place/en/sandbox/components/nuxt/category-page)
+contains the physical composition, dashed child boundaries, local preview
+controls, field/input/event contracts and exact component/interface downloads.
+The matching Russian guide uses `/ru/sandbox/components/nuxt/category-page`.
+
+
+## Search, logout and preorder flows
+
+The [search results component](https://orionmarket.place/en/sandbox/components/nuxt/search-results)
+serves `/browse?q=...` and the category result area. It renders initial loading
+placeholders, a recoverable empty result, error/retry, totals and pagination.
+Changing the URL query starts a fresh search, including changes on an already
+open browse page. Product actions and variant replacement use the same handlers
+as home and category cards. Search requires at least three characters. The blog
+alias `/browse?view=blog` redirects to `/journal`.
+
+The generated `/featured` page renders the same results with
+`useOrionplaceFeaturedProducts()` from
+`app/composables/useOrionplaceFeaturedProducts.ts`. It adds the fixed
+`only_featured: true` filter to every `products_search` request. The filter
+panel does not show it; selected filters narrow the featured products, while
+Clear and pagination keep it. The backend returns featured products only to a
+signed-in customer, so a guest sees a short note that recommendations appear
+after sign-in; the header's Login returns to `/featured`.
+`ProductSearchResults.emptyDescription` replaces the
+empty-result hint on that page. Application Load `init.featured` remains the
+short home selection; the page loads the full list a page at a time.
+
+`useOrionplaceProductSearch()` in `app/composables/useOrionplaceProductSearch.ts`
+calls `products_search`. Components read each domain through its store hook:
+`useOrionplaceSelectionsStore()`, `useOrionplaceCatalogStore()`,
+`useOrionplaceProductsStore()` or `useOrionplaceBrowseStore()`.
+`app/stores/orionplace.ts` owns Application Load and session changes and retains
+a compatibility API for existing integrations. Smaller Pinia stores own the data: `orionplaceSelections.ts`
+(language, currency and units), `orionplaceCatalog.ts` (catalog and tariffs),
+`orionplaceProducts.ts` (products, variants and counters), and
+`orionplaceBrowse.ts` (search and journal state). Each file is under
+`app/stores/` in the generated project. The stores share the current Pinia
+instance and preview scope, so separate server requests and documentation
+previews have separate data. Application Load refresh clears dependent results
+while preserving available selections; reset clears them all.
+
+The search flow fills these values in the browse and product stores:
+
+| Store value | How it is filled |
+| --- | --- |
+| `browseStore.searchFacets` | `preserveSearchFacets()` retains `page_data.selects` and `page_data.variants` from a successful search response. |
+| `browseStore.searchFilters` | `SearchFilters` writes selected conditions before emitting `change`. |
+| `productStore.productUpdates.products` | `setProduct()` saves each item from `page_data.products.data` by ID. Cards read it through `getProduct()`. |
+
+The pages pass result IDs, pagination and loading state from the composable to
+`ProductSearchResults` as inputs.
+
+The optional second argument of `useOrionplaceProductSearch()` accepts a
+`request(body, signal)` callback for an existing API client. It must return the
+validated `products_search` page data and reject failed requests. Without it,
+the supplied API client resolves `products_search` from Application Load. Set
+`scrollToTop: false` when the results are a section further down the page, then
+call `scrollToPaginatedList()` from `app/utils/orionplace/paginationScroll.ts`
+with that section after a page change. The seller page does this for its
+products, so pagination returns to the products heading.
+
+`useOrionplaceProductSearch` preserves the first confirmed selector set for the
+current query/category. Further filters, empty results and pagination do not
+replace options, colors, counts or price bounds with narrowed responses. New
+queries, categories and AppLoad refreshes reset that scope; Clear keeps
+its original selectors. Superseded requests are cancelled and ignored.
+
+`SearchFilters` supplies cumulative ID arrays and scalar price, discount and
+rating fields. Currency-keyed `selects.measures.min_price` and `max_price` supply
+the price range; Apply or a committed slider change emits `price_from`,
+`price_to` and `price_currency`. Selecting the full range removes the price
+constraint. Currency changes clear only price constraints. Color values render
+beside variant labels. Minimum discount uses `price_discount_from`; product/seller
+ratings and review availability use the corresponding API filters. Original
+counts describe the initial scope, not the narrowed result. Product grids use
+fewer columns as the container narrows. Mobile home
+rows retain their existing swipe behavior.
+
+The [preorder dialog](https://orionmarket.place/en/sandbox/components/nuxt/preorder-dialog)
+is `app/components/orionplace/products/ProductPreorderDialog.vue`, nested under
+Product actions in Components. The default layout opens it for the card's
+`preorder` event. It shows the product and price; guests provide email or phone.
+`submit` emits `{ product, email, phone }`, with trimmed contact strings. The host
+checks eligibility, calls `preorders_create`, and closes only after success.
+Pending requests disable resubmission and dismissal. Errors remain by the form.
+`modal` defaults to true; false renders the same dialog within its container.
+Both storefront and documentation product previews use this physical component.
+
+The [sign-out component](https://orionmarket.place/en/sandbox/components/nuxt/logout)
+is `app/components/orionplace/account/StorefrontLogout.vue`, under Profile menu.
+The default layout opens `/logout` after `signOut`. The route shows progress,
+uses `profile_logout` through the shared API client after mounting, refreshes
+AppLoad after confirmation and replaces the route with the localized home page.
+Failed logout leaves confirmed account data intact. Failed guest initialization
+after successful logout retries only AppLoad, without repeating the mutation.
+The presentation component emits `retry` and `selectHome`; its documentation
+preview never signs out the reader.
+
+These components' Russian guides use the matching `/ru/sandbox/components/nuxt/`
+URLs. They include real composition previews, dashed child boundaries, state
+controls, event contracts, related references and physical source downloads.
+
+## Personal profile, footer and stable layout
+
+The supplied Nuxt storefront includes `/profile` with personal details, avatar,
+verified email, optional email-notification and email-language preferences, password management,
+phone sign-in/registration and navigation to `/logout`. Account requests use the
+shared named API client, which sends the selected storefront language as `lang`;
+registration saves it as the account's initial email-notification language.
+Avatar upload uses multipart. Data changes only after confirmation. See the
+[profile guide](https://orionmarket.place/en/sandbox/components/nuxt/profile)
+and its [Russian version](https://orionmarket.place/ru/sandbox/components/nuxt/profile).
+
+The sign-in and registration form (`ProfileSignIn`) appears only on the
+`/profile` page. Header Login links there. A guest's click on an action that
+needs an account (a review, reaction or reply, a blog comment, the wishlist
+heart, an availability notification, Checkout in the cart, a plan's Subscribe
+or Try, an event) opens `/profile?locale=<locale>&redirect=<current page>` at
+once through `useOrionplaceSignIn().requireSignIn()` in
+`app/composables/useOrionplaceSignIn.ts`, with no separate sign-in notice.
+Background requests and an ended session never navigate.
+Account pages (`/orders`, `/wallet`, `/addresses`, `/subscriptions`, `/tickets`,
+`/activity`, `/wishlist`) declare the `orionplace-account` route middleware in
+`app/middleware/orionplace-account.ts`: after Application Load confirms a guest
+session, it replaces the page with that sign-in address. A pending or failed
+Application Load keeps the page, and no dialog opens automatically.
+
+After the final sign-in step, a ring spinner and a moving progress line replace
+the form while Application Load refreshes; the top loading bar runs and screen
+readers receive “Signing in…”. With reduced motion, both indicators stay still.
+The profile page then opens the `redirect` page, or the home page when it is
+missing, and keeps the indicator until that page opens.
+`app/utils/orionplace/signInReturn.ts` accepts only paths on the same storefront
+that start with a single `/`; `/profile`, `/logout` and external addresses open
+the home page instead. If the refresh fails, the form shows an error with Retry,
+which refreshes Application Load without resending credentials.
+Returned field errors stay beside their inputs and `form_errors.__all__` stays
+in the general error notice, including after a development module reload. The
+generic retry message appears only when no structured API error reaches the
+form.
+
+Messages share one square pattern from `components/orionplace/shared/features.css`:
+`op-notice op-notice-error` uses the danger colors, an error icon and
+`role="alert"`; `op-notice op-notice-success` uses the success colors, a check
+icon and `role="status"`; `op-notice op-notice-attention` uses the attention
+colors and a warning icon for a step still to complete, such as choosing a
+delivery method; plain `op-notice` is neutral information. Pending work shows
+the top loading bar from `app/app.vue` and a visually hidden `role="status"`
+message instead of a status strip. Field errors stay as red text beside their inputs. Required fields show a
+red `*` directly after the label text.
+
+The default layout renders the [footer](https://orionmarket.place/en/sandbox/components/nuxt/footer)
+with real store categories, home-section anchors, profile/journal navigation,
+a contact-page link and social links. On `/contact`, `StorefrontContact` places
+company details (address, `tel:` phone link, registration numbers with copy
+buttons and social links) in a column beside the bordered message-form panel;
+the columns stack on narrow screens and empty details are hidden.
+The home banner spans the available viewport
+width without a frame. Its media area keeps the same proportions at every width; the image fills the
+area without distortion and crops its edges when needed. Event media keeps its
+own reserved proportions, which differ on a narrow screen.
+
+Search/category filtering keeps current cards during requests and reserves the
+results area's height when a response is shorter. Product variant replacement
+retains card height. Width changes release these reserves for responsive layout;
+a new search scope resets its reserve. Stable scrollbar space avoids horizontal
+shifts. Initial search loading uses 12 skeletons. The wishlist heart appears
+for every visitor, including compact catalog representatives; a guest's click
+opens the sign-in page.
+
+The React and Svelte packages supply the corresponding storefront and account UI.
+
+## Customer API storefront sections
+
+The Nuxt starter includes native product details/reviews, cart and checkout,
+orders and downloads, support conversations, account addresses, wallet,
+search history, sign-in history, promotion codes, wishlist/availability alerts,
+journal/comments, contact form, email unsubscribe, event enrollment and
+manufacturer/seller/store/catalog directories. A seller page shows the seller's
+photos, products and the reviews of all their products. `/tariffs` lists subscription
+plans with their periods, trials, explained plan modules and limits, and a
+chooser for the plans that offer more than one option, and
+`/tariffs?ids=3,7` narrows the page to the listed plans, as a journal article
+that needs a plan links to it. `/tariffs/:slug/:id` shows one plan with its
+media, description, features and purchase choices. Guests sign in
+through links that return to the chosen plan; signed-in customers confirm the
+purchase in a dialog that links to `/subscriptions` afterwards. The account shows
+purchased subscriptions and disabling automatic renewal. Choosing a new renewal period is not yet supplied.
+
+See [`templates/orionplace/COMPONENTS.md`](templates/orionplace/COMPONENTS.md)
+for the maintained route/component/endpoint table. Components use the named
+API client, confirmed mutation results and English/Russian labels. Customer
+source bundles include transitive dependencies and installation guidance.