@tracer-kit/browser

@tracer-kit/browser

兼容 Vue 3.2 及以上版本（不含 Vue 4）。

npm install @tracer-kit/browser vue

Browser SDK 是页面侧完整 Tracer 入口。它在运行时统一接收数据库、公钥、启用开关和 common，组合 @tracer-kit/encrypted-storage 与 @tracer-kit/domain。

flowchart LR
  App[Vue 3 业务应用] --> SDK[Browser SDK]
  Metadata[Vite Build Metadata] --> SDK
  SDK --> Domain[Tracer Domain]
  SDK --> Writer[Encrypted Storage Writer]
  Domain --> Writer
  Writer --> DB[(IndexedDB 密文)]
  SDK --> Capability[运行时 capability]
  Capability --> DevTools[Tracer DevTools]

直接创建

import { createTracer } from '@tracer-kit/browser';

const tracer = await createTracer({
  // 页面只配置 RSA 公钥；私钥只在 DevTools 扩展运行时导入。
  publicKey,
  // 可按宿主需要覆盖容量；省略时使用 Core Storage 默认值。
  capacity: {
    configuredMaxBytes: 20 * 1024 * 1024,
    quotaReserveBytes: 5 * 1024 * 1024,
    lowWatermarkRatio: 0.9,
  },
  // databaseName 省略时为 tracer-storage，enabled 省略时为 true。
  common: {
    // 普通值在创建时固化。
    appName: 'customer-web',
    // 函数在每次 log() 调用时求值。
    route: () => location.pathname,
  },
});

// log() 同步且不会把 Tracer 内部错误抛给业务调用方。
tracer.log('页面加载完成', { resourceId: '42' });

Vue 3 插件

Vue 3 应用可直接安装插件，组件通过 useTracer() 获取稳定 facade：

Vue 相关的 Plugin、依赖注入、composable、响应式状态和卸载/HMR 生命周期集中维护在 src/vue-integration.ts。

import { createTracerPlugin } from '@tracer-kit/browser';

const tracerPlugin = createTracerPlugin({
  // 所有 runtime 配置只写在这里，不在 Vite Plugin 中重复。
  publicKey,
  databaseName: 'customer-tracer',
  common: { route: () => location.pathname },
  // HMR dispose 时自动销毁旧实例。
  hot: import.meta.hot,
});
app.use(tracerPlugin);

组件通过 useTracer() 获得 log()、destroy() 和只读响应式 status。status 依次使用 initializing、ready、failed、destroyed 表示初始化与生命周期状态，页面无需再次接收或持有 TracerPlugin 才能展示状态。

插件在应用卸载或 HMR dispose 时销毁实例，pagehide 不会销毁日志能力。

普通 common 值在创建时固化，函数值在每次日志调用时求值。数据库默认名为 tracer-storage，enabled 默认 true。

初始化成功后 SDK 发布 tracer capability meta，并通过 tracer:runtime-ready 事件通知扩展。生产诊断默认缓冲最近 20 条错误，收到协议为 1 的 extension-ready 后按 FIFO 输出；显式 onError 始终调用。log() 同步且永不向业务抛出内部错误，pagehide 不会销毁实例。

只需要计算 capability 公钥指纹、且不能引入 Browser SDK 的 Vite 虚拟模块时，使用独立子路径：

// 该子路径不加载宿主专用的 Vite 虚拟模块，CLI 和扩展可安全复用。
import { fingerprintPublicKey } from '@tracer-kit/browser/capability';

该兼容出口实际复用可发布的 @tracer-kit/key-fingerprint，Browser 与扩展不各自复制指纹算法。

测试与维护

• test/browser.test.ts：组合、单例、配置冲突和销毁。
• test/vue-integration.test.ts：Vue 注入、响应式状态、卸载与 HMR 生命周期。
• test/capability.test.ts：运行时 capability 与指纹。

修改公共配置、生命周期或 capability 时，必须同步本 README、相关测试与 docs/modules/host-adapter-vite.md。