cabloy 5.1.122 → 5.1.124

package/.cabloy-version

@@ -1 +1 @@
-5.1.122
+5.1.124

package/.claude/skills/cabloy-frontend-scaffold/SKILL.md

@@ -36,6 +36,14 @@ Then classify the request:
 
 Default to frontend-first. Only escalate mentally to a broader fullstack workflow when the frontend task obviously crosses the contract boundary.
 
+### Decide a form layout or ask
+
+When the task changes a schema-driven form, inspect the generated baseline, operation-specific DTO/schema, nearby Cabloy forms, the active edition and UI adapter, field relationships, and the user's stated workflow before choosing a layout.
+
+Proceed autonomously when that evidence establishes the form purpose and field relationships. Choose the smallest fitting structure: no explicit layout for a short conventional form, flow for compact filters, Grid for responsive related fields, a group for one meaningful business boundary, or tabs for genuinely independent domains or workflows. State the consequential business assumptions with the implementation.
+
+Ask one focused business question only when the layout would encode an unresolved semantic or authority decision: whether areas are independent or one workflow, which audience or task has priority, whether a form is a compact filter or a full entry workflow, or whether staged responsibilities are intended. Do not ask merely because several visual arrangements are technically valid.
+
 If the user is still deciding a new business-domain boundary or suite/module naming, use the root `cabloy-domain-planning` skill before scaffolding.
 
 If the task is really a broad cross-stack workflow, consider whether the root `cabloy-workflow` skill is the better primary router.
@@ -205,6 +213,7 @@ Especially relevant pages include:
 - `cabloy-docs/frontend/route-alias-guide.md`
 - `cabloy-docs/frontend/navigation-guards-guide.md`
 - `cabloy-docs/frontend/component-guide.md`
+- `cabloy-docs/frontend/form-layout-guide.md` for schema-driven field placement, Grid/flow selection, groups, tabs, or embedded filter actions
 - `cabloy-docs/frontend/component-props-guide.md`
 - `cabloy-docs/frontend/component-v-model-guide.md`
 - `cabloy-docs/frontend/generic-component-guide.md`
@@ -249,8 +258,9 @@ When helpful, structure the response around these points:
 1. detected edition
 2. frontend-first or clearly fullstack-sensitive classification
 3. recommended Zova CLI path
-4. required frontend follow-up layers to check
-5. optional backend-contract reminder if applicable
-6. verification steps
+4. form-layout decision, consequential business assumptions, and any user-confirmed boundary when the task is layout-sensitive
+5. required frontend follow-up layers to check
+6. optional backend-contract reminder if applicable
+7. verification steps
 
 Keep the response practical. The value of this skill is turning Cabloy frontend requests into the right generation + refactor + verification workflow, not writing more prose than necessary.

package/.claude/skills/cabloy-workflow/SKILL.md

@@ -98,6 +98,12 @@ For deeper reference material, read:
 
 The reason is simple: these files are where Cabloy already encodes its real workflows.
 
+### Parallel worktree environment setup
+
+When a request involves a second worktree, concurrent Vona/Zova development, isolated ordinary tests, or managed clean E2E, classify it as fullstack workflow setup. Read [Parallel Worktree Environment](../../../cabloy-docs/fullstack/parallel-worktree-environment.md) for the canonical Cabloy Basic recipe.
+
+Before applying the broad `.env.local` recipe, check for more-specific `.env.*.local` overrides. Keep Vona and Zova `APP_NAME` values aligned, use the required matching API target, and add database, Redis, external-service, mock, or SSR-preview isolation only when the work actually uses those shared resources. For Cabloy Start, inspect the active Start repository rather than reusing the Basic recipe unchanged.
+
 ## Step 4: Prefer CLI-first workflows
 
 Whenever the task maps to an existing generator, initializer, refactor, or metadata command, prefer the CLI.

package/.claude/skills/cabloy-workflow/evals/evals.json

@@ -30,6 +30,12 @@
       "prompt": "I want to update the public guidance for Cabloy contributors about using CLI generators first, but I also think Claude should follow the same rule automatically. Where should each part of that knowledge live?",
       "expected_output": "Splits the guidance across public docs and Claude rules/skills appropriately, keeping maintainer rationale out of public docs unless needed.",
       "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "I created a second Cabloy Basic worktree and need to run Vona, Zova, and test:e2e:basic:clean in parallel with the first worktree. Which environment files and exact variables should I configure without changing shared defaults?",
+      "expected_output": "Classifies this as fullstack parallel-worktree environment setup and routes to the canonical Parallel Worktree Environment guide. Checks for more-specific local overrides, uses Vona vona/env/.env.local with APP_NAME and SERVER_LISTEN_PORT, and Zova zova/env/.env.local with the same APP_NAME plus API_BASE_URL pointing to that Vona port, DEV_SERVER_PORT, and DEV_SERVER_HMR_PORT. Keeps SSR_API_BASE_URL inherited from API_BASE_URL unless a more-specific override changes it, and adds database, Redis, external-service, mock, or SSR-preview settings only when those resources are actually used.",
+      "files": []
     }
   ]
 }

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 5.1.124
+
+### Improvements
+
+- Refresh the Zova lockfile and core patch dependencies.
+
+## 5.1.123
+
+### Features
+
+- Add payment payload handling and A-Pay integration updates.
+- Add OpenAPI configuration support.
+- Add configurable E2E test port support.
+- Update payment scene and session view capabilities.
+
+### Bug Fixes
+
+- Import `VNode` as a type in `zova-core`.
+
+### Improvements
+
+- Align commerce documentation with the acceptance gate.
+- Update application components, SSR menu configuration, package metadata, and dependencies.
+
 ## 5.1.122
 
 ### Features

package/CLAUDE.md

@@ -58,7 +58,7 @@ Before inventing a custom implementation path:
 - Default to establishing such query state during render. Use `disableSuspenseOnInit: true` only for relatively stable query-backed state when you want to skip the init-time `query.suspense()` kick; it does not prevent query creation, fetches, or hydration-time rendering. If strict readiness is needed later, wait explicitly at the interaction boundary.
 - In SSR, keep server HTML and the client's hydration-time initial render equivalent. When server rendering intentionally omits private, cookie-unavailable, or browser-only state, keep the same neutral shell or placeholder through hydration and defer its query/load/render branch to an explicit post-hydration, admission, mounted, or interaction boundary.
 - Keep repo-wide AI rules in `CLAUDE.md` short and durable; put branching Zova analysis workflows in `.claude/skills/`.
-- Do not modify `APP_NAME` in environment files unless the user explicitly requests it. When another worktree holds shared test resources, wait and retry later rather than changing application identity or related environment settings.
+- Do not modify shared environment identity or ports merely to bypass a busy resource. For intentional parallel worktree setup, follow `cabloy-docs/fullstack/parallel-worktree-environment.md`; otherwise wait for the shared resource or ask the user.
 - For SSR theme-sensitive frontend work, detect the active edition marker and UI library before making assumptions. Cabloy Basic currently means DaisyUI + Tailwind CSS assumptions; Cabloy Start currently means Vuetify assumptions.
 - In Web SSR without cookie-backed theme resolution, do not treat server reads of `$theme.dark`, `$theme.darkMode`, or `$token` as final browser truth. Keep theme-sensitive SSR branching hydration-tolerant or defer final theme-sensitive decisions to the client.
 - Do not assume Cabloy Basic and Cabloy Start use the same adapter-level SSR theme handoff. Verify the active theme handler and client hydration path before changing SSR theme behavior.

package/cabloy-docs/.vitepress/config.mjs

@@ -75,6 +75,10 @@ const fullstackGroups = [
     text: 'Tooling & Workflow',
     items: [
       { text: 'CLI', link: '/fullstack/cli' },
+      {
+        text: 'Parallel Worktree Environment',
+        link: '/fullstack/parallel-worktree-environment',
+      },
       { text: 'VS Code Extensions', link: '/fullstack/vscode-extensions' },
     ],
   },

package/cabloy-docs/frontend/form-layout-guide.md

@@ -7,6 +7,27 @@ This guide covers the **structural** layout contract authored in DTO metadata an
 > [!TIP]
 > Cabloy Basic implements the renderer described here with DaisyUI and Tailwind CSS. The `formLayout` contract and its resolver are shared Zova surfaces, but group, Grid, flow, and tab presentation are Basic-specific. Do not assume Cabloy Start uses identical markup or styling.
 
+## Choose the layout from the business form
+
+Start with the user's task, information hierarchy, and audience—not with the available layout node types or the number of fields. The generated CRUD layout is a valid baseline to review and refine, not a requirement to preserve unchanged.
+
+Choose the smallest structure that communicates the business form:
+
+| Business shape                                                                              | Recommended structure                                                          |
+| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| A short, conventional form whose schema order is already clear                              | No explicit `formLayout`, or a flat field list when placement must be explicit |
+| One meaningful business subsection                                                          | A `group` with a title that explains the boundary                              |
+| Related fields users complete or compare together and that need responsive density or spans | A Grid `section`, normally inside the relevant group                           |
+| Compact scan-and-act controls, especially a list filter with Search/Reset                   | A `section` with `layout: 'flow'` and one embedded filter-actions block        |
+| Genuinely separate business domains or workflows                                            | `tabs` with one `tab` per independent area                                     |
+| A nested detail collection                                                                  | One normal `field`; its field renderer owns the detail UI                      |
+
+Do not select tabs merely because a form has many fields, and do not add a structural tree merely because the API supports one. A `group` communicates a semantic boundary; a `section` solves Grid or flow placement. Field renderer and wrapper requirements remain separate concerns, as explained in the next section.
+
+Create, update, and view can reuse one layout when they present the same information hierarchy. When their tasks differ—for example, a focused creation workflow versus a review-oriented view—author scene-specific DTO layouts instead of forcing a shared tree. Likewise, choose entry-form and filter layouts independently: a compact filter is not a smaller entry form.
+
+When the business grouping is unknown, keep the simpler layout or clarify the grouping before introducing groups or tabs. See the [complete entry-form example](#complete-entry-form-example) for a justified tabbed business form and the [complete filter-form example](#complete-filter-form-example) for the maintained compact filter convention.
+
 ## The layout layers are different
 
 Several APIs contain the word “layout,” but they own different concerns:
@@ -330,13 +351,14 @@ Here `formFieldLayout.inline: true` controls how each field wrapper is presented
 
 ## Authoring checklist
 
-1. Start with DTO or resource metadata; do not hand-patch generated `.zova-rest` artifacts.
-2. Use `formLayout` when the requirement is field placement, Grid or flow structure, groups, or tabs.
-3. Use `layout`, `formFieldLayout`, `options`, or provider behaviors when the requirement is one field's wrapper or renderer.
-4. Keep entry actions in page-entry toolbar blocks. Keep filter action semantics in `basic-page:blockFilterActions`; place that block inside Form Layout when the actions must share structural Grid or flow placement with fields.
-5. For maintained Cabloy Basic list filters, prefer one inline flow section that explicitly lists every real filter-schema field in schema order and ends with one embedded `basic-page:blockFilterActions` block. Do not add virtual request fields, alter filter transforms, or combine it with a sibling action block.
-6. Review field names against the scene-specific schema. Unlisted visible fields are appended; unknown and duplicate declarations are silently pruned from the rendered plan.
-7. Use the smallest layout that communicates the form structure; reserve tabs for genuinely separate field groups.
+1. Identify the audience, task, and meaningful field groupings for the operation-specific DTO before choosing a structural tree.
+2. Start with DTO or resource metadata; do not hand-patch generated `.zova-rest` artifacts.
+3. Use no structural layout when schema order is sufficient. Otherwise use the smallest layout that communicates the business structure; reserve tabs for genuinely separate business domains or workflows.
+4. Use `formLayout` when the requirement is field placement, Grid or flow structure, groups, or tabs.
+5. Use `layout`, `formFieldLayout`, `options`, or provider behaviors when the requirement is one field's wrapper or renderer.
+6. Keep entry actions in page-entry toolbar blocks. Keep filter action semantics in `basic-page:blockFilterActions`; place that block inside Form Layout when the actions must share structural Grid or flow placement with fields.
+7. For maintained Cabloy Basic list filters, prefer one inline flow section that explicitly lists every real filter-schema field in schema order and ends with one embedded `basic-page:blockFilterActions` block. Do not add virtual request fields, alter filter transforms, or combine it with a sibling action block.
+8. Review field names against the scene-specific schema. Unlisted visible fields are appended; unknown and duplicate declarations are silently pruned from the rendered plan.
 
 ## Source-reading and verification path
 

package/cabloy-docs/fullstack/parallel-worktree-environment.md

@@ -0,0 +1,87 @@
+# Parallel Worktree Environment
+
+Use worktree-local environment overrides when two Cabloy Basic worktrees need to run ordinary local development or managed E2E checks at the same time.
+
+This workflow creates an isolated local runtime without changing committed environment defaults. It covers normal Vona and Zova development, `npm run test`, and `npm run test:e2e:XXX:clean`. It does not automatically isolate every external dependency.
+
+## Before creating local overrides
+
+1. Confirm that the checkout is a separate worktree.
+2. Check `vona/env/` and `zova/env/` for applicable, more-specific `.env.*.local` files. A more-specific local override can take precedence over `.env.local`.
+3. Choose one unique worktree name and unused Vona, Zova, and HMR ports.
+
+The repository ignores `**/env/.env*.local`, so these files remain local to the worktree and must not be committed.
+
+## Minimum configuration
+
+Create these files in the new worktree.
+
+### Vona
+
+`vona/env/.env.local`
+
+```dotenv
+APP_NAME = cabloy-basic-my-worktree
+SERVER_LISTEN_PORT = 7113
+```
+
+### Zova
+
+`zova/env/.env.local`
+
+```dotenv
+APP_NAME = cabloy-basic-my-worktree
+API_BASE_URL = http://localhost:7113
+DEV_SERVER_PORT = 9013
+DEV_SERVER_HMR_PORT = 24693
+```
+
+Keep these invariants:
+
+- Vona and Zova use the same unique `APP_NAME`.
+- `API_BASE_URL` points to the selected Vona `SERVER_LISTEN_PORT`.
+- `SERVER_LISTEN_PORT`, `DEV_SERVER_PORT`, and `DEV_SERVER_HMR_PORT` are unique among concurrently running worktrees.
+
+The base Zova environment defines `SSR_API_BASE_URL = $API_BASE_URL`, so SSR uses the same Vona target in the normal baseline. Add an explicit local `SSR_API_BASE_URL` only if an applicable, more-specific environment file changes that relationship.
+
+## What this isolates
+
+A unique `APP_NAME` separates the application identity used by ordinary framework-managed local resources, including managed test database names and Redis-related key prefixes. Worktree-local generated files, runtime files, build output, and coverage output are already separated by their worktree paths.
+
+The selected Vona, Zova, and HMR ports let the worktrees run their ordinary local processes concurrently. The matching Zova API URL prevents the frontend in one worktree from calling the Vona process in another.
+
+This is sufficient for the normal local workflows:
+
+```bash
+npm run dev
+npm run dev:zova:admin
+npm run dev:zova:web
+npm run test
+npm run test:e2e:basic:clean
+```
+
+The managed clean E2E workflow reads Vona's effective local `SERVER_LISTEN_PORT`, then resets, starts, and targets that local runtime.
+
+## Add configuration only when the work uses it
+
+Do not add isolation settings preemptively. Extend the local overrides only when the selected workflow actually shares one of these resources:
+
+- an explicitly named database or a separately configured Redis target
+- mail, payment, webhook, object-storage, or other external providers
+- a standalone mock-build process, using `MOCK_BUILD_PORT`
+- an SSR preview or production process, using `SSR_PROD_PORT`
+
+For example, `APP_NAME` namespaces ordinary framework Redis keys, but it does not create a separate Redis server or automatically isolate custom, unprefixed keys. Likewise, an explicitly configured external database remains shared until it is configured separately.
+
+## Edition-aware note
+
+This page describes the current Cabloy Basic workflow. For Cabloy Start, detect the active edition first and inspect the Start repository's current scripts, flavors, environment files, and generated-output paths before applying this recipe.
+
+## Read together with
+
+- [Quick Start](/fullstack/quickstart)
+- [Vona + Zova Integration](/fullstack/vona-zova-integration)
+- [Runtime Environments and Flavors](/backend/runtime-and-flavors)
+- [Environment and Config Guide](/frontend/environment-config-guide)
+- [SSR Environment Variables](/frontend/ssr-env)
+- [Mock Guide](/frontend/mock-guide)

package/e2e/scripts/e2e.ts

@@ -1,8 +1,20 @@
+import * as dotenv from '@cabloy/dotenv';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 export const E2E_ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
-export const E2E_PORT = 7102;
+
+const vonaEnv = dotenv.loadEnvs(
+  { flavor: 'normal', mode: 'dev', local: 'local' },
+  resolve(E2E_ROOT_DIR, 'vona', 'env'),
+  '.env',
+);
+const e2ePort = Number(vonaEnv?.SERVER_LISTEN_PORT);
+if (!Number.isInteger(e2ePort) || e2ePort <= 0 || e2ePort > 65535) {
+  throw new Error('Missing or invalid SERVER_LISTEN_PORT for local E2E target');
+}
+
+export const E2E_PORT = e2ePort;
 export const E2E_LOCAL_BASE_URL = `http://127.0.0.1:${E2E_PORT}`;
 
 const E2E_CONFIG_DIR = resolve(E2E_ROOT_DIR, 'e2e', 'config');

package/e2e/scripts/startE2eVona.ts

@@ -1,11 +1,14 @@
+import type { ChildProcess } from 'node:child_process';
+
 import { spawn } from 'node:child_process';
 
 import { E2E_ROOT_DIR } from './e2e.ts';
 
-const child = spawn('npm', ['run', 'dev:one'], {
+const child: ChildProcess = spawn('npm', ['run', 'dev:one'], {
   cwd: E2E_ROOT_DIR,
   detached: process.platform !== 'win32',
   stdio: 'inherit',
+  env: process.env,
 });
 
 const gracefulShutdownTimeout = 7000;

package/e2e/specs/a-commerce/commerce.spec.ts

@@ -1,4 +1,4 @@
-import type { APIRequestContext, Browser, Page, TestInfo } from '@playwright/test';
+import type { APIRequestContext, Browser, Locator, Page, TestInfo } from '@playwright/test';
 
 import { expect, test } from '@playwright/test';
 
@@ -35,6 +35,10 @@ function waitForApiResponse(page: Page, method: string, path: string | RegExp) {
   });
 }
 
+function expectTableIdentity(value: unknown) {
+  expect(['string', 'number']).toContain(typeof value);
+}
+
 function waitForAddressResponse(page: Page, method: string, path: string | RegExp) {
   return waitForApiResponse(page, method, path);
 }
@@ -43,6 +47,12 @@ function waitForAddressMine(page: Page) {
   return waitForAddressResponse(page, 'GET', addressMinePath);
 }
 
+async function getAdminOrderRow(page: Page, orderId: number): Promise<Locator> {
+  const row = page.locator(`tr:has(td:first-child:text-is("${orderId}"))`);
+  await expect(row).toHaveCount(1);
+  return row;
+}
+
 async function login(
   page: Page,
   path: string,
@@ -63,7 +73,14 @@ async function login(
     await expect(usernameInput).toHaveValue(username);
     await expect(passwordInput).toHaveValue(password);
     await expect(page.getByPlaceholder('Please input captcha')).not.toHaveValue('');
+    const loginResponse = waitForApiResponse(page, 'POST', '/api/home/user/passport/login');
     await page.getByRole('button', { name: 'Login', exact: true }).click();
+    const loginResponseValue = await loginResponse;
+    if (!loginResponseValue.ok()) {
+      throw new Error(
+        `login failed: ${loginResponseValue.status()} ${await loginResponseValue.text()}`,
+      );
+    }
     await expect(page).not.toHaveURL(/\/login(?:\?|$)/);
   }
 }
@@ -383,38 +400,43 @@ test(
       const checkoutResponseValue = await checkoutResponse;
       expect(checkoutResponseValue.ok()).toBeTruthy();
       const checkout = (await checkoutResponseValue.json()).data;
-      expect(checkout.orderId).toEqual(expect.any(Number));
-      expect(checkout.paymentAttemptId).toEqual(expect.any(Number));
+      expectTableIdentity(checkout.orderId);
+      expectTableIdentity(checkout.paymentAttemptId);
+      expectTableIdentity(checkout.paymentSessionId);
       expect(checkout.state).toBe('awaiting_payment');
       expect(checkout.paymentAttemptState).toBe('created');
       expect(checkout.currency).toBe('USD');
       expect(checkout.payableTotalCents).toBe(4599);
       await expect(page).toHaveURL(
-        new RegExp(`/commerce/payment/${checkout.paymentAttemptId}(?:/|$)`),
+        new RegExp(`/commerce/payment/${checkout.paymentSessionId}/${checkout.orderId}(?:/|$)`),
       );
-      await expect(page.getByRole('heading', { name: 'Mock payment' })).toBeVisible();
+      await expect(page.getByRole('heading', { name: 'Payment', exact: true })).toBeVisible();
 
-      const paymentResponse = waitForApiResponse(
+      const startResponse = waitForApiResponse(
+        page,
+        'POST',
+        new RegExp(`/api/payment-session/${checkout.paymentSessionId}/start$`),
+      );
+      await page.getByRole('button', { name: 'Start payment', exact: true }).click();
+      expect((await startResponse).ok()).toBeTruthy();
+      await expect(page.getByText('Payment is being prepared.')).toBeVisible();
+      await expect(page.getByRole('heading', { name: 'Mock payment simulator' })).toBeVisible();
+      const completeResponse = waitForApiResponse(
         page,
         'POST',
-        new RegExp(`/api/commerce/trade/payment/${checkout.paymentAttemptId}/outcome$`),
+        new RegExp(`/api/pay/mock/payment-session/${checkout.paymentSessionId}/complete$`),
       );
+      await page.getByRole('button', { name: 'Payment succeeded', exact: true }).click();
+      expect((await completeResponse).ok()).toBeTruthy();
+      await expect(page).toHaveURL(new RegExp(`/commerce/order/${checkout.orderId}(?:/|$)`), {
+        timeout: 40_000,
+      });
       const orderDetailResponse = waitForApiResponse(
         page,
         'GET',
-        new RegExp('/api/commerce/trade/order/viewMine/\\d+$'),
+        new RegExp(`/api/commerce/trade/order/viewMine/${checkout.orderId}$`),
       );
-      await page.getByRole('button', { name: 'Payment succeeded', exact: true }).click();
-      const paymentResponseValue = await paymentResponse;
-      expect(paymentResponseValue.ok()).toBeTruthy();
-      const payment = (await paymentResponseValue.json()).data;
-      expect(payment.orderId).toBe(checkout.orderId);
-      expect(payment.paymentAttemptId).toBe(checkout.paymentAttemptId);
-      expect(payment.orderState).toBe('paid');
-      expect(payment.paymentAttemptState).toBe('succeeded');
-      expect(payment.currency).toBe('USD');
-      expect(payment.payableTotalCents).toBe(4599);
-      await expect(page).toHaveURL(new RegExp(`/commerce/order/${checkout.orderId}(?:/|$)`));
+      await page.reload({ waitUntil: 'load' });
       const orderDetailResponseValue = await orderDetailResponse;
       expect(orderDetailResponseValue.ok()).toBeTruthy();
       const order = (await orderDetailResponseValue.json()).data;
@@ -459,9 +481,7 @@ test(
           'data-zova-hydrated',
           'commerceAdmin',
         );
-        const orderRow = adminPage
-          .getByRole('cell', { name: String(checkout.orderId), exact: true })
-          .locator('..');
+        const orderRow = await getAdminOrderRow(adminPage, checkout.orderId);
         await expect(orderRow).toBeVisible();
         const carrierInput = orderRow.getByPlaceholder('Carrier');
         const trackingNumberInput = orderRow.getByPlaceholder('Tracking number');
@@ -525,6 +545,70 @@ test(
   },
 );
 
+test(
+  'Payment cancellation: customer observes the cancelled order after verified provider confirmation',
+  { tag: ['@web', '@flow', '@payment'] },
+  async ({ browser, request }, testInfo) => {
+    test.setTimeout(60_000);
+    const { context, fixture, page, pageErrors } = await createAddressThroughCustomerPage(
+      browser,
+      request,
+      testInfo,
+    );
+    try {
+      await page.goto('/commerce', { waitUntil: 'load' });
+      await expect(page.locator('html')).toHaveAttribute('data-zova-hydrated', 'commerce');
+      const productLink = page.getByRole('link', { name: 'Pour-Over Coffee Set', exact: true });
+      await expect(productLink).toBeVisible();
+      await productLink.click();
+      await expect(page).toHaveURL(/\/commerce\/product\/\d+(?:\/|$)/);
+      await expect(page.getByRole('heading', { name: 'Pour-Over Coffee Set' })).toBeVisible();
+      const addResponse = waitForApiResponse(page, 'POST', '/api/commerce/trade/cart/items');
+      await page.getByRole('button', { name: 'Add to cart', exact: true }).click();
+      expect((await addResponse).ok()).toBeTruthy();
+      await page.getByRole('link', { name: /^Cart/ }).click();
+      await expect(page).toHaveURL(/\/commerce\/cart(?:\/|$)/);
+      await page.getByRole('link', { name: 'Checkout', exact: true }).click();
+      await expect(page).toHaveURL(/\/commerce\/checkout(?:\/|$)/);
+      const addressChoice = page.getByRole('radio', { name: new RegExp(fixture.recipientName) });
+      await expect(addressChoice).toBeVisible();
+      await addressChoice.check();
+      await page.getByRole('radio', { name: 'No coupon', exact: true }).check();
+      const checkoutResponse = waitForApiResponse(page, 'POST', '/api/commerce/trade/checkout');
+      await page.getByRole('button', { name: 'Create order', exact: true }).click();
+      const checkoutResponseValue = await checkoutResponse;
+      expect(checkoutResponseValue.ok()).toBeTruthy();
+      const checkout = (await checkoutResponseValue.json()).data;
+      expectTableIdentity(checkout.orderId);
+      expectTableIdentity(checkout.paymentSessionId);
+      const startResponse = waitForApiResponse(
+        page,
+        'POST',
+        new RegExp(`/api/payment-session/${checkout.paymentSessionId}/start$`),
+      );
+      await page.getByRole('button', { name: 'Start payment', exact: true }).click();
+      expect((await startResponse).ok()).toBeTruthy();
+      await expect(page.getByText('Payment is being prepared.')).toBeVisible();
+      await expect(page.getByRole('heading', { name: 'Mock payment simulator' })).toBeVisible();
+      const cancelResponse = waitForApiResponse(
+        page,
+        'POST',
+        new RegExp(`/api/pay/mock/payment-session/${checkout.paymentSessionId}/complete$`),
+      );
+      await page.getByRole('button', { name: 'Cancel payment', exact: true }).click();
+      expect((await cancelResponse).ok()).toBeTruthy();
+      await expect(page).toHaveURL(new RegExp(`/commerce/order/${checkout.orderId}(?:/|$)`), {
+        timeout: 40_000,
+      });
+      await expect(page.getByText('cancelled · $45.99')).toBeVisible();
+      await expect(page.getByRole('alert')).toHaveCount(0);
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await context.close().catch(() => {});
+    }
+  },
+);
+
 test(
   'Phase 60: customer requests and operator executes a whole-order refund',
   { tag: ['@web', '@admin', '@flow', '@payment', '@refund'] },
@@ -558,15 +642,30 @@ test(
       await page.getByRole('radio', { name: 'No coupon', exact: true }).check();
       const checkoutResponse = waitForApiResponse(page, 'POST', '/api/commerce/trade/checkout');
       await page.getByRole('button', { name: 'Create order', exact: true }).click();
-      const checkout = (await (await checkoutResponse).json()).data;
-      const paymentResponse = waitForApiResponse(
+      const checkoutResponseValue = await checkoutResponse;
+      expect(checkoutResponseValue.ok()).toBeTruthy();
+      const checkout = (await checkoutResponseValue.json()).data;
+      expectTableIdentity(checkout.orderId);
+      expectTableIdentity(checkout.paymentAttemptId);
+      expectTableIdentity(checkout.paymentSessionId);
+      await expect(page.getByRole('heading', { name: 'Payment', exact: true })).toBeVisible();
+      const startResponse = waitForApiResponse(
         page,
         'POST',
-        new RegExp(`/api/commerce/trade/payment/${checkout.paymentAttemptId}/outcome$`),
+        new RegExp(`/api/payment-session/${checkout.paymentSessionId}/start$`),
+      );
+      await page.getByRole('button', { name: 'Start payment', exact: true }).click();
+      expect((await startResponse).ok()).toBeTruthy();
+      await expect(page.getByText('Payment is being prepared.')).toBeVisible();
+      await expect(page.getByRole('heading', { name: 'Mock payment simulator' })).toBeVisible();
+      const completeResponse = waitForApiResponse(
+        page,
+        'POST',
+        new RegExp(`/api/pay/mock/payment-session/${checkout.paymentSessionId}/complete$`),
       );
       await page.getByRole('button', { name: 'Payment succeeded', exact: true }).click();
-      expect((await paymentResponse).ok()).toBeTruthy();
-      await expect(page.getByText('paid · $45.99')).toBeVisible();
+      expect((await completeResponse).ok()).toBeTruthy();
+      await expect(page.getByText('paid · $45.99')).toBeVisible({ timeout: 40_000 });
 
       const requestResponse = waitForApiResponse(
         page,
@@ -591,9 +690,7 @@ test(
           'data-zova-hydrated',
           'commerceAdmin',
         );
-        const orderRow = adminPage
-          .getByRole('cell', { name: String(checkout.orderId), exact: true })
-          .locator('..');
+        const orderRow = await getAdminOrderRow(adminPage, checkout.orderId);
         await expect(orderRow).toBeVisible();
         await orderRow.getByPlaceholder('Decision reason').fill('E2E approval');
         await orderRow.getByRole('checkbox').check();
@@ -722,7 +819,7 @@ test(
   async ({ page, request }) => {
     const routes = [
       ['/commerce/checkout', '/checkout'],
-      ['/commerce/payment/1', '/payment/1'],
+      ['/commerce/payment/1/1', '/payment/1/1'],
       ['/commerce/orders', '/orders'],
       ['/commerce/order/1', '/order/1'],
     ] as const;
@@ -736,7 +833,7 @@ test(
       expect(html, path).not.toContain('Payment succeeded');
       expect(html, path).not.toContain('Order #');
       expect(html, path).not.toContain('Checkout');
-      expect(html, path).not.toContain('Mock payment');
+      expect(html, path).not.toContain('Mock payment simulator');
       expect(html, path).not.toContain('My orders');
 
       const pageErrors = collectPageErrors(page);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.122",
+  "version": "5.1.124",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [
@@ -77,6 +77,7 @@
     "prepare": "husky"
   },
   "devDependencies": {
+    "@cabloy/dotenv": "^1.2.8",
     "@cabloy/lint": "^5.1.27",
     "@cabloy/process-helper": "^3.1.3",
     "@playwright/test": "^1.61.1",