orionplace-react 0.1.0 → 0.2.0

package/src/project-readme.mjs

@@ -1,7 +1,8 @@
 export function projectReadme(settings, base = '') {
-  const frontend = settings.frontend || 'shop.example.com';
-  const backend  = settings.backend || 'https://your-project.orionplace.app/api';
-  return `# Your Orionplace React integration
+	const frontend = settings.frontend || 'shop.example.com';
+	const backend =
+		settings.backend || 'https://your-project.orionplace.app/api';
+	return `# Your Orionplace React integration
 
 This folder contains the integration source for your Next.js storefront.
 Your personal backend API is provided in your account at https://orionmarket.place.
@@ -26,16 +27,16 @@ 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 Next.js (normally http://localhost:3000). The starter
-should show \`Loaded\` in its AppLoad state section. If it shows \`Failed\`, check
-the domain mapping and backend response before building pages.
+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.
 
 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'}\`
 
@@ -84,7 +85,10 @@ and Next.js configuration are preserved.
 | \`runtime/marketplace.mjs\` | Domain lookup, configuration validation, API transport and cookies. |
 | \`runtime/marketplace.d.mts\` | Types for the gateway functions used by your TypeScript source. |
 | \`settings.json\` | The CLI's frontend list, local MIMIC domain and personal backend; not a secret store. |
+| \`../${base}app/page.tsx\`, \`../${base}app/*/page.tsx\` | Server-rendered public and account storefront routes. |
+| \`../${base}app/_storefront/\` | Route controllers that connect components, navigation and API actions. |
 | \`../${base}app/api/[...orionplace]/route.ts\` | The route handler serving \`/api/...\` from your project. |
+| \`../${base}app/ps3/blog/[...orionplace]/route.ts\` | The route handler serving guarded blog images and videos under \`/ps3/blog/...\`. |
 | \`../${base}proxy.ts\` | Marks personalized pages private and varies them by storefront domain. |
 | \`../sitemaps/${frontend}.cfg\` | The backend URL used for this frontend domain. |
 | \`../.env\` | Local MIMIC setting; keep secrets out of version control. |
@@ -93,6 +97,24 @@ You can edit these files; subsequent setup runs preserve customized source and
 this README. The CLI refuses to overwrite an unknown or manually changed domain
 mapping, and never replaces your own layout, page or middleware.
 
+## Import aliases
+
+Application imports use \`@/\`. In \`tsconfig.json\`, merge these entries into
+\`compilerOptions.paths\` while keeping your other settings:
+
+\`\`\`json
+{
+  "@/*": ["./${base}*"],
+  "@orionplace-runtime/*": ["./orionplace/runtime/*"]
+}
+\`\`\`
+
+The \`@/\` alias follows this project's \`${base || '.'}\` source layout. The gateway alias
+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.
+
 ## How requests reach your personal API
 
 The trusted hosting proxy supplies the public domain through \`X-Front-Domain\`,
@@ -124,28 +146,34 @@ In another terminal:
 \`\`\`bash
 curl -i http://localhost:3000/api/appload \\
   -H 'Content-Type: application/json' \\
-  --data '{"ignore_cache":true,"detalize_mode":"light"}'
+  --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.
+\`page_data\`; HTTP 200 by itself is insufficient. Public storefront requests do
+not require a login prompt. Protected actions still require backend permission.
 
-## AppLoad architecture
+## Application Load architecture
 
 The root layout initializes the marketplace before your page renders. The request
-uses \`POST /api/appload\` with \`detalize_mode: "light"\` and \`ignore_cache: true\`.
+uses \`POST /api/appload\` with \`ignore_cache: false\`.
 Tenant settings may override these options.
 
 | Project file | Responsibility |
 | --- | --- |
 | \`${base}app/layout.tsx\` | Awaits initialization, then passes the snapshot to the provider. |
+| \`${base}app/StorefrontShell.tsx\` | Shows initialization failures and mounts storefront content after success. |
 | \`${base}lib/orionplace/appLoadServer.ts\` | Server transport: one request per render through \`cache()\`. |
 | \`${base}lib/orionplace/appLoadClient.ts\` | Browser transport for explicit initialize and refresh. |
 | \`${base}lib/orionplace/appLoadResult.ts\` | HTTP, form-error and bootstrap-envelope checks. |
 | \`${base}lib/orionplace/domain.ts\` | The storefront domain selected for the current request. |
 | \`${base}stores/orionplace.ts\` | The typed snapshot, status, errors, merged discovery and selectors. |
-| \`${base}providers/OrionplaceProvider.tsx\` | One store per browser session, hydrated from the server snapshot. |
+| \`${base}stores/orionplaceSelections.ts\` | Current locale, currency and unit choices. |
+| \`${base}stores/orionplaceCatalog.ts\` | Categories and subscription plans from initialization or later requests. |
+| \`${base}stores/orionplaceProducts.ts\` | Product collections, confirmed updates and customer counters. |
+| \`${base}stores/orionplaceBrowse.ts\` | Search choices, selected filters and journal results. |
+| \`${base}stores/orionplaceScope.ts\` | Creates and synchronizes the stores before child components render. |
+| \`${base}providers/OrionplaceProvider.tsx\` | Provides one coordinated store scope per browser session. |
 | \`${base}hooks/useOrionplaceAppLoad.ts\` | Explicit initialize, refresh and reset actions. |
 | \`${base}interfaces/orionplace/index.ts\` | Response envelope and all nested models. |
 
@@ -158,8 +186,8 @@ prompt.
 \`\`\`tsx
 'use client';
 
-import { useOrionplace } from '../providers/OrionplaceProvider';
-import { selectCurrencies, selectFailure, selectIsReady, selectProducts, selectStatus } from '../stores/orionplace';
+import { useOrionplace } from '@/providers/OrionplaceProvider';
+import { selectCurrencies, selectFailure, selectIsReady, selectProducts, selectStatus } from '@/stores/orionplace';
 
 export function MarketplaceSummary() {
   const isReady    = useOrionplace(selectIsReady);
@@ -169,15 +197,14 @@ export function MarketplaceSummary() {
   const currencies = useOrionplace(selectCurrencies);
 
   if (failure) return <p role="alert">Marketplace initialization failed.</p>;
-  if (!isReady) return <p role="status">AppLoad: {status}</p>;
+  if (!isReady) return <p role="status">Application Load: {status}</p>;
   return <p>{products.length} products; {Object.keys(currencies).length} currencies.</p>;
 }
 \`\`\`
 
 Select one value at a time. Each selector returns a stable reference, so a
-component re-renders only when its own data changes. This example lives one
-directory below the project root, such as \`${base}components\`; adjust relative
-imports for deeper directories.
+component re-renders only when its own data changes. The \`@/\` alias resolves
+to the source root configured above, so imports work in nested component folders.
 
 | Selector | Available data |
 | --- | --- |
@@ -191,13 +218,13 @@ imports for deeper directories.
 
 Use \`selectEndpoint(section, name)\` with section and endpoint keys from the
 current response. It returns the endpoint's target, methods and forms, or
-\`undefined\` when unavailable. Full descriptions may be omitted in light mode.
+\`undefined\` when unavailable. Some endpoint descriptions may be omitted.
 Discovery describes availability; the backend checks permissions on every call.
 
 ### Read data in a server component
 
 \`\`\`tsx
-import { getOrionplaceAppLoad } from '../lib/orionplace/appLoadServer';
+import { getOrionplaceAppLoad } from '@/lib/orionplace/appLoadServer';
 
 export default async function CatalogPage() {
   const { result, failure } = await getOrionplaceAppLoad();
@@ -215,7 +242,7 @@ one request. Do not import it from a client component.
 \`\`\`tsx
 'use client';
 
-import { useOrionplaceAppLoad } from '../hooks/useOrionplaceAppLoad';
+import { useOrionplaceAppLoad } from '@/hooks/useOrionplaceAppLoad';
 
 export function SessionActions() {
   const { reset, refresh } = useOrionplaceAppLoad();
@@ -232,6 +259,20 @@ profile, initialization and discovery, aborts pending initialization and prevent
 late responses restoring the old session. Refresh replaces the whole snapshot.
 On failure, stale data and permissions remain cleared; the store exposes the error.
 
+### Storefront pages
+
+Navigation hides categories with \`exclude_from_tree: true\` and their descendants.
+The full published tree remains available for product category lookup and breadcrumbs.
+
+The maintained components and routes cover catalog and search, product details,
+variants, journal, directories, contact, tariffs and the customer's account flows.
+Public events and banner images come from Application Load. Page metadata follows
+client navigation and the selected language.
+
+A signed-in request that receives HTTP \`401\` removes private account values and
+refreshes Application Load as a guest while retaining public data and selections.
+The failed request is not repeated and no sign-in dialog opens automatically.
+
 ### Session and CSRF cookies
 
 Session and CSRF cookies travel in HTTP headers, not in the initialization JSON.
@@ -239,7 +280,7 @@ Keep the signed HttpOnly \`sessionid\` opaque: the browser sends it automaticall
 Never log, decode, rewrite or put cookie values in the store 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 AppLoad loaders handle initialization; they are
+Login can rotate the token. The Application Load loaders handle initialization; they are
 not a general CSRF-aware client for other endpoints.
 
 The server render forwards the incoming request's cookies and domain to the same
@@ -251,27 +292,32 @@ relay them from your own route handler or server action. New response cookies
 never update the current render's request. Never share a cookie jar across visitors.
 
 Renew CSRF using \`POST /api/csrf_renew\` with \`{}\`, then re-read the cookie.
-HTTP \`419\` with \`page_data.csrf: false\` means CSRF rejection; a general
-\`403\` can mean permissions or origin rejection. Offer explicit retries for
-mutations. After confirmed login/logout, reset and refresh AppLoad; these actions
+HTTP \`419\`, or HTTP \`403\` with \`page_data.csrf: false\`, means CSRF
+rejection. A \`403\` without that flag can mean permissions or origin rejection.
+The shared 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; these actions
 change application data and do not log in/out or delete cookies.
 
-[Cookie lifecycle and browser request example](https://orionmarket.place/sandbox/appload/react#session-cookies)
+[Cookie lifecycle and browser request example](https://orionmarket.place/en/sandbox/appload/react#session-cookies)
 
 ### Rendering, navigation and failures
 
 Each server render gets its own request-scoped snapshot; the provider creates one
-store per browser session and hydrates it, so hydration and client navigation do
-not repeat initialization. Concurrent \`load\` calls share one request per store.
+coordinated store scope per browser session and hydrates every store from that
+snapshot, so hydration and client navigation do not repeat initialization.
+Concurrent \`load\` calls share one request per scope.
 
 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 \`selectIsReady\` before using required data.
+trigger an automatic retry on every route. The supplied shell shows
+\`StorefrontErrorPage\` and keeps the header, route content and footer unmounted
+until initialization succeeds. Retry reloads the page; an unknown address keeps
+the 404 page. App Router components cannot set the response status, so this
+error page is sent with HTTP 200. Feature components should check
+\`selectIsReady\` before using required data.
 
 Page responses use \`private, no-store\` through \`${base}proxy.ts\`. Do not put
 personalized HTML in shared caches or persist the snapshot in localStorage. The
-debug page displays summaries; account details, keys and backend exception stacks
-are not rendered there.
+storefront does not render account keys or backend exception stacks.
 
 Interfaces cover initialization, discovery/forms, profile and nested models.
 Plugin-defined configuration uses JSON types; interfaces are not full runtime
@@ -333,9 +379,23 @@ 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 (\`lib/orionplace/nativeApp.ts\`). Without the variable the
+website build is unchanged. 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
+\`\`\`
+
 ## More documentation
 
-- [React package installation and domain setup](https://orionmarket.place/sandbox/new-project/react)
-- [AppLoad](https://orionmarket.place/sandbox)
+- [React package installation and domain setup](https://orionmarket.place/en/sandbox/new-project/react)
+- [Application Load](https://orionmarket.place/en/sandbox)
 `;
 }

package/src/setup.mjs

@@ -1,5 +1,5 @@
 import { readFile, readdir, lstat, mkdir, writeFile, rename, unlink } from 'node:fs/promises';
-import { resolve, dirname, relative, sep, posix } from 'node:path';
+import { resolve, dirname, relative, sep } from 'node:path';
 import { createHash } from 'node:crypto';
 import { backendUrl, frontendDomain } from './validation.mjs';
 import { projectReadme } from './project-readme.mjs';
@@ -28,16 +28,20 @@ async function directoryExists(root, name) {
   try { return (await lstat(resolve(root, name))).isDirectory(); }
   catch (error) { if (error.code === 'ENOENT') return false; throw error; }
 }
-/** Generated source imports the editable gateway by an explicit relative path. */
-function runtimeImport(name) {
-  const from = posix.dirname(name);
-  const path = posix.relative(from, 'orionplace/runtime/marketplace.mjs');
-  return path.startsWith('.') ? path : `./${path}`;
-}
-const nextConfigTemplate = `import type { NextConfig } from 'next';
+// The former template, replaced while the customer has not changed it.
+const previousNextConfig = `import type { NextConfig } from 'next';
 
 const nextConfig: NextConfig = {};
 
+export default nextConfig;
+`;
+const nextConfigTemplate = `import type { NextConfig } from 'next';
+import { androidAppConfig } from './orionplace/runtime/app.mjs';
+
+// The Android app build (ORIONPLACE_APP_ORIGIN) is a static export of the
+// app's own page; see orionplace/runtime/app.mjs.
+const nextConfig: NextConfig = androidAppConfig({});
+
 export default nextConfig;
 `;
 const tsconfigTemplate = {
@@ -166,7 +170,13 @@ export async function setupProject({ cwd = process.cwd(), action = 'set', field,
   }
   // All checks and content generation happen before the first write.
   const isNewNext                             = !dependencies.next;
-  if (!configs.length) await plan(configName, nextConfigTemplate, { managed: true, preserve: true });
+  if (current[configName] === previousNextConfig) {
+    // The former template is ours to replace, as an unchanged generated file.
+    previous[configName] = hash(previousNextConfig);
+  }
+  if (!configs.length || current[configName] === previousNextConfig) {
+    await plan(configName, nextConfigTemplate, { managed: true, preserve: true });
+  }
   pkg.scripts                               ||= {};
   pkg.scripts.dev                           ||= 'next dev';
   pkg.scripts.build                         ||= 'next build';
@@ -180,6 +190,9 @@ export async function setupProject({ cwd = process.cwd(), action = 'set', field,
   pkg.scripts['orionplace:update']          ||= 'orionplace-react update';
   pkg.dependencies                          ||= {};
   pkg.dependencies.zustand                  ||= dependencies.zustand || '^5.0.15';
+  pkg.dependencies['country-flag-icons']    ||= dependencies['country-flag-icons'] || '^1.6.20';
+  pkg.dependencies['libphonenumber-js']     ||= dependencies['libphonenumber-js'] || '^1.13.10';
+  pkg.dependencies.dompurify                ||= dependencies.dompurify || '^3.4.13';
   pkg.dependencies['orionplace-react']      ||= dependencies['orionplace-react'] || `^${metadata.version}`;
   if (action === 'update') {
     pkg.dependencies['orionplace-react'] = metadata.version;
@@ -203,18 +216,28 @@ export async function setupProject({ cwd = process.cwd(), action = 'set', field,
       const target = base + name;
       // Never replace a customer's own layout, page, styles or middleware.
       if (optional.includes(name) && !previous[target] && await read(await safePath(root, target)) !== null) continue;
-      const source = (await readFile(new URL(name, templateRoot), 'utf8'))
-        .replaceAll('__ORIONPLACE_RUNTIME__', runtimeImport(target));
+      const source = await readFile(new URL(name, templateRoot), 'utf8');
       await plan(target, source, { managed: true, preserve: true });
     }
   }
   await planTemplates();
-  if (!await read(await safePath(root, 'tsconfig.json'))) {
-    await plan('tsconfig.json', JSON.stringify(tsconfigTemplate, null, 2) + '\n', { managed: true });
+  const existingTsconfig = await read(await safePath(root, 'tsconfig.json'));
+  if (existingTsconfig === null || previous['tsconfig.json'] === hash(existingTsconfig)) {
+    const configuration = structuredClone(tsconfigTemplate);
+    configuration.compilerOptions.paths = {
+      '@/*': [`./${base}*`],
+      '@orionplace-runtime/*': ['./orionplace/runtime/*'],
+    };
+    await plan('tsconfig.json', JSON.stringify(configuration, null, 2) + '\n', { managed: true });
+  } else {
+    // Custom JSONC/extends settings belong to the customer; document the alias merge.
+    preserved.push('tsconfig.json');
   }
   await plan('package.json', JSON.stringify(pkg, null, 2) + '\n');
   await plan('orionplace/runtime/marketplace.mjs', await readFile(new URL('../runtime/marketplace.mjs', import.meta.url), 'utf8'), { managed: true, preserve: true });
   await plan('orionplace/runtime/marketplace.d.mts', await readFile(new URL('../runtime/marketplace.d.mts', import.meta.url), 'utf8'), { managed: true, preserve: true });
+  await plan('orionplace/runtime/app.mjs', await readFile(new URL('../runtime/app.mjs', import.meta.url), 'utf8'), { managed: true, preserve: true });
+  await plan('orionplace/runtime/app.d.mts', await readFile(new URL('../runtime/app.d.mts', import.meta.url), 'utf8'), { managed: true, preserve: true });
   await plan('orionplace/README.md', projectReadme(settings, base), { managed: true, preserve: true });
   // A new project starts explicitly empty; keep a pre-existing manual setting on init.
   const hasMimicSetting = /^\s*(?:export\s+)?MIMIC_FRONT_DOMAIN\s*=/m.test(current['.env'] || '');