orionplace-react 0.1.0 → 0.2.0

package/README.md

@@ -1,12 +1,189 @@
 # orionplace-react
 
 Set up a Next.js 16 storefront for your personal Orionplace marketplace API.
-The package includes a setup CLI, the App Router starter with typed AppLoad
+The package includes a setup CLI, the App Router starter with typed Application Load
 initialization, and commented server source that is copied into your project
 alongside an integration README.
 
+The generated source includes the shared
+[`OrionplaceImage`](templates/components/orionplace/shared/OrionplaceImage.README.md),
+[`OrionplaceEmptyState`](templates/components/orionplace/shared/OrionplaceEmptyState.README.md),
+[`OrionplaceAvatar`](templates/components/orionplace/shared/OrionplaceAvatar.README.md),
+[`OrionplaceBreadcrumbs`](templates/components/orionplace/shared/OrionplaceBreadcrumbs.README.md),
+[`OrionplaceInfoHint`](templates/components/orionplace/shared/OrionplaceInfoHint.README.md),
+[`OrionplacePasswordInput`](templates/components/orionplace/shared/OrionplacePasswordInput.README.md)
+and
+[`StorefrontPagination`](templates/components/orionplace/shared/StorefrontPagination.README.md).
+[`StorefrontErrorPage`](templates/components/orionplace/shared/StorefrontErrorPage.README.md)
+provides the public error view.
+[`OrionplaceSelect`](templates/components/orionplace/shared/OrionplaceSelect.README.md)
+provides the shared keyboard-accessible selection control.
+[`OrionplaceSearchSelect`](templates/components/orionplace/shared/OrionplaceSearchSelect.README.md)
+provides delayed search with a controlled confirmed selection, loading, empty
+and retry states.
+[`ProfileAvatar`](templates/components/orionplace/account/ProfileAvatar.README.md)
+provides the profile photo upload and removal contract with an initials fallback.
+[`ProfileDetailsForm`](templates/components/orionplace/account/ProfileDetailsForm.README.md)
+edits the customer's name and date of birth while keeping the sign-in phone
+read-only.
+[`ProfilePasswordForm`](templates/components/orionplace/account/ProfilePasswordForm.README.md)
+creates or changes the customer's password with matching confirmation.
+[`ProfileDeleteAccount`](templates/components/orionplace/account/ProfileDeleteAccount.README.md)
+lets the customer delete their own account after confirming it cannot be restored.
+[`ProfileEmailSettings`](templates/components/orionplace/account/ProfileEmailSettings.README.md)
+handles the email verification steps, optional notification choice and notification
+language.
+[`AccountSection`](templates/components/orionplace/account/AccountSection.README.md)
+provides authenticated account navigation plus guest and initialization failure
+states.
+[`StorefrontLogout`](templates/components/orionplace/account/StorefrontLogout.README.md)
+presents pending, failed and completed sign-out states while the route owns the
+request and navigation.
+[`StorefrontProfile`](templates/components/orionplace/account/StorefrontProfile.README.md)
+assembles the authenticated profile summary and all four profile settings
+sections, and shows a sign-in explanation to guests.
+[`ProfileSignIn`](templates/components/orionplace/account/ProfileSignIn.README.md)
+renders every phone, password, one-time-code and registration step and reports
+typed authentication actions to the host.
+[`SignInHistory`](templates/components/orionplace/account/SignInHistory.README.md)
+reports initial, filtered and paginated sign-in-history requests and renders the
+returned devices, browsers and locations.
+[`AccountPromocodes`](templates/components/orionplace/account/AccountPromocodes.README.md)
+shows issued promo-code conditions and statuses and reports load and apply
+requests to the host.
+[`AccountActivity`](templates/components/orionplace/account/AccountActivity.README.md)
+switches between promo codes, the customer's reviews and sign-in history while
+mounting only the active section.
+[`AddressForm`](templates/components/orionplace/address/AddressForm.README.md)
+creates or edits a delivery address with region search, address suggestions and
+optional coordinate lookup.
+[`StorefrontAddresses`](templates/components/orionplace/address/StorefrontAddresses.README.md)
+loads saved addresses and provides add, edit, default and confirmed delete
+actions.
+[`BlogPostCard`](templates/components/orionplace/blog/BlogPostCard.README.md)
+renders a localized article preview as a link or selection button.
+[`BlogPostGroup`](templates/components/orionplace/blog/BlogPostGroup.README.md)
+arranges the browse store's article previews using the configured journal view.
+[`BlogCommentForm`](templates/components/orionplace/blog/BlogCommentForm.README.md)
+collects validated text for a new comment, reply or edit.
+[`BlogComments`](templates/components/orionplace/blog/BlogComments.README.md)
+renders nested article discussions, the customer's comments and all comment
+write actions.
+[`BlogArticle`](templates/components/orionplace/blog/BlogArticle.README.md)
+renders an SSR-readable article, subscription access, safe editor HTML,
+reading accounting, related product cards and its discussion.
+[`StorefrontJournal`](templates/components/orionplace/blog/StorefrontJournal.README.md)
+renders the SSR-ready article list with category and author filters,
+pagination, linked cards and an optional inline article.
+[`CartCheckoutDetails`](templates/components/orionplace/cart/CartCheckoutDetails.README.md)
+connects the confirmed cart address, payment, recipient and comment fields to
+their typed mutation actions.
+[`MainSearch`](templates/components/orionplace/search/MainSearch.README.md)
+connects the localized search field and hints to the separate browse store.
+The first storefront data components are
+[`BrandLogos`](templates/components/orionplace/branding/BrandLogos.README.md)
+and [`SocialLinks`](templates/components/orionplace/social/SocialLinks.README.md).
+[`MainBanner`](templates/components/orionplace/banners/MainBanner.README.md)
+renders localized banner images with manual navigation and category actions.
+[`EventsBlock`](templates/components/orionplace/events/EventsBlock.README.md)
+renders page events for the selected language and reports the selected event.
+[`CategoryGroup`](templates/components/orionplace/categories/CategoryGroup.README.md)
+renders ordered public categories or one parent's immediate public children.
+[`StorefrontHome`](templates/components/orionplace/storefront/StorefrontHome.README.md)
+assembles banners, categories, product sections and page events in storefront
+order.
+[`CatalogRepresentative`](templates/components/orionplace/catalog/CatalogRepresentative.README.md)
+adapts the verified compact product card for category highlights.
+[`CatalogHeader`](templates/components/orionplace/catalog/CatalogHeader.README.md)
+provides the focus-managed category panel, shortcuts, trails and representative
+product actions used by the storefront header.
+[`StorefrontCartButton`](templates/components/orionplace/storefront/StorefrontCartButton.README.md)
+shows the shared cart-position count and reports a cart selection.
+[`StorefrontWishlistButton`](templates/components/orionplace/storefront/StorefrontWishlistButton.README.md)
+shows the shared wishlist count with plain-click application handling and
+native modifier-click navigation.
+[`WalletBalance`](templates/components/orionplace/wallet/WalletBalance.README.md)
+formats the selected currency's Application Load wallet amount in full or
+compact form.
+[`StorefrontAccount`](templates/components/orionplace/storefront/StorefrontAccount.README.md)
+provides the guest login action and the authenticated profile, wallet and logout
+menu with keyboard navigation.
+[`StorefrontFooter`](templates/components/orionplace/storefront/StorefrontFooter.README.md)
+combines branding, social links, public categories and locale-preserving
+storefront links.
+[`StorefrontHeader`](templates/components/orionplace/storefront/StorefrontHeader.README.md)
+assembles search, selections, account actions and the interactive catalog with
+localized navigation.
+[`OrionplaceThemeProvider`](templates/components/orionplace/theme/OrionplaceThemeProvider.README.md)
+sets their shared color tokens.
+[`MainCurrencySwitcher`](templates/components/orionplace/currencies/MainCurrencySwitcher.README.md)
+[`UnitSwitcher`](templates/components/orionplace/units/UnitSwitcher.README.md)
+and [`MainLanguageSwitcher`](templates/components/orionplace/locale/MainLanguageSwitcher.README.md)
+use the separate current-selection store.
+[`HoverImageViewer`](templates/components/orionplace/products/HoverImageViewer.README.md)
+shows a product's first image in server HTML and starts loading its other
+images after hover or keyboard focus.
+The first product-card parts cover the
+[`title`](templates/components/orionplace/products/ProductCardTitle.README.md),
+[`description`](templates/components/orionplace/products/ProductCardDescription.README.md),
+[`price`](templates/components/orionplace/products/ProductCardPrice.README.md),
+[`stock notice`](templates/components/orionplace/products/ProductCardStockNotice.README.md),
+[`review rating`](templates/components/orionplace/products/ProductCardRating.README.md),
+[`seller`](templates/components/orionplace/products/ProductCardSeller.README.md),
+[`badges`](templates/components/orionplace/products/ProductCardBadges.README.md),
+[`favorite`](templates/components/orionplace/products/ProductCardFavorite.README.md),
+[`purchase actions`](templates/components/orionplace/products/ProductCardActions.README.md),
+[`variant choices`](templates/components/orionplace/products/ProductCardVariants.README.md)
+and the [`secondary-choice dialog`](templates/components/orionplace/products/ProductSecondaryVariantModal.README.md).
+[`ProductCard`](templates/components/orionplace/products/ProductCard.README.md)
+assembles these parts and delays each card's secondary images until hover
+or keyboard focus. [`ProductGroup`](templates/components/orionplace/products/ProductGroup.README.md)
+renders responsive rows of cards.
+[`ProductReviewImageViewer`](templates/components/orionplace/products/ProductReviewImageViewer.README.md)
+opens review photos with keyboard navigation.
+[`ProductReviewForm`](templates/components/orionplace/products/ProductReviewForm.README.md)
+collects validated review, reply and edit values.
+[`ProductReviewGallery`](templates/components/orionplace/products/ProductReviewGallery.README.md)
+loads scoped review photos and reports the owning review selection.
+[`ProductReviews`](templates/components/orionplace/products/ProductReviews.README.md)
+assembles review statistics, filters, photos, replies, reactions and writing
+controls for product, seller and account views.
+Their contracts are documented in English and Russian beside the maintained
+React source.
+
 Requires Node.js 20.9+ and a Node server deployment. Static export and edge-only
-hosting are not supported by this filesystem-based integration.
+hosting are not supported by this filesystem-based integration; only the Android
+app build below is a static export.
+
+## 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: `androidAppConfig` in `next.config.ts` (`orionplace/runtime/app.mjs`)
+then makes `next build` a static export of one app page to `out/`. The page runs
+the same route table as the website's server pages
+(`app/_storefront/storefrontRoutes.tsx`) in the app, and every API request goes
+to `<origin>/api/...` through Capacitor's native HTTP with the storefront
+Origin (`lib/orionplace/nativeApp.ts`). 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=react).
+
+```bash
+ORIONPLACE_APP_ORIGIN=https://shop.example.com npx next build
+npx cap sync android
+```
+
+## Asset loading
+
+The starter leaves route chunk selection to the current Next.js route and does
+not add speculative preload links. Storefront image components emit intrinsic
+dimensions or a stable aspect ratio to reserve layout space. Product cards
+include the primary image in server HTML and add secondary images after hover or
+keyboard focus.
 
 ## Quick start from zero
 
@@ -26,10 +203,11 @@ npx orionplace-react add frontend shop.example.com
 npm run dev
 ```
 
-The first command creates the Next.js configuration, App Router starter and
-integration README. The first frontend becomes the local MIMIC domain. Open the
-local URL printed by Next.js (normally http://localhost:3000); the starter's
-AppLoad state should show `Loaded`. If it shows `Failed`, check your domain
+The first command creates the Next.js configuration, the complete App Router
+storefront and its integration README. The first frontend becomes the local
+MIMIC domain. Open the local URL printed by Next.js (normally
+http://localhost:3000). The home page should show the configured catalog and
+storefront content. If it shows the initialization error state, check the 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.
@@ -55,6 +233,24 @@ 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 `@/`. In `tsconfig.json`, merge these entries into
+`compilerOptions.paths` while keeping your other settings:
+
+```json
+{
+	"@/*": ["./*"],
+	"@orionplace-runtime/*": ["./orionplace/runtime/*"]
+}
+```
+
+For a `src/app/` project, use `"@/*": ["./src/*"]` instead. The gateway alias
+still points to the project-root `orionplace/runtime/` directory. Setup writes
+these mappings for new projects and updates unchanged generated configuration.
+If you already own `tsconfig.json`, it is preserved; merge these aliases before
+starting the application. Imports then work at any component directory depth.
+
 ## Commands
 
 ```bash
@@ -86,23 +282,35 @@ change your account, create DNS records, configure TLS, or deploy a VPS.
 
 ## Generated files
 
-| Path | Purpose |
-| --- | --- |
-| `app/api/[...orionplace]/route.ts` | Route handler serving `/api/...` from your project. |
-| `app/layout.tsx` | Awaits initialization and provides the marketplace store. |
-| `app/page.tsx` | Starter page showing the AppLoad state; replace it with your storefront. |
-| `proxy.ts` | Marks personalized pages `private, no-store`. |
-| `lib/orionplace/` | Server transport, browser transport, envelope checks and domain resolution. |
-| `stores/orionplace.ts` | Typed snapshot, status, merged discovery and selectors. |
-| `providers/OrionplaceProvider.tsx` | One store per browser session, hydrated from the server render. |
-| `hooks/useOrionplaceAppLoad.ts` | Explicit initialize, refresh and reset actions. |
-| `interfaces/orionplace/` | The AppLoad response envelope and every nested model. |
-| `orionplace/runtime/marketplace.mjs` | Commented domain lookup and HTTP transport. |
-| `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. |
+| Path                                    | Purpose                                                                          |
+| --------------------------------------- | -------------------------------------------------------------------------------- |
+| `app/api/[...orionplace]/route.ts`      | Route handler serving `/api/...` from your project.                              |
+| `app/ps3/blog/[...orionplace]/route.ts` | Route handler serving guarded blog images and videos under `/ps3/blog/...`.      |
+| `app/layout.tsx`                        | Awaits initialization and provides the marketplace store.                        |
+| `app/StorefrontShell.tsx`               | Shows initialization failures and mounts storefront content after success.       |
+| `app/page.tsx`, `app/*/page.tsx`        | Server-rendered public and account storefront routes.                            |
+| `app/_storefront/`                      | Route controllers that connect components, navigation and API actions.           |
+| `proxy.ts`                              | Marks personalized pages `private, no-store`.                                    |
+| `lib/orionplace/`                       | Server transport, browser transport, envelope checks and domain resolution.      |
+| `stores/orionplace.ts`                  | Typed snapshot, status, merged discovery and selectors.                          |
+| `stores/orionplaceSelections.ts`        | Current locale, currency and unit choices with availability fallbacks.           |
+| `stores/orionplaceCatalog.ts`           | Categories and subscription plans from initialization or later requests.         |
+| `stores/orionplaceProducts.ts`          | Request-scoped product collections and customer-session product updates.         |
+| `stores/orionplaceBrowse.ts`            | Search choices, selected filters and journal results.                            |
+| `stores/orionplaceScope.ts`             | Creates and synchronizes the stores before child components render.              |
+| `components/orionplace/`                | Maintained React components, styles and bilingual component contracts.           |
+| `themes/orionplace.ts`                  | Light and dark storefront palettes and scoped color overrides.                   |
+| `providers/OrionplaceProvider.tsx`      | Provides one coordinated store scope per browser session.                        |
+| `hooks/useOrionplaceAppLoad.ts`         | Explicit initialize, refresh and reset actions.                                  |
+| `hooks/useOrionplaceApi.ts`             | Browser API client with discovery, CSRF renewal and session refresh.             |
+| `interfaces/orionplace/`                | The Application Load response envelope and every nested model.                   |
+| `orionplace/runtime/marketplace.mjs`    | Commented domain lookup and HTTP transport.                                      |
+| `orionplace/runtime/app.mjs`            | `androidAppConfig`: the Android app build switch for `next.config.ts`.           |
+| `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.                           |
 
 Projects that use `src/` receive the application source under `src/` instead.
 All generated source is yours to read and customize. Later setup runs preserve
@@ -157,15 +365,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.
 
-## AppLoad starter
+## Application Load starter
 
-The root layout awaits `POST /api/appload` in light mode before the page renders,
+The root layout awaits `POST /api/appload` before the page renders,
 then hands the snapshot to the client provider. `getOrionplaceAppLoad()` is cached
 per render, so a layout and a server component share one request. Client components
-read the same snapshot through `useOrionplace(selector)`; hydration does not repeat
-the request. `useOrionplaceAppLoad()` provides explicit `initialize`, `refresh` and
-`reset` actions. Reading the store or hook never starts a request, and initialization
-never opens an authentication prompt.
+read the same snapshot through the provider's main and domain-store hooks. The
+provider initializes and synchronizes those stores before child components render;
+hydration does not repeat the request. `useOrionplaceAppLoad()` provides explicit
+`initialize`, `refresh` and `reset` actions. Reading a store or hook never starts a
+request, and initialization never opens an authentication prompt.
+
+The requested `?locale` is validated against Application Load before the
+server render. Public product, article and tariff details load through the
+maintained API client. Page metadata uses those returned records and follows
+client navigation and language selection. Home-page event clicks open enrollment
+for the returned event, preserving its return path through sign-in.
+
+`StorefrontShell` mounts the header, route content and footer after Application
+Load succeeds. If initialization fails, it shows `StorefrontErrorPage`; Retry
+runs an explicit refresh and remains disabled while that request is pending.
+
+`app/not-found.tsx` shows the native missing-page view for unknown addresses
+and missing records. `app/error.tsx` and `app/global-error.tsx` show the native
+failure view for unhandled errors. Error metadata is localized and excludes the
+page from indexing. Home and Catalog preserve the selected locale; Retry reloads
+the current address. The server snapshot contains the requested locale and its
+currency and unit selections before components render.
 
 Live discovery from `page_data.unauth.paths` and, for a signed-in session,
 `page_data.auth.paths`, is merged into one lookup without mutating the response.
@@ -173,7 +399,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
@@ -187,11 +413,20 @@ session through `/api/...` requests. `requestAppLoad()` returns the raw `Set-Coo
 values if you relay them from your own route handler or server action.
 
 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:
@@ -227,11 +462,17 @@ installation fails after source generation, run `npm install` and retry `update`
 
 ## Documentation
 
-- [Create a Next.js frontend](https://orionmarket.place/sandbox/new-project/react)
-- [Marketplace API documentation](https://orionmarket.place/sandbox/)
+- [Create a Next.js frontend](https://orionmarket.place/en/sandbox/new-project/react)
+- [Marketplace API documentation](https://orionmarket.place/en/sandbox/)
 
 ## Development
 
+In this repository checkout, the package demo uses its own
+`packages/orionplace-react/.env` and
+`packages/orionplace-react/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

package/bin/orionplace-react.mjs

@@ -17,7 +17,7 @@ From zero (Node.js 20.9+ 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 Next.js's local URL;
-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-react help
@@ -89,6 +89,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.isNewNext) console.log('Run npm install in the project, then npm run dev.');
+      if (result.preserved.includes('tsconfig.json')) {
+        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,17 +1,29 @@
 {
   "name": "orionplace-react",
-  "version": "0.1.0",
-  "description": "Next.js integration and setup CLI for your Orionplace personal marketplace backend.",
+  "version": "0.2.0",
+  "description": "Next.js 16 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/react",
+  "homepage": "https://orionmarket.place/en/sandbox/new-project/react",
   "keywords": [
     "react",
     "next",
     "nextjs",
+    "app-router",
     "orionplace",
-    "marketplace"
+    "orionmarketplace",
+    "marketplace",
+    "storefront",
+    "ecommerce",
+    "e-commerce",
+    "shop",
+    "cart",
+    "checkout",
+    "ssr",
+    "cli",
+    "android",
+    "capacitor"
   ],
   "engines": {
     "node": ">=20.9.0"
@@ -40,7 +52,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --import ../../scripts/register-test-aliases.mjs --test test/*.test.mjs"
   },
   "peerDependencies": {
     "next": "^16.0.0"
@@ -50,6 +62,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
+    "dompurify": "^3.4.13",
     "esbuild": "^0.27.7",
     "zustand": "^5.0.15"
   }

package/runtime/app.d.mts

@@ -0,0 +1,6 @@
+import type { NextConfig } from 'next';
+
+/** The validated storefront origin of an Android app build; empty for the website. */
+export function androidAppOrigin(value?: string): string;
+/** The Next.js options, made a static export of the app's page for the Android app build. */
+export function androidAppConfig(config?: NextConfig): NextConfig;

package/runtime/app.mjs

@@ -0,0 +1,48 @@
+/*
+ * Android app build: ORIONPLACE_APP_ORIGIN=https://shop.example.com next build
+ *
+ * The app is a static export (out/) that Capacitor wraps: one page,
+ * app/[[...path]]/page.app.tsx with app/layout.app.tsx, which shows the
+ * storefront page of the current address in the app. Its API requests go to
+ * the public storefront named by the variable, through its /api gateway (see
+ * lib/orionplace/nativeApp.ts). Without the variable the project builds the
+ * website as before and ignores the *.app.tsx files.
+ */
+
+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}`;
+}
+
+/**
+ * The Next.js options: the website's, with the app origin known to the code;
+ * for the app build a static export of the app's own page.
+ * @param {import('next').NextConfig} config
+ */
+export function androidAppConfig(config = {}) {
+  const origin = androidAppOrigin();
+  const env    = { ...config.env, ORIONPLACE_APP_ORIGIN: origin };
+  if (!origin) return { ...config, env };
+  return {
+    ...config,
+    env,
+    output: 'export',
+    // Only app/layout.app.tsx and app/[[...path]]/page.app.tsx: the server
+    // pages, the /api gateway and proxy.ts stay with the website.
+    pageExtensions: ['app.tsx'],
+    images: { ...config.images, unoptimized: true },
+  };
+}

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>;