cabloy 5.1.158 → 5.1.159

package/repo-docs/backend/resource-field-update.md

@@ -13,6 +13,7 @@ Use it when you need to:
 - add a stored field to an existing resource;
 - refine validation, titles, OpenAPI metadata, or `ZovaRender.field(...)` / `ZovaRender.cell(...)` metadata for an existing field;
 - add enum-like field constraints;
+- filter or sort an existing foreign-key field by a display column from its related table without replacing the stored foreign-key contract;
 - decide whether a persisted field change increments `vonaModule.fileVersion`;
 - add a custom form-field or table-cell renderer because shared renderer options are insufficient.
 
@@ -93,6 +94,43 @@ For projected fields, use `$makeMetadata(...)` for metadata-only refinement and
 
 Read [DTO Infer and Generation](/backend/dto-infer-generation) when inference cannot express the intended contract. If serialization metadata controls the returned value, also confirm that the target controller action opts into `@Core.serializer()`.
 
+## Filter and sort a relation by its display field
+
+A resource list can search and order a relation by a human-readable column from its related table without changing the persisted relation contract. Keep the entity field as the foreign-key identity and place the join mapping on that entity field. For example, `studentId` remains a `TableIdentity` even though the list filter accepts part of the student's name:
+
+```ts
+@Api.field(
+  v.filter({
+    table: 'trainingStudent',
+    joinType: 'innerJoin',
+    joinOn: ['studentId', 'trainingStudent.id'],
+    originalName: 'name',
+    op: '_includesI_',
+  }),
+  ZovaRender.column({ enableSorting: true }),
+  v.tableIdentity(),
+)
+studentId: TableIdentity;
+```
+
+`table` and `joinOn` identify the relation, while `originalName` resolves both the `studentId` filter and order key to `trainingStudent.name`. `_includesI_` makes the filter a case-insensitive partial-name match. `ZovaRender.column({ enableSorting: true })` exposes the sortable table column; the query pipeline uses the same field metadata to add the join and rewrite `orders: [['studentId', 'asc']]` to the related display column.
+
+Use `innerJoin` deliberately when the relation is required and unmatched rows should not participate in this filter/order path. For an optional relation whose unmatched rows must remain visible, choose the join behavior explicitly instead of copying the required-relation example.
+
+Keep `studentId` as the public filter and order key. In the select request DTO, override only its query-input schema and renderer so a text fragment reaches the join-backed filter; the entity and create/update contracts remain foreign-key identities:
+
+```ts
+fields: {
+  studentId: $makeSchema(
+    ZovaRender.field('basic-input:formFieldInput'),
+    v.optional(),
+    z.string(),
+  ),
+},
+```
+
+Do not add a parallel `studentName` query field unless the API intentionally needs distinct ID and display-name filtering semantics. For the underlying query behavior, see [ORM Select Guide](/backend/orm-select-guide). For the list-page query path, see [Filter to Query to Select Data Flow](/frontend/filter-query-select-data-flow-guide).
+
 ## Choose the renderer branch
 
 Prefer the smallest rendering change that expresses the requirement:
@@ -141,6 +179,14 @@ Minimum backend coverage generally includes:
 - get-by-id or view response;
 - delete behavior when it is relevant.
 
+For join-backed relation filtering and sorting, also verify:
+
+- the projected request field is optional text while the entity remains a foreign-key identity;
+- direct DTO metadata retains the intended `table`, `joinType`, `joinOn`, `originalName`, and operator;
+- the select action exposes the intended query parameter without an unintended parallel display-name parameter;
+- filtering returns records whose related display value matches the text fragment;
+- ascending and descending orders return the expected related-display ordering, including the selected join behavior for unmatched rows.
+
 For constrained enum-like values, add a negative test that proves an invalid value is rejected. Test-local persisted resources must be deleted in `finally` using precise owned identities and reverse dependency order.
 
 ## Verification checklist
@@ -151,6 +197,7 @@ Choose checks that match the layers changed:
 - run the narrow resource test and relevant typecheck;
 - run `npm run test` for any `meta.version.ts` change so the test database is recreated and migration consistency is exercised;
 - run the relevant frontend metadata/build/dependency synchronization when custom renderer resources are involved;
-- verify action-level serializer behavior with an API test when `v.serializer*` metadata changes returned fields.
+- verify action-level serializer behavior with an API test when `v.serializer*` metadata changes returned fields;
+- for join-backed filters and sorting, inspect transformed `where`, `orders`, and `joins`, then exercise the resource endpoint so metadata-only success cannot hide incorrect query behavior.
 
 Finish by confirming the backend contract, frontend resources, generated handoff, and user-visible locale labels all describe the same field behavior.

package/repo-docs/blogs/index.md

@@ -1,5 +1,7 @@
 ---
 title: Blogs
+pageClass: cabloy-blogs-index
+aside: false
 ---
 
 # Blogs

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

@@ -219,11 +219,11 @@ Set `layout: 'flow'` when compact fields should appear from left to right withou
 
 ## 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. The preceding OpenAPI normalization step is explained in [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood#scene-overlays-fieldsource-and-preserved-aliases).
+Before rendering, `resolveFormLayout(...)` reconciles `formLayout` with the current scene's resolved schema properties. A configured Form Layout is an **explicit allow-list**: it renders only successfully resolved declared fields and explicit block nodes. The preceding OpenAPI normalization step is explained in [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood#scene-overlays-fieldsource-and-preserved-aliases).
 
-### Eligible and omitted fields
+### Eligible and declared 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.
+Only schema properties with `rest.visible !== false` are eligible for a field declaration. Eligibility alone does not render a field: a visible field absent from `formLayout.children` does not render and produces no diagnostic.
 
 A field that uses `fieldSource` is represented at runtime by its nested canonical source key. The loader stores that source path in `key`, retains the first differing original schema name in `schemaKey`, and retains further coalesced names in `schemaKeys`. A property already named by its canonical key retains that identity in `key`. These preserved names are aliases for declaration matching, not separate fields or bindings.
 
@@ -237,9 +237,9 @@ For example, a real relation declaration `studentContentForm` can resolve to the
 
 An alias or relation prefix must resolve to exactly one eligible canonical source. If multiple visible source keys match, it is unresolved and receives `unknownField`; declare the exact canonical source key instead. Exact canonical matches win over colliding aliases. Invisible properties contribute neither eligible fields nor usable aliases.
 
-Duplicate declarations are detected by canonical key, so an alias and `content.descriptionMarkdown` cannot render the same field twice. Resolved field names, duplicate identity, and tab paths all use the canonical key. If a declaration is removed because it is unknown, invisible, ambiguous, or duplicate, otherwise unplaced eligible canonical fields are still appended at the root.
+Duplicate declarations are detected by canonical key, so an alias and `content.descriptionMarkdown` cannot render the same field twice. Resolved field names, duplicate identity, and tab paths all use the canonical key. If a declaration is removed because it is unknown, invisible, ambiguous, or duplicate, it does not render and no other eligible fields are added as a fallback.
 
-If a field must not render, make it invisible in schema metadata. Leaving it out of `formLayout.children` is not enough.
+Use `rest.visible: false` when a field must be ineligible in the schema scene. In a configured Form Layout, leave a visible field out of `formLayout.children` when it should not render there.
 
 ### Invalid declarations and diagnostics
 
@@ -384,7 +384,7 @@ Here `formFieldLayout.inline: true` controls how each field wrapper is presented
 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 synthetic request-only filter 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.
+8. Review field names against the scene-specific schema. Explicitly list every field that should render; omitted visible fields do not render, while unknown and duplicate declarations are silently pruned from the rendered plan.
 9. Prefer an exact canonical source path when an alias or relation prefix could match multiple visible fields. Do not list both an alias and its canonical key; canonical duplicate detection keeps only the first declaration.
 
 ## Source-reading and verification path

package/repo-docs/frontend/page-guide.md

@@ -66,6 +66,18 @@ class ControllerPageCounter {
 }
 ```
 
+### Keep callbacks on the reactive bean path
+
+Use ordinary controller methods as the default for actions that change controller state. Do not expose a state-mutating class-field arrow callback such as `onIncrement = () => this.count++`: it captures construction-time `this` before Zova exposes the controller's reactive/proxied bean.
+
+At a TSX or component-prop boundary, forward to the method instead:
+
+```typescript
+onClick={() => this.increment()}
+```
+
+When an external API requires a stable callback reference, create the closure in `__init__()` after the controller has been prepared. See [Zova Reactivity Under the Hood](/frontend/zova-reactivity-under-the-hood#construction-time-this-and-the-exposed-reactive-bean) for the lifecycle reason and safe pattern.
+
 ## Add render logic
 
 Representative TSX render pattern:

package/repo-docs/frontend/page-meta-guide.md

@@ -90,6 +90,33 @@ export interface IPageMeta {
 
 In the current Basic source, this is typically what the Admin layout uses for the level-2 item label instead of the broader menu-backed workspace title.
 
+### Resource entry `pageTitleKey`
+
+For schema-driven Resource entry pages, `basic-pageentry:blockPageEntry` derives `pageTitle` from the current form data. Its default `pageTitleKey` is `name`.
+
+When the resource's human-readable identifier uses another top-level field, configure that field explicitly on the page-entry block in the DTO:
+
+```typescript
+@Dto({
+  blocks: [
+    ZovaRender.block('basic-pageentry:blockPageEntry', {
+      pageTitleKey: 'title',
+      blocks: [
+        // form and toolbar blocks
+      ],
+    }),
+  ],
+})
+```
+
+Use the same key in the create, update, and view DTOs when those scenes should show a consistent task title. Common choices include `title` and `code`; do not add a synthetic `name` field merely to satisfy the default.
+
+Keep these boundaries in mind:
+
+- `pageTitleKey` controls the routed-shell level-2 task title, not the resource or OpenAPI schema title and not the browser document title.
+- The current implementation reads one exact top-level form-data key. It is not a dotted-path resolver or a formatter.
+- When the source field is `null` or `undefined`, the current page-entry runtime falls back to the resolved form DTO schema's OpenAPI `title`. Give the create DTO an operation-specific title such as `openapi: { title: $locale('CreateProduct') }` when it needs an initial task label; a populated source field takes precedence. The fallback is not used for an empty string.
+
 ### `pageDirty`
 
 `pageDirty` tells the routed shell whether the current work item should appear dirty.

package/repo-docs/frontend/ssr-architecture-overview.md

@@ -187,6 +187,10 @@ What can differ by edition is usually:
 
 So the architecture model is shared, while some concrete frontend examples remain edition-sensitive.
 
+## Adding an independent SSR site
+
+The architecture maps one Vona SSR site to one built Zova flavor bundle. When a new deployable mount needs its own flavor and Vona dispatch registration, follow [Independent SSR Site and Flavor Setup](/fullstack/ssr-site-and-flavor-setup). It covers the matching site ID, public path, bundle path, generated REST types, paired build wrapper, and hydration proof.
+
 ## Recommended reading order
 
 Use this order when you need the shortest path from mental model to implementation detail:

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

@@ -130,7 +130,7 @@ If you need deeper script control or need to verify the exact Zova flavor path,
 
 ### Build frontend SSR output only
 
-Use this when you need the frontend SSR artifacts refreshed but do not yet need the full backend build flow.
+Use this when you need the frontend SSR artifacts refreshed but do not yet need the full backend build flow. If the task creates a new independently mounted site rather than refreshing an existing one, first follow [Independent SSR Site and Flavor Setup](/fullstack/ssr-site-and-flavor-setup): the new site needs its own source-confirmed wrapper that pairs its SSR and REST outputs, not a renamed default Admin or Web wrapper.
 
 Representative current Basic command:
 

package/repo-docs/frontend/zova-form-source-reading-map.md

@@ -233,7 +233,7 @@ Use this path when you are asking questions like:
 - where does `formLayout` come from in a resource DTO?
 - how are fields, embedded blocks, sections, groups, and tabs normalized before rendering?
 - how do canonical keys, preserved schema aliases, and unique relation-prefix shorthand resolve to one field?
-- why are omitted visible fields appended or duplicate fields removed?
+- why do omitted fields not render, or duplicate fields get removed?
 - where does Cabloy Basic render responsive grids and tab error badges?
 
 ### Read the docs first
@@ -266,7 +266,7 @@ Use this path when you are asking questions like:
 - the resolver filters visible fields, resolves exact canonical keys before unique aliases and unique prefixes, and records duplicate identity and tab paths by canonical key
 - the Basic block controller renders sections, groups, tabs, field spans, and embedded blocks while delegating canonical field names to `$$form.renderField(...)`
 - `blockFilterActions` shows how a block rendered inside Form Layout reuses the inherited form CEL scope to invoke `$$filter`
-- the OpenAPI and Form Layout unit tests verify canonicalization, alias precedence, ambiguity, duplicates, visibility, root append, and tab paths
+- the OpenAPI and Form Layout unit tests verify canonicalization, explicit field inclusion, alias precedence, ambiguity, duplicates, visibility, and tab paths
 - the Student test verifies emitted metadata nesting, columns, spans, embedded action blocks, and optional IDs; it is not a browser rendering test
 
 ## 8. Resource-driven CRUD page integration

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

@@ -454,7 +454,7 @@ That means automatic schema-driven rendering is not happening magically in the w
 
 When `ZForm` receives a nonempty block list, the render bean delegates body rendering to those blocks instead of iterating schema fields directly. For Cabloy Basic structural forms, `basic-form:blockFormLayout` resolves `formLayout` against the form's current schema properties and calls `$$form.renderField(...)` for each surviving layout field.
 
-For a field declaration, the shared resolver first accepts an exact canonical key, then a uniquely mapped preserved schema alias, and then a unique relation-prefix shorthand. It rewrites an alias or shorthand to the canonical key before calling `$$form.renderField(...)`. Exact canonical keys win over colliding aliases; ambiguous aliases or prefixes are reported as `unknownField`. Duplicate tracking and tab-path bookkeeping use the canonical key, while visible canonical fields not placed by a surviving declaration are appended afterward. See [Form Layout Guide](/frontend/form-layout-guide#how-the-resolver-handles-the-declared-tree) for the full DTO authoring rules.
+For a field declaration, the shared resolver first accepts an exact canonical key, then a uniquely mapped preserved schema alias, and then a unique relation-prefix shorthand. It rewrites an alias or shorthand to the canonical key before calling `$$form.renderField(...)`. Exact canonical keys win over colliding aliases; ambiguous aliases or prefixes are reported as `unknownField`. A configured Form Layout is an explicit allow-list: only fields represented by surviving declarations render. Duplicate tracking and tab-path bookkeeping use the canonical key. See [Form Layout Guide](/frontend/form-layout-guide#how-the-resolver-handles-the-declared-tree) for the full DTO authoring rules.
 
 Form Layout also supports a leaf `block` node. It wraps an existing resource block descriptor and the Basic renderer invokes it with the inherited `IJsxRenderContextForm`, including the same JSX runtime and CEL scope. The node has no schema property or field value; for example, a filter can place `basic-page:blockFilterActions` inside a flow section while that action block continues to read `$$filter` from the filter-owned form scope.
 

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

@@ -151,6 +151,62 @@ This is one of the most important source-level facts for understanding Zova.
 
 Zova does not require the business author to write `reactive({ ... })` around controller state, because the framework already treats the controller bean as the reactive object.
 
+#### Construction-time `this` and the exposed reactive bean
+
+There is one lifecycle boundary that matters when a callback closes over `this`:
+
+1. the container first constructs the raw class instance with `new BeanClass(...)`;
+2. it then exposes the framework-managed reactive/proxied bean; and
+3. it invokes `__init__()` only after that preparation completes.
+
+That distinction is normally invisible when a controller uses ordinary methods and render-time `this.member` access. It matters for a class-field arrow callback that mutates controller state, because the arrow is created during construction and lexically captures the construction-time raw `this`:
+
+```typescript
+class ControllerPageCounter {
+  count = 0;
+
+  // Avoid for a state-mutating controller callback.
+  onIncrement = () => {
+    this.count++;
+  };
+}
+```
+
+The field can change on the raw instance, but the mutation bypasses the reactive/proxied bean through which render dependencies were collected. Vue therefore receives no invalidation notification. A later update to another dependency can rerender the component and reveal the changed underlying value, which can make this look intermittent.
+
+Prefer an ordinary controller method for a normal TSX action:
+
+```typescript
+class ControllerPageCounter {
+  count = 0;
+
+  increment() {
+    this.count++;
+  }
+
+  protected render() {
+    return <button onClick={() => this.increment()}>Increment</button>;
+  }
+}
+```
+
+If an external API requires a stable stored callback, create that closure in `__init__()` instead. At that point, its lexical `this` is the framework-exposed reactive/proxied bean:
+
+```typescript
+class ControllerPageCounter {
+  count = 0;
+  onIncrement: () => void;
+
+  protected async __init__() {
+    this.onIncrement = () => {
+      this.count++;
+    };
+  }
+}
+```
+
+This is not a rule that arrow functions are generally non-reactive. The narrow hazard is a **class-field arrow callback that captures construction-time `this` and mutates bean state**.
+
 ### 4. `$computed()` is an instance-scoped wrapper around Vue `computed(...)`
 
 In:
@@ -238,21 +294,21 @@ A practical reading takeaway is:
 
 ### 7. Field mutation becomes normal reactive invalidation and rerender
 
-Once the controller bean is reactive and render has read its fields, changes such as:
+Once render has read fields through the framework-exposed reactive/proxied controller, a mutation through that same identity, such as:
 
 ```typescript
 this.count++;
 ```
 
-behave the way a Vue reader would expect at the reactive-engine level:
+behaves the way a Vue reader would expect at the reactive-engine level:
 
 - the field change invalidates dependencies
 - computed values depending on that field are recomputed
 - the next render sees the updated values
 
-So the runtime behavior is still recognizably Vue-like.
+The construction-time class-field arrow case described above is the exception: its raw `this` can change the underlying field without triggering the dependency that render collected through the exposed bean.
 
-The architectural surface is what changed.
+So the runtime behavior is still recognizably Vue-like. The architectural surface, including the bean lifecycle and identity boundary, is what changed.
 
 ## A compact call-flow sketch
 
@@ -260,13 +316,13 @@ The architectural surface is what changed.
 useControllerPage(...)
   -> _useController(...)
   -> ctx.bean._newBeanInner(..., markReactive = true)
-  -> BeanContainer creates controller bean
-  -> BeanContainer applies reactive(...)
-  -> controller __init__ wires $computed / $watch helpers
+  -> BeanContainer constructs the raw controller bean
+  -> BeanContainer exposes the reactive/proxied controller bean
+  -> controller __init__ wires $computed / $watch helpers and any stored callbacks
   -> component render is patched toward controller/render bean
   -> render-time controller data update refreshes page route data
-  -> render reads controller fields
-  -> field mutation invalidates dependencies
+  -> render reads fields through the exposed bean
+  -> mutation through that same identity invalidates dependencies
   -> rerender produces updated UI
 ```
 

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,
+    },
+  },
+});