mvc-kit 2.12.0 → 2.12.2

package/src/ViewModel.derived.test.ts

@@ -0,0 +1,1583 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ViewModel } from './ViewModel';
+import { Collection } from './Collection';
+
+// ============================================================================
+// Test Setup Classes
+// ============================================================================
+
+interface Item {
+  id: string;
+  name: string;
+  role?: string;
+  status?: string;
+}
+
+class TestCollection extends Collection<Item> {}
+
+interface FilterState {
+  search: string;
+  statusFilter: string;
+  loading: boolean;
+  error: string | null;
+}
+
+class FilterViewModel extends ViewModel<FilterState> {
+  collection = new TestCollection();
+
+  get filtered(): Item[] {
+    const { search, statusFilter } = this.state;
+    let items = [...this.collection.items];
+    if (search) {
+      const q = search.toLowerCase();
+      items = items.filter((i) => i.name.toLowerCase().includes(q));
+    }
+    if (statusFilter !== 'all') {
+      items = items.filter((i) => i.status === statusFilter);
+    }
+    return items;
+  }
+
+  get total(): number {
+    return this.collection.length;
+  }
+
+  get hasResults(): boolean {
+    return this.filtered.length > 0;
+  }
+
+  get activeFilterCount(): number {
+    let count = 0;
+    if (this.state.search) count++;
+    if (this.state.statusFilter !== 'all') count++;
+    return count;
+  }
+
+  setSearch(search: string) {
+    this.set({ search });
+  }
+  setStatusFilter(statusFilter: string) {
+    this.set({ statusFilter });
+  }
+  setLoading(loading: boolean) {
+    this.set({ loading });
+  }
+}
+
+// VM with counter to track getter executions
+class CountedFilterViewModel extends FilterViewModel {
+  filteredCallCount = 0;
+  totalCallCount = 0;
+  hasResultsCallCount = 0;
+  activeFilterCountCallCount = 0;
+
+  override get filtered(): Item[] {
+    this.filteredCallCount++;
+    return super.filtered;
+  }
+
+  override get total(): number {
+    this.totalCallCount++;
+    return super.total;
+  }
+
+  override get hasResults(): boolean {
+    this.hasResultsCallCount++;
+    return super.hasResults;
+  }
+
+  override get activeFilterCount(): number {
+    this.activeFilterCountCallCount++;
+    return super.activeFilterCount;
+  }
+}
+
+// ============================================================================
+// State Proxy Tracking
+// ============================================================================
+
+describe('State Proxy Tracking', () => {
+  it('state proxy records accessed keys during tracking', () => {
+    const vm = new CountedFilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+      { id: '2', name: 'Bob', status: 'inactive' },
+    ]);
+    vm.init();
+
+    // First access - tracking records search and statusFilter
+    const result1 = vm.filtered;
+    expect(result1).toHaveLength(2);
+    expect(vm.filteredCallCount).toBe(1);
+
+    // Change search - should invalidate
+    vm.setSearch('ali');
+    const result2 = vm.filtered;
+    expect(result2).toHaveLength(1);
+    expect(vm.filteredCallCount).toBe(2);
+
+    // Change loading (not accessed in getter) - should NOT invalidate
+    vm.setLoading(true);
+    const result3 = vm.filtered;
+    expect(result3).toBe(result2); // Same reference
+    expect(vm.filteredCallCount).toBe(2); // No recompute
+  });
+
+  it('state proxy does not record when tracking is inactive', () => {
+    const vm = new FilterViewModel({
+      search: 'test',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+
+    // Before init, state proxy is just a plain accessor
+    const searchValue = vm.state.search;
+    expect(searchValue).toBe('test');
+
+    // No tracking should have occurred
+    // (This is implicit - we can't directly check tracking, but we verify
+    // that getters work as plain accessors before init)
+  });
+
+  it('state proxy prevents direct mutation', () => {
+    const vm = new FilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.init();
+
+    expect(() => {
+      (vm.state as any).search = 'test';
+    }).toThrow(); // Frozen state prevents direct mutation
+  });
+});
+
+// ============================================================================
+// Auto-Memoized Getters - Basic
+// ============================================================================
+
+describe('Auto-Memoized Getters - Basic', () => {
+  it('getter computes correct value on first access', () => {
+    const vm = new FilterViewModel({
+      search: 'ali',
+      statusFilter: 'active',
+      loading: false,
+      error: null,
+    });
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+      { id: '2', name: 'Bob', status: 'active' },
+      { id: '3', name: 'Charlie', status: 'inactive' },
+    ]);
+    vm.init();
+
+    const result = vm.filtered;
+    expect(result).toEqual([{ id: '1', name: 'Alice', status: 'active' }]);
+  });
+
+  it('getter returns cached reference on repeated access', () => {
+    const vm = new CountedFilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+      { id: '2', name: 'Bob', status: 'inactive' },
+    ]);
+    vm.init();
+
+    const result1 = vm.filtered;
+    const result2 = vm.filtered;
+    const result3 = vm.filtered;
+
+    expect(result1).toBe(result2);
+    expect(result2).toBe(result3);
+    expect(vm.filteredCallCount).toBe(1); // Computed only once
+  });
+
+  it('getter recomputes when a dependency changes', () => {
+    const vm = new CountedFilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+      { id: '2', name: 'Bob', status: 'inactive' },
+    ]);
+    vm.init();
+
+    const result1 = vm.filtered;
+    expect(result1).toHaveLength(2);
+    expect(vm.filteredCallCount).toBe(1);
+
+    vm.setSearch('ali');
+    const result2 = vm.filtered;
+    expect(result2).toHaveLength(1);
+    expect(result2).not.toBe(result1); // Different reference
+    expect(vm.filteredCallCount).toBe(2);
+  });
+
+  it('getter does NOT recompute when unrelated state changes', () => {
+    const vm = new CountedFilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+      { id: '2', name: 'Bob', status: 'inactive' },
+    ]);
+    vm.init();
+
+    const result1 = vm.filtered;
+    expect(vm.filteredCallCount).toBe(1);
+
+    vm.setLoading(true);
+    const result2 = vm.filtered;
+    expect(result2).toBe(result1); // Same reference
+    expect(vm.filteredCallCount).toBe(1); // No recompute
+  });
+
+  it('getter handles empty initial state', () => {
+    const vm = new FilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.init();
+
+    const result = vm.filtered;
+    expect(result).toEqual([]);
+  });
+});
+
+// ============================================================================
+// Conditional Dependencies
+// ============================================================================
+
+describe('Conditional Dependencies', () => {
+  interface ModeState {
+    mode: string;
+    title: string;
+    subtitle: string;
+  }
+
+  class ModeVM extends ViewModel<ModeState> {
+    displayCallCount = 0;
+
+    get display(): string {
+      this.displayCallCount++;
+      if (this.state.mode === 'compact') return this.state.title;
+      return `${this.state.title} — ${this.state.subtitle}`;
+    }
+
+    setMode(mode: string) {
+      this.set({ mode });
+    }
+    setTitle(title: string) {
+      this.set({ title });
+    }
+    setSubtitle(subtitle: string) {
+      this.set({ subtitle });
+    }
+  }
+
+  it('getter re-tracks deps when conditional branches change', () => {
+    const vm = new ModeVM({
+      mode: 'compact',
+      title: 'Hello',
+      subtitle: 'World',
+    });
+    vm.init();
+
+    // In compact mode, only title is accessed
+    const result1 = vm.display;
+    expect(result1).toBe('Hello');
+    expect(vm.displayCallCount).toBe(1);
+
+    // Change subtitle - should NOT recompute (not a dependency in compact mode)
+    vm.setSubtitle('Universe');
+    const result2 = vm.display;
+    expect(result2).toBe(result1); // Same reference
+    expect(vm.displayCallCount).toBe(1);
+
+    // Switch to full mode - recompute and re-track
+    vm.setMode('full');
+    const result3 = vm.display;
+    expect(result3).toBe('Hello — Universe');
+    expect(vm.displayCallCount).toBe(2);
+
+    // Now subtitle IS a dependency - should recompute
+    vm.setSubtitle('Galaxy');
+    const result4 = vm.display;
+    expect(result4).toBe('Hello — Galaxy');
+    expect(vm.displayCallCount).toBe(3);
+  });
+});
+
+// ============================================================================
+// Getter Composition (Nested)
+// ============================================================================
+
+describe('Getter Composition (Nested)', () => {
+  it('getter reads another getter and composes correctly', () => {
+    const vm = new FilterViewModel({
+      search: 'ali',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+      { id: '2', name: 'Bob', status: 'inactive' },
+    ]);
+    vm.init();
+
+    const hasResults = vm.hasResults;
+    expect(hasResults).toBe(true);
+  });
+
+  it('nested getter invalidates on transitive dependency', () => {
+    const vm = new CountedFilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+      { id: '2', name: 'Bob', status: 'inactive' },
+    ]);
+    vm.init();
+
+    const hasResults1 = vm.hasResults;
+    expect(hasResults1).toBe(true);
+    expect(vm.hasResultsCallCount).toBe(1);
+    expect(vm.filteredCallCount).toBe(1);
+
+    // Set search to something that matches nothing
+    vm.setSearch('xyz');
+    const hasResults2 = vm.hasResults;
+    expect(hasResults2).toBe(false);
+    expect(vm.hasResultsCallCount).toBe(2); // hasResults recomputed
+    expect(vm.filteredCallCount).toBe(2); // filtered recomputed (dependency of hasResults)
+  });
+
+  it('nested getter caches when non-dependency changes', () => {
+    const vm = new CountedFilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+      { id: '2', name: 'Bob', status: 'inactive' },
+    ]);
+    vm.init();
+
+    const hasResults1 = vm.hasResults;
+    expect(hasResults1).toBe(true);
+    expect(vm.hasResultsCallCount).toBe(1);
+
+    vm.setLoading(true);
+    const hasResults2 = vm.hasResults;
+    expect(hasResults2).toBe(hasResults1);
+    expect(vm.hasResultsCallCount).toBe(1); // No recompute
+  });
+
+  it('two sibling getters sharing a nested getter both update on collection change', () => {
+    // This is the exact bug scenario: filteredCount accesses `filtered` first,
+    // then paged accesses `filtered` second via Tier 1 cache hit.
+    // Without dep bubbling, paged misses the collection dependency.
+    class PaginatedVM extends ViewModel<FilterState> {
+      collection = new TestCollection();
+      filteredCallCount = 0;
+      filteredCountCallCount = 0;
+      pagedCallCount = 0;
+
+      get filtered(): Item[] {
+        this.filteredCallCount++;
+        const { search } = this.state;
+        let items = [...this.collection.items];
+        if (search) {
+          const q = search.toLowerCase();
+          items = items.filter((i) => i.name.toLowerCase().includes(q));
+        }
+        return items;
+      }
+
+      get filteredCount(): number {
+        this.filteredCountCallCount++;
+        return this.filtered.length;
+      }
+
+      get paged(): Item[] {
+        this.pagedCallCount++;
+        return this.filtered.slice(0, 2);
+      }
+
+      setSearch(search: string) { this.set({ search }); }
+    }
+
+    const vm = new PaginatedVM({ search: '', statusFilter: 'all', loading: false, error: null });
+    vm.init();
+
+    // Access filteredCount FIRST, then paged (same order as the component)
+    expect(vm.filteredCount).toBe(0);
+    expect(vm.paged).toEqual([]);
+
+    // Populate collection
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+      { id: '2', name: 'Bob', status: 'inactive' },
+      { id: '3', name: 'Charlie', status: 'active' },
+    ]);
+
+    // BOTH getters must update — this was the bug
+    expect(vm.filteredCount).toBe(3);
+    expect(vm.paged).toHaveLength(2);
+    expect(vm.paged[0].name).toBe('Alice');
+  });
+
+  it('sibling getters update regardless of access order (reversed)', () => {
+    class PaginatedVM extends ViewModel<FilterState> {
+      collection = new TestCollection();
+
+      get filtered(): Item[] {
+        const { search } = this.state;
+        let items = [...this.collection.items];
+        if (search) {
+          const q = search.toLowerCase();
+          items = items.filter((i) => i.name.toLowerCase().includes(q));
+        }
+        return items;
+      }
+
+      get filteredCount(): number {
+        return this.filtered.length;
+      }
+
+      get paged(): Item[] {
+        return this.filtered.slice(0, 2);
+      }
+
+      setSearch(search: string) { this.set({ search }); }
+    }
+
+    const vm = new PaginatedVM({ search: '', statusFilter: 'all', loading: false, error: null });
+    vm.init();
+
+    // Access paged FIRST, then filteredCount (reversed order)
+    expect(vm.paged).toEqual([]);
+    expect(vm.filteredCount).toBe(0);
+
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+      { id: '2', name: 'Bob', status: 'inactive' },
+    ]);
+
+    // Both must update regardless of access order
+    expect(vm.paged).toHaveLength(2);
+    expect(vm.filteredCount).toBe(2);
+  });
+
+  it('sibling getters both recompute after state dep change (counter verification)', () => {
+    class PaginatedVM extends ViewModel<FilterState> {
+      collection = new TestCollection();
+      filteredCallCount = 0;
+      filteredCountCallCount = 0;
+      pagedCallCount = 0;
+
+      get filtered(): Item[] {
+        this.filteredCallCount++;
+        const { search } = this.state;
+        let items = [...this.collection.items];
+        if (search) {
+          const q = search.toLowerCase();
+          items = items.filter((i) => i.name.toLowerCase().includes(q));
+        }
+        return items;
+      }
+
+      get filteredCount(): number {
+        this.filteredCountCallCount++;
+        return this.filtered.length;
+      }
+
+      get paged(): Item[] {
+        this.pagedCallCount++;
+        return this.filtered.slice(0, 2);
+      }
+
+      setSearch(search: string) { this.set({ search }); }
+    }
+
+    const vm = new PaginatedVM({ search: '', statusFilter: 'all', loading: false, error: null });
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+      { id: '2', name: 'Bob', status: 'inactive' },
+      { id: '3', name: 'Charlie', status: 'active' },
+    ]);
+    vm.init();
+
+    // Initial access: filteredCount first, paged second
+    expect(vm.filteredCount).toBe(3);
+    expect(vm.paged).toHaveLength(2);
+    // filtered called once by filteredCount (Tier 3), then Tier 1 cache hit for paged
+    expect(vm.filteredCallCount).toBe(1);
+    expect(vm.filteredCountCallCount).toBe(1);
+    expect(vm.pagedCallCount).toBe(1);
+
+    // Change a state dep (search) — both siblings must recompute
+    vm.setSearch('ali');
+    expect(vm.filteredCount).toBe(1);
+    expect(vm.paged).toHaveLength(1);
+    expect(vm.filteredCountCallCount).toBe(2);
+    expect(vm.pagedCallCount).toBe(2);
+  });
+
+  it('three-level nesting: grandchild deps bubble through all levels', () => {
+    // Chain: summary → paged → sorted → filtered → collection
+    class DeepChainVM extends ViewModel<FilterState> {
+      collection = new TestCollection();
+      filteredCallCount = 0;
+      sortedCallCount = 0;
+      pagedCallCount = 0;
+      summaryCallCount = 0;
+
+      get filtered(): Item[] {
+        this.filteredCallCount++;
+        const { search } = this.state;
+        let items = [...this.collection.items];
+        if (search) {
+          const q = search.toLowerCase();
+          items = items.filter((i) => i.name.toLowerCase().includes(q));
+        }
+        return items;
+      }
+
+      get sorted(): Item[] {
+        this.sortedCallCount++;
+        return [...this.filtered].sort((a, b) => a.name.localeCompare(b.name));
+      }
+
+      get paged(): Item[] {
+        this.pagedCallCount++;
+        return this.sorted.slice(0, 2);
+      }
+
+      get summary(): string {
+        this.summaryCallCount++;
+        return `Showing ${this.paged.length} of ${this.filtered.length}`;
+      }
+
+      setSearch(search: string) { this.set({ search }); }
+    }
+
+    const vm = new DeepChainVM({ search: '', statusFilter: 'all', loading: false, error: null });
+    vm.init();
+
+    expect(vm.summary).toBe('Showing 0 of 0');
+
+    vm.collection.reset([
+      { id: '1', name: 'Charlie', status: 'active' },
+      { id: '2', name: 'Alice', status: 'active' },
+      { id: '3', name: 'Bob', status: 'active' },
+    ]);
+
+    expect(vm.summary).toBe('Showing 2 of 3');
+    expect(vm.paged[0].name).toBe('Alice'); // sorted
+
+    vm.setSearch('ali');
+    expect(vm.summary).toBe('Showing 1 of 1');
+    expect(vm.paged[0].name).toBe('Alice');
+  });
+});
+
+// ============================================================================
+// Getter Inheritance
+// ============================================================================
+
+describe('Getter Inheritance', () => {
+  interface BaseState {
+    items: Item[];
+    search: string;
+  }
+
+  class BaseListVM extends ViewModel<BaseState> {
+    isEmptyCallCount = 0;
+
+    get isEmpty(): boolean {
+      this.isEmptyCallCount++;
+      return this.state.items.length === 0;
+    }
+  }
+
+  class DerivedVM extends BaseListVM {
+    filteredCallCount = 0;
+
+    get filtered(): Item[] {
+      this.filteredCallCount++;
+      return this.state.items.filter((i) => i.name.includes(this.state.search));
+    }
+
+    setSearch(s: string) {
+      this.set({ search: s });
+    }
+
+    setItems(items: Item[]) {
+      this.set({ items });
+    }
+  }
+
+  it('getters from parent classes are memoized', () => {
+    const vm = new DerivedVM({
+      items: [],
+      search: '',
+    });
+    vm.init();
+
+    const isEmpty1 = vm.isEmpty;
+    expect(isEmpty1).toBe(true);
+    expect(vm.isEmptyCallCount).toBe(1);
+
+    const filtered1 = vm.filtered;
+    expect(filtered1).toEqual([]);
+    expect(vm.filteredCallCount).toBe(1);
+  });
+
+  it('subclass getter override replaces parent', () => {
+    interface LabelState {
+      name: string;
+    }
+
+    class ParentVM extends ViewModel<LabelState> {
+      get label(): string {
+        return 'parent';
+      }
+    }
+
+    class ChildVM extends ParentVM {
+      override get label(): string {
+        return this.state.name;
+      }
+
+      setName(name: string) {
+        this.set({ name });
+      }
+    }
+
+    const vm = new ChildVM({ name: 'child' });
+    vm.init();
+
+    expect(vm.label).toBe('child');
+  });
+});
+
+// ============================================================================
+// Subscribable Auto-Detection
+// ============================================================================
+
+describe('Subscribable Auto-Detection', () => {
+  it('subscribable members are detected and subscribed', () => {
+    const vm = new FilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+    ]);
+    vm.init();
+
+    const listener = vi.fn();
+    vm.subscribe(listener);
+
+    vm.collection.reset([
+      { id: '2', name: 'Bob', status: 'inactive' },
+    ]);
+
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  it('subscribable notification does not create new state reference', () => {
+    const vm = new FilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+    ]);
+    vm.init();
+
+    const stateBefore = vm.state;
+
+    vm.collection.reset([
+      { id: '2', name: 'Bob', status: 'inactive' },
+    ]);
+
+    // State reference is unchanged — subscribable notifications no longer
+    // spread a new object, since React detection uses a version counter
+    expect(vm.state).toBe(stateBefore);
+  });
+
+  it('non-subscribable members are ignored', () => {
+    interface VMState {
+      count: number;
+    }
+
+    class VMWithPlainObject extends ViewModel<VMState> {
+      plainObject = { value: 42 };
+
+      get doubled(): number {
+        return this.state.count * 2;
+      }
+    }
+
+    const vm = new VMWithPlainObject({ count: 5 });
+    vm.init();
+
+    // Should not throw, plainObject is ignored
+    expect(vm.doubled).toBe(10);
+  });
+
+  it('subscribable notification bumps revision and triggers notify', () => {
+    const vm = new FilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+    ]);
+    vm.init();
+
+    const listener = vi.fn();
+    vm.subscribe(listener);
+
+    vm.collection.reset([
+      { id: '2', name: 'Bob', status: 'inactive' },
+    ]);
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    // Listener called with (state, state) — same object reference
+    expect(listener).toHaveBeenCalledWith(vm.state, vm.state);
+  });
+
+  it('multiple subscribable members tracked independently', () => {
+    interface TwoCollectionsState {
+      label: string;
+    }
+
+    class TwoCollectionsVM extends ViewModel<TwoCollectionsState> {
+      collection1 = new TestCollection();
+      collection2 = new TestCollection();
+
+      collection1Count = 0;
+      collection2Count = 0;
+
+      get fromCollection1() {
+        this.collection1Count++;
+        return this.collection1.items;
+      }
+
+      get fromCollection2() {
+        this.collection2Count++;
+        return this.collection2.items;
+      }
+    }
+
+    const vm = new TwoCollectionsVM({ label: 'test' });
+    vm.collection1.reset([{ id: '1', name: 'Alice' }]);
+    vm.collection2.reset([{ id: '2', name: 'Bob' }]);
+    vm.init();
+
+    const result1 = vm.fromCollection1;
+    expect(result1).toHaveLength(1);
+    expect(vm.collection1Count).toBe(1);
+
+    // Change collection2 - should NOT invalidate fromCollection1
+    vm.collection2.reset([{ id: '3', name: 'Charlie' }]);
+    const result1Again = vm.fromCollection1;
+    expect(result1Again).toBe(result1); // Same reference
+    expect(vm.collection1Count).toBe(1); // No recompute
+
+    // Change collection1 - SHOULD invalidate fromCollection1
+    vm.collection1.reset([{ id: '4', name: 'Diana' }]);
+    const result1Updated = vm.fromCollection1;
+    expect(result1Updated).not.toBe(result1);
+    expect(vm.collection1Count).toBe(2);
+  });
+
+  it('subscribable member async state changes invalidate parent getters', async () => {
+    let resolveLoad!: () => void;
+
+    class ChildVM extends ViewModel {
+      async loadData() {
+        await new Promise<void>((r) => { resolveLoad = r; });
+      }
+    }
+
+    class ParentVM extends ViewModel {
+      childVM = new ChildVM();
+
+      get isChildLoading() {
+        return this.childVM.async.loadData.loading;
+      }
+
+      onInit() {
+        this.childVM.init();
+      }
+
+      onDispose() {
+        this.childVM.dispose();
+      }
+    }
+
+    const parent = new ParentVM();
+    parent.init();
+
+    // Initially not loading
+    expect(parent.isChildLoading).toBe(false);
+
+    // Start the async operation on the child
+    const loadPromise = parent.childVM.loadData();
+    // Allow microtask to propagate async tracking
+    await Promise.resolve();
+
+    // Parent getter should now reflect loading = true
+    expect(parent.isChildLoading).toBe(true);
+
+    // Verify parent.subscribe fires on child async changes
+    const listener = vi.fn();
+    parent.subscribe(listener);
+
+    // Resolve the async operation
+    resolveLoad();
+    await loadPromise;
+
+    // Parent getter should return to false
+    expect(parent.isChildLoading).toBe(false);
+    // Listener should have been called (child async → parent notification)
+    expect(listener).toHaveBeenCalled();
+
+    parent.dispose();
+  });
+});
+
+// ============================================================================
+// Subscribable Dependencies in Getters
+// ============================================================================
+
+describe('Subscribable Dependencies in Getters', () => {
+  it('getter that reads collection depends on collection', () => {
+    const vm = new CountedFilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+    ]);
+    vm.init();
+
+    const result1 = vm.filtered;
+    expect(result1).toHaveLength(1);
+    expect(vm.filteredCallCount).toBe(1);
+
+    vm.collection.reset([
+      { id: '2', name: 'Bob', status: 'inactive' },
+      { id: '3', name: 'Charlie', status: 'active' },
+    ]);
+    const result2 = vm.filtered;
+    expect(result2).toHaveLength(2);
+    expect(vm.filteredCallCount).toBe(2);
+  });
+
+  it('getter does not recompute when unrelated subscribable changes', () => {
+    interface TwoCollectionsState {
+      label: string;
+    }
+
+    class TwoCollectionsVM extends ViewModel<TwoCollectionsState> {
+      collection1 = new TestCollection();
+      collection2 = new TestCollection();
+      callCount = 0;
+
+      get fromCollection1() {
+        this.callCount++;
+        return this.collection1.items;
+      }
+    }
+
+    const vm = new TwoCollectionsVM({ label: 'test' });
+    vm.collection1.reset([{ id: '1', name: 'Alice' }]);
+    vm.collection2.reset([{ id: '2', name: 'Bob' }]);
+    vm.init();
+
+    const result1 = vm.fromCollection1;
+    expect(result1).toHaveLength(1);
+    expect(vm.callCount).toBe(1);
+
+    // Change unrelated collection2
+    vm.collection2.reset([{ id: '3', name: 'Charlie' }]);
+    const result2 = vm.fromCollection1;
+    expect(result2).toBe(result1); // Same reference
+    expect(vm.callCount).toBe(1); // No recompute
+  });
+
+  it('getter with mixed state + subscribable deps', () => {
+    const vm = new CountedFilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+      { id: '2', name: 'Bob', status: 'inactive' },
+    ]);
+    vm.init();
+
+    // Initial access
+    const result1 = vm.filtered;
+    expect(result1).toHaveLength(2);
+    expect(vm.filteredCallCount).toBe(1);
+
+    // 1) Change state dep -> recompute
+    vm.setSearch('ali');
+    const result2 = vm.filtered;
+    expect(result2).toHaveLength(1);
+    expect(vm.filteredCallCount).toBe(2);
+
+    // 2) Change unrelated state -> no recompute
+    vm.setLoading(true);
+    const result3 = vm.filtered;
+    expect(result3).toBe(result2);
+    expect(vm.filteredCallCount).toBe(2);
+
+    // 3) Change collection -> recompute
+    vm.collection.reset([
+      { id: '3', name: 'Alice Cooper', status: 'active' },
+    ]);
+    const result4 = vm.filtered;
+    expect(result4).toHaveLength(1);
+    expect(result4[0].name).toBe('Alice Cooper');
+    expect(vm.filteredCallCount).toBe(3);
+  });
+});
+
+// ============================================================================
+// Cleanup and Dispose
+// ============================================================================
+
+describe('Cleanup and Dispose', () => {
+  it('dispose unsubscribes from all tracked sources', () => {
+    const vm = new FilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+    ]);
+    vm.init();
+
+    const listener = vi.fn();
+    vm.subscribe(listener);
+
+    // Trigger notification before dispose
+    vm.collection.reset([{ id: '2', name: 'Bob', status: 'inactive' }]);
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    vm.dispose();
+
+    // After dispose, collection changes should not trigger VM notifications
+    vm.collection.reset([{ id: '3', name: 'Charlie', status: 'active' }]);
+    expect(listener).toHaveBeenCalledTimes(1); // Still 1, no new calls
+  });
+
+  it('collection changes after dispose do not trigger notify', () => {
+    const vm = new FilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+    ]);
+    vm.init();
+
+    const listener = vi.fn();
+    vm.subscribe(listener);
+
+    vm.dispose();
+
+    vm.collection.reset([{ id: '2', name: 'Bob', status: 'inactive' }]);
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it('getter access after dispose returns last cached value', () => {
+    const vm = new CountedFilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+    ]);
+    vm.init();
+
+    const result1 = vm.filtered;
+    expect(result1).toHaveLength(1);
+    expect(vm.filteredCallCount).toBe(1);
+
+    vm.dispose();
+
+    const result2 = vm.filtered;
+    expect(result2).toBe(result1); // Same cached value
+    expect(vm.filteredCallCount).toBe(1); // No recompute
+  });
+});
+
+// ============================================================================
+// Revision Counter
+// ============================================================================
+
+describe('Revision Counter', () => {
+  it('revision starts at 0 (implicit via Tier 3 behavior)', () => {
+    const vm = new CountedFilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.init();
+
+    // First getter access always computes (revision 0 -> Tier 3)
+    // @ts-expect-error
+    const result = vm.filtered;
+    expect(vm.filteredCallCount).toBe(1);
+  });
+
+  it('set() with actual changes increments revision', () => {
+    const vm = new CountedFilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.init();
+
+    vm.filtered; // Initial compute
+    expect(vm.filteredCallCount).toBe(1);
+
+    vm.setSearch('ali'); // Changes state -> increments revision
+    vm.filtered; // Should recompute
+    expect(vm.filteredCallCount).toBe(2);
+  });
+
+  it('set() with no changes does NOT increment revision', () => {
+    const vm = new CountedFilterViewModel({
+      search: 'ali',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.init();
+
+    vm.filtered; // Initial compute
+    expect(vm.filteredCallCount).toBe(1);
+
+    vm.setSearch('ali'); // Same value -> no change, no revision increment
+    vm.filtered; // Should NOT recompute
+    expect(vm.filteredCallCount).toBe(1);
+  });
+
+  it('subscribable notification increments revision', () => {
+    const vm = new CountedFilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.collection.reset([{ id: '1', name: 'Alice', status: 'active' }]);
+    vm.init();
+
+    vm.filtered; // Initial compute
+    expect(vm.filteredCallCount).toBe(1);
+
+    vm.collection.reset([{ id: '2', name: 'Bob', status: 'inactive' }]);
+    vm.filtered; // Should recompute due to revision increment
+    expect(vm.filteredCallCount).toBe(2);
+  });
+
+  it('multiple rapid set() calls each increment revision', () => {
+    const vm = new CountedFilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.init();
+
+    vm.filtered;
+    expect(vm.filteredCallCount).toBe(1);
+
+    vm.setSearch('a');
+    vm.setSearch('ab');
+    vm.setSearch('abc');
+
+    vm.filtered;
+    expect(vm.filteredCallCount).toBe(2); // Only one recompute after all changes
+  });
+});
+
+// ============================================================================
+//  Dev-Mode Safety
+// ============================================================================
+
+describe(' Dev-Mode Safety', () => {
+  it('set() inside a getter logs error when __MVC_KIT_DEV__ is enabled', () => {
+    interface BadState {
+      count: number;
+      computed: string;
+    }
+
+    class BadVM extends ViewModel<BadState> {
+      get broken(): string {
+        this.publicSet({ count: 999 }); // BAD!
+        return 'bad';
+      }
+
+      publicSet(p: Partial<BadState>) {
+        this.set(p);
+      }
+    }
+
+    const vm = new BadVM({ count: 0, computed: '' });
+    vm.init();
+
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    vm.broken;
+
+    expect(consoleErrorSpy).toHaveBeenCalled();
+    expect(consoleErrorSpy.mock.calls[0][0]).toMatch(/set\(\) called inside a getter/i);
+    expect(vm.state.count).toBe(0); // State NOT mutated
+
+    consoleErrorSpy.mockRestore();
+  });
+});
+
+// ============================================================================
+//  Multiple Instances
+// ============================================================================
+
+describe(' Multiple Instances', () => {
+  it('two instances of same ViewModel class have independent caches', () => {
+    const vm1 = new CountedFilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm1.collection.reset([{ id: '1', name: 'Alice', status: 'active' }]);
+    vm1.init();
+
+    const vm2 = new CountedFilterViewModel({
+      search: 'bob',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm2.collection.reset([
+      { id: '2', name: 'Bob', status: 'inactive' },
+      { id: '3', name: 'Alice', status: 'active' },
+    ]);
+    vm2.init();
+
+    const result1 = vm1.filtered;
+    const result2 = vm2.filtered;
+
+    expect(result1).toHaveLength(1);
+    expect(result1[0].name).toBe('Alice');
+
+    expect(result2).toHaveLength(1);
+    expect(result2[0].name).toBe('Bob');
+
+    // Changes to vm1 should not affect vm2
+    vm1.setSearch('xyz');
+    const result1Updated = vm1.filtered;
+    const result2Again = vm2.filtered;
+
+    expect(result1Updated).toHaveLength(0);
+    expect(result2Again).toBe(result2); // vm2 unchanged
+  });
+
+  it('two instances sharing a singleton collection both react', () => {
+    const sharedCollection = new TestCollection();
+    sharedCollection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+      { id: '2', name: 'Bob', status: 'inactive' },
+    ]);
+
+    class SharedCollectionVM extends ViewModel<FilterState> {
+      constructor(initialState: FilterState, public collection: TestCollection) {
+        super(initialState);
+      }
+
+      get filtered() {
+        const { search } = this.state;
+        if (!search) return this.collection.items;
+        return this.collection.items.filter((i) =>
+          i.name.toLowerCase().includes(search.toLowerCase())
+        );
+      }
+    }
+
+    const vm1 = new SharedCollectionVM(
+      { search: '', statusFilter: 'all', loading: false, error: null },
+      sharedCollection
+    );
+    const vm2 = new SharedCollectionVM(
+      { search: '', statusFilter: 'all', loading: false, error: null },
+      sharedCollection
+    );
+
+    vm1.init();
+    vm2.init();
+
+    const listener1 = vi.fn();
+    const listener2 = vi.fn();
+    vm1.subscribe(listener1);
+    vm2.subscribe(listener2);
+
+    // Load data into shared collection
+    sharedCollection.reset([
+      { id: '3', name: 'Charlie', status: 'active' },
+    ]);
+
+    expect(listener1).toHaveBeenCalledTimes(1);
+    expect(listener2).toHaveBeenCalledTimes(1);
+
+    expect(vm1.filtered).toHaveLength(1);
+    expect(vm2.filtered).toHaveLength(1);
+  });
+});
+
+// ============================================================================
+//  Edge Cases
+// ============================================================================
+
+describe(' Edge Cases', () => {
+  it('getter with zero dependencies', () => {
+    interface ZeroDepState {
+      count: number;
+    }
+
+    class ZeroDepVM extends ViewModel<ZeroDepState> {
+      callCount = 0;
+
+      get constant(): string {
+        this.callCount++;
+        return 'always the same';
+      }
+
+      setCount(count: number) {
+        this.set({ count });
+      }
+    }
+
+    const vm = new ZeroDepVM({ count: 0 });
+    vm.init();
+
+    const result1 = vm.constant;
+    expect(result1).toBe('always the same');
+    expect(vm.callCount).toBe(1);
+
+    // Change state - getter should NOT recompute (no dependencies)
+    vm.setCount(10);
+    const result2 = vm.constant;
+    expect(result2).toBe(result1);
+    expect(vm.callCount).toBe(1);
+  });
+
+  it('getter that throws an error', () => {
+    interface ErrorState {
+      shouldThrow: boolean;
+    }
+
+    class ErrorVM extends ViewModel<ErrorState> {
+      callCount = 0;
+
+      get maybeThrow(): string {
+        this.callCount++;
+        if (this.state.shouldThrow) {
+          throw new Error('getter error');
+        }
+        return 'ok';
+      }
+
+      setThrow(shouldThrow: boolean) {
+        this.set({ shouldThrow });
+      }
+    }
+
+    const vm = new ErrorVM({ shouldThrow: true });
+    vm.init();
+
+    expect(() => vm.maybeThrow).toThrow('getter error');
+    expect(vm.callCount).toBe(1);
+
+    // Cache NOT populated, next access re-throws
+    expect(() => vm.maybeThrow).toThrow('getter error');
+    expect(vm.callCount).toBe(2);
+
+    // Fix the state
+    vm.setThrow(false);
+    const result = vm.maybeThrow;
+    expect(result).toBe('ok');
+    expect(vm.callCount).toBe(3);
+  });
+
+  it('getter accessing deeply nested collection data', () => {
+    class DeepAccessVM extends ViewModel<{ label: string }> {
+      collection = new TestCollection();
+
+      get firstName(): string | undefined {
+        return this.collection.items[0]?.name;
+      }
+    }
+
+    const vm = new DeepAccessVM({ label: 'test' });
+    vm.init();
+
+    // Empty collection
+    const result1 = vm.firstName;
+    expect(result1).toBeUndefined();
+
+    // Populate collection
+    vm.collection.reset([{ id: '1', name: 'Alice' }]);
+    const result2 = vm.firstName;
+    expect(result2).toBe('Alice');
+
+    // Clear collection
+    vm.collection.reset([]);
+    const result3 = vm.firstName;
+    expect(result3).toBeUndefined();
+  });
+
+  it('rapid state changes within same synchronous frame', () => {
+    const vm = new CountedFilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+      { id: '2', name: 'Bob', status: 'inactive' },
+      { id: '3', name: 'Alice Smith', status: 'active' },
+    ]);
+    vm.init();
+
+    // Multiple rapid changes
+    vm.setSearch('a');
+    vm.setSearch('al');
+    vm.setSearch('ali');
+
+    // After all changes, getter reflects final state
+    const result = vm.filtered;
+    expect(result).toHaveLength(2); // Alice and Alice Smith
+    expect(vm.filteredCallCount).toBe(1); // Computed once after all changes
+  });
+});
+
+// ============================================================================
+// Collection Data via Getters (without subscribeTo)
+// ============================================================================
+
+describe('Collection Data via Getters (without subscribeTo)', () => {
+  it('getters read collection data directly without subscribeTo or set()', () => {
+    // This is the prescribed pattern: getters read from collection members
+    // and auto-tracking handles reactivity. No subscribeTo() + set() needed.
+    const vm = new CountedFilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.init();
+
+    // Initially empty
+    expect(vm.filtered).toEqual([]);
+    expect(vm.total).toBe(0);
+
+    // Populate collection — getter recomputes via auto-tracked subscribable
+    vm.collection.reset([
+      { id: '1', name: 'Alice', status: 'active' },
+      { id: '2', name: 'Bob', status: 'inactive' },
+    ]);
+    expect(vm.filtered).toHaveLength(2);
+    expect(vm.total).toBe(2);
+
+    // Update collection — getter reflects new data
+    vm.collection.update('1', { id: '1', name: 'Alice Updated', status: 'active' });
+    expect(vm.filtered[0].name).toBe('Alice Updated');
+
+    // Filter via state — works with collection data
+    vm.setSearch('bob');
+    expect(vm.filtered).toHaveLength(1);
+    expect(vm.filtered[0].name).toBe('Bob');
+  });
+
+  it('subscriber notified on collection change without subscribeTo', () => {
+    const vm = new FilterViewModel({
+      search: '',
+      statusFilter: 'all',
+      loading: false,
+      error: null,
+    });
+    vm.init();
+
+    const listener = vi.fn();
+    vm.subscribe(listener);
+
+    // Collection change triggers notification to subscribers
+    // (auto-tracking detects the subscribable and wires it up)
+    vm.collection.reset([{ id: '1', name: 'Alice', status: 'active' }]);
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    // Subsequent changes also notify
+    vm.collection.reset([{ id: '2', name: 'Bob', status: 'inactive' }]);
+    expect(listener).toHaveBeenCalledTimes(2);
+  });
+
+  it('stateless ViewModel (empty state) reads all data from collections', () => {
+    // Pattern: ViewModel with S = {} and all data via getters
+    class StatelessDashboardVM extends ViewModel {
+      collection1 = new TestCollection();
+      collection2 = new TestCollection();
+
+      get totalItems(): number {
+        return this.collection1.length + this.collection2.length;
+      }
+
+      get allItems(): Item[] {
+        return [...this.collection1.items, ...this.collection2.items];
+      }
+    }
+
+    const vm = new StatelessDashboardVM();
+    vm.init();
+
+    expect(vm.totalItems).toBe(0);
+    expect(vm.allItems).toEqual([]);
+
+    vm.collection1.reset([{ id: '1', name: 'Alice' }]);
+    expect(vm.totalItems).toBe(1);
+
+    vm.collection2.reset([{ id: '2', name: 'Bob' }, { id: '3', name: 'Charlie' }]);
+    expect(vm.totalItems).toBe(3);
+    expect(vm.allItems).toHaveLength(3);
+  });
+
+  it('draft mode: getter invalidates correctly on nested mutation', () => {
+    interface ConfigState {
+      config: { theme: string; fontSize: number };
+      count: number;
+    }
+
+    class ConfigVM extends ViewModel<ConfigState> {
+      computeCount = 0;
+
+      get currentTheme() {
+        this.computeCount++;
+        return this.state.config.theme;
+      }
+
+      setTheme(theme: string) {
+        this.set((d) => { d.config.theme = theme; });
+      }
+
+      bumpCount() {
+        this.set((d) => { d.count = d.count + 1; });
+      }
+    }
+
+    const vm = new ConfigVM({ config: { theme: 'dark', fontSize: 14 }, count: 0 });
+    vm.init();
+
+    // First access → Tier 3 recompute
+    expect(vm.currentTheme).toBe('dark');
+    const countAfterFirst = vm.computeCount;
+
+    // Same access → Tier 1 (no revision change)
+    expect(vm.currentTheme).toBe('dark');
+    expect(vm.computeCount).toBe(countAfterFirst); // No recompute
+
+    // Draft mutation on a dep of this getter
+    vm.setTheme('light');
+    expect(vm.currentTheme).toBe('light');
+    expect(vm.computeCount).toBe(countAfterFirst + 1); // Recomputed
+
+    // Draft mutation on unrelated state — getter depends on config, not count
+    vm.bumpCount();
+    expect(vm.currentTheme).toBe('light');
+    // Tier 2 should detect that config reference didn't change → no recompute
+    expect(vm.computeCount).toBe(countAfterFirst + 1);
+  });
+
+  it('smart-init pattern works: skip load when collection has data', () => {
+    class SmartInitVM extends ViewModel {
+      collection = new TestCollection();
+      loadCalled = false;
+
+      protected onInit() {
+        if (this.collection.length === 0) {
+          this.loadCalled = true;
+        }
+      }
+
+      get items() {
+        return this.collection.items
+      }
+    }
+
+    // Scenario 1: empty collection → load is triggered
+    const vm1 = new SmartInitVM();
+    vm1.init();
+    expect(vm1.loadCalled).toBe(true);
+
+    // Scenario 2: pre-populated collection → load is skipped
+    const vm2 = new SmartInitVM();
+    vm2.collection.reset([{ id: '1', name: 'Alice' }]);
+    vm2.init();
+    expect(vm2.loadCalled).toBe(false);
+    expect(vm2.items).toHaveLength(1);
+  });
+});