cabloy 5.1.175 → 5.1.177

package/.cabloy-version

@@ -1 +1 @@
-5.1.175
+5.1.177

package/.claude/scheduled_tasks.lock

@@ -1 +1 @@
-{"sessionId":"4dc366c1-f1a5-45c5-a2e1-5c89e5694587","pid":67516,"procStart":"Sat Sep 12 08:03:56 2026","acquiredAt":1789284193785}
+{"sessionId":"6217847e-59ab-4e60-bb87-bbecdd19f760","pid":92862,"procStart":"Sat Sep 19 06:45:25 2026","acquiredAt":1789807599408}

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 5.1.177
+
+### Improvements
+
+- Update the menu guide documentation.
+- Refresh the pnpm lockfile.
+
+## 5.1.176
+
+### Improvements
+
+- Refactor a-pay.
+- Add a pnpm lockfile.
+
 ## 5.1.175
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.175",
+  "version": "5.1.177",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/repo-docs/backend/menu-guide.md

@@ -55,9 +55,11 @@ This makes menu retrieval part of the broader backend contract surface.
 
 In the current repo implementation, the out-of-the-box menu controller is public and delegates directly to `this.scope.service.menu.retrieveMenus(publicPath)`.
 
-## Static menu visibility
+## SSR Site targeting
 
-`@SsrMenu(...)` items can declare static role visibility without changing the public menu DTO:
+`@SsrMenu(...)` and `@SsrMenuGroup(...)` use `site` to select the SSR Site onion(s) that receive the declaration. It is a navigation-composition filter, not a site-admission, role-visibility, or backend-authorization decision.
+
+Use `site` for navigation owned by one SSR Site or deliberately exclusive to a known subset of sites:
 
 ```typescript
 @SsrMenu({
@@ -66,10 +68,41 @@ In the current repo implementation, the out-of-the-box menu controller is public
     link: 'presetResource',
     roles: ['systemAdmin'],
   },
-  site: 'basic-siteadmin:admin',
+  // This Basic Admin-owned entry intentionally targets one SSR Site.
+  site: ['basic-siteadmin:admin'],
+})
+```
+
+For a shared module declaration intended for every compatible SSR Admin site, omit `site`:
+
+```typescript
+@SsrMenu({
+  item: {
+    title: $locale('SharedOperations'),
+    link: 'presetResource',
+    roles: ['systemAdmin'],
+  },
+  // No `site`: the shared declaration is available to compatible SSR Admin sites.
 })
 ```
 
+Do not bind a shared Admin menu or menu group to the current/default Admin site merely to keep a new independent site's navigation narrow. Isolate an independent site through its enabled module composition and site-owned menus/groups. When a shared capability needs genuinely different navigation contracts per site, use an explicit, approved site-specific composition or owner instead of narrowing the shared declaration by default.
+
+`site` is distinct from a role's `siteIds`, menu `roles` or role-menu associations, and Passport/RBAC authorization:
+
+```text
+site              -> which SSR Site receives a menu/group declaration
+siteIds           -> which frontend Site a subject may enter
+roles / role-menu -> which admitted subject may discover a menu leaf
+Passport / RBAC   -> which backend actions or data the subject may use
+```
+
+See [Menu Authorization](/backend/menu-authorization) for the site-admission, navigation-disclosure, and backend-authority boundaries.
+
+## Static menu visibility
+
+`@SsrMenu(...)` items can declare static role visibility without changing the public menu DTO:
+
 - Omit `roles` to make an item visible to anonymous and authenticated callers.
 - Use `roles: []` when an item has no static role visibility and is intended to be disclosed only through dynamic Role-menu configuration.
 - A nonempty `roles` array is visible when the current Passport has at least one matching role name; it can also be disclosed through dynamic Role-menu configuration.
@@ -107,5 +140,6 @@ When editing SSR menu behavior, ask:
 2. is there a default fallback menu that should remain available?
 3. does the menu contract belong in backend API design, frontend route design, or both?
 4. does the active edition affect the menu structure or public path assumptions?
+5. is this declaration site-owned or deliberately site-exclusive (specify `site`), or shared across compatible SSR Admin sites (omit `site`)?
 
 That helps AI keep menu behavior aligned with Cabloy’s shared SSR architecture.

package/repo-docs/fullstack/a-pay-payment-suite.md

@@ -1,6 +1,6 @@
 # A-Pay Payment Suite
 
-This guide explains the current payment architecture in Cabloy Basic across Vona, Zova, and the Commerce domain.
+This guide explains the current payment architecture shared by Cabloy Basic and Cabloy Start across Vona, Zova, and the Commerce domain.
 
 It is a source-oriented architecture guide for:
 
@@ -50,12 +50,26 @@ zova/src/suite-vendor/a-pay/
 
 The general suite/module organization is described in [Suites and Modules](/fullstack/suites-and-modules). The payment suite follows the vendor-suite layout rather than being a complete user-facing page package.
 
-| Module       | Vona responsibility                                                                                       | Zova responsibility                                                                         |
-| ------------ | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `a-pay`      | Payment sessions, provider operations, callbacks, webhooks, normalized contracts, audit/outbox boundaries | Payment-session API/model, generated contracts, next-action component, redirect coordinator |
-| `pay-mock`   | Deterministic development/test provider and simulator webhook path                                        | Mock completion mutation used by the Commerce test surface                                  |
-| `pay-paypal` | PayPal API, capture, query, refund, and webhook translation                                               | Provider identity and metadata surface; no PayPal SDK execution in the browser              |
-| `pay-stripe` | Stripe Checkout, query, refund, and webhook translation                                                   | Provider identity and metadata surface; no Stripe SDK execution in the browser              |
+The shared suite contains payment-domain state and browser-safe coordination only. Presentation is owned by the active edition:
+
+```text
+zova/src/suite/cabloy-basic/modules/basic-pay/
+└── paymentNextAction  # DaisyUI and Tailwind CSS presenter
+
+zova/src/suite/cabloy-start/modules/start-pay/
+└── paymentNextAction  # Vuetify presenter
+```
+
+Each edition module exposes its own `ZPaymentNextAction` wrapper, while consuming the neutral `IPaymentNextActionProps` contract and `ServicePaymentCoordinator` from `a-pay`.
+
+| Module       | Vona responsibility                                                                                       | Zova responsibility                                                                                |
+| ------------ | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `a-pay`      | Payment sessions, provider operations, callbacks, webhooks, normalized contracts, audit/outbox boundaries | Payment-session API/model, generated contracts, normalized next-action input, redirect coordinator |
+| `basic-pay`  | —                                                                                                         | Cabloy Basic next-action presentation using DaisyUI and Tailwind CSS                               |
+| `start-pay`  | —                                                                                                         | Cabloy Start next-action presentation using Vuetify                                                |
+| `pay-mock`   | Deterministic development/test provider and simulator webhook path                                        | Mock completion mutation used by the Commerce test surface                                         |
+| `pay-paypal` | PayPal API, capture, query, refund, and webhook translation                                               | Provider identity and metadata surface; no PayPal SDK execution in the browser                     |
+| `pay-stripe` | Stripe Checkout, query, refund, and webhook translation                                                   | Provider identity and metadata surface; no Stripe SDK execution in the browser                     |
 
 The actual Web payment page is owned by the Commerce consumer, not by `zova-module-a-pay`:
 
@@ -143,7 +157,7 @@ The following flow is source-confirmed by the current Commerce and A-Pay impleme
 6. Commerce navigates to an authenticated Commerce payment route with the payment-session and order identifiers. Callback continuation remains server-selected and allowlisted; do not derive it from provider or browser input.
 7. The customer starts the session. Zova calls `POST /api/pay/payment-session/{id}/start`; A-Pay claims a provider operation with a stable idempotency key before making the external provider call.
 8. The provider adapter returns a normalized snapshot and optional `nextAction`. Redirect-capable providers normally return `requires_action` with a redirect action.
-9. Zova renders the generic next-action component. On the client, the redirect coordinator uses `window.location.assign(...)`; it does not call a provider SDK or decide whether the order is paid.
+9. Zova renders the edition-owned next-action presenter: `ZPaymentNextAction` from `basic-pay` in Cabloy Basic or from `start-pay` in Cabloy Start. On the client, the shared redirect coordinator uses `window.location.assign(...)`; it does not call a provider SDK or decide whether the order is paid.
 10. The provider returns through the server callback route, or sends a webhook to the public webhook route. A return callback can request confirmation or reconciliation, but cannot assert success.
 11. A-Pay verifies provider webhook input using the selected server-side client and the raw request body, then correlates provider, client, environment, amount, currency, and identifiers with the persisted session.
 12. Verified facts are deduplicated and applied to payment state. The state transition, audit entry, and `payment.outcome.v1` outbox record are written durably.
@@ -212,9 +226,9 @@ Read the frontend in Zova’s own roles first:
 | Zova role                        | Current A-Pay responsibility                                                                                      |
 | -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
 | `ModelPaymentSession`            | Model-owned query and mutation state for `view`, `start`, and `reconcile`, including invalidation after mutations |
-| `ControllerPaymentNextAction`    | Component-controller behavior for redirect, pending, completed, and embedded action rendering                     |
+| `IPaymentNextActionProps`        | Shared neutral input contract for edition-owned next-action presenters                                            |
 | `ServicePaymentCoordinator`      | Client-only execution of a normalized redirect action                                                             |
-| `ZPaymentNextAction`             | Metadata-backed public component wrapper for the action controller                                                |
+| `basic-pay` / `start-pay`        | Edition-owned `ControllerPaymentNextAction` and `ZPaymentNextAction` presentation wrappers                        |
 | Commerce payment page controller | Route state, start/reconcile decisions, settlement polling, and order navigation                                  |
 
 This is not page-local Vue fetching rewritten with classes. The model bean owns remote query/mutation state; the controller owns interaction and lifecycle decisions; the service bean owns reusable browser-side behavior; the render/component wrapper exposes the controller to consumers.
@@ -223,10 +237,10 @@ The core frontend reading path is:
 
 1. `zova/src/suite-vendor/a-pay/modules/a-pay/src/types/payment.ts`
 2. `zova/src/suite-vendor/a-pay/modules/a-pay/src/model/paymentSession.ts`
-3. `zova/src/suite-vendor/a-pay/modules/a-pay/src/api/paymentSession.ts`
-4. `zova/src/suite-vendor/a-pay/modules/a-pay/src/apiSchema/paymentSession.ts`
+3. `zova/src/suite-vendor/a-pay/modules/a-pay/src/api/payPaymentSession.ts`
+4. `zova/src/suite-vendor/a-pay/modules/a-pay/src/apiSchema/payPaymentSession.ts`
 5. `zova/src/suite-vendor/a-pay/modules/a-pay/src/service/paymentCoordinator.ts`
-6. `zova/src/suite-vendor/a-pay/modules/a-pay/src/component/paymentNextAction/controller.tsx`
+6. `zova/src/suite/cabloy-basic/modules/basic-pay/src/component/paymentNextAction/controller.tsx` or `zova/src/suite/cabloy-start/modules/start-pay/src/component/paymentNextAction/controller.tsx`
 7. `zova/src/suite/a-commerce/modules/commerce-trade/src/page/payment/controller.tsx`
 
 When a consumer uses `controllerRef` on `ZPaymentNextAction`, it receives the Zova component controller instance. It is not a generic DOM or Vue component reference.
@@ -235,7 +249,7 @@ When a consumer uses `controllerRef` on `ZPaymentNextAction`, it receives the Zo
 
 - Keep payment-session query/mutation state in `ModelPaymentSession`.
 - Consume generated API types and schemas; do not hand-patch generated files.
-- Pass the normalized `nextAction` to the generic action component instead of adding provider-specific branches to Commerce pages.
+- Pass the normalized `nextAction` and shared `IPaymentNextActionProps` to the active edition's action component instead of adding provider-specific branches to Commerce pages.
 - Execute redirects only in the browser.
 - Keep mock simulator controls limited to mock sessions and development/test surfaces.
 - Treat payment-session terminal state and Commerce order settlement as separate observations.
@@ -303,10 +317,10 @@ For frontend contracts and consumption:
 
 1. `zova/src/suite-vendor/a-pay/modules/a-pay/src/types/payment.ts`
 2. `zova/src/suite-vendor/a-pay/modules/a-pay/src/model/paymentSession.ts`
-3. `zova/src/suite-vendor/a-pay/modules/a-pay/src/api/paymentSession.ts`
-4. `zova/src/suite-vendor/a-pay/modules/a-pay/src/apiSchema/paymentSession.ts`
+3. `zova/src/suite-vendor/a-pay/modules/a-pay/src/api/payPaymentSession.ts`
+4. `zova/src/suite-vendor/a-pay/modules/a-pay/src/apiSchema/payPaymentSession.ts`
 5. `zova/src/suite-vendor/a-pay/modules/a-pay/src/service/paymentCoordinator.ts`
-6. `zova/src/suite-vendor/a-pay/modules/a-pay/src/component/paymentNextAction/controller.tsx`
+6. `zova/src/suite/cabloy-basic/modules/basic-pay/src/component/paymentNextAction/controller.tsx` or `zova/src/suite/cabloy-start/modules/start-pay/src/component/paymentNextAction/controller.tsx`
 7. `zova/src/suite/a-commerce/modules/commerce-trade/src/routes.ts`
 8. `zova/src/suite/a-commerce/modules/commerce-trade/src/page/checkout/controller.tsx`
 9. `zova/src/suite/a-commerce/modules/commerce-trade/src/page/payment/controller.tsx`