cabloy 5.1.109 → 5.1.111

package/.cabloy-version

@@ -1 +1 @@
-5.1.109
+5.1.111

package/.gitignore

@@ -1,6 +1,10 @@
 node_modules
 miniprogram_npm
 .assets/
+
+test-results/
+playwright-report/
+blob-report/
 **/vite.config.ts.timestamp-*
 **/coverage
 **/dist/
@@ -72,5 +76,4 @@ vona/docker-compose.yml
 /vona/src/backend/play
 !/zova/packages-utils/quasar-app-extension-zova/dist
 
-vona/src/suite/cabloy-basic/modules/basic-siteadmin/assets/site
-vona/src/suite/cabloy-basic/modules/basic-siteweb/assets/site
+**/assets/site

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 5.1.111
+
+### Features
+
+- Update the application functionality.
+
+## 5.1.110
+
+### Features
+
+- Add form layout sections for flow forms.
+- Add a Commerce development E2E workflow.
+- Establish the A-Commerce Phase 20 foundation.
+- Upgrade the Basic E2E baseline.
+- Add a Basic SSR E2E test skeleton.
+
+### Bug Fixes
+
+- Complete the Zova SSR hydration lifecycle.
+- Clarify E2E upgrade repair behavior.
+
+### Improvements
+
+- Rename and reorganize the E2E runner and harness files.
+- Standardize E2E test selection.
+- Normalize Commerce script commands.
+- Add coverage for the Student flow filter layout.
+- Update Student selection item and controller components.
+- Update framework performance documentation.
+- Add an A-Commerce planning baseline.
+- Add a Form Layout guide.
+
 ## 5.1.109
 
 ### Features

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

@@ -429,6 +429,7 @@ export default defineConfig({
           items: [
             { text: 'Component Guide', link: '/frontend/component-guide' },
             { text: 'Form Guide', link: '/frontend/form-guide' },
+            { text: 'Form Layout Guide', link: '/frontend/form-layout-guide' },
             { text: 'Image Guide', link: '/frontend/image-guide' },
             { text: 'File Guide', link: '/frontend/file-guide' },
             {

package/cabloy-docs/ai/playbook-module-removal.md

@@ -161,4 +161,4 @@ Not:
 
 1. delete a few generated files first
 2. guess which paths matter
-3. leave workspace dependencies or generated registrations stale
+3. leave workspace dependencies or generated registrations stale

package/cabloy-docs/ai/virtual-decorator-guidance.md

@@ -153,15 +153,15 @@ If a class does not need container-managed behavior, it usually belongs in `src/
 
 ## Decision table
 
-| Scenario | Use `@Virtual()` | Recommended placement | Reason |
-| --- | --- | --- | --- |
-| independent business service | No | `src/service` | it should own its own runtime resource boundary |
-| runtime-anchor base with container behavior | Yes | `src/service` or `src/service/*_.ts` | it is container-managed but belongs logically to the parent bean system |
-| bean-scene facade that intentionally stays on shorthand surface | Yes, if it is a bridge node | `src/bean` | it participates in shorthand lookup but is not a new ownership center |
-| compatibility / dialect / variant node built on a parent bean | Yes | same scene as the concrete variant type | runtime ownership should inherit from the parent chain |
-| pure helper or superclass convenience class | No | `src/lib` | no bean ownership semantics are needed |
-| class kept in `src/bean` only to expose shortcut lookup | Usually no | re-evaluate placement | `@Virtual()` is not a shorthand filter |
-| misplaced bean-scene class that should not be globally visible | No | move to `src/lib` or `src/service` | fix placement, not metadata |
+| Scenario                                                        | Use `@Virtual()`            | Recommended placement                   | Reason                                                                  |
+| --------------------------------------------------------------- | --------------------------- | --------------------------------------- | ----------------------------------------------------------------------- |
+| independent business service                                    | No                          | `src/service`                           | it should own its own runtime resource boundary                         |
+| runtime-anchor base with container behavior                     | Yes                         | `src/service` or `src/service/*_.ts`    | it is container-managed but belongs logically to the parent bean system |
+| bean-scene facade that intentionally stays on shorthand surface | Yes, if it is a bridge node | `src/bean`                              | it participates in shorthand lookup but is not a new ownership center   |
+| compatibility / dialect / variant node built on a parent bean   | Yes                         | same scene as the concrete variant type | runtime ownership should inherit from the parent chain                  |
+| pure helper or superclass convenience class                     | No                          | `src/lib`                               | no bean ownership semantics are needed                                  |
+| class kept in `src/bean` only to expose shortcut lookup         | Usually no                  | re-evaluate placement                   | `@Virtual()` is not a shorthand filter                                  |
+| misplaced bean-scene class that should not be globally visible  | No                          | move to `src/lib` or `src/service`      | fix placement, not metadata                                             |
 
 ## Worked examples
 

package/cabloy-docs/backend/websocket-call-flow.md

@@ -432,4 +432,4 @@ If you need the broader context next, read:
 - [Web Socket Guide](/backend/websocket-guide) for the architecture and extension model
 - [Web Socket Usage Guide](/backend/websocket-usage-guide) for server-side authoring patterns
 - [Web Socket Protocol Guide](/backend/websocket-protocol-guide) for the client-visible wire format
-- [Broadcast Guide](/backend/broadcast-guide) and [Worker Guide](/backend/worker-guide) for cross-worker delivery context
+- [Broadcast Guide](/backend/broadcast-guide) and [Worker Guide](/backend/worker-guide) for cross-worker delivery context

package/cabloy-docs/backend/websocket-guide.md

@@ -452,4 +452,4 @@ When extending or reviewing Web Socket behavior, ask:
 4. should delivery be point-to-point or namespace-wide?
 5. is the behavior local to one worker, or should it propagate through broadcast?
 
-That helps backend extensions stay aligned with the existing `a-socket` architecture instead of bypassing the framework transport model.
+That helps backend extensions stay aligned with the existing `a-socket` architecture instead of bypassing the framework transport model.

package/cabloy-docs/frontend/fetch-interceptor-guide.md

@@ -258,13 +258,13 @@ That distinction matters because the order is part of the onion dependency model
 
 A source-aligned hook matrix for the current built-ins is:
 
-| Interceptor | onRequest | onRequestError | onResponse | onResponseError |
-| --- | --- | --- | --- | --- |
-| `mock` | - | - | - | yes |
-| `headers` | yes | - | - | - |
-| `jwt` | yes | - | - | - |
-| `performAction` | yes | - | - | - |
-| `body` | - | - | yes | yes |
+| Interceptor     | onRequest | onRequestError | onResponse | onResponseError |
+| --------------- | --------- | -------------- | ---------- | --------------- |
+| `mock`          | -         | -              | -          | yes             |
+| `headers`       | yes       | -              | -          | -               |
+| `jwt`           | yes       | -              | -          | -               |
+| `performAction` | yes       | -              | -          | -               |
+| `body`          | -         | -              | yes        | yes             |
 
 This table is only a reading shortcut. The authoritative source is still the concrete bean implementation under `a-interceptor/src/bean/`.
 
@@ -437,4 +437,4 @@ When you use this page to reason about current behavior, verify:
 3. `ServiceComposer` still merges `config.interceptors[...]` into the final onion options
 4. the built-in bean roles still match their current source files
 
-That keeps the explanation tied to current source rather than to stale assumptions.
+That keeps the explanation tied to current source rather than to stale assumptions.

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

@@ -413,7 +413,9 @@ Use `layout` for concerns such as:
 - label text
 - icon prefix/suffix
 - field wrapper presentation
-- row-level layout intent
+- one field's row-level presentation intent
+
+`layout` is a field-level surface. When the requirement is to arrange multiple schema fields into responsive sections, groups, or tabs, use DTO-driven `formLayout` with `basic-form:blockFormLayout`; see [Form Layout Guide](/frontend/form-layout-guide).
 
 ### Use `options` for renderer-specific input props
 

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

@@ -0,0 +1,322 @@
+# Form Layout Guide
+
+Use Form Layout when a schema-driven resource form needs a deliberate structure: field order, Grid or flow sections, groups, or tabs.
+
+This guide covers the **structural** layout contract authored in DTO metadata and rendered through `basic-form:blockFormLayout`. It does not replace [Form Guide](/frontend/form-guide), which explains `ZForm`, field rendering, validation, and manual or mixed forms.
+
+> [!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.
+
+## The layout layers are different
+
+Several APIs contain the word “layout,” but they own different concerns:
+
+| Surface                                        | Owns                                                                                                           | Does not own                                              |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `formLayout`                                   | Field placement, Grid/flow sections, groups, responsive spans, and tabs                                        | Field renderer selection, validation rules, submit policy |
+| `basic-form:blockFormLayout`                   | Resolving and rendering a structural `formLayout` tree in Cabloy Basic                                         | Page-entry or filter actions                              |
+| `layout`, `formFieldLayout`, `FormFieldLayout` | One field's label and wrapper presentation: inline/block mode, icons, borders, header/footer, class, and style | Sections, Grid/flow placement, groups, or tabs            |
+
+For example, `formFieldLayout: { inline: false }` makes each field use a block-style wrapper. It does not create a grid. Pair it with `basic-form:blockFormLayout` when the fields also need structural placement.
+
+Read [Form Guide](/frontend/form-guide) for field wrapper and provider customization, and [Behavior Guide](/frontend/behavior-guide) for the `FormFieldLayout` behavior pipeline.
+
+## Compose the layout through resource blocks
+
+For resource forms, author structural layout in backend DTO metadata with `ZovaRender.block(...)`. The helper creates contract metadata; it does not render the form itself. Zova later consumes the generated schema metadata and renders the registered blocks.
+
+### Entry form composition
+
+A resource entry DTO normally nests the layout block inside the page-entry form block:
+
+```tsx
+@Dto({
+  blocks: [
+    ZovaRender.block('basic-pageentry:blockPageEntry', {
+      blocks: [
+        ZovaRender.block('basic-pageentry:blockForm', {
+          blocks: [
+            ZovaRender.block('basic-form:blockFormLayout', {
+              formLayout: {
+                children: [/* fields, groups, sections, or tabs */],
+              },
+            }),
+          ],
+        }),
+        ZovaRender.block('basic-pageentry:blockToolbarRow', {
+          actions: [/* Submit, Back, and other page-entry actions */],
+        }),
+      ],
+    }),
+  ],
+})
+```
+
+The responsibilities stay separate:
+
+- the DTO supplies the structural contract metadata
+- `basic-pageentry:blockForm` bridges page-entry form state, schema, and scene into `ZForm`
+- `basic-form:blockFormLayout` places schema fields
+- `basic-pageentry:blockToolbarRow` owns page-entry actions and their scene/permission rules
+
+Form Layout changes neither readonly behavior nor actions. Create, update, and view scenes can reuse the same structure while the normal form and page-entry pipelines decide field state and available actions. See [Resource Entry Page Deep Dive](/frontend/resource-entry-page-deep-dive) for the wider entry-page runtime.
+
+### Filter form composition
+
+A filter uses the filter block as its host and keeps filter actions as an explicit sibling block:
+
+```tsx
+ZovaRender.block('basic-page:blockFilter', {
+  formFieldLayout: { inline: false },
+  blocks: [
+    ZovaRender.block('basic-form:blockFormLayout', {
+      formLayout: {
+        children: [
+          /* structural nodes */
+        ],
+      },
+    }),
+    ZovaRender.block('basic-page:blockFilterActions'),
+  ],
+});
+```
+
+A nonempty `blocks` list replaces `ZForm`'s automatic body and footer. Therefore a structured filter must explicitly include `basic-page:blockFilterActions`; it owns Search and Reset and keeps the filter's existing normalization and page-query handoff. See [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook#use-blocks-for-a-structural-filter-layout) for the filter ownership model.
+
+## Layout node grammar
+
+`formLayout` has a root `children` array. The node types deliberately have limited nesting rather than arbitrary recursion:
+
+```text
+formLayout
+├─ field
+├─ section
+│  └─ field
+├─ group
+│  ├─ field
+│  ├─ group
+│  └─ section
+└─ tabs
+   └─ tab
+      ├─ field
+      ├─ group
+      └─ section
+```
+
+| Node      | Key properties                                             | Allowed children         | Use it for                                |
+| --------- | ---------------------------------------------------------- | ------------------------ | ----------------------------------------- |
+| `field`   | required `name`; optional `span`                           | none                     | Place one resolved schema field           |
+| `section` | optional `id`, `title`, `description`, `layout`, `columns` | fields only              | A Grid or wrapping flow field layout      |
+| `group`   | optional `id`, `title`, `description`                      | fields, groups, sections | A semantic, bordered fieldset-style group |
+| `tabs`    | optional `id`                                              | tabs only                | One tab container                         |
+| `tab`     | optional `id`; required `title`                            | fields, groups, sections | One tab panel                             |
+
+A section is a layout boundary. It uses the Grid strategy by default; set `layout: 'flow'` for compact, left-packed fields that wrap at their intrinsic widths. Use a group when the fields need a semantic or visual boundary, and place a section inside that group when it also needs Grid columns or flow placement. There is no separate `row` node: Grid and flow placement create rows automatically.
+
+Nested tabs are not part of the current contract. Likewise, a section cannot contain a group or another section.
+
+## Grid sections and field spans
+
+Grid is the default section strategy: omit `layout` or set `layout: 'grid'`. Both `section.columns` and `field.span` use the same responsive shape:
+
+```ts
+{
+  default?: 1 | 2 | 3 | 4,
+  md?: 1 | 2 | 3 | 4,
+  lg?: 1 | 2 | 3 | 4,
+}
+```
+
+- `columns` chooses how many columns a section has at each breakpoint.
+- `span` chooses how many of those columns a field occupies.
+- In Cabloy Basic, these become Tailwind classes such as `grid-cols-2`, `md:grid-cols-2`, `col-span-2`, and `md:col-span-2`.
+- A section with no `columns.default` renders as one column.
+- A field with no `span` takes its normal grid cell.
+
+The following compact filter structure becomes one column by default, two columns at `md`, and makes `createdAt` use both medium columns:
+
+```tsx
+formLayout: {
+  children: [
+    {
+      type: 'section',
+      columns: { default: 1, md: 2 },
+      children: [
+        { type: 'field', name: 'name' },
+        { type: 'field', name: 'level' },
+        { type: 'field', name: 'createdAt', span: { default: 1, md: 2 } },
+      ],
+    },
+  ],
+},
+```
+
+## Flow sections
+
+Set `layout: 'flow'` when compact fields should appear from left to right without being distributed across equal Grid columns. Cabloy Basic renders a flow section as a wrapping flex layout, so each field keeps its renderer-defined width and moves to the next line only when space runs out.
+
+```tsx
+{
+  type: 'section',
+  layout: 'flow',
+  children: [
+    { type: 'field', name: 'name' },
+    { type: 'field', name: 'level' },
+    { type: 'field', name: 'createdAt' },
+  ],
+}
+```
+
+`columns` and `span` are Grid-only settings. Omit them from flow sections; they do not determine flex widths or offsets. Use `formFieldLayout.inline` independently when the fields themselves should use compact inline wrappers.
+
+## How the resolver handles the declared tree
+
+Before rendering, `resolveFormLayout(...)` reconciles `formLayout` with the current scene's resolved schema properties. This makes the declaration a **placement overlay**, not an allow-list.
+
+### Eligible and omitted fields
+
+Only schema properties with `rest.visible !== false` are eligible. When an eligible visible field is absent from `formLayout`, the resolver appends it as a root-level field after the declared nodes, in schema-property order.
+
+If a field must not render, make it invisible in schema metadata. Leaving it out of `formLayout.children` is not enough.
+
+### Invalid declarations and diagnostics
+
+The resolver keeps the first occurrence of each field and removes later duplicates. It also removes field names that are not eligible in the current schema scene.
+
+| Situation                                 | Resolver result                               | Diagnostic       |
+| ----------------------------------------- | --------------------------------------------- | ---------------- |
+| Unknown or invisible field name           | Field is removed                              | `unknownField`   |
+| Repeated field name                       | Later field is removed                        | `duplicateField` |
+| Repeated structural ID                    | Later group, section, tabs, or tab is removed | `duplicateId`    |
+| Structural node has no surviving children | Node is removed                               | none             |
+
+Groups, sections, tab containers, and tabs receive an ID even when the DTO omits one. The resolver derives it from the node type and index path, for example `tabs-0` or `section-0-1-0`. Omit IDs for simple static layouts; provide explicit IDs when external state, diagnostics, tests, or future extensions need a stable structural reference.
+
+> [!WARNING]
+> Diagnostics are returned in the resolved layout plan, but the current `basic-form:blockFormLayout` renderer does not display or log them. Treat field names and explicit IDs as metadata that must be reviewed and tested, rather than expecting a visible authoring error at runtime.
+
+## Tabs and validation feedback
+
+The Basic renderer keeps active-tab state locally for each `tabs` node. If no saved active tab remains valid, it falls back to the first surviving tab.
+
+It renders native tab buttons and panels with `role="tablist"`, `role="tab"`, `role="tabpanel"`, `aria-selected`, `aria-controls`, and `aria-labelledby` relationships. A tab receives an error badge when fields below it have validation errors. The badge counts fields with errors, not individual error messages.
+
+Field error messages remain the responsibility of the field-layout behavior. The structural layout only summarizes their presence on tabs.
+
+Current behavior boundaries:
+
+- an error badge does not automatically activate or focus the tab containing the invalid field
+- tab state belongs to the `basic-form:blockFormLayout` component, not the form globally
+- the contract does not support nested tabs
+- Form Layout does not select field renderers, change field visibility, or alter validation and submit policies
+
+## Complete entry-form example
+
+The Student create DTO is the canonical complete example. It uses optional structural IDs, two tabs, a titled group, a responsive profile section, and a nested-details field:
+
+```tsx
+ZovaRender.block('basic-pageentry:blockForm', {
+  blocks: [
+    ZovaRender.block('basic-form:blockFormLayout', {
+      formLayout: {
+        children: [
+          {
+            type: 'tabs',
+            children: [
+              {
+                type: 'tab',
+                title: $locale('BasicInformation'),
+                children: [
+                  {
+                    type: 'group',
+                    title: $locale('StudentProfile'),
+                    children: [
+                      {
+                        type: 'section',
+                        columns: { default: 1, md: 2 },
+                        children: [
+                          { type: 'field', name: 'name' },
+                          { type: 'field', name: 'mobile' },
+                          { type: 'field', name: 'imageId' },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+              {
+                type: 'tab',
+                title: $locale('TrainingRecords'),
+                children: [
+                  { type: 'field', name: 'level' },
+                  {
+                    type: 'section',
+                    children: [{ type: 'field', name: 'trainingRecords' }],
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    }),
+  ],
+});
+```
+
+`trainingRecords` is one field in the structural tree. Its `basic-details:formFieldDetails` renderer owns the nested details UI; Form Layout does not recursively arrange the properties inside each detail record.
+
+Student update and view DTOs use the same structural shape. The normal form scene controls readonly behavior, while the page-entry toolbar decides whether Submit, Back, or other actions are available.
+
+## Complete filter-form example
+
+The Student list filter combines field-wrapper and structural layout concerns:
+
+```tsx
+ZovaRender.block('basic-page:blockFilter', {
+  formFieldLayout: { inline: true },
+  blocks: [
+    ZovaRender.block('basic-form:blockFormLayout', {
+      formLayout: {
+        children: [
+          {
+            type: 'section',
+            layout: 'flow',
+            children: [
+              { type: 'field', name: 'name' },
+              { type: 'field', name: 'level' },
+              { type: 'field', name: 'createdAt' },
+            ],
+          },
+        ],
+      },
+    }),
+    ZovaRender.block('basic-page:blockFilterActions'),
+  ],
+});
+```
+
+Here `formFieldLayout.inline: true` controls how each field wrapper is presented. The flow section keeps those compact wrappers left-packed and wraps them when necessary. `basic-page:blockFilterActions` remains required because the custom blocks replace automatic filter body/footer content.
+
+## 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 and filter actions in `basic-page:blockFilterActions`.
+5. Review field names against the scene-specific schema. Unlisted visible fields are appended; unknown and duplicate declarations are silently pruned from the rendered plan.
+6. Use the smallest layout that communicates the form structure; reserve tabs for genuinely separate field groups.
+
+## Source-reading and verification path
+
+For source-level investigation, follow this order:
+
+1. `vona/src/suite/a-training/modules/training-student/src/dto/studentCreate.tsx` or `studentSelectResItem.tsx`
+2. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/resource/formLayout.ts`
+3. `zova/src/suite-vendor/a-zova/modules/a-form/src/lib/formLayout.ts`
+4. `zova/src/suite/cabloy-basic/modules/basic-form/src/component/blockFormLayout/controller.tsx`
+5. `vona/src/suite/a-training/modules/training-student/test/student.test.ts`
+
+The Student test verifies that entry and filter DTO metadata preserves the current block nesting, optional IDs, Grid columns/spans, flow layout selection, and field order through OpenAPI generation. It is a contract-metadata test, not a browser end-to-end assertion for tabs, layout behavior, or error badges.
+
+For the broader form runtime, continue with [Zova Form Under the Hood](/frontend/zova-form-under-the-hood) and [Zova Form Source Reading Map](/frontend/zova-form-source-reading-map).

package/cabloy-docs/frontend/introduction.md

@@ -80,6 +80,7 @@ Use this path when the task is about UI composition, component contracts, form o
 
 - [Component Guide](/frontend/component-guide)
 - [Form Guide](/frontend/form-guide)
+- [Form Layout Guide](/frontend/form-layout-guide)
 - [Image Guide](/frontend/image-guide)
 - [Zova Form Under the Hood](/frontend/zova-form-under-the-hood)
 - [Zova Form Source Reading Map](/frontend/zova-form-source-reading-map)

package/cabloy-docs/frontend/resource-entry-page-deep-dive.md

@@ -187,6 +187,8 @@ Instead, it consumes `$$pageEntry` from the host render context and passes the c
 
 This is the clearest source-confirmed proof that `blockForm` is a bridge, not the main owner of entry-page orchestration.
 
+A resource DTO can provide a nested `basic-form:blockFormLayout` block here to arrange the schema fields into sections, groups, or tabs. That block only owns structural placement; read [Form Layout Guide](/frontend/form-layout-guide) for the DTO grammar and keep this page focused on the entry runtime handoff.
+
 ### 7. `blockToolbarRow` renders the action row
 
 The action row lives in:

package/cabloy-docs/frontend/router-tabs-layout-integration.md

@@ -15,6 +15,7 @@ Read this page together with:
 
 > [!TIP]
 > **Router ecosystem docs path**
+>
 > 1. **[Page Route Guide](/frontend/page-route-guide)** — learn the public route-record and layout surface
 > 2. **[Zova Router Under the Hood](/frontend/zova-router-under-the-hood)** — learn how the core router runtime cooperates
 > 3. **[Router View Hosts Guide](/frontend/router-view-hosts-guide)** — learn how routed pages are actually hosted
@@ -364,4 +365,4 @@ That means the integration story here is accurate for the current Basic Admin an
 
 If [Router Tabs Mechanism](/frontend/router-tabs-mechanism) explains how the shared tabs model works, this page explains how the real Basic layouts turn that shared model into visible shell behavior.
 
-That is the missing bridge between framework-level tabs semantics and the actual layout code contributors edit.
+That is the missing bridge between framework-level tabs semantics and the actual layout code contributors edit.

package/cabloy-docs/frontend/scripts.md

@@ -28,7 +28,62 @@ npm run dev:zova:web
 npm run build:zova
 ```
 
-These map to Basic-specific Zova flavors in this repository.
+These map to Basic-specific Zova flavors in this repository. Commerce follows the same aggregate-and-surface pattern:
+
+```bash
+# Customer Web or Operator Admin development server
+npm run dev:zova:commerce:web
+npm run dev:zova:commerce:admin
+
+# Both Commerce SSR/REST artifact pairs, or one surface only
+npm run build:zova:commerce
+npm run build:zova:commerce:web
+npm run build:zova:commerce:admin
+```
+
+## Basic SSR browser acceptance
+
+The default Basic Web and Admin sites have browser smoke commands that exercise Vona SSR dispatch at `7102`, not a standalone Zova development-server port.
+
+Prepare current artifacts explicitly when the relevant frontend SSR output changed:
+
+```bash
+# Web only
+npm run build:zova:web
+
+# Admin only
+npm run build:zova:admin
+
+# Both default Basic sites
+npm run build:zova
+npm run deps:vona
+```
+
+Then use the managed clean local acceptance command:
+
+```bash
+npm run test:e2e:basic:clean
+```
+
+It resets Vona-managed test data and the local Redis namespace, starts one development Vona worker, and runs the complete suite by default. The E2E commands consume already-built artifacts; they do not rebuild them.
+
+The suite command family is consistent across Basic and Commerce:
+
+```text
+test:e2e:<suite>          complete suite
+test:e2e:<suite>:web      all @web surface scenarios
+test:e2e:<suite>:admin    all @admin surface scenarios
+test:e2e:<suite>:clean      managed clean local suite run
+```
+
+Use Playwright tags after npm's argument delimiter for feature/category selection instead of adding one root script per scenario:
+
+```bash
+npm run test:e2e:basic:clean -- --grep @flow
+npm run test:e2e:basic -- --grep ATP-BASIC-FLOW-01
+```
+
+For the complete tag vocabulary, managed-runner argument boundaries, and externally managed-target examples, see [Repo Scripts](/reference/repo-scripts#ssr-browser-checks). For a separately managed Basic target, set `BASIC_E2E_BASE_URL`; the equivalent Commerce commands use `COMMERCE_E2E_BASE_URL`. The caller owns external-target data, cache, and artifact freshness.
 
 ## Zova script model
 

package/cabloy-docs/frontend/ssr-build-deploy-guide.md

@@ -305,4 +305,4 @@ Before finalizing an SSR build/deploy change, ask:
 4. if the change crosses the frontend/backend SSR boundary, did I verify the aligned fullstack build path?
 5. did I verify built behavior rather than relying only on dev behavior?
 
-That keeps SSR deployment guidance aligned with the real Cabloy monorepo workflow rather than with generic frontend-only assumptions.
+That keeps SSR deployment guidance aligned with the real Cabloy monorepo workflow rather than with generic frontend-only assumptions.

package/cabloy-docs/frontend/ssr-overview.md

@@ -28,6 +28,12 @@ For admin systems, SSR still needs to cooperate with client-facing behavior such
 
 A central SSR capability is preparing initial data on the server, synchronizing it to the client, and completing hydration naturally.
 
+### Initial hydration completion
+
+For browser work that must wait for the initial SSR handoff, register `this.$ssr.onHydrated(...)`. The callback runs once only after the SSR root and every currently tracked Zova nested hydration boundary complete, including deferred client updates. Root mount alone is not sufficient when an async component or controller is still hydrating.
+
+This lifecycle applies only to the initial client hydration of SSR HTML. It is not an SPA-startup or later client-navigation readiness signal. Do not render a client-ready marker into server HTML; add it from an `onHydrated(...)` callback when browser-visible evidence is required.
+
 ### SEO meta
 
 SSR also supports flexible SEO metadata handling.

package/cabloy-docs/frontend/ssr-review-checklist.md

@@ -181,4 +181,4 @@ Before accepting an SSR-related change, ask:
 3. did the review verify edition/theme assumptions when the change was SSR-UI-sensitive?
 4. did the review use the smallest correct checklist rather than relying on intuition alone?
 
-That keeps SSR reviews consistent across human contributors and AI-assisted workflows.
+That keeps SSR reviews consistent across human contributors and AI-assisted workflows.

package/cabloy-docs/frontend/ssr-troubleshooting-guide.md

@@ -51,15 +51,15 @@ If you identify the failing layer first, most SSR debugging becomes much faster.
 
 Use this quick map before diving deeper.
 
-| Symptom | Start here |
-| --- | --- |
-| request does not hit the expected SSR page | Vona SSR orchestration |
-| dev works but prod fails | frontend build output + SSR env/runtime |
-| HTML appears but hydration is wrong | client hydration |
+| Symptom                                                   | Start here                              |
+| --------------------------------------------------------- | --------------------------------------- |
+| request does not hit the expected SSR page                | Vona SSR orchestration                  |
+| dev works but prod fails                                  | frontend build output + SSR env/runtime |
+| HTML appears but hydration is wrong                       | client hydration                        |
 | server-rendered data is missing or refetched unexpectedly | Zova SSR server render + init data flow |
-| SEO/meta output is missing | Zova SSR server render + meta flow |
-| first paint theme is wrong | SSR env + theme rules |
-| static assets 404 after SSR deploy | frontend build output |
+| SEO/meta output is missing                                | Zova SSR server render + meta flow      |
+| first paint theme is wrong                                | SSR env + theme rules                   |
+| static assets 404 after SSR deploy                        | frontend build output                   |
 
 ## Symptom 1: the request does not hit the expected SSR page
 
@@ -298,4 +298,4 @@ Before finalizing an SSR fix, ask:
 3. am I reusing the intended framework abstraction instead of adding a parallel workaround?
 4. does the fix accidentally assume an edition-specific UI or theme rule is universal?
 
-That keeps SSR debugging aligned with the Cabloy fullstack model and reduces one-off fixes that solve only the symptom.
+That keeps SSR debugging aligned with the Cabloy fullstack model and reduces one-off fixes that solve only the symptom.