Merge feat/inline-wowhead-links into release/v0.3.0

Inline [Label](kind:id) markdown links in every prose section of the
analysis card. Frontend resolves to Wowhead components; talent ids get
mapped through their underlying spell id via the new
_talent_spell_ids output field.

Author: babatonga

backend/app/services/ai/analyzer.py

@@ -20,6 +20,7 @@
     ReportPlayer,
     ReportPlayerCast,
     TopLog,
+    WowLocalization,
 )
 from app.services.ai.anthropic_provider import AnthropicProvider
 from app.services.ai.base import AiProvider, AiResponse
@@ -548,6 +549,55 @@ async def _collect_localized_names(
     return names
 
 
+async def _collect_talent_spell_ids(
+    session: AsyncSession,
+    *,
+    player_summary: dict[str, Any],
+    references: list[dict[str, Any]],
+) -> dict[str, int]:
+    """Build a ``{TraitNodeEntry.ID: SpellID}`` map for every talent ID
+    that appears in the player_summary or any top-log reference detail.
+
+    Frontend uses this to turn ``[Label](talent:<id>)`` inline markdown
+    links into real Wowhead spell links — the TraitNodeEntry IDs WCL
+    ships collide with old MoP-era spell IDs, so we have to resolve
+    through ``wow_localizations.extras['spell_id']`` (populated by
+    ``_import_talents``) before linking. Missing entries silently fall
+    back to bold text on the frontend.
+    """
+    talent_ids: set[int] = set()
+    for tid in player_summary.get("talent_ids") or []:
+        if tid:
+            talent_ids.add(int(tid))
+    for ref in references:
+        for tid in (ref.get("detail") or {}).get("talent_ids") or []:
+            if tid:
+                talent_ids.add(int(tid))
+    if not talent_ids:
+        return {}
+    # One row per talent (en locale — extras['spell_id'] is locale-
+    # agnostic). UNIQUE constraint on (kind, game_id, locale) means
+    # we only ever get one row per ID.
+    rows = (
+        await session.execute(
+            select(WowLocalization.game_id, WowLocalization.extras)
+            .where(WowLocalization.kind == "talent")
+            .where(WowLocalization.locale == "en")
+            .where(WowLocalization.game_id.in_(talent_ids))
+        )
+    ).all()
+    out: dict[str, int] = {}
+    for game_id, extras in rows:
+        spell_id = (extras or {}).get("spell_id")
+        if not spell_id:
+            continue
+        try:
+            out[str(int(game_id))] = int(spell_id)
+        except (TypeError, ValueError):
+            continue
+    return out
+
+
 async def request_analysis(
     session: AsyncSession,
     *,
@@ -821,6 +871,9 @@ def _annotate_damage_taken(
         gear=gear,
         references=references,
     )
+    talent_spell_ids = await _collect_talent_spell_ids(
+        session, player_summary=player_summary, references=references
+    )
 
     # If the row already exists (worker path), it tells us whether BYOK was
     # requested. New rows fall through to the app-wide path.
@@ -915,6 +968,11 @@ def _annotate_damage_taken(
         analysis.structured = {
             **(response.structured or {}),
             "_localized_names": localized_names,
+            # ``[Label](talent:<id>)`` markdown links in the AI's prose
+            # carry TraitNodeEntry IDs (different namespace from spell
+            # IDs). Frontend resolves to the underlying spell ID via
+            # this map before linking to Wowhead.
+            "_talent_spell_ids": talent_spell_ids,
             "_parse_metrics": {
                 "parse_percent": parse_metrics.get("rank_percent"),
                 "ilvl_percent": parse_metrics.get("ilvl_percent"),

backend/app/services/ai/prompts.py

@@ -82,6 +82,27 @@ def stat_glossary_for(locale: Locale) -> dict[str, str]:
   buff/debuff uptime percentages, and damage/healing totals from the JSON.
 - For every finding, name the spell(s) or item(s) involved by spell ID / item
   ID (so the UI can render Wowhead tooltips).
+- **EVERY mention of a spell, item or talent in your prose MUST be written
+  as an inline markdown link in the form ``[Label](kind:id)``** — the
+  frontend parses these and renders them as Wowhead tooltip-aware links.
+  This applies to ``findings[*].detail``, ``rotation_summary``,
+  ``cooldown_usage_summary``, ``stat_recommendations``,
+  ``talent_recommendations``, ``gear_and_trinket_notes``,
+  ``comparison_to_top_logs``, ``headline`` and every entry of
+  ``strengths``. Three valid forms:
+
+      [Mana Tea](spell:115294)            — buffs, casts, debuffs, boss abilities
+      [Algari Mana Potion](item:212017)   — consumables, trinkets, gear
+      [Tea Time](talent:124683)           — talent-tree picks from talent_ids
+
+  ``Label`` is the localised name (use ``localized_names`` verbatim — never
+  invent translations). ``id`` is the numeric ID exactly as it appears in
+  the relevant key of ``localized_names`` / ``talent_ids`` / the gear's
+  ``item_id`` / the cast's ``ability_id``. Do **not** write a plain spell
+  name without the ``[…](spell:…)`` wrapper, do **not** emit raw Wowhead
+  URLs yourself, and do **not** invent IDs that don't appear in the data.
+  When you genuinely need to refer to an ability whose ID isn't in the
+  data, write ``the ability "X"`` in plain text — no link.
 - Compare the player's casts, buff uptimes, and gear against the supplied
   top-log reference players (same spec, same encounter, same region, same
   difficulty). Call out concrete deltas:
@@ -257,6 +278,28 @@ def stat_glossary_for(locale: Locale) -> dict[str, str]:
   Prozente, Damage-/Healing-Summen aus dem JSON.
 - Bei jedem Befund die betroffenen Zauber/Items per Spell-ID / Item-ID
   benennen, damit die UI Wowhead-Tooltips rendern kann.
+- **JEDE Erwähnung eines Zaubers, Items oder Talents in deinem Fließtext
+  MUSS als inline Markdown-Link in der Form ``[Label](kind:id)``
+  geschrieben werden** — das Frontend parst diese und rendert sie als
+  Wowhead-Tooltips. Gilt für ``findings[*].detail``, ``rotation_summary``,
+  ``cooldown_usage_summary``, ``stat_recommendations``,
+  ``talent_recommendations``, ``gear_and_trinket_notes``,
+  ``comparison_to_top_logs``, ``headline`` und jeden Eintrag von
+  ``strengths``. Drei gültige Formen:
+
+      [Mana-Tee](spell:115294)            — Buffs, Casts, Debuffs, Boss-Fähigkeiten
+      [Algari-Manatrank](item:212017)     — Verbrauchsgüter, Trinkets, Ausrüstung
+      [Teezeit](talent:124683)            — Talente aus talent_ids
+
+  ``Label`` ist der lokalisierte Name (nutze ``localized_names`` verbatim
+  — übersetze nichts selbst). ``id`` ist die numerische ID exakt wie sie
+  im jeweiligen Schlüssel von ``localized_names`` / ``talent_ids`` / im
+  ``item_id`` des Gears / im ``ability_id`` des Casts steht. Schreib
+  **keinen** plain Zaubernamen ohne ``[…](spell:…)``-Wrapper, gib
+  **keine** rohen Wowhead-URLs aus, und **erfinde keine** IDs die nicht
+  in den Daten stehen. Wenn du wirklich eine Fähigkeit erwähnen musst,
+  deren ID nicht in den Daten ist, schreib „die Fähigkeit X" als
+  Plaintext — kein Link.
 - Casts, Buff-Uptimes und Ausrüstung des Spielers gegen die mitgelieferten
   Top-Log-Referenzspieler (gleiche Spec, gleicher Boss, gleiche Region,
   gleiche Schwierigkeit) vergleichen. Konkrete Deltas nennen:

frontend/src/components/AnalysisCard.tsx

@@ -5,6 +5,7 @@ import { useEffect, useMemo } from "react";
 
 import { Card } from "@/components/ui";
 import { ItemLink } from "@/components/ItemLink";
+import { ProseWithLinks, hasInlineRefs } from "@/components/ProseWithLinks";
 import { SeverityBadge } from "@/components/SeverityBadge";
 import { SpellLink } from "@/components/SpellLink";
 import { formatPercent } from "@/lib/format";
@@ -26,6 +27,12 @@ export function AnalysisCard({ analysis, locale }: Props) {
   // for the spell/item chips even when ad blockers stop wowhead's tooltip
   // script from auto-renaming the link.
   const nameMap = structured._localized_names ?? {};
+  // ``_talent_spell_ids`` is the per-analysis lookup the backend ships so
+  // we can render ``[Label](talent:<traitNodeEntryId>)`` markdown links
+  // as Wowhead spell links. WCL ships TraitNodeEntry IDs which collide
+  // with old MoP spell IDs, so we MUST resolve to the underlying spell
+  // ID before linking.
+  const talentSpellIds = structured._talent_spell_ids ?? {};
   const parseMetrics = structured._parse_metrics;
 
   // Wowhead's tooltip script (loaded once at the layout level) only scans
@@ -88,7 +95,15 @@ export function AnalysisCard({ analysis, locale }: Props) {
     <div className="space-y-4">
       <Card>
         <div className="flex flex-wrap items-baseline justify-between gap-3">
-          <h2 className="text-xl font-semibold">{s.headline ?? "—"}</h2>
+          <h2 className="text-xl font-semibold">
+            <ProseWithLinks
+              text={s.headline ?? "—"}
+              locale={locale}
+              nameMap={nameMap}
+              talentSpellIds={talentSpellIds}
+              className=""
+            />
+          </h2>
           <div className="flex flex-wrap items-baseline gap-2">
             {parseMetrics?.parse_percent !== null && parseMetrics?.parse_percent !== undefined ? (
               <span
@@ -169,8 +184,19 @@ export function AnalysisCard({ analysis, locale }: Props) {
                 )}
               </div>
               <h4 className="mt-2 text-base font-semibold text-zinc-100">{f.title}</h4>
-              <p className="mt-1 whitespace-pre-line text-sm text-zinc-200">{f.detail}</p>
-              {f.related_spell_ids?.length || f.related_item_ids?.length ? (
+              <ProseWithLinks
+                text={f.detail}
+                locale={locale}
+                nameMap={nameMap}
+                talentSpellIds={talentSpellIds}
+                className="mt-1 text-sm text-zinc-200"
+              />
+              {/* Chip list only as a fallback for legacy analyses without
+                  inline markdown links in their prose — modern outputs
+                  render the links inline above and the chips become
+                  redundant. */}
+              {!hasInlineRefs(f.detail) &&
+              (f.related_spell_ids?.length || f.related_item_ids?.length) ? (
                 <div className="mt-2 flex flex-wrap gap-2 text-xs">
                   {f.related_spell_ids?.map((id) => (
                     <SpellLink
@@ -196,12 +222,12 @@ export function AnalysisCard({ analysis, locale }: Props) {
       </Card>
 
       <div className="grid gap-4 md:grid-cols-2">
-        {textBlock(t("analyze.rotation"), s.rotation_summary)}
-        {textBlock(t("analyze.cooldowns"), s.cooldown_usage_summary)}
-        {textBlock(t("analyze.stats"), s.stat_recommendations)}
-        {textBlock(t("analyze.talents"), s.talent_recommendations)}
-        {textBlock(t("analyze.gearTrinkets"), s.gear_and_trinket_notes)}
-        {textBlock(t("analyze.comparison"), s.comparison_to_top_logs)}
+        {proseBlock(t("analyze.rotation"), s.rotation_summary, locale, nameMap, talentSpellIds)}
+        {proseBlock(t("analyze.cooldowns"), s.cooldown_usage_summary, locale, nameMap, talentSpellIds)}
+        {proseBlock(t("analyze.stats"), s.stat_recommendations, locale, nameMap, talentSpellIds)}
+        {proseBlock(t("analyze.talents"), s.talent_recommendations, locale, nameMap, talentSpellIds)}
+        {proseBlock(t("analyze.gearTrinkets"), s.gear_and_trinket_notes, locale, nameMap, talentSpellIds)}
+        {proseBlock(t("analyze.comparison"), s.comparison_to_top_logs, locale, nameMap, talentSpellIds)}
       </div>
     </div>
   );
@@ -211,12 +237,23 @@ function severityRank(s: string): number {
   return ({ critical: 0, high: 1, medium: 2, low: 3, info: 4 } as Record<string, number>)[s] ?? 5;
 }
 
-function textBlock(title: string, body: string | undefined) {
+function proseBlock(
+  title: string,
+  body: string | undefined,
+  locale: Locale,
+  nameMap: Record<string, string>,
+  talentSpellIds: Record<string, number>,
+) {
   if (!body) return null;
   return (
     <Card>
       <h3 className="mb-2 text-sm font-semibold uppercase tracking-wide text-zinc-400">{title}</h3>
-      <p className="whitespace-pre-line text-sm text-zinc-200">{body}</p>
+      <ProseWithLinks
+        text={body}
+        locale={locale}
+        nameMap={nameMap}
+        talentSpellIds={talentSpellIds}
+      />
     </Card>
   );
 }