forge/

encounter_html.rs

//! Self-contained spatial encounter debugger generated from representative runtime telemetry.

use std::collections::BTreeMap;

use anyhow::{Context, Result};
use serde::Serialize;
use wowlab_fs::{
    atomic, directory,
    path::{Path, PathBuf},
};
use wowlab_types::{
    proto,
    sim::{SpatialLayerId, SpatialTransform},
};

use crate::encounter_debug::{EncounterDebugReport, TargetDebug, starts_active_at_encounter_start};

const ACTOR_COLORS: [&str; 8] = [
    "#ff6b6b", "#ffd166", "#a78bfa", "#fb923c", "#f472b6", "#84cc16", "#22d3ee", "#e879f9",
];

#[derive(Clone, Debug)]
struct RuntimeActor {
    id: String,
    kind: &'static str,
    label: String,
    color: &'static str,
    active: bool,
    alive: bool,
    transform: SpatialTransform,
}

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct DebuggerData<'a> {
    fixture: &'a str,
    scene: &'a wowlab_types::sim::StaticSpatialScene,
    snapshots: Vec<Snapshot>,
}

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct Snapshot {
    time_ms: u32,
    sequence: u64,
    event: String,
    source: String,
    target: String,
    pull: u32,
    group: Option<u32>,
    actors: Vec<ActorSnapshot>,
}

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct ActorSnapshot {
    id: String,
    kind: &'static str,
    label: String,
    color: &'static str,
    active: bool,
    alive: bool,
    targeted: bool,
    layer: u16,
    x: f64,
    y: f64,
    heading: f64,
}

struct SnapshotMeta {
    time_ms: u32,
    sequence: u64,
    event: String,
    source: String,
    target: Option<u32>,
    pull: u32,
    group: Option<u32>,
}

pub(crate) fn write(report: &EncounterDebugReport) -> Result<PathBuf> {
    let output = PathBuf::from("docs/multi-enemy-encounters")
        .join(format!("{}.html", report.fixture.slug()));

    let data = DebuggerData {
        fixture: report.fixture.slug(),
        scene: &report.definition.spatial_scene,
        snapshots: build_snapshots(report),
    };
    let mut json = serde_json::to_string(&data).context("failed to encode encounter debugger")?;

    json = json.replace("</", "<\\/");

    let mut html = String::with_capacity(HTML_HEAD.len() + json.len() + HTML_RUNTIME.len());

    html.push_str(HTML_HEAD);
    html.push_str(&json);
    html.push_str(HTML_RUNTIME);
    persist(&output, &html)?;

    Ok(output)
}

fn persist(output: &Path, html: &str) -> Result<()> {
    if let Some(parent) = output.parent() {
        directory::ensure(parent)
            .with_context(|| format!("failed to create {}", parent.display()))?;
    }

    atomic::replace(output, html).with_context(|| format!("failed to write {}", output.display()))
}

fn build_snapshots(report: &EncounterDebugReport) -> Vec<Snapshot> {
    let mut actors = initial_actors(report);
    let mut pull = report
        .definition
        .pulls
        .first()
        .map_or(0, |pull| u32::from(pull.id.0));
    let mut target = report
        .definition
        .pulls
        .first()
        .map(|pull| u32::from(pull.preferred_target.0));
    let mut snapshots = vec![snapshot(
        SnapshotMeta {
            time_ms: 0,
            sequence: 0,
            event: "initial authored state".to_string(),
            source: "encounter".to_string(),
            target,
            pull,
            group: None,
        },
        &actors,
    )];

    let mut events = report.encounter_events.clone();

    events.sort_by_key(|event| (event.time_ms, event.sequence));

    for event in events {
        let kind = proto::EncounterEventKind::try_from(event.kind)
            .unwrap_or(proto::EncounterEventKind::Unspecified);

        pull = event.pull_id;

        if matches!(
            kind,
            proto::EncounterEventKind::TargetChange | proto::EncounterEventKind::PullTransition
        ) {
            target = event.target_id;
        }

        apply_event(&event, kind, &mut actors);
        snapshots.push(snapshot(
            SnapshotMeta {
                time_ms: event.time_ms,
                sequence: event.sequence,
                event: event_label(&event, kind),
                source: source_label(report, &event),
                target,
                pull,
                group: event.group_id,
            },
            &actors,
        ));
    }

    snapshots
}

fn initial_actors(report: &EncounterDebugReport) -> BTreeMap<String, RuntimeActor> {
    let mut actors = BTreeMap::new();

    actors.insert(
        "player".to_string(),
        RuntimeActor {
            id: "player".to_string(),
            kind: "player",
            label: "Player".to_string(),
            color: "#38bdf8",
            active: true,
            alive: true,
            transform: report.definition.initial_player_transform,
        },
    );

    for enemy in &report.definition.enemies {
        let id = u32::from(enemy.id.0);

        actors.insert(
            enemy_key(id),
            RuntimeActor {
                id: enemy_key(id),
                kind: "enemy",
                label: target_label(&report.targets, id),
                color: ACTOR_COLORS
                    .get(id as usize % ACTOR_COLORS.len())
                    .copied()
                    .unwrap_or("#ff6b6b"),
                active: starts_active_at_encounter_start(&report.definition, enemy),
                alive: true,
                transform: enemy.initial_transform,
            },
        );
    }

    actors
}

fn apply_event(
    event: &proto::EncounterTimelineEvent,
    kind: proto::EncounterEventKind,
    actors: &mut BTreeMap<String, RuntimeActor>,
) {
    let key = match proto::ActorKind::try_from(event.actor_kind) {
        Ok(proto::ActorKind::Player) => Some("player".to_string()),
        Ok(proto::ActorKind::Enemy) => Some(enemy_key(event.actor_id)),
        _ => None,
    };
    let Some(actor) = key.and_then(|key| actors.get_mut(&key)) else {
        return;
    };

    match kind {
        proto::EncounterEventKind::Spawn => {
            actor.active = true;
            actor.alive = true;
        }
        proto::EncounterEventKind::Death => {
            actor.active = false;
            actor.alive = false;
        }
        proto::EncounterEventKind::Despawn => actor.active = false,
        _ => {}
    }

    if let (Some(layer), Some(x), Some(y), Some(heading)) =
        (event.layer_id, event.x, event.y, event.heading)
    {
        if let Ok(layer) = u16::try_from(layer) {
            actor.transform = SpatialTransform {
                layer: SpatialLayerId(layer),
                position: wowlab_types::sim::Position2 { x, y },
                heading,
            };
        }
    }
}

fn snapshot(meta: SnapshotMeta, actors: &BTreeMap<String, RuntimeActor>) -> Snapshot {
    Snapshot {
        time_ms: meta.time_ms,
        sequence: meta.sequence,
        event: meta.event,
        source: meta.source,
        target: meta.target.map_or_else(|| "none".to_string(), enemy_key),
        pull: meta.pull,
        group: meta.group,
        actors: actors
            .values()
            .map(|actor| ActorSnapshot {
                id: actor.id.clone(),
                kind: actor.kind,
                label: actor.label.clone(),
                color: actor.color,
                active: actor.active,
                alive: actor.alive,
                targeted: meta.target.is_some_and(|id| actor.id == enemy_key(id)),
                layer: actor.transform.layer.0,
                x: actor.transform.position.x,
                y: actor.transform.position.y,
                heading: actor.transform.heading,
            })
            .collect(),
    }
}

fn event_label(event: &proto::EncounterTimelineEvent, kind: proto::EncounterEventKind) -> String {
    let label = match kind {
        proto::EncounterEventKind::Spawn => "spawn",
        proto::EncounterEventKind::Movement => "movement",
        proto::EncounterEventKind::Death => "death",
        proto::EncounterEventKind::Despawn => "despawn",
        proto::EncounterEventKind::TargetChange => "target change",
        proto::EncounterEventKind::PullTransition => "pull transition",
        proto::EncounterEventKind::Unspecified => "unspecified",
    };

    match (event.x, event.y) {
        (Some(x), Some(y)) => format!("{label} → ({x:.2}, {y:.2})"),
        _ => label.to_string(),
    }
}

fn source_label(report: &EncounterDebugReport, event: &proto::EncounterTimelineEvent) -> String {
    match proto::ActorKind::try_from(event.actor_kind) {
        Ok(proto::ActorKind::Player) => "Player".to_string(),
        Ok(proto::ActorKind::Enemy) => target_label(&report.targets, event.actor_id),
        Ok(proto::ActorKind::Pet) => format!("Pet {}", event.actor_id),
        Ok(proto::ActorKind::Unspecified) | Err(_) => "Encounter".to_string(),
    }
}

fn target_label(targets: &[TargetDebug], id: u32) -> String {
    let target = targets.iter().find(|target| target.id == id);

    target.map_or_else(|| format!("Enemy {id}"), |target| target.label.clone())
}

fn enemy_key(id: u32) -> String {
    format!("enemy-{id}")
}

const HTML_HEAD: &str = r#"<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Forge spatial encounter debugger</title>
<style>
:root{color-scheme:dark;font-family:Inter,ui-sans-serif,system-ui,sans-serif;background:#070b14;color:#e5edf8}
*{box-sizing:border-box}body{margin:0;min-height:100vh;background:radial-gradient(circle at top,#14213d 0,#070b14 55%)}
header{padding:20px 24px 12px;display:flex;align-items:end;justify-content:space-between;gap:16px}h1{font-size:20px;margin:0}#fixture{color:#7dd3fc}
.subtitle{color:#8da2bd;font-size:13px;margin-top:5px}.layout{display:grid;grid-template-columns:minmax(0,1fr) 330px;gap:14px;padding:0 20px 20px;height:calc(100vh - 86px)}
.panel{background:rgba(10,17,31,.92);border:1px solid #22314a;border-radius:12px;box-shadow:0 18px 60px #0006;overflow:hidden}
.main{display:grid;grid-template-rows:auto minmax(360px,1fr) auto}.controls{display:flex;align-items:center;gap:8px;padding:12px;border-bottom:1px solid #22314a;flex-wrap:wrap}
button,select{border:1px solid #314562;background:#14213a;color:#e5edf8;border-radius:7px;padding:7px 11px;cursor:pointer}button:hover{background:#1d3152}button:disabled{opacity:.4;cursor:default}
input[type=range]{flex:1;min-width:160px;accent-color:#38bdf8}.step{font-variant-numeric:tabular-nums;color:#9fb0c8;font-size:12px;min-width:74px;text-align:right}
#arena{width:100%;height:100%;min-height:360px;background:#09101d}.info{padding:12px 14px;border-top:1px solid #22314a;display:grid;grid-template-columns:repeat(5,minmax(0,1fr));gap:10px}
.datum{min-width:0}.datum b{display:block;text-transform:uppercase;letter-spacing:.08em;font-size:10px;color:#7186a4;margin-bottom:3px}.datum span{display:block;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;font-size:13px}
.side{display:grid;grid-template-rows:auto 1fr}.side h2{font-size:13px;text-transform:uppercase;letter-spacing:.08em;color:#91a5c0;margin:0;padding:14px;border-bottom:1px solid #22314a}
#events{overflow:auto;margin:0;padding:7px;list-style:none}.event{display:grid;grid-template-columns:58px 1fr;gap:8px;padding:9px;border-radius:7px;cursor:pointer;border:1px solid transparent}.event:hover{background:#111e34}.event.current{background:#142c48;border-color:#27628b}.event-time{font:11px ui-monospace,monospace;color:#7dd3fc}.event-name{font-size:12px}.event-source{font-size:11px;color:#7f93af;margin-top:3px}
.legend{position:absolute}.grid{stroke:#1d2b40;stroke-width:1}.axis{stroke:#3b506d;stroke-width:1.3}.obstacle{fill:#33415588;stroke:#94a3b8;stroke-width:2}.path-past{fill:none;stroke-width:3}.path-future{fill:none;stroke-width:2;stroke-dasharray:6 7;opacity:.25}.label{font:12px ui-sans-serif,system-ui;fill:#e8eef8;paint-order:stroke;stroke:#070b14;stroke-width:4;stroke-linejoin:round}.coord{font:10px ui-monospace,monospace;fill:#7186a4}.target-ring{fill:none;stroke:#fff;stroke-width:2;stroke-dasharray:4 3}.inactive{opacity:.35}.dead{opacity:.28}
@media(max-width:850px){.layout{grid-template-columns:1fr;height:auto}.main{min-height:620px}.side{height:360px}.info{grid-template-columns:repeat(2,1fr)}}
</style>
</head>
<body>
<header><div><h1>Forge spatial encounter debugger · <span id="fixture"></span></h1><div class="subtitle">Recorded encounter states from representative runtime telemetry</div></div></header>
<div class="layout">
<section class="panel main">
<div class="controls"><button id="prev">← Previous</button><button id="play">Play</button><button id="next">Next →</button><input id="slider" type="range" min="0" value="0"><span class="step" id="step"></span><select id="layer"></select></div>
<svg id="arena" role="img" aria-label="Spatial encounter state"></svg>
<div class="info"><div class="datum"><b>Time</b><span id="time"></span></div><div class="datum"><b>Event</b><span id="event"></span></div><div class="datum"><b>Source</b><span id="source"></span></div><div class="datum"><b>Target</b><span id="target"></span></div><div class="datum"><b>Pull / Group</b><span id="pull"></span></div></div>
</section>
<aside class="panel side"><h2>Runtime state steps</h2><ol id="events"></ol></aside>
</div>
<script>const DATA="#;

const HTML_RUNTIME: &str = r##";
const svg=document.querySelector("#arena"),NS=svg.namespaceURI,slider=document.querySelector("#slider"),layerSelect=document.querySelector("#layer");let index=0,timer=null;
document.querySelector("#fixture").textContent=DATA.fixture;slider.max=String(DATA.snapshots.length-1);
const layers=DATA.scene.layers.map(x=>x.id);for(const layer of DATA.scene.layers){const o=document.createElement("option");o.value=layer.id;o.textContent=`Layer ${layer.id} · ${layer.slug}`;layerSelect.append(o)}
const el=(name,attrs={})=>{const n=document.createElementNS(NS,name);for(const[k,v]of Object.entries(attrs))n.setAttribute(k,String(v));return n};
function allPoints(layer){const p=[];for(const s of DATA.snapshots)for(const a of s.actors)if(a.layer===layer)p.push([a.x,a.y]);for(const o of DATA.scene.obstacles){if(o.layer!==layer)continue;if(o.kind==="segment")p.push([o.start.x,o.start.y],[o.end.x,o.end.y]);else{for(const q of o.exterior)p.push([q.x,q.y]);for(const h of o.holes)for(const q of h)p.push([q.x,q.y])}}return p}
function bounds(layer){const p=allPoints(layer);let xs=p.map(q=>q[0]),ys=p.map(q=>q[1]);if(!p.length)xs=ys=[0];let minX=Math.min(...xs),maxX=Math.max(...xs),minY=Math.min(...ys),maxY=Math.max(...ys);if(maxX-minX<10){const m=(minX+maxX)/2;minX=m-5;maxX=m+5}if(maxY-minY<10){const m=(minY+maxY)/2;minY=m-5;maxY=m+5}const pad=Math.max(maxX-minX,maxY-minY)*.12;return[minX-pad,maxX+pad,minY-pad,maxY+pad]}
function render(){const s=DATA.snapshots[index],layer=Number(layerSelect.value),[minX,maxX,minY,maxY]=bounds(layer),W=1000,H=620,pad=55,iw=W-pad*2,ih=H-pad*2,scale=Math.min(iw/(maxX-minX),ih/(maxY-minY)),mx=x=>pad+(x-minX)*scale,my=y=>H-pad-(y-minY)*scale;svg.setAttribute("viewBox",`0 0 ${W} ${H}`);svg.replaceChildren();
 const defs=el("defs"),marker=el("marker",{id:"arrow",viewBox:"0 0 10 10",refX:8,refY:5,markerWidth:5,markerHeight:5,orient:"auto-start-reverse"});marker.append(el("path",{d:"M 0 0 L 10 5 L 0 10 z",fill:"context-stroke"}));defs.append(marker);svg.append(defs);
 const span=Math.max(maxX-minX,maxY-minY),step=span<=12?1:span<=30?2:5;for(let x=Math.ceil(minX/step)*step;x<=maxX;x+=step){svg.append(el("line",{x1:mx(x),y1:pad,x2:mx(x),y2:H-pad,class:x===0?"axis":"grid"}));const t=el("text",{x:mx(x)+3,y:H-pad+16,class:"coord"});t.textContent=x;svg.append(t)}for(let y=Math.ceil(minY/step)*step;y<=maxY;y+=step){svg.append(el("line",{x1:pad,y1:my(y),x2:W-pad,y2:my(y),class:y===0?"axis":"grid"}));const t=el("text",{x:pad-8,y:my(y)+3,class:"coord","text-anchor":"end"});t.textContent=y;svg.append(t)}
 for(const o of DATA.scene.obstacles){if(o.layer!==layer)continue;if(o.kind==="segment")svg.append(el("line",{x1:mx(o.start.x),y1:my(o.start.y),x2:mx(o.end.x),y2:my(o.end.y),class:"obstacle"}));else{const d=o.exterior.map((p,i)=>`${i?"L":"M"} ${mx(p.x)} ${my(p.y)}`).join(" ")+" Z";svg.append(el("path",{d,class:"obstacle","fill-rule":"evenodd"}))}}
 const current=s.actors.filter(a=>a.layer===layer);for(const actor of current){const history=DATA.snapshots.map(x=>x.actors.find(a=>a.id===actor.id)).filter(a=>a&&a.layer===layer),past=history.slice(0,index+1),future=history.slice(index);const points=a=>a.map(p=>`${mx(p.x)},${my(p.y)}`).join(" ");if(future.length>1)svg.append(el("polyline",{points:points(future),stroke:actor.color,class:"path-future"}));if(past.length>1)svg.append(el("polyline",{points:points(past),stroke:actor.color,class:"path-past","marker-end":"url(#arrow)"}));}
 for(const actor of current){const x=mx(actor.x),y=my(actor.y),g=el("g",{class:!actor.alive?"dead":!actor.active?"inactive":""});if(actor.targeted)g.append(el("circle",{cx:x,cy:y,r:20,class:"target-ring"}));if(actor.kind==="player")g.append(el("path",{d:`M ${x} ${y-12} L ${x+11} ${y} L ${x} ${y+12} L ${x-11} ${y} Z`,fill:actor.color,stroke:"#fff","stroke-width":1.5}));else g.append(el("circle",{cx:x,cy:y,r:11,fill:actor.color,stroke:"#fff","stroke-width":1.5}));g.append(el("line",{x1:x,y1:y,x2:x+Math.cos(actor.heading)*24,y2:y-Math.sin(actor.heading)*24,stroke:actor.color,"stroke-width":3}));if(!actor.alive){g.append(el("line",{x1:x-12,y1:y-12,x2:x+12,y2:y+12,stroke:"#fff","stroke-width":3}));g.append(el("line",{x1:x+12,y1:y-12,x2:x-12,y2:y+12,stroke:"#fff","stroke-width":3}))}const label=el("text",{x:x+16,y:y-15,class:"label"});label.textContent=`${actor.label}${actor.active?"":" · inactive"}`;g.append(label);const coord=el("text",{x:x+16,y:y+2,class:"coord"});coord.textContent=`(${actor.x.toFixed(2)}, ${actor.y.toFixed(2)}) h=${actor.heading.toFixed(2)}`;g.append(coord);svg.append(g)}
 document.querySelector("#time").textContent=`${(s.timeMs/1000).toFixed(3)}s · seq ${s.sequence}`;document.querySelector("#event").textContent=s.event;document.querySelector("#source").textContent=s.source;document.querySelector("#target").textContent=s.target;document.querySelector("#pull").textContent=`${s.pull} / ${s.group??"—"}`;document.querySelector("#step").textContent=`${index+1} / ${DATA.snapshots.length}`;slider.value=String(index);document.querySelector("#prev").disabled=index===0;document.querySelector("#next").disabled=index===DATA.snapshots.length-1;document.querySelectorAll(".event").forEach((n,i)=>n.classList.toggle("current",i===index));document.querySelector(".event.current")?.scrollIntoView({block:"nearest"})}
function go(i){index=Math.max(0,Math.min(DATA.snapshots.length-1,i));render()}function stop(){if(timer){clearInterval(timer);timer=null;document.querySelector("#play").textContent="Play"}}
for(const[sIndex,s]of DATA.snapshots.entries()){const li=document.createElement("li");li.className="event";li.innerHTML=`<div class="event-time">${(s.timeMs/1000).toFixed(3)}s</div><div><div class="event-name"></div><div class="event-source"></div></div>`;li.querySelector(".event-name").textContent=s.event;li.querySelector(".event-source").textContent=`${s.source} · pull ${s.pull}`;li.onclick=()=>{stop();go(sIndex)};document.querySelector("#events").append(li)}
document.querySelector("#prev").onclick=()=>{stop();go(index-1)};document.querySelector("#next").onclick=()=>{stop();go(index+1)};document.querySelector("#play").onclick=()=>{if(timer){stop();return}document.querySelector("#play").textContent="Pause";if(index===DATA.snapshots.length-1)go(0);timer=setInterval(()=>{if(index===DATA.snapshots.length-1){stop();return}go(index+1)},700)};slider.oninput=e=>{stop();go(Number(e.target.value))};layerSelect.onchange=render;document.onkeydown=e=>{if(e.key==="ArrowLeft"){stop();go(index-1)}if(e.key==="ArrowRight"){stop();go(index+1)}};render();
</script></body></html>
"##;

#[cfg(test)]
mod tests {
    use googletest::prelude::*;
    use wowlab_fs::{directory, file, temporary::Directory};

    use super::persist;

    #[gtest]
    fn debugger_persistence_creates_parent_and_atomically_replaces_exact_html() -> Result<()> {
        let temporary = Directory::new().or_fail()?;
        let output = temporary.path().join("nested/debugger.html");

        persist(&output, "<html>first</html>").or_fail()?;
        persist(&output, "<html>second</html>").or_fail()?;

        verify_that!(
            file::read_text(&output).or_fail()?,
            eq("<html>second</html>")
        )?;

        verify_that!(
            directory::entries(output.parent().or_fail()?).or_fail()?,
            len(eq(1))
        )
    }
}