modelstage 0.0.0-stage → 0.5.28

package/src/web/debug/drag.js

@@ -0,0 +1,369 @@
+import * as uiState from '../app/ui-state.js';
+
+// debug/drag.js —— 调试日志浮层的「可拖动 + 记住位置」
+//
+// 只做移动，不做缩放（缩放手柄不在需求内）。
+//
+// 六条设计要点：
+//   1. 节流：pointermove 只累积目标坐标，真正写样式在 rAF 里做一次
+//      （结构与 render/interaction.js 的 createPanScheduler 一致：累积 → 单帧 flush → flushNow）。
+//   2. 跟手：拖动期间写 `transform: translate3d()`（只合成、不触发布局），
+//      松手时才把最终位置落到 left/top。若每帧都改 left/top，浏览器要重排整页
+//      （本页有 1920×1080 的舞台画布），手感会明显发滞。
+//   3. 记忆：pointerup 时把最终 left/top 写 localStorage；下次挂载时恢复。
+//      没有记录就保持 CSS 里写死的默认位置（right/bottom），不改默认外观。
+//   4. 边界：按**当前形态**尺寸夹取（收起=胶囊尺寸，展开=面板尺寸），整块留在视口内。
+//      不能拿展开尺寸去夹胶囊 —— 那会让胶囊只能在右上角一小块区域活动。
+//      拖出屏幕找不回来是最烦的坏状态（这个浮层没有 reset 入口）。
+//   5. 多手柄：展开态拖标题栏、收起态拖胶囊（收起后标题栏高度为 0，只剩胶囊可抓）。
+//   6. 点击/拖拽区分：位移 ≤ DRAG_THRESHOLD 视为点击，不开始拖动、不 preventDefault，
+//      否则点一下胶囊想展开会变成"轻微抖动但没反应"。
+//   7. 展开方向自适应：面板永远朝视口中心展开（靠右向左长、靠下向上长）。
+//      写死方向必然有一半位置放不下（胶囊在右下角时向下展开直接出屏）。
+//      存盘只存**锚点**（收起态胶囊盒子的位置），展开位置由锚点+方向算出。
+
+/**
+ * 位置存储统一走 app/ui-state 工厂（偏好键的 debug.panelPos 段）。
+ * 本文件不直接读写存储 —— 不再有独立的键常量与 storageKey 参数。
+ */
+
+/** 超过这个位移（px）才算拖动；之内视为点击/手抖 */
+const DRAG_THRESHOLD = 4;
+
+/** 拖动时不该被当作拖拽起点的元素（标题栏里的按钮/下拉等交互控件） */
+const NO_DRAG_SELECTOR = 'button, select, input, textarea, option, a';
+
+/**
+ * 读保存的位置。
+ * @param {string} [key] 存储键
+ * @returns {{left:number, top:number}|null} 无记录或数据损坏时返回 null
+ */
+export function readSavedPos() {
+  // S3：唯一真相源 = 工厂（旧键由工厂在启动时迁移，这里不再直读 localStorage）
+  try { return uiState.getPanelPos(); } catch { return null; }
+}
+
+/**
+ * 把坐标夹到"面板不出视口"的范围内（标题栏因此始终可见）。
+ * @param {{left:number, top:number}} pos 期望位置
+ * @param {{w:number, h:number, vw:number, vh:number}} box 面板宽高与视口尺寸
+ * @returns {{left:number, top:number}} 夹取后的位置
+ */
+export function clampPos(pos, box) {
+  const maxLeft = Math.max(0, box.vw - box.w);
+  const maxTop = Math.max(0, box.vh - box.h);
+  return {
+    left: Math.min(Math.max(0, pos.left), maxLeft),
+    top: Math.min(Math.max(0, pos.top), maxTop),
+  };
+}
+
+/**
+ * 单帧只写一次样式的调度器。
+ * @param {(pos:{left:number,top:number}) => void} write 真正的写入
+ * @returns {{queue:Function, flushNow:Function, stats:Function, resetStats:Function}} 调度器
+ */
+function createPosScheduler(write) {
+  let pending = null;
+  let frameId = 0;
+  let writes = 0;
+  /** 冲刷本帧累积的目标位置（同一帧内多次 queue 只写一次） */
+  function flush() {
+    frameId = 0;
+    if (!pending) return;
+    const pos = pending;
+    pending = null;
+    writes += 1;
+    write(pos);
+  }
+  return {
+    queue(pos) { pending = pos; if (!frameId) frameId = requestAnimationFrame(flush); },
+    flushNow() { if (frameId) { cancelAnimationFrame(frameId); flush(); } },
+    stats: () => ({ writes }),
+    resetStats: () => { writes = 0; },
+  };
+}
+
+/**
+ * 给面板装上拖动能力（支持多个手柄：标题栏 + 收起态胶囊）。
+ * @param {{root: HTMLElement, head: HTMLElement|HTMLElement[]}} opts
+ *   head：单个元素或元素数组；数组里为空的值会被过滤掉（调用方不必自己判空）
+ * @returns {{restore:Function, dispose:Function, clampIntoView:Function, stats:Function, resetStats:Function}} 句柄
+ */
+export function createPanelDrag({ root, head }) {
+  const handles = (Array.isArray(head) ? head : [head]).filter(Boolean);
+  let moves = 0;
+  let dragFrom = null;
+  /** 拖动开始时缓存的尺寸/视口：拖动过程中面板尺寸不变，逐帧读 offsetWidth 会强制重排 */
+  let dragBox = null;
+  /** 拖动起点的 left/top（transform 是相对它算的） */
+  let basePos = null;
+
+  /** 读一个尺寸常量（px）；取不到就用兜底值 */
+  function cssPx(name, fallback) {
+    try {
+      const v = parseFloat(getComputedStyle(root).getPropertyValue(name));
+      if (Number.isFinite(v)) return v;
+    } catch { /* 忽略 */ }
+    return fallback;
+  }
+
+  /** 边框厚度（常量是内容尺寸，盒子还要加边框；不加会差 2px 冒到视口外） */
+  function borderBox() {
+    try {
+      const cs = getComputedStyle(root);
+      return {
+        x: (parseFloat(cs.borderLeftWidth) || 0) + (parseFloat(cs.borderRightWidth) || 0),
+        y: (parseFloat(cs.borderTopWidth) || 0) + (parseFloat(cs.borderBottomWidth) || 0),
+      };
+    } catch { return { x: 0, y: 0 }; }
+  }
+
+  /** 当前形态（以 root 的 data-collapsed 为准） */
+  function currentForm() {
+    return root.dataset.collapsed === 'true' ? 'collapsed' : 'expanded';
+  }
+
+  /**
+   * 某个形态的盒子尺寸与视口。
+   *
+   * **按形态取尺寸**（不是永远按展开尺寸）：展开方向自适应后，从任何位置都能找到
+   *   放得下的朝向 ⇒ 不需要"提前预留展开空间"，拿展开尺寸去夹胶囊只会把可拖范围
+   *   压成右上角一小块。
+   *
+   * **不读 offsetWidth/offsetHeight**：宽度有 220ms 过渡，形态切换瞬间读到的是中间值。
+   *   统一从 CSS 常量算，随时可读且与目标尺寸一致。
+   * @param {'collapsed'|'expanded'} form
+   */
+  function boxFor(form) {
+    const b = borderBox();
+    if (form === 'collapsed') {
+      return {
+        w: cssPx('--dbg-pill-w', root.offsetWidth) + b.x,
+        h: cssPx('--dbg-pill-hbox', root.offsetHeight) + b.y,
+        vw: window.innerWidth, vh: window.innerHeight,
+      };
+    }
+    return {
+      w: cssPx('--dbg-w', root.offsetWidth) + b.x,
+      h: cssPx('--dbg-h', root.offsetHeight) + b.y,
+      vw: window.innerWidth, vh: window.innerHeight,
+    };
+  }
+
+  /** 面板当前的 left/top（未定位过时按实际渲染位置换算） */
+  function currentPos() {
+    const r = root.getBoundingClientRect();
+    return { left: r.left, top: r.top };
+  }
+
+  /** 记一次写入次数（节流证据：moves vs writes） */
+  function countWrite() {
+    root.dataset.dragWrites = String(Number(root.dataset.dragWrites || 0) + 1);
+  }
+
+  /** 把位置落到 left/top（松手/恢复/窗口变化时用；会触发布局，所以不在拖动中调用） */
+  function writeStyle(pos, box) {
+    const next = clampPos(pos, box || boxFor(currentForm()));
+    root.style.transform = '';
+    root.style.left = `${Math.round(next.left)}px`;
+    root.style.top = `${Math.round(next.top)}px`;
+    // 用 left/top 定位后必须解除 right/bottom，否则两套定位同时生效会打架
+    root.style.right = 'auto';
+    root.style.bottom = 'auto';
+    root.dataset.dragLeft = String(Math.round(next.left));
+    root.dataset.dragTop = String(Math.round(next.top));
+    countWrite();
+    return next;
+  }
+
+  /** 拖动中只写 transform（合成层，不重排）——这是"跟手"的关键 */
+  function writeTransform(pos, box) {
+    const next = clampPos(pos, box || dragBox || boxFor(currentForm()));
+    const dx = next.left - (basePos ? basePos.left : next.left);
+    const dy = next.top - (basePos ? basePos.top : next.top);
+    root.style.transform = `translate3d(${Math.round(dx)}px, ${Math.round(dy)}px, 0)`;
+    root.dataset.dragLeft = String(Math.round(next.left));
+    root.dataset.dragTop = String(Math.round(next.top));
+    countWrite();
+    return next;
+  }
+
+  /** 当前写入策略：拖动中用 transform，其余时候写 left/top */
+  let writer = writeStyle;
+  const scheduler = createPosScheduler((pos) => writer(pos));
+
+  /** 当前展开方向（由最近一次展开决定） */
+  function openDir() {
+    const dir = String(root.dataset.openDir || 'up-left');
+    return { up: dir.includes('up'), left: dir.includes('left') };
+  }
+
+  /**
+   * 把"当前形态的盒子位置"换算成**锚点**（收起态胶囊盒子的位置）。
+   * 展开态要按方向反算：向左长 ⇒ 胶囊贴在面板右边缘；向上长 ⇒ 贴在面板下边缘。
+   * @param {{left:number, top:number}} pos
+   * @param {'collapsed'|'expanded'} form
+   */
+  function toAnchor(pos, form) {
+    if (form === 'collapsed') return { left: pos.left, top: pos.top };
+    const pBox = boxFor('expanded');
+    const cBox = boxFor('collapsed');
+    const dir = openDir();
+    return {
+      left: dir.left ? pos.left + pBox.w - cBox.w : pos.left,
+      top: dir.up ? pos.top + pBox.h - cBox.h : pos.top,
+    };
+  }
+
+  /** 落盘：只存锚点（走工厂的同一条写路径） */
+  function persistPos(anchor) {
+    try { uiState.setPanelPos({ left: anchor.left, top: anchor.top }); } catch { /* 隐私模式忽略 */ }
+  }
+
+  /** 应用一次位置（当前形态）并可选落盘 */
+  function applyPos(pos, { persist = false } = {}) {
+    const next = writeStyle(pos);
+    if (persist) persistPos(toAnchor(next, currentForm()));
+    return next;
+  }
+
+  /**
+   * 切到某个形态并重新定位（**每次展开都重新判断方向**：用户可能拖过位置再展开）。
+   *
+   * 方向自适应让面板永远朝视口中心长 ⇒ 从任何位置展开都放得下。
+   * @param {'collapsed'|'expanded'} form 目标形态
+   * @returns {{left:number, top:number}} 落到的位置
+   */
+  function placeForForm(form) {
+    const saved = readSavedPos();
+    // 锚点来源：有记录就用记录；否则用当前盒子按当前方向反算（首次运行）
+    const anchor = saved || toAnchor(currentPos(), currentForm());
+    const cBox = boxFor('collapsed');
+    const pBox = boxFor('expanded');
+
+    if (form === 'collapsed') {
+      // 收起：胶囊盒子的 left/top 直接就是锚点
+      return writeStyle({ left: anchor.left, top: anchor.top }, cBox);
+    }
+
+    // 展开：按锚点中心相对视口中心的象限定方向
+    const cx = anchor.left + cBox.w / 2;
+    const cy = anchor.top + cBox.h / 2;
+    const openLeft = cx >= window.innerWidth / 2;
+    const openUp = cy >= window.innerHeight / 2;
+    root.dataset.openDir = `${openUp ? 'up' : 'down'}-${openLeft ? 'left' : 'right'}`;
+
+    const anchorX = openLeft ? anchor.left + cBox.w : anchor.left;
+    const anchorY = openUp ? anchor.top + cBox.h : anchor.top;
+    const wantLeft = openLeft ? anchorX - pBox.w : anchorX;
+    const wantTop = openUp ? anchorY - pBox.h : anchorY;
+    // 兜底：视口比面板还小的极端情况贴左上，允许溢出右/下
+    const safeLeft = Math.max(0, Math.min(wantLeft, Math.max(0, window.innerWidth - pBox.w)));
+    const safeTop = Math.max(0, Math.min(wantTop, Math.max(0, window.innerHeight - pBox.h)));
+    return writeStyle({ left: safeLeft, top: safeTop }, pBox);
+  }
+
+  /** 视口变化时重新夹一次，避免窗口变小后面板被挤出屏幕 */
+  function onResize() {
+    if (root.hidden || dragFrom) return;
+    applyPos(currentPos());
+  }
+
+  /**
+   * 按下：只记录起点，**先不进入拖动**。
+   *   进入拖动由第一次超过阈值的 pointermove 触发 —— 这样轻点胶囊仍然是一次正常 click。
+   * @param {PointerEvent} ev
+   */
+  function onPointerDown(ev) {
+    if (ev.button !== 0 && ev.pointerType === 'mouse') return;
+    // 手柄本身可能就是按钮（收起态胶囊）：它自己要能拖，所以对它跳过"按钮不拖"的过滤
+    const selfHandle = ev.currentTarget && ev.currentTarget.dataset
+      && ev.currentTarget.dataset.dragHandle === 'self';
+    if (!selfHandle && ev.target && ev.target.closest && ev.target.closest(NO_DRAG_SELECTOR)) return;
+    basePos = currentPos();
+    dragBox = boxFor(currentForm());                 // 只在按下时读一次尺寸
+    dragFrom = { px: ev.clientX, py: ev.clientY, id: ev.pointerId, active: false };
+    try { ev.currentTarget.setPointerCapture(ev.pointerId); } catch { /* 老浏览器忽略 */ }
+  }
+
+  function onPointerMove(ev) {
+    if (!dragFrom || ev.pointerId !== dragFrom.id) return;
+    moves += 1;                          // 计数不过阈值也记（节流门禁按真实 move 次数核对）
+    if (!dragFrom.active) {
+      const dist = Math.abs(ev.clientX - dragFrom.px) + Math.abs(ev.clientY - dragFrom.py);
+      if (dist <= DRAG_THRESHOLD) return; // 还在"手抖/点击"范围
+      dragFrom.active = true;
+      writer = writeTransform;           // 拖动期间走 transform
+      root.classList.add('is-dragging');
+      if (ev.cancelable) ev.preventDefault();
+    }
+    // 只累积目标坐标：真正的写入交给 rAF（同一帧多次 move 只写一次）
+    scheduler.queue({
+      left: basePos.left + (ev.clientX - dragFrom.px),
+      top: basePos.top + (ev.clientY - dragFrom.py),
+    });
+    root.dataset.dragMoves = String(moves);
+  }
+
+  function endDrag() {
+    if (!dragFrom) return;
+    const wasActive = dragFrom.active;
+    dragFrom = null;
+    root.classList.remove('is-dragging');
+    // 没超过阈值 ⇒ 这是一次点击（例如点胶囊展开）：不写位置、不落盘，
+    //   且因为全程没 preventDefault，button 的 click 会照常触发。
+    if (!wasActive) { writer = writeStyle; return; }
+    scheduler.flushNow();               // 最后一帧不能丢
+    writer = writeStyle;                // 松手后回到 left/top 真值
+    // 用 transform 期间的目标位置在 dataset 里；按它提交，视觉上不跳动
+    const left = Number(root.dataset.dragLeft);
+    const top = Number(root.dataset.dragTop);
+    if (Number.isFinite(left) && Number.isFinite(top)) applyPos({ left, top }, { persist: true });
+    else applyPos(currentPos(), { persist: true });
+  }
+
+  for (const h of handles) {
+    h.addEventListener('pointerdown', onPointerDown);
+    h.addEventListener('pointermove', onPointerMove);
+    h.addEventListener('pointerup', endDrag);
+    h.addEventListener('pointercancel', endDrag);
+  }
+  window.addEventListener('resize', onResize);
+
+  return {
+    /** 按存储的锚点恢复位置（当前形态由 root 的 data-collapsed 决定；展开会重判方向） */
+    restore() {
+      return placeForForm(currentForm());
+    },
+    /** 形态切换后重新定位（同时重新判断展开方向） */
+    applyForm(form) {
+      return placeForForm(form);
+    },
+    /** 窗口缩放等场景下重新夹一次，避免撑出视口 */
+    clampIntoView() {
+      if (root.hidden || dragFrom) return null;
+      return applyPos(currentPos());
+    },
+    dispose() {
+      for (const h of handles) {
+        h.removeEventListener('pointerdown', onPointerDown);
+        h.removeEventListener('pointermove', onPointerMove);
+        h.removeEventListener('pointerup', endDrag);
+        h.removeEventListener('pointercancel', endDrag);
+      }
+      window.removeEventListener('resize', onResize);
+      scheduler.flushNow();
+    },
+    /** 节流证据：move 次数 vs 样式写入次数 */
+    stats: () => ({
+      moves, ...scheduler.stats(),
+      left: root.dataset.dragLeft || null,
+      top: root.dataset.dragTop || null,
+      openDir: root.dataset.openDir || null,
+      // 落盘存的是"锚点"（收起态胶囊盒子的位置）；这里把它换算出来供门禁核对
+      anchor: toAnchor(currentPos(), currentForm()),
+    }),
+    resetStats: () => { moves = 0; scheduler.resetStats(); },
+  };
+}

package/src/web/debug/log.js

@@ -0,0 +1,320 @@
+// debug-log.js —— 调试日志核心（无 DOM 依赖）
+//
+// 职责：环形缓冲、分级、订阅、开关。面板（debug-panel.js）只消费这里产出的条目。
+//
+// 单一真相源（docs/设计/调试日志面板.md）：
+//   条目**只从 diag 进来** —— log() 不再直接写缓冲，而是把事件交给 window.__DIAG__，
+//   由面板注册的 sink 回调 addExternal() 写回缓冲。这样"应用事件 / 运行时异常 / 网络失败"
+//   走的是同一条管道：把 sink 注册注释掉，三类会一起消失（可反向验证"真的接通了"）。
+//   没有 diag（独立使用本模块/单测）时退回直接写缓冲，行为与旧版一致。
+//
+// 契约（docs/README.md 第二十二节）：
+//   const log = createDebugLog({ capacity: 500 });
+//   log.log(tag, message, { level = 'info', data } = {});
+//   log.entries();      // [{ ts, level, tag, message }] 快照，按时间正序
+//   log.subscribe(fn);  // 新条目回调，返回取消订阅函数
+//   log.clear(); log.setEnabled(bool); log.getEnabled();
+//
+// 硬规则（都在代码里落实）：
+//   1. 默认开启；关闭时 log() 立即返回、不产生任何对象；
+//   2. 单条 message ≤ 300 字，超出截断并注明；
+//   3. 环形缓冲默认 500 条，超出丢最旧；
+//   4. 日志绝不抛异常、不阻塞渲染（订阅者异常各自隔离）。
+//
+// 结构：本文件按职责拆成小函数（每函数 ≤50 行）：容量规整 / 文本化 / 组装正文 /
+//   环形缓冲 / 订阅总线 / 编排，四者互不重叠。
+
+import { sanitizeUrl } from '../infra/diag.js';
+
+/** 允许的 tag（大写）。调用方只能从这里取，不自造。 */
+export const DEBUG_TAGS = Object.freeze([
+  'RUNTIME', 'LOADER', 'RENDERER', 'CAMERA', 'ANIMATION', 'SKIN', 'FILTER',
+  'PMA', 'ROSTER', 'PANEL', 'TRANSPORT', 'PERSIST', 'CONFIG',
+]);
+
+/** 允许的级别 */
+// debug 是最低档：交互遥测（缩放/拖动）走这一档，默认过滤下不显示，切到低档才看
+export const DEBUG_LEVELS = Object.freeze(['debug', 'info', 'warn', 'error']);
+
+/**
+ * 条目来源（面板据此加前缀，区分"应用自己说的"和"探针抓到的"）：
+ *   app       应用事件（加载/切换/设置变更）
+ *   error     运行时异常（window.onerror / unhandledrejection / console.error）
+ *   net       网络失败（HTTP ≥400 / 请求失败）
+ *   resource  资源加载失败
+ *   其它      探针内部来源（diag/stage/console/motion…）原样透传
+ */
+export const DEBUG_SOURCES = Object.freeze(['app', 'error', 'net', 'resource', 'diag', 'stage', 'console', 'motion', 'window']);
+
+/** 来源归一：未知来源归到 app，避免面板出现奇怪前缀 */
+function normalizeSource(src) {
+  const v = String(src || '').toLowerCase();
+  return DEBUG_SOURCES.includes(v) ? v : (v ? v : 'app');
+}
+
+/** 敏感键：data 里这些键的值一律打码（与 infra/diag.js 的 URL 脱敏同一套口径） */
+const SENSITIVE_KEY_RE = /^(token|access_token|refresh_token|id_token|api_?key|apikey|secret|password|passwd|pwd|auth|authorization|session|sessionid|sid|code|sign|signature|sig)$/i;
+
+/** 递归深度上限：日志对象可能很深（含 DOM/PIXI 引用），到上限就截断成占位符 */
+const SANITIZE_MAX_DEPTH = 6;
+/** 单个对象/数组最多看多少个成员（避免大对象被整份遍历） */
+const SANITIZE_MAX_KEYS = 40;
+/** 深度截断占位符 */
+const DEPTH_MARK = '[depth-limit]';
+/** 循环引用占位符 */
+const CIRCULAR_MARK = '[circular]';
+
+/**
+ * 字符串脱敏：**凡带 query 的字符串一律按 URL 清洗**（不看有没有 scheme）。
+ *
+ * 为什么不能只看 ^https?://：日志里的地址大多是相对路径（/api/x?token=…），
+ *   只认绝对地址等于把这类凭据全放过。清洗实现复用 infra/diag.js 的 sanitizeUrl
+ *   （网络采集那条路径已经用它处理过相对/绝对两种形态）。
+ * @param {string} value
+ * @returns {string}
+ */
+function sanitizeString(value) {
+  if (!value.includes('?') || !value.includes('=')) return value;
+  try {
+    return sanitizeUrl(value);
+  } catch {
+    return value.replace(/([?&][^=&]*(?:token|key|secret|password|code|sign)[^=&]*=)[^&]*/gi, '$1***');
+  }
+}
+
+/**
+ * 递归脱敏一个值（对象/数组都进）。
+ * @param {*} value
+ * @param {number} depth 当前层数（0 = data 本身）
+ * @param {WeakSet<object>} seen 已访问对象（循环引用保护）
+ * @returns {*}
+ */
+function sanitizeValue(value, depth, seen) {
+  if (value === null || value === undefined) return value;
+  const type = typeof value;
+  if (type === 'string') return sanitizeString(value);
+  if (type !== 'object') return value;
+  if (depth >= SANITIZE_MAX_DEPTH) return DEPTH_MARK;
+  if (seen.has(value)) return CIRCULAR_MARK;
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return value.slice(0, SANITIZE_MAX_KEYS).map((item) => sanitizeValue(item, depth + 1, seen));
+    }
+    const out = {};
+    for (const key of Object.keys(value).slice(0, SANITIZE_MAX_KEYS)) {
+      out[key] = SENSITIVE_KEY_RE.test(key) ? '***' : sanitizeValue(value[key], depth + 1, seen);
+    }
+    return out;
+  } catch {
+    return null; // 抛异常的取值器（getter/DOM）整体放弃，不影响其它条目
+  }
+}
+
+/**
+ * data 脱敏（对外唯一入口）：敏感键整体打码 + 递归清洗 URL 里的凭据。
+ *
+ * 为什么要递归：日志里的凭据不只出现在顶层，常见形态是 { req: { url: '…?token=…' } }；
+ *   只洗一层等于只堵住最显眼的那条路。深度与循环都有上限，脱敏本身不能成为风险。
+ * @param {*} data
+ * @returns {*}
+ */
+function sanitizeData(data) {
+  if (data === null || data === undefined) return null;
+  try {
+    return sanitizeValue(data, 0, new WeakSet());
+  } catch {
+    return null;
+  }
+}
+
+/** 单条正文上限（字符）与默认容量 */
+const MESSAGE_MAX = 300;
+const CAPACITY_DEFAULT = 500;
+
+/** 容量规整：非正整数一律回落到默认值 */
+function normalizeCapacity(value) {
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 1 ? Math.floor(n) : CAPACITY_DEFAULT;
+}
+
+/** 任意输入压成一行文本：字符串原样，其余尝试 JSON，失败再 String() */
+function toText(raw) {
+  if (typeof raw === 'string') return raw;
+  if (raw === null || raw === undefined) return '';
+  try {
+    return JSON.stringify(raw);
+  } catch {
+    try { return String(raw); } catch { return '[unserializable]'; }
+  }
+}
+
+/**
+ * 组装正文：message +（可选）data 以「 · {json}」追加，整体受 300 字上限约束。
+ * 为什么把 data 并进 message：条目结构固定为 { ts, level, tag, message }，
+ *   面板与外部检查代码都按这 4 个键读，多一个键会让两端解析口径不一致。
+ */
+function buildMessage(message) {
+  // 只保留"发生了什么"这句话本身：级别是自有属性（level 字段 + 图标），
+  // 结构化细节是自有属性（data 字段，面板悬停/查看用），都不再拼进正文。
+  const full = toText(message);
+  if (full.length <= MESSAGE_MAX) return full;
+  const note = `…(截断 ${full.length - MESSAGE_MAX} 字)`;
+  return full.slice(0, Math.max(0, MESSAGE_MAX - note.length)) + note;
+}
+
+/**
+ * 环形缓冲：push 到末尾，超出容量从头丢最旧。
+ * @param {number} capacity
+ */
+function createBuffer(capacity) {
+  const items = [];
+  return {
+    /** 追加一条；返回是否发生了淘汰 */
+    add(entry) {
+      items.push(entry);
+      if (items.length <= capacity) return false;
+      items.splice(0, items.length - capacity);
+      return true;
+    },
+    /** 快照（浅拷贝，外部改动不影响内部） */
+    snapshot() { return items.slice(); },
+    /** 清空 */
+    reset() { items.length = 0; },
+    capacity,
+  };
+}
+
+/**
+ * 订阅总线：两路互不干扰 —— 条目路（新条目 / null=已清空）与开关路（enabled 变化）。
+ * 为什么分两路：条目回调的入参约定是「条目|null」，把开关状态塞进去会污染这个约定。
+ */
+function createNotifier() {
+  const subs = new Set();
+  const stateSubs = new Set();
+  const call = (set, arg) => {
+    for (const fn of set) {
+      try { fn(arg); } catch { /* 单个订阅者出错不影响其它订阅者 */ }
+    }
+  };
+  return {
+    subscribe(fn) {
+      if (typeof fn !== 'function') return () => {};
+      subs.add(fn);
+      return () => { subs.delete(fn); };
+    },
+    onStateChange(fn) {
+      if (typeof fn !== 'function') return () => {};
+      stateSubs.add(fn);
+      return () => { stateSubs.delete(fn); };
+    },
+    emit(entry) { call(subs, entry); },
+    emitState(enabled) { call(stateSubs, enabled); },
+  };
+}
+
+/**
+ * 创建日志实例。
+ * @param {{capacity?: number}} [options]
+ */
+export function createDebugLog(options = {}) {
+  const buffer = createBuffer(normalizeCapacity(options.capacity));
+  const bus = createNotifier();
+  // 默认开启；显式传 { enabled: false } 可关闭
+  let enabled = options.enabled === undefined ? true : !!options.enabled;
+
+  /** 组装一条内部条目（唯一构造点，保证字段齐全） */
+  function makeEntry(fields) {
+    return {
+      ts: Number(fields.ts) || Date.now(),
+      level: DEBUG_LEVELS.includes(fields.level) ? fields.level : 'info',
+      tag: String(fields.tag || '').toUpperCase(),
+      message: String(fields.message || ''),
+      src: normalizeSource(fields.src),
+      event: String(fields.event || fields.tag || ''),
+      data: sanitizeData(fields.data),
+    };
+  }
+
+  /** 写缓冲并广播（**唯一入口**，不转发 —— 转发是 log() 的事，避免自激） */
+  function addExternal(fields) {
+    try {
+      const entry = makeEntry(fields || {});
+      buffer.add(entry);
+      bus.emit(entry);
+      return entry;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * 记一条日志；关闭时立即返回 undefined。
+   *
+   * 有 window.__DIAG__ 时**只交给探针**（由面板 sink 回调 addExternal 写回缓冲），
+   * 这样三类事件共享同一条管道；没有探针（独立使用/单测）时直接写缓冲。
+   */
+  function log(tag, message, opts = {}) {
+    if (!enabled) return undefined;
+    try {
+      const fields = {
+        ts: Date.now(),
+        level: opts.level,
+        tag,
+        message: buildMessage(message, opts.data),
+        src: opts.src,
+        event: opts.event || tag,
+        // 脱敏必须发生在这里（转发之前）：diag 会把它写进缓冲并 POST 给服务端，
+        // 只在 addExternal 里脱敏的话，GET /api/diag 与落盘仍是明文。
+        data: opts.data === undefined ? null : sanitizeData(opts.data),
+      };
+      const diag = typeof window !== 'undefined' ? window.__DIAG__ : null;
+      if (diag && typeof diag.event === 'function') {
+        // message 必须一起送：只送 event+data 的话，正文（如"相机 fit: bbox=…"）会在面板里丢掉，
+        //   只剩一个标签名，等于把日志变哑。
+        diag.event(fields.event, fields.data, {
+          level: fields.level, src: fields.src || 'app', tag: fields.tag, message: fields.message,
+        });
+        return fields; // 缓冲由 sink 写回；这里只回报"已上报"
+      }
+      return addExternal(fields);
+    } catch {
+      return undefined; // 日志绝不能影响业务
+    }
+  }
+
+  return {
+    log,
+    /** 外部写入（sink 专用）：不转发，避免"转发→写缓冲→再转发"的自激 */
+    addExternal,
+    entries: () => buffer.snapshot(),
+    /**
+     * 稳定导出结构（供 API/自动化断言）：{ t, level, src, event, data }。
+     * 与面板同一份缓冲，所以"API 条数 == 面板条数"是结构保证，不靠对账。
+     */
+    dump: () => buffer.snapshot().map((e) => ({
+      t: new Date(e.ts).toISOString(),
+      level: e.level,
+      src: e.src,
+      event: e.event,
+      data: e.data,
+    })),
+    subscribe: (fn) => bus.subscribe(fn),
+    clear() {
+      buffer.reset();
+      bus.emit(null);
+    },
+    setEnabled(value) {
+      const next = !!value;
+      if (next !== enabled) {
+        enabled = next;
+        bus.emitState(enabled);
+      }
+      return enabled;
+    },
+    /** 订阅开关变化（入参为新的 enabled 值），返回取消订阅函数 */
+    onEnabledChange: (fn) => bus.onStateChange(fn),
+    getEnabled: () => enabled,
+    capacity: buffer.capacity,
+  };
+}