feat(036): fix direct photo links in large paginated albums via ?page=N

[ildyria]

Fixes #4260
Fixes #4063

Summary by CodeRabbit

Release Notes

• New Features

  • Photo links in paginated albums now include page numbers (?page=N) for direct navigation to the correct photo.
  • Background loading of preceding pages for seamless browsing in paginated albums.

• Improvements

  • Enhanced scroll restoration when navigating back to album view.
  • Improved scroll centering and retry logic for better experience.

• Documentation

  • Added comprehensive feature specification and implementation plan for photo pagination support.

[coderabbitai]

📝 Walkthrough

Walkthrough

Implements Feature 036 – Photo Page URL with comprehensive documentation and code changes. Introduces page tracking via photoPageMap, extends album loading with optional startPage parameter, adds background prepending of preceding pages, implements URL query synchronization in routing, and refines scroll restoration logic to coordinate with photo panel visibility.

Changes

Cohort / File(s)	Summary
Documentation docs/specs/4-architecture/features/036-photo-page-url/plan.md, spec.md, tasks.md	Adds feature specification documents defining behavior for direct photo links with ?page=N, scope/out-of-scope items, five implementation increments, state changes, router behavior, component updates, and scenario tracking with analysis criteria.
Photo State Management resources/js/stores/PhotosState.ts	Introduces photoPageMap state and recordPhotoPages() method; adds prependPhotos() action with timeline/non-timeline merge support; extends setPhotos() and appendPhotos() with page parameter and page mapping; adds rebuildIterOffsets() to realign iterator offsets after timeline merges.
Album State Management resources/js/stores/AlbumState.ts	Adds photos_min_page state field; extends loadPhotos() with prepend parameter for background loading; modifies load() to accept optional startPage, immediately load target page, then background-load up to 5 preceding pages via prepend behavior without blocking.
Routing & Scroll resources/js/composables/photo/photoRoute.ts, album/scrollable.ts	Conditional ?page=N query generation in photo routes via photoPageMap lookup; extends retry loop from 10 to 50 iterations in scroll restoration; defers fallback scroll recovery until thumbnail element appears in DOM.
Component Updates resources/js/views/gallery-panels/Album.vue	Parses route ?page query via getStartPage(); passes startPage to albumStore.load(); coordinates scroll and photo-panel visibility by saving thumb scroll position when photo opens and restoring on close; extends route watcher to restore scroll when returning from photo panel.
Modal Scroll Behavior resources/js/stores/ModalsState.ts	Changes modal thumb scroll alignment from "nearest" to "center" when bringing thumb into view.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~40 minutes

Poem

🐰 A photo's page now holds its place,
With queries dancing through the space!
Prepend, append, and scroll they go,
Direct links find their destined flow—
The album hops with rabbited cheer! 🥕✨

🚥 Pre-merge checks | ❌ 1

❌ Failed checks (1 warning)

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

_{✏️ 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.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (4)

resources/js/composables/album/scrollable.ts (1)

19-41: Consider adding a fallback when thumbnail never appears.

When scroll_photo_id is set but the thumbnail element is never found after 50 retries (5 seconds), the function silently exits without restoring any scroll position. Previously, it would fall back to recoverScrollPage() which restores the saved scroll offset.

If the target photo was deleted, the page param was wrong, or the background prepend failed, users may be left at an unexpected scroll position with no visual feedback.

♻️ Suggested fallback after exhausting retries

 async function setScroll(_v: void, iter = 0) {
 	if (path.value === undefined) {
 		return;
 	}

 	// Abort. We tried 10 times (waited 5s).
 	if (iter == 50) {
+		// Fallback: restore saved scroll position if thumbnail never appeared
+		const e = document.getElementById("galleryView");
+		if (e && path.value) {
+			toggleableStore.recoverScrollPage(e, path.value);
+		}
+		toggleableStore.scroll_photo_id = undefined;
 		return;
 	}

docs/specs/4-architecture/features/036-photo-page-url/tasks.md (1)

71-74: Add required footer format per coding guidelines.

Documentation files should end with an hr line followed by the last updated timestamp in the specified format.

📝 Add footer

 - **Timeline prepend ordering:** The timeline `prependPhotos` uses `unshift` for new groups not matching an existing header. The correct visual order of prepended timeline groups depends on the album sort order; for typical date-descending albums (newest first, page 1), prepending an earlier page (older photos, higher page N) will insert the group at the front of the timeline array. This is correct for date-descending sort but may need revisiting for ascending sort.
+
+---
+
+*Last updated: 2026-04-12*

As per coding guidelines: "At the bottom of documentation files, add an hr line followed by 'Last updated: [date of the update]'"

docs/specs/4-architecture/features/036-photo-page-url/spec.md (1)

69-70: Add required footer format per coding guidelines.

📝 Add footer

 | S-036-06 | User navigates next/previous across a page boundary → URL `?page` updates to the adjacent page |
+
+---
+
+*Last updated: 2026-04-12*

As per coding guidelines: "At the bottom of documentation files, add an hr line followed by 'Last updated: [date of the update]'"

docs/specs/4-architecture/features/036-photo-page-url/plan.md (1)

113-114: Add required footer format per coding guidelines.

📝 Add footer

 - **Same-pattern application to Search, Tag, Timeline views:** Currently only album and flow-album routes include `?page`. The same `photoPageMap` approach can be extended to those views.
+
+---
+
+*Last updated: 2026-04-12*

As per coding guidelines: "At the bottom of documentation files, add an hr line followed by 'Last updated: [date of the update]'"

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 42279c88-d852-478f-a5c7-6abd33fe59ec

📥 Commits

Reviewing files that changed from the base of the PR and between c1cd68f and 17c1d39.

📒 Files selected for processing (9)

• docs/specs/4-architecture/features/036-photo-page-url/plan.md
• docs/specs/4-architecture/features/036-photo-page-url/spec.md
• docs/specs/4-architecture/features/036-photo-page-url/tasks.md
• resources/js/composables/album/scrollable.ts
• resources/js/composables/photo/photoRoute.ts
• resources/js/stores/AlbumState.ts
• resources/js/stores/ModalsState.ts
• resources/js/stores/PhotosState.ts
• resources/js/views/gallery-panels/Album.vue

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.20%. Comparing base (896f517) to head (17c1d39).
⚠️ Report is 5 commits behind head on master.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.