orionplace-svelte 0.1.0 → 0.2.1

package/README.md

@@ -1,12 +1,69 @@
 # orionplace-svelte
 
-Set up a SvelteKit 2 storefront for your personal Orionplace marketplace API.
-The package includes a setup CLI, the SvelteKit starter with typed AppLoad
-initialization, and commented server source that is copied into your project
-alongside an integration README.
+**A complete SvelteKit 2 storefront for your Orionplace marketplace, set up with one command.**
+
+`orionplace-svelte` 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
+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-sveltekit-2-project) · [Components](#components) ·
+[Commands](#commands) · [Android app](#android-app) ·
+[Update](#update-an-existing-project)
 
 Requires Node.js 20.19+, Svelte 5 and `@sveltejs/adapter-node`. Static and
-edge-only adapters cannot read the domain files this integration uses.
+edge-only adapters cannot read the domain files this integration uses; only the
+Android app build below uses `@sveltejs/adapter-static`.
+
+## 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: `androidAppKit` in `svelte.config.js` (`orionplace/runtime/app.mjs`)
+then builds a client-only app to `build/` with `@sveltejs/adapter-static`. The
+route server loads run in the app as universal loads
+(`src/lib/orionplace/appRoutes.ts`), and every API request goes to
+`<origin>/api/...` through Capacitor's native HTTP with the storefront Origin
+(`src/lib/utils/orionplace/nativeApp.ts`). A route with its own server load
+stops the app build with its path. 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 the website build is
+unchanged. Setup, build and release steps:
+[Android app guide](https://orionmarket.place/en/sandbox/android-app?framework=svelte).
+
+```bash
+npm install -D @sveltejs/adapter-static
+ORIONPLACE_APP_ORIGIN=https://shop.example.com npx vite build
+npx cap sync android
+```
+
+## Error pages
+
+`src/routes/+error.svelte` uses the native `StorefrontErrorPage` for missing
+pages and unhandled errors. Its title, description, keywords and HTML language
+follow the selected locale. Error pages use `noindex, nofollow`. Home and Catalog
+keep the locale; Retry reloads the current address. Failure pages render without
+the storefront header and footer.
+
+## Asset loading
+
+The starter loads route code and route data after pointer or keyboard
+interaction instead of preloading every visible link. New storefront images
+must provide intrinsic dimensions or a stable aspect ratio; the package audit
+checks this rule for every maintained Svelte template.
 
 ## Quick start from zero
 
@@ -28,9 +85,9 @@ npm run dev
 
 The first command creates the SvelteKit configuration, starter routes and
 integration README. The first frontend becomes the local MIMIC domain. Open the
-local URL printed by Vite (normally http://localhost:5173); the starter's AppLoad
-state should show `Loaded`. If it shows `Failed`, check your domain mapping and
-backend response. The backend command accepts either a hostname or its full HTTPS
+local URL printed by Vite (normally http://localhost:5173). The storefront shows
+the catalog, products and events returned by Application Load. If initialization
+fails, it shows a retry action; 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 SvelteKit 2 project
@@ -55,6 +112,205 @@ 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.
 
+## Import aliases
+
+Application imports use `@/`. Add these entries to `kit.alias` in your existing
+`svelte.config.js` (or its `.ts`/`.mjs` equivalent), keeping the Node adapter and
+other settings. New projects already contain them:
+
+```javascript
+alias: {
+  '@': './src',
+  '@orionplace-runtime': './orionplace/runtime',
+},
+```
+
+SvelteKit applies them to both Vite and the generated TypeScript configuration.
+The gateway stays in the project-root `orionplace/runtime/` directory. Framework
+imports such as `$app`, `$env` and generated `./$types` retain their own names.
+
+<!-- components:start (generated by scripts/generate-package-readme-components.mjs) -->
+## Components
+
+The starter includes **124 storefront components**, copied into
+`src/lib/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
@@ -89,20 +345,28 @@ change your account, create DNS records, configure TLS, or deploy a VPS.
 | Path | Purpose |
 | --- | --- |
 | `src/routes/api/[...orionplace]/+server.ts` | Route serving `/api/...` from your project. |
-| `src/routes/+layout.server.ts` | Initializes AppLoad before your pages render. |
+| `src/routes/ps3/blog/[...orionplace]/+server.ts` | Route serving guarded blog images and videos under `/ps3/blog/...`. |
+| `src/routes/+layout.server.ts` | Initializes Application Load before your pages render. |
 | `src/routes/+layout.svelte` | Creates the store for this session and puts it in context. |
-| `src/routes/+page.svelte` | Starter page showing the AppLoad state; replace it with your storefront. |
+| `src/routes/+page.svelte` | Home page using the maintained storefront components. |
 | `src/hooks.server.ts` | Marks personalized pages `private, no-store` and varies them by domain. |
 | `src/lib/orionplace/` | Server transport with cookie relay, browser transport, envelope checks, domain resolution. |
 | `src/lib/orionplace/store.svelte.ts` | Typed snapshot, status, merged discovery and derived data as Svelte 5 runes. |
-| `src/lib/interfaces/orionplace/` | The AppLoad response envelope and every nested model. |
+| `src/lib/interfaces/orionplace/` | The Application Load response envelope and every nested model. |
 | `svelte.config.js`, `vite.config.ts` | Node adapter, and your storefront domains as allowed development hosts. |
 | `orionplace/runtime/marketplace.mjs` | Commented domain lookup and HTTP transport. |
+| `orionplace/runtime/app.mjs` | `androidAppKit` and `androidAppDefine`: the Android app build switch. |
 | `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. |
+
+`npm run check` runs `svelte-check` with TypeScript and Svelte diagnostics
+(`--diagnostic-sources "js,svelte"`): the CSS checker does not know Tailwind's
+at-rules and would report every `@apply` as unknown. Setup upgrades the former
+default script and keeps a script you changed.
 
 All generated source is yours to read and customize. Later setup runs preserve
 edited files and report which ones were preserved. Unchanged generated files can
@@ -159,9 +423,27 @@ 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.
 
-## AppLoad starter
+## Native storefront
+
+The starter includes Svelte components and SvelteKit routes for catalog and
+product search, product details and variants, journal articles and comments,
+manufacturer, seller and store directories, contact, tariffs, account, addresses,
+cart, orders, wallet, subscriptions and tickets. Public route loads reuse the
+layout snapshot and request the detail data needed for their first render.
+Protected routes take a guest to sign-in and preserve the return path.
+
+Components in `src/lib/components/orionplace/` use scoped Svelte state and
+controllers in `src/lib/composables/`. Their callback payloads correspond to
+the maintained Nuxt events. The package's component READMEs describe inputs,
+data and actions; `orionplace/COMPONENTS.md` lists their customer paths.
+
+Page titles, descriptions and link-preview metadata follow the current page
+and selected language, including client navigation. Public events and banner
+images come from Application Load.
+
+## Application Load starter
 
-The root layout load awaits `POST /api/appload` in light mode before your pages
+The root layout load awaits `POST /api/appload` before your pages
 render and returns the snapshot to every route, so `await parent()` in a page load
 reuses it instead of requesting again. The root layout component creates one store
 per browser session and hydrates it from that snapshot; components read it with
@@ -176,7 +458,7 @@ Discovery describes availability; the backend still checks permissions on each c
 
 ### Session and CSRF cookies
 
-AppLoad establishes the guest/customer session and CSRF cookie through HTTP
+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 the
 store or localStorage. The readable `csrftoken` supplies `X-CSRFToken` for later
@@ -189,11 +471,20 @@ the exact signed value and its attributes. Cookies established this way are also
 visible to later calls in the same render. Never share a cookie jar across visitors.
 
 Use `POST /api/csrf_renew` with `{}` to renew CSRF, then re-read the cookie.
-The backend signals CSRF rejection with HTTP `419` and `page_data.csrf: false`;
-a general `403` may mean permissions or origin rejection. Do not automatically
-replay mutations. After confirmed login/logout, reset and refresh AppLoad.
+The backend signals CSRF rejection with HTTP `419`, or HTTP `403` with
+`page_data.csrf: false`. A `403` without that flag may mean permissions or
+origin rejection. The shared API client renews the token for the next action
+and returns the failed request; the customer retries explicitly. After
+confirmed login/logout, reset and refresh Application Load.
 Those store actions update data; they do not authenticate or delete cookies.
 
+
+When a request returns HTTP `401` while the store is signed in, the shared API
+client clears profile, wallet, authenticated discovery, cart and wishlist counters
+and account fields of cached products, then reloads Application Load as a guest.
+Public data and the current selections remain available during that refresh.
+The failed request is not repeated and no sign-in dialog opens automatically.
+
 ## Update an existing project
 
 After the initial setup, use one command to get the latest package and components:
@@ -229,11 +520,18 @@ installation fails after source generation, run `npm install` and retry `update`
 
 ## Documentation
 
-- [Create a SvelteKit frontend](https://orionmarket.place/sandbox/new-project/svelte)
-- [Marketplace API documentation](https://orionmarket.place/sandbox/)
+- [Create a SvelteKit frontend](https://orionmarket.place/en/sandbox/new-project/svelte)
+- [Marketplace API documentation](https://orionmarket.place/en/sandbox/)
 
 ## Development
 
+In this repository checkout, the package demo uses its own
+`packages/orionplace-svelte/.env` and
+`packages/orionplace-svelte/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
@@ -242,3 +540,20 @@ npm pack --dry-run
 
 The published tarball includes only the CLI, runtime source, README, license,
 starter templates, and package metadata.
+
+## Storefront flows
+
+The generated storefront includes product and category pages, search, wishlist,
+cart and checkout, orders, support tickets, profile and phone sign-in, addresses,
+wallet, subscriptions, tariffs, journal, promotions, contacts and event enrollment.
+Public product, category, search, featured, journal, article and tariff routes
+await their first response during server loading and hydrate the same data.
+Account routes send a confirmed guest to the profile sign-in flow and preserve
+the return address. Form requests begin after visitor interaction.
+
+Component source lives in `src/lib/components/orionplace/`; controllers live in
+`src/lib/composables/`. `orionplace/COMPONENTS.md` describes the component catalog.
+The store is scoped to one render on the server and the root layout in the
+browser. It preserves valid selections when Application Load refreshes. HTTP
+401 clears account data and refreshes the guest session without repeating the
+failed mutation. API validation errors remain beside the affected form.

package/bin/orionplace-svelte.mjs

@@ -17,7 +17,7 @@ From zero (Node.js 20.19+ with npm; run from the parent folder):
 
 Replace the backend with the domain from your orionmarket.place profile,
 and the frontend with your storefront domain. Open the local URL printed by Vite;
-the starter's AppLoad state should show Loaded.
+the storefront opens after Application Load succeeds.
 
 Commands for an existing project (run from its root):
   npx orionplace-svelte help
@@ -90,6 +90,9 @@ try {
         : `Next: ${result.settings.backend ? 'add frontend' : 'set backend'} to complete the domain mapping.`);
       if (result.changed.some(path => path.endsWith('.cfg') || path === '.env')) console.log('Restart a running development server to reload MIMIC and domain mappings. Reload your production environment when changing MIMIC.');
       if (result.isNewKit) console.log('Run npm install in the project, then npm run dev.');
+      if ([...result.preserved, ...result.skipped].some(path => /^svelte\.config\./.test(path))) {
+        console.log('Merge the import aliases into your retained configuration; see Import aliases in orionplace/README.md.');
+      }
       console.log('Project documentation: orionplace/README.md');
       if (command === 'update') console.log(dryRun
         ? 'Dependency installation would run after applying these changes. Project files were not changed.'

package/package.json

@@ -1,16 +1,28 @@
 {
   "name": "orionplace-svelte",
-  "version": "0.1.0",
-  "description": "SvelteKit integration and setup CLI for your Orionplace personal marketplace backend.",
+  "version": "0.2.1",
+  "description": "SvelteKit 2 storefront for your Orionplace marketplace: setup CLI, server API gateway, typed store and ready-made catalog, cart, checkout and account components in English and Russian, plus an Android app build.",
   "type": "module",
   "license": "MIT",
   "author": "Orionplace",
-  "homepage": "https://orionmarket.place/sandbox/new-project/svelte",
+  "homepage": "https://orionmarket.place/en/sandbox/new-project/svelte",
   "keywords": [
     "svelte",
+    "svelte5",
     "sveltekit",
     "orionplace",
-    "marketplace"
+    "orionmarketplace",
+    "marketplace",
+    "storefront",
+    "ecommerce",
+    "e-commerce",
+    "shop",
+    "cart",
+    "checkout",
+    "ssr",
+    "cli",
+    "android",
+    "capacitor"
   ],
   "engines": {
     "node": ">=20.19.0"
@@ -39,7 +51,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --import ../../scripts/register-test-aliases.mjs --test test/*.test.mjs"
   },
   "peerDependencies": {
     "@sveltejs/kit": "^2.4.0",
@@ -51,6 +63,7 @@
   },
   "devDependencies": {
     "esbuild": "^0.27.7",
-    "svelte": "^5.57.0"
+    "svelte": "^5.57.0",
+    "happy-dom": "^20.14.5"
   }
 }

package/runtime/app.d.mts

@@ -0,0 +1,10 @@
+import type { KitConfig } from '@sveltejs/kit';
+
+/** The validated storefront origin of an Android app build; empty for the website. */
+export function androidAppOrigin(value?: string): string;
+/** Vite `define` with the storefront origin the app's requests go to. */
+export function androidAppDefine(): Record<string, string>;
+/** The SvelteKit options, made static with the app's routes for the Android app build. */
+export function androidAppKit(kit: KitConfig, root?: string): Promise<KitConfig>;
+/** Copies the routes for the app build, with app loads instead of server loads. */
+export function writeAndroidAppRoutes(source: string, target: string): void;

package/runtime/app.mjs

@@ -0,0 +1,94 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+
+/*
+ * Android app build: ORIONPLACE_APP_ORIGIN=https://shop.example.com vite build
+ *
+ * The app is a client-only build (adapter-static, written to build/) that
+ * Capacitor wraps. Its API requests go to the public storefront named by the
+ * variable, through its /api gateway (see src/lib/utils/orionplace/nativeApp.ts).
+ * Without the variable the project builds the website as before.
+ */
+
+const hostname = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+/** The validated storefront origin of an app build; empty for the website. */
+export function androidAppOrigin(value = process.env.ORIONPLACE_APP_ORIGIN) {
+  const text = value?.trim() ?? '';
+  if (!text) return '';
+  if (/^http:/i.test(text)) throw new Error('ORIONPLACE_APP_ORIGIN must use HTTPS.');
+  let url;
+  try { url = new URL(text.includes('://') ? text : `https://${text}`); }
+  catch { url = null; }
+  const host = url?.hostname.toLowerCase().replace(/\.$/, '') ?? '';
+  if (!url || url.protocol !== 'https:' || !hostname.test(host) || /^[\d.]+$/.test(host) ||
+      url.username || url.password || url.port || url.search || url.hash || url.pathname !== '/') {
+    throw new Error('ORIONPLACE_APP_ORIGIN must be your public storefront, for example https://shop.example.com.');
+  }
+  return `https://${host}`;
+}
+
+/** Vite `define`: the storefront origin the app's requests go to. */
+export function androidAppDefine() {
+  return { __ORIONPLACE_APP_ORIGIN__: JSON.stringify(androidAppOrigin()) };
+}
+
+const appLayout = `// Generated for the Android app build (orionplace/runtime/app.mjs).
+export const ssr       = false;
+export const prerender = false;
+export { loadAppLayout as load } from '@/lib/orionplace/appRoutes';
+`;
+const appPage   = `// Generated for the Android app build (orionplace/runtime/app.mjs).
+export { loadAppPage as load } from '@/lib/orionplace/appRoutes';
+`;
+const server    = /^\+(page|layout)\.server\.[jt]s$/;
+
+/*
+ * The app has no server, so its routes are a copy of src/routes with the
+ * server loads replaced by loads that run in the app. Endpoints (+server.ts)
+ * stay on the storefront, which answers the app's requests.
+ */
+export function writeAndroidAppRoutes(source, target) {
+  rmSync(target, { recursive: true, force: true });
+  mkdirSync(target, { recursive: true });
+  for (const entry of readdirSync(source, { withFileTypes: true })) {
+    const from = join(source, entry.name);
+    const to   = join(target, entry.name);
+    if (entry.isDirectory()) {
+      writeAndroidAppRoutes(from, to);
+    } else if (/^\+server\.[jt]s$/.test(entry.name)) {
+      continue;
+    } else if (server.test(entry.name)) {
+      const kind = entry.name.startsWith('+page') ? 'page' : 'layout';
+      const code = readFileSync(from, 'utf8');
+      const ours = kind === 'page' ? /\bloadStorefrontPage\b/ : /\bloadOrionplaceAppLoad\b/;
+      if (!ours.test(code)) {
+        throw new Error(`${relative(process.cwd(), from)} runs only on a server. Add a +${kind}.ts load for the Android app, or remove the page.`);
+      }
+      if (!existsSync(join(source, `+${kind}.ts`)) && !existsSync(join(source, `+${kind}.js`))) {
+        writeFileSync(join(target, `+${kind}.ts`), kind === 'page' ? appPage : appLayout);
+      }
+    } else {
+      cpSync(from, to);
+    }
+  }
+}
+
+/**
+ * The SvelteKit options: unchanged for the website; for the app build a
+ * static build with an index.html fallback and the app's copy of the routes.
+ * @param {import('@sveltejs/kit').KitConfig} kit
+ */
+export async function androidAppKit(kit, root = process.cwd()) {
+  if (!androidAppOrigin()) return kit;
+  let adapter;
+  try { ({ default: adapter } = await import('@sveltejs/adapter-static')); }
+  catch { throw new Error('The Android app build needs @sveltejs/adapter-static: npm install -D @sveltejs/adapter-static'); }
+  const routes = resolve(root, '.svelte-kit/orionplace-app/routes');
+  writeAndroidAppRoutes(resolve(root, kit.files?.routes ?? 'src/routes'), routes);
+  return {
+    ...kit,
+    adapter: adapter({ pages: 'build', assets: 'build', fallback: 'index.html' }),
+    files: { ...kit.files, routes },
+  };
+}

package/runtime/marketplace.d.mts

@@ -1,22 +1,27 @@
 export interface MarketplaceConfiguration {
-	mimicFrontDomain?: string;
+  mimicFrontDomain?: string;
 }
 
 export interface MarketplaceTenant {
-	domain: string;
-	api: URL;
+  domain: string;
+  api: URL;
 }
 
 export declare function normalizeFrontDomain(value: unknown): string | null;
 
-export declare function resolveFrontDomain(request: Request, mimic?: string): string | null;
+export declare function isMarketplaceMediaPath(pathname: string): boolean;
+
+export declare function resolveFrontDomain(
+  request: Request,
+  mimic?: string,
+): string | null;
 
 export declare function readMarketplace(
-	request: Request,
-	configuration?: MarketplaceConfiguration,
+  request: Request,
+  configuration?: MarketplaceConfiguration,
 ): Promise<MarketplaceTenant>;
 
 export declare function forwardMarketplace(
-	request: Request,
-	configuration?: MarketplaceConfiguration,
+  request: Request,
+  configuration?: MarketplaceConfiguration,
 ): Promise<Response>;