orionplace-nuxt 0.1.2 → 0.2.0

package/README.md

@@ -7,31 +7,47 @@ that is copied into your project alongside an integration README.
 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
-
-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.
+## Android app
+
+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.
 
-You can also scaffold before installing:
+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
+
+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 +55,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 +69,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,10 +83,34 @@ 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.
+
 ## Commands
 
 ```bash
 npx orionplace-nuxt init [directory]
+npx orionplace-nuxt update
 npx orionplace-nuxt set backend your-project.orionplace.app
 npx orionplace-nuxt add frontend shop.example.com
 npx orionplace-nuxt add frontend www.shop.example.com
@@ -79,6 +128,7 @@ npm run orionplace:add-frontend -- shop.example.com
 npm run orionplace:remove-frontend -- www.shop.example.com
 npm run orionplace:mimic -- shop.example.com
 npm run orionplace:help
+npm run orionplace:update
 ```
 
 `npm set` belongs to npm's own configuration system; use the commands above.
@@ -91,18 +141,19 @@ 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,
 reporting which files were preserved. Unchanged generated files can be refreshed
-by running `init` after upgrading the package. A manually edited domain file is
+with `npx orionplace-nuxt update`. A manually edited domain file is
 never silently overwritten. Keep the hash manifest in version control.
 
 ## Multiple frontend domains
@@ -159,14 +210,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
@@ -174,4 +244,621 @@ npm pack --dry-run
 ```
 
 The published tarball includes only the CLI, module, runtime source, README,
-license, and package metadata.
+license, starter templates, and package metadata.
+
+## Application Load starter
+
+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:
+
+```bash
+npx orionplace-nuxt update
+```
+
+It runs the latest CLI, adds new template files, refreshes unchanged generated
+files, updates the package dependency and runs `npm install` to synchronize the
+lockfile and installed dependencies. Edited files are preserved and listed in the
+output. Review their new versions under `node_modules/orionplace-nuxt/templates`
+or `runtime` and merge your changes manually when needed. Removed upstream files
+are retained locally; the updater does not delete customer source.
+
+Domain mappings, domain settings and `.env` remain unchanged. The command does
+not deploy your application: restart development, or rebuild and redeploy the
+production frontend after updating.
+
+```bash
+npx orionplace-nuxt update --dry-run
+npm run orionplace:update
+```
+
+Dry-run downloads the latest CLI into npm's cache to inspect its templates but
+leaves project files and dependencies unchanged. `update --local` applies the
+version of the CLI being executed instead of fetching the latest CLI; it still
+installs project dependencies. Use this only when intentionally selecting a version.
+
+For a project on 0.1.2 or older, bootstrap the new command once:
+
+```bash
+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.