mvc-kit 2.13.0 → 2.13.2

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
@@ -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 → 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
 ---
@@ -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

@@ -1,37 +1,36 @@
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, copyFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { cpSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const SKILLS_DIR = join(__dirname, '..', 'claude-code', 'skills');
-const AGENTS_DIR = join(__dirname, '..', 'claude-code', 'agents');
-
-const AUTO_HEADER = '<!-- Auto-generated by mvc-kit. Updated on npm install/update. Do not edit. -->';
-
-function stripFrontmatter(content) {
-  const match = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
-  return match ? match[1].trim() : content.trim();
-}
-
-/** Insert auto-generated header after YAML frontmatter (preserves parsing). */
-function addHeader(content) {
-  const match = content.match(/^(---\n[\s\S]*?\n---\n)([\s\S]*)$/);
-  if (match) {
-    return match[1] + '\n' + AUTO_HEADER + '\n\n' + match[2].trim() + '\n';
-  }
-  return AUTO_HEADER + '\n\n' + content;
-}
-
-function ensureDir(dir) {
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
+const SOURCE_DIR = join(__dirname, '..', 'claude-code');
+
+const SKILL_NAMES = ['mvc-kit', 'mvc-kit-review', 'mvc-kit-scaffold'];
+const AGENT_FILES = ['mvc-kit-architect.md'];
+
+function listFilesRecursive(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      for (const nested of listFilesRecursive(full)) {
+        out.push(join(entry, nested));
+      }
+    } else {
+      out.push(entry);
+    }
   }
+  return out;
 }
 
 /**
  * Install Claude Code integration files into a project's .claude/ directory.
  *
+ * Source directories under `agent-config/claude-code/` are copied verbatim —
+ * no frontmatter rewriting, no header injection. Source files are authored
+ * in their final installed form.
+ *
  * Creates:
  *   .claude/skills/mvc-kit/            — Framework reference skill + supporting docs
  *   .claude/skills/mvc-kit-review/     — Code review skill + checklist
@@ -39,103 +38,33 @@ function ensureDir(dir) {
  *   .claude/agents/mvc-kit-architect.md — Architecture planning agent
  *
  * @param {string} projectRoot — Absolute path to the consuming project's root
- * @returns {{ files: string[] }} — List of created/updated file paths (relative to projectRoot)
+ * @returns {{ files: string[] }} — List of installed file paths (relative to projectRoot)
  */
 export function installClaude(projectRoot) {
   const claudeDir = join(projectRoot, '.claude');
-  const guideDir = join(claudeDir, 'skills', 'mvc-kit');
-  const reviewDir = join(claudeDir, 'skills', 'mvc-kit-review');
-  const scaffoldDir = join(claudeDir, 'skills', 'mvc-kit-scaffold');
-  const templatesDir = join(scaffoldDir, 'templates');
-  const agentsDir = join(claudeDir, 'agents');
+  const skillsDest = join(claudeDir, 'skills');
+  const agentsDest = join(claudeDir, 'agents');
 
-  ensureDir(guideDir);
-  ensureDir(reviewDir);
-  ensureDir(scaffoldDir);
-  ensureDir(templatesDir);
-  ensureDir(agentsDir);
+  mkdirSync(skillsDest, { recursive: true });
+  mkdirSync(agentsDest, { recursive: true });
 
   const files = [];
 
-  // ─── 1. Guide skill — framework reference (model-invocable, auto-loaded) ───
-
-  const guideSkill = readFileSync(join(SKILLS_DIR, 'guide', 'SKILL.md'), 'utf-8');
-  const guideBody = stripFrontmatter(guideSkill)
-    // Remove the "Supporting Files" section — replaced with colocated file references below
-    .replace(/\n## Supporting Files[\s\S]*$/, '');
-
-  const GUIDE_FRONTMATTER = `---
-name: mvc-kit
-description: "mvc-kit framework reference — class roles, architecture rules, React hooks, and decision framework. Loaded on-demand when working with mvc-kit code."
-user-invocable: false
----`;
-
-  const skillContent = GUIDE_FRONTMATTER + '\n\n' + AUTO_HEADER + '\n\n' + guideBody + `
-
-## Supporting Files
-
-- [api-reference.md](api-reference.md) — Full API reference for all classes and hooks
-- [patterns.md](patterns.md) — Prescribed patterns with code examples
-- [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)
-
-For detailed per-class documentation, read the \`.md\` files colocated with source in:
-\`node_modules/mvc-kit/src/\`
-`;
-
-  writeFileSync(join(guideDir, 'SKILL.md'), skillContent, 'utf-8');
-  files.push('.claude/skills/mvc-kit/SKILL.md');
-
-  // Copy supporting files alongside SKILL.md
-  const guideSupportFiles = ['api-reference.md', 'patterns.md', 'anti-patterns.md', 'recipes.md', 'testing.md'];
-  for (const file of guideSupportFiles) {
-    const src = join(SKILLS_DIR, 'guide', file);
-    if (existsSync(src)) {
-      copyFileSync(src, join(guideDir, file));
-      files.push(`.claude/skills/mvc-kit/${file}`);
+  for (const skill of SKILL_NAMES) {
+    const src = join(SOURCE_DIR, 'skills', skill);
+    const dest = join(skillsDest, skill);
+    cpSync(src, dest, { recursive: true, force: true });
+    for (const rel of listFilesRecursive(src)) {
+      files.push(`.claude/skills/${skill}/${rel}`);
     }
   }
 
-  // ─── 2. Review skill — code review with checklist ──────────────────────────
-
-  const reviewSkill = readFileSync(join(SKILLS_DIR, 'review', 'SKILL.md'), 'utf-8');
-  writeFileSync(join(reviewDir, 'SKILL.md'), addHeader(reviewSkill), 'utf-8');
-  files.push('.claude/skills/mvc-kit-review/SKILL.md');
-
-  copyFileSync(
-    join(SKILLS_DIR, 'review', 'checklist.md'),
-    join(reviewDir, 'checklist.md'),
-  );
-  files.push('.claude/skills/mvc-kit-review/checklist.md');
-
-  // ─── 3. Scaffold skill — code generation with templates ────────────────────
-
-  const scaffoldSkill = readFileSync(join(SKILLS_DIR, 'scaffold', 'SKILL.md'), 'utf-8');
-  writeFileSync(join(scaffoldDir, 'SKILL.md'), addHeader(scaffoldSkill), 'utf-8');
-  files.push('.claude/skills/mvc-kit-scaffold/SKILL.md');
-
-  const templatesSrc = join(SKILLS_DIR, 'scaffold', 'templates');
-  if (existsSync(templatesSrc)) {
-    for (const file of readdirSync(templatesSrc)) {
-      if (file.endsWith('.md')) {
-        copyFileSync(join(templatesSrc, file), join(templatesDir, file));
-        files.push(`.claude/skills/mvc-kit-scaffold/templates/${file}`);
-      }
-    }
+  for (const agent of AGENT_FILES) {
+    const src = join(SOURCE_DIR, 'agents', agent);
+    const dest = join(agentsDest, agent);
+    cpSync(src, dest, { force: true });
+    files.push(`.claude/agents/${agent}`);
   }
 
-  // ─── 4. Architect agent ────────────────────────────────────────────────────
-
-  let architectAgent = readFileSync(join(AGENTS_DIR, 'mvc-kit-architect.md'), 'utf-8');
-  // The source agent preloads "mvc-kit-guide" (the source skill name).
-  // In the installed context the guide skill is named "mvc-kit", so fix the reference.
-  architectAgent = architectAgent.replace(
-    /^(\s*- )mvc-kit-guide$/m,
-    '$1mvc-kit',
-  );
-  writeFileSync(join(agentsDir, 'mvc-kit-architect.md'), addHeader(architectAgent), 'utf-8');
-  files.push('.claude/agents/mvc-kit-architect.md');
-
   return { files };
 }

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();