Debugger.cpp

浏览该文件的文档.

#include "devtools/Debugger.hpp"
 
#include "devtools/RenderVision.hpp"
 
#include "common/ScriptError.h"
 
#include <simplesquirrel/simplesquirrel.hpp>
#include <squirrel.h>
 
#include <algorithm>
#include <cctype>
#include <chrono>
#include <cstring>
#include <fstream>
#include <thread>
#include <utility>
 
namespace eve::dev {
namespace {
 
std::string truthyString(bool v) { return v ? "true" : "false"; }
 
std::string describeSqValue(HSQUIRRELVM vm, SQInteger idx) {
    const SQObjectType t = sq_gettype(vm, idx);
    switch (t) {
        case OT_NULL:
            return "null";
        case OT_INTEGER: {
            SQInteger v = 0;
            sq_getinteger(vm, idx, &v);
            return std::to_string(static_cast<long long>(v));
        }
        case OT_FLOAT: {
            SQFloat v = 0;
            sq_getfloat(vm, idx, &v);
            return std::to_string(static_cast<double>(v));
        }
        case OT_BOOL: {
            SQBool v = SQFalse;
            sq_getbool(vm, idx, &v);
            return v ? "true" : "false";
        }
        case OT_STRING: {
            const SQChar* s = nullptr;
            sq_getstring(vm, idx, &s);
            return s ? std::string("\"") + s + "\"" : "\"\"";
        }
        case OT_TABLE:
            return "<table>";
        case OT_ARRAY:
            return "<array>";
        case OT_USERDATA:
            return "<userdata>";
        case OT_CLOSURE:
            return "<closure>";
        case OT_NATIVECLOSURE:
            return "<native>";
        case OT_INSTANCE:
            return "<instance>";
        case OT_CLASS:
            return "<class>";
        case OT_THREAD:
            return "<thread>";
        default:
            return "<other>";
    }
}
 
std::string typeName(HSQUIRRELVM vm, SQInteger idx) {
    switch (sq_gettype(vm, idx)) {
        case OT_NULL:
            return "null";
        case OT_INTEGER:
            return "integer";
        case OT_FLOAT:
            return "float";
        case OT_BOOL:
            return "bool";
        case OT_STRING:
            return "string";
        case OT_TABLE:
            return "table";
        case OT_ARRAY:
            return "array";
        case OT_USERDATA:
            return "userdata";
        case OT_CLOSURE:
            return "closure";
        case OT_NATIVECLOSURE:
            return "native";
        case OT_INSTANCE:
            return "instance";
        case OT_CLASS:
            return "class";
        case OT_THREAD:
            return "thread";
        default:
            return "other";
    }
}
 
std::string typeName(HSQUIRRELVM vm, SQInteger idx);
 
VariableInfo describeAt(HSQUIRRELVM vm, SQInteger idx) {
    VariableInfo info;
    const SQObjectType t = sq_gettype(vm, idx);
    info.type = typeName(vm, idx);
    switch (t) {
        case OT_NULL:
            info.value = "null";
            break;
        case OT_INTEGER: {
            SQInteger v = 0;
            sq_getinteger(vm, idx, &v);
            info.value = std::to_string(static_cast<long long>(v));
            break;
        }
        case OT_FLOAT: {
            SQFloat v = 0;
            sq_getfloat(vm, idx, &v);
            info.value = std::to_string(static_cast<double>(v));
            break;
        }
        case OT_BOOL: {
            SQBool v = SQFalse;
            sq_getbool(vm, idx, &v);
            info.value = v ? "true" : "false";
            break;
        }
        case OT_STRING: {
            const SQChar* s = nullptr;
            sq_getstring(vm, idx, &s);
            info.value = std::string("\"") + (s ? s : "") + "\"";
            break;
        }
        case OT_TABLE:
        case OT_ARRAY: {
            const SQInteger n = sq_getsize(vm, idx);
            info.value = std::string(t == OT_TABLE ? "<table (" : "<array (") +
                         std::to_string(static_cast<long long>(n)) + ")>";
            info.expandable = true;
            info.childCount = static_cast<int>(n);
            break;
        }
        case OT_CLASS:
            info.value = "<class>";
            info.expandable = true;
            break;
        case OT_INSTANCE:
            info.value = "<instance>";
            info.expandable = true;
            break;
        case OT_USERDATA:
            info.value = "<userdata>";
            break;
        case OT_CLOSURE:
            info.value = "<closure>";
            info.expandable = true;  // expandable: free variables
            break;
        case OT_NATIVECLOSURE:
            info.value = "<native>";
            break;
        case OT_THREAD:
            info.value = "<thread>";
            break;
        case OT_GENERATOR:
            info.value = "<generator>";
            break;
        default:
            info.value = "<other>";
            break;
    }
    return info;
}
 
std::vector<VariableInfo> enumerateAt(HSQUIRRELVM vm, SQInteger idx) {
    std::vector<VariableInfo> out;
    const SQObjectType t = sq_gettype(vm, idx);
    const SQInteger top  = sq_gettop(vm);
    const int absIdx     = idx < 0 ? static_cast<int>(top) + static_cast<int>(idx) + 1 : static_cast<int>(idx);
 
    if (t == OT_ARRAY) {
        const SQInteger size = sq_getsize(vm, idx);
        for (SQInteger i = 0; i < size; ++i) {
            const SQInteger before = sq_gettop(vm);
            sq_pushinteger(vm, i);
            if (SQ_FAILED(sq_get(vm, absIdx))) {
                sq_settop(vm, before);
                continue;
            }
            VariableInfo info = describeAt(vm, -1);
            info.name         = std::to_string(static_cast<long long>(i));
            sq_settop(vm, before);
            out.push_back(std::move(info));
        }
        return out;
    }
 
    if (t == OT_TABLE || t == OT_CLASS) {
        sq_pushinteger(vm, 0);  // iterator position
        while (SQ_SUCCEEDED(sq_next(vm, absIdx))) {
            VariableInfo info = describeAt(vm, -1);
            switch (sq_gettype(vm, -2)) {
                case OT_STRING: {
                    const SQChar* s = nullptr;
                    sq_getstring(vm, -2, &s);
                    info.name = s ? s : "";
                    break;
                }
                case OT_INTEGER: {
                    SQInteger k = 0;
                    sq_getinteger(vm, -2, &k);
                    info.name = std::to_string(static_cast<long long>(k));
                    break;
                }
                case OT_FLOAT: {
                    SQFloat k = 0;
                    sq_getfloat(vm, -2, &k);
                    info.name = std::to_string(static_cast<double>(k));
                    break;
                }
                case OT_BOOL: {
                    SQBool k = SQFalse;
                    sq_getbool(vm, -2, &k);
                    info.name = truthyString(k != SQFalse);
                    break;
                }
                default:
                    info.name = "<key>";
                    break;
            }
            sq_pop(vm, 2);
            out.push_back(std::move(info));
        }
        sq_settop(vm, top);
        return out;
    }
 
    if (t == OT_INSTANCE) {
        sq_getclass(vm, absIdx);  // class at top
        const int clsAbs = static_cast<int>(sq_gettop(vm));
        sq_pushinteger(vm, 0);
        while (SQ_SUCCEEDED(sq_next(vm, clsAbs))) {
            const SQChar* s = nullptr;
            if (sq_gettype(vm, -2) == OT_STRING) sq_getstring(vm, -2, &s);
            const std::string name = s ? s : "";
            const SQInteger before = sq_gettop(vm);
            sq_push(vm, absIdx);  // instance
            sq_pushstring(vm, name.c_str(), -1);
            VariableInfo info;
            if (SQ_SUCCEEDED(sq_get(vm, -2))) {
                info = describeAt(vm, -1);
            } else {
                info.type  = "error";
                info.value = "not found";
            }
            info.name = name;
            sq_settop(vm, before);
            sq_pop(vm, 2);  // drop key + value; keep iterator position
            out.push_back(std::move(info));
        }
        sq_settop(vm, top);
        return out;
    }
 
    if (t == OT_CLOSURE) {
        SQInteger nparams = 0, nfree = 0;
        if (SQ_SUCCEEDED(sq_getclosureinfo(vm, idx, &nparams, &nfree))) {
            for (SQUnsignedInteger i = 0; i < static_cast<SQUnsignedInteger>(nfree); ++i) {
                const SQChar* n = sq_getfreevariable(vm, absIdx, i);
                VariableInfo info = describeAt(vm, -1);
                info.name = n ? n : ("upvalue_" + std::to_string(static_cast<long long>(i)));
                sq_poptop(vm);
                out.push_back(std::move(info));
            }
        }
        return out;
    }
    return out;
}
 
bool valueTruthy(const VariableInfo& info) {
    if (info.type == "error") return false;
    if (info.type == "null") return false;
    if (info.type == "bool") return info.value == "true";
    if (info.type == "integer") {
        try {
            return std::stoll(info.value) != 0;
        } catch (...) {
            return true;
        }
    }
    if (info.type == "float") {
        try {
            return std::stod(info.value) != 0.0;
        } catch (...) {
            return true;
        }
    }
    return true;
}
 
bool isGenericFuncName(const char* name) {
    if (!name || !name[0] || std::strcmp(name, "?") == 0) return true;
    return std::strcmp(name, "unknown") == 0 || std::strcmp(name, "NATIVE") == 0 ||
           std::strcmp(name, "anonymous") == 0;
}
 
bool isGenericFuncName(const std::string& name) { return isGenericFuncName(name.c_str()); }
 
std::string nthLine(const std::string& text, int line) {
    if (line <= 0) return {};
    int n = 1;
    size_t start = 0;
    while (n < line) {
        const size_t nl = text.find('\n', start);
        if (nl == std::string::npos) return {};
        start = nl + 1;
        ++n;
    }
    size_t end = text.find('\n', start);
    if (end == std::string::npos) end = text.size();
    std::string out = text.substr(start, end - start);
    if (!out.empty() && out.back() == '\r') out.pop_back();
    return out;
}
 
std::string inferNameFromDefinitionLine(std::string line) {
    while (!line.empty() && std::isspace(static_cast<unsigned char>(line.front()))) line.erase(line.begin());
    if (line.rfind("//", 0) == 0) return {};
    const auto isIdent = [](unsigned char c) { return std::isalnum(c) || c == '_' || c == '.'; };
    if (line.rfind("function ", 0) == 0) {
        size_t i = 9;
        while (i < line.size() && std::isspace(static_cast<unsigned char>(line[i]))) ++i;
        const size_t start = i;
        while (i < line.size() && isIdent(static_cast<unsigned char>(line[i]))) ++i;
        if (i > start) return line.substr(start, i - start);
        return {};
    }
    size_t i = 0;
    if (i < line.size() && (std::isalpha(static_cast<unsigned char>(line[i])) || line[i] == '_')) {
        const size_t start = i;
        while (i < line.size() && isIdent(static_cast<unsigned char>(line[i]))) ++i;
        const std::string ident = line.substr(start, i - start);
        while (i < line.size() && std::isspace(static_cast<unsigned char>(line[i]))) ++i;
        bool assign = false;
        if (i + 1 < line.size() && line[i] == '<' && line[i + 1] == '-') {
            i += 2;
            assign = true;
        } else if (i < line.size() && line[i] == '=') {
            ++i;
            assign = true;
        }
        if (!assign) return {};
        while (i < line.size() && std::isspace(static_cast<unsigned char>(line[i]))) ++i;
        if (line.compare(i, 6, "async ") == 0) {
            i += 6;
            while (i < line.size() && std::isspace(static_cast<unsigned char>(line[i]))) ++i;
        }
        if (line.compare(i, 8, "function") == 0) return ident;
    }
    return {};
}
 
std::string readDefinitionLine(const std::string& source, int line) {
    if (source.empty() || line <= 0) return {};
    std::ifstream in(source);
    if (!in) {
        const auto slash = source.find_last_of("/\\");
        if (slash != std::string::npos) in.open(source.substr(slash + 1));
    }
    if (!in) return {};
    std::string text;
    for (int n = 1; n <= line && std::getline(in, text); ++n) {
        if (n == line) {
            if (!text.empty() && text.back() == '\r') text.pop_back();
            return text;
        }
    }
    return {};
}
 
}  // namespace
 
Debugger& Debugger::instance() {
    static Debugger inst;
    return inst;
}
 
std::string Debugger::normalizeSource(std::string source) {
    if (source.empty()) return source;
    // Strip common URI prefixes VS Code may send.
    if (source.rfind("file://", 0) == 0) {
        source = source.substr(7);
        // file://localhost/Users/... → /Users/...
        if (source.rfind("localhost/", 0) == 0) source = source.substr(9);
    }
    // Unify separators.
    for (char& c : source) {
        if (c == '\\') c = '/';
    }
    // Drop leading ./
    while (source.size() >= 2 && source[0] == '.' && source[1] == '/') source = source.substr(2);
    return source;
}
 
std::string Debugger::sourceBasename(const std::string& source) {
    const std::string norm = normalizeSource(source);
    const auto slash       = norm.find_last_of('/');
    return (slash == std::string::npos) ? norm : norm.substr(slash + 1);
}
 
bool Debugger::sourcesMatch(const std::string& a, const std::string& b) {
    const std::string na = normalizeSource(a);
    const std::string nb = normalizeSource(b);
    if (na.empty() || nb.empty()) return false;
    if (na == nb) return true;
 
    const std::string& longer  = na.size() >= nb.size() ? na : nb;
    const std::string& shorter = na.size() >= nb.size() ? nb : na;
    if (longer.size() > shorter.size() &&
        longer.compare(longer.size() - shorter.size(), shorter.size(), shorter) == 0) {
        const auto idx = longer.size() - shorter.size();
        if (idx == 0 || longer[idx - 1] == '/') return true;
    }
 
    // Bare filenames (no slash) still match any path with the same basename so
    // Squirrel's `main.nut` can hit a VS Code absolute breakpoint. Two paths
    // that both include a directory must not match on basename alone.
    const bool aHasDir = na.find('/') != std::string::npos;
    const bool bHasDir = nb.find('/') != std::string::npos;
    if (aHasDir && bHasDir) return false;
    const std::string ba = sourceBasename(na);
    const std::string bb = sourceBasename(nb);
    return !ba.empty() && ba == bb;
}
 
void Debugger::attach(HSQUIRRELVM vm) {
    std::lock_guard<std::mutex> lock(mu_);
    vm_   = vm;
    mode_ = RunMode::Running;
    reason_ = PauseReason::None;
    pauseLoc_ = {};
    stepFrameArmed_ = false;
    ownGraph_.clear();
    virtualSources_.clear();
}
 
void Debugger::detach() {
    std::lock_guard<std::mutex> lock(mu_);
    vm_ = nullptr;
    mode_ = RunMode::Running;
    reason_ = PauseReason::None;
    stepFrameArmed_ = false;
    callGraph_ = nullptr;
    ownGraph_.clear();
    virtualSources_.clear();
}
 
void Debugger::setCallGraph(CallGraph* graph) {
    std::lock_guard<std::mutex> lock(mu_);
    callGraph_ = graph;
}
 
void Debugger::setVirtualSource(std::string source, std::string text) {
    std::lock_guard<std::mutex> lock(mu_);
    virtualSources_[normalizeSource(std::move(source))] = std::move(text);
}
 
CallGraph& Debugger::activeGraph() {
    return callGraph_ ? *callGraph_ : ownGraph_;
}
 
const CallGraph& Debugger::activeGraph() const {
    return callGraph_ ? *callGraph_ : ownGraph_;
}
 
std::string Debugger::lineAt(const std::string& source, int line) const {
    if (line <= 0) return {};
    {
        std::lock_guard<std::mutex> lock(mu_);
        for (const auto& [name, text] : virtualSources_) {
            if (sourcesMatch(name, source)) return nthLine(text, line);
        }
    }
    return readDefinitionLine(source, line);
}
 
std::string Debugger::resolveCallName(const SourceLoc& loc) const {
    if (!isGenericFuncName(loc.function)) return loc.function;
    // Only the hook's own line: loc.line-1 is often the *caller's* definition
    // when Squirrel reports the call site.
    const std::string name = inferNameFromDefinitionLine(lineAt(loc.source, loc.line));
    if (!name.empty()) return name;
    return loc.function.empty() ? "unknown" : loc.function;
}
 
std::string Debugger::onCall(SourceLoc loc) {
    const std::string name = resolveCallName(loc);
    loc.function = name;
    activeGraph().onCall(loc, name);
    return name;
}
 
void Debugger::onReturn(const SourceLoc& loc) {
    activeGraph().onReturn(loc, loc.function);
}
 
std::string Debugger::nameFromPrototype(int level, const char* rawName, const SourceLoc& loc) const {
    if (!isGenericFuncName(rawName)) return rawName;
    if (vm_) {
        SQFunctionInfo fi;
        std::memset(&fi, 0, sizeof(fi));
        if (SQ_SUCCEEDED(sq_getfunctioninfo(vm_, level, &fi))) {
            if (!isGenericFuncName(fi.name)) return fi.name;
            const char* src = (fi.source && fi.source[0]) ? fi.source : loc.source.c_str();
            const int defLine = fi.line > 0 ? static_cast<int>(fi.line) : loc.line;
            const std::string inferred = inferNameFromDefinitionLine(lineAt(src, defLine));
            if (!inferred.empty()) return inferred;
        }
    }
    const std::string fromPc = inferNameFromDefinitionLine(lineAt(loc.source, loc.line));
    if (!fromPc.empty()) return fromPc;
    for (int ln = loc.line - 1; ln > 0 && ln >= loc.line - 32; --ln) {
        const std::string inferred = inferNameFromDefinitionLine(lineAt(loc.source, ln));
        if (!inferred.empty()) return inferred;
    }
    return "unknown";
}
 
void Debugger::applyCallGraphNames(std::vector<StackFrameInfo>& frames) const {
    std::vector<std::string> cgInner;
    const auto stack = activeGraph().currentStack();
    for (auto it = stack.rbegin(); it != stack.rend(); ++it) {
        if (it->loc.source == "NATIVE") continue;
        cgInner.push_back(it->loc.function);
    }
    // Align from the outer end so an extra/missing inner CallGraph frame cannot
    // relabel the current SQ frame as its caller.
    const int delta = static_cast<int>(frames.size()) - static_cast<int>(cgInner.size());
    for (size_t i = 0; i < frames.size(); ++i) {
        if (!isGenericFuncName(frames[i].name)) continue;
        const int cgi = static_cast<int>(i) - delta;
        if (cgi < 0 || cgi >= static_cast<int>(cgInner.size())) continue;
        if (isGenericFuncName(cgInner[static_cast<size_t>(cgi)])) continue;
        frames[i].name         = cgInner[static_cast<size_t>(cgi)];
        frames[i].loc.function = frames[i].name;
    }
}
 
void Debugger::pause(PauseReason reason) {
    // PauseKey is frame-level: drop any stale script site so smart step()
    // becomes stepFrame. Other reasons keep the last script location unless
    // the caller uses pauseAt.
    if (reason == PauseReason::PauseKey) {
        pauseAt(reason, {});
        return;
    }
    pauseAt(reason, pauseLoc_);
}
 
void Debugger::pauseAt(PauseReason reason, SourceLoc loc) {
    reason_.store(reason);
    mode_.store(RunMode::Paused);
    remainingHostFrames_ = 0;
    pauseLoc_ = std::move(loc);
}
 
void Debugger::resume() {
    reason_.store(PauseReason::None);
    mode_.store(RunMode::Running);
    stepFrameArmed_  = false;
    remainingHostFrames_ = 0;
    stepStartDepth_  = 0;
    stepSkipLoc_     = {};
    pauseLoc_        = {};
}
 
void Debugger::stepFrame() {
    reason_.store(PauseReason::Step);
    mode_.store(RunMode::StepFrame);
    stepFrameArmed_ = true;
}
 
void Debugger::stepFrames(int count) {
    remainingHostFrames_ = count < 1 ? 1 : count;
    stepFrame();
}
 
int Debugger::scriptStackDepth() const {
    HSQUIRRELVM vm = vm_;
    if (!vm) return 0;
    int depth = 0;
    for (int level = 0;; ++level) {
        SQStackInfos si;
        if (SQ_FAILED(sq_stackinfos(vm, level, &si))) break;
        ++depth;
    }
    return depth;
}
 
void Debugger::beginScriptStep(RunMode stepMode) {
    reason_.store(PauseReason::Step);
    stepStartDepth_ = scriptStackDepth();
    // Squirrel can emit several _OP_LINE for one source line; skip the line we
    // are currently paused on until the location changes.
    stepSkipLoc_ = pauseLoc_;
    // Not currently inside a script frame (frame-level pause): stop on the
    // first line we see — treat like stepInto with an open depth gate.
    if (stepStartDepth_ <= 0) {
        mode_.store(RunMode::StepInto);
        stepStartDepth_ = 0;
        return;
    }
    mode_.store(stepMode);
}
 
void Debugger::stepInto() { beginScriptStep(RunMode::StepInto); }
 
void Debugger::stepOver() { beginScriptStep(RunMode::StepOver); }
 
void Debugger::stepOut() {
    // No caller to return to → just step over the current line.
    if (scriptStackDepth() <= 1) {
        beginScriptStep(RunMode::StepOver);
        return;
    }
    beginScriptStep(RunMode::StepOut);
}
 
void Debugger::step() {
    // Prefer script step-over when we have a script pause site; else one frame.
    const PauseReason r = reason_.load();
    if (!pauseLoc_.empty() &&
        (r == PauseReason::Breakpoint || r == PauseReason::Step ||
         r == PauseReason::Exception || r == PauseReason::Snapshot)) {
        stepOver();
        return;
    }
    stepFrame();
}
 
bool Debugger::shouldRunUpdate() {
    const RunMode m = mode_.load();
    if (m == RunMode::Running) return true;
    if (m == RunMode::StepFrame) return true;
    // Allow the game loop to enter eve_update so script steps can begin after
    // a frame-level pause.
    if (m == RunMode::StepInto || m == RunMode::StepOver || m == RunMode::StepOut) return true;
    return false;  // Paused
}
 
void Debugger::notifyFrameDone() {
    if (mode_.load() == RunMode::StepFrame || stepFrameArmed_) {
        stepFrameArmed_ = false;
        if (remainingHostFrames_ > 1) {
            --remainingHostFrames_;
            stepFrame();
            return;
        }
        remainingHostFrames_ = 0;
        reason_.store(PauseReason::Step);
        mode_.store(RunMode::Paused);
        // Frame step finished outside the line hook — next smart step is frame.
        pauseLoc_ = {};
    }
}
 
bool Debugger::matchBreakpoint(const std::string& source, int line) const {
    if (!bpsEnabled_.load()) return false;
    for (const auto& bp : bps_) {
        if (!bp.enabled || bp.line != line) continue;
        if (sourcesMatch(source, bp.source)) return true;
    }
    return false;
}
 
bool Debugger::matchBreakpointAny(const std::string& source, int line) const {
    for (const auto& bp : bps_) {
        if (bp.line != line) continue;
        if (sourcesMatch(source, bp.source)) return true;
    }
    return false;
}
 
bool Debugger::conditionHolds(const Breakpoint& bp) const {
    if (bp.condition.empty()) return true;
    // Failed / unreadable conditions stop (safer than silently never stopping).
    const VariableInfo r = evaluate(bp.condition, 0);
    if (r.type == "error") return true;
    return valueTruthy(r);
}
 
bool Debugger::onScriptLine(const SourceLoc& loc) {
    const RunMode m = mode_.load();
    if (m == RunMode::Paused) {
        return true;
    }
 
    // Verification: any breakpoint whose exact line we just executed is real.
    // Report it (once) even when stepping filters or conditions suppress the stop.
    std::vector<int> verifiedNow;
    {
        std::lock_guard<std::mutex> lock(mu_);
        if (!bps_.empty() && matchBreakpointAny(loc.source, loc.line)) {
            for (auto& bp : bps_) {
                if (bp.verified || bp.line != loc.line ||
                    !sourcesMatch(loc.source, bp.source))
                    continue;
                bp.verified    = true;
                verifiedNow.push_back(bp.id);
            }
        }
    }
    for (const int id : verifiedNow) {
        if (bpEventFn_) bpEventFn_(id, loc.source, loc.line, true);
    }
 
    const bool stepping =
        m == RunMode::StepInto || m == RunMode::StepOver || m == RunMode::StepOut;
 
    // While leaving the paused line, ignore further events for that exact
    // source+line (extra _OP_LINE and re-armed breakpoints on the same site).
    if (stepping && !stepSkipLoc_.empty() && stepSkipLoc_.line == loc.line &&
        sourcesMatch(stepSkipLoc_.source, loc.source)) {
        return false;
    }
 
    // Breakpoints win over step filters (hit inside a skipped call).
    Breakpoint matched;
    bool hit = false;
    {
        std::lock_guard<std::mutex> lock(mu_);
        if (bpsEnabled_.load()) {
            for (const auto& bp : bps_) {
                if (!bp.enabled || bp.line != loc.line ||
                    !sourcesMatch(loc.source, bp.source))
                    continue;
                matched = bp;
                hit     = true;
                break;
            }
        }
    }
    if (hit) {
        if (!conditionHolds(matched)) return false;
        stepSkipLoc_ = {};
        pauseLoc_    = loc;
        reason_.store(PauseReason::Breakpoint);
        mode_.store(RunMode::Paused);
        RenderVision::instance().notifyPending("breakpoint", loc.source, loc.line);
        return true;
    }
 
    if (stepping) {
        const int depth = scriptStackDepth();
        bool stop       = false;
        if (m == RunMode::StepInto) {
            stop = true;
        } else if (m == RunMode::StepOver) {
            // Same frame or outer: stop. Deeper (inside a call): keep going.
            stop = depth <= stepStartDepth_;
        } else {  // StepOut
            stop = depth < stepStartDepth_;
        }
        if (stop) {
            stepSkipLoc_ = {};
            pauseLoc_    = loc;
            reason_.store(PauseReason::Step);
            mode_.store(RunMode::Paused);
            return true;
        }
        return false;
    }
    return false;
}
 
void Debugger::waitWhilePaused(const std::function<void()>& pump) {
    // Re-entrancy guard: evaluating an expression (eve_eval / watches /
    // breakpoint conditions) while already paused runs bytecode on this VM,
    // whose line hook reports "paused" and would otherwise block again on the
    // same thread — deadlocking the pause pump. The nested caller only wants
    // the eval to finish, so let it run instead of blocking a second time.
    static thread_local int pausePumpDepth = 0;
    if (pausePumpDepth > 0) return;
    ++pausePumpDepth;
    struct Guard {
        ~Guard() { --pausePumpDepth; }
    } guard;
    try {
        while (mode_.load() == RunMode::Paused) {
            if (pump) pump();
            else if (pump_) pump_();
            std::this_thread::sleep_for(std::chrono::milliseconds(5));
            if (!vm_) break;
        }
    } catch (...) {
        // Keep the pump re-entrancy state consistent; the caller's hook is
        // responsible for surfacing the failure.
    }
}
 
int Debugger::setBreakpoint(std::string source, int line, bool enabled,
                            std::string condition) {
    source = normalizeSource(std::move(source));
    if (source.empty() || line <= 0) return 0;
    std::lock_guard<std::mutex> lock(mu_);
    for (auto& bp : bps_) {
        if (bp.line == line && normalizeSource(bp.source) == source) {
            bp.enabled   = enabled;
            bp.condition = std::move(condition);
            return bp.id;
        }
    }
    Breakpoint bp;
    bp.source    = std::move(source);
    bp.line      = line;
    bp.enabled   = enabled;
    bp.condition = std::move(condition);
    bp.id        = nextBpId_++;
    bps_.push_back(bp);
    return bp.id;
}
 
bool Debugger::clearBreakpoint(std::string source, int line) {
    std::lock_guard<std::mutex> lock(mu_);
    const auto before = bps_.size();
    bps_.erase(std::remove_if(bps_.begin(), bps_.end(),
                              [&](const Breakpoint& bp) {
                                  return bp.line == line && sourcesMatch(source, bp.source);
                              }),
               bps_.end());
    return bps_.size() != before;
}
 
void Debugger::clearBreakpoints(const std::string& source) {
    std::lock_guard<std::mutex> lock(mu_);
    if (source.empty()) {
        bps_.clear();
        return;
    }
    bps_.erase(std::remove_if(bps_.begin(), bps_.end(),
                              [&](const Breakpoint& bp) { return sourcesMatch(source, bp.source); }),
               bps_.end());
}
 
bool Debugger::setBreakpointEnabled(int id, bool enabled) {
    std::lock_guard<std::mutex> lock(mu_);
    for (auto& bp : bps_) {
        if (bp.id != id) continue;
        bp.enabled = enabled;
        return true;
    }
    return false;
}
 
std::vector<Breakpoint> Debugger::breakpoints() const {
    std::lock_guard<std::mutex> lock(mu_);
    return bps_;
}
 
bool Debugger::hasBreakpoint(const std::string& source, int line) const {
    std::lock_guard<std::mutex> lock(mu_);
    return matchBreakpointAny(source, line);
}
 
void Debugger::addWatch(std::string expression) {
    if (expression.empty()) return;
    std::lock_guard<std::mutex> lock(mu_);
    for (const auto& e : watchExprs_) {
        if (e == expression) return;
    }
    watchExprs_.push_back(std::move(expression));
}
 
bool Debugger::removeWatch(const std::string& expression) {
    std::lock_guard<std::mutex> lock(mu_);
    const auto before = watchExprs_.size();
    watchExprs_.erase(std::remove(watchExprs_.begin(), watchExprs_.end(), expression),
                      watchExprs_.end());
    return watchExprs_.size() != before;
}
 
void Debugger::clearWatches() {
    std::lock_guard<std::mutex> lock(mu_);
    watchExprs_.clear();
    watchCache_.clear();
}
 
std::vector<WatchEntry> Debugger::watches() const {
    std::lock_guard<std::mutex> lock(mu_);
    return watchCache_;
}
 
void Debugger::refreshWatches() {
    std::vector<std::string> exprs;
    {
        std::lock_guard<std::mutex> lock(mu_);
        exprs = watchExprs_;
    }
    std::vector<WatchEntry> cache;
    cache.reserve(exprs.size());
    for (const auto& e : exprs) {
        WatchEntry w;
        w.expression = e;
        auto info    = evaluate(e);
        w.ok         = !info.type.empty() && info.type != "error";
        w.value      = info.value;
        cache.push_back(std::move(w));
    }
    std::lock_guard<std::mutex> lock(mu_);
    watchCache_ = std::move(cache);
}
 
VariableInfo Debugger::readLocal(HSQUIRRELVM vm, unsigned level, const std::string& name) const {
    VariableInfo info;
    info.name = name;
    if (!vm) {
        info.type  = "error";
        info.value = "no vm";
        return info;
    }
    for (SQUnsignedInteger n = 0;; ++n) {
        const SQInteger top  = sq_gettop(vm);
        const SQChar*   lname = sq_getlocal(vm, level, n);
        if (!lname) {
            sq_settop(vm, top);
            break;
        }
        if (name == lname) {
            info.value = describeSqValue(vm, -1);
            info.type  = typeName(vm, -1);
            sq_settop(vm, top);
            return info;
        }
        sq_settop(vm, top);
    }
    info.type  = "error";
    info.value = "not found";
    return info;
}
 
VariableInfo Debugger::readRoot(HSQUIRRELVM vm, const std::string& name) const {
    VariableInfo info;
    info.name = name;
    if (!vm) {
        info.type  = "error";
        info.value = "no vm";
        return info;
    }
    const SQInteger top = sq_gettop(vm);
    sq_pushroottable(vm);
    sq_pushstring(vm, name.c_str(), -1);
    if (SQ_SUCCEEDED(sq_get(vm, -2))) {
        info.value = describeSqValue(vm, -1);
        info.type  = typeName(vm, -1);
    } else {
        info.type  = "error";
        info.value = "not found";
    }
    sq_settop(vm, top);
    return info;
}
 
VariableInfo Debugger::evaluateLegacy(const std::string& expression) const {
    HSQUIRRELVM vm = vm_;
    if (!vm || expression.empty()) {
        VariableInfo info;
        info.name  = expression;
        info.type  = "error";
        info.value = "unavailable";
        return info;
    }
    // Prefer local, then roottable slot. Full expression eval is intentionally
    // limited (safe for watches of variable names / dotted root paths).
    auto local = readLocal(vm, 0, expression);
    if (local.type != "error") return local;
 
    // Support a.b root path (tables only).
    if (expression.find('.') != std::string::npos) {
        VariableInfo info;
        info.name             = expression;
        const SQInteger top   = sq_gettop(vm);
        sq_pushroottable(vm);
        bool ok = true;
        size_t start = 0;
        while (start < expression.size()) {
            size_t dot = expression.find('.', start);
            if (dot == std::string::npos) dot = expression.size();
            const std::string part = expression.substr(start, dot - start);
            sq_pushstring(vm, part.c_str(), -1);
            if (SQ_FAILED(sq_get(vm, -2))) {
                ok = false;
                break;
            }
            // Replace parent with child: [root, parent, child] → keep child under root.
            sq_remove(vm, -2);
            start = dot + 1;
        }
        if (ok) {
            info.value = describeSqValue(vm, -1);
            info.type  = typeName(vm, -1);
        } else {
            info.type  = "error";
            info.value = "not found";
        }
        sq_settop(vm, top);
        return info;
    }
    return readRoot(vm, expression);
}
 
std::vector<VariableInfo> Debugger::locals(int stackLevel) const {
    std::vector<VariableInfo> out;
    HSQUIRRELVM vm = vm_;
    if (!vm) return out;
    const SQUnsignedInteger level = static_cast<SQUnsignedInteger>(stackLevel < 0 ? 0 : stackLevel);
    for (SQUnsignedInteger n = 0;; ++n) {
        const SQInteger top  = sq_gettop(vm);
        const SQChar*   name = sq_getlocal(vm, level, n);
        if (!name) {
            sq_settop(vm, top);
            break;
        }
        VariableInfo info = describeAt(vm, -1);
        info.name         = name;
        sq_settop(vm, top);
        out.push_back(std::move(info));
    }
    return out;
}
 
std::vector<VariableInfo> Debugger::globals() const {
    std::vector<VariableInfo> out;
    HSQUIRRELVM vm = vm_;
    if (!vm) return out;
    const SQInteger top = sq_gettop(vm);
    sq_pushroottable(vm);
    out = enumerateAt(vm, -1);
    sq_settop(vm, top);
    return out;
}
 
bool Debugger::pushLocalValue(HSQUIRRELVM vm, unsigned level, const std::string& name) const {
    for (SQUnsignedInteger n = 0;; ++n) {
        const SQInteger top  = sq_gettop(vm);
        const SQChar*   lname = sq_getlocal(vm, level, n);
        if (!lname) {
            sq_settop(vm, top);
            return false;
        }
        if (name == lname) return true;  // local value is on the stack
        sq_settop(vm, top);
    }
}
 
bool Debugger::pushPathValue(HSQUIRRELVM vm, VarKind kind, int frame,
                             const std::vector<std::string>& path) const {
    if (!vm) return false;
    const SQInteger top = sq_gettop(vm);
    if (kind == VarKind::Globals) {
        sq_pushroottable(vm);
    } else if (kind == VarKind::Locals) {
        if (path.empty()) return false;
        if (!pushLocalValue(vm, static_cast<unsigned>(frame < 0 ? 0 : frame), path[0]))
            return false;
    } else {
        return false;
    }
 
    const size_t start = (kind == VarKind::Globals) ? 0 : 1;
    for (size_t i = start; i < path.size(); ++i) {
        const SQInteger before = sq_gettop(vm);
        const int curAbs       = static_cast<int>(before);
        sq_pushstring(vm, path[i].c_str(), -1);
        if (SQ_FAILED(sq_get(vm, curAbs))) {
            sq_settop(vm, top);
            return false;
        }
        sq_remove(vm, -2);  // drop parent, keep child
    }
    return true;
}
 
std::vector<VariableInfo> Debugger::containerChildren(VarKind kind, int frame,
                                                      const std::vector<std::string>& path) const {
    HSQUIRRELVM vm = vm_;
    if (!vm) return {};
    if (path.empty()) {
        if (kind == VarKind::Locals) return locals(frame);
        if (kind == VarKind::Globals) return globals();
        return {};
    }
    const SQInteger top = sq_gettop(vm);
    if (!pushPathValue(vm, kind, frame, path)) {
        sq_settop(vm, top);
        return {};
    }
    std::vector<VariableInfo> out = enumerateAt(vm, -1);
    sq_settop(vm, top);
    return out;
}
 
VariableInfo Debugger::evaluate(const std::string& expression, int frameLevel) const {
    HSQUIRRELVM vm = vm_;
    if (!vm || expression.empty()) {
        VariableInfo info;
        info.name  = expression;
        info.type  = "error";
        info.value = "unavailable";
        return info;
    }
    const SQInteger top = sq_gettop(vm);
    const int level     = frameLevel < 0 ? 0 : frameLevel;
 
    // Locals env: fresh table seeded with the frame's locals; delegate = roottable
    // so global names also resolve (locals shadow globals, like in the frame).
    sq_newtable(vm);
    for (SQUnsignedInteger n = 0;; ++n) {
        const SQInteger before = sq_gettop(vm);
        const SQChar*   lname  = sq_getlocal(vm, static_cast<SQUnsignedInteger>(level), n);
        if (!lname) {
            sq_settop(vm, before);
            break;
        }
        // Stack after sq_getlocal: [env, value]; build [env, key, value].
        sq_pushstring(vm, lname, -1);  // key
        sq_push(vm, -2);               // duplicate value
        sq_remove(vm, -3);             // drop original value
        sq_newslot(vm, -3, SQFalse);   // env[key] = value (pops key+value)
    }
    sq_pushroottable(vm);
    if (SQ_FAILED(sq_setdelegate(vm, -2))) {
        sq_settop(vm, top);
        return evaluateLegacy(expression);
    }
 
    const std::string src = "return (" + expression + ");";
    // Debugger/MCP evaluation is an in-memory operation. Do not register the
    // expression as a project script or give it a filesystem-shaped identity.
    if (SQ_FAILED(sq_compilebuffer(vm, src.c_str(), static_cast<SQInteger>(src.size()),
                                   _SC("memory://devtools/evaluate"), SQTrue))) {
        sq_settop(vm, top);
        eve::script::ScriptErrorContext ctx = eve::script::captureCompileError(vm);
        VariableInfo info;
        info.name = expression;
        info.type = "error";
        info.value = ctx.empty() ? "compile error" : eve::script::formatScriptError(ctx);
        return info;
    }
    // stack: [env, closure]
    sq_push(vm, -2);                 // [env, closure, env]
    sq_setclosureroot(vm, -2);       // closure env = locals table (pops copy)
    sq_pushroottable(vm);            // this/arg for the call
    VariableInfo info;
    info.name = expression;
    if (SQ_SUCCEEDED(sq_call(vm, 1, SQTrue, SQFalse))) {
        info = describeAt(vm, -1);
    } else {
        eve::script::ScriptErrorContext ctx = eve::script::takeLastScriptError(vm);
        info.type  = "error";
        info.value = ctx.empty() ? "eval error" : eve::script::formatScriptError(ctx);
    }
    sq_settop(vm, top);
    return info;
}
 
std::vector<StackFrameInfo> Debugger::stackTrace(int maxFrames) const {
    std::vector<StackFrameInfo> out;
    HSQUIRRELVM vm = vm_;
    if (!vm) return out;
    if (maxFrames <= 0) maxFrames = 32;
    for (int level = 0; level <= maxFrames; ++level) {
        SQStackInfos si;
        if (SQ_FAILED(sq_stackinfos(vm, level, &si))) break;
        StackFrameInfo f;
        f.id = level;
        if (si.source) f.loc.source = si.source;
        f.loc.line = static_cast<int>(si.line);
        // Native-only frames (Squirrel reports source "NATIVE" / line -1, e.g.
        // the uncaught-error hook parked above the throwing script frame) carry
        // no script location. Skip them so frame 0 in the IDE is the throw
        // site; ids stay at stack levels so scopes(frameId) still resolves to
        // the right frame's locals.
        if (f.loc.source == "NATIVE" || (f.loc.source.empty() && f.loc.line <= 0)) continue;
        f.name         = nameFromPrototype(level, si.funcname, f.loc);
        f.loc.function = f.name;
        out.push_back(std::move(f));
    }
    applyCallGraphNames(out);
    return out;
}
 
}  // namespace eve::dev