ObsiViewer/docs/PERFORMENCE/phase2/INTEGRATION_CHECKLIST.md

# Phase 2 Integration Checklist

## Pre-Integration Verification

- [ ] All files created successfully
- [ ] No compilation errors
- [ ] Server starts without errors: `npm run dev`
- [ ] Pagination endpoint responds: `npm run test:pagination`

## Integration Steps

### Step 1: Identify Parent Component (5 min)

- [ ] Locate the component that currently uses `NotesListComponent`
- [ ] Note the file path (e.g., `src/app/layout/sidebar.component.ts`)
- [ ] Document current inputs and outputs

### Step 2: Update Imports (5 min)

**File**: Your parent component

```typescript
// Add this import
import { PaginatedNotesListComponent } from './list/paginated-notes-list.component';

// Add to @Component imports array
imports: [
  // ... existing imports
  PaginatedNotesListComponent
]
```

- [ ] Import added
- [ ] No import errors

### Step 3: Update Template (5 min)

**File**: Your parent component template

**Before**:
```html
<app-notes-list
  [notes]="notes()"
  [folderFilter]="selectedFolder()"
  [query]="searchQuery()"
  [tagFilter]="selectedTag()"
  [quickLinkFilter]="quickLinkFilter()"
  (openNote)="onNoteSelected($event)"
  (queryChange)="onSearchChange($event)"
  (clearQuickLinkFilter)="onClearQuickLink()">
</app-notes-list>
```

**After**:
```html
<app-paginated-notes-list
  [folderFilter]="selectedFolder()"
  [query]="searchQuery()"
  [tagFilter]="selectedTag()"
  [quickLinkFilter]="quickLinkFilter()"
  (openNote)="onNoteSelected($event)"
  (queryChange)="onSearchChange($event)"
  (clearQuickLinkFilter)="onClearQuickLink()">
</app-paginated-notes-list>
```

**Note**: Remove `[notes]` input - pagination handles data loading automatically

- [ ] Template updated
- [ ] No template errors

### Step 4: Update Event Handlers (5 min)

**File**: Your parent component TypeScript

Ensure these methods exist:

```typescript
onNoteSelected(noteId: string) {
  // Navigate to note or update state
  this.router.navigate(['/note', noteId]);
}

onSearchChange(term: string) {
  // Update your search state if needed
  this.searchQuery.set(term);
}

onClearQuickLink() {
  // Clear quick link filter
  this.quickLinkFilter.set(null);
}
```

- [ ] `onNoteSelected` method exists
- [ ] `onSearchChange` method exists
- [ ] `onClearQuickLink` method exists

### Step 5: Remove Old Data Loading (5 min)

**File**: Your parent component

Remove or comment out:
```typescript
// OLD - No longer needed
private loadAllNotes() {
  this.http.get('/api/vault/metadata').subscribe(notes => {
    this.notes.set(notes);
  });
}
```

The pagination service handles all data loading automatically.

- [ ] Old data loading code removed/commented
- [ ] No references to old metadata endpoint

### Step 6: Handle File Change Events (5 min)

**File**: Your vault event service (if you have one)

Add cache invalidation:
```typescript
private handleFileChange(event: VaultEvent) {
  // Inject PaginationService
  private paginationService = inject(PaginationService);

  switch (event.type) {
    case 'add':
    case 'change':
    case 'unlink':
      // Invalidate pagination cache
      this.paginationService.invalidateCache();
      // Reload first page
      this.paginationService.loadInitial();
      break;
  }
}
```

- [ ] PaginationService injected
- [ ] Cache invalidation added
- [ ] File change handler updated

### Step 7: Compile and Test (10 min)

```bash
# Terminal 1: Start dev server
npm run dev

# Terminal 2: Run tests
npm run test:pagination
```

- [ ] No compilation errors
- [ ] Dev server starts successfully
- [ ] `npm run test:pagination` passes all tests

### Step 8: Manual Testing (10 min)

1. **Open the app** in browser
2. **Scroll through notes list**
   - [ ] List appears and is scrollable
   - [ ] Scrolling is smooth (60fps)
   - [ ] No jank or lag

3. **Check network requests**
   - [ ] Open DevTools → Network tab
   - [ ] Scroll to bottom of list
   - [ ] Should see requests to `/api/vault/metadata/paginated`
   - [ ] Each request loads ~100 items

4. **Test search**
   - [ ] Type in search box
   - [ ] Results should update
   - [ ] Scrolling should load more results

5. **Test filters**
   - [ ] Tag filter works
   - [ ] Quick link filter works
   - [ ] Folder filter works

6. **Test selection**
   - [ ] Click on a note
   - [ ] Note should be selected
   - [ ] Navigation should work

### Step 9: Performance Verification (10 min)

**DevTools Performance Tab**:
1. Open DevTools → Performance tab
2. Click Record
3. Scroll through list for 10 seconds
4. Stop recording
5. Check results:
   - [ ] FPS stays at 60
   - [ ] No red bars (dropped frames)
   - [ ] No long tasks

**DevTools Memory Tab**:
1. Open DevTools → Memory tab
2. Take heap snapshot
3. Scroll through 1000+ items
4. Take another heap snapshot
5. Check:
   - [ ] Memory < 50MB
   - [ ] No memory leaks
   - [ ] Heap size stable

### Step 10: Browser Compatibility (5 min)

Test in:
- [ ] Chrome/Chromium
- [ ] Firefox
- [ ] Safari
- [ ] Mobile browser (if applicable)

## Rollback Plan (if needed)

If you need to revert to the old component:

1. Revert template to use `app-notes-list`
2. Restore old data loading code
3. Remove `PaginatedNotesListComponent` import
4. Restart dev server

The old endpoint `/api/vault/metadata` still works for backward compatibility.

## Post-Integration

### Monitor Performance

- [ ] Check browser console for errors
- [ ] Monitor memory usage over time
- [ ] Track scroll performance
- [ ] Verify search works correctly

### Optimize if Needed

If performance is not as expected:

1. **Adjust page size** (default 100):
   ```typescript
   // In pagination.service.ts
   const params: any = {
     limit: 50,  // Try smaller value
   };
   ```

2. **Adjust item height** (default 60px):
   ```html
   <!-- In paginated-notes-list.component.ts -->
   <cdk-virtual-scroll-viewport itemSize="70">
   ```

3. **Adjust preload threshold** (default 20):
   ```typescript
   // In paginated-notes-list.component.ts
   if (index > items.length - 10 && this.canLoadMore()) {
     // Load sooner
   }
   ```

### Document Changes

- [ ] Update team documentation
- [ ] Add notes about new pagination behavior
- [ ] Document any configuration changes

## Success Criteria

All of the following should be true:

- [ ] App compiles without errors
- [ ] Pagination endpoint works (`npm run test:pagination`)
- [ ] Notes list displays and is scrollable
- [ ] Scrolling is smooth (60fps)
- [ ] Search works with pagination
- [ ] Filters work correctly
- [ ] Memory usage < 50MB for 10k+ files
- [ ] No console errors
- [ ] No memory leaks
- [ ] Works on all target browsers

## Estimated Time

- Pre-integration: 5 min
- Integration: 45 min
- Testing: 15 min
- **Total: ~1 hour**

## Support

If you encounter issues:

1. Check the troubleshooting section in `IMPLEMENTATION_PHASE2.md`
2. Run `npm run test:pagination` to verify endpoint
3. Check browser console for errors
4. Review DevTools Network and Performance tabs
5. Verify Meilisearch is running: `npm run meili:up`

## Files Modified

- `src/app/features/list/paginated-notes-list.component.ts` - New component
- `src/app/services/pagination.service.ts` - New service
- `src/app/constants/pagination.config.ts` - New config
- `server/index.mjs` - New endpoint
- `package.json` - New test script
- Your parent component - Updated imports and template

## Files Not Modified

- Old `NotesListComponent` - Still works for backward compatibility
- Old `/api/vault/metadata` endpoint - Still works
- Other components - No changes needed

---

**Ready to integrate?** Follow the steps above and you'll have Phase 2 running in about 1 hour! 🚀