mvc-kit 2.13.1 → 2.14.0

package/BEST_PRACTICES.md

@@ -986,11 +986,59 @@ class UserFormModel extends Model<UserFormState> {
 
 ### Models Inside ViewModels
 
-For forms with surrounding page state (submission, server errors), wrap the Model inside a ViewModel:
+For forms with surrounding page state (submission, server errors), wrap the Model inside a ViewModel. There are two shapes; the right choice depends on whether the form's initial data is already in hand:
+
+| If the initial data is... | Shape |
+|---|---|
+| **Available at construction** (create modal, edit modal receiving an entity prop) | Create the Model in the **constructor** as `readonly`. Non-nullable, no guard. |
+| **Fetched by ID** after mount (edit page that loads from the server) | Declare the Model as `\| null = null` and create it in `onInit()`. Component must guard. |
+
+**Never** write `public model!: FormModel` — the `!` definite-assignment assertion lies to TypeScript about runtime state. First render runs before `onInit()`, `vm.model` is undefined, and any component reading it crashes. Pick one of the two shapes below instead.
+
+#### Shape 1 — Data available at construction (preferred when applicable)
 
 ```typescript
 class EditUserViewModel extends ViewModel<EditState, EditEvents> {
-  public model!: UserFormModel;
+  // `readonly` refers to the *reference* — the model's state still changes via set().
+  public readonly model: UserFormModel;
+  private service = singleton(UserService);
+
+  constructor(initialState: EditState) {
+    super(initialState);
+    this.model = new UserFormModel(initialState.existing ?? INITIAL_FORM_STATE);
+  }
+
+  async save() {
+    if (!this.model.valid) return;
+    const result = await this.service.save(this.model.state, this.disposeSignal);
+    this.model.commit();
+    this.emit('saved', { id: result.id });
+  }
+
+  protected onDispose() {
+    this.model.dispose();
+  }
+}
+```
+
+The component — no guard needed; the model exists from the first render:
+
+```tsx
+function EditUserModal({ existing, onClose }: Props) {
+  const [, vm] = useLocal(EditUserViewModel, { existing });
+  const saveState = vm.async.save;
+
+  useEvent(vm, 'saved', onClose);
+
+  return <EditUserForm model={vm.model} onSave={vm.save} saving={saveState.loading} />;
+}
+```
+
+#### Shape 2 — Data fetched by ID
+
+```typescript
+class EditUserViewModel extends ViewModel<EditState, EditEvents> {
+  public model: UserFormModel | null = null;
   private service = singleton(UserService);
 
   protected async onInit() {
@@ -1000,7 +1048,7 @@ class EditUserViewModel extends ViewModel<EditState, EditEvents> {
   }
 
   async save() {
-    if (!this.model.valid) return;
+    if (!this.model || !this.model.valid) return;
     await this.service.update(this.userId, this.model.state, this.disposeSignal);
     this.model.commit();
     this.emit('saved', { id: this.userId });
@@ -1012,7 +1060,7 @@ class EditUserViewModel extends ViewModel<EditState, EditEvents> {
 }
 ```
 
-The component:
+The component — **must** guard on `vm.model` before rendering the form:
 
 ```tsx
 function EditUserPage() {
@@ -1388,3 +1436,4 @@ Components emit data attributes for CSS hooks — no class name opinions:
 - `Pending` as a ViewModel own property — it dies on unmount; put it on the singleton Resource
 - Passing `this.disposeSignal` to fetch inside Pending's execute callback — would abort on VM unmount, defeating resilience
 - Using `collection.optimistic()` rollback with Pending — snapshot goes stale during retries
+- Write `public model!: FormModel` or any other `!` definite-assignment / non-null assertion on a ViewModel / Model field — the `!` lies to TypeScript about runtime state. Either make the field non-nullable by creating it in the constructor, or declare it nullable and guard the component render. Same rule for non-null assertions on any nullable value (`foo!.bar`) — narrow or restructure instead.

package/agent-config/claude-code/agents/mvc-kit-architect.md

@@ -6,14 +6,14 @@ tools: Read, Grep, Glob, Bash
 memory: project
 color: blue
 skills:
-  - mvc-kit-guide
+  - mvc-kit
 ---
 
 You are an architecture planning agent for applications built with **mvc-kit**, a TypeScript-first reactive state management library for React. You help developers plan features by deciding which classes to create, designing state shapes, and selecting sharing patterns.
 
 ## Documentation
 
-The mvc-kit framework reference skill is preloaded into this agent's context. For deeper reference, read the supporting files in the mvc-kit skill directory (search for `.claude/skills/mvc-kit/` or `node_modules/mvc-kit/agent-config/claude-code/skills/guide/`):
+The mvc-kit framework reference skill is preloaded into this agent's context. For deeper reference, read the supporting files in the mvc-kit skill directory (search for `.claude/skills/mvc-kit/` or `node_modules/mvc-kit/agent-config/claude-code/skills/mvc-kit/`):
 
 - `api-reference.md` — Full API reference for all classes and hooks
 - `patterns.md` — Prescribed patterns with code examples

package/agent-config/claude-code/skills/{guide → mvc-kit}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: mvc-kit-guide
+name: mvc-kit
 description: "mvc-kit framework reference — class roles, architecture rules, React hooks, and decision framework. Use when working with mvc-kit imports or planning mvc-kit features."
 user-invocable: false
 ---
@@ -84,7 +84,7 @@ Most features combine multiple classes. These are the key composition patterns:
 
 - **Data table**: ViewModel + Collection/Resource + Sorting + Pagination + Selection → getter pipeline (`items → filtered → sorted → paged`). Always reset pagination when filters change.
 - **Infinite scroll / chat**: ViewModel + Feed + Service → cursor-based server pagination with `appendPage()`. Use `AbortSignal.any()` for per-call cancellation on rapid user interactions.
-- **Form with validation**: ViewModel creates Model in `onInit()`, disposes in `onDispose()`. Guard `save()` on `model.valid`. Call `model.commit()` after successful save.
+- **Form with validation**: ViewModel owns a Model. If the initial data is known at construction (create modal, edit modal with entity prop), declare the Model `readonly` and create it in the **constructor**. If the data is fetched by ID, declare it `| null = null` and create it in `onInit()` — the component must then guard with `if (!vm.model) return <Spinner />`. Never write `public model!: FormModel` (the `!` lies and crashes the first render). Dispose in `onDispose()`, guard `save()` on `model.valid`, commit after successful save. See Recipe 3 (known data) and Recipe 4 (fetched data).
 - **Two-tier events**: ViewModel `.emit()` for component reactions (navigate, show inline error). EventBus `.emit()` for app-wide side effects (toasts, analytics).
 - **Singleton with DEFAULT_STATE**: `static DEFAULT_STATE` lets `singleton()` and `useSingleton()` work without repeating initial state at every call site.
 

package/agent-config/claude-code/skills/{guide → mvc-kit}/anti-patterns.md

@@ -591,3 +591,50 @@ async deleteItem(id: string) {
   });
 }
 ```
+
+---
+
+## 26. Definite-Assignment Assertion (`!`) on a Model/ViewModel Field
+
+```typescript
+// BAD — `!` lies to TypeScript about runtime state.
+// First render runs before onInit(), so vm.model is undefined and useField/useModel crash.
+class EditVM extends ViewModel<EditState> {
+  public model!: FormModel;
+
+  protected onInit() {
+    this.model = new FormModel(this.state.existing);
+  }
+}
+
+// GOOD (data known at construction) — create in constructor, non-nullable
+class EditVM extends ViewModel<EditState> {
+  public readonly model: FormModel;
+
+  constructor(state: EditState) {
+    super(state);
+    this.model = new FormModel(state.existing ?? INITIAL);
+  }
+
+  protected onDispose() { this.model.dispose(); }
+}
+
+// GOOD (data fetched by ID) — declare nullable, guard in component
+class EditVM extends ViewModel<EditState> {
+  public model: FormModel | null = null;
+
+  protected async onInit() {
+    const entity = await this.service.getById(this.state.id, this.disposeSignal);
+    this.model = new FormModel(entity);
+  }
+
+  protected onDispose() { this.model?.dispose(); }
+}
+```
+
+```tsx
+// Component must guard for the nullable shape:
+if (!vm.model) return <Spinner />;
+```
+
+Extends to non-null assertions in general (`foo!.bar`, `arr[0]!`) — don't use `!` to paper over a nullable type when the real fix is either (a) make it non-nullable by construction, or (b) narrow it with a proper check. See Recipe 3 (known data) and Recipe 4 (fetched data).

package/agent-config/claude-code/skills/{guide → mvc-kit}/patterns.md

@@ -608,6 +608,17 @@ class UserFormModel extends Model<UserFormState> {
 const { state, errors, valid, dirty, model } = useModel(() => new UserFormModel({ name: '', email: '' }));
 ```
 
+### Model inside a ViewModel — two shapes
+
+| If the initial data is... | Shape |
+|---|---|
+| **Available at construction** (create modal, edit modal with entity prop) | `readonly model: FormModel;` + assign in constructor. Non-nullable, no guard. |
+| **Fetched by ID** after mount | `model: FormModel \| null = null;` + assign in `onInit()`. Component must guard with `if (!vm.model) return <Spinner />`. |
+
+**Never** write `public model!: FormModel`. The `!` definite-assignment assertion lies about runtime state: first render runs before `onInit`, so `vm.model` is `undefined`, and `useField`/`useModel` crash. Always either make the field non-nullable via constructor creation, or declare it nullable and guard.
+
+See Recipe 3 (known data) and Recipe 4 (fetched data) in [recipes.md](recipes.md).
+
 ---
 
 ## Testing Pattern

package/agent-config/claude-code/skills/{guide → mvc-kit}/recipes.md

@@ -240,9 +240,96 @@ function MessageThread({ conversationId }: { conversationId: string }) {
 
 ---
 
-## Recipe 3: Form with Model Validation
+## Choosing a Form Recipe
 
-ViewModel creates and owns a Model instance. Model handles validation, dirty tracking, commit/rollback. ViewModel handles async save.
+| If the form's initial data is... | Use |
+|---|---|
+| **Already available** at construction (create modal, edit modal receiving an entity prop, wizard step) | **Recipe 3** — Form with Known Initial Data |
+| **Fetched by ID** after mount (edit page that loads from the server) | **Recipe 4** — Form that Loads by ID |
+
+The distinction matters because Recipe 4 has a null guard and a lifecycle trap that Recipe 3 does not. Don't copy Recipe 4 when Recipe 3 applies — you'll write defensive code for a nullability you never needed.
+
+---
+
+## Recipe 3: Form with Known Initial Data
+
+The initial data is available when the ViewModel is constructed — passed through `useLocal`'s initial state, or known from a constant. The Model is created in the constructor, so it's non-nullable from the first render onward.
+
+```typescript
+interface EditState {
+  existing: AlertConfig | null;  // null → create mode, non-null → edit mode
+}
+
+interface EditEvents {
+  saved: { id: string };
+}
+
+class EditAlertConfigViewModel extends ViewModel<EditState, EditEvents> {
+  // `readonly` means the reference never changes — the model's *state* still changes via set().
+  public readonly model: AlertConfigFormModel;
+
+  private service = singleton(AlertConfigService);
+  private collection = singleton(AlertConfigsCollection);
+
+  constructor(initialState: EditState) {
+    super(initialState);
+    this.model = new AlertConfigFormModel(
+      initialState.existing
+        ? alertConfigToFormState(initialState.existing)
+        : INITIAL_FORM_STATE,
+    );
+  }
+
+  get canSave(): boolean {
+    return this.model.valid && this.model.dirty;
+  }
+
+  protected onDispose() {
+    this.model.dispose();
+  }
+
+  async save() {
+    if (!this.model.valid) return;
+    const result = this.state.existing
+      ? await this.service.update(this.state.existing.id, this.model.state, this.disposeSignal)
+      : await this.service.create(this.model.state, this.disposeSignal);
+    this.collection.upsert(result);
+    this.model.commit();
+    this.emit('saved', { id: result.id });
+  }
+}
+```
+
+```tsx
+function EditAlertConfigModal({ existing, onClose }: { existing: AlertConfig | null; onClose: () => void }) {
+  const [, vm] = useLocal(EditAlertConfigViewModel, { existing });
+  const { loading: saving } = vm.async.save;
+
+  useEvent(vm, 'saved', onClose);
+
+  // No `!vm.model` guard — the model exists from the first render.
+  return (
+    <form onSubmit={e => { e.preventDefault(); vm.save(); }}>
+      <ModelFields model={vm.model} />
+      <button disabled={!vm.canSave || saving}>
+        {saving ? 'Saving…' : 'Save'}
+      </button>
+    </form>
+  );
+}
+```
+
+**Key rules:**
+- Declare the field as `readonly model: FormModel` and assign it in the constructor — not `model!:` (the `!` would lie about runtime state)
+- Pair the constructor creation with `this.model.dispose()` in `onDispose()`
+- No null guard needed — the component never sees a half-initialized ViewModel
+- Re-create the ViewModel when the entity changes using `useLocal(..., [existing.id])` — the constructor re-runs with the new data
+
+---
+
+## Recipe 4: Form that Loads by ID
+
+The ViewModel only knows an ID at construction; the entity is fetched in `onInit()`. The Model is nullable until the fetch completes, and the component must guard its render.
 
 ```typescript
 interface ProfileState {
@@ -255,32 +342,25 @@ interface ProfileEvents {
 }
 
 class LocationProfileViewModel extends ViewModel<ProfileState, ProfileEvents> {
-  // Model is created dynamically after data loads — starts null
+  // Model is created after the fetch resolves — starts null, component must guard.
   public model: LocationFormModel | null = null;
 
   private service = singleton(LocationService);
   private collection = singleton(LocationsCollection);
   private bus = singleton(AppEventBus);
 
-  // --- Computed getters ---
-
   get canSave(): boolean {
     return this.model !== null && this.model.valid && this.model.dirty;
   }
 
-  // --- Lifecycle ---
-
   protected onInit() {
     this.load();
   }
 
   protected onDispose() {
-    // Model has its own lifecycle — must dispose
     this.model?.dispose();
   }
 
-  // --- Actions ---
-
   async load() {
     const location = await this.service.getById(this.state.locationId, this.disposeSignal);
 
@@ -303,7 +383,7 @@ class LocationProfileViewModel extends ViewModel<ProfileState, ProfileEvents> {
         this.disposeSignal,
       );
       this.collection.update(this.state.locationId, updated);
-      this.model.commit(); // Reset dirty state after successful save
+      this.model.commit();
       this.set({ location: updated });
       this.emit('saved', { id: updated.id });
       this.bus.emit('toast:show', { message: 'Location saved', severity: 'success' });
@@ -311,7 +391,7 @@ class LocationProfileViewModel extends ViewModel<ProfileState, ProfileEvents> {
       if (!isAbortError(e)) {
         this.bus.emit('toast:show', { message: 'Failed to save', severity: 'error' });
       }
-      throw e; // Re-throw so async tracking captures it
+      throw e;
     }
   }
 }
@@ -319,18 +399,19 @@ class LocationProfileViewModel extends ViewModel<ProfileState, ProfileEvents> {
 
 ```tsx
 function LocationProfile({ locationId }: { locationId: string }) {
-  const [state, vm] = useLocal(LocationProfileViewModel, { location: null, locationId });
-  const { loading: saving } = vm.async.save ?? {};
+  const [, vm] = useLocal(LocationProfileViewModel, { location: null, locationId });
+  const { loading: saving } = vm.async.save;
 
   useEvent(vm, 'saved', () => navigate('/locations'));
 
+  // Required: the model is created in onInit() after the fetch resolves.
   if (!vm.model) return <Spinner />;
 
   return (
     <form onSubmit={e => { e.preventDefault(); vm.save(); }}>
       <ModelFields model={vm.model} />
       <button disabled={!vm.canSave || saving}>
-        {saving ? 'Saving...' : 'Save'}
+        {saving ? 'Saving…' : 'Save'}
       </button>
     </form>
   );
@@ -338,16 +419,16 @@ function LocationProfile({ locationId }: { locationId: string }) {
 ```
 
 **Key rules:**
-- Model is created in `onInit()` (or after async load), disposed in `onDispose()` — **always pair create/dispose**
-- Guard `save()` with `model.valid` — never submit invalid data
-- Call `model.commit()` after successful save to reset dirty tracking
-- Use `model.rollback()` for cancel/discard
+- Declare the field as `model: FormModel | null = null` — not `model!:` (the `!` would lie about runtime state and crash `useField`/`useModel` on the first render)
+- Guard the form render with `if (!vm.model) return <Spinner />` — the model is undefined until `onInit` resolves
+- Dispose with `this.model?.dispose()` (optional chain — may never have been created on error paths)
+- Guard `save()` with `!this.model || !this.model.valid`
 - For large forms: use `useModelRef(factory)` + `useField(model, 'fieldName')` for surgical per-field re-renders
 - ViewModel events (`emit('saved')`) for navigation; EventBus for app-wide toasts
 
 ---
 
-## Recipe 4: Two-Tier Event System
+## Recipe 5: Two-Tier Event System
 
 ViewModel events are for "this instance did something" (component reactions). EventBus events are for "something happened app-wide" (toasts, analytics, navigation).
 
@@ -419,7 +500,7 @@ function ToastProvider() {
 
 ---
 
-## Recipe 5: Resource with Singleton DEFAULT_STATE
+## Recipe 6: Resource with Singleton DEFAULT_STATE
 
 Singleton ViewModels that share state across routes need `static DEFAULT_STATE` so `singleton()` and `useSingleton()` work without repeating initial state at every call site.
 
@@ -454,7 +535,7 @@ const [state, auth] = useSingleton(AuthViewModel);  // React (auto-init + subscr
 
 ---
 
-## Recipe 6: Error Handling with isAbortError
+## Recipe 7: Error Handling with isAbortError
 
 Async tracking handles errors automatically. Manual try/catch is only needed when you have **side effects** in the catch block (toasts, event emissions, collection rollbacks).
 

package/agent-config/claude-code/skills/{guide → mvc-kit}/testing.md

@@ -81,8 +81,9 @@ it('captures errors in async tracking', async () => {
 
   await vm.load().catch(() => {}); // Swallow the re-thrown error
 
-  expect(vm.async.load.error).toBeInstanceOf(Error);
-  expect(vm.async.load.error!.message).toBe('Network error');
+  // async.error is a string (message), not an Error. errorCode is the canonical code.
+  expect(vm.async.load.error).toBe('Network error');
+  expect(vm.async.load.errorCode).toBe('unknown');
 
   vm.dispose();
 });

package/agent-config/claude-code/skills/{review → mvc-kit-review}/checklist.md

@@ -166,16 +166,17 @@
 
 ---
 
-## Composition Checks (6)
+## Composition Checks (7)
 
 ### Critical
 1. **Model lifecycle pairing** — If a ViewModel creates a Model in `onInit()` or an action, it must dispose it in `onDispose()`.
+2. **No `!` definite-assignment or non-null assertion on a ViewModel/Model field** — `public model!: FormModel` lies to TypeScript about runtime state: first render runs before `onInit`, so `vm.model` is `undefined` and any component reading it crashes. Either (a) create the Model in the constructor so it's non-nullable (`readonly model: FormModel`, assigned in `constructor`), or (b) declare it nullable (`model: FormModel \| null = null`) and guard the component render with `if (!vm.model) return <Spinner />`. Same rule applies to non-null assertions on any other nullable field. See Recipe 3 (known data) and Recipe 4 (fetched data).
 
 ### Warning
-2. **Per-call cancellation for rapid interactions** — When users can switch contexts rapidly (conversations, search-as-you-type), use `AbortSignal.any([this.disposeSignal, controller.signal])` instead of `disposeSignal` alone.
-3. **Two-tier events** — ViewModel `.emit()` for component-scoped reactions (navigate, show error). EventBus `.emit()` for app-wide side effects (toasts, analytics). Don't use EventBus for single-component concerns.
-4. **Singleton DEFAULT_STATE** — Singleton ViewModels used with `useSingleton()` should have `static DEFAULT_STATE` to avoid repeating initial state at every call site.
-5. **Smart init** — `onInit()` should check `if (this.collection.length === 0)` before fetching to prevent re-fetching when component re-mounts and data is already loaded.
+3. **Per-call cancellation for rapid interactions** — When users can switch contexts rapidly (conversations, search-as-you-type), use `AbortSignal.any([this.disposeSignal, controller.signal])` instead of `disposeSignal` alone.
+4. **Two-tier events** — ViewModel `.emit()` for component-scoped reactions (navigate, show error). EventBus `.emit()` for app-wide side effects (toasts, analytics). Don't use EventBus for single-component concerns.
+5. **Singleton DEFAULT_STATE** — Singleton ViewModels used with `useSingleton()` should have `static DEFAULT_STATE` to avoid repeating initial state at every call site.
+6. **Smart init** — `onInit()` should check `if (this.collection.length === 0)` before fetching to prevent re-fetching when component re-mounts and data is already loaded.
 
 ### Suggestion
-6. **File naming convention** — Files should follow `{Name}{Role}.ts` pattern: `UsersViewModel.ts`, `UserService.ts`, `UsersCollection.ts`, `UsersResource.ts`, `LocationFormModel.ts`, `AppEventBus.ts`.
+7. **File naming convention** — Files should follow `{Name}{Role}.ts` pattern: `UsersViewModel.ts`, `UserService.ts`, `UsersCollection.ts`, `UsersResource.ts`, `LocationFormModel.ts`, `AppEventBus.ts`.

package/agent-config/copilot/copilot-instructions.md

@@ -179,6 +179,40 @@ class UserModel extends Model<UserFormState> {
 }
 ```
 
+### Model owned by a ViewModel — pick one of two shapes
+
+If the initial data is available at construction (create modal, edit modal receiving an entity prop):
+
+```typescript
+class EditUserVM extends ViewModel<{ existing: User | null }> {
+  public readonly model: UserModel;  // non-nullable — set in constructor
+
+  constructor(state: { existing: User | null }) {
+    super(state);
+    this.model = new UserModel(state.existing ?? INITIAL);
+  }
+
+  protected onDispose() { this.model.dispose(); }
+}
+```
+
+If the initial data is fetched by ID:
+
+```typescript
+class EditUserVM extends ViewModel<{ userId: string }> {
+  public model: UserModel | null = null;  // nullable — component must guard
+
+  protected async onInit() {
+    const user = await this.service.getById(this.state.userId, this.disposeSignal);
+    this.model = new UserModel(user);
+  }
+
+  protected onDispose() { this.model?.dispose(); }
+}
+```
+
+**Never** write `public model!: UserModel` — the `!` lies to TypeScript about runtime state and causes `useField`/`useModel` to crash on the first render with "Cannot read properties of undefined." Either make the Model non-nullable via constructor creation, or declare it nullable and guard the component with `if (!vm.model) return <Spinner />`.
+
 ## Composable Helpers Pattern
 
 Declare helpers as ViewModel instance properties. They have `subscribe()` so they're auto-tracked -- getters that read them recompute when helper state changes.

package/agent-config/cursor/cursorrules

@@ -179,6 +179,40 @@ class UserModel extends Model<UserFormState> {
 }
 ```
 
+### Model owned by a ViewModel — pick one of two shapes
+
+If the initial data is available at construction (create modal, edit modal receiving an entity prop):
+
+```typescript
+class EditUserVM extends ViewModel<{ existing: User | null }> {
+  public readonly model: UserModel;  // non-nullable — set in constructor
+
+  constructor(state: { existing: User | null }) {
+    super(state);
+    this.model = new UserModel(state.existing ?? INITIAL);
+  }
+
+  protected onDispose() { this.model.dispose(); }
+}
+```
+
+If the initial data is fetched by ID:
+
+```typescript
+class EditUserVM extends ViewModel<{ userId: string }> {
+  public model: UserModel | null = null;  // nullable — component must guard
+
+  protected async onInit() {
+    const user = await this.service.getById(this.state.userId, this.disposeSignal);
+    this.model = new UserModel(user);
+  }
+
+  protected onDispose() { this.model?.dispose(); }
+}
+```
+
+**Never** write `public model!: UserModel` — the `!` lies to TypeScript about runtime state and causes `useField`/`useModel` to crash on the first render with "Cannot read properties of undefined." Either make the Model non-nullable via constructor creation, or declare it nullable and guard the component with `if (!vm.model) return <Spinner />`.
+
 ## Composable Helpers Pattern
 
 Declare helpers as ViewModel instance properties. They have `subscribe()` so they're auto-tracked — getters that read them recompute when helper state changes.