Phase 4: Frontend-Core MVP — Decks, Cards, Study mit FSRS-Loop

Stack:
- Tailwind 4 via @tailwindcss/vite (oklch-Theme + Dark-Mode-Auto)
- marked + DOMPurify für Markdown (sanitized, SSR-Safe)
- Svelte 5 runes durchgängig ($state, $derived, $effect)
- @sveltejs/adapter-node für Production-Build

Infrastruktur:
- $lib/auth/dev-stub.svelte.ts: User-ID via sessionStorage (Phase 2
  ersetzt durch echtes JWT via @mana/shared-auth)
- $lib/api/{client,decks,cards,reviews}.ts: typed Fetch-Wrapper, ruft
  cards-api auf 3081 mit X-User-Id-Header
- $lib/stores/toasts.svelte.ts: Toast-Store mit info/success/warning/error
- $lib/markdown.ts: marked → DOMPurify-Pipeline
- $lib/components/{Header,ToastStack}.svelte: Layout-Shell

Routes:
- / → Dev-Login-Form oder Redirect zu /decks (wenn eingeloggt)
- /decks → Liste mit Color-Dot, Hover-Delete-Button
- /decks/new → Create-Form (Name, Beschreibung, Color-Picker)
- /decks/[id] → Detail mit Cards-Liste + dueCount + "Lernen"-Button
- /cards/new?deck=... → Type-Picker (basic|basic-reverse) +
  Side-by-Side Markdown-Editor mit Live-Preview
- /study → Übersicht aller Decks mit Due-Counts
- /study/[deckId] → Session-View mit Queue-Snapshot, Reveal/Grade,
  Hotkeys (Space/Enter=Reveal & Good, 1-4=Again/Hard/Good/Easy),
  INPUT-Skip im Keyboard-Handler

CORS auf cards-api für localhost-Origins + cardecky.mana.how.

Verifiziert:
- pnpm run type-check ✅ 4/4 packages, svelte-check 0 errors
- pnpm build (cards-web) ✅ adapter-node bundle 140 kB server,
  alle Routen bundled
- Tailwind-CSS inlined in SSR-HTML, oklch-Theme korrekt
- CORS-Preflight funktioniert (OPTIONS 204 mit korrekten Allow-*-Headers)
- Live-Smoke-Test gegen localhost:3081 (cards-api) + localhost:3082
  (cards-web): Beide laufen parallel, Web → API CORS-fetch grün

Outside scope (Phase 4):
- Card-Edit-Page (/cards/[id]/edit) — heute nur Create + Delete
- Settings/Account/Credits/DSGVO-Pages — Phase 9 (Polish)
- Anki-Import — Phase 8

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

apps/web/src/lib/api/cards.ts

@@ -0,0 +1,23 @@
+import type { Card, CardCreate, CardUpdate } from '@cards/domain';
+import { api } from './client.ts';
+
+export function listCards(deckId?: string) {
+	const qs = deckId ? `?deck_id=${encodeURIComponent(deckId)}` : '';
+	return api<{ cards: Card[]; total: number }>(`/api/v1/cards${qs}`);
+}
+
+export function getCard(id: string) {
+	return api<Card>(`/api/v1/cards/${id}`);
+}
+
+export function createCard(input: CardCreate) {
+	return api<Card>('/api/v1/cards', { method: 'POST', body: input });
+}
+
+export function updateCard(id: string, patch: CardUpdate) {
+	return api<Card>(`/api/v1/cards/${id}`, { method: 'PATCH', body: patch });
+}
+
+export function deleteCard(id: string) {
+	return api<{ deleted: string }>(`/api/v1/cards/${id}`, { method: 'DELETE' });
+}

apps/web/src/lib/api/client.ts

@@ -0,0 +1,55 @@
+/**
+ * Cards-API-Client. Dünner Fetch-Wrapper, der `X-User-Id`-Header aus
+ * dem Dev-Auth-Stub setzt. Phase 2 ersetzt das durch ein Bearer-Token
+ * aus @mana/shared-auth.
+ */
+
+import { devUser } from '$lib/auth/dev-stub.svelte.ts';
+
+export const API_BASE = (() => {
+	if (typeof window !== 'undefined') {
+		return import.meta.env.PUBLIC_CARDS_API_URL ?? 'http://localhost:3081';
+	}
+	return process.env.CARDS_API_URL ?? 'http://localhost:3081';
+})();
+
+export class ApiError extends Error {
+	constructor(
+		readonly status: number,
+		readonly body: unknown,
+		message?: string
+	) {
+		super(message ?? `cards-api ${status}`);
+	}
+}
+
+type RequestOptions = {
+	method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+	body?: unknown;
+	signal?: AbortSignal;
+};
+
+export async function api<T>(path: string, opts: RequestOptions = {}): Promise<T> {
+	const headers: Record<string, string> = {
+		'Content-Type': 'application/json',
+	};
+	if (devUser.id) {
+		headers['X-User-Id'] = devUser.id;
+	}
+	const res = await fetch(`${API_BASE}${path}`, {
+		method: opts.method ?? 'GET',
+		headers,
+		body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+		signal: opts.signal,
+	});
+	if (!res.ok) {
+		let body: unknown = null;
+		try {
+			body = await res.json();
+		} catch {
+			body = await res.text();
+		}
+		throw new ApiError(res.status, body);
+	}
+	return (await res.json()) as T;
+}

apps/web/src/lib/api/decks.ts

@@ -0,0 +1,22 @@
+import type { Deck, DeckCreate, DeckUpdate } from '@cards/domain';
+import { api } from './client.ts';
+
+export function listDecks() {
+	return api<{ decks: Deck[]; total: number }>('/api/v1/decks');
+}
+
+export function getDeck(id: string) {
+	return api<Deck>(`/api/v1/decks/${id}`);
+}
+
+export function createDeck(input: DeckCreate) {
+	return api<Deck>('/api/v1/decks', { method: 'POST', body: input });
+}
+
+export function updateDeck(id: string, patch: DeckUpdate) {
+	return api<Deck>(`/api/v1/decks/${id}`, { method: 'PATCH', body: patch });
+}
+
+export function deleteDeck(id: string) {
+	return api<{ deleted: string }>(`/api/v1/decks/${id}`, { method: 'DELETE' });
+}

apps/web/src/lib/api/reviews.ts

@@ -0,0 +1,23 @@
+import type { Card, Rating, Review } from '@cards/domain';
+import { api } from './client.ts';
+
+export type DueReview = Review & {
+	card?: Pick<Card, 'id' | 'deck_id' | 'type' | 'fields'>;
+};
+
+export function listDueReviews(opts: { deckId?: string; limit?: number } = {}) {
+	const params = new URLSearchParams();
+	if (opts.deckId) params.set('deck_id', opts.deckId);
+	if (opts.limit) params.set('limit', String(opts.limit));
+	const qs = params.toString();
+	return api<{ reviews: DueReview[]; total: number }>(
+		`/api/v1/reviews/due${qs ? `?${qs}` : ''}`
+	);
+}
+
+export function gradeReview(cardId: string, subIndex: number, rating: Rating) {
+	return api<Review>(`/api/v1/reviews/${cardId}/${subIndex}/grade`, {
+		method: 'POST',
+		body: { rating },
+	});
+}

apps/web/src/lib/auth/dev-stub.svelte.ts

@@ -0,0 +1,35 @@
+/**
+ * Dev-Auth-Stub. Phase 2 ersetzt diesen Layer durch echtes JWT-
+ * Handling via @mana/shared-auth gegen mana-auth.
+ *
+ * Für jetzt: User-ID lebt in sessionStorage und wird als
+ * `X-User-Id`-Header an cards-api geschickt.
+ */
+
+class DevUser {
+	id = $state<string | null>(null);
+
+	constructor() {
+		if (typeof window !== 'undefined') {
+			this.id = sessionStorage.getItem('cards.dev.userId');
+		}
+	}
+
+	set(userId: string) {
+		const trimmed = userId.trim();
+		if (!trimmed) return;
+		this.id = trimmed;
+		if (typeof window !== 'undefined') {
+			sessionStorage.setItem('cards.dev.userId', trimmed);
+		}
+	}
+
+	clear() {
+		this.id = null;
+		if (typeof window !== 'undefined') {
+			sessionStorage.removeItem('cards.dev.userId');
+		}
+	}
+}
+
+export const devUser = new DevUser();

apps/web/src/lib/components/Header.svelte

@@ -0,0 +1,53 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { devUser } from '$lib/auth/dev-stub.svelte.ts';
+</script>
+
+<header
+	class="sticky top-0 z-40 w-full border-b bg-[var(--color-card)] border-[var(--color-border)]"
+>
+	<div class="mx-auto flex max-w-6xl items-center justify-between px-4 py-3">
+		<a href="/" class="flex items-center gap-2 font-semibold">
+			<span
+				class="inline-flex h-7 w-7 items-center justify-center rounded bg-[var(--color-primary)] text-[var(--color-primary-fg)] text-sm"
+			>
+				C
+			</span>
+			<span>Cards</span>
+		</a>
+
+		<nav class="flex items-center gap-6 text-sm">
+			<a
+				href="/decks"
+				class="hover:text-[var(--color-primary)]"
+				class:font-medium={page.url.pathname.startsWith('/decks')}>Decks</a
+			>
+			<a
+				href="/study"
+				class="hover:text-[var(--color-primary)]"
+				class:font-medium={page.url.pathname.startsWith('/study')}>Lernen</a
+			>
+		</nav>
+
+		<div class="flex items-center gap-3 text-sm">
+			{#if devUser.id}
+				<span class="text-[var(--color-muted)]"
+					>{devUser.id}
+				</span>
+				<button
+					class="rounded border px-2 py-1 text-xs hover:bg-[var(--color-border)] border-[var(--color-border)]"
+					onclick={() => devUser.clear()}
+				>
+					Logout (dev)
+				</button>
+			{:else}
+				<button
+					class="rounded bg-[var(--color-primary)] px-3 py-1 text-[var(--color-primary-fg)]"
+					onclick={() => devUser.set(prompt('User-ID (dev):') ?? '')}
+				>
+					Login (dev)
+				</button>
+			{/if}
+		</div>
+	</div>
+</header>

apps/web/src/lib/components/ToastStack.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+	import { toasts } from '$lib/stores/toasts.svelte.ts';
+</script>
+
+{#if toasts.items.length > 0}
+	<div class="fixed bottom-4 right-4 z-50 flex flex-col gap-2">
+		{#each toasts.items as t (t.id)}
+			<div
+				class="flex items-start gap-3 rounded-lg px-4 py-3 shadow-lg max-w-sm border bg-[var(--color-card)] border-[var(--color-border)]"
+				class:text-[var(--color-success)]={t.kind === 'success'}
+				class:text-[var(--color-warning)]={t.kind === 'warning'}
+				class:text-[var(--color-danger)]={t.kind === 'error'}
+			>
+				<span class="flex-1 text-sm">{t.message}</span>
+				<button
+					class="text-[var(--color-muted)] hover:text-[var(--color-fg)] text-lg leading-none"
+					onclick={() => toasts.dismiss(t.id)}
+					aria-label="Schließen"
+				>
+					×
+				</button>
+			</div>
+		{/each}
+	</div>
+{/if}

apps/web/src/lib/markdown.ts

@@ -0,0 +1,22 @@
+import DOMPurify from 'dompurify';
+import { marked } from 'marked';
+
+marked.setOptions({
+	gfm: true,
+	breaks: true,
+});
+
+/**
+ * Markdown → HTML, sanitized via DOMPurify.
+ * Sicher gegen Stored-XSS aus User-Card-Inhalten.
+ *
+ * SSR-Hinweis: marked + DOMPurify müssen nur im Browser laufen
+ * (DOMPurify erwartet `window`). Aufrufer sind Card-Editor und
+ * Study-View, beide sind client-only.
+ */
+export function renderMarkdown(source: string): string {
+	if (!source) return '';
+	const html = marked.parse(source, { async: false }) as string;
+	if (typeof window === 'undefined') return html; // SSR-Fallback (selten Pfad)
+	return DOMPurify.sanitize(html);
+}

apps/web/src/lib/stores/toasts.svelte.ts

@@ -0,0 +1,44 @@
+/**
+ * Toast-Notifications. Svelte-5-Runes-Pattern: ein Modul-State,
+ * dessen Mutationen reaktiv von Components beobachtet werden.
+ */
+
+export type ToastKind = 'info' | 'success' | 'warning' | 'error';
+
+export type Toast = {
+	id: string;
+	kind: ToastKind;
+	message: string;
+	expires_at: number;
+};
+
+class ToastStore {
+	items = $state<Toast[]>([]);
+	private nextId = 1;
+
+	push(kind: ToastKind, message: string, durationMs = 4000) {
+		const id = `t-${this.nextId++}`;
+		const t: Toast = { id, kind, message, expires_at: Date.now() + durationMs };
+		this.items.push(t);
+		setTimeout(() => this.dismiss(id), durationMs);
+	}
+
+	dismiss(id: string) {
+		this.items = this.items.filter((t) => t.id !== id);
+	}
+
+	info(msg: string) {
+		this.push('info', msg);
+	}
+	success(msg: string) {
+		this.push('success', msg);
+	}
+	warning(msg: string) {
+		this.push('warning', msg);
+	}
+	error(msg: string) {
+		this.push('error', msg);
+	}
+}
+
+export const toasts = new ToastStore();