refactor: extract reusable library

- move reusable domain, data, state, ui code into src/lib
- update host screens to consume new library exports
- document architecture and configure path aliases
- bump astro integration dependencies for compatibility

Refs #30

README.md

@@ -14,44 +14,17 @@ A modern, responsive pool/billiards scoring application built with **Astro** and
 
 ## 🏗️ Architecture
 
-This project has been refactored following modern software development best practices:
+Everything reusable now lives under `src/lib`, allowing you to embed the core experience inside another React/Preact host without the Astro shell.
 
-### **Separation of Concerns**
-- **Services Layer**: Game data management and localStorage operations
-- **Custom Hooks**: Reusable state management logic
-- **Components**: UI components with single responsibilities
-- **Utils**: Pure utility functions for common operations
+- **`@lib/domain`** – Pure TypeScript domain model (types, constants, validation, helpers).
+- **`@lib/data`** – Persistence adapters and repositories (IndexedDB, migrations).
+- **`@lib/state`** – Composable hooks that orchestrate domain + data.
+- **`@lib/ui`** – Stateless UI primitives with co-located CSS modules.
+- **`@lib/features/*`** – Feature bundles composing UI + state (game list, detail, lifecycle modals, new-game wizard).
 
-### **Type Safety**
-- Full TypeScript implementation
-- Comprehensive type definitions for game domain
-- Type-safe component props and state management
+The Astro `src/components` folder is now a thin host layer (screens + island bootstrap) that consumes the library.
 
-### **Component Architecture**
-```
-src/
-├── components/
-│   ├── ui/           # Reusable UI components (Button, Card, Layout)
-│   ├── screens/      # Screen-level components
-│   └── ...           # Feature-specific components
-├── hooks/            # Custom React/Preact hooks
-├── services/         # Business logic and data management
-├── types/            # TypeScript type definitions
-├── utils/            # Pure utility functions
-└── styles/           # Global styles and CSS modules
-```
-
-### **State Management**
-- **useGameState**: Centralized game data management
-- **useNavigation**: Screen and routing state
-- **useModal**: Modal state management
-- **Custom hooks**: Encapsulated, reusable state logic
-
-### **Design System**
-- Consistent design tokens and CSS custom properties
-- Reusable UI components with variant support
-- Responsive design patterns
-- Accessibility-first approach
+Detailed module docs live in `src/lib/docs/architecture.md` and the individual `README.md` files under each package.
 
 ## 🚀 Getting Started
 
@@ -122,23 +95,23 @@ For detailed instructions on recording, modifying, and running scripts, see:
 ## 📁 Project Structure
 
 ### **Core Components**
-- `App.tsx` - Main application component with orchestrated state management
-- `screens/` - Screen-level components (GameList, NewGame, GameDetail)
-- `ui/` - Reusable UI components following design system
+- `src/components/App.tsx` - Astro-bound shell orchestrating library modules
+- `src/components/screens/` - Screen containers consuming `@lib/features`
+- `src/lib/` - Reusable application spine (domain/data/state/ui/features)
 
 ### **State Management**
-- `hooks/useGameState.ts` - Game CRUD operations and persistence
-- `hooks/useNavigation.ts` - Application routing and screen state
-- `hooks/useModal.ts` - Modal state management
+- `@lib/state/useGameState` - Game CRUD operations and persistence
+- `@lib/state/useNavigation` - Application routing and screen state
+- `@lib/state/useModal` - Modal state management helpers
 
 ### **Business Logic**
-- `services/gameService.ts` - Game creation, updates, and business rules
-- `utils/gameUtils.ts` - Game-related utility functions
-- `utils/validation.ts` - Input validation and sanitization
+- `@lib/data/gameService` - Game creation, updates, and persistence orchestration
+- `@lib/domain/gameUtils` - Game-related utility functions
+- `@lib/domain/validation` - Input validation and sanitisation
 
 ### **Type Definitions**
-- `types/game.ts` - Game domain types
-- `types/ui.ts` - UI component types
+- `@lib/domain/types` - Game domain types
+- `@lib/ui/types` - UI component types
 - `types/css-modules.d.ts` - CSS modules type support
 
 ## 🎯 Key Improvements