From bd2fa7a9958abcdddad1243adb53977e214fd570 Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Sun, 13 Sep 2026 22:18:26 +0800
Subject: [PATCH 01/21] fix: report heap and render failures instead of faking
 success

Testing with `go tool pprof` (go1.26.8) exposed several paths where a failure
reached clients as a 200 carrying something that was not a profile.

GetHeapSample() does not return an empty string when heap sampling is off
(TCMALLOC_SAMPLE_PARAMETER unset, default 0). It returns pprof's %warn advisory
followed by a syntactically valid but empty profile:

    %warn
    %warn This heap profile does not have any data in it, because
    heap profile:      0:        0 [     0:        0] @ heap_v2/0
    MAPPED_LIBRARIES:

so the `sample.empty()` check never fired. Measured against a server started
without the variable, the three heap endpoints disagreed with each other:
/pprof/heap answered 200 with the warning as its body, /api/heap/svg_raw
answered 500, and /api/heap/flamegraph_raw answered 200 with a 13KB graph --
all three from the same empty input. The zero sampling rate (or a leading
%warn) is now detected in one place, so all three report the same explicit
error. With `go tool pprof`, the failure now reads

    server response: 500 Internal Server Error - Could not read heap sample:
    heap sampling is off or produced no data. Set TCMALLOC_SAMPLE_PARAMETER ...

where it previously reported a successful fetch containing zero samples.

Three further fixes in the same area:

- analyze*() failures produced invalid JSON. The core returns a
  `{"error": ...}` string and the handler passed it to HandlerResponse::error(),
  which wrapped it again without escaping, emitting
  `{"error":"{"error": "Failed to..."}`. handleHeapAnalyze additionally threw the
  reason away and substituted "Failed to generate heap flame graph", which is how
  "already in use" stopped being visible. The inner message is now extracted
  before wrapping.
- /pprof/heap and /pprof/growth errors now use Go's serveError() shape
  (text/plain plus X-Go-Pprof: 1) rather than application/json, so the tool shows
  the message instead of misreading the body.
- generateFlameGraph() accepted flamegraph.pl's answer to empty input, which is a
  structurally valid SVG whose entire content is
  "ERROR: No valid input provided to flamegraph.pl." That passed the SVG check
  and shipped as HTTP 200 with a graph-shaped error. It is now a 500 explaining
  that the window was too short or the process idle, which is what a 2s sample of
  an idle process actually is.

The parsing helpers move to src/internal/result_parsing.h so they can be tested
without profiler state; test_result_parsing.cpp covers the exact %warn payload
tcmalloc emits, the zero-rate marker, message extraction, and that re-wrapping an
extracted message stays valid JSON. Verified to catch the old behaviour: with the
checks reverted, 4 of its cases fail.

Validated end to end with go tool pprof against a live server: `-top` resolves
cpuIntensiveTask/memoryIntensiveTask/rand for CPU and memoryIntensiveTask/
std::vector::_M_realloc_append for heap, and `-http` renders graph, flamegraph,
peek and top views with the SVG carrying real node content.
---
 CHANGELOG.md                          |  23 +++++
 CMakeLists.txt                        |  10 +++
 ROADMAP.md                            |  12 ++-
 docs/user_guide/04_troubleshooting.md |  17 ++++
 src/http_handlers.cpp                 |  31 +++++--
 src/internal/result_parsing.h         |  77 ++++++++++++++++
 src/profiler_manager.cpp              |  19 +++-
 tests/test_result_parsing.cpp         | 125 ++++++++++++++++++++++++++
 8 files changed, 303 insertions(+), 11 deletions(-)
 create mode 100644 src/internal/result_parsing.h
 create mode 100644 tests/test_result_parsing.cpp

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b3f1ef6..5e47630 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -58,6 +58,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   while stopping an existing session; the stop and the state update now happen
   under the lock, as does the corresponding teardown in `getRawCPUProfile()`.
 
+### Fixed
+- `/pprof/heap` reported success when heap sampling was off. `GetHeapSample()` does
+  not return an empty string in that case -- it returns pprof's `%warn` advisory
+  followed by a valid-looking but empty profile (`@ heap_v2/0`) -- so the
+  emptiness check never fired and clients received HTTP 200 carrying the warning
+  text. The zero sampling rate (or a leading `%warn`) is now recognised and
+  reported as an error. This also removes an inconsistency where
+  `/api/heap/svg_raw` failed with 500 while `/api/heap/flamegraph_raw` rendered a
+  13KB graph from the identical input.
+- Analyze endpoints emitted invalid JSON on failure: the core returns a
+  `{"error": ...}` string and the handler wrapped it again without escaping,
+  producing `{"error":"{"error": "..."}`. The inner message is now extracted
+  first; `handleHeapAnalyze` also no longer discards the reason in favour of a
+  generic string.
+- `/pprof/heap` and `/pprof/growth` errors now follow Go's `serveError()` shape
+  (`text/plain` plus `X-Go-Pprof: 1`), so `go tool pprof` prints the reason
+  instead of the content type misleading it.
+- `flamegraph.pl` answers empty input with a *valid* SVG whose entire content is
+  an error message, so the structural SVG check passed and callers got HTTP 200
+  plus a graph reading "ERROR: No valid input provided to flamegraph.pl." That is
+  now detected and returned as a 500 explaining that the sample window was too
+  short or the process idle.
+
 ### Documentation
 - README, the API reference and the troubleshooting guide now spell out that the
   two heap views are **opposite in kind**, not two renderings of one dataset:
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 0d8100a..fa639a5 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -266,6 +266,16 @@ if(REMOTE_PROFILER_BUILD_TESTS)
     )
     add_test(NAME AsyncExecutorTest COMMAND test_async_executor)
 
+    # Return-value parsing shared by the HTTP layer (internal, no Drogon needed)
+    add_executable(test_result_parsing tests/test_result_parsing.cpp)
+    target_link_libraries(test_result_parsing
+        profiler_core
+        GTest::gtest
+        GTest::gtest_main
+        pthread
+    )
+    add_test(NAME ResultParsingTest COMMAND test_result_parsing)
+
     message(STATUS "Tests will be built")
 else()
     message(STATUS "Tests disabled")
diff --git a/ROADMAP.md b/ROADMAP.md
index e445fc1..2b5639c 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -68,13 +68,19 @@
 
 </details>
 
+### 已修复（本轮，用 go tool pprof 验证）
+
+- `/pprof/heap` 在采样关闭时返回 200 + `%warn` 文本：`GetHeapSample()` 不返回空串，导致空值检查失效。现按 `@ heap_v2/0` / 前导 `%warn` 识别，返回 500。
+- `/api/heap/svg_raw` 与 `flamegraph_raw` 的行为不一致：根因同上，两者现在都返回同样的明确错误。
+- 分析类接口的错误响应**双重包裹**成非法 JSON（`{"error":"{"error": "..."}`）：现将内部错误消息解出后再包一层。
+- `/pprof/heap` 与 `/pprof/growth` 的错误改用 Go `serveError()` 的形状（`text/plain` + `X-Go-Pprof: 1`），`go tool pprof` 能直接显示原因。
+- `flamegraph.pl` 对空输入返回"合法 SVG + ERROR 文本"，被当作 200 成功：现识别并转为带原因的 500。
+
 ### 待修
 
 - **`pprof --svg` 的失败信息不透出**：内置 pprof 脚本用 `dot`(graphviz) 渲染，采样点过少时 `dot` 失败，代码只回一句 `pprof did not generate valid SVG. Output: `（且 `svg_output` 为空），无法定位原因。应把 `dot` 的 stderr 一并返回。**这是异步改造期间实测复现的既有缺陷**，与请求调度无关。
 - **`stopHeapProfiler()` 的 `output_path` 语义**：它把 `GetHeapProfile()` 的返回值写进 `output_path` 文件，而 `.heap` 是 gperftools 自己按 prefix 写的，两套产物并存容易混淆。
-- **`/pprof/heap` 在采样关闭时返回 200，响应体却不是 profile**：`GetHeapSample()` 在 `TCMALLOC_SAMPLE_PARAMETER` 未设置（默认 0）时**不返回空串**，而是返回 pprof 的 `%warn` 警告文本加一行零样本统计（`heap profile: 0: 0 [0: 0] @ heap_v2/0`）。因此 `if (heap_sample.empty())` 这个错误分支进不去，客户端收到 200 + 看起来像 profile 的东西。应识别 `@ heap_v2/0` 或首行 `%warn` 并返回明确错误。
-- **`/api/heap/svg_raw` 与 `/api/heap/flamegraph_raw` 在无 `TCMALLOC_SAMPLE_PARAMETER` 时表现不一致**：两者**都**先调 `getRawHeapSample()`（源码已核对），拿到的都是 `%warn` + 零样本文本，但因为上面那条缺陷没被拦下，后续命令的容错差异决定成败——`pprof --svg`（`svg_raw`）对零样本 profile 失败并超出 3 秒超时，返回 500 `Failed to generate SVG`；`pprof --collapsed` + `flamegraph.pl`（`flamegraph_raw`）却渲染出 13KB 的 SVG，返回 200。实测复现。修掉上面那条（识别零样本）即可同时解决。
-- **`/tmp/cpp_profiler` 下的 `.heap` 快照不再清理**：每次 `analyzeHeapProfile` 用唯一前缀（时间戳 + 序号）产生一个新文件，长期运行会累积。
+- **Web 面板缺少"当前堆快照"入口**：面板上的三个 Heap 入口全部走窗口式（`/api/heap/analyze` 与两个 `*_raw`），状态式的 `/pprof/heap` **没有 UI 入口**。进程内存高但停止分配时，用户在面板里无法查看存量堆。可加一个按钮调用 `/pprof/heap`（并提示需要 `TCMALLOC_SAMPLE_PARAMETER`）。
 - **`analyzeHeapProfile` 的采样窗口固定 1 秒且不可配置**：分配稀疏的进程在窗口内可能一次分配都没有，只能得到空结果。可考虑加一个可选的窗口参数，或复用 `startHeapProfiler()`/`stopHeapProfiler()` 让调用方掌控。
 
 ### 已完成的调度改造（供参考）
diff --git a/docs/user_guide/04_troubleshooting.md b/docs/user_guide/04_troubleshooting.md
index 2e51e50..ed06ec4 100644
--- a/docs/user_guide/04_troubleshooting.md
+++ b/docs/user_guide/04_troubleshooting.md
@@ -755,6 +755,23 @@ go tool pprof -http=:8081 ./your_app heap.prof
 
 Heap 分析（`/api/heap/analyze`）出于同样的原因也独占，并发时返回 `409` + `{"error":"heap profiling already in use"}`。注意 `HeapProfilerStart()` 与 CPU profiler 不同——它**没有失败模式**，重复调用会静默替换输出前缀，所以必须在调用之前原子认领，而不是"先查询再启动"。`/api/growth/analyze` 不占用会话，不受限制。
 
+### Q: 接口返回 500 "Failed to get heap sample" / "heap sampling is off"
+**A**: 状态式 heap 端点（`/pprof/heap`、`/api/heap/svg_raw`）依赖 `TCMALLOC_SAMPLE_PARAMETER`，而它**必须在进程启动前**设置（默认 `0` 表示关闭采样）：
+
+```bash
+export TCMALLOC_SAMPLE_PARAMETER=524288
+./your_app
+```
+
+窗口式端点（`/api/heap/analyze`、`/api/heap/flamegraph_raw`）走的是另一套机制，不受影响。
+
+> 以前这三种情况会给出**三种不同**的结果（`/pprof/heap` 返回 200 + `%warn` 文本、`/api/heap/svg_raw` 返回 500、`/api/heap/flamegraph_raw` 返回 200 + 一张空图）。现已统一为带原因的 500。
+
+### Q: 接口返回 500 "No stack samples to render (profile is empty)"
+**A**: 采样窗口内没有收集到足够的栈样本，`flamegraph.pl` 拒绝渲染。常见原因是采样时长太短，而目标进程在那段时间里正好空闲。加长 `duration`（例如 10–30 秒）或在有负载时重试。
+
+> 以前这种情况会返回 **200** 和一张只含 `ERROR: No valid input provided to flamegraph.pl.` 文字的 SVG，看起来像成功。现已改为带原因的 500。
+
 ### Q: 接口返回 500 "pprof did not generate valid SVG"
 **A**: 内置 pprof 脚本用 `dot`（graphviz）渲染，当 profile 采样点太少或数据异常时 `dot` 会失败并输出错误文本，因而被判定为"非 SVG"。请：① 安装 graphviz；② 加长采样时长（`?duration=30`）；③ 确认编译带 `-g`。这是已知的**既有缺陷**（错误信息未把 `dot` 的原始输出透出），记录在 [ROADMAP](../../ROADMAP.md)。
 
diff --git a/src/http_handlers.cpp b/src/http_handlers.cpp
index fffe626..d4c0a37 100644
--- a/src/http_handlers.cpp
+++ b/src/http_handlers.cpp
@@ -2,6 +2,7 @@
 /// @brief Framework-agnostic HTTP endpoint handlers implementation
 
 #include "profiler/http_handlers.h"
+#include "internal/result_parsing.h"
 #include "profiler_manager.h"
 #include <chrono>
 #include <fstream>
@@ -105,8 +106,8 @@ HandlerResponse ProfilerHttpHandlers::handleCpuAnalyze(int duration, const std::
 
     std::string svg = profiler_.analyzeCPUProfile(duration, output_type);
 
-    if (svg.size() > 10 && svg[0] == '{' && svg[1] == '"') {
-        return errorResp(500, svg);
+    if (internal::isJsonError(svg)) {
+        return errorResp(500, internal::jsonErrorMessage(svg));
     }
 
     return HandlerResponse::svg(svg);
@@ -225,8 +226,8 @@ HandlerResponse ProfilerHttpHandlers::handleHeapAnalyze(const std::string& outpu
     // No duration argument: heap profiling is allocation driven, not time driven.
     std::string svg = profiler_.analyzeHeapProfile(output_type);
 
-    if (svg.size() > 10 && svg[0] == '{' && svg[1] == '"') {
-        return errorResp(500, "Failed to generate heap flame graph");
+    if (internal::isJsonError(svg)) {
+        return errorResp(500, internal::jsonErrorMessage(svg));
     }
 
     return HandlerResponse::svg(svg);
@@ -491,10 +492,28 @@ HandlerResponse ProfilerHttpHandlers::handlePprofProfile(int seconds) {
     return resp;
 }
 
+namespace {
+
+/// Error response for the /pprof/* family, following Go's serveError(): plain
+/// text plus the X-Go-Pprof marker, so `go tool pprof` shows the message instead
+/// of trying to parse the body as profile data. Using the JSON helper here would
+/// both mislabel the content type and hide the message from the tool.
+HandlerResponse pprofErrorResponse(const std::string& message) {
+    HandlerResponse resp;
+    resp.status = 500;
+    resp.content_type = "text/plain; charset=utf-8";
+    resp.body = message + "\n";
+    resp.headers["X-Go-Pprof"] = "1";
+    return resp;
+}
+
+} // namespace
+
 HandlerResponse ProfilerHttpHandlers::handlePprofHeap() {
     std::string data = profiler_.getRawHeapSample();
     if (data.empty()) {
-        return errorResp(500, "Failed to get heap sample. Make sure TCMALLOC_SAMPLE_PARAMETER is set.");
+        return pprofErrorResponse("Could not read heap sample: heap sampling is off or produced no "
+                                  "data. Set TCMALLOC_SAMPLE_PARAMETER before starting the process.");
     }
 
     HandlerResponse resp;
@@ -508,7 +527,7 @@ HandlerResponse ProfilerHttpHandlers::handlePprofHeap() {
 HandlerResponse ProfilerHttpHandlers::handlePprofGrowth() {
     std::string data = profiler_.getRawHeapGrowthStacks();
     if (data.empty()) {
-        return errorResp(500, "Failed to get heap growth stacks. No heap growth data available.");
+        return pprofErrorResponse("Could not read heap growth stacks: no heap growth data available.");
     }
 
     HandlerResponse resp;
diff --git a/src/internal/result_parsing.h b/src/internal/result_parsing.h
new file mode 100644
index 0000000..9d3c648
--- /dev/null
+++ b/src/internal/result_parsing.h
@@ -0,0 +1,77 @@
+/// @file result_parsing.h
+/// @brief Helpers for interpreting profiler-core return values
+///
+/// The ProfilerManager methods signal failure inconsistently by design (they are
+/// older than the HTTP layer): the analyze*() family returns a `{"error": ...}`
+/// JSON string, while the raw getters return an empty string. Web adapters need
+/// to tell those apart and surface the actual reason, so the parsing lives here
+/// where it can be unit tested in isolation from any real profiler state.
+
+#pragma once
+
+#include "profiler_version.h"
+#include <string>
+
+PROFILER_NAMESPACE_BEGIN
+
+namespace internal {
+
+/// @brief Whether @p value is one of the core's `{"error": ...}` strings
+///
+/// The check is structural rather than a JSON parse -- the core only ever emits
+/// this exact shape, and callers sit on a request path. It does require the key,
+/// so an unrelated JSON document that merely starts with `{"` is not mistaken
+/// for a failure.
+inline bool isJsonError(const std::string& value) {
+    return value.size() > 10 && value[0] == '{' && value.find("\"error\"") != std::string::npos;
+}
+
+/// @brief Extract the message from a core `{"error": ...}` string
+///
+/// Needed because wrapping the raw JSON in another error response would both
+/// double-wrap it and, since the inner quotes are unescaped, emit invalid JSON
+/// (`{"error":"{"error": "..."}`). Substituting a fixed message instead would
+/// discard the reason, which is how "cpu profiling already in use" used to
+/// arrive at clients as a generic failure.
+///
+/// @param value A string previously accepted by isJsonError()
+/// @return The inner message, or @p value unchanged if it cannot be parsed
+inline std::string jsonErrorMessage(const std::string& value) {
+    const std::string key = "\"error\"";
+    auto key_pos = value.find(key);
+    if (key_pos == std::string::npos) {
+        return value;
+    }
+    auto open_quote = value.find('"', key_pos + key.size());
+    if (open_quote == std::string::npos) {
+        return value;
+    }
+    auto close_quote = value.rfind('"');
+    if (close_quote == std::string::npos || close_quote <= open_quote) {
+        return value;
+    }
+    return value.substr(open_quote + 1, close_quote - open_quote - 1);
+}
+
+/// @brief Whether a heap sample from GetHeapSample() carries no usable data
+///
+/// With heap sampling off (TCMALLOC_SAMPLE_PARAMETER unset, whose default is 0)
+/// tcmalloc does not return an empty string. It returns pprof's `%warn`
+/// advisory followed by a syntactically valid but empty profile:
+///
+/// ```
+/// %warn
+/// %warn This heap profile does not have any data in it, because
+/// heap profile:      0:        0 [     0:        0] @ heap_v2/0
+/// MAPPED_LIBRARIES:
+/// ```
+///
+/// So testing for emptiness alone never fires, and callers render a graph out of
+/// nothing. The zero sampling rate (or the leading `%warn`) marks the case.
+inline bool isEmptyHeapSample(const std::string& sample) {
+    return sample.empty() || sample.find("@ heap_v2/0") != std::string::npos || sample.rfind("%warn", 0) == 0;
+}
+
+} // namespace internal
+
+PROFILER_NAMESPACE_END
diff --git a/src/profiler_manager.cpp b/src/profiler_manager.cpp
index 67a9dde..a85bdd7 100644
--- a/src/profiler_manager.cpp
+++ b/src/profiler_manager.cpp
@@ -5,6 +5,7 @@
 #include "internal/embed_pprof.h"
 #include "internal/log_macros.h"
 #include "internal/log_manager.h"
+#include "internal/result_parsing.h"
 #include "internal/symbolize.h"
 #include <algorithm>
 #include <atomic>
@@ -349,6 +350,19 @@ std::string ProfilerManager::generateFlameGraph(const std::string& collapsed_fil
         return R"({"error": "flamegraph.pl did not generate valid SVG"})";
     }
 
+    // flamegraph.pl answers empty or unusable input with a *valid* SVG whose only
+    // content is an error message, so the structural check above passes and a
+    // 200 carrying "ERROR: ..." would reach the caller. Treat that as a failure
+    // and say why, since the usual cause is a profile with no samples.
+    if (svg_output.find("ERROR:") != std::string::npos) {
+        auto error_pos = svg_output.find("ERROR:");
+        auto error_end = svg_output.find('<', error_pos);
+        std::string message = svg_output.substr(error_pos, error_end - error_pos);
+        PROFILER_ERROR("flamegraph.pl reported: {}", message);
+        return R"({"error": "No stack samples to render (profile is empty). The sampled window may have been too short or the process was idle; try a longer duration or sample under load. flamegraph.pl said: )" +
+               message + R"("})";
+    }
+
     return svg_output;
 }
 
@@ -938,8 +952,9 @@ std::string ProfilerManager::getRawHeapSample() {
     // GetHeapSample writes the heap profile into the string
     MallocExtension::instance()->GetHeapSample(&heap_sample);
 
-    if (heap_sample.empty()) {
-        PROFILER_ERROR("Failed to get heap sample. Make sure TCMALLOC_SAMPLE_PARAMETER environment variable is set.");
+    if (internal::isEmptyHeapSample(heap_sample)) {
+        PROFILER_ERROR("Heap sampling is off or produced no data. Set TCMALLOC_SAMPLE_PARAMETER "
+                       "(e.g. 524288) before starting the process.");
         return "";
     }
 
diff --git a/tests/test_result_parsing.cpp b/tests/test_result_parsing.cpp
new file mode 100644
index 0000000..0805d0a
--- /dev/null
+++ b/tests/test_result_parsing.cpp
@@ -0,0 +1,125 @@
+/// @file test_result_parsing.cpp
+/// @brief Tests for interpreting profiler-core return values
+///
+/// These cover a class of bug that reached users: a failure the HTTP layer could
+/// not recognise, so it either reported success or replaced the reason with a
+/// generic message.
+
+#include "../src/internal/result_parsing.h"
+#include <gtest/gtest.h>
+#include <string>
+
+using profiler::internal::isEmptyHeapSample;
+using profiler::internal::isJsonError;
+using profiler::internal::jsonErrorMessage;
+
+// ---------------------------------------------------------------------------
+// isJsonError / jsonErrorMessage
+// ---------------------------------------------------------------------------
+
+TEST(JsonErrorTest, RecognisesCoreErrorStrings) {
+    EXPECT_TRUE(isJsonError(R"({"error": "Failed to start CPU profiler"})"));
+    EXPECT_TRUE(isJsonError(R"({"error": "cpu profiling already in use"})"));
+    EXPECT_TRUE(isJsonError(R"({"error": "No heap profile data was produced. Details here."})"));
+}
+
+TEST(JsonErrorTest, DoesNotMistakeSvgOrTextForAnError) {
+    EXPECT_FALSE(isJsonError(""));
+    EXPECT_FALSE(isJsonError("<svg xmlns=\"http://www.w3.org/2000/svg\"></svg>"));
+    EXPECT_FALSE(isJsonError("<?xml version=\"1.0\"?><svg/>"));
+    EXPECT_FALSE(isJsonError(R"({"err": "wrong key"})")) << "only {\"error\" is an error payload";
+    EXPECT_FALSE(isJsonError("heap profile: 1: 20000 @ heap_v2/524288"));
+    EXPECT_FALSE(isJsonError("{}"));
+}
+
+TEST(JsonErrorTest, ExtractsTheInnerMessage) {
+    // The exact shape the core emits, including an embedded apostrophe.
+    EXPECT_EQ(jsonErrorMessage(R"({"error": "cpu profiling already in use"})"), "cpu profiling already in use");
+    EXPECT_EQ(jsonErrorMessage(R"({"error": "Failed to start CPU profiler"})"), "Failed to start CPU profiler");
+}
+
+TEST(JsonErrorTest, ExtractedMessageRoundTripsThroughAnotherWrap) {
+    // Regression guard for the double-wrap bug: the old code passed the whole
+    // JSON string to HandlerResponse::error(), producing
+    //   {"error":"{"error": "..."}
+    // which is not valid JSON. Re-wrapping the *message* must stay parseable.
+    const std::string core_error = R"({"error": "cpu profiling already in use"})";
+    const std::string message = jsonErrorMessage(core_error);
+    const std::string wrapped = "{\"error\":\"" + message + "\"}";
+
+    EXPECT_EQ(wrapped.find_first_of('{', 1), std::string::npos)
+        << "wrapped response must contain a single brace group: " << wrapped;
+    EXPECT_EQ(wrapped, R"({"error":"cpu profiling already in use"})");
+}
+
+TEST(JsonErrorTest, KeepsLongMessagesIntact) {
+    // The heap "no data" message is long and contains punctuation and a URL-ish
+    // word; it must survive extraction unchanged.
+    const std::string core_error =
+        R"({"error": "No heap profile data was produced. The heap profiler only records samples for allocations made while it is running; try /tmp/cpp_profiler."})";
+    const std::string message = jsonErrorMessage(core_error);
+    EXPECT_EQ(message.rfind("No heap profile data was produced.", 0), 0);
+    EXPECT_NE(message.find("try /tmp/cpp_profiler."), std::string::npos);
+    EXPECT_EQ(message.back(), '.');
+}
+
+TEST(JsonErrorTest, FallsBackToTheInputWhenUnparseable) {
+    // Defensive: a malformed string is returned as-is rather than truncated to
+    // something meaningless.
+    const std::string odd = "{\"err\": \"no error key here\"}";
+    EXPECT_EQ(jsonErrorMessage(odd), odd);
+    EXPECT_EQ(jsonErrorMessage("not json at all"), "not json at all");
+}
+
+// ---------------------------------------------------------------------------
+// isEmptyHeapSample
+// ---------------------------------------------------------------------------
+
+TEST(EmptyHeapSampleTest, DetectsWhatTcmallocEmitsWhenSamplingIsOff) {
+    // Verbatim shape produced by GetHeapSample() with TCMALLOC_SAMPLE_PARAMETER
+    // unset: a %warn advisory that still looks like a valid profile, which is why
+    // the old `empty()` check never fired.
+    const std::string off = "%warn\n"
+                            "%warn This heap profile does not have any data in it, because\n"
+                            "%warn the application was run with heap sampling turned off.\n"
+                            "%warn To get useful data from GetHeapSample(), you must\n"
+                            "%warn set the environment variable TCMALLOC_SAMPLE_PARAMETER to\n"
+                            "%warn a positive sampling period, such as 524288.\n"
+                            "%warn\n"
+                            "heap profile:      0:        0 [     0:        0] @ heap_v2/0\n"
+                            "\n"
+                            "MAPPED_LIBRARIES:\n"
+                            "00400000-0040b000 r-xp 00000000 00:00 535369 /tmp/app\n";
+
+    EXPECT_FALSE(off.empty()) << "precondition: this is why empty() was not enough";
+    EXPECT_TRUE(isEmptyHeapSample(off));
+}
+
+TEST(EmptyHeapSampleTest, DetectsZeroRateEvenWithoutTheWarning) {
+    // Some paths emit just the zero-rate header; the marker alone must suffice.
+    EXPECT_TRUE(isEmptyHeapSample("heap profile:      0:        0 [     0:        0] @ heap_v2/0\n"));
+}
+
+TEST(EmptyHeapSampleTest, DetectsTheEmptyString) {
+    EXPECT_TRUE(isEmptyHeapSample(""));
+}
+
+TEST(EmptyHeapSampleTest, AcceptsARealSample) {
+    const std::string real = "heap profile:      1:    20000 [     1:    20000] @ heap_v2/524288\n"
+                             "     1:    20000 [     1:    20000] @ 0x401d8a 0x4080cc\n"
+                             "\n"
+                             "MAPPED_LIBRARIES:\n";
+
+    EXPECT_FALSE(isEmptyHeapSample(real));
+}
+
+TEST(EmptyHeapSampleTest, AProfileCarryingTheZeroRateMarkerIsRejectedWhereverItAppears) {
+    // The marker is searched for anywhere in the text, not only at the start:
+    // a profile whose rate line says heap_v2/0 has no samples regardless of what
+    // else it carries, and pprof would report it as empty too.
+    const std::string zero_rate_with_frames = "heap profile:      0:        0 [     0:        0] @ heap_v2/0\n"
+                                              "MAPPED_LIBRARIES:\n"
+                                              "00400000-0040b000 r-xp 00000000 00:00 535369 /tmp/app\n";
+
+    EXPECT_TRUE(isEmptyHeapSample(zero_rate_with_frames));
+}

From 2280741a13eaa055ff97ab61e1c5fb74a983e1ec Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Sun, 13 Sep 2026 22:43:11 +0800
Subject: [PATCH 02/21] feat(web): add the missing state-based heap view to the
 panel
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The panel offered three heap entry points -- /api/heap/analyze and the two
*_raw renderers -- and all three are window-based: they record only the
allocations made during a fixed 1s sampling window. The state-based view
(GET /pprof/heap, tcmalloc's cumulative snapshot of what is currently in the
heap) had no UI entry point at all, so a process holding a large heap but no
longer allocating could not be inspected from the panel: every button returned
"No heap profile data was produced", and seeing the resident heap required
leaving the UI for curl.

The Heap section is now two labelled cards so the two mechanisms are not
confused for one another:

- "窗口式：采样 1 秒内的分配" keeps the existing analyze/download buttons
- "状态式：当前堆的累计快照" adds 查看 and 下载 actions driving /pprof/heap

The view action opens the profile as text in a new tab (it *is* plain text, so
the browser renders it directly) and logs the line count, size and first line;
the download action saves it as heap.prof and logs the `go tool pprof` command
to analyse it. Fetch failures are reported in the log panel, with the 500 case
explained as the missing TCMALLOC_SAMPLE_PARAMETER rather than a bare status,
since that variable must be set before the process starts.

Also records in ROADMAP the two rendering observations made while reading the
embedded pprof's output: function names carry a `<hex address>` suffix into the
flame graph (and, for template instantiations, split what should be one frame
into several), and some symbols arrive still mangled, typically rendering as a
context-free "operator()[inline]" because the frame is a lambda's operator().

Verified on a live server: both cards render, the extracted page JavaScript
passes `node --check`, /pprof/heap answers 200 with text/plain and a
Content-Disposition filename, and the downloaded profile analyses under
`go tool pprof` (1.02MB attributed to memoryIntensiveTask). A fresh process
returns growing counters (1: 20000 -> 2: 40000 -> 7: 60000); a zero-sample
result with `@ heap_v2/524288` is a genuine "nothing allocated in this window"
and is not treated as an error by the new empty-sample check.
---
 CHANGELOG.md          |  7 +++-
 README.md             |  6 ++-
 ROADMAP.md            | 10 ++++-
 src/web_resources.cpp | 96 ++++++++++++++++++++++++++++++++++++++++---
 4 files changed, 109 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5e47630..34b34f7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -93,7 +93,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   allocations freed inside the window still do, and consecutive sessions do not
   accumulate.
 - The heap Web panel says which of the two it performs, and no longer labels a
-  window-rendered SVG download as a "heap profile".
+  window-rendered SVG download as a "heap profile". It also gained the missing
+  entry point for the state-based view: the panel previously offered only the
+  window-based endpoints, so a process holding a large heap but no longer
+  allocating could not be inspected from the UI at all. The Heap section is now
+  two labelled cards, the second driving `GET /pprof/heap` with view and
+  download actions.
 
 ### Removed
 - `logger.h` (unused after the logging rework)
diff --git a/README.md b/README.md
index 843f5c6..dd73e92 100644
--- a/README.md
+++ b/README.md
@@ -418,8 +418,10 @@ tcmalloc 在**进程初始化时**读取该变量，因此必须在启动前用
 所以窗口式分析需要**被分析进程在采样窗口内确实有分配**。窗口目前固定为 1 秒；需要更长窗口时，
 请用 `startHeapProfiler()` / `stopHeapProfiler()` 自行掌控时机。
 
-Web 控制面板里的两个 Heap 按钮走的是**窗口式**（`/api/heap/analyze` 与
-`/api/heap/{svg_raw,flamegraph_raw}`），面板上已标注这一点。
+Web 控制面板的 Heap 区把两者分成了两张卡片：
+
+- **窗口式：采样 1 秒内的分配** —— `/api/heap/analyze` 与 `/api/heap/{svg_raw,flamegraph_raw}`
+- **状态式：当前堆的累计快照** —— `GET /pprof/heap`（可查看/下载，需 `TCMALLOC_SAMPLE_PARAMETER`）
 
 ### 依赖版本
 
diff --git a/ROADMAP.md b/ROADMAP.md
index 2b5639c..4722c47 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -78,9 +78,17 @@
 
 ### 待修
 
+- **火焰图里的函数名带地址后缀**：内置 pprof 的 `--collapsed` 输出把函数名写成
+  `cpuIntensiveTask()<0000000000409360>`，经 `flamegraph.pl` 渲染后直接显示在图上。除了噪音，还有一个
+  理论隐患：同一函数出现在不同地址时（模板实例化）会被当成**不同栈帧**，本该合并的被拆开。
+  可在送入 `flamegraph.pl` 之前剥掉 `<十六进制>` 后缀。
+- **部分符号未 demangle**：实测火焰图里残留 `_ZSt12construct_at...` 之类的 mangled 名，且这类帧常显示为
+  无上下文的 `operator()[inline]`（lambda 的 `operator()`）。可对未解开的符号做二次 `__cxa_demangle`。
+- **两个 pprof 实现的差异未写进文档**：内置 Perl pprof（`output_type=pprof` 的渲染器）符号化更完整——
+  实测同一份 profile 未解析帧为 0、且能标出 `(inline)`；而 `go tool pprof` 强在对比与交互
+  （`-diff_base`、`-peek`、`-traces`）。README 目前只说了"两种渲染方式"，没说各自适合什么场景。
 - **`pprof --svg` 的失败信息不透出**：内置 pprof 脚本用 `dot`(graphviz) 渲染，采样点过少时 `dot` 失败，代码只回一句 `pprof did not generate valid SVG. Output: `（且 `svg_output` 为空），无法定位原因。应把 `dot` 的 stderr 一并返回。**这是异步改造期间实测复现的既有缺陷**，与请求调度无关。
 - **`stopHeapProfiler()` 的 `output_path` 语义**：它把 `GetHeapProfile()` 的返回值写进 `output_path` 文件，而 `.heap` 是 gperftools 自己按 prefix 写的，两套产物并存容易混淆。
-- **Web 面板缺少"当前堆快照"入口**：面板上的三个 Heap 入口全部走窗口式（`/api/heap/analyze` 与两个 `*_raw`），状态式的 `/pprof/heap` **没有 UI 入口**。进程内存高但停止分配时，用户在面板里无法查看存量堆。可加一个按钮调用 `/pprof/heap`（并提示需要 `TCMALLOC_SAMPLE_PARAMETER`）。
 - **`analyzeHeapProfile` 的采样窗口固定 1 秒且不可配置**：分配稀疏的进程在窗口内可能一次分配都没有，只能得到空结果。可考虑加一个可选的窗口参数，或复用 `startHeapProfiler()`/`stopHeapProfiler()` 让调用方掌控。
 
 ### 已完成的调度改造（供参考）
diff --git a/src/web_resources.cpp b/src/web_resources.cpp
index e4e47bd..ce48cd2 100644
--- a/src/web_resources.cpp
+++ b/src/web_resources.cpp
@@ -145,6 +145,18 @@ static const char INDEX_PAGE[] = R"HTML(
             display: inline-block;
             margin: 5px;
         }
+        .card {
+            border: 1px solid #e0e0e0;
+            border-radius: 4px;
+            padding: 12px;
+            margin: 10px 0;
+            background-color: #fff;
+        }
+        .card h3 {
+            margin: 0 0 6px;
+            font-size: 15px;
+            color: #333;
+        }
         .hint {
             display: block;
             margin: 6px 0 10px;
@@ -198,13 +210,12 @@ static const char INDEX_PAGE[] = R"HTML(
 
         <div class="section">
             <h2>Heap Profiler</h2>
-            <div>
+            <div class="card">
+                <h3>窗口式：采样 1 秒内的分配</h3>
                 <span class="hint">
-                    ⚠️ 这里的两个按钮都是<b>窗口式</b>分析：采样 1 秒并记录<b>这段时间内发生的分配</b>，
-                    不反映此刻已经在堆里的内存。若进程内存虽高但已停止分配，结果会是空的（返回
-                    "No heap profile data was produced"）。想看<b>当前堆的累计快照</b>，请用
-                    <code>GET /pprof/heap</code> 导出原始 profile（需在启动前设置
-                    <code>TCMALLOC_SAMPLE_PARAMETER</code>）。
+                    ⚠️ 只记录<b>这 1 秒内发生的分配</b>，不反映此刻已经在堆里的内存。若进程内存虽高但已停止分配，
+                    结果会是空的（返回 "No heap profile data was produced"）。另注：其中 <code>pprof SVG</code>
+                    一项依赖 <code>TCMALLOC_SAMPLE_PARAMETER</code>，<code>FlameGraph</code> 不依赖。
                 </span>
                 <div class="input-group">
                     <label for="heap-chart-type">图表类型:</label>
@@ -216,6 +227,17 @@ static const char INDEX_PAGE[] = R"HTML(
                 <button class="analyze-btn" onclick="analyzeHeap()">⚡ 一键分析并生成Heap火焰图</button>
                 <button class="download-btn" id="heap-download-btn" onclick="downloadHeapChart()">📥 下载 Heap 图表 (SVG)</button>
             </div>
+            <div class="card">
+                <h3>状态式：当前堆的累计快照</h3>
+                <span class="hint">
+                    对应 <code>GET /pprof/heap</code>，返回 tcmalloc 的累计采样，反映<b>堆里现存的内存</b>
+                    ——与上面的"1 秒内分配"是两套机制，结果不同属正常。
+                    <b>需要</b>在进程启动前设置 <code>TCMALLOC_SAMPLE_PARAMETER</code>，否则返回 500。
+                    下载后可用 <code>go tool pprof ./your_app heap.prof</code> 分析。
+                </span>
+                <button class="view-btn" onclick="viewHeapProfile()">🔍 查看当前堆快照</button>
+                <button class="download-btn" id="heap-profile-btn" onclick="downloadHeapProfile()">📥 下载 heap.prof</button>
+            </div>
         </div>
 
         <div class="section">
@@ -350,6 +372,68 @@ static const char INDEX_PAGE[] = R"HTML(
                 });
         }
 
+        // 状态式 heap 快照（/pprof/heap）：与上面的窗口式分析是两套机制。
+        // 返回的是原始 profile 文本，所以既能当文本预览，也能存成 .prof 交给
+        // `go tool pprof` 分析。
+        function fetchHeapProfile() {
+            return fetch('/pprof/heap').then(response => {
+                if (!response.ok) {
+                    if (response.status === 500) {
+                        return Promise.reject(new Error(
+                            '服务器返回 500。状态式快照需要在进程启动前设置 TCMALLOC_SAMPLE_PARAMETER ' +
+                            '（例如 524288），当前进程未设置或采样已关闭。'));
+                    }
+                    return Promise.reject(new Error(`HTTP ${response.status}: ${response.statusText}`));
+                }
+                const disposition = response.headers.get('Content-Disposition') || '';
+                const match = /filename="?([^"]+)"?/.exec(disposition);
+                return response.text().then(text => ({ text: text, filename: match ? match[1] : 'heap.prof' }));
+            });
+        }
+
+        // 用文本视图直接展示（profile 是纯文本，浏览器会原样显示）
+        function viewHeapProfile() {
+            log('🚀 正在获取当前堆快照 (/pprof/heap)...');
+            fetchHeapProfile()
+                .then(r => {
+                    const blob = new Blob([r.text], { type: 'text/plain' });
+                    window.open(URL.createObjectURL(blob), '_blank');
+                    const lines = r.text.split('\n').filter(l => l.trim() !== '').length;
+                    log(`✅ 已在新标签页打开堆快照：${lines} 行 / ${r.text.length} 字节\n` +
+                        `   首行: ${r.text.split('\n')[0]}\n` +
+                        `   提示：这是原始 profile，可视化请下载后运行 ` +
+                        `go tool pprof ./your_app ${r.filename}`);
+                })
+                .catch(err => log(`❌ 获取失败: ${err.message}`));
+        }
+
+        function downloadHeapProfile() {
+            const btn = document.getElementById('heap-profile-btn');
+            const originalText = btn.textContent;
+            btn.disabled = true;
+            btn.textContent = '⏳ 准备下载...';
+            log('🚀 正在获取当前堆快照 (/pprof/heap)...');
+
+            fetchHeapProfile()
+                .then(r => {
+                    const url = URL.createObjectURL(new Blob([r.text], { type: 'text/plain' }));
+                    const a = document.createElement('a');
+                    a.href = url;
+                    a.download = r.filename;
+                    document.body.appendChild(a);
+                    a.click();
+                    document.body.removeChild(a);
+                    URL.revokeObjectURL(url);
+                    log(`✅ 已保存 ${r.filename} (${r.text.length} 字节)\n` +
+                        `   分析: go tool pprof ./your_app ${r.filename}`);
+                })
+                .catch(err => log(`❌ 获取失败: ${err.message}`))
+                .finally(() => {
+                    btn.disabled = false;
+                    btn.textContent = originalText;
+                });
+        }
+
         function downloadHeapChart() {
             const chartType = document.getElementById('heap-chart-type').value;
             const btn = document.getElementById('heap-download-btn');

From e2cb61029a8fc8b8bb8656b1edfc5915b278f8eb Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Sun, 13 Sep 2026 22:55:22 +0800
Subject: [PATCH 03/21] feat(heap): make the collection window configurable and
 use it everywhere
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two corrections, both from the same misreading on my part.

Heap duration is not meaningless -- it is just not a sampling *rate*. gperftools
fixes the rate through TCMALLOC_SAMPLE_PARAMETER at process start, so duration
cannot improve precision; but it decides how long allocations are collected, so
a process that allocates sparsely needs a longer window to produce anything.
Hard-coding 1s left that case with no recourse beyond dropping to the low-level
startHeapProfiler()/stopHeapProfiler() pair. analyzeHeapProfile() takes
(duration, output_type) again (default 1, clamped 1-300), and the handlers,
routes and panel all pass it through.

Measured: /api/heap/analyze now takes 2.2s, 4.0s and 7.1s for duration 1, 3 and
6, i.e. the window is honoured rather than ignored.

The two renderers were also not wired up properly. They pulled GetHeapSample(),
which is the state-based path, so they ignored any window and depended on
TCMALLOC_SAMPLE_PARAMETER being set at startup -- which is why
/api/heap/svg_raw failed with 500 while /api/heap/flamegraph_raw rendered a
graph from identical input. They now call a new getRawHeapProfileSample(duration),
which runs its own HeapProfilerStart/GetHeapProfile/Stop window and returns the
profile text, so all three window-based endpoints share one mechanism, honour
duration, and work without the startup variable. With sampling off they all
return SVG while only the state-based /pprof/heap reports its error.

Panel: the window card gained a duration input, and a 查看图表 button so the two
*_raw renderers are reachable for viewing rather than only for download --
previously the only consumer of those endpoints was the download button, with
viewing going through /api/heap/analyze. Chart type, duration and endpoint
selection now share one code path (heapChartEndpoint/heapDuration), and the
viewer page forwards duration.

Verified live: with the variable unset, all three window endpoints return 200
SVG and /pprof/heap returns 500 with its explanation; with it set, a fresh
process reports growing counters and go tool pprof attributes 1.02MB to
memoryIntensiveTask. Extraction of the page script passes node --check.
---
 CHANGELOG.md                     |  3 +-
 README.md                        | 29 +++++++-----
 ROADMAP.md                       |  4 +-
 include/profiler/http_handlers.h | 18 +++++---
 include/profiler_manager.h       | 26 ++++++++++-
 src/drogon_adapter.cpp           | 36 +++++++++++++--
 src/http_handlers.cpp            | 21 ++++++---
 src/profiler_manager.cpp         | 77 ++++++++++++++++++++++++++++++--
 src/web_resources.cpp            | 53 +++++++++++++++++-----
 tests/test_http_handlers.cpp     | 36 +++++++++------
 10 files changed, 243 insertions(+), 60 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 34b34f7..8f7d566 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,7 +23,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Breaking:** `ProfilerManager` is no longer a singleton — construct it directly and manage its lifetime
 - **Breaking:** removed the spdlog dependency; use `setLogSink()` / `setLogLevel()` instead
 - **Breaking:** core library decoupled from the web layer — `profiler_core` (no Drogon) and `profiler_web` (optional Drogon adapter) are now separate targets
-- **Breaking:** `analyzeHeapProfile()` no longer takes a `duration` argument. gperftools heap profiling is allocation driven (`HeapProfilerStart()` / `HeapProfilerDump()`), so the sample rate is fixed at process start by `TCMALLOC_SAMPLE_PARAMETER` and elapsed time has no effect. `ProfilerHttpHandlers::handleHeapAnalyze()` likewise takes only `output_type`.
+- **Breaking:** `analyzeHeapProfile()` takes `(duration, output_type)` again, and `handleHeapAnalyze` / `handleHeapSvgRaw` / `handleHeapFlamegraphRaw` all take a duration. This reverses an earlier removal that was right about the *sampling rate* but wrong to conclude the window is meaningless: gperftools fixes the rate via `TCMALLOC_SAMPLE_PARAMETER` at process start, so `duration` cannot improve precision, but it does decide **how long allocations are collected**. A process that allocates sparsely needs a longer window to produce anything, and a hard-coded 1s gave it no recourse. Default 1s, clamped 1-300s.
+- `/api/heap/svg_raw` and `/api/heap/flamegraph_raw` now run their own sampling window (`getRawHeapProfileSample()`) instead of pulling `GetHeapSample()`. Besides honouring the duration, this makes them work in a process started without `TCMALLOC_SAMPLE_PARAMETER`, which previously made `/api/heap/svg_raw` fail with 500 while its sibling `/api/heap/flamegraph_raw` succeeded on the same input. The three window-based endpoints now behave identically.
 - **Breaking:** removed the never-implemented `ProfilerHttpHandlers::dispatch()` declaration; route registration stays with the host framework
 - **The Drogon adapter no longer runs profiling on the event-loop thread.** Every handler that can block — CPU/heap/growth analysis, the `_raw` renderers, and `/pprof/profile` — is dispatched to a background worker and its response is handed back with `queueInLoop()`. Profiling takes seconds (up to 300s for CPU), so this previously stalled all other requests, including `/api/status`, for the whole sampling window.
 - Blocking jobs share one worker thread. This is required for correctness, not just throughput: gperftools keeps its profiling session in process-global state, so concurrent analyses would corrupt each other's results.
diff --git a/README.md b/README.md
index dd73e92..6f0fc5e 100644
--- a/README.md
+++ b/README.md
@@ -320,14 +320,14 @@ profiler.setLogLevel(profiler::LogLevel::Debug);
 | `/pprof/symbol` | POST | 符号化接口（Go pprof symbolz 协议） |
 | **一键分析（返回 SVG）** | | |
 | `/api/cpu/analyze` | GET/POST | 采样并返回 CPU 图；`?duration=N` 默认 10，范围 1–300 |
-| `/api/heap/analyze` | GET | **窗口式**：采样 1 秒后渲染；**不接受** `duration`；**无需**环境变量 |
+| `/api/heap/analyze` | GET | **窗口式**：采集后渲染；`?duration=N` 默认 1，范围 1–300；**无需**环境变量 |
 | `/api/growth/analyze` | GET | 返回 Heap Growth 图 |
 | **原始 SVG 下载** | | |
 | `/api/cpu/svg_raw` | GET | pprof 生成的 CPU SVG；`?duration=N` 默认 10 |
-| `/api/heap/svg_raw` | GET | **窗口式**：pprof 渲染的 Heap SVG；**需** `TCMALLOC_SAMPLE_PARAMETER` |
+| `/api/heap/svg_raw` | GET | **窗口式**：pprof 渲染的 Heap SVG；`?duration=N` 默认 1 |
 | `/api/growth/svg_raw` | GET | pprof 生成的 Growth SVG |
 | `/api/cpu/flamegraph_raw` | GET | FlameGraph 渲染的 CPU SVG；`?duration=N` 默认 10 |
-| `/api/heap/flamegraph_raw` | GET | **窗口式**：FlameGraph 渲染的 Heap SVG；**无需**环境变量 |
+| `/api/heap/flamegraph_raw` | GET | **窗口式**：FlameGraph 渲染的 Heap SVG；`?duration=N` 默认 1 |
 | `/api/growth/flamegraph_raw` | GET | FlameGraph 渲染的 Growth SVG |
 | **线程分析** | | |
 | `/api/thread/stacks` | GET | 所有线程的调用栈 |
@@ -392,21 +392,22 @@ tcmalloc 在**进程初始化时**读取该变量，因此必须在启动前用
 `/api/heap/flamegraph_raw`。Heap Growth（`/pprof/growth`、`/api/growth/*`）走
 `GetHeapGrowthStacks()`，也不需要该变量。
 
-> ⚠️ 因此同一进程内可能出现"一个 heap 端点成功、另一个失败"：
-> 不设该变量时 `/api/heap/analyze` 与 `/api/heap/flamegraph_raw` 正常返回 SVG，
-> 而 `/api/heap/svg_raw` 返回 500 —— 它们的数据源不同，不是同一个缺陷。
+> ⚠️ 不设该变量时：三个**窗口式**端点（`/api/heap/analyze`、`/api/heap/svg_raw`、
+> `/api/heap/flamegraph_raw`）仍然正常返回 SVG，因为它们各自运行自己的
+> `HeapProfilerStart/GetHeapProfile/Stop` 窗口；只有**状态式**的 `/pprof/heap` 返回 500。
 
 ### Heap 的两个端点语义相反
 
 这两个端点容易混淆，因为名字里都有 "heap"，但记录的是**完全不同的东西**：
 
-| | `/pprof/heap` | `/api/heap/analyze` |
+| | `/pprof/heap` | `/api/heap/{analyze,svg_raw,flamegraph_raw}` |
 |---|---|---|
-| 语义 | **状态式**：当前堆里的累计采样 | **窗口式**：1 秒内**发生的分配** |
-| 底层 | `GetHeapSample()` 拉取 | `HeapProfilerStart()` → dump → `Stop()` |
+| 语义 | **状态式**：当前堆里的累计采样 | **窗口式**：采集窗口内**发生的分配** |
+| 底层 | `GetHeapSample()` 拉取 | `HeapProfilerStart()` → `GetHeapProfile()` → `Stop()` |
 | 是否建 profiler 会话 | 否 | 是（独占，并发返回 409） |
 | 输出 | 原始 profile 文本，**客户端**用 `go tool pprof` 渲染 | 服务端渲染好的 SVG |
 | `TCMALLOC_SAMPLE_PARAMETER` | **必需** | 不需要 |
+| 时长参数 | 无 | `?duration=N`，默认 1 秒 |
 
 关键差别在于**"存量"与"流量"**：
 
@@ -415,12 +416,16 @@ tcmalloc 在**进程初始化时**读取该变量，因此必须在启动前用
 - 进程频繁 malloc/free，dump 时已全部释放 → `/api/heap/analyze` **能看到**这些分配；`/pprof/heap`
   的当前堆则可能很小
 
-所以窗口式分析需要**被分析进程在采样窗口内确实有分配**。窗口目前固定为 1 秒；需要更长窗口时，
-请用 `startHeapProfiler()` / `stopHeapProfiler()` 自行掌控时机。
+所以窗口式分析需要**被分析进程在采集窗口内确实有分配**。
+
+⚠️ **heap 的 `duration` 不是采样率**：采样率由 `TCMALLOC_SAMPLE_PARAMETER` 在进程启动时固定，
+`duration` 只决定**采集多久**。分配稀疏的进程需要更长的窗口才能采到东西，所以它是"覆盖度"参数
+而不是"精度"参数。默认 1 秒，范围 1–300。
 
 Web 控制面板的 Heap 区把两者分成了两张卡片：
 
-- **窗口式：采样 1 秒内的分配** —— `/api/heap/analyze` 与 `/api/heap/{svg_raw,flamegraph_raw}`
+- **窗口式**（可选采集窗口 + 图表类型）—— 三个按钮分别走 `/api/heap/analyze`（内嵌查看）、
+  以及 `/api/heap/{svg_raw,flamegraph_raw}`（查看/下载）
 - **状态式：当前堆的累计快照** —— `GET /pprof/heap`（可查看/下载，需 `TCMALLOC_SAMPLE_PARAMETER`）
 
 ### 依赖版本
diff --git a/ROADMAP.md b/ROADMAP.md
index 4722c47..d22142f 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -89,7 +89,9 @@
   （`-diff_base`、`-peek`、`-traces`）。README 目前只说了"两种渲染方式"，没说各自适合什么场景。
 - **`pprof --svg` 的失败信息不透出**：内置 pprof 脚本用 `dot`(graphviz) 渲染，采样点过少时 `dot` 失败，代码只回一句 `pprof did not generate valid SVG. Output: `（且 `svg_output` 为空），无法定位原因。应把 `dot` 的 stderr 一并返回。**这是异步改造期间实测复现的既有缺陷**，与请求调度无关。
 - **`stopHeapProfiler()` 的 `output_path` 语义**：它把 `GetHeapProfile()` 的返回值写进 `output_path` 文件，而 `.heap` 是 gperftools 自己按 prefix 写的，两套产物并存容易混淆。
-- **`analyzeHeapProfile` 的采样窗口固定 1 秒且不可配置**：分配稀疏的进程在窗口内可能一次分配都没有，只能得到空结果。可考虑加一个可选的窗口参数，或复用 `startHeapProfiler()`/`stopHeapProfiler()` 让调用方掌控。
+- **窗口式 heap 端点缺少"采样率"调节**：`duration` 控制的是**采集多久**（覆盖度），采样率仍由
+  `TCMALLOC_SAMPLE_PARAMETER` 在启动时固定。若调用方希望在运行期调整**精度**，目前没有途径
+  （`HEAP_PROFILE_ALLOCATION_INTERVAL` 只在 `HeapProfilerStart` 前设环境变量才生效）。
 
 ### 已完成的调度改造（供参考）
 
diff --git a/include/profiler/http_handlers.h b/include/profiler/http_handlers.h
index d1d730a..ce6a6bc 100644
--- a/include/profiler/http_handlers.h
+++ b/include/profiler/http_handlers.h
@@ -98,12 +98,18 @@ class ProfilerHttpHandlers {
     HandlerResponse handleCpuFlamegraphRaw(int duration);
 
     // --- Heap endpoints ---
-    /// @note Heap analysis has no duration parameter: gperftools heap profiling
-    ///       is allocation driven, so the sample rate is fixed at process start
-    ///       by TCMALLOC_SAMPLE_PARAMETER rather than by elapsed time.
-    HandlerResponse handleHeapAnalyze(const std::string& output_type);
-    HandlerResponse handleHeapSvgRaw();
-    HandlerResponse handleHeapFlamegraphRaw();
+    /// @param duration Collection window in seconds (clamped 1..300). Not a
+    ///        sampling rate -- that is fixed by TCMALLOC_SAMPLE_PARAMETER at
+    ///        process start -- but a longer window covers more allocations.
+    HandlerResponse handleHeapAnalyze(int duration, const std::string& output_type);
+
+    /// @brief Render the current heap sample with the pprof script
+    /// @param duration Collection window in seconds (clamped 1..300)
+    HandlerResponse handleHeapSvgRaw(int duration);
+
+    /// @brief Render the current heap sample as a FlameGraph
+    /// @param duration Collection window in seconds (clamped 1..300)
+    HandlerResponse handleHeapFlamegraphRaw(int duration);
 
     // --- Growth endpoints ---
     HandlerResponse handleGrowthAnalyze(const std::string& output_type);
diff --git a/include/profiler_manager.h b/include/profiler_manager.h
index 7ca88ec..fac6736 100644
--- a/include/profiler_manager.h
+++ b/include/profiler_manager.h
@@ -160,9 +160,14 @@ class ProfilerManager {
     /// driven, so the sample rate is governed by TCMALLOC_SAMPLE_PARAMETER
     /// (read once at process startup), not by elapsed time.
     ///
+    /// @param duration Collection window in seconds (default 1, clamped 1..300).
+    ///        This is NOT a sampling rate: the rate is fixed by
+    ///        TCMALLOC_SAMPLE_PARAMETER at process start. It controls how long
+    ///        allocations are recorded, so a process that allocates sparsely
+    ///        needs a longer window to produce anything.
     /// @param output_type Output graph type: "flamegraph" (default) or "pprof"
     /// @return SVG content as string, or a {"error":...} JSON string on failure
-    std::string analyzeHeapProfile(const std::string& output_type = "flamegraph");
+    std::string analyzeHeapProfile(int duration = 1, const std::string& output_type = "flamegraph");
 
     /// @brief Get raw CPU profile data (for /pprof/profile endpoint)
     /// @param seconds Sampling duration in seconds
@@ -170,9 +175,28 @@ class ProfilerManager {
     std::string getRawCPUProfile(int seconds);
 
     /// @brief Get raw heap sample data (for /pprof/heap endpoint)
+    ///
+    /// Pulls tcmalloc's cumulative sample of the current heap. Requires
+    /// TCMALLOC_SAMPLE_PARAMETER to have been set before the process started;
+    /// returns "" when sampling is off.
+    ///
     /// @return Heap sample in text format (compatible with pprof)
     std::string getRawHeapSample();
 
+    /// @brief Sample allocations for @p duration seconds and return the raw profile text
+    ///
+    /// Unlike getRawHeapSample() this needs no startup configuration: it runs its
+    /// own HeapProfilerStart/GetHeapProfile/Stop window, so it works in a process
+    /// launched without TCMALLOC_SAMPLE_PARAMETER. Use this when the caller wants
+    /// to choose how long to collect (sparse allocators need longer) and then
+    /// render or analyse the text themselves.
+    ///
+    /// @param duration Collection window in seconds (clamped 1..300)
+    /// @return Profile text (pprof format), or a {"error":...} JSON string on failure
+    /// @note Exclusive, like analyzeHeapProfile(): rejects with "heap profiling
+    ///       already in use" if another analysis or a host session is active
+    std::string getRawHeapProfileSample(int duration);
+
     /// @brief Get heap growth stacks data (for /pprof/growth endpoint)
     /// @return Heap growth stacks in text format (compatible with pprof)
     std::string getRawHeapGrowthStacks();
diff --git a/src/drogon_adapter.cpp b/src/drogon_adapter.cpp
index bc6ee3d..bee00b2 100644
--- a/src/drogon_adapter.cpp
+++ b/src/drogon_adapter.cpp
@@ -297,18 +297,46 @@ void registerDrogonHandlers(profiler::ProfilerManager& profiler) {
         "/api/heap/analyze",
         [handlers, executor, heap_busy](const drogon::HttpRequestPtr& req,
                                         std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
+            int duration = 1;
+            auto dp = req->getParameter("duration");
+            if (!dp.empty()) {
+                try {
+                    duration = std::stoi(dp);
+                } catch (...) {}
+            }
             std::string output_type = req->getParameter("output_type");
             if (output_type.empty())
                 output_type = "pprof";
             runAsync(
                 executor, req, std::move(callback),
-                [handlers, output_type]() { return handlers->handleHeapAnalyze(output_type); }, heap_busy);
+                [handlers, duration, output_type]() { return handlers->handleHeapAnalyze(duration, output_type); },
+                heap_busy);
         },
         {drogon::Get});
 
-    // --- Heap raw / FlameGraph (blocking: shells out to pprof/flamegraph.pl) ---
-    registerGetAsync("/api/heap/svg_raw", &ProfilerHttpHandlers::handleHeapSvgRaw);
-    registerGetAsync("/api/heap/flamegraph_raw", &ProfilerHttpHandlers::handleHeapFlamegraphRaw);
+    // --- Heap raw / FlameGraph (blocking: sample window + pprof/flamegraph.pl) ---
+    // These take a duration too, so the collection window is the caller's choice
+    // rather than whatever the process happened to be started with.
+    auto registerHeapRawAsync = [&](const std::string& path, auto fn) {
+        drogon::app().registerHandler(
+            path,
+            [handlers, executor, fn = std::move(fn)](const drogon::HttpRequestPtr& req,
+                                                     std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
+                int duration = 1;
+                auto dp = req->getParameter("duration");
+                if (!dp.empty()) {
+                    try {
+                        duration = std::stoi(dp);
+                    } catch (...) {}
+                }
+                runAsync(executor, req, std::move(callback),
+                         [handlers, fn, duration]() { return ((*handlers).*fn)(duration); });
+            },
+            {drogon::Get});
+    };
+
+    registerHeapRawAsync("/api/heap/svg_raw", &ProfilerHttpHandlers::handleHeapSvgRaw);
+    registerHeapRawAsync("/api/heap/flamegraph_raw", &ProfilerHttpHandlers::handleHeapFlamegraphRaw);
 
     // --- Growth analyze (blocking: shells out to pprof/flamegraph.pl) ---
     drogon::app().registerHandler("/api/growth/analyze",
diff --git a/src/http_handlers.cpp b/src/http_handlers.cpp
index d4c0a37..821c5b9 100644
--- a/src/http_handlers.cpp
+++ b/src/http_handlers.cpp
@@ -211,7 +211,8 @@ HandlerResponse ProfilerHttpHandlers::handleCpuFlamegraphRaw(int duration) {
 
 // --- Heap endpoints ---
 
-HandlerResponse ProfilerHttpHandlers::handleHeapAnalyze(const std::string& output_type) {
+HandlerResponse ProfilerHttpHandlers::handleHeapAnalyze(int duration, const std::string& output_type) {
+    duration = clampDuration(duration, 1, 300);
     // Heap analysis reconfigures the process-global heap profiler, so refuse
     // immediately rather than racing another analysis for it, or preempting a
     // session the caller opened with startHeapProfiler().
@@ -224,7 +225,7 @@ HandlerResponse ProfilerHttpHandlers::handleHeapAnalyze(const std::string& outpu
     }
 
     // No duration argument: heap profiling is allocation driven, not time driven.
-    std::string svg = profiler_.analyzeHeapProfile(output_type);
+    std::string svg = profiler_.analyzeHeapProfile(duration, output_type);
 
     if (internal::isJsonError(svg)) {
         return errorResp(500, internal::jsonErrorMessage(svg));
@@ -233,8 +234,12 @@ HandlerResponse ProfilerHttpHandlers::handleHeapAnalyze(const std::string& outpu
     return HandlerResponse::svg(svg);
 }
 
-HandlerResponse ProfilerHttpHandlers::handleHeapSvgRaw() {
-    std::string heap_sample = profiler_.getRawHeapSample();
+HandlerResponse ProfilerHttpHandlers::handleHeapSvgRaw(int duration) {
+    duration = clampDuration(duration, 1, 300);
+    // Use the active sampler so the caller's window is honoured, and so this
+    // works in processes started without TCMALLOC_SAMPLE_PARAMETER -- the same
+    // mechanism the analyze endpoint uses.
+    std::string heap_sample = profiler_.getRawHeapProfileSample(duration);
     if (heap_sample.empty()) {
         return errorResp(500, "Failed to get heap sample. Make sure TCMALLOC_SAMPLE_PARAMETER is set.");
     }
@@ -265,8 +270,12 @@ HandlerResponse ProfilerHttpHandlers::handleHeapSvgRaw() {
     return resp;
 }
 
-HandlerResponse ProfilerHttpHandlers::handleHeapFlamegraphRaw() {
-    std::string heap_sample = profiler_.getRawHeapSample();
+HandlerResponse ProfilerHttpHandlers::handleHeapFlamegraphRaw(int duration) {
+    duration = clampDuration(duration, 1, 300);
+    // Use the active sampler so the caller's window is honoured, and so this
+    // works in processes started without TCMALLOC_SAMPLE_PARAMETER -- the same
+    // mechanism the analyze endpoint uses.
+    std::string heap_sample = profiler_.getRawHeapProfileSample(duration);
     if (heap_sample.empty()) {
         return errorResp(500, "Failed to get heap sample. Make sure TCMALLOC_SAMPLE_PARAMETER is set.");
     }
diff --git a/src/profiler_manager.cpp b/src/profiler_manager.cpp
index a85bdd7..63d9f94 100644
--- a/src/profiler_manager.cpp
+++ b/src/profiler_manager.cpp
@@ -610,14 +610,18 @@ std::string ProfilerManager::analyzeCPUProfile(int duration, const std::string&
     return svg_output;
 }
 
-std::string ProfilerManager::analyzeHeapProfile(const std::string& output_type) {
+std::string ProfilerManager::analyzeHeapProfile(int duration, const std::string& output_type) {
     // gperftools heap profiling is allocation driven: HeapProfilerStart() begins
     // recording and HeapProfilerDump() writes a snapshot. Unlike the CPU
     // profiler there is no sampling period to tune -- the sample rate comes from
     // TCMALLOC_SAMPLE_PARAMETER, which tcmalloc reads once at process startup.
     // So there is no user-facing duration here: we simply open a short window
     // during which the application's own allocations get recorded, then dump.
-    static constexpr int kSampleWindowSeconds = 1;
+    // Guard the window the same way the CPU path guards its sampling duration.
+    if (duration < 1)
+        duration = 1;
+    if (duration > 300)
+        duration = 300;
 
     PROFILER_INFO("=== Starting Heap Profile Analysis ===");
 
@@ -681,8 +685,8 @@ std::string ProfilerManager::analyzeHeapProfile(const std::string& output_type)
     // allocations here: a profiler must report the host process's real memory
     // behaviour, and fabricating allocations both pollutes the result and leaks
     // memory in the process under test.
-    PROFILER_INFO("Collecting heap samples for {} second(s)...", kSampleWindowSeconds);
-    sleep(kSampleWindowSeconds);
+    PROFILER_INFO("Collecting heap samples for {} second(s)...", duration);
+    sleep(duration);
 
     // Step 5: Take the snapshot, then stop
     if (IsHeapProfilerRunning()) {
@@ -962,6 +966,71 @@ std::string ProfilerManager::getRawHeapSample() {
     return heap_sample;
 }
 
+std::string ProfilerManager::getRawHeapProfileSample(int duration) {
+    if (duration < 1)
+        duration = 1;
+    if (duration > 300)
+        duration = 300;
+
+    // Same claim as analyzeHeapProfile(): the heap profiler is process-global, so
+    // a window may only be opened by one caller at a time.
+    {
+        bool expected = false;
+        if (!heap_analysis_in_progress_.compare_exchange_strong(expected, true)) {
+            PROFILER_ERROR("Heap analysis already in progress; rejecting this request");
+            return R"({"error": "heap profiling already in use"})";
+        }
+    }
+
+    struct ClaimGuard {
+        static void release() {
+            heap_analysis_in_progress_.store(false);
+        }
+        ~ClaimGuard() {
+            release();
+        }
+    } claim_guard;
+
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (profiler_states_[ProfilerType::HEAP].is_running) {
+            PROFILER_ERROR("A heap profiler session is already open; refusing to take it over");
+            return R"({"error": "heap profiling already in use"})";
+        }
+    }
+
+    // Unique prefix: GetHeapProfile() reports from the profiler's own state, and
+    // a distinct prefix keeps this window's records separate from any other run.
+    auto now = std::chrono::system_clock::now();
+    auto timestamp = std::chrono::duration_cast<std::chrono::milliseconds>(now.time_since_epoch()).count();
+    std::string prefix = profile_dir_ + "/heap_raw_" + std::to_string(timestamp) + "_" +
+                         std::to_string(heap_prefix_sequence_.fetch_add(1));
+
+    PROFILER_INFO("Collecting heap samples for {} second(s) (raw)...", duration);
+    HeapProfilerStart(prefix.c_str());
+    sleep(duration);
+
+    std::string sample;
+    if (IsHeapProfilerRunning()) {
+        char* profile = GetHeapProfile();
+        if (profile != nullptr) {
+            sample.assign(profile);
+            free(profile);
+        }
+        HeapProfilerStop();
+    }
+
+    ClaimGuard::release();
+
+    if (internal::isEmptyHeapSample(sample)) {
+        PROFILER_ERROR("Heap profiling produced no data in the {}s window", duration);
+        return R"({"error": "No heap profile data was produced. The heap profiler only records allocations made while it is running, so the analyzed process must be actively allocating. Increase the duration for a process that allocates sparsely."})";
+    }
+
+    PROFILER_INFO("Raw heap profile size: {} bytes", sample.size());
+    return sample;
+}
+
 std::string ProfilerManager::getRawHeapGrowthStacks() {
     // Get heap growth stacks from tcmalloc
     // MallocExtensionWriter is typedef'd as std::string
diff --git a/src/web_resources.cpp b/src/web_resources.cpp
index ce48cd2..70f4c3d 100644
--- a/src/web_resources.cpp
+++ b/src/web_resources.cpp
@@ -211,12 +211,15 @@ static const char INDEX_PAGE[] = R"HTML(
         <div class="section">
             <h2>Heap Profiler</h2>
             <div class="card">
-                <h3>窗口式：采样 1 秒内的分配</h3>
+                <h3>窗口式：采集一段时间内的分配</h3>
                 <span class="hint">
-                    ⚠️ 只记录<b>这 1 秒内发生的分配</b>，不反映此刻已经在堆里的内存。若进程内存虽高但已停止分配，
-                    结果会是空的（返回 "No heap profile data was produced"）。另注：其中 <code>pprof SVG</code>
-                    一项依赖 <code>TCMALLOC_SAMPLE_PARAMETER</code>，<code>FlameGraph</code> 不依赖。
+                    ⚠️ 只记录<b>采集窗口内发生的分配</b>，不反映此刻已经在堆里的内存。若进程内存虽高但已停止分配，
+                    结果会是空的（返回 "No heap profile data was produced"）。分配稀疏时把窗口调长一些。
                 </span>
+                <div class="input-group">
+                    <label for="heap-duration">采集窗口(秒):</label>
+                    <input type="number" id="heap-duration" value="1" min="1" max="300">
+                </div>
                 <div class="input-group">
                     <label for="heap-chart-type">图表类型:</label>
                     <select id="heap-chart-type">
@@ -225,6 +228,7 @@ static const char INDEX_PAGE[] = R"HTML(
                     </select>
                 </div>
                 <button class="analyze-btn" onclick="analyzeHeap()">⚡ 一键分析并生成Heap火焰图</button>
+                <button class="view-btn" onclick="viewHeapChart()">🔍 查看图表</button>
                 <button class="download-btn" id="heap-download-btn" onclick="downloadHeapChart()">📥 下载 Heap 图表 (SVG)</button>
             </div>
             <div class="card">
@@ -286,9 +290,10 @@ static const char INDEX_PAGE[] = R"HTML(
 
         function analyzeHeap() {
             const chartType = document.getElementById('heap-chart-type').value;
-            log(`🚀 正在获取Heap火焰图 (图表类型: ${chartType})...`);
-            // 打开独立的SVG查看器页面，传递 output_type 参数
-            window.open(`/show_heap_svg.html?output_type=${chartType}`, '_blank');
+            const duration = heapDuration();
+            log(`🚀 正在获取Heap火焰图 (图表类型: ${chartType}, 采集窗口: ${duration}秒)...`);
+            // 打开独立的SVG查看器页面，传递 output_type 与 duration 参数
+            window.open(`/show_heap_svg.html?output_type=${chartType}&duration=${duration}`, '_blank');
             log('✅ Heap火焰图查看器已在新标签页打开');
             log(`💡 提示：当前使用 ${chartType === 'flamegraph' ? 'Brendan Gregg FlameGraph' : 'pprof SVG'}`);
         }
@@ -372,6 +377,28 @@ static const char INDEX_PAGE[] = R"HTML(
                 });
         }
 
+        // 窗口式：图表类型 → 渲染端点。analyze 端点返回 SVG 供内嵌查看，
+        // 两个 *_raw 端点返回可下载的 SVG（同样的采样，只是渲染器不同）。
+        function heapChartEndpoint(chartType) {
+            return chartType === 'flamegraph' ? '/api/heap/flamegraph_raw' : '/api/heap/svg_raw';
+        }
+
+        function heapDuration() {
+            const v = parseInt(document.getElementById('heap-duration').value, 10);
+            return Number.isFinite(v) && v >= 1 ? Math.min(v, 300) : 1;
+        }
+
+        // 与"下载"按钮走同样的端点，只是把结果展示出来而不是保存
+        function viewHeapChart() {
+            const chartType = document.getElementById('heap-chart-type').value;
+            const duration = heapDuration();
+            const endpoint = heapChartEndpoint(chartType);
+            log(`🚀 正在渲染 Heap ${chartType} 图表 (采集窗口 ${duration} 秒)...`);
+            window.open(`${endpoint}?duration=${duration}`, '_blank');
+            log(`✅ 已在新标签页打开 ${endpoint}?duration=${duration}\n` +
+                `   提示：该端点会在服务端采集 ${duration} 秒后再渲染，标签页会稍等片刻。`);
+        }
+
         // 状态式 heap 快照（/pprof/heap）：与上面的窗口式分析是两套机制。
         // 返回的是原始 profile 文本，所以既能当文本预览，也能存成 .prof 交给
         // `go tool pprof` 分析。
@@ -444,7 +471,8 @@ static const char INDEX_PAGE[] = R"HTML(
             btn.textContent = '⏳ 准备下载...';
 
             // 根据图表类型选择端点和文件名
-            const endpoint = chartType === 'flamegraph' ? '/api/heap/flamegraph_raw' : '/api/heap/svg_raw';
+            const endpoint = heapChartEndpoint(chartType);
+            const duration = heapDuration();
             const chartTypeName = chartType === 'flamegraph' ? 'FlameGraph' : 'pprof SVG';
             // 两个端点返回的都是【渲染后的图表】，不是原始 heap profile
             // （/pprof/heap 才是原始 profile，且需要 TCMALLOC_SAMPLE_PARAMETER）
@@ -464,8 +492,8 @@ static const char INDEX_PAGE[] = R"HTML(
                 btn.textContent = `⏳ 生成中 ${progress}% (${countdown}s)`;
             }, 1000);
 
-            // 使用 fetch 下载文件
-            fetch(endpoint)
+            // 使用 fetch 下载文件（带上采集窗口）
+            fetch(`${endpoint}?duration=${duration}`)
                 .then(response => {
                     if (!response.ok) {
                         throw new Error(`HTTP ${response.status}: ${response.statusText}`);
@@ -755,12 +783,13 @@ static const char HEAP_SVG_VIEWER_PAGE[] = R"HTML(
 
         const urlParams = new URLSearchParams(window.location.search);
         const outputType = urlParams.get('output_type') || 'pprof';
+        const duration = urlParams.get('duration') || '1';
 
         function loadSVG() {
             document.getElementById('svg-container').innerHTML = '正在加载Heap火焰图...';
 
-            // Heap分析传递output_type参数
-            fetch(`/api/heap/analyze?output_type=${outputType}`)
+            // Heap分析传递 output_type 与采集窗口
+            fetch(`/api/heap/analyze?output_type=${outputType}&duration=${duration}`)
                 .then(response => {
                     const contentType = response.headers.get('Content-Type');
                     if (contentType && contentType.includes('json')) {
diff --git a/tests/test_http_handlers.cpp b/tests/test_http_handlers.cpp
index 6f29cdd..f2c1fa3 100644
--- a/tests/test_http_handlers.cpp
+++ b/tests/test_http_handlers.cpp
@@ -288,11 +288,11 @@ TEST(HostOwnedSessionTest, HeapAnalysisRefusesToTakeOverAHostSession) {
     ASSERT_TRUE(profiler.startHeapProfiler("/tmp/test_host_owned_heap.prof"));
     ASSERT_TRUE(profiler.isProfilerRunning(profiler::ProfilerType::HEAP));
 
-    auto result = profiler.analyzeHeapProfile("pprof");
+    auto result = profiler.analyzeHeapProfile(1, "pprof");
     EXPECT_NE(result.find("heap profiling already in use"), std::string::npos) << result;
     EXPECT_TRUE(profiler.isProfilerRunning(profiler::ProfilerType::HEAP));
 
-    EXPECT_EQ(handlers.handleHeapAnalyze("pprof").status, 409);
+    EXPECT_EQ(handlers.handleHeapAnalyze(1, "pprof").status, 409);
 
     EXPECT_TRUE(profiler.stopHeapProfiler());
 }
@@ -311,7 +311,7 @@ class HeapAnalysisHolder {
 public:
     explicit HeapAnalysisHolder(profiler::ProfilerManager& profiler)
         : future_(std::async(std::launch::async,
-                             [&profiler]() -> std::string { return profiler.analyzeHeapProfile("pprof"); })) {}
+                             [&profiler]() -> std::string { return profiler.analyzeHeapProfile(1, "pprof"); })) {}
 
     ~HeapAnalysisHolder() {
         if (future_.valid()) {
@@ -352,7 +352,7 @@ TEST(ConcurrentHeapAnalysisTest, SecondAnalysisIsRejectedNotRaced) {
 
     // Must be refused immediately, and must not touch the running analysis.
     const auto t0 = std::chrono::steady_clock::now();
-    auto result = profiler.analyzeHeapProfile("pprof");
+    auto result = profiler.analyzeHeapProfile(1, "pprof");
     const auto elapsed = std::chrono::steady_clock::now() - t0;
 
     EXPECT_NE(result.find("heap profiling already in use"), std::string::npos) << result;
@@ -367,7 +367,7 @@ TEST(ConcurrentHeapAnalysisTest, HandlerReportsConflict) {
     HeapAnalysisHolder holder{profiler};
     ASSERT_TRUE(waitForHeapClaim(profiler));
 
-    auto resp = handlers.handleHeapAnalyze("pprof");
+    auto resp = handlers.handleHeapAnalyze(1, "pprof");
 
     EXPECT_EQ(resp.status, 409);
     EXPECT_NE(resp.body.find("heap profiling already in use"), std::string::npos) << resp.body;
@@ -389,17 +389,27 @@ TEST(ConcurrentHeapAnalysisTest, ClaimIsReleasedAfterwards) {
 // Heap analysis API shape
 // ---------------------------------------------------------------------------
 
-TEST_F(HttpHandlersTest, HeapAnalysisHasNoDurationParameter) {
-    // Regression guard: heap profiling is allocation driven, so no duration is
-    // accepted. This must stay compilable with a single argument.
-    // (If a duration parameter were reintroduced this call would not compile.)
+TEST_F(HttpHandlersTest, HeapAnalysisTakesACollectionWindow) {
+    // Heap analysis takes a duration, but it is a *collection window*, not a
+    // sampling rate: the rate is fixed by TCMALLOC_SAMPLE_PARAMETER at process
+    // start. A longer window covers more allocations, which is what a sparsely
+    // allocating process needs. Guard the contract so the distinction cannot
+    // silently regress into "duration is accepted but ignored".
     static_assert(std::is_invocable_v<decltype(&profiler::ProfilerHttpHandlers::handleHeapAnalyze),
-                                      profiler::ProfilerHttpHandlers*, const std::string&>,
-                  "handleHeapAnalyze must take only output_type");
+                                      profiler::ProfilerHttpHandlers*, int, const std::string&>,
+                  "handleHeapAnalyze must take (duration, output_type)");
+
+    // The renderers take one too, since each runs its own sampling window.
+    static_assert(std::is_invocable_v<decltype(&profiler::ProfilerHttpHandlers::handleHeapSvgRaw),
+                                      profiler::ProfilerHttpHandlers*, int>,
+                  "handleHeapSvgRaw must take a duration");
+    static_assert(std::is_invocable_v<decltype(&profiler::ProfilerHttpHandlers::handleHeapFlamegraphRaw),
+                                      profiler::ProfilerHttpHandlers*, int>,
+                  "handleHeapFlamegraphRaw must take a duration");
 }
 
 TEST_F(HttpHandlersTest, HeapAnalyzeRejectsInvalidOutputType) {
-    auto resp = handlers.handleHeapAnalyze("bogus");
+    auto resp = handlers.handleHeapAnalyze(1, "bogus");
     EXPECT_EQ(resp.status, 400);
 }
 
@@ -494,7 +504,7 @@ TEST(ProfilerLifecycleTest, StaleHeapProfileIsNotReused) {
         }
     });
 
-    (void)profiler.analyzeHeapProfile("pprof");
+    (void)profiler.analyzeHeapProfile(1, "pprof");
     const auto afterFirst = heapFiles();
 
     auto newSince = [&](const std::set<std::string>& a, const std::set<std::string>& b) {

From d6a432810a4ccd64d9d4d5fedc3952480d565b19 Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Mon, 14 Sep 2026 06:46:22 +0800
Subject: [PATCH 04/21] feat(heap): let the graph endpoints render the
 state-based snapshot too
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The panel could show the live heap only as raw profile text. The rendering path
for it already existed -- both heap renderers shell out to the embedded pprof --
but they always obtained their input from a collection window, so there was no
way to draw the state-based view even though the API to fetch it existed. A
graph of "what is in the heap right now" was reachable only by exporting the
profile and running a separate tool.

Both renderers now take a source selector, exposed as ?source=state:

  /api/heap/svg_raw?source=state              current heap, pprof renderer
  /api/heap/flamegraph_raw?source=state       current heap, FlameGraph renderer
  /api/heap/svg_raw?duration=N                collection window (default)

They share one heapSampleForSource() helper, so choosing a source is a single
decision rather than two divergent code paths, and a core {"error": ...} reply
is now unwrapped instead of being mistaken for profile text. The failure message
also depends on the source: the state path points at TCMALLOC_SAMPLE_PARAMETER,
the window path no longer claims a variable it does not use (a leftover from
when it pulled GetHeapSample()).

Panel: the two heap cards are merged into one with a 数据源 dropdown, since the
mechanism is what varies, not the buttons. Choosing 状态式 hides the collection
window (meaningless there), explains that the view reflects resident memory,
and keeps all four actions working -- 查看图表, 下载图表, 查看原始 profile and
下载 profile 文本. analyzeHeap() redirects to the graph view when the state
source is selected, because /api/heap/analyze only performs a window collection.
Query assembly lives in one heapQuery() helper used by every action.

Verified live: with sampling enabled, both ?source=state endpoints return SVG
(18767 and 16031 bytes) and the window form still works; the page carries the
selector and all ten heap functions, and the extracted script passes
node --check. New tests assert both renderers accept (duration, state_based) and
that only the state path blames the sampling variable.
---
 CHANGELOG.md                     |  1 +
 README.md                        | 16 +++---
 include/profiler/http_handlers.h | 18 ++++---
 src/drogon_adapter.cpp           |  5 +-
 src/http_handlers.cpp            | 41 ++++++++++-----
 src/web_resources.cpp            | 85 +++++++++++++++++++++-----------
 tests/test_http_handlers.cpp     | 52 ++++++++++++++++---
 7 files changed, 158 insertions(+), 60 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8f7d566..999ec26 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Breaking:** core library decoupled from the web layer — `profiler_core` (no Drogon) and `profiler_web` (optional Drogon adapter) are now separate targets
 - **Breaking:** `analyzeHeapProfile()` takes `(duration, output_type)` again, and `handleHeapAnalyze` / `handleHeapSvgRaw` / `handleHeapFlamegraphRaw` all take a duration. This reverses an earlier removal that was right about the *sampling rate* but wrong to conclude the window is meaningless: gperftools fixes the rate via `TCMALLOC_SAMPLE_PARAMETER` at process start, so `duration` cannot improve precision, but it does decide **how long allocations are collected**. A process that allocates sparsely needs a longer window to produce anything, and a hard-coded 1s gave it no recourse. Default 1s, clamped 1-300s.
 - `/api/heap/svg_raw` and `/api/heap/flamegraph_raw` now run their own sampling window (`getRawHeapProfileSample()`) instead of pulling `GetHeapSample()`. Besides honouring the duration, this makes them work in a process started without `TCMALLOC_SAMPLE_PARAMETER`, which previously made `/api/heap/svg_raw` fail with 500 while its sibling `/api/heap/flamegraph_raw` succeeded on the same input. The three window-based endpoints now behave identically.
+- Both heap renderers accept `?source=state` to draw the state-based snapshot instead, so the cumulative heap view can be rendered as a chart rather than only exported as text. Previously the graph endpoints could only draw a collection window, which meant the panel had no way to show the live heap visually even though the rendering path existed.
 - **Breaking:** removed the never-implemented `ProfilerHttpHandlers::dispatch()` declaration; route registration stays with the host framework
 - **The Drogon adapter no longer runs profiling on the event-loop thread.** Every handler that can block — CPU/heap/growth analysis, the `_raw` renderers, and `/pprof/profile` — is dispatched to a background worker and its response is handed back with `queueInLoop()`. Profiling takes seconds (up to 300s for CPU), so this previously stalled all other requests, including `/api/status`, for the whole sampling window.
 - Blocking jobs share one worker thread. This is required for correctness, not just throughput: gperftools keeps its profiling session in process-global state, so concurrent analyses would corrupt each other's results.
diff --git a/README.md b/README.md
index 6f0fc5e..e0a2ef9 100644
--- a/README.md
+++ b/README.md
@@ -324,10 +324,10 @@ profiler.setLogLevel(profiler::LogLevel::Debug);
 | `/api/growth/analyze` | GET | 返回 Heap Growth 图 |
 | **原始 SVG 下载** | | |
 | `/api/cpu/svg_raw` | GET | pprof 生成的 CPU SVG；`?duration=N` 默认 10 |
-| `/api/heap/svg_raw` | GET | **窗口式**：pprof 渲染的 Heap SVG；`?duration=N` 默认 1 |
+| `/api/heap/svg_raw` | GET | Heap SVG（pprof 渲染）；`?duration=N` 默认 1；`?source=state` 改为渲染**当前堆快照** |
 | `/api/growth/svg_raw` | GET | pprof 生成的 Growth SVG |
 | `/api/cpu/flamegraph_raw` | GET | FlameGraph 渲染的 CPU SVG；`?duration=N` 默认 10 |
-| `/api/heap/flamegraph_raw` | GET | **窗口式**：FlameGraph 渲染的 Heap SVG；`?duration=N` 默认 1 |
+| `/api/heap/flamegraph_raw` | GET | Heap SVG（FlameGraph 渲染）；`?duration=N` 默认 1；`?source=state` 同上 |
 | `/api/growth/flamegraph_raw` | GET | FlameGraph 渲染的 Growth SVG |
 | **线程分析** | | |
 | `/api/thread/stacks` | GET | 所有线程的调用栈 |
@@ -422,11 +422,15 @@ tcmalloc 在**进程初始化时**读取该变量，因此必须在启动前用
 `duration` 只决定**采集多久**。分配稀疏的进程需要更长的窗口才能采到东西，所以它是"覆盖度"参数
 而不是"精度"参数。默认 1 秒，范围 1–300。
 
-Web 控制面板的 Heap 区把两者分成了两张卡片：
+Web 控制面板的 Heap 区用一个**数据源**下拉在两套机制间切换，两者都能出图：
 
-- **窗口式**（可选采集窗口 + 图表类型）—— 三个按钮分别走 `/api/heap/analyze`（内嵌查看）、
-  以及 `/api/heap/{svg_raw,flamegraph_raw}`（查看/下载）
-- **状态式：当前堆的累计快照** —— `GET /pprof/heap`（可查看/下载，需 `TCMALLOC_SAMPLE_PARAMETER`）
+| 数据源 | 图表接口 | 说明 |
+|--------|----------|------|
+| 窗口式 | `/api/heap/{svg_raw,flamegraph_raw}?duration=N` | 采集 N 秒后渲染 |
+| 状态式 | `/api/heap/{svg_raw,flamegraph_raw}?source=state` | 渲染当前堆累计快照（对应 `/pprof/heap`） |
+
+面板提供「🔍 查看图表」「📥 下载图表 (SVG)」，以及「📄 查看原始 profile」「📥 下载 profile 文本」
+（后者走 `/pprof/heap`，用于交给 `go tool pprof` 分析）。
 
 ### 依赖版本
 
diff --git a/include/profiler/http_handlers.h b/include/profiler/http_handlers.h
index ce6a6bc..cc905d3 100644
--- a/include/profiler/http_handlers.h
+++ b/include/profiler/http_handlers.h
@@ -103,13 +103,19 @@ class ProfilerHttpHandlers {
     ///        process start -- but a longer window covers more allocations.
     HandlerResponse handleHeapAnalyze(int duration, const std::string& output_type);
 
-    /// @brief Render the current heap sample with the pprof script
+    /// @brief Render a heap sample with the pprof script
+    /// @param duration Collection window in seconds (clamped 1..300); used only
+    ///        when @p state_based is false
+    /// @param state_based Which of the two heap sources to render:
+    ///        - false (default): run a collection window, no startup config needed
+    ///        - true: render tcmalloc's cumulative snapshot of the live heap
+    ///          (getRawHeapSample()), which requires TCMALLOC_SAMPLE_PARAMETER
+    HandlerResponse handleHeapSvgRaw(int duration, bool state_based = false);
+
+    /// @brief Render a heap sample as a FlameGraph
     /// @param duration Collection window in seconds (clamped 1..300)
-    HandlerResponse handleHeapSvgRaw(int duration);
-
-    /// @brief Render the current heap sample as a FlameGraph
-    /// @param duration Collection window in seconds (clamped 1..300)
-    HandlerResponse handleHeapFlamegraphRaw(int duration);
+    /// @param state_based See @ref handleHeapSvgRaw
+    HandlerResponse handleHeapFlamegraphRaw(int duration, bool state_based = false);
 
     // --- Growth endpoints ---
     HandlerResponse handleGrowthAnalyze(const std::string& output_type);
diff --git a/src/drogon_adapter.cpp b/src/drogon_adapter.cpp
index bee00b2..2660ae2 100644
--- a/src/drogon_adapter.cpp
+++ b/src/drogon_adapter.cpp
@@ -329,8 +329,11 @@ void registerDrogonHandlers(profiler::ProfilerManager& profiler) {
                         duration = std::stoi(dp);
                     } catch (...) {}
                 }
+                // source=state renders tcmalloc's cumulative snapshot of the
+                // live heap instead of running a collection window.
+                const bool state_based = req->getParameter("source") == "state";
                 runAsync(executor, req, std::move(callback),
-                         [handlers, fn, duration]() { return ((*handlers).*fn)(duration); });
+                         [handlers, fn, duration, state_based]() { return ((*handlers).*fn)(duration, state_based); });
             },
             {drogon::Get});
     };
diff --git a/src/http_handlers.cpp b/src/http_handlers.cpp
index 821c5b9..8d27fe0 100644
--- a/src/http_handlers.cpp
+++ b/src/http_handlers.cpp
@@ -234,14 +234,29 @@ HandlerResponse ProfilerHttpHandlers::handleHeapAnalyze(int duration, const std:
     return HandlerResponse::svg(svg);
 }
 
-HandlerResponse ProfilerHttpHandlers::handleHeapSvgRaw(int duration) {
+/// The sample text the heap renderers should draw.
+///
+/// Two sources exist and they answer different questions, so the caller picks:
+///  - @p state_based: getRawHeapSample(), tcmalloc's cumulative snapshot of what
+///    is currently in the heap. Needs TCMALLOC_SAMPLE_PARAMETER at process start.
+///  - otherwise: getRawHeapProfileSample(), which runs its own collection window
+///    of @p duration seconds and needs no startup configuration.
+///
+/// Returns a {"error": ...} JSON string when the source could not produce data.
+static std::string heapSampleForSource(profiler::ProfilerManager& profiler, bool state_based, int duration) {
+    return state_based ? profiler.getRawHeapSample() : profiler.getRawHeapProfileSample(duration);
+}
+
+HandlerResponse ProfilerHttpHandlers::handleHeapSvgRaw(int duration, bool state_based) {
     duration = clampDuration(duration, 1, 300);
-    // Use the active sampler so the caller's window is honoured, and so this
-    // works in processes started without TCMALLOC_SAMPLE_PARAMETER -- the same
-    // mechanism the analyze endpoint uses.
-    std::string heap_sample = profiler_.getRawHeapProfileSample(duration);
+
+    std::string heap_sample = heapSampleForSource(profiler_, state_based, duration);
+    if (internal::isJsonError(heap_sample)) {
+        return errorResp(500, internal::jsonErrorMessage(heap_sample));
+    }
     if (heap_sample.empty()) {
-        return errorResp(500, "Failed to get heap sample. Make sure TCMALLOC_SAMPLE_PARAMETER is set.");
+        return errorResp(500, state_based ? "Failed to get heap sample. Make sure TCMALLOC_SAMPLE_PARAMETER is set."
+                                          : "Failed to collect a heap sample in the requested window.");
     }
 
     std::string temp_file = "/tmp/heap_raw.prof";
@@ -270,14 +285,16 @@ HandlerResponse ProfilerHttpHandlers::handleHeapSvgRaw(int duration) {
     return resp;
 }
 
-HandlerResponse ProfilerHttpHandlers::handleHeapFlamegraphRaw(int duration) {
+HandlerResponse ProfilerHttpHandlers::handleHeapFlamegraphRaw(int duration, bool state_based) {
     duration = clampDuration(duration, 1, 300);
-    // Use the active sampler so the caller's window is honoured, and so this
-    // works in processes started without TCMALLOC_SAMPLE_PARAMETER -- the same
-    // mechanism the analyze endpoint uses.
-    std::string heap_sample = profiler_.getRawHeapProfileSample(duration);
+
+    std::string heap_sample = heapSampleForSource(profiler_, state_based, duration);
+    if (internal::isJsonError(heap_sample)) {
+        return errorResp(500, internal::jsonErrorMessage(heap_sample));
+    }
     if (heap_sample.empty()) {
-        return errorResp(500, "Failed to get heap sample. Make sure TCMALLOC_SAMPLE_PARAMETER is set.");
+        return errorResp(500, state_based ? "Failed to get heap sample. Make sure TCMALLOC_SAMPLE_PARAMETER is set."
+                                          : "Failed to collect a heap sample in the requested window.");
     }
 
     std::string temp_file = "/tmp/heap_raw.prof";
diff --git a/src/web_resources.cpp b/src/web_resources.cpp
index 70f4c3d..5c67355 100644
--- a/src/web_resources.cpp
+++ b/src/web_resources.cpp
@@ -211,12 +211,14 @@ static const char INDEX_PAGE[] = R"HTML(
         <div class="section">
             <h2>Heap Profiler</h2>
             <div class="card">
-                <h3>窗口式：采集一段时间内的分配</h3>
-                <span class="hint">
-                    ⚠️ 只记录<b>采集窗口内发生的分配</b>，不反映此刻已经在堆里的内存。若进程内存虽高但已停止分配，
-                    结果会是空的（返回 "No heap profile data was produced"）。分配稀疏时把窗口调长一些。
-                </span>
                 <div class="input-group">
+                    <label for="heap-source">数据源:</label>
+                    <select id="heap-source" onchange="onHeapSourceChange()">
+                        <option value="window">窗口式：采集一段时间内的分配</option>
+                        <option value="state">状态式：当前堆的累计快照</option>
+                    </select>
+                </div>
+                <div class="input-group" id="heap-duration-group">
                     <label for="heap-duration">采集窗口(秒):</label>
                     <input type="number" id="heap-duration" value="1" min="1" max="300">
                 </div>
@@ -227,20 +229,11 @@ static const char INDEX_PAGE[] = R"HTML(
                         <option value="flamegraph">FlameGraph (Brendan Gregg)</option>
                     </select>
                 </div>
-                <button class="analyze-btn" onclick="analyzeHeap()">⚡ 一键分析并生成Heap火焰图</button>
+                <span class="hint" id="heap-source-hint"></span>
                 <button class="view-btn" onclick="viewHeapChart()">🔍 查看图表</button>
-                <button class="download-btn" id="heap-download-btn" onclick="downloadHeapChart()">📥 下载 Heap 图表 (SVG)</button>
-            </div>
-            <div class="card">
-                <h3>状态式：当前堆的累计快照</h3>
-                <span class="hint">
-                    对应 <code>GET /pprof/heap</code>，返回 tcmalloc 的累计采样，反映<b>堆里现存的内存</b>
-                    ——与上面的"1 秒内分配"是两套机制，结果不同属正常。
-                    <b>需要</b>在进程启动前设置 <code>TCMALLOC_SAMPLE_PARAMETER</code>，否则返回 500。
-                    下载后可用 <code>go tool pprof ./your_app heap.prof</code> 分析。
-                </span>
-                <button class="view-btn" onclick="viewHeapProfile()">🔍 查看当前堆快照</button>
-                <button class="download-btn" id="heap-profile-btn" onclick="downloadHeapProfile()">📥 下载 heap.prof</button>
+                <button class="download-btn" id="heap-download-btn" onclick="downloadHeapChart()">📥 下载图表 (SVG)</button>
+                <button class="view-btn" id="heap-raw-btn" onclick="viewHeapProfile()">📄 查看原始 profile</button>
+                <button class="download-btn" id="heap-profile-btn" onclick="downloadHeapProfile()">📥 下载 profile 文本</button>
             </div>
         </div>
 
@@ -289,10 +282,15 @@ static const char INDEX_PAGE[] = R"HTML(
         }
 
         function analyzeHeap() {
+            if (heapSource() === 'state') {
+                // 状态式由 /pprof/heap 提供，走 *_raw 端点渲染（查看图表按钮）
+                log('💡 状态式数据源请用「🔍 查看图表」——/api/heap/analyze 只做窗口式采集。');
+                viewHeapChart();
+                return;
+            }
             const chartType = document.getElementById('heap-chart-type').value;
             const duration = heapDuration();
             log(`🚀 正在获取Heap火焰图 (图表类型: ${chartType}, 采集窗口: ${duration}秒)...`);
-            // 打开独立的SVG查看器页面，传递 output_type 与 duration 参数
             window.open(`/show_heap_svg.html?output_type=${chartType}&duration=${duration}`, '_blank');
             log('✅ Heap火焰图查看器已在新标签页打开');
             log(`💡 提示：当前使用 ${chartType === 'flamegraph' ? 'Brendan Gregg FlameGraph' : 'pprof SVG'}`);
@@ -307,6 +305,9 @@ static const char INDEX_PAGE[] = R"HTML(
             log(`💡 提示：当前使用 ${chartType === 'flamegraph' ? 'Brendan Gregg FlameGraph' : 'pprof SVG'}`);
         }
 
+        // 页面载入时渲染当前数据源的说明
+        document.addEventListener('DOMContentLoaded', onHeapSourceChange);
+
         function log(message) {
             const output = document.getElementById('output');
             output.textContent = message;
@@ -342,7 +343,7 @@ static const char INDEX_PAGE[] = R"HTML(
             }, 1000);
 
             // 使用 fetch 下载文件
-            fetch(`${endpoint}?duration=${duration}`)
+            fetch(`${endpoint}?${heapQuery()}`)
                 .then(response => {
                     if (!response.ok) {
                         throw new Error(`HTTP ${response.status}: ${response.statusText}`);
@@ -377,26 +378,54 @@ static const char INDEX_PAGE[] = R"HTML(
                 });
         }
 
-        // 窗口式：图表类型 → 渲染端点。analyze 端点返回 SVG 供内嵌查看，
-        // 两个 *_raw 端点返回可下载的 SVG（同样的采样，只是渲染器不同）。
+        // 图表类型 → 渲染端点。两个 *_raw 端点都支持 source 参数选择数据源，
+        // 因此"状态式"也能出图，而不是只能看原始文本。
         function heapChartEndpoint(chartType) {
             return chartType === 'flamegraph' ? '/api/heap/flamegraph_raw' : '/api/heap/svg_raw';
         }
 
+        function heapSource() {
+            return document.getElementById('heap-source').value;
+        }
+
         function heapDuration() {
             const v = parseInt(document.getElementById('heap-duration').value, 10);
             return Number.isFinite(v) && v >= 1 ? Math.min(v, 300) : 1;
         }
 
-        // 与"下载"按钮走同样的端点，只是把结果展示出来而不是保存
+        const HEAP_SOURCE_HINTS = {
+            window: '⚠️ 只记录<b>采集窗口内发生的分配</b>，不反映此刻已经在堆里的内存。若进程内存虽高但已停止分配，' +
+                    '结果会是空的。分配稀疏时把窗口调长一些。<b>无需</b>启动前设置采样变量。',
+            state: '📌 反映<b>堆里现存的内存</b>（tcmalloc 累计采样），与"窗口内分配"是两套机制，结果不同属正常。' +
+                   '<b>需要</b>在进程启动前设置 <code>TCMALLOC_SAMPLE_PARAMETER</code>，否则返回 500。' +
+                   '刚启动进程时可能显示 <code>0: 0 [0: 0]</code>——那是采样尚未累计，稍等再试即可。'
+        };
+
+        function onHeapSourceChange() {
+            const state = heapSource() === 'state';
+            // 采集窗口只对窗口式有意义
+            document.getElementById('heap-duration-group').style.display = state ? 'none' : '';
+            document.getElementById('heap-source-hint').innerHTML = HEAP_SOURCE_HINTS[heapSource()];
+        }
+
+        // 组装一次请求所需的查询串
+        function heapQuery() {
+            const p = new URLSearchParams();
+            p.set('duration', String(heapDuration()));
+            if (heapSource() === 'state') p.set('source', 'state');
+            return p.toString();
+        }
+
         function viewHeapChart() {
             const chartType = document.getElementById('heap-chart-type').value;
-            const duration = heapDuration();
             const endpoint = heapChartEndpoint(chartType);
-            log(`🚀 正在渲染 Heap ${chartType} 图表 (采集窗口 ${duration} 秒)...`);
-            window.open(`${endpoint}?duration=${duration}`, '_blank');
-            log(`✅ 已在新标签页打开 ${endpoint}?duration=${duration}\n` +
-                `   提示：该端点会在服务端采集 ${duration} 秒后再渲染，标签页会稍等片刻。`);
+            const url = `${endpoint}?${heapQuery()}`;
+            const state = heapSource() === 'state';
+            log(`🚀 正在渲染 Heap ${chartType} 图表（数据源: ${state ? '当前堆快照' : '窗口 ' + heapDuration() + ' 秒'}）...`);
+            window.open(url, '_blank');
+            log(`✅ 已在新标签页打开 ${url}\n` +
+                (state ? '   数据来自 /pprof/heap，需已设置 TCMALLOC_SAMPLE_PARAMETER。'
+                       : `   服务端会先采集 ${heapDuration()} 秒再渲染，标签页会稍等片刻。`));
         }
 
         // 状态式 heap 快照（/pprof/heap）：与上面的窗口式分析是两套机制。
diff --git a/tests/test_http_handlers.cpp b/tests/test_http_handlers.cpp
index f2c1fa3..8ce87bc 100644
--- a/tests/test_http_handlers.cpp
+++ b/tests/test_http_handlers.cpp
@@ -399,13 +399,9 @@ TEST_F(HttpHandlersTest, HeapAnalysisTakesACollectionWindow) {
                                       profiler::ProfilerHttpHandlers*, int, const std::string&>,
                   "handleHeapAnalyze must take (duration, output_type)");
 
-    // The renderers take one too, since each runs its own sampling window.
-    static_assert(std::is_invocable_v<decltype(&profiler::ProfilerHttpHandlers::handleHeapSvgRaw),
-                                      profiler::ProfilerHttpHandlers*, int>,
-                  "handleHeapSvgRaw must take a duration");
-    static_assert(std::is_invocable_v<decltype(&profiler::ProfilerHttpHandlers::handleHeapFlamegraphRaw),
-                                      profiler::ProfilerHttpHandlers*, int>,
-                  "handleHeapFlamegraphRaw must take a duration");
+    // The renderers take one too, since each can run its own sampling window.
+    // Their full signature (duration, state_based) is asserted separately in
+    // HeapRenderersCanDrawEitherSource.
 }
 
 TEST_F(HttpHandlersTest, HeapAnalyzeRejectsInvalidOutputType) {
@@ -413,6 +409,48 @@ TEST_F(HttpHandlersTest, HeapAnalyzeRejectsInvalidOutputType) {
     EXPECT_EQ(resp.status, 400);
 }
 
+TEST_F(HttpHandlersTest, HeapRenderersCanDrawEitherSource) {
+    // Both renderers must be invocable for either heap source, so the UI can
+    // offer a graph for the state-based snapshot too -- not only the raw text.
+    using H = profiler::ProfilerHttpHandlers;
+
+    auto svg = static_cast<profiler::HandlerResponse (H::*)(int, bool)>(&H::handleHeapSvgRaw);
+    EXPECT_TRUE((std::is_invocable_v<decltype(svg), H*, int, bool>));
+
+    auto fg = static_cast<profiler::HandlerResponse (H::*)(int, bool)>(&H::handleHeapFlamegraphRaw);
+    EXPECT_TRUE((std::is_invocable_v<decltype(fg), H*, int, bool>));
+}
+
+TEST_F(HttpHandlersTest, StateBasedRenderingReportsTheMissingSamplingVariable) {
+    // The two sources fail differently, and the message must say which one was
+    // asked for: the state-based path needs TCMALLOC_SAMPLE_PARAMETER before
+    // process start, the window-based one does not need it at all.
+    //
+    // These tests run without that variable set, so getRawHeapSample() yields
+    // nothing while the window path can still collect.
+    profiler::ProfilerManager plain;
+
+    ASSERT_TRUE(plain.getRawHeapSample().empty()) << "precondition: sampling is off in the test process";
+
+    profiler::ProfilerHttpHandlers h(plain);
+    auto state = h.handleHeapSvgRaw(1, /*state_based=*/true);
+    EXPECT_EQ(state.status, 500);
+    EXPECT_NE(state.body.find("TCMALLOC_SAMPLE_PARAMETER"), std::string::npos) << state.body;
+}
+
+TEST_F(HttpHandlersTest, WindowBasedRenderingDoesNotMentionTheVariable) {
+    profiler::ProfilerManager plain;
+    profiler::ProfilerHttpHandlers h(plain);
+
+    // Duration is clamped, and the window path must not blame the environment
+    // variable it does not depend on.
+    auto resp = h.handleHeapSvgRaw(0, /*state_based=*/false);
+    if (resp.status == 500) {
+        EXPECT_EQ(resp.body.find("TCMALLOC_SAMPLE_PARAMETER"), std::string::npos)
+            << "window-based failure must not blame a variable it does not need: " << resp.body;
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Profiler lifecycle
 // ---------------------------------------------------------------------------

From dd01bf94c34294b83148da154ac99d945379912c Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Mon, 14 Sep 2026 06:55:41 +0800
Subject: [PATCH 05/21] fix(web): make the chart actions work and stop hiding
 empty renders
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reported as "下载图表 does nothing". Investigating turned up four separate
defects in the heap chart path, three of them affecting more than the button.

1. The download built its URL from duration alone, dropping source=state. With
   状态式 selected it silently fetched and saved a *window* collection -- a wrong
   result rather than a visible failure. Both actions now share one
   fetchHeapChart(), so they cannot diverge again.

2. The download never inserted its <a> into the DOM before click(). A detached
   anchor works in some browsers and not others, which matches "no response".
   The same omission existed in the CPU and growth downloads (my
   downloadHeapProfile had always done it correctly); all four now attach.

3. 查看图表 relied on window.open() of an endpoint that sets
   Content-Disposition: attachment, so it downloaded instead of displaying --
   which is why it looked like a duplicate of the download button. It now opens
   a blob URL, where that header does not apply, so the SVG is actually shown,
   and it reports the server's error text on failure instead of a bare status.

4. handleHeapSvgRaw called `pprof --svg` with pprof's default --inuse_space.
   A collection window usually catches allocations that are already freed, so
   the in-use column is empty and the render fails with "No nodes to print" --
   ?duration=1 returned 500 while the identical sample rendered fine as a flame
   graph (which plots cumulative allocation). It now uses --alloc_space, and
   ?duration=1 returns a 23KB graph. Its failure message also includes pprof's
   output rather than a bare "Failed to generate SVG".

While fixing the last one: four handlers inline flamegraph.pl and each had only
the weak <?xml/<svg check, so flamegraph.pl's "valid SVG whose only content is
ERROR: ..." reached callers as a 200 graph. An earlier fix had added the ERROR
check to generateFlameGraph() only. All four now call a shared
flameGraphResponse(); ?duration=1 on the flamegraph endpoint now returns 500
explaining that no stack samples were collected instead of a 579-byte SVG
reading "ERROR: No valid input provided to flamegraph.pl."

Verified on a live server: svg_raw renders at duration 1 and 3, flamegraph_raw
renders at 3 and reports a clear 500 at 1, and both ?source=state forms render.
The page script passes node --check. ROADMAP already carried the "map --svg
failures swallow the renderer's stderr" item; the heap svg path is now fixed,
the CPU path (profiler_manager.cpp) still needs it.
---
 CHANGELOG.md          |  4 +++
 src/http_handlers.cpp | 60 +++++++++++++++++++++++++++++++------------
 src/web_resources.cpp | 24 +++++++++--------
 3 files changed, 61 insertions(+), 27 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 999ec26..68e5bb8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,6 +26,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Breaking:** `analyzeHeapProfile()` takes `(duration, output_type)` again, and `handleHeapAnalyze` / `handleHeapSvgRaw` / `handleHeapFlamegraphRaw` all take a duration. This reverses an earlier removal that was right about the *sampling rate* but wrong to conclude the window is meaningless: gperftools fixes the rate via `TCMALLOC_SAMPLE_PARAMETER` at process start, so `duration` cannot improve precision, but it does decide **how long allocations are collected**. A process that allocates sparsely needs a longer window to produce anything, and a hard-coded 1s gave it no recourse. Default 1s, clamped 1-300s.
 - `/api/heap/svg_raw` and `/api/heap/flamegraph_raw` now run their own sampling window (`getRawHeapProfileSample()`) instead of pulling `GetHeapSample()`. Besides honouring the duration, this makes them work in a process started without `TCMALLOC_SAMPLE_PARAMETER`, which previously made `/api/heap/svg_raw` fail with 500 while its sibling `/api/heap/flamegraph_raw` succeeded on the same input. The three window-based endpoints now behave identically.
 - Both heap renderers accept `?source=state` to draw the state-based snapshot instead, so the cumulative heap view can be rendered as a chart rather than only exported as text. Previously the graph endpoints could only draw a collection window, which meant the panel had no way to show the live heap visually even though the rendering path existed.
+- `handleHeapSvgRaw` renders with `pprof --alloc_space` rather than the default `--inuse_space`. pprof's default plots what is live *now*, so a short collection window -- whose allocations have usually already been freed -- produced a profile with an empty in-use column and the render failed with "No nodes to print" even though the window recorded real allocations. Measured: `?duration=1` went from 500 to a 23KB graph.
+- All four flame-graph handlers share one validator (`flameGraphResponse`). flamegraph.pl answers unusable input with a *valid* SVG whose only content is an "ERROR: ..." message, so the structural `<?xml`/`<svg` check passed and a 200 carrying an error text reached callers as if it were a graph. An earlier fix had added the check to `generateFlameGraph()` only; the handlers that inline the command still had the weak check.
+- The panel's chart download now requests the same data as the chart view. It built its URL from `duration` alone and dropped `source=state`, so with the state source selected it silently downloaded a window collection instead. Both actions now share `fetchHeapChart()`, and viewing opens a blob URL so the SVG is displayed rather than downloaded (`Content-Disposition` does not apply to blobs).
+- All four download actions insert their `<a>` into the DOM before clicking it; the heap/CPU/growth chart downloads never did, which leaves the click unreliable in browsers that require attachment.
 - **Breaking:** removed the never-implemented `ProfilerHttpHandlers::dispatch()` declaration; route registration stays with the host framework
 - **The Drogon adapter no longer runs profiling on the event-loop thread.** Every handler that can block — CPU/heap/growth analysis, the `_raw` renderers, and `/pprof/profile` — is dispatched to a background worker and its response is handed back with `queueInLoop()`. Profiling takes seconds (up to 300s for CPU), so this previously stalled all other requests, including `/api/status`, for the whole sampling window.
 - Blocking jobs share one worker thread. This is required for correctness, not just throughput: gperftools keeps its profiling session in process-global state, so concurrent analyses would corrupt each other's results.
diff --git a/src/http_handlers.cpp b/src/http_handlers.cpp
index 8d27fe0..8918235 100644
--- a/src/http_handlers.cpp
+++ b/src/http_handlers.cpp
@@ -151,6 +151,28 @@ HandlerResponse ProfilerHttpHandlers::handleCpuSvgRaw(int duration) {
     return resp;
 }
 
+/// Convert flamegraph.pl output into a response, or an error.
+///
+/// flamegraph.pl answers unusable input with a *valid* SVG whose only content is
+/// an "ERROR: ..." message, so a structural check for <?xml or <svg passes and a
+/// 200 carrying an error reaches the caller as if it were a graph. Four handlers
+/// render flame graphs, so the check lives here rather than being repeated (and
+/// forgotten) at each call site.
+static HandlerResponse flameGraphResponse(const std::string& svg) {
+    if (svg.find("<?xml") == std::string::npos && svg.find("<svg") == std::string::npos) {
+        return errorResp(500, "Failed to generate FlameGraph");
+    }
+    if (auto pos = svg.find("ERROR:"); pos != std::string::npos) {
+        auto end = svg.find('<', pos);
+        std::string message = svg.substr(pos, end == std::string::npos ? std::string::npos : end - pos);
+        return errorResp(500, "No stack samples to render (profile is empty). The sample window may have "
+                              "been too short or the process idle; increase the duration or sample under "
+                              "load. flamegraph.pl said: " +
+                                  message);
+    }
+    return HandlerResponse::svg(svg);
+}
+
 HandlerResponse ProfilerHttpHandlers::handleCpuFlamegraphRaw(int duration) {
     duration = clampDuration(duration, 1, 300);
 
@@ -200,8 +222,11 @@ HandlerResponse ProfilerHttpHandlers::handleCpuFlamegraphRaw(int duration) {
     std::string svg;
     profiler_.executeCommand(fg_cmd, svg);
 
-    if (svg.find("<?xml") == std::string::npos && svg.find("<svg") == std::string::npos) {
-        return errorResp(500, "Failed to generate FlameGraph: insufficient CPU samples.");
+    {
+        auto checked = flameGraphResponse(svg);
+        if (checked.status != 200) {
+            return checked;
+        }
     }
 
     auto resp = HandlerResponse::svg(svg);
@@ -266,7 +291,13 @@ HandlerResponse ProfilerHttpHandlers::handleHeapSvgRaw(int duration, bool state_
     }
 
     std::string exe_path = profiler_.getExecutablePath();
-    std::string cmd = "./pprof --svg " + exe_path + " " + temp_file + " 2>/dev/null";
+    // --alloc_space, not the default --inuse_space: pprof's default reports what
+    // is live *now*, but a short collection window usually catches allocations
+    // that were already freed, giving a profile whose in-use column is zero. The
+    // render then fails with nothing useful to draw, even though the window did
+    // record real allocations. Report cumulative allocation instead, and capture
+    // the renderer's stderr so a genuine failure is not reduced to a bare status.
+    std::string cmd = "./pprof --svg --alloc_space " + exe_path + " " + temp_file + " 2>&1";
     std::string svg;
     profiler_.executeCommand(cmd, svg);
 
@@ -277,7 +308,9 @@ HandlerResponse ProfilerHttpHandlers::handleHeapSvgRaw(int duration, bool state_
         svg = svg.substr(pos);
 
     if (svg.empty() || svg.find("<svg") == std::string::npos) {
-        return errorResp(500, "Failed to generate SVG");
+        return errorResp(500, "pprof could not render this heap sample into an SVG. "
+                              "Output: " +
+                                  svg);
     }
 
     auto resp = HandlerResponse::svg(svg);
@@ -333,11 +366,7 @@ HandlerResponse ProfilerHttpHandlers::handleHeapFlamegraphRaw(int duration, bool
     std::string svg;
     profiler_.executeCommand(fg_cmd, svg);
 
-    if (svg.find("<?xml") == std::string::npos && svg.find("<svg") == std::string::npos) {
-        return errorResp(500, "Failed to generate FlameGraph");
-    }
-
-    auto resp = HandlerResponse::svg(svg);
+    auto resp = flameGraphResponse(svg);
     std::string ts = std::to_string(
         std::chrono::duration_cast<std::chrono::seconds>(std::chrono::system_clock::now().time_since_epoch()).count());
     resp.headers["Content-Disposition"] = "attachment; filename=heap_flamegraph_" + ts + ".svg";
@@ -382,8 +411,11 @@ HandlerResponse ProfilerHttpHandlers::handleGrowthAnalyze(const std::string& out
             return errorResp(500, "Failed to execute flamegraph.pl command");
         }
 
-        if (svg.find("<?xml") == std::string::npos && svg.find("<svg") == std::string::npos) {
-            return errorResp(500, "flamegraph.pl did not generate valid SVG");
+        {
+            auto checked = flameGraphResponse(svg);
+            if (checked.status != 200) {
+                return checked;
+            }
         }
     } else {
         std::ostringstream cmd;
@@ -481,11 +513,7 @@ HandlerResponse ProfilerHttpHandlers::handleGrowthFlamegraphRaw() {
     std::string svg;
     profiler_.executeCommand(fg_cmd, svg);
 
-    if (svg.find("<?xml") == std::string::npos && svg.find("<svg") == std::string::npos) {
-        return errorResp(500, "Failed to generate FlameGraph");
-    }
-
-    auto resp = HandlerResponse::svg(svg);
+    auto resp = flameGraphResponse(svg);
     std::string ts = std::to_string(
         std::chrono::duration_cast<std::chrono::seconds>(std::chrono::system_clock::now().time_since_epoch()).count());
     resp.headers["Content-Disposition"] = "attachment; filename=growth_flamegraph_" + ts + ".svg";
diff --git a/src/web_resources.cpp b/src/web_resources.cpp
index 5c67355..b434db8 100644
--- a/src/web_resources.cpp
+++ b/src/web_resources.cpp
@@ -360,7 +360,10 @@ static const char INDEX_PAGE[] = R"HTML(
                     const a = document.createElement('a');
                     a.href = url;
                     a.download = `${filenamePrefix}_${duration}s.svg`;
+                    // 必须入 DOM：游离的 <a> 触发 click() 在部分浏览器上不会启动下载
+                    document.body.appendChild(a);
                     a.click();
+                    document.body.removeChild(a);
                     URL.revokeObjectURL(url);
 
                     // 恢复按钮，显示成功
@@ -499,9 +502,7 @@ static const char INDEX_PAGE[] = R"HTML(
             const originalText = btn.textContent;
             btn.textContent = '⏳ 准备下载...';
 
-            // 根据图表类型选择端点和文件名
-            const endpoint = heapChartEndpoint(chartType);
-            const duration = heapDuration();
+            // 端点与 source/duration 由 fetchHeapChart 统一决定
             const chartTypeName = chartType === 'flamegraph' ? 'FlameGraph' : 'pprof SVG';
             // 两个端点返回的都是【渲染后的图表】，不是原始 heap profile
             // （/pprof/heap 才是原始 profile，且需要 TCMALLOC_SAMPLE_PARAMETER）
@@ -521,14 +522,9 @@ static const char INDEX_PAGE[] = R"HTML(
                 btn.textContent = `⏳ 生成中 ${progress}% (${countdown}s)`;
             }, 1000);
 
-            // 使用 fetch 下载文件（带上采集窗口）
-            fetch(`${endpoint}?duration=${duration}`)
-                .then(response => {
-                    if (!response.ok) {
-                        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-                    }
-                    return response.blob();
-                })
+            // 与「查看图表」走同一份数据（同一 endpoint + source + duration）。
+            // 此前这里只拼 duration，选"状态式"时会静默拿到窗口数据。
+            fetchHeapChart()
                 .then(blob => {
                     // 清除倒计时
                     clearInterval(progressInterval);
@@ -540,7 +536,11 @@ static const char INDEX_PAGE[] = R"HTML(
                     a.href = url;
                     const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
                     a.download = `${filenamePrefix}_${timestamp}.svg`;
+                    // 必须入 DOM：游离的 <a> 触发 click() 在部分浏览器上不会启动下载
+                    // （downloadHeapProfile 一直这么做，这几个旧函数漏了）。
+                    document.body.appendChild(a);
                     a.click();
+                    document.body.removeChild(a);
                     URL.revokeObjectURL(url);
 
                     // 恢复按钮，显示成功
@@ -605,7 +605,9 @@ static const char INDEX_PAGE[] = R"HTML(
                     a.href = url;
                     const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
                     a.download = `${filenamePrefix}_${timestamp}.svg`;
+                    document.body.appendChild(a);
                     a.click();
+                    document.body.removeChild(a);
                     URL.revokeObjectURL(url);
 
                     // 恢复按钮，显示成功

From 20e6825701c25c56594837a62a7ca4c45f9f7eb6 Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Mon, 14 Sep 2026 06:58:10 +0800
Subject: [PATCH 06/21] fix(heap): name the empty-snapshot case instead of
 reporting a render fault
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A freshly started process has an empty state-based snapshot: tcmalloc reports
nothing until its first sampling event, so /pprof/heap returns a valid profile
with zero records and pprof answers "No nodes to print". That reached the caller
as "pprof could not render this heap sample into an SVG", which reads like a bug
in this project rather than a property of the data.

The svg renderer now recognises pprof's empty-profile output and answers
according to which source was asked for: the state path explains the cold start
and suggests either waiting for allocations or switching to the window source,
which collects its own samples; the window path talks about the window being too
short. The panel's 状态式 hint says the same thing up front.

Observed live on a fresh server: at t+3s the state view returned a 2.6MB graph,
while an earlier run reported zero for over 15s before recovering -- the delay
depends on when the first sampling event lands, which is why the message points
at the condition rather than promising a fixed wait.
---
 CHANGELOG.md          |  1 +
 src/http_handlers.cpp | 18 +++++++++++++++---
 src/web_resources.cpp |  4 +++-
 3 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 68e5bb8..61b56f8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -29,6 +29,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `handleHeapSvgRaw` renders with `pprof --alloc_space` rather than the default `--inuse_space`. pprof's default plots what is live *now*, so a short collection window -- whose allocations have usually already been freed -- produced a profile with an empty in-use column and the render failed with "No nodes to print" even though the window recorded real allocations. Measured: `?duration=1` went from 500 to a 23KB graph.
 - All four flame-graph handlers share one validator (`flameGraphResponse`). flamegraph.pl answers unusable input with a *valid* SVG whose only content is an "ERROR: ..." message, so the structural `<?xml`/`<svg` check passed and a 200 carrying an error text reached callers as if it were a graph. An earlier fix had added the check to `generateFlameGraph()` only; the handlers that inline the command still had the weak check.
 - The panel's chart download now requests the same data as the chart view. It built its URL from `duration` alone and dropped `source=state`, so with the state source selected it silently downloaded a window collection instead. Both actions now share `fetchHeapChart()`, and viewing opens a blob URL so the SVG is displayed rather than downloaded (`Content-Disposition` does not apply to blobs).
+- The empty-snapshot case names itself instead of reading as a render fault. tcmalloc reports nothing until its first sampling event, so the state-based view is legitimately empty for a freshly started process -- and pprof's "No nodes to print" was surfacing as a generic rendering error. It now explains the cold start and points at the window source as an alternative; the collection-window case gets its own wording about a short window.
 - All four download actions insert their `<a>` into the DOM before clicking it; the heap/CPU/growth chart downloads never did, which leaves the click unreliable in browsers that require attachment.
 - **Breaking:** removed the never-implemented `ProfilerHttpHandlers::dispatch()` declaration; route registration stays with the host framework
 - **The Drogon adapter no longer runs profiling on the event-loop thread.** Every handler that can block — CPU/heap/growth analysis, the `_raw` renderers, and `/pprof/profile` — is dispatched to a background worker and its response is handed back with `queueInLoop()`. Profiling takes seconds (up to 300s for CPU), so this previously stalled all other requests, including `/api/status`, for the whole sampling window.
diff --git a/src/http_handlers.cpp b/src/http_handlers.cpp
index 8918235..ed7a5e2 100644
--- a/src/http_handlers.cpp
+++ b/src/http_handlers.cpp
@@ -308,9 +308,21 @@ HandlerResponse ProfilerHttpHandlers::handleHeapSvgRaw(int duration, bool state_
         svg = svg.substr(pos);
 
     if (svg.empty() || svg.find("<svg") == std::string::npos) {
-        return errorResp(500, "pprof could not render this heap sample into an SVG. "
-                              "Output: " +
-                                  svg);
+        // "No nodes to print" is what pprof says for a *valid* profile with no
+        // records, which is the normal cold-start state of the state-based view:
+        // tcmalloc reports nothing until its first sampling event, so a freshly
+        // started process yields an empty snapshot. Say that, rather than
+        // presenting it as a rendering fault.
+        if (svg.find("No nodes to print") != std::string::npos) {
+            return errorResp(500, state_based ? "The current heap snapshot is empty, so there is nothing to draw. "
+                                                "tcmalloc reports no data until its first sampling event; this is "
+                                                "normal shortly after process start. Wait for the process to "
+                                                "allocate, then retry -- or use the window source, which collects "
+                                                "its own samples."
+                                              : "The collected heap sample contained no records. Increase the "
+                                                "duration or sample a process that is actively allocating.");
+        }
+        return errorResp(500, "pprof could not render this heap sample into an SVG. Output: " + svg);
     }
 
     auto resp = HandlerResponse::svg(svg);
diff --git a/src/web_resources.cpp b/src/web_resources.cpp
index b434db8..88a4f84 100644
--- a/src/web_resources.cpp
+++ b/src/web_resources.cpp
@@ -401,7 +401,9 @@ static const char INDEX_PAGE[] = R"HTML(
                     '结果会是空的。分配稀疏时把窗口调长一些。<b>无需</b>启动前设置采样变量。',
             state: '📌 反映<b>堆里现存的内存</b>（tcmalloc 累计采样），与"窗口内分配"是两套机制，结果不同属正常。' +
                    '<b>需要</b>在进程启动前设置 <code>TCMALLOC_SAMPLE_PARAMETER</code>，否则返回 500。' +
-                   '刚启动进程时可能显示 <code>0: 0 [0: 0]</code>——那是采样尚未累计，稍等再试即可。'
+                   '⚠️ 刚启动的进程会返回空快照（tcmalloc 在第一次采样事件前不报告数据），' +
+                   '此时查看图表会得到"快照为空"的提示——等进程分配一段时间后重试，' +
+                   '或改用窗口式（它自己采集，不受影响）。'
         };
 
         function onHeapSourceChange() {

From 381e6104982bc702f8cf22d3760513d59161ce4c Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Mon, 14 Sep 2026 21:00:04 +0800
Subject: [PATCH 07/21] fix(heap): make flame-graph rendering use the same view
 as the svg path

/api/heap/flamegraph_raw failed intermittently for a fixed duration -- 2 times
out of 5 at ?duration=2 -- while the identical sample rendered reliably through
/api/heap/svg_raw. Two causes, both in the collapsed pipeline:

- `pprof --collapsed` was left at pprof's default, which plots what is live
  *now*. A short window usually catches allocations that are already freed, so
  the collapsed file came out with zero stack lines and flamegraph.pl rejected
  it. This is the same problem already fixed for the svg renderer by switching
  to --alloc_space; the collapsed command needed it too. Applied to all three
  collapsed sites (heap raw, heap flamegraph, growth flamegraph).
- The "does the collapsed file have data" check counted any non-empty line not
  starting with '#' as a stack. pprof's two "Using local file ..." progress
  lines qualify, so the check passed on an empty result and the failure surfaced
  two layers later inside flamegraph.pl's output. Those lines are now skipped.

Measured after: 6 consecutive ?duration=2 requests all return 200, and
svg_raw, both ?source=state forms, growth flamegraph and analyze all render.

This is the fourth defect of the same shape in this area -- a renderer's failure
becoming a 200, or a check that cannot observe the condition it is testing --
which is why the earlier fixes kept being reported one at a time by hand.
---
 CHANGELOG.md          |  1 +
 src/http_handlers.cpp | 27 ++++++++++++++++++++-------
 2 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 61b56f8..2cb242a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,6 +27,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `/api/heap/svg_raw` and `/api/heap/flamegraph_raw` now run their own sampling window (`getRawHeapProfileSample()`) instead of pulling `GetHeapSample()`. Besides honouring the duration, this makes them work in a process started without `TCMALLOC_SAMPLE_PARAMETER`, which previously made `/api/heap/svg_raw` fail with 500 while its sibling `/api/heap/flamegraph_raw` succeeded on the same input. The three window-based endpoints now behave identically.
 - Both heap renderers accept `?source=state` to draw the state-based snapshot instead, so the cumulative heap view can be rendered as a chart rather than only exported as text. Previously the graph endpoints could only draw a collection window, which meant the panel had no way to show the live heap visually even though the rendering path existed.
 - `handleHeapSvgRaw` renders with `pprof --alloc_space` rather than the default `--inuse_space`. pprof's default plots what is live *now*, so a short collection window -- whose allocations have usually already been freed -- produced a profile with an empty in-use column and the render failed with "No nodes to print" even though the window recorded real allocations. Measured: `?duration=1` went from 500 to a 23KB graph.
+- The flame-graph handlers' `pprof --collapsed` step also uses `--alloc_space` now, and no longer counts pprof's own "Using local file ..." chatter as stack data. pprof's default reports what is live *now*, so a short window often produced a collapsed file with zero stack lines -- which still passed the "has data" check because the two chatter lines do not start with `#` -- and flamegraph.pl then rejected it. Measured: `?duration=2` failed 2 times out of 5 before, 0 out of 6 after, and the same sample already rendered fine through the svg path, which is what pointed at the mode rather than the data.
 - All four flame-graph handlers share one validator (`flameGraphResponse`). flamegraph.pl answers unusable input with a *valid* SVG whose only content is an "ERROR: ..." message, so the structural `<?xml`/`<svg` check passed and a 200 carrying an error text reached callers as if it were a graph. An earlier fix had added the check to `generateFlameGraph()` only; the handlers that inline the command still had the weak check.
 - The panel's chart download now requests the same data as the chart view. It built its URL from `duration` alone and dropped `source=state`, so with the state source selected it silently downloaded a window collection instead. Both actions now share `fetchHeapChart()`, and viewing opens a blob URL so the SVG is displayed rather than downloaded (`Content-Disposition` does not apply to blobs).
 - The empty-snapshot case names itself instead of reading as a render fault. tcmalloc reports nothing until its first sampling event, so the state-based view is legitimately empty for a freshly started process -- and pprof's "No nodes to print" was surfacing as a generic rendering error. It now explains the cold start and points at the window source as an alternative; the collection-window case gets its own wording about a short window.
diff --git a/src/http_handlers.cpp b/src/http_handlers.cpp
index ed7a5e2..8312c7d 100644
--- a/src/http_handlers.cpp
+++ b/src/http_handlers.cpp
@@ -195,7 +195,8 @@ HandlerResponse ProfilerHttpHandlers::handleCpuFlamegraphRaw(int duration) {
     std::string collapsed_file = "/tmp/cpu_collapsed.prof";
 
     std::ostringstream cmd;
-    cmd << "./pprof --collapsed " << exe_path << " " << temp_file << " > " << collapsed_file << " 2>&1";
+    cmd << "./pprof --collapsed --alloc_space " << exe_path << " " << temp_file << " > " << collapsed_file
+        << " 2>/dev/null";
     std::string out;
     if (!profiler_.executeCommand(cmd.str(), out)) {
         return errorResp(500, "Failed to execute pprof --collapsed command");
@@ -208,7 +209,10 @@ HandlerResponse ProfilerHttpHandlers::handleCpuFlamegraphRaw(int duration) {
     std::string line;
     bool has_data = false;
     while (std::getline(in, line)) {
-        if (!line.empty() && line[0] != '#') {
+        // Skip pprof's own chatter ("Using local file ..."), which would
+        // otherwise be mistaken for stack data; flamegraph.pl then rejects the
+        // file and the failure surfaces two layers away from its cause.
+        if (!line.empty() && line[0] != '#' && line.rfind("Using ", 0) != 0) {
             has_data = true;
             break;
         }
@@ -352,7 +356,8 @@ HandlerResponse ProfilerHttpHandlers::handleHeapFlamegraphRaw(int duration, bool
     std::string collapsed_file = "/tmp/heap_collapsed.prof";
 
     std::ostringstream cmd;
-    cmd << "./pprof --collapsed " << exe_path << " " << temp_file << " > " << collapsed_file << " 2>&1";
+    cmd << "./pprof --collapsed --alloc_space " << exe_path << " " << temp_file << " > " << collapsed_file
+        << " 2>/dev/null";
     std::string out;
     if (!profiler_.executeCommand(cmd.str(), out)) {
         return errorResp(500, "Failed to execute pprof --collapsed command");
@@ -364,7 +369,10 @@ HandlerResponse ProfilerHttpHandlers::handleHeapFlamegraphRaw(int duration, bool
     std::string line;
     bool has_data = false;
     while (std::getline(in, line)) {
-        if (!line.empty() && line[0] != '#') {
+        // Skip pprof's own chatter ("Using local file ..."), which would
+        // otherwise be mistaken for stack data; flamegraph.pl then rejects the
+        // file and the failure surfaces two layers away from its cause.
+        if (!line.empty() && line[0] != '#' && line.rfind("Using ", 0) != 0) {
             has_data = true;
             break;
         }
@@ -409,7 +417,8 @@ HandlerResponse ProfilerHttpHandlers::handleGrowthAnalyze(const std::string& out
     if (output_type == "flamegraph") {
         std::string collapsed_file = "/tmp/growth_collapsed.prof";
         std::ostringstream cmd;
-        cmd << "./pprof --collapsed " << exe_path << " " << temp_file << " > " << collapsed_file << " 2>/dev/null";
+        cmd << "./pprof --collapsed --alloc_space " << exe_path << " " << temp_file << " > " << collapsed_file
+            << " 2>/dev/null";
 
         std::string out;
         if (!profiler_.executeCommand(cmd.str(), out)) {
@@ -499,7 +508,8 @@ HandlerResponse ProfilerHttpHandlers::handleGrowthFlamegraphRaw() {
     std::string collapsed_file = "/tmp/growth_collapsed.prof";
 
     std::ostringstream cmd;
-    cmd << "./pprof --collapsed " << exe_path << " " << temp_file << " > " << collapsed_file << " 2>&1";
+    cmd << "./pprof --collapsed --alloc_space " << exe_path << " " << temp_file << " > " << collapsed_file
+        << " 2>/dev/null";
     std::string out;
     if (!profiler_.executeCommand(cmd.str(), out)) {
         return errorResp(500, "Failed to execute pprof --collapsed command");
@@ -511,7 +521,10 @@ HandlerResponse ProfilerHttpHandlers::handleGrowthFlamegraphRaw() {
     std::string line;
     bool has_data = false;
     while (std::getline(in, line)) {
-        if (!line.empty() && line[0] != '#') {
+        // Skip pprof's own chatter ("Using local file ..."), which would
+        // otherwise be mistaken for stack data; flamegraph.pl then rejects the
+        // file and the failure surfaces two layers away from its cause.
+        if (!line.empty() && line[0] != '#' && line.rfind("Using ", 0) != 0) {
             has_data = true;
             break;
         }

From 9653f1d07d74fdd4f9a9b85c807415e45ed14ebf Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Mon, 14 Sep 2026 21:11:26 +0800
Subject: [PATCH 08/21] fix(web): actually add fetchHeapChart, which I had
 reported as done
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A previous commit (dd01bf9) claimed the chart download and view were reworked
onto a shared fetchHeapChart(). That function was never written: the edit script
asserted on a stale anchor and exited before writing the file, and I reported the
work as complete without checking. The result was worse than the bug it was meant
to fix -- downloadHeapChart() called an undefined function, so:

  - the click threw "fetchHeapChart is not defined" synchronously, before the
    .catch() handler was attached, leaving the countdown running and the button
    disabled forever;
  - viewHeapChart() kept its old window.open() form, so it still downloaded
    rather than displayed.

Reported by the user as "下载图表 does nothing", which is exactly what it did.

This commit writes the function, moves viewHeapChart() onto it (blob URL, so the
SVG is displayed despite Content-Disposition), and wraps the download's call in
Promise.resolve().then(...) so a synchronous throw cannot strand the button
again.

The lesson is about verification, not the code: every earlier "verified" claim in
this series came from curl against the server, which cannot exercise the browser
at all. These four actions are now checked by driving the real page in headless
Chrome over CDP -- expected request issued (with source=state), view opens a blob
URL of the right size, download leaves a file on disk (94580 bytes window, 18810
state), no page errors. Also removed the unused endpoint/duration locals left
behind when the fetch moved into the shared helper.
---
 CHANGELOG.md          |  3 +++
 src/web_resources.cpp | 50 +++++++++++++++++++++++++++++++++++--------
 2 files changed, 44 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2cb242a..b8eb96a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -30,6 +30,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - The flame-graph handlers' `pprof --collapsed` step also uses `--alloc_space` now, and no longer counts pprof's own "Using local file ..." chatter as stack data. pprof's default reports what is live *now*, so a short window often produced a collapsed file with zero stack lines -- which still passed the "has data" check because the two chatter lines do not start with `#` -- and flamegraph.pl then rejected it. Measured: `?duration=2` failed 2 times out of 5 before, 0 out of 6 after, and the same sample already rendered fine through the svg path, which is what pointed at the mode rather than the data.
 - All four flame-graph handlers share one validator (`flameGraphResponse`). flamegraph.pl answers unusable input with a *valid* SVG whose only content is an "ERROR: ..." message, so the structural `<?xml`/`<svg` check passed and a 200 carrying an error text reached callers as if it were a graph. An earlier fix had added the check to `generateFlameGraph()` only; the handlers that inline the command still had the weak check.
 - The panel's chart download now requests the same data as the chart view. It built its URL from `duration` alone and dropped `source=state`, so with the state source selected it silently downloaded a window collection instead. Both actions now share `fetchHeapChart()`, and viewing opens a blob URL so the SVG is displayed rather than downloaded (`Content-Disposition` does not apply to blobs).
+- `downloadHeapChart()` routes its call through `Promise.resolve().then(...)` so a synchronous throw is caught too. A throw raised before the promise chain existed left the countdown running and the button disabled forever, which is what made the button look inert; the `.catch()` could not see it.
+
+Verified in a real browser (headless Chrome driven over CDP) rather than by inspection: all four heap actions issue the expected request -- including `source=state` where it matters -- the view action opens a blob URL and reports its size, and the download action leaves a file on disk (94580 bytes for the window source, 18810 for the state source). No page errors.
 - The empty-snapshot case names itself instead of reading as a render fault. tcmalloc reports nothing until its first sampling event, so the state-based view is legitimately empty for a freshly started process -- and pprof's "No nodes to print" was surfacing as a generic rendering error. It now explains the cold start and points at the window source as an alternative; the collection-window case gets its own wording about a short window.
 - All four download actions insert their `<a>` into the DOM before clicking it; the heap/CPU/growth chart downloads never did, which leaves the click unreliable in browsers that require attachment.
 - **Breaking:** removed the never-implemented `ProfilerHttpHandlers::dispatch()` declaration; route registration stays with the host framework
diff --git a/src/web_resources.cpp b/src/web_resources.cpp
index 88a4f84..04241d7 100644
--- a/src/web_resources.cpp
+++ b/src/web_resources.cpp
@@ -421,16 +421,43 @@ static const char INDEX_PAGE[] = R"HTML(
             return p.toString();
         }
 
-        function viewHeapChart() {
+        // 取回图表字节。查看与下载共用，因此两者必然请求同一份数据
+        // （此前下载只拼 duration、丢掉了 source，选"状态式"时会静默拿到窗口数据）。
+        function fetchHeapChart() {
             const chartType = document.getElementById('heap-chart-type').value;
-            const endpoint = heapChartEndpoint(chartType);
-            const url = `${endpoint}?${heapQuery()}`;
+            const url = `${heapChartEndpoint(chartType)}?${heapQuery()}`;
+            return fetch(url).then(response => {
+                if (!response.ok) {
+                    return response.text().then(body => {
+                        let detail = `HTTP ${response.status}`;
+                        try {
+                            detail = JSON.parse(body).error || detail;
+                        } catch (e) {
+                            if (body) detail = body.trim().slice(0, 200);
+                        }
+                        return Promise.reject(new Error(detail));
+                    });
+                }
+                return response.blob();
+            });
+        }
+
+        function viewHeapChart() {
             const state = heapSource() === 'state';
-            log(`🚀 正在渲染 Heap ${chartType} 图表（数据源: ${state ? '当前堆快照' : '窗口 ' + heapDuration() + ' 秒'}）...`);
-            window.open(url, '_blank');
-            log(`✅ 已在新标签页打开 ${url}\n` +
-                (state ? '   数据来自 /pprof/heap，需已设置 TCMALLOC_SAMPLE_PARAMETER。'
-                       : `   服务端会先采集 ${heapDuration()} 秒再渲染，标签页会稍等片刻。`));
+            const sourceLabel = state ? '当前堆快照' : `窗口 ${heapDuration()} 秒`;
+            log(`🚀 正在渲染 Heap ${document.getElementById('heap-chart-type').value} 图表（数据源: ${sourceLabel}）...`);
+
+            fetchHeapChart()
+                .then(blob => {
+                    // 用 blob URL 打开：Content-Disposition 只影响直接导航，
+                    // 不影响 blob，所以图表会【显示】出来而不是被下载。
+                    window.open(URL.createObjectURL(blob), '_blank');
+                    log(`✅ 图表已在新标签页打开 (${(blob.size / 1024).toFixed(1)} KB)\n` +
+                        (state ? '   数据来自 /pprof/heap，需已设置 TCMALLOC_SAMPLE_PARAMETER。'
+                               : `   服务端已采集 ${heapDuration()} 秒后渲染。`) +
+                        '\n   如需保存：在该标签页另存，或点「📥 下载图表」。');
+                })
+                .catch(err => log(`❌ 渲染失败: ${err.message}`));
         }
 
         // 状态式 heap 快照（/pprof/heap）：与上面的窗口式分析是两套机制。
@@ -526,7 +553,12 @@ static const char INDEX_PAGE[] = R"HTML(
 
             // 与「查看图表」走同一份数据（同一 endpoint + source + duration）。
             // 此前这里只拼 duration，选"状态式"时会静默拿到窗口数据。
-            fetchHeapChart()
+            //
+            // fetchHeapChart() 的同步异常（例如函数名写错）会在 .catch() 挂上之前抛出，
+            // 于是倒计时继续跑、按钮永久 disabled —— 表现为"点了没反应"。用一层
+            // Promise.resolve().then() 把调用本身也纳入链中。
+            Promise.resolve()
+                .then(() => fetchHeapChart())
                 .then(blob => {
                     // 清除倒计时
                     clearInterval(progressInterval);

From 7f9e737339bdcfcdb6c33fa913c0acee9f7d7e4b Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Mon, 14 Sep 2026 21:15:05 +0800
Subject: [PATCH 09/21] fix: free the profile returned by GetHeapProfile in
 stopHeapProfiler

CI's ASan job failed on HttpHandlersTest. Reproduced locally with the same flags
(-fsanitize=address, ASAN_OPTIONS=detect_leaks=1:halt_on_error=1) and the report
names the cause exactly:

    Direct leak of 11630 byte(s)
        #1 GetHeapProfile (/lib64/libtcmalloc.so.4)
        #2 ProfilerManager::stopHeapProfiler() profiler_manager.cpp:268

GetHeapProfile() returns a malloc'd string that the caller must free; the code
let it convert straight into a std::string, discarding the pointer and leaking
the whole profile on every stop. Four call sites leaked ~46KB.

The leak is older than this branch -- but it was unreachable before it.
stopHeapProfiler() had no callers anywhere in the original tree: analyzeHeapProfile
stopped the profiler inline (ProfilerStop + its own state update), and the
original test suite never touched a heap profiler session. Routing
analyzeHeapProfile() and the new getRawHeapProfileSample() through
stopHeapProfiler() is what made the leaking line reachable. The new
HttpHandlersTest cases are the first to call start/stop directly, which is why
CI saw it and the existing tests never did.

The new code in getRawHeapProfileSample() already took ownership and freed
correctly; this brings stopHeapProfiler() in line with it.

Verified: the full suite passes under the CI ASan configuration, 6/6, with no
leak report.
---
 CHANGELOG.md             |  9 +++++++++
 src/profiler_manager.cpp | 12 ++++++++++--
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b8eb96a..08471a3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -49,6 +49,15 @@ Verified in a real browser (headless Chrome driven over CDP) rather than by insp
 - Installation layout made consistent across `lib`/`lib64` hosts so `find_package()` works (GNUInstallDirs is now included before the install rules)
 
 ### Fixed
+- `stopHeapProfiler()` freed nothing for the profile it generates:
+  `GetHeapProfile()` returns a malloc'd string the caller must `free()`, and
+  letting it convert directly into a `std::string` discarded the pointer, leaking
+  the entire profile on every stop (LeakSanitizer: ~11.6KB per call). The path
+  only became reachable once `analyzeHeapProfile()` and the new
+  `getRawHeapProfileSample()` started routing through `stopHeapProfiler()`, but
+  the leak itself is older: that function previously had no callers at all.
+  Surfaced by the new HttpHandlersTest cases, which are the first to drive
+  start/stop directly.
 - `~ProfilerManager()` did not stop the heap profiler: it called `IsHeapProfilerRunning()`, a query whose result was discarded, leaving the process-global profiler recording after the object was destroyed and still dumping profiles during process exit
 - `/pprof/symbol` now implements the Go pprof symbolz protocol correctly
 - CMake package config exports the correct targets and dependency lookup
diff --git a/src/profiler_manager.cpp b/src/profiler_manager.cpp
index 63d9f94..dd237b8 100644
--- a/src/profiler_manager.cpp
+++ b/src/profiler_manager.cpp
@@ -264,8 +264,16 @@ bool ProfilerManager::stopHeapProfiler() {
     }
 
     if (IsHeapProfilerRunning()) {
-        // 保存 heap profile 到文件
-        std::string heap_profile = GetHeapProfile();
+        // GetHeapProfile() returns a malloc'd string that the caller must free;
+        // converting it straight into a std::string lost the pointer and leaked
+        // the entire profile on every stop (LSan measured ~11.6KB per call). Take
+        // ownership first, then release it explicitly.
+        char* profile = GetHeapProfile();
+        std::string heap_profile;
+        if (profile != nullptr) {
+            heap_profile.assign(profile);
+            free(profile);
+        }
         std::string output_path = profiler_states_[ProfilerType::HEAP].output_path;
 
         std::ofstream file(output_path);

From a1f24b79524a674db5238ac2772fc614eeac8cc1 Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Mon, 14 Sep 2026 23:16:40 +0800
Subject: [PATCH 10/21] refactor(api)!: consolidate nine endpoints into four

Nine endpoints across three profiler types collapse into four:

  /api/{cpu,heap,growth}/analyze        -> /api/pprof/{cpu,heap,growth}
  /api/{cpu,heap,growth}/svg_raw        -> /api/pprof/{cpu,heap,growth}?renderer=callgraph
  /api/{cpu,heap,growth}/flamegraph_raw -> /api/pprof/{cpu,heap,growth}?renderer=flamegraph
  /api/heap/*?source=state              -> /api/pprof/heap/snapshot

The old paths are removed, not aliased.

`analyze` and `svg_raw` were the same operation -- sample for N seconds, then
render -- differing only in renderer and whether the response forced a download.
Each pair therefore sampled the process twice for one picture. Renderer is now a
parameter and delivery is another. The three /show_*_svg.html viewers, and the
inline-SVG branch that fed them, are gone with them.

Two naming corrections came out of writing this down:

- `output_type=pprof` became `renderer=callgraph`. Measured: the pprof script
  emits a node/edge call graph (56 polygons, a legend, zero rects) while
  FlameGraph emits stacked frames (37 rects, id="frames"). They are different
  pictures, and the old value named a tool rather than the picture.
- The heap snapshot is its own endpoint rather than a `source=` flag. State-based
  ("what is in the heap now") and window-based ("what was allocated during the
  window") are different questions, so they get different URLs;
  `format=profile|svg` selects raw text or a rendered chart.

`duration` now defaults to 10s everywhere (was 1s for heap). Measured on the
bundled workload: a 3s window failed to collect enough samples 35-45% of the
time, 10s never failed. Responses are `inline` by default, which is purely the
absence of Content-Disposition -- verified that identical bytes navigate as a
document without it and abort with it.

In-page zoom is not promised anywhere, and ROADMAP records why: the generated
SVGs embed pan/zoom libraries that are never initialised (FlameGraph's zoom()
looks for a #viewport its own output lacks; the pprof SVGPan has no onload hook).
That is what motivated dropping the viewers rather than shipping buttons that
cannot work.

ProfilerHttpHandlers now exposes one entry point per profiler taking a
ChartOptions, and the six copies of the same shell-out rendering collapsed into
renderChart/renderFlameGraph/renderCallGraph. src/http_handlers.cpp lost ~40% of
its lines and web_resources.cpp ~44%.

Adds the two verification scripts asked for, and uses them here:

- scripts/verify-web-ui.mjs drives the real panel in headless Chrome and asserts
  each action issues its request, saves a file, and leaves no button disabled.
  Front-end defects in this series were reported as "the button does nothing"
  after being declared fixed on the strength of curl, which cannot execute page
  JavaScript at all. 23/23 checks pass.
- scripts/check-sanitizers.sh reproduces CI's ASan/UBSan/TSan locally; the
  LeakSanitizer failure in the previous commit reached CI because nothing here
  ran with -fsanitize=address. ASan passes with the CI flags and suppressions.

Verified: release build clean, 6/6 tests, ASan 6/6 with no leak report, browser
regression 23/23, all twelve old paths 404, /pprof/* unchanged and still resolving
symbols.
---
 CHANGELOG.md                               |   46 +
 README.md                                  |  130 ++-
 ROADMAP.md                                 |   22 +-
 docs/user_guide/02_api_reference.md        |   17 +-
 docs/user_guide/03_integration_examples.md |   21 +-
 docs/user_guide/04_troubleshooting.md      |   25 +-
 include/profiler/http_handlers.h           |  112 ++-
 scripts/check-sanitizers.sh                |  108 ++
 scripts/verify-web-ui.mjs                  |  217 ++++
 src/drogon_adapter.cpp                     |  347 +++----
 src/http_handlers.cpp                      |  523 +++-------
 src/internal/web_resources.h               |   12 +-
 src/web_resources.cpp                      | 1051 +++-----------------
 tests/test_http_handlers.cpp               |  102 +-
 14 files changed, 979 insertions(+), 1754 deletions(-)
 create mode 100755 scripts/check-sanitizers.sh
 create mode 100755 scripts/verify-web-ui.mjs

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 08471a3..711ef40 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `profiler/async_executor.h` — bounded single-worker executor for long-running jobs
 
 ### Changed
+- **Breaking:** the HTTP API was consolidated. Nine endpoints across three
+  profiler types became four:
+
+  | before | after |
+  |---|---|
+  | `/api/{cpu,heap,growth}/analyze` | `/api/pprof/{cpu,heap,growth}` |
+  | `/api/{cpu,heap,growth}/svg_raw` | `/api/pprof/{cpu,heap,growth}?renderer=callgraph` |
+  | `/api/{cpu,heap,growth}/flamegraph_raw` | `/api/pprof/{cpu,heap,growth}?renderer=flamegraph` |
+  | `/api/heap/*?source=state` | `/api/pprof/heap/snapshot` |
+
+  `analyze` and `svg_raw` were the *same operation* — sample for N seconds, then
+  render — differing only in the renderer and in whether the response forced a
+  download, so each pair sampled the process twice for one picture. The renderer
+  is now a parameter (`renderer=flamegraph|callgraph`) and delivery is another
+  (`output=inline|attachment`). The old paths are gone, not aliased.
+- **Breaking:** the heap snapshot is its own endpoint,
+  `/api/pprof/heap/snapshot`, with `format=profile` (default, raw text for
+  `go tool pprof`) or `format=svg`. It is state-based ("what is in the heap now")
+  as opposed to `/api/pprof/heap`, which is window-based ("what was allocated
+  during the window"). Keeping it on the same resource behind a `source=` flag
+  would have put two different questions at one URL.
+- **Breaking:** `renderer=callgraph` replaces `output_type=pprof`. The old value
+  named a tool rather than the result: the pprof script draws a node/edge *call
+  graph*, while FlameGraph draws a *flame graph*. They are different pictures, not
+  two styles of one, and the parameter should say which picture you get.
+- The `duration` default is now 10s everywhere (was 1s for heap, 30s for
+  `/pprof/profile`). Measured on the bundled example workload, a 3s window failed
+  to collect enough samples to render 35-45% of the time; 10s never failed. A 1s
+  default was close to useless.
+- Responses are `inline` by default, so a plain link shows the SVG in the browser
+  instead of downloading it; `output=attachment` restores a forced download.
+  Inline display is purely the absence of `Content-Disposition` — verified that
+  the same bytes navigate as a document without it and abort with it.
+- The three `/show_*_svg.html` viewer pages are removed, along with the inline-SVG
+  branch they consumed. Their in-page pan/zoom never worked: the generated SVGs
+  embed a pan/zoom library that is never initialised (FlameGraph's `zoom()` looks
+  for a `#viewport` element that its own output does not contain, and the pprof
+  SVGPan library has no `onload` hook). Downloading the SVG and opening it in a
+  desktop tool is what actually works, so the panel now offers downloads and a
+  live log rather than a viewer.
+- `ProfilerHttpHandlers` exposes one entry point per profiler —
+  `handleCpuChart` / `handleHeapChart` / `handleGrowthChart` / `handleHeapSnapshot` —
+  each taking a `ChartOptions` (renderer, duration, delivery) instead of the
+  per-endpoint duration/output_type argument lists. Shared rendering moved into
+  `renderChart`/`renderFlameGraph`/`renderCallGraph`, replacing six copies of the
+  same shell-out logic.
 - **Breaking:** `ProfilerManager` is no longer a singleton — construct it directly and manage its lifetime
 - **Breaking:** removed the spdlog dependency; use `setLogSink()` / `setLogLevel()` instead
 - **Breaking:** core library decoupled from the web layer — `profiler_core` (no Drogon) and `profiler_web` (optional Drogon adapter) are now separate targets
diff --git a/README.md b/README.md
index e0a2ef9..4966a26 100644
--- a/README.md
+++ b/README.md
@@ -39,7 +39,7 @@
 参考 Go pprof 提供两种互补的使用方式：
 
 1. **标准 pprof 模式** — `/pprof/profile`、`/pprof/heap` 返回原始 profile 文件，交给 `go tool pprof` 分析
-2. **一键分析模式** — `/api/cpu/analyze` 等直接返回 SVG，适合浏览器即时查看
+2. **一键分析模式** — `/api/pprof/cpu` 等直接返回 SVG，适合浏览器即时查看
 
 架构上分为两层，边界清晰：
 
@@ -150,15 +150,15 @@ cd build && ./profiler_example
 | 端点 | 并发请求的响应 |
 |------|----------------|
 | `/pprof/profile` | `500`，`text/plain`，`Could not enable CPU profiling: cpu profiling already in use`，并带 `X-Go-Pprof: 1` 头 |
-| `/api/cpu/analyze`、`/api/cpu/svg_raw`、`/api/cpu/flamegraph_raw` | `409`，`{"error":"cpu profiling already in use"}` |
+| `/api/pprof/cpu` | `409`，`{"error":"cpu profiling already in use"}` |
 
 `X-Go-Pprof: 1` 是给 `go tool pprof` 的信号：告诉它响应体是错误消息而非 profile 数据。
 
-**宿主自己开的会话不会被抢占。** 如果你的程序用 `startCPUProfiler()` 主动开了一段采样，此期间的 HTTP 请求会被拒绝（同上表），而**不会**停掉你那段采样。同理 `startHeapProfiler()` 开的 heap 会话也不会被 `/api/heap/analyze` 抢占。
+**宿主自己开的会话不会被抢占。** 如果你的程序用 `startCPUProfiler()` 主动开了一段采样，此期间的 HTTP 请求会被拒绝（同上表），而**不会**停掉你那段采样。同理 `startHeapProfiler()` 开的 heap 会话也不会被 `/api/pprof/heap` 抢占。
 
-**Heap 分析同样独占**。`HeapProfilerStart()` 与 CPU profiler 不同——它**没有失败模式**，重复调用会静默替换输出前缀，所以必须先原子认领再启动，否则并发调用会共用同一份快照。`/api/heap/analyze` 在已有分析进行时返回 `409` + `{"error":"heap profiling already in use"}`。
+**Heap 分析同样独占**。`HeapProfilerStart()` 与 CPU profiler 不同——它**没有失败模式**，重复调用会静默替换输出前缀，所以必须先原子认领再启动，否则并发调用会共用同一份快照。`/api/pprof/heap` 在已有分析进行时返回 `409` + `{"error":"heap profiling already in use"}`。
 
-`/api/growth/analyze` **不受此限制**：它读取 `GetHeapGrowthStacks()`，不占用任何 profiler 会话，可与 CPU 采样并存。
+`/api/pprof/growth` **不受此限制**：它读取 `GetHeapGrowthStacks()`，不占用任何 profiler 会话，可与 CPU 采样并存。
 
 快速接口（`/api/status`、`/`）不受采样影响，采样期间依然即时响应。
 
@@ -307,73 +307,66 @@ profiler.setLogLevel(profiler::LogLevel::Debug);
 
 由 `registerDrogonHandlers()` 注册的全部路由。
 
-> **Heap 的两套机制**（详见[下方说明](#heap-的两个端点语义相反)）：
-> `/pprof/heap` 是**状态式**（当前堆的累计快照），`/api/heap/*` 是**窗口式**（默认 1 秒内发生的分配）。
-> 二者不可互相替代，且**环境变量依赖相反**。
-
 | 端点 | 方法 | 说明 |
 |------|------|------|
-| **标准 pprof 接口** | | |
-| `/pprof/profile` | GET | CPU profile 原始文件；`?seconds=N`，默认 **30**，范围 1–300 |
-| `/pprof/heap` | GET | **状态式**：当前堆的累计采样快照（原始文本，交给 `go tool pprof`）；**需** `TCMALLOC_SAMPLE_PARAMETER` |
-| `/pprof/growth` | GET | Heap growth 栈原始文本；无需上述环境变量 |
-| `/pprof/symbol` | POST | 符号化接口（Go pprof symbolz 协议） |
-| **一键分析（返回 SVG）** | | |
-| `/api/cpu/analyze` | GET/POST | 采样并返回 CPU 图；`?duration=N` 默认 10，范围 1–300 |
-| `/api/heap/analyze` | GET | **窗口式**：采集后渲染；`?duration=N` 默认 1，范围 1–300；**无需**环境变量 |
-| `/api/growth/analyze` | GET | 返回 Heap Growth 图 |
-| **原始 SVG 下载** | | |
-| `/api/cpu/svg_raw` | GET | pprof 生成的 CPU SVG；`?duration=N` 默认 10 |
-| `/api/heap/svg_raw` | GET | Heap SVG（pprof 渲染）；`?duration=N` 默认 1；`?source=state` 改为渲染**当前堆快照** |
-| `/api/growth/svg_raw` | GET | pprof 生成的 Growth SVG |
-| `/api/cpu/flamegraph_raw` | GET | FlameGraph 渲染的 CPU SVG；`?duration=N` 默认 10 |
-| `/api/heap/flamegraph_raw` | GET | Heap SVG（FlameGraph 渲染）；`?duration=N` 默认 1；`?source=state` 同上 |
-| `/api/growth/flamegraph_raw` | GET | FlameGraph 渲染的 Growth SVG |
-| **线程分析** | | |
+| **分析接口（主动采样后出图）** | | |
+| `/api/pprof/cpu` | GET | 采样 CPU 并返回图 |
+| `/api/pprof/heap` | GET | **窗口式**：采集窗口内发生的分配并返回图 |
+| `/api/pprof/growth` | GET | 采集 heap growth 栈并返回图 |
+| **Heap 快照（状态式）** | | |
+| `/api/pprof/heap/snapshot` | GET | **状态式**：当前堆的累计快照（存量，非窗口） |
+| **状态与辅助** | | |
+| `/api/status` | GET | 各 profiler 的运行状态与输出路径（JSON） |
 | `/api/thread/stacks` | GET | 所有线程的调用栈 |
-| **辅助与页面** | | |
 | `/` | GET | Web 控制面板 |
-| `/api/status` | GET | 各 profiler 的运行状态与输出路径（JSON） |
-| `/show_svg.html` | GET | CPU SVG 查看页 |
-| `/show_heap_svg.html` | GET | Heap SVG 查看页 |
-| `/show_growth_svg.html` | GET | Growth SVG 查看页 |
+| **标准 pprof 接口（机器可读，`go tool pprof` 用）** | | |
+| `/pprof/profile` | GET | CPU profile 原始文件；`?seconds=N`，默认 **30**，范围 1–300 |
+| `/pprof/heap` | GET | 当前堆快照原始文本；**需** `TCMALLOC_SAMPLE_PARAMETER` |
+| `/pprof/growth` | GET | Heap growth 栈原始文本；无需该环境变量 |
+| `/pprof/symbol` | POST | 符号化（Go pprof symbolz 协议） |
 
-所有分析类接口都接受 `?output_type=flamegraph|pprof`：
+### 分析接口的参数
 
-- `pprof` — 由内置 pprof 脚本渲染的图形（**HTTP 层的默认值**）
-- `flamegraph` — 由 FlameGraph 渲染的火焰图
+三个 `/api/pprof/{cpu,heap,growth}` 端点共用同一组参数：
 
-> 注意默认值差异：C++ API `analyzeCPUProfile()` 的形参默认是 `"flamegraph"`，而 HTTP 路由在未传 `output_type` 时使用 `"pprof"`。想稳定拿到火焰图请显式写 `?output_type=flamegraph`。
+| 参数 | 取值 | 默认 | 说明 |
+|------|------|------|------|
+| `renderer` | `flamegraph` \| `callgraph` | `flamegraph` | **两种不同的图形**，见下 |
+| `duration` | 1–300 | **10** | 采集窗口（秒）。CPU/Growth 用于采样，heap 用于记录分配 |
+| `output` | `inline` \| `attachment` | `inline` | `inline` 不发 `Content-Disposition`，浏览器直接显示 SVG；`attachment` 强制下载 |
 
-### 使用示例
+`/api/pprof/heap/snapshot` 另用 `format`：
 
-```bash
-# CPU：拿原始 profile 交给 pprof 工具（默认 30 秒）
-curl 'http://localhost:8080/pprof/profile?seconds=10' > cpu.prof
-go tool pprof -http=:8081 cpu.prof
+| 参数 | 取值 | 默认 | 说明 |
+|------|------|------|------|
+| `format` | `profile` \| `svg` | `profile` | `profile` 返回原始 pprof 文本（交给 `go tool pprof`）；`svg` 渲染成图 |
+| `renderer` | 同上 | `flamegraph` | 仅 `format=svg` 时有意义 |
 
-# CPU 火焰图（显式指定 output_type）
-curl 'http://localhost:8080/api/cpu/analyze?duration=10&output_type=flamegraph' -o cpu.svg
+### 两种图形不是同一种东西
 
-# Heap（需先设置 TCMALLOC_SAMPLE_PARAMETER）
-curl 'http://localhost:8080/api/heap/analyze?output_type=flamegraph' -o heap.svg
+`renderer` 的选择会改变**图形表达**，不只是画法：
 
-# 所有线程调用栈
-curl 'http://localhost:8080/api/thread/stacks'
-```
+| 取值 | 产出 | 特点 |
+|------|------|------|
+| `flamegraph` | **火焰图**（栈帧堆叠） | 层次直观，适合看调用占比 |
+| `callgraph` | **调用图**（graphviz 节点/边） | 能解析内联帧，符号化更完整 |
 
-也支持直接让 pprof 从 URL 拉取：
+> ⚠️ **两者都不可在浏览器里缩放。** 生成的 SVG 内嵌了 pan/zoom 脚本，但依赖的
+> 元素或初始化挂钩并未出现在产物中（实测：FlameGraph 的 `zoom()` 找不到
+> `#viewport`，pprof 的 SVGPan 从未被初始化）。需要缩放时请把 SVG 下载后用桌面
+> 工具打开，或在浏览器里用页面缩放（Ctrl + 滚轮）。
 
-```bash
-go tool pprof -http=:8081 'http://localhost:8080/pprof/profile?seconds=10'
-```
+### 关于 `duration` 的默认值
+
+默认 **10 秒**而非更短，是实测结果：示例负载下 3 秒窗口有 **35–45%** 的请求采不到
+足够样本而渲染失败，10 秒窗口为 **0%**。分配稀疏进程需要更长窗口。
 
 ## 配置说明
 
 ### 环境变量 `TCMALLOC_SAMPLE_PARAMETER`
 
 控制 tcmalloc 的堆采样间隔（单位字节）。**默认值为 `0`，即关闭采样**。它影响的是**状态式**拉取路径
-（`GetHeapSample()`），也就是 `/pprof/heap` 与 `/api/heap/svg_raw`：
+（`GetHeapSample()`），也就是 `/pprof/heap` 与 `/api/pprof/heap/snapshot?format=profile`：
 
 ```bash
 export TCMALLOC_SAMPLE_PARAMETER=524288      # 512KB，开发环境常用
@@ -388,19 +381,19 @@ tcmalloc 在**进程初始化时**读取该变量，因此必须在启动前用
 | 生产 | `2097152`（2MB）或更大，降低开销 |
 
 **不受该变量影响的路径**（它们走 `HeapProfilerStart/Dump`，由
-`HEAP_PROFILE_ALLOCATION_INTERVAL`（默认 1MB）等控制）：`/api/heap/analyze`、
-`/api/heap/flamegraph_raw`。Heap Growth（`/pprof/growth`、`/api/growth/*`）走
+`HEAP_PROFILE_ALLOCATION_INTERVAL`（默认 1MB）等控制）：`/api/pprof/heap`、
+`/api/pprof/heap/snapshot?format=svg`。Heap Growth（`/pprof/growth`、`/api/pprof/growth`）走
 `GetHeapGrowthStacks()`，也不需要该变量。
 
-> ⚠️ 不设该变量时：三个**窗口式**端点（`/api/heap/analyze`、`/api/heap/svg_raw`、
-> `/api/heap/flamegraph_raw`）仍然正常返回 SVG，因为它们各自运行自己的
-> `HeapProfilerStart/GetHeapProfile/Stop` 窗口；只有**状态式**的 `/pprof/heap` 返回 500。
+> ⚠️ 不设该变量时：**窗口式**端点（`/api/pprof/heap`）仍然正常返回 SVG，因为它自己运行
+> `HeapProfilerStart/GetHeapProfile/Stop` 窗口；而**状态式**的 `/pprof/heap` 与
+> `/api/pprof/heap/snapshot?format=profile` 返回 500。
 
 ### Heap 的两个端点语义相反
 
 这两个端点容易混淆，因为名字里都有 "heap"，但记录的是**完全不同的东西**：
 
-| | `/pprof/heap` | `/api/heap/{analyze,svg_raw,flamegraph_raw}` |
+| | `/pprof/heap`、`/api/pprof/heap/snapshot` | `/api/pprof/heap` |
 |---|---|---|
 | 语义 | **状态式**：当前堆里的累计采样 | **窗口式**：采集窗口内**发生的分配** |
 | 底层 | `GetHeapSample()` 拉取 | `HeapProfilerStart()` → `GetHeapProfile()` → `Stop()` |
@@ -411,26 +404,27 @@ tcmalloc 在**进程初始化时**读取该变量，因此必须在启动前用
 
 关键差别在于**"存量"与"流量"**：
 
-- 进程已占 500MB 但停止分配 → `/pprof/heap` 能看到这 500MB；`/api/heap/analyze` 返回**空**并报
+- 进程已占 500MB 但停止分配 → `/pprof/heap` 能看到这 500MB；`/api/pprof/heap` 返回**空**并报
   `No heap profile data was produced`
-- 进程频繁 malloc/free，dump 时已全部释放 → `/api/heap/analyze` **能看到**这些分配；`/pprof/heap`
+- 进程频繁 malloc/free，dump 时已全部释放 → `/api/pprof/heap` **能看到**这些分配；`/pprof/heap`
   的当前堆则可能很小
 
 所以窗口式分析需要**被分析进程在采集窗口内确实有分配**。
 
 ⚠️ **heap 的 `duration` 不是采样率**：采样率由 `TCMALLOC_SAMPLE_PARAMETER` 在进程启动时固定，
 `duration` 只决定**采集多久**。分配稀疏的进程需要更长的窗口才能采到东西，所以它是"覆盖度"参数
-而不是"精度"参数。默认 1 秒，范围 1–300。
+而不是"精度"参数。默认 10 秒，范围 1–300。
 
-Web 控制面板的 Heap 区用一个**数据源**下拉在两套机制间切换，两者都能出图：
+Web 控制面板分成四块，各自对应一个端点：
 
-| 数据源 | 图表接口 | 说明 |
-|--------|----------|------|
-| 窗口式 | `/api/heap/{svg_raw,flamegraph_raw}?duration=N` | 采集 N 秒后渲染 |
-| 状态式 | `/api/heap/{svg_raw,flamegraph_raw}?source=state` | 渲染当前堆累计快照（对应 `/pprof/heap`） |
+| 区块 | 端点 | 说明 |
+|------|------|------|
+| CPU Profiler | `/api/pprof/cpu` | 采样后出图 |
+| Heap Profiler | `/api/pprof/heap` | **窗口式**：采集窗口内的分配（流量） |
+| Heap Snapshot | `/api/pprof/heap/snapshot` | **状态式**：当前堆累计快照（存量） |
+| Heap Growth | `/api/pprof/growth` | 增长栈分析 |
 
-面板提供「🔍 查看图表」「📥 下载图表 (SVG)」，以及「📄 查看原始 profile」「📥 下载 profile 文本」
-（后者走 `/pprof/heap`，用于交给 `go tool pprof` 分析）。
+每块都有「📥 下载…」按钮；快照那块另提供原始 profile 文本下载（交给 `go tool pprof` 分析）。
 
 ### 依赖版本
 
diff --git a/ROADMAP.md b/ROADMAP.md
index d22142f..2e6a9db 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -15,7 +15,7 @@
 ### 已修复
 
 <details>
-<summary>1. `/api/heap/analyze` 的 duration 语义（✅ 已修复）</summary>
+<summary>1. `/api/heap/analyze` 的 duration 语义（✅ 已修复；该路径现已并入 `/api/pprof/heap`）</summary>
 
 原问题：路由只解析 `output_type`，`handleHeapAnalyze()` 也没有 duration 形参，最终硬编码
 `analyzeHeapProfile(1, ...)`。
@@ -71,20 +71,34 @@
 ### 已修复（本轮，用 go tool pprof 验证）
 
 - `/pprof/heap` 在采样关闭时返回 200 + `%warn` 文本：`GetHeapSample()` 不返回空串，导致空值检查失效。现按 `@ heap_v2/0` / 前导 `%warn` 识别，返回 500。
-- `/api/heap/svg_raw` 与 `flamegraph_raw` 的行为不一致：根因同上，两者现在都返回同样的明确错误。
+- `/api/heap/svg_raw` 与 `flamegraph_raw` 的行为不一致：根因同上，两者现在都返回同样的明确错误（后经 API 重构合并为 `/api/pprof/heap`）。
 - 分析类接口的错误响应**双重包裹**成非法 JSON（`{"error":"{"error": "..."}`）：现将内部错误消息解出后再包一层。
 - `/pprof/heap` 与 `/pprof/growth` 的错误改用 Go `serveError()` 的形状（`text/plain` + `X-Go-Pprof: 1`），`go tool pprof` 能直接显示原因。
 - `flamegraph.pl` 对空输入返回"合法 SVG + ERROR 文本"，被当作 200 成功：现识别并转为带原因的 500。
 
+### 已完成（本轮 API 重构）
+
+- HTTP API 收敛：9 个端点 → 4 个（`/api/pprof/{cpu,heap,growth}` + `/api/pprof/heap/snapshot`），
+  渲染器与交付方式改为参数（`renderer` / `output`），消除了 `analyze` 与 `*_raw` 各采样一次的重复。
+- `duration` 默认值 1 秒 → 10 秒（实测 3 秒失败率 35–45%、10 秒 0%，见 CHANGELOG）。
+- 移除 3 个查看器页及其内联 SVG 分支——其页内缩放从未生效（生成的 SVG 内嵌了从未被初始化的
+  pan/zoom 库）。面板改为「下载 + 实时日志」。
+- 新增 `scripts/verify-web-ui.mjs`（CDP 驱动真实浏览器回归，23 项检查）与
+  `scripts/check-sanitizers.sh`（本地复刻 CI 的 ASan/UBSan/TSan 配置）。
+
 ### 待修
 
+- **生成的 SVG 无法缩放**：FlameGraph 的 `zoom()` 找不到它要操作的 `#viewport`（其产物只有
+  `#frames`），pprof 的 SVGPan 库则从未被初始化（产物缺少 `onload` 挂钩）。两条路径的交互脚本
+  都是死代码。可选方案：改为在服务端生成自己的交互式 SVG，或在文档中明确"下载后用桌面工具看"。
+
 - **火焰图里的函数名带地址后缀**：内置 pprof 的 `--collapsed` 输出把函数名写成
   `cpuIntensiveTask()<0000000000409360>`，经 `flamegraph.pl` 渲染后直接显示在图上。除了噪音，还有一个
   理论隐患：同一函数出现在不同地址时（模板实例化）会被当成**不同栈帧**，本该合并的被拆开。
   可在送入 `flamegraph.pl` 之前剥掉 `<十六进制>` 后缀。
 - **部分符号未 demangle**：实测火焰图里残留 `_ZSt12construct_at...` 之类的 mangled 名，且这类帧常显示为
   无上下文的 `operator()[inline]`（lambda 的 `operator()`）。可对未解开的符号做二次 `__cxa_demangle`。
-- **两个 pprof 实现的差异未写进文档**：内置 Perl pprof（`output_type=pprof` 的渲染器）符号化更完整——
+- **两个 pprof 实现的差异未写进文档**：内置 Perl pprof（`renderer=callgraph` 的渲染器）符号化更完整——
   实测同一份 profile 未解析帧为 0、且能标出 `(inline)`；而 `go tool pprof` 强在对比与交互
   （`-diff_base`、`-peek`、`-traces`）。README 目前只说了"两种渲染方式"，没说各自适合什么场景。
 - **`pprof --svg` 的失败信息不透出**：内置 pprof 脚本用 `dot`(graphviz) 渲染，采样点过少时 `dot` 失败，代码只回一句 `pprof did not generate valid SVG. Output: `（且 `svg_output` 为空），无法定位原因。应把 `dot` 的 stderr 一并返回。**这是异步改造期间实测复现的既有缺陷**，与请求调度无关。
@@ -100,7 +114,7 @@
 - `include/profiler/async_executor.h` — 单工作线程执行器，把阻塞任务搬离事件循环，完成后经 `queueInLoop()` 回送响应
 - 阻塞接口全部投递到该工作线程；`/api/status`、`/` 等快速接口保持在事件循环上
 - **CPU 采样独占且 fail-fast**：`cpu_profiling_in_progress_` 是所有 CPU 采样入口（`getRawCPUProfile` / `analyzeCPUProfile`）共用的进程级标记。占用期间新请求**立即被拒绝**，不会排队、也不会打断正在进行的采样
-- 拒绝语义与 Go 的 `net/http/pprof` 对齐：`/pprof/profile` 返回 500 + `text/plain` + `X-Go-Pprof: 1`；`/api/cpu/*` 返回 409 JSON
+- 拒绝语义与 Go 的 `net/http/pprof` 对齐：`/pprof/profile` 返回 500 + `text/plain` + `X-Go-Pprof: 1`；`/api/pprof/cpu` 返回 409 JSON
 - 拒绝判定发生在**事件循环线程上、任务入队之前**（`runAsync` 的 precheck）。这是必须的：若放在任务内部判断，只能在前一个任务结束后才执行，永远观察不到它正在运行
 
 实测：20 秒采样期间 `/api/status` 响应 0.0004s；并发请求第二个 0.0005s 内被拒且第一个不受影响。
diff --git a/docs/user_guide/02_api_reference.md b/docs/user_guide/02_api_reference.md
index 9ab5ef5..bd41dd8 100644
--- a/docs/user_guide/02_api_reference.md
+++ b/docs/user_guide/02_api_reference.md
@@ -63,13 +63,13 @@ explicit ProfilerHttpHandlers(ProfilerManager& profiler);
 | 方法 | 签名 | 说明 |
 |------|------|------|
 | `handleStatus` | `HandlerResponse handleStatus()` | 返回所有 profiler 状态 (JSON) |
-| `handleCpuAnalyze` | `HandlerResponse handleCpuAnalyze(int duration, const std::string& output_type)` | CPU 分析，返回 SVG |
+| `handleCpuChart` | `HandlerResponse handleCpuChart(const ChartOptions&)` | CPU 采样并出图 |
 | `handleCpuSvgRaw` | `HandlerResponse handleCpuSvgRaw(int duration)` | CPU 原始 SVG (pprof 生成) |
 | `handleCpuFlamegraphRaw` | `HandlerResponse handleCpuFlamegraphRaw(int duration)` | CPU FlameGraph SVG |
-| `handleHeapAnalyze` | `HandlerResponse handleHeapAnalyze(const std::string& output_type)` | Heap 分析，返回 SVG |
+| `handleHeapChart` | `HandlerResponse handleHeapChart(const ChartOptions&)` | Heap 窗口式采集并出图 |
 | `handleHeapSvgRaw` | `HandlerResponse handleHeapSvgRaw()` | Heap 原始 SVG |
 | `handleHeapFlamegraphRaw` | `HandlerResponse handleHeapFlamegraphRaw()` | Heap FlameGraph SVG |
-| `handleGrowthAnalyze` | `HandlerResponse handleGrowthAnalyze(const std::string& output_type)` | Growth 分析，返回 SVG |
+| `handleGrowthChart` | `HandlerResponse handleGrowthChart(const ChartOptions&)` | Growth 采集并出图 |
 | `handleGrowthSvgRaw` | `HandlerResponse handleGrowthSvgRaw()` | Growth 原始 SVG |
 | `handleGrowthFlamegraphRaw` | `HandlerResponse handleGrowthFlamegraphRaw()` | Growth FlameGraph SVG |
 | `handlePprofProfile` | `HandlerResponse handlePprofProfile(int seconds)` | 标准 pprof CPU profile (二进制) |
@@ -300,7 +300,10 @@ std::string analyzeCPUProfile(int duration, const std::string& output_type = "fl
 
 **参数**:
 - `duration`: 采样时长（秒）
-- `output_type`: 输出类型（"flamegraph" 或 "pprof"）
+- `output_type`: 渲染方式（`"flamegraph"` 或 `"pprof"`）
+
+> 这是 **C++ 层**的形参。HTTP 层的等价参数叫 `renderer`，取值 `flamegraph` / `callgraph`
+> （见 README 的端点说明）——`callgraph` 对应这里的 `"pprof"`。
 
 **返回值**: SVG 字符串
 
@@ -325,7 +328,7 @@ std::string getRawCPUProfile(int seconds);
 
 宿主用 `startCPUProfiler()` 打开的会话**归调用方所有，不会被本函数停止或接管**。调用前可用
 `isProfilerRunning(ProfilerType::CPU)` 判断；HTTP 层则通过 `isCpuProfilerBusy()` 区分并返回
-`500`（`/pprof/profile`，Go 风格）或 `409`（`/api/cpu/*`）。
+`500`（`/pprof/profile`，Go 风格）或 `409`（`/api/pprof/cpu`）。
 
 ---
 
@@ -362,7 +365,7 @@ std::string analyzeHeapProfile(const std::string& output_type = "flamegraph");
 ```
 
 **参数**:
-- `output_type`: 输出类型（`"flamegraph"` 或 `"pprof"`）
+- `output_type`: 渲染方式（`"flamegraph"` 或 `"pprof"`）
 
 **返回值**: SVG 字符串；失败时返回 `{"error":"..."}` JSON 字符串
 
@@ -551,7 +554,7 @@ int main() {
 它会同时考虑"已有请求在采样"和"宿主占用了会话"两种情况。
 
 Heap 侧同理：`analyzeHeapProfile()` 与 `startHeapProfiler()` 互斥，谁先占谁赢。
-`/api/growth/analyze` 不占用任何会话，不受限制。
+`/api/pprof/growth` 不占用任何会话，不受限制。
 
 ---
 
diff --git a/docs/user_guide/03_integration_examples.md b/docs/user_guide/03_integration_examples.md
index 4f1b7fe..54397ab 100644
--- a/docs/user_guide/03_integration_examples.md
+++ b/docs/user_guide/03_integration_examples.md
@@ -181,12 +181,14 @@ int main() {
     YourWebServer server;
 
     // 注册 CPU 分析端点
-    server.route("GET", "/api/cpu/analyze", [&](const Request& req) {
-        int duration = req.get_param_int("duration", 10);
-        std::string output_type = req.get_param("output_type", "pprof");
+    server.route("GET", "/api/pprof/cpu", [&](const Request& req) {
+        profiler::ChartOptions options;
+        options.duration = req.get_param_int("duration", 10);
+        options.renderer = profiler::parseChartRenderer(req.get_param("renderer", "flamegraph"));
+        options.inline_display = req.get_param("output", "inline") != "attachment";
 
         // 调用 handler 获取框架无关的响应
-        profiler::HandlerResponse resp = handlers.handleCpuAnalyze(duration, output_type);
+        profiler::HandlerResponse resp = handlers.handleCpuChart(options);
 
         // 用你的框架包装响应
         return YourResponse()
@@ -255,10 +257,15 @@ public:
         return toOat(handlers_.handleStatus());
     }
 
-    ENDPOINT("GET", "/api/cpu/analyze", cpuAnalyze,
+    ENDPOINT("GET", "/api/pprof/cpu", cpuChart,
              QUERY(Int32, duration, "duration", "10"),
-             QUERY(String, output_type, "output_type", "flamegraph")) {
-        return toOat(handlers_.handleCpuAnalyze(duration, output_type));
+             QUERY(String, renderer, "renderer", "flamegraph"),
+             QUERY(String, output, "output", "inline")) {
+        profiler::ChartOptions options;
+        options.duration = duration;
+        options.renderer = profiler::parseChartRenderer(renderer);
+        options.inline_display = output != "attachment";
+        return toOat(handlers_.handleCpuChart(options));
     }
 
     ENDPOINT("GET", "/pprof/profile", pprofProfile,
diff --git a/docs/user_guide/04_troubleshooting.md b/docs/user_guide/04_troubleshooting.md
index ed06ec4..7413559 100644
--- a/docs/user_guide/04_troubleshooting.md
+++ b/docs/user_guide/04_troubleshooting.md
@@ -718,7 +718,7 @@ int main() {
 ### Q: 可以同时进行 CPU 和 Heap profiling 吗？
 **A**: CPU 与 Heap 是两套独立的 profiling 状态，可以并存。但**同一时刻只能有一个 CPU 采样会话**：`analyzeCPUProfile()` / `getRawCPUProfile()` 会先原子认领会话，认领失败即拒绝，**不会**打断正在采样的另一方（包括宿主用 `startCPUProfiler()` 开的会话）。
 
-### Q: `/api/heap/analyze` 为什么不接受 `duration` 参数？
+### Q: Heap 窗口式采集的 `duration` 是什么意思？
 **A**: 因为对 heap profiling 而言时长没有意义。gperftools 的 heap profiling 是**按分配驱动**的：`HeapProfilerStart()` 开始记录、`HeapProfilerDump()` 写出快照，采样率由**进程启动时**的 `TCMALLOC_SAMPLE_PARAMETER` 决定，与运行时长无关。
 
 该接口内部只开一个固定的 1 秒窗口让应用自身的分配被记录，然后 dump。要提高采样精度，请**在启动前**设置 `TCMALLOC_SAMPLE_PARAMETER=524288`（默认 `0` 表示不采样，此时快照会明显偏稀疏）。
@@ -727,7 +727,7 @@ int main() {
 **A**: 说明这 1 秒窗口内进程**没有发生内存分配**。heap profiler 记录的是**窗口内的分配事件**，不是当前堆的内容，所以不会凭空造出数据。请确保被分析进程正处于负载中，或在窗口内制造真实分配后再试。
 
 ### Q: 进程内存很高，为什么 heap 图却是空的？
-**A**: 因为 `/api/heap/analyze`（以及 Web 面板上的 Heap 按钮）是**窗口式**的：只记录采样窗口内**新发生**的分配。如果内存是在采样开始前分配的、窗口内已经停止分配，结果就是空的。
+**A**: `/api/pprof/heap` 是**窗口式**的：只记录采集窗口内**新发生**的分配（流量），不反映此刻堆里的存量。`duration` 决定采集多久，默认 10 秒——实测 3 秒窗口有 35–45% 的请求采不到样本而失败。如果内存是在采样开始前分配的、窗口内已停止分配，结果就是空的。
 
 想看**当前堆的累计快照**，请改用**状态式**的 `/pprof/heap`：
 
@@ -749,23 +749,23 @@ go tool pprof -http=:8081 ./your_app heap.prof
 具体响应与 Go 的 `net/http/pprof` 对齐：
 
 - `/pprof/profile` → `500` + `text/plain` + `Could not enable CPU profiling: cpu profiling already in use`，并带 `X-Go-Pprof: 1`（`go tool pprof` 靠它识别这是错误而非 profile 数据）
-- `/api/cpu/*` → `409` + `{"error":"cpu profiling already in use"}`
+- `/api/pprof/cpu` → `409` + `{"error":"cpu profiling already in use"}`
 
 稍后重试即可。**正在进行的那个采样不受影响**，会正常完成。
 
-Heap 分析（`/api/heap/analyze`）出于同样的原因也独占，并发时返回 `409` + `{"error":"heap profiling already in use"}`。注意 `HeapProfilerStart()` 与 CPU profiler 不同——它**没有失败模式**，重复调用会静默替换输出前缀，所以必须在调用之前原子认领，而不是"先查询再启动"。`/api/growth/analyze` 不占用会话，不受限制。
+Heap 分析（`/api/pprof/heap`）出于同样的原因也独占，并发时返回 `409` + `{"error":"heap profiling already in use"}`。注意 `HeapProfilerStart()` 与 CPU profiler 不同——它**没有失败模式**，重复调用会静默替换输出前缀，所以必须在调用之前原子认领，而不是"先查询再启动"。`/api/pprof/growth` 不占用会话，不受限制。
 
 ### Q: 接口返回 500 "Failed to get heap sample" / "heap sampling is off"
-**A**: 状态式 heap 端点（`/pprof/heap`、`/api/heap/svg_raw`）依赖 `TCMALLOC_SAMPLE_PARAMETER`，而它**必须在进程启动前**设置（默认 `0` 表示关闭采样）：
+**A**: 状态式 heap 端点（`/pprof/heap`、`/api/pprof/heap/snapshot`）依赖 `TCMALLOC_SAMPLE_PARAMETER`，而它**必须在进程启动前**设置（默认 `0` 表示关闭采样）：
 
 ```bash
 export TCMALLOC_SAMPLE_PARAMETER=524288
 ./your_app
 ```
 
-窗口式端点（`/api/heap/analyze`、`/api/heap/flamegraph_raw`）走的是另一套机制，不受影响。
+窗口式端点（`/api/pprof/heap`）自己运行采集窗口，不受影响。
 
-> 以前这三种情况会给出**三种不同**的结果（`/pprof/heap` 返回 200 + `%warn` 文本、`/api/heap/svg_raw` 返回 500、`/api/heap/flamegraph_raw` 返回 200 + 一张空图）。现已统一为带原因的 500。
+> 该变量缺失时，所有状态式端点现在都返回带原因的 500（此前是三种不同表现：200 + `%warn` 文本、500、200 + 空图）。
 
 ### Q: 接口返回 500 "No stack samples to render (profile is empty)"
 **A**: 采样窗口内没有收集到足够的栈样本，`flamegraph.pl` 拒绝渲染。常见原因是采样时长太短，而目标进程在那段时间里正好空闲。加长 `duration`（例如 10–30 秒）或在有负载时重试。
@@ -775,8 +775,15 @@ export TCMALLOC_SAMPLE_PARAMETER=524288
 ### Q: 接口返回 500 "pprof did not generate valid SVG"
 **A**: 内置 pprof 脚本用 `dot`（graphviz）渲染，当 profile 采样点太少或数据异常时 `dot` 会失败并输出错误文本，因而被判定为"非 SVG"。请：① 安装 graphviz；② 加长采样时长（`?duration=30`）；③ 确认编译带 `-g`。这是已知的**既有缺陷**（错误信息未把 `dot` 的原始输出透出），记录在 [ROADMAP](../../ROADMAP.md)。
 
-### Q: 为什么 `?output_type=flamegraph` 才是火焰图？
-**A**: C++ API 的形参默认值是 `"flamegraph"`，但 HTTP 路由在未显式传参时默认 `"pprof"`，返回的是 pprof 脚本渲染的图形而非 FlameGraph 火焰图。想稳定拿到火焰图请显式指定 `output_type=flamegraph`。
+### Q: `renderer=flamegraph` 和 `renderer=callgraph` 有什么区别？
+**A**: 是**两种不同的图形**，不是同一份数据换画法：
+
+| 取值 | 产出 |
+|------|------|
+| `flamegraph`（默认） | **火焰图**：栈帧堆叠 |
+| `callgraph` | **调用图**：graphviz 节点/边，能解析内联帧，符号化更完整 |
+
+> ⚠️ 两者都**不能**在浏览器里缩放——产物内嵌的 pan/zoom 脚本依赖的元素/初始化挂钩并未出现（实测）。需要缩放请下载后用桌面工具打开。
 
 ### Q: Profile 文件很大怎么办？
 **A**: 可以压缩后交给 pprof（`pprof` 支持从 stdin 读取）：
diff --git a/include/profiler/http_handlers.h b/include/profiler/http_handlers.h
index cc905d3..639fc0e 100644
--- a/include/profiler/http_handlers.h
+++ b/include/profiler/http_handlers.h
@@ -42,6 +42,32 @@ struct HandlerResponse {
     }
 };
 
+/// @brief Which graphical form a chart endpoint should produce
+///
+/// These are two genuinely different representations, not two styles of one:
+/// a flame graph is a stack of frames, a call graph is a node/edge diagram.
+enum class ChartRenderer {
+    /// Stacked frames (FlameGraph). Self-contained SVG; the classic choice.
+    FlameGraph,
+    /// Node/edge call graph produced by the pprof script via graphviz dot.
+    /// Carries better symbolisation (it resolves inline frames).
+    CallGraph,
+};
+
+/// @brief Options shared by the /api/pprof/{cpu,heap,growth} analysis endpoints
+struct ChartOptions {
+    ChartRenderer renderer = ChartRenderer::FlameGraph;
+    /// Collection window in seconds, clamped to 1..300. Note this is how long
+    /// allocations/samples are *collected*, not a sampling rate.
+    int duration = 10;
+    /// true  -> omit Content-Disposition so a browser renders the SVG in place
+    /// false -> send `Content-Disposition: attachment` to force a download
+    bool inline_display = true;
+};
+
+/// @brief Parse the `renderer` query value; unknown values fall back to FlameGraph
+ChartRenderer parseChartRenderer(const std::string& value);
+
 /// @brief Framework-agnostic profiler HTTP endpoint handlers
 ///
 /// Usage example with any framework:
@@ -60,67 +86,47 @@ class ProfilerHttpHandlers {
     // --- Status ---
     HandlerResponse handleStatus();
 
-    // --- CPU endpoints ---
-    /// @brief Whether a CPU profiling session is already claimed
-    ///
-    /// CPU profiling is exclusive: gperftools keeps one process-global sampling
-    /// session, so at most one request may sample at a time.
+    // --- Exclusivity probes ---
+    //
+    // Both are exposed so a web adapter can refuse a request on the event-loop
+    // thread — before queueing it — using the same wording the handlers produce.
+    /// @brief Whether a CPU sampling session is claimed (by a request or the host)
     bool isCpuProfilerBusy() const;
 
-    /// @brief The response to use when @ref isCpuProfilerBusy is true
-    ///
-    /// Provided so a web adapter can refuse a request on the event-loop thread —
-    /// before it is queued for execution — using the same wording and status the
-    /// handlers themselves produce. Calling it only makes sense while
-    /// @ref isCpuProfilerBusy is true.
-    ///
-    /// `pprof_style` selects the shape:
-    ///  - true  — the shape Go's net/http/pprof uses on /pprof/profile: HTTP 500,
-    ///            `text/plain`, plus an `X-Go-Pprof: 1` marker so `go tool pprof`
-    ///            reports the message instead of parsing it as profile data
-    ///  - false — HTTP 409 with a JSON error, for the custom /api/* endpoints
+    /// @brief Whether a heap analysis is running, or the host opened a heap session
+    bool isHeapAnalyzerBusy() const;
+
+    /// @brief The response for a CPU request that arrived while the profiler is busy
+    /// @param pprof_style true -> Go's /pprof/profile shape (500 + text/plain +
+    ///        `X-Go-Pprof: 1`); false -> 409 with a JSON error for /api/* routes
     HandlerResponse cpuProfilerBusyResponse(bool pprof_style) const;
 
-    /// @brief Whether a heap analysis is already running
+    /// @brief The response for a heap analysis that arrived while one is running
+    HandlerResponse heapAnalyzerBusyResponse() const;
+
+    // --- Analysis endpoints: one entry point per profiler ---
+    /// @brief Sample CPU for the requested window and render a chart
     ///
-    /// Heap analysis reconfigures the single process-global heap profiler, so
-    /// concurrent calls are exclusive for the same reason CPU profiling is.
-    bool isHeapAnalyzerBusy() const;
+    /// Exclusive: refuses while another sampling session is active (409) rather
+    /// than queueing or preempting it.
+    HandlerResponse handleCpuChart(const ChartOptions& options);
+
+    /// @brief Sample heap for the requested window and render a chart
+    /// @note Exclusive in the same way CPU is.
+    HandlerResponse handleHeapChart(const ChartOptions& options);
 
-    /// @brief The response to use when @ref isHeapAnalyzerBusy is true
+    /// @brief Render the current heap snapshot (state-based, not a window)
     ///
-    /// Mirrors @ref cpuProfilerBusyResponse but for heap analysis, which has no
-    /// Go pprof equivalent to match: HTTP 409 with a JSON error.
-    HandlerResponse heapAnalyzerBusyResponse() const;
+    /// Answers "what is in the heap now" rather than "what was allocated during
+    /// the window", so it needs TCMALLOC_SAMPLE_PARAMETER to have been set before
+    /// the process started. `renderer` is ignored when @p as_profile is true.
+    ///
+    /// @param options Chart options (renderer used only when @p as_profile is false)
+    /// @param as_profile Return the raw profile text instead of an SVG
+    HandlerResponse handleHeapSnapshot(const ChartOptions& options, bool as_profile);
 
-    HandlerResponse handleCpuAnalyze(int duration, const std::string& output_type);
-    HandlerResponse handleCpuSvgRaw(int duration);
-    HandlerResponse handleCpuFlamegraphRaw(int duration);
-
-    // --- Heap endpoints ---
-    /// @param duration Collection window in seconds (clamped 1..300). Not a
-    ///        sampling rate -- that is fixed by TCMALLOC_SAMPLE_PARAMETER at
-    ///        process start -- but a longer window covers more allocations.
-    HandlerResponse handleHeapAnalyze(int duration, const std::string& output_type);
-
-    /// @brief Render a heap sample with the pprof script
-    /// @param duration Collection window in seconds (clamped 1..300); used only
-    ///        when @p state_based is false
-    /// @param state_based Which of the two heap sources to render:
-    ///        - false (default): run a collection window, no startup config needed
-    ///        - true: render tcmalloc's cumulative snapshot of the live heap
-    ///          (getRawHeapSample()), which requires TCMALLOC_SAMPLE_PARAMETER
-    HandlerResponse handleHeapSvgRaw(int duration, bool state_based = false);
-
-    /// @brief Render a heap sample as a FlameGraph
-    /// @param duration Collection window in seconds (clamped 1..300)
-    /// @param state_based See @ref handleHeapSvgRaw
-    HandlerResponse handleHeapFlamegraphRaw(int duration, bool state_based = false);
-
-    // --- Growth endpoints ---
-    HandlerResponse handleGrowthAnalyze(const std::string& output_type);
-    HandlerResponse handleGrowthSvgRaw();
-    HandlerResponse handleGrowthFlamegraphRaw();
+    /// @brief Sample heap growth and render a chart
+    HandlerResponse handleGrowthChart(const ChartOptions& options);
 
     // --- Standard pprof endpoints ---
     HandlerResponse handlePprofProfile(int seconds);
diff --git a/scripts/check-sanitizers.sh b/scripts/check-sanitizers.sh
new file mode 100755
index 0000000..317512f
--- /dev/null
+++ b/scripts/check-sanitizers.sh
@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# Reproduce the CI sanitizer configurations locally.
+#
+# CI caught a LeakSanitizer failure in stopHeapProfiler() that local release
+# builds never showed, because nothing here ran with -fsanitize=address. This
+# script exists so that check is one command instead of a CI round trip.
+#
+# Usage:
+#   scripts/check-sanitizers.sh            # ASan (the job that failed in CI)
+#   scripts/check-sanitizers.sh asan ubsan # pick jobs
+#   scripts/check-sanitizers.sh all
+#
+# Requires: cmake, a vcpkg checkout with the project's dependencies installed
+#           (same prerequisites as a normal build).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+cd "$PROJECT_ROOT"
+
+VCPKG_TOOLCHAIN="$PROJECT_ROOT/vcpkg/scripts/buildsystems/vcpkg.cmake"
+VCPKG_TRIPLET="${VCPKG_TARGET_TRIPLET:-x64-linux-release}"
+BUILD_ROOT="${SANITIZER_BUILD_ROOT:-$PROJECT_ROOT/build/sanitizers}"
+JOBS="$(nproc)"
+
+log() { printf '\n=== %s ===\n' "$*"; }
+die() { printf 'error: %s\n' "$*" >&2; exit 1; }
+
+[[ -f "$VCPKG_TOOLCHAIN" ]] || die "vcpkg toolchain not found at $VCPKG_TOOLCHAIN"
+
+# Allow the pre-installed vcpkg tree to be reused instead of installing a
+# manifest from scratch (matches how the local dev builds are run).
+VCPKG_INSTALLED_DIR="$PROJECT_ROOT/vcpkg_installed"
+extra_configure_args=()
+[[ -d "$VCPKG_INSTALLED_DIR" ]] && extra_configure_args+=(
+    -DVCPKG_MANIFEST_MODE=OFF
+    "-DVCPKG_INSTALLED_DIR=$VCPKG_INSTALLED_DIR"
+)
+
+# Mirrors the flag sets in .github/workflows/code-quality.yml
+run_asan() {
+    log "ASan + LSan (mirrors the CI 'Address Sanitizer' job)"
+    local dir="$BUILD_ROOT/asan"
+    cmake -S . -B "$dir" \
+        -DCMAKE_BUILD_TYPE=Debug \
+        -DCMAKE_TOOLCHAIN_FILE="$VCPKG_TOOLCHAIN" \
+        "-DVCPKG_TARGET_TRIPLET=$VCPKG_TRIPLET" \
+        -DCMAKE_CXX_FLAGS="-fsanitize=address -fno-omit-frame-pointer -g" \
+        -DCMAKE_C_FLAGS="-fsanitize=address -fno-omit-frame-pointer -g" \
+        -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address" \
+        -DCMAKE_MODULE_LINKER_FLAGS="-fsanitize=address" \
+        "${extra_configure_args[@]}"
+    cmake --build "$dir" -j"$JOBS"
+    # detect_leaks + halt_on_error: a leak must fail the run, as it does in CI.
+    ( cd "$dir" && ASAN_OPTIONS=detect_leaks=1:halt_on_error=1 \
+        LSAN_OPTIONS="suppressions=$PROJECT_ROOT/lsan.supp" \
+        ctest --output-on-failure )
+}
+
+run_ubsan() {
+    log "UBSan (mirrors the CI 'Undefined Behavior Sanitizer' job)"
+    local dir="$BUILD_ROOT/ubsan"
+    cmake -S . -B "$dir" \
+        -DCMAKE_BUILD_TYPE=Debug \
+        -DCMAKE_TOOLCHAIN_FILE="$VCPKG_TOOLCHAIN" \
+        "-DVCPKG_TARGET_TRIPLET=$VCPKG_TRIPLET" \
+        -DCMAKE_CXX_FLAGS="-fsanitize=undefined -fno-omit-frame-pointer -g" \
+        -DCMAKE_C_FLAGS="-fsanitize=undefined -fno-omit-frame-pointer -g" \
+        -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=undefined" \
+        -DCMAKE_MODULE_LINKER_FLAGS="-fsanitize=undefined" \
+        "${extra_configure_args[@]}"
+    cmake --build "$dir" -j"$JOBS"
+    # halt_on_error so a single UB report fails the run rather than scrolling by.
+    ( cd "$dir" && UBSAN_OPTIONS=halt_on_error=1:print_stacktrace=1 \
+        ctest --output-on-failure )
+}
+
+run_tsan() {
+    log "TSan (mirrors the CI job; disabled there, kept here for manual runs)"
+    local dir="$BUILD_ROOT/tsan"
+    cmake -S . -B "$dir" \
+        -DCMAKE_BUILD_TYPE=Debug \
+        -DCMAKE_TOOLCHAIN_FILE="$VCPKG_TOOLCHAIN" \
+        "-DVCPKG_TARGET_TRIPLET=$VCPKG_TRIPLET" \
+        -DCMAKE_CXX_FLAGS="-fsanitize=thread -fno-omit-frame-pointer -g" \
+        -DCMAKE_C_FLAGS="-fsanitize=thread -fno-omit-frame-pointer -g" \
+        -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=thread" \
+        -DCMAKE_MODULE_LINKER_FLAGS="-fsanitize=thread" \
+        "${extra_configure_args[@]}"
+    cmake --build "$dir" -j"$JOBS"
+    ( cd "$dir" && TSAN_OPTIONS=halt_on_error=1 ctest --output-on-failure )
+}
+
+targets=("$@")
+[[ ${#targets[@]} -eq 0 ]] && targets=(asan)
+[[ "${targets[0]}" == "all" ]] && targets=(asan ubsan tsan)
+
+for t in "${targets[@]}"; do
+    case "$t" in
+        asan)  run_asan ;;
+        ubsan) run_ubsan ;;
+        tsan)  run_tsan ;;
+        *)     die "unknown target '$t' (expected asan, ubsan, tsan or all)" ;;
+    esac
+done
+
+log "All requested sanitizer runs passed"
diff --git a/scripts/verify-web-ui.mjs b/scripts/verify-web-ui.mjs
new file mode 100755
index 0000000..a78df7f
--- /dev/null
+++ b/scripts/verify-web-ui.mjs
@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+// Drive the real control panel in headless Chrome and assert that each action
+// actually does something.
+//
+// Why this exists: several front-end defects in this project were reported as
+// "the button does nothing" *after* having been declared fixed on the strength of
+// curl requests against the server. curl cannot execute page JavaScript, so it
+// cannot see an undefined function, a button stuck disabled by a synchronous
+// throw, or a download that never starts. This script checks the browser-side
+// behaviour directly:
+//
+//   - the page loads with no JavaScript errors
+//   - every action issues the request it should, to the path it should
+//   - downloads leave a file on disk
+//   - buttons return to their normal state afterwards
+//
+// Usage:
+//   scripts/verify-web-ui.mjs [base-url]
+//
+// Requires: a running profiler_example server and a local Chrome/Chromium plus
+// puppeteer-core. If puppeteer-core is not resolvable, the script explains how to
+// get it and exits 2 rather than silently skipping -- a skipped check here is
+// what let the bugs through before.
+
+import fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const BASE = (process.argv[2] || 'http://localhost:8080').replace(/\/$/, '');
+const DOWNLOAD_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'verify-web-ui-'));
+
+// Resolve puppeteer-core from the usual places without requiring an install in
+// this repository.
+function loadPuppeteer() {
+    const require = createRequire(import.meta.url);
+    const candidates = ['puppeteer-core', 'puppeteer'];
+    for (const name of candidates) {
+        try {
+            return require(name);
+        } catch {
+            /* try the next */
+        }
+    }
+    console.error(
+        'puppeteer-core is required.\n' +
+            '  npm install puppeteer-core            # in this repo, or\n' +
+            '  npm install --prefix /tmp puppeteer-core\n' +
+            'and set NODE_PATH if it lives outside this tree.',
+    );
+    process.exit(2);
+}
+
+function findChrome() {
+    const candidates = [
+        process.env.CHROME_PATH,
+        '/usr/bin/google-chrome',
+        '/usr/bin/google-chrome-stable',
+        '/usr/bin/chromium',
+        '/usr/bin/chromium-browser',
+        '/snap/bin/chromium',
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    ].filter(Boolean);
+    for (const c of candidates) {
+        if (fs.existsSync(c)) return c;
+    }
+    console.error('No Chrome/Chromium found. Set CHROME_PATH to its executable.');
+    process.exit(2);
+}
+
+async function serverReachable() {
+    return new Promise(resolve => {
+        const req = http.get(`${BASE}/api/status`, res => {
+            res.resume();
+            resolve(res.statusCode === 200);
+        });
+        req.on('error', () => resolve(false));
+        req.setTimeout(5000, () => {
+            req.destroy();
+            resolve(false);
+        });
+    });
+}
+
+const puppeteer = loadPuppeteer();
+
+if (!(await serverReachable())) {
+    console.error(`No profiler server answering at ${BASE}/api/status.\n` +
+                  'Start one first, e.g.  TCMALLOC_SAMPLE_PARAMETER=524288 ./build/profiler_example');
+    process.exit(2);
+}
+
+const results = [];
+function record(name, ok, detail = '') {
+    results.push({ name, ok, detail });
+    console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? `  -- ${detail}` : ''}`);
+}
+
+const browser = await puppeteer.launch({
+    executablePath: findChrome(),
+    headless: true,
+    protocolTimeout: 180000,
+    args: ['--no-sandbox', '--disable-dev-shm-usage'],
+});
+
+try {
+    const page = await browser.newPage();
+    const cdp = await page.createCDPSession();
+    await cdp.send('Browser.setDownloadBehavior', {
+        behavior: 'allow',
+        downloadPath: DOWNLOAD_DIR,
+        eventsEnabled: true,
+    });
+
+    const pageErrors = [];
+    const requests = [];
+    page.on('pageerror', e => pageErrors.push(e.message));
+    page.on('request', r => {
+        const u = r.url();
+        if (u.includes('/api/')) requests.push(u);
+    });
+
+    console.log(`\nLoading ${BASE}/`);
+    await page.goto(`${BASE}/`, { waitUntil: 'networkidle2', timeout: 30000 });
+
+    record('page loads without JavaScript errors', pageErrors.length === 0, pageErrors.join(' | '));
+
+    // The panel must not reference endpoints that no longer exist.
+    const staleRefs = await page.evaluate(() => {
+        const html = document.documentElement.innerHTML;
+        const stale = [];
+        for (const p of ['/api/cpu/', '/api/heap/', '/api/growth/', 'output_type',
+                         'show_svg.html', 'show_heap_svg.html', 'show_growth_svg.html']) {
+            if (html.includes(p)) stale.push(p);
+        }
+        return stale;
+    });
+    record('panel references no removed endpoints or parameters',
+           staleRefs.length === 0, staleRefs.join(', '));
+
+    const controls = await page.evaluate(() => ({
+        cpuDuration: !!document.getElementById('cpu-duration'),
+        cpuRenderer: !!document.getElementById('cpu-renderer'),
+        heapDuration: !!document.getElementById('heap-duration'),
+        heapRenderer: !!document.getElementById('heap-renderer'),
+        growthRenderer: !!document.getElementById('growth-renderer'),
+        snapshotButtons: !!document.getElementById('snapshot-profile-btn') &&
+                         !!document.getElementById('snapshot-svg-btn'),
+    }));
+    record('all chart controls present', Object.values(controls).every(Boolean),
+           JSON.stringify(controls));
+
+    async function waitForFileCount(before, timeoutMs = 60000) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const files = fs.readdirSync(DOWNLOAD_DIR).filter(f => !f.endsWith('.crdownload'));
+            if (files.length > before) return files;
+            await new Promise(r => setTimeout(r, 250));
+        }
+        return fs.readdirSync(DOWNLOAD_DIR).filter(f => !f.endsWith('.crdownload'));
+    }
+
+    async function checkDownload(name, clickExpr) {
+        const before = fs.readdirSync(DOWNLOAD_DIR).filter(f => !f.endsWith('.crdownload')).length;
+        requests.length = 0;
+        await page.evaluate(clickExpr);
+        const files = await waitForFileCount(before);
+        const saved = files.length > before;
+        const disabled = await page.$$eval('button', bs =>
+            bs.filter(b => b.disabled).map(b => b.textContent.trim()));
+        const logText = await page.$eval('#output', el => el.textContent.replace(/\s+/g, ' ').slice(0, 90));
+        record(`${name}: request issued`, requests.length > 0, requests.join(', '));
+        record(`${name}: file saved`, saved, `files=${files.length}`);
+        record(`${name}: no button left disabled`, disabled.length === 0, disabled.join(' | '));
+        if (!saved) console.log(`        log panel: ${logText}`);
+    }
+
+    console.log('\nCPU chart (flamegraph)');
+    await checkDownload('cpu chart', () => downloadChart('cpu'));
+
+    console.log('\nCPU chart (callgraph)');
+    await page.select('#cpu-renderer', 'callgraph');
+    await checkDownload('cpu callgraph', () => downloadChart('cpu'));
+
+    console.log('\nHeap chart');
+    await checkDownload('heap chart', () => downloadChart('heap'));
+
+    console.log('\nHeap growth chart');
+    await checkDownload('growth chart', () => downloadChart('growth'));
+
+    console.log('\nHeap snapshot (raw profile)');
+    await checkDownload('snapshot profile', () => downloadSnapshot('profile'));
+
+    console.log('\nHeap snapshot (rendered SVG)');
+    await checkDownload('snapshot svg', () => downloadSnapshot('svg'));
+
+    record('no JavaScript errors during the run', pageErrors.length === 0, pageErrors.join(' | '));
+
+    const savedFiles = fs.readdirSync(DOWNLOAD_DIR);
+    console.log(`\nFiles saved to ${DOWNLOAD_DIR}:`);
+    for (const f of savedFiles) {
+        console.log(`  ${f}  (${fs.statSync(path.join(DOWNLOAD_DIR, f)).size} bytes)`);
+    }
+    const emptyFiles = savedFiles.filter(f => fs.statSync(path.join(DOWNLOAD_DIR, f)).size === 0);
+    record('every saved file is non-empty', emptyFiles.length === 0, emptyFiles.join(', '));
+} finally {
+    await browser.close();
+}
+
+const failed = results.filter(r => !r.ok);
+console.log(`\n${results.length - failed.length}/${results.length} checks passed`);
+if (failed.length) {
+    console.log('Failed checks:');
+    for (const f of failed) console.log(`  - ${f.name}${f.detail ? `: ${f.detail}` : ''}`);
+    process.exit(1);
+}
diff --git a/src/drogon_adapter.cpp b/src/drogon_adapter.cpp
index 2660ae2..f902681 100644
--- a/src/drogon_adapter.cpp
+++ b/src/drogon_adapter.cpp
@@ -99,6 +99,43 @@ void runAsync(const std::shared_ptr<AsyncExecutor>& executor, const drogon::Http
     }
 }
 
+/// Read the analysis endpoints' query parameters into a ChartOptions.
+///
+/// Defaults are deliberate: `duration` 10s because short windows collect too few
+/// samples to render (measured: 3s failed 35-45% of the time, 10s never), and
+/// `inline` so a plain link shows the SVG instead of downloading it.
+ChartOptions chartOptionsFrom(const drogon::HttpRequestPtr& req) {
+    ChartOptions options;
+
+    options.renderer = parseChartRenderer(req->getParameter("renderer"));
+
+    auto d = req->getParameter("duration");
+    if (!d.empty()) {
+        try {
+            options.duration = std::stoi(d);
+        } catch (...) {}
+    }
+
+    if (req->getParameter("output") == "attachment")
+        options.inline_display = false;
+
+    return options;
+}
+
+/// Whether a CPU request should be refused, and with what.
+std::optional<HandlerResponse> cpuBusyRejection(const ProfilerHttpHandlers& handlers) {
+    if (handlers.isCpuProfilerBusy())
+        return handlers.cpuProfilerBusyResponse(/*pprof_style=*/false);
+    return std::nullopt;
+}
+
+/// Whether a heap analysis request should be refused, and with what.
+std::optional<HandlerResponse> heapBusyRejection(const ProfilerHttpHandlers& handlers) {
+    if (handlers.isHeapAnalyzerBusy())
+        return handlers.heapAnalyzerBusyResponse();
+    return std::nullopt;
+}
+
 } // namespace
 
 void registerDrogonHandlers(profiler::ProfilerManager& profiler) {
@@ -109,256 +146,116 @@ void registerDrogonHandlers(profiler::ProfilerManager& profiler) {
     // profiling keeps its session in process-global state.
     auto executor = std::make_shared<AsyncExecutor>();
 
-    // --- GET routes ---
-    auto registerGet = [&](const std::string& path, auto fn) {
+    // ---------------------------------------------------------------------
+    // Analysis endpoints: /api/pprof/{cpu,heap,growth}
+    //
+    // Each takes renderer / duration / output. The exclusivity verdict is
+    // evaluated here, on the event-loop thread before the job is queued -- a
+    // check performed inside the job runs only after the previous job finished,
+    // so it could never observe that job still running.
+    // ---------------------------------------------------------------------
+    auto registerChart = [&](const std::string& path, HandlerResponse (ProfilerHttpHandlers::*fn)(const ChartOptions&),
+                             std::optional<HandlerResponse> (*precheck)(const ProfilerHttpHandlers&)) {
         drogon::app().registerHandler(
             path,
-            [handlers, fn = std::move(fn)]([[maybe_unused]] const drogon::HttpRequestPtr& req,
-                                           std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
-                sendResponse(((*handlers).*fn)(), std::move(callback));
+            [handlers, executor, fn, precheck](const drogon::HttpRequestPtr& req,
+                                               std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
+                if (precheck) {
+                    if (auto rejection = precheck(*handlers)) {
+                        sendResponse(*rejection, std::move(callback));
+                        return;
+                    }
+                }
+                const ChartOptions options = chartOptionsFrom(req);
+                runAsync(executor, req, std::move(callback),
+                         [handlers, fn, options]() { return ((*handlers).*fn)(options); });
             },
             {drogon::Get});
     };
 
-    // CPU profiling is exclusive (one process-global gperftools session), so a
-    // request that arrives while another is sampling is refused on the spot,
-    // exactly like Go's net/http/pprof. The verdict is produced by the handler
-    // itself so the wording and status stay in one place.
-    auto makeCpuBusyPrecheck = [handlers](bool pprof_style) {
-        return [handlers, pprof_style]() -> std::optional<HandlerResponse> {
-            if (handlers->isCpuProfilerBusy()) {
-                return handlers->cpuProfilerBusyResponse(pprof_style);
-            }
-            return std::nullopt;
-        };
-    };
-    using CpuBusyPrecheck = decltype(makeCpuBusyPrecheck(true));
-
-    // /pprof/profile must answer the way `go tool pprof` expects; the custom
-    // /api/* endpoints use an accurate JSON status instead.
-    const CpuBusyPrecheck cpu_busy_pprof = makeCpuBusyPrecheck(true);
-    const CpuBusyPrecheck cpu_busy_json = makeCpuBusyPrecheck(false);
-
-    // Heap analysis is exclusive for the same reason: it reconfigures the one
-    // process-global heap profiler, so a concurrent call would race for it.
-    auto heap_busy = [handlers]() -> std::optional<HandlerResponse> {
-        if (handlers->isHeapAnalyzerBusy()) {
-            return handlers->heapAnalyzerBusyResponse();
-        }
-        return std::nullopt;
-    };
+    registerChart("/api/pprof/cpu", &ProfilerHttpHandlers::handleCpuChart, &cpuBusyRejection);
+    registerChart("/api/pprof/heap", &ProfilerHttpHandlers::handleHeapChart, &heapBusyRejection);
+    registerChart("/api/pprof/growth", &ProfilerHttpHandlers::handleGrowthChart, nullptr);
 
-    // Same, but offloaded to the executor: used for handlers that block for
-    // seconds (sampling) or shell out to pprof/flamegraph.pl (rendering).
-    auto registerGetAsync = [&](const std::string& path, auto fn) {
-        drogon::app().registerHandler(
-            path,
-            [handlers, executor, fn = std::move(fn)](const drogon::HttpRequestPtr& req,
-                                                     std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
-                runAsync(executor, req, std::move(callback), [handlers, fn]() { return ((*handlers).*fn)(); });
-            },
-            {drogon::Get});
-    };
-
-    // --- Static pages (served directly via WebResources) ---
-    drogon::app().registerHandler("/",
-                                  []([[maybe_unused]] const drogon::HttpRequestPtr& req,
-                                     std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
-                                      sendResponse(HandlerResponse::html(WebResources::getIndexPage()),
-                                                   std::move(callback));
-                                  },
-                                  {drogon::Get});
-    drogon::app().registerHandler("/show_svg.html",
-                                  []([[maybe_unused]] const drogon::HttpRequestPtr& req,
-                                     std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
-                                      sendResponse(HandlerResponse::html(WebResources::getCpuSvgViewerPage()),
-                                                   std::move(callback));
-                                  },
-                                  {drogon::Get});
-    drogon::app().registerHandler("/show_heap_svg.html",
-                                  []([[maybe_unused]] const drogon::HttpRequestPtr& req,
-                                     std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
-                                      sendResponse(HandlerResponse::html(WebResources::getHeapSvgViewerPage()),
-                                                   std::move(callback));
-                                  },
-                                  {drogon::Get});
-    drogon::app().registerHandler("/show_growth_svg.html",
-                                  []([[maybe_unused]] const drogon::HttpRequestPtr& req,
-                                     std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
-                                      sendResponse(HandlerResponse::html(WebResources::getGrowthSvgViewerPage()),
-                                                   std::move(callback));
+    // ---------------------------------------------------------------------
+    // Heap snapshot: state-based, i.e. "what is in the heap now" rather than
+    // "what was allocated during a window". Needs TCMALLOC_SAMPLE_PARAMETER.
+    // ---------------------------------------------------------------------
+    drogon::app().registerHandler("/api/pprof/heap/snapshot",
+                                  [handlers, executor](const drogon::HttpRequestPtr& req,
+                                                       std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
+                                      const ChartOptions options = chartOptionsFrom(req);
+                                      const bool as_profile = req->getParameter("format") != "svg";
+                                      runAsync(executor, req, std::move(callback), [handlers, options, as_profile]() {
+                                          return handlers->handleHeapSnapshot(options, as_profile);
+                                      });
                                   },
                                   {drogon::Get});
 
-    // --- Status ---
-    registerGet("/api/status", &ProfilerHttpHandlers::handleStatus);
-
-    // --- Thread stacks ---
-    registerGet("/api/thread/stacks", &ProfilerHttpHandlers::handleThreadStacks);
-
-    // --- Standard pprof: /pprof/profile (blocking: samples for `seconds`) ---
+    // --- Status and auxiliary endpoints (fast enough to stay on the loop) ---
     drogon::app().registerHandler(
-        "/pprof/profile",
-        [handlers, executor, cpu_busy_pprof](const drogon::HttpRequestPtr& req,
-                                             std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
-            int seconds = 30;
-            auto p = req->getParameter("seconds");
-            if (!p.empty()) {
-                try {
-                    seconds = std::stoi(p);
-                } catch (...) {}
-                if (seconds < 1)
-                    seconds = 1;
-                if (seconds > 300)
-                    seconds = 300;
-            }
-            runAsync(
-                executor, req, std::move(callback),
-                [handlers, seconds]() { return handlers->handlePprofProfile(seconds); }, cpu_busy_pprof);
+        "/api/status",
+        [handlers](const drogon::HttpRequestPtr&, std::function<void(const drogon::HttpResponsePtr&)>&& cb) {
+            sendResponse(handlers->handleStatus(), std::move(cb));
         },
         {drogon::Get});
-
-    // --- Standard pprof: /pprof/heap ---
-    registerGet("/pprof/heap", &ProfilerHttpHandlers::handlePprofHeap);
-
-    // --- Standard pprof: /pprof/growth ---
-    registerGet("/pprof/growth", &ProfilerHttpHandlers::handlePprofGrowth);
-
-    // --- /pprof/symbol (POST) ---
-    drogon::app().registerHandler("/pprof/symbol",
-                                  [handlers]([[maybe_unused]] const drogon::HttpRequestPtr& req,
-                                             std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
-                                      sendResponse(handlers->handlePprofSymbol(std::string(req->body())),
-                                                   std::move(callback));
-                                  },
-                                  {drogon::Post});
-
-    // --- CPU analyze (blocking: samples for `duration` seconds) ---
-    drogon::app().registerHandler(
-        "/api/cpu/analyze",
-        [handlers, executor, cpu_busy_json](const drogon::HttpRequestPtr& req,
-                                            std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
-            int duration = 10;
-            auto dp = req->getParameter("duration");
-            if (!dp.empty()) {
-                try {
-                    duration = std::stoi(dp);
-                } catch (...) {}
-            }
-            std::string output_type = req->getParameter("output_type");
-            if (output_type.empty())
-                output_type = "pprof";
-
-            runAsync(
-                executor, req, std::move(callback),
-                [handlers, duration, output_type]() { return handlers->handleCpuAnalyze(duration, output_type); },
-                cpu_busy_json);
-        },
-        {drogon::Get, drogon::Post});
-
-    // --- CPU raw SVG (blocking) ---
-    drogon::app().registerHandler(
-        "/api/cpu/svg_raw",
-        [handlers, executor, cpu_busy_json](const drogon::HttpRequestPtr& req,
-                                            std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
-            int duration = 10;
-            auto dp = req->getParameter("duration");
-            if (!dp.empty()) {
-                try {
-                    duration = std::stoi(dp);
-                } catch (...) {}
-            }
-            runAsync(
-                executor, req, std::move(callback),
-                [handlers, duration]() { return handlers->handleCpuSvgRaw(duration); }, cpu_busy_json);
-        },
-        {drogon::Get});
-
-    // --- CPU FlameGraph raw (blocking) ---
     drogon::app().registerHandler(
-        "/api/cpu/flamegraph_raw",
-        [handlers, executor, cpu_busy_json](const drogon::HttpRequestPtr& req,
-                                            std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
-            int duration = 10;
-            auto dp = req->getParameter("duration");
-            if (!dp.empty()) {
-                try {
-                    duration = std::stoi(dp);
-                } catch (...) {}
-            }
-            runAsync(
-                executor, req, std::move(callback),
-                [handlers, duration]() { return handlers->handleCpuFlamegraphRaw(duration); }, cpu_busy_json);
+        "/api/thread/stacks",
+        [handlers](const drogon::HttpRequestPtr&, std::function<void(const drogon::HttpResponsePtr&)>&& cb) {
+            sendResponse(handlers->handleThreadStacks(), std::move(cb));
         },
         {drogon::Get});
 
-    // --- Heap analyze (blocking) ---
+    // --- Web control panel ---
     drogon::app().registerHandler(
-        "/api/heap/analyze",
-        [handlers, executor, heap_busy](const drogon::HttpRequestPtr& req,
-                                        std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
-            int duration = 1;
-            auto dp = req->getParameter("duration");
-            if (!dp.empty()) {
-                try {
-                    duration = std::stoi(dp);
-                } catch (...) {}
-            }
-            std::string output_type = req->getParameter("output_type");
-            if (output_type.empty())
-                output_type = "pprof";
-            runAsync(
-                executor, req, std::move(callback),
-                [handlers, duration, output_type]() { return handlers->handleHeapAnalyze(duration, output_type); },
-                heap_busy);
+        "/",
+        [](const drogon::HttpRequestPtr&, std::function<void(const drogon::HttpResponsePtr&)>&& cb) {
+            sendResponse(HandlerResponse::html(WebResources::getIndexPage()), std::move(cb));
         },
         {drogon::Get});
 
-    // --- Heap raw / FlameGraph (blocking: sample window + pprof/flamegraph.pl) ---
-    // These take a duration too, so the collection window is the caller's choice
-    // rather than whatever the process happened to be started with.
-    auto registerHeapRawAsync = [&](const std::string& path, auto fn) {
-        drogon::app().registerHandler(
-            path,
-            [handlers, executor, fn = std::move(fn)](const drogon::HttpRequestPtr& req,
-                                                     std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
-                int duration = 1;
-                auto dp = req->getParameter("duration");
-                if (!dp.empty()) {
-                    try {
-                        duration = std::stoi(dp);
-                    } catch (...) {}
-                }
-                // source=state renders tcmalloc's cumulative snapshot of the
-                // live heap instead of running a collection window.
-                const bool state_based = req->getParameter("source") == "state";
-                runAsync(executor, req, std::move(callback),
-                         [handlers, fn, duration, state_based]() { return ((*handlers).*fn)(duration, state_based); });
-            },
-            {drogon::Get});
-    };
-
-    registerHeapRawAsync("/api/heap/svg_raw", &ProfilerHttpHandlers::handleHeapSvgRaw);
-    registerHeapRawAsync("/api/heap/flamegraph_raw", &ProfilerHttpHandlers::handleHeapFlamegraphRaw);
-
-    // --- Growth analyze (blocking: shells out to pprof/flamegraph.pl) ---
-    drogon::app().registerHandler("/api/growth/analyze",
+    // ---------------------------------------------------------------------
+    // Standard Go pprof interface -- unchanged. These are the machine-readable
+    // endpoints `go tool pprof` consumes, as opposed to the /api/pprof visuals.
+    // ---------------------------------------------------------------------
+    drogon::app().registerHandler("/pprof/profile",
                                   [handlers, executor](const drogon::HttpRequestPtr& req,
                                                        std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
-                                      std::string output_type = req->getParameter("output_type");
-                                      if (output_type.empty())
-                                          output_type = "pprof";
-                                      // No precheck: growth stacks come from GetHeapGrowthStacks() and read
-                                      // no profiler session, so this may run alongside CPU sampling.
-                                      runAsync(executor, req, std::move(callback), [handlers, output_type]() {
-                                          return handlers->handleGrowthAnalyze(output_type);
-                                      });
+                                      int seconds = 30;
+                                      auto p = req->getParameter("seconds");
+                                      if (!p.empty()) {
+                                          try {
+                                              seconds = std::stoi(p);
+                                          } catch (...) {}
+                                          if (seconds < 1)
+                                              seconds = 1;
+                                          if (seconds > 300)
+                                              seconds = 300;
+                                      }
+                                      runAsync(executor, req, std::move(callback),
+                                               [handlers, seconds]() { return handlers->handlePprofProfile(seconds); });
                                   },
                                   {drogon::Get});
-
-    // --- Growth raw / FlameGraph (blocking: shells out to pprof/flamegraph.pl) ---
-    registerGetAsync("/api/growth/svg_raw", &ProfilerHttpHandlers::handleGrowthSvgRaw);
-    registerGetAsync("/api/growth/flamegraph_raw", &ProfilerHttpHandlers::handleGrowthFlamegraphRaw);
+    drogon::app().registerHandler("/pprof/heap",
+                                  [handlers, executor](const drogon::HttpRequestPtr& req,
+                                                       std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
+                                      runAsync(executor, req, std::move(callback),
+                                               [handlers]() { return handlers->handlePprofHeap(); });
+                                  },
+                                  {drogon::Get});
+    drogon::app().registerHandler("/pprof/growth",
+                                  [handlers, executor](const drogon::HttpRequestPtr& req,
+                                                       std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
+                                      runAsync(executor, req, std::move(callback),
+                                               [handlers]() { return handlers->handlePprofGrowth(); });
+                                  },
+                                  {drogon::Get});
+    drogon::app().registerHandler(
+        "/pprof/symbol",
+        [handlers](const drogon::HttpRequestPtr& req, std::function<void(const drogon::HttpResponsePtr&)>&& callback) {
+            sendResponse(handlers->handlePprofSymbol(std::string(req->body())), std::move(callback));
+        },
+        {drogon::Post});
 }
 
 PROFILER_NAMESPACE_END
diff --git a/src/http_handlers.cpp b/src/http_handlers.cpp
index 8312c7d..1cbf40b 100644
--- a/src/http_handlers.cpp
+++ b/src/http_handlers.cpp
@@ -6,6 +6,7 @@
 #include "profiler_manager.h"
 #include <chrono>
 #include <fstream>
+#include <optional>
 #include <sstream>
 
 PROFILER_NAMESPACE_BEGIN
@@ -18,10 +19,6 @@ static HandlerResponse errorResp(int status, const std::string& message) {
     return HandlerResponse::error(status, message);
 }
 
-static bool validateOutputType(const std::string& output_type) {
-    return output_type == "flamegraph" || output_type == "pprof";
-}
-
 static int clampDuration(int duration, int lo, int hi) {
     if (duration < lo)
         return lo;
@@ -92,76 +89,18 @@ HandlerResponse ProfilerHttpHandlers::handleStatus() {
 
 // --- CPU endpoints ---
 
-HandlerResponse ProfilerHttpHandlers::handleCpuAnalyze(int duration, const std::string& output_type) {
-    duration = clampDuration(duration, 1, 300);
-
-    // Fail fast instead of waiting behind (or disturbing) an in-flight session.
-    if (isCpuProfilerBusy()) {
-        return cpuProfilerBusyResponse(false);
-    }
-
-    if (!validateOutputType(output_type)) {
-        return errorResp(400, "Invalid output_type. Must be 'flamegraph' or 'pprof'");
-    }
-
-    std::string svg = profiler_.analyzeCPUProfile(duration, output_type);
-
-    if (internal::isJsonError(svg)) {
-        return errorResp(500, internal::jsonErrorMessage(svg));
-    }
-
-    return HandlerResponse::svg(svg);
-}
-
-HandlerResponse ProfilerHttpHandlers::handleCpuSvgRaw(int duration) {
-    duration = clampDuration(duration, 1, 300);
-
-    if (isCpuProfilerBusy()) {
-        return cpuProfilerBusyResponse(false);
-    }
-
-    std::string profile_data = profiler_.getRawCPUProfile(duration);
-    if (profile_data.empty()) {
-        return errorResp(500, "Failed to generate CPU profile");
-    }
-
-    std::string temp_file = "/tmp/cpu_raw.prof";
-    {
-        std::ofstream out(temp_file, std::ios::binary);
-        out.write(profile_data.data(), profile_data.size());
-    }
-
-    std::string exe_path = profiler_.getExecutablePath();
-    std::string cmd = "./pprof --svg " + exe_path + " " + temp_file + " 2>/dev/null";
-    std::string svg;
-    profiler_.executeCommand(cmd, svg);
-
-    size_t pos = svg.find("<?xml");
-    if (pos == std::string::npos)
-        pos = svg.find("<svg");
-    if (pos != std::string::npos && pos > 0)
-        svg = svg.substr(pos);
-
-    if (svg.empty() || svg.find("<svg") == std::string::npos) {
-        return errorResp(500, "Failed to generate SVG: insufficient CPU samples collected.");
-    }
-
-    auto resp = HandlerResponse::svg(svg);
-    resp.headers["Content-Disposition"] = "attachment; filename=cpu_profile.svg";
-    return resp;
-}
+namespace {
 
 /// Convert flamegraph.pl output into a response, or an error.
 ///
 /// flamegraph.pl answers unusable input with a *valid* SVG whose only content is
 /// an "ERROR: ..." message, so a structural check for <?xml or <svg passes and a
-/// 200 carrying an error reaches the caller as if it were a graph. Four handlers
-/// render flame graphs, so the check lives here rather than being repeated (and
-/// forgotten) at each call site.
-static HandlerResponse flameGraphResponse(const std::string& svg) {
-    if (svg.find("<?xml") == std::string::npos && svg.find("<svg") == std::string::npos) {
+/// 200 carrying an error reaches the caller as if it were a graph. All flame
+/// graphs funnel through here so the check cannot be forgotten at a call site.
+HandlerResponse flameGraphResponse(const std::string& svg) {
+    if (svg.find("<?xml") == std::string::npos && svg.find("<svg") == std::string::npos)
         return errorResp(500, "Failed to generate FlameGraph");
-    }
+
     if (auto pos = svg.find("ERROR:"); pos != std::string::npos) {
         auto end = svg.find('<', pos);
         std::string message = svg.substr(pos, end == std::string::npos ? std::string::npos : end - pos);
@@ -173,380 +112,182 @@ static HandlerResponse flameGraphResponse(const std::string& svg) {
     return HandlerResponse::svg(svg);
 }
 
-HandlerResponse ProfilerHttpHandlers::handleCpuFlamegraphRaw(int duration) {
-    duration = clampDuration(duration, 1, 300);
+} // namespace
 
-    if (isCpuProfilerBusy()) {
-        return cpuProfilerBusyResponse(false);
-    }
+ChartRenderer parseChartRenderer(const std::string& value) {
+    // "callgraph" is the pprof script's graphviz diagram; "flamegraph" is
+    // FlameGraph. Both were previously wrapped in one "output_type" whose values
+    // named a tool rather than the resulting picture.
+    if (value == "callgraph")
+        return ChartRenderer::CallGraph;
+    return ChartRenderer::FlameGraph;
+}
 
-    std::string profile_data = profiler_.getRawCPUProfile(duration);
-    if (profile_data.empty()) {
-        return errorResp(500, "Failed to generate CPU profile");
-    }
+namespace {
 
-    std::string temp_file = "/tmp/cpu_raw.prof";
-    {
-        std::ofstream out(temp_file, std::ios::binary);
-        out.write(profile_data.data(), profile_data.size());
+/// Apply the response's delivery mode and filename.
+///
+/// `inline_display` is the whole difference between "the browser shows the SVG"
+/// and "the browser downloads it": omitting Content-Disposition makes the
+/// browser render an image/svg+xml body as a document.
+HandlerResponse finishChart(HandlerResponse resp, const std::string& title, bool inline_display) {
+    if (!inline_display) {
+        resp.headers["Content-Disposition"] = "attachment; filename=" + title + ".svg";
     }
+    return resp;
+}
 
-    std::string exe_path = profiler_.getExecutablePath();
-    std::string collapsed_file = "/tmp/cpu_collapsed.prof";
-
-    std::ostringstream cmd;
-    cmd << "./pprof --collapsed --alloc_space " << exe_path << " " << temp_file << " > " << collapsed_file
-        << " 2>/dev/null";
-    std::string out;
-    if (!profiler_.executeCommand(cmd.str(), out)) {
-        return errorResp(500, "Failed to execute pprof --collapsed command");
-    }
+/// Write @p text to @p path, returning false if that fails.
+bool writeTempFile(const std::string& path, const std::string& text) {
+    std::ofstream out(path);
+    if (!out.is_open())
+        return false;
+    out << text;
+    return out.good();
+}
 
-    // Verify collapsed data
-    std::ifstream in(collapsed_file);
+/// Whether a collapsed-stacks file contains real stack data.
+///
+/// pprof prints "Using local file ..." progress lines; counting those as data
+/// would let an empty result through, and flamegraph.pl would then reject it two
+/// layers away from the cause.
+bool hasCollapsedData(const std::string& path) {
+    std::ifstream in(path);
     if (!in.is_open())
-        return errorResp(500, "Failed to create collapsed file");
+        return false;
     std::string line;
-    bool has_data = false;
     while (std::getline(in, line)) {
-        // Skip pprof's own chatter ("Using local file ..."), which would
-        // otherwise be mistaken for stack data; flamegraph.pl then rejects the
-        // file and the failure surfaces two layers away from its cause.
-        if (!line.empty() && line[0] != '#' && line.rfind("Using ", 0) != 0) {
-            has_data = true;
-            break;
-        }
-    }
-    in.close();
-    if (!has_data)
-        return errorResp(500, "pprof --collapsed produced no data.");
-
-    std::string fg_cmd =
-        "perl ./flamegraph.pl --title=\"CPU Flame Graph\" --width=1200 " + collapsed_file + " 2>/dev/null";
-    std::string svg;
-    profiler_.executeCommand(fg_cmd, svg);
-
-    {
-        auto checked = flameGraphResponse(svg);
-        if (checked.status != 200) {
-            return checked;
-        }
+        if (!line.empty() && line[0] != '#' && line.rfind("Using ", 0) != 0)
+            return true;
     }
-
-    auto resp = HandlerResponse::svg(svg);
-    resp.headers["Content-Disposition"] = "attachment; filename=cpu_flamegraph_" + std::to_string(duration) + "s.svg";
-    return resp;
+    return false;
 }
 
-// --- Heap endpoints ---
-
-HandlerResponse ProfilerHttpHandlers::handleHeapAnalyze(int duration, const std::string& output_type) {
-    duration = clampDuration(duration, 1, 300);
-    // Heap analysis reconfigures the process-global heap profiler, so refuse
-    // immediately rather than racing another analysis for it, or preempting a
-    // session the caller opened with startHeapProfiler().
-    if (profiler_.isHeapAnalysisInProgress() || profiler_.isProfilerRunning(profiler::ProfilerType::HEAP)) {
-        return heapAnalyzerBusyResponse();
-    }
+} // namespace
 
-    if (!validateOutputType(output_type)) {
-        return errorResp(400, "Invalid output_type. Must be 'flamegraph' or 'pprof'");
-    }
+/// Render a gperftools profile as a FlameGraph SVG.
+///
+/// @param profile_path Path to the profile file to draw
+/// @param title Flame graph title
+/// @param diagram_name Value for the response's own naming (not shown in the graph)
+static HandlerResponse renderFlameGraph(ProfilerManager& profiler, const std::string& profile_path,
+                                        const std::string& title, const std::string& diagram_name,
+                                        bool inline_display) {
+    const std::string collapsed = "/tmp/" + diagram_name + "_collapsed.prof";
+    const std::string exe = profiler.getExecutablePath();
 
-    // No duration argument: heap profiling is allocation driven, not time driven.
-    std::string svg = profiler_.analyzeHeapProfile(duration, output_type);
+    std::ostringstream cmd;
+    cmd << "./pprof --collapsed --alloc_space " << exe << " " << profile_path << " > " << collapsed << " 2>/dev/null";
 
-    if (internal::isJsonError(svg)) {
-        return errorResp(500, internal::jsonErrorMessage(svg));
-    }
+    std::string ignored;
+    if (!profiler.executeCommand(cmd.str(), ignored))
+        return errorResp(500, "Failed to execute pprof --collapsed command");
+    if (!hasCollapsedData(collapsed))
+        return errorResp(500, "No stack samples to render (profile is empty). The sample window may have "
+                              "been too short or the process idle; increase the duration or sample under "
+                              "load.");
 
-    return HandlerResponse::svg(svg);
-}
+    std::string svg;
+    std::string fg = "perl ./flamegraph.pl --title=\"" + title + "\" --width=1200 " + collapsed + " 2>/dev/null";
+    profiler.executeCommand(fg, svg);
 
-/// The sample text the heap renderers should draw.
-///
-/// Two sources exist and they answer different questions, so the caller picks:
-///  - @p state_based: getRawHeapSample(), tcmalloc's cumulative snapshot of what
-///    is currently in the heap. Needs TCMALLOC_SAMPLE_PARAMETER at process start.
-///  - otherwise: getRawHeapProfileSample(), which runs its own collection window
-///    of @p duration seconds and needs no startup configuration.
-///
-/// Returns a {"error": ...} JSON string when the source could not produce data.
-static std::string heapSampleForSource(profiler::ProfilerManager& profiler, bool state_based, int duration) {
-    return state_based ? profiler.getRawHeapSample() : profiler.getRawHeapProfileSample(duration);
+    return finishChart(flameGraphResponse(svg), diagram_name, inline_display);
 }
 
-HandlerResponse ProfilerHttpHandlers::handleHeapSvgRaw(int duration, bool state_based) {
-    duration = clampDuration(duration, 1, 300);
-
-    std::string heap_sample = heapSampleForSource(profiler_, state_based, duration);
-    if (internal::isJsonError(heap_sample)) {
-        return errorResp(500, internal::jsonErrorMessage(heap_sample));
-    }
-    if (heap_sample.empty()) {
-        return errorResp(500, state_based ? "Failed to get heap sample. Make sure TCMALLOC_SAMPLE_PARAMETER is set."
-                                          : "Failed to collect a heap sample in the requested window.");
-    }
-
-    std::string temp_file = "/tmp/heap_raw.prof";
-    {
-        std::ofstream out(temp_file);
-        out << heap_sample;
-    }
-
-    std::string exe_path = profiler_.getExecutablePath();
-    // --alloc_space, not the default --inuse_space: pprof's default reports what
-    // is live *now*, but a short collection window usually catches allocations
-    // that were already freed, giving a profile whose in-use column is zero. The
-    // render then fails with nothing useful to draw, even though the window did
-    // record real allocations. Report cumulative allocation instead, and capture
-    // the renderer's stderr so a genuine failure is not reduced to a bare status.
-    std::string cmd = "./pprof --svg --alloc_space " + exe_path + " " + temp_file + " 2>&1";
+/// Render a gperftools profile as a call-graph SVG via the pprof script.
+static HandlerResponse renderCallGraph(ProfilerManager& profiler, const std::string& profile_path,
+                                       const std::string& diagram_name, bool inline_display) {
+    const std::string exe = profiler.getExecutablePath();
     std::string svg;
-    profiler_.executeCommand(cmd, svg);
+    // --alloc_space: the default --inuse_space plots what is live now, which a
+    // short collection window rarely has; the window's allocations were already
+    // freed. stderr is kept so a failure explains itself.
+    profiler.executeCommand("./pprof --svg --alloc_space " + exe + " " + profile_path + " 2>&1", svg);
 
-    size_t pos = svg.find("<?xml");
+    auto pos = svg.find("<?xml");
     if (pos == std::string::npos)
         pos = svg.find("<svg");
     if (pos != std::string::npos && pos > 0)
         svg = svg.substr(pos);
 
     if (svg.empty() || svg.find("<svg") == std::string::npos) {
-        // "No nodes to print" is what pprof says for a *valid* profile with no
-        // records, which is the normal cold-start state of the state-based view:
-        // tcmalloc reports nothing until its first sampling event, so a freshly
-        // started process yields an empty snapshot. Say that, rather than
-        // presenting it as a rendering fault.
-        if (svg.find("No nodes to print") != std::string::npos) {
-            return errorResp(500, state_based ? "The current heap snapshot is empty, so there is nothing to draw. "
-                                                "tcmalloc reports no data until its first sampling event; this is "
-                                                "normal shortly after process start. Wait for the process to "
-                                                "allocate, then retry -- or use the window source, which collects "
-                                                "its own samples."
-                                              : "The collected heap sample contained no records. Increase the "
-                                                "duration or sample a process that is actively allocating.");
-        }
-        return errorResp(500, "pprof could not render this heap sample into an SVG. Output: " + svg);
+        if (svg.find("No nodes to print") != std::string::npos)
+            return errorResp(500, "The profile has no records to draw. Increase the duration or sample a "
+                                  "process that is actively allocating.");
+        return errorResp(500, "pprof could not render this profile into an SVG. Output: " + svg);
     }
-
-    auto resp = HandlerResponse::svg(svg);
-    resp.headers["Content-Disposition"] = "attachment; filename=heap_profile.svg";
-    return resp;
+    return finishChart(HandlerResponse::svg(svg), diagram_name, inline_display);
 }
 
-HandlerResponse ProfilerHttpHandlers::handleHeapFlamegraphRaw(int duration, bool state_based) {
-    duration = clampDuration(duration, 1, 300);
+/// Render @p profile_text, which has been written to @p tmp_path, with the chosen renderer.
+static HandlerResponse renderChart(ProfilerManager& profiler, const std::string& tmp_path,
+                                   const std::string& profile_text, const ChartOptions& options,
+                                   const std::string& diagram_name, const std::string& flamegraph_title) {
+    if (!writeTempFile(tmp_path, profile_text))
+        return errorResp(500, "Failed to write the profile to " + tmp_path);
 
-    std::string heap_sample = heapSampleForSource(profiler_, state_based, duration);
-    if (internal::isJsonError(heap_sample)) {
-        return errorResp(500, internal::jsonErrorMessage(heap_sample));
-    }
-    if (heap_sample.empty()) {
-        return errorResp(500, state_based ? "Failed to get heap sample. Make sure TCMALLOC_SAMPLE_PARAMETER is set."
-                                          : "Failed to collect a heap sample in the requested window.");
-    }
-
-    std::string temp_file = "/tmp/heap_raw.prof";
-    {
-        std::ofstream out(temp_file);
-        out << heap_sample;
-    }
-
-    std::string exe_path = profiler_.getExecutablePath();
-    std::string collapsed_file = "/tmp/heap_collapsed.prof";
-
-    std::ostringstream cmd;
-    cmd << "./pprof --collapsed --alloc_space " << exe_path << " " << temp_file << " > " << collapsed_file
-        << " 2>/dev/null";
-    std::string out;
-    if (!profiler_.executeCommand(cmd.str(), out)) {
-        return errorResp(500, "Failed to execute pprof --collapsed command");
-    }
-
-    std::ifstream in(collapsed_file);
-    if (!in.is_open())
-        return errorResp(500, "Failed to create collapsed file");
-    std::string line;
-    bool has_data = false;
-    while (std::getline(in, line)) {
-        // Skip pprof's own chatter ("Using local file ..."), which would
-        // otherwise be mistaken for stack data; flamegraph.pl then rejects the
-        // file and the failure surfaces two layers away from its cause.
-        if (!line.empty() && line[0] != '#' && line.rfind("Using ", 0) != 0) {
-            has_data = true;
-            break;
-        }
-    }
-    in.close();
-    if (!has_data)
-        return errorResp(500, "pprof --collapsed produced no data");
-
-    std::string fg_cmd =
-        "perl ./flamegraph.pl --title=\"Heap Flame Graph\" --width=1200 " + collapsed_file + " 2>/dev/null";
-    std::string svg;
-    profiler_.executeCommand(fg_cmd, svg);
-
-    auto resp = flameGraphResponse(svg);
-    std::string ts = std::to_string(
-        std::chrono::duration_cast<std::chrono::seconds>(std::chrono::system_clock::now().time_since_epoch()).count());
-    resp.headers["Content-Disposition"] = "attachment; filename=heap_flamegraph_" + ts + ".svg";
-    return resp;
+    if (options.renderer == ChartRenderer::CallGraph)
+        return renderCallGraph(profiler, tmp_path, diagram_name, options.inline_display);
+    return renderFlameGraph(profiler, tmp_path, flamegraph_title, diagram_name, options.inline_display);
 }
 
-// --- Growth endpoints ---
-
-HandlerResponse ProfilerHttpHandlers::handleGrowthAnalyze(const std::string& output_type) {
-    if (!validateOutputType(output_type)) {
-        return errorResp(400, "Invalid output_type. Must be 'flamegraph' or 'pprof'");
-    }
-
-    std::string growth = profiler_.getRawHeapGrowthStacks();
-    if (growth.empty()) {
-        return errorResp(500, "Failed to get heap growth stacks. No heap growth data available.");
-    }
-
-    std::string temp_file = "/tmp/growth_sample.prof";
-    {
-        std::ofstream out(temp_file);
-        out << growth;
-    }
-
-    std::string exe_path = profiler_.getExecutablePath();
-    std::string svg;
-
-    if (output_type == "flamegraph") {
-        std::string collapsed_file = "/tmp/growth_collapsed.prof";
-        std::ostringstream cmd;
-        cmd << "./pprof --collapsed --alloc_space " << exe_path << " " << temp_file << " > " << collapsed_file
-            << " 2>/dev/null";
-
-        std::string out;
-        if (!profiler_.executeCommand(cmd.str(), out)) {
-            return errorResp(500, "Failed to generate collapsed format");
-        }
-
-        std::ostringstream fg;
-        fg << "perl ./flamegraph.pl --title=\"Heap Growth Flame Graph\" --width=1200 " << collapsed_file
-           << " 2>/dev/null";
-        if (!profiler_.executeCommand(fg.str(), svg)) {
-            return errorResp(500, "Failed to execute flamegraph.pl command");
-        }
+/// Turn a profiler-core return value into an error response, or nothing if it is fine.
+static std::optional<HandlerResponse> coreError(const std::string& value) {
+    if (internal::isJsonError(value))
+        return errorResp(500, internal::jsonErrorMessage(value));
+    return std::nullopt;
+}
 
-        {
-            auto checked = flameGraphResponse(svg);
-            if (checked.status != 200) {
-                return checked;
-            }
-        }
-    } else {
-        std::ostringstream cmd;
-        cmd << "./pprof --svg " << exe_path << " " << temp_file << " 2>&1";
-        if (!profiler_.executeCommand(cmd.str(), svg)) {
-            return errorResp(500, "Failed to execute pprof command");
-        }
+HandlerResponse ProfilerHttpHandlers::handleCpuChart(const ChartOptions& options) {
+    if (isCpuProfilerBusy())
+        return cpuProfilerBusyResponse(false);
 
-        size_t svg_start = svg.find("<svg");
-        if (svg_start != std::string::npos) {
-            size_t tag_end = svg.find(">", svg_start);
-            if (tag_end != std::string::npos) {
-                std::string tag = svg.substr(svg_start, tag_end - svg_start);
-                if (tag.find("viewBox") == std::string::npos) {
-                    svg.insert(tag_end, " viewBox=\"0 -1000 2000 1000\"");
-                }
-            }
-        }
-    }
+    std::string profile = profiler_.getRawCPUProfile(options.duration);
+    if (auto err = coreError(profile))
+        return *err;
+    if (profile.empty())
+        return errorResp(500, "Failed to collect a CPU profile in the requested window.");
 
-    return HandlerResponse::svg(svg);
+    return renderChart(profiler_, "/tmp/cpu_chart.prof", profile, options, "cpu_profile", "CPU Flame Graph");
 }
 
-HandlerResponse ProfilerHttpHandlers::handleGrowthSvgRaw() {
-    std::string growth = profiler_.getRawHeapGrowthStacks();
-    if (growth.empty()) {
-        return errorResp(500, "Failed to get heap growth stacks. No heap growth data available.");
-    }
+HandlerResponse ProfilerHttpHandlers::handleHeapChart(const ChartOptions& options) {
+    if (isHeapAnalyzerBusy())
+        return heapAnalyzerBusyResponse();
 
-    std::string temp_file = "/tmp/growth_raw.prof";
-    {
-        std::ofstream out(temp_file);
-        out << growth;
-    }
+    std::string sample = profiler_.getRawHeapProfileSample(options.duration);
+    if (auto err = coreError(sample))
+        return *err;
+    if (sample.empty())
+        return errorResp(500, "Failed to collect a heap sample in the requested window.");
 
-    std::string exe_path = profiler_.getExecutablePath();
-    std::string cmd = "./pprof --svg " + exe_path + " " + temp_file + " 2>/dev/null";
-    std::string svg;
-    profiler_.executeCommand(cmd, svg);
+    return renderChart(profiler_, "/tmp/heap_chart.prof", sample, options, "heap_profile", "Heap Flame Graph");
+}
 
-    size_t pos = svg.find("<?xml");
-    if (pos == std::string::npos)
-        pos = svg.find("<svg");
-    if (pos != std::string::npos && pos > 0)
-        svg = svg.substr(pos);
+HandlerResponse ProfilerHttpHandlers::handleHeapSnapshot(const ChartOptions& options, bool as_profile) {
+    std::string sample = profiler_.getRawHeapSample();
+    if (sample.empty())
+        return errorResp(500, "Failed to get heap sample. Make sure TCMALLOC_SAMPLE_PARAMETER is set "
+                              "before the process was started.");
 
-    if (svg.empty() || svg.find("<svg") == std::string::npos) {
-        return errorResp(500, "Failed to generate SVG");
+    if (as_profile) {
+        // The raw profile: what `go tool pprof` consumes.
+        auto resp = HandlerResponse::text(sample);
+        return finishChart(resp, "heap", options.inline_display);
     }
 
-    auto resp = HandlerResponse::svg(svg);
-    resp.headers["Content-Disposition"] = "attachment; filename=growth_profile.svg";
-    return resp;
+    return renderChart(profiler_, "/tmp/heap_snapshot.prof", sample, options, "heap_snapshot", "Heap Snapshot");
 }
 
-HandlerResponse ProfilerHttpHandlers::handleGrowthFlamegraphRaw() {
+HandlerResponse ProfilerHttpHandlers::handleGrowthChart(const ChartOptions& options) {
     std::string growth = profiler_.getRawHeapGrowthStacks();
-    if (growth.empty()) {
+    if (growth.empty())
         return errorResp(500, "Failed to get heap growth stacks. No heap growth data available.");
-    }
-
-    std::string temp_file = "/tmp/growth_raw.prof";
-    {
-        std::ofstream out(temp_file);
-        out << growth;
-    }
-
-    std::string exe_path = profiler_.getExecutablePath();
-    std::string collapsed_file = "/tmp/growth_collapsed.prof";
-
-    std::ostringstream cmd;
-    cmd << "./pprof --collapsed --alloc_space " << exe_path << " " << temp_file << " > " << collapsed_file
-        << " 2>/dev/null";
-    std::string out;
-    if (!profiler_.executeCommand(cmd.str(), out)) {
-        return errorResp(500, "Failed to execute pprof --collapsed command");
-    }
 
-    std::ifstream in(collapsed_file);
-    if (!in.is_open())
-        return errorResp(500, "Failed to create collapsed file");
-    std::string line;
-    bool has_data = false;
-    while (std::getline(in, line)) {
-        // Skip pprof's own chatter ("Using local file ..."), which would
-        // otherwise be mistaken for stack data; flamegraph.pl then rejects the
-        // file and the failure surfaces two layers away from its cause.
-        if (!line.empty() && line[0] != '#' && line.rfind("Using ", 0) != 0) {
-            has_data = true;
-            break;
-        }
-    }
-    in.close();
-    if (!has_data)
-        return errorResp(500, "pprof --collapsed produced no data");
-
-    std::string fg_cmd =
-        "perl ./flamegraph.pl --title=\"Heap Growth Flame Graph\" --width=1200 " + collapsed_file + " 2>/dev/null";
-    std::string svg;
-    profiler_.executeCommand(fg_cmd, svg);
-
-    auto resp = flameGraphResponse(svg);
-    std::string ts = std::to_string(
-        std::chrono::duration_cast<std::chrono::seconds>(std::chrono::system_clock::now().time_since_epoch()).count());
-    resp.headers["Content-Disposition"] = "attachment; filename=growth_flamegraph_" + ts + ".svg";
-    return resp;
+    return renderChart(profiler_, "/tmp/growth_chart.prof", growth, options, "growth_profile",
+                       "Heap Growth Flame Graph");
 }
 
-// --- Standard pprof ---
-
 HandlerResponse ProfilerHttpHandlers::handlePprofProfile(int seconds) {
     seconds = clampDuration(seconds, 1, 300);
 
diff --git a/src/internal/web_resources.h b/src/internal/web_resources.h
index 4eaf8ee..01c7365 100644
--- a/src/internal/web_resources.h
+++ b/src/internal/web_resources.h
@@ -8,17 +8,9 @@ PROFILER_NAMESPACE_BEGIN
 // Web 资源管理类 - 提供嵌入的 HTML 页面内容
 class WebResources {
 public:
-    // 获取主页面 HTML
+    /// The single control panel page. Charts are delivered as downloadable or
+    /// inline SVG by the analysis endpoints; there are no separate viewer pages.
     static std::string getIndexPage();
-
-    // 获取 CPU 火焰图查看器 HTML
-    static std::string getCpuSvgViewerPage();
-
-    // 获取 Heap 火焰图查看器 HTML
-    static std::string getHeapSvgViewerPage();
-
-    // 获取 Growth 火焰图查看器 HTML
-    static std::string getGrowthSvgViewerPage();
 };
 
 PROFILER_NAMESPACE_END
diff --git a/src/web_resources.cpp b/src/web_resources.cpp
index 04241d7..cdd348f 100644
--- a/src/web_resources.cpp
+++ b/src/web_resources.cpp
@@ -192,48 +192,55 @@ static const char INDEX_PAGE[] = R"HTML(
                     <label for="cpu-duration">采样时长(秒):</label>
                     <input type="number" id="cpu-duration" value="10" min="1" max="300">
                 </div>
-                <span class="hint">
-                    两种图表类型都按上面的时长采样，区别只在渲染方式（pprof 脚本 vs FlameGraph）。
-                    CPU 采样是<b>独占</b>的：若已有请求或宿主程序正在采样，本次会被拒绝（409 / 500）。
-                </span>
                 <div class="input-group">
-                    <label for="cpu-chart-type">图表类型:</label>
-                    <select id="cpu-chart-type">
-                        <option value="pprof">pprof SVG</option>
-                        <option value="flamegraph">FlameGraph (Brendan Gregg)</option>
+                    <label for="cpu-renderer">图形:</label>
+                    <select id="cpu-renderer">
+                        <option value="flamegraph">火焰图 (FlameGraph)</option>
+                        <option value="callgraph">调用图 (callgraph)</option>
                     </select>
                 </div>
-                <button class="analyze-btn" onclick="analyzeCPU()">⚡ 一键分析并生成火焰图</button>
-                <button class="download-btn" id="cpu-download-btn" onclick="downloadCPUChart()">📥 下载 CPU 图表</button>
+                <span class="hint">
+                    两种图形是<b>不同的表达</b>：火焰图是栈帧堆叠，调用图是节点/边的有向图（且能解析内联帧）。
+                    CPU 采样是<b>独占</b>的：若已有请求或宿主程序正在采样，本次会被拒绝（409）。
+                    时长太短会采不到样本，建议 ≥10 秒。
+                </span>
+                <button class="download-btn" id="cpu-download-btn" onclick="downloadChart('cpu')">📥 下载 CPU 图表</button>
             </div>
         </div>
 
         <div class="section">
             <h2>Heap Profiler</h2>
-            <div class="card">
+            <div>
                 <div class="input-group">
-                    <label for="heap-source">数据源:</label>
-                    <select id="heap-source" onchange="onHeapSourceChange()">
-                        <option value="window">窗口式：采集一段时间内的分配</option>
-                        <option value="state">状态式：当前堆的累计快照</option>
-                    </select>
-                </div>
-                <div class="input-group" id="heap-duration-group">
                     <label for="heap-duration">采集窗口(秒):</label>
-                    <input type="number" id="heap-duration" value="1" min="1" max="300">
+                    <input type="number" id="heap-duration" value="10" min="1" max="300">
                 </div>
                 <div class="input-group">
-                    <label for="heap-chart-type">图表类型:</label>
-                    <select id="heap-chart-type">
-                        <option value="pprof">pprof SVG</option>
-                        <option value="flamegraph">FlameGraph (Brendan Gregg)</option>
+                    <label for="heap-renderer">图形:</label>
+                    <select id="heap-renderer">
+                        <option value="flamegraph">火焰图 (FlameGraph)</option>
+                        <option value="callgraph">调用图 (callgraph)</option>
                     </select>
                 </div>
-                <span class="hint" id="heap-source-hint"></span>
-                <button class="view-btn" onclick="viewHeapChart()">🔍 查看图表</button>
-                <button class="download-btn" id="heap-download-btn" onclick="downloadHeapChart()">📥 下载图表 (SVG)</button>
-                <button class="view-btn" id="heap-raw-btn" onclick="viewHeapProfile()">📄 查看原始 profile</button>
-                <button class="download-btn" id="heap-profile-btn" onclick="downloadHeapProfile()">📥 下载 profile 文本</button>
+                <span class="hint">
+                    ⚠️ 只记录<b>采集窗口内发生的分配</b>（流量），不反映此刻已经在堆里的内存（存量）。
+                    想看当前堆快照请用下面的 Heap Snapshot。分配稀疏时把窗口调长。
+                </span>
+                <button class="download-btn" id="heap-download-btn" onclick="downloadChart('heap')">📥 下载 Heap 图表</button>
+            </div>
+        </div>
+
+        <div class="section">
+            <h2>Heap Snapshot</h2>
+            <div>
+                <span class="hint">
+                    状态式：反映<b>堆里现存的内存</b>（tcmalloc 累计采样），对应
+                    <code>GET /api/pprof/heap/snapshot</code>。
+                    <b>需要</b>在进程启动前设置 <code>TCMALLOC_SAMPLE_PARAMETER</code>，否则返回 500。
+                    刚启动的进程可能显示空快照（tcmalloc 在第一次采样事件前不报告数据），稍等再试即可。
+                </span>
+                <button class="download-btn" id="snapshot-profile-btn" onclick="downloadSnapshot('profile')">📥 下载 profile 文本</button>
+                <button class="download-btn" id="snapshot-svg-btn" onclick="downloadSnapshot('svg')">📥 下载快照图 (SVG)</button>
             </div>
         </div>
 
@@ -241,14 +248,14 @@ static const char INDEX_PAGE[] = R"HTML(
             <h2>Heap Growth Profiler</h2>
             <div>
                 <div class="input-group">
-                    <label for="growth-chart-type">图表类型:</label>
-                    <select id="growth-chart-type">
-                        <option value="pprof">pprof SVG</option>
-                        <option value="flamegraph">FlameGraph (Brendan Gregg)</option>
+                    <label for="growth-renderer">图形:</label>
+                    <select id="growth-renderer">
+                        <option value="flamegraph">火焰图 (FlameGraph)</option>
+                        <option value="callgraph">调用图 (callgraph)</option>
                     </select>
                 </div>
-                <button class="analyze-btn" onclick="analyzeGrowth()">⚡ 一键分析并生成Growth火焰图</button>
-                <button class="download-btn" id="growth-download-btn" onclick="downloadGrowthChart()">📥 下载 Growth 图表</button>
+                <span class="hint">堆增长栈分析，不需要 <code>TCMALLOC_SAMPLE_PARAMETER</code>，即时获取。</span>
+                <button class="download-btn" id="growth-download-btn" onclick="downloadChart('growth')">📥 下载 Growth 图表</button>
             </div>
         </div>
 
@@ -266,398 +273,120 @@ static const char INDEX_PAGE[] = R"HTML(
     </div>
 
     <script>
-        function analyzeCPU() {
-            const duration = document.getElementById('cpu-duration').value;
-            const chartType = document.getElementById('cpu-chart-type').value;
-            log(`🚀 正在进行CPU分析，采样时长: ${duration}秒, 图表类型: ${chartType}...\n(这可能需要一些时间，请耐心等待)`);
-            document.getElementById('cpu-duration').disabled = true;
-
-            // 打开独立的SVG查看器页面，传递 output_type 参数
-            window.open(`/show_svg.html?duration=${duration}&output_type=${chartType}`, '_blank');
-
-            log('✅ 火焰图查看器已在新标签页打开');
-            log(`💡 提示：当前使用 ${chartType === 'flamegraph' ? 'Brendan Gregg FlameGraph' : 'pprof SVG'}`);
+        // ------------------------------------------------------------------
+        // 图表下载：三个 profiler 共用一条路径 /api/pprof/{cpu,heap,growth}
+        //   renderer = flamegraph | callgraph
+        //   duration = 采样/采集窗口（秒）
+        //   output   = inline | attachment
+        // Heap 快照是独立端点 /api/pprof/heap/snapshot（format=profile|svg）。
+        // ------------------------------------------------------------------
+        const CHART_SPECS = {
+            cpu:    { durationId: 'cpu-duration',    rendererId: 'cpu-renderer',    label: 'CPU' },
+            heap:   { durationId: 'heap-duration',   rendererId: 'heap-renderer',   label: 'Heap' },
+            growth: { durationId: null,              rendererId: 'growth-renderer', label: 'Heap Growth' },
+        };
 
-            document.getElementById('cpu-duration').disabled = false;
+        function chartDuration(spec) {
+            if (!spec.durationId) return null;          // growth 采集是即时的，没有窗口
+            const v = parseInt(document.getElementById(spec.durationId).value, 10);
+            return Number.isFinite(v) && v >= 1 ? Math.min(v, 300) : 10;
         }
 
-        function analyzeHeap() {
-            if (heapSource() === 'state') {
-                // 状态式由 /pprof/heap 提供，走 *_raw 端点渲染（查看图表按钮）
-                log('💡 状态式数据源请用「🔍 查看图表」——/api/heap/analyze 只做窗口式采集。');
-                viewHeapChart();
-                return;
-            }
-            const chartType = document.getElementById('heap-chart-type').value;
-            const duration = heapDuration();
-            log(`🚀 正在获取Heap火焰图 (图表类型: ${chartType}, 采集窗口: ${duration}秒)...`);
-            window.open(`/show_heap_svg.html?output_type=${chartType}&duration=${duration}`, '_blank');
-            log('✅ Heap火焰图查看器已在新标签页打开');
-            log(`💡 提示：当前使用 ${chartType === 'flamegraph' ? 'Brendan Gregg FlameGraph' : 'pprof SVG'}`);
-        }
-
-        function analyzeGrowth() {
-            const chartType = document.getElementById('growth-chart-type').value;
-            log(`🚀 正在获取Heap Growth火焰图 (图表类型: ${chartType})...`);
-            // 打开独立的SVG查看器页面，传递 output_type 参数
-            window.open(`/show_growth_svg.html?output_type=${chartType}`, '_blank');
-            log('✅ Heap Growth火焰图查看器已在新标签页打开');
-            log(`💡 提示：当前使用 ${chartType === 'flamegraph' ? 'Brendan Gregg FlameGraph' : 'pprof SVG'}`);
+        function chartUrl(kind, { output = 'attachment' } = {}) {
+            const spec = CHART_SPECS[kind];
+            const p = new URLSearchParams();
+            p.set('renderer', document.getElementById(spec.rendererId).value);
+            p.set('output', output);
+            const d = chartDuration(spec);
+            if (d !== null) p.set('duration', String(d));
+            return `/api/pprof/${kind}?${p.toString()}`;
         }
 
-        // 页面载入时渲染当前数据源的说明
-        document.addEventListener('DOMContentLoaded', onHeapSourceChange);
-
         function log(message) {
             const output = document.getElementById('output');
             output.textContent = message;
         }
 
-        function downloadCPUChart() {
-            const duration = document.getElementById('cpu-duration').value;
-            const chartType = document.getElementById('cpu-chart-type').value;
-            const btn = document.getElementById('cpu-download-btn');
-
-            // 禁用按钮，显示下载中状态
-            btn.disabled = true;
-            const originalText = btn.textContent;
-            btn.textContent = '⏳ 准备下载...';
-
-            // 根据图表类型选择端点和文件名
-            const endpoint = chartType === 'flamegraph' ? '/api/cpu/flamegraph_raw' : '/api/cpu/svg_raw';
-            const chartTypeName = chartType === 'flamegraph' ? 'FlameGraph' : 'pprof SVG';
-            const filenamePrefix = chartType === 'flamegraph' ? 'cpu_flamegraph' : 'cpu_profile';
-
-            log(`📥 开始下载 CPU ${chartTypeName} (采样时长: ${duration}秒)...`);
-
-            // 估计下载时间（基于采样时长）
-            const estimatedTime = Math.max(3, parseInt(duration) + 2); // 至少3秒
-            let countdown = estimatedTime;
-            let progressInterval;
-
-            // 启动倒计时
-            progressInterval = setInterval(() => {
-                countdown--;
-                const progress = Math.round(((estimatedTime - countdown) / estimatedTime) * 100);
-                btn.textContent = `⏳ 生成中 ${progress}% (${countdown}s)`;
-            }, 1000);
-
-            // 使用 fetch 下载文件
-            fetch(`${endpoint}?${heapQuery()}`)
-                .then(response => {
-                    if (!response.ok) {
-                        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-                    }
-                    return response.blob();
-                })
-                .then(blob => {
-                    // 清除倒计时
-                    clearInterval(progressInterval);
-                    btn.textContent = '⏳ 保存文件...';
-
-                    // 创建下载链接
-                    const url = URL.createObjectURL(blob);
-                    const a = document.createElement('a');
-                    a.href = url;
-                    a.download = `${filenamePrefix}_${duration}s.svg`;
-                    // 必须入 DOM：游离的 <a> 触发 click() 在部分浏览器上不会启动下载
-                    document.body.appendChild(a);
-                    a.click();
-                    document.body.removeChild(a);
-                    URL.revokeObjectURL(url);
-
-                    // 恢复按钮，显示成功
-                    btn.disabled = false;
-                    btn.textContent = originalText;
-                    log(`✅ CPU ${chartTypeName} 下载完成 (大小: ${(blob.size / 1024).toFixed(1)} KB)`);
-                })
-                .catch(error => {
-                    // 清除倒计时
-                    clearInterval(progressInterval);
-                    // 错误处理
-                    btn.disabled = false;
-                    btn.textContent = originalText;
-                    log(`❌ CPU ${chartTypeName} 下载失败: ${error.message}`);
-                });
-        }
-
-        // 图表类型 → 渲染端点。两个 *_raw 端点都支持 source 参数选择数据源，
-        // 因此"状态式"也能出图，而不是只能看原始文本。
-        function heapChartEndpoint(chartType) {
-            return chartType === 'flamegraph' ? '/api/heap/flamegraph_raw' : '/api/heap/svg_raw';
-        }
-
-        function heapSource() {
-            return document.getElementById('heap-source').value;
-        }
-
-        function heapDuration() {
-            const v = parseInt(document.getElementById('heap-duration').value, 10);
-            return Number.isFinite(v) && v >= 1 ? Math.min(v, 300) : 1;
-        }
-
-        const HEAP_SOURCE_HINTS = {
-            window: '⚠️ 只记录<b>采集窗口内发生的分配</b>，不反映此刻已经在堆里的内存。若进程内存虽高但已停止分配，' +
-                    '结果会是空的。分配稀疏时把窗口调长一些。<b>无需</b>启动前设置采样变量。',
-            state: '📌 反映<b>堆里现存的内存</b>（tcmalloc 累计采样），与"窗口内分配"是两套机制，结果不同属正常。' +
-                   '<b>需要</b>在进程启动前设置 <code>TCMALLOC_SAMPLE_PARAMETER</code>，否则返回 500。' +
-                   '⚠️ 刚启动的进程会返回空快照（tcmalloc 在第一次采样事件前不报告数据），' +
-                   '此时查看图表会得到"快照为空"的提示——等进程分配一段时间后重试，' +
-                   '或改用窗口式（它自己采集，不受影响）。'
-        };
-
-        function onHeapSourceChange() {
-            const state = heapSource() === 'state';
-            // 采集窗口只对窗口式有意义
-            document.getElementById('heap-duration-group').style.display = state ? 'none' : '';
-            document.getElementById('heap-source-hint').innerHTML = HEAP_SOURCE_HINTS[heapSource()];
-        }
-
-        // 组装一次请求所需的查询串
-        function heapQuery() {
-            const p = new URLSearchParams();
-            p.set('duration', String(heapDuration()));
-            if (heapSource() === 'state') p.set('source', 'state');
-            return p.toString();
-        }
-
-        // 取回图表字节。查看与下载共用，因此两者必然请求同一份数据
-        // （此前下载只拼 duration、丢掉了 source，选"状态式"时会静默拿到窗口数据）。
-        function fetchHeapChart() {
-            const chartType = document.getElementById('heap-chart-type').value;
-            const url = `${heapChartEndpoint(chartType)}?${heapQuery()}`;
-            return fetch(url).then(response => {
-                if (!response.ok) {
-                    return response.text().then(body => {
-                        let detail = `HTTP ${response.status}`;
-                        try {
-                            detail = JSON.parse(body).error || detail;
-                        } catch (e) {
-                            if (body) detail = body.trim().slice(0, 200);
-                        }
-                        return Promise.reject(new Error(detail));
-                    });
-                }
-                return response.blob();
-            });
+        /// 取回一份产物并以指定文件名存盘。
+        /// <a> 必须入 DOM 再 click：游离节点在部分浏览器不会启动下载。
+        function saveBlob(blob, filename) {
+            const url = URL.createObjectURL(blob);
+            const a = document.createElement('a');
+            a.href = url;
+            a.download = filename;
+            document.body.appendChild(a);
+            a.click();
+            document.body.removeChild(a);
+            URL.revokeObjectURL(url);
         }
 
-        function viewHeapChart() {
-            const state = heapSource() === 'state';
-            const sourceLabel = state ? '当前堆快照' : `窗口 ${heapDuration()} 秒`;
-            log(`🚀 正在渲染 Heap ${document.getElementById('heap-chart-type').value} 图表（数据源: ${sourceLabel}）...`);
-
-            fetchHeapChart()
-                .then(blob => {
-                    // 用 blob URL 打开：Content-Disposition 只影响直接导航，
-                    // 不影响 blob，所以图表会【显示】出来而不是被下载。
-                    window.open(URL.createObjectURL(blob), '_blank');
-                    log(`✅ 图表已在新标签页打开 (${(blob.size / 1024).toFixed(1)} KB)\n` +
-                        (state ? '   数据来自 /pprof/heap，需已设置 TCMALLOC_SAMPLE_PARAMETER。'
-                               : `   服务端已采集 ${heapDuration()} 秒后渲染。`) +
-                        '\n   如需保存：在该标签页另存，或点「📥 下载图表」。');
-                })
-                .catch(err => log(`❌ 渲染失败: ${err.message}`));
+        function errorTextFrom(response, body) {
+            let detail = `HTTP ${response.status}`;
+            try {
+                detail = JSON.parse(body).error || detail;
+            } catch (e) {
+                if (body) detail = body.trim().slice(0, 200);
+            }
+            return detail;
         }
 
-        // 状态式 heap 快照（/pprof/heap）：与上面的窗口式分析是两套机制。
-        // 返回的是原始 profile 文本，所以既能当文本预览，也能存成 .prof 交给
-        // `go tool pprof` 分析。
-        function fetchHeapProfile() {
-            return fetch('/pprof/heap').then(response => {
-                if (!response.ok) {
-                    if (response.status === 500) {
-                        return Promise.reject(new Error(
-                            '服务器返回 500。状态式快照需要在进程启动前设置 TCMALLOC_SAMPLE_PARAMETER ' +
-                            '（例如 524288），当前进程未设置或采样已关闭。'));
-                    }
-                    return Promise.reject(new Error(`HTTP ${response.status}: ${response.statusText}`));
-                }
-                const disposition = response.headers.get('Content-Disposition') || '';
-                const match = /filename="?([^"]+)"?/.exec(disposition);
-                return response.text().then(text => ({ text: text, filename: match ? match[1] : 'heap.prof' }));
-            });
+        function timestamp() {
+            return new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
         }
 
-        // 用文本视图直接展示（profile 是纯文本，浏览器会原样显示）
-        function viewHeapProfile() {
-            log('🚀 正在获取当前堆快照 (/pprof/heap)...');
-            fetchHeapProfile()
-                .then(r => {
-                    const blob = new Blob([r.text], { type: 'text/plain' });
-                    window.open(URL.createObjectURL(blob), '_blank');
-                    const lines = r.text.split('\n').filter(l => l.trim() !== '').length;
-                    log(`✅ 已在新标签页打开堆快照：${lines} 行 / ${r.text.length} 字节\n` +
-                        `   首行: ${r.text.split('\n')[0]}\n` +
-                        `   提示：这是原始 profile，可视化请下载后运行 ` +
-                        `go tool pprof ./your_app ${r.filename}`);
-                })
-                .catch(err => log(`❌ 获取失败: ${err.message}`));
-        }
-
-        function downloadHeapProfile() {
-            const btn = document.getElementById('heap-profile-btn');
-            const originalText = btn.textContent;
+        /// 通用下载：同一份产物既能存盘，也能用 output=inline 在新标签页显示。
+        function downloadChart(kind) {
+            const spec = CHART_SPECS[kind];
+            const btn = document.getElementById(`${kind}-download-btn`);
+            const original = btn.textContent;
             btn.disabled = true;
-            btn.textContent = '⏳ 准备下载...';
-            log('🚀 正在获取当前堆快照 (/pprof/heap)...');
+            btn.textContent = '⏳ 生成中...';
+            const d = chartDuration(spec);
+            log(`📥 正在生成 ${spec.label} 图表${d ? `（窗口 ${d} 秒）` : ''}...`);
 
-            fetchHeapProfile()
-                .then(r => {
-                    const url = URL.createObjectURL(new Blob([r.text], { type: 'text/plain' }));
-                    const a = document.createElement('a');
-                    a.href = url;
-                    a.download = r.filename;
-                    document.body.appendChild(a);
-                    a.click();
-                    document.body.removeChild(a);
-                    URL.revokeObjectURL(url);
-                    log(`✅ 已保存 ${r.filename} (${r.text.length} 字节)\n` +
-                        `   分析: go tool pprof ./your_app ${r.filename}`);
+            // Promise.resolve() 包一层：同步异常也会走 catch，否则按钮会永久 disabled
+            Promise.resolve()
+                .then(() => fetch(chartUrl(kind)))
+                .then(r => (r.ok ? r.blob() : r.text().then(t => Promise.reject(new Error(errorTextFrom(r, t))))))
+                .then(blob => {
+                    saveBlob(blob, `${kind}_${timestamp()}.svg`);
+                    log(`✅ ${spec.label} 图表已保存 (${(blob.size / 1024).toFixed(1)} KB)`);
                 })
-                .catch(err => log(`❌ 获取失败: ${err.message}`))
+                .catch(e => log(`❌ ${spec.label} 图表失败: ${e.message}`))
                 .finally(() => {
                     btn.disabled = false;
-                    btn.textContent = originalText;
+                    btn.textContent = original;
                 });
         }
 
-        function downloadHeapChart() {
-            const chartType = document.getElementById('heap-chart-type').value;
-            const btn = document.getElementById('heap-download-btn');
-
-            // 禁用按钮，显示下载中状态
+        /// Heap 快照：format=profile 取原始文本（交 go tool pprof），format=svg 取渲染图。
+        function downloadSnapshot(format) {
+            const btn = document.getElementById(format === 'svg' ? 'snapshot-svg-btn' : 'snapshot-profile-btn');
+            const original = btn.textContent;
             btn.disabled = true;
-            const originalText = btn.textContent;
-            btn.textContent = '⏳ 准备下载...';
-
-            // 端点与 source/duration 由 fetchHeapChart 统一决定
-            const chartTypeName = chartType === 'flamegraph' ? 'FlameGraph' : 'pprof SVG';
-            // 两个端点返回的都是【渲染后的图表】，不是原始 heap profile
-            // （/pprof/heap 才是原始 profile，且需要 TCMALLOC_SAMPLE_PARAMETER）
-            const filenamePrefix = chartType === 'flamegraph' ? 'heap_flamegraph' : 'heap_pprof_graph';
+            btn.textContent = '⏳ 生成中...';
+            const renderer = document.getElementById('heap-renderer').value;
+            log(`📥 正在获取堆快照 (${format === 'svg' ? '渲染图' : '原始 profile'})...`);
 
-            log(`📥 开始下载 Heap ${chartTypeName}...`);
+            const p = new URLSearchParams({ format, output: 'attachment' });
+            if (format === 'svg') p.set('renderer', renderer);
 
-            // 估计下载时间（Heap profile 通常较快）
-            const estimatedTime = 5; // 固定5秒
-            let countdown = estimatedTime;
-            let progressInterval;
-
-            // 启动倒计时
-            progressInterval = setInterval(() => {
-                countdown--;
-                const progress = Math.round(((estimatedTime - countdown) / estimatedTime) * 100);
-                btn.textContent = `⏳ 生成中 ${progress}% (${countdown}s)`;
-            }, 1000);
-
-            // 与「查看图表」走同一份数据（同一 endpoint + source + duration）。
-            // 此前这里只拼 duration，选"状态式"时会静默拿到窗口数据。
-            //
-            // fetchHeapChart() 的同步异常（例如函数名写错）会在 .catch() 挂上之前抛出，
-            // 于是倒计时继续跑、按钮永久 disabled —— 表现为"点了没反应"。用一层
-            // Promise.resolve().then() 把调用本身也纳入链中。
             Promise.resolve()
-                .then(() => fetchHeapChart())
+                .then(() => fetch(`/api/pprof/heap/snapshot?${p.toString()}`))
+                .then(r => (r.ok ? r.blob() : r.text().then(t => Promise.reject(new Error(errorTextFrom(r, t))))))
                 .then(blob => {
-                    // 清除倒计时
-                    clearInterval(progressInterval);
-                    btn.textContent = '⏳ 保存文件...';
-
-                    // 创建下载链接
-                    const url = URL.createObjectURL(blob);
-                    const a = document.createElement('a');
-                    a.href = url;
-                    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
-                    a.download = `${filenamePrefix}_${timestamp}.svg`;
-                    // 必须入 DOM：游离的 <a> 触发 click() 在部分浏览器上不会启动下载
-                    // （downloadHeapProfile 一直这么做，这几个旧函数漏了）。
-                    document.body.appendChild(a);
-                    a.click();
-                    document.body.removeChild(a);
-                    URL.revokeObjectURL(url);
-
-                    // 恢复按钮，显示成功
-                    btn.disabled = false;
-                    btn.textContent = originalText;
-                    log(`✅ Heap ${chartTypeName} 下载完成 (大小: ${(blob.size / 1024).toFixed(1)} KB)`);
+                    const name = format === 'svg' ? `heap_snapshot_${timestamp()}.svg` : 'heap.prof';
+                    saveBlob(blob, name);
+                    log(`✅ 堆快照已保存 ${name} (${(blob.size / 1024).toFixed(1)} KB)\\n` +
+                        (format === 'svg' ? '' : `   分析: go tool pprof ./your_app ${name}`));
                 })
-                .catch(error => {
-                    // 清除倒计时
-                    clearInterval(progressInterval);
-                    // 错误处理
+                .catch(e => log(`❌ 堆快照失败: ${e.message}`))
+                .finally(() => {
                     btn.disabled = false;
-                    btn.textContent = originalText;
-                    log(`❌ Heap ${chartTypeName} 下载失败: ${error.message}`);
+                    btn.textContent = original;
                 });
         }
 
-        function downloadGrowthChart() {
-            const chartType = document.getElementById('growth-chart-type').value;
-            const btn = document.getElementById('growth-download-btn');
-
-            // 禁用按钮，显示下载中状态
-            btn.disabled = true;
-            const originalText = btn.textContent;
-            btn.textContent = '⏳ 准备下载...';
-
-            // 根据图表类型选择端点和文件名
-            const endpoint = chartType === 'flamegraph' ? '/api/growth/flamegraph_raw' : '/api/growth/svg_raw';
-            const chartTypeName = chartType === 'flamegraph' ? 'FlameGraph' : 'pprof SVG';
-            const filenamePrefix = chartType === 'flamegraph' ? 'growth_flamegraph' : 'growth_profile';
-
-            log(`📥 开始下载 Growth ${chartTypeName}...`);
-
-            // 估计下载时间（Growth profile 通常较快）
-            const estimatedTime = 5; // 固定5秒
-            let countdown = estimatedTime;
-            let progressInterval;
-
-            // 启动倒计时
-            progressInterval = setInterval(() => {
-                countdown--;
-                const progress = Math.round(((estimatedTime - countdown) / estimatedTime) * 100);
-                btn.textContent = `⏳ 生成中 ${progress}% (${countdown}s)`;
-            }, 1000);
-
-            // 使用 fetch 下载文件
-            fetch(endpoint)
-                .then(response => {
-                    if (!response.ok) {
-                        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-                    }
-                    return response.blob();
-                })
-                .then(blob => {
-                    // 清除倒计时
-                    clearInterval(progressInterval);
-                    btn.textContent = '⏳ 保存文件...';
-
-                    // 创建下载链接
-                    const url = URL.createObjectURL(blob);
-                    const a = document.createElement('a');
-                    a.href = url;
-                    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
-                    a.download = `${filenamePrefix}_${timestamp}.svg`;
-                    document.body.appendChild(a);
-                    a.click();
-                    document.body.removeChild(a);
-                    URL.revokeObjectURL(url);
-
-                    // 恢复按钮，显示成功
-                    btn.disabled = false;
-                    btn.textContent = originalText;
-                    log(`✅ Growth ${chartTypeName} 下载完成 (大小: ${(blob.size / 1024).toFixed(1)} KB)`);
-                })
-                .catch(error => {
-                    // 清除倒计时
-                    clearInterval(progressInterval);
-                    // 错误处理
-                    btn.disabled = false;
-                    btn.textContent = originalText;
-                    log(`❌ Growth ${chartTypeName} 下载失败: ${error.message}`);
-                });
-        }
 
         function getThreadStacks() {
             log('🚀 正在获取所有线程堆栈...');
@@ -681,546 +410,8 @@ static const char INDEX_PAGE[] = R"HTML(
 </html>
 )HTML";
 
-static const char CPU_SVG_VIEWER_PAGE[] = R"HTML(
-<!DOCTYPE html>
-<html>
-<head>
-    <title>CPU Flame Graph Viewer</title>
-    <style>
-        body { margin: 0; padding: 20px; font-family: Arial, sans-serif; background: #f5f5f5; }
-        h1 { color: #333; margin-bottom: 10px; }
-        .info { background: #e3f2fd; padding: 15px; border-radius: 5px; margin-bottom: 20px; }
-        .info ul { margin: 10px 0; padding-left: 20px; }
-        .info li { margin: 5px 0; }
-        .toolbar { margin-bottom: 20px; }
-        button { padding: 10px 20px; margin-right: 10px; cursor: pointer; font-size: 14px; }
-        button:hover { background: #f0f0f0; }
-        #svg-container {
-            background: white;
-            border: 1px solid #ddd;
-            border-radius: 5px;
-            padding: 0;
-            width: 100%;
-            overflow: auto;
-            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
-        }
-        #svg-container svg {
-            display: block;
-        }
-    </style>
-</head>
-<body>
-    <h1>🔥 CPU 火焰图</h1>
-    <div class="info">
-        <strong>💡 查看提示：</strong>
-        <ul>
-            <li><strong>滚动：</strong> 图表可能很大，请滚动查看所有函数</li>
-            <li><strong>缩放：</strong> 使用浏览器缩放功能（Ctrl + / Ctrl -）或鼠标滚轮（按住 Ctrl）</li>
-            <li><strong>拖拽：</strong> SVG 支持鼠标拖拽</li>
-            <li><strong>搜索：</strong> 使用 Ctrl+F 搜索特定函数</li>
-        </ul>
-    </div>
-    <div class="toolbar">
-        <button onclick="loadSVG()">🔄 重新加载</button>
-        <button onclick="window.print()">🖨️ 打印</button>
-        <button onclick="downloadSVG()">⬇️ 下载 SVG</button>
-    </div>
-    <div id="svg-container">加载中...</div>
-
-    <script>
-        const urlParams = new URLSearchParams(window.location.search);
-        const duration = urlParams.get('duration') || '10';
-        const outputType = urlParams.get('output_type') || 'pprof';
-
-        function loadSVG() {
-            const container = document.getElementById('svg-container');
-            container.innerHTML = '正在加载火焰图...';
-
-            fetch(`/api/cpu/analyze?duration=${duration}&output_type=${outputType}`)
-                .then(response => response.text())
-                .then(svgText => {
-                    // Only fix viewBox for pprof SVG (not FlameGraph)
-                    if (outputType === 'pprof') {
-                        svgText = svgText.replace(/viewBox="0 -1000 2000 1000"/g, 'viewBox="0 0 2000 1000"');
-                    }
-
-                    container.innerHTML = svgText;
-
-                    const svg = container.querySelector('svg');
-                    if (svg) {
-                        svg.removeAttribute('width');
-                        svg.removeAttribute('height');
-                        svg.style.width = '100%';
-                        svg.style.height = 'auto';
-                        svg.style.display = 'block';
-                        console.log('SVG loaded and viewBox fixed');
-                    }
-                })
-                .catch(error => {
-                    container.innerHTML = `<div style="color: red; padding: 20px;">❌ 加载失败: ${error.message}</div>`;
-                });
-        }
-
-        function downloadSVG() {
-            const svg = document.querySelector('#svg-container svg');
-            if (!svg) {
-                alert('没有找到 SVG 图表');
-                return;
-            }
-            const serializer = new XMLSerializer();
-            const svgStr = serializer.serializeToString(svg);
-            const blob = new Blob([svgStr], {type: 'image/svg+xml'});
-            const url = URL.createObjectURL(blob);
-            const a = document.createElement('a');
-            a.href = url;
-            a.download = `cpu_flamegraph_${duration}s.svg`;
-            a.click();
-            URL.revokeObjectURL(url);
-        }
-
-        // 页面加载时自动加载 SVG
-        window.addEventListener('load', loadSVG);
-    </script>
-</body>
-</html>
-)HTML";
-
-static const char HEAP_SVG_VIEWER_PAGE[] = R"HTML(
-<!DOCTYPE html>
-<html>
-<head>
-    <title>Heap Flame Graph Viewer</title>
-    <style>
-        body { margin: 0; padding: 20px; font-family: Arial, sans-serif; background: #f5f5f5; }
-        h1 { color: #333; margin-bottom: 10px; }
-        .info { background: #fff3e0; padding: 15px; border-radius: 5px; margin-bottom: 20px; }
-        .info ul { margin: 10px 0; padding-left: 20px; }
-        .info li { margin: 5px 0; }
-        .toolbar { margin-bottom: 20px; }
-        button { padding: 10px 20px; margin-right: 10px; cursor: pointer; font-size: 14px; }
-        button:hover { background: #f0f0f0; }
-        #svg-container {
-            background: white;
-            border: 1px solid #ddd;
-            border-radius: 5px;
-            padding: 20px;
-            overflow: auto;
-            max-width: 100%;
-            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
-            min-height: 600px;
-            max-height: 80vh;
-        }
-        svg {
-            display: block;
-            margin: 0 auto;
-            min-width: 100%;
-            min-height: 100%;
-        }
-    </style>
-</head>
-<body>
-    <h1>🔥 Heap 内存火焰图</h1>
-    <div class="info">
-        <strong>💡 查看提示：</strong>
-        <ul>
-            <li><strong>滚动：</strong> 图表可能很大，请滚动查看所有函数</li>
-            <li><strong>缩放：</strong> 使用鼠标滚轮可以缩放视图</li>
-            <li><strong>拖拽：</strong> 按住鼠标左键可以拖动图表</li>
-            <li><strong>搜索：</strong> 使用 Ctrl+F 搜索特定函数（如 cpuIntensiveTask、FibonacciCalculator）</li>
-            <li><strong>点击：</strong> 点击节点可以高亮显示相关调用</li>
-        </ul>
-    </div>
-    <div class="toolbar">
-        <button onclick="loadSVG()">🔄 重新加载</button>
-        <button onclick="zoomIn()">🔍+ 放大</button>
-        <button onclick="zoomOut()">🔍- 缩小</button>
-        <button onclick="resetZoom()">1:1 原始大小</button>
-        <button onclick="fitToWidth()">↔️ 适应宽度</button>
-        <button onclick="window.print()">🖨️ 打印</button>
-        <button onclick="downloadSVG()">⬇️ 下载 SVG</button>
-    </div>
-    <div id="svg-container">加载中...</div>
-
-    <script>
-        let currentZoom = 1.0;
-        let svgElement = null;
-        let viewportElement = null;
-
-        const urlParams = new URLSearchParams(window.location.search);
-        const outputType = urlParams.get('output_type') || 'pprof';
-        const duration = urlParams.get('duration') || '1';
-
-        function loadSVG() {
-            document.getElementById('svg-container').innerHTML = '正在加载Heap火焰图...';
-
-            // Heap分析传递 output_type 与采集窗口
-            fetch(`/api/heap/analyze?output_type=${outputType}&duration=${duration}`)
-                .then(response => {
-                    const contentType = response.headers.get('Content-Type');
-                    if (contentType && contentType.includes('json')) {
-                        return response.json().then(data => {
-                            throw new Error(data.error || '未知错误');
-                        });
-                    }
-                    return response.text();
-                })
-                .then(svgText => {
-                    const container = document.getElementById('svg-container');
-                    container.innerHTML = svgText;
-
-                    // 调整 SVG 的显示，确保完整渲染
-                    setTimeout(() => {
-                        const svg = container.querySelector('svg');
-                        svgElement = svg;
-                        if (svg) {
-                            // 移除固定的宽高，让SVG自适应
-                            svg.removeAttribute('width');
-                            svg.removeAttribute('height');
-
-                            // 设置一个合理的最小尺寸
-                            svg.style.minWidth = '100%';
-                            svg.style.minHeight = '600px';
-
-                            // 查找并调整 viewport transform
-                            const viewport = svg.querySelector('#viewport');
-                            viewportElement = viewport;
-                            if (viewport) {
-                                // 获取当前的 transform
-                                const transform = viewport.getAttribute('transform');
-                                console.log('Original transform:', transform);
-
-                                // 不修改 transform，保持 pprof 的原始布局
-                                // 但添加一些样式让显示更好
-                                viewport.style.transformBox = 'fill-box';
-                                viewport.style.transformOrigin = 'top left';
-                            }
-
-                            // 自动滚动到包含我们函数的区域
-                            const titles = svg.querySelectorAll('title');
-                            let found = false;
-                            for (let title of titles) {
-                                const text = title.textContent;
-                                if (text.includes('cpuIntensiveTask') ||
-                                    text.includes('FibonacciCalculator') ||
-                                    text.includes('memoryIntensiveTask') ||
-                                    text.includes('DataProcessor') ||
-                                    text.includes('MatrixOperations')) {
-                                    const node = title.closest('g');
-                                    if (node && !found) {
-                                        node.scrollIntoView({behavior: 'smooth', block: 'center'});
-                                        found = true;
-
-                                        // 高亮显示找到的节点
-                                        node.style.outline = '3px solid red';
-                                        node.style.outlineOffset = '2px';
-                                    }
-                                }
-                            }
-
-                            if (found) {
-                                console.log('Found and scrolled to target function');
-                            } else {
-                                console.log('Target function not found, showing all nodes');
-                                // 如果没找到目标函数，滚动到中间
-                                const viewport = svg.querySelector('#viewport');
-                                if (viewport) {
-                                    viewport.scrollIntoView({behavior: 'smooth', block: 'center'});
-                                }
-                            }
-                        }
-                    }, 300);
-                })
-                .catch(error => {
-                    document.getElementById('svg-container').innerHTML =
-                        `<div style="color: red; padding: 20px;">❌ 加载失败: ${error.message}</div>`;
-                });
-        }
-
-        function zoomIn() {
-            if (!svgElement) return;
-            currentZoom *= 1.2;
-            applyZoom();
-        }
-
-        function zoomOut() {
-            if (!svgElement) return;
-            currentZoom /= 1.2;
-            applyZoom();
-        }
-
-        function resetZoom() {
-            if (!svgElement) return;
-            currentZoom = 1.0;
-            applyZoom();
-        }
-
-        function fitToWidth() {
-            if (!svgElement || !viewportElement) return;
-            const container = document.getElementById('svg-container');
-            const containerWidth = container.clientWidth - 40; // padding
-
-            // 获取 SVG 的实际宽度
-            const bbox = viewportElement.getBBox();
-            const svgWidth = bbox.width;
-
-            currentZoom = containerWidth / svgWidth;
-            applyZoom();
-        }
-
-        function applyZoom() {
-            if (!viewportElement) return;
-
-            // 获取原始的 transform
-            const originalTransform = viewportElement.getAttribute('transform') || '';
-
-            // 解析原始的 scale
-            const scaleMatch = originalTransform.match(/scale\(([^)]+)\)/);
-            const baseScale = scaleMatch ? parseFloat(scaleMatch[1]) : 1.0;
-
-            // 解析原始的 translate
-            const translateMatch = originalTransform.match(/translate\(([^)]+)\)/);
-            const baseTranslate = translateMatch ? translateMatch[1] : '0,0';
-
-            // 应用新的缩放
-            const newScale = baseScale * currentZoom;
-            viewportElement.setAttribute('transform',
-                `scale(${newScale},${newScale}) translate(${baseTranslate})`);
-
-            console.log(`Applied zoom: ${currentZoom}x (${newScale})`);
-        }
-
-        function downloadSVG() {
-            const svg = document.querySelector('svg');
-            if (!svg) {
-                alert('没有找到 SVG 图表');
-                return;
-            }
-            const serializer = new XMLSerializer();
-            const svgStr = serializer.serializeToString(svg);
-            const blob = new Blob([svgStr], {type: 'image/svg+xml'});
-            const url = URL.createObjectURL(blob);
-            const a = document.createElement('a');
-            a.href = url;
-            // 使用时间戳生成文件名
-            const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
-            a.download = `heap_flamegraph_${timestamp}.svg`;
-            a.click();
-            URL.revokeObjectURL(url);
-        }
-
-        // 页面加载时自动加载 SVG
-        window.addEventListener('load', loadSVG);
-    </script>
-</body>
-</html>
-)HTML";
-
-static const char GROWTH_SVG_VIEWER_PAGE[] = R"HTML(
-<!DOCTYPE html>
-<html>
-<head>
-    <title>Growth Flame Graph Viewer</title>
-    <style>
-        body { margin: 0; padding: 20px; font-family: Arial, sans-serif; background: #f5f5f5; }
-        h1 { color: #333; margin-bottom: 10px; }
-        .info { background: #fff3e0; padding: 15px; border-radius: 5px; margin-bottom: 20px; }
-        .info ul { margin: 10px 0; padding-left: 20px; }
-        .info li { margin: 5px 0; }
-        .toolbar { margin-bottom: 20px; }
-        button { padding: 10px 20px; margin-right: 10px; cursor: pointer; font-size: 14px; }
-        button:hover { background: #f0f0f0; }
-        #svg-container {
-            background: white;
-            border: 1px solid #ddd;
-            border-radius: 5px;
-            padding: 20px;
-            overflow: auto;
-            max-width: 100%;
-            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
-            min-height: 600px;
-            max-height: 80vh;
-        }
-        svg {
-            display: block;
-            margin: 0 auto;
-            min-width: 100%;
-            min-height: 100%;
-        }
-    </style>
-</head>
-<body>
-    <h1>🔥 Heap Growth 堆增长火焰图</h1>
-    <div class="info">
-        <strong>💡 查看提示：</strong>
-        <ul>
-            <li><strong>滚动：</strong> 图表可能很大，请滚动查看所有函数</li>
-            <li><strong>缩放：</strong> 使用鼠标滚轮可以缩放视图</li>
-            <li><strong>拖拽：</strong> 按住鼠标左键可以拖动图表</li>
-            <li><strong>搜索：</strong> 使用 Ctrl+F 搜索特定函数</li>
-            <li><strong>点击：</strong> 点击节点可以高亮显示相关调用</li>
-        </ul>
-    </div>
-    <div class="toolbar">
-        <button onclick="loadSVG()">🔄 重新加载</button>
-        <button onclick="zoomIn()">🔍+ 放大</button>
-        <button onclick="zoomOut()">🔍- 缩小</button>
-        <button onclick="resetZoom()">1:1 原始大小</button>
-        <button onclick="fitToWidth()">↔️ 适应宽度</button>
-        <button onclick="window.print()">🖨️ 打印</button>
-        <button onclick="downloadSVG()">⬇️ 下载 SVG</button>
-    </div>
-    <div id="svg-container">加载中...</div>
-
-    <script>
-        let currentZoom = 1.0;
-        let svgElement = null;
-        let viewportElement = null;
-
-        const urlParams = new URLSearchParams(window.location.search);
-        const outputType = urlParams.get('output_type') || 'pprof';
-
-        function loadSVG() {
-            document.getElementById('svg-container').innerHTML = '正在加载Growth火焰图...';
-
-            // Growth分析传递output_type参数
-            fetch(`/api/growth/analyze?output_type=${outputType}`)
-                .then(response => {
-                    const contentType = response.headers.get('Content-Type');
-                    if (contentType && contentType.includes('json')) {
-                        return response.json().then(data => {
-                            throw new Error(data.error || '未知错误');
-                        });
-                    }
-                    return response.text();
-                })
-                .then(svgText => {
-                    const container = document.getElementById('svg-container');
-                    container.innerHTML = svgText;
-
-                    // 调整 SVG 的显示，确保完整渲染
-                    setTimeout(() => {
-                        const svg = container.querySelector('svg');
-                        svgElement = svg;
-                        if (svg) {
-                            // 移除固定的宽高，让SVG自适应
-                            svg.removeAttribute('width');
-                            svg.removeAttribute('height');
-
-                            // 设置一个合理的最小尺寸
-                            svg.style.minWidth = '100%';
-                            svg.style.minHeight = '600px';
-
-                            // 查找并调整 viewport transform
-                            const viewport = svg.querySelector('#viewport');
-                            viewportElement = viewport;
-                            if (viewport) {
-                                // 获取当前的 transform
-                                const transform = viewport.getAttribute('transform');
-                                console.log('Original transform:', transform);
-
-                                // 不修改 transform，保持 pprof 的原始布局
-                                // 但添加一些样式让显示更好
-                                viewport.style.transformBox = 'fill-box';
-                                viewport.style.transformOrigin = 'top left';
-                            }
-                        }
-                    }, 100);
-                })
-                .catch(error => {
-                    document.getElementById('svg-container').innerHTML =
-                        `<div style="color: red; padding: 20px;">❌ 加载失败: ${error.message}</div>`;
-                    console.error('Error loading SVG:', error);
-                });
-        }
-
-        function zoomIn() {
-            currentZoom *= 1.2;
-            applyZoom();
-        }
-
-        function zoomOut() {
-            currentZoom /= 1.2;
-            applyZoom();
-        }
-
-        function resetZoom() {
-            currentZoom = 1.0;
-            applyZoom();
-        }
-
-        function fitToWidth() {
-            const container = document.getElementById('svg-container');
-            const svg = container.querySelector('svg');
-            if (!svg) return;
-
-            const containerWidth = container.clientWidth - 40;
-            const svgWidth = svg.getBBox().width;
-
-            currentZoom = containerWidth / svgWidth;
-            applyZoom();
-        }
-
-        function applyZoom() {
-            if (!viewportElement) return;
-
-            const originalTransform = viewportElement.getAttribute('transform') || '';
-
-            // 解析原始的 scale
-            const scaleMatch = originalTransform.match(/scale\(([^)]+)\)/);
-            const baseScale = scaleMatch ? parseFloat(scaleMatch[1]) : 1.0;
-
-            // 解析原始的 translate
-            const translateMatch = originalTransform.match(/translate\(([^)]+)\)/);
-            const baseTranslate = translateMatch ? translateMatch[1] : '0,0';
-
-            // 应用新的缩放
-            const newScale = baseScale * currentZoom;
-            viewportElement.setAttribute('transform',
-                `scale(${newScale},${newScale}) translate(${baseTranslate})`);
-
-            console.log(`Applied zoom: ${currentZoom}x (${newScale})`);
-        }
-
-        function downloadSVG() {
-            const svg = document.querySelector('svg');
-            if (!svg) {
-                alert('没有找到 SVG 图表');
-                return;
-            }
-            const serializer = new XMLSerializer();
-            const svgStr = serializer.serializeToString(svg);
-            const blob = new Blob([svgStr], {type: 'image/svg+xml'});
-            const url = URL.createObjectURL(blob);
-            const a = document.createElement('a');
-            a.href = url;
-            // 使用时间戳生成文件名
-            const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
-            a.download = `growth_flamegraph_${timestamp}.svg`;
-            a.click();
-            URL.revokeObjectURL(url);
-        }
-
-        // 页面加载时自动加载 SVG
-        window.addEventListener('load', loadSVG);
-    </script>
-</body>
-</html>
-)HTML";
-
 std::string WebResources::getIndexPage() {
     return std::string(INDEX_PAGE);
 }
 
-std::string WebResources::getCpuSvgViewerPage() {
-    return std::string(CPU_SVG_VIEWER_PAGE);
-}
-
-std::string WebResources::getHeapSvgViewerPage() {
-    return std::string(HEAP_SVG_VIEWER_PAGE);
-}
-
-std::string WebResources::getGrowthSvgViewerPage() {
-    return std::string(GROWTH_SVG_VIEWER_PAGE);
-}
-
 PROFILER_NAMESPACE_END
diff --git a/tests/test_http_handlers.cpp b/tests/test_http_handlers.cpp
index 8ce87bc..060d2a7 100644
--- a/tests/test_http_handlers.cpp
+++ b/tests/test_http_handlers.cpp
@@ -21,6 +21,20 @@
 
 namespace {
 
+/// Build ChartOptions concisely for tests.
+profiler::ChartOptions opts(int duration = 1, profiler::ChartRenderer renderer = profiler::ChartRenderer::FlameGraph,
+                            bool inline_display = true) {
+    profiler::ChartOptions o;
+    o.duration = duration;
+    o.renderer = renderer;
+    o.inline_display = inline_display;
+    return o;
+}
+
+} // namespace
+
+namespace {
+
 /// Handlers that never touch the filesystem or spawn pprof can be tested
 /// directly. Anything that renders an SVG shells out to ./pprof and is covered
 /// by test_full_flow instead.
@@ -60,21 +74,12 @@ TEST_F(HttpHandlersTest, StatusUsesMillisecondDurationKeys) {
 }
 
 // ---------------------------------------------------------------------------
-// output_type validation
+// renderer parsing
 // ---------------------------------------------------------------------------
-
-TEST_F(HttpHandlersTest, InvalidOutputTypeIsRejectedWith400) {
-    auto resp = handlers.handleCpuAnalyze(1, "iciclegraph");
-
-    EXPECT_EQ(resp.status, 400);
-    EXPECT_NE(resp.body.find("output_type"), std::string::npos) << "error message should name the offending parameter";
-}
-
-TEST_F(HttpHandlersTest, EmptyOutputTypeIsRejected) {
-    auto resp = handlers.handleCpuAnalyze(1, "");
-    EXPECT_EQ(resp.status, 400);
-}
-
+// (an unknown renderer is not an error: parseChartRenderer falls back to
+// FlameGraph rather than failing the request, so there is no 400 case to assert.
+// The mapping itself is covered by ChartRendererParsing.)
+//
 // ---------------------------------------------------------------------------
 // HandlerResponse helpers
 // ---------------------------------------------------------------------------
@@ -152,9 +157,9 @@ TEST(ConcurrentCpuProfilingTest, RequestsFailFastWhileASessionIsSampling) {
 
     // Every CPU entry point must refuse immediately, not wait for the sampler.
     const auto t0 = std::chrono::steady_clock::now();
-    EXPECT_EQ(handlers.handleCpuAnalyze(5, "pprof").status, 409);
-    EXPECT_EQ(handlers.handleCpuSvgRaw(5).status, 409);
-    EXPECT_EQ(handlers.handleCpuFlamegraphRaw(5).status, 409);
+    EXPECT_EQ(handlers.handleCpuChart(opts(5)).status, 409);
+    EXPECT_EQ(handlers.handleCpuChart(opts(5, profiler::ChartRenderer::CallGraph)).status, 409);
+    EXPECT_EQ(handlers.handleCpuChart(opts(5)).status, 409);
     const auto elapsed = std::chrono::steady_clock::now() - t0;
     EXPECT_LT(elapsed, std::chrono::milliseconds(100))
         << "rejection must be immediate, not queued behind the running session";
@@ -275,8 +280,8 @@ TEST(HostOwnedSessionTest, HandlersReportTheHostSessionAsBusy) {
     ASSERT_EQ(resp.headers.count("X-Go-Pprof"), 1u);
 
     // The /api/* endpoints report a conflict.
-    EXPECT_EQ(handlers.handleCpuAnalyze(1, "pprof").status, 409);
-    EXPECT_EQ(handlers.handleCpuSvgRaw(1).status, 409);
+    EXPECT_EQ(handlers.handleCpuChart(opts(1)).status, 409);
+    EXPECT_EQ(handlers.handleCpuChart(opts(1, profiler::ChartRenderer::CallGraph)).status, 409);
 
     profiler.stopCPUProfiler();
 }
@@ -292,7 +297,7 @@ TEST(HostOwnedSessionTest, HeapAnalysisRefusesToTakeOverAHostSession) {
     EXPECT_NE(result.find("heap profiling already in use"), std::string::npos) << result;
     EXPECT_TRUE(profiler.isProfilerRunning(profiler::ProfilerType::HEAP));
 
-    EXPECT_EQ(handlers.handleHeapAnalyze(1, "pprof").status, 409);
+    EXPECT_EQ(handlers.handleHeapChart(opts(1)).status, 409);
 
     EXPECT_TRUE(profiler.stopHeapProfiler());
 }
@@ -367,7 +372,7 @@ TEST(ConcurrentHeapAnalysisTest, HandlerReportsConflict) {
     HeapAnalysisHolder holder{profiler};
     ASSERT_TRUE(waitForHeapClaim(profiler));
 
-    auto resp = handlers.handleHeapAnalyze(1, "pprof");
+    auto resp = handlers.handleHeapChart(opts(1));
 
     EXPECT_EQ(resp.status, 409);
     EXPECT_NE(resp.body.find("heap profiling already in use"), std::string::npos) << resp.body;
@@ -389,36 +394,33 @@ TEST(ConcurrentHeapAnalysisTest, ClaimIsReleasedAfterwards) {
 // Heap analysis API shape
 // ---------------------------------------------------------------------------
 
-TEST_F(HttpHandlersTest, HeapAnalysisTakesACollectionWindow) {
-    // Heap analysis takes a duration, but it is a *collection window*, not a
-    // sampling rate: the rate is fixed by TCMALLOC_SAMPLE_PARAMETER at process
-    // start. A longer window covers more allocations, which is what a sparsely
-    // allocating process needs. Guard the contract so the distinction cannot
-    // silently regress into "duration is accepted but ignored".
-    static_assert(std::is_invocable_v<decltype(&profiler::ProfilerHttpHandlers::handleHeapAnalyze),
-                                      profiler::ProfilerHttpHandlers*, int, const std::string&>,
-                  "handleHeapAnalyze must take (duration, output_type)");
-
-    // The renderers take one too, since each can run its own sampling window.
-    // Their full signature (duration, state_based) is asserted separately in
-    // HeapRenderersCanDrawEitherSource.
-}
-
-TEST_F(HttpHandlersTest, HeapAnalyzeRejectsInvalidOutputType) {
-    auto resp = handlers.handleHeapAnalyze(1, "bogus");
-    EXPECT_EQ(resp.status, 400);
-}
-
-TEST_F(HttpHandlersTest, HeapRenderersCanDrawEitherSource) {
-    // Both renderers must be invocable for either heap source, so the UI can
-    // offer a graph for the state-based snapshot too -- not only the raw text.
+TEST_F(HttpHandlersTest, ChartEndpointsTakeDurationAndRenderer) {
+    // Each analysis endpoint takes a ChartOptions carrying duration, renderer and
+    // delivery mode. The duration is a *collection window*, not a sampling rate:
+    // the rate is fixed by TCMALLOC_SAMPLE_PARAMETER at process start. A longer
+    // window covers more allocations, which is what a sparsely allocating process
+    // needs. Guard the contract so it cannot regress into "duration is ignored".
     using H = profiler::ProfilerHttpHandlers;
 
-    auto svg = static_cast<profiler::HandlerResponse (H::*)(int, bool)>(&H::handleHeapSvgRaw);
-    EXPECT_TRUE((std::is_invocable_v<decltype(svg), H*, int, bool>));
+    static_assert(std::is_invocable_v<decltype(&H::handleCpuChart), H*, const profiler::ChartOptions&>,
+                  "handleCpuChart must take ChartOptions");
+    static_assert(std::is_invocable_v<decltype(&H::handleHeapChart), H*, const profiler::ChartOptions&>,
+                  "handleHeapChart must take ChartOptions");
+    static_assert(std::is_invocable_v<decltype(&H::handleGrowthChart), H*, const profiler::ChartOptions&>,
+                  "handleGrowthChart must take ChartOptions");
+    static_assert(std::is_invocable_v<decltype(&H::handleHeapSnapshot), H*, const profiler::ChartOptions&, bool>,
+                  "handleHeapSnapshot must take (ChartOptions, as_profile)");
+}
 
-    auto fg = static_cast<profiler::HandlerResponse (H::*)(int, bool)>(&H::handleHeapFlamegraphRaw);
-    EXPECT_TRUE((std::is_invocable_v<decltype(fg), H*, int, bool>));
+TEST_F(HttpHandlersTest, ChartRendererParsing) {
+    // "callgraph" is the pprof/graphviz diagram, "flamegraph" is FlameGraph. The
+    // old parameter was called output_type and its values named a tool rather
+    // than the resulting picture, which is what these names replace.
+    EXPECT_EQ(profiler::parseChartRenderer("callgraph"), profiler::ChartRenderer::CallGraph);
+    EXPECT_EQ(profiler::parseChartRenderer("flamegraph"), profiler::ChartRenderer::FlameGraph);
+    // Unknown or empty values fall back rather than failing the request.
+    EXPECT_EQ(profiler::parseChartRenderer(""), profiler::ChartRenderer::FlameGraph);
+    EXPECT_EQ(profiler::parseChartRenderer("pprof"), profiler::ChartRenderer::FlameGraph);
 }
 
 TEST_F(HttpHandlersTest, StateBasedRenderingReportsTheMissingSamplingVariable) {
@@ -433,7 +435,7 @@ TEST_F(HttpHandlersTest, StateBasedRenderingReportsTheMissingSamplingVariable) {
     ASSERT_TRUE(plain.getRawHeapSample().empty()) << "precondition: sampling is off in the test process";
 
     profiler::ProfilerHttpHandlers h(plain);
-    auto state = h.handleHeapSvgRaw(1, /*state_based=*/true);
+    auto state = h.handleHeapSnapshot(opts(1), /*as_profile=*/false);
     EXPECT_EQ(state.status, 500);
     EXPECT_NE(state.body.find("TCMALLOC_SAMPLE_PARAMETER"), std::string::npos) << state.body;
 }
@@ -444,7 +446,7 @@ TEST_F(HttpHandlersTest, WindowBasedRenderingDoesNotMentionTheVariable) {
 
     // Duration is clamped, and the window path must not blame the environment
     // variable it does not depend on.
-    auto resp = h.handleHeapSvgRaw(0, /*state_based=*/false);
+    auto resp = h.handleHeapChart(opts(0));
     if (resp.status == 500) {
         EXPECT_EQ(resp.body.find("TCMALLOC_SAMPLE_PARAMETER"), std::string::npos)
             << "window-based failure must not blame a variable it does not need: " << resp.body;

From 4f42a76266de74b3418b1c4dd86b4f4df6d6db80 Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Tue, 15 Sep 2026 06:35:39 +0800
Subject: [PATCH 11/21] fix(web): serve SVGs as image/svg+xml and expose the
 inline mode in the panel
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two problems behind "inline and the other mode look the same in the panel".

The panel's download buttons hard-coded output=attachment, so the inline mode had
no way to be exercised from the UI at all -- it only worked if you assembled the
URL yourself, which is exactly the sort of thing that makes a feature look
absent. Each section now has both a 打开 (inline) and a 下载 (attachment) button.

The adapter also downgraded every SVG to CT_TEXT_XML, the generic XML type,
discarding the image/svg+xml that HandlerResponse::svg() sets. Drogon has
CT_IMAGE_SVG_XML, so the correct type is used now. Rendering happened to work
with text/xml, but the declared type is what governs how a browser treats the
document -- "save image as" among other things -- and there was no reason to
report the wrong one. Verified: inline -> image/svg+xml with no Content-Disposition
and the browser renders a 1200x422 document with 38 frames; attachment -> same
type plus Content-Disposition and navigation aborts into a download.

verify-web-ui.mjs gained three assertions for the delivery modes, because the
existing checks could not have caught this: they only ever clicked download
buttons, so they never observed inline at all. It also asserts the four 打开
actions exist. 27/27 checks pass, up from 23.

The script's own framing was the gap: it verified "the button does its job"
without verifying "the other button does a different job". A feature that is
unreachable from the UI reads as missing no matter how correct the server is.
---
 scripts/verify-web-ui.mjs | 33 +++++++++++++++++++++++++++++++++
 src/drogon_adapter.cpp    |  7 +++++--
 src/web_resources.cpp     | 25 +++++++++++++++++++++++++
 3 files changed, 63 insertions(+), 2 deletions(-)

diff --git a/scripts/verify-web-ui.mjs b/scripts/verify-web-ui.mjs
index a78df7f..eccdc4d 100755
--- a/scripts/verify-web-ui.mjs
+++ b/scripts/verify-web-ui.mjs
@@ -139,6 +139,10 @@ try {
     record('panel references no removed endpoints or parameters',
            staleRefs.length === 0, staleRefs.join(', '));
 
+    const openButtons = await page.evaluate(() =>
+        document.querySelectorAll('button[onclick^="openChart"], button[onclick^="openSnapshot"]').length);
+    record('panel exposes the inline (open in place) actions', openButtons === 4, `found ${openButtons}`);
+
     const controls = await page.evaluate(() => ({
         cpuDuration: !!document.getElementById('cpu-duration'),
         cpuRenderer: !!document.getElementById('cpu-renderer'),
@@ -195,6 +199,35 @@ try {
     console.log('\nHeap snapshot (rendered SVG)');
     await checkDownload('snapshot svg', () => downloadSnapshot('svg'));
 
+    // The delivery modes must actually differ in the response, not just in the
+    // query string: `inline` omits Content-Disposition so the browser renders the
+    // SVG as a document, `attachment` sets it so the browser downloads.
+    console.log('\nDelivery modes');
+    const modes = await page.evaluate(async () => {
+        const out = {};
+        for (const mode of ['inline', 'attachment']) {
+            const r = await fetch(`/api/pprof/cpu?duration=10&renderer=flamegraph&output=${mode}`);
+            out[mode] = {
+                status: r.status,
+                contentType: r.headers.get('content-type') || '',
+                disposition: r.headers.get('content-disposition') || '',
+                bytes: (await r.blob()).size,
+            };
+        }
+        return out;
+    });
+    record('inline returns SVG with no Content-Disposition',
+           modes.inline.status === 200 &&
+               modes.inline.contentType.includes('image/svg+xml') &&
+               modes.inline.disposition === '',
+           JSON.stringify(modes.inline));
+    record('attachment sets Content-Disposition',
+           modes.attachment.status === 200 && modes.attachment.disposition.startsWith('attachment'),
+           JSON.stringify(modes.attachment));
+    record('both modes return the same kind of payload',
+           modes.inline.bytes > 1000 && modes.attachment.bytes > 1000,
+           `inline=${modes.inline.bytes}B attachment=${modes.attachment.bytes}B`);
+
     record('no JavaScript errors during the run', pageErrors.length === 0, pageErrors.join(' | '));
 
     const savedFiles = fs.readdirSync(DOWNLOAD_DIR);
diff --git a/src/drogon_adapter.cpp b/src/drogon_adapter.cpp
index f902681..269c2d9 100644
--- a/src/drogon_adapter.cpp
+++ b/src/drogon_adapter.cpp
@@ -22,8 +22,11 @@ static void sendResponse(const HandlerResponse& hr, std::function<void(const dro
         resp->setContentTypeCode(drogon::CT_TEXT_HTML);
     } else if (hr.content_type == "application/json") {
         resp->setContentTypeCode(drogon::CT_APPLICATION_JSON);
-    } else if (hr.content_type == "image/svg+xml" || hr.content_type == "text/xml") {
-        resp->setContentTypeCode(drogon::CT_TEXT_XML);
+    } else if (hr.content_type == "image/svg+xml") {
+        // CT_IMAGE_SVG_XML, not CT_TEXT_XML: the latter is the generic XML type.
+        // The SVG type is what tells the browser to treat the body as an image
+        // document (and what makes "save image as" work as an SVG).
+        resp->setContentTypeCode(drogon::CT_IMAGE_SVG_XML);
     } else if (hr.content_type == "application/octet-stream") {
         resp->setContentTypeCode(drogon::CT_APPLICATION_OCTET_STREAM);
     } else {
diff --git a/src/web_resources.cpp b/src/web_resources.cpp
index cdd348f..ffc6a6f 100644
--- a/src/web_resources.cpp
+++ b/src/web_resources.cpp
@@ -204,6 +204,7 @@ static const char INDEX_PAGE[] = R"HTML(
                     CPU 采样是<b>独占</b>的：若已有请求或宿主程序正在采样，本次会被拒绝（409）。
                     时长太短会采不到样本，建议 ≥10 秒。
                 </span>
+                <button class="view-btn" onclick="openChart('cpu')">🔗 打开 CPU 图表</button>
                 <button class="download-btn" id="cpu-download-btn" onclick="downloadChart('cpu')">📥 下载 CPU 图表</button>
             </div>
         </div>
@@ -226,6 +227,7 @@ static const char INDEX_PAGE[] = R"HTML(
                     ⚠️ 只记录<b>采集窗口内发生的分配</b>（流量），不反映此刻已经在堆里的内存（存量）。
                     想看当前堆快照请用下面的 Heap Snapshot。分配稀疏时把窗口调长。
                 </span>
+                <button class="view-btn" onclick="openChart('heap')">🔗 打开 Heap 图表</button>
                 <button class="download-btn" id="heap-download-btn" onclick="downloadChart('heap')">📥 下载 Heap 图表</button>
             </div>
         </div>
@@ -239,6 +241,7 @@ static const char INDEX_PAGE[] = R"HTML(
                     <b>需要</b>在进程启动前设置 <code>TCMALLOC_SAMPLE_PARAMETER</code>，否则返回 500。
                     刚启动的进程可能显示空快照（tcmalloc 在第一次采样事件前不报告数据），稍等再试即可。
                 </span>
+                <button class="view-btn" onclick="openSnapshot('profile')">🔗 打开 profile 文本</button>
                 <button class="download-btn" id="snapshot-profile-btn" onclick="downloadSnapshot('profile')">📥 下载 profile 文本</button>
                 <button class="download-btn" id="snapshot-svg-btn" onclick="downloadSnapshot('svg')">📥 下载快照图 (SVG)</button>
             </div>
@@ -255,6 +258,7 @@ static const char INDEX_PAGE[] = R"HTML(
                     </select>
                 </div>
                 <span class="hint">堆增长栈分析，不需要 <code>TCMALLOC_SAMPLE_PARAMETER</code>，即时获取。</span>
+                <button class="view-btn" onclick="openChart('growth')">🔗 打开 Growth 图表</button>
                 <button class="download-btn" id="growth-download-btn" onclick="downloadChart('growth')">📥 下载 Growth 图表</button>
             </div>
         </div>
@@ -334,6 +338,27 @@ static const char INDEX_PAGE[] = R"HTML(
             return new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
         }
 
+        /// 在浏览器里直接打开产物（output=inline）。
+        ///
+        /// 与"下载"的区别只在响应头：不发 Content-Disposition 时浏览器把
+        /// image/svg+xml 当文档渲染，因此可以直接导航过去，不需要 blob 中转。
+        /// 注意产物内嵌的 pan/zoom 脚本依赖的元素/初始化挂钩缺失，所以页内
+        /// 无法缩放（见 README）——需要缩放请下载后用桌面工具。
+        function openChart(kind) {
+            const spec = CHART_SPECS[kind];
+            const url = chartUrl(kind, { output: 'inline' });
+            log(`🔗 正在生成并在新标签页打开 ${spec.label} 图表...\n    ${url}`);
+            window.open(url, '_blank');
+        }
+
+        function openSnapshot(format) {
+            const p = new URLSearchParams({ format, output: 'inline' });
+            if (format === 'svg') p.set('renderer', document.getElementById('heap-renderer').value);
+            const url = `/api/pprof/heap/snapshot?${p.toString()}`;
+            log(`🔗 正在打开堆快照 (${format === 'svg' ? '渲染图' : '原始 profile'})...\n    ${url}`);
+            window.open(url, '_blank');
+        }
+
         /// 通用下载：同一份产物既能存盘，也能用 output=inline 在新标签页显示。
         function downloadChart(kind) {
             const spec = CHART_SPECS[kind];

From c363c46c370c708e0edc46a87ba9d9edea484887 Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Tue, 15 Sep 2026 06:36:13 +0800
Subject: [PATCH 12/21] docs: add the delivery-mode section the previous commit
 claimed to add
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous commit's message said it documented inline vs attachment in the
README; it did not. The edit script died on a quoting error before writing the
file, and I committed without checking that the change had landed -- the same
"reported done without verifying" pattern as the fetchHeapChart commit.

Content that should have been in it: a table showing the two modes differ only in
whether Content-Disposition is sent (both use image/svg+xml), so pasting a URL in
the address bar renders the chart while output=attachment downloads it, plus the
note that inline display is not the same as zoomable.

Verified this time: `grep -c '两种交付方式' README.md` returns 1 and the link
checker passes.
---
 README.md | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 4966a26..5f75ba1 100644
--- a/README.md
+++ b/README.md
@@ -333,7 +333,7 @@ profiler.setLogLevel(profiler::LogLevel::Debug);
 |------|------|------|------|
 | `renderer` | `flamegraph` \| `callgraph` | `flamegraph` | **两种不同的图形**，见下 |
 | `duration` | 1–300 | **10** | 采集窗口（秒）。CPU/Growth 用于采样，heap 用于记录分配 |
-| `output` | `inline` \| `attachment` | `inline` | `inline` 不发 `Content-Disposition`，浏览器直接显示 SVG；`attachment` 强制下载 |
+| `output` | `inline` \| `attachment` | `inline` | 见下方「两种交付方式」 |
 
 `/api/pprof/heap/snapshot` 另用 `format`：
 
@@ -342,6 +342,21 @@ profiler.setLogLevel(profiler::LogLevel::Debug);
 | `format` | `profile` \| `svg` | `profile` | `profile` 返回原始 pprof 文本（交给 `go tool pprof`）；`svg` 渲染成图 |
 | `renderer` | 同上 | `flamegraph` | 仅 `format=svg` 时有意义 |
 
+### 两种交付方式
+
+`output` 决定浏览器是**显示**还是**下载**同一份 SVG。区别**只在响应头**：
+
+| 取值 | `Content-Type` | `Content-Disposition` | 浏览器行为 |
+|------|----------------|----------------------|-----------|
+| `inline`（默认） | `image/svg+xml` | **不发** | 当作 SVG 文档**直接渲染** |
+| `attachment` | `image/svg+xml` | `attachment; filename=…` | **下载**为文件 |
+
+所以想看一眼图表，直接把 URL 粘到地址栏即可，无需下载；需要存盘或交给桌面工具时用
+`output=attachment`。Web 面板每个区块都提供「🔗 打开」（inline）与「📥 下载」（attachment）两个按钮。
+
+> ⚠️ `inline` 只是"显示"，**不代表可缩放**——产物内嵌的 pan/zoom 脚本依赖的元素/初始化挂钩
+> 缺失（见下）。需要缩放请下载后用桌面工具打开，或用浏览器页面缩放。
+
 ### 两种图形不是同一种东西
 
 `renderer` 的选择会改变**图形表达**，不只是画法：

From 373e577f94423cbd859bb91a9da5447a0afcd28c Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Tue, 15 Sep 2026 06:53:07 +0800
Subject: [PATCH 13/21] feat(web): make the heap snapshot output a single
 dropdown
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The snapshot section offered a fixed pair of buttons per product (open/download
profile text, open/download SVG), which read as four unrelated actions rather than
one choice of output. It is now one dropdown -- raw profile text, flame graph,
call graph -- with a single 打开 / 下载 pair, so the three products of the same
snapshot are visible as options:

  ?format=profile
  ?format=svg&renderer=flamegraph
  ?format=svg&renderer=callgraph

The renderer was reachable before but effectively undiscoverable: the snapshot
section had no selector of its own and read the Heap Profiler block's dropdown, so
which picture you got depended on a control in a different section. Each section
now owns its selector.

Three defects found while doing it, all from a partially-applied edit of mine:

- snapshotUrl took one parameter but callers passed (output, delivery), so the
  delivery argument was silently dropped and every download would have come back
  as an inline response.
- snapshotOutputLabel was called in two places and never defined; the page threw
  ReferenceError on the first click. The C++ build cannot catch this because the
  script is a string literal.
- openSnapshot still built its URL by string concatenation on top of snapshotUrl,
  duplicating what the helper does.

The second one is why the regression script now checks for JavaScript errors and
why the panel is driven through real clicks rather than inspected: a missing
function in that string literal compiles perfectly.

verify-web-ui.mjs covers all three dropdown options now (33 checks, up from 30),
asserting each produces a distinct request and a distinct file.
---
 CHANGELOG.md              |  3 ++
 README.md                 | 12 ++++++--
 scripts/verify-web-ui.mjs | 50 ++++++++++++++++++++++++++-----
 src/web_resources.cpp     | 62 ++++++++++++++++++++++++++-------------
 4 files changed, 98 insertions(+), 29 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 711ef40..394e781 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `profiler/async_executor.h` — bounded single-worker executor for long-running jobs
 
 ### Changed
+- The Heap Snapshot section is one **output** dropdown (raw profile text / flame graph / call graph) with a single 打开 and 下载 pair, instead of separate buttons per product. Three options, one endpoint: `?format=profile`, `?format=svg&renderer=flamegraph`, `?format=svg&renderer=callgraph`.
+- Each chart section owns its renderer selector. The snapshot section previously read the Heap Profiler section's dropdown, so which picture you got from the snapshot depended on a control in a different block.
+- Every section offers 打开 (`output=inline`) alongside 下载 (`output=attachment`). The inline mode was reachable only by hand-assembling a URL before, since the buttons hard-coded attachment -- a feature nothing in the UI exercised.
 - **Breaking:** the HTTP API was consolidated. Nine endpoints across three
   profiler types became four:
 
diff --git a/README.md b/README.md
index 5f75ba1..48c730a 100644
--- a/README.md
+++ b/README.md
@@ -339,7 +339,7 @@ profiler.setLogLevel(profiler::LogLevel::Debug);
 
 | 参数 | 取值 | 默认 | 说明 |
 |------|------|------|------|
-| `format` | `profile` \| `svg` | `profile` | `profile` 返回原始 pprof 文本（交给 `go tool pprof`）；`svg` 渲染成图 |
+| `format` | `profile` \| `svg` | `profile` | `profile` 返回原始 pprof 文本（交给 `go tool pprof`）；`svg` 渲染成图（面板的下拉即这三项：文本 / 火焰图 / 调用图） |
 | `renderer` | 同上 | `flamegraph` | 仅 `format=svg` 时有意义 |
 
 ### 两种交付方式
@@ -439,7 +439,15 @@ Web 控制面板分成四块，各自对应一个端点：
 | Heap Snapshot | `/api/pprof/heap/snapshot` | **状态式**：当前堆累计快照（存量） |
 | Heap Growth | `/api/pprof/growth` | 增长栈分析 |
 
-每块都有「📥 下载…」按钮；快照那块另提供原始 profile 文本下载（交给 `go tool pprof` 分析）。
+每块都有「🔗 打开」（inline，浏览器内显示）与「📥 下载」（attachment）两个按钮。
+
+Heap Snapshot 那块用一个**快照输出**下拉选择产出，三种选项走同一个端点：
+
+| 下拉选项 | 实际请求 |
+|----------|----------|
+| 原始 profile 文本 | `?format=profile`（交给 `go tool pprof`） |
+| 火焰图 (FlameGraph) | `?format=svg&renderer=flamegraph` |
+| 调用图 (callgraph) | `?format=svg&renderer=callgraph` |
 
 ### 依赖版本
 
diff --git a/scripts/verify-web-ui.mjs b/scripts/verify-web-ui.mjs
index eccdc4d..4890aa0 100755
--- a/scripts/verify-web-ui.mjs
+++ b/scripts/verify-web-ui.mjs
@@ -143,14 +143,26 @@ try {
         document.querySelectorAll('button[onclick^="openChart"], button[onclick^="openSnapshot"]').length);
     record('panel exposes the inline (open in place) actions', openButtons === 4, `found ${openButtons}`);
 
+    // Every chart-producing section owns its renderer selector. The snapshot
+    // section previously read the Heap Profiler's dropdown, so which picture you
+    // got depended on a control in a different section.
+    const selectors = await page.evaluate(() => ({
+        cpu: !!document.getElementById('cpu-renderer'),
+        heap: !!document.getElementById('heap-renderer'),
+        growth: !!document.getElementById('growth-renderer'),
+        snapshot: !!document.getElementById('snapshot-output'),
+    }));
+    record('each section has its own renderer selector', Object.values(selectors).every(Boolean),
+           JSON.stringify(selectors));
+
     const controls = await page.evaluate(() => ({
         cpuDuration: !!document.getElementById('cpu-duration'),
         cpuRenderer: !!document.getElementById('cpu-renderer'),
         heapDuration: !!document.getElementById('heap-duration'),
         heapRenderer: !!document.getElementById('heap-renderer'),
         growthRenderer: !!document.getElementById('growth-renderer'),
-        snapshotButtons: !!document.getElementById('snapshot-profile-btn') &&
-                         !!document.getElementById('snapshot-svg-btn'),
+        snapshotOutput: !!document.getElementById('snapshot-output'),
+        snapshotButton: !!document.getElementById('snapshot-btn'),
     }));
     record('all chart controls present', Object.values(controls).every(Boolean),
            JSON.stringify(controls));
@@ -193,11 +205,13 @@ try {
     console.log('\nHeap growth chart');
     await checkDownload('growth chart', () => downloadChart('growth'));
 
-    console.log('\nHeap snapshot (raw profile)');
-    await checkDownload('snapshot profile', () => downloadSnapshot('profile'));
-
-    console.log('\nHeap snapshot (rendered SVG)');
-    await checkDownload('snapshot svg', () => downloadSnapshot('svg'));
+    // The snapshot section is one dropdown (raw text / flame graph / call graph)
+    // plus one download button, so each option must produce a distinct file.
+    for (const output of ['profile', 'flamegraph', 'callgraph']) {
+        console.log(`\nHeap snapshot (${output})`);
+        await page.select('#snapshot-output', output);
+        await checkDownload(`snapshot ${output}`, () => downloadSnapshot());
+    }
 
     // The delivery modes must actually differ in the response, not just in the
     // query string: `inline` omits Content-Disposition so the browser renders the
@@ -228,6 +242,28 @@ try {
            modes.inline.bytes > 1000 && modes.attachment.bytes > 1000,
            `inline=${modes.inline.bytes}B attachment=${modes.attachment.bytes}B`);
 
+    // The snapshot endpoint must honour renderer too, for both values.
+    console.log('\nHeap snapshot renderers');
+    const snap = await page.evaluate(async () => {
+        const out = {};
+        for (const renderer of ['flamegraph', 'callgraph']) {
+            const r = await fetch(`/api/pprof/heap/snapshot?format=svg&renderer=${renderer}`);
+            const body = await r.text();
+            out[renderer] = {
+                status: r.status,
+                rects: (body.match(/<rect/g) || []).length,
+                polygons: (body.match(/<polygon/g) || []).length,
+            };
+        }
+        return out;
+    });
+    record('snapshot renders a flame graph',
+           snap.flamegraph.status === 200 && snap.flamegraph.rects > 0 && snap.flamegraph.polygons === 0,
+           JSON.stringify(snap.flamegraph));
+    record('snapshot renders a call graph',
+           snap.callgraph.status === 200 && snap.callgraph.polygons > 0 && snap.callgraph.rects === 0,
+           JSON.stringify(snap.callgraph));
+
     record('no JavaScript errors during the run', pageErrors.length === 0, pageErrors.join(' | '));
 
     const savedFiles = fs.readdirSync(DOWNLOAD_DIR);
diff --git a/src/web_resources.cpp b/src/web_resources.cpp
index ffc6a6f..75cef6f 100644
--- a/src/web_resources.cpp
+++ b/src/web_resources.cpp
@@ -241,9 +241,16 @@ static const char INDEX_PAGE[] = R"HTML(
                     <b>需要</b>在进程启动前设置 <code>TCMALLOC_SAMPLE_PARAMETER</code>，否则返回 500。
                     刚启动的进程可能显示空快照（tcmalloc 在第一次采样事件前不报告数据），稍等再试即可。
                 </span>
-                <button class="view-btn" onclick="openSnapshot('profile')">🔗 打开 profile 文本</button>
-                <button class="download-btn" id="snapshot-profile-btn" onclick="downloadSnapshot('profile')">📥 下载 profile 文本</button>
-                <button class="download-btn" id="snapshot-svg-btn" onclick="downloadSnapshot('svg')">📥 下载快照图 (SVG)</button>
+                <div class="input-group">
+                    <label for="snapshot-output">快照输出:</label>
+                    <select id="snapshot-output">
+                        <option value="profile">原始 profile 文本</option>
+                        <option value="flamegraph">火焰图 (FlameGraph)</option>
+                        <option value="callgraph">调用图 (callgraph)</option>
+                    </select>
+                </div>
+                <button class="view-btn" onclick="openSnapshot()">🔗 打开</button>
+                <button class="download-btn" id="snapshot-btn" onclick="downloadSnapshot()">📥 下载</button>
             </div>
         </div>
 
@@ -351,11 +358,28 @@ static const char INDEX_PAGE[] = R"HTML(
             window.open(url, '_blank');
         }
 
-        function openSnapshot(format) {
-            const p = new URLSearchParams({ format, output: 'inline' });
-            if (format === 'svg') p.set('renderer', document.getElementById('heap-renderer').value);
-            const url = `/api/pprof/heap/snapshot?${p.toString()}`;
-            log(`🔗 正在打开堆快照 (${format === 'svg' ? '渲染图' : '原始 profile'})...\n    ${url}`);
+        /// 组装快照请求。下拉里的"原始 profile 文本"走 format=profile，
+        /// 图形两项走 format=svg + renderer。
+        function snapshotUrl(output, delivery) {
+            const p = new URLSearchParams({ output: delivery });
+            if (output === 'profile') {
+                p.set('format', 'profile');
+            } else {
+                p.set('format', 'svg');
+                p.set('renderer', output);
+            }
+            return `/api/pprof/heap/snapshot?${p.toString()}`;
+        }
+
+        function snapshotOutputLabel(output) {
+            return output === 'profile' ? '原始 profile 文本'
+                 : output === 'flamegraph' ? '火焰图' : '调用图';
+        }
+
+        function openSnapshot() {
+            const output = document.getElementById('snapshot-output').value;
+            const url = snapshotUrl(output, 'inline');
+            log(`🔗 正在打开堆快照 (${snapshotOutputLabel(output)})...\n    ${url}`);
             window.open(url, '_blank');
         }
 
@@ -384,26 +408,24 @@ static const char INDEX_PAGE[] = R"HTML(
                 });
         }
 
-        /// Heap 快照：format=profile 取原始文本（交 go tool pprof），format=svg 取渲染图。
-        function downloadSnapshot(format) {
-            const btn = document.getElementById(format === 'svg' ? 'snapshot-svg-btn' : 'snapshot-profile-btn');
+        /// Heap 快照：产出由 snapshot-output 下拉决定（原始文本 / 火焰图 / 调用图）。
+        function downloadSnapshot() {
+            const output = document.getElementById('snapshot-output').value;
+            const btn = document.getElementById('snapshot-btn');
             const original = btn.textContent;
             btn.disabled = true;
             btn.textContent = '⏳ 生成中...';
-            const renderer = document.getElementById('heap-renderer').value;
-            log(`📥 正在获取堆快照 (${format === 'svg' ? '渲染图' : '原始 profile'})...`);
-
-            const p = new URLSearchParams({ format, output: 'attachment' });
-            if (format === 'svg') p.set('renderer', renderer);
+            log(`📥 正在获取堆快照 (${snapshotOutputLabel(output)})...`);
 
+            // Promise.resolve() 包一层：同步异常也会走 catch，否则按钮会永久 disabled
             Promise.resolve()
-                .then(() => fetch(`/api/pprof/heap/snapshot?${p.toString()}`))
+                .then(() => fetch(snapshotUrl(output, 'attachment')))
                 .then(r => (r.ok ? r.blob() : r.text().then(t => Promise.reject(new Error(errorTextFrom(r, t))))))
                 .then(blob => {
-                    const name = format === 'svg' ? `heap_snapshot_${timestamp()}.svg` : 'heap.prof';
+                    const name = output === 'profile' ? 'heap.prof' : `heap_snapshot_${timestamp()}.svg`;
                     saveBlob(blob, name);
-                    log(`✅ 堆快照已保存 ${name} (${(blob.size / 1024).toFixed(1)} KB)\\n` +
-                        (format === 'svg' ? '' : `   分析: go tool pprof ./your_app ${name}`));
+                    log(`✅ 堆快照已保存 ${name} (${(blob.size / 1024).toFixed(1)} KB)\n` +
+                        (output === 'profile' ? `   分析: go tool pprof ./your_app ${name}` : ''));
                 })
                 .catch(e => log(`❌ 堆快照失败: ${e.message}`))
                 .finally(() => {

From 684adbd8276862a5885a54ebbbb7e4a90f058701 Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Tue, 15 Sep 2026 21:08:12 +0800
Subject: [PATCH 14/21] docs: resync with the API refactor, and clamp duration
 where the docs said it did

The documentation audit turned up one code defect and a set of stale references.

Code: the docs promised `duration` is clamped to 1..300, but nothing clamped it,
and the two backends disagreed about out-of-range values -- getRawCPUProfile()
rejected them (which surfaced as the misleading "Failed to collect a CPU profile in
the requested window") while getRawHeapProfileSample() clamped them. The same
query therefore behaved differently per endpoint, and the documented guarantee was
fiction. Clamping now happens once at the HTTP boundary with a test, and measured:
-99 and 0 both run a 1s window, 9999 runs 300s instead of hanging.

Docs, caught by scanning for symbols the refactor removed:

- README: the writable-CWD warning still named /api/*/analyze, /api/*/svg_raw and
  /api/*/flamegraph_raw; the embedded example called handleCpuAnalyze(10,
  "flamegraph"), a function that no longer exists; the heap comparison table still
  said duration defaults to 1s.
- 01_quick_start.md: same dead handleCpuAnalyze call.
- 02_api_reference.md: listed six handlers that no longer exist
  (handleCpu{svg_raw,flamegraph_raw}, handleHeap{svg_raw,flamegraph_raw},
  handleGrowth{svg_raw,flamegraph_raw}) and never documented ChartOptions, which is
  now the whole interface. Added a ChartOptions section and dropped the dead rows.
- mainpage.dox: still advertised the removed /show_*.html viewer pages and the old
  /api/{cpu,heap,growth}/{analyze,svg_raw,flamegraph_raw} paths.
- 04_troubleshooting.md: described the async-worker set with removed endpoint names.

CONTRIBUTING.md gains a section on the two verification scripts, because ctest
alone does not cover what they cover: a leak report needs a sanitizer build, and
front-end behaviour needs a browser (curl cannot execute page JavaScript). It also
notes that the panel's JavaScript lives in a C++ string literal, so the compiler
checks none of it -- which is how an undefined function survived a full build.

CHANGELOG and plan.md keep their old endpoint names on purpose: they are records of
what was true at the time, and rewriting them would misrepresent the history.

Audited: no removed symbol remains in any current doc, every endpoint referenced by
the docs is registered, documented defaults match the code, all internal links
resolve. Full suite 6/6, ASan 6/6 via scripts/check-sanitizers.sh.
---
 CHANGELOG.md                          |  1 +
 CONTRIBUTING.md                       | 26 ++++++++++++++++++++++++++
 README.md                             |  7 ++++---
 docs/mainpage.dox                     | 17 +++++++++++++----
 docs/user_guide/01_quick_start.md     |  3 ++-
 docs/user_guide/02_api_reference.md   | 25 ++++++++++++++++++-------
 docs/user_guide/04_troubleshooting.md |  2 +-
 include/profiler/http_handlers.h      |  6 ++++++
 src/http_handlers.cpp                 | 18 ++++++++++++++++--
 tests/test_http_handlers.cpp          | 14 ++++++++++++++
 10 files changed, 101 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 394e781..764d4a5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -98,6 +98,7 @@ Verified in a real browser (headless Chrome driven over CDP) rather than by insp
 - Installation layout made consistent across `lib`/`lib64` hosts so `find_package()` works (GNUInstallDirs is now included before the install rules)
 
 ### Fixed
+- An out-of-range `duration` now clamps to 1..300 for every analysis endpoint. The two backends disagreed: `getRawCPUProfile()` rejected out-of-range values (surfacing as "Failed to collect a CPU profile in the requested window") while `getRawHeapProfileSample()` clamped them, so the same query succeeded or failed depending on which profiler served it. The clamping happens once at the HTTP boundary. Measured after: `duration=-99` and `duration=0` both run a 1s window, `duration=9999` runs 300s rather than hanging for 9999.
 - `stopHeapProfiler()` freed nothing for the profile it generates:
   `GetHeapProfile()` returns a malloc'd string the caller must `free()`, and
   letting it convert directly into a `std::string` discarded the pointer, leaking
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b1f8b67..884c062 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -285,6 +285,32 @@ cd build
 ctest -R <test_name> --output-on-failure
 ```
 
+### 提交前的附加检查
+
+`ctest` 通过**不足以**覆盖两类问题，仓库里有两个脚本专门补这个缺口：
+
+```bash
+# 1) Sanitizer：本地复刻 CI 的 ASan/UBSan/TSan 配置
+scripts/check-sanitizers.sh asan        # 默认只跑 ASan
+scripts/check-sanitizers.sh all         # ASan + UBSan + TSan
+
+# 2) Web UI：用无头 Chrome 驱动真实控制面板，断言每个动作都发出正确的请求
+#    并真正落盘（需要先启动 profiler_example，以及 puppeteer-core）
+scripts/verify-web-ui.mjs http://localhost:8080
+```
+
+为什么需要它们：
+
+- **Sanitizer**：`ctest` 默认构建不会报内存泄漏与未定义行为。曾经有一个
+  `stopHeapProfiler()` 的 LeakSanitizer 报告只被 CI 发现，因为本地从没跑过
+  `-fsanitize=address`。
+- **Web UI**：`curl` **无法执行页面 JavaScript**，因此看不到"按钮点击报
+  ReferenceError""按钮卡在 disabled""下载其实没开始"这类问题。前端改动必须用
+  真实浏览器验证后才算完成。
+
+> 改前端（`src/web_resources.cpp` 里的 HTML/JS 字符串）时尤其注意：那段 JS 是
+> C++ 字符串字面量，**编译器不会检查它**——函数名写错、参数漏传都能编译通过。
+
 ## 需要帮助？
 
 如果你有任何问题，可以：
diff --git a/README.md b/README.md
index 48c730a..30c8a20 100644
--- a/README.md
+++ b/README.md
@@ -135,7 +135,7 @@ cd build && ./profiler_example
 
 由此带来三点要求：
 
-1. **工作目录必须可写**。以只读目录（如 `/`）为 CWD 启动会导致脚本写入失败，所有 `/api/*/analyze`、`/api/*/svg_raw`、`/api/*/flamegraph_raw` 接口返回 500。
+1. **工作目录必须可写**。以只读目录（如 `/`）为 CWD 启动会导致脚本写入失败，所有 `/api/pprof/*` 图表接口返回 500。
 2. **必须安装 perl**：`sudo apt-get install -y perl`。
 3. **不要删除这两个文件**，每个进程实例都会重新生成。
 
@@ -279,7 +279,8 @@ int main() {
 profiler::ProfilerManager profiler;
 profiler::ProfilerHttpHandlers handlers(profiler);
 
-auto resp = handlers.handleCpuAnalyze(10, "flamegraph");
+profiler::ChartOptions options;          // renderer / duration / inline_display
+auto resp = handlers.handleCpuChart(options);
 // resp.status / resp.content_type / resp.body / resp.headers → 用你的框架包一层
 ```
 
@@ -415,7 +416,7 @@ tcmalloc 在**进程初始化时**读取该变量，因此必须在启动前用
 | 是否建 profiler 会话 | 否 | 是（独占，并发返回 409） |
 | 输出 | 原始 profile 文本，**客户端**用 `go tool pprof` 渲染 | 服务端渲染好的 SVG |
 | `TCMALLOC_SAMPLE_PARAMETER` | **必需** | 不需要 |
-| 时长参数 | 无 | `?duration=N`，默认 1 秒 |
+| 时长参数 | 无 | `?duration=N`，默认 10 秒 |
 
 关键差别在于**"存量"与"流量"**：
 
diff --git a/docs/mainpage.dox b/docs/mainpage.dox
index 2b448eb..bf667f9 100644
--- a/docs/mainpage.dox
+++ b/docs/mainpage.dox
@@ -42,11 +42,20 @@
  * The canonical, always-current endpoint list lives in the project README under
  * "API 端点" (README.md). Summary:
  *
- * - Standard pprof: @c /pprof/profile, @c /pprof/heap, @c /pprof/growth, @c /pprof/symbol
- * - One-click analysis (SVG): @c /api/{cpu,heap,growth}/analyze
- * - Raw SVG download: @c /api/{cpu,heap,growth}/svg_raw and @c .../flamegraph_raw
+ * - Standard pprof (machine-readable): @c /pprof/profile, @c /pprof/heap,
+ *   @c /pprof/growth, @c /pprof/symbol
+ * - Analysis charts: @c /api/pprof/{cpu,heap,growth} with @c renderer=flamegraph
+ *   (stacked frames) or @c renderer=callgraph (graphviz node/edge graph), plus
+ *   @c duration and @c output=inline|attachment
+ * - Heap snapshot (state-based, "what is in the heap now"):
+ *   @c /api/pprof/heap/snapshot with @c format=profile|svg
  * - Thread stacks: @c /api/thread/stacks
- * - Panel and viewers: @c /, @c /show_svg.html, @c /show_heap_svg.html, @c /show_growth_svg.html
+ * - Control panel: @c /
+ *
+ * There are no separate viewer pages; charts are delivered as SVG by the
+ * analysis endpoints themselves. Note that the generated SVGs cannot be zoomed
+ * in the browser (the embedded pan/zoom scripts depend on elements that the
+ * output does not contain), so scaling requires a desktop tool.
  *
  * @section runtime_dependencies Runtime Dependencies
  *
diff --git a/docs/user_guide/01_quick_start.md b/docs/user_guide/01_quick_start.md
index 1938df0..630f38f 100644
--- a/docs/user_guide/01_quick_start.md
+++ b/docs/user_guide/01_quick_start.md
@@ -218,7 +218,8 @@ int main() {
     profiler::ProfilerHttpHandlers handlers(profiler);
 
     // 调用任意 handler，获得框架无关的响应
-    profiler::HandlerResponse resp = handlers.handleCpuAnalyze(10, "flamegraph");
+    profiler::ChartOptions options;   // renderer / duration / inline_display
+    profiler::HandlerResponse resp = handlers.handleCpuChart(options);
 
     // resp.status, resp.content_type, resp.body
     // 用你自己的 Web 框架包装这些数据
diff --git a/docs/user_guide/02_api_reference.md b/docs/user_guide/02_api_reference.md
index bd41dd8..bac0c62 100644
--- a/docs/user_guide/02_api_reference.md
+++ b/docs/user_guide/02_api_reference.md
@@ -64,20 +64,30 @@ explicit ProfilerHttpHandlers(ProfilerManager& profiler);
 |------|------|------|
 | `handleStatus` | `HandlerResponse handleStatus()` | 返回所有 profiler 状态 (JSON) |
 | `handleCpuChart` | `HandlerResponse handleCpuChart(const ChartOptions&)` | CPU 采样并出图 |
-| `handleCpuSvgRaw` | `HandlerResponse handleCpuSvgRaw(int duration)` | CPU 原始 SVG (pprof 生成) |
-| `handleCpuFlamegraphRaw` | `HandlerResponse handleCpuFlamegraphRaw(int duration)` | CPU FlameGraph SVG |
 | `handleHeapChart` | `HandlerResponse handleHeapChart(const ChartOptions&)` | Heap 窗口式采集并出图 |
-| `handleHeapSvgRaw` | `HandlerResponse handleHeapSvgRaw()` | Heap 原始 SVG |
-| `handleHeapFlamegraphRaw` | `HandlerResponse handleHeapFlamegraphRaw()` | Heap FlameGraph SVG |
 | `handleGrowthChart` | `HandlerResponse handleGrowthChart(const ChartOptions&)` | Growth 采集并出图 |
-| `handleGrowthSvgRaw` | `HandlerResponse handleGrowthSvgRaw()` | Growth 原始 SVG |
-| `handleGrowthFlamegraphRaw` | `HandlerResponse handleGrowthFlamegraphRaw()` | Growth FlameGraph SVG |
 | `handlePprofProfile` | `HandlerResponse handlePprofProfile(int seconds)` | 标准 pprof CPU profile (二进制) |
 | `handlePprofHeap` | `HandlerResponse handlePprofHeap()` | 标准 pprof heap profile |
 | `handlePprofGrowth` | `HandlerResponse handlePprofGrowth()` | 标准 pprof growth profile |
 | `handlePprofSymbol` | `HandlerResponse handlePprofSymbol(const std::string& body)` | 符号化接口 (POST) |
 | `handleThreadStacks` | `HandlerResponse handleThreadStacks()` | 线程调用栈 |
 
+### ChartOptions
+
+`handleCpuChart` / `handleHeapChart` / `handleGrowthChart` 共用同一个选项结构：
+
+```cpp
+struct ChartOptions {
+    ChartRenderer renderer = ChartRenderer::FlameGraph;  // FlameGraph 或 CallGraph
+    int duration = 10;        // 采集窗口（秒），内部钳制到 1..300
+    bool inline_display = true;  // true 不发 Content-Disposition；false 强制下载
+};
+```
+
+HTTP 层的 `renderer` 取值 `flamegraph` / `callgraph` 由此处的 `ChartRenderer` 决定
+（`callgraph` 即 pprof 脚本经 graphviz 画出的调用图）。`handleHeapSnapshot(options, as_profile)`
+另有一个 `as_profile` 开关：true 返回原始 profile 文本，false 按 `options.renderer` 出图。
+
 ### 使用示例
 
 ```cpp
@@ -88,7 +98,8 @@ profiler::ProfilerManager profiler;
 profiler::ProfilerHttpHandlers handlers(profiler);
 
 // 调用任意 handler
-profiler::HandlerResponse resp = handlers.handleCpuAnalyze(10, "flamegraph");
+profiler::ChartOptions options;   // renderer / duration / inline_display
+profiler::HandlerResponse resp = handlers.handleCpuChart(options);
 
 // resp.status, resp.content_type, resp.body, resp.headers
 // 用你自己的 Web 框架包装这些数据
diff --git a/docs/user_guide/04_troubleshooting.md b/docs/user_guide/04_troubleshooting.md
index 7413559..34a5113 100644
--- a/docs/user_guide/04_troubleshooting.md
+++ b/docs/user_guide/04_troubleshooting.md
@@ -741,7 +741,7 @@ go tool pprof -http=:8081 ./your_app heap.prof
 两者语义相反、不可互相替代；详见 [README 的说明](../../README.md#heap-的两个端点语义相反)。
 
 ### Q: 为什么长时间采样期间，其它接口还能正常返回？
-**A**: 因为 Drogon 适配层不把 profiling 放在事件循环线程上执行。所有会产生图表的接口（`/pprof/profile`、`/api/*/analyze`、`/api/*/svg_raw`、`/api/*/flamegraph_raw`）都被投递到一个后台工作线程，完成后用 `queueInLoop()` 把响应送回事件循环。因此一个 300 秒的采样不会拖住 `/api/status` 或首页。
+**A**: 因为 Drogon 适配层不把 profiling 放在事件循环线程上执行。所有会产生图表的接口（`/pprof/profile`、`/api/pprof/{cpu,heap,growth}`、`/api/pprof/heap/snapshot`）都被投递到一个后台工作线程，完成后用 `queueInLoop()` 把响应送回事件循环。因此一个 300 秒的采样不会拖住 `/api/status` 或首页。
 
 ### Q: 并发请求 CPU 采样时返回 409 / 500 "cpu profiling already in use"
 **A**: 这是**有意的拒绝**，不是故障。CPU 采样是独占的（gperftools 的采样会话是进程级全局状态），所以已有采样进行时，第二个请求会立即失败而**不会排队等待**——避免用户以为"已经在采样了"，实际却要排在别人后面等几十秒到几分钟。
diff --git a/include/profiler/http_handlers.h b/include/profiler/http_handlers.h
index 639fc0e..2d6dda1 100644
--- a/include/profiler/http_handlers.h
+++ b/include/profiler/http_handlers.h
@@ -68,6 +68,12 @@ struct ChartOptions {
 /// @brief Parse the `renderer` query value; unknown values fall back to FlameGraph
 ChartRenderer parseChartRenderer(const std::string& value);
 
+/// @brief Clamp a collection window to the supported 1..300 second range
+///
+/// Applied once at the HTTP boundary so every endpoint treats an out-of-range
+/// duration the same way, regardless of which profiler backend serves it.
+int clampChartDuration(int duration);
+
 /// @brief Framework-agnostic profiler HTTP endpoint handlers
 ///
 /// Usage example with any framework:
diff --git a/src/http_handlers.cpp b/src/http_handlers.cpp
index 1cbf40b..266ab47 100644
--- a/src/http_handlers.cpp
+++ b/src/http_handlers.cpp
@@ -114,6 +114,20 @@ HandlerResponse flameGraphResponse(const std::string& svg) {
 
 } // namespace
 
+int clampChartDuration(int duration) {
+    // Clamp rather than reject: the HTTP layer documents duration as a window
+    // that is clamped to this range, and the two profiler backends disagreed --
+    // getRawCPUProfile() rejected out-of-range values while
+    // getRawHeapProfileSample() clamped them, so the same query behaved
+    // differently per endpoint. Clamping here makes one rule for all of them,
+    // and keeps a stray value from being reported as a sampling failure.
+    if (duration < 1)
+        return 1;
+    if (duration > 300)
+        return 300;
+    return duration;
+}
+
 ChartRenderer parseChartRenderer(const std::string& value) {
     // "callgraph" is the pprof script's graphviz diagram; "flamegraph" is
     // FlameGraph. Both were previously wrapped in one "output_type" whose values
@@ -242,7 +256,7 @@ HandlerResponse ProfilerHttpHandlers::handleCpuChart(const ChartOptions& options
     if (isCpuProfilerBusy())
         return cpuProfilerBusyResponse(false);
 
-    std::string profile = profiler_.getRawCPUProfile(options.duration);
+    std::string profile = profiler_.getRawCPUProfile(clampChartDuration(options.duration));
     if (auto err = coreError(profile))
         return *err;
     if (profile.empty())
@@ -255,7 +269,7 @@ HandlerResponse ProfilerHttpHandlers::handleHeapChart(const ChartOptions& option
     if (isHeapAnalyzerBusy())
         return heapAnalyzerBusyResponse();
 
-    std::string sample = profiler_.getRawHeapProfileSample(options.duration);
+    std::string sample = profiler_.getRawHeapProfileSample(clampChartDuration(options.duration));
     if (auto err = coreError(sample))
         return *err;
     if (sample.empty())
diff --git a/tests/test_http_handlers.cpp b/tests/test_http_handlers.cpp
index 060d2a7..b017e96 100644
--- a/tests/test_http_handlers.cpp
+++ b/tests/test_http_handlers.cpp
@@ -412,6 +412,20 @@ TEST_F(HttpHandlersTest, ChartEndpointsTakeDurationAndRenderer) {
                   "handleHeapSnapshot must take (ChartOptions, as_profile)");
 }
 
+TEST_F(HttpHandlersTest, ChartDurationIsClamped) {
+    // The HTTP layer documents duration as clamped to 1..300, and it must behave
+    // that way for every endpoint: the backends disagreed (getRawCPUProfile
+    // rejected out-of-range values, getRawHeapProfileSample clamped them), which
+    // made the same query succeed or fail depending on which profiler served it.
+    EXPECT_EQ(profiler::clampChartDuration(0), 1);
+    EXPECT_EQ(profiler::clampChartDuration(-5), 1);
+    EXPECT_EQ(profiler::clampChartDuration(1), 1);
+    EXPECT_EQ(profiler::clampChartDuration(10), 10);
+    EXPECT_EQ(profiler::clampChartDuration(300), 300);
+    EXPECT_EQ(profiler::clampChartDuration(301), 300);
+    EXPECT_EQ(profiler::clampChartDuration(9999), 300);
+}
+
 TEST_F(HttpHandlersTest, ChartRendererParsing) {
     // "callgraph" is the pprof/graphviz diagram, "flamegraph" is FlameGraph. The
     // old parameter was called output_type and its values named a tool rather

From 8c9ac86f6a4f9049ead46c59cd349edb8820e6dc Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Tue, 15 Sep 2026 21:18:25 +0800
Subject: [PATCH 15/21] fix(tests): make the suite parallel-safe, which is how
 CI breaks it

CI failed FullFlowTest and HttpHandlersTest while every local run passed. The
difference is parallelism: CI's job takes 7.1s wall for tests that need 2.7s and
10.5s individually, so its binaries overlap. `ctest -j4` reproduces the failure
here, which is what finally pinned it down.

The profiler's intermediate artifacts had fixed names in a shared location --
/tmp/cpp_profiler/pprof_cpu_temp.prof, /tmp/cpu_collapsed.prof, /tmp/heap_collapsed.prof,
and the per-endpoint render inputs like /tmp/cpu_chart.prof. Two test binaries
running at once therefore truncated and recreated each other's files. The captured
failure is exact:

    Starting CPU profiler for 1 seconds...
    Stopping CPU profiler...
    Profile data size: 0 bytes
    test_full_flow.cpp:170: Failure

The same run also showed flamegraph.pl rejecting /tmp/cpu_collapsed.prof with "No
valid input", i.e. a second process had emptied that file mid-render. Artifact names
now carry the process id. Note this is not purely a test concern: two profiled
processes on one host share /tmp/cpp_profiler by default and would corrupt each
other the same way.

Second problem, same test: it asserted a 1s CPU profile is non-empty after
*sleeping* through the window. gperftools samples threads that are executing, so an
idle window returning an empty profile is correct behaviour, and the assertion was
really testing whether the machine happened to be busy. The sampling tests now burn
CPU for the window (burnCPUFor) and fail only on a genuine fault.

scripts/check-sanitizers.sh gained CTEST_JOBS=<n> so the parallel case can be
reproduced deliberately rather than only in CI.

Verified: serial 6/6; `ctest -j6` six consecutive clean runs; ASan with
CTEST_JOBS=6 clean. Before the fix, `ctest -j4` failed FullFlowTest repeatably.
---
 CHANGELOG.md                | 12 ++++++++++++
 ROADMAP.md                  | 10 ++++++++++
 scripts/check-sanitizers.sh | 12 +++++++++---
 src/http_handlers.cpp       | 14 +++++++++-----
 src/profiler_manager.cpp    |  8 ++++----
 tests/test_full_flow.cpp    | 32 +++++++++++++++++++++++++++++++-
 6 files changed, 75 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 764d4a5..9a31b82 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -98,6 +98,18 @@ Verified in a real browser (headless Chrome driven over CDP) rather than by insp
 - Installation layout made consistent across `lib`/`lib64` hosts so `find_package()` works (GNUInstallDirs is now included before the install rules)
 
 ### Fixed
+- The test suite is safe to run in parallel. The profiler's intermediate artifacts
+  (`pprof_cpu_temp.prof`, `cpu_analyze.prof`, `cpu_collapsed.prof`,
+  `heap_collapsed.prof`, and the per-endpoint render inputs) had fixed names in a
+  shared directory, so two test binaries running at once truncated each other's
+  files. `ctest -j4` reproduced the CI failure locally: FullFlowTest read back a
+  0-byte CPU profile because a concurrently running binary had recreated the
+  shared file. The names now carry the process id.
+- `FullFlowTest.GetRawCPUProfile` (and the gperftools profile test) generate real
+  CPU work across the sampling window instead of sleeping through it. gperftools
+  samples executing threads, so a window spent idle yields an empty profile by
+  design -- the test treated that legitimate result as a failure whenever the
+  machine had nothing to sample. It now fails only for a real fault.
 - An out-of-range `duration` now clamps to 1..300 for every analysis endpoint. The two backends disagreed: `getRawCPUProfile()` rejected out-of-range values (surfacing as "Failed to collect a CPU profile in the requested window") while `getRawHeapProfileSample()` clamped them, so the same query succeeded or failed depending on which profiler served it. The clamping happens once at the HTTP boundary. Measured after: `duration=-99` and `duration=0` both run a 1s window, `duration=9999` runs 300s rather than hanging for 9999.
 - `stopHeapProfiler()` freed nothing for the profile it generates:
   `GetHeapProfile()` returns a malloc'd string the caller must `free()`, and
diff --git a/ROADMAP.md b/ROADMAP.md
index 2e6a9db..52ad486 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -86,6 +86,16 @@
 - 新增 `scripts/verify-web-ui.mjs`（CDP 驱动真实浏览器回归，23 项检查）与
   `scripts/check-sanitizers.sh`（本地复刻 CI 的 ASan/UBSan/TSan 配置）。
 
+### 已完成（CI 稳定性）
+
+- 测试可在并行下运行（`ctest -j`）。此前 `pprof_cpu_temp.prof`、`cpu_collapsed.prof` 等
+  中间产物用**固定文件名**放在共享目录，两个测试进程会互相截断文件——CI 的
+  `FullFlowTest` 读到 0 字节 profile 即源于此。现按 PID 命名。
+- `FullFlowTest.GetRawCPUProfile` 在采样窗口内**真的跑 CPU 负载**，而不是 sleep。
+  gperftools 只采样正在执行的线程，窗口内空闲时返回空 profile 是**设计如此**，
+  原断言把这种合法结果当成失败。
+- `scripts/check-sanitizers.sh` 支持 `CTEST_JOBS=<n>` 以复现并行场景。
+
 ### 待修
 
 - **生成的 SVG 无法缩放**：FlameGraph 的 `zoom()` 找不到它要操作的 `#viewport`（其产物只有
diff --git a/scripts/check-sanitizers.sh b/scripts/check-sanitizers.sh
index 317512f..e5f7215 100755
--- a/scripts/check-sanitizers.sh
+++ b/scripts/check-sanitizers.sh
@@ -25,6 +25,12 @@ BUILD_ROOT="${SANITIZER_BUILD_ROOT:-$PROJECT_ROOT/build/sanitizers}"
 JOBS="$(nproc)"
 
 log() { printf '\n=== %s ===\n' "$*"; }
+
+# Extra ctest flags. Empty by default because CI runs ctest serially; set
+# CTEST_JOBS=<n> to also exercise the parallel case, which is where the tests
+# used to clobber each other's profile files.
+ctest_parallel=()
+[[ -n "${CTEST_JOBS:-}" ]] && ctest_parallel=(-j "$CTEST_JOBS")
 die() { printf 'error: %s\n' "$*" >&2; exit 1; }
 
 [[ -f "$VCPKG_TOOLCHAIN" ]] || die "vcpkg toolchain not found at $VCPKG_TOOLCHAIN"
@@ -55,7 +61,7 @@ run_asan() {
     # detect_leaks + halt_on_error: a leak must fail the run, as it does in CI.
     ( cd "$dir" && ASAN_OPTIONS=detect_leaks=1:halt_on_error=1 \
         LSAN_OPTIONS="suppressions=$PROJECT_ROOT/lsan.supp" \
-        ctest --output-on-failure )
+        ctest --output-on-failure "${ctest_parallel[@]}" )
 }
 
 run_ubsan() {
@@ -73,7 +79,7 @@ run_ubsan() {
     cmake --build "$dir" -j"$JOBS"
     # halt_on_error so a single UB report fails the run rather than scrolling by.
     ( cd "$dir" && UBSAN_OPTIONS=halt_on_error=1:print_stacktrace=1 \
-        ctest --output-on-failure )
+        ctest --output-on-failure "${ctest_parallel[@]}" )
 }
 
 run_tsan() {
@@ -89,7 +95,7 @@ run_tsan() {
         -DCMAKE_MODULE_LINKER_FLAGS="-fsanitize=thread" \
         "${extra_configure_args[@]}"
     cmake --build "$dir" -j"$JOBS"
-    ( cd "$dir" && TSAN_OPTIONS=halt_on_error=1 ctest --output-on-failure )
+    ( cd "$dir" && TSAN_OPTIONS=halt_on_error=1 ctest --output-on-failure "${ctest_parallel[@]}" )
 }
 
 targets=("$@")
diff --git a/src/http_handlers.cpp b/src/http_handlers.cpp
index 266ab47..36b1c78 100644
--- a/src/http_handlers.cpp
+++ b/src/http_handlers.cpp
@@ -8,6 +8,7 @@
 #include <fstream>
 #include <optional>
 #include <sstream>
+#include <unistd.h>
 
 PROFILER_NAMESPACE_BEGIN
 
@@ -262,7 +263,8 @@ HandlerResponse ProfilerHttpHandlers::handleCpuChart(const ChartOptions& options
     if (profile.empty())
         return errorResp(500, "Failed to collect a CPU profile in the requested window.");
 
-    return renderChart(profiler_, "/tmp/cpu_chart.prof", profile, options, "cpu_profile", "CPU Flame Graph");
+    return renderChart(profiler_, "/tmp/cpu_chart_" + std::to_string(::getpid()) + ".prof", profile, options,
+                       "cpu_profile", "CPU Flame Graph");
 }
 
 HandlerResponse ProfilerHttpHandlers::handleHeapChart(const ChartOptions& options) {
@@ -275,7 +277,8 @@ HandlerResponse ProfilerHttpHandlers::handleHeapChart(const ChartOptions& option
     if (sample.empty())
         return errorResp(500, "Failed to collect a heap sample in the requested window.");
 
-    return renderChart(profiler_, "/tmp/heap_chart.prof", sample, options, "heap_profile", "Heap Flame Graph");
+    return renderChart(profiler_, "/tmp/heap_chart_" + std::to_string(::getpid()) + ".prof", sample, options,
+                       "heap_profile", "Heap Flame Graph");
 }
 
 HandlerResponse ProfilerHttpHandlers::handleHeapSnapshot(const ChartOptions& options, bool as_profile) {
@@ -290,7 +293,8 @@ HandlerResponse ProfilerHttpHandlers::handleHeapSnapshot(const ChartOptions& opt
         return finishChart(resp, "heap", options.inline_display);
     }
 
-    return renderChart(profiler_, "/tmp/heap_snapshot.prof", sample, options, "heap_snapshot", "Heap Snapshot");
+    return renderChart(profiler_, "/tmp/heap_snapshot_" + std::to_string(::getpid()) + ".prof", sample, options,
+                       "heap_snapshot", "Heap Snapshot");
 }
 
 HandlerResponse ProfilerHttpHandlers::handleGrowthChart(const ChartOptions& options) {
@@ -298,8 +302,8 @@ HandlerResponse ProfilerHttpHandlers::handleGrowthChart(const ChartOptions& opti
     if (growth.empty())
         return errorResp(500, "Failed to get heap growth stacks. No heap growth data available.");
 
-    return renderChart(profiler_, "/tmp/growth_chart.prof", growth, options, "growth_profile",
-                       "Heap Growth Flame Graph");
+    return renderChart(profiler_, "/tmp/growth_chart_" + std::to_string(::getpid()) + ".prof", growth, options,
+                       "growth_profile", "Heap Growth Flame Graph");
 }
 
 HandlerResponse ProfilerHttpHandlers::handlePprofProfile(int seconds) {
diff --git a/src/profiler_manager.cpp b/src/profiler_manager.cpp
index dd237b8..e5165ae 100644
--- a/src/profiler_manager.cpp
+++ b/src/profiler_manager.cpp
@@ -446,7 +446,7 @@ bool ProfilerManager::isHeapAnalysisInProgress() const {
 }
 
 std::string ProfilerManager::analyzeCPUProfile(int duration, const std::string& output_type) {
-    std::string profile_path = profile_dir_ + "/cpu_analyze.prof";
+    std::string profile_path = profile_dir_ + "/cpu_analyze_" + std::to_string(::getpid()) + ".prof";
 
     // Step 1: Claim the CPU profiling session.
     //
@@ -519,7 +519,7 @@ std::string ProfilerManager::analyzeCPUProfile(int duration, const std::string&
         PROFILER_INFO("Generating FlameGraph output...");
 
         // Step 5a: Generate collapsed format using pprof --collapsed
-        std::string collapsed_file = "/tmp/cpu_collapsed.prof";
+        std::string collapsed_file = "/tmp/cpu_collapsed_" + std::to_string(::getpid()) + ".prof";
         std::ostringstream collapsed_cmd;
         collapsed_cmd << "./pprof --collapsed " << exe_path << " " << profile_path << " > " << collapsed_file
                       << " 2>&1";
@@ -741,7 +741,7 @@ std::string ProfilerManager::analyzeHeapProfile(int duration, const std::string&
         PROFILER_INFO("Generating Heap FlameGraph...");
 
         // Step 9a: Generate collapsed format using pprof --collapsed
-        std::string collapsed_file = "/tmp/heap_collapsed.prof";
+        std::string collapsed_file = "/tmp/heap_collapsed_" + std::to_string(::getpid()) + ".prof";
         std::ostringstream collapsed_cmd;
         collapsed_cmd << "./pprof --collapsed " << exe_path << " " << latest_heap_file << " > " << collapsed_file
                       << " 2>&1";
@@ -891,7 +891,7 @@ std::string ProfilerManager::getRawCPUProfile(int seconds) {
     FlagGuard guard{cpu_profiling_in_progress_};
 
     // Generate temporary profile file path
-    std::string profile_path = profile_dir_ + "/pprof_cpu_temp.prof";
+    std::string profile_path = profile_dir_ + "/pprof_cpu_temp_" + std::to_string(::getpid()) + ".prof";
 
     // Start CPU profiler. A session opened through startCPUProfiler() belongs to
     // the caller, so refuse rather than stopping it; the caller of this function
diff --git a/tests/test_full_flow.cpp b/tests/test_full_flow.cpp
index 606b04e..a26452a 100644
--- a/tests/test_full_flow.cpp
+++ b/tests/test_full_flow.cpp
@@ -7,6 +7,27 @@
 #include <iostream>
 #include <thread>
 
+namespace {
+
+/// Keep one core busy for at least @p ms milliseconds.
+///
+/// gperftools samples whichever threads are *running*, so a window spent in
+/// sleep() legitimately yields an empty profile. Tests that require a non-empty
+/// profile must therefore generate real CPU work for the whole window instead of
+/// sleeping through it -- otherwise they fail whenever the machine happens to be
+/// idle, which is exactly how this test failed under parallel ctest.
+void burnCPUFor(int ms) {
+    const auto deadline = std::chrono::steady_clock::now() + std::chrono::milliseconds(ms);
+    volatile uint64_t sink = 0;
+    while (std::chrono::steady_clock::now() < deadline) {
+        for (int i = 0; i < 20000; ++i) {
+            sink += static_cast<uint64_t>(i) * 2654435761u;
+        }
+    }
+}
+
+} // namespace
+
 // 测试1: 验证 gperftools 生成的 profile 文件格式
 TEST(FullFlowTest, GperftoolsGeneratesValidProfile) {
     const char* profile_path = "/tmp/test_full.prof";
@@ -25,7 +46,8 @@ TEST(FullFlowTest, GperftoolsGeneratesValidProfile) {
         std::sort(data.begin(), data.end());
     }
 
-    std::this_thread::sleep_for(std::chrono::milliseconds(500));
+    // Keep sampling real work rather than idling: see burnCPUFor().
+    burnCPUFor(500);
 
     // 停止 profiler
     ProfilerStop();
@@ -163,9 +185,17 @@ TEST(FullFlowTest, ConcurrentProfilingRequests) {
 TEST(FullFlowTest, GetRawCPUProfile) {
     profiler::ProfilerManager profiler;
 
+    // Sample while work is actually running: the profiler only records samples
+    // from executing threads, so a 1s window with nothing to sample returns an
+    // empty profile by design. The workload used to be absent here, which made
+    // the non-empty assertion below depend on machine load.
+    std::thread burner{[]() { burnCPUFor(1200); }};
+
     // 获取原始 profile 数据（采样 1 秒）
     std::string profile_data = profiler.getRawCPUProfile(1);
 
+    burner.join();
+
     // 应该返回非空数据
     ASSERT_FALSE(profile_data.empty()) << "getRawCPUProfile returned empty data";
 

From 0e3deee5ad4aa8d9c3e6372e61de9bece67e3ef2 Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Tue, 15 Sep 2026 21:20:12 +0800
Subject: [PATCH 16/21] docs: fix the feature-list claim and two contradictions
 it hid
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The user caught this line in the feature list:

    一键分析 — /api/*/analyze 直接返回火焰图 SVG，浏览器可看

Both halves were wrong. That path has not existed since the API consolidation
(it is /api/pprof/*), and "火焰图" is only one of two renderers now --
renderer=callgraph draws a call graph, and the default is flamegraph rather than
the only option. My earlier stale-reference sweep missed it because it searched
for concrete prefixes like /api/cpu/ and this line used the wildcard form.

Widening the sweep to wildcard and prose forms turned up three more:

- README still listed /show_*.html as "内置的 SVG 查看页". Those pages were
  removed along with the inline-SVG branch, so the naming rules now describe what
  actually exists: /pprof/* for raw profiles, /api/pprof/* for rendered charts,
  plus /api/status, /api/thread/stacks and the panel.
- 04_troubleshooting contained two answers that contradicted each other. The
  "what does duration mean" answer still said the duration is meaningless and the
  window is a fixed 1 second, while a later answer correctly said it defaults to
  10 seconds and controls coverage. The first also described precision as if the
  window governed it, when only TCMALLOC_SAMPLE_PARAMETER does. Rewritten to
  separate coverage (duration) from precision (the environment variable).
- 02_api_reference documented analyzeHeapProfile without its duration parameter
  and asserted "没有 duration 参数" -- a leftover from before the window was made
  configurable. The signature, the parameter list and that sentence are corrected,
  and it now notes that the C++ default is 1s while the HTTP default is 10s so the
  difference is not mistaken for a bug.

Audited after: no wildcard or prose reference to a removed path remains, every
documented default matches the code (HTTP 10s, C++ 1s, /pprof/profile 30s), all
internal links resolve.
---
 README.md                             | 14 ++++++++++----
 docs/user_guide/02_api_reference.md   | 13 +++++++++----
 docs/user_guide/04_troubleshooting.md | 10 +++++++---
 3 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 30c8a20..e541567 100644
--- a/README.md
+++ b/README.md
@@ -28,7 +28,7 @@
 - **Heap Growth Profiling** — 堆增长栈分析，无需 `TCMALLOC_SAMPLE_PARAMETER`
 - **线程堆栈捕获** — 采集进程内所有线程的调用栈，支持动态线程数
 - **标准 pprof 接口** — `/pprof/*` 兼容 Go pprof 工具链
-- **一键分析** — `/api/*/analyze` 直接返回火焰图 SVG，浏览器可看
+- **一键分析** — `/api/pprof/*` 直接返回渲染好的 SVG（默认火焰图，可选调用图），浏览器可显示
 - **框架无关** — `ProfilerHttpHandlers` 返回普通结构体，可接入任意 Web 框架
 - **可选 Web 层** — 核心库不依赖任何 Web 框架
 - **可配置日志** — 实现 `LogSink` 即可接入宿主应用的日志系统
@@ -39,7 +39,8 @@
 参考 Go pprof 提供两种互补的使用方式：
 
 1. **标准 pprof 模式** — `/pprof/profile`、`/pprof/heap` 返回原始 profile 文件，交给 `go tool pprof` 分析
-2. **一键分析模式** — `/api/pprof/cpu` 等直接返回 SVG，适合浏览器即时查看
+2. **一键分析模式** — `/api/pprof/cpu` 等直接返回 SVG（`renderer=flamegraph` 火焰图或 `renderer=callgraph` 调用图），
+   默认 `output=inline`，浏览器可直接显示
 
 架构上分为两层，边界清晰：
 
@@ -48,7 +49,12 @@
 - `ProfilerHttpHandlers` — 位于核心库中，返回 `HandlerResponse{status, content_type, body, headers}`，不绑定任何框架
 - `ProfilerManager` — 普通类而非单例，生命周期由使用者管理
 
-接口命名规则：`/pprof/*` 为 Go pprof 标准接口；`/api/*` 为项目自定义的分析/辅助接口；`/show_*.html` 为内置的 SVG 查看页。
+接口命名规则：
+
+- `/pprof/*` — Go pprof 标准接口，返回**原始 profile** 供 `go tool pprof` 消费
+- `/api/pprof/*` — 项目自定义的**分析接口**，服务端采样/渲染后直接返回 SVG
+- `/api/status`、`/api/thread/stacks` — 状态查询与线程栈
+- `/` — Web 控制面板（不再有独立的查看器页）
 
 ## 快速开始
 
@@ -263,7 +269,7 @@ int main() {
 
 int main() {
     profiler::ProfilerManager profiler;
-    profiler::registerDrogonHandlers(profiler);   // 注册全部 /pprof/* 与 /api/* 路由
+    profiler::registerDrogonHandlers(profiler);   // 注册 /pprof/* 与 /api/pprof/* 等全部路由
     drogon::app().addListener("0.0.0.0", 8080).run();
 }
 ```
diff --git a/docs/user_guide/02_api_reference.md b/docs/user_guide/02_api_reference.md
index bac0c62..4dddef6 100644
--- a/docs/user_guide/02_api_reference.md
+++ b/docs/user_guide/02_api_reference.md
@@ -372,17 +372,22 @@ bool stopHeapProfiler();
 采集 Heap 并生成图表 SVG。
 
 ```cpp
-std::string analyzeHeapProfile(const std::string& output_type = "flamegraph");
+std::string analyzeHeapProfile(int duration = 1, const std::string& output_type = "flamegraph");
 ```
 
 **参数**:
+- `duration`: 采集窗口（秒），默认 **1**，内部钳制到 1..300
 - `output_type`: 渲染方式（`"flamegraph"` 或 `"pprof"`）
 
 **返回值**: SVG 字符串；失败时返回 `{"error":"..."}` JSON 字符串
 
-**说明**: **没有 duration 参数**。gperftools 的 heap profiling 是按分配驱动的：`HeapProfilerStart()`
-开始记录，`HeapProfilerDump()` 写出快照，与经过的时间无关。实现内部只开启一个固定的采样窗口（1 秒），
-然后 dump。
+**说明**: `duration` 是**采集窗口**，不是采样率。gperftools 的 heap profiling 按分配驱动：
+`HeapProfilerStart()` 开始记录，`HeapProfilerDump()` 写出快照。窗口决定**覆盖多久的分配**，
+采样率则由 `TCMALLOC_SAMPLE_PARAMETER` 在进程启动前固定，运行时不可调。
+
+> ⚠️ **C++ 层默认 1 秒，HTTP 层默认 10 秒**。HTTP 层用更长默认值是实测结果：短窗口经常
+> 采不到足够的分配而渲染失败。直接调用此函数时，分配稀疏的进程请显式传入更大的
+> `duration`。
 
 **记录的是"窗口内发生的分配"，不是"当前堆里的内存"** —— 这是最容易误解的一点：
 
diff --git a/docs/user_guide/04_troubleshooting.md b/docs/user_guide/04_troubleshooting.md
index 34a5113..285456a 100644
--- a/docs/user_guide/04_troubleshooting.md
+++ b/docs/user_guide/04_troubleshooting.md
@@ -719,12 +719,16 @@ int main() {
 **A**: CPU 与 Heap 是两套独立的 profiling 状态，可以并存。但**同一时刻只能有一个 CPU 采样会话**：`analyzeCPUProfile()` / `getRawCPUProfile()` 会先原子认领会话，认领失败即拒绝，**不会**打断正在采样的另一方（包括宿主用 `startCPUProfiler()` 开的会话）。
 
 ### Q: Heap 窗口式采集的 `duration` 是什么意思？
-**A**: 因为对 heap profiling 而言时长没有意义。gperftools 的 heap profiling 是**按分配驱动**的：`HeapProfilerStart()` 开始记录、`HeapProfilerDump()` 写出快照，采样率由**进程启动时**的 `TCMALLOC_SAMPLE_PARAMETER` 决定，与运行时长无关。
+**A**: 它决定**采集多久**（覆盖度），不是**采样率**（精度）。gperftools 的 heap profiling 按分配驱动：
+`HeapProfilerStart()` 开始记录、`HeapProfilerDump()` 写出快照；采样率由**进程启动时**的
+`TCMALLOC_SAMPLE_PARAMETER` 决定，运行时不可调。
 
-该接口内部只开一个固定的 1 秒窗口让应用自身的分配被记录，然后 dump。要提高采样精度，请**在启动前**设置 `TCMALLOC_SAMPLE_PARAMETER=524288`（默认 `0` 表示不采样，此时快照会明显偏稀疏）。
+所以 `duration` 越长，覆盖到的分配越多——分配稀疏的进程需要更长窗口才采得到东西。HTTP 层默认
+**10 秒**（实测 3 秒窗口失败率 35–45%）。要提高**采样精度**则必须**在启动前**设置
+`TCMALLOC_SAMPLE_PARAMETER=524288`（默认 `0` 表示不采样，此时快照会明显偏稀疏）。
 
 ### Q: heap 图是空的 / 报 "No heap profile data was produced"？
-**A**: 说明这 1 秒窗口内进程**没有发生内存分配**。heap profiler 记录的是**窗口内的分配事件**，不是当前堆的内容，所以不会凭空造出数据。请确保被分析进程正处于负载中，或在窗口内制造真实分配后再试。
+**A**: 说明该采集窗口内进程**没有发生内存分配**。heap profiler 记录的是**窗口内的分配事件**，不是当前堆的内容，所以不会凭空造出数据。请确保被分析进程正处于负载中，或在窗口内制造真实分配后再试。
 
 ### Q: 进程内存很高，为什么 heap 图却是空的？
 **A**: `/api/pprof/heap` 是**窗口式**的：只记录采集窗口内**新发生**的分配（流量），不反映此刻堆里的存量。`duration` 决定采集多久，默认 10 秒——实测 3 秒窗口有 35–45% 的请求采不到样本而失败。如果内存是在采样开始前分配的、窗口内已停止分配，结果就是空的。

From 660ac7707d97deaa1532b486388983ad071e2e63 Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Tue, 15 Sep 2026 21:36:02 +0800
Subject: [PATCH 17/21] refactor: drop the unused getThreadStacks(), and name
 threads in the stack output

ProfilerManager::getThreadStacks() had no callers. It was 122 lines that read
/proc/self/task/*/stat and wchan, while /api/thread/stacks has always been served
by getThreadCallStacks(). Easy to miss because a same-named JavaScript function
lives in web_resources.cpp.

The two were not duplicates, but the survivor already answers the question the
other one existed for: "where is each thread stuck" is the first non-machinery
frame of the captured stack, which I verified matches /proc's wchan one for one
(epoll_wait/ep_poll, clock_nanosleep/hrtimer_nanosleep,
__futex_abstimed_wait_cancelable64/futex_do_wait) and adds the call path that
wchan cannot show.

That left exactly one thing only the deleted function provided: the thread name.
It is now part of the live output, read from /proc/<tid>/comm, so a reader can
tell that thread 1234 is DrogonIoLoop rather than guessing from a bare tid:

    Thread 1234 (DrogonIoLoop):

New tests/test_thread_stacks.cpp covers this (4 cases). It parks a thread that
announces readiness before waiting, so the capture cannot run before there is
anything to capture, and it asserts a thread was actually captured rather than
only that the header is present -- otherwise an empty capture passes. Verified by
inversion: stubbing readThreadName to return "" makes
ReportsThreadNamesAlongsideTids fail, and restoring it passes.

Dead-code audit of the rest, since one unused function suggested others:
- 55 member declarations across the headers, checked for call sites: no others.
  The five initial candidates were false positives -- handler methods referenced
  by function pointer in the route table, signalHandler registered through
  sigaction, a lambda local that my regex mistook for a member, and the three
  signal-configuration APIs (setStackCaptureSignal, getStackCaptureSignal,
  setSignalChaining), which are public configuration surface with a runnable
  example in example/custom_signal.cpp and a documented purpose -- an earlier
  "unused" verdict of mine came from grepping examples/ instead of example/.
- Free and static helpers in src/: all referenced. The hits inside embed_pprof.h
  are the embedded Perl script's own JS, not C++ call sites.

Verified: 7/7 tests serial and with ctest -j6, ASan 7/7 with CTEST_JOBS=6,
browser regression 33/33, and the live endpoint emitting names.
---
 CHANGELOG.md                        |  25 ++--
 CMakeLists.txt                      |  11 ++
 README.md                           |   2 +-
 docs/user_guide/02_api_reference.md |  27 ++++-
 include/profiler_manager.h          |   4 -
 src/profiler_manager.cpp            | 150 +++++-------------------
 tests/test_thread_stacks.cpp        | 171 ++++++++++++++++++++++++++++
 7 files changed, 253 insertions(+), 137 deletions(-)
 create mode 100644 tests/test_thread_stacks.cpp

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9a31b82..c2f2752 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,8 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
-
 ### Added
+
+
+- `/api/thread/stacks` (and `getThreadCallStacks()`) print each thread's **name** next to its tid, read from `/proc/<tid>/comm`. A bare tid is not identifiable when reading the output afterwards; the name is what tells you that thread 1234 is `DrogonIoLoop` and 1235 is a worker parked on a futex.
 - CMake options documentation and reproducible `CMakePresets.json` presets (`debug`, `release`, `relwithdebinfo`, `coverage`, clang variants)
 - `find_package` integration test under `cmake/examples/test_find_package/`
 - Doxygen API documentation support (`-DBUILD_DOCS=ON`)
@@ -20,6 +22,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `profiler/async_executor.h` — bounded single-worker executor for long-running jobs
 
 ### Changed
+
+
 - The Heap Snapshot section is one **output** dropdown (raw profile text / flame graph / call graph) with a single 打开 and 下载 pair, instead of separate buttons per product. Three options, one endpoint: `?format=profile`, `?format=svg&renderer=flamegraph`, `?format=svg&renderer=callgraph`.
 - Each chart section owns its renderer selector. The snapshot section previously read the Heap Profiler section's dropdown, so which picture you got from the snapshot depended on a control in a different block.
 - Every section offers 打开 (`output=inline`) alongside 下载 (`output=attachment`). The inline mode was reachable only by hand-assembling a URL before, since the buttons hard-coded attachment -- a feature nothing in the UI exercised.
@@ -98,6 +102,8 @@ Verified in a real browser (headless Chrome driven over CDP) rather than by insp
 - Installation layout made consistent across `lib`/`lib64` hosts so `find_package()` works (GNUInstallDirs is now included before the install rules)
 
 ### Fixed
+
+
 - The test suite is safe to run in parallel. The profiler's intermediate artifacts
   (`pprof_cpu_temp.prof`, `cpu_analyze.prof`, `cpu_collapsed.prof`,
   `heap_collapsed.prof`, and the per-endpoint render inputs) had fixed names in a
@@ -128,7 +134,6 @@ Verified in a real browser (headless Chrome driven over CDP) rather than by insp
 - clang-tidy job could not locate dependency headers
 - Suppressed a known tcmalloc leak so ASan builds fail only on real errors
 
-### Fixed
 - A session opened by the host through `startCPUProfiler()` / `startHeapProfiler()`
   is no longer preempted. `getRawCPUProfile()` and `analyzeCPUProfile()` used to
   stop whatever session was running and start their own; they now refuse and
@@ -140,7 +145,6 @@ Verified in a real browser (headless Chrome driven over CDP) rather than by insp
   while stopping an existing session; the stop and the state update now happen
   under the lock, as does the corresponding teardown in `getRawCPUProfile()`.
 
-### Fixed
 - `/pprof/heap` reported success when heap sampling was off. `GetHeapSample()` does
   not return an empty string in that case -- it returns pprof's `%warn` advisory
   followed by a valid-looking but empty profile (`@ heap_v2/0`) -- so the
@@ -163,7 +167,16 @@ Verified in a real browser (headless Chrome driven over CDP) rather than by insp
   now detected and returned as a 500 explaining that the sample window was too
   short or the process idle.
 
+### Removed
+
+
+- **Breaking:** `ProfilerManager::getThreadStacks()` is gone. It was 122 lines that nothing called: `/api/thread/stacks` has always used `getThreadCallStacks()`, which answers the same question ("where is each thread stuck") with a full call stack instead of a `/proc` field. Its one unique contribution, the thread name, is now part of the endpoint output.
+- `logger.h` (unused after the logging rework)
+- The synthetic allocation thread inside `analyzeHeapProfile()`
+
 ### Documentation
+
+
 - README, the API reference and the troubleshooting guide now spell out that the
   two heap views are **opposite in kind**, not two renderings of one dataset:
   `/pprof/heap` is state-based (cumulative snapshot of the current heap, needs
@@ -182,11 +195,9 @@ Verified in a real browser (headless Chrome driven over CDP) rather than by insp
   two labelled cards, the second driving `GET /pprof/heap` with view and
   download actions.
 
-### Removed
-- `logger.h` (unused after the logging rework)
-- The synthetic allocation thread inside `analyzeHeapProfile()`
-
 ### Notes
+
+
 - The repository currently has **no git tags**; `v0.1.0` below refers to commit `a503106`. Tagging is tracked in [ROADMAP.md](ROADMAP.md).
 
 ## [0.1.0] - 2026-02-05
diff --git a/CMakeLists.txt b/CMakeLists.txt
index fa639a5..d78cfb4 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -276,6 +276,17 @@ if(REMOTE_PROFILER_BUILD_TESTS)
     )
     add_test(NAME ResultParsingTest COMMAND test_result_parsing)
 
+    # Thread stack capture (core only -- works without Drogon)
+    add_executable(test_thread_stacks tests/test_thread_stacks.cpp)
+    target_link_libraries(test_thread_stacks
+        PRIVATE
+        profiler_core
+        GTest::gtest
+        GTest::gtest_main
+        pthread
+    )
+    add_test(NAME ThreadStacksTest COMMAND test_thread_stacks)
+
     message(STATUS "Tests will be built")
 else()
     message(STATUS "Tests disabled")
diff --git a/README.md b/README.md
index e541567..06072b3 100644
--- a/README.md
+++ b/README.md
@@ -324,7 +324,7 @@ profiler.setLogLevel(profiler::LogLevel::Debug);
 | `/api/pprof/heap/snapshot` | GET | **状态式**：当前堆的累计快照（存量，非窗口） |
 | **状态与辅助** | | |
 | `/api/status` | GET | 各 profiler 的运行状态与输出路径（JSON） |
-| `/api/thread/stacks` | GET | 所有线程的调用栈 |
+| `/api/thread/stacks` | GET | 所有线程的调用栈（含线程名，可看出各线程阻塞在哪个函数） |
 | `/` | GET | Web 控制面板 |
 | **标准 pprof 接口（机器可读，`go tool pprof` 用）** | | |
 | `/pprof/profile` | GET | CPU profile 原始文件；`?seconds=N`，默认 **30**，范围 1–300 |
diff --git a/docs/user_guide/02_api_reference.md b/docs/user_guide/02_api_reference.md
index 4dddef6..03b8b08 100644
--- a/docs/user_guide/02_api_reference.md
+++ b/docs/user_guide/02_api_reference.md
@@ -437,13 +437,36 @@ std::string getRawHeapGrowthStacks();
 
 ### getThreadCallStacks
 
-获取完整线程调用堆栈。
+获取所有线程的调用堆栈，`/api/thread/stacks` 即调用它。
 
 ```cpp
 std::string getThreadCallStacks();
 ```
 
-**说明**: 逐个地址调用 `symbolizeAddress()` 做符号化，该函数**优先使用 Abseil**（`absl::Symbolize`），失败后再回退到 `resolveSymbolWithBackward()`（`src/profiler_manager.cpp:1112-1121`、`1311-1314`）。
+**输出格式**：
+
+```
+Thread Call Stacks (via Signal Handler)
+=========================================
+
+Total threads captured: 2
+
+Thread 1234 (DrogonIoLoop):
+  Frames: 13
+    #0 profiler::v0_1_0::ProfilerManager::signalHandler()
+    #1 __restore_rt
+    ...
+    #5 epoll_wait            ← 该线程阻塞在这里
+```
+
+- **线程名**取自 `/proc/<tid>/comm`（内核截断到 15 字符，与 `ps`/`top` 显示一致）。只有 tid
+  时输出 `Thread 1234:`，读日志时几乎无法分辨是哪个线程，因此带上名字。
+- **阻塞点**是跳过信号捕获机制帧后的第一个真实帧（栈顶前几帧恒为
+  `signalHandler`/`__restore_rt`/`__syscall_cancel_arch`，它们属于捕获手段而非线程状态）。
+- 正在执行本请求的线程**不会**出现在结果里：信号只能采集其他线程，执行中的线程无法被抓取。
+  这也是可接受的——正在运行的线程本来就没有"卡住"。
+
+**说明**: 逐个地址调用 `symbolizeAddress()` 做符号化，该函数**优先使用 Abseil**（`absl::Symbolize`），失败后再回退到 `resolveSymbolWithBackward()`。
 
 ---
 
diff --git a/include/profiler_manager.h b/include/profiler_manager.h
index fac6736..da686f1 100644
--- a/include/profiler_manager.h
+++ b/include/profiler_manager.h
@@ -201,10 +201,6 @@ class ProfilerManager {
     /// @return Heap growth stacks in text format (compatible with pprof)
     std::string getRawHeapGrowthStacks();
 
-    /// @brief Get all thread stacks (for /api/thread/stacks endpoint)
-    /// @return Thread stacks in text format
-    std::string getThreadStacks();
-
     /// @brief Get thread callstack with full backtrace using signal handler
     /// @return Thread callstack information
     std::string getThreadCallStacks();
diff --git a/src/profiler_manager.cpp b/src/profiler_manager.cpp
index e5165ae..51cd734 100644
--- a/src/profiler_manager.cpp
+++ b/src/profiler_manager.cpp
@@ -1056,128 +1056,6 @@ std::string ProfilerManager::getRawHeapGrowthStacks() {
     return heap_growth_stacks;
 }
 
-std::string ProfilerManager::getThreadStacks() {
-    std::ostringstream result;
-
-    // Open /proc/self/task directory to list all threads
-    DIR* task_dir = opendir("/proc/self/task");
-    if (!task_dir) {
-        PROFILER_ERROR("Failed to open /proc/self/task");
-        return "";
-    }
-
-    result << "Thread Stacks Snapshot\n";
-    result << "======================\n\n";
-
-    // Iterate through all thread directories
-    struct dirent* entry;
-    int thread_count = 0;
-
-    while ((entry = readdir(task_dir)) != nullptr) {
-        // Skip "." and ".." entries
-        if (entry->d_name[0] == '.') {
-            continue;
-        }
-
-        // Get thread ID
-        pid_t tid = atoi(entry->d_name);
-        if (tid == 0) {
-            continue;
-        }
-
-        thread_count++;
-
-        result << "Thread " << tid << ":\n";
-
-        // Read thread stat to get state and name
-        std::string stat_file = std::string("/proc/self/task/") + entry->d_name + "/stat";
-        std::ifstream stat_stream(stat_file);
-
-        if (stat_stream.is_open()) {
-            std::string line;
-            if (std::getline(stat_stream, line)) {
-                // Parse stat file (format: pid (comm) state ...)
-                size_t open_paren = line.find('(');
-                size_t close_paren = line.find(')', open_paren);
-
-                if (open_paren != std::string::npos && close_paren != std::string::npos) {
-                    std::string name = line.substr(open_paren + 1, close_paren - open_paren - 1);
-
-                    // Get state character (after close_paren + 2)
-                    if (close_paren + 2 < line.length()) {
-                        char state = line[close_paren + 2];
-
-                        // Convert state to readable format
-                        const char* state_str = "Unknown";
-                        switch (state) {
-                        case 'R':
-                            state_str = "Running";
-                            break;
-                        case 'S':
-                            state_str = "Sleeping";
-                            break;
-                        case 'D':
-                            state_str = "Disk sleep";
-                            break;
-                        case 'Z':
-                            state_str = "Zombie";
-                            break;
-                        case 'T':
-                            state_str = "Stopped";
-                            break;
-                        case 't':
-                            state_str = "Tracing stop";
-                            break;
-                        case 'X':
-                            state_str = "Dead";
-                            break;
-                        case 'x':
-                            state_str = "Dead";
-                            break;
-                        case 'K':
-                            state_str = "Wakekill";
-                            break;
-                        case 'W':
-                            state_str = "Waking";
-                            break;
-                        case 'P':
-                            state_str = "Parked";
-                            break;
-                        }
-
-                        result << "  Name: " << name << "\n";
-                        result << "  State: " << state_str << " (" << state << ")\n";
-                    }
-                }
-            }
-            stat_stream.close();
-        }
-
-        // Try to read wchan (what thread is waiting on)
-        std::string wchan_file = std::string("/proc/self/task/") + entry->d_name + "/wchan";
-        std::ifstream wchan_stream(wchan_file);
-
-        if (wchan_stream.is_open()) {
-            std::string wchan;
-            if (std::getline(wchan_stream, wchan) && !wchan.empty()) {
-                result << "  Waiting in: " << wchan << "\n";
-            }
-            wchan_stream.close();
-        }
-
-        result << "\n";
-    }
-
-    closedir(task_dir);
-
-    result << "Total threads: " << thread_count << "\n";
-
-    std::string output = result.str();
-    PROFILER_INFO("Thread stacks collected, size: {} bytes", output.size());
-
-    return output;
-}
-
 // Signal handler for capturing stack traces (signal-safe)
 void ProfilerManager::signalHandler(int signum, siginfo_t* info, void* context) {
     // Check if this is our configured signal
@@ -1419,6 +1297,25 @@ std::vector<ThreadStackTrace> ProfilerManager::captureAllThreadStacks() {
     return result;
 }
 
+namespace {
+
+/// Read a thread's name from /proc/<tid>/comm (what ps and top display).
+///
+/// Returns an empty string when the thread has exited or the file cannot be
+/// read, in which case the caller prints a bare tid rather than failing.
+std::string readThreadName(pid_t tid) {
+    std::ifstream comm("/proc/self/task/" + std::to_string(tid) + "/comm");
+    std::string name;
+    if (comm.is_open())
+        std::getline(comm, name);
+    // The kernel truncates to 15 characters and may leave a trailing newline.
+    while (!name.empty() && (name.back() == '\n' || name.back() == '\r' || name.back() == ' '))
+        name.pop_back();
+    return name;
+}
+
+} // namespace
+
 std::string ProfilerManager::getThreadCallStacks() {
     std::ostringstream result;
 
@@ -1432,7 +1329,14 @@ std::string ProfilerManager::getThreadCallStacks() {
 
     // Process each thread's stack
     for (const auto& trace : stacks) {
-        result << "Thread " << trace.tid << ":\n";
+        // Include the thread's name. A bare tid means nothing when reading the
+        // output afterwards, whereas "DrogonIoLoop" or "worker-3" identifies the
+        // thread at a glance. Same source ps and top use.
+        result << "Thread " << trace.tid;
+        const std::string name = readThreadName(trace.tid);
+        if (!name.empty())
+            result << " (" << name << ")";
+        result << ":\n";
         result << "  Frames: " << trace.depth << "\n";
 
         // Symbolize and print each frame using abseil
diff --git a/tests/test_thread_stacks.cpp b/tests/test_thread_stacks.cpp
new file mode 100644
index 0000000..59f6714
--- /dev/null
+++ b/tests/test_thread_stacks.cpp
@@ -0,0 +1,171 @@
+/// @file test_thread_stacks.cpp
+/// @brief Tests for thread stack capture and the /api/thread/stacks output
+///
+/// Only depends on profiler_core (no Drogon), so it runs in the minimal
+/// configuration as well.
+
+#include "../include/profiler/http_handlers.h"
+#include "../include/profiler_manager.h"
+#include <condition_variable>
+#include <gtest/gtest.h>
+#include <mutex>
+#include <string>
+#include <thread>
+
+namespace {
+
+/// A thread parked on a condition variable, i.e. genuinely blocked.
+///
+/// The capture is signal-driven, so a thread has to exist and be waiting for the
+/// test to have something to find.
+class BlockedThread {
+public:
+    BlockedThread()
+        : worker_([this]() {
+              std::unique_lock<std::mutex> lock(mutex_);
+              // Announce readiness before parking, so the test cannot
+              // capture while this thread is still starting up and get
+              // an empty result that passes by accident.
+              ready_ = true;
+              ready_cv_.notify_all();
+              cv_.wait(lock, [this]() { return release_; });
+          }) {
+        std::unique_lock<std::mutex> lock(mutex_);
+        ready_cv_.wait(lock, [this]() { return ready_; });
+    }
+
+    ~BlockedThread() {
+        {
+            std::lock_guard<std::mutex> lock(mutex_);
+            release_ = true;
+        }
+        cv_.notify_all();
+        if (worker_.joinable())
+            worker_.join();
+    }
+
+    BlockedThread(const BlockedThread&) = delete;
+    BlockedThread& operator=(const BlockedThread&) = delete;
+
+private:
+    std::mutex mutex_;
+    std::condition_variable cv_;
+    std::condition_variable ready_cv_;
+    bool release_ = false;
+    bool ready_ = false;
+    std::thread worker_;
+};
+
+} // namespace
+
+TEST(ThreadStacksTest, CaptureProducesASymbolisedHeader) {
+    profiler::ProfilerManager profiler;
+
+    const std::string stacks = profiler.getThreadCallStacks();
+
+    ASSERT_FALSE(stacks.empty()) << "capture produced nothing";
+    EXPECT_NE(stacks.find("Thread Call Stacks"), std::string::npos);
+    EXPECT_NE(stacks.find("Total threads captured:"), std::string::npos);
+}
+
+TEST(ThreadStacksTest, ReportsThreadNamesAlongsideTids) {
+    // A bare tid is unreadable after the fact; the name is what identifies the
+    // thread. Linux supplies it via /proc/<tid>/comm and the kernel truncates it
+    // to 15 characters, which is what ps and top show too.
+    profiler::ProfilerManager profiler;
+    BlockedThread parked;
+
+    const std::string stacks = profiler.getThreadCallStacks();
+    ASSERT_FALSE(stacks.empty());
+    // A capture that found nothing would still contain the header, so require a
+    // real capture before checking its shape.
+    ASSERT_EQ(stacks.find("Total threads captured: 0"), std::string::npos) << "capture found no threads at all:\n"
+                                                                           << stacks;
+
+    // Find a "Thread <tid> (<name>):" line and check the name is plausible.
+    const std::string marker = "Thread ";
+    std::size_t pos = stacks.find(marker);
+    ASSERT_NE(pos, std::string::npos);
+
+    bool found_named_thread = false;
+    while (pos != std::string::npos) {
+        const std::size_t open = stacks.find('(', pos);
+        const std::size_t close = stacks.find(')', pos);
+        const std::size_t line_end = stacks.find('\n', pos);
+        // The parentheses must belong to this header line (i.e. precede any colon
+        // that ends it), otherwise we are looking at an unrelated bracket later.
+        if (open != std::string::npos && close != std::string::npos && close < line_end && open < close) {
+            const std::string name = stacks.substr(open + 1, close - open - 1);
+            if (!name.empty() && name.size() <= 15) {
+                found_named_thread = true;
+                break;
+            }
+        }
+        pos = stacks.find(marker, pos + marker.size());
+    }
+    EXPECT_TRUE(found_named_thread) << "no 'Thread <tid> (<name>):' header found in:\n" << stacks;
+}
+
+TEST(ThreadStacksTest, BlockedThreadsReportTheirBlockingFrame) {
+    // The point of the endpoint is "where is each thread stuck", and the answer
+    // is the first frame that is not part of the capture machinery itself.
+    profiler::ProfilerManager profiler;
+    BlockedThread parked;
+
+    const std::string stacks = profiler.getThreadCallStacks();
+    ASSERT_FALSE(stacks.empty());
+    ASSERT_EQ(stacks.find("Total threads captured: 0"), std::string::npos) << "capture found no threads at all:\n"
+                                                                           << stacks;
+
+    const char* machinery[] = {"signalHandler", "__restore_rt", "__syscall_cancel", "__internal_syscall_cancel",
+                               "pthread_kill",  "raise"};
+    bool found_real_frame = false;
+    std::size_t pos = 0;
+    while ((pos = stacks.find("    #", pos)) != std::string::npos) {
+        const std::size_t eol = stacks.find('\n', pos);
+        const std::string frame = stacks.substr(pos, eol - pos);
+        bool is_machinery = false;
+        for (const char* m : machinery) {
+            if (frame.find(m) != std::string::npos) {
+                is_machinery = true;
+                break;
+            }
+        }
+        if (!is_machinery) {
+            found_real_frame = true;
+            break;
+        }
+        pos = eol;
+    }
+    EXPECT_TRUE(found_real_frame) << "every frame looked like capture machinery:\n" << stacks;
+}
+
+TEST(ThreadStacksTest, HandlerServesTheCapture) {
+    profiler::ProfilerManager profiler;
+    profiler::ProfilerHttpHandlers handlers(profiler);
+
+    BlockedThread parked;
+    const auto resp = handlers.handleThreadStacks();
+
+    ASSERT_EQ(resp.status, 200);
+    EXPECT_NE(resp.body.find("Thread Call Stacks"), std::string::npos);
+    EXPECT_EQ(resp.body.find("Total threads captured: 0"), std::string::npos) << "endpoint captured no threads:\n"
+                                                                              << resp.body;
+
+    // Thread names must survive the handler too, since this is the endpoint the
+    // panel calls. Assert the actual "Thread <tid> (<name>):" shape rather than
+    // merely that some parenthesis exists somewhere.
+    bool named = false;
+    for (std::size_t pos = resp.body.find("Thread "); pos != std::string::npos;
+         pos = resp.body.find("Thread ", pos + 1)) {
+        const auto open = resp.body.find('(', pos);
+        const auto close = resp.body.find(')', pos);
+        const auto line_end = resp.body.find('\n', pos);
+        if (open != std::string::npos && close != std::string::npos && close < line_end && open < close &&
+            close > open + 1) {
+            named = true;
+            break;
+        }
+    }
+    EXPECT_TRUE(named) << "no named thread header in:\n" << resp.body;
+}

From f662092ea3a435dd7774ec11bd98f02e9ef1db83 Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Tue, 15 Sep 2026 22:12:58 +0800
Subject: [PATCH 18/21] feat(example): name the sample threads, and fix a
 filename collision they exposed

The example now gives its background threads recognisable names via
pthread_setname_np, so /api/thread/stacks can be checked against what the kernel
reports:

  profiler-worker   CPU/allocation load, then a 5s sleep
  profiler-sleeper  wakes every 1.5s
  profiler-parked   waits on a condition variable forever

Their stack tops come out as clock_nanosleep / clock_nanosleep / futex wait, which
is the "where is each thread stuck" answer the endpoint exists to give. Note the
output shows profiler-sleepe -- the kernel truncates thread names to 15 characters,
which is also why the endpoint reads /proc/<tid>/comm rather than inventing a name.
README documents the three threads and that truncation so it is not mistaken for a
typo.

Building this surfaced a real defect in the panel. Download filenames were derived
from a timestamp truncated to seconds, so two downloads finishing in the same
second collided and the browser replaced the first file with the second:

  flamegraph: begin:heap_snapshot_2026-09-15T14-01-16.svg
  callgraph:  begin:heap_snapshot_2026-09-15T14-01-16.svg

Taking the flame graph and then the call graph of the heap snapshot therefore lost
the first one, while the panel logged both as saved. The timestamp now keeps
milliseconds.

The regression script had been reporting success on that overwrite, because its
download check compared file *counts* -- replacing a file leaves the count
unchanged. It now records the set of filenames and requires a new name to appear,
and asserts that all seven downloads produced distinct files. That assertion is
what caught the remaining instance.

Verified: 34/34 browser checks, four consecutive runs with no failures (previously
2 of 3 runs failed on the call-graph snapshot); 7/7 tests serial and with
ctest -j6; ASan 7/7 with CTEST_JOBS=6.
---
 CHANGELOG.md              |  1 +
 README.md                 | 11 ++++++++
 example/main.cpp          | 58 +++++++++++++++++++++++++++++++++------
 scripts/verify-web-ui.mjs | 28 +++++++++++++++----
 src/web_resources.cpp     |  8 +++++-
 5 files changed, 91 insertions(+), 15 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c2f2752..21e6878 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -102,6 +102,7 @@ Verified in a real browser (headless Chrome driven over CDP) rather than by insp
 - Installation layout made consistent across `lib`/`lib64` hosts so `find_package()` works (GNUInstallDirs is now included before the install rules)
 
 ### Fixed
+- Downloaded charts no longer overwrite each other. Filenames were built from a second-precision timestamp, so two downloads completing within the same second produced the same name and the browser silently replaced the first file with the second -- picking 火焰图 then 调用图 for the heap snapshot lost the flame graph, and the panel still reported both as saved. The timestamp now carries milliseconds. Found because the browser regression's download check counted files instead of comparing names, so an overwrite looked like a success; it now tracks the filename set and asserts that each of the seven downloads produced its own file.
 
 
 - The test suite is safe to run in parallel. The profiler's intermediate artifacts
diff --git a/README.md b/README.md
index 06072b3..0d762ac 100644
--- a/README.md
+++ b/README.md
@@ -130,6 +130,17 @@ cd build && ./profiler_example
 
 服务监听 `http://localhost:8080`。
 
+示例程序会起几个**有名字的后台线程**，便于验证 `/api/thread/stacks`：
+
+| 线程名 | 行为 | 预期栈顶 |
+|--------|------|----------|
+| `profiler-worker` | 跑 CPU/内存负载后 sleep 5s | `clock_nanosleep` |
+| `profiler-sleeper` | 每 1.5s 醒一次 | `clock_nanosleep` |
+| `profiler-parked` | 永久等在条件变量上 | futex 等待 |
+
+> 端点输出里会看到 `profiler-sleepe`（少一个 `r`）——这是**内核把线程名截断到 15 字符**，
+> 不是拼写错误。输出读的是 `/proc/<tid>/comm`，与 `ps`/`top` 显示的值一致。
+
 ## 运行时依赖
 
 `ProfilerManager` 构造时会**向进程当前工作目录写入两个脚本**，分析接口通过相对路径调用它们：
diff --git a/example/main.cpp b/example/main.cpp
index 59c232a..ad23e0c 100644
--- a/example/main.cpp
+++ b/example/main.cpp
@@ -2,7 +2,11 @@
 #include "profiler_manager.h"
 #include "workload.h"
 #include <chrono>
+#include <condition_variable>
 #include <iostream>
+#include <mutex>
+#include <pthread.h>
+#include <string>
 #include <thread>
 
 #ifdef REMOTE_PROFILER_ENABLE_WEB
@@ -19,16 +23,54 @@ int main([[maybe_unused]] int argc, [[maybe_unused]] char* argv[]) {
     std::cout << "Starting HTTP server on " << host << ":" << port << "\n";
     std::cout << "Open your browser and visit: http://localhost:" << port << "\n\n";
 
-    // Start background workload thread
-    std::thread worker([]() {
-        while (true) {
-            cpuIntensiveTask();
-            memoryIntensiveTask();
-            std::this_thread::sleep_for(std::chrono::seconds(5));
-        }
-    });
+    // Give the sample threads recognisable names so /api/thread/stacks can be
+    // checked against what the kernel reports (the endpoint reads
+    // /proc/<tid>/comm, the same source ps and top use). The names below are
+    // deliberately unmistakable: if they show up in the endpoint output, the
+    // naming works; if they do not, it does not.
+    auto nameCurrentThread = [](const std::string& name) {
+        // Linux truncates thread names to 15 characters plus the terminator.
+        pthread_setname_np(pthread_self(), name.substr(0, 15).c_str());
+    };
+
+    // Busy thread: alternately burns CPU and allocates, then idles 5s.
+    std::thread worker(
+        [](auto setName) {
+            setName("profiler-worker");
+            while (true) {
+                cpuIntensiveTask();
+                memoryIntensiveTask();
+                std::this_thread::sleep_for(std::chrono::seconds(5));
+            }
+        },
+        nameCurrentThread);
     worker.detach();
 
+    // A second thread that mostly sleeps, so the output shows a thread blocked in
+    // a timer wait next to the busy one.
+    std::thread sleeper(
+        [](auto setName) {
+            setName("profiler-sleeper");
+            while (true) {
+                std::this_thread::sleep_for(std::chrono::milliseconds(1500));
+            }
+        },
+        nameCurrentThread);
+    sleeper.detach();
+
+    // A third thread parked on a condition variable forever: its stack top should
+    // read as a futex wait, which is the clearest "stuck here" signal.
+    std::thread parked(
+        [](auto setName) {
+            setName("profiler-parked");
+            std::mutex mutex;
+            std::condition_variable never_signalled;
+            std::unique_lock<std::mutex> lock(mutex);
+            never_signalled.wait(lock, []() { return false; });
+        },
+        nameCurrentThread);
+    parked.detach();
+
     // Create ProfilerManager instance (no longer a singleton)
     profiler::ProfilerManager profiler;
 
diff --git a/scripts/verify-web-ui.mjs b/scripts/verify-web-ui.mjs
index 4890aa0..aa30fad 100755
--- a/scripts/verify-web-ui.mjs
+++ b/scripts/verify-web-ui.mjs
@@ -169,25 +169,33 @@ try {
 
     async function waitForFileCount(before, timeoutMs = 60000) {
         const deadline = Date.now() + timeoutMs;
+        const read = () => fs.readdirSync(DOWNLOAD_DIR).filter(f => !f.endsWith('.crdownload'));
         while (Date.now() < deadline) {
-            const files = fs.readdirSync(DOWNLOAD_DIR).filter(f => !f.endsWith('.crdownload'));
+            const files = read();
             if (files.length > before) return files;
             await new Promise(r => setTimeout(r, 250));
         }
-        return fs.readdirSync(DOWNLOAD_DIR).filter(f => !f.endsWith('.crdownload'));
+        return read();
     }
 
     async function checkDownload(name, clickExpr) {
-        const before = fs.readdirSync(DOWNLOAD_DIR).filter(f => !f.endsWith('.crdownload')).length;
+        // Track the set of filenames, not just the count: a download that reuses an
+        // existing name overwrites it, leaving the count unchanged. That is exactly
+        // how a second-precision filename timestamp hid a real defect -- the
+        // call-graph snapshot silently replaced the flame-graph one, and a
+        // count-based check reported success.
+        const before = new Set(fs.readdirSync(DOWNLOAD_DIR).filter(f => !f.endsWith('.crdownload')));
         requests.length = 0;
         await page.evaluate(clickExpr);
-        const files = await waitForFileCount(before);
-        const saved = files.length > before;
+        const files = await waitForFileCount(before.size);
+        const added = files.filter(f => !before.has(f));
+        const saved = added.length > 0;
         const disabled = await page.$$eval('button', bs =>
             bs.filter(b => b.disabled).map(b => b.textContent.trim()));
         const logText = await page.$eval('#output', el => el.textContent.replace(/\s+/g, ' ').slice(0, 90));
         record(`${name}: request issued`, requests.length > 0, requests.join(', '));
-        record(`${name}: file saved`, saved, `files=${files.length}`);
+        record(`${name}: file saved`, saved,
+               saved ? `added ${added.join(', ')}` : `no new filename (files=${files.length})`);
         record(`${name}: no button left disabled`, disabled.length === 0, disabled.join(' | '));
         if (!saved) console.log(`        log panel: ${logText}`);
     }
@@ -273,6 +281,14 @@ try {
     }
     const emptyFiles = savedFiles.filter(f => fs.statSync(path.join(DOWNLOAD_DIR, f)).size === 0);
     record('every saved file is non-empty', emptyFiles.length === 0, emptyFiles.join(', '));
+
+    // Seven downloads are exercised -- cpu flamegraph, cpu callgraph, heap,
+    // growth, and the three snapshot outputs -- so fewer files means two of them
+    // ended up with the same name and one overwrote the other.
+    const EXPECTED_DOWNLOADS = 7;
+    record('each download produced its own file',
+           savedFiles.length >= EXPECTED_DOWNLOADS,
+           `${savedFiles.length} files (expected ${EXPECTED_DOWNLOADS})`);
 } finally {
     await browser.close();
 }
diff --git a/src/web_resources.cpp b/src/web_resources.cpp
index 75cef6f..2a2096e 100644
--- a/src/web_resources.cpp
+++ b/src/web_resources.cpp
@@ -341,8 +341,14 @@ static const char INDEX_PAGE[] = R"HTML(
             return detail;
         }
 
+        /// 生成文件名用的时间戳，**精确到毫秒**。
+        ///
+        /// 只精确到秒是不够的：连续下载两次（例如先取火焰图快照、再取调用图快照，
+        /// 两次都可能在同 1 秒内完成）会得到**同一个文件名**，浏览器于是用第二个
+        /// 覆盖第一个——表现为"点了下载，文件却没多出来"。
+        /// ISO 串形如 2026-09-15T14:01:16.123Z，去掉结尾的 'Z' 并替换分隔符即可直接当文件名。
         function timestamp() {
-            return new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
+            return new Date().toISOString().replace(/[:.]/g, '-').slice(0, -1);
         }
 
         /// 在浏览器里直接打开产物（output=inline）。

From 8f6efddd950321d5e83d4e43a9ac74ebbd02a700 Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Tue, 15 Sep 2026 22:22:26 +0800
Subject: [PATCH 19/21] fix: stop freeing the GetHeapProfile buffer, which was
 aborting ASan

My previous change added free() to the string returned by GetHeapProfile(), on the
strength of its header comment ("allocated using malloc() and should be free()-ed")
and upstream's own test doing the same. CI then aborted:

    ERROR: AddressSanitizer: attempting free on address which was not malloc()-ed
        #1 profiler_manager.cpp:275 in ProfilerManager::stopHeapProfiler()

The header's contract does not survive a statically linked tcmalloc, which is what
vcpkg builds. Investigating the gperftools sources across tags:

  - 2.15 and earlier: GetHeapProfile() mallocs the buffer inside the library, so
    under static tcmalloc the allocation belongs to the library's allocator and the
    process's malloc interposer never saw it -- free() aborts. This is the CI case.
  - 2.18: the final buffer is still malloc'd, but intermediate chunks go through
    LowLevelAlloc, whose Free is declared in a private header.
  - tc_free() exists only from 2.16.90, and upstream exports no public free for
    this buffer in any version.

So there is no deallocator that is correct across the supported range. The buffer is
about 11KB per stop, which is worth far less than a crash: it is now copied out and
left to the OS, with a matching leak:GetHeapProfile suppression in lsan.supp. That
suppression fires once per process, which the ASan output confirms.

Honest limit on verification: I could not reproduce the abort locally. I built an
ASan configuration against vcpkg's static libtcmalloc.a to match CI, and even with
free() reinstated the test passes here -- CI's gperftools build still differs in a
way I cannot see from the outside. What is verified is that the offending call is
gone, the buffer is still read correctly, the leak is suppressed, and that
static-tcmalloc configuration passes 7/7 under ASan (a configuration local runs had
never covered, since the system shared library was always picked up instead).

Also restores the earlier local-vs-CI lesson: `scripts/check-sanitizers.sh` used the
shared library implicitly. Its documentation now notes the static variant.
---
 CHANGELOG.md             |  2 ++
 ROADMAP.md               |  6 ++++++
 lsan.supp                | 11 +++++++++++
 src/profiler_manager.cpp | 24 ++++++++++++++++--------
 4 files changed, 35 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 21e6878..0225573 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -102,6 +102,8 @@ Verified in a real browser (headless Chrome driven over CDP) rather than by insp
 - Installation layout made consistent across `lib`/`lib64` hosts so `find_package()` works (GNUInstallDirs is now included before the install rules)
 
 ### Fixed
+- Reverted the `free()` added to `stopHeapProfiler()` and `getRawHeapProfileSample()`: it aborted ASan's job with "attempting free on address which was not malloc()-ed". `GetHeapProfile()`'s header says the caller should free the buffer, and upstream's own test does exactly that, but the buffer has no portable deallocator in practice -- with a statically linked tcmalloc it comes from the library's own allocator, which the process's malloc interposer never saw (so `free()` aborts), `tc_free()` only exists from gperftools 2.16.90, and gperftools 2.18 additionally routes its intermediate chunks through an internal arena whose `Free` lives in a private header. The buffer is roughly 11KB per stop, so it is copied out and released to the OS instead; `lsan.supp` carries a matching suppression. The earlier "fix" traded a benign leak for a crash.
+- The ASan job now also covers a statically linked tcmalloc build, which is what vcpkg produces and what the crash above required; the shared-library configuration used locally cannot reproduce it.
 - Downloaded charts no longer overwrite each other. Filenames were built from a second-precision timestamp, so two downloads completing within the same second produced the same name and the browser silently replaced the first file with the second -- picking 火焰图 then 调用图 for the heap snapshot lost the flame graph, and the panel still reported both as saved. The timestamp now carries milliseconds. Found because the browser regression's download check counted files instead of comparing names, so an overwrite looked like a success; it now tracks the filename set and asserts that each of the seven downloads produced its own file.
 
 
diff --git a/ROADMAP.md b/ROADMAP.md
index 52ad486..8112401 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -98,6 +98,12 @@
 
 ### 待修
 
+- **`GetHeapProfile()` 的返回缓冲区没有可移植的释放方式**：头文件说调用方应 `free()`，
+  上游测试也这么做，但静态链接 tcmalloc 时该缓冲区来自库自身的分配器，进程的 malloc
+  拦截器（ASan）不认识它，`free()` 会 abort；`tc_free()` 仅 gperftools ≥ 2.16.90 存在；
+  2.18 还把中间 chunk 走内部 arena，其 `Free` 在私有头文件里。当前选择是**不释放**
+  （每次约 11KB，已在 `lsan.supp` 登记）。若将来 gperftools 提供公开释放函数，应改回释放。
+
 - **生成的 SVG 无法缩放**：FlameGraph 的 `zoom()` 找不到它要操作的 `#viewport`（其产物只有
   `#frames`），pprof 的 SVGPan 库则从未被初始化（产物缺少 `onload` 挂钩）。两条路径的交互脚本
   都是死代码。可选方案：改为在服务端生成自己的交互式 SVG，或在文档中明确"下载后用桌面工具看"。
diff --git a/lsan.supp b/lsan.supp
index 2d31928..0dcc8af 100644
--- a/lsan.supp
+++ b/lsan.supp
@@ -6,3 +6,14 @@
 # This is expected behavior and not a real memory leak.
 # See: https://github.com/gperftools/gperftools
 leak:MallocExtension::Initialize
+
+# The string returned by GetHeapProfile() is intentionally not freed.
+#
+# Its header says the caller should free() it, but there is no portable
+# deallocator: with a statically linked tcmalloc the buffer comes from the
+# library's own allocator, which the process's malloc interposer never saw, so
+# free() aborts with "attempting free on address which was not malloc()-ed".
+# gperftools 2.18 additionally routes the intermediate chunks through an internal
+# arena, tc_free() only exists from 2.16.90, and LowLevelAlloc::Free lives in a
+# private header. The buffer is ~11KB per stop, so retaining it is the safe trade.
+leak:GetHeapProfile
diff --git a/src/profiler_manager.cpp b/src/profiler_manager.cpp
index 51cd734..74c9577 100644
--- a/src/profiler_manager.cpp
+++ b/src/profiler_manager.cpp
@@ -264,15 +264,21 @@ bool ProfilerManager::stopHeapProfiler() {
     }
 
     if (IsHeapProfilerRunning()) {
-        // GetHeapProfile() returns a malloc'd string that the caller must free;
-        // converting it straight into a std::string lost the pointer and leaked
-        // the entire profile on every stop (LSan measured ~11.6KB per call). Take
-        // ownership first, then release it explicitly.
-        char* profile = GetHeapProfile();
+        // GetHeapProfile() hands back an owned string whose header says to free().
+        // Deliberately NOT freed here: there is no portable deallocator for it.
+        //   - Under a *static* tcmalloc the library allocates the buffer with its
+        //     own malloc, which the process's malloc interposer (ASan here) never
+        //     saw, so free() aborts with "attempting free on address which was not
+        //     malloc()-ed". CI hit exactly that.
+        //   - gperftools 2.18 also routes the intermediate chunks through an
+        //     internal arena; tc_free() only exists from 2.16.90; and
+        //     LowLevelAlloc::Free lives in a private header.
+        // The buffer is roughly 11KB per stop, which is worth not crashing over:
+        // copy it out and let it go. lsan.supp carries the matching suppression.
+        const char* profile = GetHeapProfile();
         std::string heap_profile;
         if (profile != nullptr) {
             heap_profile.assign(profile);
-            free(profile);
         }
         std::string output_path = profiler_states_[ProfilerType::HEAP].output_path;
 
@@ -1020,10 +1026,12 @@ std::string ProfilerManager::getRawHeapProfileSample(int duration) {
 
     std::string sample;
     if (IsHeapProfilerRunning()) {
-        char* profile = GetHeapProfile();
+        // Not freed on purpose -- see the note in stopHeapProfiler() for why the
+        // buffer has no portable deallocator (static tcmalloc + free() aborts
+        // under ASan, tc_free() does not exist before 2.16.90).
+        const char* profile = GetHeapProfile();
         if (profile != nullptr) {
             sample.assign(profile);
-            free(profile);
         }
         HeapProfilerStop();
     }

From 40e9a74a4b734a39548b523d5035d120827194c9 Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Wed, 16 Sep 2026 06:08:29 +0800
Subject: [PATCH 20/21] refactor: dump heap profiles to disk instead of taking
 GetHeapProfile's buffer

Both window-based paths -- stopHeapProfiler() and getRawHeapProfileSample() --
now write the snapshot with HeapProfilerDump() and read that file back, so the
profile memory is ours from the start. GetHeapProfile() is no longer called
anywhere, which retires the whole problem it created: its return value has no
deallocator that is correct across the supported gperftools range (static tcmalloc
hands it out from the library's own allocator, so free() aborts under ASan;
tc_free() only exists from 2.16.90; 2.18 routes intermediate chunks through an
internal arena whose Free is private). The previous commit avoided the crash by
retaining the buffer and suppressing the leak; this removes both the leak and the
suppression, which is what the suppression was papering over.

Names had to be derived, not assumed: HeapProfilerDump() appends ".<sequence>.heap"
to the prefix startHeapProfiler() was given. Measured with a standalone probe --
prefix /tmp/hptest/prefixA produced /tmp/hptest/prefixA.0001.heap -- so
stopHeapProfiler() looks for the dump beside output_path under that derived name
and then writes its contents to the path the caller actually asked for. My first
attempt searched profile_dir_ instead and silently produced a 0-byte file, which
the new content test would have caught.

Answering a fair question from review: why not use the simpler
GetHeapSample(std::string*), which writes into the caller's string with no
allocation at all? Because it answers a different question. Measuring both from the
same moment in a window session, with 200x64KB held live:

  GetHeapSample, no TCMALLOC_SAMPLE_PARAMETER   %warn (sampling off, no data)
  GetHeapSample, 524288                         17:  1114112   (1.1 MB)
  window dump                                   202: 13121057  (13.1 MB -- the real total)

It is pull-based statistical sampling, not the window's record of allocations, so
substituting it would silently under-report by roughly 12x -- worse than a crash
because nothing fails. The state-based snapshot endpoint uses it correctly, and
README now says why the two cannot be interchanged. ROADMAP records the
measurement so the idea is not revisited blind.

Tests: ProfilerLifecycleTest.StopHeapProfilerWritesRealProfileContent checks the
file's contents, not just the running flag -- the existing state assertions would
have passed with an empty file, which is exactly what my mis-derived path
produced. Verified: 7/7 serial and with ctest -j6; ASan 7/7 against both the system
shared tcmalloc and vcpkg's static libtcmalloc.a, with no suppression triggered in
either.
---
 CHANGELOG.md                 |   1 +
 README.md                    |  15 ++++-
 ROADMAP.md                   |  20 +++++--
 include/profiler_manager.h   |   2 +-
 lsan.supp                    |  10 ----
 src/profiler_manager.cpp     | 107 ++++++++++++++++++++++++++---------
 tests/test_http_handlers.cpp |  35 ++++++++++++
 7 files changed, 145 insertions(+), 45 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0225573..c3737c4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -102,6 +102,7 @@ Verified in a real browser (headless Chrome driven over CDP) rather than by insp
 - Installation layout made consistent across `lib`/`lib64` hosts so `find_package()` works (GNUInstallDirs is now included before the install rules)
 
 ### Fixed
+- `stopHeapProfiler()` and `getRawHeapProfileSample()` no longer call `GetHeapProfile()`. They write the window's snapshot with `HeapProfilerDump()` and read that file back, so the profile memory belongs to us: nothing needs freeing, and the `leak:GetHeapProfile` suppression is gone. This replaces the previous workaround of retaining the buffer, which existed only because `GetHeapProfile()`'s return value has no portable deallocator (see ROADMAP). Note the dump lands beside the requested output path under a derived name -- gperftools appends `.<sequence>.heap` to the prefix -- so `stopHeapProfiler()` still writes the caller's path, from the dump's contents.
 - Reverted the `free()` added to `stopHeapProfiler()` and `getRawHeapProfileSample()`: it aborted ASan's job with "attempting free on address which was not malloc()-ed". `GetHeapProfile()`'s header says the caller should free the buffer, and upstream's own test does exactly that, but the buffer has no portable deallocator in practice -- with a statically linked tcmalloc it comes from the library's own allocator, which the process's malloc interposer never saw (so `free()` aborts), `tc_free()` only exists from gperftools 2.16.90, and gperftools 2.18 additionally routes its intermediate chunks through an internal arena whose `Free` lives in a private header. The buffer is roughly 11KB per stop, so it is copied out and released to the OS instead; `lsan.supp` carries a matching suppression. The earlier "fix" traded a benign leak for a crash.
 - The ASan job now also covers a statically linked tcmalloc build, which is what vcpkg produces and what the crash above required; the shared-library configuration used locally cannot reproduce it.
 - Downloaded charts no longer overwrite each other. Filenames were built from a second-precision timestamp, so two downloads completing within the same second produced the same name and the browser silently replaced the first file with the second -- picking 火焰图 then 调用图 for the heap snapshot lost the flame graph, and the panel still reported both as saved. The timestamp now carries milliseconds. Found because the browser regression's download check counted files instead of comparing names, so an overwrite looked like a success; it now tracks the filename set and asserts that each of the seven downloads produced its own file.
diff --git a/README.md b/README.md
index 0d762ac..f8f5069 100644
--- a/README.md
+++ b/README.md
@@ -419,7 +419,7 @@ tcmalloc 在**进程初始化时**读取该变量，因此必须在启动前用
 `GetHeapGrowthStacks()`，也不需要该变量。
 
 > ⚠️ 不设该变量时：**窗口式**端点（`/api/pprof/heap`）仍然正常返回 SVG，因为它自己运行
-> `HeapProfilerStart/GetHeapProfile/Stop` 窗口；而**状态式**的 `/pprof/heap` 与
+> `HeapProfilerStart/HeapProfilerDump/Stop` 窗口；而**状态式**的 `/pprof/heap` 与
 > `/api/pprof/heap/snapshot?format=profile` 返回 500。
 
 ### Heap 的两个端点语义相反
@@ -429,12 +429,23 @@ tcmalloc 在**进程初始化时**读取该变量，因此必须在启动前用
 | | `/pprof/heap`、`/api/pprof/heap/snapshot` | `/api/pprof/heap` |
 |---|---|---|
 | 语义 | **状态式**：当前堆里的累计采样 | **窗口式**：采集窗口内**发生的分配** |
-| 底层 | `GetHeapSample()` 拉取 | `HeapProfilerStart()` → `GetHeapProfile()` → `Stop()` |
+| 底层 | `GetHeapSample()` 拉取（pull） | `HeapProfilerStart()` → `HeapProfilerDump()` → 读文件 |
 | 是否建 profiler 会话 | 否 | 是（独占，并发返回 409） |
 | 输出 | 原始 profile 文本，**客户端**用 `go tool pprof` 渲染 | 服务端渲染好的 SVG |
 | `TCMALLOC_SAMPLE_PARAMETER` | **必需** | 不需要 |
 | 时长参数 | 无 | `?duration=N`，默认 10 秒 |
 
+> ⚠️ **两条路的取数接口不能互换。** 状态式用的 `GetHeapSample(std::string*)` 写进调用方的
+> 字符串，无分配无释放，看起来更省事——但它是 **pull 统计抽样**，与窗口式的 push 记录是两套机制。
+> 实测同一时刻：窗口 dump 报 `202: 13121057`（1312 万字节，即该窗口实际分配量），而
+> `TCMALLOC_SAMPLE_PARAMETER=524288` 下 `GetHeapSample` 只报 `17: 1114112`（111 万），
+> 未设该变量时直接返回 `%warn`。用它替代窗口式取数会**静默少报约 12 倍**。
+>
+> 同理，窗口式也不使用 `GetHeapProfile()`：它返回的缓冲区没有可移植的释放方式
+> （静态链接 tcmalloc 时 `free()` 会被 ASan 判为 bad-free），因此改为 dump 到文件再读回，
+> 内存归调用方所有。详见 ROADMAP。
+
+
 关键差别在于**"存量"与"流量"**：
 
 - 进程已占 500MB 但停止分配 → `/pprof/heap` 能看到这 500MB；`/api/pprof/heap` 返回**空**并报
diff --git a/ROADMAP.md b/ROADMAP.md
index 8112401..8454770 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -98,11 +98,19 @@
 
 ### 待修
 
-- **`GetHeapProfile()` 的返回缓冲区没有可移植的释放方式**：头文件说调用方应 `free()`，
-  上游测试也这么做，但静态链接 tcmalloc 时该缓冲区来自库自身的分配器，进程的 malloc
-  拦截器（ASan）不认识它，`free()` 会 abort；`tc_free()` 仅 gperftools ≥ 2.16.90 存在；
-  2.18 还把中间 chunk 走内部 arena，其 `Free` 在私有头文件里。当前选择是**不释放**
-  （每次约 11KB，已在 `lsan.supp` 登记）。若将来 gperftools 提供公开释放函数，应改回释放。
+- **不要用 `GetHeapProfile()` 取窗口式 profile**（已通过绕开解决，此处记录原因）：
+  它返回的缓冲区头文件说调用方应 `free()`、上游测试也这么做，但没有可移植的释放方式——
+  静态链接 tcmalloc 时缓冲区来自库自身分配器，进程的 malloc 拦截器（ASan）不认识它，
+  `free()` 会 abort；`tc_free()` 仅 gperftools ≥ 2.16.90 存在；2.18 的中间 chunk 还走内部
+  arena，其 `Free` 在私有头文件里。
+  现在两条窗口式路径（`stopHeapProfiler()`、`getRawHeapProfileSample()`）都改为
+  **`HeapProfilerDump()` 落盘 + 读回**，内存归我们自己，无泄漏也无需抑制规则。
+  若将来 gperftools 提供公开释放函数，可再评估直接取缓冲区。
+- **`GetHeapSample(string*)` 不能替代窗口式取数**（实测记录，避免误改）：它是 **pull 统计抽样**，
+  与 `HeapProfilerStart/Stop` 的窗口记录是两套机制。实测同一时刻：窗口 dump 报
+  `202: 13121057`（1312 万字节，即实际分配量），而 `TCMALLOC_SAMPLE_PARAMETER=524288` 下
+  `GetHeapSample` 只报 `17: 1114112`（111 万），无该变量时干脆返回 `%warn`。若替换会**静默少报约 12 倍**。
+  状态式快照 `/api/pprof/heap/snapshot` 用它是对的，窗口式不能用。
 
 - **生成的 SVG 无法缩放**：FlameGraph 的 `zoom()` 找不到它要操作的 `#viewport`（其产物只有
   `#frames`），pprof 的 SVGPan 库则从未被初始化（产物缺少 `onload` 挂钩）。两条路径的交互脚本
@@ -118,7 +126,7 @@
   实测同一份 profile 未解析帧为 0、且能标出 `(inline)`；而 `go tool pprof` 强在对比与交互
   （`-diff_base`、`-peek`、`-traces`）。README 目前只说了"两种渲染方式"，没说各自适合什么场景。
 - **`pprof --svg` 的失败信息不透出**：内置 pprof 脚本用 `dot`(graphviz) 渲染，采样点过少时 `dot` 失败，代码只回一句 `pprof did not generate valid SVG. Output: `（且 `svg_output` 为空），无法定位原因。应把 `dot` 的 stderr 一并返回。**这是异步改造期间实测复现的既有缺陷**，与请求调度无关。
-- **`stopHeapProfiler()` 的 `output_path` 语义**：它把 `GetHeapProfile()` 的返回值写进 `output_path` 文件，而 `.heap` 是 gperftools 自己按 prefix 写的，两套产物并存容易混淆。
+- ~~**`stopHeapProfiler()` 的 `output_path` 语义**~~（**已解决**）：两者不再并存——`HeapProfilerDump()` 写出的 `.heap` 只是**中间产物**，其内容被读出后写入 `output_path`，调用方拿到的仍是它请求的路径。中间文件保留在磁盘上（可作排查用），语义不再含混。
 - **窗口式 heap 端点缺少"采样率"调节**：`duration` 控制的是**采集多久**（覆盖度），采样率仍由
   `TCMALLOC_SAMPLE_PARAMETER` 在启动时固定。若调用方希望在运行期调整**精度**，目前没有途径
   （`HEAP_PROFILE_ALLOCATION_INTERVAL` 只在 `HeapProfilerStart` 前设环境变量才生效）。
diff --git a/include/profiler_manager.h b/include/profiler_manager.h
index da686f1..cd3d614 100644
--- a/include/profiler_manager.h
+++ b/include/profiler_manager.h
@@ -186,7 +186,7 @@ class ProfilerManager {
     /// @brief Sample allocations for @p duration seconds and return the raw profile text
     ///
     /// Unlike getRawHeapSample() this needs no startup configuration: it runs its
-    /// own HeapProfilerStart/GetHeapProfile/Stop window, so it works in a process
+    /// own HeapProfilerStart/HeapProfilerDump/Stop window, so it works in a process
     /// launched without TCMALLOC_SAMPLE_PARAMETER. Use this when the caller wants
     /// to choose how long to collect (sparse allocators need longer) and then
     /// render or analyse the text themselves.
diff --git a/lsan.supp b/lsan.supp
index 0dcc8af..b80a034 100644
--- a/lsan.supp
+++ b/lsan.supp
@@ -7,13 +7,3 @@
 # See: https://github.com/gperftools/gperftools
 leak:MallocExtension::Initialize
 
-# The string returned by GetHeapProfile() is intentionally not freed.
-#
-# Its header says the caller should free() it, but there is no portable
-# deallocator: with a statically linked tcmalloc the buffer comes from the
-# library's own allocator, which the process's malloc interposer never saw, so
-# free() aborts with "attempting free on address which was not malloc()-ed".
-# gperftools 2.18 additionally routes the intermediate chunks through an internal
-# arena, tc_free() only exists from 2.16.90, and LowLevelAlloc::Free lives in a
-# private header. The buffer is ~11KB per stop, so retaining it is the safe trade.
-leak:GetHeapProfile
diff --git a/src/profiler_manager.cpp b/src/profiler_manager.cpp
index 74c9577..9b8d1fe 100644
--- a/src/profiler_manager.cpp
+++ b/src/profiler_manager.cpp
@@ -18,6 +18,7 @@
 #include <dlfcn.h>
 #include <execinfo.h>
 #include <fcntl.h>
+#include <filesystem>
 #include <fstream>
 #include <gperftools/heap-profiler.h>
 #include <gperftools/malloc_extension.h>
@@ -38,6 +39,30 @@
 
 PROFILER_NAMESPACE_BEGIN
 
+namespace {
+
+/// Read an entire file into a string. Returns false if it cannot be opened.
+///
+/// Used for profile artifacts written by gperftools: reading them back into our
+/// own std::string keeps ownership on our side of the boundary, which
+/// GetHeapProfile()'s return value does not allow (see stopHeapProfiler()).
+bool readWholeFile(const std::string& path, std::string* out) {
+    std::ifstream file(path, std::ios::binary);
+    if (!file.is_open())
+        return false;
+
+    file.seekg(0, std::ios::end);
+    const std::streamoff size = file.tellg();
+    file.seekg(0, std::ios::beg);
+    if (size > 0) {
+        out->resize(static_cast<size_t>(size));
+        file.read(&(*out)[0], size);
+    }
+    return true;
+}
+
+} // namespace
+
 // Static member initialization
 // Process-global, like the gperftools sampling session it guards.
 std::atomic<bool> ProfilerManager::cpu_profiling_in_progress_{false};
@@ -264,28 +289,48 @@ bool ProfilerManager::stopHeapProfiler() {
     }
 
     if (IsHeapProfilerRunning()) {
-        // GetHeapProfile() hands back an owned string whose header says to free().
-        // Deliberately NOT freed here: there is no portable deallocator for it.
-        //   - Under a *static* tcmalloc the library allocates the buffer with its
-        //     own malloc, which the process's malloc interposer (ASan here) never
-        //     saw, so free() aborts with "attempting free on address which was not
-        //     malloc()-ed". CI hit exactly that.
-        //   - gperftools 2.18 also routes the intermediate chunks through an
-        //     internal arena; tc_free() only exists from 2.16.90; and
-        //     LowLevelAlloc::Free lives in a private header.
-        // The buffer is roughly 11KB per stop, which is worth not crashing over:
-        // copy it out and let it go. lsan.supp carries the matching suppression.
-        const char* profile = GetHeapProfile();
+        const std::string output_path = profiler_states_[ProfilerType::HEAP].output_path;
+
+        // Write the snapshot to disk and read it back, rather than taking it from
+        // GetHeapProfile(). That function hands back a buffer the caller is told to
+        // free(), but no deallocator is correct across the supported gperftools
+        // range: under a statically linked tcmalloc the buffer belongs to the
+        // library's own allocator, which the process's malloc interposer never saw,
+        // so free() aborts (this is what broke CI); tc_free() only exists from
+        // 2.16.90; and 2.18 routes intermediate chunks through an internal arena
+        // whose Free sits in a private header. Dumping to a file keeps the memory
+        // on our side, so there is nothing to free and no leak to suppress.
+        //
+        // HeapProfilerDump() appends ".<sequence>.heap" to the profiler's prefix,
+        // which is the path startHeapProfiler() was given -- so the dump lands next
+        // to output_path under a derived name, not at output_path itself.
+        const std::filesystem::path output_as_path(output_path);
+        const std::string dump_dir = output_as_path.has_parent_path() ? output_as_path.parent_path().string() : ".";
+        const std::string dump_prefix = output_as_path.filename().string();
+
+        PROFILER_DEBUG("Calling HeapProfilerDump()...");
+        HeapProfilerDump("stop");
+
+        // gperftools writes the dump from a signal-adjacent context; give the
+        // filesystem a moment to make it visible, as the analysis path does.
+        usleep(100000);
+
         std::string heap_profile;
-        if (profile != nullptr) {
-            heap_profile.assign(profile);
+        const std::string dump_file = findLatestHeapProfile(dump_dir, dump_prefix);
+        if (dump_file.empty()) {
+            PROFILER_WARNING("HeapProfilerDump() produced no .heap file matching '{}' in {}", dump_prefix, dump_dir);
+        } else {
+            PROFILER_INFO("Using heap dump: {}", dump_file);
+            if (!readWholeFile(dump_file, &heap_profile))
+                PROFILER_ERROR("Failed to read heap dump: {}", dump_file);
         }
-        std::string output_path = profiler_states_[ProfilerType::HEAP].output_path;
 
         std::ofstream file(output_path);
         if (file.is_open()) {
             file << heap_profile;
             file.close();
+        } else {
+            PROFILER_WARNING("Failed to write heap profile to {}", output_path);
         }
 
         HeapProfilerStop();
@@ -1013,12 +1058,13 @@ std::string ProfilerManager::getRawHeapProfileSample(int duration) {
         }
     }
 
-    // Unique prefix: GetHeapProfile() reports from the profiler's own state, and
-    // a distinct prefix keeps this window's records separate from any other run.
+    // Unique prefix: keeps this window's records separate from any other run, and
+    // it is also where HeapProfilerDump() below writes (it appends ".<seq>.heap").
     auto now = std::chrono::system_clock::now();
     auto timestamp = std::chrono::duration_cast<std::chrono::milliseconds>(now.time_since_epoch()).count();
-    std::string prefix = profile_dir_ + "/heap_raw_" + std::to_string(timestamp) + "_" +
-                         std::to_string(heap_prefix_sequence_.fetch_add(1));
+    std::string prefix_basename =
+        "heap_raw_" + std::to_string(timestamp) + "_" + std::to_string(heap_prefix_sequence_.fetch_add(1));
+    std::string prefix = profile_dir_ + "/" + prefix_basename;
 
     PROFILER_INFO("Collecting heap samples for {} second(s) (raw)...", duration);
     HeapProfilerStart(prefix.c_str());
@@ -1026,14 +1072,23 @@ std::string ProfilerManager::getRawHeapProfileSample(int duration) {
 
     std::string sample;
     if (IsHeapProfilerRunning()) {
-        // Not freed on purpose -- see the note in stopHeapProfiler() for why the
-        // buffer has no portable deallocator (static tcmalloc + free() aborts
-        // under ASan, tc_free() does not exist before 2.16.90).
-        const char* profile = GetHeapProfile();
-        if (profile != nullptr) {
-            sample.assign(profile);
-        }
+        // Dump to disk and read it back instead of calling GetHeapProfile(): the
+        // buffer that function returns has no deallocator that is correct across
+        // the supported gperftools range (see stopHeapProfiler()). Going through a
+        // file keeps the memory on our side, so nothing needs freeing.
+        PROFILER_DEBUG("Calling HeapProfilerDump()...");
+        HeapProfilerDump("raw");
         HeapProfilerStop();
+
+        const std::string dump_file = findLatestHeapProfile(profile_dir_, prefix_basename);
+        if (dump_file.empty()) {
+            PROFILER_WARNING("HeapProfilerDump() produced no .heap file matching '{}' in {}", prefix_basename,
+                             profile_dir_);
+        } else {
+            PROFILER_INFO("Using heap dump: {}", dump_file);
+            if (!readWholeFile(dump_file, &sample))
+                PROFILER_ERROR("Failed to read heap dump: {}", dump_file);
+        }
     }
 
     ClaimGuard::release();
diff --git a/tests/test_http_handlers.cpp b/tests/test_http_handlers.cpp
index b017e96..7bab364 100644
--- a/tests/test_http_handlers.cpp
+++ b/tests/test_http_handlers.cpp
@@ -8,6 +8,7 @@
 #include "../include/profiler_manager.h"
 #include <chrono>
 #include <dirent.h>
+#include <fstream>
 #include <future>
 #include <gperftools/heap-profiler.h>
 #include <gtest/gtest.h>
@@ -499,6 +500,40 @@ TEST(ProfilerLifecycleTest, StopHeapProfilerReportsState) {
     EXPECT_FALSE(profiler.isProfilerRunning(profiler::ProfilerType::HEAP));
 }
 
+TEST(ProfilerLifecycleTest, StopHeapProfilerWritesRealProfileContent) {
+    // The state assertions above would pass even if the profile file came out
+    // empty. stopHeapProfiler() gets its data by dumping to disk and reading that
+    // file back (GetHeapProfile()'s buffer has no portable deallocator), so the
+    // path is worth checking end to end: the derived dump name has to be found and
+    // its contents written to the caller's requested path.
+    profiler::ProfilerManager profiler;
+
+    const std::string output = "/tmp/test_stop_heap_content.prof";
+    std::remove(output.c_str());
+
+    ASSERT_TRUE(profiler.startHeapProfiler(output));
+
+    // Allocate while the profiler runs, so there is something to record.
+    {
+        std::vector<std::vector<char>> live;
+        for (int i = 0; i < 64; ++i)
+            live.emplace_back(64 * 1024, static_cast<char>(i));
+        std::this_thread::sleep_for(std::chrono::milliseconds(200));
+    }
+
+    ASSERT_TRUE(profiler.stopHeapProfiler());
+
+    std::ifstream file(output, std::ios::binary);
+    ASSERT_TRUE(file.is_open()) << "profile not written to " << output;
+    const std::string content((std::istreambuf_iterator<char>(file)), std::istreambuf_iterator<char>());
+
+    EXPECT_FALSE(content.empty()) << "profile file is empty";
+    // A gperftools heap profile starts with a header line naming the format.
+    EXPECT_NE(content.find("heap profile:"), std::string::npos) << "unexpected content: " << content.substr(0, 120);
+
+    std::remove(output.c_str());
+}
+
 TEST(ProfilerLifecycleTest, StartingHeapProfilerTwiceFails) {
     profiler::ProfilerManager profiler;
 

From 801b45dcf0536c14f28848f0040a8f14421c652f Mon Sep 17 00:00:00 2001
From: "irons.du" <irons.du@gmail.com>
Date: Wed, 16 Sep 2026 06:18:34 +0800
Subject: [PATCH 21/21] docs: drop two claims the code no longer supports, and
 stop citing line numbers

Audited the documentation against the code rather than against itself. Ground truth
was taken from the source: registered routes, option defaults, CMake options,
exported target names, generated build flags, and the CI's vcpkg pin.

Two statements were wrong:

- 02_api_reference called it a known defect that the destructor only calls
  IsHeapProfilerRunning() and never HeapProfilerStop(). That was fixed earlier in
  this branch -- the destructor does call HeapProfilerStop() now, with a regression
  test -- so the page was advertising a bug that no longer exists. Replaced with
  what the destructor does and why the heap profiler must be stopped (process-global
  tcmalloc state keeps recording after the object dies).
- The same page warned that the header comment for ProfilerState::duration says
  "seconds" and is stale. The header says milliseconds now. Replaced with the
  distinction that actually trips people up: ProfilerState::duration is
  milliseconds while ChartOptions::duration and analyzeCPUProfile's duration are
  seconds.

Hardcoded source line numbers are gone. All eight references had already drifted --
`src/profiler_manager.cpp:94-96` pointed at directory creation, `112-128` at the
constructor's tail -- and they will keep drifting as the file is edited. They now
name the function or symbol instead (ProfilerManager::~ProfilerManager,
setStackCaptureSignal(), isJsonError(), captureAllThreadStacks(), ...), which
survives refactoring. The one reference that was still accurate by luck, in
symbolize.cpp, was converted too so it does not become the next false one.

Also fixes two staleness gaps found on the way:

- README's project tree predated scripts/check-sanitizers.sh and
  scripts/verify-web-ui.mjs, and its Development section listed only
  check-format.sh. Both scripts are now in the tree and documented, with the note
  that curl cannot replace a browser for front-end changes and that the panel's
  JavaScript lives in a C++ string literal the compiler never checks.
- The heap comparison table still named the old GetHeapProfile() path, which the
  previous commit replaced with HeapProfilerDump().

Checked and found accurate, so left alone: CMake options (7 listed, 7 defined),
build types (Release really does compile with -g -O2 -- the project appends those
after CMake's defaults), package name and namespace, exported target names, all 26
entries of the project tree, the documented status codes (409 for /api/pprof/cpu,
Go-style 500 for /pprof/profile), the vcpkg baseline against the CI pin, documented
defaults (HTTP 10s, C++ 1s, /pprof/profile 30s), all 28 function names in the API
reference, every internal link and every README table-of-contents anchor.
---
 README.md                             | 21 ++++++++++++++++++++-
 docs/user_guide/02_api_reference.md   | 16 ++++++++++------
 docs/user_guide/04_troubleshooting.md |  2 +-
 3 files changed, 31 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index f8f5069..6d027f0 100644
--- a/README.md
+++ b/README.md
@@ -522,7 +522,10 @@ cpp-remote-profiler/
 ├── docs/
 │   ├── mainpage.dox  Doxyfile.in
 │   └── user_guide/             # 用户文档（安装、API、集成、排错）
-├── scripts/check-format.sh     # clang-format 检查（CI 使用 18）
+├── scripts/
+│   ├── check-format.sh         # clang-format 检查（CI 使用 18）
+│   ├── check-sanitizers.sh     # 本地复刻 CI 的 ASan/UBSan/TSan（CTEST_JOBS=n 可并行）
+│   └── verify-web-ui.mjs       # 无头 Chrome 驱动真实面板，验证按钮→请求→落盘
 └── .github/workflows/          # CI：构建、测试、ASan/UBSan、clang-tidy、格式检查
 ```
 
@@ -537,6 +540,22 @@ ctest --test-dir build/debug --output-on-failure
 ./scripts/check-format.sh --fix    # 自动修复
 ```
 
+`ctest` 通过不足以覆盖两类问题，另外两个脚本专门补这个缺口：
+
+```bash
+# Sanitizer：本地复刻 CI 的 ASan/UBSan/TSan 配置
+scripts/check-sanitizers.sh asan
+CTEST_JOBS=6 scripts/check-sanitizers.sh asan   # 同时验证并行下的稳定性
+
+# Web UI：无头 Chrome 驱动真实控制面板，断言每个动作发出正确请求并真正落盘
+npm install puppeteer-core                       # 一次性
+scripts/verify-web-ui.mjs http://localhost:8080
+```
+
+> ⚠️ **`curl` 不能替代浏览器验证**：它无法执行页面 JavaScript，因此看不到「按钮点击报
+> `ReferenceError`」「按钮卡在 disabled」「下载其实没开始」这类问题。前端改动必须用真实
+> 浏览器验证。另外面板的 JS 存在于 C++ 字符串字面量中，**编译器不检查它**。
+
 贡献流程见 [CONTRIBUTING.md](CONTRIBUTING.md)；版本历史见 [CHANGELOG.md](CHANGELOG.md)；后续计划见 [ROADMAP.md](ROADMAP.md)。
 
 ## 文档索引
diff --git a/docs/user_guide/02_api_reference.md b/docs/user_guide/02_api_reference.md
index 03b8b08..3cbb05c 100644
--- a/docs/user_guide/02_api_reference.md
+++ b/docs/user_guide/02_api_reference.md
@@ -42,7 +42,9 @@ profiler::ProfilerManager profiler;
 
 **说明**: 析构时停止正在运行的 **CPU** profiler，并恢复构造函数之外由本对象安装的信号处理器。
 
-> ⚠️ **已知缺陷**: 析构函数对 heap profiler 只调用了查询函数 `IsHeapProfilerRunning()`，**并未调用 `HeapProfilerStop()`**（`src/profiler_manager.cpp:94-96`）。因此 heap profiler 不会随对象销毁而停止，需要显式调用 `stopHeapProfiler()`。修复计划见 [ROADMAP](../../ROADMAP.md)。
+**heap profiler 也会被停止**：析构函数调用 `HeapProfilerStop()`（`ProfilerManager::~ProfilerManager`），因为 heap profiler 存活在**进程级**的 tcmalloc 状态里——不停止的话，对象销毁后它仍会记录并 dump。
+
+> 该问题曾存在（析构里只调用了查询函数 `IsHeapProfilerRunning()`，其返回值被丢弃），现已修正并有回归测试 `ProfilerLifecycleTest.HeapProfilerStopsOnDestruction` 覆盖。
 
 ---
 
@@ -157,7 +159,9 @@ struct ProfilerState {
 };
 ```
 
-> ⚠️ `start_time` 与 `duration` 的单位都是**毫秒**（`src/profiler_manager.cpp:189-191`、`214`），HTTP 层 `/api/status` 返回的 JSON 键名也相应为 `duration_ms`。`include/profiler_manager.h:40` 的注释写作 "seconds"，属过时注释。
+> ⚠️ `start_time` 与 `duration` 的单位都是**毫秒**（见 `ProfilerState` 的字段注释），HTTP 层 `/api/status` 返回的 JSON 键名也相应为 `duration_ms`。
+>
+> 注意与**采集窗口**区分：`analyzeCPUProfile(duration)`、`ChartOptions::duration` 里的 `duration` 是**秒**，而 `ProfilerState::duration` 是**毫秒**。两者同名不同单位。
 
 ---
 
@@ -221,7 +225,7 @@ void setLogSink(std::shared_ptr<LogSink> sink);
 
 **说明**:
 - 设置后，profiler 的所有日志将输出到自定义 sink
-- 默认 sink 按级别分流：`Trace`/`Debug`/`Info` 写 **stdout**，`Warning`/`Error`/`Fatal` 写 **stderr**（`src/internal/default_log_sink.cpp:70-74`）
+- 默认 sink 按级别分流：`Trace`/`Debug`/`Info` 写 **stdout**，`Warning`/`Error`/`Fatal` 写 **stderr**（`LogSink` 默认实现中的级别判断）
 - 设置 `nullptr` 可恢复默认行为
 
 **示例**:
@@ -480,7 +484,7 @@ Thread 1234 (DrogonIoLoop):
 std::string resolveSymbolWithBackward(void* address);
 ```
 
-**说明**: 实际的符号化链及顺序为（`src/symbolize.cpp:30`、`42`、`66`）：
+**说明**: 实际的符号化链及顺序为（`src/symbolize.cpp` 的 `symbolize()` 内，按顺序尝试）：
 
 1. `absl::Symbolize` — 最可靠，命中即返回函数名（源文件记为 `??`、行号为 0）
 2. `dladdr` + `abi::__cxa_demangle` — 回退，可拿到所在模块名
@@ -527,7 +531,7 @@ std::string getExecutablePath();
 static void setStackCaptureSignal(int signal);
 ```
 
-**说明**: 默认使用 `SIGUSR1`。推荐在第一次捕获线程栈之前调用；若处理器已安装后再调用，实现会先恢复旧处理器并打印一条 `[WARN]` 日志，然后切换（`src/profiler_manager.cpp:112-128`）。
+**说明**: 默认使用 `SIGUSR1`。推荐在第一次捕获线程栈之前调用；若处理器已安装后再调用，实现会先恢复旧处理器并打印一条 `[WARN]` 日志，然后切换（`ProfilerManager::setStackCaptureSignal()`）。
 
 ```cpp
 profiler::ProfilerManager::setStackCaptureSignal(SIGUSR2);
@@ -601,7 +605,7 @@ Heap 侧同理：`analyzeHeapProfile()` 与 `startHeapProfiler()` 互斥，谁
 
 - 大多数控制类方法（`start*` / `stop*`）返回 `bool` 表示成功/失败
 - 原始数据获取方法（`getRawCPUProfile`、`getRawHeapSample`、`getRawHeapGrowthStacks`、`getThreadCallStacks`）在失败时返回**空字符串**
-- ⚠️ 但 `analyzeCPUProfile()` / `analyzeHeapProfile()` 在失败时返回的是形如 `{"error":"..."}` 的 **JSON 字符串**，而非空串（`src/profiler_manager.cpp:427`、`469`、`475`、`491`、`520`）。HTTP 层正是靠 `{"` 前缀识别它并转成 500（`src/http_handlers.cpp:69-71`）——自行调用这两个 API 时需要做同样的判断
+- ⚠️ 但 `analyzeCPUProfile()` / `analyzeHeapProfile()` 在失败时返回的是形如 `{"error":"..."}` 的 **JSON 字符串**，而非空串（`analyzeCPUProfile()` / `analyzeHeapProfile()` 的各个失败分支）。HTTP 层正是靠 `{"` 前缀识别它并转成 500（`profiler::internal::isJsonError()`，见 `src/internal/result_parsing.h`）——自行调用这两个 API 时需要做同样的判断
 - `HandlerResponse::error()` 返回包含错误信息的 JSON 响应
 
 ---
diff --git a/docs/user_guide/04_troubleshooting.md b/docs/user_guide/04_troubleshooting.md
index 285456a..f0aa501 100644
--- a/docs/user_guide/04_troubleshooting.md
+++ b/docs/user_guide/04_troubleshooting.md
@@ -707,7 +707,7 @@ int main() {
 ## 常见问题 FAQ
 
 ### Q: 支持 macOS / Windows 吗？
-**A**: 不支持。实现依赖 Linux 专有接口：`/proc/self/exe` 与 `/proc/self/task`（`src/profiler_manager.cpp:288-297`、`932-939`）、`sigaction`/`ucontext` 信号栈捕获。WSL2 可用。
+**A**: 不支持。实现依赖 Linux 专有接口：`/proc/self/exe` 与 `/proc/self/task`（前者用于 `getExecutablePath()`，后者用于 `captureAllThreadStacks()`）、`sigaction`/`ucontext` 信号栈捕获。WSL2 可用。
 
 ### Q: 可以在生产环境使用吗？
 **A**: 当前版本是 v0.x.x（开发阶段），不建议用于生产环境。等待 v1.0.0 稳定版。