perf: optimize gallery rendering for large libraries

[bhavyaxtech]

Summary

Implemented performance optimizations for gallery rendering to improve responsiveness when working with large local photo libraries. The changes reduce rendering overhead and improve scrolling performance while preserving full-resolution image viewing and download functionality.

Fixes #172

Type of change

• Bug fix
• Feature
• Documentation update
• Refactor
• CI / tooling

What changed

• Added gallery rendering optimizations for large media collections.
• Implemented virtualization/lazy rendering to reduce DOM workload.
• Improved performance across Gallery, Search, People, and Clusters views.
• Added reusable virtualized grid component.
• Preserved full-resolution image previews and downloads.
• Reduced unnecessary re-renders for smoother navigation.

Screenshots / recordings (for UI changes)

Attach before/after screenshots or performance comparison recordings.

How to test

1. Run the application locally.
2. Import or use a large image library.
3. Open Gallery, Search, People, and Clusters views.
4. Verify smooth scrolling and reduced rendering lag.
5. Open image previews and confirm original-resolution images load correctly.

Checklist

• I linked the related issue
• I ran required checks from CONTRIBUTING.md
• I updated docs/env notes if needed
• My PR is scoped to a single issue
• I followed commit message conventions
• I am not committing secrets or local artifacts

GSSoC'26 checklist

• I requested issue assignment before starting
• I have meaningful commits (no spam commits)
• I am ready to explain my implementation in review comments

Summary by CodeRabbit

Release Notes

• Performance Improvements

  • Optimized rendering of large image galleries and grids across gallery, search, clusters, and people sections for faster load times and smoother scrolling.

• Documentation

  • Added performance benchmarking guidelines and implementation tracking for grid-based views to ensure optimal responsiveness.

[github-actions]

PR Context Summary

• Linked issue(s): roadmap: optimize gallery rendering for large local libraries #172
• Referenced but not closing: none
• PR author trusted by GitHub: no
• Dependabot PR: no
• PR assignee synced from linked issue: yes
• Macroscope review status: Already triggered once for this PR. Use the workflow dispatch to manually rerun.

Suggested issue links

• No strong issue match found yet.

Use Fixes #123 or Closes #123 in the PR body when one of the suggestions is the intended issue.
Manual rerun: Actions > PR Context Triage > Run workflow > set pr_number and force_review=true.

[macroscopeapp]

Approvability

Verdict: Needs human review

Unable to check for correctness in f2e0c7b. Introduces a new VirtualizedGrid component (~200 lines) that changes rendering behavior across 4 major page grids. While this is a standard virtualization pattern for performance, the scope of changes and new component logic affecting core user-facing views warrants human verification.

^{You can customize Macroscope's approvability policy. Learn more.}

[bhavyaxtech]

Hi @Abhash-Chakraborty,

I've submitted the PR for this issue. Could you please review it when you have time?

Thank you!

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 93e690ec-a266-4b26-884c-dfa973b69792

📥 Commits

Reviewing files that changed from the base of the PR and between 6b9f935 and f2e0c7b.

📒 Files selected for processing (6)

• docs/guides/image-loading.md
• frontend/src/app/clusters/page.tsx
• frontend/src/app/gallery/page.tsx
• frontend/src/app/people/page.tsx
• frontend/src/app/search/page.tsx
• frontend/src/components/virtualized-grid.tsx

---

📝 Walkthrough

Walkthrough

This PR implements a reusable VirtualizedGrid component and applies it across gallery, search, clusters, and people views to render only visible grid items. The component calculates a virtual window based on scroll position and viewport dimensions, rendering spacer elements to maintain scroll behavior. Documentation captures performance targets and a manual benchmarking procedure.

Changes

Grid Virtualization Implementation

Layer / File(s)	Summary
VirtualizedGrid component core frontend/src/components/virtualized-grid.tsx	Introduces generic React component that virtualizes grid rendering. Computes column count from CSS grid, establishes virtual row window from scroll position and viewport height with overscan, listens to scroll/resize/ResizeObserver lifecycle events, calculates visible item slice with top/bottom spacer elements, and renders only visible items via renderItem with stable keys from getKey.
Gallery, search, clusters, and people grid integrations frontend/src/app/gallery/page.tsx, frontend/src/app/search/page.tsx, frontend/src/app/clusters/page.tsx, frontend/src/app/people/page.tsx	Replaces non-virtualized .map() grid rendering with VirtualizedGrid configured with item lists, estimated row heights, grid gaps, keying functions, and renderItem callbacks. Gallery wraps thumbnail grid; search wraps results grid; clusters wraps main cluster grid and member preview grid; people wraps person list grid and modal images grid. Preserves existing card UI, selection handlers, modal triggers, and actions.
Performance targets and benchmarking docs/guides/image-loading.md	Documents performance targets for thumbnail-based grids: bounded mounting/overscan behavior, responsive scrolling without long tasks (>100 ms), and original-URL usage for preview/download. Adds implementation tracking table for thumbnail generation, API fields/endpoints, frontend grid usage, and virtualization tuning. Provides manual benchmark procedure with dataset seeding, performance recording, interaction steps, and verification criteria for correct thumbnail/original URL behavior and absence of long tasks.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

frontend, performance, type:refactor, level:advanced, quality:clean

Suggested reviewers

• Abhash-Chakraborty

Poem

🐰 A rabbit hops through vast photo grids,
No longer rendering all the kids—
Just those in view scroll swift and light,
With spacers keeping scrollbar right!
Thumbnails dance on velvet streams. 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: performance optimization for gallery rendering in large libraries, matching the core objectives of the PR.
Description check	✅ Passed	The description covers the key aspects: summary, type of change, what changed, testing steps, and most checklist items completed. However, it lacks before/after screenshots/recordings and details on docs/env updates.
Linked Issues check	✅ Passed	The PR addresses the main acceptance criteria: implements grid virtualization/pagination (VirtualizedGrid component) [172], preserves full-resolution previews/downloads, adds performance optimization documentation [172], and reduces DOM rendering overhead as required.
Out of Scope Changes check	✅ Passed	All changes directly support the performance optimization goals: VirtualizedGrid component, gallery/search/people/clusters virtualization, documentation additions, and no removal of existing features or image quality reduction.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

@macroscope-app review

Please review this PR against its linked issue, local-first privacy rules, and the current Find repo instructions.
Linked issue(s): #172.
Trigger source: label-gated review (ready-to-merge).

[Abhash-Chakraborty]

Looks good. I checked the virtualization integration across gallery, search, clusters, and people; it keeps thumbnail grid rendering bounded while preserving existing preview/download behavior. No code changes were needed.\n\nChecked locally:\n- pnpm exec biome check src/components/virtualized-grid.tsx src/app/gallery/page.tsx src/app/search/page.tsx src/app/clusters/page.tsx src/app/people/page.tsx\n- pnpm build