logquill 0.3.0 → 1.0.0

package/dist/browser.mjs

@@ -0,0 +1,783 @@
+// src/core/levels.ts
+var Level = /* @__PURE__ */ ((Level2) => {
+  Level2[Level2["TRACE"] = 5] = "TRACE";
+  Level2[Level2["DEBUG"] = 10] = "DEBUG";
+  Level2[Level2["INFO"] = 20] = "INFO";
+  Level2[Level2["WARN"] = 30] = "WARN";
+  Level2[Level2["ERROR"] = 40] = "ERROR";
+  Level2[Level2["FATAL"] = 50] = "FATAL";
+  return Level2;
+})(Level || {});
+var NAME_TO_LEVEL = {
+  TRACE: 5 /* TRACE */,
+  DEBUG: 10 /* DEBUG */,
+  INFO: 20 /* INFO */,
+  WARN: 30 /* WARN */,
+  ERROR: 40 /* ERROR */,
+  FATAL: 50 /* FATAL */
+};
+function levelName(level) {
+  return Level[level];
+}
+function parseLevel(level) {
+  if (typeof level === "string") {
+    const parsed = NAME_TO_LEVEL[level.toUpperCase()];
+    if (parsed === void 0) {
+      throw new Error(`Unknown log level: ${level}`);
+    }
+    return parsed;
+  }
+  if (Level[level] === void 0) {
+    throw new Error(`Unknown log level: ${String(level)}`);
+  }
+  return level;
+}
+
+// src/core/records.ts
+function utcTimestamp() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function createRecord(params) {
+  return {
+    timestamp: utcTimestamp(),
+    level: levelName(params.level),
+    logger: params.logger,
+    message: params.message,
+    meta: params.meta
+  };
+}
+
+// src/core/formatter.ts
+var JSONFormatter = class {
+  /** Returns `JSON.stringify(record)`. */
+  format(record) {
+    return JSON.stringify(record);
+  }
+};
+
+// src/core/plugin.ts
+var FunctionPlugin = class {
+  func;
+  constructor(func) {
+    this.func = func;
+  }
+  beforeLog(record) {
+    return this.func(record);
+  }
+};
+
+// src/plugins/context-plugin.ts
+var ContextPlugin = class {
+  /** Fixed key/value pairs merged into every record's `meta`. */
+  context;
+  constructor(context) {
+    this.context = context;
+  }
+  beforeLog(record) {
+    return { ...record, meta: { ...this.context, ...record.meta } };
+  }
+};
+
+// src/plugins/redact-plugin.ts
+var DEFAULT_REDACTED_KEYS = ["password", "token", "secret", "api_key", "authorization"];
+var RedactPlugin = class {
+  keys;
+  /** Placeholder a matched value is replaced with. */
+  replacement;
+  constructor(options = {}) {
+    this.keys = new Set((options.keys ?? DEFAULT_REDACTED_KEYS).map((key) => key.toLowerCase()));
+    this.replacement = options.replacement ?? "***";
+  }
+  beforeLog(record) {
+    const meta = {};
+    for (const [key, value] of Object.entries(record.meta)) {
+      meta[key] = this.keys.has(key.toLowerCase()) ? this.replacement : value;
+    }
+    return { ...record, meta };
+  }
+};
+
+// src/plugins/pii-redact-plugin.ts
+var DEFAULT_PII_PATTERNS = {
+  email: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+  ssn: /\b\d{3}-\d{2}-\d{4}\b/g,
+  creditCard: /\b(?:\d[ -]?){13,16}\b/g,
+  phone: /\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g
+};
+var MAX_DEPTH = 50;
+var PIIRedactPlugin = class {
+  /** Named patterns scanned for in every string `meta` value. */
+  patterns;
+  /** Placeholder a matched substring is replaced with. */
+  replacement;
+  constructor(options = {}) {
+    this.patterns = options.patterns ?? DEFAULT_PII_PATTERNS;
+    this.replacement = options.replacement ?? "***";
+  }
+  beforeLog(record) {
+    return { ...record, meta: this.redactValue(record.meta, /* @__PURE__ */ new Set(), 0) };
+  }
+  redactValue(value, seen, depth) {
+    if (depth > MAX_DEPTH) {
+      return value;
+    }
+    if (typeof value === "string") {
+      return this.redactText(value);
+    }
+    if (Array.isArray(value)) {
+      if (seen.has(value)) {
+        return value;
+      }
+      const nextSeen = new Set(seen).add(value);
+      return value.map((entry) => this.redactValue(entry, nextSeen, depth + 1));
+    }
+    if (value !== null && typeof value === "object") {
+      if (seen.has(value)) {
+        return value;
+      }
+      const nextSeen = new Set(seen).add(value);
+      const result = {};
+      for (const [key, entryValue] of Object.entries(value)) {
+        result[key] = this.redactValue(entryValue, nextSeen, depth + 1);
+      }
+      return result;
+    }
+    return value;
+  }
+  redactText(text) {
+    let redacted = text;
+    for (const pattern of Object.values(this.patterns)) {
+      const global = pattern.global ? pattern : new RegExp(pattern.source, `${pattern.flags}g`);
+      redacted = redacted.replace(global, this.replacement);
+    }
+    return redacted;
+  }
+};
+
+// src/plugins/sampling-plugin.ts
+var SamplingPlugin = class {
+  /** Fraction of non-elevated records kept, in `[0, 1]`. */
+  rate;
+  /** `meta` key holding the trace/run id used to group buffered records. */
+  traceKey;
+  /** A record at or above this level elevates its whole trace. */
+  elevateAt;
+  /** Transports buffered records are flushed straight to on elevation; `undefined` disables tail-based elevation. */
+  transports;
+  /** Total buffered records allowed across every trace before the oldest trace is evicted. */
+  maxBufferedRecords;
+  /** Distinct trace ids held at once before the oldest is evicted. */
+  maxTraces;
+  rng;
+  buffer = /* @__PURE__ */ new Map();
+  bufferedCount = 0;
+  elevated = /* @__PURE__ */ new Set();
+  constructor(rate, options = {}) {
+    if (rate < 0 || rate > 1) {
+      throw new Error(`rate must be between 0 and 1, got ${String(rate)}`);
+    }
+    this.rate = rate;
+    this.rng = options.rng ?? Math.random;
+    this.traceKey = options.traceKey ?? "traceId";
+    this.elevateAt = parseLevel(options.elevateAt ?? 40 /* ERROR */);
+    this.transports = options.transports;
+    this.maxBufferedRecords = options.maxBufferedRecords ?? 1e3;
+    this.maxTraces = options.maxTraces ?? 200;
+  }
+  beforeLog(record) {
+    const transports = this.transports;
+    if (transports === void 0) {
+      return this.rng() < this.rate ? record : null;
+    }
+    const traceId = record.meta[this.traceKey];
+    if (traceId !== void 0 && this.elevated.has(traceId)) {
+      return record;
+    }
+    const keep = this.rng() < this.rate;
+    const reachedElevateLevel = parseLevel(record.level) >= this.elevateAt;
+    if (traceId !== void 0 && reachedElevateLevel) {
+      this.elevate(traceId, transports);
+      return record;
+    }
+    if (keep) {
+      return record;
+    }
+    if (traceId !== void 0) {
+      this.bufferRecord(traceId, record);
+    }
+    return null;
+  }
+  elevate(traceId, transports) {
+    this.elevated.add(traceId);
+    const buffered = this.buffer.get(traceId) ?? [];
+    this.buffer.delete(traceId);
+    this.bufferedCount -= buffered.length;
+    for (const bufferedRecord of buffered) {
+      for (const transport of transports) {
+        transport.write(transport.format(bufferedRecord), bufferedRecord);
+      }
+    }
+  }
+  bufferRecord(traceId, record) {
+    let records = this.buffer.get(traceId);
+    if (records) {
+      this.buffer.delete(traceId);
+      this.buffer.set(traceId, records);
+    } else {
+      if (this.buffer.size >= this.maxTraces) {
+        this.evictOldestTrace();
+      }
+      records = [];
+      this.buffer.set(traceId, records);
+    }
+    records.push(record);
+    this.bufferedCount += 1;
+    while (this.bufferedCount > this.maxBufferedRecords && this.buffer.size > 0) {
+      this.evictOldestTrace();
+    }
+  }
+  evictOldestTrace() {
+    const oldest = this.buffer.entries().next();
+    if (oldest.done) {
+      return;
+    }
+    const [oldestKey, oldestRecords] = oldest.value;
+    this.buffer.delete(oldestKey);
+    this.bufferedCount -= oldestRecords.length;
+  }
+};
+
+// src/transports/transport.ts
+var Transport = class {
+  /** Turns a `LogRecord` into the string this transport actually writes. Defaults to `JSONFormatter`. */
+  formatter;
+  constructor(formatter = new JSONFormatter()) {
+    this.formatter = formatter;
+  }
+  /** Formats `record` via `this.formatter`. Called once per record before `write()`. */
+  format(record) {
+    return this.formatter.format(record);
+  }
+  /** Flush/release resources on shutdown. No-op unless a transport overrides it. */
+  close() {
+  }
+};
+function hasFlush(transport) {
+  return typeof transport.flush === "function";
+}
+var CollectingTransport = class extends Transport {
+  /** Every formatted string passed to `write()`, in call order. */
+  formatted = [];
+  /** Every raw `LogRecord` passed to `write()`, in call order. */
+  records = [];
+  /** Set once `close()` has been called. */
+  closed = false;
+  write(formatted, record) {
+    this.formatted.push(formatted);
+    this.records.push(record);
+  }
+  close() {
+    this.closed = true;
+  }
+};
+
+// src/transports/console-transport.ts
+var COLORS = {
+  [5 /* TRACE */]: "\x1B[90m",
+  // gray
+  [10 /* DEBUG */]: "\x1B[36m",
+  // cyan
+  [20 /* INFO */]: "\x1B[32m",
+  // green
+  [30 /* WARN */]: "\x1B[33m",
+  // yellow
+  [40 /* ERROR */]: "\x1B[31m",
+  // red
+  [50 /* FATAL */]: "\x1B[35m"
+  // magenta
+};
+var RESET = "\x1B[0m";
+function defaultColorize() {
+  const env = typeof process === "undefined" ? void 0 : process.env;
+  return env?.NO_COLOR === void 0;
+}
+var ConsoleTransport = class extends Transport {
+  /** Whether each line is wrapped in an ANSI color escape for its level. */
+  colorize;
+  out;
+  constructor(options = {}) {
+    super(options.formatter);
+    this.colorize = options.colorize ?? defaultColorize();
+    this.out = options.console ?? console;
+  }
+  /** Writes `formatted` via `console.log`, or `console.error` for ERROR/FATAL records. */
+  write(formatted, record) {
+    const level = parseLevel(record.level);
+    const line = this.colorize ? this.applyColor(formatted, level) : formatted;
+    if (level >= 40 /* ERROR */) {
+      this.out.error(line);
+    } else {
+      this.out.log(line);
+    }
+  }
+  applyColor(formatted, level) {
+    return `${COLORS[level]}${formatted}${RESET}`;
+  }
+};
+
+// src/transports/beacon-transport.ts
+function defaultBeaconSender(url, batch) {
+  const body = batch.join("\n");
+  const nav = typeof navigator === "undefined" ? void 0 : navigator;
+  if (nav && typeof nav.sendBeacon === "function") {
+    nav.sendBeacon(url, body);
+    return;
+  }
+  void fetch(url, { method: "POST", body, keepalive: true }).catch((error) => {
+    console.error("BeaconTransport: failed to send log batch", error);
+  });
+}
+var BeaconTransport = class extends Transport {
+  /** Endpoint each batch is sent to. */
+  url;
+  /** Buffer is flushed once it holds this many lines. */
+  batchSize;
+  sender;
+  batch = [];
+  constructor(url, options = {}) {
+    super(options.formatter);
+    this.url = url;
+    this.batchSize = options.batchSize ?? 20;
+    this.sender = options.sender ?? defaultBeaconSender;
+  }
+  /** Buffers the formatted line, flushing the batch once `batchSize` is reached. */
+  write(formatted) {
+    this.batch.push(formatted);
+    if (this.batch.length >= this.batchSize) {
+      this.flush();
+    }
+  }
+  /** Send the current batch now, even if it hasn't reached `batchSize`. */
+  flush() {
+    if (this.batch.length === 0) {
+      return;
+    }
+    const batch = this.batch;
+    this.batch = [];
+    try {
+      this.sender(this.url, batch);
+    } catch (error) {
+      console.error("BeaconTransport: failed to send log batch", error);
+    }
+  }
+  close() {
+    this.flush();
+  }
+};
+
+// src/core/context-browser.ts
+var contextStack = [];
+function currentContext() {
+  return contextStack[contextStack.length - 1] ?? {};
+}
+
+// src/core/dispatch-queue.ts
+function isPromise(value) {
+  return typeof value === "object" && typeof value.then === "function";
+}
+function defaultScheduler(run) {
+  if (typeof setImmediate === "function") {
+    setImmediate(run);
+  } else {
+    queueMicrotask(run);
+  }
+}
+function defaultOnDrop(count, policy) {
+  console.warn(
+    `DispatchQueue: dropped ${String(count)} record(s) \u2014 queue exceeded its configured size under the "${policy}" backpressure policy`
+  );
+}
+var DispatchQueue = class {
+  /** Maximum number of pending tasks held at once, as configured via `DispatchQueueOptions`. */
+  maxSize;
+  /** Backpressure policy applied once `maxSize` is reached, as configured via `DispatchQueueOptions`. */
+  policy;
+  onDrop;
+  warnIntervalMs;
+  tasks = [];
+  draining = false;
+  scheduled = false;
+  idleWaiters = [];
+  droppedSinceWarning = 0;
+  lastWarnAt = 0;
+  constructor(options = {}) {
+    this.maxSize = options.maxSize ?? 1e4;
+    this.policy = options.policy ?? "dropOldest";
+    this.onDrop = options.onDrop ?? defaultOnDrop;
+    this.warnIntervalMs = options.warnIntervalMs ?? 5e3;
+  }
+  /** Number of tasks currently waiting to run. Bounded by `maxSize`. */
+  get size() {
+    return this.tasks.length;
+  }
+  /**
+   * Queue `task` to run outside the current call stack, applying the
+   * configured backpressure policy if the queue is already full. Under
+   * `"block"`, `task` may run synchronously before this call returns.
+   */
+  enqueue(task) {
+    if (this.tasks.length < this.maxSize) {
+      this.tasks.push(task);
+      this.schedule();
+      return;
+    }
+    switch (this.policy) {
+      case "dropNewest":
+        this.recordDrop();
+        return;
+      case "block":
+        this.runInline(task);
+        return;
+      case "dropOldest":
+      default:
+        this.tasks.shift();
+        this.recordDrop();
+        this.tasks.push(task);
+        this.schedule();
+        return;
+    }
+  }
+  /** Resolves once every task queued so far has run. Safe to call when idle. */
+  async flush() {
+    if (this.tasks.length === 0 && !this.draining) {
+      return;
+    }
+    await new Promise((resolve) => {
+      this.idleWaiters.push(resolve);
+      this.schedule();
+    });
+  }
+  recordDrop() {
+    this.droppedSinceWarning += 1;
+    const now = Date.now();
+    if (now - this.lastWarnAt >= this.warnIntervalMs) {
+      const count = this.droppedSinceWarning;
+      this.droppedSinceWarning = 0;
+      this.lastWarnAt = now;
+      try {
+        this.onDrop(count, this.policy);
+      } catch {
+      }
+    }
+  }
+  runInline(task) {
+    try {
+      const result = task();
+      if (isPromise(result)) {
+        result.catch((error) => {
+          console.error("DispatchQueue: a blocked task failed", error);
+        });
+      }
+    } catch (error) {
+      console.error("DispatchQueue: a blocked task failed", error);
+    }
+  }
+  schedule() {
+    if (this.scheduled) {
+      return;
+    }
+    this.scheduled = true;
+    defaultScheduler(() => {
+      this.scheduled = false;
+      void this.drainAll();
+    });
+  }
+  async drainAll() {
+    if (this.draining) {
+      return;
+    }
+    this.draining = true;
+    try {
+      while (this.tasks.length > 0) {
+        const task = this.tasks.shift();
+        if (!task) {
+          continue;
+        }
+        try {
+          await task();
+        } catch (error) {
+          console.error("DispatchQueue: a queued task failed", error);
+        }
+      }
+    } finally {
+      this.draining = false;
+      const waiters = this.idleWaiters;
+      this.idleWaiters = [];
+      for (const resolve of waiters) {
+        resolve();
+      }
+    }
+  }
+};
+
+// src/core/span-browser.ts
+var spanStack = [];
+function currentSpanId() {
+  return spanStack[spanStack.length - 1];
+}
+function newSpanId() {
+  const bytes = new Uint8Array(8);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function runInSpan(spanId, fn) {
+  spanStack.push(spanId);
+  let result;
+  try {
+    result = fn();
+  } catch (error) {
+    spanStack.pop();
+    throw error;
+  }
+  if (result instanceof Promise) {
+    return result.finally(() => spanStack.pop());
+  }
+  spanStack.pop();
+  return result;
+}
+
+// src/core/logger.ts
+function formatSpanError(error) {
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message}`;
+  }
+  return String(error);
+}
+function withStackFromErr(meta) {
+  const err = meta.err;
+  if (!(err instanceof Error)) {
+    return meta;
+  }
+  const next = { ...meta };
+  delete next.err;
+  next.stack = err.stack ?? `${err.name}: ${err.message}`;
+  return next;
+}
+var Logger = class _Logger {
+  /** This logger's name, as passed to the constructor (or derived via `.child()`). Appears on every record as `logger`. */
+  name;
+  /** Every transport a written record is sent to. */
+  transports;
+  /** Every plugin registered via `.use()`, in registration order. */
+  plugins;
+  currentLevel;
+  baseMeta;
+  dispatchQueue;
+  constructor(name, options = {}) {
+    this.name = name;
+    this.currentLevel = parseLevel(options.level ?? 20 /* INFO */);
+    this.transports = options.transports ? [...options.transports] : [];
+    this.plugins = [];
+    for (const plugin of options.plugins ?? []) {
+      this.use(plugin);
+    }
+    this.baseMeta = options.meta ? { ...options.meta } : {};
+    this.dispatchQueue = new DispatchQueue(options.queue);
+  }
+  /** This logger's current minimum level — records below it are filtered before any plugin runs. */
+  get level() {
+    return this.currentLevel;
+  }
+  /** Changes the minimum level records must meet to reach a transport. Accepts a `Level`, its numeric weight, or its name. */
+  setLevel(level) {
+    this.currentLevel = parseLevel(level);
+  }
+  /**
+   * Register a plugin, or a plain `beforeLog`-style function. A function is
+   * wrapped internally as an anonymous `Plugin` (`FunctionPlugin`) — the
+   * same middleware ergonomics as Express/Koa, without needing to read the
+   * `Plugin` interface first. Returns `this` so calls can be chained.
+   */
+  use(plugin) {
+    this.plugins.push(typeof plugin === "function" ? new FunctionPlugin(plugin) : plugin);
+    return this;
+  }
+  /** Number of dispatched records not yet written to their transports. Bounded by the `queue` option. */
+  get queueSize() {
+    return this.dispatchQueue.size;
+  }
+  /**
+   * Waits for every record dispatched so far to reach its transports'
+   * `write()` (and any plugin `afterLog` hooks). Note this does *not* force
+   * a batching transport (SQL, a queue, `HTTPTransport`, ...) to send a
+   * batch still under its own `maxRecords`/`maxBytes` threshold early — it
+   * only guarantees the record has been handed to that transport, the same
+   * contract `write()` always had. Before a process may pause or exit
+   * (a serverless freeze, a shutdown signal), prefer `withLambda`/
+   * `installShutdownHandlers`, which additionally force every batching
+   * transport to send its current buffer regardless of threshold.
+   */
+  async flush() {
+    await this.dispatchQueue.flush();
+  }
+  /** Flush every pending record, then close every attached transport. Call once, on shutdown. */
+  async close() {
+    await this.flush();
+    for (const transport of this.transports) {
+      transport.close();
+    }
+  }
+  /** A logger scoped under this one, inheriting its level, transports, plugins, and dispatch queue. */
+  child(name, meta = {}) {
+    const child = new _Logger(`${this.name}.${name}`, {
+      level: this.currentLevel,
+      transports: this.transports,
+      plugins: this.plugins,
+      meta: { ...this.baseMeta, ...meta }
+    });
+    child.dispatchQueue = this.dispatchQueue;
+    return child;
+  }
+  notifyError(plugin, error, record) {
+    try {
+      plugin.onError?.(error, record);
+    } catch {
+    }
+  }
+  dispatch(level, message, meta) {
+    if (level < this.currentLevel) {
+      return null;
+    }
+    let record = createRecord({
+      level,
+      logger: this.name,
+      message,
+      meta: { ...this.baseMeta, ...currentContext(), ...withStackFromErr(meta) }
+    });
+    const parentSpanId = currentSpanId();
+    if (parentSpanId !== void 0) {
+      record.meta.parentSpanId ??= parentSpanId;
+    }
+    for (const plugin of this.plugins) {
+      let result;
+      try {
+        result = plugin.beforeLog ? plugin.beforeLog(record) : record;
+      } catch (error) {
+        this.notifyError(plugin, error, record);
+        continue;
+      }
+      if (result === null) {
+        return null;
+      }
+      record = result;
+    }
+    this.dispatchQueue.enqueue(() => {
+      this.writeAndNotify(record);
+    });
+    return record;
+  }
+  writeAndNotify(record) {
+    for (const transport of this.transports) {
+      try {
+        transport.write(transport.format(record), record);
+      } catch (error) {
+        console.error(`${transport.constructor.name}: failed to write a log record`, error);
+      }
+    }
+    for (const plugin of this.plugins) {
+      try {
+        plugin.afterLog?.(record);
+      } catch (error) {
+        this.notifyError(plugin, error, record);
+      }
+    }
+  }
+  /** Logs at `TRACE` — the lowest level, for fine-grained diagnostic detail. Returns the record, or `null` if filtered/dropped. */
+  trace(message, meta = {}) {
+    return this.dispatch(5 /* TRACE */, message, meta);
+  }
+  /** Logs at `DEBUG`. Returns the record, or `null` if filtered/dropped. */
+  debug(message, meta = {}) {
+    return this.dispatch(10 /* DEBUG */, message, meta);
+  }
+  /** Logs at `INFO`. Returns the record, or `null` if filtered/dropped. */
+  info(message, meta = {}) {
+    return this.dispatch(20 /* INFO */, message, meta);
+  }
+  /** Logs at `WARN`. Returns the record, or `null` if filtered/dropped. */
+  warn(message, meta = {}) {
+    return this.dispatch(30 /* WARN */, message, meta);
+  }
+  /** Logs at `ERROR`. Returns the record, or `null` if filtered/dropped. */
+  error(message, meta = {}) {
+    return this.dispatch(40 /* ERROR */, message, meta);
+  }
+  /** Logs at `FATAL` — the highest level, for errors that precede an unrecoverable failure. Returns the record, or `null` if filtered/dropped. */
+  fatal(message, meta = {}) {
+    return this.dispatch(50 /* FATAL */, message, meta);
+  }
+  /** `.info()` tagged `meta.kind = "thought"` — an agent's internal reasoning step, for harness/agentic tracing. */
+  thought(message, meta = {}) {
+    return this.dispatch(20 /* INFO */, message, { kind: "thought", ...meta });
+  }
+  /** `.info()` tagged `meta.kind = "action"` — an agent taking an action (a tool call, an LLM request), for harness/agentic tracing. */
+  action(message, meta = {}) {
+    return this.dispatch(20 /* INFO */, message, { kind: "action", ...meta });
+  }
+  /** `.info()` tagged `meta.kind = "observation"` — the result an agent observed from an action, for harness/agentic tracing. */
+  observation(message, meta = {}) {
+    return this.dispatch(20 /* INFO */, message, { kind: "observation", ...meta });
+  }
+  /** `.info()` tagged `meta.kind = "decision"` — an agent's concluding decision for a step or run, for harness/agentic tracing. */
+  decision(message, meta = {}) {
+    return this.dispatch(20 /* INFO */, message, { kind: "decision", ...meta });
+  }
+  /**
+   * `await logger.span("callLlm", async () => {...})` — runs `fn`, and on
+   * settling (success or throw) emits one record for the span itself
+   * carrying `meta.spanId` and `meta.durationMs`. Every record logged
+   * inside `fn` — through any method, and through any further `await` —
+   * is automatically stamped with `meta.parentSpanId` pointing at this
+   * span, so nested/sub-agent calls reconstruct their exact nesting when
+   * sorted by `spanId`/`parentSpanId`.
+   *
+   * Still emits its record — at `ERROR`, with `meta.error` set — if `fn`
+   * throws; the error itself propagates unchanged to the caller.
+   *
+   * `spanId`/`parentSpanId` normally auto-generate/auto-nest; pass them in
+   * `options` to adopt an id handed in from elsewhere (e.g. a framework
+   * adapter translating an id it already received).
+   */
+  async span(name, fn, options = {}) {
+    const { spanId: explicitSpanId, parentSpanId: explicitParentSpanId, ...meta } = options;
+    const spanId = explicitSpanId ?? newSpanId();
+    const start = performance.now();
+    try {
+      const result = await runInSpan(spanId, () => fn());
+      this.finishSpan(name, spanId, explicitParentSpanId, performance.now() - start, meta);
+      return result;
+    } catch (error) {
+      this.finishSpan(name, spanId, explicitParentSpanId, performance.now() - start, meta, error);
+      throw error;
+    }
+  }
+  finishSpan(name, spanId, explicitParentSpanId, durationMs, meta, error) {
+    const fullMeta = {
+      spanId,
+      durationMs: Math.round(durationMs * 1e3) / 1e3,
+      ...meta
+    };
+    if (explicitParentSpanId !== void 0) {
+      fullMeta.parentSpanId = explicitParentSpanId;
+    }
+    fullMeta.kind ??= "span";
+    if (error !== void 0) {
+      fullMeta.error = formatSpanError(error);
+    }
+    this.dispatch(error !== void 0 ? 40 /* ERROR */ : 20 /* INFO */, name, fullMeta);
+  }
+};
+
+export { BeaconTransport, CollectingTransport, ConsoleTransport, ContextPlugin, DEFAULT_PII_PATTERNS, DEFAULT_REDACTED_KEYS, FunctionPlugin, JSONFormatter, Level, Logger, PIIRedactPlugin, RedactPlugin, SamplingPlugin, Transport, createRecord, hasFlush, levelName, parseLevel, utcTimestamp };
+//# sourceMappingURL=browser.mjs.map
+//# sourceMappingURL=browser.mjs.map