@e2edev/e2e 0.2.0

package/dist/internal/ai-trace.js

@@ -0,0 +1,360 @@
+/**
+ * AI trace recording for `e2e run --ai-trace`: every model round trip the
+ * run makes, in the AI SDK devtools database shape (`{ runs[], steps[] }`)
+ * that trace viewers such as unbox-ai already read.
+ *
+ * This is a debugging aid, not a report: the report stays the canonical
+ * record and the trace is written next to it only on request. The recorder
+ * is an AI SDK telemetry integration, so it sees the exact prompt, tool
+ * definitions, response, and usage of each generation — including calls a
+ * custom executor makes through its own `ai` import, because the SDK
+ * resolves registered integrations process-wide. What the model saw is
+ * already redacted and size-bounded by the observation pipeline, so the
+ * trace carries no secret the model could not have seen either.
+ *
+ * Attribution comes from an async-local scope the run layer enters per
+ * attempt and per step, so no model call site needs to know it is traced.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+/** Longest step label quoted in a run name before truncation. */
+const MAX_LABEL_CHARS = 80;
+const scopeStorage = new AsyncLocalStorage();
+/** Runs `work` with `scope` as the attribution for every model call inside. */
+export function withAiTraceScope(scope, work) {
+    return scopeStorage.run(scope, work);
+}
+/**
+ * Narrows the current attempt scope to one public API step. Outside an
+ * attempt scope there is nothing to narrow, and the work runs as is.
+ */
+export function withAiTraceStep(api, label, work) {
+    const parent = scopeStorage.getStore();
+    if (parent === undefined)
+        return work();
+    return scopeStorage.run({ ...parent, api, label }, work);
+}
+/** The scope of the calling async context, when inside an attempt. */
+function currentAiTraceScope() {
+    return scopeStorage.getStore();
+}
+/**
+ * Collects one process's model calls. Registered once with the AI SDK via
+ * `registerTelemetry`; `drain()` hands the completed records to the run
+ * layer, which ships them to the runner over the worker channel.
+ */
+export class AiTraceRecorder {
+    calls = new Map();
+    /**
+     * One run per agent step: every generation made under the same step scope
+     * — a `waitFor` poll, a judgment repair round — continues the step's run
+     * rather than starting its own, so a viewer's run list reads as the test's
+     * step list. Keyed by scope identity, which is fresh per step.
+     */
+    stepRuns = new WeakMap();
+    runs = [];
+    steps = [];
+    /**
+     * The tool a generation is being made from, carried by async context so
+     * tools that execute in parallel each see only their own ancestry.
+     */
+    toolAncestry = new AsyncLocalStorage();
+    disposed = false;
+    /** The integration object to hand to `registerTelemetry`. */
+    telemetry = {
+        onStart: (event) => this.onStart(event),
+        onStepStart: (event) => this.onStepStart(event),
+        onLanguageModelCallStart: (event) => this.onModelCallStart(event),
+        onLanguageModelCallEnd: (event) => this.onModelCallEnd(event),
+        onStepEnd: (event) => this.onStepEnd(event),
+        onEnd: (event) => this.onEnd(event),
+        onError: (event) => this.onError(event),
+        executeTool: ({ callId, execute }) => {
+            const state = this.calls.get(callId);
+            if (state === undefined)
+                return execute();
+            const open = [...state.openSteps.values()].at(-1);
+            return this.toolAncestry.run({ runId: state.runId, stepId: open?.id }, () => execute());
+        },
+    };
+    /**
+     * Stops recording. The SDK offers no unregister, so a disposed recorder
+     * simply ignores every later event; the entry it leaves in the global
+     * integration list is removed when that list is where the SDK keeps it.
+     */
+    dispose() {
+        this.disposed = true;
+        const registry = globalThis
+            .AI_SDK_TELEMETRY_INTEGRATIONS;
+        if (Array.isArray(registry)) {
+            const index = registry.indexOf(this.telemetry);
+            if (index >= 0)
+                registry.splice(index, 1);
+        }
+    }
+    /**
+     * Returns every run created and every step closed since the previous
+     * drain. Open steps stay until they close, so a step that finishes after a
+     * unit boundary is never reported half-written; `drain({ all: true })` at
+     * shutdown takes them as they are.
+     */
+    drain(options = {}) {
+        const snapshot = { runs: this.runs, steps: this.steps };
+        this.runs = [];
+        this.steps = [];
+        if (options.all === true) {
+            for (const state of this.calls.values()) {
+                for (const open of state.openSteps.values()) {
+                    snapshot.steps.push(this.closeStep(open, { error: 'run ended before the model answered' }));
+                }
+            }
+            this.calls.clear();
+        }
+        return snapshot;
+    }
+    /** True while any step has started and not yet ended; useful in tests. */
+    get pending() {
+        return [...this.calls.values()].some((state) => state.openSteps.size > 0);
+    }
+    onStart(event) {
+        if (this.disposed)
+            return;
+        if (event.operationId !== 'ai.generateText' && event.operationId !== 'ai.streamText')
+            return;
+        const parent = this.toolAncestry.getStore();
+        const scope = currentAiTraceScope();
+        // A generation made inside a tool is its own nested run, never a
+        // continuation of the step's run, so the parent link stays meaningful.
+        const stepScope = scope !== undefined && scope.api !== undefined && parent === undefined ? scope : undefined;
+        const existing = stepScope === undefined ? undefined : this.stepRuns.get(stepScope);
+        if (existing !== undefined) {
+            this.calls.set(event.callId, { runId: existing.runId, openSteps: new Map(), run: existing });
+            return;
+        }
+        const run = { runId: randomUUID(), steps: 0 };
+        if (stepScope !== undefined)
+            this.stepRuns.set(stepScope, run);
+        const runId = run.runId;
+        this.calls.set(event.callId, { runId, openSteps: new Map(), run });
+        this.runs.push({
+            id: runId,
+            started_at: new Date().toISOString(),
+            parent_run_id: parent?.runId ?? null,
+            parent_step_id: parent?.stepId ?? null,
+            function_id: runName(scope, event.functionId),
+            e2e: scope,
+        });
+    }
+    onStepStart(event) {
+        const state = this.calls.get(event.callId);
+        if (state === undefined)
+            return;
+        const stepNumber = state.run.steps;
+        state.run.steps += 1;
+        const open = {
+            id: randomUUID(),
+            runId: state.runId,
+            stepNumber,
+            modelId: event.modelId,
+            provider: event.provider,
+            startedAt: new Date().toISOString(),
+            startedMs: Date.now(),
+            prompt: promptMessages(event.instructions, event.messages),
+            tools: undefined,
+            toolChoice: event.toolChoice,
+            responseTimeMs: undefined,
+        };
+        state.openSteps.set(event.stepNumber, open);
+    }
+    /**
+     * The request as actually sent: after `prepareStep`, with the prepared tool
+     * definitions carrying their JSON schemas. This supersedes the step-start
+     * view, which predates per-step message compaction and tool filtering.
+     */
+    onModelCallStart(event) {
+        const open = this.newestOpen(event.callId);
+        if (open === undefined)
+            return;
+        if (Array.isArray(event.messages)) {
+            open.prompt = promptMessages(event.instructions, event.messages);
+        }
+        if (event.tools !== undefined) {
+            open.tools = event.tools.map((tool) => ({
+                name: tool['name'],
+                ...(tool['description'] === undefined ? {} : { description: tool['description'] }),
+                ...(tool['inputSchema'] === undefined ? {} : { parameters: tool['inputSchema'] }),
+            }));
+        }
+        if (event.toolChoice !== undefined)
+            open.toolChoice = event.toolChoice;
+    }
+    onModelCallEnd(event) {
+        const open = this.newestOpen(event.callId);
+        if (open === undefined)
+            return;
+        const responseTimeMs = event.performance?.responseTimeMs;
+        if (typeof responseTimeMs === 'number')
+            open.responseTimeMs = responseTimeMs;
+    }
+    onStepEnd(event) {
+        const state = this.calls.get(event.callId);
+        const open = state?.openSteps.get(event.stepNumber);
+        if (state === undefined || open === undefined)
+            return;
+        state.openSteps.delete(event.stepNumber);
+        const response = event.response;
+        this.steps.push(this.closeStep(open, {
+            output: {
+                content: event.content,
+                finishReason: event.finishReason,
+                response: {
+                    id: response.id,
+                    modelId: response.modelId,
+                    timestamp: response.timestamp,
+                    messages: response.messages,
+                },
+                ...(event.providerMetadata === undefined ? {} : { providerMetadata: event.providerMetadata }),
+            },
+            usage: event.usage,
+        }));
+    }
+    onEnd(event) {
+        const state = this.calls.get(event.callId);
+        if (state === undefined)
+            return;
+        // Steps that never reported an end (aborted mid-flight) close here so
+        // nothing dangles once the generation itself is over.
+        for (const open of state.openSteps.values()) {
+            this.steps.push(this.closeStep(open, { error: 'the generation ended before this step did' }));
+        }
+        this.calls.delete(event.callId);
+    }
+    onError(event) {
+        const callId = event?.callId;
+        if (callId === undefined)
+            return;
+        const state = this.calls.get(callId);
+        if (state === undefined)
+            return;
+        const cause = event?.error;
+        const message = cause instanceof Error ? cause.message : String(cause ?? 'unknown error');
+        for (const open of state.openSteps.values()) {
+            this.steps.push(this.closeStep(open, { error: message }));
+        }
+        this.calls.delete(callId);
+    }
+    newestOpen(callId) {
+        const state = this.calls.get(callId);
+        if (state === undefined)
+            return undefined;
+        return [...state.openSteps.values()].at(-1);
+    }
+    closeStep(open, outcome) {
+        return {
+            id: open.id,
+            run_id: open.runId,
+            step_number: open.stepNumber + 1,
+            type: 'generate',
+            model_id: open.modelId,
+            provider: open.provider,
+            started_at: open.startedAt,
+            duration_ms: open.responseTimeMs ?? Date.now() - open.startedMs,
+            input: stringify({
+                prompt: open.prompt,
+                ...(open.tools === undefined ? {} : { tools: open.tools }),
+                ...(open.toolChoice === undefined ? {} : { toolChoice: open.toolChoice }),
+            }),
+            output: outcome.output === undefined ? null : stringify(outcome.output),
+            usage: outcome.usage === undefined ? null : stringify(outcome.usage),
+            error: outcome.error ?? null,
+        };
+    }
+}
+/**
+ * Registers a recorder with the AI SDK. The SDK is an optional peer: when it
+ * is absent no model call can go through it, so there is nothing to record
+ * and the absence is not an error here.
+ */
+export async function registerAiTraceRecorder(recorder, load) {
+    let sdk;
+    try {
+        sdk = await load();
+    }
+    catch {
+        return;
+    }
+    sdk.registerTelemetry(recorder.telemetry);
+}
+/** Merges drained snapshots into one document; call order is arrival order. */
+export class AiTraceCollector {
+    runs = [];
+    steps = [];
+    merge(snapshot) {
+        this.runs.push(...snapshot.runs);
+        this.steps.push(...snapshot.steps);
+    }
+    /**
+     * The document to write. Workers drain in batches, so records are put back
+     * in start order: viewers read file order as time order.
+     */
+    document() {
+        const byStart = (a, b) => a.started_at < b.started_at ? -1 : a.started_at > b.started_at ? 1 : 0;
+        return {
+            runs: this.runs.toSorted(byStart),
+            steps: this.steps.toSorted(byStart),
+        };
+    }
+    get size() {
+        return this.steps.length;
+    }
+}
+/**
+ * The prompt as a message list. The SDK keeps the system prompt apart from
+ * the conversation (`instructions`); viewers attribute tokens per message
+ * role, so it is put back in front as system messages.
+ */
+function promptMessages(instructions, messages) {
+    const system = [];
+    if (typeof instructions === 'string') {
+        system.push({ role: 'system', content: instructions });
+    }
+    else if (Array.isArray(instructions)) {
+        system.push(...instructions);
+    }
+    else if (instructions !== undefined && instructions !== null) {
+        system.push(instructions);
+    }
+    return [...system, ...messages];
+}
+function runName(scope, functionId) {
+    if (scope === undefined)
+        return functionId ?? null;
+    const parts = [scope.test];
+    if (scope.attempt > 0)
+        parts.push(`attempt ${scope.attempt + 1}`);
+    if (scope.api !== undefined) {
+        const label = scope.label === undefined || scope.label === '' ? '' : ` ${JSON.stringify(truncate(scope.label))}`;
+        parts.push(`${scope.api}${label}`);
+    }
+    return parts.join(' · ');
+}
+function truncate(text) {
+    return text.length <= MAX_LABEL_CHARS ? text : `${text.slice(0, MAX_LABEL_CHARS)}…`;
+}
+/**
+ * JSON with binary payloads replaced by a size note. Image evidence travels
+ * as bytes in vision calls; the trace records that pixels were sent and how
+ * many, never the pixels, which keeps the file small and screenshot-free.
+ */
+export function stringify(value) {
+    return JSON.stringify(value, (_key, current) => {
+        if (current instanceof ArrayBuffer)
+            return `[binary ${current.byteLength} bytes omitted]`;
+        if (ArrayBuffer.isView(current))
+            return `[binary ${current.byteLength} bytes omitted]`;
+        if (typeof current === 'bigint')
+            return current.toString();
+        return current;
+    });
+}
+//# sourceMappingURL=ai-trace.js.map

package/dist/internal/ai-trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-trace.js","sourceRoot":"","sources":["../../src/internal/ai-trace.ts"],"names":[],"mappings":"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"}

package/dist/internal/brands.d.ts

@@ -0,0 +1,9 @@
+/** Internal brand symbols backing the opaque spec types. */
+export declare const secretBrand: unique symbol;
+export declare const credentialBrand: unique symbol;
+export declare const testCaseBrand: unique symbol;
+export declare const backendBrand: unique symbol;
+export declare const locatorBrand: unique symbol;
+/** Slot under which a fixture carries its attached expectation surface. */
+export declare const expectationBrand: unique symbol;
+//# sourceMappingURL=brands.d.ts.map

package/dist/internal/brands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brands.d.ts","sourceRoot":"","sources":["../../src/internal/brands.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAE5D,eAAO,MAAM,WAAW,EAAE,OAAO,MAAiC,CAAC;AACnE,eAAO,MAAM,eAAe,EAAE,OAAO,MAAqC,CAAC;AAC3E,eAAO,MAAM,aAAa,EAAE,OAAO,MAAmC,CAAC;AACvE,eAAO,MAAM,YAAY,EAAE,OAAO,MAAqC,CAAC;AACxE,eAAO,MAAM,YAAY,EAAE,OAAO,MAAkC,CAAC;AACrE,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAAyC,CAAC"}

package/dist/internal/brands.js

@@ -0,0 +1,9 @@
+/** Internal brand symbols backing the opaque spec types. */
+export const secretBrand = Symbol.for('e2e.secret');
+export const credentialBrand = Symbol.for('e2e.credential');
+export const testCaseBrand = Symbol.for('e2e.testCase');
+export const backendBrand = Symbol.for('e2e.backend.v1');
+export const locatorBrand = Symbol.for('e2e.locator');
+/** Slot under which a fixture carries its attached expectation surface. */
+export const expectationBrand = Symbol.for('e2e.expectation.v1');
+//# sourceMappingURL=brands.js.map

package/dist/internal/brands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brands.js","sourceRoot":"","sources":["../../src/internal/brands.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAE5D,MAAM,CAAC,MAAM,WAAW,GAAkB,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,eAAe,GAAkB,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AAC3E,MAAM,CAAC,MAAM,aAAa,GAAkB,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AACvE,MAAM,CAAC,MAAM,YAAY,GAAkB,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AACxE,MAAM,CAAC,MAAM,YAAY,GAAkB,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;AACrE,2EAA2E;AAC3E,MAAM,CAAC,MAAM,gBAAgB,GAAkB,MAAM,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC"}

package/dist/internal/debug.d.ts

@@ -0,0 +1,43 @@
+/** Opt-in phase timing collection for `e2e run --debug`. */
+interface DebugEntry {
+    totalMs: number;
+    count: number;
+    maxMs: number;
+}
+/** One aggregated phase, JSON-serializable so workers can ship it over IPC. */
+export interface DebugEntrySnapshot extends DebugEntry {
+    readonly label: string;
+}
+/** Everything one trace collected, JSON-serializable for the worker channel. */
+export interface DebugSnapshot {
+    readonly entries: readonly DebugEntrySnapshot[];
+}
+/**
+ * Aggregates named phase durations for one run. When disabled every method is
+ * a near-zero pass-through, so call sites never need to branch.
+ */
+export declare class DebugTrace {
+    readonly enabled: boolean;
+    private readonly entries;
+    private readonly startedMs;
+    constructor(enabled: boolean);
+    /** Records one completed phase duration under a label. */
+    record(label: string, durationMs: number): void;
+    /** Times one async phase and records it, rethrowing any failure. */
+    time<T>(label: string, work: () => Promise<T>): Promise<T>;
+    /** Returns everything recorded so far and resets, for transport to another trace. */
+    drain(): DebugSnapshot;
+    /** Folds a drained snapshot from another trace into this one. */
+    merge(snapshot: DebugSnapshot): void;
+    /** Formats aggregated timings as one aligned table, phases sorted by total time. */
+    summary(): string;
+}
+/**
+ * Renders one aligned table. The first column is left-aligned and the rest are
+ * right-aligned, which suits numbers; `leftAligned` names any further columns
+ * that hold prose and would be unreadable pushed to the right.
+ */
+export declare function table(title: string, header: readonly string[], rows: readonly (readonly string[])[], empty: string, leftAligned?: ReadonlySet<number>): string;
+export declare function formatMs(value: number): string;
+export {};
+//# sourceMappingURL=debug.d.ts.map

package/dist/internal/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/internal/debug.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAE5D,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,+EAA+E;AAC/E,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACjD;AAED;;;GAGG;AACH,qBAAa,UAAU;IAIT,QAAQ,CAAC,OAAO,EAAE,OAAO;IAHrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IAExC,YAAqB,OAAO,EAAE,OAAO,EAAI;IAEzC,0DAA0D;IAC1D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAU9C;IAED,oEAAoE;IAC9D,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAQ/D;IAED,qFAAqF;IACrF,KAAK,IAAI,aAAa,CAMrB;IAED,iEAAiE;IACjE,KAAK,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAgBnC;IAED,oFAAoF;IACpF,OAAO,IAAI,MAAM,CAgBhB;CACF;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CACnB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,IAAI,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,EACpC,KAAK,EAAE,MAAM,EACb,WAAW,GAAE,WAAW,CAAC,MAAM,CAAa,GAC3C,MAAM,CAeR;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG9C"}

package/dist/internal/debug.js

@@ -0,0 +1,102 @@
+/** Opt-in phase timing collection for `e2e run --debug`. */
+/**
+ * Aggregates named phase durations for one run. When disabled every method is
+ * a near-zero pass-through, so call sites never need to branch.
+ */
+export class DebugTrace {
+    enabled;
+    entries = new Map();
+    startedMs = Date.now();
+    constructor(enabled) {
+        this.enabled = enabled;
+    }
+    /** Records one completed phase duration under a label. */
+    record(label, durationMs) {
+        if (!this.enabled)
+            return;
+        const entry = this.entries.get(label);
+        if (entry === undefined) {
+            this.entries.set(label, { totalMs: durationMs, count: 1, maxMs: durationMs });
+            return;
+        }
+        entry.totalMs += durationMs;
+        entry.count += 1;
+        if (durationMs > entry.maxMs)
+            entry.maxMs = durationMs;
+    }
+    /** Times one async phase and records it, rethrowing any failure. */
+    async time(label, work) {
+        if (!this.enabled)
+            return work();
+        const started = Date.now();
+        try {
+            return await work();
+        }
+        finally {
+            this.record(label, Date.now() - started);
+        }
+    }
+    /** Returns everything recorded so far and resets, for transport to another trace. */
+    drain() {
+        const snapshot = {
+            entries: [...this.entries.entries()].map(([label, entry]) => ({ label, ...entry })),
+        };
+        this.entries.clear();
+        return snapshot;
+    }
+    /** Folds a drained snapshot from another trace into this one. */
+    merge(snapshot) {
+        if (!this.enabled)
+            return;
+        for (const incoming of snapshot.entries) {
+            const entry = this.entries.get(incoming.label);
+            if (entry === undefined) {
+                this.entries.set(incoming.label, {
+                    totalMs: incoming.totalMs,
+                    count: incoming.count,
+                    maxMs: incoming.maxMs,
+                });
+                continue;
+            }
+            entry.totalMs += incoming.totalMs;
+            entry.count += incoming.count;
+            if (incoming.maxMs > entry.maxMs)
+                entry.maxMs = incoming.maxMs;
+        }
+    }
+    /** Formats aggregated timings as one aligned table, phases sorted by total time. */
+    summary() {
+        const rows = [...this.entries.entries()]
+            .toSorted((left, right) => right[1].totalMs - left[1].totalMs)
+            .map(([label, entry]) => [
+            label,
+            String(entry.count),
+            formatMs(entry.totalMs),
+            formatMs(entry.totalMs / entry.count),
+            formatMs(entry.maxMs),
+        ]);
+        return table(`[e2e debug] phase timings (wall ${formatMs(Date.now() - this.startedMs)})`, ['phase', 'count', 'total', 'avg', 'max'], rows, '(no phases recorded)');
+    }
+}
+/**
+ * Renders one aligned table. The first column is left-aligned and the rest are
+ * right-aligned, which suits numbers; `leftAligned` names any further columns
+ * that hold prose and would be unreadable pushed to the right.
+ */
+export function table(title, header, rows, empty, leftAligned = new Set()) {
+    const widths = header.map((label, column) => Math.max(label.length, ...rows.map((row) => row[column]?.length ?? 0)));
+    const line = (row) => `  ${row
+        .map((cell, column) => column === 0 || leftAligned.has(column)
+        ? cell.padEnd(widths[column] ?? 0)
+        : cell.padStart(widths[column] ?? 0))
+        .join('  ')
+        .trimEnd()}`;
+    const body = rows.length === 0 ? [`  ${empty}`] : rows.map(line);
+    return [title, line(header), ...body, ''].join('\n');
+}
+export function formatMs(value) {
+    if (value >= 10_000)
+        return `${(value / 1000).toFixed(1)}s`;
+    return `${Math.round(value)}ms`;
+}
+//# sourceMappingURL=debug.js.map

package/dist/internal/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../src/internal/debug.ts"],"names":[],"mappings":"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"}