@jskit-ai/agent-docs 0.1.53 → 0.1.55

package/guide/agent/generators/advanced-cruds.md

@@ -454,7 +454,8 @@ This is the list-page container.
 Its job is usually to:
 
 - call `useCrudListScreen()`
-- pass page-local `listFilters` and `listBulkActions`
+- pass page-local `listFilters`, `listBulkActions`, and `listRowActions` when needed
+- pass `syntheticRows` when the page needs non-CRUD display rows such as an owner/master row
 - render the shared `CrudListScreen`
 - resolve list/view/edit/new URLs
 - pass route query state through when navigating deeper
@@ -470,6 +471,8 @@ Its job is usually to:
 - call `useCrudViewScreen()`
 - render the shared `CrudViewScreen`
 - resolve "back" and "edit" navigation
+- pass read options such as `requestQueryParams`, `readEnabled`, and `queryKeyFactory` when the detail read needs them
+- use the shared view slots for page-specific sections around the generated field list
 
 Again, the runtime behavior is mostly uphill. The page is a route-level composition layer.
 
@@ -822,6 +825,8 @@ Use this rule of thumb when deciding where to edit:
 | Change SQL, joins, parent filters, or advanced search | `repository.js` | This is the data-access layer |
 | Add cross-record or domain rules on save/delete | `service.js` | This is business logic |
 | Change shared CRUD screen chrome, load states, or retry behavior | `users-web` shared screen components | Generated pages consume the shared screen contract |
+| Add per-row commands to a generated list page | page-local `listRowActions.js`, usually calling `useCommand()`-backed composables | The shared list screen renders action chrome; the page owns explicit mutation behavior |
+| Add non-CRUD display rows to a generated list page | route page `syntheticRows` input | Synthetic rows are presentation rows, not repository records |
 | Change page-specific display behavior | the route pages, generated slots, and app-owned composables | This is presentation |
 | Change form field layout and inputs | `_components/CrudAddEditForm.vue` and `CrudAddEditFormFields.js` | This is the generated form field layer |
 
@@ -832,6 +837,7 @@ The baseline generator output is only the start. As the tutorial's `contacts`, `
 - `src/server/listQueryValidators.js` when a list needs extra query filters beyond `q`
 - `src/server/service.test.js` once save/delete rules stop being trivial
 - `packages/contacts/src/shared/contactListFilters.js` when the contacts CRUD gains structured list filters that both server and client should share
+- `src/pages/.../contacts/listRowActions.js` when a generated list needs row-level commands such as Delete, Block, or Unblock
 - `src/composables/addresses/useAddressDisplay.js` when addresses need app-specific display formatting
 - `src/composables/comments/useCommentsListRuntime.js` when an embedded comments list needs local UI state
 
@@ -840,6 +846,55 @@ That is the right direction of growth:
 - server customizations stay in the CRUD package
 - presentation and page-specific UI state stay in app-owned client files
 - shared structured list filters live best in a CRUD-package shared module that both server and client can import
+- shared generated screen chrome stays in `users-web`; adapted pages feed it definitions, slots, and explicit command handlers
+
+### Detail read options and extension slots
+
+Use the shared detail screen first, even when the detail page needs includes or domain sections.
+
+`useCrudViewScreen(...)` accepts the same read-pass-through options that adapted detail pages usually need:
+
+- `requestQueryParams`
+- `readEnabled`
+- `queryKeyFactory`
+
+For example:
+
+```js
+const screen = useCrudViewScreen({
+  resource: drumResource,
+  apiUrlTemplate: "/drums/:recordId",
+  requestQueryParams() {
+    return {
+      include: "drumSpecId,locationId,contents,contents.processingLotId"
+    };
+  }
+});
+```
+
+Render domain sections through `CrudViewScreen` slots instead of replacing the shared load/error/retry chrome:
+
+```vue
+<CrudViewScreen :screen="screen" resource-singular-title="Drum">
+  <template #before-fields="{ view }">
+    <DrumArrivalSummary :drum="view.record" />
+  </template>
+
+  <template #fields="{ view }">
+    <GeneratedDrumFields :record="view.record" />
+  </template>
+
+  <template #after-fields="{ view }">
+    <DrumProvenancePanel :drum="view.record" />
+  </template>
+
+  <template #supporting-content="{ view }">
+    <DrumContentsPanel :drum="view.record" />
+  </template>
+</CrudViewScreen>
+```
+
+The screen still owns loading, not-found, retry, title, back/edit actions, and responsive shell structure. The page owns only the domain panels.
 
 ## Search and filters: the deep dive
 
@@ -948,6 +1003,7 @@ In JSKIT CRUD:
 - the schema defines the API contract
 - field definitions may also carry storage/lookup/ui metadata
 - the repository runtime owns computed SQL projections
+- internal JSON REST resources can expose SQL-selected query projections through `createJsonRestResourceScopeOptions(...)`
 
 Use these rules:
 
@@ -1018,7 +1074,31 @@ const repositoryRuntime = createCrudResourceRuntime(resource, {
 });
 ```
 
-Once registered there:
+For JSON REST-backed generated CRUD packages, keep the output field virtual in the resource and register the SQL projection at the JSON REST resource boundary:
+
+```js
+await addResourceIfMissing(
+  api,
+  "receivals",
+  createJsonRestResourceScopeOptions(resource, {
+    queryFields: {
+      remainingBatchWeight: {
+        type: "number",
+        select({ knex, column }) {
+          return knex.raw("?? - coalesce(??, 0)", [
+            column("received_weight"),
+            column("processed_weight")
+          ]);
+        }
+      }
+    }
+  })
+);
+```
+
+`createJsonRestResourceScopeOptions(...)` moves matching virtual fields out of the storage schema and into JSON REST `queryFields`, where they are selected for reads and ignored for writes. Prefer the `queryFields` option when the resource module is imported by both server and client code; use `storage.queryProjection` only in server-only resource modules.
+
+For the repository runtime, once registered there:
 
 - generic CRUD `list`
 - generic CRUD `findById`
@@ -1121,19 +1201,106 @@ The generated runtime passes action handlers:
 
 Keep bulk action definitions page-local unless another page needs to share them.
 
+### Pattern 3C: row actions and synthetic display rows
+
+Generated CRUD list pages can keep the shared list screen while adding per-row actions and non-CRUD display rows.
+
+Use row actions for explicit commands on one record. JSKIT renders the action menu in card and table layouts, tracks per-row execution state, and passes the handler enough context to run app-owned commands. It does not invent or auto-replay writes.
+
+For example:
+
+```js
+import { defineCrudListRowActions } from "@jskit-ai/users-web/client/rowActions";
+
+const listRowActions = defineCrudListRowActions([
+  {
+    key: "delete",
+    label: "Delete",
+    color: "error",
+    visible: ({ record }) => record.isOwnerRow !== true,
+    disabled: ({ record }) => record.isOwnerRow === true,
+    loading: ({ record }) => deleteCommand.isRunningFor(record.id),
+    async run({ record, reload }) {
+      await deleteCommand.runFor(record);
+      await reload();
+    }
+  }
+]);
+
+export { listRowActions };
+```
+
+Pass the actions into the generated list screen:
+
+```js
+import { listRowActions } from "./listRowActions.js";
+
+const screen = useCrudListScreen({
+  resource: uiResource,
+  apiSuffix: "/allowed-login-emails",
+  listRowActions
+});
+```
+
+The row-action handler receives:
+
+- `action`
+- `record`
+- `index`
+- `recordId`
+- `records`
+- `reload`
+
+Use `syntheticRows` when the page needs display rows that do not come from the CRUD list response, such as an owner row at the top of an allowlist. An array is prepended by default. Use `{ prepend, append }` when placement matters.
+
+```js
+const ownerRows = computed(() => owner.value
+  ? [
+      {
+        key: "owner",
+        record: {
+          id: owner.value.id,
+          email: owner.value.email,
+          role: "Owner",
+          isOwnerRow: true
+        }
+      }
+    ]
+  : []);
+
+const screen = useCrudListScreen({
+  resource: uiResource,
+  apiSuffix: "/allowed-login-emails",
+  listRowActions,
+  syntheticRows: ownerRows
+});
+```
+
+Synthetic rows:
+
+- render in the same card/table layouts as real rows
+- do not get standard Open/Edit CRUD navigation
+- are excluded from bulk selection by default
+- can still participate in row-action visibility/disabled logic
+
+Use this seam for display rows only. If a row should be persisted, it should come from the CRUD list response.
+
 #### Exact file checklist
 
 For a generated CRUD, treat this as the concrete file plan:
 
 - edit `src/pages/.../contacts/listFilters.js`
-- make sure the matching server route/action/repository code already accepts and applies the declared query params
+- create `src/pages/.../contacts/listRowActions.js` when the list needs row-level commands
+- make sure the matching server route/action/repository code accepts and applies the declared query params when filters are server-backed
 
 If the filter contract should be shared with server code, promote it into a CRUD package module and import it from both sides:
 
 - create `packages/contacts/src/shared/contactListFilters.js`
-- update `packages/contacts/src/server/registerRoutes.js` so the list route query validator lists structured filter params explicitly with `createCrudListFilterQueryField(...)`, unless you already extracted list-query composition into `packages/contacts/src/server/listQueryValidators.js`
-- update `packages/contacts/src/server/actions.js` so the list action input validator includes that same explicit contract choice
-- update `packages/contacts/src/server/repository.js` so the list query path builds the `createCrudListFilters(...)` runtime and calls `applyQuery(...)`
+- create `packages/contacts/src/server/contactListFilterContract.js` with `createCrudListFilterContract(...)`
+- update `packages/contacts/src/server/registerRoutes.js` so the list route query validator includes `contactListFilterContract.queryValidator`
+- update `packages/contacts/src/server/actions.js` so the list action input validator includes the same `queryValidator`
+- update the provider's `createJsonRestResourceScopeOptions(...)` call so it merges `searchSchema: contactListFilterContract.jsonRestSearchSchema`
+- update `packages/contacts/src/server/repository.js` so the list query path passes `contactListFilterContract.toJsonRestQuery(query)` into `buildJsonRestQueryParams(...)`
 
 #### Client side
 
@@ -1231,101 +1398,105 @@ Use `mode: "merge"` when a preset should only change one filter group, such as t
 
 #### Server side
 
-Build the server runtime from the same shared definitions:
+Build the server contract from the same shared definitions:
 
 ```js
-const contactsListFiltersRuntime = createCrudListFilters(
+import { createCrudListFilterContract } from "@jskit-ai/crud-core/server/listFilters";
+import { CONTACTS_LIST_FILTER_DEFINITIONS } from "../shared/contactListFilters.js";
+
+const contactListFilterContract = createCrudListFilterContract(
   CONTACTS_LIST_FILTER_DEFINITIONS,
   {
     columns: {
-      onlyStaff: "is_staff",
-      onlyVip: "vip",
+      status: "status",
+      supplierContactId: "supplier_contact_id",
+      arrivalDate: "arrival_datetime",
       onlyArchived: "archived"
-    }
+    },
+    invalidValues: "reject"
   }
 );
-```
-
-There is no default query-validator mode or route-runtime alias. Keep the filter runtime for repository semantics, but author route/action query params explicitly.
 
-Strict contract example:
-
-```js
-const contactsListFilters = CONTACTS_LIST_FILTER_DEFINITIONS;
-
-const contactsListFiltersQueryValidator = {
-  schema: createCrudListFilterQuerySchema({
-    status: createCrudListFilterQueryField(contactsListFilters.status, {
-      invalidValues: "reject"
-    }),
-    arrivalDate: createCrudListFilterQueryField(contactsListFilters.arrivalDate, {
-      invalidValues: "reject"
-    })
-  }),
-  mode: "patch"
-};
+export { contactListFilterContract };
 ```
 
-Lenient contract example:
+That one contract gives the server:
 
-```js
-const contactsListFiltersQueryValidator = {
-  schema: createCrudListFilterQuerySchema({
-    status: createCrudListFilterQueryField(CONTACTS_LIST_FILTER_DEFINITIONS.status, {
-      invalidValues: "discard"
-    }),
-    arrivalDate: createCrudListFilterQueryField(CONTACTS_LIST_FILTER_DEFINITIONS.arrivalDate, {
-      invalidValues: "discard"
-    })
-  }),
-  mode: "patch"
-};
-```
+- `queryValidator` for route/action input validation
+- `jsonRestSearchSchema` for JSON REST resource registration
+- `toJsonRestQuery(query)` for repository query normalization
+- `applyQuery(...)` when a non-JSON REST repository still needs direct Knex filtering
 
-Wire the explicit query contract into the list validator and the repository:
+Wire the contract into route and action validators:
 
 ```js
 const listRouteQueryValidator = composeSchemaDefinitions([
   listCursorPaginationQueryValidator,
   listSearchQueryValidator,
-  contactsListFiltersQueryValidator,
   listParentFilterQueryValidator,
+  contactListFilterContract.queryValidator,
   lookupIncludeQueryValidator
 ], {
   mode: "patch"
 });
 ```
 
-Use that same explicit `contactsListFiltersQueryValidator` anywhere else the list query is validated, such as the composed list action input validator if your CRUD package validates query shape at both the route and action boundaries.
+Use the same `contactListFilterContract.queryValidator` anywhere else the list query is validated, such as the composed list action input validator if your CRUD package validates query shape at both the route and action boundaries.
+
+Merge the JSON REST search schema when the provider registers the resource:
+
+```js
+await addResourceIfMissing(
+  api,
+  JSON_REST_SCOPE_NAME,
+  createJsonRestResourceScopeOptions(resource, {
+    searchSchema: contactListFilterContract.jsonRestSearchSchema,
+    writeSerializers: {
+      "datetime-utc": toDatabaseDateTimeUtc
+    }
+  })
+);
+```
+
+Normalize the list query before building JSON REST query params:
+
+```js
+async function queryDocuments(query = {}, options = {}) {
+  return api.resources.contacts.query(
+    {
+      queryParams: buildJsonRestQueryParams(
+        JSON_REST_SCOPE_NAME,
+        contactListFilterContract.toJsonRestQuery(query)
+      ),
+      transaction: options?.trx || null,
+      simplified: false
+    },
+    createJsonRestContext(options?.context || null)
+  );
+}
+```
+
+`enumMany` and `recordIdMany` filters stay arrays. Date and number ranges become internal JSON REST search keys, so callers keep one public query key such as `arrivalDate` while the backend receives precise lower/upper filter operations.
 
 Choose the invalid-value contract deliberately:
 
-- there is no default mode and no fallback alias, so every structured filter field must choose `invalidValues: "reject"` or `invalidValues: "discard"` explicitly
+- `createCrudListFilterContract(...)` defaults to `invalidValues: "reject"` for a strict server boundary
+- set `invalidValues` explicitly when a package is choosing a non-default validation posture
 - use `invalidValues: "reject"` when malformed filter values should fail validation and produce a 400-style contract error
 - use `invalidValues: "discard"` when malformed filter values should be ignored and normalization should drop them
 - route query validation runs before auth, so this choice changes whether malformed unauthenticated requests fail at validation or fall through to auth
 - for normal HTTP CRUD handlers, route-level `discard` means the handler receives already-parsed filter values for the explicit fields you listed, so the action layer will not see those discarded bad values again later
-- the filter runtime is still a deliberate two-phase exception: schema parsing owns query-field values, then `applyQuery(...)` maps those parsed values back through filter keys and SQL semantics
-
-```js
-async function list(query = {}, callOptions = {}) {
-  return crudRepositoryList(repositoryRuntime, knex, query, options, callOptions, {
-    modifyQuery(dbQuery, context = {}) {
-      return contactsListFiltersRuntime.applyQuery(dbQuery, context.query || {});
-    }
-  });
-}
-```
+- the filter contract is still a deliberate two-phase exception: schema parsing owns public query-field values, then `toJsonRestQuery(...)` maps those parsed values to JSON REST filter keys and SQL semantics
 
 #### Best practices
 
 - Keep client-only filters in the generated page-local `listFilters.js`. Move definitions into a CRUD package only when server code or another page needs to share them.
 - Keep the filter keys identical all the way through: definition key, query param key, and repository meaning.
-- Prefer `createCrudListFilterQueryField(...)` plus `createCrudListFilterQuerySchema(...)` at route/action boundaries so accepted structured-filter params stay visible in app code.
+- Prefer `createCrudListFilterContract(...)` for server-backed structured filters so route/action validators, JSON REST search schema, and repository query normalization stay derived from one shared definition.
 - Use `type: "presence"` for null/not-null filters such as assigned vs unassigned storage. Do not model those as custom enums plus `applyQuery(...)` overrides unless the SQL semantics are genuinely different from `whereNotNull(...)` / `whereNull(...)`.
-- Use `createCrudListFilters(...)` unless the list semantics are truly unusual.
+- Use `createCrudListFilters(...)` directly only for non-JSON REST repository code that needs direct Knex filtering without JSON REST registration.
 - Use `q` for free-text and explicit query params for structured filters.
-- Run `jskit doctor` after wiring filters. It flags inline filter-definition objects passed into `useCrudListFilters(...)` or `createCrudListFilters(...)`.
+- Run `jskit doctor` after wiring filters.
 
 ### Pattern 4: lookup-backed structured filters
 
@@ -1456,7 +1627,7 @@ The runtime already handles both together.
 
 #### Server side
 
-Let the generic list search handle `q`, and let your custom validator/repository code handle the structured filters.
+Let the generic list search handle `q`, and let `createCrudListFilterContract(...)` handle the structured route/action validators, JSON REST search schema, and repository query normalization.
 
 #### Best practices
 
@@ -1612,8 +1783,10 @@ Use `scaffold-field` when it fits, then review the generated result. It patches
 Touch:
 
 - `packages/<crud>/src/shared/<crud>ListFilters.js` and make it the only authored filter-definition module
-- `packages/<crud>/src/server/registerRoutes.js` and `packages/<crud>/src/server/actions.js` so the list validator lists structured filter params explicitly with `createCrudListFilterQueryField(...)`, or `packages/<crud>/src/server/listQueryValidators.js` if you extracted list-query composition there
-- `packages/<crud>/src/server/repository.js` so the list query applies the runtime
+- `packages/<crud>/src/server/<crud>ListFilterContract.js` with `createCrudListFilterContract(...)`
+- `packages/<crud>/src/server/registerRoutes.js` and `packages/<crud>/src/server/actions.js` so list validators include `<crud>ListFilterContract.queryValidator`, or `packages/<crud>/src/server/listQueryValidators.js` if you extracted list-query composition there
+- the provider registration so `createJsonRestResourceScopeOptions(resource, { searchSchema: <crud>ListFilterContract.jsonRestSearchSchema })` merges the JSON REST search schema
+- `packages/<crud>/src/server/repository.js` so the list query calls `<crud>ListFilterContract.toJsonRestQuery(query)` before `buildJsonRestQueryParams(...)`
 - the app-owned list page or list-runtime composable that calls `useCrudList(...)`
 
 If the filter is lookup-backed, touch that same client file again to wire `useCrudListFilterLookups(...)`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.53",
+  "version": "0.1.55",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/INDEX.md

@@ -30,7 +30,7 @@ How to use it:
   - `client-requests.md`
 - playwright, browser test, e2e, ui verification, authenticated ui test, test auth, dev login as, dev auth bypass
   - `ui-testing.md`
-- generated UI contract, design contract, navigation roles, density, placeholder copy, card shells, shared CRUD screens
+- generated UI contract, design contract, navigation roles, density, placeholder copy, card shells, shared CRUD screens, row actions, synthetic rows, detail slots
   - `generated-ui-contract-tracking.md`
 - filter, filters, search facets, chips, date range, enum filter, lookup filter, `useCrudListFilters`, `createCrudListFilters`
   - `filters.md`

package/patterns/client-requests.md

@@ -44,6 +44,14 @@ Use the shared CRUD screen wrappers when the route is a generated CRUD page:
 - `useCrudViewScreen()` plus `CrudViewScreen` for record view route pages
 - `useCrudAddEditScreen()` plus `CrudAddEditScreen` for generated new/edit route pages
 
+Generated screen wrapper extension rules:
+
+- Use `useCrudViewScreen({ requestQueryParams })` for detail includes instead of putting query strings in `apiUrlTemplate`.
+- Use `readEnabled` and `queryKeyFactory` on `useCrudViewScreen()` when the detail read needs the same gating or cache identity control as `useCrudView()`.
+- Use `CrudViewScreen` slots (`before-fields`, `fields`, `after-fields`, `supporting-content`) for page-specific domain sections while keeping shared load/error/retry chrome.
+- Use `listRowActions` with `defineCrudListRowActions(...)` for row-level commands in `CrudListScreen`.
+- Use `syntheticRows` for display-only rows that do not come from the CRUD response, such as owner/master rows.
+
 Use the CRUD wrappers when they fit:
 
 - `useCrudList()` for routed CRUD lists
@@ -86,5 +94,6 @@ Avoid:
 - manually concatenating scoped route params into API URLs
 - using a lower-level seam when a higher-level routed CRUD or command runtime already fits
 - smuggling query params into `apiUrlTemplate`
+- replacing `CrudListScreen` or `CrudViewScreen` only to add row actions, synthetic display rows, includes, or domain detail sections
 - reporting routine resource load errors through hand-written global snackbar/banner calls
 - calling `useShellRequestRecoveryRuntime().report(...)` from normal panels just to recover an HTTP read

package/patterns/crud-repository-mapping.md

@@ -12,8 +12,9 @@ Default JSKIT pattern:
 4. Let generic CRUD runtime handle standard writable `date-time` fields automatically at the DB write seam.
 5. Use `storage.writeSerializer` only for non-default write serialization.
 6. Use `storage: { virtual: true }` for computed output fields.
-7. Register computed SQL projections once in the repository runtime with `virtualFields`.
-8. Let generic CRUD read paths apply those projections automatically.
+7. For `createCrudResourceRuntime(...)` repositories, register computed SQL projections once with `virtualFields`.
+8. For internal JSON REST repositories, register SQL-selected output fields with `createJsonRestResourceScopeOptions(resource, { queryFields })`.
+9. Let generic read paths apply those projections automatically.
 
 Field metadata rules:
 - for a normal override, write:
@@ -80,6 +81,35 @@ const repositoryRuntime = createCrudResourceRuntime(resource, {
 });
 ```
 
+Internal JSON REST pattern:
+- keep the API field in the resource schema as `storage: { virtual: true }`
+- pass server-only SQL projection callbacks through `createJsonRestResourceScopeOptions(...)`
+- keep query projection SQL in the provider/server registration file, not in browser-imported page code
+
+Example:
+
+```js
+await addResourceIfMissing(
+  api,
+  "receivals",
+  createJsonRestResourceScopeOptions(resource, {
+    queryFields: {
+      remainingProcessableWeight: {
+        type: "number",
+        select({ knex, column }) {
+          return knex.raw("?? - coalesce(??, 0)", [
+            column("received_weight"),
+            column("processed_weight")
+          ]);
+        }
+      }
+    }
+  })
+);
+```
+
+If the resource module is server-only, a field may also declare `storage.queryProjection`; `createJsonRestResourceScopeOptions(...)` moves it into JSON REST `queryFields` and removes the virtual field from the storage schema. Prefer the `queryFields` option when the resource module is shared with client code.
+
 What CRUD core does for you:
 - default select columns include only column-backed output fields
 - create/update write payloads serialize standard writable `date-time` fields centrally
@@ -99,5 +129,5 @@ Review checks:
 - standard datetime DB write serialization stays automatic and runtime-owned
 - any non-default DB write serialization lives in `storage.writeSerializer`, not in per-repository hooks
 - computed fields use `storage: { virtual: true }`
-- repository runtime registers matching `virtualFields`
+- repository runtime registers matching `virtualFields`, or the JSON REST provider registers matching `queryFields`
 - no per-method projection duplication when generic CRUD reads already cover the field

package/patterns/crud-scaffolding.md

@@ -29,7 +29,8 @@ Rules:
 - Generated CRUD list screens need real loading, empty, and error states. Empty copy should name the resource, such as "No customers yet", and offer the create action when available.
 - Generated CRUD view/new/edit screens should use page headers plus direct sheet panels. Do not use generic card shells as the page architecture.
 - Compact CRUD actions should be reachable without a drawer. Use a mobile-visible primary action or FAB for create flows.
-- Row actions should collapse into an overflow/action menu on compact widths and can be inline on wider layouts.
+- Row actions should be declared with `defineCrudListRowActions(...)` in a page-local `listRowActions.js` and passed into `useCrudListScreen(...)`; the shared list screen owns the compact/wide action rendering.
+- Use `syntheticRows` for display-only owner/master rows that should appear inside the shared list layout without becoming CRUD records.
 - Bulk actions should be declared in the generated page-local `listBulkActions.js`. The generated list owns selection state, keeps selection controls hidden until actions exist, and exposes selected ids/records to action handlers.
 - Structured filters should use shared filter definitions and collapse to compact filter controls/sheets when they outgrow simple search. Do not stack dense desktop filter bars on phone widths.
 - Use `--navigation-role` for CRUD list placement intent. Main resources can stay `primary`; nested/detail/workflow CRUD routes should usually be `secondary`, `workflow`, or `none`.

package/patterns/filters.md

@@ -35,25 +35,30 @@ Generated client shape:
 - `<CrudListFilterSurface :filters="listFilters" :runtime="filterRuntime" />`
 
 Server-side pattern, only when implementing real backend filter semantics:
-1. Put reusable server-aware filter definitions in the CRUD package if the filter contract needs to be shared outside one generated page.
+1. Put reusable filter definitions in the CRUD package if server code or multiple pages need the same contract.
    Example path: `packages/<crud>/src/shared/<crud>ListFilters.js`
-2. Build the server runtime from that module with `createCrudListFilters(...)`.
-3. Build route/action validators explicitly with `createCrudListFilterQueryField(...)` plus `createCrudListFilterQuerySchema(...)`, and use `applyQuery(...)` in the repository. There is no default validator mode or route-runtime alias.
+2. Build a server contract from that module with `createCrudListFilterContract(...)`.
+3. Use the contract's `queryValidator` in route/action input composition.
+4. Pass the contract's `jsonRestSearchSchema` into `createJsonRestResourceScopeOptions(..., { searchSchema })`.
+5. Call `contract.toJsonRestQuery(query)` before `buildJsonRestQueryParams(...)` in the JSON REST repository path.
 
 Exact file checklist:
 - create `packages/<crud>/src/shared/<crud>ListFilters.js`
-- update `packages/<crud>/src/server/registerRoutes.js` and `packages/<crud>/src/server/actions.js` so the list query validator lists structured filter params explicitly with `createCrudListFilterQueryField(...)` inside `createCrudListFilterQuerySchema(...)`, or update `packages/<crud>/src/server/listQueryValidators.js` if that package already extracts list-query composition there
-- update `packages/<crud>/src/server/repository.js` so list queries call the runtime's `applyQuery(...)`
+- create `packages/<crud>/src/server/<crud>ListFilterContract.js` with `createCrudListFilterContract(...)`
+- update `packages/<crud>/src/server/registerRoutes.js` and `packages/<crud>/src/server/actions.js` so the list query validator includes `listFilterContract.queryValidator`
+- update the provider's `createJsonRestResourceScopeOptions(...)` call so `searchSchema: listFilterContract.jsonRestSearchSchema` is merged into the internal JSON REST resource
+- update `packages/<crud>/src/server/repository.js` so list queries pass `listFilterContract.toJsonRestQuery(query)` into `buildJsonRestQueryParams(...)`
 - update the generated page-local `listFilters.js` first; only edit `index.vue` if a specialist lookup label/runtime integration is needed
 - for lookup-backed filters, wire `useCrudListFilterLookups(...)` beside the existing generated filter runtime instead of replacing `CrudListFilterSurface`
 
 Validation mode is part of the contract:
-- there is no default mode and no fallback alias, so every explicit structured filter field must choose `invalidValues: "reject"` or `invalidValues: "discard"` deliberately
+- `createCrudListFilterContract(...)` defaults to `invalidValues: "reject"` for a strict server boundary
+- set `invalidValues` explicitly when a package is choosing a non-default validation posture
 - use `invalidValues: "reject"` when malformed filter values should fail validation and return a 400-style contract error
 - use `invalidValues: "discard"` when malformed filter values should be ignored and normalization should drop them
 - route query validation runs before auth, so this choice affects whether malformed unauthenticated requests fail at validation or fall through to auth
 - for normal HTTP CRUD handlers, route-level `discard` means the action layer receives already-parsed values for those explicit filter fields; do not assume route `discard` plus action `reject` will still reject malformed HTTP query strings later
-- CRUD list filters are still a deliberate two-phase exception: schema parsing owns query-field values, then the server runtime reprojects those parsed values through filter keys and `applyQuery(...)`
+- CRUD list filters are still a deliberate two-phase exception: schema parsing owns public query-field values, then the server contract reprojects parsed values to JSON REST filters with `toJsonRestQuery(...)`
 
 Keep separate:
 - free-text search uses `records.searchQuery` and `q`
@@ -77,18 +82,18 @@ Use runtime presets when:
 
 Put unusual SQL semantics on the server:
 - examples: `pending` meaning `whereNull("ccp1_passed")`, or business-specific status buckets that combine multiple columns
-- implement those in `createCrudListFilters(..., { apply: { ... } })`
+- implement those in `createCrudListFilterContract(..., { apply: { ... } })`
 - do not use custom `apply` just for null/not-null checks when `type: "presence"` fits
 
 Avoid:
 - local filter composables that duplicate the same keys the server already knows about
 - a custom validator shape that does not match the page state
-- hiding accepted structured filter params behind whole-query validator generation when the route/action contract can list them directly
+- hand-rolled route/action validators or repository filters that duplicate `createCrudListFilterContract(...)`
 - hand-rolled preset apply/reset/active-state helpers when `useCrudListFilters(..., { presets })`, `applyPreset(...)`, and `matchesPreset(...)` fit
 - per-screen `useList()` wrappers for lookup-backed filters when `useCrudListFilterLookups(...)` fits
 - editing generated `.vue` files just to add basic filter controls; use the page-local `listFilters.js` seam first
 - overloading `q` with structured filter meaning
-- inline filter-definition objects passed into `useCrudListFilters(...)` or `createCrudListFilters(...)`; keep definitions in a named module
+- inline filter-definition objects passed into `useCrudListFilters(...)`, `createCrudListFilters(...)`, or `createCrudListFilterContract(...)`; keep definitions in a named module
 
 Good shape:
 - `src/pages/home/customers/listFilters.js`
@@ -96,7 +101,9 @@ Good shape:
 - generated page passes `listFilters` into `useCrudListScreen(...)`
 - shared screen runtime passes `filterRuntime.queryParams` into the list request
 - `packages/receivals/src/shared/receivalListFilters.js`
-- `createCrudListFilters(RECEIVAL_LIST_FILTER_DEFINITIONS, ...)`
+- `createCrudListFilterContract(RECEIVAL_LIST_FILTER_DEFINITIONS, { columns, invalidValues: "reject" })`
+- `createJsonRestResourceScopeOptions(resource, { searchSchema: receivalListFilterContract.jsonRestSearchSchema })`
+- `buildJsonRestQueryParams(JSON_REST_SCOPE_NAME, receivalListFilterContract.toJsonRestQuery(query))`
 - `const listFilters = useCrudListFilters(RECEIVAL_LIST_FILTER_DEFINITIONS, { presets: [...] })`
 - `const filterLookups = useCrudListFilterLookups(RECEIVAL_LIST_FILTER_DEFINITIONS, { values: listFilters.values, ... })`
 - `queryParams: listFilters.queryParams`
@@ -108,7 +115,7 @@ Preset contract notes:
 
 Review checks:
 - one filter definition source of truth: generated page-local `listFilters.js` for client-only filters, or a shared CRUD-package module when server code imports the same definitions
-- server validator/repository logic derived from that source, with route/action query params still listed explicitly
+- server validator, JSON REST search schema, and repository query projection derived from that source through `createCrudListFilterContract(...)`
 - client query params/chips/reset logic derived from that source
 - lookup-backed filters use the shared lookup helper, not a page-local mini-framework
 - the two-phase server exception is intentional and documented, not accidental drift

package/patterns/generated-ui-contract-tracking.md

@@ -55,8 +55,11 @@ Generated JSKIT apps should feel like real adaptive apps by default, not framewo
 - Item 3 is complete for current generated surfaces: page, CRUD, shell, and starter outputs require compact/medium/expanded coverage, horizontal overflow checks, generated screen checks, and 48px tap target checks. Calendar/grid/bottom-sheet specialist generators remain future scope until those generators exist.
 - Item 5 is complete for current generators: `primary`, `secondary`, `utility`, `detail`, `workflow`, and `none` are centralized in the generated UI contract, generators consume that contract, and `utility` resolves to seeded `shell.global-actions` topology.
 - Item 6 is complete for the default shell: compact app bars use compact density and bounded top-left/top-right regions, while primary navigation remains in semantic bottom navigation instead of app-bar chrome.
-- CRUD filters are client-side by default: generated list pages create a page-local `listFilters.js` and pass it into `useCrudListScreen(...)`; the shared list screen wires `filterRuntime.queryParams` into the list request and renders `CrudListFilterSurface`. Server filter behavior remains explicit app/package work.
+- CRUD filters are client-side by default: generated list pages create a page-local `listFilters.js` and pass it into `useCrudListScreen(...)`; the shared list screen wires `filterRuntime.queryParams` into the list request and renders `CrudListFilterSurface`. When server filtering is needed, promote the definitions into a shared package module and use `createCrudListFilterContract(...)` so route/action validators, JSON REST search schema, and repository query normalization stay derived from the same definition.
 - CRUD bulk actions are client-side by default: generated list pages create a page-local `listBulkActions.js` and pass it into `useCrudListScreen(...)`; the shared list screen wires `useCrudListBulkActions(...)` and keeps selection controls hidden until actions are declared.
-- Generated CRUD page templates delegate their screen chrome to shared `users-web` screen components (`CrudListScreen`, `CrudViewScreen`, and `CrudAddEditScreen`) so list/view/form load states, retry actions, responsive shell layout, filters, and bulk actions do not drift across generated pages.
+- CRUD row actions are client-side by default: generated list pages can create a page-local `listRowActions.js` with `defineCrudListRowActions(...)` and pass it into `useCrudListScreen(...)`; the shared list screen renders per-row actions in card and table layouts while action handlers stay explicit and page-owned.
+- CRUD synthetic rows are display-only: pass `syntheticRows` into `useCrudListScreen(...)` for owner/master rows that are not repository records. Synthetic rows render through the shared list screen, skip standard Open/Edit links, and are excluded from bulk selection unless explicitly marked selectable.
+- Generated CRUD page templates delegate their screen chrome to shared `users-web` screen components (`CrudListScreen`, `CrudViewScreen`, and `CrudAddEditScreen`) so list/view/form load states, retry actions, responsive shell layout, filters, bulk actions, row actions, and detail slots do not drift across generated pages.
+- Generated CRUD detail pages should use `useCrudViewScreen({ requestQueryParams, readEnabled, queryKeyFactory })` for read pass-throughs and `CrudViewScreen` slots (`before-fields`, `fields`, `after-fields`, `supporting-content`) for domain sections instead of replacing the shared detail chrome.
 - Routine resource-load errors stay local to the generated screen and retry affordance. Action feedback uses the shell error policy through `action-feedback`.
 - `page.supporting-content` is a semantic supporting region in the default shell. Compact layout renders it as a closed bottom sheet; medium/expanded layouts render it as a closed side panel.

package/patterns/server-search.md

@@ -10,20 +10,21 @@ Core rule:
 - for current JSKIT CRUD apps, the server search contract lives in `resource.searchSchema` on the internal JSON REST path
 - route validators decide which public query keys HTTP callers may send
 - repositories may add internal-only filter keys before forwarding the query to JSON REST
+- structured list filters should use `createCrudListFilterContract(...)` so route/action validators, JSON REST search schema, and repository query normalization are derived from one definition
 
 Fresh generated CRUD repositories already follow this path:
 
 ```js
 return api.resources.contacts.query({
-  queryParams: buildJsonRestQueryParams(RESOURCE_TYPE, query),
+  queryParams: buildJsonRestQueryParams(RESOURCE_TYPE, contactListFilterContract.toJsonRestQuery(query)),
   simplified: false
 }, createJsonRestContext(context));
 ```
 
 The normal layer split is:
 1. `actions.js` / `registerRoutes.js`: accept and validate public query keys
-2. `repository.js`: add internal-only filter keys such as visibility scope
-3. `*Resource.js`: define the backend filter behavior in `searchSchema`
+2. `repository.js`: add internal-only filter keys such as visibility scope, or call `listFilterContract.toJsonRestQuery(query)` for structured filters
+3. provider/resource registration: merge backend filter behavior into JSON REST with `createJsonRestResourceScopeOptions(resource, { searchSchema })`
 
 ## Decision Rules
 
@@ -147,6 +148,26 @@ That means:
 - `q` and the structured filter keys are accepted publicly
 - the repository may still add internal-only keys later
 
+For structured list filters, prefer the generated contract shape:
+
+```js
+const receivalListFilterContract = createCrudListFilterContract(
+  RECEIVAL_LIST_FILTER_DEFINITIONS,
+  {
+    columns: {
+      status: "status",
+      supplierContactId: "supplier_contact_id",
+      arrivalDate: "arrival_datetime"
+    },
+    invalidValues: "reject"
+  }
+);
+```
+
+Use `receivalListFilterContract.queryValidator` at route/action boundaries. Use `receivalListFilterContract.jsonRestSearchSchema` when registering the JSON REST resource. Use `receivalListFilterContract.toJsonRestQuery(query)` before `buildJsonRestQueryParams(...)`.
+
+That contract preserves arrays for `enumMany` and `recordIdMany`, maps range filters to internal JSON REST search keys, and keeps those internal keys out of the public HTTP query contract.
+
 Do not add route validators for:
 - repository-injected internal keys such as `"__viewerAccess"`
 - filters that must never be supplied by the client directly
@@ -197,6 +218,7 @@ function buildScopedQuery(query = {}, context = null) {
 ## Keep These Boundaries Clean
 
 - Put backend filter behavior in `searchSchema`, not in page code.
+- Use `createCrudListFilterContract(...)` for structured list filters before writing custom JSON REST query glue.
 - Put permission checks in the action/service layer, not in `applyFilter`.
 - Put repository-only scoping in the repository, not in route query validation.
 - Do not expose a query key publicly just because the repository uses it internally.

package/reference/autogen/packages/crud-core.md

@@ -133,7 +133,9 @@ Exports
 - `CRUD_LIST_FILTER_INVALID_VALUES_DISCARD`
 - `createCrudListFilterQueryField(filterDefinition = {}, { invalidValues = CRUD_LIST_FILTER_INVALID_VALUES_REJECT } = {})`
 - `createCrudListFilterQuerySchema(structure = {})`
+- `createCrudListFilterJsonRestSearchSchema(runtime = {}, { columns = {}, apply = {} } = {})`
 - `createCrudListFilters(definitions = {}, { columns = {}, apply = {} } = {})`
+- `createCrudListFilterContract(definitions = {}, { columns = {}, apply = {}, invalidValues = CRUD_LIST_FILTER_INVALID_VALUES_REJECT } = {})`
 Local functions
 - `cloneTransportSchema(value)`
 - `buildSingleOrMultiTransportSchema(itemSchema)`
@@ -144,6 +146,18 @@ Local functions
 - `buildFilterQuerySchemaDefinition(filterEntries = [], { invalidValues = CRUD_LIST_FILTER_INVALID_VALUES_REJECT } = {})`
 - `projectNormalizedFilterValues(filterEntries = [], source = {}, errors = {})`
 - `normalizeColumnsMap(columns = {})`
+- `resolveJsonRestFilterActualField(filter = {}, columns = {})`
+- `renderInternalJsonRestFilterKey(filter = {}, suffix = "")`
+- `createJsonRestSearchSchemaEntry({ type = "string", actualField = "", filterOperator = "=", extra = {} } = {})`
+- `buildJsonRestFilterItemSchema(filter = {})`
+- `buildJsonRestSimpleFilterSearchSchemaEntry(filter = {}, { actualField = "" } = {})`
+- `buildJsonRestRangeFilterSearchSchemaEntries(filter = {}, { actualField = "" } = {})`
+- `buildJsonRestPresenceFilterSearchSchemaEntry(filter = {}, { actualField = "" } = {})`
+- `buildJsonRestCustomFilterSearchSchemaEntry(filter = {}, customApply = null)`
+- `resolveCrudListFilterEntries(value = {})`
+- `addJsonRestDateFilterValues(target = {}, filter = {}, value = "")`
+- `addJsonRestFilterValue(target = {}, filter = {}, value)`
+- `normalizeCrudListFilterJsonRestQuery(runtime = {}, query = {})`
 - `applyDefaultFilterQuery(queryBuilder, filter = {}, value, column = "")`
 
 ### `src/server/listQueryValidators.js`
@@ -295,7 +309,7 @@ Local functions
 
 ### `src/server/routeContracts.js`
 Exports
-- `createCrudJsonApiRouteContracts({ resource = {}, routeParamsValidator = null, listSearchQueryValidator = defaultListSearchQueryValidator, lookupIncludeQueryValidator = defaultLookupIncludeQueryValidator } = {})`
+- `createCrudJsonApiRouteContracts({ resource = {}, routeParamsValidator = null, listSearchQueryValidator = defaultListSearchQueryValidator, lookupIncludeQueryValidator = defaultLookupIncludeQueryValidator, listFilterQueryValidator = null } = {})`
 Local functions
 - `isRecord(value)`
 - `resolveSchemaFieldDefinitions(definition = null)`

package/reference/autogen/packages/json-rest-api-core.md

@@ -26,7 +26,7 @@ Exports
 - `buildJsonRestQueryParams(resourceType = "", query = {}, { include = undefined } = {})`
 - `createJsonApiInputRecord(resourceType = "", attributes = {}, { id = null, relationships = null, resource = null } = {})`
 - `createJsonApiRelationship(resourceType = "", id = null)`
-- `createJsonRestResourceScopeOptions(resource = {}, { writeSerializers = {}, normalizeId = null } = {})`
+- `createJsonRestResourceScopeOptions(resource = {}, { writeSerializers = {}, normalizeId = null, searchSchema = null, queryFields = null } = {})`
 - `createJsonRestContext(context = null)`
 - `extractJsonRestCollectionRows(payload = null)`
 - `isJsonRestResourceMissingError(error = null)`
@@ -40,9 +40,13 @@ Local functions
 - `cloneJsonRestResourceValue(value, { writeSerializers = {} } = {})`
 - `normalizeScopeValue(value)`
 - `normalizeJsonRestText(value, { fallback = "" } = {})`
+- `normalizeJsonRestFilterValue(value)`
 - `normalizeJsonRestObject(value)`
 - `normalizeJsonRestList(value)`
 - `resolveJsonRestCollectionRelationships(resource = {})`
+- `normalizeJsonRestQueryField(fieldName = "", fieldDefinition = {}, projectionDefinition = null)`
+- `isJsonRestVirtualField(fieldDefinition = null)`
+- `applyJsonRestQueryFields(scopeOptions = {}, extraQueryFields = {})`
 - `extractJsonApiInputRelationships(attributes = {}, resource = null, relationships = null)`
 
 ### root

package/reference/autogen/packages/users-web.md

@@ -66,6 +66,14 @@ Local functions
 - `clearChip(chip = {})`
 - `clearFilters()`
 
+### `src/client/components/CrudListRecordActionMenu.vue`
+Exports
+- None
+Local functions
+- `isRowActionLoading(action = {})`
+- `isRowActionDisabled(action = {})`
+- `runRowAction(action = {})`
+
 ### `src/client/components/CrudListScreen.vue`
 Exports
 - None
@@ -74,6 +82,12 @@ Local functions
 - `formatListCardValue(value)`
 - `resolveViewLocation(record)`
 - `resolveEditLocation(record)`
+- `hasRowActionsFor(record, index)`
+- `isBulkRowSelected(row = {})`
+- `setBulkRowSelected(row = {}, selected = true)`
+- `allSelectableRowsSelected()`
+- `someSelectableRowsSelected()`
+- `setSelectableRowsSelected(selected = true)`
 
 ### `src/client/components/CrudViewScreen.vue`
 Exports
@@ -484,15 +498,30 @@ Exports
 Local functions
 - `normalizeQueryKeyPrefix(value = [])`
 
+### `src/client/composables/useCrudListRowActions.js`
+Exports
+- `useCrudListRowActions(actions = [], { resolveRecordId = null, resolveContext = null } = {})`
+Local functions
+- `normalizeRowActionKey(actionOrKey = "")`
+- `normalizeRowId(value = "")`
+- `createExecutionKey(actionKey = "", recordId = "", index = 0)`
+- `asContextObject(value = null)`
+
 ### `src/client/composables/useCrudListScreen.js`
 Exports
-- `useCrudListScreen({ adapter = null, resource = null, resourceNamespace = "resource", apiSuffix = "", recordIdParam = "recordId", recordIdSelector = null, titleFallbackFieldKey = "", viewUrlTemplate = "", editUrlTemplate = "", newUrlTemplate = "", recordChangedEvents = [], listFilters = {}, listBulkActions = [], routeQueryBlacklist = Object.freeze(["include", "cursor", "limit"]), requestRecoveryLabel = "Records", fallbackLoadError = "Unable to load records." } = {})`
+- `useCrudListScreen({ adapter = null, resource = null, resourceNamespace = "resource", apiSuffix = "", recordIdParam = "recordId", recordIdSelector = null, titleFallbackFieldKey = "", viewUrlTemplate = "", editUrlTemplate = "", newUrlTemplate = "", recordChangedEvents = [], listFilters = {}, listBulkActions = [], listRowActions = [], syntheticRows = null, routeQueryBlacklist = Object.freeze(["include", "cursor", "limit"]), requestQueryParams = null, requestRecoveryLabel = "Records", fallbackLoadError = "Unable to load records." } = {})`
 Local functions
 - `formatCrudListCardValue(value)`
+- `asList(value = [])`
+- `hasSyntheticRowGroups(value = null)`
+- `normalizeSyntheticDisplayRow(source = null, index = 0, placement = "prepend")`
+- `normalizeSyntheticDisplayRows(value = [], placement = "prepend")`
+- `normalizeSyntheticDisplayRowGroups(syntheticRows = null)`
+- `createCrudListDisplayRow(record = {}, index = 0, records = {})`
 
 ### `src/client/composables/useCrudViewScreen.js`
 Exports
-- `useCrudViewScreen({ adapter = null, resource = null, resourceNamespace = "resource", apiUrlTemplate = "", recordIdParam = "recordId", titleFallbackFieldKey = "", listUrlTemplate = "", editUrlTemplate = "", recordChangedEvent = "", requestRecoveryLabel = "Record", fallbackLoadError = "Unable to load record.", notFoundMessage = "Record not found." } = {})`
+- `useCrudViewScreen({ adapter = null, resource = null, resourceNamespace = "resource", apiUrlTemplate = "", recordIdParam = "recordId", titleFallbackFieldKey = "", listUrlTemplate = "", editUrlTemplate = "", recordChangedEvent = "", requestQueryParams = null, readEnabled = true, queryKeyFactory = null, requestRecoveryLabel = "Record", fallbackLoadError = "Unable to load record.", notFoundMessage = "Record not found." } = {})`
 
 ### `src/client/composables/usePagedCollection.js`
 Exports
@@ -605,6 +634,12 @@ Local functions
 Exports
 - `UsersWebClientProvider`
 
+### `src/client/rowActions.js`
+Exports
+- `defineCrudListRowActions(actions = [])`
+Local functions
+- `normalizeCrudListRowAction(rawAction = {}, index = 0)`
+
 ### `src/client/support/contractGuards.js`
 Exports
 - `requireRecord(value, label = "value", owner = "Contract")`