mvc-kit 2.11.1 → 2.12.1

package/README.md

@@ -781,9 +781,12 @@ function App() {
 | `Controller` | Stateless orchestrator (Disposable) |
 | `Service` | Non-reactive infrastructure service (Disposable) |
 | `EventBus<E>` | Typed pub/sub event bus |
+| `Trackable` | Base class for custom reactive objects (subscribable + disposable + auto-bind) |
 
 ### Composable Helpers
 
+All composable helpers extend `Trackable` — subscribable, disposable, and auto-bound.
+
 | Class | Description |
 |-------|-------------|
 | `Sorting<T>` | Multi-column sort state with 3-click toggle cycle and `apply()` pipeline |
@@ -890,6 +893,7 @@ Each core class and React hook has a dedicated reference doc with full API detai
 | [Service](src/Service.md) | Non-reactive infrastructure adapters (HTTP, storage, SDKs) |
 | [EventBus](src/EventBus.md) | Typed pub/sub for cross-cutting event communication |
 | [Channel](src/Channel.md) | Persistent connections (WebSocket, SSE) with auto-reconnect |
+| [Trackable](src/Trackable.md) | Base class for custom reactive objects (subscribable + disposable + auto-bind) |
 | [Singleton Registry](src/singleton.md) | Global instance management: `singleton()`, `teardown()`, `teardownAll()` |
 | [Sorting](src/Sorting.md) | Multi-column sort state with 3-click toggle cycle and apply pipeline |
 | [Pagination](src/Pagination.md) | Page/pageSize state with array slicing |

package/agent-config/bin/postinstall.mjs

@@ -21,14 +21,16 @@ if (resolve(projectRoot) === ownPackageRoot) {
 }
 
 // If the developer previously opted in (files exist), auto-update them
-const rulesFile = join(projectRoot, '.claude', 'rules', 'mvc-kit.md');
+const skillFile = join(projectRoot, '.claude', 'commands', 'mvc-kit.md');
+// Also detect legacy rules file from older versions
+const legacyRulesFile = join(projectRoot, '.claude', 'rules', 'mvc-kit.md');
 
-if (existsSync(rulesFile)) {
+if (existsSync(skillFile) || existsSync(legacyRulesFile)) {
   try {
     const { installClaude } = await import('../lib/install-claude.mjs');
     installClaude(projectRoot);
     console.log('');
-    console.log('  mvc-kit — Claude Code rules updated');
+    console.log('  mvc-kit — Claude Code files updated');
     console.log('');
   } catch {
     // Never break npm install

package/agent-config/bin/setup.mjs

@@ -23,7 +23,7 @@ function printUsage() {
 Usage: npx mvc-kit-setup [targets...] [options]
 
 Targets:
-  claude     Install Claude Code rules and commands into .claude/
+  claude     Install Claude Code skill and agent into .claude/
   cursor     Copy mvc-kit rules to .cursorrules
   copilot    Copy mvc-kit instructions to .github/copilot-instructions.md
   all        Set up all targets (default)
@@ -87,9 +87,8 @@ function setupClaude() {
     console.log(`    ${f}`);
   }
   console.log('');
-  console.log('  Commands:  /project:mvc-kit-scaffold, /project:mvc-kit-review');
-  console.log('  Agent:     mvc-kit-architect (architecture planning)');
-  console.log('  Reference: Auto-loaded via .claude/rules/mvc-kit.md\n');
+  console.log('  Skill:  /project:mvc-kit (framework reference, on-demand)');
+  console.log('  Agent:  mvc-kit-architect (architecture planning)\n');
 }
 
 async function setupCursor(force) {

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

@@ -6,6 +6,20 @@ model: sonnet
 
 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
+
+For detailed, up-to-date documentation on any class or hook, search the `.md` files colocated with source in `node_modules/mvc-kit/src/`. Read these when you need specifics beyond the summary tables below.
+
+**Core classes:** `ViewModel.md`, `Model.md`, `Collection.md`, `PersistentCollection.md`, `Resource.md`, `Service.md`, `EventBus.md`, `Channel.md`, `Controller.md`, `Trackable.md`, `singleton.md`
+**Composable 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`
+**Headless components:** `react/components/DataTable.md`, `react/components/CardList.md`, `react/components/InfiniteScroll.md`
+
+Additional reference files in `node_modules/mvc-kit/agent-config/claude-code/skills/guide/`:
+- `api-reference.md` — Full API reference for all classes and hooks
+- `patterns.md` — Prescribed patterns with code examples
+- `anti-patterns.md` — Anti-patterns to reject with fixes
+
 ## Core Classes
 
 | Class | Role | Scope |

package/agent-config/claude-code/skills/guide/anti-patterns.md

@@ -526,6 +526,47 @@ this.pending.enqueue(id, 'delete', async (signal) => {
 
 ---
 
+## 25. Manually Reimplementing Subscribe/Notify/Dispose Boilerplate
+
+```typescript
+// BAD — hand-rolling what Trackable provides
+class QueryState {
+  private listeners = new Set<() => void>();
+  private _disposed = false;
+  private _data: Data | undefined;
+
+  subscribe(cb: () => void) {
+    this.listeners.add(cb);
+    return () => this.listeners.delete(cb);
+  }
+  private notify() {
+    for (const cb of this.listeners) cb();
+  }
+  dispose() {
+    this._disposed = true;
+    this.listeners.clear();
+  }
+  // ... more boilerplate
+}
+
+// GOOD — extend Trackable for subscribe, notify, dispose, disposeSignal, addCleanup, and auto-binding
+import { Trackable } from 'mvc-kit';
+
+class QueryState extends Trackable {
+  private _data: Data | undefined;
+  get data() { return this._data; }
+
+  async load() {
+    this._data = await fetchData(this.disposeSignal);
+    this.notify();
+  }
+}
+```
+
+Trackable is the base class for all composable helpers (Sorting, Selection, Feed, Pagination, Pending). Use it whenever you need a subscribable + disposable object.
+
+---
+
 ## 24. Using collection.optimistic() Rollback with Pending
 
 ```typescript

package/agent-config/claude-code/skills/guide/api-reference.md

@@ -6,6 +6,7 @@
 // Core classes and utilities
 import { ViewModel, Model, Collection, PersistentCollection, Resource, Controller, Service, EventBus, Channel } from 'mvc-kit';
 import { Sorting, Pagination, Selection, Feed, Pending } from 'mvc-kit';
+import { Trackable, bindPublicMethods, produceDraft } from 'mvc-kit';
 import { singleton, hasSingleton, teardown, teardownAll } from 'mvc-kit';
 import { HttpError, isAbortError, classifyError } from 'mvc-kit';
 import type { Subscribable, Disposable, Initializable, Listener, Updater, ValidationErrors, TaskState, EventSource, EventPayload, AppError, AsyncMethodKeys, ResourceAsyncMethodKeys, ChannelStatus, SortDescriptor, FeedPage, PendingOperation, PendingEntry } from 'mvc-kit';
@@ -36,7 +37,8 @@ new MyViewModel(initialState: S)
 ### State
 - `state: S` — Current frozen state. Read `state.x` for raw values.
 - `set(partial: Partial<S>)` — Merge partial state. Skips if no values change.
-- `set(updater: (prev: S) => Partial<S>)` — Functional update.
+- `set(updater: (prev: S) => Partial<S>)` — Functional update (return a partial).
+- `set(drafter: (draft: S) => void)` — Draft mode: mutate the draft proxy, return nothing. Uses `produceDraft` internally.
 - `reset(newState?: S)` — Tear down lifecycle, re-initialize. Clears async tracking, re-runs `onInit()`.
 
 ### Computed Getters
@@ -93,6 +95,7 @@ new MyModel(initialState: S)
 ### State & Validation
 - `state: S` — Current state.
 - `set(partial: Partial<S>)` — Update state, re-validates.
+- `set(drafter: (draft: S) => void)` — Draft mode: mutate the draft, return nothing.
 - `errors: ValidationErrors<S>` — `Partial<Record<keyof S, string>>`.
 - `valid: boolean` — True when `errors` is empty.
 - `dirty: boolean` — True when state differs from committed state.
@@ -285,9 +288,70 @@ No state, no getters, no async tracking.
 
 ---
 
+## Trackable
+
+Base class for custom reactive objects. Provides subscribe/notify, disposal lifecycle (disposeSignal, addCleanup, onDispose), and auto-bound methods — the same building blocks used by Sorting, Selection, Feed, Pagination, and Pending (all extend Trackable).
+
+Use Trackable when integrating third-party SDKs, custom query objects, or any reactive state that doesn't fit ViewModel's state/getter model.
+
+### Subscribe & Notify
+- `subscribe(cb: () => void): () => void` — Subscribe to change notifications. Duck-typed contract recognized by ViewModel auto-tracking.
+- `notify(): void` — Protected. Notify all subscribers that state changed.
+
+### Lifecycle & Cleanup
+- `disposed: boolean` — Whether this instance has been disposed.
+- `disposeSignal: AbortSignal` — Lazily created, auto-aborted on `dispose()`.
+- `addCleanup(fn: () => void): void` — Protected. Register teardown callback.
+- `onDispose(): void` — Protected lifecycle hook called at the end of `dispose()`.
+- `dispose(): void` — Idempotent. Aborts signal, runs cleanups, clears subscribers, calls `onDispose`.
+
+### Auto-Binding
+Public methods are auto-bound in the constructor via `bindPublicMethods()`, so they can be passed point-free as callbacks.
+
+---
+
+## bindPublicMethods(instance, stopPrototype?, exclude?)
+
+Utility function that auto-binds all public methods on an instance. Used internally by Trackable, Collection, Service, EventBus, Channel, Controller, and Model. Available as a named export for custom classes that don't extend Trackable.
+
+```typescript
+import { bindPublicMethods } from 'mvc-kit';
+
+class MyClass {
+  constructor() {
+    bindPublicMethods(this);
+  }
+  greet() { return 'hello'; }
+}
+const { greet } = new MyClass();
+greet(); // 'hello' — no lost `this`
+```
+
+---
+
+## produceDraft(state, mutator)
+
+Copy-on-write draft utility. Creates a proxy of a frozen state object, runs a mutator, and returns only changed top-level keys as a `Partial<S>` (or `null` if nothing changed). Used internally by `ViewModel.set()` and `Model.set()` for draft mode.
+
+```typescript
+import { produceDraft } from 'mvc-kit';
+
+const changes = produceDraft(state, draft => {
+  draft.user.name = 'Bob';
+});
+// { user: { name: 'Bob', ...unchanged fields } } or null
+```
+
+- Nested plain objects use structural sharing (unchanged subtrees keep original references)
+- Same-value assignment is a no-op (returns `null`)
+- Arrays must be replaced via assignment (`draft.items = [...]`), not mutated in place
+- Only POJOs are proxied; class instances, Dates, Maps pass through as-is
+
+---
+
 ## Composable Helpers
 
-Plain classes with `subscribe()` — auto-tracked when declared as ViewModel instance properties. Each has an `apply()` method that transforms arrays. Helpers manage state; ViewModels compose them in getters.
+Plain classes that extend `Trackable` — auto-tracked when declared as ViewModel instance properties. Each has an `apply()` method that transforms arrays. Helpers manage state; ViewModels compose them in getters.
 
 ### Sorting\<T\>
 

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

@@ -387,6 +387,58 @@ Components and helpers are independent — use helpers without components, or co
 
 ---
 
+## Custom Trackable Pattern
+
+Extend `Trackable` when you need a reactive object that integrates with ViewModel auto-tracking but doesn't fit the state/getter model. Call `notify()` after mutating internal state. The object gets `subscribe()`, `dispose()`, `disposeSignal`, `addCleanup()`, and auto-bound methods for free.
+
+```typescript
+import { Trackable } from 'mvc-kit';
+
+class RPCQuery<Data> extends Trackable {
+  private _data: Data | undefined;
+  private _loading = false;
+  private _error: string | null = null;
+
+  get data() { return this._data; }
+  get loading() { return this._loading; }
+  get error() { return this._error; }
+
+  async execute(params: Record<string, unknown>): Promise<void> {
+    this._loading = true;
+    this._error = null;
+    this.notify();
+    try {
+      this._data = await rpcClient.call(params, { signal: this.disposeSignal });
+    } catch (e) {
+      this._error = (e as Error).message;
+      throw e;
+    } finally {
+      this._loading = false;
+      this.notify();
+    }
+  }
+}
+```
+
+Used as a ViewModel property — auto-tracked like any composable helper:
+
+```typescript
+class UsersVM extends ViewModel {
+  readonly query = new RPCQuery<User[]>();
+
+  get users() { return this.query.data ?? []; }
+  get loading() { return this.query.loading; }
+
+  protected onInit() { this.query.execute({ limit: 50 }); }
+}
+```
+
+**When to use Trackable vs ViewModel:**
+- Trackable: custom reactive object used as a ViewModel property (query wrapper, SDK adapter, animation state).
+- ViewModel: component-scoped reactive state with computed getters, async tracking, and lifecycle hooks.
+
+---
+
 ## Persistence Pattern
 
 ```typescript

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

@@ -15,11 +15,12 @@ This project uses **mvc-kit**, a zero-dependency TypeScript-first reactive state
 | `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 |
-| `Sorting<T>` | Multi-column sort state with 3-click toggle cycle and `apply()` pipeline | ViewModel property |
-| `Pagination` | Page/pageSize state with `apply()` slicing | ViewModel property |
-| `Selection<K>` | Key-based selection set with toggle/select-all semantics | ViewModel property |
-| `Feed<T>` | Cursor + hasMore + item accumulation for server-side pagination | ViewModel property |
-| `Pending<K, Meta?>` | Per-item operation queue with retry + status tracking + optional typed metadata | Resource property |
+| `Trackable` | Base class for custom reactive objects — subscribable + disposable + auto-bind | ViewModel property / `useLocal` |
+| `Sorting<T>` | Multi-column sort state with 3-click toggle cycle and `apply()` pipeline (extends Trackable) | ViewModel property |
+| `Pagination` | Page/pageSize state with `apply()` slicing (extends Trackable) | ViewModel property |
+| `Selection<K>` | Key-based selection set with toggle/select-all semantics (extends Trackable) | ViewModel property |
+| `Feed<T>` | Cursor + hasMore + item accumulation for server-side pagination (extends Trackable) | ViewModel property |
+| `Pending<K, Meta?>` | Per-item operation queue with retry + status tracking + optional typed metadata (extends Trackable) | Resource property |
 
 ## Headless React Components (`mvc-kit/react`)
 
@@ -34,6 +35,7 @@ This project uses **mvc-kit**, a zero-dependency TypeScript-first reactive state
 ```typescript
 import { ViewModel, Model, Collection, PersistentCollection, Resource, Controller, Service, EventBus, Channel } from 'mvc-kit';
 import { Sorting, Pagination, Selection, Feed, Pending } from 'mvc-kit';
+import { Trackable, bindPublicMethods } from 'mvc-kit';
 import { singleton, teardownAll, HttpError, isAbortError, classifyError } from 'mvc-kit';
 import { useLocal, useSingleton, useInstance, useModel, useModelRef, useField, useEvent, useEmit, useResolve, useTeardown, Provider } from 'mvc-kit/react';
 import { DataTable, CardList, InfiniteScroll } from 'mvc-kit/react';
@@ -288,6 +290,7 @@ test('example', () => {
 - Pass-through Service wrapping a typed API client → call the client directly from Resource
 - `addCleanup` for `channel.on()`/`bus.on()` subscriptions → use `listenTo()` (auto-cleanup on dispose and reset)
 - Missing `hydrate()` for async adapters (IndexedDB, NativeCollection) → call `hydrate()` in `onInit()` before accessing data
+- Manually reimplementing subscribe/notify/dispose boilerplate → extend `Trackable`
 
 ## Resource Pattern
 
@@ -325,6 +328,7 @@ class UsersVM extends ViewModel<{ search: string }> {
 - Cross-cutting events → **EventBus**
 - Persistent connection → **Channel**
 - Coordinates multiple ViewModels → **Controller** (rare)
+- Custom reactive object (SDK wrapper, query, animation) → **Trackable** (base class for helpers)
 - Sort/paginate/select on a list → **Sorting/Pagination/Selection** helpers
 - Cursor-based server pagination → **Feed** helper
 - Per-item operation retry with status → **Pending** helper (on Resource, not ViewModel)

package/agent-config/cursor/cursorrules

@@ -15,11 +15,12 @@ This project uses **mvc-kit**, a zero-dependency TypeScript-first reactive state
 | `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 |
-| `Sorting<T>` | Multi-column sort state with 3-click toggle cycle and `apply()` pipeline | ViewModel property |
-| `Pagination` | Page/pageSize state with `apply()` slicing | ViewModel property |
-| `Selection<K>` | Key-based selection set with toggle/select-all semantics | ViewModel property |
-| `Feed<T>` | Cursor + hasMore + item accumulation for server-side pagination | ViewModel property |
-| `Pending<K, Meta?>` | Per-item operation queue with retry + status tracking + optional typed metadata | Resource property |
+| `Trackable` | Base class for custom reactive objects — subscribable + disposable + auto-bind | ViewModel property / `useLocal` |
+| `Sorting<T>` | Multi-column sort state with 3-click toggle cycle and `apply()` pipeline (extends Trackable) | ViewModel property |
+| `Pagination` | Page/pageSize state with `apply()` slicing (extends Trackable) | ViewModel property |
+| `Selection<K>` | Key-based selection set with toggle/select-all semantics (extends Trackable) | ViewModel property |
+| `Feed<T>` | Cursor + hasMore + item accumulation for server-side pagination (extends Trackable) | ViewModel property |
+| `Pending<K, Meta?>` | Per-item operation queue with retry + status tracking + optional typed metadata (extends Trackable) | Resource property |
 
 ## Headless React Components (`mvc-kit/react`)
 
@@ -34,6 +35,7 @@ This project uses **mvc-kit**, a zero-dependency TypeScript-first reactive state
 ```typescript
 import { ViewModel, Model, Collection, PersistentCollection, Resource, Controller, Service, EventBus, Channel } from 'mvc-kit';
 import { Sorting, Pagination, Selection, Feed, Pending } from 'mvc-kit';
+import { Trackable, bindPublicMethods } from 'mvc-kit';
 import { singleton, teardownAll, HttpError, isAbortError, classifyError } from 'mvc-kit';
 import { useLocal, useSingleton, useInstance, useModel, useModelRef, useField, useEvent, useEmit, useResolve, useTeardown, Provider } from 'mvc-kit/react';
 import { DataTable, CardList, InfiniteScroll } from 'mvc-kit/react';
@@ -288,6 +290,7 @@ test('example', () => {
 - Pass-through Service wrapping a typed API client → call the client directly from Resource
 - `addCleanup` for `channel.on()`/`bus.on()` subscriptions → use `listenTo()` (auto-cleanup on dispose and reset)
 - Missing `hydrate()` for async adapters (IndexedDB, NativeCollection) → call `hydrate()` in `onInit()` before accessing data
+- Manually reimplementing subscribe/notify/dispose boilerplate → extend `Trackable`
 
 ## Resource Pattern
 
@@ -325,6 +328,7 @@ class UsersVM extends ViewModel<{ search: string }> {
 - Cross-cutting events → **EventBus**
 - Persistent connection → **Channel**
 - Coordinates multiple ViewModels → **Controller** (rare)
+- Custom reactive object (SDK wrapper, query, animation) → **Trackable** (base class for helpers)
 - Sort/paginate/select on a list → **Sorting/Pagination/Selection** helpers
 - Cursor-based server pagination → **Feed** helper
 - Per-item operation retry with status → **Pending** helper (on Resource, not ViewModel)

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

@@ -24,33 +24,29 @@ function ensureDir(dir) {
  * Install Claude Code integration files into a project's .claude/ directory.
  *
  * Creates:
- *   .claude/rules/mvc-kit.md          — Framework reference (always loaded in context)
- *   .claude/commands/mvc-kit-scaffold.md — Scaffold command (/project:mvc-kit-scaffold)
- *   .claude/commands/mvc-kit-review.md   — Review command (/project:mvc-kit-review)
- *   .claude/agents/mvc-kit-architect.md  — Architecture planning agent
+ *   .claude/commands/mvc-kit.md        — Framework reference skill (on-demand via /project:mvc-kit)
+ *   .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)
  */
 export function installClaude(projectRoot) {
   const claudeDir = join(projectRoot, '.claude');
-  const rulesDir = join(claudeDir, 'rules');
   const commandsDir = join(claudeDir, 'commands');
   const agentsDir = join(claudeDir, 'agents');
 
-  ensureDir(rulesDir);
   ensureDir(commandsDir);
   ensureDir(agentsDir);
 
   const files = [];
 
-  // 1. Rules file — framework reference (always loaded in context)
+  // 1. Guide skill — framework reference (on-demand, not always-loaded)
   const guideSkill = readFileSync(join(SKILLS_DIR, 'guide', 'SKILL.md'), 'utf-8');
   const guideBody = stripFrontmatter(guideSkill)
     // Remove the "Supporting Files" section — replaced by "Detailed Reference" below
     .replace(/\n## Supporting Files[\s\S]*$/, '');
 
-  const rulesContent = AUTO_HEADER + guideBody + `
+  const skillContent = AUTO_HEADER + guideBody + `
 
 ## Detailed Reference
 
@@ -60,34 +56,15 @@ For complete API details, patterns, and anti-patterns, read the files in:
 - \`api-reference.md\` — Full API reference for all classes and hooks
 - \`patterns.md\` — Prescribed patterns with code examples
 - \`anti-patterns.md\` — Anti-patterns to reject with fixes
-`;
-
-  writeFileSync(join(rulesDir, 'mvc-kit.md'), rulesContent, 'utf-8');
-  files.push('.claude/rules/mvc-kit.md');
-
-  // 2. Scaffold command
-  const scaffoldSkill = readFileSync(join(SKILLS_DIR, 'scaffold', 'SKILL.md'), 'utf-8');
-  const scaffoldBody = stripFrontmatter(scaffoldSkill)
-    .replace(
-      'Read the template file from `templates/<type>.md` in this skill directory.',
-      'Read the template file from `node_modules/mvc-kit/agent-config/claude-code/skills/scaffold/templates/<type>.md`.'
-    );
 
-  writeFileSync(join(commandsDir, 'mvc-kit-scaffold.md'), AUTO_HEADER + scaffoldBody, 'utf-8');
-  files.push('.claude/commands/mvc-kit-scaffold.md');
-
-  // 3. Review command
-  const reviewSkill = readFileSync(join(SKILLS_DIR, 'review', 'SKILL.md'), 'utf-8');
-  const reviewBody = stripFrontmatter(reviewSkill)
-    .replaceAll(
-      '`checklist.md`',
-      '`node_modules/mvc-kit/agent-config/claude-code/skills/review/checklist.md`'
-    );
+For detailed per-class documentation, read the \`.md\` files colocated with source in:
+\`node_modules/mvc-kit/src/\`
+`;
 
-  writeFileSync(join(commandsDir, 'mvc-kit-review.md'), AUTO_HEADER + reviewBody, 'utf-8');
-  files.push('.claude/commands/mvc-kit-review.md');
+  writeFileSync(join(commandsDir, 'mvc-kit.md'), skillContent, 'utf-8');
+  files.push('.claude/commands/mvc-kit.md');
 
-  // 4. Architect agent
+  // 2. Architect agent
   const architectAgent = readFileSync(join(AGENTS_DIR, 'mvc-kit-architect.md'), 'utf-8');
   writeFileSync(join(agentsDir, 'mvc-kit-architect.md'), AUTO_HEADER + architectAgent, 'utf-8');
   files.push('.claude/agents/mvc-kit-architect.md');

package/dist/Feed.cjs

@@ -1,13 +1,12 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const bindPublicMethods = require("./bindPublicMethods.cjs");
-class Feed {
+const Trackable = require("./Trackable.cjs");
+class Feed extends Trackable.Trackable {
   _cursor = null;
   _hasMore = true;
   _items = Object.freeze([]);
-  _listeners = /* @__PURE__ */ new Set();
   constructor() {
-    bindPublicMethods.bindPublicMethods(this);
+    super();
   }
   // ── Readable state ──
   /** Current cursor position for the next page fetch, or null if at the beginning. */
@@ -31,59 +30,48 @@ class Feed {
   setResult(result) {
     this._hasMore = result.hasMore;
     this._cursor = result.cursor ?? null;
-    this._notify();
+    this.notify();
   }
   /** Append page items and update cursor/hasMore. */
   appendPage(page) {
     this._items = Object.freeze([...this._items, ...page.items]);
     this._hasMore = page.hasMore;
     this._cursor = page.cursor ?? null;
-    this._notify();
+    this.notify();
   }
   /** Prepend page items and update cursor/hasMore. */
   prependPage(page) {
     this._items = Object.freeze([...page.items, ...this._items]);
     this._hasMore = page.hasMore;
     this._cursor = page.cursor ?? null;
-    this._notify();
+    this.notify();
   }
   /** Add items without affecting cursor/hasMore. */
   push(...items) {
     if (items.length === 0) return;
     this._items = Object.freeze([...this._items, ...items]);
-    this._notify();
+    this.notify();
   }
   /** Remove items that don't match the predicate. No-op if nothing is filtered out. */
   filter(predicate) {
     const filtered = this._items.filter(predicate);
     if (filtered.length === this._items.length) return;
     this._items = Object.freeze(filtered);
-    this._notify();
+    this.notify();
   }
   /** Replace all items and update cursor/hasMore atomically. Ideal for pull-to-refresh. */
   replacePage(page) {
     this._items = Object.freeze([...page.items]);
     this._hasMore = page.hasMore;
     this._cursor = page.cursor ?? null;
-    this._notify();
+    this.notify();
   }
   /** Reset to initial empty state with hasMore=true. */
   reset() {
     this._cursor = null;
     this._hasMore = true;
     this._items = Object.freeze([]);
-    this._notify();
-  }
-  // ── Subscribable interface ──
-  /** Subscribe to feed state changes. Returns an unsubscribe function. */
-  subscribe(cb) {
-    this._listeners.add(cb);
-    return () => {
-      this._listeners.delete(cb);
-    };
-  }
-  _notify() {
-    for (const cb of this._listeners) cb();
+    this.notify();
   }
 }
 exports.Feed = Feed;

package/dist/Feed.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"Feed.cjs","sources":["../src/Feed.ts"],"sourcesContent":["import { bindPublicMethods } from './bindPublicMethods';\n\n/** Represents a page of items from a paginated API response. */\nexport interface FeedPage<T> {\n  items: T[];\n  hasMore: boolean;\n  cursor?: string | null;\n}\n\n/**\n * Cursor-based pagination state for server-side paginated feeds.\n * Accumulates items across pages, tracks cursor position and hasMore flag.\n * Subscribable — auto-tracked when used as a ViewModel property.\n */\nexport class Feed<T = unknown> {\n  private _cursor: string | null = null;\n  private _hasMore: boolean = true;\n  private _items: readonly T[] = Object.freeze([] as T[]);\n  private _listeners = new Set<() => void>();\n\n  constructor() {\n    bindPublicMethods(this);\n  }\n\n  // ── Readable state ──\n\n  /** Current cursor position for the next page fetch, or null if at the beginning. */\n  get cursor(): string | null {\n    return this._cursor;\n  }\n\n  /** Whether more pages are available from the server. */\n  get hasMore(): boolean {\n    return this._hasMore;\n  }\n\n  /** Accumulated items across all loaded pages. */\n  get items(): readonly T[] {\n    return this._items;\n  }\n\n  /** Total number of accumulated items. */\n  get count(): number {\n    return this._items.length;\n  }\n\n  // ── Actions ──\n\n  /** Update cursor/hasMore only (backward-compatible, does NOT affect items). */\n  setResult(result: { hasMore: boolean; cursor?: string | null }): void {\n    this._hasMore = result.hasMore;\n    this._cursor = result.cursor ?? null;\n    this._notify();\n  }\n\n  /** Append page items and update cursor/hasMore. */\n  appendPage(page: FeedPage<T>): void {\n    this._items = Object.freeze([...this._items, ...page.items]);\n    this._hasMore = page.hasMore;\n    this._cursor = page.cursor ?? null;\n    this._notify();\n  }\n\n  /** Prepend page items and update cursor/hasMore. */\n  prependPage(page: FeedPage<T>): void {\n    this._items = Object.freeze([...page.items, ...this._items]);\n    this._hasMore = page.hasMore;\n    this._cursor = page.cursor ?? null;\n    this._notify();\n  }\n\n  /** Add items without affecting cursor/hasMore. */\n  push(...items: T[]): void {\n    if (items.length === 0) return;\n    this._items = Object.freeze([...this._items, ...items]);\n    this._notify();\n  }\n\n  /** Remove items that don't match the predicate. No-op if nothing is filtered out. */\n  filter(predicate: (item: T) => boolean): void {\n    const filtered = this._items.filter(predicate);\n    if (filtered.length === this._items.length) return;\n    this._items = Object.freeze(filtered);\n    this._notify();\n  }\n\n  /** Replace all items and update cursor/hasMore atomically. Ideal for pull-to-refresh. */\n  replacePage(page: FeedPage<T>): void {\n    this._items = Object.freeze([...page.items]);\n    this._hasMore = page.hasMore;\n    this._cursor = page.cursor ?? null;\n    this._notify();\n  }\n\n  /** Reset to initial empty state with hasMore=true. */\n  reset(): void {\n    this._cursor = null;\n    this._hasMore = true;\n    this._items = Object.freeze([] as T[]);\n    this._notify();\n  }\n\n  // ── Subscribable interface ──\n\n  /** Subscribe to feed state changes. Returns an unsubscribe function. */\n  subscribe(cb: () => void): () => void {\n    this._listeners.add(cb);\n    return () => { this._listeners.delete(cb); };\n  }\n\n  private _notify(): void {\n    for (const cb of this._listeners) cb();\n  }\n}\n"],"names":["bindPublicMethods"],"mappings":";;;AAcO,MAAM,KAAkB;AAAA,EACrB,UAAyB;AAAA,EACzB,WAAoB;AAAA,EACpB,SAAuB,OAAO,OAAO,EAAS;AAAA,EAC9C,iCAAiB,IAAA;AAAA,EAEzB,cAAc;AACZA,sBAAAA,kBAAkB,IAAI;AAAA,EACxB;AAAA;AAAA;AAAA,EAKA,IAAI,SAAwB;AAC1B,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,UAAmB;AACrB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,QAAsB;AACxB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,QAAgB;AAClB,WAAO,KAAK,OAAO;AAAA,EACrB;AAAA;AAAA;AAAA,EAKA,UAAU,QAA4D;AACpE,SAAK,WAAW,OAAO;AACvB,SAAK,UAAU,OAAO,UAAU;AAChC,SAAK,QAAA;AAAA,EACP;AAAA;AAAA,EAGA,WAAW,MAAyB;AAClC,SAAK,SAAS,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,GAAG,KAAK,KAAK,CAAC;AAC3D,SAAK,WAAW,KAAK;AACrB,SAAK,UAAU,KAAK,UAAU;AAC9B,SAAK,QAAA;AAAA,EACP;AAAA;AAAA,EAGA,YAAY,MAAyB;AACnC,SAAK,SAAS,OAAO,OAAO,CAAC,GAAG,KAAK,OAAO,GAAG,KAAK,MAAM,CAAC;AAC3D,SAAK,WAAW,KAAK;AACrB,SAAK,UAAU,KAAK,UAAU;AAC9B,SAAK,QAAA;AAAA,EACP;AAAA;AAAA,EAGA,QAAQ,OAAkB;AACxB,QAAI,MAAM,WAAW,EAAG;AACxB,SAAK,SAAS,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,GAAG,KAAK,CAAC;AACtD,SAAK,QAAA;AAAA,EACP;AAAA;AAAA,EAGA,OAAO,WAAuC;AAC5C,UAAM,WAAW,KAAK,OAAO,OAAO,SAAS;AAC7C,QAAI,SAAS,WAAW,KAAK,OAAO,OAAQ;AAC5C,SAAK,SAAS,OAAO,OAAO,QAAQ;AACpC,SAAK,QAAA;AAAA,EACP;AAAA;AAAA,EAGA,YAAY,MAAyB;AACnC,SAAK,SAAS,OAAO,OAAO,CAAC,GAAG,KAAK,KAAK,CAAC;AAC3C,SAAK,WAAW,KAAK;AACrB,SAAK,UAAU,KAAK,UAAU;AAC9B,SAAK,QAAA;AAAA,EACP;AAAA;AAAA,EAGA,QAAc;AACZ,SAAK,UAAU;AACf,SAAK,WAAW;AAChB,SAAK,SAAS,OAAO,OAAO,CAAA,CAAS;AACrC,SAAK,QAAA;AAAA,EACP;AAAA;AAAA;AAAA,EAKA,UAAU,IAA4B;AACpC,SAAK,WAAW,IAAI,EAAE;AACtB,WAAO,MAAM;AAAE,WAAK,WAAW,OAAO,EAAE;AAAA,IAAG;AAAA,EAC7C;AAAA,EAEQ,UAAgB;AACtB,eAAW,MAAM,KAAK,WAAY,IAAA;AAAA,EACpC;AACF;;"}
+{"version":3,"file":"Feed.cjs","sources":["../src/Feed.ts"],"sourcesContent":["import { Trackable } from './Trackable';\n\n/** Represents a page of items from a paginated API response. */\nexport interface FeedPage<T> {\n  items: T[];\n  hasMore: boolean;\n  cursor?: string | null;\n}\n\n/**\n * Cursor-based pagination state for server-side paginated feeds.\n * Accumulates items across pages, tracks cursor position and hasMore flag.\n * Subscribable — auto-tracked when used as a ViewModel property.\n */\nexport class Feed<T = unknown> extends Trackable {\n  private _cursor: string | null = null;\n  private _hasMore: boolean = true;\n  private _items: readonly T[] = Object.freeze([] as T[]);\n\n  constructor() {\n    super();\n  }\n\n  // ── Readable state ──\n\n  /** Current cursor position for the next page fetch, or null if at the beginning. */\n  get cursor(): string | null {\n    return this._cursor;\n  }\n\n  /** Whether more pages are available from the server. */\n  get hasMore(): boolean {\n    return this._hasMore;\n  }\n\n  /** Accumulated items across all loaded pages. */\n  get items(): readonly T[] {\n    return this._items;\n  }\n\n  /** Total number of accumulated items. */\n  get count(): number {\n    return this._items.length;\n  }\n\n  // ── Actions ──\n\n  /** Update cursor/hasMore only (backward-compatible, does NOT affect items). */\n  setResult(result: { hasMore: boolean; cursor?: string | null }): void {\n    this._hasMore = result.hasMore;\n    this._cursor = result.cursor ?? null;\n    this.notify();\n  }\n\n  /** Append page items and update cursor/hasMore. */\n  appendPage(page: FeedPage<T>): void {\n    this._items = Object.freeze([...this._items, ...page.items]);\n    this._hasMore = page.hasMore;\n    this._cursor = page.cursor ?? null;\n    this.notify();\n  }\n\n  /** Prepend page items and update cursor/hasMore. */\n  prependPage(page: FeedPage<T>): void {\n    this._items = Object.freeze([...page.items, ...this._items]);\n    this._hasMore = page.hasMore;\n    this._cursor = page.cursor ?? null;\n    this.notify();\n  }\n\n  /** Add items without affecting cursor/hasMore. */\n  push(...items: T[]): void {\n    if (items.length === 0) return;\n    this._items = Object.freeze([...this._items, ...items]);\n    this.notify();\n  }\n\n  /** Remove items that don't match the predicate. No-op if nothing is filtered out. */\n  filter(predicate: (item: T) => boolean): void {\n    const filtered = this._items.filter(predicate);\n    if (filtered.length === this._items.length) return;\n    this._items = Object.freeze(filtered);\n    this.notify();\n  }\n\n  /** Replace all items and update cursor/hasMore atomically. Ideal for pull-to-refresh. */\n  replacePage(page: FeedPage<T>): void {\n    this._items = Object.freeze([...page.items]);\n    this._hasMore = page.hasMore;\n    this._cursor = page.cursor ?? null;\n    this.notify();\n  }\n\n  /** Reset to initial empty state with hasMore=true. */\n  reset(): void {\n    this._cursor = null;\n    this._hasMore = true;\n    this._items = Object.freeze([] as T[]);\n    this.notify();\n  }\n}\n"],"names":["Trackable"],"mappings":";;;AAcO,MAAM,aAA0BA,UAAAA,UAAU;AAAA,EACvC,UAAyB;AAAA,EACzB,WAAoB;AAAA,EACpB,SAAuB,OAAO,OAAO,EAAS;AAAA,EAEtD,cAAc;AACZ,UAAA;AAAA,EACF;AAAA;AAAA;AAAA,EAKA,IAAI,SAAwB;AAC1B,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,UAAmB;AACrB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,QAAsB;AACxB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,QAAgB;AAClB,WAAO,KAAK,OAAO;AAAA,EACrB;AAAA;AAAA;AAAA,EAKA,UAAU,QAA4D;AACpE,SAAK,WAAW,OAAO;AACvB,SAAK,UAAU,OAAO,UAAU;AAChC,SAAK,OAAA;AAAA,EACP;AAAA;AAAA,EAGA,WAAW,MAAyB;AAClC,SAAK,SAAS,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,GAAG,KAAK,KAAK,CAAC;AAC3D,SAAK,WAAW,KAAK;AACrB,SAAK,UAAU,KAAK,UAAU;AAC9B,SAAK,OAAA;AAAA,EACP;AAAA;AAAA,EAGA,YAAY,MAAyB;AACnC,SAAK,SAAS,OAAO,OAAO,CAAC,GAAG,KAAK,OAAO,GAAG,KAAK,MAAM,CAAC;AAC3D,SAAK,WAAW,KAAK;AACrB,SAAK,UAAU,KAAK,UAAU;AAC9B,SAAK,OAAA;AAAA,EACP;AAAA;AAAA,EAGA,QAAQ,OAAkB;AACxB,QAAI,MAAM,WAAW,EAAG;AACxB,SAAK,SAAS,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,GAAG,KAAK,CAAC;AACtD,SAAK,OAAA;AAAA,EACP;AAAA;AAAA,EAGA,OAAO,WAAuC;AAC5C,UAAM,WAAW,KAAK,OAAO,OAAO,SAAS;AAC7C,QAAI,SAAS,WAAW,KAAK,OAAO,OAAQ;AAC5C,SAAK,SAAS,OAAO,OAAO,QAAQ;AACpC,SAAK,OAAA;AAAA,EACP;AAAA;AAAA,EAGA,YAAY,MAAyB;AACnC,SAAK,SAAS,OAAO,OAAO,CAAC,GAAG,KAAK,KAAK,CAAC;AAC3C,SAAK,WAAW,KAAK;AACrB,SAAK,UAAU,KAAK,UAAU;AAC9B,SAAK,OAAA;AAAA,EACP;AAAA;AAAA,EAGA,QAAc;AACZ,SAAK,UAAU;AACf,SAAK,WAAW;AAChB,SAAK,SAAS,OAAO,OAAO,CAAA,CAAS;AACrC,SAAK,OAAA;AAAA,EACP;AACF;;"}

package/dist/Feed.d.ts

@@ -1,3 +1,4 @@
+import { Trackable } from './Trackable';
 /** Represents a page of items from a paginated API response. */
 export interface FeedPage<T> {
     items: T[];
@@ -9,11 +10,10 @@ export interface FeedPage<T> {
  * Accumulates items across pages, tracks cursor position and hasMore flag.
  * Subscribable — auto-tracked when used as a ViewModel property.
  */
-export declare class Feed<T = unknown> {
+export declare class Feed<T = unknown> extends Trackable {
     private _cursor;
     private _hasMore;
     private _items;
-    private _listeners;
     constructor();
     /** Current cursor position for the next page fetch, or null if at the beginning. */
     get cursor(): string | null;
@@ -40,8 +40,5 @@ export declare class Feed<T = unknown> {
     replacePage(page: FeedPage<T>): void;
     /** Reset to initial empty state with hasMore=true. */
     reset(): void;
-    /** Subscribe to feed state changes. Returns an unsubscribe function. */
-    subscribe(cb: () => void): () => void;
-    private _notify;
 }
 //# sourceMappingURL=Feed.d.ts.map

package/dist/Feed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Feed.d.ts","sourceRoot":"","sources":["../src/Feed.ts"],"names":[],"mappings":"AAEA,gEAAgE;AAChE,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;GAIG;AACH,qBAAa,IAAI,CAAC,CAAC,GAAG,OAAO;IAC3B,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,MAAM,CAA0C;IACxD,OAAO,CAAC,UAAU,CAAyB;;IAQ3C,oFAAoF;IACpF,IAAI,MAAM,IAAI,MAAM,GAAG,IAAI,CAE1B;IAED,wDAAwD;IACxD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,iDAAiD;IACjD,IAAI,KAAK,IAAI,SAAS,CAAC,EAAE,CAExB;IAED,yCAAyC;IACzC,IAAI,KAAK,IAAI,MAAM,CAElB;IAID,+EAA+E;IAC/E,SAAS,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI;IAMrE,mDAAmD;IACnD,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI;IAOnC,oDAAoD;IACpD,WAAW,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI;IAOpC,kDAAkD;IAClD,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAMzB,qFAAqF;IACrF,MAAM,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,IAAI;IAO7C,yFAAyF;IACzF,WAAW,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI;IAOpC,sDAAsD;IACtD,KAAK,IAAI,IAAI;IASb,wEAAwE;IACxE,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKrC,OAAO,CAAC,OAAO;CAGhB"}
+{"version":3,"file":"Feed.d.ts","sourceRoot":"","sources":["../src/Feed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,gEAAgE;AAChE,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;GAIG;AACH,qBAAa,IAAI,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,SAAS;IAC9C,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,MAAM,CAA0C;;IAQxD,oFAAoF;IACpF,IAAI,MAAM,IAAI,MAAM,GAAG,IAAI,CAE1B;IAED,wDAAwD;IACxD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,iDAAiD;IACjD,IAAI,KAAK,IAAI,SAAS,CAAC,EAAE,CAExB;IAED,yCAAyC;IACzC,IAAI,KAAK,IAAI,MAAM,CAElB;IAID,+EAA+E;IAC/E,SAAS,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI;IAMrE,mDAAmD;IACnD,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI;IAOnC,oDAAoD;IACpD,WAAW,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI;IAOpC,kDAAkD;IAClD,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAMzB,qFAAqF;IACrF,MAAM,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,IAAI;IAO7C,yFAAyF;IACzF,WAAW,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI;IAOpC,sDAAsD;IACtD,KAAK,IAAI,IAAI;CAMd"}