ca-grow-ops-manager/.agent/plans/3d_viewer_refactor.md

3D Facility Viewer Refactor Plan: "Project Panopticon"

1. Executive Summary

Objective: Transform the 3D Facility Viewer from a basic visualization tool into a comprehensive, "dead simple" interface for managing complex facility operations. Core Philosophy: "Functional Realism". The interface should look premium and architectural, but every visual element must serve a data-driven purpose. Key Goals:

1. Human Readability: Instant understanding of facility layout, plant locations, and environmental status.
2. Temporal Visualization: Ability to visualize data over time (e.g., "Show me the spread of this batch over the last 30 days").
3. Rapid Location: Locate any METRC-compliant plant or batch instantly with clear visual guidance.

2. Visual & UX Overhaul

A. "Clean Industrial" Aesthetics

• Move away from: Wireframes, glowing neon lines, dark "hacker" themes.
• Move toward: Clean concrete textures, matte metal finishes, soft global illumination, and distinct color coding for biological vs. structural elements.
• Lighting: Use an HDRI environment (preset="city" or similar) for realistic reflections, plus soft ambient occlusion (<ContactShadows />) to ground objects.

B. "Human Readable" Indicators

• Smart Labels: Instead of static 3D text floating in space, use Html overlays that scale and fade based on camera distance (LOD).
  • Close Zoom: Show individual Plant Tags and Health Stats.
  • Medium Zoom: Show Rack/Shelf IDs and Aggregate Health.
  • Far Zoom: Show Room Names and Environmental Averages.
• Beacons: When searching for a plant, do not just snap the camera. Place a vertical "light beacon" or animated indicator over the target so the user sees where it is in context before zooming in.

C. Controls & Navigation

• Hybrid Controls:
  • WASD + Right Click Drag: For "gamer" style free-flight.
  • Click-to-Move: Click any room floor to smoothly fly the camera there.
  • Double-Click: Focus specifically on a rack or plant.
• Tour Mode: A "Next Issue" button to cycle the camera through all plants with "Critical" health or environmental alerts.

3. New Feature: "The Time Slider"

• Concept: A timeline interface at the bottom of the screen.
• Function: Dragging the slider behaves like a video scrubber.
  • Past: Visualize historical plant positions (from PlantLocationHistory). See where a batch started and how it moved.
  • Present: Live state.
  • Future (Projected): Visualize yield forecasts or space planning (from Yield model).

4. Technical Architecture Refactor

A. Component Decomposition

The current Facility3DViewerPage.tsx is becoming monolithic. We will break it down:

• FacilityScene.tsx: Main canvas and lighting setup.
• FacilityWorld.tsx: Handles the "physics" and separate rooms.
• RoomObject.tsx: Encapsulates a single room's logic (floor, walls, labels).
• SmartRack.tsx: Manages a single rack/section, including its tiers and labels.
• PlantSystem.tsx: Optimized InstancedMesh system for rendering thousands of plants efficiently.

B. Data & State Management

• Zustand Store: Move 3D state (selected plant, camera target, visualization mode, timeline position) out of React useState and into a global store for better performance and access outside the canvas.
• React Query: Use for fetching standard API data.
• Optimized History Fetching: New API endpoint needed: GET /api/facilities/:id/history-snapshot?date=ISO_DATE to fetch the state of the facility at a specific point in time.

5. Implementation Phases

Phase 1: The "Visual Foundation" (Current Priority)

• Split code into smaller components.
• Implement "Clean Industrial" materials and lighting. (Using Environment preset="city", ContactShadows)
• Fix the camera controller to be "smooth yet precise". (CameraControls with WASD + mouse)
• Add "LOD" (Level of Detail) labels that fade in/out. (Future enhancement)

Phase 2: "Search & Locate" (Locating Plants) ✅ COMPLETE

• Build the "Search Sidebar" with fuzzy search for Tags/Batches. (PlantSearch.tsx)
• Implement the "Beacon" visual indicator system. (Beacon.tsx - animated light beam)
• Add "Highlight Mode": Dim the entire facility except the search results. (dimMode + highlightedTags)

Phase 3: "The Time Machine"

• Implement the UI Slider component.
• Create backend endpoint for historical snapshots.
• Wire up the slider to update plant positions dynamically.

6. Review Request

Does this plan align with your vision for "dead simple" and "human readable"? specifically:

1. Is the Time Slider a desired feature for "complex data over time"?
2. Do you agree with the "Clean Industrial" aesthetic direction?