citrine-devtools 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6ad9103211d1286b38e3106ddd895c46661b975fb5dcf08a30bb92d6262d4ea1
+  data.tar.gz: 40c98f02c45fbf012a60e32295d8f831d79c912b5042aefd29c6898c3d81cf68
+SHA512:
+  metadata.gz: 936fcc314caf398396fdfd2240c9644a8293418a4baadbca114737aa0733f310ad1a4d1ae1a85a4d67f0469553cdacf4104b94fc5883e3cbad9410caf55df1bc
+  data.tar.gz: 43c261c4ad493df5c91cb9f21ef91d26c629654dd08b24f2cd2a8a266b3162846532990e4dcf04f4db6a0b2ba060af5b14256dc4ba1bf3a826cbb48a19c55509

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShiningRay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,44 @@
+# citrine-devtools
+
+Citrine/Emerald DevTools 传输层：中继服务 + 浏览器桥接脚本 + Web 调试面板。
+
+信号式 Ruby UI 框架（[citrine](https://github.com/ShiningRay/citrine) /
+[emerald](https://github.com/ShiningRay/emerald)）的调试器底座——把 M1 时序探针
+（`write_log` / `flush_trace` / `event_stream` / `component_tree`）的数据经消息
+总线送达调试面板，并把面板指令（`set_signal` / `force_rerun` / `request_tree` /
+`request_graph`）转发回被调试页执行。协议契约见 [docs/PROTOCOL.md](docs/PROTOCOL.md)。
+
+## 组成
+
+| 组件 | 说明 |
+|---|---|
+| `citrine-devtools serve` | 中继服务（默认 9527）：SSE 下行 + ingest/cmd 上行 + 静态托管面板与桥接脚本 |
+| `bridge.js` | 被调试页引入的桥接脚本：采集探针 ring、上报、执行面板指令 |
+| `panel.html` / `panel.js` | Web 调试面板：组件树 / 信号列表 / 依赖图（Cytoscape）/ Timeline / Inspector |
+
+## 快速开始
+
+```bash
+gem install citrine-devtools
+citrine-devtools serve          # → http://localhost:9527/ 打开面板
+
+# 被调试页（由 citrine dev server 服务时）加一行：
+<script src="http://127.0.0.1:9527/bridge.js"></script>
+```
+
+## 开发
+
+```bash
+bundle install && bundle exec rake   # Ruby 集成测试 + bridge 契约 + 面板模型契约
+node --test                          # JS 契约（node 24+）
+```
+
+## 设计文档
+
+分层架构、红线与路线图见 citrine 仓的
+[DESIGN-devtools.md](https://github.com/ShiningRay/citrine/blob/main/docs/DESIGN-devtools.md) 与
+[PLAN-devtools.md](https://github.com/ShiningRay/citrine/blob/main/docs/PLAN-devtools.md)。
+
+## License
+
+MIT（含 vendor 的 Cytoscape.js，MIT © The Cytoscape Consortium）。

data/bin/citrine-devtools

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# lib 入 $LOAD_PATH：与 gem 安装后的 require 解析行为一致
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+$stdout.sync = true # CLI 输出重定向到文件/管道时不应块缓冲
+
+require "citrine-devtools"
+
+cmd = ARGV.shift
+case cmd
+when "serve"
+  Citrine::DevTools::Server.run!(ARGV)
+when nil, "help", "-h", "--help"
+  puts <<~USAGE
+    citrine-devtools — Citrine/Emerald DevTools 中继服务
+
+    用法:
+      bin/citrine-devtools serve [-p 端口]   启动中继（消息总线，默认端口 9527）
+
+    被调试页引入桥接脚本（协议见 docs/PROTOCOL.md）:
+      <script src="http://127.0.0.1:9527/bridge.js"></script>
+  USAGE
+else
+  warn "未知命令: #{cmd}（试试 bin/citrine-devtools help）"
+  exit 1
+end

data/docs/PROTOCOL.md

@@ -0,0 +1,52 @@
+# citrine-devtools · 传输协议 v1
+
+> DESIGN-devtools §4 的落地契约。中继（`citrine-devtools serve`）是消息总线：
+> 浏览器桥接脚本上报探针数据，调试面板订阅消费；面板指令经同一条总线下发桥接执行。
+> 所有消息 JSON，顶层带 `v: 1` 与 `type`。
+
+## 端点（默认端口 9527）
+
+| 端点 | 方法 | 方向 | 说明 |
+|---|---|---|---|
+| `/__devtools/stream` | GET | 下行 | SSE 流。客户端两类：面板（消费数据+发指令）与桥接（收指令）。15s comment ping 清扫僵尸连接 |
+| `/__devtools/ingest` | POST | 上行 | 桥接批量上报：`{v:1, messages:[…]}`。中继逐条广播给所有 stream 客户端 |
+| `/__devtools/cmd` | POST | 上行 | 面板发指令：`{v:1, type:"cmd", cmd:"set_signal", …}`。中继原样广播（桥接消费、面板忽略） |
+| `/bridge.js` | GET | — | 桥接脚本静态资源，`<script src="http://127.0.0.1:9527/bridge.js">` 引入被调试页 |
+
+CORS：`Access-Control-Allow-Origin: *`（仅 localhost 调试场景），处理 OPTIONS 预检。
+
+## 下行消息（v1）
+
+| type | 载荷 | 生产者 |
+|---|---|---|
+| `hello` | `{v, app_name?, citrine_version?}` | 桥接连接时上报（幂等：Emerald 热更新重连可重复发） |
+| `signal_write` | M1 write_log 条目 `{t, signal_id, old, new, source}` | 桥接 |
+| `flush` | M1 flush_trace 条目 `{flush_id, t, effects, trigger_signal_ids}` | 桥接 |
+| `event` | M1 event_stream 条目 `{t, event_type, target_component, handler_name, flush_ids}` | 桥接 |
+| `tree` | `Citrine.debug_component_tree` 快照 | 桥接（应 `request_tree` 指令触发，也允许定时） |
+| `graph` | `Citrine.debug_dependency_graph` 快照 | 桥接（应 `request_graph` 指令触发） |
+| `cmd` | `{cmd, …参数}` 见下表 | 面板 → 中继广播 → 桥接执行 |
+
+## 指令（cmd 载荷）
+
+| cmd | 参数 | 桥接行为 |
+|---|---|---|
+| `set_signal` | `{signal_id, value}` | 在 `Signal.all` 里按 object_id 找信号并 `$set(value)`；找不到回 `error` |
+| `force_rerun` | `{effect_id}` | 在 `Effect.all` 里按 object_id 找 effect 并 `$run` |
+| `request_tree` / `request_graph` | `{}` | 采集快照以 `tree`/`graph` 消息回传 |
+| `highlight_node` | `{node_id}` | v1 未实现：回 `{type:"error", error:"highlight_node 未实现（M3）"}` |
+
+## 桥接脚本（bridge.js）行为契约
+
+- 激活条件：`window.CITRINE_DEV && window.Opal`；否则静默不启动（生产/SSR 零影响）。
+- 中继地址：`window.CITRINE_DEVTOOLS_URL` 覆盖，默认 `http://127.0.0.1:9527`。
+- 采集：每 100ms 读 `Opal.Citrine` 的 write_log / flush_trace / event_stream 三个 ring
+  （`$to_a().$to_n()`），与上次快照 diff（按条目去重，不假设 ring 不滚动），
+  新条目攒批 POST ingest（另 50ms 聚合窗口）。
+- 上报故障静默降级（warn 一次），绝不抛进被调试应用。
+- 收到自身发不认识的 type 一律忽略；执行 cmd 的异常回 `{type:"error", cmd, error}`。
+
+## 会话
+
+v1 单会话：`hello` 的 `app_name` 仅作展示。多 Emerald 窗口同连一个中继时消息混合——
+M5 前不按会话隔离（DESIGN §八 风险 5）。

data/lib/citrine-devtools/bridge.js

@@ -0,0 +1,264 @@
+/*
+ * citrine-devtools 桥接脚本（M2-2）——被调试页经
+ * <script src="http://127.0.0.1:9527/bridge.js"> 引入。
+ *
+ * 行为契约见 citrine-devtools docs/PROTOCOL.md v1 §桥接脚本：
+ *   - 激活条件 window.CITRINE_DEV && window.Opal；否则静默不启动（生产/SSR 零影响）
+ *   - 中继地址 window.CITRINE_DEVTOOLS_URL 覆盖，默认 http://127.0.0.1:9527
+ *   - 每 100ms 读三个 ring（write_log / flush_trace / event_stream，$to_a().$to_n()），
+ *     按条目指纹去重 diff（不假设 ring 不滚动），新条目攒批 POST ingest
+ *     （另 50ms 聚合窗口）
+ *   - 上报故障静默降级（warn 一次），绝不抛进被调试应用
+ *   - 收到自身发不认识的 type 一律忽略；执行 cmd 的异常回 {type:"error", cmd, error}
+ *
+ * request_tree 的根节点发现（本地实现细节，线上协议之外），按序尝试：
+ *   1. window.CITRINE_DEVTOOLS_ROOT（页面可选提供：根 Node 或组件实例）
+ *   2. 渲染器（Citrine.renderer）暴露的 root_node 方法（beryl 入口）
+ *   3. 渲染器的 @root 实例变量（Canvas 渲染器有存）
+ * 都找不到时回 error，由页面提供 CITRINE_DEVTOOLS_ROOT 解决。
+ */
+(function () {
+  "use strict";
+
+  if (typeof window === "undefined") return; // SSR：静默不启动
+  // 激活条件（协议）：否则静默不启动
+  if (!window.CITRINE_DEV || !window.Opal) return;
+  // 同一页面二次求值不起第二个桥接实例（Emerald 热更新会重放脚本）
+  if (window.__CITRINE_DEVTOOLS_BRIDGE__) return;
+  window.__CITRINE_DEVTOOLS_BRIDGE__ = true;
+
+  var Opal = window.Opal;
+  var Citrine = Opal.Citrine;
+  if (!Citrine) return;
+
+  var PROTOCOL_VERSION = 1;
+  var COLLECT_INTERVAL_MS = 100; // 协议：每 100ms 采集
+  var FLUSH_WINDOW_MS = 50; // 协议：另 50ms 聚合窗口
+  var SEEN_FINGERPRINTS_LIMIT = 2000; // ring 容量 500/个，去重指纹 FIFO 封顶（不假设 ring 不滚动）
+
+  var relayUrl = String(window.CITRINE_DEVTOOLS_URL || "http://127.0.0.1:9527").replace(/\/+$/, "");
+
+  // 探针只在 debug_tracking 开启时记录（M1 口径）：桥接是页面的调试代理，负责打开它
+  try { Citrine["$debug_tracking="](true); } catch (e) { /* 旧版内核无开关则探针自管 */ }
+
+  // ── 上行：攒批 POST ingest ─────────────────────────────
+
+  var outbox = [];
+  var flushTimer = null;
+  var lastFlushAt = 0;
+  var degraded = false; // 上报故障静默降级（warn 一次）
+
+  function enqueue(message) {
+    outbox.push(message);
+    scheduleFlush();
+  }
+
+  function scheduleFlush() {
+    if (flushTimer) return;
+    var wait = Math.max(0, FLUSH_WINDOW_MS - (Date.now() - lastFlushAt));
+    flushTimer = setTimeout(flush, wait);
+  }
+
+  function flush() {
+    flushTimer = null;
+    if (!outbox.length) return;
+    var batch = outbox;
+    outbox = [];
+    lastFlushAt = Date.now();
+    fetch(relayUrl + "/__devtools/ingest", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ v: PROTOCOL_VERSION, messages: batch })
+    }).then(function (res) {
+      if (res && res.ok === false) throw new Error("HTTP " + res.status); // 非 2xx 也按上报失败降级
+    }).catch(function (err) {
+      if (!degraded) {
+        degraded = true;
+        console.warn("[citrine-devtools] 上报失败，桥接静默降级：", err);
+      }
+    });
+  }
+
+  function reportError(cmd, error) {
+    enqueue({ v: PROTOCOL_VERSION, type: "error", cmd: cmd, error: String((error && error.message) || error) });
+  }
+
+  // ── 采集：三个 ring 的增量 diff ─────────────────────────
+
+  var rings = [
+    { type: "signal_write", read: function () { return Citrine.$debug_write_log().$to_a().$to_n(); } },
+    { type: "flush", read: function () { return Citrine.$debug_flush_trace().$to_a().$to_n(); } },
+    { type: "event", read: function () { return Citrine.$debug_event_stream().$to_a().$to_n(); } }
+  ];
+  var seen = new Map(); // 条目指纹 FIFO 集合：同一条目（ring 未滚动重读）只上报一次
+
+  function fingerprint(entry) {
+    try { return JSON.stringify(entry); } catch (e) { return String(entry); }
+  }
+
+  function markSeen(fp) {
+    if (seen.has(fp)) return false;
+    seen.set(fp, true);
+    if (seen.size > SEEN_FINGERPRINTS_LIMIT) seen.delete(seen.keys().next().value);
+    return true;
+  }
+
+  function collect() {
+    rings.forEach(function (ring) {
+      var entries;
+      try {
+        entries = ring.read();
+      } catch (e) {
+        return; // 探针读取失败不抛进被调试应用
+      }
+      if (!entries || !entries.length) return;
+      entries.forEach(function (entry) {
+        if (!entry || typeof entry !== "object") return;
+        var fp = fingerprint(entry);
+        if (!markSeen(fp)) return; // ring 未滚动时的重读 / 已上报条目
+        var message = { v: PROTOCOL_VERSION, type: ring.type };
+        for (var key in entry) message[key] = entry[key]; // 载荷即 M1 条目字段
+        enqueue(message);
+      });
+    });
+  }
+
+  // ── 下行：SSE 收指令 ───────────────────────────────────
+
+  var es = new EventSource(relayUrl + "/__devtools/stream");
+
+  // 连接时上报 hello（幂等：热更新重连可重复发）；EventSource 自动重连
+  es.onopen = function () {
+    var hello = { v: PROTOCOL_VERSION, type: "hello", citrine_version: citrineVersion() };
+    if (typeof document !== "undefined" && document.title) hello.app_name = document.title;
+    enqueue(hello);
+  };
+
+  es.onmessage = function (e) {
+    var message;
+    try {
+      message = JSON.parse(e.data);
+    } catch (err) {
+      return; // 非 JSON 包一律忽略
+    }
+    if (!message || message.v !== PROTOCOL_VERSION) return;
+    // 畸形 cmd（缺 cmd 字段）按协议静默忽略；其余 type（含自身上报被广播回来的）一律忽略
+    if (message.type === "cmd" && typeof message.cmd === "string") handleCmd(message);
+  };
+
+  function citrineVersion() {
+    try { return Citrine.$const_get("VERSION"); } catch (e) { return undefined; }
+  }
+
+  function handleCmd(cmd) {
+    try {
+      switch (cmd.cmd) {
+        case "set_signal": setSignal(cmd); break;
+        case "force_rerun": forceRerun(cmd); break;
+        case "request_tree": requestTree(cmd); break;
+        case "request_graph": requestGraph(); break;
+        case "highlight_node":
+          reportError("highlight_node", "highlight_node 未实现（M3）");
+          break;
+        default:
+          reportError(cmd.cmd, "未知指令: " + cmd.cmd);
+      }
+    } catch (err) {
+      reportError(cmd.cmd, err); // 执行 cmd 的异常按协议回 error
+    }
+  }
+
+  // JS 值 → Opal 值（跨语言边界）：null/undefined → Opal.nil，对象 → Opal.hash，数组递归，标量直通
+  function jsToOpal(value) {
+    if (value === null || value === undefined) return Opal.nil;
+    if (Array.isArray(value)) {
+      var list = [];
+      for (var i = 0; i < value.length; i++) list.push(jsToOpal(value[i]));
+      return list;
+    }
+    if (typeof value === "object") {
+      var args = [];
+      for (var key in value) {
+        if (Object.prototype.hasOwnProperty.call(value, key)) args.push(key, jsToOpal(value[key]));
+      }
+      return Opal.hash.apply(null, args);
+    }
+    return value;
+  }
+
+  function setSignal(cmd) {
+    var signal = findByObjectId(Citrine.Signal.$all(), cmd.signal_id);
+    if (!signal) {
+      reportError("set_signal", "找不到 signal（object_id=" + cmd.signal_id + "）");
+      return;
+    }
+    signal.$set(jsToOpal(cmd.value));
+  }
+
+  function forceRerun(cmd) {
+    var effect = findByObjectId(Citrine.Effect.$all(), cmd.effect_id);
+    if (!effect) {
+      reportError("force_rerun", "找不到 effect（object_id=" + cmd.effect_id + "）");
+      return;
+    }
+    effect.$run();
+  }
+
+  // Opal 数组即 JS 数组，逐元素比 object_id（Signal.all / Effect.all 仅在埋点开启时填充，
+  // 桥接启动时已打开 debug_tracking）
+  function findByObjectId(all, id) {
+    if (!all) return null;
+    for (var i = 0; i < all.length; i++) {
+      if (all[i] && all[i].$object_id() === id) return all[i];
+    }
+    return null;
+  }
+
+  function requestGraph() {
+    var graph = Citrine.$debug_dependency_graph().$to_n(); // 打开埋点并取 {signals, effects}
+    var message = { v: PROTOCOL_VERSION, type: "graph" };
+    for (var key in graph) message[key] = graph[key];
+    enqueue(message);
+  }
+
+  function requestTree(cmd) {
+    var rootNode = findRootNode();
+    if (!rootNode) {
+      reportError("request_tree",
+        "找不到渲染根节点：请在页面设置 window.CITRINE_DEVTOOLS_ROOT（根 Node 或组件实例）");
+      return;
+    }
+    var snapshot = Citrine.$debug_component_tree(rootNode).$to_n();
+    var message = { v: PROTOCOL_VERSION, type: "tree" };
+    for (var key in snapshot) message[key] = snapshot[key];
+    enqueue(message);
+  }
+
+  // 根节点发现顺序见文件头注释；组件（有 $root）与 Node（有 $children）都接受
+  function findRootNode() {
+    var provided = window.CITRINE_DEVTOOLS_ROOT;
+    if (provided) {
+      if (typeof provided.$children === "function") return provided; // 已是 Node
+      if (typeof provided.$root === "function") return provided.$root(); // 组件实例
+      return null;
+    }
+    try {
+      var renderer = Citrine.$renderer();
+      if (renderer) {
+        // beryl 入口：渲染器暴露 root_node 方法（Opal 侧 respond_to? 判存在，判不到则鸭子类型）
+        if (typeof renderer.$root_node === "function" &&
+            (!renderer.$respond_to || renderer.$respond_to("root_node"))) {
+          return renderer.$root_node();
+        }
+        // Canvas 渲染器：@root 实例变量
+        var root = renderer.$instance_variable_get("@root");
+        if (root) return root;
+      }
+    } catch (e) { /* 无渲染器或未挂载 */ }
+    return null;
+  }
+
+  // ── 主循环 ────────────────────────────────────────────
+
+  setInterval(collect, COLLECT_INTERVAL_MS);
+})();

data/lib/citrine-devtools/panel.html

@@ -0,0 +1,127 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<title>Citrine DevTools · v1</title>
+<style>
+  /* 暗色 token 参照 Emerald desktop.html（与其 theme.rb 调色板同源） */
+  :root { --bg: #0b0e14; --panel: #11151f; --panel2: #151b28; --line: #232b3b;
+          --fg: #c9d4e6; --dim: #7d8aa5; --accent: #4f8cff;
+          --ok: #3fb950; --err: #f85149; }
+  * { box-sizing: border-box; scrollbar-width: thin; scrollbar-color: #2a3348 transparent; }
+  ::-webkit-scrollbar { width: 8px; height: 8px; }
+  ::-webkit-scrollbar-track { background: transparent; }
+  ::-webkit-scrollbar-thumb { background: #2a3348; border-radius: 4px; }
+  body { margin: 0; background: var(--bg); color: var(--fg); height: 100vh;
+         display: flex; flex-direction: column; overflow: hidden;
+         font: 12px/1.5 ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace; }
+  button { background: var(--panel2); color: var(--fg); border: 1px solid var(--line);
+           border-radius: 6px; padding: 2px 10px; cursor: pointer; font: inherit; }
+  button:hover { border-color: var(--accent); }
+
+  /* 顶部标题栏：标题 + 连接状态点 + 刷新 */
+  #topbar { display: flex; align-items: center; gap: 8px; padding: 6px 10px;
+            background: var(--panel2); border-bottom: 1px solid var(--line); }
+  #topbar .title { font-weight: 600; }
+  #status { display: flex; align-items: center; gap: 5px; color: var(--dim); }
+  .dot { width: 8px; height: 8px; border-radius: 50%; background: var(--err); display: inline-block; }
+  .dot.on { background: var(--ok); }
+  #refresh { margin-left: auto; }
+
+  /* 标签页 */
+  #tabs { display: flex; gap: 2px; padding: 0 6px; background: var(--panel);
+          border-bottom: 1px solid var(--line); }
+  .tab { background: none; border: none; border-bottom: 2px solid transparent; border-radius: 0;
+         color: var(--dim); padding: 5px 10px; cursor: pointer; font: inherit; }
+  .tab:hover { color: var(--fg); }
+  .tab.active { color: var(--fg); border-bottom-color: var(--accent); }
+
+  main { flex: 1; overflow: auto; }
+
+  /* 组件树：缩进列表 */
+  .tree-line { padding: 2px 8px; white-space: nowrap; }
+  .tree-line:hover { background: var(--panel2); }
+  .empty { color: var(--dim); padding: 8px 10px; }
+
+  /* 信号列表 */
+  table { width: 100%; border-collapse: collapse; }
+  th { text-align: left; font-weight: normal; color: var(--dim); padding: 4px 8px;
+       border-bottom: 1px solid var(--line); background: var(--bg);
+       position: sticky; top: 0; }
+  td { padding: 2px 8px; border-bottom: 1px solid rgba(35, 43, 59, .5); white-space: nowrap; }
+  td.val { max-width: 260px; overflow: hidden; text-overflow: ellipsis; }
+
+  /* 依赖图：canvas 渲染区占满标签页剩余空间 */
+  #view-graph { height: 100%; }
+  #graph { width: 100%; height: 100%; }
+
+  /* 值变化行内闪烁（0.6s） */
+  @keyframes flash { from { background: rgba(79, 140, 255, .28); } to { background: transparent; } }
+  .flash { animation: flash .6s ease-out; }
+
+  /* Inspector 详情条（选中信号后出现） */
+  #inspector { display: flex; align-items: center; gap: 6px; padding: 5px 10px;
+               background: var(--panel2); border-bottom: 1px solid var(--line); }
+  #inspector[hidden] { display: none; }
+  #inspector input { background: var(--bg); color: var(--fg); border: 1px solid var(--line);
+                     border-radius: 6px; padding: 2px 8px; font: inherit; width: 200px; }
+  #inspector input:focus { outline: none; border-color: var(--accent); }
+  #inspector-status.ok { color: var(--ok); }
+  #inspector-status.err { color: var(--err); }
+  #inspector-status.dim { color: var(--dim); }
+  tr.selected td { background: rgba(79, 140, 255, .12); }
+
+  /* Timeline：纵向时间轴（最新在上） */
+  #view-timeline { height: 100%; }
+  #timeline { height: 100%; overflow: auto; padding: 4px 0; }
+  .tl-row { display: flex; gap: 8px; padding: 1px 10px; white-space: nowrap; align-items: baseline; }
+  .tl-row:hover { background: var(--panel2); }
+  .tl-time { color: var(--dim); }
+  .tl-chip { flex: none; min-width: 64px; text-align: center; border-radius: 8px;
+             padding: 0 8px; font-size: 11px; border: 1px solid var(--line); }
+  .tl-chip-event { color: var(--accent); border-color: var(--accent); }
+  .tl-chip-flush { color: var(--ok); border-color: var(--ok); }
+  .tl-chip-signal { color: var(--fg); }
+  .tl-chip-other { color: var(--dim); }
+  .tl-row.tl-event { cursor: pointer; }
+  .tl-row.linked { background: rgba(79, 140, 255, .18); } /* event 点击关联高亮的 flush 行 */
+</style>
+</head>
+<body>
+  <header id="topbar">
+    <span class="title">Citrine DevTools · v1</span>
+    <span id="status"><span id="dot" class="dot"></span><span id="status-text">未连接</span></span>
+    <button id="refresh" type="button">刷新</button>
+  </header>
+  <nav id="tabs">
+    <button class="tab active" data-tab="tree" type="button">组件树</button>
+    <button class="tab" data-tab="signals" type="button">信号列表</button>
+    <button class="tab" data-tab="graph" type="button">依赖图</button>
+    <button class="tab" data-tab="timeline" type="button">Timeline</button>
+  </nav>
+  <main>
+    <section id="view-tree"><div id="tree"></div></section>
+    <section id="view-signals" hidden>
+      <div id="inspector" hidden>
+        <span>选中 <b id="inspector-sig">#----</b></span>
+        <span id="inspector-value" class="val"></span>
+        <input id="inspector-input" type="text" spellcheck="false"
+               placeholder="新值：数字/布尔/null/JSON/裸字符串">
+        <button id="inspector-write" type="button">写入</button>
+        <button id="inspector-rerun" type="button">force_rerun</button>
+        <span id="inspector-status"></span>
+      </div>
+      <table>
+        <thead>
+          <tr><th>sig</th><th>当前值</th><th>写入次数</th><th>最近写入</th><th>订阅数</th><th>runs</th></tr>
+        </thead>
+        <tbody id="signals-body"></tbody>
+      </table>
+    </section>
+    <section id="view-graph" hidden><div id="graph"></div></section>
+    <section id="view-timeline" hidden><div id="timeline"></div></section>
+  </main>
+  <script src="/vendor/cytoscape.min.js"></script>
+  <script src="/panel.js"></script>
+</body>
+</html>