cabloy 5.1.158 → 5.1.160

package/repo-docs/frontend/zova-table-under-the-hood.md

@@ -58,13 +58,14 @@ This page is that bridge.
 
 For a typical Zova table, the shortest accurate model is:
 
-1. the `ZTable` wrapper creates a table controller bean through the normal Zova controller path
-2. the table controller loads table-scene schema properties from the row schema
-3. the controller builds table metadata with visible properties and per-column render functions
-4. the controller creates TanStack table options through Zova’s `$useTable(...)` wrapper
-5. each cell render resolves either to text fallback, a general JSX render target, or a `tableCell` bean
-6. the cell runtime evaluates JSX/CEL props with table-aware column and cell scope
-7. resource pages feed schema, data, permissions, and page scope into the same table runtime through `basic-page:blockTable`
+1. backend schema helpers such as `ZovaRender.column(...)` attach table-column metadata to the field contract
+2. the `ZTable` wrapper creates a table controller bean through the normal Zova controller path
+3. the table controller loads effective table-scene schema properties from the row schema
+4. the controller builds table metadata with visible properties and per-column render functions
+5. the controller creates TanStack table options through Zova’s `$useTable(...)` wrapper
+6. each cell render resolves either to text fallback, a general JSX render target, or a `tableCell` bean
+7. the cell runtime evaluates JSX/CEL props with table-aware column and cell scope
+8. resource pages feed schema, data, permissions, and page scope into the same table runtime through `basic-page:blockTable`
 
 That is why Zova Table is not only a thin wrapper around TanStack Table. The business-facing runtime surface is still Zova-native.
 
@@ -98,25 +99,27 @@ These three files already show the core architecture:
 
 When you want to trace the full mechanism, read these files in order:
 
-1. `zova/src/suite-vendor/a-zova/modules/a-table/src/.metadata/component/table.ts`
-2. `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/controller.tsx`
-3. `zova/src/suite-vendor/a-zova/modules/a-table/src/lib/beanControllerTableBase.ts`
-4. `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/render.tsx`
-5. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/lib/schema.ts`
-6. `zova/src/suite-vendor/a-zova/modules/a-table/src/types/tableCell.ts`
-7. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controller.tsx`
-8. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx`
+1. `zova/packages-cli/cli-set-front/cli/templates/rest/rest.ts`
+2. `zova/src/suite-vendor/a-zova/modules/a-table/src/.metadata/component/table.ts`
+3. `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/controller.tsx`
+4. `zova/src/suite-vendor/a-zova/modules/a-table/src/lib/beanControllerTableBase.ts`
+5. `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/render.tsx`
+6. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/lib/schema.ts`
+7. `zova/src/suite-vendor/a-zova/modules/a-table/src/types/tableCell.ts`
+8. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controller.tsx`
+9. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx`
 
 A compact role map is:
 
+- `cli/templates/rest/rest.ts` shows that `ZovaRender.column(...)` stores its options under `rest.table`
 - `table.ts` shows how the public wrapper enters `useController(...)`
-- `component/table/controller.tsx` owns schema properties, metadata refresh, TanStack bridge, and cell rendering
+- `component/table/controller.tsx` owns schema properties, metadata refresh, TanStack bridge, pinning, sorting eligibility, and cell rendering
 - `beanControllerTableBase.ts` shows the Zova wrapper around `useVueTable(...)`
-- `component/table/render.tsx` shows the default table DOM render path through `FlexRender`
-- `schema.ts` shows how table-scene schema properties are loaded and ordered
+- `component/table/render.tsx` shows the default table DOM render path, layout metadata, sortable headers, and `FlexRender`
+- `schema.ts` shows how top-level and table-scene metadata are merged and ordered
 - `types/tableCell.ts` shows the `tableCell` scene contract
-- `blockTable/controller.tsx` shows how page blocks feed `data`, `schema`, and `tableScope` into `ZTable`
-- `blockPage/controller.tsx` shows where resource data, permissions, and page scope come from
+- `blockTable/controller.tsx` shows how Basic page blocks feed data, schemas, scope, and sorting state into `ZTable`
+- `blockPage/controller.tsx` shows where resource data, permissions, page scope, and backend `orders` mapping come from
 
 ## Step-by-step runtime path
 
@@ -205,16 +208,19 @@ zova/src/suite-vendor/a-zova/modules/a-openapi/src/lib/schema.ts
 
 The important runtime path is:
 
-1. the table receives `schema`
-2. `_createProperties()` computes `this.$sdk.loadSchemaProperties(this.schema, 'table')`
-3. `loadSchemaProperties(...)` resolves `$ref`, applies `rest.table` overlays, and sorts by `rest.order`
-4. `_createTableMeta()` iterates those properties and decides visibility and render behavior
-5. `_createColumnsMiddle()` converts the surviving properties into TanStack column definitions
+1. `ZovaRender.column(options)` stores the field's column options under `rest.table`
+2. the table receives `schema`
+3. `_createProperties()` computes `this.$sdk.loadSchemaProperties(this.schema, 'table')`
+4. `loadSchemaProperties(...)` resolves `$ref`, merges shared `rest` metadata with the `rest.table` overlay, and sorts by effective `rest.order`
+5. `_createTableMeta()` iterates those properties and decides visibility and render behavior
+6. `_createColumnsMiddle()` converts the surviving properties into TanStack column definitions
+
+`ZovaRender.column(...)` is a shared Zova API available in both Cabloy Basic and Cabloy Start. It supplies metadata only; it neither registers a frontend column nor selects a cell renderer. `ZovaRender.cell(...)` supplies the render target, and `tableCell` beans implement reusable cell behavior.
 
 A practical reading takeaway is:
 
 - **schema is not only validation truth**
-- **schema also drives table order, visibility, and cell render metadata**
+- **schema also drives table order, physical-column behavior, visibility, and cell render metadata**
 
 ## 5. How table metadata is built
 
@@ -257,6 +263,21 @@ A practical reading takeaway is:
 - **TanStack owns the row-model mechanics**
 - **the controller still owns which data and columns TanStack sees**
 
+### Column metadata becomes TanStack and DOM behavior
+
+When `_createColumnsMiddle()` creates each surviving property column, it maps effective table metadata as follows:
+
+| Metadata             | Controller and render behavior                                                                       |
+| -------------------- | ---------------------------------------------------------------------------------------------------- |
+| `rest.order`         | Orders properties during schema-property loading.                                                    |
+| `rest.width`         | Becomes the TanStack `size`; render beans apply pixel `width` and `min-width`.                       |
+| `rest.align`         | Remains in column metadata; render beans apply header/cell text alignment.                           |
+| `rest.fixed`         | Builds left/right TanStack pinning arrays; render beans use sticky positions and calculated offsets. |
+| `rest.enableSorting` | Enables sorting only when the field's key or aliases are also present in `schemaOrder`.              |
+| `rest.sortDescFirst` | Becomes TanStack's first-toggle direction.                                                           |
+
+The sorting gate is intentional: metadata can request sorting, but the order schema remains the contract that authorizes the field. The standard resource-page table is controlled and `manualSorting`; it does not locally reorder the fetched data.
+
 ## 7. Column and cell render context are explicitly separated
 
 The controller creates two related but distinct runtime contexts.
@@ -392,12 +413,12 @@ That contract defines:
 The decorator itself is:
 
 ```typescript
-createBeanDecorator('tableCell', 'sys', true, options);
+createBeanDecorator('tableCell', 'app', true, options);
 ```
 
-That means `tableCell` is not only a naming convention. It is a frontend bean scene with:
+That means `tableCell` is not only a naming convention. It is an app-scoped frontend bean scene with:
 
-- system-scoped resolution behavior
+- app-scoped reusable bean resolution
 - scene-level typing
 - CLI boilerplate support
 - metadata-driven resource identity
@@ -437,9 +458,12 @@ The default render bean lives in:
 zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/render.tsx
 ```
 
-It does two important jobs:
+It does more than delegate vnode creation:
 
 - render the outer table markup with `<table class="table">`
+- apply effective column alignment, pixel width/minimum width, and fixed-column sticky positioning
+- calculate and apply left/right pinned-column offsets
+- render accessible sortable header buttons, `aria-sort`, and sort-state indicators when the controller exposes a sortable column
 - delegate header and cell vnode creation to TanStack `FlexRender`
 
 If `slotDefault` is supplied, the render bean yields to that slot instead of the built-in table DOM.
@@ -470,7 +494,8 @@ zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controll
 - loads `ModelResource`
 - creates page-level JSX/CEL environment
 - computes resource query state
-- exposes `data`, `schemaRow`, and `permissions`
+- exposes `data`, `schemaRow`, `schemaOrder`, and `permissions`
+- owns controlled table sorting and converts its single current sorting entry into backend `orders`
 - refreshes table metadata when permissions change
 
 ### Table block path
@@ -480,6 +505,8 @@ zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controll
 - renders `ZTable`
 - passes `data={$$page.data}`
 - passes `schema={$$page.schemaRow}`
+- passes `schemaOrder={$$page.schemaOrder}`
+- passes controlled `sorting` and `onSortingChange`
 - passes `tableScope={$$page.jsxCelScope}`
 - captures `controllerRef` and stores `tableRef` back onto the page controller
 
@@ -487,18 +514,22 @@ This is one of the most important integration facts about the module.
 
 The resource page does not manually rebuild the table runtime. It feeds page-owned resource state into the same reusable table controller.
 
+This section uses Cabloy Basic `basic-page` paths as the concrete resource-page specimen. The core `ZovaRender.column(...)` metadata contract and the base Zova Table controller behavior are shared by Cabloy Basic and Cabloy Start; resolve Start-specific page modules and renderer keys from the active Start repository.
+
 ## 14. Compact call-flow sketch
 
 When in doubt, use this short call flow:
 
-1. `ZTable` wrapper enters the normal Zova controller path
-2. `ControllerTable.__init__()` creates CEL/JSX support and schema-driven properties
-3. `refreshMeta()` computes visible table properties and per-column render functions
-4. `_createTable()` creates the TanStack bridge through `$useTable(...)`
-5. `RenderTable` renders headers and rows through `FlexRender`
-6. each cell render resolves to text fallback, a general render target, or a `tableCell` bean
-7. `tableCell` beans receive controller-prepared options, scope, and `next()`
-8. resource pages prepare `data`, `schemaRow`, `permissions`, and `tableScope` before entering the same runtime
+1. `ZovaRender.column(...)` contributes `rest.table` metadata to the backend/OpenAPI field contract
+2. `ZTable` wrapper enters the normal Zova controller path
+3. `ControllerTable.__init__()` creates CEL/JSX support and schema-driven properties
+4. `refreshMeta()` computes visible table properties, column pinning, and per-column render functions
+5. `_createTable()` creates the TanStack bridge through `$useTable(...)`
+6. `RenderTable` applies column metadata and renders headers and rows through `FlexRender`
+7. each cell render resolves to text fallback, a general render target, or a `tableCell` bean
+8. `tableCell` beans receive controller-prepared options, scope, and `next()`
+9. resource pages prepare `data`, `schemaRow`, `schemaOrder`, sorting state, permissions, and `tableScope` before entering the same runtime
+10. a resource-page sort becomes backend `orders`; TanStack does not locally sort the fetched page
 
 That is the shortest end-to-end explanation of how the module cooperates.
 

package/repo-docs/fullstack/contract-loop-playbook.md

@@ -146,6 +146,8 @@ Then use the **reverse chain**:
 
 See [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend) for the end-to-end reverse-chain bridge from frontend-owned truth to backend-visible shared handoff.
 
+When the frontend change creates a new independently mounted SSR site rather than refreshing an existing consumer, use [Independent SSR Site and Flavor Setup](/fullstack/ssr-site-and-flavor-setup). The new Vona consumer needs a matched flavor, paired SSR/REST build wrapper, site registration, and dispatch/hydration proof.
+
 ### 3. Do generated artifacts look stale?
 
 Examples:

package/repo-docs/fullstack/ssr-site-and-flavor-setup.md

@@ -0,0 +1,198 @@
+# Independent SSR Site and Flavor Setup
+
+Use this guide when adding a new deployable Zova SSR surface that Vona must dispatch and serve. It covers a new **site + flavor** pair, not merely a page or route inside an existing site.
+
+The durable outcome is one aligned identity tuple:
+
+```text
+Zova flavor
+  ↕
+flavor env/config + Zova SSR/REST scripts
+  ↕
+root paired build wrapper
+  ↕
+SSR release directory + generated REST package
+  ↕
+Vona @SsrSite registration
+```
+
+Do not substitute identifiers from an existing Admin, Web, or business site. Select and verify every member of the tuple together.
+
+## Before you start
+
+### Detect the active edition
+
+Read the repository marker first:
+
+- `__CABLOY_BASIC__` → use the current Basic scripts, flavors, UI baselines, site modules, and paths.
+- `__CABLOY_START__` → inspect the active Start repository before naming a flavor, wrapper, generated package, or site module.
+- both markers → stop: the checkout is ambiguous.
+
+The framework model is shared, but the exact flavor names, site baselines, UI layer, assets, scripts, and generated output paths can differ by edition. See [Edition Detection](/editions/detection) and [Edition Collaboration Differences](/fullstack/edition-collaboration-differences).
+
+### Confirm that a new site is needed
+
+| Change                                                                                      | Normal boundary                                                                                   |
+| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| New page or route inside an existing SSR site                                               | Page, route, model, and existing site verification; normally no new flavor or `@SsrSite`.         |
+| Frontend metadata/resource handoff to an existing backend consumer                          | Reverse contract loop; rebuild every affected existing flavor pair, then run `npm run deps:vona`. |
+| New deployable URL mount, SSR admission policy, assets, or independent frontend composition | New independent flavor and Vona SSR site; continue with this guide.                               |
+
+A new site is an ownership decision, not a convenient alias for an existing Admin or Web surface.
+
+## Define the identity tuple
+
+Choose these values before editing source. Keep their spelling and ownership consistent:
+
+| Identity               | Role                                                                                                            |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `<site-flavor>`        | Exact Zova flavor identifier used in env/config, lower-level scripts, build output, and generated REST package. |
+| `<site-id>`            | Vona SSR site identity and Zova `SITE_ID`; unique among enabled sites.                                          |
+| `<public-path>`        | External mount path; aligned between Zova `APP_PUBLIC_PATH` and Vona `publicPath`; unique among enabled sites.  |
+| `<site-module>`        | Vona module that owns the site bean and copied SSR assets.                                                      |
+| `<bundle-path>`        | Copied SSR release directory under `<site-module>/assets/site`; exactly matches Vona `bundlePath`.              |
+| `<zova-rest-package>`  | Flavor-specific generated REST/type package imported by the Vona site bean.                                     |
+| `<root-build-wrapper>` | Root command that produces the selected SSR bundle **and** REST/type package.                                   |
+
+Only one enabled SSR site may own the empty/root public path. A non-root site’s route aliases are relative to the router mount base; do not repeat `<public-path>` inside those aliases.
+
+## Configure Zova
+
+### 1. Add a tracked flavor environment
+
+Keep shared defaults in `zova/env/.env`; add the site’s tracked flavor override at:
+
+```text
+zova/env/.env.<site-flavor>
+```
+
+The override must select a non-empty `SITE_ID`, the matching `APP_PUBLIC_PATH`, an SSR rendering profile, and the build-copy targets. For a Vona-integrated SSR site, set `SSR_WITH_VONA=true`.
+
+Choose `SSR_PROFILE` from the rendering contract:
+
+- use a public profile for cookie-free, cache-safe first paint;
+- choose a session/private profile deliberately for cookie-backed admission, personalized first paint, or private SSR data.
+
+Point the build destinations to the selected Vona site module and generated package workspace:
+
+```text
+BUILD_COPY_RELEASE = ../vona/src/.../modules/<site-module>/assets/site
+BUILD_REST_COPY_DIST = ../vona/.zova-rest
+```
+
+Do not change ports or worktree-local environment overrides to make a new site work. Follow the normal worktree-environment workflow only when that separate setup is explicitly required.
+
+### 2. Add flavor-specific frontend configuration only where necessary
+
+Use `zova/src/front/config/config/config.<site-flavor>.ts` for site-specific route aliases, route exclusions, layouts, or app configuration. Keep shared API, locale, theme, SSR, and app assembly in base `config.ts`.
+
+For mounted routing:
+
+- configure an unnamed canonical route through `config.routes.path`;
+- configure a named dynamic route through `config.routes.name`;
+- generate a named alias with `$router.getAliasPath(...)` rather than assuming `$router.getPagePath(...)` selects an alias;
+- do not duplicate the external mount prefix in an alias because `APP_PUBLIC_PATH` supplies that boundary.
+
+Choose layouts, title, locales, assets, route exclusions, `requiresAuth`, and redirects from the new site’s contract. Existing Admin and Web sites are specimens, not defaults to copy blindly.
+
+### 3. Add durable scripts and root wrappers
+
+Inspect the active root `package.json` and `zova/package.json` first. Add lower-level Zova scripts in the durable source manifest, normally including:
+
+```text
+dev:ssr:<site-flavor>
+build:ssr:<site-flavor>
+build:rest:<site-flavor>
+preview:ssr:<site-flavor>
+```
+
+The SSR and REST scripts must pass the same flavor. Add a paired batch and an explicit root build wrapper that runs both outputs in order:
+
+```bash
+npm run build:ssr:<site-flavor>
+npm run build:rest:<site-flavor>
+```
+
+Use the root wrapper for normal site-level builds and in Vona diagnostics. Add the flavor to an aggregate build only when it belongs to that edition’s default shipped artifact set.
+
+Edit durable manifests such as root `package.json` and `zova/package.original.json`; do not hand-edit generated `zova/package.json`, generated REST output, copied bundles, or generated dependency state. Do not run `npm run init` merely to synchronize a manifest.
+
+## Register the Vona SSR site
+
+Create or refine an independently packaged Vona site module. It must expose its assets, source entry point, locale metadata, and an SSR-site bean.
+
+The site bean should:
+
+1. import `IPagePathRecord` and `IIconRecord` from `<zova-rest-package>`;
+2. augment the SSR site-ID and public-path type records;
+3. define typed page/page-data options around the generated route record;
+4. extend `BeanSsrSiteBase` and register `@SsrSite(...)`;
+5. provide a localized title, `<site-id>`, `<public-path>`, `<bundle-path>`, and `<root-build-wrapper>` diagnostics command.
+
+Conceptually:
+
+```ts
+@SsrSite({
+  siteId: '<site-id>',
+  publicPath: '<public-path>',
+  bundlePath: '<bundle-path>',
+  diagnostics: { buildCommand: 'npm run <root-build-wrapper>' },
+})
+export class SsrSiteExample extends BeanSsrSiteBase<...> {}
+```
+
+The default release identity is normally `ssr-<site-flavor>-<app-version>`. Unless you intentionally override it, use that exact copied directory as `<bundle-path>`. Vona resolves the bundle from the owning site module’s `assets/site/<bundle-path>` directory.
+
+Ensure the site module is discoverable through its durable suite/module manifest. Let normal tooling generate metadata and dependency closures; do not hand-edit generated metadata.
+
+## Build the artifact pair and sync Vona
+
+For every Vona-consumed independent SSR site, this sequence is required:
+
+```bash
+npm run <root-build-wrapper>
+npm run deps:vona
+```
+
+The wrapper must create both:
+
+```text
+SSR bundle and client assets
++ generated flavor REST/type package
+```
+
+`build:rest:<site-flavor>` alone is not a valid Vona SSR handoff: Vona needs the bundle, assets, and typed REST package to move together. Likewise, a default Admin or Web wrapper does not prove an independently named site was rebuilt.
+
+After generation, verify that:
+
+- the copied release directory matches `<bundle-path>`;
+- the generated package name and Vona import match `<zova-rest-package>`;
+- the Vona local workspace can discover the package after `npm run deps:vona`;
+- the site bean’s diagnostics command names the same root wrapper that produced the artifacts.
+
+If the generated artifacts are correct and `npm run deps:vona` completed but Vona still sees stale local types, diagnose [local dependency drift](/fullstack/contract-loop-playbook#recovery-path-for-local-dependency-drift) only then.
+
+## Verify through the Vona boundary
+
+A standalone Zova development server can help with page iteration, but it does not prove copied artifacts, Vona site matching, generated type handoff, or production-like hydration.
+
+Run the narrowest meaningful checks first:
+
+```bash
+npm run tsc:zova
+npm run <root-build-wrapper>
+npm run deps:vona
+pnpm --dir vona run tsc
+```
+
+Then prove the Vona-served site:
+
+1. request the exact public mount path and assert the intended Vona SSR site handled it;
+2. inspect raw HTML for server-rendered content and the correct cache/admission behavior;
+3. verify client assets load from the mounted site;
+4. open the same route in a browser and assert hydration completes without errors or SSR/client mismatch;
+5. verify canonical and alias route behavior, including no duplicated mount path;
+6. exercise the site’s public/private admission or redirect contract;
+7. retain focused browser/E2E evidence for the new site rather than relying only on compilation.
+
+For more detail, read [SSR Architecture Overview](/frontend/ssr-architecture-overview), [SSR Build and Deploy Guide](/frontend/ssr-build-deploy-guide), [Vona + Zova Integration](/fullstack/vona-zova-integration), and [Contract Loop Playbook](/fullstack/contract-loop-playbook).

package/repo-docs/fullstack/vona-zova-integration.md

@@ -64,6 +64,8 @@ Because Start can differ in UI layer, module composition, SSR site baselines, an
 2. the Start repo’s `package.json`
 3. the exact Zova flavor names and generated output paths used there
 
+For a new independently mounted SSR surface, use [Independent SSR Site and Flavor Setup](/fullstack/ssr-site-and-flavor-setup). It defines the linked Zova flavor, paired SSR/REST artifacts, Vona `@SsrSite` registration, and browser proof without assuming that either edition’s default Admin or Web wrapper applies.
+
 ## Recommended integration workflow
 
 ### 1. Detect the edition

package/repo-e2e/docs/playwright.config.ts

@@ -0,0 +1,37 @@
+import { defineConfig } from '@playwright/test';
+
+const rootDir = new URL('../..', import.meta.url).pathname;
+const baseURL = 'http://127.0.0.1:4173';
+
+export default defineConfig({
+  testDir: `${rootDir}/repo-e2e/docs/specs`,
+  outputDir: `${rootDir}/repo-e2e/docs/test-results`,
+  fullyParallel: false,
+  workers: 1,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  reporter: process.env.CI
+    ? [
+        ['html', { open: 'never', outputFolder: `${rootDir}/repo-e2e/docs/playwright-report` }],
+        ['list'],
+      ]
+    : 'list',
+  use: {
+    baseURL,
+    viewport: { width: 1440, height: 900 },
+    trace: 'on-first-retry',
+  },
+  webServer: {
+    command: 'pnpm --dir repo-docs docs:preview -- --host 127.0.0.1 --port 4173 --strictPort',
+    cwd: rootDir,
+    url: `${baseURL}/`,
+    timeout: 120_000,
+    reuseExistingServer: false,
+    stdout: 'pipe',
+    stderr: 'pipe',
+    gracefulShutdown: {
+      signal: 'SIGINT',
+      timeout: 10_000,
+    },
+  },
+});

package/repo-e2e/docs/specs/blogs-index.spec.ts

@@ -0,0 +1,180 @@
+import type { Page } from '@playwright/test';
+
+import { expect, test } from '@playwright/test';
+
+interface IRectangle {
+  bottom: number;
+  height: number;
+  left: number;
+  right: number;
+  top: number;
+  width: number;
+}
+
+interface IBlogsGeometry {
+  cards: IRectangle[];
+  grid: IRectangle & { display: string };
+}
+
+interface IArticleGeometry {
+  aside: IRectangle;
+  container: IRectangle;
+  content: IRectangle;
+  contentContainer: IRectangle;
+  body: IRectangle;
+}
+
+const blogArticlePaths = [
+  '/blogs/ai-react-nextjs-enterprise-architecture-cabloy/',
+  '/blogs/cabloy-fullstack-resource-addressing/',
+  '/blogs/nextjs-integrated-fullstack-cabloy-contract-loop/',
+  '/blogs/vue-object-oriented-zova-beginner-mental-model/',
+];
+
+function collectPageErrors(page: Page) {
+  const errors: Error[] = [];
+  page.on('pageerror', error => {
+    errors.push(error);
+  });
+  return errors;
+}
+
+function collectConsoleErrors(page: Page) {
+  const errors: string[] = [];
+  page.on('console', message => {
+    const text = message.text();
+    if (message.type() === 'error' || /hydration mismatch/i.test(text)) {
+      errors.push(text);
+    }
+  });
+  return errors;
+}
+
+function getDocumentHorizontalOverflow(page: Page) {
+  return page.evaluate(() => {
+    return (
+      Math.max(document.documentElement.scrollWidth, document.body.scrollWidth) - window.innerWidth
+    );
+  });
+}
+
+function getBlogsGeometry(page: Page) {
+  return page.locator('.cabloy-blog-grid').evaluate(grid => {
+    const toRectangle = (element: Element) => {
+      const { bottom, height, left, right, top, width } = element.getBoundingClientRect();
+      return { bottom, height, left, right, top, width };
+    };
+    const cards = Array.from(grid.querySelectorAll('.cabloy-blog-card'), toRectangle);
+    return {
+      grid: {
+        ...toRectangle(grid),
+        display: getComputedStyle(grid).display,
+      },
+      cards,
+    };
+  }) as Promise<IBlogsGeometry>;
+}
+
+function getArticleGeometry(page: Page) {
+  return page.locator('.VPDoc').evaluate(doc => {
+    const getRequiredChild = (parent: Element, selector: string) => {
+      const element = parent.querySelector(`:scope > ${selector}`);
+      if (!element) throw new Error(`Could not find ${selector}`);
+      return element;
+    };
+    const toRectangle = (element: Element) => {
+      const { bottom, height, left, right, top, width } = element.getBoundingClientRect();
+      return { bottom, height, left, right, top, width };
+    };
+    const container = getRequiredChild(doc, '.container');
+    const aside = getRequiredChild(container, '.aside');
+    const content = getRequiredChild(container, '.content');
+    const contentContainer = getRequiredChild(content, '.content-container');
+    const body = getRequiredChild(contentContainer, '.main').querySelector('.vp-doc');
+    if (!body) throw new Error('Could not find .vp-doc');
+    return {
+      aside: toRectangle(aside),
+      container: toRectangle(container),
+      content: toRectangle(content),
+      contentContainer: toRectangle(contentContainer),
+      body: toRectangle(body),
+    };
+  }) as Promise<IArticleGeometry>;
+}
+
+test(
+  'DOCS-BLOGS-01: Blogs index uses a wide desktop card grid',
+  { tag: '@layout' },
+  async ({ page }) => {
+    const pageErrors = collectPageErrors(page);
+    const consoleErrors = collectConsoleErrors(page);
+
+    const documentResponse = await page.goto('/blogs/', { waitUntil: 'load' });
+    expect(documentResponse?.ok()).toBeTruthy();
+
+    await expect(page.locator('.Layout.cabloy-blogs-index')).toBeVisible();
+    await expect(page.getByRole('heading', { name: 'Blogs', level: 1 })).toBeVisible();
+    await expect(page.locator('.VPDoc.has-sidebar')).toHaveCount(0);
+    await expect(page.locator('.VPDoc.has-aside')).toHaveCount(0);
+
+    const cards = page.locator('.cabloy-blog-card');
+    await expect(cards).toHaveCount(4);
+    for (let index = 0; index < 4; index++) {
+      await expect(cards.nth(index)).toBeVisible();
+      await expect(cards.nth(index).locator('.cabloy-blog-card__cover img')).toBeVisible();
+    }
+
+    const geometry = await getBlogsGeometry(page);
+    expect(geometry.grid.display).toBe('grid');
+    expect(geometry.cards).toHaveLength(4);
+
+    const [firstCard, ...remainingCards] = geometry.cards;
+    expect(firstCard.width).toBeGreaterThanOrEqual(279);
+    for (const card of remainingCards) {
+      expect(Math.abs(card.top - firstCard.top)).toBeLessThanOrEqual(1);
+      expect(Math.abs(card.width - firstCard.width)).toBeLessThanOrEqual(1);
+      expect(card.left).toBeGreaterThan(firstCard.left);
+      expect(card.left).toBeGreaterThanOrEqual(geometry.grid.left - 1);
+      expect(card.right).toBeLessThanOrEqual(geometry.grid.right + 1);
+      expect(card.right).toBeLessThanOrEqual(1441);
+    }
+    expect(firstCard.left).toBeGreaterThanOrEqual(geometry.grid.left - 1);
+    expect(firstCard.right).toBeLessThanOrEqual(geometry.grid.right + 1);
+    expect(firstCard.right).toBeLessThanOrEqual(1441);
+
+    await expect.poll(() => getDocumentHorizontalOverflow(page)).toBeLessThanOrEqual(1);
+    expect(pageErrors).toEqual([]);
+    expect(consoleErrors).toEqual([]);
+  },
+);
+
+test(
+  'DOCS-BLOGS-02: Blog articles use a wide desktop body with an outline aside',
+  { tag: '@layout' },
+  async ({ page }) => {
+    const pageErrors = collectPageErrors(page);
+    const consoleErrors = collectConsoleErrors(page);
+
+    for (const path of blogArticlePaths) {
+      const documentResponse = await page.goto(path, { waitUntil: 'load' });
+      expect(documentResponse?.ok()).toBeTruthy();
+
+      await expect(page.locator('.Layout.cabloy-blogs-article')).toBeVisible();
+      await expect(page.locator('.VPDoc.has-sidebar')).toHaveCount(0);
+      await expect(page.locator('.VPDoc.has-aside')).toHaveCount(1);
+      await expect(page.locator('.aside')).toBeVisible();
+
+      const geometry = await getArticleGeometry(page);
+      expect(geometry.container.width).toBeCloseTo(1216, 0);
+      expect(geometry.content.width).toBeCloseTo(960, 0);
+      expect(geometry.contentContainer.width).toBeCloseTo(896, 0);
+      expect(geometry.body.width).toBeCloseTo(896, 0);
+      expect(geometry.aside.left).toBeGreaterThanOrEqual(geometry.content.right - 1);
+      expect(geometry.aside.right).toBeLessThanOrEqual(geometry.container.right + 1);
+      await expect.poll(() => getDocumentHorizontalOverflow(page)).toBeLessThanOrEqual(1);
+    }
+
+    expect(pageErrors).toEqual([]);
+    expect(consoleErrors).toEqual([]);
+  },
+);