@cratis/pi 7.36.1 → 7.38.0

package/package/corpus/product-sync.json

@@ -166,9 +166,9 @@
         }
       ],
       "synced": {
-        "version": "4.142.0",
+        "version": "4.144.0",
         "date": "2026-10-12",
-        "by": "Cratis/AI#597"
+        "by": "Cratis/AI#627"
       },
       "covers": {
         "skills": [
@@ -230,7 +230,8 @@
       },
       "covers": {
         "skills": [
-          "cratis-chronicle-hosting"
+          "cratis-chronicle-hosting",
+          "cratis-orleans-jobs"
         ],
         "rules": [
           "orleans.md"
@@ -384,6 +385,7 @@
           "cratis-code-review",
           "cratis-engineering-csharp-conventions",
           "cratis-fundamentals-concept",
+          "cratis-fundamentals-telemetry",
           "cratis-fundamentals-type-discovery"
         ],
         "rules": [
@@ -411,6 +413,8 @@
         "skills": [
           "cratis-arc-react-page",
           "cratis-components-accessibility",
+          "cratis-components-common-controls",
+          "cratis-components-data-surfaces",
           "cratis-components-schema-editor",
           "cratis-components-stepper-command-dialog",
           "cratis-components-styling",

package/package/corpus/rules/orleans.md

@@ -43,6 +43,10 @@ in its resilient storage pipeline.
 
 ## Co-host a silo with Cratis.Orleans
 
+For job/step authoring, stage barriers, recovery, storage scopes and state-machine
+APIs, load **cratis-orleans-jobs** from `cratis/engineering/csharp`. These APIs are
+framework/service guidance; they do not impose application slice architecture.
+
 For service authors, `Cratis.Orleans` supplies hosting, grain serializers, and the
 shared job system without requiring Chronicle. With `Cratis.Orleans` and
 `Cratis.Orleans.Storage.MongoDB` 1.16.3, this host uses durable MongoDB membership

package/package/corpus/rules/profiles.md

@@ -73,8 +73,8 @@ profile includes neither Screenplay nor Stage.
 |---|---|---|
 | `cratis/arc` | Arc CQRS framework | `cratis/arc/csharp`, `cratis/arc/java`, `cratis/arc/kotlin` |
 | `cratis/chronicle` | Chronicle event sourcing engine (does not compose `cratis/chronicle/mcp`) | `cratis/chronicle/compliance`, `cratis/chronicle/csharp`, `cratis/chronicle/elixir`, `cratis/chronicle/java`, `cratis/chronicle/kotlin`, `cratis/chronicle/multi-tenancy`, `cratis/chronicle/typescript`, `cratis/chronicle/web-workbench` |
-| `cratis/components` | React component library | (no child profiles) |
-| `cratis/fundamentals` | Core primitives (`ConceptAs<T>`, `EventSourceId<T>`) | (no child profiles) |
+| `cratis/components` | React component library, including `cratis-components-common-controls` and `cratis-components-data-surfaces` | (no child profiles) |
+| `cratis/fundamentals` | Core primitives and generated .NET telemetry (`cratis-fundamentals-telemetry`) | (no child profiles) |
 | `cratis/arc/go` | Experimental Arc.Go HTTP CQRS (root module) | `cratis/language/go`, `cratis/fundamentals/go` |
 | `cratis/chronicle/client-go` | Experimental standalone Chronicle.Go client | `cratis/language/go`, `cratis/fundamentals/go` |
 | `cratis/fundamentals/go` | Fundamentals.Go named scalar concepts and codecs | `cratis/language/go` |
@@ -86,7 +86,7 @@ profile includes neither Screenplay nor Stage.
 | Profile ID | Description | Automatically Includes |
 |---|---|---|
 | `cratis/engineering` | Engineering conventions and workflows | `cratis/engineering/core`, `cratis/engineering/csharp`, `cratis/engineering/elixir`, `cratis/engineering/go`, `cratis/engineering/kotlin`, `cratis/engineering/react`, `cratis/engineering/typescript` |
-| `cratis/engineering/csharp` | C# engineering conventions | `cratis/engineering/core` |
+| `cratis/engineering/csharp` | C# engineering conventions and framework Orleans jobs (`cratis-orleans-jobs`, alongside `orleans.md`) | `cratis/engineering/core` |
 | `cratis/engineering/go` | Go framework parity and immutable module releases | `cratis/engineering/core`, `cratis/language/go` |
 | `cratis/engineering/typescript` | TypeScript engineering conventions | `cratis/engineering/core` |
 | `cratis/engineering/react` | React engineering conventions | `cratis/engineering/core` |

package/package/corpus/skills/cratis-arc-observable-query-http/SKILL.md

@@ -136,6 +136,23 @@ Sources at v22.75.0: `Arc.Core/Queries/ObservableQueryHttp.cs`,
 `ObservableQueryHandler.cs` and
 [MongoDB observations](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/backend/csharp/mongodb/observing-collections.md).
 
+### Local `cratis` template ports
+
+Templates `v1.7.4` still publishes MongoDB on host port `27017` and configures
+`mongodb://localhost:27017` for the app (`Templates/Cratis/docker-compose.yml:3–13`,
+`appsettings.json:35–37`). Its Vite dev server runs on `9000` and proxies `/api`,
+`/.cratis` and `/swagger` to `http://localhost:5000`
+(`Templates/Cratis/.frontend/vite.config.ts:24–39`). A backend started on another
+port needs matching proxy targets; a healthy Chronicle container alone does not
+prove the browser can reach the app or its MongoDB read models.
+
+The bundled development MongoDB replica set advertises `localhost:27017`
+(Chronicle `v19.34.0`, `Docker/entrypoint.sh:23–25`). For that setup, merely changing
+Docker's host mapping to another port does not change the advertised member
+address. Keep `27017` available, or deliberately reconfigure the replica set and
+application connection together. These are local template defaults, not Arc
+requirements or production topology advice.
+
 ## What comes back
 
 Every transport carries the same `QueryResult` shape:

package/package/corpus/skills/cratis-arc-observable-query-http/verification.json

@@ -0,0 +1,12 @@
+{
+  "skill": "cratis-arc-observable-query-http",
+  "input": "Our local cratis template query is stuck Loading after changing the MongoDB and backend host ports. Which connections should we check?",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "Templates `v1.7.4`" },
+    { "kind": "skill-contains", "value": "mongodb://localhost:27017" },
+    { "kind": "skill-contains", "value": "http://localhost:5000" },
+    { "kind": "skill-contains", "value": "does not change the advertised member" },
+    { "kind": "skill-contains", "value": "local template defaults, not Arc" }
+  ]
+}

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

@@ -71,7 +71,11 @@ must move focus into itself.
   `@cratis/components`) above every Cratis component — it carries the locale,
   the Components-owned labels. Enable `toaster` (or mount one `<Toaster />`)
   for notifications; without it even `toastCommandResult` displays nothing.
-  Mount exactly one toaster, not both.
+  Mount exactly one toaster, not both. The `cratis` template already mounts
+  `<CratisComponentsProvider toaster>` **inside** `<Arc>` at Templates `v1.7.4`
+  (`Templates/Cratis/.frontend/main.tsx:12–19`); the missing-toaster/outside-Arc
+  workaround for `v1.7.2` no longer applies to that template version. Check an
+  older application's entry point rather than adding a second toaster.
 - The app must import the stylesheets explicitly; components do not import
   their own CSS:
 

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

@@ -12,6 +12,9 @@
     },
     { "kind": "skill-contains", "value": "DataPage has no snapshot refresh handle" },
     { "kind": "skill-contains", "value": "Mount exactly one toaster" },
+    { "kind": "skill-contains", "value": "<CratisComponentsProvider toaster>" },
+    { "kind": "skill-contains", "value": "Templates `v1.7.4`" },
+    { "kind": "skill-contains", "value": "rather than adding a second 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" }

package/package/corpus/skills/cratis-chronicle-client-kotlin/SKILL.md

@@ -247,8 +247,8 @@ store.eventLog.transactional.appendMany("<id>", listOf(<OtherEvent>()))
 unitOfWork.commit()
 ```
 
-`transactional` appends return `Unit`, not an `AppendResult`; the results are on
-the unit of work (`transactions/IUnitOfWork.kt:23-101`).
+In a unit of work, `transactional` appends return a placeholder `AppendResult`
+(sequence `-1`); real results are on the unit of work after `commit()`.
 
 ## Observing
 

package/package/corpus/skills/cratis-components-common-controls/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: cratis-components-common-controls
+description: Choose and bind Cratis Components ComboBox, ToggleGroup, Tabs, TagGroup and Breadcrumbs with controlled values, query states, keyboard semantics and localizable names. Use for entity pickers, exclusive choices, panel tabs, tag inputs or navigation trails. Do not use for Arc generated command fields, data tables, canvas palettes or theming.
+license: MIT
+---
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Common controlled controls
+
+## Verified product sources
+
+All claims and prop shapes are from **Cratis/Components v4.26.4**, source rather than unversioned examples.
+
+| Package | Version | Sources |
+| --- | --- | --- |
+| `@cratis/components` | `4.26.4` | `Source/Common/ComboBox.tsx:44-161,223-295`; `ToggleGroup.tsx:21-87,109-145`; `Tabs.tsx:23-79,91-132`; `TagGroup.tsx:49-145,155-260`; `Breadcrumbs.tsx:23-61,81-126` |
+| React | `^19.0.0` peer | `Source/package.json:319-340` |
+
+Imports are exported by `Source/Common/index.ts:11-15`; `Source/package.json:95-99` exposes the `Common` subpath. Use **cratis-components-styling** for the provider and CSS setup and **cratis-components-accessibility** for naming/focus. These controls do not replace Arc's generated `InputTextField`/other command fields; use **cratis-arc-react-page** for those bindings.
+
+## Choose the semantic control first
+
+| Need | Control | Controlled contract |
+| --- | --- | --- |
+| Pick one option, with search | `ComboBox` | `options: { key, label, description?, disabled? }[]`, `value: string \| null`, `onChange(key)` |
+| Choose one value from a small set | `ToggleGroup` | `options: { value, label, icon?, disabled? }[]`, `value: string`, `onChange(value)` |
+| Reveal a corresponding content panel | `Tabs` | `tabs: { id, label, content, disabled? }[]`, `value: string`, `onChange(id)` |
+| Add/remove string values | `TagGroup` | `value: string[]`, `onChange(nextValues)` |
+| Show where the page sits in navigation | `Breadcrumbs` | `items: { label, href?, onNavigate? }[]`, outermost first |
+
+`ToggleGroup` is a single-selection value choice with radio-group semantics and one Tab stop. `Tabs` supplies real panels and tab/panel relationships. Do not use panel-less tabs as a fancy radio group (`ToggleGroup.tsx:78-87`, `Tabs.tsx:70-79`).
+
+## 1. Bind a picker, not its display text
+
+A controlled presentation component; the caller owns the selected key and supplies approved/localized text. `inputValue` is a separate search draft, not the selected value.
+
+```tsx
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ComboBox, type ComboBoxOption } from '@cratis/components/Common';
+
+interface AccountPickerProps {
+    options: ComboBoxOption[];
+    value: string | null;
+    onChange: (key: string | null) => void;
+    label: string;
+    loading: boolean;
+    loadingMessage: string;
+    emptyMessage: string;
+}
+
+export const AccountPicker = (props: AccountPickerProps) => (
+    <ComboBox
+        options={props.options}
+        value={props.value}
+        onChange={props.onChange}
+        aria-label={props.label}
+        loading={props.loading}
+        loadingMessage={props.loadingMessage}
+        emptyMessage={props.emptyMessage}
+        openOnFocus
+    />
+);
+```
+
+The host loads options; ComboBox never fetches them. For server-filtered results, supply `inputValue`, `onInputChange` and `filter='none'`; the caller debounces/cancels requests and discards stale answers. Local `filter` defaults to `'contains'`; `'startsWith'` is also supported. Explicit open/focus shows all options rather than filtering to the selected label (`ComboBox.tsx:170-177,223-266`).
+
+Useful props (`:106-161`):
+
+- `failure: ReactNode` replaces options with failure content. `loading` shows `loadingMessage`; `emptyMessage` is for a genuine empty result. Do not map denied/failed loads to an empty list without an explanation.
+- `optionLayout='inline' | 'stacked'` controls secondary `description` placement.
+- `action={{ label, onAction }}` offers a footer action receiving the current input text. It **does not select or create an option for you**. The handler may return a promise, but the component fires it without awaiting; the caller owns busy/error handling (`:268-287`).
+- `required`, `invalid`, `errorMessage`, `description`, `disabled`, `readOnly`, `name` and `id` cover field state. `id` belongs to the input for `<label htmlFor>`. `name` carries the selected key, not search text (`:133-156`).
+
+## 2. Choose a value or a panel
+
+JSX binding excerpts inside an existing view. They assume caller-owned string values, change callbacks, and localized `labels` with the named properties:
+
+```tsx
+import { ToggleGroup, Tabs } from '@cratis/components/Common';
+
+<ToggleGroup
+    aria-label={labels.viewMode}
+    value={viewMode}
+    onChange={changeViewMode}
+    options={[
+        { value: 'compact', label: labels.compact },
+        { value: 'expanded', label: labels.expanded }
+    ]}
+/>
+
+<Tabs
+    aria-label={labels.details}
+    value={selectedTab}
+    onChange={changeTab}
+    tabs={[
+        { id: 'overview', label: labels.overview, content: overview },
+        { id: 'history', label: labels.history, content: history }
+    ]}
+/>
+```
+
+`ToggleGroup.onChange` receives a string, not a DOM event; selecting the already-selected value is ignored. `Tabs.onChange` also receives an ID string. Both offer `disabled`, accessible labeling, `className` and typed `pt` parts. ToggleGroup additionally exposes `invalid` and `aria-describedby` (`ToggleGroup.tsx:52-76,116-121`; `Tabs.tsx:51-68`). Do not infer route navigation from changing a tab; its job is revealing content.
+
+## 3. Add tags without confusing display with read-only
+
+JSX excerpt in a view with caller-owned `tags: string[]`, `changeTags`, and localized labels:
+
+```tsx
+import { TagGroup } from '@cratis/components/Common';
+
+<TagGroup
+    aria-label={labels.tags}
+    value={tags}
+    onChange={changeTags}
+    separators={[',', ';']}
+    removeLabel={tag => labels.removeTag.replace('{tag}', tag)}
+/>
+```
+
+TagGroup defaults to `editable=true`, comma separators and `allowDuplicates=false`. Enter or separators commit trimmed nonempty values; paste splits on separators. Empty-entry Backspace removes the last tag (`TagGroup.tsx:94-109,127-145,190-260`).
+
+**`editable=false` only removes the adding input; existing tags remain removable.** Use `disabled` when removal must also be unavailable, or a display-only surface for noninteractive tags. Supply `removeLabel(value)` for localized accessible names. `removeIcon` overrides that group's glyph (ahead of provider `icons.remove`) without changing the button's name or keyboard behavior (`TagGroup.tsx:54-91,155-190`). Prefer unique values: removal is value-keyed, so this is not an identity-preserving collection editor (`:139-140`).
+
+## 4. Build the breadcrumb trail from actual navigation
+
+JSX excerpt in a view whose `labels` are localized:
+
+```tsx
+import { Breadcrumbs } from '@cratis/components/Common';
+
+<Breadcrumbs
+    aria-label={labels.location}
+    items={[
+        { label: labels.home, href: '/' },
+        { label: labels.accounts, href: '/accounts' },
+        { label: labels.currentAccount }
+    ]}
+/>
+```
+
+Earlier entries can supply `href` or router-owned `onNavigate`. The last item is current: its destination/callback is suppressed and React Aria supplies `aria-current='page'`. Separators are decorative; `separator` accepts any React node (`Breadcrumbs.tsx:97-126`). Supply a distinct landmark name if a page has multiple trails. Breadcrumbs do not discover routes or enforce access.
+
+## Verify the binding
+
+Test caller state changes using the real payload shapes (key/string/string array), not invented `{ value }` events. Exercise null selection, query failure, disabled options, panel content, tag removal and the final breadcrumb. Browser-check keyboard/focus and accessible names. `pt` keys belong to each exported `*Parts` interface; style those parts rather than overriding internal React Aria markup. Do not add undocumented props to work around a failed interaction.

package/package/corpus/skills/cratis-components-common-controls/verification.json

@@ -0,0 +1,15 @@
+{
+  "skill": "cratis-components-common-controls",
+  "input": "Choose between a value toggle and panel tabs, wire a nullable entity picker and disable tag editing correctly.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "@cratis/components/Common" },
+    { "kind": "skill-contains", "value": "ComboBoxOption" },
+    { "kind": "skill-contains", "value": "inputValue" },
+    { "kind": "skill-contains", "value": "radio-group semantics" },
+    { "kind": "skill-contains", "value": "content: overview" },
+    { "kind": "skill-contains", "value": "existing tags remain removable" },
+    { "kind": "skill-contains", "value": "removeLabel" },
+    { "kind": "skill-contains", "value": "aria-current='page'" }
+  ]
+}

package/package/corpus/skills/cratis-components-data-surfaces/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: cratis-components-data-surfaces
+description: Compose Cratis Components PivotViewer exploration, TimeMachine historical snapshots, Canvas pan/zoom boards and public Chat conversation/sidebar surfaces. Use when a table is not the right presentation, when supplying Pixi-backed content, or when binding host-owned chat data and actions. Do not use for DataPage lists, backend event replay, chat persistence, canvas tool palettes or Scene authoring.
+license: MIT
+---
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Data beyond a table
+
+## Verified product sources
+
+All API and behavior claims below use **Cratis/Components v4.26.4**.
+
+| Package | Version | Source |
+| --- | --- | --- |
+| `@cratis/components` | `4.26.4` | `Source/PivotViewer/types.ts:67-112,145-187`; `Source/TimeMachine/{TimeMachine.tsx:19-65,types.ts:8-34}`; `Source/Canvas/{Canvas.tsx:38-104,CanvasItem.tsx:8-38,CanvasHandle.ts:7-21}`; `Source/Chat/{index.ts:4-40,ChatConversation.tsx:78-180,ChatSidebar.tsx:86-203}` |
+| `pixi.js` | `^8.20.0` optional peer | `Source/package.json:319-340`; required when using Canvas or PivotViewer |
+| React | `^19.0.0` peer | `Source/package.json:319-340` |
+
+Subpath exports: `Source/package.json:60-69,155-159,178-182`; each area's `index.ts` exports the types used below. Load **cratis-components-styling** for CSS/provider setup and **cratis-components-accessibility** for localized names. For tabular queries use **cratis-arc-react-page**; for a board tool palette use **cratis-components-toolbar**.
+
+These are **presentation contracts**. The host owns loading, access control, data acquisition and persistence. A historical slider is not event replay; a chat send callback is not a durable write.
+
+## Choose the surface
+
+| Surface | Fit | Avoid assuming |
+| --- | --- | --- |
+| `PivotViewer` | Faceted card exploration of an already-loaded collection | Server paging, JSX card rendering or controlled selection |
+| `TimeMachine` | Supplied historical snapshots and event descriptions | Fetching history, rebuilding a read model or a controlled current index |
+| `Canvas` | A pan/zoom board combining DOM items and optional Pixi objects | That moving the camera persists item positions |
+| `ChatConversation` / `ChatSidebar` | Host-owned messages, topic selection and actions | Automatic message persistence, authorization or topic naming |
+
+Keep Canvas/PivotViewer behind their subpath imports so ordinary pages do not acquire a Pixi import edge. Install/deduplicate the optional `pixi.js` peer for these areas, including a DOM-only Canvas: `Canvas.tsx:176` initializes Pixi through `usePixiApplication`. Do not rely on the word "optional" to omit it when importing those areas.
+
+## 1. PivotViewer: data and text cards, not React cards
+
+`data`, `dimensions` and `cardRenderer` are required. Each dimension has `key`, `label`, `getValue`; optional `formatValue` and `sort` control group presentation. **`cardRenderer` returns structured text, not JSX**. `detailRenderer(item, onClose)` may return a React node (`PivotViewer/types.ts:67-78,145-163`).
+
+This component accepts loaded domain data; its labels come from the host's localization layer:
+
+```tsx
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PivotViewer } from '@cratis/components/PivotViewer';
+
+interface CatalogItem {
+    id: string;
+    name: string;
+    category: string;
+}
+
+interface CatalogExplorerProps {
+    items: CatalogItem[];
+    categoryLabel: string;
+    loadingLabel: string;
+    isLoading: boolean;
+}
+
+export const CatalogExplorer = (props: CatalogExplorerProps) => (
+    <PivotViewer<CatalogItem>
+        data={props.items}
+        dimensions={[{ key: 'category', label: props.categoryLabel, getValue: item => item.category }]}
+        getItemId={item => item.id}
+        cardRenderer={item => ({ title: item.name, values: [item.category] })}
+        searchFields={[item => item.name]}
+        isLoading={props.isLoading}
+        loadingLabel={props.loadingLabel}
+    />
+);
+```
+
+Other substantial props (`types.ts:93-112,145-185`):
+
+- `filters` accepts keyed facets with `label` and `getValue`. Optional `options` are `{ key, label, value, count }`; otherwise they are computed from data. Numeric `type='number'` supports a range/histogram with `buckets`; `renderEditor` replaces a facet editor.
+- `defaultDimensionKey` initializes grouping. Group/filter/selection state is internal; there is no `selectedItem`/`onSelectedItemChange` prop at this tag (`PivotViewer.tsx:54-112`).
+- `searchFields` are property accessors. Use direct property paths, not computed expressions: the implementation extracts paths from accessor source (`types.ts:23-29`, `utils/search.ts`).
+- `emptyContent`, `isLoading`, `loadingLabel`, `labels` and `colors` control presentation. Use the exported `PivotViewerLabels` shape for localization; do not put DOM markup in a text-card result.
+
+Bound the dataset in the host. A worker and virtualized rendering do not make loading an unbounded collection a safe query shape (`PivotViewer.tsx:152-165`). Test actual browser rendering, resizing, zoom and keyboard behavior; a server-rendered shell does not exercise Pixi.
+
+## 2. TimeMachine: prepare history before rendering
+
+`Version` is `{ id: string, timestamp: Date, label: string, content: ReactNode, events?: Event[] }`. `Event` is `{ sequenceNumber: number, type: string, occurred: Date, content: Record<string, unknown> }`; it is a presentation DTO, not a Chronicle client object (`TimeMachine/types.ts:8-34`). Supply versions in the intended history order.
+
+Binding excerpt for an existing view with `versions: Version[]`, a caller-owned `onVersionSelected(index)` callback and translated `timelineLabels: Partial<TimeMachineLabels>`:
+
+```tsx
+import { TimeMachine } from '@cratis/components/TimeMachine';
+
+<TimeMachine
+    versions={versions}
+    currentVersionIndex={0}
+    onVersionChange={onVersionSelected}
+    labels={timelineLabels}
+/>
+```
+
+**`currentVersionIndex` is initial-only**. Later prop changes do not replace internal selection. `onVersionChange(index)` reports timeline/wheel/previous/next selection; `scrollSensitivity` defaults to 50. The component offers read-model and event views over supplied data (`TimeMachine.tsx:19-65,73-125,133-145`). Do not promise an externally controlled scrubber or backend replay.
+
+Load only authorized, redacted history. The presence of an event payload in this display is not permission to reveal it, and snapshot content is host-supplied React content. Exercise both modes and localization with the real DTOs.
+
+## 3. Canvas: distinguish camera, DOM items and Pixi data
+
+DOM content belongs in `Canvas` children. Position measured items with `CanvasItem x/y`, optional stable `id`, and optional `zIndex` on the item root (nested z-index cannot escape its stacking context). The item registry feeds minimap measurements (`CanvasItem.tsx:8-42,65-95`).
+
+```tsx
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Canvas, CanvasItem } from '@cratis/components/Canvas';
+
+export const Board = () => (
+    <Canvas style={{ height: '32rem' }} showMinimap minimapWorldWidth={1600} minimapWorldHeight={1200}>
+        <CanvasItem id='first-card' x={100} y={80}>
+            <article>First card</article>
+        </CanvasItem>
+    </Canvas>
+);
+```
+
+The literal card text is illustrative; use the host's approved/localized content. Give the board visible dimensions. For Pixi items, supply `items: T[]` extending `CanvasItemData` and `renderItem(item): PIXI.Container`; `onItemPointerDown` reports item activation, `onReady` receives `CanvasContext` (`Canvas.tsx:38-50`). Do not return React nodes from `renderItem`.
+
+Camera/controls contract (`Canvas.tsx:51-104,119-160`, `CanvasHandle.ts:7-21`):
+
+- `initialZoom` and `initialPan` are initial values, not a controlled camera. `onTransformChange(zoom, pan)` reports movement. Use `onHandleReady` and `CanvasHandle.smoothPanToWorld`/`smoothPanZoomToWorld` for navigation; `getContainerRect` and `getItemBounds` measure it.
+- `minZoom`/`maxZoom` default to 0.1/5. `showControls` defaults true; `showMinimap` false. `minimapItems` can replace registry-derived rectangles.
+- `controlsPlacement` is `'bottom-left' | 'bottom-right'`; `controlsLabels` and `controlsIcons` are typed override objects. `controlsFollowViewportInsets` defaults true, stepping aside by `--canvas-viewport-left/right`. Set false when the host already offsets the whole canvas, or the inset is applied twice.
+- `readOnly` absorbs content interaction but leaves pan/zoom available. `backgroundDragPans=false` lets a product own background drag selection while wheel/middle-button/touch panning remain available.
+
+Persist item edits in the host, not in camera callbacks. Browser-test gestures and dimensions. For jsdom tests provide a `ResizeObserver` substitute where required; Pixi integration still needs a real browser signal.
+
+## 4. Public Chat: bind the host's messages and outcomes
+
+The public `@cratis/components/Chat` exports **`ChatConversation`**, **`ChatSidebar`**, **`ChatSidebarForObservableQueries`**, **`ChatTopicList`** and their types. It does **not** export the Kit `Chat` component or expose a `Chat/Kit` package subpath (`Source/Chat/index.ts:4-40`, `Source/package.json`). **`Chat` is exported through `@cratis/components/Canvas`** via the Kit barrel (`Source/Canvas/index.ts:37-40`, `Source/Chat/Kit/index.ts:4-26`). Prefer the non-spatial Chat subpath for ordinary host-data conversations; importing Canvas brings its Pixi edge.
+
+The Kit `Chat` has a different contract: required `messages`, `onSend(text)` and `onClose`; optional `variant`, `typingAuthors`, `currentUserId`, `onReact(messageId, emoji)`, `onAct(messageId)`, `canAct` and nested `labels`. Its messages use the Kit `ChatMessage` shape, not the public Chat subpath's message type. Reactions need both `currentUserId` and `onReact`. An optional `id` additionally publishes `ChatMessageAdded` over an available Arc messenger at send time, not after persistence succeeds (`Source/Chat/Kit/Chat.tsx:58-135`, `ChatMessage.ts`). Never count that notification as durable delivery, or mix `onSend` with the public conversation's `onSendMessage`.
+
+The public `ChatMessage` has `id`, `topicId`, `authorId`, `body`, `timestamp: Date`, optional `mentions` and `metadata`. Identifiers use `ChatIdentifier`; resolve authors through `authorOf`, not an invented `authorName` property (`ChatMessage.ts:17-37`, `ChatConversation.tsx:78-127`).
+
+Complete presentation wrapper using the real public types:
+
+```tsx
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    ChatConversation, ChatStatus,
+    type ChatConversationLabels, type ChatMention, type ChatMessage
+} from '@cratis/components/Chat';
+
+interface ConversationProps {
+    messages: ChatMessage[];
+    status: ChatStatus;
+    labels: ChatConversationLabels;
+    send: (body: string, mentions: ChatMention[]) => void;
+}
+
+export const Conversation = (props: ConversationProps) => (
+    <ChatConversation
+        messages={props.messages}
+        status={props.status}
+        labels={props.labels}
+        onSendMessage={props.send}
+    />
+);
+```
+
+`onSendMessage` reports the trimmed body and mentions; persistence is the host's responsibility. Supply fresh authorized data after command success. Handle failure visibly rather than adding a fabricated message that looks saved.
+
+`ChatStatus.Ready/Loading/Failed/Unauthorized` distinguish query outcomes. Existing messages remain during loading/failure; unauthorized replaces them and disables the composer (`ChatStatus.ts:5-14`, `ChatConversation.tsx:85`). This is UI behavior, not backend enforcement.
+
+Additional public contracts:
+
+- `actions` are typed `ChatMessageAction<TMessage>[]`; `renderMessageExtra(message)` supplies reaction/failure/detail content under the body. `mentionCandidates` or `resolveMentionCandidates` supplies available mentions (`ChatConversation.tsx:121-180`).
+- `ChatSidebar` requires `open`, `onClose`, `topics`, `messages`, and `onSendMessage(topicId, body, mentions)`. `topicActions` is separate from inherited message `actions`; `renderHeaderActions(openTopic)` belongs to the sidebar (`ChatSidebar.tsx:86-163`).
+- `selectedTopicId` is controlled when provided: ID opens a topic, null shows the list, omission uses internal selection. `onTopicSelected` reports selection. `topicsStatus` and `messagesStatus` are separate; do not show one topic's cached messages while another topic is loading (`:123-142`).
+- `onStartTopic` returns a created identifier or undefined, optionally in a promise. `onRequestTopicName` asks the host to name an unnamed topic after its first message. Neither creates/saves/names anything on its own (`:144-180`).
+- The sidebar defaults non-modal, right edge, `24rem`; `position`, `width`, `modal`, `labels`, and typed `pt` customize it (`:182-203`).
+
+## Verify the surface, not only the props
+
+Test host orchestration separately from Components: loading/failed/denied vs empty, stable IDs, data ordering, and persistence errors. Browser-check interaction/focus and all visible/localized labels. Do not infer remote fetch, tenant isolation, history reconstruction or message delivery from a rendered surface or a passing type check.

package/package/corpus/skills/cratis-components-data-surfaces/verification.json

@@ -0,0 +1,16 @@
+{
+  "skill": "cratis-components-data-surfaces",
+  "input": "Present loaded faceted data, history snapshots, a pan/zoom board and host-owned chat without inventing persistence.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "cardRenderer` returns structured text, not JSX" },
+    { "kind": "skill-contains", "value": "currentVersionIndex` is initial-only" },
+    { "kind": "skill-contains", "value": "CanvasItem" },
+    { "kind": "skill-contains", "value": "controlsFollowViewportInsets" },
+    { "kind": "skill-contains", "value": "pixi.js" },
+    { "kind": "skill-contains", "value": "Chat` is exported through `@cratis/components/Canvas`" },
+    { "kind": "skill-contains", "value": "onSendMessage" },
+    { "kind": "skill-contains", "value": "renderHeaderActions(openTopic)" },
+    { "kind": "skill-contains", "value": "not backend enforcement" }
+  ]
+}