Release 0.3.0 - UX, Performance & Hugging Face Pivot

CONTRIBUTING.md

@@ -12,6 +12,7 @@ Thank you for your interest in contributing! We follow a **Spec-Driven Developme
 ## 💻 Coding Standards
 
 - **No Inline Styles**: To ensure maintainability and style consistency, inline styles (`style={{ ... }}`) are prohibited in production components. Use Tailwind classes exclusively.
+- **Markdown Security**: All AI-generated content MUST be passed through the sanitization pipeline in `TripViewer.tsx`. Never use `dangerouslySetInnerHTML` or disable sanitization without a security review. Any new component added to the markdown renderer must be explicitly whitelisted in the sanitization schema.
 
 ## 🔄 Workflow & Automation
 
@@ -57,6 +58,16 @@ If working without an agent, follow these steps to keep the project state synchr
 | `npm run test:e2e`   | Run E2E tests with Playwright                        |
 | `npm run type-check` | Validate TypeScript types                            |
 
+## 📦 Deployment
+
+This project is optimized for static hosting on **GitHub Pages**:
+
+```bash
+npm run deploy
+```
+
+_Note: This command runs `next build` with `output: 'export'` and pushes the `out` directory to the `gh-pages` branch._
+
 ## 🧪 Testing Strategy
 
 Beyond end-to-end testing, we use a multi-tiered strategy for component, accessibility, and visual validation:

README.md

@@ -6,24 +6,44 @@
 [![Framework](https://img.shields.io/badge/Built_with-React-61DAFB?logo=react)](https://react.dev)
 [![AI](https://img.shields.io/badge/AI_Model-Llama_3-7B1FA2?logo=meta)](https://huggingface.co)
 
-**Quick-tripper** is a privacy-first, zero-backend travel companion web app that generates detailed road trip itineraries using AI. It operates entirely in your browser—no databases, no logins, no tracking.
+**Quick-tripper** is a privacy-first, zero-backend travel companion web app that generates detailed road trip itineraries using AI. It operates entirely in your browser—no databases, no logins, no tracking. Now powered by **Llama 3.1** via the Hugging Face Serverless API.
 
 ## ✨ Features
 
-- **🌍 Smart Itineraries**: Generate day-by-day travel plans using Llama 3 via the Hugging Face Router.
-- **🗺️ Interactive Maps**: Embedded Google Maps for every journey, secured via client-side validation.
+- **🌍 Smart Itineraries**: Generate day-by-day travel plans using Llama 3.1.
+- **🗺️ Interactive Maps**: Embedded Google Maps for every journey, rendered securely from AI-generated routes.
 - **🔒 Privacy-First**: "Bring Your Own Key" (BYOK) model. Your API token is stored locally in your browser and never sent to our servers.
-- **🔗 Compressed Sharing**: Share your entire itinerary via a single, ultra-compressed URL (powered by LZString). No backend storage required.
+- **🔗 Compressed Sharing**: Share your entire itinerary via a single, ultra-compressed URL (powered by LZString).
 - **💾 Local Persistence**: Automatic synchronization with your browser's local storage.
-- **🚦 Quality Control**: Pre-commit hooks via Husky and lint-staged to ensure type safety and code style.
-- **🧪 Automated Testing**: Unit and utility testing powered by Vitest and JSDOM.
-- **🚀 Serverless Architecture**: Designed to be hosted on static platforms like GitHub Pages.
+- **🛡️ Secure Rendering**: Strict markdown sanitization to prevent XSS and ensure your browser environment remains safe.
+
+## 📖 How-to Use
+
+1. **Enter your Hugging Face API Token**: Get a free "User Access Token" from your [Hugging Face Settings](https://huggingface.co/settings/tokens).
+2. **Describe your trip**: Use the prompt area to describe where you want to go, for how long, and what you like.
+3. **Generate**: Click "Generate Itinerary" and wait a few seconds.
+4. **Explore**: Use the interactive map and read the day-by-day suggestions.
+5. **Manage**: Your trips are saved automatically. You can export them as JSON or share them via a unique link.
+
+## 🔒 Privacy & BYOK (Bring Your Own Key)
+
+Quick-tripper is designed to be **serverless and private**. We don't have a backend to store your data or your keys.
+
+- **Local Storage**: Your API token and trip history are stored ONLY in your browser's local storage.
+- **Direct AI Calls**: The app communicates directly with Hugging Face APIs from your browser.
+- **No Tracking**: We don't use cookies, analytics, or tracking scripts.
+
+To use the app, you need a **Hugging Face User Access Token**.
+
+- Visit [Hugging Face Settings](https://huggingface.co/settings/tokens).
+- Create a new token (Read access is enough).
+- Paste it into the top bar of Quick-tripper.
 
 ## 🛠️ Tech Stack
 
 - **Framework**: [Next.js 15+](https://nextjs.org) (App Router)
 - **Styling**: [TailwindCSS 4](https://tailwindcss.com) + [DaisyUI 5](https://daisyui.com)
-- **AI Integration**: [Hugging Face Router](https://huggingface.co/docs/hub/spaces-router) (OpenAI-compatible)
+- **AI Integration**: [Llama 3.1 8B](https://huggingface.co/meta-llama/Llama-3.1-8B-Instruct) via Hugging Face Router.
 - **Data Compression**: [LZString](https://pieroxy.net/lua/lz-string/index.html)
 - **Testing**: [Vitest](https://vitest.dev) + [React Testing Library](https://testing-library.com)
 - **Automation**: [Husky](https://typicode.github.io/husky/) + [lint-staged](https://github.com/lint-staged/lint-staged)
@@ -37,21 +57,20 @@ This project follows **Spec-Driven Development (SDD)** to maintain a clear roadm
 
 ## 🚀 Getting Started
 
-1. **Get an API Key**: Obtain a free User Access Token from [Hugging Face Settings](https://huggingface.co/settings/tokens).
-2. **Clone the Repo**:
+1. **Clone the Repo**:
    ```bash
    git clone https://github.com/gehdoc/quick-tripper.git
    cd quick-tripper
    ```
-3. **Install Dependencies**:
+2. **Install Dependencies**:
    ```bash
    npm install
    ```
-4. **Run Locally**:
+3. **Run Locally**:
    ```bash
    npm run dev
    ```
-5. **Open the App**: Visit `http://localhost:3000` (development) or `http://localhost:3000/quick-tripper` (production-emulated) and enter your API key in the top bar.
+4. **Open the App**: Visit `http://localhost:3000` (development) or `http://localhost:3000/quick-tripper` (production-emulated) and enter your API key in the top bar.
 
 ## 🏗️ Architecture
 
@@ -68,16 +87,6 @@ To maintain a robust "zero-backend" application, we rely on a multi-tiered valid
 5. **E2E Testing**: Playwright validates full user workflows and "golden paths" in a real browser environment.
 6. **Spec-First Implementation**: Every change is traced back to a technical specification in `specs/`, ensuring architectural alignment.
 
-## 📦 Deployment
-
-This project is optimized for static hosting on **GitHub Pages**:
-
-```bash
-npm run deploy
-```
-
-_Note: This command runs `next build` with `output: 'export'` and pushes the `out` directory to the `gh-pages` branch._
-
 ## 📄 License
 
 MIT © [Quick-tripper](https://github.com/gehdoc/quick-tripper)

docs/ARCHITECTURE.md

@@ -40,6 +40,29 @@ When the `Trip` data structure changes in a breaking way, follow these steps to
 5.  **Test**:
     - Add test cases in `src/tests/migration.test.ts` to verify the upgrade path from `v<N-1>` to `v<N>`.
 
+## AI Integration
+
+The application uses **Llama 3.1 (8B)** for itinerary generation, accessed via the Hugging Face Serverless API.
+
+### Structured Output
+
+We enforce a JSON schema through strict system prompts. This allows us to reliably extract:
+
+- `title`: A clean summary of the trip.
+- `start`/`stop`: Geocodable endpoints for map rendering and future filtering.
+- `content`: The markdown-formatted itinerary.
+
+## Security Architecture
+
+### Markdown Sanitization (XSS Prevention)
+
+To maintain user safety in a BYOK (Bring Your Own Key) environment, the application implements a strict **Whitelist-Only** sanitization policy for AI-generated content.
+
+1.  **Strict Whitelisting**: We use `rehype-sanitize` to strip all potentially dangerous HTML tags (`<script>`, `<object>`, `<embed>`, `<form>`, etc.) and attributes (event handlers like `onclick`).
+2.  **Iframe Protection**: Raw `<iframe>` tags from the AI are blocked entirely.
+3.  **Managed Map Rendering**: Iframes are ONLY permitted when generated by our internal `TripViewer` logic, which converts verified Google Maps URLs into secure embedded views.
+4.  **No Tracking**: By blocking `<img>` tags and external CSS, we prevent the AI from including tracking pixels or malicious styling.
+
 ## Component Architecture
 
 The project follows a **Smart Container & Dumb Presenter** pattern (Clean Architecture) to ensure high testability and separation of concerns.

e2e/golden-path.spec.ts

@@ -2,30 +2,41 @@ import { test, expect } from '@playwright/test';
 
 test('golden path - generate trip', async ({ page }) => {
   await page.goto('/');
-  // Mock API
-  await page.route('https://router.huggingface.co/v1/chat/completions', (route) =>
+
+  // Mock Hugging Face API (OpenAI compatible)
+  await page.route('**/v1/chat/completions', (route) =>
     route.fulfill({
       status: 200,
       contentType: 'application/json',
       body: JSON.stringify({
         choices: [
           {
             message: {
-              content: '# Golden Trip\nThis is a mocked itinerary.',
+              content: JSON.stringify({
+                title: 'Golden Trip',
+                start: 'Zurich',
+                stop: 'Interlaken',
+                content: '### Golden Trip\nThis is a mocked itinerary.',
+              }),
             },
           },
         ],
       }),
     }),
   );
 
-  // Enter API Key
-  await page.getByPlaceholder('HuggingFace API Token').fill('dummy-key');
-  // Enter Destination
-  await page.getByPlaceholder('Ex: A 4-day hike').fill('Swiss Alps');
+  // Enter API Key (Restored Hugging Face placeholder)
+  await page.getByPlaceholder('HuggingFace API Token').fill('hf_dummy-key');
+
+  // Enter Prompt (Textarea)
+  await page.getByPlaceholder(/Ex: A 4-day hike itinerary/i).fill('Swiss Alps');
+
   // Send
-  await page.locator('.join').getByRole('button').click(); // Send icon button within join component
+  await page.getByRole('button', { name: /Generate Itinerary/i }).click();
+
+  // Verify Heading (Rendered in Navigator) - Using .first() or specific role to avoid ambiguity
+  await expect(page.getByRole('heading', { name: 'Golden Trip' })).toBeVisible();
 
-  // Verify
-  await expect(page.getByText('Golden Trip')).toBeVisible();
+  // Verify Content
+  await expect(page.getByText('This is a mocked itinerary.')).toBeVisible();
 });

package.json

@@ -1,7 +1,7 @@
 {
   "name": "quick-tripper",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true,
   "description": "Privacy-first, zero-backend AI travel companion",
   "author": "GehDoc",
@@ -60,7 +60,8 @@
     "react-dom": "19.2.4",
     "react-icons": "^5.6.0",
     "react-markdown": "^10.1.0",
-    "rehype-raw": "^7.0.0"
+    "rehype-raw": "^7.0.0",
+    "rehype-sanitize": "^6.0.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",

playwright.config.ts

@@ -8,7 +8,7 @@ export default defineConfig({
   workers: process.env.CI ? 1 : undefined,
   reporter: 'list',
   use: {
-    baseURL: 'http://localhost:3001',
+    baseURL: 'http://localhost:3002',
     trace: 'on-first-retry',
   },
   projects: [
@@ -18,8 +18,8 @@ export default defineConfig({
     },
   ],
   webServer: {
-    command: 'npx next dev -p 3001',
-    url: 'http://localhost:3001',
+    command: 'npx next dev -p 3002',
+    url: 'http://localhost:3002',
     reuseExistingServer: !process.env.CI,
     timeout: 120000,
   },