feat(gallery): add map view with geo-tagged photo markers

[joaquimscosta]

Summary

• Backend: Add hasGeo query parameter to GET /api/v1/gallery endpoint for server-side geo-filtering
• Shared primitives: Extract reusable BaseMap component and useMapClustering hook from BravaMap, refactor MapCanvas to use them
• Gallery map: Build GalleryMapCanvas with clustered photo markers, popup cards, empty states, and auto-fit bounds
• Integration: Add map view toggle (grid/timeline/map), lazy-loaded via next/dynamic, URL sync with ?view=map, "Show on Map" button in lightbox
• Tests: 7 backend integration tests + 14 frontend component tests + 10 geo-adapter unit tests
• Accessibility: ARIA roles, keyboard navigation, 44px touch targets, semantic design tokens

Spec

plan/arkhe/specs/026-gallery-map-view/ — 12 tasks across 4 waves, all completed. Verification report: 95% overall confidence (PASS).

Key files

Area	Files
Backend	GalleryController.kt, GalleryService.kt, GalleryControllerGeoFilterTest.kt
Shared map	features/map/shared/base-map.tsx, use-map-clustering.ts, types.ts
Gallery map	components/gallery/gallery-map-canvas.tsx, gallery-map-marker.tsx, gallery-map-popup.tsx
Integration	gallery-content.tsx, image-lightbox.tsx, gallery-mappers.ts
Tests	gallery-map-canvas.test.tsx, gallery-mappers.test.ts

Test plan

• Backend: ./gradlew test — 7 geo-filter integration tests pass
• Frontend: pnpm run test:unit — 270/270 tests pass (14 new component tests)
• TypeScript: npx tsc --noEmit — clean
• Manual: Navigate to /gallery?view=map, verify markers, clustering, popup, empty states
• Manual: Open lightbox → "Show on Map" → verify fly-to animation
• Manual: Test on mobile viewport (responsive layout, touch targets)

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[github-actions]

🚀 PR Validation Results

📁 Components Changed:

• ℹ️ No core component changes detected

🔍 Validation Results:

⏭️ Backend CI: Skipped (no relevant changes)
✅ Frontend CI: success
⏭️ Infrastructure CI: Skipped (no relevant changes)
✅ Global Security Scan: success

🎉 Status: READY FOR REVIEW

All validation checks have passed! This PR is ready for code review.

---

Updated: 2026-02-27T00:18:02.444Z | PR: #83

[joaquimscosta]

Code review

Found 5 issues:

1. Backend size cap bypassed when hasGeo=true triggers the in-memory filter path. The pageable is capped at minOf(size, 100) on line 542, but the in-memory branch at lines 567-568 slices with the raw, uncapped size parameter (val start = page * size). A caller can send GET /api/v1/gallery?hasGeo=true&size=10000 and receive all geo-tagged records in a single response, bypassing the 100-item max. (bug: uncapped size in in-memory filter path)

nosilha/apps/api/src/main/kotlin/com/nosilha/core/gallery/domain/GalleryService.kt

Lines 541 to 570 in 5df75af

	): Page<GalleryMedia> {
	val pageable = PageRequest.of(page, minOf(size, 100))
	val needsInMemoryFilter = category != null || decade != null || hasGeo == true
	return if (needsInMemoryFilter) {
	var filtered: List<GalleryMedia> = repository
	.findByStatusAndShowInGalleryTrue(GalleryMediaStatus.ACTIVE)
	if (category != null) {
	filtered = filtered.filter { it.category == category }
	}
	if (decade != null) {
	val yearRange = parseDecadeRange(decade)
	if (yearRange != null) {
	filtered = filtered.filter { media -> resolveYear(media) in yearRange }
	}
	}
	if (hasGeo == true) {
	filtered = filtered.filter { media ->
	media is UserUploadedMedia && media.latitude != null && media.longitude != null
	}
	}
	filtered = filtered.sortedBy { it.displayOrder }
	val start = page * size
	val end = minOf(start + size, filtered.size)
	val pageContent = if (start < filtered.size) filtered.subList(start, end) else emptyList()

2. flyToCoords state is never cleared after "Show on Map" fires, causing stale fly-to on map remount. flyToCoords is set when clicking "Show on Map" but never reset to null. The deduplication guard lastFlyToRef is local to GalleryMapCanvas and resets to null on every mount. When a user switches from map to grid and back, the component remounts, lastFlyToRef is null again, and the stale flyToCoords re-triggers a fly animation to old coordinates. (bug: stale state across unmount/remount cycle)

nosilha/apps/web/src/app/(main)/gallery/gallery-content.tsx

Lines 120 to 126 in 5df75af

	const [mapLightboxIndex, setMapLightboxIndex] = useState<number | null>(null);
	const [flyToCoords, setFlyToCoords] = useState<{
	lat: number;
	lng: number;
	photoId: string;
	} | null>(null);

nosilha/apps/web/src/components/gallery/gallery-map-canvas.tsx

Lines 130 to 148 in 5df75af

	// Handle flyTo from external source (e.g., "Show on Map" button)
	useEffect(() => {
	if (
	!flyToCoords ||
	flyToCoords.photoId === lastFlyToRef.current ||
	!mapRef.current
	) {
	return;
	}
	lastFlyToRef.current = flyToCoords.photoId;
	const photo = photoById.get(flyToCoords.photoId);
	// eslint-disable-next-line react-hooks/set-state-in-effect -- popup must sync with flyTo animation trigger
	if (photo) setPopupPhoto(photo);
	mapRef.current.flyTo({
	center: [flyToCoords.lng, flyToCoords.lat],
	zoom: MAP_CONFIG.LOCATION_ZOOM,
	duration: MAP_CONFIG.ANIMATION_DURATION,
	});
	}, [flyToCoords, photoById]);

3. getGalleryMedia uses 30-minute ISR cache even when hasGeo=true serves map data. api-contracts.ts defines MAP_DATA: { cache: "no-store" } with the comment "Map data - needs to be dynamic", but the gallery endpoint in backend-api.ts always uses next: { revalidate: 1800 }. Newly uploaded geo-tagged photos would be invisible on the map for up to 30 minutes. (bug: cache policy contradicts documented MAP_DATA contract in api-contracts.ts)

nosilha/apps/web/src/lib/backend-api.ts

Lines 2385 to 2389 in 5df75af

	// Use ISR with 30 minute cache for gallery content
	const response = await fetch(endpoint, {
	next: { revalidate: 1800 }, // 30 minutes
	});

nosilha/apps/web/src/lib/api-contracts.ts

Lines 1067 to 1069 in 5df75af

	// Map data - needs to be dynamic
	MAP_DATA: { cache: "no-store" as const },

4. GalleryMapPopup falls back to photo.url for <Image src>, which for VIDEO items is a YouTube embed/watch URL. .claude/rules/frontend/gallery-media.md says "Never pass an external VIDEO/AUDIO url or embedUrl to next/image." In practice the backend hasGeo filter only returns UserUploadedMedia, but the component accepts generic MediaItem with no type guard — a future caller passing mixed media types would crash the page. (.claude/rules/frontend/gallery-media.md says "Never pass an external VIDEO/AUDIO url or embedUrl to next/image")

nosilha/apps/web/src/components/gallery/gallery-map-popup.tsx

Lines 21 to 23 in 5df75af

	}: GalleryMapPopupProps) {
	const imageUrl = photo.thumbnailUrl ?? photo.url;

5. flyTo silently drops on first map load when "Show on Map" triggers lazy-loaded GalleryMapCanvas. When the user clicks "Show on Map", the parent simultaneously sets flyToCoords and switches to map view. Because GalleryMapCanvas is dynamic() loaded, calling mapRef.current.flyTo() before the Mapbox style has loaded fails silently, and lastFlyToRef is updated (line 139), preventing retry. handleMapLoad (line 90) does not check for a pending flyTo. (bug: race condition between lazy component mount and flyTo side-effect)

nosilha/apps/web/src/components/gallery/gallery-map-canvas.tsx

Lines 129 to 148 in 5df75af

	// Handle flyTo from external source (e.g., "Show on Map" button)
	useEffect(() => {
	if (
	!flyToCoords ||
	flyToCoords.photoId === lastFlyToRef.current ||
	!mapRef.current
	) {
	return;
	}
	lastFlyToRef.current = flyToCoords.photoId;
	const photo = photoById.get(flyToCoords.photoId);
	// eslint-disable-next-line react-hooks/set-state-in-effect -- popup must sync with flyTo animation trigger
	if (photo) setPopupPhoto(photo);
	mapRef.current.flyTo({
	center: [flyToCoords.lng, flyToCoords.lat],
	zoom: MAP_CONFIG.LOCATION_ZOOM,
	duration: MAP_CONFIG.ANIMATION_DURATION,
	});
	}, [flyToCoords, photoById]);

nosilha/apps/web/src/components/gallery/gallery-map-canvas.tsx

Lines 89 to 93 in 5df75af

	const handleMapLoad = useCallback(() => {
	setMapReady(true);
	const b = mapRef.current?.getMap().getBounds();
	if (b) {

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[joaquimscosta]

All 5 issues addressed in commit b253cb5:

1. Backend size cap — queryActiveMedia now uses cappedSize (minOf(size, 100)) for the in-memory slicing path, matching searchActiveMedia which was already correct.

2. Stale flyToCoords — handleViewChange now clears flyToCoords to null when switching away from map view, preventing stale fly-to animations on remount.

3. ISR cache for map data — getGalleryMedia now uses CacheConfig.MAP_DATA (no-store) when hasGeo=true, and CacheConfig.GALLERY (30-min ISR) otherwise.

4. GalleryMapPopup VIDEO URL — Changed photo.thumbnailUrl ?? photo.url to photo.thumbnailUrl ?? null, following the gallery-media golden rule. The placeholder image handles the null case.

5. flyTo race condition — Added mapReady as a dependency and guard condition in the flyTo useEffect. The effect now waits for the Mapbox style to load before attempting flyTo, and re-runs when mapReady transitions to true.

All 270 frontend unit tests and 7 backend geo-filter integration tests pass. TypeScript compilation clean.