lemon-model 1.2.2 → 1.2.3

package/dist/esm/index.js

@@ -13,4 +13,6 @@ export * from './cores/index.js';
 export * from './socket/index.js';
 export * from './genai/index.js';
 export * from './buffer/index.js';
+export * from './progress/index.js';
+export * from './logtrace/index.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/esm/logtrace/index.js

@@ -0,0 +1,11 @@
+/**
+ * `logtrace/index.ts`
+ * - one-way realtime log stream (reporter/consumer) over a shared socket.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+export * from './logtrace.js';
+//! NOTE: the verification loop harness (`./testing`) is intentionally NOT re-exported here.
+//! It pulls in the in-memory socket simulator — import it via the isolated
+//! `lemon-model/logtrace/testing` entry so production bundles stay clean.
+//# sourceMappingURL=index.js.map

package/dist/esm/logtrace/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/logtrace/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,YAAY,CAAC;AAE3B,4FAA4F;AAC5F,2EAA2E;AAC3E,0EAA0E"}

package/dist/esm/logtrace/logtrace.js

@@ -0,0 +1,251 @@
+import { createFilteredNetwork } from '../socket/websocket.js';
+const DEFAULT_TYPE = 'log:trace';
+const DEFAULT_TYPE_PREFIX = 'log:';
+const DEFAULT_MIN_LEVEL = 'debug';
+const DEFAULT_FLUSH_COUNT = 20;
+const DEFAULT_FLUSH_INTERVAL_MS = 250;
+const DEFAULT_MAX_PACKET_BYTES = 64 * 1024;
+const DEFAULT_MAX_ENTRIES = 1000;
+const LEVEL_WEIGHT = { debug: 0, info: 1, warn: 2, error: 3 };
+/** create a batching log reporter over an injected send path */
+export const createLogTraceReporter = (sink, options) => new LogTraceReporter(sink, options);
+/** create a log consumer over a shared raw string network */
+export const createLogTraceConsumer = (network, options) => new LogTraceConsumer(network, options);
+/** server-side log reporter - batches entries and emits SocketMessage<LogTraceBatch> via the sink */
+class LogTraceReporter {
+    constructor(sink, options) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        this.buffer = [];
+        this.bufferBytes = 0;
+        this.seqNo = 0;
+        this.midNo = 0;
+        this.sentOnce = false;
+        this.closed = false;
+        const maxPacketBytes = (_a = options === null || options === void 0 ? void 0 : options.maxPacketBytes) !== null && _a !== void 0 ? _a : DEFAULT_MAX_PACKET_BYTES;
+        this.sink = sink;
+        this.type = (_b = options === null || options === void 0 ? void 0 : options.type) !== null && _b !== void 0 ? _b : DEFAULT_TYPE;
+        this.source = (_c = options === null || options === void 0 ? void 0 : options.source) !== null && _c !== void 0 ? _c : nextRandomSource();
+        this.minLevel = LEVEL_WEIGHT[(_d = options === null || options === void 0 ? void 0 : options.minLevel) !== null && _d !== void 0 ? _d : DEFAULT_MIN_LEVEL];
+        this.flushCount = (_e = options === null || options === void 0 ? void 0 : options.flushCount) !== null && _e !== void 0 ? _e : DEFAULT_FLUSH_COUNT;
+        this.flushIntervalMs = (_f = options === null || options === void 0 ? void 0 : options.flushIntervalMs) !== null && _f !== void 0 ? _f : DEFAULT_FLUSH_INTERVAL_MS;
+        this.maxBatchBytes = (_g = options === null || options === void 0 ? void 0 : options.maxBatchBytes) !== null && _g !== void 0 ? _g : Math.floor((maxPacketBytes * 3) / 4);
+        this.onError = options === null || options === void 0 ? void 0 : options.onError;
+    }
+    /** record one log entry. auto-flushes when a flush condition is reached */
+    log(level, message, json) {
+        if (this.closed)
+            return;
+        //! seq is issued only past this gate so a raised minLevel never creates seq gaps.
+        if (LEVEL_WEIGHT[level] < this.minLevel)
+            return;
+        const entry = { level, ts: Date.now(), message, seq: ++this.seqNo };
+        if (json !== undefined)
+            entry.json = json;
+        let bytes = byteLength(JSON.stringify(entry));
+        if (bytes > this.maxBatchBytes)
+            bytes = this.truncate(entry, bytes);
+        //! adding this entry would exceed the batch budget: flush the current buffer, start a new batch.
+        if (this.buffer.length > 0 && this.bufferBytes + bytes + 1 > this.maxBatchBytes)
+            this.flush();
+        this.buffer.push(entry);
+        this.bufferBytes += bytes + 1;
+        if (level === 'error' || this.buffer.length >= this.flushCount)
+            return this.flush();
+        if (this.flushIntervalMs <= 0)
+            return;
+        //! leading edge: the first batch of this reporter flushes immediately so the viewer never waits a window.
+        if (!this.sentOnce)
+            return this.flush();
+        if (!this.timer)
+            this.timer = setTimeout(() => this.flush(), this.flushIntervalMs);
+    }
+    debug(message, json) {
+        this.log('debug', message, json);
+    }
+    info(message, json) {
+        this.log('info', message, json);
+    }
+    warn(message, json) {
+        this.log('warn', message, json);
+    }
+    error(message, json) {
+        this.log('error', message, json);
+    }
+    /** send the buffered entries now */
+    flush() {
+        this.clearTimer();
+        if (this.buffer.length <= 0)
+            return;
+        const entries = this.buffer;
+        this.buffer = [];
+        this.bufferBytes = 0;
+        this.sentOnce = true;
+        const message = {
+            type: this.type,
+            data: { entries, source: this.source },
+            mid: `l${++this.midNo}`,
+        };
+        //! at-most-once: a failed batch is reported to onError and dropped. never breaks the caller.
+        try {
+            const result = this.sink(message);
+            if (result && typeof result.then === 'function')
+                result.catch(e => this.emitError(e, entries));
+        }
+        catch (e) {
+            this.emitError(e, entries);
+        }
+    }
+    /** flush + release the timer. later log calls are ignored */
+    close() {
+        this.flush();
+        this.closed = true;
+    }
+    /** fit an oversized entry into the batch budget: drop json first, then cut the message */
+    truncate(entry, bytes) {
+        const error = new Error(`@entry[${entry.seq}] exceeds batch budget(${this.maxBatchBytes}) - logtrace.truncate`);
+        entry.truncated = true;
+        if (entry.json !== undefined) {
+            delete entry.json;
+            bytes = byteLength(JSON.stringify(entry));
+        }
+        //! every removed character frees at least 1 byte, so this loop converges quickly.
+        while (bytes > this.maxBatchBytes && entry.message.length > 0) {
+            entry.message = entry.message.slice(0, Math.max(0, entry.message.length - (bytes - this.maxBatchBytes)));
+            bytes = byteLength(JSON.stringify(entry));
+        }
+        this.emitError(error, [entry]);
+        return bytes;
+    }
+    emitError(error, entries) {
+        var _a;
+        try {
+            (_a = this.onError) === null || _a === void 0 ? void 0 : _a.call(this, error, entries);
+        }
+        catch (_b) {
+            // The error observer must never break the reporter.
+        }
+    }
+    clearTimer() {
+        if (!this.timer)
+            return;
+        clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+}
+/** client-side log consumer - unpacks batches into a (ts, seq)-sorted ring buffer */
+class LogTraceConsumer {
+    constructor(network, options) {
+        var _a, _b, _c;
+        this.handlers = new Set();
+        this.sources = new Map();
+        this.entries = [];
+        this.typePrefix = (_a = options === null || options === void 0 ? void 0 : options.typePrefix) !== null && _a !== void 0 ? _a : DEFAULT_TYPE_PREFIX;
+        this.minLevel = LEVEL_WEIGHT[(_b = options === null || options === void 0 ? void 0 : options.minLevel) !== null && _b !== void 0 ? _b : DEFAULT_MIN_LEVEL];
+        this.maxEntries = (_c = options === null || options === void 0 ? void 0 : options.maxEntries) !== null && _c !== void 0 ? _c : DEFAULT_MAX_ENTRIES;
+        //! raw stage of the 2-stage filter: substring check without parsing.
+        const marker = `"type":"${this.typePrefix}`;
+        const filtered = createFilteredNetwork(network, raw => raw.includes(marker));
+        this.unsubscribe = filtered.onMessage(raw => this.receive(raw));
+    }
+    /** subscribe to received entries */
+    onEntry(handler) {
+        this.handlers.add(handler);
+        return () => {
+            this.handlers.delete(handler);
+        };
+    }
+    /** list retained entries in (ts, seq) ascending order */
+    list(query) {
+        var _a;
+        const min = LEVEL_WEIGHT[(_a = query === null || query === void 0 ? void 0 : query.minLevel) !== null && _a !== void 0 ? _a : DEFAULT_MIN_LEVEL];
+        let listed = min > 0 ? this.entries.filter(entry => LEVEL_WEIGHT[entry.level] >= min) : [...this.entries];
+        const limit = query === null || query === void 0 ? void 0 : query.limit;
+        if (limit !== undefined && limit >= 0 && listed.length > limit)
+            listed = listed.slice(listed.length - limit);
+        return listed;
+    }
+    /** observed wire loss - sum of (max seq - received count) per source */
+    get gapCount() {
+        let gaps = 0;
+        for (const state of this.sources.values())
+            gaps += Math.max(0, state.maxSeq - state.seen.size);
+        return gaps;
+    }
+    /** drop retained entries (subscriptions and loss accounting stay) */
+    clear() {
+        this.entries = [];
+    }
+    /** unsubscribe from the network. does NOT close the network (shared socket) */
+    close() {
+        this.unsubscribe();
+        this.handlers.clear();
+    }
+    receive(raw) {
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch (_a) {
+            return; // the raw substring filter is best-effort; a non-JSON hit is simply not ours.
+        }
+        if (!message || typeof message.type !== 'string' || !message.type.startsWith(this.typePrefix))
+            return;
+        const batch = message.data;
+        if (!batch || typeof batch.source !== 'string' || !Array.isArray(batch.entries))
+            return;
+        const state = this.stateOf(batch.source);
+        for (const entry of batch.entries) {
+            if (!isLogTraceEntry(entry))
+                continue;
+            //! dedup + loss accounting happen BEFORE the minLevel gate so gapCount stays a pure wire-loss metric.
+            if (state.seen.has(entry.seq))
+                continue;
+            state.seen.add(entry.seq);
+            if (entry.seq > state.maxSeq)
+                state.maxSeq = entry.seq;
+            if (LEVEL_WEIGHT[entry.level] < this.minLevel)
+                continue;
+            const accepted = Object.assign(Object.assign({}, entry), { source: batch.source });
+            this.store(accepted);
+            for (const handler of [...this.handlers])
+                handler(accepted);
+        }
+    }
+    /** binary-insert by (ts, seq) so list() never re-sorts; evict the oldest on overflow */
+    store(entry) {
+        let lo = 0;
+        let hi = this.entries.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (compareEntry(this.entries[mid], entry) <= 0)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        this.entries.splice(lo, 0, entry);
+        if (this.entries.length > this.maxEntries)
+            this.entries.shift();
+    }
+    stateOf(source) {
+        let state = this.sources.get(source);
+        if (!state) {
+            // ponytail: the per-source seen Set grows with log volume; swap to seq-range tracking if sessions get huge.
+            state = { maxSeq: 0, seen: new Set() };
+            this.sources.set(source, state);
+        }
+        return state;
+    }
+}
+let sourceNo = 0;
+const nextRandomSource = () => `src-${Math.random().toString(36).slice(2, 8)}${++sourceNo}`;
+const compareEntry = (a, b) => a.ts - b.ts || a.seq - b.seq;
+const isLogTraceEntry = (entry) => !!entry &&
+    typeof entry === 'object' &&
+    LEVEL_WEIGHT[entry.level] !== undefined &&
+    typeof entry.ts === 'number' &&
+    typeof entry.message === 'string' &&
+    Number.isInteger(entry.seq) &&
+    entry.seq > 0;
+const textEncoder = new TextEncoder();
+const byteLength = (value) => textEncoder.encode(value).length;
+//# sourceMappingURL=logtrace.js.map

package/dist/esm/logtrace/logtrace.js.map

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

package/dist/esm/logtrace/testing.js

@@ -0,0 +1,77 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+/**
+ * `logtrace/testing.ts`
+ * - isolated entry for the logtrace verification loop harness.
+ * - kept OUT of the package root barrel so production bundles do not include the in-memory socket simulator.
+ *
+ * Usage (tests / dev only):
+ *   import { runLogTraceLoop } from 'lemon-model/logtrace/testing';
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import { createNetwork } from '../socket/socket.js';
+import { createLogTraceConsumer, createLogTraceReporter, } from './logtrace.js';
+/**
+ * Run an end-to-end verification loop:
+ * entries -> LogTraceReporter (batching) -> NetworkSupportable -> LogTraceConsumer (ring buffer).
+ *
+ * Metrics-based assertions belong in specs; this helper only records numbers.
+ */
+export const runLogTraceLoop = (options) => __awaiter(void 0, void 0, void 0, function* () {
+    const startedAt = Date.now();
+    const network = createNetwork(options.networkOptions);
+    // Raw packets measure batching and packet budgets, separate from delivery.
+    const rawPackets = [];
+    const unsubscribeRaw = network.onMessage(packet => rawPackets.push(packet));
+    const consumer = createLogTraceConsumer(network, options.consumerOptions);
+    let delivered = 0;
+    let truncated = 0;
+    // Consumer callbacks are the source of delivered/truncated metrics.
+    const unsubscribeEntry = consumer.onEntry(entry => {
+        delivered += 1;
+        if (entry.truncated)
+            truncated += 1;
+    });
+    let batches = 0;
+    const reporter = createLogTraceReporter(message => {
+        batches += 1;
+        network.send(JSON.stringify(message));
+    }, options.reporterOptions);
+    try {
+        // Replay input synchronously; reporter options decide when batches flush.
+        for (const record of options.entries)
+            reporter.log(record.level, record.message, record.json);
+        reporter.close();
+        yield new Promise(resolve => { var _a; return setTimeout(resolve, (_a = options.settleMs) !== null && _a !== void 0 ? _a : 50); });
+        const packetBytes = rawPackets.reduce((sum, packet) => sum + byteLength(packet), 0);
+        const maxPacketBytes = rawPackets.reduce((max, packet) => Math.max(max, byteLength(packet)), 0);
+        return {
+            elapsedMs: Date.now() - startedAt,
+            packets: rawPackets.length,
+            packetBytes,
+            maxPacketBytes,
+            batches,
+            delivered,
+            truncated,
+            gapCount: consumer.gapCount,
+            finalEntries: consumer.list(),
+        };
+    }
+    finally {
+        unsubscribeRaw();
+        unsubscribeEntry();
+        consumer.close();
+        network.close();
+    }
+});
+const textEncoder = new TextEncoder();
+const byteLength = (value) => textEncoder.encode(value).length;
+//# sourceMappingURL=testing.js.map

package/dist/esm/logtrace/testing.js.map

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

package/dist/esm/progress/index.js

@@ -0,0 +1,9 @@
+/**
+ * `progress/index.ts`
+ * - public re-export for the progress module.
+ * - `./testing` is intentionally excluded from this barrel (subpath-only, see SPEC.md).
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+export * from './progress.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/progress/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/progress/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,YAAY,CAAC"}

package/dist/esm/progress/progress.js

@@ -0,0 +1,256 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { createFilteredNetwork } from '../socket/websocket.js';
+/** default serialized packet size limit (same family as `src/socket`) */
+export const DEFAULT_MAX_PACKET_BYTES = 64 * 1024;
+/** time-flow gauge - elapsed ratio against expectedMs, capped at 99% (only done() declares completion) */
+export const createTimeProgressGauge = (expectedMs, now = Date.now) => {
+    const startedAt = now();
+    return () => {
+        if (!(expectedMs > 0))
+            return { percent: 99 };
+        const percent = Math.floor(((now() - startedAt) / expectedMs) * 100);
+        return { percent: Math.min(99, Math.max(0, percent)) };
+    };
+};
+/** buffer-fill gauge - reads percent/bufferPercent from a GenAIStreamProgress-compatible source (structural type, no src/buffer dependency) */
+export const createBufferProgressGauge = (source) => {
+    return () => {
+        var _a;
+        const snapshot = source();
+        const percent = (_a = snapshot === null || snapshot === void 0 ? void 0 : snapshot.percent) !== null && _a !== void 0 ? _a : snapshot === null || snapshot === void 0 ? void 0 : snapshot.bufferPercent;
+        return percent === undefined ? {} : { percent };
+    };
+};
+const GAUGE_KEYS = ['percent', 'step', 'totalSteps', 'label'];
+const textEncoder = new TextEncoder();
+const byteLength = (value) => textEncoder.encode(value).length;
+/** assign only defined values so a partial patch never erases fields */
+const assignDefined = (target, patch) => {
+    if (!patch)
+        return;
+    for (const key of Object.keys(patch)) {
+        if (patch[key] !== undefined)
+            target[key] = patch[key];
+    }
+};
+/** create a server-side progress reporter over an injected sink */
+export const createProgressReporter = (sink, options) => {
+    var _a, _b, _c, _d;
+    const type = (_a = options === null || options === void 0 ? void 0 : options.type) !== null && _a !== void 0 ? _a : 'progress:update';
+    const throttleMs = (_b = options === null || options === void 0 ? void 0 : options.throttleMs) !== null && _b !== void 0 ? _b : 0;
+    const heartbeatMs = (_c = options === null || options === void 0 ? void 0 : options.heartbeatMs) !== null && _c !== void 0 ? _c : 0;
+    const maxPacketBytes = (_d = options === null || options === void 0 ? void 0 : options.maxPacketBytes) !== null && _d !== void 0 ? _d : DEFAULT_MAX_PACKET_BYTES;
+    const tasks = new Map();
+    let seq = 0;
+    let mid = 0;
+    const notifyError = (error, state) => { var _a; return (_a = options === null || options === void 0 ? void 0 : options.onError) === null || _a === void 0 ? void 0 : _a.call(options, error, state); };
+    /** the reporter never interrupts task code: sink throw/reject only reaches onError */
+    const dispatch = (message) => {
+        try {
+            const result = sink(message);
+            if (result && typeof result.then === 'function') {
+                result.then(undefined, error => notifyError(error, message.data));
+            }
+        }
+        catch (error) {
+            notifyError(error, message.data);
+        }
+    };
+    const emit = (task) => {
+        task.dirty = false;
+        const snapshot = Object.assign(Object.assign({}, task.local), { ts: Date.now(), seq: ++seq });
+        if (task.gauge) {
+            try {
+                const measure = task.gauge();
+                for (const key of GAUGE_KEYS) {
+                    if (snapshot[key] === undefined && measure[key] !== undefined)
+                        snapshot[key] = measure[key];
+                }
+            }
+            catch (error) {
+                notifyError(error, snapshot);
+            }
+        }
+        let message = { type, data: snapshot, mid: `p${++mid}` };
+        if (snapshot.meta !== undefined && byteLength(JSON.stringify(message)) > maxPacketBytes) {
+            const { meta: _meta } = snapshot, stripped = __rest(snapshot, ["meta"]);
+            message = Object.assign(Object.assign({}, message), { data: stripped });
+            notifyError(new Error(`progress packet exceeds maxPacketBytes:${maxPacketBytes}`), snapshot);
+        }
+        task.last = message.data;
+        dispatch(message);
+    };
+    /** trailing edge: emit the latest snapshot once per window while updates keep arriving */
+    const openWindow = (task) => {
+        task.timer = setTimeout(() => {
+            task.timer = undefined;
+            if (!task.dirty || task.closed)
+                return;
+            emit(task);
+            openWindow(task);
+        }, throttleMs);
+    };
+    const cancelWindow = (task) => {
+        if (!task.timer)
+            return;
+        clearTimeout(task.timer);
+        task.timer = undefined;
+    };
+    const finish = (task, status, patch) => {
+        if (task.closed)
+            return;
+        task.closed = true;
+        cancelWindow(task);
+        assignDefined(task.local, patch);
+        task.local.status = status;
+        emit(task);
+    };
+    const heartbeatTimer = heartbeatMs > 0
+        ? setInterval(() => {
+            tasks.forEach(task => {
+                if (!task.closed && task.local.status === 'running')
+                    emit(task);
+            });
+        }, heartbeatMs)
+        : undefined;
+    return {
+        start: (id, initial, taskOptions) => {
+            const existing = tasks.get(id);
+            if (existing)
+                return existing.handle;
+            const local = { id, status: 'pending', ts: 0, seq: 0 };
+            assignDefined(local, initial);
+            const task = {
+                local,
+                last: local,
+                gauge: taskOptions === null || taskOptions === void 0 ? void 0 : taskOptions.gauge,
+                dirty: false,
+                closed: false,
+                handle: {
+                    id,
+                    get state() {
+                        return task.last;
+                    },
+                    update: patch => {
+                        if (task.closed)
+                            return;
+                        const _a = patch !== null && patch !== void 0 ? patch : {}, { status } = _a, rest = __rest(_a, ["status"]);
+                        if (status && !(status === 'pending' && task.local.status === 'running')) {
+                            task.local.status = status;
+                        }
+                        assignDefined(task.local, rest);
+                        if (throttleMs <= 0)
+                            return emit(task);
+                        if (task.timer) {
+                            task.dirty = true;
+                            return;
+                        }
+                        emit(task);
+                        openWindow(task);
+                    },
+                    done: patch => finish(task, 'done', patch),
+                    error: (error, patch) => {
+                        var _a;
+                        task.local.error = typeof error === 'string' ? error : `${(_a = error === null || error === void 0 ? void 0 : error.message) !== null && _a !== void 0 ? _a : error}`;
+                        finish(task, 'error', patch);
+                    },
+                },
+            };
+            tasks.set(id, task);
+            emit(task);
+            return task.handle;
+        },
+        close: () => {
+            if (heartbeatTimer)
+                clearInterval(heartbeatTimer);
+            tasks.forEach(task => {
+                cancelWindow(task);
+                if (task.dirty && !task.closed)
+                    emit(task);
+            });
+        },
+    };
+};
+/** create a client-side progress consumer on a shared network */
+export const createProgressConsumer = (network, options) => {
+    var _a, _b;
+    const typePrefix = (_a = options === null || options === void 0 ? void 0 : options.typePrefix) !== null && _a !== void 0 ? _a : 'progress:';
+    const maxTasks = Math.max(1, (_b = options === null || options === void 0 ? void 0 : options.maxTasks) !== null && _b !== void 0 ? _b : 100);
+    const rawKey = `"type":"${typePrefix}`;
+    /** two-stage filter: raw substring check (no parse) then parsed type re-check */
+    const filtered = createFilteredNetwork(network, raw => raw.includes(rawKey));
+    const store = new Map();
+    const handlers = new Set();
+    const evict = (keepId) => {
+        if (store.size <= maxTasks)
+            return;
+        let evictId;
+        for (const [id, state] of store) {
+            if (id !== keepId && (state.status === 'done' || state.status === 'error')) {
+                evictId = id;
+                break;
+            }
+        }
+        if (evictId === undefined) {
+            for (const id of store.keys()) {
+                if (id !== keepId) {
+                    evictId = id;
+                    break;
+                }
+            }
+        }
+        if (evictId !== undefined)
+            store.delete(evictId);
+    };
+    const unsubscribe = filtered.onMessage(raw => {
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch (_a) {
+            return;
+        }
+        if (typeof (message === null || message === void 0 ? void 0 : message.type) !== 'string' || !message.type.startsWith(typePrefix))
+            return;
+        const state = message.data;
+        if (!state || typeof state.id !== 'string' || typeof state.seq !== 'number')
+            return;
+        const existing = store.get(state.id);
+        if (existing && state.seq <= existing.seq)
+            return;
+        store.set(state.id, state);
+        if (!existing)
+            evict(state.id);
+        for (const handler of [...handlers]) {
+            try {
+                handler({ state, created: !existing });
+            }
+            catch (_b) {
+                // a subscriber error must not break other subscribers or the shared network
+            }
+        }
+    });
+    return {
+        get: id => store.get(id),
+        list: () => [...store.values()],
+        onChange: handler => {
+            handlers.add(handler);
+            return () => handlers.delete(handler);
+        },
+        close: () => {
+            unsubscribe();
+            handlers.clear();
+        },
+    };
+};
+//# sourceMappingURL=progress.js.map