@cratis/pi 7.34.1 → 7.35.0

package/package/corpus/skills/cratis-arc-query-paging/SKILL.md

@@ -24,12 +24,13 @@ the query string — you choose a **return shape** that the framework can narrow
 
 | Package | Version | Purpose |
 | --- | --- | --- |
-| `Cratis.Arc.Core` | `22.16.0` | `QueryableQueryRenderer`, `Paging`, `Sorting`, `PagingInfo` |
-| `Cratis.Arc.MongoDB` | `22.16.0` | `Observe` helpers that page at the source |
-| `Cratis.Arc.EntityFrameworkCore` | `22.16.0` | `DbSet<T>` observe helpers that page at the source |
-| `@cratis/arc.react` | `22.16.0` | `useWithPaging`, `useSuspenseWithPaging` |
+| `Cratis.Arc.Core` | `22.75.0` | `QueryableQueryRenderer`, `Paging`, `Sorting`, `PagingInfo` |
+| `Cratis.Arc.MongoDB` | `22.75.0` | `Observe` helpers that page at the source |
+| `Cratis.Arc.EntityFrameworkCore` | `22.75.0` | `DbSet<T>` observe helpers that page at the source |
+| `@cratis/arc.react` | `22.75.0` | `useWithPaging`, `useSuspenseWithPaging` |
 
-> Re-verified at the versions above by **symbol and signature**: every type, attribute and member this skill names exists at that tag, and the public surface it describes is unchanged since the previous verification (Chronicle 16.45.x / Arc 22.10.4 — the Chronicle 16→18 client diff is converters, options and doc comments; no type was removed or renamed). Behavior claims were verified at the earlier tag unless a section says otherwise.
+> Rechecked at Arc v22.75.0: request parsing, paging validation and storage
+> observation contracts. Do not transfer a provider's ordering guarantee to another.
 
 Reverify before claiming support for another version. A small, bounded result
 set does not need any of this — `IEnumerable<T>` is fine.
@@ -38,10 +39,10 @@ set does not need any of this — `IEnumerable<T>` is fine.
 
 | Query-string key | Effect |
 | --- | --- |
-| `pageSize` | **Required to page at all** on the query string; any parseable integer is accepted (`0` yields an empty page, negatives are clamped by `Skip`) — the JSON body reader, by contrast, treats `pageSize <= 0` as not paged |
+| `pageSize` | **Required to page at all** on the query string; parseable values enroll paging validation (`page >= 0`, `pageSize > 0`) — the JSON body reader, by contrast, treats `pageSize <= 0` as not paged |
 | `page` | Zero-based. Defaults to `0` when `pageSize` is present |
 | `sortby` | Field name; PascalCased before use, so `?sortby=name` sorts on `Name` |
-| `sortDirection` | `desc` (case-insensitive) sorts descending; **anything else, including a missing value, is ascending** |
+| `sortDirection` | `asc`/`ascending` or `desc`/`descending`, case-insensitive; unknown values are `malformedRequest` (HTTP 400) |
 
 Two consequences that surprise people:
 
@@ -49,12 +50,12 @@ Two consequences that surprise people:
 - **Sorting needs both keys.** `sortby` without `sortDirection` is ignored
   entirely.
 
-Paging is **not** validated on the request path at 22.16.0: `PageNumber`/`PageSize`
-concept validators exist (`page >= 0`, `pageSize > 0`) but nothing feeds the
-query-string paging into them, so an out-of-range value produces an empty or
-clamped page rather than a validation failure. Validate paging arguments in the
-frontend, or expose them as explicit query arguments if the rule must be
-enforced.
+GET paging/sorting keys are matched case-insensitively. `QueryPipeline.ValidatePaging`
+runs the page validators whenever `paging.IsPaged`: negative page and zero or
+negative size fail validation. This was already true at 22.16.0. A missing sort
+direction parses as ascending, but GET sorting still needs both nonempty keys.
+Sources at Arc v22.75.0: `Arc.Core/Queries/QueryStringQueryRequestReader.cs`,
+`SortDirections.cs` and `QueryPipeline.cs` under `Source/DotNET`.
 
 ## Which return shapes page
 
@@ -102,10 +103,10 @@ query-shaped method on a read model is generic — a generic method is registere
 and routed but can never be invoked, because there is nothing to close its type
 parameters with.
 
-For MongoDB `Observe` cost, distinguish the initial retained result, incremental
-membership updates, and page-refill queries from an application callback that
-explicitly re-runs a query. It does not always fetch the whole collection per
-change. See the read-model skill's [versioned query-cost guidance](../cratis-chronicle-read-model/references/queries.md#cost-and-composition).
+At v22.75.0, paged MongoDB observations re-read the page and total on each
+change; unpaged observations retain incremental membership. The watch does not
+always fetch the whole collection. MongoDB observation breaks sort ties on `_id`
+and orders unsorted pages on `_id`. See the read-model skill's [versioned query-cost guidance](../cratis-chronicle-read-model/references/queries.md#cost-and-composition).
 
 ## Page the source, not the answer
 
@@ -134,9 +135,13 @@ a second round trip to the store per query.
 Because `sortby` is PascalCased, the client sends the camelCase property name
 the generated proxy uses and the server resolves the CLR property.
 
-Give any list with a natural order a default `OrderBy`. Paging without one is
-unstable across storage providers, which return unordered results in different
-orders.
+Give any list with a natural order a default `OrderBy`; do not generalize the
+MongoDB observation tie-break to every `IQueryable` provider. Generated proxies
+provide field-named sort helpers. For composed MongoDB/EF observations, pass
+`ignoreQueryContext: true` to auxiliary sources so only the primary consumes
+client paging/sorting and writes totals. Single-instance observations emit
+`default` when absent/deleted/outside the filter; guard `hasData`/`isReady` in React.
+Source: [Arc v22.75.0 MongoDB observations](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/backend/csharp/mongodb/observing-collections.md).
 
 ## Consume it from the frontend
 

package/package/corpus/skills/cratis-arc-query-typescript/SKILL.md

@@ -19,8 +19,8 @@ frontend. Project setup, the builder, and hosts are in
 
 ## Verified product sources
 
-Verified against `Cratis/Arc.TypeScript` `main` at commit `94d398d` (tag
-`v0.33.0` plus three commits), reading
+Verified against `Cratis/Arc.TypeScript` tag **v0.57.2** (GitHub pre-release;
+server packages 0.57.2, not on npm), reading
 `Source/Core/queries/index.ts`, `Documentation/queries/**`,
 `Documentation/mongodb/**`, `Documentation/sql/**`,
 `Documentation/testing/queries.md` and `observable-queries.md`, and
@@ -143,7 +143,13 @@ Every query route accepts GET and the HTTP `QUERY` method, whose JSON body is
 `generatedApis: { enableQueryHttpMethod: false }` turns it off (405 with
 `Allow: GET`). `@query({ httpMethod: QueryHttpMethod.Query })` only sets the
 generated client's preference; it does not change the server. OpenAPI describes
-queries as GET only.
+queries as GET only. OpenAPI includes `POST <command route>/validate` with
+operation id `<id>:validate`; paging/sorting parameters only for array/`queryPage`
+queries (metadata-free arrays need `generatedReturn: { cardinality: 'many', nullable: false }`).
+401 appears only when authentication can produce it. `/openapi.json` is protected
+by the secure discovery defaults; read
+[the identity/introspection reference](../cratis-arc-command-typescript/references/identity-and-introspection.md)
+when configuring discovery access or identity.
 
 ## Page and sort
 
@@ -151,6 +157,11 @@ queries as GET only.
   `page` is zero-based. `pageSize` of 0 or less, or a negative page, answers
   400. Sorting in memory requires the field on every item; a non-array result
   asked to page or sort answers 400.
+- In-memory complex-field sorting (object/array/map or a concept over one) answers
+  400 `malformedRequest`, or a validation frame after streaming starts. Concepts
+  sort by their underlying scalar value (including numeric/chronological values);
+  temporal values sort naturally and null concepts join other nulls. Generated
+  complex-field `sortBy` helpers are deprecated: sort on scalar fields.
 - To cut the page in the data source, add `queryOptions()` and return
   `queryPage(items, totalItems)`. `items` must be exactly the requested page.
   If the request asked for sorting, pass the applied sort as the third argument —
@@ -174,7 +185,10 @@ static observeAllTasks(tasks: Tasks): BehaviorSubject<TaskItem[]> { return tasks
 Arc must know a query is observable **before** registration. Generated metadata
 infers it from the declared return type; without metadata, say so explicitly:
 `@query({ observable: true }, service(Tasks))`. A snapshot query that returns a
-live source anyway fails at run time.
+live source anyway throws `SnapshotStreamError`, without subscribing or calling
+`unsubscribe()` on a shared Subject. Arc releases it once through its available
+async/sync disposal, `dispose`, `close`, or `return` hook;
+`snapshotStreamSource(result)` is exported from core.
 
 | Source | Snapshot GET |
 | --- | --- |
@@ -194,7 +208,8 @@ live source anyway fails at run time.
   its `signal` aborts when the subscriber leaves.
 - Paging and sorting apply to **every** emission, in memory. An observable query
   cannot return `queryPage`; narrow what the source emits instead, or use a
-  database-backed observation such as MongoDB change streams.
+  database-backed observation such as MongoDB change streams or opted-in Drizzle
+  observation (see the storage reference below).
 - Transports: `Accept: text/event-stream` on the route (direct SSE, one
   `data: <QueryResult>` frame per change), a direct WebSocket upgrade
   (`{"type":"Data","data":<QueryResult>}` frames, `Ping`/`Pong`), or the
@@ -276,13 +291,22 @@ export class Author {
   `observe()` needs a replica set. Build owner filters from the verified
   principal, never from a caller-provided filter object.
 - Drizzle: `drizzleReadModel(Model)` is a read-only handle; writes belong in
-  commands through `drizzleDatabase()`.
+  commands through `drizzleDatabase()`. Live queries require opt-in
+  `DrizzleObservation.InProcess` announcements or experimental PostgreSQLNotify;
+  `rxjs` is a required peer of `@cratis/arc.drizzle`.
+- Protected raw MongoDB reads need typed `MongoReadModels` with `readModel`
+  registered with Chronicle (optional `subjectFor`). Untyped reads and
+  `MongoDBWatcher.changes()` still expose stored ciphertext.
+
 - Chronicle: `ChronicleReadModels` offers `getAll`, `getById`, `observeAll`,
   `observeById` for the current tenant's namespace. Projecting happens after the
   append, so a query right after a command can be stale; a live query updates
   when the projection catches up. Projection authoring is
   `cratis-chronicle-client-typescript`.
 
+Read [references/storage-observation-and-compliance.md](references/storage-observation-and-compliance.md)
+when implementing Drizzle observation or serving protected raw MongoDB documents.
+
 ## Specify the query
 
 `@cratis/arc.testing` runs the real query pipeline in-process. From
@@ -313,6 +337,8 @@ export class a_task_listing {
   rehydrated model.
 - `perform(arguments, { paging, sorting }?)` returns the actual `QueryResult`,
   e.g. `perform({}, { sorting: { field: 'title', direction: SortDirection.Ascending }, paging: { page: 0, pageSize: 1 } })`.
+- `QueryScenario.perform()` throws `StreamingQueryNotSupportedError` for
+  observable queries: use `ObservableQueryScenario` instead.
 - `ObservableQueryScenario.collect(count, timeoutMs = 5000, arguments?, options?)`
   returns `{ emissions, completed, rejection }`; a rejected subscription lands in
   `rejection`, not `emissions`. Always assert the emission count.

package/package/corpus/skills/cratis-arc-query-typescript/references/storage-observation-and-compliance.md

@@ -0,0 +1,66 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Storage observation and protected raw reads
+
+Verified at `Cratis/Arc.TypeScript` **v0.57.2** (source preview, not on npm):
+`Source/Drizzle/DrizzleOptions.ts`, package exports and observation code,
+`Source/MongoDB/MongoReadModelsOptions.ts`, `Source/Chronicle/releaseRawDocument.ts`,
+`Documentation/sql/observing-tables.md`, `observing-postgresql.md`, and
+`Documentation/chronicle/compliance.md`.
+
+## Drizzle live queries
+
+`rxjs ^7.8.2` is a **required peer** of `@cratis/arc.drizzle`, even with
+observation disabled. Starting an observation without opting in throws; it never
+silently returns a stream that will not update.
+
+- In-process: `withDrizzle({ ..., observation: DrizzleObservation.InProcess })`.
+  Writers call `DrizzleHandle.notifyChanged(tableOrType)` for a registered table
+  object/model, in the current tenant. Only announced writes in this process
+  invalidate reads. Inside commands, notifications coalesce until that tenant's
+  outermost command finishes (success **or failure**). Transactions owned outside
+  Arc are not covered; announce only after their commit. Background writes
+  announce immediately, so call after commit.
+- Cross-process PostgreSQL (experimental): use observation options
+  `{ mode: DrizzleObservation.PostgreSQLNotify, listener }`. Install the SQL from
+  `postgresqlChangeTrigger(table, { schema })` in an application-owned drizzle-kit
+  custom migration, not at runtime. `nodePostgresListener(new Client(...))` wraps
+  a new, unconnected, dedicated `pg.Client`; route both listener and query pool
+  to the same primary database. Aliased tables, views, partitions, inherited and
+  temporary tables are rejected. Recovery reconnects with bounded backoff,
+  revalidates triggers, then forces fresh snapshots; there is no in-process
+  fallback and no durable replay of outage history.
+
+`DrizzleReadModels.observe(filter?)` / `observeById(key)` return RxJS sources
+with `current()`. The former fails on `maxPageSize` overflow rather than
+truncating; the latter emits null for absence/deletion. Use these for model-bound
+observable queries. `observePage` requires low-level `defineObservableQuery` and
+has **no generated proxy support**. Count and page are eventually consistent,
+not one atomic snapshot. Release subscriptions/scopes to release listeners.
+
+## MongoDB compliance release
+
+With Chronicle registered, decoded **exact** protected read-model instances are
+released before query encoding. For raw `MongoReadModels` documents, pass
+`readModel: PersonView`, with that type registered with `withChronicle`, and
+optionally `subjectFor(document)`. Default subject is stored `__subject`, then a
+string/numeric `_id`. Typed reads reject partial MongoDB projections.
+
+Release is fail-closed. The query/emission fails for a mismatched subject or
+tenant, nonempty `__subjects` (per-property subjects), undeclared fields,
+non-JSON BSON values, missing schemas, or a failed/incomplete release. Date
+values are accepted; BSON ObjectId/Binary/Decimal128 payload fields are not.
+Return typed documents directly, in arrays, or in **`queryPage`**. Nesting one
+inside another response shape — including `MongoReadModels.page()`'s `MongoPage`
+— fails; read multi-subject models through `ChronicleReadModels` instead.
+
+Untyped MongoReadModels, unmarked driver documents, copies that lose their
+marking, and `MongoDBWatcher.changes()` are still served **as stored ciphertext**.
+Do not assume any raw query was decrypted merely because Chronicle is installed.
+Protected reducer-watch removals whose payload the SDK cannot release carry an
+empty model instance rather than that unreleased payload.
+
+Release is not authorization. Filter by the verified caller separately. See
+`cratis-chronicle-compliance` for subject/erasure principles, but use these
+TypeScript APIs rather than its .NET code shapes.

package/package/corpus/skills/cratis-arc-query-typescript/verification.json

@@ -9,6 +9,10 @@
     { "kind": "skill-contains", "value": "`@query({ observable: true }, service(Tasks))`" },
     { "kind": "skill-contains", "value": "| RxJS `BehaviorSubject<T>` | 200 immediately" },
     { "kind": "skill-contains", "value": "authorization runs **once**, when the subscription\n  opens" },
-    { "kind": "skill-contains", "value": "QueryScenario.for<T>(ReadModel, 'methodName', ...artifacts)" }
+    { "kind": "skill-contains", "value": "QueryScenario.for<T>(ReadModel, 'methodName', ...artifacts)" },
+    { "kind": "skill-contains", "value": "SnapshotStreamError" },
+    { "kind": "skill-contains", "value": "400 `malformedRequest`" },
+    { "kind": "skill-contains", "value": "DrizzleObservation.InProcess", "file": "references/storage-observation-and-compliance.md" },
+    { "kind": "skill-contains", "value": "Untyped MongoReadModels", "file": "references/storage-observation-and-compliance.md" }
   ]
 }

package/package/corpus/skills/cratis-arc-react-page/SKILL.md

@@ -28,10 +28,10 @@ This skill is verified against these exact package contracts:
 
 | Package | Version | Verified from |
 | --- | --- | --- |
-| `@cratis/components` | `4.6.0` | its package manifest (`exports`, peers), `Source/DataPage/*`, `Source/DataTables/*`, `Source/Dialogs/*`, `Source/CommandDialog/*`, `Source/MIGRATION.md` |
-| `@cratis/arc` | `>=20.3.1 <23` | peer range declared by `@cratis/components@4.6.0` |
-| `@cratis/arc.react` | `>=20.3.1 <23` | peer range declared by `@cratis/components@4.6.0` |
-| `react` | `^19.0.0` | peer of `@cratis/components@4.6.0` |
+| `@cratis/components` | `4.26.4` | its package manifest (`exports`, peers), `Source/DataPage/*`, `Source/DataTables/*`, `Source/Dialogs/*`, `Source/CommandDialog/*`, `Source/MIGRATION.md` |
+| `@cratis/arc` | `>=20.3.1 <23` | peer range declared by `@cratis/components@4.26.4` |
+| `@cratis/arc.react` | `>=20.3.1 <23` | peer range declared by `@cratis/components@4.26.4` |
+| `react` | `^19.0.0` | peer of `@cratis/components@4.26.4` |
 
 `@cratis/arc.react.mvvm` ships with `@cratis/arc.react` and is an explicit
 application dependency. Reverify before claiming another version.
@@ -69,16 +69,26 @@ must move focus into itself.
   fix the C# source and rebuild instead of editing one.
 - The app must mount `CratisComponentsProvider` (from the package root,
   `@cratis/components`) above every Cratis component — it carries the locale,
-  the Components-owned labels and the toast region (`toaster`).
+  the Components-owned labels. Enable `toaster` (or mount one `<Toaster />`)
+  for notifications; without it even `toastCommandResult` displays nothing.
+  Mount exactly one toaster, not both.
 - The app must import the stylesheets explicitly; components do not import
   their own CSS:
 
-  ```ts
-  import '@cratis/components/tokens';   // the --cratis-* token seam
-  import '@cratis/components/styles';   // structural rules for every component
-  import '@cratis/components/theme';    // optional: the maintained baseline look
+  In `index.css`, imported by the entry with `import './index.css'`:
+
+  ```css
+  @import '@cratis/components/tokens';
+  @import '@cratis/components/styles';
+  @import '@cratis/components/theme'; /* optional baseline */
   ```
 
+  CSS subpath imports from TypeScript need ambient declarations on TypeScript 6;
+  use CSS `@import` to avoid TS2882. For a smaller bundle use `styles/base` plus
+  the needed area sheets (`DataPage/styles`, etc.); area order does not matter.
+  Import `reflect-metadata` at the entry point; it remains required. `tsyringe`
+  is optional for Components but installed by Arc React.
+
   Components has no vendor UI dependency — do not install PrimeReact or an icon
   font for it. Menu icons are React component types (`react-icons` works).
 
@@ -268,8 +278,9 @@ const [selected, setSelected] = useState<AccountSummary | null>(null);
 The **same `query` prop** takes a snapshot query or an observable query. There
 is no separate `observableQuery` prop: `DataPage` inspects the query prototype
 and picks the snapshot or observable table itself. Pass an observable query and
-the page stays live; pass a snapshot query and call `onRefresh` after a command
-succeeds.
+the page stays live. `onRefresh` only forwards a caller callback to the details
+component; it never refetches the table. DataPage has no snapshot refresh handle.
+Use an observable query when commands must update the list.
 
 Read [queries-and-commands.md](references/queries-and-commands.md) when using generated proxy hooks, implementing paging, or handling command results; it covers the
 generated proxy hooks, their exact return tuples, paging, and how to read a
@@ -325,8 +336,8 @@ props handling, or teardown.
 ## Verify
 
 - Every Cratis Components import uses a subpath, not the root barrel.
-- `CratisComponentsProvider` wraps the tree and the three stylesheets are
-  imported once at the app entry point.
+- `CratisComponentsProvider` wraps the tree, one toaster is mounted for
+  notifications, and the CSS entries are imported once via the app's CSS file.
 - `DataPage` receives `title`, `query`, `emptyMessage`, and children, and
   `dataKey` when the read model has an identity.
 - Columns sit in `<DataPage.Columns>`; menu items sit in

package/package/corpus/skills/cratis-arc-react-page/references/data-page.md

@@ -38,17 +38,22 @@ Three static members exist:
 | --- | --- | --- |
 | `title` | `string` | required — menubar title |
 | `query` | `Constructor<TQuery>` | required — a snapshot **or** observable query proxy |
-| `emptyMessage` | `string` | required — shown when the query returns no rows |
+| `emptyMessage` | `string` | required — only a real empty result |
+| `loadingMessage` / `failureMessage` / `unauthorizedMessage` | `ReactNode` | query-state rows; defaults from `messages.dataTable.loading/failed/unauthorized` |
 | `children` | `ReactNode` | required — `DataPage.Columns` and optionally `DataPage.MenuItems` |
 | `queryArguments` | `TArguments` | forwarded to the query |
 | `dataKey` | `string \| undefined` | row identity; pass whenever the read model has one |
-| `selection` | `any \| undefined \| null` | controlled selection |
+| `selection` | `any \| undefined \| null` | controlled single selection |
+| `selectionMode` | `'single' \| 'multiple'` | default single |
+| `selectedItems` / `onSelectedItemsChange` | `TDataType[]` / `(items: TDataType[]) => void` | multiple selection; omit `selectedItems` for internal state |
 | `onSelectionChange` | `(event: DataTableSelectionChangeEvent<any>) => void` | `event.value` is the row or `null` |
 | `detailsComponent` | `React.FC<IDetailsComponentProps<any>>` | rendered beside the table for the selected row |
 | `globalFilterFields` | `string[] \| undefined` | enables the global search box over these fields |
 | `defaultFilters` | `DataTableFilterMeta` | initial per-column filter state |
-| `onRefresh` | `() => void` | invoked to re-fetch a snapshot query |
+| `onRefresh` | `() => void` | forwarded unchanged to details; DataPage never invokes it or refetches |
 | `actionsAriaLabel` | `string` | accessible name of the actions menubar, default `'Actions'` |
+| `globalSearchPlaceholder` / `globalSearchAriaLabel` | `string` | search copy and accessible name |
+| `paginatorClassName` / `paginatorAriaLabels` | class / label overrides | paginator presentation and localization |
 | `tableClassName` | `string` | class on the inner table |
 | `tablePt` | `DataTableParts` | per-part attributes on the inner data table (`tablePtOptions`/`tableUnstyled` are accepted no-ops) |
 | `menubarClassName` | `string` | class on the action menubar |
@@ -61,8 +66,14 @@ Three static members exist:
 There is no `observableQuery` prop. `DataPage` inspects the query prototype at
 render time: a snapshot query renders the snapshot table, anything else renders
 the observable table. Pass an observable query proxy and the page pushes
-updates automatically; pass a snapshot query and re-fetch through `onRefresh`
-after a command succeeds.
+updates automatically. There is no snapshot refresh handle on DataPage;
+`onRefresh` is only a caller-owned callback forwarded to the details component.
+Do not promise it will rerun the table's query.
+
+Until the first result, query tables show a loading row, not an empty row. Error
+and unauthorized results show a failure row; `empty-row` means a real empty
+result. While refreshing, the table marks `aria-busy`. Style status rows with
+`tablePt.loadingRow/loadingCell/failureRow/failureCell`.
 
 ## `MenuItemProps`
 
@@ -112,9 +123,10 @@ declaration the table reads.
 | `dataType` | `'text' \| 'numeric' \| 'date' \| 'boolean'` |
 | `showFilterMatchModes` | `boolean` |
 | `filterElement` | `(options: ColumnFilterElementOptions) => ReactNode` |
+| `filterOptions` | `{ label: string; value: unknown }[]` — list choices instead of a free-form input |
 | `filterLabels` | `Partial<ColumnFilterMenuLabels>` |
 | `filterPt` | `ColumnFilterMenuParts` — parts of the filter popup |
-| `selectionMode` | `'single'` — the only implemented value; there is no checkbox multi-selection |
+| `selectionMode` | `'single' \| 'multiple'` — selectors, including checkbox multi-selection |
 | `style` / `className` | `React.CSSProperties` / `string` |
 | `headerStyle` / `headerClassName` | `React.CSSProperties` / `string` |
 | `bodyStyle` / `bodyClassName` | `React.CSSProperties` / `string` |
@@ -128,10 +140,8 @@ Use `body` for a computed or formatted cell:
 ## Type name caution
 
 `ColumnProps` from `@cratis/components/DataPage` is the **column declaration**
-type re-exported from `DataTables` (the explicit named re-export shadows the
-`DataPage.Columns` wrapper's own `ColumnProps`, which is not reachable from the
-subpath). Import it from `@cratis/components/DataTables` when you want the
-reference to say so.
+type re-exported from `DataTables`. `ColumnsProps` is also exported from the
+DataPage subpath: it is the props type of the `DataPage.Columns` wrapper.
 
 ## Layout
 

package/package/corpus/skills/cratis-arc-react-page/references/data-tables.md

@@ -41,13 +41,17 @@ Both components take the same prop names:
 | Prop | Type | Notes |
 | --- | --- | --- |
 | `query` | `Constructor<TQuery>` | required |
-| `emptyMessage` | `string` | required |
+| `emptyMessage` | `string` | required; only for a real empty result |
+| `loadingMessage` / `failureMessage` / `unauthorizedMessage` | `ReactNode` | default `messages.dataTable.loading/failed/unauthorized` |
 | `children` | `ReactNode` | the `Column` declarations |
 | `queryArguments` | `TArguments` | forwarded to the query |
 | `dataKey` | `string \| undefined` | row identity |
-| `selection` | `TDataType \| undefined \| null` | controlled selection |
+| `selection` | `TDataType \| undefined \| null` | controlled single selection |
+| `selectionMode` | `'single' \| 'multiple'` | default single |
+| `selectedItems` / `onSelectedItemsChange` | `TDataType[]` / `(items: TDataType[]) => void` | checkbox multi-selection |
 | `onSelectionChange` | `(event: DataTableSelectionChangeEvent<TDataType>) => void` | `event.value` is the row or `null` |
 | `globalFilterFields` | `string[] \| undefined` | enables the search box |
+| `globalSearchPlaceholder` / `globalSearchAriaLabel` | `string` | search copy and accessible name |
 | `defaultFilters` | `DataTableFilterMeta` | initial filter state |
 | `className` | `string` | |
 | `pt` | `DataTableParts` | per-part attributes (`ptOptions`/`unstyled` are accepted no-ops) |
@@ -69,6 +73,10 @@ Both components take the same prop names:
 </DataTableForQuery>
 ```
 
+Query tables show loading until the first result, failure on error/unauthorized,
+and `empty-row` only for a real empty result. During refresh the table marks
+`aria-busy`; status parts are `loadingRow`, `loadingCell`, `failureRow`, `failureCell`.
+
 ## Paging, sorting and filtering scope
 
 Column sorting and filtering — and the search box — apply to the **currently
@@ -96,11 +104,17 @@ interface DataTableSelectionChangeEvent<TData> {
 Add a selection column with `<Column selectionMode='single' headerStyle={{ width: '3rem' }} />`
 when you want an explicit selector rather than row click selection.
 
+For checkboxes, use `selectionMode='multiple'` on the table and column, with
+`selectedItems` / `onSelectedItemsChange` (receives the array, not an event).
+Select-all covers only rows left visible by filtering, not unloaded pages;
+localize its name with `messages.dataTable.selectAllRows`.
+
 ## Column filtering
 
 Set `filter` on a column to get a per-column filter menu. `dataType` picks the
 match modes (`'text'`, `'numeric'`, `'date'`, `'boolean'`; default `'text'`),
-`showFilterMatchModes={false}` hides the mode picker, and `filterElement`
+`showFilterMatchModes={false}` hides the mode picker. `filterOptions` takes
+`{ label, value }[]` for list choices instead of free-form input; `filterElement`
 replaces the editor entirely:
 
 ```tsx

package/package/corpus/skills/cratis-arc-react-page/references/dialogs.md

@@ -85,6 +85,9 @@ The most-used props:
 | --- | --- |
 | `command` | the generated command class |
 | `title` | dialog header |
+| `subtitle` / `closeIcon` | secondary header content / dismissal glyph (`ReactNode`) |
+| `placement` | `'center' \| 'start' \| 'end'`; RTL-aware side sheets |
+| `confirmBeforeExecute` | `(values) => boolean \| Promise<boolean>`; pre-execution approval |
 | `okLabel` / `cancelLabel` | button labels (`'Ok'` / `'Cancel'` by default) |
 | `initialValues` | synchronous baseline; also the change-tracking baseline |
 | `currentValues` | reactive overlay for late-loading values |
@@ -99,6 +102,10 @@ The most-used props:
 | `dismissable` | X, Escape, and backdrop dismissal |
 | `pt` | `DialogParts` — per-part attributes (`backdrop`, `positioner`, `root`, `header`, `title`, `close`, `content`, `footer`, `confirm`, `cancel`); `ptOptions`/`unstyled` are accepted no-ops |
 
+Dialog presentation props, including `subtitle`, `placement` and `closeIcon`,
+are forwarded to the dialog (4.14.1+), not the form. `children` may also be a
+render function receiving the command form context (4.25.1+).
+
 `CommandDialog.Column` exists for multi-column layouts:
 
 ```tsx
@@ -114,8 +121,10 @@ The most-used props:
 
 ### Execution flow
 
-On confirm, `CommandDialog` applies `onBeforeExecute`, sets busy, executes the
-command, and on failure calls `onValidationFailure(result.validationResults)`
+On confirm, after validation, `CommandDialog` applies `onBeforeExecute` and
+awaits `confirmBeforeExecute` when supplied. Only `true` executes; fields are
+disabled while it is pending, and changed command values discard approval.
+The command then executes, and on failure calls `onValidationFailure(result.validationResults)`
 or `onFailed(result)` and **keeps the dialog open**. On success it calls
 `onSuccess(result.response)` and then the close gate.
 
@@ -174,7 +183,9 @@ selection — renaming a command property produces a compile error at every
 binding.
 
 `AutoCommandForm` renders a field per command property from the generated
-property descriptors, with `exclude` for the ones you do not want:
+property descriptors, with `exclude` for the ones you do not want and `footer`
+for custom footer content. Generated fields bind to their own property; this
+requires Arc and Arc React >=22.16.0:
 
 ```tsx
 <AutoCommandForm command={RegisterInvoice} exclude={['invoiceId']} />

package/package/corpus/skills/cratis-arc-react-page/references/from-screenplay.md

@@ -25,7 +25,12 @@ Three different claims are mixed in any "screen to page" mapping. Keep them apar
 | --- | --- | --- |
 | What each `screen`, `form` and interaction construct means | Verified | Screenplay `v4.66.0`: `Documentation/screenplay/{screens,forms,interactions}.md` |
 | What Stage does with a screen | Verified: it draws it through Scene, it does not write a React page | Stage `v4.24.0`: `Documentation/reference/stage-rendering.md` ("It does not generate screens for it"), `Documentation/reference/default-scene-composition.md` ("does not ... generate per-screen TypeScript components"), `Source/Contracts/Scene/ScreenDirectiveConverter.cs` (`data`, `action`, `section`, `title`, `table`, `summary` become Scene elements) |
-| Which Components and Arc API gives a page the same behavior | Verified API; the pairing is this skill's convention | `@cratis/components` `v4.6.0` (`DataPage`, `DataTables`, `CommandDialog`, `CommandForm`) and the sibling references |
+| Which Components and Arc API gives a page the same behavior | Verified API; the pairing is this skill's convention | `@cratis/components` `v4.26.4` (`DataPage`, `DataTables`, `CommandDialog`, `CommandForm`) and the sibling references |
+
+A hand-written Arc React page and a Scene-rendered screen are different surfaces;
+they share Components, not ownership or runtime APIs. Scene is the experimental
+UI model/runtime in Stage output; read `cratis-stage-rendering-and-sandbox`
+`references/scene-runtime.md` when inspecting that generated surface.
 
 So no product source maps a `.play` screen to an Arc React page. A hand-written
 page is a **gap-fill** (`cratis-screenplay-render-and-gap-fill`) with the `.play`

package/package/corpus/skills/cratis-arc-react-page/references/provenance.md

@@ -4,7 +4,7 @@ No TrogonStack text is adapted in this skill. Nebulit material is credited in th
 
 | Item | Source | Licence | Treatment | Where in this skill |
 |---|---|---|---|---|
-| Component APIs, props and hooks | Cratis Components 4.6.0 and Arc, see *Verified product sources* | MIT | original | SKILL.md, references/ |
+| Component APIs, props and hooks | Cratis Components 4.26.4 and Arc, see *Verified product sources* | MIT | original | SKILL.md, references/ |
 | Screenplay and Stage facts in the screen mapping | Cratis/Screenplay v4.66.0 and Cratis/Stage v4.24.0 documentation and source | MIT | original | references/from-screenplay.md |
 
 ## Adapted closely (Martin Dilger and Nebulit GmbH)

package/package/corpus/skills/cratis-arc-react-page/references/queries-and-commands.md

@@ -220,10 +220,20 @@ view model as `ICommandScope`. It exposes `hasChanges`, `isPerforming`,
 `execute()` (which runs only the commands that have changes), and
 `revertChanges()`.
 
+At Arc v22.75.0 `CommandForm` hides raw server exception text by default
+("An unexpected error occurred. Please try again."). Customize `exceptionMessage`
+or `exceptionDisplayComponent` (`ExceptionDisplayProps`); `showErrors={false}`
+hides built-in display. Dynamic accessors need `fieldName`; custom field validation
+failures block submit. `useIdentity(type)` deserializes typed details.
+Sources: `Source/JavaScript/Arc.React/Arc.tsx` and
+`commands/CommandForm/CommandForm.tsx` at v22.75.0.
+
 ## `<Arc>` configuration
 
 The top-level provider configures the microservice name, API base path, and
-query transport. Its props include `microservice`, `origin`, `basePath`,
+query transport. Verified at Arc v22.75.0: `basePath` is deprecated and does not
+configure routing; use `apiBasePath` for APIs, router basename for client routing
+and `UsePathBase` on the host. Its props include `microservice`, `origin`,
 `apiBasePath`, `httpHeadersCallback` (merged into every request — bearer and
 tenant headers), `detailsType`, `queryTransportMethod`, `queryConnectionCount`,
 `queryDirectMode`, `observableQueryTransferMode`, and `queryCacheRetentionMs`.

package/package/corpus/skills/cratis-arc-react-page/verification.json

@@ -9,6 +9,11 @@
     {
       "kind": "skill-contains",
       "value": "DataPage"
-    }
+    },
+    { "kind": "skill-contains", "value": "DataPage has no snapshot refresh handle" },
+    { "kind": "skill-contains", "value": "Mount exactly one toaster" },
+    { "kind": "skill-contains", "value": "4.26.4" },
+    { "kind": "skill-contains", "value": "checkbox multi-selection", "file": "references/data-tables.md" },
+    { "kind": "skill-contains", "value": "DataPage never invokes it or refetches", "file": "references/data-page.md" }
   ]
 }