@cratis/pi 7.37.0 → 7.38.1

package/package/corpus/harnesses/copilot/instructions/storybook.instructions.md

@@ -0,0 +1,85 @@
+---
+applyTo: "**/*.stories.tsx"
+profile: application
+paths:
+  - "**/*.stories.tsx"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# Storybook Story Conventions
+
+Stories are visual coverage and documentation for reusable React components built on Cratis Components — **not** the behavior test suite. Non-trivial view-model/helper behavior still needs BDD Vitest specs (see [frontend-testing.md](./frontend-testing.instructions.md)). Every story file is colocated with the component it covers.
+
+## When to write a story
+
+Write stories for **reusable components**: shared component-library primitives and slice-internal components reused across slices. Do **not** story live slice pages wired directly to Arc query/command hooks or a backend — exercise those in the running app. For a presentational view that needs visual coverage, extract it or render its presentational subcomponents with deterministic fixture props.
+
+Good candidates: a presentational card/list-item/form-field with multiple visual states; a component with hover/selected/disabled/error variants; anything reusable across slices.
+
+## Preview infrastructure (what you get for free)
+
+A configured `.storybook/preview` should wrap every story in `CratisComponentsProvider` (from `@cratis/components`) with `toaster` when stories show notifications. Import one `index.css` containing `@import '@cratis/components/tokens'`, `@import '@cratis/components/styles'` and (for the baseline look) `@import '@cratis/components/theme'`, each terminated by a semicolon — the same entries as the app. CSS imports from TypeScript need ambient declarations on TypeScript 6; keeping the subpaths in CSS avoids TS2882. Mount only one toaster. With that in place:
+
+- **Auto prop tables** via `react-docgen-typescript` — a component's `interface` + per-prop JSDoc renders as a Docs prop table, and union props become `select` controls automatically. Keep a JSDoc comment on every prop. **`argTypes` is an override layer** (change control type, group under `table.category`, disable a control) — don't re-list every prop.
+- **Accessibility panel** (`@storybook/addon-a11y`) scans each story with axe-core. Treat new violations as defects.
+
+## Meta block
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react';
+import { MyComponent } from './MyComponent';
+
+const meta = {
+    title: 'Components/MyComponent',          // sidebar path
+    component: MyComponent,
+    parameters: { layout: 'centered' },       // 'centered' | 'padded' | 'fullscreen'
+    tags: ['autodocs'],                       // always include
+} satisfies Meta<typeof MyComponent>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+```
+
+Use `satisfies Meta<typeof Component>` — never `: Meta<T>` (better inference). `layout`: `centered` for atoms, `padded` for compound/container components, `fullscreen` for layout shells.
+
+## Required stories
+
+Adapt depth to the component — rich for complex/stateful, trimmed for atoms:
+
+1. **`Playground`** — controllable: `args` for the happy path, all props tweakable. Use `fn()` from `storybook/test` for callbacks (not `() => {}`).
+2. **Showcase** — one or more `render:` stories covering the meaningful axes (`Variants`/`Tones`, `Sizes`, `States`, `WithIcons`). Use the Arc story-kit (`StoryContainer`, `StorySection`, `StoryGrid`, `StoryDivider`, `StoryBadge` from `@cratis/arc.react/stories`) for layout. Note: `StorySection` has no `label` prop (use an `<h3>` inside); `StoryGrid` has no `columns` prop (it auto-wraps).
+3. **`InContext`** — the component in a small realistic composition.
+4. **`Interactive`** — for **stateful** components: a local `const Demo: React.FC` owning `useState`, plus a `play:` test. **Omit for presentational atoms.**
+
+Add a one-line `/** … */` doc above each story; set `parameters.docs.description.component` on the meta.
+
+## Interaction tests (`play:`) — stateful components only
+
+```tsx
+import { expect, fn, userEvent, within } from 'storybook/test';
+
+export const Interactive: Story = {
+    render: () => <Demo />,
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await userEvent.click(canvas.getAllByRole('tab')[1]);
+        await expect(canvas.getAllByRole('tab')[1]).toHaveAttribute('aria-selected', 'true');
+    },
+};
+```
+
+- **Stateful only** — presentational atoms get no `play:`. Components' own overlay components (dialogs, dropdowns, toasts) are excluded — their behavior is the library's, not yours.
+- Prefer role/structure queries over localized text. `play:` runs in the Interactions panel (documentation/QA); the enforced behavioral gate is the Vitest spec.
+
+## Router-dependent components
+
+Wrap with `MemoryRouter` via a story decorator when a component uses `Link`/`useNavigate`.
+
+## Gate
+
+`build-storybook` should be green in CI — it compiles every story and `play:` function (catching broken imports/decorators) but does not execute play assertions.
+
+## See also
+
+- [react.md](./react.instructions.md) — component patterns; [components.md](./components.instructions.md) — component structure/styling.
+- [frontend-testing.md](./frontend-testing.instructions.md) — BDD Vitest specs (the behavioral gate).

package/package/corpus/harnesses/copilot/instructions/typescript.instructions.md

@@ -0,0 +1,151 @@
+---
+applyTo: "**/*.ts,**/*.tsx"
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+
+# TypeScript Conventions
+
+TypeScript's type system is the primary tool for catching bugs before they reach production. Every rule here pushes toward maximum compiler coverage and self-documenting code. If the types are right, the code almost writes itself.
+
+## Enums over Magic Strings
+
+String literal unions look concise but provide no refactoring support, no namespace, and no discoverability. Enums give you all three — plus `switch` exhaustiveness checking.
+
+```ts
+// ✅ Correct — refactorable, discoverable, exhaustive
+export enum SliceType {
+    StateChange = 'stateChange',
+    StateView   = 'stateView',
+    Automation  = 'automation',
+    Translator  = 'translator',
+}
+
+// ❌ Wrong — no refactoring support, invisible to tooling
+export type SliceType = 'stateChange' | 'stateView' | 'automation' | 'translator';
+```
+
+- Use enum members everywhere — `switch` cases, comparisons, defaults.
+- Do **not** import enums as `type`; they are values.
+- Export enums from `index.ts` without the `type` keyword.
+
+## One Type or Enum per File
+
+Each type gets its own file because it makes the codebase navigable — finding `SliceType` means opening `SliceType.ts`, not hunting through `types.ts`. It also keeps diffs clean and makes imports explicit.
+
+- Every interface, type alias, and enum lives in **its own file**, named after the type (e.g. `SliceType.ts`).
+- **Never create** `types.ts`, `models.ts`, `interfaces.ts` grab-bag files — they become dumping grounds that grow without limit.
+- Exception: component props interfaces (`*Props`) may live alongside their component `.tsx` file since they are tightly coupled to that component.
+- Aggregate exports through the folder's `index.ts`.
+
+## Type Safety
+
+`any` disables the compiler — the one tool that catches bugs for free. Every `any` is a hole in the safety net. Use `unknown` and narrow with type guards instead.
+
+- Never use `any` — use `unknown`, `Record<string, unknown>`, or proper generic constraints.
+- Prefer `value as unknown as TargetType` over `value as any`.
+- Use `unknown` as default generic parameter instead of `any`.
+- React synthetic events (`React.MouseEvent<Element, MouseEvent>`) and DOM events (`MouseEvent`) are different types — don't mix them.
+- **`int64`/`uint64` Chronicle fields generate as `bigint`** in the TypeScript proxies (not `number`, which silently truncated past `Number.MAX_SAFE_INTEGER`). Sequence numbers, large counters, and 64-bit ids surface as `bigint` — use `bigint` arithmetic, never `Number()`.
+
+## User-facing strings (localization)
+
+How user-visible text is handled is **product policy, not a Cratis framework rule** (see [general.md](../../../rules/general.md) — locales belong in a downstream app's own `.cratis/ai/`). Cratis itself has no mandatory i18n layer or `Strings` alias.
+
+- If the app has a localization convention (e.g. a translation object behind a `strings`/`Strings` import, or any i18n library), follow it consistently and keep raw string literals to constant, non-user-facing values (CSS class names, `key` props, internal identifiers).
+- If the app ships literal text, literal labels in JSX are fine.
+
+Either way, the Cratis-generic rule is only that strings are handled consistently within the app — not a specific file layout or import alias.
+
+## Arc Frontend Patterns
+
+Arc's proxy generator bridges C# and TypeScript automatically — every `[Command]` and `[ReadModel]` becomes a TypeScript class with `.use()` hooks, `.execute()` methods, and change tracking. This is the foundation of full-stack type safety: change a C# record and the TypeScript proxy updates on the next `dotnet build`.
+
+### Commands
+
+Auto-generated from C# `[Command]` records. The `.use()` hook returns a tuple: the command instance (with change tracking) and a setter for property values.
+
+```tsx
+const [command, setValues] = OpenAccount.use({ name: '', owner: '' });
+await command.execute();       // Sends command to backend, returns CommandResult
+await command.validate();      // Pre-flight validation only, no side effects
+command.hasChanges;            // True when any property differs from initial values
+command.revertChanges();       // Reset all properties to initial values
+```
+
+### Queries
+
+Auto-generated from C# `[ReadModel]` static query methods. Observable queries (returning `ISubject<T>` on the backend) auto-subscribe via WebSocket — the component re-renders when data changes on the server.
+
+```tsx
+const [result, perform] = AllProjects.use();
+// result.data — the query result
+// result.isPerforming — true while loading
+// result.hasData — true when data has arrived
+// result.isSuccess — true when query completed without errors
+```
+
+Paginated queries:
+```tsx
+const [result, , setPage] = AllProjects.useWithPaging(10);
+```
+
+### CommandScope
+
+Wraps multiple command-using components, aggregating their `hasChanges` state and enabling bulk `execute()` and `revertChanges()`. Useful for forms that span multiple components.
+
+### CommandForm
+
+Declarative form component with built-in field types, validation timing (`validateOn: blur|change|both`), and automatic server-side validation feedback.
+
+## Language — American English Only
+
+All identifiers, comments, JSDoc, and string literals must use **American English** spelling (initialize, serialize, behavior, color, organization, center, modeling, dialog, license, judgment, gray). See [general.md](../../../rules/general.md) for the full guidance.
+
+## Variables and Naming
+
+- Prefer `const` over `let` over `var` when declaring variables.
+- Never use shortened or abbreviated names for variables, parameters, or properties.
+  - Use full descriptive names: `deltaX` not `dx`, `index` not `idx`, `event` not `e`, `previous` not `prev`, `direction` not `dir`, `position` not `pos`, `contextMenu` not `ctx`/`ctxMenu`.
+  - The only acceptable short names are well-established domain terms (e.g. `id`, `url`, `min`, `max`).
+
+## Imports and Compilation
+
+- Never leave unused import statements in the code.
+- Always ensure that the code compiles without warnings — use `yarn compile` to verify (successful runs produce no output).
+- Review each file for lint compliance before finalizing.
+- Never use placeholder or temporary types — use proper types from the start.
+- **Never modify any file inside `node_modules/` or any build cache (e.g. `.vite/deps/`).** These are managed by the package manager and will be overwritten on the next install. If something appears broken in a library, look harder at the application code — especially when other usages of the same library work fine. Fixes belong in application code or upstream in the library's own repo.
+
+## Folder Structure
+
+- **Never give a `.tsx` the same basename as a `.ts` in the same folder.** The Arc proxy generator emits `<Slice>.ts` beside the slice's C#; a component named `<Slice>.tsx` next to it is **silently dropped from the program**: for one basename TypeScript keeps only the `.ts`, so the component's type errors are never reported and `tsc -b` stays green while the file is broken (reproduced on TypeScript 6.0.3 and 7.0.2 with `include: ["src/**/*"]`). At Arc v22.75.0 use `<CratisProxiesUseProxyFileSuffix>true</CratisProxiesUseProxyFileSuffix>` to emit `<Slice>.proxy.ts` with matching barrels; that is the clean generator fix. Otherwise name the component for what it renders (`Listing.tsx`, `RegisterAuthor.tsx`), never for the slice, and consider a repository spec that fails on any `.tsx` with a sibling `.ts` of the same name.
+- Do not prefix a file, component, type, or symbol with the name of its containing folder or the concept it belongs to. Instead, use folder structure to provide that context.
+- Favor functional folder structure over technical folder structure.
+  - Group files by the feature or concept they belong to, not by their technical role.
+  - Avoid folders like `components/`, `hooks/`, `utils/`, `types/` at the feature level.
+
+## Advanced Type Safety
+
+Additional patterns for common tricky scenarios:
+
+**Storybook:**
+- Use `React.ComponentType<Record<string, never>>` for components with no props.
+- Always use `as unknown as` when converting component imports to avoid type mismatch errors.
+- Properly type story args — never use `any`.
+
+**External libraries with strict generic constraints:**
+- Import necessary types (e.g. `Command` from `@cratis/arc/commands`) rather than asserting to `any`.
+- Use type assertions through `unknown`: `props.command as unknown as Constructor<Command<...>>`.
+- Extract tuple results explicitly rather than destructuring when type assertions are needed.
+- Use proper library types when available; use specific property types (e.g. `{ canvas?: HTMLCanvasElement }`) over `any`.
+
+**Dynamic and generic types:**
+- Add type guards for unknown function parameters: `if (typeof accessor !== 'function') return ''`.
+- Type parameters with fallbacks: `function<T = unknown>(accessor: ((obj: T) => unknown) | unknown)`.
+- Cast arrays from `unknown` explicitly: `((obj as Record<string, unknown>).items || []) as string[]`.
+- Use `String(value)` for string conversions in generic contexts.
+- Use explicit Date parameter types: `new Date(value as string | number | Date)`.

package/package/corpus/harnesses/copilot/instructions/verification-discipline.instructions.md

@@ -0,0 +1,27 @@
+---
+applyTo: "**/*"
+paths:
+  - "**/*"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# Verification Discipline
+
+Verification answers whether changed behavior works. It does not establish who
+authored a file or preserve a chain of evidence about how it arrived.
+
+- Run the narrowest relevant build, type check, lint, and specifications while iterating; explain when a wider gate is required before completion or push/PR.
+- Run one phase per command with its real exit status. Budget targeted checks around 120 seconds and build/test phases around 300 seconds; explain any longer budget first, and obtain explicit approval before a phase exceeds 600 seconds. Stop on a failure; do not blindly retry or repeat passing tests on unchanged inputs without a flaky-test hypothesis or required matrix.
+- Separate status/fetch from builds, Debug from Release, each test project, and frontend lint/compile/test/build. Do not combine these into an opaque command with a large outer timeout. Expose progress and cancellation; report the precise failed or timed-out phase and do not continue dependent phases after failure.
+- Never use `build/test | grep | sort/head/tail` as gate evidence. Capture the producer's exit status before summarising output; `pipefail` alone is insufficient with early-closing consumers such as `head`. Printed zero-error counts are not proof of success. Preserve needed full diagnostics in task-scoped `.ai-work/` logs rather than hiding them in `/tmp`.
+- Add a focused specification for every behavior or rejection rule you change.
+- Keep each check deterministic and runnable locally and in CI.
+- Never replace a real behavior check with a checksum, inventory, generated
+  receipt, or provenance record.
+- Documentary evidence — a receipt, ledger, attestation, hash inventory,
+  snapshot, escrow copy, or ad-hoc `verify-*` script — is not verification and
+  is not produced unless a repository workflow (such as a governed release) or
+  the user asks for it. The check's own output is the evidence.
+- Report the conclusion and any real uncertainty in a line or two, not the
+  audit trail. Show the output when asked, when a claim is contested, or when
+  the check failed. Report failures and skipped checks honestly.