orionplace-nuxt 0.1.2 → 0.2.0

package/src/project-readme.mjs

@@ -7,9 +7,35 @@ This folder contains the integration source for your Nuxt 4 storefront.
 Your personal backend API is provided in your account at https://orionmarket.place.
 You can change that backend domain in your account, then update this project.
 
+## Quick start from zero
+
+Install Node.js 22.12 or newer (including npm). Run these commands from the folder
+where you want to create a new project; no existing Nuxt project is needed:
+
+\`\`\`bash
+npx --yes orionplace-nuxt init my-marketplace
+cd my-marketplace
+npm install
+npx orionplace-nuxt set backend your-project.orionplace.app
+npx orionplace-nuxt add frontend shop.example.com
+npm run dev
+\`\`\`
+
+Replace \`your-project.orionplace.app\` with the personal backend domain shown in
+your profile at [orionmarket.place](https://orionmarket.place), and
+\`shop.example.com\` with your storefront domain. The first frontend also 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 the domain
+mapping and backend response.
+
+This project is already generated. To configure or run it, use the following
+sections from its root directory; do not create another project inside it.
+
 ## Current setup
 
-- Frontend domains: ${settings.frontends?.length ? settings.frontends.map(domain => '\`' + domain + '\`').join(', ') : 'not configured yet'}
+- Frontend domains: ${settings.frontends?.length ? settings.frontends.map((domain) => '\`' + domain + '\`').join(', ') : 'not configured yet'}
 - Local MIMIC domain: \`${settings.frontend || 'empty'}\`
 - Personal API: \`${settings.backend || 'not configured yet'}\`
 
@@ -51,12 +77,74 @@ request; restart or reload the process environment when changing MIMIC. DNS, TLS
 and hosting-proxy settings must also cover each public frontend domain.
 Existing unrelated environment variables and Nuxt configuration are preserved.
 
+## 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; 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.
+
+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\` link, social links and the company name in its copyright line.
+Company contact and registration details appear beside the message form on
+\`/contact\`. 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.
+
 ## Files you can read and customize
 
 | File | Purpose |
 | --- | --- |
 | \`runtime/marketplace.mjs\` | Domain lookup, configuration validation, API transport and cookies. |
-| \`runtime/api.mjs\` | The Nuxt/Nitro HTTP handler for \`/api/**\`. |
+| \`runtime/api.mjs\` | The Nuxt/Nitro HTTP handler for \`/api/**\` and blog media under \`/ps3/blog/**\`. |
 | \`runtime/domain.mjs\` | Resolves the frontend domain into the request context. |
 | \`settings.json\` | The CLI's frontend list, local MIMIC domain and personal backend; not a secret store. |
 | \`../sitemaps/${frontend}.cfg\` | The backend URL used for this frontend domain. |
@@ -67,6 +155,12 @@ The module registers these local source files with Nitro. You can edit them;
 subsequent setup runs preserve customized runtime files and this README.
 The CLI refuses to overwrite an unknown or manually changed domain mapping.
 
+## 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.
+
 ## How requests reach your personal API
 
 The trusted hosting proxy supplies the public domain through \`X-Front-Domain\`,
@@ -84,6 +178,23 @@ directory. Set \`SITEMAPS_DIR\` only if you store it elsewhere. Runtime configur
 does not set a fixed public site URL. The middleware exposes the active domain
 as \`event.context.marketplaceDomain\`; use it when implementing your page metadata.
 
+## Nuxt compatibility date
+
+Setup adds \`compatibilityDate: '2025-07-15'\` to \`nuxt.config.ts\` when the setting
+is missing. This pins the existing fallback and prevents warning \`NUXT_B5001\`.
+An existing date is preserved during setup and updates.
+
+For an older generated project, add this property inside its existing
+\`defineNuxtConfig({ ... })\` object, keeping the other settings:
+
+\`\`\`typescript
+compatibilityDate: '2025-07-15',
+\`\`\`
+
+Restart the development server afterward. The date controls compatibility
+behavior; it does not need to match today's date. See the
+[Nuxt configuration reference](https://nuxt.com/docs/4.x/api/nuxt-config#compatibilitydate).
+
 ## Start and verify
 
 Use Node.js 22.12 or newer. After scaffolding a new project, install dependencies:
@@ -98,53 +209,307 @@ In another terminal:
 \`\`\`bash
 curl -i http://localhost:3000/api/appload \\
   -H 'Content-Type: application/json' \\
-  --data '{"ignore_cache":true,"detalize_mode":"full"}'
+  --data '{"ignore_cache":false,"detalize_mode":"light"}'
 \`\`\`
 
 Check both the HTTP status and \`form_errors\`. Successful initialization returns
 \`page_data\`; HTTP 200 by itself is insufficient. Documentation and public requests
 do not require a login prompt. Protected actions still require backend permission.
 
-Browser requests use the storefront's own API path:
-
-\`\`\`javascript
-const response = await fetch('/api/appload', {
-  method: 'POST',
-  credentials: 'same-origin',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ ignore_cache: true, detalize_mode: 'full' }),
-});
-const result = await response.json();
-console.log(response.status, result);
-\`\`\`
-
-For SSR, use Nuxt's \`useRequestFetch()\` so the request's domain, cookie and
-authorization headers reach the same gateway. For example, in \`app/app.vue\`:
+## Application Load architecture
+
+Global route middleware initializes the marketplace before page setup. The
+request uses \`POST /api/appload\` with
+\`ignore_cache: false\`. Tenant settings may override these options.
+
+The CLI registers \`@pinia/nuxt\`, installs Pinia and enables Nuxt pages.
+\`app/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; the initial
+\`app/pages/index.vue\` renders categories, product collections, banners and events.
+Initialization failures offer an explicit retry.
+\`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. Error
+pages use \`noindex, nofollow\` and never show 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.
+\`/product/: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. 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 \`/product/:id?key=<preview key>\` address 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\`. A failed request keeps the page with its Retry
+button.
+Existing custom apps and index pages are preserved; render \`NuxtPage\` in your own app to display route pages.
+
+| Project file | Responsibility |
+| --- | --- |
+| \`app/middleware/00.orionplace.global.ts\` | Awaits initialization before pages and later route middleware. |
+| \`app/stores/orionplace.ts\` | Loads Application Load, handles session changes and keeps the \`useOrionplaceStore()\` API for components. |
+| \`app/stores/orionplaceSelections.ts\` | Holds the selected language, currency and units. |
+| \`app/stores/orionplaceCatalog.ts\` | Holds the catalog and tariff lists, including later replacements. |
+| \`app/stores/orionplaceProducts.ts\` | Holds product updates, variants, home groups and cart/wishlist counters. |
+| \`app/stores/orionplaceBrowse.ts\` | Holds the search query, filters, facets and journal posts. |
+| \`app/composables/useOrionplaceAppLoad.ts\` | Request-aware transport and explicit initialize, refresh and reset actions. |
+| \`app/utils/orionplaceAppLoad.ts\` | HTTP, form-error and bootstrap-envelope checks. |
+| \`app/interfaces/orionplace/index.ts\` | Response envelope and all nested models. |
+
+### Application Load components
+
+[COMPONENTS.md](COMPONENTS.md) maps initialization fields to their consumers and
+lists the installed components and source files. Configuration, session flags
+and shared counters have data references linked to the relevant features.
+Components are grouped by feature under
+\`app/components/orionplace/\`. Components read the initialized store directly;
+no additional Application Load request is needed.
+
+The [field sandboxes](https://orionmarket.place/en/sandbox/appload/nuxt) display
+these same source files and interfaces. Selections emit events for your
+application to handle; they do not perform account, cart or subscription requests.
+
+### Language selector
+
+\`app/components/orionplace/locale/MainLanguageSwitcher.vue\` reads
+\`store.locales\` and displays the available languages with their flags.
+Selection updates the shared language and its default currency and units.
+The selector uses Tailwind utilities and needs no translation plugin.
+
+Setup installs Tailwind CSS 4 and its Vite plugin. Existing Tailwind 3 installations
+must be upgraded first; setup rejects incompatible versions before writing files.
+The Orionplace module registers
+\`app/assets/css/orionplace.css\` for the generated components and pages, reusing an
+existing Tailwind Vite plugin. It supplies utilities without replacing your CSS
+reset or theme. The selector uses utility classes and needs no Sass. Keyboard
+focus uses its existing border and background, without outlines.
+
+The optional \`label\` defaults to Language; \`disabled\` defaults to false.
+The store starts with its first available language. Selection calls
+\`store.setLocale(code)\`, updating \`store.localeCode\` and that language's default
+currency and units, then emits \`change\` with the locale object. Navigation and
+translation plugin integration remain your application's responsibility.
+Empty data disables selection. Missing names use another translation, the human
+name or the language code.
+
+Flags from \`flag_img\` appear beside the selected language and its dropdown options.
+Missing or failed images leave the names readable. Use arrow keys or type a name
+or code to find a language; Enter, Space or Tab confirms it. Escape or an outside
+click closes the list without applying 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.
+
+### Themes
+
+Define your themes in \`app/themes/orionplace.ts\`. Add as many entries as your
+storefront needs; components inherit the active palette automatically.
+The shared [theme guide](./THEMES.md) explains configuration and selection.
+
+### Read data in a page or component
+
+Middleware loads the data; reading the store does not send another request.
+Use \`storeToRefs\` when destructuring reactive properties:
 
 \`\`\`vue
-<script setup>
-const requestFetch = useRequestFetch();
-const { data, error } = await useAsyncData('marketplace-initialization', () =>
-  requestFetch('/api/appload', {
-    method: 'POST',
-    body: { ignore_cache: true, detalize_mode: 'full' },
-  }),
-);
+<script setup lang="ts">
+import { usePinia } from '#imports';
+import { storeToRefs } from 'pinia';
+import { useOrionplaceStore } from '@/stores/orionplace';
+
+const marketplace                                        = useOrionplaceStore(usePinia());
+const { isReady, status, failure, products, currencies } = storeToRefs(marketplace);
 </script>
 
 <template>
   <main>
-    <p v-if="error">The marketplace API is currently unavailable.</p>
-    <pre v-else>{{ data }}</pre>
+    <p v-if="failure" role="alert">Marketplace initialization failed.</p>
+    <p v-else-if="!isReady" role="status">Application Load: {{ status }}</p>
+    <p v-else>{{ products.length }} products; {{ Object.keys(currencies).length }} currencies.</p>
   </main>
 </template>
 \`\`\`
 
-Keep private data out of shared caches. This SSR example forwards incoming cookies;
-it does not relay new upstream cookies to the browser. Make session-changing calls
-from the browser, or explicitly append each returned Set-Cookie header to the SSR
-response in your server integration.
+The \`@/\` alias resolves to \`app/\`, so these imports also work from nested
+page and component folders.
+
+| Store property | Available data |
+| --- | --- |
+| \`result\` | Response envelope, HTTP status and load time. |
+| \`data\` | Complete \`page_data\`, including optional sections. |
+| \`init\` | All initialization settings, banners, events, contacts, SEO, units and other sections. |
+| \`profile\`, \`isAuthenticated\` | Current profile and session state. |
+| \`locales\`, \`currencies\`, \`catalog\`, \`products\`, \`tariffs\` | Reactive access to common initial collections. |
+| \`publicEndpoints\`, \`authenticatedEndpoints\`, \`endpoints\` | Current discovery groups and their combined view. |
+| \`isReady\`, \`status\`, \`failure\` | Readiness, loading/success/error state and sanitized failure details. |
+
+Use \`marketplace.getEndpoint(section, name)\` with section and endpoint keys
+from the current response. It returns the endpoint's target, methods and forms,
+or \`undefined\` when unavailable. Some endpoint descriptions may be omitted.
+Discovery describes availability; the backend checks permissions on every call.
+
+### Refresh after a session change
+
+Capture actions during setup and invoke them from your explicit login/logout or
+reload flow. Reading the composable does not initialize Application Load:
+
+\`\`\`typescript
+import { useOrionplaceAppLoad } from '@/composables/useOrionplaceAppLoad';
+
+const { reset, refresh } = useOrionplaceAppLoad();
+async function afterSessionChanged() {
+  reset();
+  await refresh();
+}
+\`\`\`
+
+Call this after the session-changing API request has completed. Reset clears the
+profile, initialization and discovery, aborts pending initialization and prevents
+late responses restoring the old session. Refresh replaces the whole snapshot.
+On failure, stale data and permissions remain cleared; the store exposes the error.
+
+### Session and CSRF cookies
+
+Session and CSRF cookies travel in HTTP headers, not in the initialization JSON.
+Keep the signed HttpOnly \`sessionid\` opaque: the browser sends it automatically.
+Never log, decode, rewrite or put cookie values in Pinia or localStorage.
+Read the current \`csrftoken\` for each protected browser action and send it as
+\`X-CSRFToken\` through the same-origin \`/api/\` gateway with credentials enabled.
+Login can rotate the token. The shared \`OrionplaceApi\` client owns initialization and discovered browser
+requests. \`useOrionplaceApi()\` creates one instance per Nuxt application. It
+resolves current discovery and handles CSRF renewal; components send discovered
+requests in the browser. Page data for the server render uses
+\`useOrionplaceServerApi()\`, the same class and transport, through
+\`useOrionplaceServerData()\`; the browser hydrates that result without a
+second request.
+
+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, and relays each raw \`Set-Cookie\`
+separately. That cookie list belongs to one render; never share it across
+visitors.
+
+Renew CSRF using \`POST /api/csrf_renew\` with \`{}\`, then re-read the cookie.
+HTTP \`419\`, or HTTP \`403\` with \`page_data.csrf: false\`, means CSRF
+rejection; a \`403\` without that flag can mean permissions or origin rejection. Offer explicit retries for
+mutations. After confirmed login/logout, reset and refresh Application Load; these actions
+change application data and do not log in/out 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.
+
+[Cookie lifecycle and browser request example](https://orionmarket.place/en/sandbox/appload/nuxt#session-cookies)
+
+### SSR, navigation and failures
+
+Each SSR request gets its own Pinia instance. The loader forwards the incoming
+domain and session and relays new response cookies to the browser. Pinia hydrates
+the result, so hydration and later client navigation do not repeat initialization.
+Concurrent initialization calls share one request within that instance.
+
+Failures also survive hydration and navigation. They never open a login modal or
+trigger an automatic retry on every route. Show the error and offer explicit
+reload. Feature components should check \`isReady\` before using required data.
+
+Page responses use \`private, no-store\`. Do not put personalized HTML in shared
+caches or persist the snapshot in localStorage. The storefront page displays
+public content and the account menu. Raw initialization payloads, keys and
+backend exception stacks are not rendered there.
+
+Interfaces cover initialization, discovery/forms, profile and nested models.
+Plugin-defined configuration uses JSON types; interfaces are not full runtime
+validation of every nested field. Existing edited generated source is preserved;
+review and merge newer templates manually where the CLI reports preserved files.
+
+## Storefront header
+
+Browse [Components](https://orionmarket.place/en/sandbox/components/nuxt) for the
+Header composition and its search, language, currency, profile, wallet and catalog
+children, with live previews and source downloads. Russian guides are available too.
+
+The default layout renders \`StorefrontHeader\` above every page, including the
+StorefrontHome sections. It combines catalog navigation with Manufacturers and
+Journal links, search, language/currency selection, the account menu and
+wishlist/cart buttons. English and Russian labels
+follow the shared storefront locale.
+\`StorefrontAccount\` adds guest sign-in and an authenticated profile/wallet menu.
+The generated layout opens \`/profile\` for sign-in and profile selection;
+after sign-in, the user returns to the page passed in \`redirect\`,
+\`/wallet\` for wallet selection and \`/logout\` for sign-out. No credentials or
+payments are submitted by these presentation components. The balance follows
+the selected currency, preserves zero and uses a dash for missing amounts.
+After confirmed authentication changes, refresh Application Load to replace the
+session, profile, wallet and discovery. See the [account guide and source downloads](https://orionmarket.place/en/sandbox/appload/nuxt/init/is_authenticated).
+The wishlist and cart buttons display \`store.counters\`: initial Application Load
+counts, updated by confirmed product actions. The wishlist button opens
+\`/wishlist\`; the cart button opens the cart preview, whose product and full-cart
+selections open \`/product/:id\` and \`/cart\`. Search opens
+\`/browse?q=...\`; the Manufacturers and Journal links open /manufacturers and
+/journal; catalog selections open /category/:id, product selections open
+/product/:id and seller selections open /sellers?seller=<id>. Variant selection replaces the
+whole representative card; missing products and secondary choices are loaded
+through the shared API client. Purchase, wishlist, notification and preorder
+events run the shared product action controller. The header's \`actions\` and \`catalog\` slots support those
+integrations. See [the header contract](./COMPONENTS.md#storefront-header).
+
+## Storefront home
+
+The initial page renders banners and categories, then ordinary products, discounts,
+new products, events and non-empty featured recommendations through
+\`StorefrontHome\`. Category tiles follow the storefront's count and ordering
+settings. Each product section shows its first records; More
+expands that section independently, except in Featured, where it opens
+/featured. Discounted, new and featured IDs are excluded
+from the ordinary section. New products may also belong to Discounts. If AppLoad
+has no new products and products_search is available, a browser request loads up
+to 20 with the only_new filter. Banners and layout events use the selected locale and responsive image formats. Both display full-width carousels
+with manual slide controls. Empty sections stay hidden.
+Category tiles, catalog actions and linked banners open /category/:id.
+The /featured route lists the signed-in customer's featured products with the
+same filters and pagination, using the fixed only_featured search filter; guests
+see a short note that recommendations appear after sign-in.
+The category route includes public descendants, filters and paged products,
+with a vertical mobile grid. The shared default layout keeps the header and
+purchase feedback available across routes. Product selections open /product/:id
+and seller selections open /sellers?seller=<id>. Selecting an event with a promotion
+opens the enrollment dialog; enrollment is sent only after its explicit
+confirmation. Existing product controllers handle variants and purchase actions.
+
+See [the home composition](./COMPONENTS.md#storefront-home-sections) and the
+[Components guide](https://orionmarket.place/en/sandbox/components/nuxt/home)
+for child contracts, settings, events, slots and physical source.
+
+## Update the package and components
+
+Run this from your project root whenever you want the latest release:
 
+\`\`\`bash
+npx orionplace-nuxt update
+\`\`\`
+
+The command fetches the latest CLI, adds new template files, refreshes unchanged
+generated source, updates the package dependency, and runs \`npm install\`.
+It preserves edited files and lists them for manual review. Find their incoming
+versions under \`node_modules/orionplace-nuxt/templates\` or \`runtime\`.
+Domain mappings, domain settings and \`.env\` are preserved. Upstream file removals
+do not delete local source. Restart development or rebuild and redeploy afterward.
+
+Use \`npx orionplace-nuxt update --dry-run\` to review changes without modifying
+project files or installed dependencies; downloading the CLI may update npm's
+cache. The alias \`npm run orionplace:update\` performs the same normal update.
+If installation fails after source generation, run \`npm install\` and retry.
 
 ## Deploy on your VPS
 
@@ -181,10 +546,117 @@ remote personal API from the domain file. The proxy must overwrite those headers
 An unknown domain never falls back to another tenant. This setup does not generate
 sitemap XML or add analytics.
 
+## Android app
+
+Deploy the website first, then build the app with Capacitor 8. With
+\`ORIONPLACE_APP_ORIGIN\` set to your public storefront (HTTPS) the build is
+client-only and sends every API request to that storefront through Capacitor's
+native HTTP (\`app/utils/orionplace/nativeApp.ts\`). Without the variable the
+website build is unchanged. Steps:
+[Android app guide](https://orionmarket.place/en/sandbox/android-app).
+
+\`\`\`bash
+ORIONPLACE_APP_ORIGIN=https://shop.example.com npx nuxt generate
+npx cap sync android
+\`\`\`
+
 ## More documentation
 
-- [Nuxt project setup](https://orionmarket.place/sandbox/new-project/nuxt)
-- [Domain setup and direct Nginx alternative](https://orionmarket.place/sandbox/backend-domain/nuxt)
-- [AppLoad](https://orionmarket.place/sandbox)
+- [Nuxt package installation and domain setup](https://orionmarket.place/en/sandbox/new-project/nuxt)
+- [Application Load](https://orionmarket.place/en/sandbox)
+
+## 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/notifications report the need
+for 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.
+
+### 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 \`store.getProduct\`; an omitted
+  value uses the AppLoad collection, and an empty array displays no cards.
+- [Search results](https://orionmarket.place/en/sandbox/components/nuxt/search-results)
+  retain initial selector choices, support currency price ranges and color filters,
+  and display loading, empty and failure states.
+- [Preorder dialog](https://orionmarket.place/en/sandbox/components/nuxt/preorder-dialog)
+  is shared by storefront and documentation product previews.
+- [Sign-out page](https://orionmarket.place/en/sandbox/components/nuxt/logout)
+  calls profile_logout at /logout, then refreshes guest AppLoad and returns home.
+- [Category page](https://orionmarket.place/en/sandbox/components/nuxt/category-page)
+- [SearchFilters](https://orionmarket.place/en/sandbox/components/nuxt/search-filters)
+  uses \`show_filter_counters\` for counts supplied in \`selects\` and \`variants\`.
+  \`store.preserveSearchFacets(page_data)\` retains the initial options and price
+  bounds from \`products_search\`; \`store.setSearchFacets\` explicitly replaces them
+  for a new scope or editor. Selection updates \`store.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. The backend currently returns false.
+- [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.
+Text search requires at least three characters. A seller, manufacturer or store
+selection can define the product scope without a text query. Product links open
+/product/:id and journal entries open /journal/:id. Search uses the shared
+purchase handlers.
+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[]\`.
+
+## Customer account and shopping flows
+
+The generated application supplies cart/checkout, order history and attachments,
+support conversations, saved addresses, wallet, wishlist/availability alerts,
+search history, sign-in history, promotion codes, product reviews, journal
+comments, contact form, email unsubscribe, event enrollment and public
+manufacturer/seller/store/catalog directories. \`/tariffs\` lists subscription
+plans with their periods, trials, named plan parameters and options, and
+\`/tariffs/:slug/:id\` shows one plan in the product-detail layout. 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 subscription
+account lists dates and can disable automatic renewal. Choosing a new renewal period is not yet supplied.
+
+[COMPONENTS.md](COMPONENTS.md) maps these routes to maintained components and
+endpoint names. API requests use the discovered method and URL, the current
+session, CSRF and confirmed response handling. Account sections mount after
+sign-in. Failed reads preserve existing content; form errors preserve drafts.
+Physical components, their composables, styles and English/Russian labels are
+installed from this package. Source ZIPs include their imported dependencies;
+see [COMPONENT-DOWNLOAD.md](COMPONENT-DOWNLOAD.md) for consumer configuration.
+
+Catalog refresh replaces the current catalog through store.setCatalogTree().
+Tariff search replaces the current plan list through store.setTariffs(). A new
+Application Load clears those overrides. Confirmed cart and wishlist changes
+update already-loaded product cards, including featured and secondary variants.
 `;
 }