lograil 0.1.0

package/dist/cjs/plugin/manager.d.ts

@@ -0,0 +1,38 @@
+import type { LogEntry } from '../types.js';
+import type { Transport } from '../transport/transport.js';
+import type { Plugin, PluginContext } from './plugin.js';
+/**
+ * Manages plugin registration and lifecycle. The logger delegates entry
+ * interception and transport registration to this manager.
+ */
+export declare class PluginManager {
+    private plugins;
+    private host;
+    /** Count of plugins with an `onEntry` hook; gates the async intercept path. */
+    private entryInterceptors;
+    /**
+     * Error sink for a plugin's `onEntry` hook. A throwing hook must never drop
+     * the entry silently or crash logging; the error is reported and the entry
+     * proceeds unchanged.
+     */
+    onError?: (pluginName: string, err: unknown, entry: LogEntry) => void;
+    constructor(host: PluginContext);
+    register(plugin: Plugin): Promise<void>;
+    /** Unregister a plugin by name. Its `onDestroy` hook (if any) is invoked. */
+    unregister(name: string): void;
+    has(name: string): boolean;
+    /** True when at least one plugin can intercept entries via `onEntry`. */
+    hasEntryInterceptors(): boolean;
+    /**
+     * Notify plugins that a transport was added (so `onTransport` hooks run).
+     * Called by the logger's `addTransport`.
+     */
+    notifyTransport(transport: Transport): void;
+    /**
+     * Run every plugin's `onEntry` hook in registration order. A plugin may
+     * return `null` to drop the entry, or a modified entry to pass downstream.
+     */
+    intercept(entry: LogEntry): Promise<LogEntry | null>;
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/cjs/plugin/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../src/plugin/manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEzD;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,IAAI,CAAgB;IAC5B,+EAA+E;IAC/E,OAAO,CAAC,iBAAiB,CAAK;IAC9B;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;gBAE1D,IAAI,EAAE,aAAa;IAIzB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7C,6EAA6E;IAC7E,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAQ9B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,yEAAyE;IACzE,oBAAoB,IAAI,OAAO;IAI/B;;;OAGG;IACH,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAM3C;;;OAGG;IACG,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAgBpD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAM/B"}

package/dist/cjs/plugin/manager.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginManager = void 0;
+/**
+ * Manages plugin registration and lifecycle. The logger delegates entry
+ * interception and transport registration to this manager.
+ */
+class PluginManager {
+    constructor(host) {
+        this.plugins = new Map();
+        /** Count of plugins with an `onEntry` hook; gates the async intercept path. */
+        this.entryInterceptors = 0;
+        this.host = host;
+    }
+    async register(plugin) {
+        if (this.plugins.has(plugin.name)) {
+            throw new Error(`Plugin already registered: ${plugin.name}`);
+        }
+        this.plugins.set(plugin.name, plugin);
+        if (plugin.onEntry)
+            this.entryInterceptors++;
+        await plugin.onInit?.(this.host);
+    }
+    /** Unregister a plugin by name. Its `onDestroy` hook (if any) is invoked. */
+    unregister(name) {
+        const plugin = this.plugins.get(name);
+        if (!plugin)
+            return;
+        if (plugin.onEntry)
+            this.entryInterceptors--;
+        this.plugins.delete(name);
+        void plugin.onDestroy?.();
+    }
+    has(name) {
+        return this.plugins.has(name);
+    }
+    /** True when at least one plugin can intercept entries via `onEntry`. */
+    hasEntryInterceptors() {
+        return this.entryInterceptors > 0;
+    }
+    /**
+     * Notify plugins that a transport was added (so `onTransport` hooks run).
+     * Called by the logger's `addTransport`.
+     */
+    notifyTransport(transport) {
+        for (const plugin of this.plugins.values()) {
+            plugin.onTransport?.(transport);
+        }
+    }
+    /**
+     * Run every plugin's `onEntry` hook in registration order. A plugin may
+     * return `null` to drop the entry, or a modified entry to pass downstream.
+     */
+    async intercept(entry) {
+        let current = entry;
+        for (const plugin of this.plugins.values()) {
+            if (!current)
+                break;
+            if (plugin.onEntry) {
+                try {
+                    current = await plugin.onEntry(current);
+                }
+                catch (err) {
+                    this.onError?.(plugin.name, err, entry);
+                    // Keep the entry as-is; a faulty plugin must not drop or mutate it.
+                }
+            }
+        }
+        return current;
+    }
+    async destroy() {
+        for (const plugin of this.plugins.values()) {
+            await plugin.onDestroy?.();
+        }
+        this.plugins.clear();
+    }
+}
+exports.PluginManager = PluginManager;
+//# sourceMappingURL=manager.js.map

package/dist/cjs/plugin/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../../src/plugin/manager.ts"],"names":[],"mappings":";;;AAIA;;;GAGG;AACH,MAAa,aAAa;IAYxB,YAAY,IAAmB;QAXvB,YAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;QAE5C,+EAA+E;QACvE,sBAAiB,GAAG,CAAC,CAAC;QAS5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,MAAc;QAC3B,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,8BAA8B,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACtC,IAAI,MAAM,CAAC,OAAO;YAAE,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC7C,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,6EAA6E;IAC7E,UAAU,CAAC,IAAY;QACrB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,IAAI,MAAM,CAAC,OAAO;YAAE,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC7C,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1B,KAAK,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;IAC5B,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,yEAAyE;IACzE,oBAAoB;QAClB,OAAO,IAAI,CAAC,iBAAiB,GAAG,CAAC,CAAC;IACpC,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,SAAoB;QAClC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YAC3C,MAAM,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,SAAS,CAAC,KAAe;QAC7B,IAAI,OAAO,GAAoB,KAAK,CAAC;QACrC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YAC3C,IAAI,CAAC,OAAO;gBAAE,MAAM;YACpB,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBACnB,IAAI,CAAC;oBACH,OAAO,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;gBAC1C,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,IAAI,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;oBACxC,oEAAoE;gBACtE,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,OAAO;QACX,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YAC3C,MAAM,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;QAC7B,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;CACF;AA/ED,sCA+EC"}

package/dist/cjs/plugin/otel-trace.d.ts

@@ -0,0 +1,19 @@
+import type { Plugin } from './plugin.js';
+/**
+ * Plugin that injects the active OpenTelemetry trace/span identifiers into each
+ * entry's `metadata` (`traceId` / `spanId`), so an `OtlpTransport` (or any
+ * backend that reads those fields) can correlate logs with their span without
+ * you having to thread the context manually.
+ *
+ * `@opentelemetry/api` is an **optional** peer dependency: if it isn't installed,
+ * or no span is active, the plugin is a no-op and entries are unaffected. Load
+ * it once via `logger.use(createOtelTracePlugin())`.
+ *
+ * @example
+ * import { trace } from '@opentelemetry/api';
+ * const span = tracer.startSpan('op');
+ * trace.setSpan(context.active(), span);
+ * logger.info('inside span'); // => metadata: { traceId, spanId }
+ */
+export declare function createOtelTracePlugin(): Plugin;
+//# sourceMappingURL=otel-trace.d.ts.map

package/dist/cjs/plugin/otel-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-trace.d.ts","sourceRoot":"","sources":["../../../src/plugin/otel-trace.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAW1C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAgC9C"}

package/dist/cjs/plugin/otel-trace.js

@@ -0,0 +1,91 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOtelTracePlugin = createOtelTracePlugin;
+/**
+ * Plugin that injects the active OpenTelemetry trace/span identifiers into each
+ * entry's `metadata` (`traceId` / `spanId`), so an `OtlpTransport` (or any
+ * backend that reads those fields) can correlate logs with their span without
+ * you having to thread the context manually.
+ *
+ * `@opentelemetry/api` is an **optional** peer dependency: if it isn't installed,
+ * or no span is active, the plugin is a no-op and entries are unaffected. Load
+ * it once via `logger.use(createOtelTracePlugin())`.
+ *
+ * @example
+ * import { trace } from '@opentelemetry/api';
+ * const span = tracer.startSpan('op');
+ * trace.setSpan(context.active(), span);
+ * logger.info('inside span'); // => metadata: { traceId, spanId }
+ */
+function createOtelTracePlugin() {
+    let traceApi;
+    return {
+        name: 'otel-trace',
+        async onInit() {
+            try {
+                // Lazy, optional resolution — never fails if the package is absent.
+                // The specifier is held in a variable so TypeScript does not try to
+                // resolve the (optional) module at compile time.
+                const specifier = '@opentelemetry/api';
+                const mod = (await Promise.resolve(`${specifier}`).then(s => __importStar(require(s))));
+                traceApi = mod.trace;
+            }
+            catch {
+                traceApi = undefined;
+            }
+        },
+        onEntry(entry) {
+            if (!traceApi)
+                return entry;
+            const span = traceApi.getActiveSpan();
+            if (!span)
+                return entry;
+            // Some tracer implementations return a span object without a
+            // `spanContext` method; tolerate that instead of throwing on the hot
+            // path.
+            if (typeof span.spanContext !== 'function')
+                return entry;
+            const ctx = span.spanContext();
+            if (!ctx)
+                return entry;
+            return {
+                ...entry,
+                metadata: { ...entry.metadata, traceId: ctx.traceId, spanId: ctx.spanId },
+            };
+        },
+    };
+}
+//# sourceMappingURL=otel-trace.js.map

package/dist/cjs/plugin/otel-trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-trace.js","sourceRoot":"","sources":["../../../src/plugin/otel-trace.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,sDAgCC;AAhDD;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,qBAAqB;IACnC,IAAI,QAAkC,CAAC;IACvC,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,KAAK,CAAC,MAAM;YACV,IAAI,CAAC;gBACH,oEAAoE;gBACpE,oEAAoE;gBACpE,iDAAiD;gBACjD,MAAM,SAAS,GAAG,oBAAoB,CAAC;gBACvC,MAAM,GAAG,GAAG,CAAC,yBAAa,SAAS,uCAAC,CAAwC,CAAC;gBAC7E,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC;YACvB,CAAC;YAAC,MAAM,CAAC;gBACP,QAAQ,GAAG,SAAS,CAAC;YACvB,CAAC;QACH,CAAC;QACD,OAAO,CAAC,KAAe;YACrB,IAAI,CAAC,QAAQ;gBAAE,OAAO,KAAK,CAAC;YAC5B,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,EAAE,CAAC;YACtC,IAAI,CAAC,IAAI;gBAAE,OAAO,KAAK,CAAC;YACxB,6DAA6D;YAC7D,qEAAqE;YACrE,QAAQ;YACR,IAAI,OAAO,IAAI,CAAC,WAAW,KAAK,UAAU;gBAAE,OAAO,KAAK,CAAC;YACzD,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;YAC/B,IAAI,CAAC,GAAG;gBAAE,OAAO,KAAK,CAAC;YACvB,OAAO;gBACL,GAAG,KAAK;gBACR,QAAQ,EAAE,EAAE,GAAG,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE;aAC1E,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/cjs/plugin/plugin.d.ts

@@ -0,0 +1,41 @@
+import type { LogEntry } from '../types.js';
+import type { Transport } from '../transport/transport.js';
+import type { Pipeline } from '../pipeline/pipeline.js';
+import type { Logger } from '../core/logger.js';
+/**
+ * A Plugin extends the logger's behavior through lifecycle hooks. All hooks
+ * are optional. A plugin that needs to transform entries should implement
+ * `onEntry`, returning the (possibly new) entry or `null` to drop it.
+ */
+export interface Plugin {
+    /** Unique plugin name. */
+    readonly name: string;
+    /** Called once when the plugin is registered (or via `ctx.use`). */
+    onInit?(ctx: PluginContext): void | Promise<void>;
+    /** Called for every entry before it reaches the pipeline's formatter. */
+    onEntry?(entry: LogEntry): LogEntry | null | Promise<LogEntry | null>;
+    /** Called when a transport is added (incl. by other plugins). */
+    onTransport?(transport: Transport): void;
+    /** Called when the plugin is unregistered or the logger is destroyed. */
+    onDestroy?(): void | Promise<void>;
+}
+/**
+ * Capabilities handed to a plugin so it can reconfigure the logger at runtime.
+ * This is the bridge that lets plugins dynamically add/remove transports,
+ * reshape the processing pipeline, and even register/unregister other plugins.
+ */
+export interface PluginContext {
+    /** Add a transport at runtime. */
+    addTransport(transport: Transport): void;
+    /** Remove a transport by name. */
+    removeTransport(name: string): void;
+    /** The processing pipeline — add/remove filters & processors, change the formatter. */
+    pipeline: Pipeline;
+    /** Register another plugin at runtime. */
+    use(plugin: Plugin): Promise<void>;
+    /** Unregister a plugin by name. */
+    unregisterPlugin(name: string): void;
+    /** The owning logger (e.g. to call `setLevel`). */
+    logger: Logger;
+}
+//# sourceMappingURL=plugin.d.ts.map

package/dist/cjs/plugin/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/plugin/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,MAAM,CAAC,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,yEAAyE;IACzE,OAAO,CAAC,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IACtE,iEAAiE;IACjE,WAAW,CAAC,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IACzC,yEAAyE;IACzE,SAAS,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IACzC,kCAAkC;IAClC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,uFAAuF;IACvF,QAAQ,EAAE,QAAQ,CAAC;IACnB,0CAA0C;IAC1C,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,mCAAmC;IACnC,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/dist/cjs/plugin/plugin.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=plugin.js.map

package/dist/cjs/plugin/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../../src/plugin/plugin.ts"],"names":[],"mappings":""}

package/dist/cjs/runtime/adapter.d.ts

@@ -0,0 +1,81 @@
+import type { Transport } from '../transport/transport.js';
+import type { LogEntry } from '../types.js';
+/**
+ * Supported runtime environments:
+ *  - `web`       : browsers, no filesystem / process id.
+ *  - `node`      : plain Node.js (CLI / server), has filesystem and process id.
+ *  - `electron`  : Electron, further differentiated by {@link processType}.
+ */
+export type RuntimeName = 'web' | 'node' | 'electron';
+/**
+ * For Electron, whether we run in the main process (owns the filesystem) or a
+ * renderer process (sandboxed, console only by default).
+ */
+export type ElectronProcessType = 'main' | 'renderer';
+/** Callback that feeds a received entry back into a logger. */
+export type IngestFn = (entry: LogEntry) => void;
+/**
+ * Host lifecycle hooks. A runtime implements these to tell the logger *when*
+ * it should flush pending entries before the host goes away (process exit,
+ * page unload, app quit) and *when* a fatal, uncaught host error occurs.
+ *
+ * The logger supplies the actual flush/fatal behaviour (and its timeout
+ * safety); the runtime owns the trigger and any host-specific exit semantics
+ * (e.g. `process.exit` on a signal, or simply letting the browser unload).
+ * This keeps {@link Logger} runtime-agnostic — it never references `process`
+ * or `window` directly.
+ */
+export interface LifecycleHooks {
+    /**
+     * Register `cb` to run when the host is about to exit/close. The runtime
+     * decides the actual trigger (Node/Electron `process` `beforeExit`/signals,
+     * Web `pagehide`/`visibilitychange`, Electron `app` `before-quit`) and owns
+     * any `process.exit()` it needs. Returns an unregister function; a no-op
+     * host returns a no-op detach.
+     */
+    onFlushBeforeExit(cb: () => void | Promise<void>): () => void;
+    /**
+     * Register `cb` for fatal, uncaught host errors (Node/Electron
+     * `uncaughtException` / `unhandledRejection`). Optional — omit it on runtimes
+     * with no such concept (e.g. web). Returns an unregister function.
+     */
+    onUncaughtError?(cb: (err: unknown) => void): () => void;
+}
+/**
+ * RuntimeAdapter isolates differences between the Web, Node.js and Electron
+ * environments: time source, process id, filesystem availability and the set
+ * of transports enabled by default.
+ */
+export interface RuntimeAdapter {
+    readonly name: RuntimeName;
+    /** `main` / `renderer` for Electron, otherwise `undefined`. */
+    readonly processType?: ElectronProcessType;
+    /** Current epoch milliseconds. */
+    now(): number;
+    /** Process id when available (Electron main / Node). */
+    pid(): number | undefined;
+    /** Whether persistent local file storage is available. */
+    hasFileSystem(): boolean;
+    /** Transports enabled by default for this runtime. */
+    defaultTransports(): Transport[];
+    /**
+     * For Electron main process: register a receiver that forwards entries sent
+     * by renderer processes (via IPC) into the host logger. Returns an
+     * unregister function. Undefined when not applicable.
+     */
+    attachReceiver?: (ingest: IngestFn) => () => void;
+    /**
+     * Cross-process level-setting callback. When set on the runtime, any
+     * `setLevel` call from a child process will invoke this with the new level.
+     * Undefined when not applicable.
+     */
+    onLevelCommand?: (level: number) => void;
+    /**
+     * Host lifecycle hooks. When present, the logger wires its flush-on-exit and
+     * crash-logging behaviour through these instead of touching `process` /
+     * `window` itself. Omit (or leave `undefined`) on runtimes where the logger
+     * should not react to host lifecycle.
+     */
+    lifecycle?: LifecycleHooks;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/cjs/runtime/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/runtime/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,CAAC;AAEtD;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,UAAU,CAAC;AAEtD,+DAA+D;AAC/D,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC;IAC9D;;;;OAIG;IACH,eAAe,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC1D;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAC3C,kCAAkC;IAClC,GAAG,IAAI,MAAM,CAAC;IACd,wDAAwD;IACxD,GAAG,IAAI,MAAM,GAAG,SAAS,CAAC;IAC1B,0DAA0D;IAC1D,aAAa,IAAI,OAAO,CAAC;IACzB,sDAAsD;IACtD,iBAAiB,IAAI,SAAS,EAAE,CAAC;IACjC;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,KAAK,MAAM,IAAI,CAAC;IAClD;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B"}

package/dist/cjs/runtime/adapter.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=adapter.js.map

package/dist/cjs/runtime/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/runtime/adapter.ts"],"names":[],"mappings":""}

package/dist/cjs/runtime/defaults.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Sensible disk-safety defaults for the built-in runtimes' default
+ * `FileTransport` (mode `rotate-time`, daily). A zero-config logger must never
+ * eat the disk, so the defaults bound every growth axis:
+ *
+ * - `maxSize` caps each file (the global caps never delete the active file,
+ *   so the active file needs its own limit);
+ * - `maxFiles` keeps roughly two weeks of daily buckets;
+ * - `maxTotalSize` is the absolute disk ceiling (~200 MB) even if a single
+ *   day produces far more data.
+ *
+ * Every value can be overridden via `fileTransportOptions`; passing `undefined`
+ * keeps the default, while explicit values replace it.
+ */
+/** Max bytes per file: 10 MB. */
+export declare const DEFAULT_MAX_FILE_SIZE: number;
+/** Max daily buckets kept: 14 (about two weeks). */
+export declare const DEFAULT_MAX_FILES = 14;
+/** Absolute disk ceiling for all owned files: 200 MB. */
+export declare const DEFAULT_MAX_TOTAL_SIZE: number;
+/** Default caps merged into the runtimes' default `FileTransport` options. */
+export declare const DEFAULT_FILE_CAPS: {
+    readonly maxSize: number;
+    readonly maxFiles: 14;
+    readonly maxTotalSize: number;
+};
+//# sourceMappingURL=defaults.d.ts.map

package/dist/cjs/runtime/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../../src/runtime/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,iCAAiC;AACjC,eAAO,MAAM,qBAAqB,QAAmB,CAAC;AACtD,oDAAoD;AACpD,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,yDAAyD;AACzD,eAAO,MAAM,sBAAsB,QAAoB,CAAC;AAExD,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB;;;;CAIpB,CAAC"}

package/dist/cjs/runtime/defaults.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Sensible disk-safety defaults for the built-in runtimes' default
+ * `FileTransport` (mode `rotate-time`, daily). A zero-config logger must never
+ * eat the disk, so the defaults bound every growth axis:
+ *
+ * - `maxSize` caps each file (the global caps never delete the active file,
+ *   so the active file needs its own limit);
+ * - `maxFiles` keeps roughly two weeks of daily buckets;
+ * - `maxTotalSize` is the absolute disk ceiling (~200 MB) even if a single
+ *   day produces far more data.
+ *
+ * Every value can be overridden via `fileTransportOptions`; passing `undefined`
+ * keeps the default, while explicit values replace it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_FILE_CAPS = exports.DEFAULT_MAX_TOTAL_SIZE = exports.DEFAULT_MAX_FILES = exports.DEFAULT_MAX_FILE_SIZE = void 0;
+/** Max bytes per file: 10 MB. */
+exports.DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024;
+/** Max daily buckets kept: 14 (about two weeks). */
+exports.DEFAULT_MAX_FILES = 14;
+/** Absolute disk ceiling for all owned files: 200 MB. */
+exports.DEFAULT_MAX_TOTAL_SIZE = 200 * 1024 * 1024;
+/** Default caps merged into the runtimes' default `FileTransport` options. */
+exports.DEFAULT_FILE_CAPS = {
+    maxSize: exports.DEFAULT_MAX_FILE_SIZE,
+    maxFiles: exports.DEFAULT_MAX_FILES,
+    maxTotalSize: exports.DEFAULT_MAX_TOTAL_SIZE,
+};
+//# sourceMappingURL=defaults.js.map

package/dist/cjs/runtime/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../../src/runtime/defaults.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAEH,iCAAiC;AACpB,QAAA,qBAAqB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AACtD,oDAAoD;AACvC,QAAA,iBAAiB,GAAG,EAAE,CAAC;AACpC,yDAAyD;AAC5C,QAAA,sBAAsB,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;AAExD,8EAA8E;AACjE,QAAA,iBAAiB,GAAG;IAC/B,OAAO,EAAE,6BAAqB;IAC9B,QAAQ,EAAE,yBAAiB;IAC3B,YAAY,EAAE,8BAAsB;CAC5B,CAAC"}

package/dist/cjs/runtime/electron-binding.browser.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Type of the `electron` module as returned by `require('electron')`. Mirrors
+ * the real binding (`Electron.CrossProcessExports`) so the web/browser swap
+ * stays type-compatible.
+ */
+export type ElectronModule = typeof Electron.CrossProcessExports;
+export declare function isElectronProcess(): boolean;
+export declare function getElectron(): ElectronModule;
+export declare function getElectronApp(): undefined;
+//# sourceMappingURL=electron-binding.browser.d.ts.map

package/dist/cjs/runtime/electron-binding.browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"electron-binding.browser.d.ts","sourceRoot":"","sources":["../../../src/runtime/electron-binding.browser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,QAAQ,CAAC,mBAAmB,CAAC;AAKjE,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED,wBAAgB,WAAW,IAAI,cAAc,CAE5C;AAED,wBAAgB,cAAc,IAAI,SAAS,CAE1C"}

package/dist/cjs/runtime/electron-binding.browser.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isElectronProcess = isElectronProcess;
+exports.getElectron = getElectron;
+exports.getElectronApp = getElectronApp;
+// Browser stub: the real `electron` module (and its binary) is never available
+// in a web bundle. `package.json`'s `browser` field maps the runtime binding to
+// this module so web builds stay free of any `require('electron')`.
+function isElectronProcess() {
+    return false;
+}
+function getElectron() {
+    throw new Error('electron is not available in browser builds');
+}
+function getElectronApp() {
+    return undefined;
+}
+//# sourceMappingURL=electron-binding.browser.js.map

package/dist/cjs/runtime/electron-binding.browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"electron-binding.browser.js","sourceRoot":"","sources":["../../../src/runtime/electron-binding.browser.ts"],"names":[],"mappings":";;AAUA,8CAEC;AAED,kCAEC;AAED,wCAEC;AAbD,+EAA+E;AAC/E,gFAAgF;AAChF,oEAAoE;AACpE,SAAgB,iBAAiB;IAC/B,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAgB,WAAW;IACzB,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;AACjE,CAAC;AAED,SAAgB,cAAc;IAC5B,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/cjs/runtime/electron-binding.d.ts

@@ -0,0 +1,24 @@
+import type { App } from 'electron';
+/**
+ * Type of the `electron` module as returned by `require('electron')`. We use
+ * electron's own `Electron.CrossProcessExports` type so we stay in sync with
+ * the real API without hand-writing interfaces.
+ */
+export type ElectronModule = typeof Electron.CrossProcessExports;
+/** True when running inside an Electron process. */
+export declare function isElectronProcess(): boolean;
+/**
+ * Resolve the `electron` module. This is the **only** place in the library
+ * that performs `require('electron')`, so a web bundler can swap this whole
+ * module for `electron-binding.browser` (via package.json `browser`) and never
+ * touch the Electron binary.
+ */
+export declare function getElectron(): ElectronModule;
+/**
+ * Resolve the Electron `app` instance. Only meaningful inside a real Electron
+ * process; returns `undefined` when Electron is absent or `app` can't be read
+ * (e.g. a renderer process, or a bundler that stripped `electron`). This is the
+ * runtime layer's single entry point for `app`-level lifecycle wiring.
+ */
+export declare function getElectronApp(): App | undefined;
+//# sourceMappingURL=electron-binding.d.ts.map

package/dist/cjs/runtime/electron-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"electron-binding.d.ts","sourceRoot":"","sources":["../../../src/runtime/electron-binding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAEpC;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,QAAQ,CAAC,mBAAmB,CAAC;AAIjE,oDAAoD;AACpD,wBAAgB,iBAAiB,IAAI,OAAO,CAK3C;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,cAAc,CAc5C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,GAAG,GAAG,SAAS,CAOhD"}

package/dist/cjs/runtime/electron-binding.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isElectronProcess = isElectronProcess;
+exports.getElectron = getElectron;
+exports.getElectronApp = getElectronApp;
+let cached;
+/** True when running inside an Electron process. */
+function isElectronProcess() {
+    return (typeof process !== 'undefined' &&
+        !!process.versions?.electron);
+}
+/**
+ * Resolve the `electron` module. This is the **only** place in the library
+ * that performs `require('electron')`, so a web bundler can swap this whole
+ * module for `electron-binding.browser` (via package.json `browser`) and never
+ * touch the Electron binary.
+ */
+function getElectron() {
+    if (cached !== undefined) {
+        if (cached === null) {
+            throw new Error('electron is only available inside an Electron process');
+        }
+        return cached;
+    }
+    if (!isElectronProcess()) {
+        cached = null;
+        throw new Error('electron is only available inside an Electron process');
+    }
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    cached = require('electron');
+    return cached;
+}
+/**
+ * Resolve the Electron `app` instance. Only meaningful inside a real Electron
+ * process; returns `undefined` when Electron is absent or `app` can't be read
+ * (e.g. a renderer process, or a bundler that stripped `electron`). This is the
+ * runtime layer's single entry point for `app`-level lifecycle wiring.
+ */
+function getElectronApp() {
+    if (!isElectronProcess())
+        return undefined;
+    try {
+        return getElectron().app;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=electron-binding.js.map

package/dist/cjs/runtime/electron-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"electron-binding.js","sourceRoot":"","sources":["../../../src/runtime/electron-binding.ts"],"names":[],"mappings":";;AAYA,8CAKC;AAQD,kCAcC;AAQD,wCAOC;AA7CD,IAAI,MAAyC,CAAC;AAE9C,oDAAoD;AACpD,SAAgB,iBAAiB;IAC/B,OAAO,CACL,OAAO,OAAO,KAAK,WAAW;QAC9B,CAAC,CAAE,OAAgD,CAAC,QAAQ,EAAE,QAAQ,CACvE,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,WAAW;IACzB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC3E,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,CAAC,iBAAiB,EAAE,EAAE,CAAC;QACzB,MAAM,GAAG,IAAI,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IACD,iEAAiE;IACjE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAmB,CAAC;IAC/C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,cAAc;IAC5B,IAAI,CAAC,iBAAiB,EAAE;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,CAAC;QACH,OAAO,WAAW,EAAE,CAAC,GAAG,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/cjs/runtime/electron-lifecycle.d.ts

@@ -0,0 +1,17 @@
+import type { LifecycleHooks } from './adapter.js';
+/**
+ * Electron **main process** lifecycle hooks.
+ *
+ * GUI-driven termination goes through the Electron `app` event surface
+ * (`before-quit` / `will-quit`) rather than Node's `process` events, which do
+ * not fire on a normal window close. We flush pending entries on those events,
+ * mirroring the existing Node `beforeExit` semantics (fire-and-forget, bounded
+ * by the logger's flush timeout). When `app` is unavailable (e.g. a plain Node
+ * host, or a test runtime), we fall back to the process-based hooks so the
+ * behaviour degrades gracefully.
+ *
+ * Uncaught-error handling stays on `process` (`uncaughtException` /
+ * `unhandledRejection`) — those are still the right surface inside Electron.
+ */
+export declare function createElectronLifecycle(): LifecycleHooks;
+//# sourceMappingURL=electron-lifecycle.d.ts.map

package/dist/cjs/runtime/electron-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"electron-lifecycle.d.ts","sourceRoot":"","sources":["../../../src/runtime/electron-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAInD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,IAAI,cAAc,CA4BxD"}