cabloy 5.1.157 → 5.1.159

package/repo-docs/.vitepress/theme/components/GitHubRepositoriesNav.vue

@@ -0,0 +1,255 @@
+<script setup>
+import { nextTick, onMounted, onUnmounted, ref, useId } from 'vue';
+
+const props = defineProps({
+  repositories: {
+    type: Array,
+    required: true,
+  },
+  screenMenu: Boolean,
+});
+
+const isOpen = ref(false);
+const root = ref();
+const trigger = ref();
+const menu = ref();
+const menuId = useId();
+
+function close({ returnFocus = false } = {}) {
+  isOpen.value = false;
+  if (returnFocus) {
+    trigger.value?.focus();
+  }
+}
+
+async function open({ focusIndex } = {}) {
+  isOpen.value = true;
+  if (focusIndex === undefined) return;
+
+  await nextTick();
+  menu.value?.querySelectorAll('a')[focusIndex]?.focus();
+}
+
+function toggle() {
+  if (isOpen.value) {
+    close();
+  } else {
+    open();
+  }
+}
+
+function handleTriggerKeydown(event) {
+  if (event.key === 'ArrowDown') {
+    event.preventDefault();
+    open({ focusIndex: 0 });
+  } else if (event.key === 'ArrowUp') {
+    event.preventDefault();
+    open({ focusIndex: props.repositories.length - 1 });
+  } else if (event.key === 'Escape') {
+    close();
+  }
+}
+
+function handleMenuKeydown(event) {
+  const links = [...menu.value.querySelectorAll('a')];
+  const index = links.indexOf(document.activeElement);
+  if (index === -1) return;
+
+  let nextIndex;
+  if (event.key === 'ArrowDown') {
+    nextIndex = (index + 1) % links.length;
+  } else if (event.key === 'ArrowUp') {
+    nextIndex = (index - 1 + links.length) % links.length;
+  } else if (event.key === 'Home') {
+    nextIndex = 0;
+  } else if (event.key === 'End') {
+    nextIndex = links.length - 1;
+  } else if (event.key === 'Escape') {
+    event.preventDefault();
+    close({ returnFocus: true });
+    return;
+  } else {
+    return;
+  }
+
+  event.preventDefault();
+  links[nextIndex]?.focus();
+}
+
+function handlePointerDown(event) {
+  if (isOpen.value && !root.value?.contains(event.target)) {
+    close();
+  }
+}
+
+function handleFocusIn(event) {
+  if (isOpen.value && !root.value?.contains(event.target)) {
+    close();
+  }
+}
+
+onMounted(() => {
+  document.addEventListener('pointerdown', handlePointerDown);
+  document.addEventListener('focusin', handleFocusIn);
+});
+
+onUnmounted(() => {
+  document.removeEventListener('pointerdown', handlePointerDown);
+  document.removeEventListener('focusin', handleFocusIn);
+});
+</script>
+
+<template>
+  <section v-if="screenMenu" class="cabloy-github-repositories cabloy-github-repositories--screen">
+    <p class="cabloy-github-repositories__title">GitHub repositories</p>
+    <a
+      v-for="repository in repositories"
+      :key="repository.link"
+      class="cabloy-github-repositories__screen-link"
+      :href="repository.link"
+      target="_blank"
+      rel="noopener noreferrer"
+    >
+      {{ repository.text }}
+    </a>
+  </section>
+
+  <div v-else ref="root" class="cabloy-github-repositories">
+    <button
+      ref="trigger"
+      class="cabloy-github-repositories__trigger"
+      type="button"
+      aria-label="GitHub repositories"
+      aria-haspopup="menu"
+      :aria-controls="menuId"
+      :aria-expanded="isOpen"
+      @click="toggle"
+      @keydown="handleTriggerKeydown"
+    >
+      <svg aria-hidden="true" focusable="false" viewBox="0 0 24 24">
+        <path
+          fill="currentColor"
+          d="M12 2C6.477 2 2 6.59 2 12.253c0 4.53 2.865 8.37 6.839 9.727.5.095.682-.223.682-.494 0-.244-.009-1.05-.014-1.906-2.782.621-3.369-1.215-3.369-1.215-.455-1.185-1.11-1.5-1.11-1.5-.908-.64.069-.627.069-.627 1.004.073 1.532 1.057 1.532 1.057.892 1.567 2.341 1.114 2.91.852.09-.663.349-1.115.635-1.371-2.22-.26-4.555-1.139-4.555-5.067 0-1.12.39-2.034 1.03-2.752-.104-.26-.447-1.306.098-2.724 0 0 .84-.278 2.75 1.051A9.3 9.3 0 0 1 12 6.89a9.3 9.3 0 0 1 2.504.347c1.909-1.33 2.748-1.051 2.748-1.051.546 1.418.203 2.464.1 2.724.64.718 1.028 1.632 1.028 2.752 0 3.938-2.339 4.804-4.566 5.058.359.32.678.947.678 1.91 0 1.38-.012 2.492-.012 2.832 0 .274.18.594.688.493C19.14 20.619 22 16.78 22 12.253 22 6.59 17.523 2 12 2Z"
+        />
+      </svg>
+    </button>
+
+    <div
+      v-if="isOpen"
+      :id="menuId"
+      ref="menu"
+      class="cabloy-github-repositories__menu"
+      role="menu"
+      aria-label="GitHub repositories"
+      @keydown="handleMenuKeydown"
+    >
+      <a
+        v-for="repository in repositories"
+        :key="repository.link"
+        class="cabloy-github-repositories__menu-link"
+        :href="repository.link"
+        role="menuitem"
+        target="_blank"
+        rel="noopener noreferrer"
+        @click="close"
+      >
+        {{ repository.text }}
+      </a>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.cabloy-github-repositories {
+  position: relative;
+  display: flex;
+  align-items: center;
+}
+
+.cabloy-github-repositories__trigger {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--vp-c-text-2);
+  cursor: pointer;
+}
+
+.cabloy-github-repositories__trigger:hover,
+.cabloy-github-repositories__trigger[aria-expanded='true'] {
+  color: var(--vp-c-text-1);
+}
+
+.cabloy-github-repositories__trigger:focus-visible,
+.cabloy-github-repositories__menu-link:focus-visible,
+.cabloy-github-repositories__screen-link:focus-visible {
+  outline: 2px solid var(--vp-c-brand-1);
+  outline-offset: 2px;
+}
+
+.cabloy-github-repositories__trigger svg {
+  width: 20px;
+  height: 20px;
+}
+
+.cabloy-github-repositories__menu {
+  position: absolute;
+  z-index: 1;
+  top: calc(100% + 4px);
+  right: 0;
+  min-width: 160px;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  padding: 4px;
+  background: var(--vp-c-bg-elv);
+  box-shadow: var(--vp-shadow-3);
+}
+
+.cabloy-github-repositories__menu-link,
+.cabloy-github-repositories__screen-link {
+  display: block;
+  color: var(--vp-c-text-1);
+  text-decoration: none;
+}
+
+.cabloy-github-repositories__menu-link {
+  border-radius: 4px;
+  padding: 0.5rem 0.75rem;
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  white-space: nowrap;
+}
+
+.cabloy-github-repositories__menu-link:hover {
+  background: var(--vp-c-bg-soft);
+  color: var(--vp-c-brand-1);
+}
+
+.cabloy-github-repositories--screen {
+  display: block;
+  padding: 12px 0;
+}
+
+.cabloy-github-repositories__title {
+  margin: 0 0 4px;
+  color: var(--vp-c-text-2);
+  font-size: 0.75rem;
+  font-weight: 600;
+  line-height: 1.25rem;
+  text-transform: uppercase;
+}
+
+.cabloy-github-repositories__screen-link {
+  padding: 0.5rem 0;
+  font-size: 1rem;
+  line-height: 1.5rem;
+}
+
+.cabloy-github-repositories__screen-link:hover {
+  color: var(--vp-c-brand-1);
+}
+</style>

package/repo-docs/.vitepress/theme/custom.css

@@ -63,6 +63,27 @@
   color: #fdba74;
 }
 
+@media (min-width: 960px) {
+  .cabloy-blogs-index .VPDoc:not(.has-sidebar) .container,
+  .cabloy-blogs-index .VPDoc:not(.has-sidebar) .content {
+    max-width: 1440px;
+  }
+}
+
+@media (min-width: 1280px) {
+  .cabloy-blogs-article .VPDoc.has-aside:not(.has-sidebar) .container {
+    max-width: 1216px;
+  }
+
+  .cabloy-blogs-article .VPDoc.has-aside:not(.has-sidebar) .content {
+    max-width: 960px;
+  }
+
+  .cabloy-blogs-article .VPDoc.has-aside:not(.has-sidebar) .content-container {
+    max-width: 896px;
+  }
+}
+
 .cabloy-blog-grid {
   display: grid;
   grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));

package/repo-docs/.vitepress/theme/index.js

@@ -1,5 +1,11 @@
 import DefaultTheme from 'vitepress/theme';
 
+import GitHubRepositoriesNav from './components/GitHubRepositoriesNav.vue';
 import './custom.css';
 
-export default DefaultTheme;
+export default {
+  extends: DefaultTheme,
+  enhanceApp({ app }) {
+    app.component('GitHubRepositoriesNav', GitHubRepositoriesNav);
+  },
+};

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: