@parallax-rn/sdk 0.0.0-stage → 0.1.0-beta.2

package/dist/push.d.ts

@@ -0,0 +1,36 @@
+import { type ErrorEntry, type LogEntry, type SourceEntry } from '@parallax-rn/protocol';
+import type { HostGlobal } from './host.js';
+import type { SdkLimits } from './limits.js';
+import type { RingBuffer } from './ring-buffer.js';
+export interface PushDeps {
+    readonly host: HostGlobal;
+    readonly contextId: string;
+    readonly logs: RingBuffer<LogEntry>;
+    readonly errors: RingBuffer<ErrorEntry>;
+    /** The namespaced data sources (protocol 0.5) by name; rings may be added after the batcher exists. */
+    readonly sources: ReadonlyMap<string, RingBuffer<SourceEntry>>;
+    readonly limits: SdkLimits;
+}
+export declare class PushBatcher {
+    private readonly deps;
+    private timer;
+    private urgent;
+    private pushedLogs;
+    private pushedErrors;
+    private readonly pushedSources;
+    private disposed;
+    /** Pushes handed to the binding (for diagnostics and tests). */
+    pushes: number;
+    constructor(deps: PushDeps);
+    /** Called after an entry was appended. */
+    notify(urgent: boolean): void;
+    flush(): void;
+    /**
+     * An empty push that says this context's SDK has started. Nothing else makes a server that looked before the SDK started (the app was found without one, or the SDK was
+     * injected later) ask again until the first entry, and the producer of a source stays with the debugger until then.
+     */
+    hello(): void;
+    dispose(): void;
+    private send;
+}
+//# sourceMappingURL=push.d.ts.map

package/dist/push.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PushBatcher = void 0;
+// Pushes new entries to the server through the CDP binding (decision 0010, spike 0006). Pushes only reduce latency: the ring
+// buffers stay the source of truth and the server drains them by cursor, so a missed push loses nothing.
+//  - the payload is always a string (an object passed to the binding is silently dropped by Hermes);
+//  - the binding is checked with `typeof === 'function'` before every call (it does not exist in a fresh process until a
+//    session adds it);
+//  - bursts are coalesced: the first new entry starts a timer, everything that arrives within `flushIntervalMs` goes out
+//    together; errors are pushed at once;
+//  - one push is split when it would exceed the entry or size limits.
+const protocol_1 = require("@parallax-rn/protocol");
+const OVERHEAD = 80; // rough JSON overhead per entry, in characters
+const weight = (entry) => OVERHEAD + entry.message.length + ('stack' in entry && typeof entry.stack === 'string' ? entry.stack.length : 0);
+class PushBatcher {
+    constructor(deps) {
+        this.deps = deps;
+        this.timer = null;
+        this.urgent = false;
+        this.pushedLogs = 0;
+        this.pushedErrors = 0;
+        this.pushedSources = new Map();
+        this.disposed = false;
+        /** Pushes handed to the binding (for diagnostics and tests). */
+        this.pushes = 0;
+        this.pushedLogs = deps.logs.last;
+        this.pushedErrors = deps.errors.last;
+    }
+    /** Called after an entry was appended. */
+    notify(urgent) {
+        if (this.disposed)
+            return;
+        const { host, limits } = this.deps;
+        if (typeof host.setTimeout !== 'function') {
+            this.flush();
+            return;
+        }
+        if (this.timer !== null) {
+            if (!urgent || this.urgent)
+                return; // a timer is already pending, and it is not going to be sooner
+            if (typeof host.clearTimeout === 'function')
+                host.clearTimeout(this.timer);
+        }
+        this.urgent = urgent;
+        this.timer = host.setTimeout(() => this.flush(), urgent ? 0 : limits.flushIntervalMs);
+    }
+    flush() {
+        var _a;
+        const { host, logs, errors, sources, limits, contextId } = this.deps;
+        if (this.timer !== null && typeof host.clearTimeout === 'function')
+            host.clearTimeout(this.timer);
+        this.timer = null;
+        this.urgent = false;
+        const newLogs = logs.drain(this.pushedLogs, Infinity).entries;
+        const newErrors = errors.drain(this.pushedErrors, Infinity).entries;
+        // advance first: whether or not anyone listens, the buffers hold the history
+        this.pushedLogs = logs.last;
+        this.pushedErrors = errors.last;
+        const newSources = [];
+        for (const [name, ring] of sources) {
+            const drained = ring.drain((_a = this.pushedSources.get(name)) !== null && _a !== void 0 ? _a : 0, Infinity).entries;
+            this.pushedSources.set(name, ring.last);
+            if (drained.length > 0)
+                newSources.push([name, drained]);
+        }
+        if (newLogs.length === 0 && newErrors.length === 0 && newSources.length === 0)
+            return;
+        let batch = { logs: [], errors: [], sources: {} };
+        let entries = 0;
+        let chars = 0;
+        const send = () => {
+            if (entries === 0)
+                return;
+            this.send(JSON.stringify({ contextId, logs: batch.logs, errors: batch.errors, ...(Object.keys(batch.sources).length > 0 ? { sources: batch.sources } : {}) }));
+            batch = { logs: [], errors: [], sources: {} };
+            entries = 0;
+            chars = 0;
+        };
+        const add = (entry, into) => {
+            const w = weight(entry);
+            if (entries > 0 && (entries >= limits.maxBatchEntries || chars + w > limits.maxBatchChars))
+                send();
+            batch[into].push(entry);
+            entries++;
+            chars += w;
+        };
+        const addSource = (name, entry) => {
+            var _a, _b;
+            var _c;
+            const w = OVERHEAD + ((_a = JSON.stringify(entry.data)) !== null && _a !== void 0 ? _a : '').length;
+            if (entries > 0 && (entries >= limits.maxBatchEntries || chars + w > limits.maxBatchChars))
+                send();
+            ((_b = (_c = batch.sources)[name]) !== null && _b !== void 0 ? _b : (_c[name] = [])).push(entry);
+            entries++;
+            chars += w;
+        };
+        for (const entry of newErrors)
+            add(entry, 'errors');
+        for (const entry of newLogs)
+            add(entry, 'logs');
+        for (const [name, list] of newSources)
+            for (const entry of list)
+                addSource(name, entry);
+        send();
+    }
+    /**
+     * An empty push that says this context's SDK has started. Nothing else makes a server that looked before the SDK started (the app was found without one, or the SDK was
+     * injected later) ask again until the first entry, and the producer of a source stays with the debugger until then.
+     */
+    hello() {
+        this.send(JSON.stringify({ contextId: this.deps.contextId, logs: [], errors: [] }));
+    }
+    dispose() {
+        this.flush();
+        this.disposed = true;
+    }
+    send(payload) {
+        const binding = this.deps.host[protocol_1.PUSH_BINDING_NAME];
+        if (typeof binding !== 'function')
+            return;
+        this.pushes++;
+        try {
+            binding(payload);
+        }
+        catch {
+            /* pushing must never break the app */
+        }
+    }
+}
+exports.PushBatcher = PushBatcher;

package/dist/ring-buffer.d.ts

@@ -0,0 +1,26 @@
+import type { BufferState } from '@parallax-rn/protocol';
+export interface Sequenced {
+    readonly seq: number;
+}
+export interface Drained<T> {
+    readonly entries: T[];
+    /** The highest seq returned, or the (clamped) cursor when nothing was returned. */
+    readonly next: number;
+    /** Entries after the cursor that were evicted before they could be returned. */
+    readonly dropped: number;
+}
+export declare class RingBuffer<T extends Sequenced> {
+    readonly capacity: number;
+    private readonly slots;
+    private count;
+    private lastSeq;
+    private droppedTotal;
+    constructor(capacity: number);
+    /** Assigns the next seq, stores the entry and evicts the oldest one when full. */
+    append(make: (seq: number) => T): T;
+    get last(): number;
+    state(): BufferState;
+    /** Entries with seq greater than `cursor`, oldest first, at most `limit`. */
+    drain(cursor: number, limit: number): Drained<T>;
+}
+//# sourceMappingURL=ring-buffer.d.ts.map

package/dist/ring-buffer.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RingBuffer = void 0;
+class RingBuffer {
+    constructor(capacity) {
+        this.capacity = capacity;
+        this.count = 0;
+        this.lastSeq = 0;
+        this.droppedTotal = 0;
+        if (!(capacity >= 1) || Math.floor(capacity) !== capacity)
+            throw new Error('capacity must be a positive integer');
+        this.slots = new Array(capacity);
+    }
+    /** Assigns the next seq, stores the entry and evicts the oldest one when full. */
+    append(make) {
+        const seq = ++this.lastSeq;
+        const entry = make(seq);
+        if (this.count === this.capacity)
+            this.droppedTotal++;
+        else
+            this.count++;
+        this.slots[(seq - 1) % this.capacity] = entry;
+        return entry;
+    }
+    get last() {
+        return this.lastSeq;
+    }
+    state() {
+        return { first: this.lastSeq - this.count + 1, last: this.lastSeq, dropped: this.droppedTotal };
+    }
+    /** Entries with seq greater than `cursor`, oldest first, at most `limit`. */
+    drain(cursor, limit) {
+        const first = this.lastSeq - this.count + 1;
+        const from = Math.max(cursor + 1, first);
+        const dropped = cursor + 1 < first ? first - (cursor + 1) : 0;
+        const entries = [];
+        for (let seq = from; seq <= this.lastSeq && entries.length < limit; seq++) {
+            const entry = this.slots[(seq - 1) % this.capacity];
+            if (entry)
+                entries.push(entry);
+        }
+        const lastReturned = entries.length > 0 ? entries[entries.length - 1] : undefined;
+        return { entries, next: lastReturned ? lastReturned.seq : Math.min(cursor, this.lastSeq), dropped };
+    }
+}
+exports.RingBuffer = RingBuffer;

package/dist/sdk.d.ts

@@ -0,0 +1,35 @@
+import { type Handshake, type SdkApi } from '@parallax-rn/protocol';
+import { type CommandHandler, type CommandMeta } from './commands.js';
+import { type NavigationRefLike } from './navigation.js';
+import { type HostGlobal } from './host.js';
+import { type SdkLimits } from './limits.js';
+import { type StoreOptions } from './stores.js';
+export interface SdkOptions {
+    readonly host?: HostGlobal;
+    readonly limits?: Partial<SdkLimits>;
+    readonly version?: string;
+    readonly now?: () => number;
+    /** Capture HTTP requests as the `network` source (default true). */
+    readonly network?: boolean;
+}
+export interface Sdk {
+    /** Starts capturing. Returns false (and does nothing) when `__DEV__` is false. Idempotent. */
+    start(): boolean;
+    /** Stops capturing and restores the original console methods and error handler. */
+    stop(): void;
+    readonly started: boolean;
+    /** Changes whenever the JS context is recreated (the SDK module is evaluated again). */
+    readonly contextId: string;
+    readonly limits: SdkLimits;
+    readonly api: SdkApi;
+    registerCommand(name: string, handler: CommandHandler, meta?: CommandMeta): () => void;
+    /** Follows a navigation container ref (the `navigation` source); registering again replaces the previous one. Returns the stop function. */
+    registerNavigation(ref: NavigationRefLike): () => void;
+    /** Follows a store with `getState()` and `subscribe()` (Redux, Zustand) as the source `state:<name>`. Returns an unregister function. */
+    registerStore(name: string, store: unknown, options?: StoreOptions): () => void;
+    /** Follows a TanStack Query client as the source `query:<name>`. Returns an unregister function. */
+    registerQueryClient(name: string, client: unknown): () => void;
+    handshake(): Handshake;
+}
+export declare function createSdk(options?: SdkOptions): Sdk;
+//# sourceMappingURL=sdk.d.ts.map

package/dist/sdk.js

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSdk = createSdk;
+// Assembles the SDK: ring buffers, console and error capture, push, the command registry and the API object under
+// `globalThis.__PARALLAX_RN__.sdk` (decisions 0002, 0010, 0012). Nothing happens until `start()`.
+const protocol_1 = require("@parallax-rn/protocol");
+const commands_js_1 = require("./commands.js");
+const console_capture_js_1 = require("./console-capture.js");
+const error_capture_js_1 = require("./error-capture.js");
+const navigation_js_1 = require("./navigation.js");
+const network_capture_js_1 = require("./network-capture.js");
+const format_js_1 = require("./format.js");
+const host_js_1 = require("./host.js");
+const limits_js_1 = require("./limits.js");
+const push_js_1 = require("./push.js");
+const ring_buffer_js_1 = require("./ring-buffer.js");
+const stores_js_1 = require("./stores.js");
+const version_js_1 = require("./version.js");
+function newContextId(now) {
+    return `${now.toString(36)}-${Math.floor(Math.random() * 0x7fffffff).toString(36)}`;
+}
+function createSdk(options = {}) {
+    var _a, _b, _c;
+    const host = (_a = options.host) !== null && _a !== void 0 ? _a : (0, host_js_1.defaultHost)();
+    const now = (_b = options.now) !== null && _b !== void 0 ? _b : (() => Date.now());
+    const version = (_c = options.version) !== null && _c !== void 0 ? _c : version_js_1.SDK_VERSION;
+    const limits = { ...limits_js_1.DEFAULT_LIMITS, ...options.limits };
+    const startedAt = now();
+    const contextId = newContextId(startedAt);
+    const logs = new ring_buffer_js_1.RingBuffer(limits.logCapacity);
+    const errors = new ring_buffer_js_1.RingBuffer(limits.errorCapacity);
+    const registry = new commands_js_1.CommandRegistry();
+    // namespaced data sources (protocol 0.5) the SDK announces: a ring is added here only once its producer is installed
+    const sources = new Map();
+    const networkRing = new ring_buffer_js_1.RingBuffer(limits.networkCapacity);
+    const navigationRing = new ring_buffer_js_1.RingBuffer(limits.navigationCapacity);
+    let stopNavigation = null;
+    const batcher = new push_js_1.PushBatcher({ host, contextId, logs, errors, sources, limits });
+    // a store's ring is added on its first snapshot, which only happens while started (so a release build announces none)
+    const stores = new stores_js_1.StoreAdapters({
+        host,
+        limits,
+        emit: (name, data) => {
+            let ring = sources.get(name);
+            if (!ring)
+                sources.set(name, (ring = new ring_buffer_js_1.RingBuffer(limits.storeCapacity)));
+            ring.append(seq => ({ seq, time: now(), data }));
+            batcher.notify(false);
+        },
+    });
+    const captures = [];
+    let started = false;
+    registry.register('parallax.ping', () => ({ pong: true, time: now() }), { description: 'Checks that the SDK answers.' });
+    registry.register('parallax.info', () => handshake(), { description: 'The SDK handshake: versions, context id and buffer state.' });
+    function handshake() {
+        const base = { protocol: [protocol_1.PROTOCOL_VERSION[0], protocol_1.PROTOCOL_VERSION[1]], sdk: version, contextId, startedAt, buffers: { logs: logs.state(), errors: errors.state() } };
+        if (sources.size === 0)
+            return base;
+        const announced = {};
+        for (const [name, ring] of sources)
+            announced[name] = ring.state();
+        return { ...base, sources: announced };
+    }
+    function appendLog(level, args) {
+        const message = (0, format_js_1.cap)((0, format_js_1.formatArgs)(args), limits.maxMessageChars);
+        const time = now();
+        logs.append(seq => (message.truncated ? { seq, time, level, message: message.text, truncated: true } : { seq, time, level, message: message.text }));
+        batcher.notify(false);
+        const rejection = (0, protocol_1.unhandledRejectionOf)(level, args);
+        if (rejection)
+            appendError(rejection, false);
+    }
+    function appendError(error, fatal) {
+        var _a;
+        const source = typeof error === 'object' && error !== null ? error : null;
+        const message = (0, format_js_1.cap)(typeof (source === null || source === void 0 ? void 0 : source.message) === 'string' ? source.message : (0, format_js_1.formatArg)(error), limits.maxMessageChars);
+        const stack = typeof (source === null || source === void 0 ? void 0 : source.stack) === 'string' ? (0, format_js_1.cap)(source.stack, limits.maxStackChars) : null;
+        const name = typeof (source === null || source === void 0 ? void 0 : source.name) === 'string' ? source.name : null;
+        const time = now();
+        const truncated = message.truncated || ((_a = stack === null || stack === void 0 ? void 0 : stack.truncated) !== null && _a !== void 0 ? _a : false);
+        errors.append(seq => {
+            const entry = { seq, time, message: message.text, fatal };
+            if (name !== null)
+                entry.name = name;
+            if (stack !== null)
+                entry.stack = stack.text;
+            if (truncated)
+                entry.truncated = true;
+            return entry;
+        });
+        batcher.notify(true);
+    }
+    const api = {
+        handshake: () => JSON.stringify(handshake()),
+        drain(requestJson) {
+            var _a;
+            let parsed;
+            try {
+                parsed = JSON.parse(requestJson);
+            }
+            catch (error) {
+                throw new Error(`invalid drain request: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const request = (0, protocol_1.parseDrainRequest)(parsed);
+            if (!request.ok)
+                throw new Error(`invalid drain request: ${request.error}`);
+            const limit = Math.min((_a = request.value.limit) !== null && _a !== void 0 ? _a : limits.drainLimit, limits.drainLimit);
+            const result = { contextId, logs: logs.drain(request.value.logs, limit), errors: errors.drain(request.value.errors, limit) };
+            const asked = request.value.sources;
+            if (asked) {
+                result.sources = {};
+                for (const [name, ring] of sources)
+                    if (Object.prototype.hasOwnProperty.call(asked, name))
+                        result.sources[name] = ring.drain(asked[name], limit);
+            }
+            return JSON.stringify(result);
+        },
+        commands: () => JSON.stringify(registry.list()),
+        async call(requestJson) {
+            let result;
+            try {
+                const request = (0, protocol_1.parseCommandCall)(JSON.parse(requestJson));
+                result = request.ok
+                    ? await registry.call(request.value.name, request.value.args === undefined ? null : request.value.args)
+                    : { ok: false, error: { code: 'command_failed', message: `invalid command request: ${request.error}` } };
+            }
+            catch (error) {
+                result = { ok: false, error: { code: 'command_failed', message: `invalid command request: ${error instanceof Error ? error.message : String(error)}` } };
+            }
+            return JSON.stringify(result);
+        },
+        dispose: () => sdk.stop(),
+    };
+    function container() {
+        const existing = host[protocol_1.GLOBAL_NAME];
+        if (typeof existing === 'object' && existing !== null)
+            return existing;
+        const created = {};
+        host[protocol_1.GLOBAL_NAME] = created;
+        return created;
+    }
+    const sdk = {
+        get started() {
+            return started;
+        },
+        contextId,
+        limits,
+        api,
+        registerCommand: (name, handler, meta) => registry.register(name, handler, meta),
+        registerNavigation(ref) {
+            if (typeof ref !== 'object' || ref === null || typeof ref.getRootState !== 'function' || typeof ref.addListener !== 'function')
+                throw new TypeError('a navigation ref needs getRootState and addListener');
+            if (host.__DEV__ === false)
+                return () => undefined; // never active in a release build
+            if (stopNavigation)
+                stopNavigation(); // Fast Refresh re-runs modules: the new ref replaces the old one
+            sources.set('navigation', navigationRing);
+            const stop = (0, navigation_js_1.followNavigation)(ref, data => {
+                navigationRing.append(seq => ({ seq, time: now(), data }));
+                batcher.notify(false);
+            });
+            stopNavigation = stop;
+            return () => {
+                stop();
+                if (stopNavigation === stop)
+                    stopNavigation = null;
+            };
+        },
+        registerStore: (name, store, options) => stores.registerStore(name, store, options),
+        registerQueryClient: (name, client) => stores.registerQueryClient(name, client),
+        handshake,
+        start() {
+            if (host.__DEV__ === false)
+                return false; // never active in a release build
+            if (started)
+                return true;
+            const target = container();
+            if (target.sdk && typeof target.sdk.dispose === 'function')
+                target.sdk.dispose(); // an older instance of this module (for example after a hot reload) steps aside
+            captures.push((0, console_capture_js_1.installConsoleCapture)(host, appendLog));
+            const errorCapture = (0, error_capture_js_1.installErrorCapture)(host, appendError);
+            if (errorCapture)
+                captures.push(errorCapture);
+            if (options.network !== false) {
+                const network = (0, network_capture_js_1.installNetworkCapture)(host, {
+                    now,
+                    bodyChars: limits.networkBodyChars,
+                    headerChars: limits.networkHeaderChars,
+                    stackChars: limits.networkStackChars,
+                    onEntry: (data, time) => {
+                        networkRing.append(seq => ({ seq, time, data }));
+                        batcher.notify(false);
+                    },
+                });
+                if (network) {
+                    captures.push(network);
+                    sources.set('network', networkRing);
+                }
+            }
+            target.sdk = api;
+            started = true;
+            stores.start();
+            batcher.hello();
+            return true;
+        },
+        stop() {
+            if (!started)
+                return;
+            started = false;
+            for (const capture of captures.splice(0))
+                capture.uninstall();
+            if (stopNavigation)
+                stopNavigation();
+            stopNavigation = null;
+            stores.stop();
+            batcher.flush();
+            const target = host[protocol_1.GLOBAL_NAME];
+            if (target && target.sdk === api)
+                delete target.sdk;
+        },
+    };
+    return sdk;
+}

package/dist/snapshot.d.ts

@@ -0,0 +1,9 @@
+export interface Snapshot {
+    readonly value: unknown;
+    /** True when anything was cut: depth, a container's keys, the character budget, a long string. */
+    readonly truncated: boolean;
+}
+export declare function snapshotOf(value: unknown, maxChars: number, maxDepth: number): Snapshot;
+/** Dotted paths (three levels deep) where two snapshots differ, at most 30. */
+export declare function changedPaths(before: unknown, after: unknown): string[];
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/snapshot.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.snapshotOf = snapshotOf;
+exports.changedPaths = changedPaths;
+// Turns an app's state into a JSON-safe, masked, size-bounded copy (plan 0013, 13.9). Nothing here calls app code: no getter runs, no toJSON, no function is invoked, so a hostile or
+// huge state costs a bounded walk. Secret-looking keys are replaced and string values go through `scrubText` before the copy leaves the app.
+const protocol_1 = require("@parallax-rn/protocol");
+const MAX_KEYS = 100; // per object, array, map or set
+const MAX_STRING = 500;
+const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+function put(out, key, value) {
+    if (key === '__proto__')
+        Object.defineProperty(out, key, { value, enumerable: true, writable: true, configurable: true });
+    else
+        out[key] = value;
+}
+function walkItems(items, depth, seen, budget) {
+    const out = [];
+    for (let i = 0; i < items.length; i++) {
+        if (budget.left <= 0 || i >= MAX_KEYS) {
+            budget.truncated = true;
+            break;
+        }
+        out.push(walk(items[i], depth, seen, budget));
+    }
+    return out;
+}
+function walkObject(value, depth, seen, budget) {
+    const out = {};
+    let count = 0;
+    for (const key in value) {
+        if (!hasOwn(value, key))
+            continue;
+        if (budget.left <= 0 || count >= MAX_KEYS) {
+            budget.truncated = true;
+            break;
+        }
+        count++;
+        budget.left -= key.length + 4;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor || descriptor.get || descriptor.set)
+            put(out, key, '[Getter]');
+        else if ((0, protocol_1.isSecretKey)(key) && descriptor.value !== null && descriptor.value !== undefined)
+            put(out, key, protocol_1.REDACTED_TEXT);
+        else
+            put(out, key, walk(descriptor.value, depth, seen, budget));
+    }
+    return out;
+}
+function walk(value, depth, seen, budget) {
+    switch (typeof value) {
+        case 'string': {
+            const text = value.length > MAX_STRING ? ((budget.truncated = true), value.slice(0, MAX_STRING) + '…') : value;
+            budget.left -= text.length + 2;
+            return (0, protocol_1.scrubText)(text);
+        }
+        case 'number':
+            budget.left -= 8;
+            return Number.isFinite(value) ? value : String(value);
+        case 'boolean':
+            budget.left -= 5;
+            return value;
+        case 'undefined':
+            budget.left -= 11;
+            return '[undefined]';
+        case 'bigint':
+        case 'symbol':
+            budget.left -= 12;
+            return String(value);
+        case 'function':
+            budget.left -= 20;
+            return value.name ? `[Function ${String(value.name)}]` : '[Function]';
+        default:
+    }
+    if (value === null) {
+        budget.left -= 4;
+        return null;
+    }
+    const object = value;
+    if (seen.indexOf(object) !== -1)
+        return '[Circular]';
+    if (object instanceof Date)
+        return Number.isNaN(object.getTime()) ? 'Invalid Date' : object.toISOString();
+    if (object instanceof Error)
+        return `[${object.name}: ${(0, protocol_1.scrubText)(String(object.message).slice(0, MAX_STRING))}]`;
+    const kind = Array.isArray(object) ? `Array(${object.length})` : object instanceof Map ? `Map(${object.size})` : object instanceof Set ? `Set(${object.size})` : 'Object';
+    if (depth >= budget.maxDepth) {
+        budget.truncated = true;
+        return `[${kind}]`;
+    }
+    seen.push(object);
+    let out;
+    if (Array.isArray(object)) {
+        if (object.length > MAX_KEYS)
+            budget.truncated = true;
+        out = walkItems(object.slice(0, MAX_KEYS), depth + 1, seen, budget);
+    }
+    else if (object instanceof Map || object instanceof Set) {
+        const items = [];
+        const iterator = object.entries();
+        for (let step = iterator.next(); !step.done; step = iterator.next()) {
+            if (items.length >= MAX_KEYS) {
+                budget.truncated = true;
+                break;
+            }
+            items.push(object instanceof Map ? step.value : step.value[0]);
+        }
+        out = { [`[${kind}]`]: walkItems(items, depth + 1, seen, budget) };
+    }
+    else {
+        out = walkObject(object, depth + 1, seen, budget);
+    }
+    seen.pop();
+    return out;
+}
+function snapshotOf(value, maxChars, maxDepth) {
+    const budget = { left: maxChars, maxDepth, truncated: false };
+    const copy = walk(value, 0, [], budget);
+    if (budget.left <= 0)
+        budget.truncated = true;
+    return { value: copy, truncated: budget.truncated };
+}
+const MAX_CHANGED = 30;
+const IDENT = /^[A-Za-z_$][\w$]*$/;
+/** The path form of the desktop app and `app_data` (`user.items`, `a["x-y"]`): a key that is not a plain name is quoted. */
+const pathOf = (parent, key) => (IDENT.test(key) ? (parent === '' ? key : `${parent}.${key}`) : `${parent}[${JSON.stringify(key)}]`);
+const DIFF_DEPTH = 3;
+function diff(before, after, path, depth, out) {
+    if (out.length >= MAX_CHANGED)
+        return;
+    const plain = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+    if (plain(before) && plain(after) && depth < DIFF_DEPTH) {
+        const keys = Object.keys(before);
+        for (const key of Object.keys(after))
+            if (!hasOwn(before, key))
+                keys.push(key);
+        for (let i = 0; i < keys.length; i++) {
+            const key = keys[i];
+            diff(before[key], after[key], pathOf(path, key), depth + 1, out);
+        }
+    }
+    else if (JSON.stringify(before) !== JSON.stringify(after)) {
+        out.push(path === '' ? '(root)' : path);
+    }
+}
+/** Dotted paths (three levels deep) where two snapshots differ, at most 30. */
+function changedPaths(before, after) {
+    const out = [];
+    diff(before, after, '', 0, out);
+    return out;
+}