cabloy 5.1.174 → 5.1.176

package/repo-docs/frontend/controller-boundary-guide.md

@@ -0,0 +1,229 @@
+# Controller Load Boundary Guide
+
+A Zova Controller-load boundary renders a loading or error fallback while a page or component controller host initializes. It is available in both **Cabloy Basic** and **Cabloy Start**.
+
+The runtime contract is shared by the editions. Their default fallback presentation is deliberately different: Basic uses DaisyUI + Tailwind CSS, while Start uses Vuetify. See [Cabloy Editions](/editions/overview) before copying UI-specific renderer code between editions.
+
+## What this boundary owns
+
+A generated Zova page or component host loads these beans in order:
+
+```text
+Controller → optional Style bean → optional Render bean
+```
+
+While that chain is pending, the host can render a loading fallback. If an initialization error is not handled by the application error path, the host can render an error fallback instead.
+
+This is a **Controller-load** boundary, not a general-purpose Vue error boundary. In particular, it does not automatically turn these failures into its fallback UI:
+
+- an exception from ordinary `render()` work after the Controller has loaded;
+- an event-handler or action failure;
+- a query, mutation, or data-fetch failure that occurs after initialization;
+- browser-only work that should have been deferred from SSR.
+
+Choose the owner that matches the concern: use [Behavior Guide](/frontend/behavior-guide) for composable render-time interception, [$useStateData Best Practices](/frontend/use-state-data-best-practices) for model-owned async state, and [SSR ClientOnly](/frontend/ssr-client-only) for browser-only rendering. Read [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers) first if the Controller / Render / Style bean model is unfamiliar.
+
+## Configure one Controller host
+
+Declare boundary options on the page or component Controller:
+
+```ts
+import { BeanControllerBase, IComponentOptions } from 'zova';
+import { Controller } from 'zova-module-a-bean';
+
+@Controller()
+export class ControllerReport extends BeanControllerBase {
+  static $componentOptions: IComponentOptions = {
+    boundary: {
+      loading: { delay: 500 },
+      renderMode: 'inline',
+      retry: true,
+    },
+  };
+}
+```
+
+The options have the following roles:
+
+| Option                   | Meaning                                                                                           |
+| ------------------------ | ------------------------------------------------------------------------------------------------- |
+| `boundary.loading.delay` | Milliseconds to wait before exposing the loading fallback for this Controller host.               |
+| `boundary.renderMode`    | Fallback structure hint: `'block'` or `'inline'`.                                                 |
+| `boundary.retry`         | Opts this Controller host into a retry action after an error fallback. It is disabled by default. |
+
+### Resolution and defaults
+
+| Concern            | Controller option                        | Global application configuration                              | Runtime behavior                                                                                      |
+| ------------------ | ---------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Loading delay      | `boundary.loading.delay`                 | `config.boundary.loading?.delay`                              | The Controller value wins. An invalid, zero, or negative resolved value displays loading immediately. |
+| Render mode        | `boundary.renderMode`                    | —                                                             | Defaults to `'block'`; only the explicit value `'inline'` selects inline mode.                        |
+| Retry availability | `boundary.retry`                         | —                                                             | Disabled by default; see [Retry safely](#retry-safely).                                               |
+| Loading renderer   | `renderLoading(renderMode)`              | `config.boundary.renderLoading(ctx, renderMode)`              | Controller renderer wins, then application renderer, then no loading VNode.                           |
+| Error renderer     | `renderError(error, renderMode, retry?)` | `config.boundary.renderError(ctx, error, renderMode, retry?)` | Controller renderer wins, then application renderer, then normalized error text.                      |
+
+`renderMode` and `retry` are Controller-level options. They are not global `config.boundary` switches.
+
+## Choose block or inline structure
+
+Use the default `block` mode when the fallback is allowed to own a block-level region. Use `inline` when the fallback must remain valid phrasing content, for example inside a paragraph:
+
+```tsx
+<p>
+  Import status: <ZImportStatus />
+</p>
+```
+
+```ts
+static $componentOptions: IComponentOptions = {
+  boundary: {
+    renderMode: 'inline',
+  },
+};
+```
+
+`inline` is an HTML-structure requirement, not merely a visual choice. An application renderer receives the selected mode and must preserve suitable markup: current Basic and Start renderers use a `span` host for inline fallback output. Do not use a block-oriented renderer that inserts a `div` into phrasing-only content.
+
+## Provide application defaults
+
+Application configuration supplies the shared renderer contract:
+
+```ts
+import type { ZovaContext } from 'zova';
+import type { VNodeChild } from 'vue';
+
+config.boundary = {
+  loading: {
+    delay: 500,
+  },
+  renderLoading(ctx: ZovaContext, renderMode: 'block' | 'inline'): VNodeChild {
+    return null;
+  },
+  renderError(
+    ctx: ZovaContext,
+    error: unknown,
+    renderMode: 'block' | 'inline',
+    retry?: () => Promise<void>,
+  ): VNodeChild {
+    return null;
+  },
+};
+```
+
+The renderer decides the actual VNode, accessibility semantics, localization, and presentation. Keep customer-facing error text safe: an error fallback is not a substitute for error reporting, monitoring, or a deliberate disclosure policy.
+
+The `retry` callback is optional. It is absent when retry is disabled and remains unavailable until an enabled failed boundary has completed client hydration. A global renderer should render its retry control only when this callback is present.
+
+## Override rendering for one Controller
+
+A Controller can own its boundary presentation without changing application defaults:
+
+```tsx
+import type { VNodeChild } from 'vue';
+import type { TypeComponentBoundaryRenderMode } from 'zova';
+
+protected renderLoading(renderMode: TypeComponentBoundaryRenderMode): VNodeChild {
+  return <span role="status">Loading report ({renderMode})</span>;
+}
+
+protected renderError(
+  error: unknown,
+  renderMode: TypeComponentBoundaryRenderMode,
+  retry?: () => Promise<void>,
+): VNodeChild {
+  const message = error instanceof Error ? error.message : String(error);
+  return (
+    <span role="alert">
+      Report failed in {renderMode} mode: {message}
+      {retry && <button onClick={() => void retry()}>Retry</button>}
+    </span>
+  );
+}
+```
+
+A Controller renderer always takes precedence over the global renderer. Once it provides `renderError`, it owns the whole fallback output; Zova does not append the application retry button around it.
+
+The trailing callback was added compatibly. Existing error renderers that accept only `error`, or `error, renderMode`, remain valid. Add the optional third argument only when the Controller needs to surface retry itself.
+
+## Retry safely
+
+`retry: true` is intentionally opt-in. A retry does **not** call `__init__()` again on the failed Controller instance. Instead, Zova clears the prior load attempt, disposes the beans it owns, and creates a fresh Controller → Style → Render graph.
+
+Enable retry only when every relevant initialization effect is safe to perform again. Typical safe cases include a local read whose repeated execution is harmless, or a request with a defined idempotency/recovery contract. Do not enable it for initialization that can repeat a non-idempotent external effect without such a contract.
+
+The runtime also protects the interaction boundary:
+
+- only one retry attempt is active at a time; repeated clicks share that attempt;
+- retry is available only when `retry: true`, the host is still active, and the current state is an error;
+- it becomes interactive after client hydration, not in server HTML;
+- a successful retry restores the fresh Controller graph and normal ready rendering.
+
+## Error handling and SSR
+
+### Error routing
+
+A Controller-load failure is reported through the application error handler before Zova decides to show a local fallback. An application handler can mark the load error as handled; in that case, the Controller-load error fallback is not rendered.
+
+Treat a visible fallback and operational reporting as separate responsibilities. The default Basic renderer displays an error message, but production applications should decide which message is appropriate for the current audience and preserve diagnostic information through their normal error-handling path.
+
+### SSR and hydration
+
+For SSR, the sequence is designed to keep server HTML and the browser's first hydration output equivalent:
+
+1. server prefetch runs the Controller-load chain;
+2. an unhandled server fallback is captured as deferred SSR state;
+3. the browser replays that fallback during its initial hydration render, even if a new browser attempt could now succeed;
+4. after hydration, an enabled retry control can start a fresh client-side load graph.
+
+Do not render a retry affordance unconditionally in server output. The optional callback is the signal that it is interactive and available. Also distinguish a Controller-load fallback from SSR-wide handled control flow such as redirects or authentication handling; those can be handled without selecting this local fallback.
+
+For the larger render and handoff model, read [SSR Architecture Overview](/frontend/ssr-architecture-overview) and use [SSR Review Checklist](/frontend/ssr-review-checklist) when changing SSR-sensitive UI.
+
+## Shared contract, edition-specific defaults
+
+The Controller options, renderer signatures, renderer precedence, retry rules, and SSR behavior above are shared Zova behavior. The default application renderers are edition-specific implementation choices.
+
+| Surface                 | Cabloy Basic                                                      | Cabloy Start                                                              |
+| ----------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Global loading delay    | `500ms`                                                           | `500ms`                                                                   |
+| Block loading fallback  | Centered DaisyUI/Tailwind spinner in a `div` with `role="status"` | Centered Vuetify `VProgressCircular` in a flex `div` with `role="status"` |
+| Inline loading fallback | DaisyUI/Tailwind spinner in a `span` host                         | `VProgressCircular` in a `span` host                                      |
+| Block error fallback    | DaisyUI `alert alert-error` presentation                          | Tonal Vuetify `VAlert`                                                    |
+| Inline error fallback   | Inline error `span` presentation                                  | Inline Vuetify-oriented error and action presentation in a `span` host    |
+| Retry affordance        | DaisyUI ghost button                                              | Small text-variant `VBtn`                                                 |
+
+DaisyUI classes, Vuetify component names, spacing, and colors are not part of the shared Zova API. Keep shared Controller code UI-neutral where possible, then configure edition-local global renderers for the desired visual system.
+
+## Validate the behavior in Cabloy Basic
+
+Cabloy Basic includes a manual demonstration at:
+
+```text
+/demo/basic/controllerBoundary
+```
+
+Its source is in `zova/src/suite/a-demo/modules/demo-basic/src/page/controllerBoundary/controller.tsx`, with separate normal, inline, and Controller-override probes. The focused browser specification is `repo-e2e/specs/controller-boundary.spec.ts`.
+
+Together, those probes verify that:
+
+- fast initialization finishes without exposing delayed loading;
+- slow initialization exposes loading, then ready content;
+- an error fallback can expose and recover through retry;
+- inline fallback markup remains valid in phrasing content;
+- Controller overrides receive the render mode and retain legacy error-renderer compatibility;
+- a server-selected fallback survives as the initial hydration result, then can recover through a post-hydration retry.
+
+The demo and this focused E2E specification are Basic-specific evidence. Cabloy Start shares the Controller-load contract but uses its own Vuetify default presentation and should validate its own controller hosts accordingly.
+
+## Implementation checklist
+
+Before enabling a Controller-load boundary, check that:
+
+- [ ] the concern is initialization of a Controller, Style, or Render bean rather than later render/action/query work;
+- [ ] `inline` is selected whenever the fallback sits in phrasing-only content;
+- [ ] the application renderer handles both `block` and `inline` output safely and accessibly;
+- [ ] retry is enabled only for a replay-safe fresh load graph;
+- [ ] customer-facing error text is safe and operational details remain in the normal error path;
+- [ ] SSR fallback output remains compatible with hydration and relies on the optional retry callback;
+- [ ] UI-specific fallback code matches the active edition.
+
+Read [Component Guide](/frontend/component-guide) for the broader component model and [Cabloy Editions](/editions/overview) when choosing Basic or Start UI conventions.

package/repo-docs/frontend/introduction.md

@@ -65,6 +65,7 @@ Use this path when the task is page-oriented, route-oriented, or the first time
 - [Navigation Guards Guide](/frontend/navigation-guards-guide)
 - [Zova Router Under the Hood](/frontend/zova-router-under-the-hood)
 - [Router View Hosts Guide](/frontend/router-view-hosts-guide)
+- [Routed Dialog Guide](/frontend/routed-dialog-guide)
 - [Router Tabs Introduction](/frontend/router-tabs-introduction)
 - [Router Tabs Overview](/frontend/router-tabs-overview)
 - [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
@@ -79,13 +80,16 @@ Use this path when the task is page-oriented, route-oriented, or the first time
 Use this path when the task is about UI composition, component contracts, form or table architecture, form or table internals, form or table source reading, or theme work:
 
 - [Component Guide](/frontend/component-guide)
+- [Controller Load Boundary Guide](/frontend/controller-boundary-guide)
 - [Form Guide](/frontend/form-guide)
+- [Resource Picker Guide](/frontend/resource-picker-guide)
 - [Semantic Presentation Contract](/fullstack/semantic-presentation-contract)
 - [Form Layout Guide](/frontend/form-layout-guide)
 - [Image Guide](/frontend/image-guide)
 - [Zova Form Under the Hood](/frontend/zova-form-under-the-hood)
 - [Zova Form Source Reading Map](/frontend/zova-form-source-reading-map)
 - [Table Guide](/frontend/table-guide)
+- [Column Configuration Guide](/frontend/column-configuration-guide)
 - [TableCell Authoring Cookbook](/frontend/table-cell-cookbook)
 - [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook)
 - [Zova Table Under the Hood](/frontend/zova-table-under-the-hood)

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

@@ -72,6 +72,12 @@ Choose `meta.ssrProfile` from the page's rendering contract. Use `session` when
 
 This is one reason route records matter so much: they are not just URL declarations. They are an application-behavior surface.
 
+## Route records inside routed dialogs
+
+An ordinary page route can also be the target of a [Routed Dialog](/frontend/routed-dialog-guide). The route still follows the rules on this page: dynamic params require `name`, static routes normally remain unnamed, and generated `$params` / `$query` schemas continue to apply.
+
+The difference is hosting rather than route declaration. A routed dialog runs the target through its own local memory-history router, so navigation inside the dialog does not change the main browser URL or route. Do not infer that every routed-dialog target is a suitable direct browser entry: a feature-specific target may require a page-host contract supplied only by its routed-dialog workflow.
+
 ## Route -> shell -> routed page
 
 A useful frontend mental model is:

package/repo-docs/frontend/resource-picker-guide.md

@@ -0,0 +1,223 @@
+# Resource Picker Guide
+
+Use a Resource Picker when a form field stores the identity of an existing resource, such as a Student, Product, or Role. The picker is schema-driven: declare the field renderer in backend entity or DTO metadata, and the active Cabloy edition renders the appropriate frontend control.
+
+Use this page together with:
+
+- [Form Guide](/frontend/form-guide)
+- [API Schema Guide](/frontend/api-schema-guide)
+- [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+- [Routed Dialog Guide](/frontend/routed-dialog-guide)
+- [TableCell Authoring Cookbook](/frontend/table-cell-cookbook)
+
+> [!TIP]
+> A Resource Picker is a resource-field renderer, not a standalone client-side component API. The backend contract remains the source of truth for the field, its target resource, its selectable rows, and its display data.
+
+## What a Resource Picker stores
+
+A picker field persists an identity, not the whole selected row:
+
+- `single` selection stores one ID;
+- `multiple` selection stores an ID array;
+- related objects are response-only display projections used to show labels.
+
+For example, a Training Record can persist `studentId` while its select and view responses include a narrow `student` relation with the Student ID and display name. Do not replace the ID write contract with a submitted Student object merely because the UI displays a Student label.
+
+## Prerequisites
+
+Before adding a picker, verify the target resource has all of the following:
+
+1. A valid resource name and a selectable resource API that the current user may access.
+2. Select results with stable, nonempty row IDs.
+3. A label field such as `name`, or a configured alternative such as `title` or `code`.
+4. For `routedDialog` mode, select-schema blocks that produce the target resource's normal list experience, such as filter, table, and pager blocks.
+5. A response-only relation projection for labels when the editing, readonly, or list experience needs to display the selected resource after loading.
+
+The target resource's server-side authorization, instance scope, filtering, and validation remain authoritative. A client-side `query`, `actionPath`, or picker field does not authorize a user to select a row.
+
+## Declare the field renderer
+
+Declare the field renderer on the persisted identity field with `ZovaRender.field(...)`. Add a matching cell renderer when a resource list should display the relation label instead of a raw ID.
+
+### Cabloy Basic
+
+```ts
+@Api.field(
+  v.title($locale('Student')),
+  ZovaRender.field('basic-resource:formFieldResourcePicker', {
+    resource: $resourceName('training-student:student'),
+    pickerMode: 'routedDialog',
+    selectionMode: 'single',
+  }),
+  ZovaRender.cell('basic-resource:resourcePicker', {
+    resource: $resourceName('training-student:student'),
+  }),
+  v.tableIdentity(),
+)
+studentId: TableIdentity;
+```
+
+### Cabloy Start
+
+Use the same business contract, but use Start's renderer identities:
+
+```ts
+@Api.field(
+  v.title($locale('Student')),
+  ZovaRender.field('start-resource:formFieldResourcePicker', {
+    resource: $resourceName('training-student:student'),
+    pickerMode: 'routedDialog',
+    selectionMode: 'single',
+  }),
+  ZovaRender.cell('start-resource:resourcePicker', {
+    resource: $resourceName('training-student:student'),
+  }),
+  v.tableIdentity(),
+)
+studentId: TableIdentity;
+```
+
+The two renderer names are edition-specific. Do not use `basic-resource:*` names in Start, or `start-resource:*` names in Basic.
+
+> [!IMPORTANT]
+> The `resourcePicker` **cell** renderer is presentation-only. It reads related display data already returned in the list row; it does not open a picker and it does not fetch a missing label.
+
+## Field options
+
+The form-field renderer supports the following public metadata options.
+
+| Option          | Applies to               | Meaning                                                                                                                                                                             |
+| --------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `resource`      | both modes               | Required target resource name. The type currently marks it optional, but the renderer throws if it is missing.                                                                      |
+| `actionPath`    | both modes               | Optional target-resource select action. Use it when the resource exposes a dedicated selection endpoint.                                                                            |
+| `query`         | both modes               | Optional fixed list query. In dialog mode it is supplied to the picker list; it does not replace server-side scope or authorization.                                                |
+| `relationName`  | labels                   | Response relation used to present selected labels. When omitted, the renderer can derive a relation name from a field ending in `Id`; specify it explicitly for exceptions.         |
+| `selectOptions` | inline select and labels | Edition-native select options, including `itemValue` and `itemTitle`. The default mapping is `id` and `name`; use another `itemTitle`, such as `title` or `code`, when appropriate. |
+| `pickerMode`    | interaction              | `'select'` by default, or `'routedDialog'` for the hosted resource-list picker.                                                                                                     |
+| `selectionMode` | routed dialog            | `'single'` by default, or `'multiple'`.                                                                                                                                             |
+| `selectionMax`  | routed dialog            | Maximum selected identities. Single mode is always limited to one. Multiple mode currently defaults to 100 when no valid nonnegative integer limit is supplied.                     |
+
+Cabloy Start also provides Vuetify presentation options for this field, including `display`, `chipGroupOptions`, and `chipOptions`. Use them only in Start-specific metadata; they are not shared Basic options.
+
+## Choose an interaction mode
+
+### Inline select: the default
+
+When `pickerMode` is omitted, the field loads the target `ModelResource` through its select query and renders an inline select. Use this for a small, readily available option set.
+
+```ts
+ZovaRender.field('basic-resource:formFieldResourcePicker', {
+  resource: $resourceName('commerce-catalog:category'),
+  selectOptions: {
+    itemValue: 'id',
+    itemTitle: 'name',
+  },
+});
+```
+
+`actionPath` and `query` affect the target select request. `selectionMode` and `selectionMax` are routed-dialog controls; do not use them to assume an inline select will enforce a dialog-style selection policy.
+
+### Routed dialog: searchable resource-list selection
+
+Use `pickerMode: 'routedDialog'` when the user needs the target resource's table-based selection experience, including its existing filters, pager, list actions, fixed query, or controlled multi-selection.
+
+```ts
+ZovaRender.field('basic-resource:formFieldResourcePicker', {
+  resource: $resourceName('training-student:student'),
+  pickerMode: 'routedDialog',
+  selectionMode: 'single',
+});
+```
+
+The routed picker reuses the target resource's schema-authored select blocks instead of maintaining a second hard-coded list. It opens the named `rest-resource:resourcePicker` route inside a routed-dialog host.
+
+> [!WARNING]
+> `rest-resource:resourcePicker` is not a standalone browser page or a direct navigation API. Its page controller requires a host-scoped picker contract supplied by the field/dialog workflow. Do not link users directly to `/rest/resource/:resource/picker`, treat it as bookmarkable state, or build application behavior around entering that route without its host.
+
+## Selection result and limits
+
+When the user confirms a routed picker:
+
+- `single` writes the first selected ID;
+- `multiple` writes a capped array of selected IDs;
+- null, undefined, and empty IDs are discarded;
+- duplicate IDs are collapsed while preserving the original ID value type;
+- the dialog requires a valid nonempty selection to enable confirmation.
+
+Single mode always has an effective maximum of one. For multiple mode, a missing or invalid limit currently becomes 100. A maximum of `0` prevents confirmation; it is not a useful way to request a deliberate empty result.
+
+The picker keeps selection across list pages, filters, and sorting within the dialog. Its returned row snapshots are useful presentation data, but the saved field value remains IDs.
+
+## Persisted IDs and display relations
+
+A good picker contract separates writing from presentation:
+
+```ts
+// Write data
+studentId: TableIdentity;
+
+// Response-only display projection
+student?: {
+  id: TableIdentity;
+  name: string;
+};
+```
+
+The exact DTO form may differ, but the rule stays the same:
+
+- send and persist `studentId`;
+- return a narrow `student` relation for labels;
+- use `relationName` if the relation does not follow the normal `...Id` naming convention;
+- align the relation's title property with `selectOptions.itemTitle`.
+
+After routed selection, the field can synchronize selected display data and may hydrate a missing label through the target resource. That behavior improves the immediate UI, but it is not a replacement for a correct view/select response projection. Readonly fields and list cells should receive the labels they need from the server response.
+
+## Readonly fields and table cells
+
+A Resource Picker field is interactive only in an editable form. In readonly mode it displays a relation-backed label instead of a chooser.
+
+The paired `resourcePicker` table cell is also noninteractive. It formats relation data already attached to the table row. In particular:
+
+- it does not fetch a related row;
+- it does not open a dialog;
+- missing display projection data can leave the cell without a useful label.
+
+Use a relation projection deliberately rather than relying on a raw foreign-key ID to become readable presentation data.
+
+## Routed-dialog lifecycle and SSR
+
+A routed picker starts with the field's current IDs as its selection. On confirmation, it updates the field; on Cancel or an ordinary close, its result is `undefined` and the form keeps its prior value.
+
+The routed dialog has its own in-memory route history. Opening, navigating inside, or closing it does not change the outer browser URL. It therefore is not appropriate for a flow that must be bookmarkable or survive a browser reload.
+
+Routed dialogs are client-only. Open them from an interaction such as a button click, or defer lifecycle-driven behavior to an explicit post-hydration client boundary. Do not open a routed dialog from SSR execution merely because the surrounding page supports SSR. For the general lifecycle and presentation contract, see [Routed Dialog Guide](/frontend/routed-dialog-guide).
+
+## Basic and Start UI differences
+
+The resource/data contract is shared, but the visual implementation is deliberately edition-specific.
+
+| Surface                              | Cabloy Basic                                         | Cabloy Start                                 |
+| ------------------------------------ | ---------------------------------------------------- | -------------------------------------------- |
+| Inline field                         | `ZSelect` with Basic's DaisyUI-oriented presentation | Vuetify `VSelect`                            |
+| Optional selected-value presentation | Standard Basic field presentation                    | Can use Start's Vuetify chip-display options |
+| Routed picker trigger and actions    | Basic/DaisyUI-oriented controls                      | Vuetify controls                             |
+| Routed single selection              | Radio control                                        | Checkbox selection surface                   |
+| Renderer identities                  | `basic-resource:*`                                   | `start-resource:*`                           |
+
+Treat these as UI differences only. They do not change the core persistence rule, resource-owner data ownership, or server authorization boundary.
+
+## Authoring checklist
+
+Before shipping a Resource Picker, check the following:
+
+- [ ] The field persists a stable identity or identity array.
+- [ ] `resource` names the intended target resource.
+- [ ] The target select API returns stable IDs and the configured title property.
+- [ ] The target resource's select schema contains the list blocks needed by dialog mode.
+- [ ] `actionPath` and `query` express only the desired selection view; server-side scope and authorization still enforce access.
+- [ ] The response DTO supplies a narrow relation projection for editable, readonly, and table-label presentation.
+- [ ] `relationName` and `selectOptions.itemTitle` match the returned projection when defaults do not.
+- [ ] The field and table-cell renderer names match the active edition.
+- [ ] The selected IDs, labels, cancellation behavior, and authorization rules are covered by a targeted test or end-to-end scenario.
+
+The Training Record → Student picker is covered by existing end-to-end scenarios in both Cabloy Basic and Cabloy Start. Use that flow as the reference specimen when verifying an equivalent picker in your own resource.

package/repo-docs/frontend/rest-resource-source-reading-map.md

@@ -53,9 +53,9 @@ It is also a **route-to-page-shell-to-block-to-model bridge** for resource-drive
 
 If you only remember one mental model, remember this one:
 
-1. `routes.ts` chooses one of three resource-oriented pages
+1. `routes.ts` declares three ordinary resource workspace routes and one host-dependent picker route
 2. generated `ZPage*` wrappers bind those route entries to page controllers
-3. the page controllers resolve the current `resource`, `id`, and `formScene`
+3. the ordinary page controllers resolve the current `resource`, `id`, and `formScene`, while the picker controller also requires its host-scoped picker contract
 4. the page controllers load top-level schema metadata and render `rest.blocks`
 5. those rendered blocks usually enter generic Basic runtimes such as `basic-page:blockPage` or `basic-pageentry:blockPageEntry`
 6. those downstream runtimes resolve the same selector-backed `ModelResource` instance again
@@ -65,7 +65,7 @@ A compact relationship map is:
 
 ```text
 routes.ts
-  └─ ZPageResource / ZPageEntry / ZPageEntryCreate
+  └─ ZPageResource / ZPageEntry / ZPageEntryCreate / ZPageResourcePicker
        └─ page controller shell
             └─ schema rest.blocks
                  └─ generic Basic blocks
@@ -73,6 +73,8 @@ routes.ts
                            └─ OpenAPI bootstrap / fetch / mutation / invalidation
 ```
 
+The picker route is intentionally different from an ordinary workspace page: it consumes an injected host contract and is normally entered through a routed dialog. For its public authoring contract, see [Resource Picker Guide](/frontend/resource-picker-guide).
+
 That is why `rest-resource` should not be read as “one page that does CRUD directly”.
 
 The Zova-native meaning is:
@@ -89,14 +91,16 @@ When you want the shortest correct reading order, use this sequence:
 2. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/.metadata/page/resource.ts`
 3. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/.metadata/page/entry.ts`
 4. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/.metadata/page/entryCreate.ts`
-5. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/resource/controller.tsx`
-6. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/entry/controller.tsx`
-7. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/entryCreate/controller.tsx`
-8. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/model/resource.ts`
-9. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx`
-10. `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockPageEntry/controller.tsx`
-11. `zova/src/suite/cabloy-basic/modules/basic-commands/src/bean/command.delete.tsx`
-12. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/.metadata/index.ts`
+5. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/.metadata/page/resourcePicker.ts`
+6. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/resource/controller.tsx`
+7. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/entry/controller.tsx`
+8. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/entryCreate/controller.tsx`
+9. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/resourcePicker/controller.tsx`
+10. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/model/resource.ts`
+11. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx`
+12. `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockPageEntry/controller.tsx`
+13. `zova/src/suite/cabloy-basic/modules/basic-commands/src/bean/command.delete.tsx`
+14. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/.metadata/index.ts`
 
 A compact role map is:
 
@@ -105,6 +109,7 @@ A compact role map is:
 - `page/resource/controller.tsx` shows the list-page shell
 - `page/entry/controller.tsx` shows the entry-page shell
 - `page/entryCreate/controller.tsx` shows virtual create-page reuse
+- `page/resourcePicker/controller.tsx` shows the host-dependent picker shell
 - `model/resource.ts` shows the resource-owner core
 - `basic-page:blockPage` shows the deeper list runtime
 - `basic-pageentry:blockPageEntry` shows the deeper form runtime
@@ -117,31 +122,30 @@ Start with:
 
 - `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/routes.ts`
 
-This file declares three routes:
+This file declares four routes:
 
 - `:resource`
 - `:resource/create`
 - `:resource/:id/:formScene?`
+- `:resource/picker`
 
-That already tells you the module’s public role.
-
-It is not tied to one concrete resource such as Student or Product.
+The first three are ordinary resource workspace routes. The fourth is the host-dependent Resource Picker route; it is normally rendered by a routed-dialog workflow, not entered as a direct browser destination. See [Resource Picker Guide](/frontend/resource-picker-guide) for the public authoring contract.
 
-Instead, it is a generic route module whose runtime identity comes from `route.params.resource`.
+The module is not tied to one concrete resource such as Student or Product. Its runtime identity comes from `route.params.resource`.
 
 ### Why `tabKey` matters
 
-All three routes use the same `tabKey(route)` shape:
+The list, create, and entry routes use the same `tabKey(route)` shape:
 
 ```typescript
 `/rest/resource/${encodeURIComponent(route.params.resource)}`;
 ```
 
-This means the tab identity is resource-level rather than row-level.
+This means their workspace identity is resource-level rather than row-level. The picker route deliberately does not use that shared workspace identity: its controller requires the host-scoped picker contract that its routed-dialog caller provides.
 
 If your next question becomes specifically how the entry route becomes a working page through `basic-pageentry`, continue with [Resource Entry Page Deep Dive](/frontend/resource-entry-page-deep-dive).
 
-So these views are grouped under one resource-oriented tab boundary:
+The ordinary workspace views are grouped under one resource-oriented tab boundary:
 
 - resource list
 - create entry
@@ -172,6 +176,7 @@ Instead, each route enters the normal Zova page-controller path through:
 - `createZovaComponentPage(ControllerPageResource, ...)`
 - `createZovaComponentPage(ControllerPageEntry, ...)`
 - `createZovaComponentPage(ControllerPageEntryCreate, ...)`
+- `createZovaComponentPage(ControllerPageResourcePicker, ...)`
 
 These files also expose the typed Zod-based params schema for each page.
 
@@ -184,8 +189,8 @@ After the page wrappers, read:
 This generated file is mostly not “business logic”, but it is still the best summary of the module’s registered surfaces:
 
 - `rest-resource.model.resource` → model bean full name
-- `rest-resource.controller.pageResource` / `pageEntry` / `pageEntryCreate` → controller registrations
-- page-path and page-name typing for `/rest/resource/...`
+- `rest-resource.controller.pageResource` / `pageEntry` / `pageEntryCreate` / `pageResourcePicker` → controller registrations
+- page-path and page-name typing for `/rest/resource/...`, including the hosted picker route
 - module scope typing for `rest-resource`
 
 Use this file as the **registry map**, not as the first place to learn the runtime behavior.
@@ -266,6 +271,16 @@ Instead, the create route reuses the entry shell and lets route params plus form
 
 This is a good example of Zova keeping page identity separate from duplicated controller logic.
 
+### 3.4 Resource Picker shell is host-dependent
+
+Read:
+
+- `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/resourcePicker/controller.tsx`
+
+This controller resolves the selector-backed target resource and its select schema, then renders the schema's list blocks through a picker page host. Unlike the ordinary list and entry shells, it requires an injected host contract whose resource must match the route parameter. The host adapts the resource's existing list blocks for selection and supplies the confirm/cancel workflow.
+
+That makes the picker route an internal routed-dialog workflow page, not a direct browser-entry CRUD page. For the supported field metadata and result contract, continue with [Resource Picker Guide](/frontend/resource-picker-guide).
+
 ## 4. `ModelResource` is the owner core, not only a helper
 
 Read:
@@ -384,6 +399,7 @@ These are the main runtime logic files:
 - `src/page/resource/controller.tsx`
 - `src/page/entry/controller.tsx`
 - `src/page/entryCreate/controller.tsx`
+- `src/page/resourcePicker/controller.tsx`
 - `src/model/resource.ts`
 
 These are where the real behavior decisions live.