mvc-kit 2.13.0 → 2.13.1

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

@@ -21,7 +21,12 @@ The mvc-kit framework reference skill is preloaded into this agent's context. Fo
 - `recipes.md` — Composition recipes for real-world features
 - `testing.md` — Testing patterns
 
-For detailed per-class documentation, search the `.md` files colocated with source in `node_modules/mvc-kit/src/`.
+For deep dives on any specific class or hook, search for the `.md` file by name in `node_modules/mvc-kit/src/`:
+
+- **Core:** `ViewModel.md`, `Model.md`, `Collection.md`, `PersistentCollection.md`, `Resource.md`, `Service.md`, `EventBus.md`, `Channel.md`, `Controller.md`, `Trackable.md`, `singleton.md`
+- **Helpers:** `Sorting.md`, `Pagination.md`, `Selection.md`, `Feed.md`, `Pending.md`, `produceDraft.md`
+- **React hooks:** `react/use-local.md`, `react/use-instance.md`, `react/use-singleton.md`, `react/use-model.md`, `react/use-event-bus.md`, `react/use-teardown.md`
+- **Components:** `react/components/DataTable.md`, `react/components/CardList.md`, `react/components/InfiniteScroll.md`
 
 ## Core Classes
 

package/agent-config/claude-code/skills/guide/SKILL.md

@@ -97,3 +97,12 @@ For full composition recipes with code, see [recipes.md](recipes.md).
 - [anti-patterns.md](anti-patterns.md) — Anti-patterns to reject with fixes
 - [recipes.md](recipes.md) — Composition recipes for real-world features
 - [testing.md](testing.md) — Testing patterns (teardownAll, async assertions, memoization verification)
+
+### Per-Class Documentation (in `node_modules/mvc-kit/src/`)
+
+For deep dives on any specific class or hook, search for the `.md` file by name:
+
+- **Core:** `ViewModel.md`, `Model.md`, `Collection.md`, `PersistentCollection.md`, `Resource.md`, `Service.md`, `EventBus.md`, `Channel.md`, `Controller.md`, `Trackable.md`, `singleton.md`
+- **Helpers:** `Sorting.md`, `Pagination.md`, `Selection.md`, `Feed.md`, `Pending.md`, `produceDraft.md`
+- **React hooks:** `react/use-local.md`, `react/use-instance.md`, `react/use-singleton.md`, `react/use-model.md`, `react/use-event-bus.md`, `react/use-teardown.md`
+- **Components:** `react/components/DataTable.md`, `react/components/CardList.md`, `react/components/InfiniteScroll.md`

package/agent-config/lib/install-claude.mjs

@@ -80,8 +80,14 @@ user-invocable: false
 - [recipes.md](recipes.md) — Composition recipes for real-world features
 - [testing.md](testing.md) — Testing patterns (teardownAll, async assertions, memoization verification)
 
-For detailed per-class documentation, read the \`.md\` files colocated with source in:
-\`node_modules/mvc-kit/src/\`
+### Per-Class Documentation (in \`node_modules/mvc-kit/src/\`)
+
+For deep dives on any specific class or hook, search for the \`.md\` file by name:
+
+- **Core:** \`ViewModel.md\`, \`Model.md\`, \`Collection.md\`, \`PersistentCollection.md\`, \`Resource.md\`, \`Service.md\`, \`EventBus.md\`, \`Channel.md\`, \`Controller.md\`, \`Trackable.md\`, \`singleton.md\`
+- **Helpers:** \`Sorting.md\`, \`Pagination.md\`, \`Selection.md\`, \`Feed.md\`, \`Pending.md\`, \`produceDraft.md\`
+- **React hooks:** \`react/use-local.md\`, \`react/use-instance.md\`, \`react/use-singleton.md\`, \`react/use-model.md\`, \`react/use-event-bus.md\`, \`react/use-teardown.md\`
+- **Components:** \`react/components/DataTable.md\`, \`react/components/CardList.md\`, \`react/components/InfiniteScroll.md\`
 `;
 
   writeFileSync(join(guideDir, 'SKILL.md'), skillContent, 'utf-8');

package/examples/primitive/channel.ts

@@ -0,0 +1,109 @@
+import { Channel, singleton, teardownAll } from 'mvc-kit';
+import type { ChannelStatus } from 'mvc-kit';
+
+// Channel: Persistent connection with auto-reconnect and typed messages
+//
+// Extend Channel<MessageMap> and implement two abstract methods:
+//   open(signal)  — establish the connection (WebSocket, SSE, etc.)
+//   close()       — tear down the transport
+//
+// The framework handles connection status, reconnect with exponential
+// backoff, message routing, and lifecycle management.
+
+// --- Message type map ---
+
+interface ChatMessages {
+  message: { userId: string; text: string };
+  typing: { userId: string };
+  presence: { online: string[] };
+}
+
+// --- Channel subclass ---
+
+class ChatChannel extends Channel<ChatMessages> {
+  // Tune reconnect behavior via static overrides
+  static override RECONNECT_BASE = 1000;   // initial backoff (ms)
+  static override RECONNECT_MAX = 30000;   // max backoff cap (ms)
+  static override MAX_ATTEMPTS = 5;        // give up after 5 attempts
+
+  private ws: { close(): void } | null = null;
+
+  // open() is called by the framework when connect() is invoked.
+  // The signal aborts on disconnect() or dispose().
+  protected open(signal: AbortSignal): void {
+    // In production, this would be:
+    //   this.ws = new WebSocket('wss://chat.example.com');
+    //   this.ws.onmessage = (e) => {
+    //     const { type, payload } = JSON.parse(e.data);
+    //     this.receive(type, payload);
+    //   };
+
+    // Simulated connection
+    console.log('Connecting...');
+    const connectTimer = setTimeout(() => {
+      if (!signal.aborted) {
+        console.log('Connected!');
+        // Simulate incoming messages
+        this.receive('presence', { online: ['alice', 'bob'] });
+        this.receive('message', { userId: 'alice', text: 'Hello!' });
+      }
+    }, 100);
+
+    this.ws = {
+      close: () => clearTimeout(connectTimer),
+    };
+
+    // Always clean up when the signal aborts (disconnect or dispose)
+    signal.addEventListener('abort', () => this.ws?.close());
+  }
+
+  // close() tears down the transport. Must not throw.
+  protected close(): void {
+    this.ws?.close();
+    this.ws = null;
+  }
+}
+
+// --- Usage ---
+
+const chat = singleton(ChatChannel);
+chat.init();
+
+// Subscribe to connection status changes
+chat.subscribe((next: ChannelStatus, prev: ChannelStatus) => {
+  console.log(`Status: connected=${next.connected}, reconnecting=${next.reconnecting}`);
+  if (next.error) console.log(`Error: ${next.error}`);
+});
+
+// Subscribe to typed messages
+const unsubMessage = chat.on('message', ({ userId, text }) => {
+  console.log(`${userId}: ${text}`);
+});
+
+// One-time subscription — auto-unsubscribes after first event
+chat.once('presence', ({ online }) => {
+  console.log('Initial presence:', online);
+});
+
+// Initiate connection
+chat.connect();
+
+// Read current status at any time
+console.log('Connected:', chat.state.connected);
+console.log('Reconnecting:', chat.state.reconnecting);
+console.log('Attempt:', chat.state.attempt);
+
+// Manually disconnect (cancels pending reconnect, resets status)
+// chat.disconnect();
+
+// Reconnect after disconnect
+// chat.connect();
+
+// Unsubscribe from a message type
+unsubMessage();
+
+// Cleanup — cancels timers, aborts signals, calls close()
+setTimeout(() => {
+  chat.dispose();
+  teardownAll();
+}, 500);

package/examples/primitive/collection.ts

@@ -0,0 +1,118 @@
+import { Collection } from 'mvc-kit';
+
+// Collection: Reactive typed array with CRUD and query methods
+
+interface Todo {
+  id: string;
+  text: string;
+  done: boolean;
+  priority: 'low' | 'medium' | 'high';
+}
+
+// --- Basic usage ---
+
+const todos = new Collection<Todo>();
+
+// Subscribe to changes
+todos.subscribe((items, prev) => {
+  console.log(`Collection changed: ${prev.length} → ${items.length} items`);
+});
+
+// CRUD operations (trigger notifications)
+
+// Add items
+todos.add(
+  { id: '1', text: 'Learn mvc-kit', done: false, priority: 'high' },
+  { id: '2', text: 'Build an app', done: false, priority: 'medium' },
+  { id: '3', text: 'Write tests', done: true, priority: 'low' }
+);
+
+console.log('Length:', todos.length); // 3
+console.log('Items:', todos.items);
+
+// Update an item
+todos.update('1', { done: true });
+console.log('After update:', todos.get('1')?.done); // true
+
+// Remove an item
+todos.remove('3');
+console.log('After remove length:', todos.length); // 2
+
+// Query operations (pure, no notifications)
+
+// Get by id (O(1) lookup)
+const todo = todos.get('1');
+console.log('Get by id:', todo?.text);
+
+// Check existence
+console.log('Has id 1:', todos.has('1')); // true
+console.log('Has id 99:', todos.has('99')); // false
+
+// Find first match
+const firstIncomplete = todos.find(t => !t.done);
+console.log('First incomplete:', firstIncomplete?.text);
+
+// Filter
+const highPriority = todos.filter(t => t.priority === 'high');
+console.log('High priority count:', highPriority.length);
+
+// Sort (returns new array, doesn't mutate)
+const sorted = todos.sorted((a, b) => a.text.localeCompare(b.text));
+console.log('Sorted:', sorted.map(t => t.text));
+
+// Map
+const texts = todos.map(t => t.text);
+console.log('Texts:', texts);
+
+// Reset - replace all items
+todos.reset([
+  { id: 'a', text: 'New todo', done: false, priority: 'medium' }
+]);
+console.log('After reset length:', todos.length); // 1
+
+// Clear all items
+todos.clear();
+console.log('After clear length:', todos.length); // 0
+
+// --- Upsert: add-or-replace by ID ---
+
+todos.reset([
+  { id: '1', text: 'Learn mvc-kit', done: false, priority: 'high' },
+  { id: '2', text: 'Build an app', done: false, priority: 'medium' },
+]);
+
+// Upsert replaces existing items in-place and appends new ones
+todos.upsert(
+  { id: '2', text: 'Build an app', done: true, priority: 'medium' },  // replaces in position
+  { id: '3', text: 'Ship it', done: false, priority: 'high' },         // appended
+);
+console.log('After upsert length:', todos.length); // 3
+console.log('Item 2 done:', todos.get('2')?.done); // true (replaced)
+console.log('Item 3 text:', todos.get('3')?.text); // 'Ship it' (new)
+
+// --- Optimistic updates ---
+
+// Reset with some data for the optimistic demo
+todos.reset([
+  { id: '1', text: 'Learn mvc-kit', done: false, priority: 'high' },
+  { id: '2', text: 'Build an app', done: false, priority: 'medium' },
+]);
+
+// Snapshot current state, apply mutations, get a rollback function
+const rollback = todos.optimistic(() => {
+  todos.update('1', { done: true });
+  todos.remove('2');
+});
+
+console.log('After optimistic:', todos.length); // 1
+console.log('Item 1 done:', todos.get('1')?.done); // true
+
+// If the server call fails, rollback restores pre-optimistic state
+rollback();
+
+console.log('After rollback:', todos.length); // 2
+console.log('Item 1 done:', todos.get('1')?.done); // false
+console.log('Item 2 exists:', todos.has('2')); // true
+
+// Cleanup
+todos.dispose();

package/examples/primitive/controller.ts

@@ -0,0 +1,118 @@
+import { Controller, ViewModel, Collection, singleton, teardownAll } from 'mvc-kit';
+
+// Controller: Stateless multi-ViewModel orchestrator
+//
+// Controllers coordinate between ViewModels, Models, and Services when
+// a single ViewModel can't own the workflow. This is rare — most
+// orchestration fits in a single ViewModel.
+//
+// Use Controller only for pure cross-cutting coordination with no state
+// of its own: multi-step checkout, drag-and-drop between lists, etc.
+//
+// What Controller provides:
+//   - init() / dispose() lifecycle
+//   - subscribeTo() / listenTo() with auto-cleanup
+//   - disposeSignal for cancelling async operations
+//   - addCleanup() for custom teardown
+//
+// What Controller does NOT provide:
+//   - State (no set())
+//   - Computed getters
+//   - Async tracking
+//   - Events (no emit())
+
+// --- Supporting types ---
+
+interface Task {
+  id: string;
+  title: string;
+  status: 'todo' | 'done';
+}
+
+interface TaskListState {
+  items: Task[];
+}
+
+// --- Two ViewModels that the Controller coordinates ---
+
+class TodoListViewModel extends ViewModel<TaskListState> {
+  removeItem(id: string) {
+    this.set({ items: this.state.items.filter(t => t.id !== id) });
+  }
+
+  addItem(task: Task) {
+    this.set({ items: [...this.state.items, task] });
+  }
+}
+
+class DoneListViewModel extends ViewModel<TaskListState> {
+  addItem(task: Task) {
+    this.set({ items: [...this.state.items, { ...task, status: 'done' as const }] });
+  }
+}
+
+// --- Controller definition ---
+
+class TaskTransferController extends Controller {
+  constructor(
+    private todoVM: TodoListViewModel,
+    private doneVM: DoneListViewModel,
+  ) {
+    super();
+  }
+
+  protected onInit() {
+    // subscribeTo auto-cleans up on dispose
+    this.subscribeTo(this.todoVM, (state) => {
+      console.log(`Todo list: ${state.items.length} items`);
+    });
+
+    this.subscribeTo(this.doneVM, (state) => {
+      console.log(`Done list: ${state.items.length} items`);
+    });
+  }
+
+  // Pure coordination — moves an item from todo to done
+  completeTask(taskId: string) {
+    const task = this.todoVM.state.items.find(t => t.id === taskId);
+    if (!task) return;
+    this.todoVM.removeItem(taskId);
+    this.doneVM.addItem(task);
+  }
+
+  protected onDispose() {
+    console.log('TaskTransferController disposed');
+  }
+}
+
+// --- Usage ---
+
+const todoVM = new TodoListViewModel({
+  items: [
+    { id: '1', title: 'Learn mvc-kit', status: 'todo' },
+    { id: '2', title: 'Build an app', status: 'todo' },
+    { id: '3', title: 'Write tests', status: 'todo' },
+  ],
+});
+todoVM.init();
+
+const doneVM = new DoneListViewModel({ items: [] });
+doneVM.init();
+
+const controller = new TaskTransferController(todoVM, doneVM);
+controller.init();
+
+console.log('Todo:', todoVM.state.items.length); // 3
+console.log('Done:', doneVM.state.items.length); // 0
+
+// Controller coordinates the move
+controller.completeTask('1');
+
+console.log('Todo:', todoVM.state.items.length); // 2
+console.log('Done:', doneVM.state.items.length); // 1
+console.log('Done item:', doneVM.state.items[0]?.title); // 'Learn mvc-kit'
+
+// Cleanup
+controller.dispose();
+todoVM.dispose();
+doneVM.dispose();

package/examples/primitive/counter.ts

@@ -0,0 +1,108 @@
+import { ViewModel, singleton, hasSingleton, teardown, teardownAll } from 'mvc-kit';
+
+// ViewModel: Reactive state + computed getters + async tracking + typed events
+//
+// The core building block. Holds state, derives computed values via getters,
+// provides actions to update state, and tracks async method loading/error
+// automatically. After init(), getters are auto-memoized and only recompute
+// when their dependencies change.
+
+// Define state interface
+interface CounterState {
+  count: number;
+}
+
+// Create a ViewModel by extending the base class
+class CounterViewModel extends ViewModel<CounterState> {
+  // --- Computed getters (auto-memoized after init) ---
+  get doubled(): number {
+    return this.state.count * 2;
+  }
+
+  get isPositive(): boolean {
+    return this.state.count > 0;
+  }
+
+  get parity(): 'even' | 'odd' {
+    return this.state.count % 2 === 0 ? 'even' : 'odd';
+  }
+
+  // --- Actions ---
+  increment() {
+    this.set({ count: this.state.count + 1 });
+  }
+
+  decrement() {
+    this.set({ count: this.state.count - 1 });
+  }
+
+  reset() {
+    this.set({ count: 0 });
+  }
+
+  // Updater function pattern for derived updates
+  multiplyBy(factor: number) {
+    this.set(prev => ({ count: prev.count * factor }));
+  }
+
+  // Lifecycle hook: called after each state update
+  protected onSet(prev: Readonly<CounterState>, next: Readonly<CounterState>) {
+    console.log(`Count changed: ${prev.count} → ${next.count}`);
+  }
+
+  // Lifecycle hook: called when disposed
+  protected onDispose() {
+    console.log('CounterViewModel disposed');
+  }
+}
+
+// --- Basic usage ---
+
+const counter = new CounterViewModel({ count: 0 });
+counter.init(); // activates getter memoization and async tracking
+
+// Subscribe to state changes
+const unsubscribe = counter.subscribe((state, prev) => {
+  console.log(`Subscriber notified: ${prev.count} → ${state.count}`);
+});
+
+counter.increment(); // Count changed: 0 → 1
+counter.increment(); // Count changed: 1 → 2
+counter.multiplyBy(5); // Count changed: 2 → 10
+
+// Access current state
+console.log('Current count:', counter.state.count); // 10
+
+// --- Computed getters ---
+
+console.log('Doubled:', counter.doubled); // 20
+console.log('Is positive:', counter.isPositive); // true
+console.log('Parity:', counter.parity); // even
+
+counter.decrement(); // Count changed: 10 → 9
+console.log('Doubled:', counter.doubled); // 18
+console.log('Parity:', counter.parity); // odd
+
+// Cleanup
+unsubscribe();
+counter.dispose();
+
+// --- Singleton pattern ---
+
+// Get or create a singleton instance
+const shared1 = singleton(CounterViewModel, { count: 100 });
+shared1.init(); // activate getter memoization on the singleton too
+const shared2 = singleton(CounterViewModel, { count: 999 }); // args ignored, same instance returned
+
+console.log('Same instance:', shared1 === shared2); // true
+console.log('Singleton count:', shared1.state.count); // 100
+
+// Check if singleton exists
+console.log('Has singleton:', hasSingleton(CounterViewModel)); // true
+
+// Cleanup singleton
+teardown(CounterViewModel);
+console.log('Has singleton after teardown:', hasSingleton(CounterViewModel)); // false
+
+// Cleanup all singletons (useful in tests)
+teardownAll();

package/examples/primitive/env.d.ts

@@ -0,0 +1 @@
+declare const __MVC_KIT_DEV__: boolean;

package/examples/primitive/eventbus.ts

@@ -0,0 +1,77 @@
+import { EventBus } from 'mvc-kit';
+
+// EventBus: Typed pub/sub for decoupled communication
+
+// Define event types
+interface AppEvents {
+  'user:login': { userId: string; timestamp: number };
+  'user:logout': { userId: string };
+  'notification': { message: string; type: 'info' | 'warning' | 'error' };
+  'cart:updated': { itemCount: number };
+}
+
+// --- Basic usage ---
+
+const bus = new EventBus<AppEvents>();
+
+// Subscribe to events
+const unsubLogin = bus.on('user:login', ({ userId, timestamp }) => {
+  console.log(`User ${userId} logged in at ${new Date(timestamp).toISOString()}`);
+});
+
+const unsubNotification = bus.on('notification', ({ message, type }) => {
+  console.log(`[${type.toUpperCase()}] ${message}`);
+});
+
+// Emit events
+bus.emit('user:login', { userId: '123', timestamp: Date.now() });
+bus.emit('notification', { message: 'Welcome back!', type: 'info' });
+
+// One-time subscription - auto-unsubscribes after first event
+bus.once('user:logout', ({ userId }) => {
+  console.log(`User ${userId} logged out (one-time handler)`);
+});
+
+bus.emit('user:logout', { userId: '123' }); // Handler called
+bus.emit('user:logout', { userId: '123' }); // Handler NOT called (already unsubscribed)
+
+// Unsubscribe manually
+unsubLogin();
+unsubNotification();
+
+// After unsubscribe, handlers are not called
+bus.emit('user:login', { userId: '456', timestamp: Date.now() }); // No output
+
+// --- Practical pattern: Cross-component communication ---
+
+class AuthService {
+  constructor(private bus: EventBus<AppEvents>) {}
+
+  login(userId: string) {
+    // ... authentication logic ...
+    this.bus.emit('user:login', { userId, timestamp: Date.now() });
+  }
+
+  logout(userId: string) {
+    // ... logout logic ...
+    this.bus.emit('user:logout', { userId });
+  }
+}
+
+class NotificationManager {
+  constructor(private bus: EventBus<AppEvents>) {
+    // React to login events
+    this.bus.on('user:login', () => {
+      this.bus.emit('notification', { message: 'Welcome!', type: 'info' });
+    });
+  }
+}
+
+// Components can communicate without direct references
+const auth = new AuthService(bus);
+new NotificationManager(bus);
+
+auth.login('789'); // Triggers login event, which triggers notification
+
+// Cleanup
+bus.dispose();