/**
 * The wire format spoken between the injected `@lensmcp/client-runtime`
 * and the bridge's WebSocket. Kept intentionally narrow — the client
 * runtime *only* emits these envelopes, never anything else.
 *
 * This type was originally owned by `@lensmcp/vite-plugin`; it moved here
 * when the bridge was decoupled from Vite so every host (webpack, Next.js,
 * no-build) shares one definition. The Vite plugin re-exports it for
 * backwards compatibility.
 */
export type ClientEnvelope = (
/**
 * An uncaught JS error (`window.onerror`). `message` is OPTIONAL because it
 * genuinely can be absent: a synthesised or cross-origin `ErrorEvent`
 * carries none, and 3 of the 7 real browser errors captured on foodguard
 * (2026-07-30) had no message at all. `name` is the constructor name of the
 * thrown value, which survives when a cross-origin policy strips the rest.
 */
{
    kind: 'error';
    at: number;
    message?: string;
    name?: string;
    stack?: string;
    source?: string;
    lineno?: number;
    colno?: number;
}
/**
 * A SUBRESOURCE that failed to load — `<img>`, `<script>`, `<link>`,
 * `<video>`. The browser delivers these through the SAME `error` listener as
 * an uncaught exception, but as a plain `Event`, not an `ErrorEvent`: no
 * message, no filename, no line. Its only identity is the target element and
 * its `src`/`href`, which the tap previously never read — so every one of
 * them serialised to a bare `{ kind: 'error', at, tabId }` and arrived
 * completely anonymous. Splitting the kind is what makes that identity
 * representable.
 */
 | {
    kind: 'resource-error';
    at: number;
    tagName: string;
    url?: string;
}
/**
 * An unhandled promise rejection. The reason is decomposed rather than
 * pre-stringified: a rejected non-Error object (`{ status: 401 }`, a
 * `Response`) used to be flattened by `String(reason)` into the useless
 * `"[object Object]"`.
 */
 | {
    kind: 'unhandledrejection';
    at: number;
    reason: string;
    name?: string;
    stack?: string;
} | {
    kind: 'console';
    at: number;
    level: 'log' | 'info' | 'warn' | 'error' | 'debug';
    args: unknown[];
} | {
    kind: 'fetch';
    at: number;
    method: string;
    url: string;
    status?: number;
    statusText?: string;
    durationMs?: number;
    ok?: boolean;
    error?: string;
} | {
    kind: 'route';
    at: number;
    url: string;
    from?: string;
} | {
    kind: 'ready';
    at: number;
    userAgent: string;
    url: string;
    /**
     * Why THIS document exists, when the previous one in the tab was thrown away by Vite: the
     * `vite:beforeFullReload` the runtime saw just before the reload, parked in `sessionStorage`
     * because the socket that saw it died with the page. Absent on a fresh navigation.
     */
    reloadCause?: {
        path?: string;
        triggeredBy?: string;
        at: number;
    };
}
/**
 * Vite's HMR channel as the PAGE sees it — the client-side events Vite emits on `import.meta.hot`.
 * This is what lets the lens answer "why did the page reload instead of hot-updating?" and "why
 * did the tab lose its dev server?": `full-reload` names the file Vite could not hot-update
 * (`triggeredBy`) and the path it reloaded for; `update` lists the modules that DID hot-update;
 * `invalidate` is a module giving up on self-acceptance; `ws-disconnect` / `ws-connect` are the
 * HMR socket itself — the "[vite] server connection lost" console line, as data. Without these the
 * lens was blind to ~320 full reloads a day on one workspace (issues/dev-gateway/08).
 */
 | {
    kind: 'hmr';
    at: number;
    event: 'full-reload' | 'update' | 'invalidate' | 'ws-disconnect' | 'ws-connect';
    /** `full-reload`: the reload path; `invalidate`: the invalidated module. */
    path?: string;
    /** `full-reload`: the changed file Vite could not hot-update (Vite ≥ 5.1). */
    triggeredBy?: string;
    /** `update`: the hot-updated module paths (bounded). */
    updates?: string[];
    /** `update`: how many updates the payload carried (before bounding). */
    count?: number;
    /** `invalidate`: Vite's reason. */
    message?: string;
}
/**
 * The tab's transport closed — its document is GONE.
 *
 * Synthesised by the BRIDGE on socket close, never sent by the page: the
 * failure this exists for is exactly the one a page cannot report. `ready`
 * comes from the injected client runtime, so a tab whose entry script failed
 * to load can never announce a document boundary — and under `ready`-only
 * retraction its error was immortal by construction.
 *
 * Measured on foodguard (2026-08-01): 38 retained browser errors across 26
 * DISTINCT tabs, none with more than two — 26 dead one-shot documents, 15 of
 * them the client script itself failing to load. `agent://current-status`
 * reported `failing` on all of it while the app served cleanly.
 */
 | {
    kind: 'gone';
    at: number;
} | {
    kind: 'publish';
    at: number;
    source: string;
    category: string;
    severity?: string;
    title: string;
    message?: string;
    fingerprint?: string;
    context?: Record<string, unknown>;
    raw?: unknown;
}
/**
 * A COALESCED frame: every envelope the page produced within one flush
 * window (a macrotask), in capture order. The client runtime batches so a
 * render storm costs ONE stringify + ONE socket frame scheduled OFF the
 * interaction task instead of hundreds inline in it — each inner event
 * still carries its own capture-time `at` (and `tabId`), so the recorded
 * timeline is unchanged; only where the transport work happens moves.
 */
 | {
    kind: 'batch';
    at: number;
    events: ClientEnvelope[];
}) & {
    /** Per-tab identity stamped by the client runtime (sessionStorage is per-tab) — keys `browser://tabs`. */
    tabId?: string;
};
/** A cross-process event sink: takes one normalised event and forwards it onward. */
export type EnvSink = (event: import('@lensmcp/protocol-types').BaseEvent) => void;