analogger 2.8.1 → 2.9.1

package/README.md

@@ -1436,6 +1436,190 @@ anaLogger.log("lid: USR_LOGIN, color: purple", "User logged in");
 ---
 
 
+---
+
+## Snapshots
+
+Snapshots let you capture the set of log IDs (lids) seen at a specific point in time, persist them, and later compare two captures side by side. This is useful for regression checks — verifying that the same lids fire in two different runs, or that a code change does not add or remove unexpected log calls.
+
+Snapshots work in both **Node.js** (persisted as JSON files under `os.tmpdir()/analogger-snapshots/`) and the **browser** (persisted in `localStorage`).
+
+> `keepLogHistory()` must be called before any logging starts, as snapshots read from the in-memory log history.
+
+---
+
+### startSnapshotProcess()
+
+Marks the start of a snapshot window. Any subsequent `takeSnapshot()` call will only capture lids logged **from this point forward**, ignoring everything already in the history. Calling it again moves the window start to the current position.
+
+```javascript
+anaLogger.keepLogHistory();
+
+anaLogger.log({ lid: "BOOT_001" }, "application boot");  // excluded
+anaLogger.log({ lid: "BOOT_002" }, "config loaded");     // excluded
+
+anaLogger.startSnapshotProcess();
+
+anaLogger.log({ lid: "WEB_001" }, "request received");   // included
+anaLogger.log({ lid: "WEB_002" }, "response sent");      // included
+
+anaLogger.takeSnapshot("SNAP01");   // captures only WEB_001 and WEB_002
+```
+
+If `startSnapshotProcess()` is never called, `takeSnapshot()` captures the entire history.
+
+<br/>
+
+---
+
+### takeSnapshot()
+
+Captures all lids logged since the last `startSnapshotProcess()` (or since session start) and persists the snapshot under a unique ID.
+
+Returns the array of captured entries so you can inspect or assert on them programmatically.
+
+```javascript
+takeSnapshot(snapshotID, options?)
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `snapshotID` | `string` | — | Unique label for this snapshot, e.g. `"SNAP01"` |
+| `options.messages` | `boolean` | `true` | Store the log message alongside each lid |
+| `options.context` | `boolean` | `true` | Store the full context object alongside each lid |
+
+```javascript
+anaLogger.keepLogHistory();
+anaLogger.log({ lid: "API_001" }, "initialised");
+anaLogger.log({ lid: "WEB_002" }, "request in");
+
+// Capture lids + messages + context (defaults)
+const entries = anaLogger.takeSnapshot("SNAP01");
+// entries = [{ lid: "API_001", message: "initialised", context: {...} }, ...]
+
+// Capture lids only (lighter footprint)
+anaLogger.takeSnapshot("SNAP02", { messages: false, context: false });
+```
+
+In Node.js the snapshot is written to a file and its path is logged:
+
+```
+[AnaLogger] Snapshot "SNAP01" saved - 2 lid(s) captured.
+[AnaLogger] Snapshot persisted to: /tmp/analogger-snapshots/analogger_snapshot_default_SNAP01.json
+```
+
+Because the file lives in `os.tmpdir()`, snapshots persist across Node process restarts — you can take `SNAP01` in one run and compare it in a later one.
+
+<br/>
+
+---
+
+### compareSnapshots()
+
+Loads two previously saved snapshots and prints a side-by-side diff table using `console.table`, which gives automatic column alignment in both Node.js terminals and browser devtools.
+
+```javascript
+compareSnapshots(snapshotID1, snapshotID2, displayOpts?)
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `snapshotID1` | `string` | — | ID of the first snapshot |
+| `snapshotID2` | `string` | — | ID of the second snapshot |
+| `displayOpts[0].messages` | `boolean` | `false` | Show a message column for snapshot 1 |
+| `displayOpts[1].messages` | `boolean` | `false` | Show a message column for snapshot 2 |
+
+Returns `{ onlyInSnap1, onlyInSnap2, inBoth }` for programmatic use, or `null` if either snapshot is not found.
+
+#### Basic comparison (lids only)
+
+```javascript
+anaLogger.compareSnapshots("SNAP01", "SNAP02");
+```
+
+```
+Snapshot comparison: "SNAP01"  vs  "SNAP02"
+  SNAP01 captured at 09:04:28 - 3 lid(s)
+  SNAP02 captured at 09:04:31 - 4 lid(s)
+
+┌─────────┬─────────┬─────────┐
+│ (index) │  SNAP01 │  SNAP02 │
+├─────────┼─────────┼─────────┤
+│    0    │ API_001 │ API_001 │
+│    1    │ WEB_002 │ WEB_002 │
+│    2    │ DB_003  │         │
+│    3    │         │ WEB_004 │
+└─────────┴─────────┴─────────┘
+```
+
+#### With message columns
+
+```javascript
+anaLogger.compareSnapshots("SNAP01", "SNAP02", [{ messages: true }, { messages: true }]);
+```
+
+```
+┌─────────┬─────────┬──────────────────────┬─────────┬──────────────────────┐
+│ (index) │  SNAP01 │   SNAP01 message     │  SNAP02 │   SNAP02 message     │
+├─────────┼─────────┼──────────────────────┼─────────┼──────────────────────┤
+│    0    │ API_001 │ 'initialised'        │ API_001 │ 'initialised'        │
+│    1    │ WEB_002 │ 'request in'         │         │                      │
+│    2    │         │                      │ WEB_004 │ 'new endpoint added' │
+└─────────┴─────────┴──────────────────────┴─────────┴──────────────────────┘
+```
+
+You can also enable messages for only one side:
+
+```javascript
+// Messages only for SNAP02
+anaLogger.compareSnapshots("SNAP01", "SNAP02", [{ messages: false }, { messages: true }]);
+```
+
+In the browser, `compareSnapshots` also injects a colour-coded HTML widget into the `#analogger` DOM container (or `document.body` as a fallback): lids present in both snapshots are shown in neutral, snap1-only rows are highlighted in red, and snap2-only rows in green.
+
+#### Using the return value
+
+```javascript
+const { onlyInSnap1, onlyInSnap2, inBoth } = anaLogger.compareSnapshots("SNAP01", "SNAP02");
+
+if (onlyInSnap2.length > 0) {
+    console.warn("New lids appeared in SNAP02:", onlyInSnap2);
+}
+```
+
+#### Full workflow example
+
+```javascript
+const { anaLogger } = require("analogger");
+
+anaLogger.keepLogHistory();
+
+// --- First run (or first phase) ---
+anaLogger.startSnapshotProcess();
+anaLogger.log({ lid: "API_001" }, "initialised");
+anaLogger.log({ lid: "WEB_002" }, "request received");
+anaLogger.log({ lid: "DB_003"  }, "query executed");
+anaLogger.takeSnapshot("SNAP01");
+
+// --- Second run (or second phase, e.g. after a code change) ---
+anaLogger.startSnapshotProcess();
+anaLogger.log({ lid: "API_001" }, "initialised");
+anaLogger.log({ lid: "WEB_002" }, "request received");
+// DB_003 is gone, WEB_004 is new
+anaLogger.log({ lid: "WEB_004" }, "cache hit");
+anaLogger.takeSnapshot("SNAP02");
+
+// --- Compare ---
+const diff = anaLogger.compareSnapshots("SNAP01", "SNAP02", [{ messages: true }, { messages: true }]);
+// diff.onlyInSnap1 => ["DB_003"]   (removed)
+// diff.onlyInSnap2 => ["WEB_004"]  (added)
+// diff.inBoth      => ["API_001", "WEB_002"]
+```
+
+<br/>
+
+---
+
 ## Changelog
 
 ##### current:
@@ -1445,6 +1629,9 @@ anaLogger.log("lid: USR_LOGIN, color: purple", "User logged in");
 *  Add `order` option to detect and warn on out-of-sequence log calls
 *  Add `maxSeen` option to warn when a lid is logged more times than allowed
 *  Add `test` context option and `report()` method for inline assertions and test summaries
+*  Add `startSnapshotProcess()` to mark the start of a snapshot window
+*  Add `takeSnapshot(id, opts?)` to capture lids at a point in time; persists to `localStorage` (browser) or `os.tmpdir()` (Node); returns captured entries
+*  Add `compareSnapshots(id1, id2, displayOpts?)` to diff two snapshots side by side using `console.table`; optional message columns via `[{ messages: true }, { messages: true }]`
 
 
 ##### 1.23.2:

package/ana-logger.d.cts

@@ -423,6 +423,69 @@ declare class ____AnaLogger {
     }): Promise<any>;
     alert(...args: any[]): void;
     assert(condition: any, expected?: boolean, ...args: any[]): boolean;
+    /**
+     * Mark the start of a snapshot window.
+     * When called, any subsequent takeSnapshot() will only capture lids logged
+     * from this point forward, ignoring everything already in the history.
+     * Calling it again moves the window start to the current position.
+     *
+     * @example
+     * anaLogger.keepLogHistory();
+     * anaLogger.log({ lid: "WEB0001" }, "boot");   // excluded
+     * anaLogger.startSnapshotProcess();
+     * anaLogger.log({ lid: "WEB0002" }, "step 1"); // included
+     * anaLogger.takeSnapshot("SNAP01");             // captures only WEB0002
+     */
+    startSnapshotProcess(): void;
+    _snapshotWindowStart: number;
+    /**
+     * Capture all lids logged since the last startSnapshotProcess() (or since the
+     * beginning of the session if startSnapshotProcess was never called) into a
+     * named snapshot stored in localStorage / temp file.
+     *
+     * @param {string} snapshotID                            - unique label, e.g. "SNAP01"
+     * @param {{ messages?: boolean, context?: boolean }} [opts]
+     *   messages: true  - also store the log message per lid  (default: true)
+     *   context:  true  - also store the full context object  (default: true)
+     * @returns {object[]} The array of snapshot entries that were saved
+     *
+     * @example
+     * anaLogger.keepLogHistory();
+     * anaLogger.log({ lid: "WEB0001" }, "step 1");
+     * const entries = anaLogger.takeSnapshot("SNAP01");
+     * anaLogger.log({ lid: "WEB0002" }, "step 2");
+     * anaLogger.takeSnapshot("SNAP02", { messages: false, context: false });
+     */
+    takeSnapshot(snapshotID: string, opts?: {
+        messages?: boolean;
+        context?: boolean;
+    }): object[];
+    /**
+     * Compare two previously saved snapshots and print a side-by-side diff table
+     * showing which lids are shared, present only in snap1, or only in snap2.
+     *
+     * @param {string} snapshotID1
+     * @param {string} snapshotID2
+     * @param {[{ messages?: boolean }, { messages?: boolean }]} [displayOpts]
+     *   Optional per-snapshot display options.
+     *   displayOpts[0].messages = true  - add a message column for snapshotID1
+     *   displayOpts[1].messages = true  - add a message column for snapshotID2
+     * @returns {{ onlyInSnap1: string[], onlyInSnap2: string[], inBoth: string[] } | null}
+     *
+     * @example
+     * anaLogger.compareSnapshots("SNAP01", "SNAP02");
+     * anaLogger.compareSnapshots("SNAP01", "SNAP02", [{ messages: true }, { messages: true }]);
+     * anaLogger.compareSnapshots("SNAP01", "SNAP02", [{ messages: true }, { messages: false }]);
+     */
+    compareSnapshots(snapshotID1: string, snapshotID2: string, displayOpts?: [{
+        messages?: boolean;
+    }, {
+        messages?: boolean;
+    }]): {
+        onlyInSnap1: string[];
+        onlyInSnap2: string[];
+        inBoth: string[];
+    } | null;
     /**
      * Set standard Analogger format
      * @example

package/browser/ana-logger.mjs

@@ -3565,6 +3565,365 @@ class ____AnaLogger
         return false;
     }
 
+    // ─── Snapshot storage ─────────────────────────────────────────────────────
+    // Browser  → localStorage
+    // Node.js  → os.tmpdir()/analogger-snapshots/<key>.json   (persists across runs)
+
+    /**
+     * Resolve the file path used to persist a snapshot in Node.js.
+     * The directory is created on first use.
+     * @param {string} key  – storage key, e.g. "analogger_snapshot_default_SNAP01"
+     * @returns {string}    – absolute file path
+     */
+    #_snapshotFilePath(key) {
+        
+    }
+
+    #_snapshotGet(key) {
+        // Browser path
+        try {
+            if (this.isBrowser() && typeof localStorage !== "undefined") {
+                return localStorage.getItem(key);
+            }
+        } catch (e) {}
+
+        // Node.js path – read from temp file
+        
+
+        return null;
+    }
+
+    #_snapshotSet(key, value) {
+        // Browser path
+        try {
+            if (this.isBrowser() && typeof localStorage !== "undefined") {
+                localStorage.setItem(key, value);
+                return;
+            }
+        } catch (e) {}
+
+        // Node.js path – write to temp file
+        
+    }
+
+    #_snapshotKey(snapshotID) {
+        return `analogger_snapshot_${this.instanceName || "default"}_${snapshotID}`;
+    }
+
+    /**
+     * Harvest lid entries from the current log history.
+     * Only entries logged after the last startSnapshotProcess() call are included
+     * when a snapshot window is active.
+     * @param {{ messages?: boolean, context?: boolean }} opts
+     * @returns {object[]}
+     */
+    #_harvestSnapshot(opts = {}) {
+        const { messages = true, context: includeContext = true } = opts;
+        const fullHistory = this.getRawLogHistory ? this.getRawLogHistory() : (this.logHistory || []);
+
+        // If a snapshot window is active, slice from the marker index
+        const history = this._snapshotWindowStart !== undefined
+            ? fullHistory.slice(this._snapshotWindowStart)
+            : fullHistory;
+
+        /** Deduplicate by lid - keep the last occurrence */
+        const seen = new Map();
+        for (const entry of history) {
+            const ctx = entry.context || {};
+            const lid = ctx.lid;
+            if (!lid) continue;
+            const record = { lid };
+            if (messages)       record.message = entry.message ?? "";
+            if (includeContext) record.context = { ...ctx };
+            seen.set(lid, record);
+        }
+        return Array.from(seen.values());
+    }
+
+    /**
+     * Mark the start of a snapshot window.
+     * When called, any subsequent takeSnapshot() will only capture lids logged
+     * from this point forward, ignoring everything already in the history.
+     * Calling it again moves the window start to the current position.
+     *
+     * @example
+     * anaLogger.keepLogHistory();
+     * anaLogger.log({ lid: "WEB0001" }, "boot");   // excluded
+     * anaLogger.startSnapshotProcess();
+     * anaLogger.log({ lid: "WEB0002" }, "step 1"); // included
+     * anaLogger.takeSnapshot("SNAP01");             // captures only WEB0002
+     */
+    startSnapshotProcess() {
+        const history = this.getRawLogHistory ? this.getRawLogHistory() : (this.logHistory || []);
+        this._snapshotWindowStart = history.length;
+        console.log(
+            `[AnaLogger] Snapshot window started at history index ${this._snapshotWindowStart}.`
+        );
+    }
+
+    /**
+     * Capture all lids logged since the last startSnapshotProcess() (or since the
+     * beginning of the session if startSnapshotProcess was never called) into a
+     * named snapshot stored in localStorage / temp file.
+     *
+     * @param {string} snapshotID                            - unique label, e.g. "SNAP01"
+     * @param {{ messages?: boolean, context?: boolean }} [opts]
+     *   messages: true  - also store the log message per lid  (default: true)
+     *   context:  true  - also store the full context object  (default: true)
+     * @returns {object[]} The array of snapshot entries that were saved
+     *
+     * @example
+     * anaLogger.keepLogHistory();
+     * anaLogger.log({ lid: "WEB0001" }, "step 1");
+     * const entries = anaLogger.takeSnapshot("SNAP01");
+     * anaLogger.log({ lid: "WEB0002" }, "step 2");
+     * anaLogger.takeSnapshot("SNAP02", { messages: false, context: false });
+     */
+    takeSnapshot(snapshotID, opts = {}) {
+        try {
+            if (!snapshotID || typeof snapshotID !== "string") {
+                console.warn("[AnaLogger] takeSnapshot: snapshotID must be a non-empty string.");
+                return [];
+            }
+
+            const { messages = true, context: includeContext = true } = opts;
+            const entries = this.#_harvestSnapshot({ messages, context: includeContext });
+
+            const payload = {
+                snapshotID,
+                timestamp : Date.now(),
+                options   : { messages, context: includeContext },
+                entries,
+            };
+
+            this.#_snapshotSet(this.#_snapshotKey(snapshotID), JSON.stringify(payload));
+
+            console.log(
+                `[AnaLogger] Snapshot "${snapshotID}" saved - ${entries.length} lid(s) captured.`
+            );
+
+            return entries;
+        } catch (e) {
+            console.error("[AnaLogger] takeSnapshot error:", e.message);
+            return [];
+        }
+    }
+
+    /**
+     * Compare two previously saved snapshots and print a side-by-side diff table
+     * showing which lids are shared, present only in snap1, or only in snap2.
+     *
+     * @param {string} snapshotID1
+     * @param {string} snapshotID2
+     * @param {[{ messages?: boolean }, { messages?: boolean }]} [displayOpts]
+     *   Optional per-snapshot display options.
+     *   displayOpts[0].messages = true  - add a message column for snapshotID1
+     *   displayOpts[1].messages = true  - add a message column for snapshotID2
+     * @returns {{ onlyInSnap1: string[], onlyInSnap2: string[], inBoth: string[] } | null}
+     *
+     * @example
+     * anaLogger.compareSnapshots("SNAP01", "SNAP02");
+     * anaLogger.compareSnapshots("SNAP01", "SNAP02", [{ messages: true }, { messages: true }]);
+     * anaLogger.compareSnapshots("SNAP01", "SNAP02", [{ messages: true }, { messages: false }]);
+     */
+    compareSnapshots(snapshotID1, snapshotID2, displayOpts = []) {
+        try {
+            const raw1 = this.#_snapshotGet(this.#_snapshotKey(snapshotID1));
+            const raw2 = this.#_snapshotGet(this.#_snapshotKey(snapshotID2));
+
+            if (!raw1) console.warn(`[AnaLogger] compareSnapshots: snapshot "${snapshotID1}" not found.`);
+            if (!raw2) console.warn(`[AnaLogger] compareSnapshots: snapshot "${snapshotID2}" not found.`);
+            if (!raw1 || !raw2) return null;
+
+            const snap1 = JSON.parse(raw1);
+            const snap2 = JSON.parse(raw2);
+
+            // Resolve per-snapshot message display flags
+            const showMsg1 = !!(displayOpts[0] && displayOpts[0].messages);
+            const showMsg2 = !!(displayOpts[1] && displayOpts[1].messages);
+
+            const map1 = new Map(snap1.entries.map((e) => [e.lid, e]));
+            const map2 = new Map(snap2.entries.map((e) => [e.lid, e]));
+            const allLids = new Set([...map1.keys(), ...map2.keys()]);
+
+            const inBoth  = [];
+            const onlyIn1 = [];
+            const onlyIn2 = [];
+
+            for (const lid of allLids) {
+                const in1 = map1.has(lid);
+                const in2 = map2.has(lid);
+                if (in1 && in2) inBoth.push(lid);
+                else if (in1)   onlyIn1.push(lid);
+                else            onlyIn2.push(lid);
+            }
+
+            // Build display rows: shared lids paired, then each exclusive lid on its own row
+            const rows = [];
+            for (const lid of inBoth) {
+                rows.push({
+                    left: lid, right: lid, status: "both",
+                    msgLeft : map1.get(lid)?.message ?? "",
+                    msgRight: map2.get(lid)?.message ?? "",
+                });
+            }
+            for (const lid of onlyIn1) {
+                rows.push({
+                    left: lid, right: "",
+                    status: "left",
+                    msgLeft : map1.get(lid)?.message ?? "",
+                    msgRight: "",
+                });
+            }
+            for (const lid of onlyIn2) {
+                rows.push({
+                    left: "", right: lid,
+                    status: "right",
+                    msgLeft : "",
+                    msgRight: map2.get(lid)?.message ?? "",
+                });
+            }
+
+            this.#_renderSnapshotTable(
+                snapshotID1, snapshotID2, rows, snap1, snap2,
+                { showMsg1, showMsg2 }
+            );
+
+            return { onlyInSnap1: onlyIn1, onlyInSnap2: onlyIn2, inBoth };
+        } catch (e) {
+            console.error("[AnaLogger] compareSnapshots error:", e.message);
+            return null;
+        }
+    }
+
+    // ─── Snapshot table renderers ─────────────────────────────────────────────
+
+    #_renderSnapshotTable(id1, id2, rows, snap1, snap2, { showMsg1 = false, showMsg2 = false } = {}) {
+        const ts = (snap) =>
+            snap.timestamp ? new Date(snap.timestamp).toLocaleTimeString() : "-";
+
+        // ── Header ───────────────────────────────────────────────────────────
+        console.log(`\nSnapshot comparison: "${id1}"  vs  "${id2}"`);
+        console.log(`  ${id1} captured at ${ts(snap1)} - ${snap1.entries.length} lid(s)`);
+        console.log(`  ${id2} captured at ${ts(snap2)} - ${snap2.entries.length} lid(s)\n`);
+
+        // ── console.table (auto-aligned in Node and browser devtools) ────────
+        // Column keys are the snapshot IDs so headers are self-documenting.
+        // Message columns are appended only when requested.
+        const msgKey1 = `${id1} message`;
+        const msgKey2 = `${id2} message`;
+
+        const tableData = rows.length
+            ? rows.map((r) => {
+                const row = { [id1]: r.left, [id2]: r.right };
+                if (showMsg1) row[msgKey1] = r.msgLeft;
+                if (showMsg2) row[msgKey2] = r.msgRight;
+                return row;
+            })
+            : [(() => {
+                const row = { [id1]: "(empty)", [id2]: "(empty)" };
+                if (showMsg1) row[msgKey1] = "";
+                if (showMsg2) row[msgKey2] = "";
+                return row;
+            })()];
+
+        console.table(tableData);
+
+        // ── Browser HTML widget (progressive enhancement) ────────────────────
+        if (typeof document !== "undefined") {
+            this.#_renderSnapshotHtml(id1, id2, rows, snap1, snap2, ts, { showMsg1, showMsg2 });
+        }
+    }
+
+    #_renderSnapshotHtml(id1, id2, rows, snap1, snap2, ts, { showMsg1 = false, showMsg2 = false } = {}) {
+        try {
+            const C = {
+                both: "#1e293b", bothBg: "#f8fafc",
+                left: "#7f1d1d", leftBg: "#fef2f2",
+                right: "#14532d", rightBg: "#f0fdf4",
+                msg: "#475569", msgBg: "#f8fafc",
+                header: "#1e40af", border: "#e2e8f0",
+            };
+
+            const sharedCount = snap1.entries.filter(e => snap2.entries.some(e2 => e2.lid === e.lid)).length;
+            const only1Count  = snap1.entries.length - sharedCount;
+            const only2Count  = snap2.entries.length - sharedCount;
+
+            // Total visible columns: lid1, [msg1], sym, lid2, [msg2]
+            const totalCols = 3 + (showMsg1 ? 1 : 0) + (showMsg2 ? 1 : 0);
+            const td = (extra = "") =>
+                `padding:4px 10px;font-family:monospace;font-size:12px;border-bottom:1px solid ${C.border};${extra}`;
+            const tdMsg = (extra = "") =>
+                `padding:4px 10px;font-size:11px;color:${C.msg};border-bottom:1px solid ${C.border};max-width:200px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;${extra}`;
+            const thStyle = `padding:5px 10px;text-align:left;background:#f1f5f9;font-size:11px;color:#475569;border-bottom:2px solid ${C.border}`;
+
+            const mkRow = (row) => {
+                const lBg = row.status === "left"  ? C.leftBg  : C.bothBg;
+                const rBg = row.status === "right" ? C.rightBg : C.bothBg;
+                const lCl = row.status === "left"  ? C.left    : row.status === "right" ? "#94a3b8" : C.both;
+                const rCl = row.status === "right" ? C.right   : row.status === "left"  ? "#94a3b8" : C.both;
+                const sym = row.status === "both" ? "=" : row.status === "left" ? "◀" : row.status === "right" ? "▶" : "≠";
+
+                return `<tr>
+                    <td style="${td(`background:${lBg};color:${lCl}`)}">${row.left  || ""}</td>
+                    ${showMsg1 ? `<td style="${tdMsg(`background:${lBg}`)}" title="${(row.msgLeft  || "").replace(/"/g, "&quot;")}">${row.msgLeft  || ""}</td>` : ""}
+                    <td style="width:20px;text-align:center;border-bottom:1px solid ${C.border};color:#94a3b8;font-size:10px">${sym}</td>
+                    <td style="${td(`background:${rBg};color:${rCl}`)}">${row.right || ""}</td>
+                    ${showMsg2 ? `<td style="${tdMsg(`background:${rBg}`)}" title="${(row.msgRight || "").replace(/"/g, "&quot;")}">${row.msgRight || ""}</td>` : ""}
+                </tr>`;
+            };
+
+            const html = `
+<div id="analogger-snapshot-cmp" style="
+    font-family:system-ui,sans-serif;font-size:13px;
+    border:1px solid ${C.border};border-radius:8px;overflow:hidden;
+    max-width:${showMsg1 || showMsg2 ? "820px" : "520px"};margin:12px 0;box-shadow:0 2px 8px rgba(0,0,0,.08)">
+  <div style="background:${C.header};color:#fff;padding:8px 14px;font-weight:600">
+    Snapshot diff &mdash;
+    <code style="font-size:12px">${id1}</code>
+    <span style="opacity:.7"> vs </span>
+    <code style="font-size:12px">${id2}</code>
+  </div>
+  <div style="display:flex;background:#e2e8f0;font-size:11px;color:#64748b;padding:3px 0">
+    <span style="flex:1;padding-left:10px">${id1} &middot; ${ts(snap1)} &middot; ${snap1.entries.length} lids</span>
+    <span style="width:20px"></span>
+    <span style="flex:1;padding-left:10px">${id2} &middot; ${ts(snap2)} &middot; ${snap2.entries.length} lids</span>
+  </div>
+  <table style="width:100%;border-collapse:collapse">
+    <thead>
+      <tr>
+        <th style="${thStyle}">${id1}</th>
+        ${showMsg1 ? `<th style="${thStyle};color:#94a3b8;font-style:italic">message</th>` : ""}
+        <th style="width:20px;background:#f1f5f9;border-bottom:2px solid ${C.border}"></th>
+        <th style="${thStyle}">${id2}</th>
+        ${showMsg2 ? `<th style="${thStyle};color:#94a3b8;font-style:italic">message</th>` : ""}
+      </tr>
+    </thead>
+    <tbody>
+      ${rows.length
+          ? rows.map(mkRow).join("")
+          : `<tr><td colspan="${totalCols}" style="padding:10px;color:#94a3b8;text-align:center">(no lids in either snapshot)</td></tr>`}
+    </tbody>
+  </table>
+  <div style="background:#f8fafc;padding:5px 10px;font-size:11px;color:#64748b;display:flex;gap:16px">
+    <span>&#x2714; ${sharedCount} shared</span>
+    <span style="color:${C.left}">&#x25C4; ${only1Count} only in ${id1}</span>
+    <span style="color:${C.right}">&#x25BA; ${only2Count} only in ${id2}</span>
+  </div>
+</div>`;
+
+            const $old = document.getElementById("analogger-snapshot-cmp");
+            if ($old) $old.remove();
+
+            const $mount = document.querySelector("#analogger") || document.body;
+            const $wrapper = document.createElement("div");
+            $wrapper.innerHTML = html;
+            $mount.appendChild($wrapper.firstElementChild);
+        } catch (e) {
+            // Non-fatal - plain-text already printed
+        }
+    }
+
     /**
      * Set default targets, contexts and log levels
      * @returns {boolean}