From 2cf7687d51dc1eee2f3a02b0414ee7f98002dceb Mon Sep 17 00:00:00 2001
From: Markus Graf <info@markusgraf.ch>
Date: Sun, 29 Mar 2026 12:14:28 +0200
Subject: [PATCH] feat(02-05): add avatar images to welcome screen with emoji
 fallback

- Extend CompanionDefinition with avatarUrl field using Vite static imports
- Replace emoji-only companion cards with avatar img + onerror emoji fallback
- Add companion-card__avatar CSS (80px round) and companion-area styles (48px)
- Add vite-env.d.ts for PNG import type declarations

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/companion/characters.ts | 17 +++++++++++++----
 src/styles/main.css         | 34 ++++++++++++++++++++++++++++++++++
 src/ui/screens.ts           |  4 +++-
 src/vite-env.d.ts           |  6 ++++++
 4 files changed, 56 insertions(+), 5 deletions(-)
 create mode 100644 src/vite-env.d.ts

diff --git a/src/companion/characters.ts b/src/companion/characters.ts
index 742a5e9..67c2cad 100644
--- a/src/companion/characters.ts
+++ b/src/companion/characters.ts
@@ -1,35 +1,44 @@
 import type { CompanionType } from "../types";
+import feeLilaAvatar from "../assets/companions/fee-lila/avatar.png";
+import einhornStellaAvatar from "../assets/companions/einhorn-stella/avatar.png";
+import fuchsFinnAvatar from "../assets/companions/fuchs-finn/avatar.png";
+import euleElsaAvatar from "../assets/companions/eule-elsa/avatar.png";
 
 export interface CompanionDefinition {
 	type: CompanionType;
 	name: string;
 	emoji: string;
 	personality: string;
+	avatarUrl: string;
 }
 
 export const companions: CompanionDefinition[] = [
 	{
 		type: "fee",
 		name: "Lila",
-		emoji: "🧚",
+		emoji: "\u{1F9DA}",
 		personality: "Sanft, ermutigend, ein bisschen vertraeumt",
+		avatarUrl: feeLilaAvatar,
 	},
 	{
 		type: "einhorn",
 		name: "Stella",
-		emoji: "🦄",
+		emoji: "\u{1F984}",
 		personality: "Froehlich, enthusiastisch, feiert jeden kleinen Erfolg",
+		avatarUrl: einhornStellaAvatar,
 	},
 	{
 		type: "fuchs",
 		name: "Finn",
-		emoji: "🦊",
+		emoji: "\u{1F98A}",
 		personality: "Ruhig, weise, humorvoll",
+		avatarUrl: fuchsFinnAvatar,
 	},
 	{
 		type: "eule",
 		name: "Elsa",
-		emoji: "🦉",
+		emoji: "\u{1F989}",
 		personality: "Geduldig, warm, grossmuetterlich",
+		avatarUrl: euleElsaAvatar,
 	},
 ];
diff --git a/src/styles/main.css b/src/styles/main.css
index c70c6b6..c27fcac 100644
--- a/src/styles/main.css
+++ b/src/styles/main.css
@@ -109,6 +109,14 @@ h3 {
 	background: var(--bg-forest);
 }
 
+.companion-card__avatar {
+	width: 80px;
+	height: 80px;
+	border-radius: 50%;
+	object-fit: cover;
+	margin-bottom: 0.5rem;
+}
+
 .companion-card__emoji {
 	font-size: 3rem;
 }
@@ -344,6 +352,32 @@ h3 {
 	}
 }
 
+/* Companion area (forest greeting + lesson avatar) */
+.companion-area {
+	display: flex;
+	align-items: center;
+	gap: 0.75rem;
+	padding: 0.75rem 1rem;
+	background: var(--bg-cream);
+	border-radius: 1rem;
+	margin-bottom: 1rem;
+}
+
+.companion-area__avatar {
+	width: 48px;
+	height: 48px;
+	border-radius: 50%;
+	object-fit: cover;
+	flex-shrink: 0;
+}
+
+.companion-area__text {
+	font-family: "Nunito", sans-serif;
+	font-size: 1rem;
+	color: var(--text-warm);
+	line-height: 1.4;
+}
+
 /* Keyboard */
 .keyboard {
 	display: flex;
diff --git a/src/ui/screens.ts b/src/ui/screens.ts
index efc249b..1de9bf4 100644
--- a/src/ui/screens.ts
+++ b/src/ui/screens.ts
@@ -30,7 +30,9 @@ export function initWelcomeScreen(
 		card.className = "companion-card";
 		card.dataset.companion = c.type;
 		card.innerHTML = `
-			<span class="companion-card__emoji">${c.emoji}</span>
+			<img class="companion-card__avatar" src="${c.avatarUrl}" alt="${c.name}"
+				onerror="this.style.display='none'; this.nextElementSibling.style.display='block';">
+			<span class="companion-card__emoji" style="display:none">${c.emoji}</span>
 			<span class="companion-card__name">${c.name}</span>
 		`;
 		card.addEventListener("click", () => {
diff --git a/src/vite-env.d.ts b/src/vite-env.d.ts
new file mode 100644
index 0000000..d8d4dd0
--- /dev/null
+++ b/src/vite-env.d.ts
@@ -0,0 +1,6 @@
+/// <reference types="vite/client" />
+
+declare module "*.png" {
+	const src: string;
+	export default src;
+}