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

src/lib/ui/README.md

@@ -0,0 +1,35 @@
+# UI Primitives (`@lib/ui`)
+
+Reusable presentation components with co-located CSS modules. No business logic; just view concerns.
+
+## Components
+
+- `Button` – Variant + size aware button with shared styling.
+- `Card` – Basic container with optional elevated/outlined variants.
+- `Layout` / `Screen` – Page chrome primitives used by the Astro shell.
+- `Modal` – Generic confirmation modal (title, message, confirm/cancel).
+- `ValidationModal` – Specialized modal for validation feedback.
+
+## Types
+
+- `types.ts` defines `ButtonProps`, modal state types, etc. Re-exported via `@lib/ui`.
+
+## Usage
+
+```tsx
+import { Button, Card, Layout } from '@lib/ui';
+
+<Layout>
+  <Card variant="elevated">
+    <Button variant="primary">Start</Button>
+  </Card>
+</Layout>
+```
+
+## Styling
+
+- Each component ships with a `.module.css` file.  
+  Astro/Vite handles module scoping automatically—consumers simply import the component.
+- Custom class names can be injected through the exposed `className` props when required.
+
+