✨ Add narrator texts infrastructure with API (Story 3.1)

- Create narrator_texts table migration with context/hero_type indexes
- Add NarratorText model with getRandomText() for variant selection
- Add NarratorTextSeeder with 30+ texts for 11 contexts
- Implement vouvoiement (recruteur) vs tutoiement (client/dev)
- Create NarratorController with GET /api/narrator/{context}
- Add useFetchNarratorText composable for frontend

Contexts: intro, transitions, hints, encouragements, contact_unlocked, welcome_back

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

api/app/Http/Controllers/Api/NarratorController.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Models\NarratorText;
+use App\Models\Translation;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+class NarratorController extends Controller
+{
+    private const VALID_CONTEXTS = [
+        'intro',
+        'transition_projects',
+        'transition_skills',
+        'transition_testimonials',
+        'transition_journey',
+        'hint',
+        'encouragement_25',
+        'encouragement_50',
+        'encouragement_75',
+        'contact_unlocked',
+        'welcome_back',
+    ];
+
+    private const VALID_HERO_TYPES = ['recruteur', 'client', 'dev'];
+
+    public function getText(Request $request, string $context): JsonResponse
+    {
+        if (!in_array($context, self::VALID_CONTEXTS)) {
+            return response()->json([
+                'error' => [
+                    'code' => 'INVALID_CONTEXT',
+                    'message' => 'Invalid narrator context',
+                    'valid_contexts' => self::VALID_CONTEXTS,
+                ],
+            ], 404);
+        }
+
+        $lang = app()->getLocale();
+        $heroType = $request->query('hero');
+
+        // Valider hero_type
+        if ($heroType && !in_array($heroType, self::VALID_HERO_TYPES)) {
+            $heroType = null;
+        }
+
+        $narratorText = NarratorText::getRandomText($context, $heroType);
+
+        if (!$narratorText) {
+            return response()->json([
+                'error' => [
+                    'code' => 'NO_TEXT_FOUND',
+                    'message' => 'No narrator text found for this context',
+                ],
+            ], 404);
+        }
+
+        $text = Translation::getTranslation($narratorText->text_key, $lang);
+
+        return response()->json([
+            'data' => [
+                'context' => $context,
+                'text' => $text,
+                'variant' => $narratorText->variant,
+                'hero_type' => $narratorText->hero_type,
+            ],
+            'meta' => [
+                'lang' => $lang,
+            ],
+        ]);
+    }
+}

api/app/Models/NarratorText.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
+
+class NarratorText extends Model
+{
+    protected $fillable = [
+        'context',
+        'text_key',
+        'variant',
+        'hero_type',
+    ];
+
+    public function scopeForContext(Builder $query, string $context): Builder
+    {
+        return $query->where('context', $context);
+    }
+
+    public function scopeForHero(Builder $query, ?string $heroType): Builder
+    {
+        if ($heroType) {
+            return $query->where(function ($q) use ($heroType) {
+                $q->where('hero_type', $heroType)
+                  ->orWhereNull('hero_type');
+            });
+        }
+
+        return $query->whereNull('hero_type');
+    }
+
+    public static function getRandomText(string $context, ?string $heroType = null): ?self
+    {
+        $query = static::forContext($context);
+
+        if ($heroType) {
+            // Priorité aux textes spécifiques au héros, sinon textes génériques
+            $heroSpecific = (clone $query)->where('hero_type', $heroType)->inRandomOrder()->first();
+            if ($heroSpecific) {
+                return $heroSpecific;
+            }
+        }
+
+        return $query->whereNull('hero_type')->inRandomOrder()->first();
+    }
+}