mvc-kit 2.0.0 → 2.1.0

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

@@ -0,0 +1,242 @@
+# mvc-kit Framework Instructions
+
+This project uses **mvc-kit**, a zero-dependency TypeScript-first reactive state management library for React. Follow these rules strictly when writing or reviewing code.
+
+## Core Classes
+
+| Class | Role | Scope |
+|-------|------|-------|
+| `ViewModel<S, E?>` | Reactive state + computed getters + async tracking + typed events | Component-scoped (`useLocal`) |
+| `Model<S>` | Entity with validation + dirty tracking + commit/rollback | Component-scoped (`useModel`) |
+| `Collection<T>` | Reactive typed array, shared data cache, optimistic updates | Singleton |
+| `Service` | Stateless infrastructure adapter (HTTP, storage) | Singleton |
+| `EventBus<E>` | Typed pub/sub for cross-cutting events | Singleton |
+| `Channel<M>` | Persistent connection (WebSocket/SSE) with auto-reconnect | Singleton |
+| `Controller` | Stateless multi-ViewModel orchestrator (rare) | Component-scoped |
+
+## Imports
+
+```typescript
+import { ViewModel, Model, Collection, Controller, Service, EventBus, Channel } from 'mvc-kit';
+import { singleton, teardownAll, HttpError, isAbortError, classifyError } from 'mvc-kit';
+import { useLocal, useSingleton, useInstance, useModel, useField, useEvent, useEmit, useResolve, useTeardown, Provider } from 'mvc-kit/react';
+```
+
+## Architecture Rules
+
+1. **State = source of truth only.** No derived values, no loading/error flags in state interfaces.
+2. **Derived values are `get` accessors** on the ViewModel. Auto-memoized after `init()`.
+3. **Async status is automatic.** After `init()`, `vm.async.methodName` returns `{ loading, error, errorCode }`. Never store loading/error in state.
+4. **One ViewModel per component** via `useLocal`. No `useEffect` for data loading — use `onInit()`.
+5. **No `useState`/`useMemo`/`useCallback`** — the ViewModel is the hook.
+6. **Components are declarative.** Read `state.x` for raw, `vm.x` for computed, `vm.async.x` for loading/error.
+7. **Collections are encapsulated.** ViewModels subscribe via `subscribeTo()` in `onInit()`. Components never import Collections.
+8. **Services are stateless.** Accept `AbortSignal`, throw `HttpError`, no knowledge of ViewModels.
+9. **Pass `this.disposeSignal`** to every async call.
+10. **Lifecycle**: `construct → init() → use → dispose()`. Hooks auto-call `init()`.
+
+## ViewModel Pattern
+
+```typescript
+interface ItemState {
+  items: Item[];
+  search: string;
+}
+
+class ItemsViewModel extends ViewModel<ItemState> {
+  // --- Private fields ---
+  private service = singleton(ItemService);
+  private collection = singleton(ItemsCollection);
+
+  // --- Computed getters ---
+  get filtered(): Item[] {
+    const { items, search } = this.state;
+    if (!search) return items;
+    const q = search.toLowerCase();
+    return items.filter(i => i.name.toLowerCase().includes(q));
+  }
+
+  get total(): number { return this.state.items.length; }
+
+  // --- Lifecycle ---
+  protected onInit() {
+    this.subscribeTo(this.collection, () => {
+      this.set({ items: this.collection.items });
+    });
+    if (this.collection.length > 0) {
+      this.set({ items: this.collection.items });
+    } else {
+      this.load();
+    }
+  }
+
+  // --- Actions ---
+  async load() {
+    const data = await this.service.getAll(this.disposeSignal);
+    this.collection.reset(data);
+  }
+
+  // --- Setters ---
+  setSearch(search: string) { this.set({ search }); }
+}
+```
+
+**Section order:** Private fields → Computed getters → Lifecycle → Actions → Setters.
+
+## Component Pattern
+
+```tsx
+function ItemsPage() {
+  const [state, vm] = useLocal(ItemsViewModel, { items: [], search: '' });
+  const { loading, error } = vm.async.load;
+
+  return (
+    <div>
+      <input value={state.search} onChange={e => vm.setSearch(e.target.value)} />
+      {loading && <Spinner />}
+      {error && <ErrorBanner message={error} />}
+      <ItemsTable items={vm.filtered} />
+      <p>Showing {vm.filtered.length} of {vm.total}</p>
+    </div>
+  );
+}
+```
+
+## React Hooks
+
+| Hook | Usage |
+|------|-------|
+| `useLocal(Class, ...args)` | Component-scoped, auto-init/dispose. Returns `[state, instance]`. |
+| `useSingleton(Class, ...args)` | Singleton, shared state. Returns `[state, instance]`. |
+| `useInstance(subscribable)` | Subscribe to existing instance. Returns `state`. |
+| `useModel(factory)` | Model with `{ state, errors, valid, dirty, model }`. |
+| `useField(model, key)` | Single field: `{ value, error, set }`. |
+| `useEvent(source, event, handler)` | EventBus/ViewModel event subscription. |
+| `useEmit(bus)` | Stable emit function. |
+| `useResolve(Class)` | Resolve from Provider or singleton. |
+| `useTeardown(...Classes)` | Teardown singletons on unmount. |
+
+## Service Pattern
+
+```typescript
+class UserService extends Service {
+  async getAll(signal?: AbortSignal): Promise<User[]> {
+    const res = await fetch('/api/users', { signal });
+    if (!res.ok) throw new HttpError(res.status, res.statusText);
+    return res.json();
+  }
+}
+```
+
+## Collection Pattern
+
+```typescript
+class UsersCollection extends Collection<UserState> {}
+// Thin subclass. Query logic in ViewModel getters.
+```
+
+## Model Pattern
+
+```typescript
+class UserModel extends Model<UserFormState> {
+  setName(name: string) { this.set({ name }); }
+
+  protected validate(state: UserFormState) {
+    const errors: Partial<Record<keyof UserFormState, string>> = {};
+    if (!state.name.trim()) errors.name = 'Required';
+    return errors;
+  }
+}
+```
+
+## Sharing Patterns
+
+1. **Pattern A** (default): Parent ViewModel passes props to presentational children
+2. **Pattern B**: Singleton ViewModel via `useSingleton` for app-wide state
+3. **Pattern C**: Separate ViewModels sharing a singleton Collection
+
+## ViewModel Events
+
+```typescript
+interface SaveEvents { saved: { id: string }; error: void; }
+
+class ItemVM extends ViewModel<State, SaveEvents> {
+  async save() {
+    const result = await this.service.save(this.state.draft, this.disposeSignal);
+    this.emit('saved', { id: result.id }); // protected, type-safe
+  }
+}
+
+// Component
+useEvent(vm, 'saved', ({ id }) => toast.success(`Saved ${id}`));
+```
+
+## Optimistic Updates
+
+```typescript
+async toggleStatus(id: string) {
+  const rollback = this.collection.optimistic(() => {
+    this.collection.update(id, { status: 'done' });
+  });
+  try {
+    await this.service.update(id, { status: 'done' }, this.disposeSignal);
+  } catch (e) {
+    if (!isAbortError(e)) rollback();
+    throw e;
+  }
+}
+```
+
+## Error Handling Layers
+
+1. **Async tracking** (automatic): Write happy path, read `vm.async.method.error`
+2. **Imperative events** (explicit): try/catch + `emit()` + **re-throw**
+3. **Error classification** (services): `throw HttpError`, `classifyError()`
+
+## Testing
+
+```typescript
+beforeEach(() => teardownAll());
+
+test('example', () => {
+  const vm = new MyViewModel({ items: [], search: '' });
+  vm.init();
+  vm.setSearch('test');
+  expect(vm.filtered).toHaveLength(1);
+  vm.dispose();
+});
+```
+
+## Anti-Patterns — NEVER Do These
+
+- Loading/error flags in State → use `vm.async`
+- Derived state in State → use getters
+- `set()` inside a getter → infinite loop
+- `useEffect` for data loading → use `onInit()`
+- Multiple `useLocal` in one component → split components
+- Components importing Collections/Services → only ViewModel + hooks
+- Services holding state/cache → use Collections
+- Swallowing errors without re-throw → breaks async tracking
+- Manual try/catch for standard loads → async tracking handles it
+- Two-step setters with refilter calls → getters auto-recompute
+- Manual optimistic snapshot/restore → use `collection.optimistic()`
+- `useState`/`useMemo`/`useCallback` in connected components → ViewModel handles it
+
+## Decision Framework
+
+- Holds UI state for a component → **ViewModel**
+- Single entity with validation → **Model**
+- List of entities with CRUD → **Collection**
+- Fetches external data → **Service**
+- Cross-cutting events → **EventBus**
+- Persistent connection → **Channel**
+- Coordinates multiple ViewModels → **Controller** (rare)
+
+## Dev Mode
+
+```typescript
+// vite.config.ts
+define: { __MVC_KIT_DEV__: process.env.NODE_ENV !== 'production' }
+```
+
+Catches: `set()` inside getter, ghost async ops, method call after dispose, reserved key override.

package/agent-config/cursor/cursorrules

@@ -0,0 +1,242 @@
+# mvc-kit Framework Rules
+
+This project uses **mvc-kit**, a zero-dependency TypeScript-first reactive state management library for React. Follow these rules strictly when writing or reviewing code.
+
+## Core Classes
+
+| Class | Role | Scope |
+|-------|------|-------|
+| `ViewModel<S, E?>` | Reactive state + computed getters + async tracking + typed events | Component-scoped (`useLocal`) |
+| `Model<S>` | Entity with validation + dirty tracking + commit/rollback | Component-scoped (`useModel`) |
+| `Collection<T>` | Reactive typed array, shared data cache, optimistic updates | Singleton |
+| `Service` | Stateless infrastructure adapter (HTTP, storage) | Singleton |
+| `EventBus<E>` | Typed pub/sub for cross-cutting events | Singleton |
+| `Channel<M>` | Persistent connection (WebSocket/SSE) with auto-reconnect | Singleton |
+| `Controller` | Stateless multi-ViewModel orchestrator (rare) | Component-scoped |
+
+## Imports
+
+```typescript
+import { ViewModel, Model, Collection, Controller, Service, EventBus, Channel } from 'mvc-kit';
+import { singleton, teardownAll, HttpError, isAbortError, classifyError } from 'mvc-kit';
+import { useLocal, useSingleton, useInstance, useModel, useField, useEvent, useEmit, useResolve, useTeardown, Provider } from 'mvc-kit/react';
+```
+
+## Architecture Rules
+
+1. **State = source of truth only.** No derived values, no loading/error flags in state interfaces.
+2. **Derived values are `get` accessors** on the ViewModel. Auto-memoized after `init()`.
+3. **Async status is automatic.** After `init()`, `vm.async.methodName` returns `{ loading, error, errorCode }`. Never store loading/error in state.
+4. **One ViewModel per component** via `useLocal`. No `useEffect` for data loading — use `onInit()`.
+5. **No `useState`/`useMemo`/`useCallback`** — the ViewModel is the hook.
+6. **Components are declarative.** Read `state.x` for raw, `vm.x` for computed, `vm.async.x` for loading/error.
+7. **Collections are encapsulated.** ViewModels subscribe via `subscribeTo()` in `onInit()`. Components never import Collections.
+8. **Services are stateless.** Accept `AbortSignal`, throw `HttpError`, no knowledge of ViewModels.
+9. **Pass `this.disposeSignal`** to every async call.
+10. **Lifecycle**: `construct → init() → use → dispose()`. Hooks auto-call `init()`.
+
+## ViewModel Pattern
+
+```typescript
+interface ItemState {
+  items: Item[];
+  search: string;
+}
+
+class ItemsViewModel extends ViewModel<ItemState> {
+  // --- Private fields ---
+  private service = singleton(ItemService);
+  private collection = singleton(ItemsCollection);
+
+  // --- Computed getters ---
+  get filtered(): Item[] {
+    const { items, search } = this.state;
+    if (!search) return items;
+    const q = search.toLowerCase();
+    return items.filter(i => i.name.toLowerCase().includes(q));
+  }
+
+  get total(): number { return this.state.items.length; }
+
+  // --- Lifecycle ---
+  protected onInit() {
+    this.subscribeTo(this.collection, () => {
+      this.set({ items: this.collection.items });
+    });
+    if (this.collection.length > 0) {
+      this.set({ items: this.collection.items });
+    } else {
+      this.load();
+    }
+  }
+
+  // --- Actions ---
+  async load() {
+    const data = await this.service.getAll(this.disposeSignal);
+    this.collection.reset(data);
+  }
+
+  // --- Setters ---
+  setSearch(search: string) { this.set({ search }); }
+}
+```
+
+**Section order:** Private fields → Computed getters → Lifecycle → Actions → Setters.
+
+## Component Pattern
+
+```tsx
+function ItemsPage() {
+  const [state, vm] = useLocal(ItemsViewModel, { items: [], search: '' });
+  const { loading, error } = vm.async.load;
+
+  return (
+    <div>
+      <input value={state.search} onChange={e => vm.setSearch(e.target.value)} />
+      {loading && <Spinner />}
+      {error && <ErrorBanner message={error} />}
+      <ItemsTable items={vm.filtered} />
+      <p>Showing {vm.filtered.length} of {vm.total}</p>
+    </div>
+  );
+}
+```
+
+## React Hooks
+
+| Hook | Usage |
+|------|-------|
+| `useLocal(Class, ...args)` | Component-scoped, auto-init/dispose. Returns `[state, instance]`. |
+| `useSingleton(Class, ...args)` | Singleton, shared state. Returns `[state, instance]`. |
+| `useInstance(subscribable)` | Subscribe to existing instance. Returns `state`. |
+| `useModel(factory)` | Model with `{ state, errors, valid, dirty, model }`. |
+| `useField(model, key)` | Single field: `{ value, error, set }`. |
+| `useEvent(source, event, handler)` | EventBus/ViewModel event subscription. |
+| `useEmit(bus)` | Stable emit function. |
+| `useResolve(Class)` | Resolve from Provider or singleton. |
+| `useTeardown(...Classes)` | Teardown singletons on unmount. |
+
+## Service Pattern
+
+```typescript
+class UserService extends Service {
+  async getAll(signal?: AbortSignal): Promise<User[]> {
+    const res = await fetch('/api/users', { signal });
+    if (!res.ok) throw new HttpError(res.status, res.statusText);
+    return res.json();
+  }
+}
+```
+
+## Collection Pattern
+
+```typescript
+class UsersCollection extends Collection<UserState> {}
+// Thin subclass. Query logic in ViewModel getters.
+```
+
+## Model Pattern
+
+```typescript
+class UserModel extends Model<UserFormState> {
+  setName(name: string) { this.set({ name }); }
+
+  protected validate(state: UserFormState) {
+    const errors: Partial<Record<keyof UserFormState, string>> = {};
+    if (!state.name.trim()) errors.name = 'Required';
+    return errors;
+  }
+}
+```
+
+## Sharing Patterns
+
+1. **Pattern A** (default): Parent ViewModel passes props to presentational children
+2. **Pattern B**: Singleton ViewModel via `useSingleton` for app-wide state
+3. **Pattern C**: Separate ViewModels sharing a singleton Collection
+
+## ViewModel Events
+
+```typescript
+interface SaveEvents { saved: { id: string }; error: void; }
+
+class ItemVM extends ViewModel<State, SaveEvents> {
+  async save() {
+    const result = await this.service.save(this.state.draft, this.disposeSignal);
+    this.emit('saved', { id: result.id }); // protected, type-safe
+  }
+}
+
+// Component
+useEvent(vm, 'saved', ({ id }) => toast.success(`Saved ${id}`));
+```
+
+## Optimistic Updates
+
+```typescript
+async toggleStatus(id: string) {
+  const rollback = this.collection.optimistic(() => {
+    this.collection.update(id, { status: 'done' });
+  });
+  try {
+    await this.service.update(id, { status: 'done' }, this.disposeSignal);
+  } catch (e) {
+    if (!isAbortError(e)) rollback();
+    throw e;
+  }
+}
+```
+
+## Error Handling Layers
+
+1. **Async tracking** (automatic): Write happy path, read `vm.async.method.error`
+2. **Imperative events** (explicit): try/catch + `emit()` + **re-throw**
+3. **Error classification** (services): `throw HttpError`, `classifyError()`
+
+## Testing
+
+```typescript
+beforeEach(() => teardownAll());
+
+test('example', () => {
+  const vm = new MyViewModel({ items: [], search: '' });
+  vm.init();
+  vm.setSearch('test');
+  expect(vm.filtered).toHaveLength(1);
+  vm.dispose();
+});
+```
+
+## Anti-Patterns — NEVER Do These
+
+- Loading/error flags in State → use `vm.async`
+- Derived state in State → use getters
+- `set()` inside a getter → infinite loop
+- `useEffect` for data loading → use `onInit()`
+- Multiple `useLocal` in one component → split components
+- Components importing Collections/Services → only ViewModel + hooks
+- Services holding state/cache → use Collections
+- Swallowing errors without re-throw → breaks async tracking
+- Manual try/catch for standard loads → async tracking handles it
+- Two-step setters with refilter calls → getters auto-recompute
+- Manual optimistic snapshot/restore → use `collection.optimistic()`
+- `useState`/`useMemo`/`useCallback` in connected components → ViewModel handles it
+
+## Decision Framework
+
+- Holds UI state for a component → **ViewModel**
+- Single entity with validation → **Model**
+- List of entities with CRUD → **Collection**
+- Fetches external data → **Service**
+- Cross-cutting events → **EventBus**
+- Persistent connection → **Channel**
+- Coordinates multiple ViewModels → **Controller** (rare)
+
+## Dev Mode
+
+```typescript
+// vite.config.ts
+define: { __MVC_KIT_DEV__: process.env.NODE_ENV !== 'production' }
+```
+
+Catches: `set()` inside getter, ghost async ops, method call after dispose, reserved key override.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mvc-kit",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Zero-magic, class-based reactive ViewModel library",
   "type": "module",
   "main": "./dist/mvc-kit.cjs",
@@ -29,8 +29,12 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "agent-config"
   ],
+  "bin": {
+    "mvc-kit-setup": "./agent-config/bin/setup.mjs"
+  },
   "sideEffects": false,
   "scripts": {
     "dev": "vite",