orionplace-nuxt 0.1.2 → 0.1.3

package/README.md

@@ -62,6 +62,7 @@ to inspect planned changes without writing them.
 
 ```bash
 npx orionplace-nuxt init [directory]
+npx orionplace-nuxt update
 npx orionplace-nuxt set backend your-project.orionplace.app
 npx orionplace-nuxt add frontend shop.example.com
 npx orionplace-nuxt add frontend www.shop.example.com
@@ -79,6 +80,7 @@ npm run orionplace:add-frontend -- shop.example.com
 npm run orionplace:remove-frontend -- www.shop.example.com
 npm run orionplace:mimic -- shop.example.com
 npm run orionplace:help
+npm run orionplace:update
 ```
 
 `npm set` belongs to npm's own configuration system; use the commands above.
@@ -102,7 +104,7 @@ change your account, create DNS records, configure TLS, or deploy a VPS.
 The module executes the generated local runtime files. You can read and customize
 them. Later setup runs preserve edited runtime files and the project README,
 reporting which files were preserved. Unchanged generated files can be refreshed
-by running `init` after upgrading the package. A manually edited domain file is
+with `npx orionplace-nuxt update`. A manually edited domain file is
 never silently overwritten. Keep the hash manifest in version control.
 
 ## Multiple frontend domains
@@ -174,4 +176,52 @@ npm pack --dry-run
 ```
 
 The published tarball includes only the CLI, module, runtime source, README,
-license, and package metadata.
+license, starter templates, and package metadata.
+
+## AppLoad starter
+
+The CLI generates an AppLoad debug `app/app.vue`, an SSR-aware
+`useOrionplaceAppLoad()` composable, validation helpers and the full nested
+TypeScript contract under `app/interfaces/orionplace/`. The first page loads
+`POST /api/appload`, shows request state and section counts, and supports reload.
+It preserves custom apps and edited generated files. Generated instructions in
+`orionplace/README.md` explain how to integrate the composable in an existing app.
+
+## Update an existing project
+
+After the initial setup, use one command to get the latest package and components:
+
+```bash
+npx orionplace-nuxt update
+```
+
+It runs the latest CLI, adds new template files, refreshes unchanged generated
+files, updates the package dependency and runs `npm install` to synchronize the
+lockfile and installed dependencies. Edited files are preserved and listed in the
+output. Review their new versions under `node_modules/orionplace-nuxt/templates`
+or `runtime` and merge your changes manually when needed. Removed upstream files
+are retained locally; the updater does not delete customer source.
+
+Domain mappings, domain settings and `.env` remain unchanged. The command does
+not deploy your application: restart development, or rebuild and redeploy the
+production frontend after updating.
+
+```bash
+npx orionplace-nuxt update --dry-run
+npm run orionplace:update
+```
+
+Dry-run downloads the latest CLI into npm's cache to inspect its templates but
+leaves project files and dependencies unchanged. `update --local` applies the
+version of the CLI being executed instead of fetching the latest CLI; it still
+installs project dependencies. Use this only when intentionally selecting a version.
+
+For a project on 0.1.2 or older, bootstrap the new command once:
+
+```bash
+npx --yes orionplace-nuxt@latest update
+```
+
+Updates require the existing `orionplace/settings.json` and `.generated.json`.
+Conflicting untracked files stop the source update before any writes. If dependency
+installation fails after source generation, run `npm install` and retry `update`.

package/bin/orionplace-nuxt.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { setupProject } from '../src/setup.mjs';
+import { updateProject } from '../src/update.mjs';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
@@ -8,6 +9,7 @@ const help = `Orionplace Nuxt setup
 
   npx orionplace-nuxt help
   npx orionplace-nuxt init [directory]
+  npx orionplace-nuxt update
   npx orionplace-nuxt set backend <personal-backend.orionplace.app>
   npx orionplace-nuxt add frontend <shop.example.com>
   npx orionplace-nuxt remove frontend <shop.example.com>
@@ -15,7 +17,10 @@ const help = `Orionplace Nuxt setup
   npx orionplace-nuxt set frontend <shop.example.com>
 
 Options: --cwd <directory>  --dry-run  --help  --version
+Update option: --local (apply this CLI version instead of fetching the latest release)
 
+Update downloads the latest release, refreshes unedited source, and installs dependencies.
+It preserves edited source, domain mappings and MIMIC. --dry-run leaves project files unchanged.
 Set backend or add frontend also initializes the integration; either can come first.
 MIMIC starts empty. The first added frontend sets it; later additions preserve it.
 Set mimic selects an existing frontend without changing any domain mappings.
@@ -33,8 +38,10 @@ try {
     const positional = [];
     let cwd = process.cwd();
     let dryRun = false;
+    let local = false;
     for (let index = 0; index < argv.length; index++) {
       if (argv[index] === '--dry-run') dryRun = true;
+      else if (argv[index] === '--local') local = true;
       else if (argv[index] === '--cwd') {
         if (!argv[index + 1]) throw new Error('--cwd needs a directory');
         cwd = resolve(argv[++index]);
@@ -42,9 +49,12 @@ try {
       else positional.push(argv[index]);
     }
     const [command, target] = positional;
+    if (local && command !== 'update') throw new Error('--local is only supported by update.');
     let result;
     if (command === 'init' && positional.length <= 2) {
       result = await setupProject({ cwd: target ? resolve(cwd, target) : cwd, dryRun });
+    } else if (command === 'update' && positional.length === 1) {
+      result = await updateProject({ cwd, dryRun, local });
     } else if (((command === 'set' && ['backend', 'frontend', 'mimic'].includes(target)) ||
         (['add', 'remove'].includes(command) && target === 'frontend')) && positional.length <= 3) {
       let value = positional[2];
@@ -56,15 +66,20 @@ try {
       if (!value) throw new Error(`Provide the ${target} domain. See --help.`);
       result = await setupProject({ cwd, action: command, field: target, value, dryRun });
     } else throw new Error('Unknown command. See --help.');
-    console.log(`${dryRun ? 'Planned' : 'Updated'} ${result.root}`);
-    for (const path of result.changed) console.log(`  ${result.removed.includes(path) ? 'Remove: ' : ''}${path}`);
-    for (const path of result.preserved) console.log(`  Preserved your edits: ${path}`);
-    console.log(result.settings.backend && result.settings.frontend
-      ? `Ready: ${result.settings.frontends.join(', ')} -> ${result.settings.backend}\nLocal MIMIC: ${result.settings.frontend}`
-      : `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 refresh allowed hosts and MIMIC. Reload your production environment when changing MIMIC.');
-    if (result.isNewNuxt) console.log('Run npm install in the project, then npm run dev.');
-    console.log('Project documentation: orionplace/README.md');
+    if (result) {
+      console.log(`${dryRun ? 'Planned' : 'Updated'} ${result.root}`);
+      for (const path of result.changed) console.log(`  ${result.removed.includes(path) ? 'Remove: ' : ''}${path}`);
+      for (const path of result.preserved) console.log(`  Preserved your edits: ${path}`);
+      console.log(result.settings.backend && result.settings.frontend
+        ? `Ready: ${result.settings.frontends.join(', ')} -> ${result.settings.backend}\nLocal MIMIC: ${result.settings.frontend}`
+        : `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 refresh allowed hosts and MIMIC. Reload your production environment when changing MIMIC.');
+      if (result.isNewNuxt) console.log('Run npm install in the project, then npm run dev.');
+      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.'
+        : 'Update complete. Restart development, or rebuild and redeploy your production frontend.');
+    }
   }
 } catch (error) {
   console.error(`Orionplace: ${error.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orionplace-nuxt",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Nuxt integration and setup CLI for your Orionplace personal marketplace backend.",
   "type": "module",
   "license": "MIT",
@@ -31,11 +31,12 @@
     "bin",
     "src",
     "runtime",
+    "templates",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --experimental-strip-types --test test/*.test.mjs"
   },
   "peerDependencies": {
     "nuxt": "^4.0.0"

package/src/project-readme.mjs

@@ -98,53 +98,88 @@ In another terminal:
 \`\`\`bash
 curl -i http://localhost:3000/api/appload \\
   -H 'Content-Type: application/json' \\
-  --data '{"ignore_cache":true,"detalize_mode":"full"}'
+  --data '{"ignore_cache":true,"detalize_mode":"light"}'
 \`\`\`
 
 Check both the HTTP status and \`form_errors\`. Successful initialization returns
 \`page_data\`; HTTP 200 by itself is insufficient. Documentation and public requests
 do not require a login prompt. Protected actions still require backend permission.
 
-Browser requests use the storefront's own API path:
-
-\`\`\`javascript
-const response = await fetch('/api/appload', {
-  method: 'POST',
-  credentials: 'same-origin',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ ignore_cache: true, detalize_mode: 'full' }),
-});
-const result = await response.json();
-console.log(response.status, result);
-\`\`\`
+## AppLoad initialization
+
+The generated \`app/app.vue\` calls \`useOrionplaceAppLoad()\` and displays loading,
+success or failure, HTTP status, session state and counts of returned sections.
+Use **Reload AppLoad** to issue a fresh request. A failed request never opens a
+login modal. Once the connection works, replace this debug page with your storefront.
+
+| Project file | Purpose |
+| --- | --- |
+| \`app/composables/useOrionplaceAppLoad.ts\` | SSR-aware initialization and manual reload. |
+| \`app/utils/orionplaceAppLoad.ts\` | HTTP, form-error and bootstrap-envelope checks. |
+| \`app/interfaces/orionplace/index.ts\` | All AppLoad interfaces and nested model exports. |
+| \`app/interfaces/orionplace/transport.ts\` | Request, response, result and error contracts. |
+
+The interfaces cover initialization settings, locales, currencies, units, catalog,
+products, banners, events, tariffs and subscriptions, API discovery and forms,
+and the optional signed-in profile. Plugin-defined JSON remains explicitly typed
+as JSON; interfaces are not a full runtime schema validator.
+
+The server uses the current request's domain and session. Its result is reused
+during browser hydration, and new response cookies are relayed to the browser.
+The page response uses \`private, no-store\`; do not put personalized pages behind
+shared HTML caches. Reloading replaces the current session's discovery data.
+
+Requests use \`detalize_mode: "light"\` and \`ignore_cache: true\`. Tenant settings
+can override these options, and individual initialization sections have separate
+backend caches. Full endpoint descriptions are therefore optional.
 
-For SSR, use Nuxt's \`useRequestFetch()\` so the request's domain, cookie and
-authorization headers reach the same gateway. For example, in \`app/app.vue\`:
+If your project already has a custom \`app/app.vue\`, the CLI preserves it.
+Integrate the generated composable explicitly:
 
 \`\`\`vue
-<script setup>
-const requestFetch = useRequestFetch();
-const { data, error } = await useAsyncData('marketplace-initialization', () =>
-  requestFetch('/api/appload', {
-    method: 'POST',
-    body: { ignore_cache: true, detalize_mode: 'full' },
-  }),
-);
+<script setup lang="ts">
+import { useOrionplaceAppLoad } from './composables/useOrionplaceAppLoad';
+const { data, status, error, refresh } = await useOrionplaceAppLoad();
+// data.value?.response.page_data contains the typed initialization and discovery.
 </script>
 
 <template>
   <main>
-    <p v-if="error">The marketplace API is currently unavailable.</p>
-    <pre v-else>{{ data }}</pre>
+    <p role="status">AppLoad: {{ status }}</p>
+    <p v-if="error" role="alert">Marketplace initialization failed.</p>
+    <button type="button" :disabled="status === 'pending'" @click="refresh()">Reload AppLoad</button>
+    <p v-if="data">HTTP {{ data.httpStatus }}</p>
   </main>
 </template>
 \`\`\`
 
-Keep private data out of shared caches. This SSR example forwards incoming cookies;
-it does not relay new upstream cookies to the browser. Make session-changing calls
-from the browser, or explicitly append each returned Set-Cookie header to the SSR
-response in your server integration.
+Call the composable once in your app root and pass the data to your components.
+The generated debug view displays section summaries; it does not render profile
+fields, keys or backend exception stacks. The typed response is still available
+to your application, so avoid logging or publishing it indiscriminately.
+
+CLI reruns preserve edited generated source. Review updated package templates
+manually when you have customized a file. Existing custom apps are not replaced.
+
+## Update the package and components
+
+Run this from your project root whenever you want the latest release:
+
+\`\`\`bash
+npx orionplace-nuxt update
+\`\`\`
 
+The command fetches the latest CLI, adds new template files, refreshes unchanged
+generated source, updates the package dependency, and runs \`npm install\`.
+It preserves edited files and lists them for manual review. Find their incoming
+versions under \`node_modules/orionplace-nuxt/templates\` or \`runtime\`.
+Domain mappings, domain settings and \`.env\` are preserved. Upstream file removals
+do not delete local source. Restart development or rebuild and redeploy afterward.
+
+Use \`npx orionplace-nuxt update --dry-run\` to review changes without modifying
+project files or installed dependencies; downloading the CLI may update npm's
+cache. The alias \`npm run orionplace:update\` performs the same normal update.
+If installation fails after source generation, run \`npm install\` and retry.
 
 ## Deploy on your VPS
 

package/src/setup.mjs

@@ -57,7 +57,8 @@ function updateEnvironment(source, domain) {
 }
 
 export async function setupProject({ cwd = process.cwd(), action = 'set', field, value, dryRun = false } = {}) {
-  if (!['set', 'add', 'remove'].includes(action) || (action !== 'set' && field !== 'frontend')) {
+  if (!['set', 'add', 'remove', 'update'].includes(action) ||
+      (['add', 'remove'].includes(action) && field !== 'frontend') || (action === 'update' && field)) {
     throw new Error('Use set backend, add frontend, remove frontend, set mimic, or set frontend.');
   }
   const root = resolve(cwd);
@@ -68,6 +69,9 @@ export async function setupProject({ cwd = process.cwd(), action = 'set', field,
   for (const name of names) current[name] = await read(await safePath(root, name));
   const pkg = current['package.json'] ? JSON.parse(current['package.json']) : { name: 'orionplace-storefront', private: true, type: 'module' };
   const dependencies = { ...pkg.devDependencies, ...pkg.dependencies };
+  if (action === 'update' && (!dependencies.nuxt || !current['orionplace/settings.json'] || !current['orionplace/.generated.json'])) {
+    throw new Error('Update requires an initialized Orionplace Nuxt project. Run init first.');
+  }
   if (!dependencies.nuxt && ['next', '@sveltejs/kit'].some(name => dependencies[name])) throw new Error('This package sets up Nuxt projects only.');
   if (dependencies.nuxt && !/^(?:[~^]|>=)?4(?:\.|$)/.test(dependencies.nuxt)) {
     throw new Error('This release supports Nuxt 4. Upgrade your Nuxt dependency before setup.');
@@ -151,27 +155,53 @@ export async function setupProject({ cwd = process.cwd(), action = 'set', field,
   pkg.scripts['orionplace:remove-frontend'] ||= 'orionplace-nuxt remove frontend';
   pkg.scripts['orionplace:mimic'] ||= 'orionplace-nuxt set mimic';
   pkg.scripts['orionplace:help'] ||= 'orionplace-nuxt help';
+  pkg.scripts['orionplace:update'] ||= 'orionplace-nuxt update';
   pkg.dependencies ||= {};
   pkg.dependencies['orionplace-nuxt'] ||= dependencies['orionplace-nuxt'] || `^${metadata.version}`;
+  if (action === 'update') {
+    pkg.dependencies['orionplace-nuxt'] = metadata.version;
+    if (pkg.devDependencies) delete pkg.devDependencies['orionplace-nuxt'];
+  }
   if (isNewNuxt) {
     pkg.dependencies.nuxt = '^4.5.0';
     pkg.dependencies.vue ||= '^3.5.0';
     pkg.dependencies['vue-router'] ||= '^5.0.0';
   }
+  // Install the complete editable AppLoad source. Never replace a customer's app.
+  const appPath = 'app/app.vue';
+  const existingApp = await read(await safePath(root, appPath));
+  const installApp = existingApp === null || Boolean(previous[appPath]);
+  const templateRoot = new URL('../templates/', import.meta.url);
+  async function planTemplates(directory = '') {
+    for (const entry of await readdir(new URL(directory, templateRoot), { withFileTypes: true })) {
+      const name = directory + entry.name;
+      if (entry.isDirectory()) { await planTemplates(name + '/'); continue; }
+      if (name === appPath && !installApp) continue;
+      await plan(name, await readFile(new URL(name, templateRoot), 'utf8'), { managed: true, preserve: true });
+    }
+  }
+  await planTemplates();
+  if (installApp && !dependencies.sass && !dependencies['sass-embedded']) {
+    pkg.devDependencies ||= {};
+    pkg.devDependencies.sass = '^1.102.0';
+  }
+  if (!await read(await safePath(root, 'tsconfig.json'))) {
+    await plan('tsconfig.json', JSON.stringify({ files: [], references: [
+      { path: './.nuxt/tsconfig.app.json' }, { path: './.nuxt/tsconfig.server.json' },
+      { path: './.nuxt/tsconfig.shared.json' }, { path: './.nuxt/tsconfig.node.json' },
+    ] }, null, 2) + '\n', { managed: true });
+  }
   await plan('package.json', JSON.stringify(pkg, null, 2) + '\n');
   for (const file of ['marketplace.mjs', 'api.mjs', 'domain.mjs']) {
     await plan(`orionplace/runtime/${file}`, await readFile(new URL(`../runtime/${file}`, import.meta.url), 'utf8'), { managed: true, preserve: true });
   }
   await plan('orionplace/README.md', projectReadme(settings), { managed: true, preserve: true });
-  if (isNewNuxt && !(await read(await safePath(root, 'app/app.vue')))) {
-    await plan('app/app.vue', '<template>\n  <main>\n    <h1>Your marketplace</h1>\n    <p>Domain setup and API instructions are in orionplace/README.md.</p>\n  </main>\n</template>\n', { managed: 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'] || '');
-  if (settings.frontend || oldFrontend || !hasMimicSetting) {
+  if (action !== 'update' && (settings.frontend || oldFrontend || !hasMimicSetting)) {
     await plan('.env', updateEnvironment(current['.env'], settings.frontend || ''));
   }
-  if (settings.backend) {
+  if (settings.backend && action !== 'update') {
     const mappings = action === 'remove' || field === 'mimic' ? []
       : field === 'frontend' ? [setting] : settings.frontends;
     for (const domain of mappings) {
@@ -184,7 +214,7 @@ export async function setupProject({ cwd = process.cwd(), action = 'set', field,
     if (!ignore.split(/\r?\n/).includes(entry)) ignore = ignore.replace(/\n*$/, '\n') + entry + '\n';
   }
   await plan('.gitignore', ignore);
-  await plan('orionplace/settings.json', JSON.stringify(settings, null, 2) + '\n');
+  if (action !== 'update') await plan('orionplace/settings.json', JSON.stringify(settings, null, 2) + '\n');
   await plan('orionplace/.generated.json', JSON.stringify(manifest, null, 2) + '\n');
   if (!dryRun) {
     for (const [name, content] of changes) {

package/src/update.mjs

@@ -0,0 +1,36 @@
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { setupProject } from './setup.mjs';
+
+export function runNpm(args, cwd) {
+  const npmCli = process.env.npm_execpath;
+  const command = npmCli ? process.execPath : 'npm';
+  const commandArgs = npmCli ? [npmCli, ...args] : args;
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, commandArgs, { cwd, stdio: 'inherit', shell: false });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => code === 0 ? resolve() : reject(new Error(
+      `npm ${args[0]} failed (${signal || code}).`,
+    )));
+  });
+}
+
+export async function updateProject({ cwd = process.cwd(), dryRun = false, local = false, npm = runNpm } = {}) {
+  cwd = resolve(cwd);
+  // Validate before downloading or writing; the latest CLI repeats preflight with its own templates.
+  const preview = await setupProject({ cwd, action: 'update', dryRun: true });
+  if (!local) {
+    console.log('Checking the latest Orionplace Nuxt release…');
+    await npm(['exec', '--yes', '--prefer-online', '--package=orionplace-nuxt@latest', '--',
+      'orionplace-nuxt', 'update', '--local', '--cwd', cwd, ...(dryRun ? ['--dry-run'] : [])], cwd);
+    return null; // The latest CLI reports its own changes.
+  }
+  if (dryRun) return preview;
+  const result = await setupProject({ cwd, action: 'update' });
+  try {
+    await npm(['install', '--no-audit', '--no-fund'], cwd);
+  } catch (error) {
+    throw new Error(`Source files were updated, but dependency installation failed. Run npm install in the project, then retry update. ${error.message}`);
+  }
+  return result;
+}

package/templates/app/app.vue

@@ -0,0 +1,90 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useHead } from '#imports';
+import { useOrionplaceAppLoad } from './composables/useOrionplaceAppLoad';
+import type { IAppLoadPathsRecord } from './interfaces/orionplace';
+
+useHead({ title: 'Marketplace · AppLoad debug' });
+const { data, status, error, refresh } = await useOrionplaceAppLoad();
+const page = computed(() => data.value?.response.page_data);
+const init = computed(() => page.value?.init);
+const countEndpoints = (routes?: IAppLoadPathsRecord) =>
+  Object.values(routes?.paths ?? {}).reduce((total, section) => total + Object.keys(section).length, 0);
+const stateLabel = computed(() => ({ idle: 'Not started', pending: 'Loading', success: 'Loaded', error: 'Failed' })[status.value]);
+const failure = computed(() => error.value?.data);
+</script>
+
+<template>
+  <main class="bootstrap">
+    <header>
+      <p class="eyebrow">Orionplace · Nuxt starter</p>
+      <h1>Your marketplace connection</h1>
+      <p>This first page checks initialization through <code>POST /api/appload</code>.
+        Replace it with your storefront when the connection is ready.</p>
+    </header>
+    <section aria-labelledby="status-title" :aria-busy="status === 'pending'">
+      <div class="section-heading">
+        <h2 id="status-title">AppLoad state</h2>
+        <button type="button" :disabled="status === 'pending'" @click="refresh()">Reload AppLoad</button>
+      </div>
+      <p role="status" aria-live="polite" class="state" :data-state="status">{{ stateLabel }}</p>
+      <p v-if="status === 'pending'">Loading initialization data and available API endpoints…</p>
+      <div v-else-if="error" role="alert">
+        <p>AppLoad could not initialize. {{ failure?.kind === 'validation' ? 'The backend returned form errors.' :
+          failure?.kind === 'invalid-response' ? 'The response is missing required initialization data.' :
+          failure?.kind === 'network' ? 'The API request did not complete.' : 'The API returned an HTTP error.' }}</p>
+        <p v-if="failure?.httpStatus">HTTP status: <code>{{ failure.httpStatus }}</code></p>
+        <p>Check your backend, frontend domain and <code>MIMIC_FRONT_DOMAIN</code> using
+          <code>npx orionplace-nuxt help</code>. Setup instructions are in <code>orionplace/README.md</code>.</p>
+      </div>
+      <dl v-else-if="data && init">
+        <div><dt>HTTP status</dt><dd>{{ data.httpStatus }}</dd></div>
+        <div><dt>Loaded at (UTC)</dt><dd><time :datetime="data.loadedAt">{{ data.loadedAt }}</time></dd></div>
+        <div><dt>Session</dt><dd>{{ init.is_authenticated ? 'Signed in' : 'Guest' }}</dd></div>
+        <div><dt>Languages</dt><dd>{{ Object.keys(init.locale).length }}</dd></div>
+        <div><dt>Currencies</dt><dd>{{ Object.keys(init.currencies).length }}</dd></div>
+        <div><dt>Public endpoints</dt><dd>{{ countEndpoints(page?.unauth) }}</dd></div>
+        <div><dt>Authenticated endpoints</dt><dd>{{ countEndpoints(page?.auth) }}</dd></div>
+        <div><dt>Catalog roots</dt><dd>{{ init.catalog?.length ?? 'Not included' }}</dd></div>
+        <div><dt>Initial products</dt><dd>{{ init.products?.length ?? 'Not included' }}</dd></div>
+        <div><dt>Tariffs</dt><dd>{{ init.tariffs?.data.length ?? 'Not included' }}</dd></div>
+      </dl>
+    </section>
+    <section aria-labelledby="next-title">
+      <h2 id="next-title">Build from typed initialization data</h2>
+      <p>The request lives in <code>app/composables/useOrionplaceAppLoad.ts</code>.
+        The response and its nested interfaces are in <code>app/interfaces/orionplace/</code>.</p>
+      <p>This debug page shows section counts. Account details, keys and backend diagnostics are not displayed.</p>
+      <a href="https://orionmarket.place/sandbox">Read the marketplace documentation</a>
+    </section>
+  </main>
+</template>
+
+<style lang="scss">
+body { margin: 0; background: #f5f6f8; color: #202b38; font-family: system-ui, sans-serif; }
+.bootstrap {
+  max-width: 860px; margin: 0 auto; padding: 48px 24px;
+  h1, h2 { font-weight: 400; line-height: 1.25; }
+  h1 { font-size: 32px; margin: 12px 0; }
+  h2 { font-size: 21px; margin: 0; }
+  p { line-height: 1.7; }
+  .eyebrow { color: #596777; font-size: 14px; }
+  section { margin-top: 28px; padding: 24px; border: 1px solid #d9dfe6; border-radius: 10px; background: #fff; }
+  .section-heading { display: flex; align-items: center; justify-content: space-between; gap: 16px; flex-wrap: wrap; }
+  .state { display: inline-block; padding: 4px 12px; border-radius: 4px; background: #eaf0f5;
+    &[data-state='success'] { background: #e6f2ec; color: #245c40; }
+    &[data-state='error'] { background: #fbeceb; color: #8c302a; }
+  }
+  button { font: inherit; color: inherit; background: #f5f6f8; border: 1px solid #bfc9d4; border-radius: 5px; padding: 9px 14px; cursor: pointer;
+    &:disabled { opacity: .6; cursor: wait; }
+    &:hover:not(:disabled) { background: #eaf0f5; }
+  }
+  a { color: #245786; text-underline-offset: 3px; }
+  :focus-visible { outline: 2px solid #245786; outline-offset: 4px; }
+  code { font-size: .9em; overflow-wrap: anywhere; }
+  dl { margin-bottom: 0; div { display: grid; grid-template-columns: minmax(140px, 1fr) 2fr; gap: 12px; padding: 12px 0; border-top: 1px solid #e8ecf0; }
+    dt { color: #596777; } dd { margin: 0; overflow-wrap: anywhere; }
+  }
+  @media (max-width: 520px) { padding: 24px 16px; section { padding: 18px; } dl div { grid-template-columns: 1fr; gap: 4px; } }
+}
+</style>

package/templates/app/composables/useOrionplaceAppLoad.ts

@@ -0,0 +1,51 @@
+import { createError, useAsyncData, useRequestFetch, useResponseHeader } from '#imports';
+import type { AppLoadFailure, AppLoadRequest, AppLoadResult } from '../interfaces/orionplace/transport';
+import { appLoadResult, inspectAppLoad } from '../utils/orionplaceAppLoad';
+
+/** Call once in app.vue. Nuxt transfers the SSR result to the browser during hydration. */
+export function useOrionplaceAppLoad() {
+  // SSR forwards the current request's domain, cookies and authorization to our own gateway.
+  const requestFetch = useRequestFetch();
+  const responseCookies = import.meta.server ? useResponseHeader('set-cookie') : undefined;
+  if (import.meta.server) useResponseHeader('cache-control').value = 'private, no-store';
+
+  return useAsyncData<AppLoadResult, AppLoadFailure>(
+    'orionplace:appload',
+    async (_app, { signal }) => {
+      let received: { body: unknown; status: number; cookies: string[] } | undefined;
+      try {
+        await requestFetch<unknown>('/api/appload', {
+          method: 'POST',
+          body: { detalize_mode: 'light', ignore_cache: true } satisfies AppLoadRequest,
+          credentials: 'same-origin',
+          cache: 'no-store',
+          retry: 0,
+          timeout: 35_000,
+          ignoreResponseError: true,
+          signal,
+          onResponse({ response }) {
+            received = { body: response._data, status: response.status,
+              cookies: import.meta.server ? response.headers.getSetCookie() : [] };
+          },
+        });
+      } catch {
+        throw createError({ message: 'Could not reach the marketplace API.', data: {
+          kind: 'network', httpStatus: null, fields: [],
+        } satisfies AppLoadFailure });
+      }
+      if (!received) throw createError({ message: 'The API returned no response.', data: {
+        kind: 'network', httpStatus: null, fields: [],
+      } satisfies AppLoadFailure });
+      // AppLoad can establish a CSRF/session cookie during SSR. Relay each cookie separately.
+      if (responseCookies) {
+        const cookies = received.cookies;
+        const existing = responseCookies.value;
+        if (cookies.length) responseCookies.value = [...(Array.isArray(existing) ? existing : existing ? [String(existing)] : []), ...cookies];
+      }
+      const failure = inspectAppLoad(received.body, received.status);
+      if (failure) throw createError({ message: 'Marketplace initialization failed.', data: failure });
+      return appLoadResult(received.body, received.status);
+    },
+    { deep: false, dedupe: 'defer' },
+  );
+}

package/templates/app/interfaces/orionplace/apiBase/TMethod.ts

@@ -0,0 +1 @@
+export type TMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';

package/templates/app/interfaces/orionplace/appBase/IAppLoad.ts

@@ -0,0 +1,15 @@
+import type { IAppLoadCommon } from './IAppLoadCommon';
+import type { IApploadUserProfile } from './IApploadUserProfile';
+import type { IAppLoadPathsRecord } from './appLoadCommon/IAppLoadCommonPath';
+
+export interface IAppLoad {
+	init: IAppLoadCommon;
+	unauth: IAppLoadPathsRecord;
+	user?: IApploadUserProfile;
+	auth?: IAppLoadPathsRecord;
+	view_key?: string;
+	spent_total?: number;
+	spent_init?: number;
+	unauth_spent?: number;
+	auth_spent?: number;
+}

package/templates/app/interfaces/orionplace/appBase/IAppLoadCommon.ts

@@ -0,0 +1,54 @@
+import type { IAppLoadCommonLocale } from './appLoadCommon/IAppLoadCommonLocale';
+import type { IAppLoadCommonCurrency } from './appLoadCommon/IAppLoadCommonCurrency';
+import type { IAppLoadCommonUnit } from './appLoadCommon/IAppLoadCommonUnit';
+import type { IAppLoadCommonLogos } from './appLoadCommon/IAppLoadCommonLogos';
+import type { IGeoCoordinates } from '../shared/IGeoCoordinates';
+import type { IAppLoadCommonSeo } from './appLoadCommon/IAppLoadCommonSEO';
+import type { IAppLoadCommonSocial } from './appLoadCommon/IAppLoadCommonSocial';
+import type { IAppLoadCommonVisualSettings } from './appLoadCommon/IAppLoadCommonVisualSettings';
+import type { IAppLoadCommonEvents } from './appLoadCommon/IAppLoadCommonEvents';
+import type { IAppLoadCommonBanner } from './appLoadCommon/IAppLoadCommonBanner';
+import type { ICategory } from '../category/ICategory';
+import type { IProduct } from '../products/IProduct';
+import type { IAppLoadCommonTariff } from './appLoadCommon/IAppLoadCommonTariff';
+import type { IAppLoadCommonWalletValue } from './appLoadCommon/IAppLoadCommonWalletValue';
+import type { IAppLoadCommonVariables } from './appLoadCommon/IAppLoadCommonVariables';
+import type { IAppLoadCommonContact } from './appLoadCommon/IAppLoadCommonContact';
+
+export interface IAppLoadCommon {
+	locale: Record<string, IAppLoadCommonLocale>;
+	currencies: Record<string, IAppLoadCommonCurrency>;
+	weights: Record<string, IAppLoadCommonUnit>;
+	lengths: Record<string, IAppLoadCommonUnit>;
+	geo_location_enabled: boolean;
+	is_authenticated: boolean;
+	wallet?: Record<string, IAppLoadCommonWalletValue>;
+	logos: IAppLoadCommonLogos;
+	public_keys: Record<string, string>;
+	default_map: IGeoCoordinates;
+	seo?: IAppLoadCommonSeo[];
+	sm?: IAppLoadCommonSocial[];
+	variables?: IAppLoadCommonVariables;
+	contact?: IAppLoadCommonContact;
+	visual_settings?: IAppLoadCommonVisualSettings;
+	events?: IAppLoadCommonEvents[];
+	main_banner?: Record<string, IAppLoadCommonBanner[]>;
+	catalog?: ICategory[];
+	products?: IProduct[];
+	featured?: IProduct[];
+	search_hints?: Record<string, string>[];
+	tariffs?: IAppLoadCommonTariff;
+	stock?: { mode: 'bar' | 'qr'; simple: boolean };
+	order?: { order_auto_register_with_carrier: boolean };
+	promo?: { create_benefits: boolean };
+	product?: { common_properties: boolean };
+	app?: { backend: boolean };
+	domains?: IAppLoadDomain[];
+}
+
+export interface IAppLoadDomain {
+	id: number;
+	domain_group: number | null;
+	domain: string;
+	is_active: boolean;
+}