JLeshnick · JLeshnick · Jul 24, 2026 · Jul 24, 2026 · Jul 24, 2026 · Jul 24, 2026
diff --git a/LabyrinthPro.png b/LabyrinthPro.png
diff --git a/MazeMaster.png b/MazeMaster.png
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -0,0 +1,56 @@
+# Architecture: Labyrinth Solver V2
+
+This document details the system design, directory structures, worker pipelines, and state management flow of the Labyrinth Solver.
+
+## Core Component Diagram
+```mermaid
+graph TD
+    App[src/App.tsx] --> AppHeader[src/components/AppHeader.tsx]
+    App --> MainLayout[Main View Grid]
+
+    MainLayout --> LeftSidebar[Setup Panel Widget]
+    MainLayout --> CentralHero[Board.tsx & Tile.tsx]
+    MainLayout --> RightSidebar[Solver Panel Widget]
+
+    App --> Worker[src/solver.worker.js]
+    Worker --> Pathfinder[src/solver.js - BFS Engine]
+
+    App --> HistoryHook[useLabyrinthHistory.ts]
+    App --> StorageHook[useLabyrinthStorage.ts]
+    App --> AudioSystem[utils/audio.ts - Web Audio API]
+```
+
+## Folder Structure (Modernized V2)
+
+To reduce technical debt and maximize maintainability, files are grouped logically by concern:
+
+```
+src/
+├── assets/             # Raw svg / graphic resources
+├── components/         # React markup and presentation
+│   ├── ui/             # Radix & Shadcn UI primitive blocks
+│   ├── board/          # Board rendering & Tile renderers
+│   ├── panels/         # Left and Right panels (Setup / Solver widgets)
+│   └── modals/         # Dialog views (MoveHistory, Settings, PhotoScan)
+├── hooks/              # State & behavior lifecycle code
+├── lib/                # Adapters, utilities, and helper code
+├── utils/              # Base services (e.g. Synthesized Audio system)
+├── types.ts            # Common type interfaces
+├── solver.js           # Core BFS search calculations
+├── solver.worker.js    # Off-thread Web Worker wrapper
+└── main.tsx            # App render mounting
+```
+
+## System Modules
+
+### 1. Web Worker Pipeline
+Complex pathfinder searches run inside `solver.worker.js` (Web Worker).
+- **Communication Protocol**: JSON messages containing the serialized 7x7 board state, players' current target coordinates, active pawn color, and search depth parameters (`maxTurns`).
+- **Response**: The solver returns a sorted list of best moves, each featuring path coordinates (`pawnPath`), arrow directions, and explanations.
+
+### 2. State & History Synchronization
+- **`useLabyrinthHistory`**: Keeps deep cloned snapshots of `AppGameState` to manage custom undo/redo actions.
+- **`useLabyrinthStorage`**: Provides quick read/write tools to standard `localStorage` to save game slots and sync setup options.
+
+### 3. Native Web Audio Synth
+Audio feedback is synthesized dynamically using the Web Audio API in `src/utils/audio.ts` (minimizing app footprint by not packing static mp3/wav files).
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -0,0 +1,22 @@
+# Changelog: Labyrinth Solver Redesign
+
+All notable changes to the Labyrinth Solver V2 will be documented in this file.
+
+## [2.0.0] - Modernized Design & Refactored Architecture
+
+### Added
+- Created V2 Master Plan, Design System guidelines, and updated Architecture specs.
+- Designed premium application frame shell (desktop sidebar layout, mobile drawer layouts).
+- Integrated framer-motion animations for sidebar transitions and tile shifts.
+- Implemented high-contrast Light/Dark mode themes.
+- Added **3D Isometric Perspective View**: Live 3D board tilting with card/badge billboarding to stand upright towards the camera.
+- Added **3D Board Tray Platform**: Grid board tilts inside a real 3D play tray styled in Neo-Brutalism thick borders and shadows, scaling responsively utilizing `w-full h-full aspect-square` grids.
+- Added **Rounded Pathway Tubes**: Replaced blocky pathways with smooth white plastic tubes with highlight bevels and drop-shadow styling.
+- Added **Glossy Peg Pawns & Gold Coins**: Pawns render as glossy spherical 3D pegs, and treasures render as circular gold medallions.
+- Added **Soft-Neumorphic Shadows**: Standard 2D view renders tiles and buttons with double-shadow highlights (`shadow-neumorphic`) for a soft, pillow-like extruded look.
+- Added **Neo-Brutalist Styling**: Cards and buttons utilize thick black borders and flat offset solid shadows (`neo-brutalism-card` and `neo-brutalism-button`).
+
+### Changed
+- Unified all tiles to render as a consistent warm stone gray clay block with thick black outlines (pawn starts retain colors for game logic).
+- Removed temporary Dashboard widgets panel.
+- Refactored color system to map shadcn/ui semantic variables (background, card, border) to theme-aware values, eliminating hardcoded dark panels in light mode.
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
@@ -0,0 +1,38 @@
+# Decisions Log: Labyrinth Solver V2
+
+This document records the Architectural Decision Records (ADRs) for Project Phoenix.
+
+---
+
+## ADR 1: Unified Component Organization
+
+### Context
+The original project placed all UI components (board, tiles, settings dialog, setup panel, side sheets) inside a flat `src/components/` directory. As the application grows in features, this clutter makes it harder to identify visual modules and reuse styles.
+
+### Decision
+Segregate components into functional subfolders under `src/components/`:
+- `board/`: Contains the board grid space (`Board.tsx`, `Tile.tsx`, and relevant helper cards).
+- `panels/`: Houses sidebar panels (`SetupPanel.tsx`, `SolverPanel.tsx`, `StatsPanel.tsx`).
+- `modals/`: Houses full screen and overlay dialogs (`SettingsDialog.tsx`, `BoardScanModal.tsx`, `MoveHistoryDialog.tsx`, `WelcomeGuide.tsx`).
+- `ui/`: Standard reusable design primitives.
+
+### Consequences
+- Imports will be cleaner and localized.
+- Easier to navigate component dependencies.
+- Avoids namespace clutter.
+
+---
+
+## ADR 2: Responsive Workspace Grid
+
+### Context
+The board is the hero element of the game (~70% visual focus on desktops). We need a layout that handles both ultra-wide screens and compact mobile devices (portrait screens, touch inputs).
+
+### Decision
+We will construct a CSS Grid wrapper in `App.tsx` that splits the layout:
+- **Desktop (md and above)**: A 3-column grid of `[Setup Sidebar (Left)] [Board (Center)] [Solver & Analysis (Right)]`.
+- **Mobile / Portrait**: A vertical stacks system where the board is centered at the top, and bottom-sheets / sliding drawer panels display Setup/Solver actions.
+
+### Consequences
+- Optimizes board layout constraints dynamically.
+- Eliminates overlapping widgets or double scrollbars.
diff --git a/docs/DESIGN_SYSTEM.md b/docs/DESIGN_SYSTEM.md
@@ -0,0 +1,44 @@
+# Design System: Labyrinth V2 (Project Phoenix)
+
+This document defines the visual layout guidelines, typographic hierarchy, color systems, and animation guidelines for the redesigned browser game.
+
+## Visual Archetype: Sleek Desktop in the Browser
+The design system takes cues from high-performance desktop tools (Linear, Raycast, Apple Sonama), utilizing space, glassmorphism, subtle micro-animations, and minimal borders to create a calm, professional experience.
+
+---
+
+## 🎨 Color Palette
+
+### 🟢 Base Colors (Dark Theme First)
+- **Background**: `stone-950` (#0c0a09) — Neutral deep slate.
+- **Surface**: `stone-900` (#1c1917) — Raised panels and cards.
+- **Muted Surface**: `stone-900/50` — Secondary list elements.
+- **Borders**: `stone-800` (#292524) — Clean, thin hairline boundary.
+- **Foreground Text**: `stone-50` (#fafaf9) — High contrast text.
+- **Muted Text**: `stone-400` (#a8a29e) — Secondary description text.
+
+### 🟡 Brand & Accent Theme Tint
+- **Default Theme Color**: Amber Orange (`#f59e0b`).
+- Custom accent colors can be specified in settings (synchronized into CSS variables `--theme-color`, `--theme-color-rgb`, and `--theme-glow`).
+
+---
+
+## 📐 Spacing & Layout
+- **The 70% Board Rule**: The Labyrinth board occupies ~70% of the desktop viewport space. Side panels split the remaining 30%.
+- **Borders**: Always `1px` width using `--color-border` (`stone-800`). Avoid heavy dividers.
+- **Border Radius**: Use `0.75rem` (`rounded-xl`) for panel containers and cards; `0.5rem` (`rounded-lg`) for buttons and small badges.
+
+---
+
+## ✍️ Typography
+- **Primary Font**: Inter / system-ui (clean, readable interface elements).
+- **Display Font**: Outfit / system-ui (headers and titles).
+- **Line Heights**: Relaxed line spacing for text descriptions; tight heights for compact metrics cards.
+
+---
+
+## 🎭 Animations & Transitions
+- **Hover effects**: Translate up by `1px` with a subtle glow increase.
+- **Slide animations**: Smooth translations when inserting the spare tile.
+- **Pawn movement**: Fast, snappy cubic-bezier offsets (`cubic-bezier(0.16, 1, 0.3, 1)`) to avoid trailing delays.
+- **Spring parameters**: `stiffness: 300, damping: 30` for interactive overlays.
diff --git a/docs/MASTER_PLAN.md b/docs/MASTER_PLAN.md
@@ -0,0 +1,72 @@
+# Master Plan: Labyrinth Solver V2 Modernization
+
+This document tracks the execution phases for Project Phoenix—the complete modernization of the Labyrinth Solver.
+
+## Progress Overview
+
+- [x] **Phase 1: Project Audit & Assessment** (Done)
+- [x] **Phase 2: Architectural Design** (Done)
+- [x] **Phase 3: Design System Definition** (Done)
+- [x] **Phase 4: Shell & Frame Implementation** (Done)
+- [x] **Phase 5: Board Modernization** (Done)
+- [x] **Phase 6: Solver Widgets Integration** (Done)
+- [x] **Phase 7: Animation & UX Polish** (Done)
+- [x] **Phase 8: Release Review & Verification** (Done)
+
+---
+
+## Phase Details & Checklists
+
+### Phase 1: Project Audit & Assessment
+- [x] Examine existing React app and folder structure.
+- [x] Identify strengths and weaknesses of the current UI.
+- [x] Review typescript types, state hooks, and solver integrations.
+- [x] Document audit findings in `docs/ARCHITECTURE.md`.
+- [x] Record baseline layout, design system issues, and target layout metrics.
+
+### Phase 2: Architectural Design
+- [x] Design decoupled, modular component structure.
+- [x] Establish folder design in `docs/ARCHITECTURE.md`.
+- [x] Move board setup, solver state, and utility code into clean directories.
+- [x] Plan state synchronization model and background worker pipelines.
+- [x] Create ADRs in `docs/DECISIONS.md`.
+
+### Phase 3: Design System Definition
+- [x] Set up unified CSS variables and dark/light tokens in `docs/DESIGN_SYSTEM.md`.
+- [x] Define premium styling variables: typography (Outfit/Inter), spacing, border radius, and glassmorphism.
+- [x] Define animation guidelines with framer-motion and vanilla transitions.
+- [x] Check compatibility of Tailwind v4 configs with our design variables.
+
+### Phase 4: Shell & Frame Implementation
+- [x] Create core layout skeleton (Sidebar + Main Board View + Right Panels).
+- [x] Implement responsive behavior (Side sheets for mobile, expanded grids for desktop).
+- [x] Rebuild Navigation header with premium styling (Glassmorphism, custom toggles).
+- [x] Implement user settings dialog, local storage configurations, and audio mute settings.
+- [x] Build theme toggle (Light / Dark) supporting clean color palettes.
+
+### Phase 5: Board Modernization
+- [x] Re-engineer `Board` and `Tile` components.
+- [x] Add smooth animations for sliding rows/columns (Framer Motion).
+- [x] Refine drag-and-drop tiles (dnd-kit integration) with smooth drag indicators.
+- [x] Implement clean hover previews for paths, reachable nodes, and active targets.
+- [x] Clean up board rotation animation support.
+
+### Phase 6: Solver Widgets Integration
+- [x] Create current objective card showing target card details and stats.
+- [x] Build "Best Move" suggestion widget with a visual route preview.
+- [x] Build "Alternative Moves" list and rankings with collapsible path details.
+- [x] Rebuild statistics panel and turn history widgets.
+- [x] Rebuild player hands manager and setup settings widgets.
+
+### Phase 7: Animation & UX Polish
+- [x] Add micro-animations to all interactive buttons, cards, and list items.
+- [x] Implement keyboard shortcut overlays and smooth sheet animations.
+- [x] Verify accessibility, standard ARIA labels, and keyboard navigation.
+- [x] Test mobile response, scroll indicators, and swipe behaviors.
+
+### Phase 8: Release Review & Verification
+- [x] Perform a full codebase review for clean, strict TypeScript.
+- [x] Clean up redundant code, styles, and comments.
+- [x] Run full test suites (`vitest`) and type checking.
+- [x] Verify deployment configuration for Vercel.
+- [x] Certify full project completion.
diff --git a/docs/TODO.md b/docs/TODO.md
@@ -0,0 +1,23 @@
+# Todo List: Labyrinth Solver V2
+
+This document tracks immediate task checklists for development and testing.
+
+## Active Tasks
+
+### Phase 1: Audit
+- [x] Review current components, folders, and tests.
+- [x] Create baseline design and documentation system.
+
+### Phase 2: Architecture
+- [x] Refactor component subdirectories (`components/board`, `components/panels`, `components/modals`).
+- [x] Re-route component imports inside `App.tsx` and test files.
+
+### Phase 3: Design System
+- [x] Establish styling properties in `index.css`.
+- [x] Confirm layout spacing variables are compatible with Tailwind v4.
+
+### Phase 4 & Beyond
+- [x] Implement V2 shell UI (layout, navigation header, control widgets).
+- [x] Implement V2 board design (animations, previews, indicators).
+- [x] Implement V2 solver panels & details layout.
+- [x] Verify test suite passes (`npm test`).
diff --git a/index.html b/index.html
@@ -8,6 +8,10 @@
     <meta name="apple-mobile-web-app-capable" content="yes" />
     <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
     <meta name="apple-mobile-web-app-title" content="Labyrinth Solver" />
+    <!-- Fonts -->
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Outfit:wght@500;600;700;800&display=swap" rel="stylesheet">
     <title>Labyrinth Game Solver</title>
   </head>
   <body>