@ereo/trace 0.1.28

package/dist/index.js

@@ -0,0 +1,1367 @@
+// @bun
+// src/noop.ts
+var NOOP_SPAN = {
+  id: "",
+  traceId: "",
+  setAttribute() {},
+  event() {},
+  end() {},
+  error() {},
+  child() {
+    return NOOP_SPAN;
+  }
+};
+
+class NoopTracer {
+  startTrace() {
+    return NOOP_SPAN;
+  }
+  startSpan() {
+    return NOOP_SPAN;
+  }
+  activeSpan() {
+    return null;
+  }
+  withSpan(_name, _layer, fn) {
+    return fn(NOOP_SPAN);
+  }
+  getTraces() {
+    return [];
+  }
+  getTrace() {
+    return;
+  }
+  subscribe() {
+    return () => {};
+  }
+  mergeClientSpans() {}
+}
+var noopTracer = new NoopTracer;
+var noopSpan = NOOP_SPAN;
+// src/span.ts
+var idCounter = 0;
+function randomHex(len) {
+  let s = "";
+  while (s.length < len) {
+    s += Math.random().toString(16).slice(2);
+  }
+  return s.slice(0, len);
+}
+function generateSpanId() {
+  idCounter++;
+  const time = Date.now().toString(16).slice(-8);
+  const counter = (idCounter & 65535).toString(16).padStart(4, "0");
+  const random = randomHex(4);
+  return `${time}${counter}${random}`;
+}
+function generateTraceId() {
+  return randomHex(32);
+}
+
+class SpanImpl {
+  id;
+  traceId;
+  _parentId;
+  _name;
+  _layer;
+  _status = "ok";
+  _startTime;
+  _endTime = 0;
+  _attributes = {};
+  _events = [];
+  _children = [];
+  _ended = false;
+  _onEnd;
+  _childFactory;
+  _onEvent;
+  constructor(traceId, parentId, name, layer, onEnd, childFactory, onEvent) {
+    this.id = generateSpanId();
+    this.traceId = traceId;
+    this._parentId = parentId;
+    this._name = name;
+    this._layer = layer;
+    this._startTime = performance.now();
+    this._onEnd = onEnd;
+    this._childFactory = childFactory;
+    this._onEvent = onEvent;
+  }
+  setAttribute(key, value) {
+    if (this._ended)
+      return;
+    this._attributes[key] = value;
+  }
+  event(name, attributes) {
+    if (this._ended)
+      return;
+    const evt = { name, time: performance.now(), attributes };
+    this._events.push(evt);
+    this._onEvent?.(this.id, evt);
+  }
+  end() {
+    if (this._ended)
+      return;
+    this._ended = true;
+    this._endTime = performance.now();
+    this._onEnd(this);
+  }
+  error(err) {
+    if (this._ended)
+      return;
+    this._status = "error";
+    if (err instanceof Error) {
+      this._attributes["error.message"] = err.message;
+      this._attributes["error.name"] = err.name;
+      if (err.stack) {
+        this._attributes["error.stack"] = err.stack.slice(0, 500);
+      }
+    } else {
+      this._attributes["error.message"] = String(err);
+    }
+  }
+  child(name, layer) {
+    const childSpan = this._childFactory(name, layer, this.id);
+    this._children.push(childSpan.id);
+    return childSpan;
+  }
+  get ended() {
+    return this._ended;
+  }
+  toData() {
+    return {
+      id: this.id,
+      traceId: this.traceId,
+      parentId: this._parentId,
+      name: this._name,
+      layer: this._layer,
+      status: this._status,
+      startTime: this._startTime,
+      endTime: this._endTime || performance.now(),
+      duration: (this._endTime || performance.now()) - this._startTime,
+      attributes: { ...this._attributes },
+      events: [...this._events],
+      children: [...this._children]
+    };
+  }
+}
+
+// src/ring-buffer.ts
+class RingBuffer {
+  capacity;
+  buffer;
+  index = 0;
+  count = 0;
+  lookup = new Map;
+  constructor(capacity) {
+    this.capacity = capacity;
+    this.buffer = new Array(capacity);
+  }
+  push(item) {
+    const evicted = this.buffer[this.index];
+    if (evicted) {
+      this.lookup.delete(evicted.id);
+    }
+    this.buffer[this.index] = item;
+    this.lookup.set(item.id, item);
+    this.index = (this.index + 1) % this.capacity;
+    if (this.count < this.capacity)
+      this.count++;
+  }
+  get(id) {
+    return this.lookup.get(id);
+  }
+  toArray() {
+    const result = [];
+    if (this.count < this.capacity) {
+      for (let i = 0;i < this.count; i++) {
+        const item = this.buffer[i];
+        if (item)
+          result.push(item);
+      }
+    } else {
+      for (let i = 0;i < this.capacity; i++) {
+        const item = this.buffer[(this.index + i) % this.capacity];
+        if (item)
+          result.push(item);
+      }
+    }
+    return result;
+  }
+  get size() {
+    return this.count;
+  }
+  clear() {
+    this.buffer = new Array(this.capacity);
+    this.index = 0;
+    this.count = 0;
+    this.lookup.clear();
+  }
+}
+
+// src/tracer.ts
+class TracerImpl {
+  traces;
+  activeTraces = new Map;
+  spanStacks = new Map;
+  subscribers = new Set;
+  config;
+  constructor(config = {}) {
+    this.config = {
+      maxTraces: config.maxTraces ?? 200,
+      maxSpansPerTrace: config.maxSpansPerTrace ?? 500,
+      layers: config.layers ?? [],
+      minDuration: config.minDuration ?? 0
+    };
+    this.traces = new RingBuffer(this.config.maxTraces);
+  }
+  startTrace(name, layer, metadata) {
+    const traceId = generateTraceId();
+    const span = this.createSpan(traceId, null, name, layer);
+    const activeTrace = {
+      id: traceId,
+      rootSpanId: span.id,
+      startTime: performance.now(),
+      spans: new Map,
+      metadata: {
+        origin: "server",
+        ...metadata
+      },
+      activeSpanCount: 1
+    };
+    this.activeTraces.set(traceId, activeTrace);
+    this.spanStacks.set(traceId, [span]);
+    const traceData = this.buildTraceData(activeTrace);
+    this.emit({ type: "trace:start", trace: traceData });
+    return span;
+  }
+  startSpan(name, layer) {
+    const parentSpan = this.findActiveSpan();
+    if (!parentSpan) {
+      return this.startTrace(name, layer);
+    }
+    const traceId = parentSpan.traceId;
+    const activeTrace = this.activeTraces.get(traceId);
+    if (activeTrace)
+      activeTrace.activeSpanCount++;
+    const span = this.createSpan(traceId, parentSpan.id, name, layer);
+    const stack = this.spanStacks.get(traceId);
+    if (stack)
+      stack.push(span);
+    return span;
+  }
+  activeSpan() {
+    return this.findActiveSpan();
+  }
+  withSpan(name, layer, fn) {
+    const span = this.startSpan(name, layer);
+    try {
+      const result = fn(span);
+      if (result instanceof Promise) {
+        return result.then((v) => {
+          span.end();
+          return v;
+        }).catch((err) => {
+          span.error(err);
+          span.end();
+          throw err;
+        });
+      }
+      span.end();
+      return result;
+    } catch (err) {
+      span.error(err);
+      span.end();
+      throw err;
+    }
+  }
+  getTraces() {
+    return this.traces.toArray();
+  }
+  getTrace(id) {
+    return this.traces.get(id);
+  }
+  subscribe(cb) {
+    this.subscribers.add(cb);
+    return () => {
+      this.subscribers.delete(cb);
+    };
+  }
+  mergeClientSpans(traceId, spans) {
+    const trace = this.traces.get(traceId);
+    if (!trace)
+      return;
+    for (const span of spans) {
+      if (trace.spans.size >= this.config.maxSpansPerTrace)
+        break;
+      trace.spans.set(span.id, span);
+    }
+    for (const span of spans) {
+      if (span.endTime > trace.endTime) {
+        trace.endTime = span.endTime;
+        trace.duration = trace.endTime - trace.startTime;
+      }
+    }
+  }
+  findActiveSpan() {
+    let latest = null;
+    for (const stack of this.spanStacks.values()) {
+      const top = stack[stack.length - 1];
+      if (top)
+        latest = top;
+    }
+    return latest;
+  }
+  createSpan(traceId, parentId, name, layer) {
+    const childFactory = (childName, childLayer, pId) => {
+      const activeTrace = this.activeTraces.get(traceId);
+      if (activeTrace)
+        activeTrace.activeSpanCount++;
+      const child = this.createSpan(traceId, pId, childName, childLayer);
+      const stack = this.spanStacks.get(traceId);
+      if (stack)
+        stack.push(child);
+      return child;
+    };
+    const onEnd = (span2) => {
+      const stack = this.spanStacks.get(traceId);
+      if (stack) {
+        const idx = stack.indexOf(span2);
+        if (idx !== -1)
+          stack.splice(idx, 1);
+      }
+      const spanData = span2.toData();
+      const activeTrace = this.activeTraces.get(traceId);
+      if (activeTrace) {
+        if (activeTrace.spans.size < this.config.maxSpansPerTrace) {
+          activeTrace.spans.set(spanData.id, spanData);
+        }
+        activeTrace.activeSpanCount--;
+        this.emit({ type: "span:end", span: spanData });
+        if (activeTrace.activeSpanCount <= 0) {
+          this.finalizeTrace(activeTrace);
+        }
+      }
+    };
+    const onEvent = (spanId, event) => {
+      this.emit({ type: "span:event", spanId, event });
+    };
+    const span = new SpanImpl(traceId, parentId, name, layer, onEnd, childFactory, onEvent);
+    this.emit({ type: "span:start", span: span.toData() });
+    return span;
+  }
+  finalizeTrace(active) {
+    this.activeTraces.delete(active.id);
+    this.spanStacks.delete(active.id);
+    let endTime = active.startTime;
+    for (const span of active.spans.values()) {
+      if (span.endTime > endTime)
+        endTime = span.endTime;
+    }
+    const duration = endTime - active.startTime;
+    if (this.config.minDuration > 0 && duration < this.config.minDuration) {
+      return;
+    }
+    const traceData = {
+      id: active.id,
+      rootSpanId: active.rootSpanId,
+      startTime: active.startTime,
+      endTime,
+      duration,
+      spans: active.spans,
+      metadata: active.metadata
+    };
+    this.traces.push(traceData);
+    this.emit({ type: "trace:end", trace: traceData });
+  }
+  buildTraceData(active) {
+    return {
+      id: active.id,
+      rootSpanId: active.rootSpanId,
+      startTime: active.startTime,
+      endTime: 0,
+      duration: 0,
+      spans: active.spans,
+      metadata: active.metadata
+    };
+  }
+  emit(event) {
+    for (const cb of this.subscribers) {
+      try {
+        cb(event);
+      } catch {}
+    }
+  }
+}
+function createTracer(config) {
+  return new TracerImpl(config);
+}
+// src/context.ts
+var TRACER_KEY = "__ereo_tracer";
+var ACTIVE_SPAN_KEY = "__ereo_active_span";
+function setTracer(context, tracer) {
+  context.set(TRACER_KEY, tracer);
+}
+function getTracer(context) {
+  return context.get(TRACER_KEY);
+}
+function setActiveSpan(context, span) {
+  context.set(ACTIVE_SPAN_KEY, span);
+}
+function getActiveSpan(context) {
+  return context.get(ACTIVE_SPAN_KEY);
+}
+// src/cli-reporter.ts
+var RESET = "\x1B[0m";
+var BOLD = "\x1B[1m";
+var DIM = "\x1B[2m";
+var GREEN = "\x1B[32m";
+var YELLOW = "\x1B[33m";
+var RED = "\x1B[31m";
+var CYAN = "\x1B[36m";
+var MAGENTA = "\x1B[35m";
+var BLUE = "\x1B[34m";
+var GRAY = "\x1B[90m";
+var WHITE = "\x1B[37m";
+function durationColor(ms) {
+  if (ms < 50)
+    return GREEN;
+  if (ms < 200)
+    return YELLOW;
+  return RED;
+}
+function formatDuration(ms) {
+  if (ms < 1)
+    return `${(ms * 1000).toFixed(0)}us`;
+  if (ms < 1000)
+    return `${ms.toFixed(1)}ms`;
+  return `${(ms / 1000).toFixed(2)}s`;
+}
+function statusColor(code) {
+  if (code < 300)
+    return GREEN;
+  if (code < 400)
+    return CYAN;
+  if (code < 500)
+    return YELLOW;
+  return RED;
+}
+function layerColor(layer) {
+  switch (layer) {
+    case "request":
+      return WHITE;
+    case "routing":
+      return CYAN;
+    case "data":
+      return BLUE;
+    case "database":
+      return MAGENTA;
+    case "auth":
+      return YELLOW;
+    case "rpc":
+      return CYAN;
+    case "forms":
+      return GREEN;
+    case "islands":
+      return MAGENTA;
+    case "build":
+      return BLUE;
+    case "errors":
+      return RED;
+    case "signals":
+      return GREEN;
+    case "custom":
+      return GRAY;
+  }
+}
+function spanSummary(span) {
+  const parts = [];
+  if (span.attributes["route.pattern"]) {
+    parts.push(`matched ${span.attributes["route.pattern"]}`);
+  }
+  if (span.attributes["cache.hit"] === true) {
+    parts.push("cache hit");
+  } else if (span.attributes["db.system"]) {
+    parts.push(`${span.attributes["db.system"]}`);
+  }
+  if (span.attributes["auth.result"]) {
+    parts.push(`${span.attributes["auth.provider"] || "auth"} -> ${span.attributes["auth.result"]}`);
+  }
+  if (span.attributes["rpc.procedure"]) {
+    parts.push(`${span.attributes["rpc.type"] || "query"}`);
+  }
+  if (span.status === "error" && span.attributes["error.message"]) {
+    parts.push(`${span.attributes["error.message"]}`);
+  }
+  if (span.attributes["db.statement"]) {
+    const stmt = String(span.attributes["db.statement"]);
+    parts.push(stmt.length > 50 ? stmt.slice(0, 50) + "..." : stmt);
+  }
+  return parts.join("  ");
+}
+function printTrace(trace, options) {
+  const { verbose, layers, minDuration, colors } = options;
+  const c = (color, text) => colors ? `${color}${text}${RESET}` : text;
+  const rootSpan = trace.spans.get(trace.rootSpanId);
+  if (!rootSpan)
+    return;
+  const method = String(trace.metadata.method || "GET");
+  const pathname = String(trace.metadata.pathname || "/");
+  const statusCode = Number(trace.metadata.statusCode || rootSpan.attributes["http.status_code"] || 200);
+  const duration = trace.duration;
+  const methodStr = c(BOLD, method.padEnd(7));
+  const pathStr = pathname;
+  const statusStr = c(statusColor(statusCode), String(statusCode));
+  const durationStr = c(durationColor(duration), formatDuration(duration));
+  console.log(`  ${methodStr}${pathStr}  ${statusStr}  ${durationStr}`);
+  const children = getChildSpans(trace, rootSpan.id);
+  printChildren(trace, children, "  ", options);
+  console.log();
+}
+function getChildSpans(trace, parentId) {
+  const children = [];
+  for (const span of trace.spans.values()) {
+    if (span.parentId === parentId && span.id !== parentId) {
+      children.push(span);
+    }
+  }
+  return children.sort((a, b) => a.startTime - b.startTime);
+}
+function printChildren(trace, children, prefix, options) {
+  const { layers, minDuration, colors } = options;
+  const c = (color, text) => colors ? `${color}${text}${RESET}` : text;
+  const filtered = children.filter((span) => {
+    if (layers.length > 0 && !layers.includes(span.layer))
+      return false;
+    if (span.duration < minDuration)
+      return false;
+    return true;
+  });
+  for (let i = 0;i < filtered.length; i++) {
+    const span = filtered[i];
+    const isLast = i === filtered.length - 1;
+    const connector = isLast ? "`-- " : "|-- ";
+    const childPrefix = isLast ? "    " : "|   ";
+    const name = c(layerColor(span.layer), span.name.padEnd(16));
+    const dur = c(durationColor(span.duration), formatDuration(span.duration).padStart(8));
+    const summary = c(DIM, spanSummary(span));
+    console.log(`${prefix}${c(GRAY, connector)}${name}${dur}   ${summary}`);
+    const grandchildren = getChildSpans(trace, span.id);
+    if (grandchildren.length > 0) {
+      printChildren(trace, grandchildren, prefix + childPrefix, options);
+    }
+  }
+}
+function createCLIReporter(tracer, options = {}) {
+  const resolved = {
+    verbose: options.verbose ?? false,
+    layers: options.layers ?? [],
+    minDuration: options.minDuration ?? 0,
+    colors: options.colors ?? true
+  };
+  return tracer.subscribe((event) => {
+    if (event.type === "trace:end") {
+      const rootSpan = event.trace.spans.get(event.trace.rootSpanId);
+      if (rootSpan && rootSpan.attributes["http.status_code"]) {
+        event.trace.metadata.statusCode = Number(rootSpan.attributes["http.status_code"]);
+      }
+      printTrace(event.trace, resolved);
+    }
+  });
+}
+// src/transport.ts
+function serializeTrace(trace) {
+  const spans = {};
+  for (const [id, span] of trace.spans) {
+    spans[id] = span;
+  }
+  return {
+    id: trace.id,
+    rootSpanId: trace.rootSpanId,
+    startTime: trace.startTime,
+    endTime: trace.endTime,
+    duration: trace.duration,
+    spans,
+    metadata: trace.metadata
+  };
+}
+function deserializeTrace(data) {
+  const spans = new Map;
+  for (const [id, span] of Object.entries(data.spans)) {
+    spans.set(id, span);
+  }
+  return {
+    id: data.id,
+    rootSpanId: data.rootSpanId,
+    startTime: data.startTime,
+    endTime: data.endTime,
+    duration: data.duration,
+    spans,
+    metadata: data.metadata
+  };
+}
+function serializeEvent(event) {
+  if (event.type === "trace:start" || event.type === "trace:end") {
+    return { type: event.type, trace: serializeTrace(event.trace) };
+  }
+  return event;
+}
+function createTraceWebSocket(tracer) {
+  const clients = new Set;
+  let unsubscribe = null;
+  const startBroadcast = () => {
+    if (unsubscribe)
+      return;
+    unsubscribe = tracer.subscribe((event) => {
+      const serialized = JSON.stringify(serializeEvent(event));
+      for (const client of clients) {
+        try {
+          client.send(serialized);
+        } catch {
+          clients.delete(client);
+        }
+      }
+    });
+  };
+  return {
+    upgrade(request) {
+      const url = new URL(request.url);
+      return url.pathname === "/__ereo/trace-ws";
+    },
+    websocket: {
+      open(ws) {
+        clients.add(ws);
+        if (clients.size === 1)
+          startBroadcast();
+        const traces = tracer.getTraces();
+        const initial = JSON.stringify({
+          type: "initial",
+          traces: traces.map(serializeTrace)
+        });
+        ws.send(initial);
+      },
+      close(ws) {
+        clients.delete(ws);
+        if (clients.size === 0 && unsubscribe) {
+          unsubscribe();
+          unsubscribe = null;
+        }
+      },
+      message(_ws, message) {
+        try {
+          const data = JSON.parse(typeof message === "string" ? message : message.toString());
+          if (data.type === "client:spans" && data.traceId && Array.isArray(data.spans)) {
+            tracer.mergeClientSpans(data.traceId, data.spans);
+          }
+        } catch {}
+      }
+    },
+    close() {
+      if (unsubscribe) {
+        unsubscribe();
+        unsubscribe = null;
+      }
+      clients.clear();
+    }
+  };
+}
+function createTracesAPIHandler(tracer) {
+  return (request) => {
+    const url = new URL(request.url);
+    const traceId = url.searchParams.get("id");
+    if (traceId) {
+      const trace = tracer.getTrace(traceId);
+      if (!trace) {
+        return new Response(JSON.stringify({ error: "Trace not found" }), {
+          status: 404,
+          headers: { "Content-Type": "application/json" }
+        });
+      }
+      return new Response(JSON.stringify(serializeTrace(trace)), {
+        headers: { "Content-Type": "application/json" }
+      });
+    }
+    const traces = tracer.getTraces().map(serializeTrace);
+    return new Response(JSON.stringify({ traces }), {
+      headers: { "Content-Type": "application/json" }
+    });
+  };
+}
+// src/collector.ts
+class TraceCollector {
+  tracer;
+  constructor(tracer) {
+    this.tracer = tracer;
+  }
+  mergeClientSpans(traceId, clientSpans) {
+    this.tracer.mergeClientSpans(traceId, clientSpans);
+  }
+  getUnifiedTrace(traceId) {
+    return this.tracer.getTrace(traceId);
+  }
+}
+function createCollector(tracer) {
+  return new TraceCollector(tracer);
+}
+// src/viewer.ts
+function generateViewerHTML(traces) {
+  const serialized = traces.map(serializeTrace);
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Ereo Trace Viewer</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, monospace; background: #0d1117; color: #c9d1d9; }
+    .header { padding: 16px 24px; border-bottom: 1px solid #21262d; display: flex; align-items: center; gap: 12px; }
+    .header h1 { font-size: 16px; font-weight: 600; }
+    .header .badge { font-size: 12px; background: #1f6feb; color: white; padding: 2px 8px; border-radius: 10px; }
+    .container { display: flex; height: calc(100vh - 53px); }
+    .trace-list { width: 380px; border-right: 1px solid #21262d; overflow-y: auto; }
+    .trace-item { padding: 10px 16px; border-bottom: 1px solid #21262d; cursor: pointer; font-size: 13px; }
+    .trace-item:hover { background: #161b22; }
+    .trace-item.active { background: #1c2128; border-left: 3px solid #1f6feb; }
+    .trace-item .method { font-weight: 600; width: 50px; display: inline-block; }
+    .trace-item .path { color: #8b949e; }
+    .trace-item .status { float: right; font-size: 12px; }
+    .trace-item .duration { float: right; margin-right: 12px; font-size: 12px; }
+    .status-2xx { color: #3fb950; }
+    .status-3xx { color: #58a6ff; }
+    .status-4xx { color: #d29922; }
+    .status-5xx { color: #f85149; }
+    .dur-fast { color: #3fb950; }
+    .dur-medium { color: #d29922; }
+    .dur-slow { color: #f85149; }
+    .detail-panel { flex: 1; overflow-y: auto; padding: 16px; }
+    .waterfall { padding: 8px 0; }
+    .span-row { display: flex; align-items: center; padding: 4px 8px; font-size: 12px; border-radius: 4px; }
+    .span-row:hover { background: #161b22; }
+    .span-name { width: 200px; flex-shrink: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+    .span-bar-container { flex: 1; height: 20px; position: relative; margin: 0 12px; }
+    .span-bar { position: absolute; height: 16px; border-radius: 3px; top: 2px; min-width: 2px; }
+    .span-duration { width: 70px; text-align: right; flex-shrink: 0; font-size: 11px; color: #8b949e; }
+    .layer-request { background: #8b949e; }
+    .layer-routing { background: #58a6ff; }
+    .layer-data { background: #1f6feb; }
+    .layer-database { background: #bc8cff; }
+    .layer-auth { background: #d29922; }
+    .layer-rpc { background: #58a6ff; }
+    .layer-forms { background: #3fb950; }
+    .layer-islands { background: #bc8cff; }
+    .layer-build { background: #1f6feb; }
+    .layer-errors { background: #f85149; }
+    .layer-signals { background: #3fb950; }
+    .layer-custom { background: #8b949e; }
+    .span-detail { margin-top: 16px; padding: 16px; background: #161b22; border-radius: 8px; font-size: 12px; }
+    .span-detail h3 { font-size: 14px; margin-bottom: 8px; }
+    .span-detail table { width: 100%; border-collapse: collapse; }
+    .span-detail td { padding: 4px 8px; border-bottom: 1px solid #21262d; }
+    .span-detail td:first-child { color: #8b949e; width: 150px; }
+    .empty { text-align: center; padding: 48px; color: #8b949e; }
+    .filters { padding: 8px 16px; border-bottom: 1px solid #21262d; display: flex; gap: 8px; font-size: 12px; }
+    .filters select, .filters input { background: #0d1117; border: 1px solid #30363d; color: #c9d1d9; padding: 4px 8px; border-radius: 4px; font-size: 12px; }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <h1>Ereo Trace Viewer</h1>
+    <span class="badge">${serialized.length} traces</span>
+  </div>
+  <div class="filters">
+    <select id="filter-method"><option value="">All Methods</option><option>GET</option><option>POST</option><option>PUT</option><option>DELETE</option></select>
+    <input id="filter-path" type="text" placeholder="Filter by path..." />
+    <select id="filter-status"><option value="">All Status</option><option value="2xx">2xx</option><option value="4xx">4xx</option><option value="5xx">5xx</option></select>
+  </div>
+  <div class="container">
+    <div class="trace-list" id="trace-list"></div>
+    <div class="detail-panel" id="detail-panel"><div class="empty">Select a trace to view details</div></div>
+  </div>
+  <script>
+    const TRACES = ${JSON.stringify(serialized).replace(/<\//g, "<\\/")};
+    let selectedTraceId = null;
+    let selectedSpanId = null;
+
+    function esc(s) { return String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;'); }
+    function durClass(ms) { return ms < 50 ? 'dur-fast' : ms < 200 ? 'dur-medium' : 'dur-slow'; }
+    function statusClass(code) {
+      if (code < 300) return 'status-2xx';
+      if (code < 400) return 'status-3xx';
+      if (code < 500) return 'status-4xx';
+      return 'status-5xx';
+    }
+    function fmtDur(ms) { return ms < 1 ? (ms*1000).toFixed(0)+'us' : ms < 1000 ? ms.toFixed(1)+'ms' : (ms/1000).toFixed(2)+'s'; }
+
+    function renderTraceList(traces) {
+      const el = document.getElementById('trace-list');
+      if (!traces.length) { el.innerHTML = '<div class="empty">No traces recorded</div>'; return; }
+      el.innerHTML = traces.map(t => {
+        const s = t.metadata.statusCode || 200;
+        const d = t.duration;
+        return '<div class="trace-item'+(t.id===selectedTraceId?' active':'')+'" data-id="'+esc(t.id)+'">' +
+          '<span class="method">'+esc(t.metadata.method||'GET')+'</span>' +
+          '<span class="path">'+esc(t.metadata.pathname||'/')+'</span>' +
+          '<span class="status '+statusClass(s)+'">'+s+'</span>' +
+          '<span class="duration '+durClass(d)+'">'+fmtDur(d)+'</span>' +
+          '</div>';
+      }).join('');
+      el.querySelectorAll('.trace-item').forEach(item => {
+        item.onclick = () => { selectedTraceId = item.dataset.id; selectedSpanId = null; render(); };
+      });
+    }
+
+    function flattenSpans(trace) {
+      const spans = Object.values(trace.spans);
+      const root = spans.find(s => s.id === trace.rootSpanId);
+      if (!root) return spans;
+      const result = [];
+      function walk(span, depth) {
+        result.push({ ...span, depth });
+        const children = spans.filter(s => s.parentId === span.id).sort((a,b) => a.startTime - b.startTime);
+        children.forEach(c => walk(c, depth+1));
+      }
+      walk(root, 0);
+      return result;
+    }
+
+    function renderDetail(trace) {
+      const panel = document.getElementById('detail-panel');
+      if (!trace) { panel.innerHTML = '<div class="empty">Select a trace to view details</div>'; return; }
+      const spans = flattenSpans(trace);
+      const minTime = trace.startTime;
+      const totalDur = trace.duration || 1;
+      let html = '<div class="waterfall">';
+      spans.forEach(s => {
+        const left = ((s.startTime - minTime) / totalDur * 100).toFixed(2);
+        const width = Math.max(0.5, (s.duration / totalDur * 100));
+        const indent = s.depth * 16;
+        html += '<div class="span-row'+(s.id===selectedSpanId?' active':'')+'" data-span="'+esc(s.id)+'">' +
+          '<div class="span-name" style="padding-left:'+indent+'px">'+esc(s.name)+'</div>' +
+          '<div class="span-bar-container"><div class="span-bar layer-'+esc(s.layer)+'" style="left:'+left+'%;width:'+width.toFixed(2)+'%"></div></div>' +
+          '<div class="span-duration '+durClass(s.duration)+'">'+fmtDur(s.duration)+'</div>' +
+          '</div>';
+      });
+      html += '</div>';
+      if (selectedSpanId) {
+        const span = trace.spans[selectedSpanId];
+        if (span) {
+          html += '<div class="span-detail"><h3>'+esc(span.name)+' ('+esc(span.layer)+')</h3><table>';
+          html += '<tr><td>Status</td><td>'+esc(span.status)+'</td></tr>';
+          html += '<tr><td>Duration</td><td>'+fmtDur(span.duration)+'</td></tr>';
+          Object.entries(span.attributes||{}).forEach(([k,v]) => { html += '<tr><td>'+esc(k)+'</td><td>'+esc(v)+'</td></tr>'; });
+          if (span.events && span.events.length) {
+            html += '<tr><td>Events</td><td>'+span.events.map(e=>esc(e.name)).join(', ')+'</td></tr>';
+          }
+          html += '</table></div>';
+        }
+      }
+      panel.innerHTML = html;
+      panel.querySelectorAll('.span-row').forEach(row => {
+        row.onclick = () => { selectedSpanId = row.dataset.span; renderDetail(trace); };
+      });
+    }
+
+    function getFiltered() {
+      let t = TRACES;
+      const method = document.getElementById('filter-method').value;
+      const path = document.getElementById('filter-path').value;
+      const status = document.getElementById('filter-status').value;
+      if (method) t = t.filter(x => x.metadata.method === method);
+      if (path) t = t.filter(x => (x.metadata.pathname||'').includes(path));
+      if (status) {
+        const base = parseInt(status);
+        t = t.filter(x => { const s = x.metadata.statusCode||200; return s >= base && s < base+100; });
+      }
+      return t.reverse();
+    }
+
+    function render() {
+      const filtered = getFiltered();
+      renderTraceList(filtered);
+      const trace = selectedTraceId ? TRACES.find(t => t.id === selectedTraceId) : null;
+      renderDetail(trace);
+    }
+
+    document.getElementById('filter-method').onchange = render;
+    document.getElementById('filter-path').oninput = render;
+    document.getElementById('filter-status').onchange = render;
+    render();
+
+    // Live updates via WebSocket
+    if (typeof WebSocket !== 'undefined') {
+      try {
+        const protocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+        const ws = new WebSocket(protocol + '//' + location.host + '/__ereo/trace-ws');
+        ws.onmessage = (e) => {
+          try {
+            const data = JSON.parse(e.data);
+            if (data.type === 'trace:end') {
+              TRACES.push(data.trace);
+              render();
+            }
+          } catch {}
+        };
+      } catch {}
+    }
+  </script>
+</body>
+</html>`;
+}
+function createViewerHandler(tracer) {
+  return () => {
+    const traces = tracer.getTraces();
+    const html = generateViewerHTML(traces);
+    return new Response(html, {
+      headers: { "Content-Type": "text/html; charset=utf-8" }
+    });
+  };
+}
+function exportTracesHTML(tracer) {
+  return generateViewerHTML(tracer.getTraces());
+}
+// src/instrumentors/request.ts
+function traceMiddleware(tracer, options = {}) {
+  const { exclude = ["/_ereo/", "/__ereo/", "/favicon.ico"], recordHeaders = false } = options;
+  return async (request, context, next) => {
+    const url = new URL(request.url);
+    for (const pattern of exclude) {
+      if (url.pathname.startsWith(pattern)) {
+        return next();
+      }
+    }
+    const rootSpan = tracer.startTrace(`${request.method} ${url.pathname}`, "request", {
+      origin: "server",
+      method: request.method,
+      pathname: url.pathname
+    });
+    rootSpan.setAttribute("http.method", request.method);
+    rootSpan.setAttribute("http.pathname", url.pathname);
+    rootSpan.setAttribute("http.search", url.search);
+    if (recordHeaders) {
+      const headers2 = [];
+      request.headers.forEach((value, key) => {
+        if (key.toLowerCase() !== "cookie" && key.toLowerCase() !== "authorization") {
+          headers2.push(`${key}: ${value}`);
+        }
+      });
+      rootSpan.setAttribute("http.request_headers", headers2.join("; "));
+    }
+    setTracer(context, tracer);
+    setActiveSpan(context, rootSpan);
+    const clientTraceId = request.headers.get("X-Ereo-Trace-Id");
+    if (clientTraceId) {
+      rootSpan.setAttribute("trace.client_id", clientTraceId);
+    }
+    let response;
+    try {
+      response = await next();
+    } catch (err) {
+      rootSpan.error(err);
+      rootSpan.setAttribute("http.status_code", 500);
+      rootSpan.end();
+      throw err;
+    }
+    rootSpan.setAttribute("http.status_code", response.status);
+    if (response.status >= 400) {
+      rootSpan.setAttribute("http.error", true);
+    }
+    rootSpan.end();
+    const headers = new Headers(response.headers);
+    headers.set("X-Ereo-Trace-Id", rootSpan.traceId);
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers
+    });
+  };
+}
+// src/instrumentors/routing.ts
+function traceRouteMatch(parentSpan, matchFn) {
+  const span = parentSpan.child("route.match", "routing");
+  try {
+    const result = matchFn();
+    if (result && typeof result === "object" && "route" in result) {
+      const match = result;
+      span.setAttribute("route.pattern", match.route.path);
+      span.setAttribute("route.id", match.route.id);
+      span.setAttribute("route.params", JSON.stringify(match.params));
+      if (match.layouts) {
+        span.setAttribute("route.layouts", match.layouts.map((l) => l.id).join(" > "));
+      }
+    } else {
+      span.setAttribute("route.matched", false);
+      span.event("404", { pathname: "unknown" });
+    }
+    span.end();
+    return result;
+  } catch (err) {
+    span.error(err);
+    span.end();
+    throw err;
+  }
+}
+function recordRouteMatch(parentSpan, match) {
+  if (match) {
+    parentSpan.setAttribute("route.pattern", match.route.path);
+    parentSpan.setAttribute("route.id", match.route.id);
+    parentSpan.event("route.matched", { pattern: match.route.path });
+  } else {
+    parentSpan.event("route.miss");
+  }
+}
+// src/instrumentors/data.ts
+function traceLoader(parentSpan, loaderKey, loaderFn) {
+  const span = parentSpan.child(`loader:${loaderKey}`, "data");
+  span.setAttribute("loader.key", loaderKey);
+  try {
+    const result = loaderFn();
+    if (result instanceof Promise) {
+      return result.then((v) => {
+        span.end();
+        return v;
+      }).catch((err) => {
+        span.error(err);
+        span.end();
+        throw err;
+      });
+    }
+    span.end();
+    return result;
+  } catch (err) {
+    span.error(err);
+    span.end();
+    throw err;
+  }
+}
+function recordLoaderMetrics(parentSpan, metrics) {
+  for (const metric of metrics) {
+    const span = parentSpan.child(`loader:${metric.key}`, "data");
+    span.setAttribute("loader.key", metric.key);
+    span.setAttribute("loader.duration_ms", metric.duration);
+    if (metric.cacheHit !== undefined) {
+      span.setAttribute("cache.hit", metric.cacheHit);
+    }
+    if (metric.source) {
+      span.setAttribute("loader.source", metric.source);
+    }
+    if (metric.waitingFor && metric.waitingFor.length > 0) {
+      span.setAttribute("loader.waiting_for", metric.waitingFor.join(", "));
+    }
+    if (metric.error) {
+      span.setAttribute("error.message", metric.error);
+    }
+    span.end();
+  }
+}
+function traceCacheOperation(parentSpan, operation, key, hit) {
+  parentSpan.event(`cache.${operation}`, {
+    key: key.length > 100 ? key.slice(0, 100) + "..." : key,
+    ...hit !== undefined ? { hit } : {}
+  });
+}
+// src/instrumentors/forms.ts
+function traceFormSubmit(parentSpan, formName, submitFn, attrs) {
+  const span = parentSpan.child(`form:${formName}`, "forms");
+  span.setAttribute("form.name", formName);
+  if (attrs?.fieldCount)
+    span.setAttribute("form.field_count", attrs.fieldCount);
+  try {
+    const result = submitFn();
+    if (result instanceof Promise) {
+      return result.then((v) => {
+        span.end();
+        return v;
+      }).catch((err) => {
+        span.error(err);
+        span.end();
+        throw err;
+      });
+    }
+    span.end();
+    return result;
+  } catch (err) {
+    span.error(err);
+    span.end();
+    throw err;
+  }
+}
+function recordFormValidation(parentSpan, formName, attrs) {
+  parentSpan.event("form.validation", {
+    form: formName,
+    error_count: attrs.errorCount,
+    duration_ms: attrs.validationMs,
+    ...attrs.errorSources ? { sources: attrs.errorSources.join(", ") } : {}
+  });
+}
+// src/instrumentors/signals.ts
+function recordSignalUpdate(span, name, attrs) {
+  span.event("signal.update", {
+    name,
+    ...attrs?.subscriberCount !== undefined ? { subscribers: attrs.subscriberCount } : {},
+    ...attrs?.batched !== undefined ? { batched: attrs.batched } : {}
+  });
+}
+function recordSignalBatch(span, signalNames, attrs) {
+  span.event("signal.batch", {
+    count: signalNames.length,
+    signals: signalNames.join(", "),
+    ...attrs?.subscriberCount !== undefined ? { total_subscribers: attrs.subscriberCount } : {}
+  });
+}
+// src/instrumentors/rpc.ts
+function traceRPCCall(parentSpan, procedure, type, callFn) {
+  const span = parentSpan.child(`rpc:${procedure}`, "rpc");
+  span.setAttribute("rpc.procedure", procedure);
+  span.setAttribute("rpc.type", type);
+  try {
+    const result = callFn();
+    if (result instanceof Promise) {
+      return result.then((v) => {
+        span.end();
+        return v;
+      }).catch((err) => {
+        span.error(err);
+        span.end();
+        throw err;
+      });
+    }
+    span.end();
+    return result;
+  } catch (err) {
+    span.error(err);
+    span.end();
+    throw err;
+  }
+}
+function recordRPCValidation(parentSpan, procedure, validationMs, valid) {
+  parentSpan.event("rpc.validation", {
+    procedure,
+    duration_ms: validationMs,
+    valid
+  });
+}
+// src/instrumentors/database.ts
+function tracedAdapter(adapter, getSpan) {
+  const methodsToTrace = ["query", "execute", "get", "all", "run"];
+  return new Proxy(adapter, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof prop !== "string" || typeof value !== "function" || !methodsToTrace.includes(prop)) {
+        return value;
+      }
+      return async function tracedMethod(sql, params) {
+        const parentSpan = getSpan();
+        if (!parentSpan) {
+          return value.call(target, sql, params);
+        }
+        const span = parentSpan.child(`db.${prop}`, "database");
+        span.setAttribute("db.operation", prop);
+        span.setAttribute("db.statement", typeof sql === "string" ? sql.slice(0, 200) : "");
+        if (params) {
+          span.setAttribute("db.param_count", params.length);
+        }
+        try {
+          const result = await value.call(target, sql, params);
+          if (Array.isArray(result)) {
+            span.setAttribute("db.row_count", result.length);
+          }
+          span.end();
+          return result;
+        } catch (err) {
+          span.error(err);
+          span.end();
+          throw err;
+        }
+      };
+    }
+  });
+}
+function traceQuery(parentSpan, operation, sql, queryFn) {
+  const span = parentSpan.child(`db.${operation}`, "database");
+  span.setAttribute("db.operation", operation);
+  span.setAttribute("db.statement", sql.slice(0, 200));
+  return queryFn().then((result) => {
+    if (Array.isArray(result)) {
+      span.setAttribute("db.row_count", result.length);
+    }
+    span.end();
+    return result;
+  }).catch((err) => {
+    span.error(err);
+    span.end();
+    throw err;
+  });
+}
+// src/instrumentors/auth.ts
+function traceAuthCheck(parentSpan, operation, checkFn, attrs) {
+  const span = parentSpan.child(`auth:${operation}`, "auth");
+  span.setAttribute("auth.operation", operation);
+  if (attrs?.provider)
+    span.setAttribute("auth.provider", attrs.provider);
+  if (attrs?.roles)
+    span.setAttribute("auth.roles", attrs.roles.join(", "));
+  try {
+    const result = checkFn();
+    if (result instanceof Promise) {
+      return result.then((v) => {
+        span.setAttribute("auth.result", "ok");
+        span.end();
+        return v;
+      }).catch((err) => {
+        span.setAttribute("auth.result", "denied");
+        if (err instanceof Response) {
+          const location = err.headers.get("Location");
+          if (location)
+            span.setAttribute("auth.redirect", location);
+        }
+        span.error(err);
+        span.end();
+        throw err;
+      });
+    }
+    span.setAttribute("auth.result", "ok");
+    span.end();
+    return result;
+  } catch (err) {
+    span.setAttribute("auth.result", "denied");
+    span.error(err);
+    span.end();
+    throw err;
+  }
+}
+// src/instrumentors/islands.ts
+function traceHydration(parentSpan, componentName, strategy, hydrateFn, attrs) {
+  const span = parentSpan.child(`hydrate:${componentName}`, "islands");
+  span.setAttribute("island.component", componentName);
+  span.setAttribute("island.strategy", strategy);
+  if (attrs?.propsSize)
+    span.setAttribute("island.props_size", attrs.propsSize);
+  try {
+    const result = hydrateFn();
+    if (result instanceof Promise) {
+      return result.then((v) => {
+        span.end();
+        return v;
+      }).catch((err) => {
+        span.error(err);
+        span.end();
+        throw err;
+      });
+    }
+    span.end();
+    return result;
+  } catch (err) {
+    span.error(err);
+    span.end();
+    throw err;
+  }
+}
+function recordHydration(parentSpan, componentName, strategy, durationMs) {
+  parentSpan.event("island.hydrated", {
+    component: componentName,
+    strategy,
+    duration_ms: durationMs
+  });
+}
+// src/instrumentors/build.ts
+function traceBuildStage(parentSpan, stageName, stageFn, attrs) {
+  const span = parentSpan.child(`build:${stageName}`, "build");
+  span.setAttribute("build.stage", stageName);
+  if (attrs?.filesCount)
+    span.setAttribute("build.files_count", attrs.filesCount);
+  try {
+    const result = stageFn();
+    if (result instanceof Promise) {
+      return result.then((v) => {
+        span.end();
+        return v;
+      }).catch((err) => {
+        span.error(err);
+        span.end();
+        throw err;
+      });
+    }
+    span.end();
+    return result;
+  } catch (err) {
+    span.error(err);
+    span.end();
+    throw err;
+  }
+}
+function traceBuild(tracer, buildName = "production build") {
+  return tracer.startTrace(buildName, "build", { origin: "server" });
+}
+// src/instrumentors/errors.ts
+function traceError(span, err, phase = "unknown") {
+  span.error(err);
+  span.setAttribute("error.phase", phase);
+  if (err instanceof Error) {
+    span.setAttribute("error.class", err.constructor.name);
+    span.event("error", {
+      message: err.message,
+      class: err.constructor.name,
+      phase
+    });
+  }
+}
+function withErrorCapture(span, phase, fn) {
+  try {
+    const result = fn();
+    if (result instanceof Promise) {
+      return result.catch((err) => {
+        traceError(span, err, phase);
+        throw err;
+      });
+    }
+    return result;
+  } catch (err) {
+    traceError(span, err, phase);
+    throw err;
+  }
+}
+export {
+  withErrorCapture,
+  tracedAdapter,
+  traceRouteMatch,
+  traceRPCCall,
+  traceQuery,
+  traceMiddleware,
+  traceLoader,
+  traceHydration,
+  traceFormSubmit,
+  traceError,
+  traceCacheOperation,
+  traceBuildStage,
+  traceBuild,
+  traceAuthCheck,
+  setTracer,
+  setActiveSpan,
+  serializeTrace,
+  recordSignalUpdate,
+  recordSignalBatch,
+  recordRouteMatch,
+  recordRPCValidation,
+  recordLoaderMetrics,
+  recordHydration,
+  recordFormValidation,
+  noopTracer,
+  noopSpan,
+  getTracer,
+  getActiveSpan,
+  generateViewerHTML,
+  generateTraceId,
+  generateSpanId,
+  exportTracesHTML,
+  deserializeTrace,
+  createViewerHandler,
+  createTracesAPIHandler,
+  createTracer,
+  createTraceWebSocket,
+  createCollector,
+  createCLIReporter,
+  TracerImpl,
+  TraceCollector,
+  SpanImpl,
+  RingBuffer,
+  NoopTracer
+};