Refactor foundation: split monoliths into sections, shared hooks/utilities, and docs alignment

CHANGELOG.md

@@ -16,10 +16,37 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ### Added
 
+- Foundation refactor: extracted core utilities to `src/lib/` for reuse across features:
+  - `uploadUtils.ts` — file upload with exponential backoff retry logic (transient error detection, original error preservation).
+  - `zoomPanUtils.ts` — viewport math utilities (`clampScale`, `clampPanPosition`) for consistent zoom/pan behavior.
+  - `markerUtils.ts` — marker detection and placement helpers.
+- Shared React hooks extracted to `src/hooks/` for reuse:
+  - `useZoomPan` — manages zoom/pan state and mouse/wheel event handlers for map-based interfaces.
+  - `useScheduleGeneration` — generates shift schedules from event duration and team coverage.
+  - `useTeamForm` — team/supervisor form submission and validation.
+- Shared UI primitives added to `src/components/ui/`:
+  - `map-zoom-controls.tsx` — zoom in/out/reset button cluster with accessibility labels (reused across event create and venue management).
+  - `map-pan-surface.tsx` — reusable pan/wheel interaction surface for canvas-based viewers.
+- Event creation flow decomposed into focused section components under `src/components/event-create/`:
+  - `MetadataSection.tsx` — event name, date, and venue selection.
+  - `TeamStaffingSection.tsx` — team roster assignment.
+  - `SupervisorStaffingSection.tsx` — supervisor roster assignment.
+  - `PostingScheduleSection.tsx` — shift schedule generation and management.
+  - `PostsEquipmentSection.tsx` — posts and equipment selection with multi-select state.
+- Venue management flow decomposed into focused section components under `src/components/venue-management/`:
+  - `EquipmentManagementSection.tsx` — add/edit/delete equipment with stable React keys.
+  - `LayerControlBar.tsx` — layer navigation (previous/next/add/delete) with accessibility labels.
+  - `MarkerModeToggleButton.tsx` — toggle marker placement mode.
+  - `PendingMarkerDialog.tsx` — marker naming dialog.
+  - `MarkerPlacementInstruction.tsx` — on-screen guidance during marker placement.
 - Lite event drafts now persist a `postingScheduleEnabled` flag to keep posting schedule behavior consistent between setup and dispatch.
 
 ### Changed
 
+- Event creation page (`src/app/(main)/events/[eventId]/create/page.tsx`) now uses decomposed section components instead of a monolithic page layout, improving maintainability and testability.
+- Venue management page (`src/app/(main)/venues/management/page.client.tsx`) now uses decomposed section components and shared map controls instead of page-local implementations.
+- Dispatch call tracking page now threads styling through `rowClassName` prop to restore per-status visual differentiation.
+- Pan math in `zoomPanUtils.clampPanPosition` corrected to properly clamp against scaled image overflow (fixes off-by-factor error at different zoom levels).
 - Lite setup Locations/Equipment add row now uses an attached input + action button style with aligned corner radii and consistent spacing.
 - Teams and Supervisors panel actions in Lite setup now use explicit `Add Team` and `Add Supervisor` buttons.
 - Lite dispatch navbar now hides `Posting Schedule` when posting schedule is disabled in event setup.
@@ -29,7 +56,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ### Fixed
 
+- Upload retry logic now only retries on transient Firebase Storage errors (`storage/retry-limit-exceeded`, `storage/unknown`) to avoid masking real failures, and preserves original error for diagnostics.
 - Removed initial navbar mount flicker/layout shift on page reload by rendering the main app navbar in the initial render path instead of client-only lazy loading.
+- Equipment list now uses stable React keys (`item.id`) instead of array indices to prevent component state loss on edit/delete operations.
 
 ---
 

docs/ARCHITECTURE.md

@@ -17,8 +17,10 @@ Repository layout (important folders)
 - `src/components/` — UI components grouped by role:
   - `src/components/modals/` — modal components (modal files follow `*modal.tsx` naming)
   - `src/components/dispatch/` — dispatch-specific UI (cards, tracking widgets)
+  - `src/components/event-create/` — event creation sections split by responsibility (metadata, staffing, schedule, posts/equipment)
+  - `src/components/venue-management/` — venue management sections split by responsibility (layers, marker placement, uploads, equipment)
   - `src/components/layout/` — layout-level components (navbar, etc.)
-  - `src/components/ui/` — small reusable primitives (Button, Input, Tooltip, Sidebar)
+  - `src/components/ui/` — small reusable primitives and shared controls (Button, Input, Tooltip, Sidebar, map pan/zoom overlays)
 
 - `src/hooks/` — shared React hooks (auth, mobile helpers, data collection)
 - `src/lib/` — utilities (e.g., `utils.ts` and `cn()` helpers)
@@ -30,6 +32,7 @@ Key architectural decisions
 - App Router / Server Components: Pages under `src/app` are server components by default. Client interactivity (hooks, event handlers) requires the `'use client'` directive at the top of the file.
 - Firebase-first: The app uses Firebase for auth, realtime persistence, storage and hosting. `src/app/firebase.ts` centralizes initialization and should not be edited lightly.
 - Component-first UI: UI is organized around modular components and small primitives in `src/components/ui` so features compose cleanly.
+- Feature decomposition: page-level screens should be split into focused section components when a page starts to accumulate unrelated responsibilities.
 - Tailwind + HeroUI: Tailwind utility classes are used for styling; HeroUI provides higher-level components.
 
 Data model and types
@@ -68,3 +71,4 @@ Notes
 
 - Keep changes small and scoped; add tests for backend rules when modifying data shapes.
 - When adding client components, remember to add `'use client'` and import only client-safe modules.
+- Prefer one-responsibility feature sections over large page-local JSX blocks, and reuse shared viewport controls and other primitives from `src/components/ui` before introducing page-specific copies.

docs/COMPONENTS.md

@@ -21,9 +21,19 @@ Directory highlights
 - `src/components/dispatch/` — feature-specific UI used on the dispatch dashboard:
   - `teamcard.tsx`, `calltrackingcard.tsx`, `clinictrackingcard.tsx` — cards and tracking widgets.
 
+- `src/components/event-create/` — event creation sections used by the event create page:
+  - metadata, staffing, posting schedule, and posts/equipment are split into focused components rather than a single page-local block.
+
+- `src/components/venue-management/` — venue management sections used by the venue editor:
+  - layer controls, marker placement UI, upload handling, and equipment management are separated into dedicated components.
+
 - `src/components/layout/` — layout-level components (global navigation, header):
   - `appnavbar.tsx` — top navigation used in `layout.tsx`.
 
+- `src/components/ui/` also contains shared interaction chrome used by multiple pages:
+  - `map-pan-surface.tsx` — reusable pan/wheel surface for map canvases.
+  - `map-zoom-controls.tsx` — shared zoom/reset button cluster for map viewers.
+
 - Root helpers
   - `src/components/devServiceWorkerCleanup.tsx` — helper for service worker cleanup in dev.
 
@@ -32,6 +42,7 @@ Styling and design tokens
 - TailwindCSS powers styling. Use the `cn()` helper in `src/lib/utils.ts` for conditional class merging.
 - Use `tailwind-merge` (`tailwind-merge` is already a dependency) for combining utility classes safely.
 - Follow existing token and utility patterns when adding new classes to preserve visual consistency.
+- Keep feature sections small and typed explicitly; prefer local prop types for section components and avoid passing untyped page state through multiple layers.
 
 Third-party UI libraries
 
@@ -71,6 +82,7 @@ Tips
 
 - Keep components small and focused — prefer composition over large monolithic components.
 - Reuse primitives from `src/components/ui` rather than adding duplicated styles.
+- Reuse shared map controls and viewport wrappers from `src/components/ui` before creating page-specific zoom/pan implementations.
 - When creating new modals, follow the `*modal.tsx` naming convention so they are easy to locate.
 
 Where to find examples