@syncular/client 0.19.0 → 0.20.1

package/dist/client.js

@@ -1,3 +1,4 @@
+import { ProgressEmitter, } from './progress.js';
 /**
  * SyncClient implements the client side of SPEC.md §§3–8.
  *
@@ -8,7 +9,7 @@
  * `sync()` round (§7.2); local reads go straight to the database.
  */
 import { canonicalScopeJson, decodeMessage, decodeRow, decodeRowsSegment, encodeMessage, encodePresencePublish, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseRealtimeServerEvent, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, } from '@syncular/core';
-import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, evictScopedRows, upsertLocalRow, } from './apply.js';
+import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, evictScopedRows, yieldToHost, upsertLocalRow, } from './apply.js';
 import { clearPendingUpload, computeBlobId, deleteUnreferencedCachedBlobs, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
 import { registerDevtools } from './devtools.js';
 import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS, } from './diagnostics.js';
@@ -102,6 +103,8 @@ export class SyncClient {
     #realtimeGeneration = 0;
     #pendingRound;
     #needsPull = false;
+    #progress = new ProgressEmitter();
+    #progressAttempt = 0;
     #syncing = false;
     /**
      * True from the synchronous entry of `sync()` until its serialized round
@@ -233,6 +236,7 @@ export class SyncClient {
         // an application-issued sync() call.
         const startupWork = this.#schemaFloor === undefined &&
             (countOutbox(this.#db) > 0 ||
+                loadPendingEvictions(this.#db).length > 0 ||
                 subscriptions.some((sub) => sub.status === 'active'));
         if (startupWork && this.#securityLifecycle === 'active') {
             this.#needsPull = true;
@@ -359,6 +363,7 @@ export class SyncClient {
         await this.#lease?.release();
         this.#lease = undefined;
         this.#started = false;
+        this.#progress.clear();
         this.#syncNeededListeners.clear();
         this.#syncIntentListeners.clear();
     }
@@ -537,6 +542,12 @@ export class SyncClient {
         return this.#invalidation.on(listener);
     }
     /** Subscribe to exact revisioned observer transactions (SPEC §7.5). */
+    onProgress(listener) {
+        return this.#progress.on(listener);
+    }
+    progressSnapshot() {
+        return this.#progress.snapshot();
+    }
     onChange(listener) {
         return this.#changes.on(listener);
     }
@@ -1116,22 +1127,17 @@ export class SyncClient {
         }
         socket.send(encodePresencePublish(scopeKey, doc));
     }
-    /**
-     * §4.2 accept mask: the configured override, or the rows baseline plus
-     * bit 2 when the backend can import sqlite images (§5.3) and a segment
-     * downloader exists (sqlite segments are never inline, §5.7), plus
-     * bit 3 when the downloader exposes a direct URL fetch (§5.4
-     * capability negotiation).
-     */
+    /** Advertise supported segment formats; all imports yield between commits. */
     #acceptMask() {
         const configured = this.#config.limits?.accept;
         if (configured !== undefined)
             return configured;
         const segments = this.#config.segments;
-        const sqliteCapable = typeof this.#db.withSqliteImage === 'function' && segments !== undefined;
         const urlCapable = typeof segments?.fetchUrl === 'function';
         return (ACCEPT_ROWS_BASELINE |
-            (sqliteCapable ? ACCEPT_SQLITE : 0) |
+            (typeof this.#db.withSqliteImage === 'function' && segments !== undefined
+                ? ACCEPT_SQLITE
+                : 0) |
             (urlCapable ? ACCEPT_SIGNED_URLS : 0));
     }
     subscriptions() {
@@ -1189,8 +1195,8 @@ export class SyncClient {
      * Set the live window units for a base (§4.8): a value-sharded family of
      * subscriptions, one per unit. Computes the diff against the registry —
      * added units get fresh subscriptions (image-lane bootstrap on the next
-     * sync); removed units are unsubscribed and evicted, fused in one local
-     * transaction (E1–E4). Idempotent: calling with the same units is a
+     * sync); removed units are unsubscribed with their first eviction chunk
+     * in one local transaction (E1–E4). Idempotent: calling with the same units is a
      * no-op. Re-entry (a unit removed then re-added) cancels any deferred
      * eviction and fresh-bootstraps.
      *
@@ -1248,7 +1254,7 @@ export class SyncClient {
             for (const { unit, subId } of live) {
                 if (wanted.has(unit))
                     continue;
-                this.#evictUnit(baseKey, base, unit, subId);
+                await this.#evictUnit(baseKey, base, unit, subId);
                 changed = true;
             }
         });
@@ -1287,8 +1293,8 @@ export class SyncClient {
         return { units: live.map((u) => u.unit), pending };
     }
     /**
-     * §4.8 E1–E4: evict one departing unit, fused with its unsubscription in
-     * one transaction. Deletes the unit's rows EXCEPT those pinned by a
+     * §4.8 E1–E4: evict one departing unit in committed chunks, fusing
+     * its first chunk with unsubscription. Deletes the unit's rows EXCEPT those pinned by a
      * pending outbox commit (E1); if any pin remains, records a deferred
      * eviction retried on the next outbox drain. Discards the subscription's
      * cursor/resume/effective-echo (E3) and its version state with the rows
@@ -1296,19 +1302,21 @@ export class SyncClient {
      * with no local scope-column mapping, surfaces a configuration error and
      * evicts nothing (§4.8/§3.3).
      */
-    #evictUnit(baseKey, base, unit, subId) {
+    async #evictUnit(baseKey, base, unit, subId) {
         const table = this.#table(base.table);
         const sub = getSubscription(this.#db, subId);
         // The rows a unit holds live under its LAST effective scopes if it ever
         // synced; before first sync, the requested unit scopes are the match.
         const effective = sub?.effectiveScopes ?? unitScopes(base, unit);
         const pinned = this.#pinnedRowIds(base.table);
+        let remaining = false;
         this.#applyBatch((batch) => {
             this.#db.transaction(() => {
-                const deferred = evictScopedRows(this.#db, table, effective, pinned);
+                const result = evictScopedRows(this.#db, table, effective, pinned);
+                remaining = result.remaining;
                 deleteWindowUnit(this.#db, baseKey, unit);
                 deleteSubscription(this.#db, subId);
-                if (deferred) {
+                if (result.deferred) {
                     savePendingEviction(this.#db, subId, base.table, effective);
                 }
                 else {
@@ -1320,13 +1328,17 @@ export class SyncClient {
             this.#needsPull = true;
             batch.status();
         });
+        if (remaining) {
+            await yieldToHost();
+            await this.#drainPendingEvictions();
+        }
     }
     /**
      * §4.8 E1: retry deferred evictions after the outbox drains. A pinned
      * unit's rows are removed once no pending commit references them; a unit
      * that re-entered the window in the meantime has no pending record left.
      */
-    #drainPendingEvictions() {
+    async #drainPendingEvictions() {
         const pending = loadPendingEvictions(this.#db);
         if (pending.length === 0)
             return;
@@ -1336,16 +1348,23 @@ export class SyncClient {
                 deletePendingEviction(this.#db, entry.subId);
                 continue;
             }
-            const pinned = this.#pinnedRowIds(entry.table);
-            this.#applyBatch((batch) => {
-                let deferred = false;
-                this.#db.transaction(() => {
-                    deferred = evictScopedRows(this.#db, table, entry.effective, pinned);
-                    if (!deferred)
+            let remaining;
+            do {
+                if (!loadPendingEvictions(this.#db).some((item) => item.subId === entry.subId))
+                    break;
+                // Local writes may add pins while the worker yields between chunks.
+                const pinned = this.#pinnedRowIds(entry.table);
+                remaining = false;
+                this.#applyBatch((batch) => {
+                    const result = evictScopedRows(this.#db, table, entry.effective, pinned);
+                    remaining = result.remaining;
+                    if (!result.deferred)
                         deletePendingEviction(this.#db, entry.subId);
+                    batch.scopeMap(table, entry.effective);
                 });
-                batch.scopeMap(table, entry.effective);
-            });
+                if (remaining)
+                    await yieldToHost();
+            } while (remaining);
         }
     }
     /**
@@ -1837,6 +1856,12 @@ export class SyncClient {
         }, (error) => {
             const completedAtMs = this.#now();
             const code = error.code;
+            this.#progress.update({
+                state: 'failed',
+                errorCode: typeof code === 'string'
+                    ? this.#diagnosticCode(code)
+                    : 'client.unknown_failure',
+            });
             this.#lastRound = {
                 status: 'failed',
                 startedAtMs,
@@ -1883,7 +1908,15 @@ export class SyncClient {
             : 'client.unknown_failure';
     }
     async #runSync() {
+        this.#progress.emit({
+            attempt: ++this.#progressAttempt,
+            state: 'running',
+            phase: 'request',
+            bytesReceived: 0,
+            rowsProcessed: 0,
+        });
         if (this.#schemaFloor !== undefined) {
+            this.#progress.update({ state: 'complete' });
             return {
                 ...emptySummary(0),
                 bootstrapping: [],
@@ -1896,6 +1929,7 @@ export class SyncClient {
         // survive it — the reference server keeps no replay buffer (§8.2).
         this.#setSyncNeeded(false);
         try {
+            await this.#drainPendingEvictions();
             const logEpoch = getMeta(this.#db, LOG_EPOCH_META_KEY);
             // §5.9.7 B4: upload pending blobs BEFORE pushing rows that reference
             // them, so the server-side existence check (§6.6) passes.
@@ -1957,7 +1991,10 @@ export class SyncClient {
             const summary = await this.#processResponse(message, outbox, subs, 'pull', resetEpoch);
             // §4.8 E1: the push half may have drained commits that pinned rows of
             // a shrunk window unit — retry any deferred evictions now.
-            this.#drainPendingEvictions();
+            await this.#drainPendingEvictions();
+            this.#progress.update(summary.failed.length > 0
+                ? { state: 'failed', errorCode: 'sync.scope_revoked' }
+                : { state: 'complete' });
             this.#retryDelayMs = 250;
             if (deferred > 0) {
                 // §6.1 splitBatch remainder: more queued commits than this request
@@ -2001,10 +2038,21 @@ export class SyncClient {
      * Pull repeatedly until quiescent: no commits delivered, no bootstrap
      * pages pending, no resets to recover (§4.5 "pull again" SHOULD).
      */
-    async syncUntilIdle(maxRounds = 20) {
+    async syncUntilIdle(maxRounds) {
+        const budget = maxRounds ?? 20;
         let last;
-        for (let round = 0; round < maxRounds; round++) {
+        for (let round = 0; round < budget; round++) {
+            const before = JSON.stringify(loadSubscriptions(this.#db).map((sub) => [sub.id, sub.bootstrapState]));
             last = await this.sync();
+            if (maxRounds === undefined &&
+                last.segmentRowsApplied > 0 &&
+                last.bootstrapping.length > 0 &&
+                before !==
+                    JSON.stringify(loadSubscriptions(this.#db).map((sub) => [
+                        sub.id,
+                        sub.bootstrapState,
+                    ])))
+                round = -1;
             if (last.schemaFloor !== undefined)
                 return last;
             if (last.commitsApplied === 0 &&
@@ -2016,7 +2064,7 @@ export class SyncClient {
                 return last;
             }
         }
-        throw new ClientSyncError('sync.invalid_request', `sync did not reach idle within ${maxRounds} rounds`);
+        throw new ClientSyncError('sync.invalid_request', 'sync did not reach idle within the round budget');
     }
     /**
      * One request/response round trip (§8.7): over the socket whenever it
@@ -2430,8 +2478,20 @@ export class SyncClient {
                             break;
                         }
                         const segment = decodeRowsSegment(frame.payload);
+                        this.#progress.update({
+                            phase: 'import',
+                            subscriptionId: section.sub.id,
+                            table: section.sub.table,
+                            segmentId: undefined,
+                            bytesReceived: frame.payload.byteLength,
+                            bytesTotal: frame.payload.byteLength,
+                            rowsProcessed: 0,
+                            rowsTotal: segment.blocks.reduce((n, block) => n + block.length, 0),
+                        });
                         await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective) => applyRowsSegment(this.#db, this.#schema, table, segment, {
                             clearFirst,
+                            isCurrent: () => this.#localResetEpoch === resetEpoch,
+                            onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
                             effective,
                             transaction: (fn) => this.#applyBatch((batch) => {
                                 if (segment.blocks.some((block) => block.length > 0) ||
@@ -2439,7 +2499,9 @@ export class SyncClient {
                                         this.#scopedRowsExist(table, effective))) {
                                     batch.table(table.name);
                                 }
-                                return fn();
+                                const result = fn();
+                                this.#replayOutbox();
+                                return result;
                             }),
                         }, this.#encryption), section.fresh && !section.cleared);
                         break;
@@ -2457,6 +2519,7 @@ export class SyncClient {
                             throw new ClientSyncError('sync.invalid_request', 'SEGMENT_REF mediaType sqlite was not advertised in accept (§4.2)');
                         }
                         const bytes = await this.#downloadSegment(frame, section.sub);
+                        this.#progress.update({ phase: 'import' });
                         if (frame.mediaType === 'sqlite') {
                             // §5.3: images are whole-table — a paged descriptor is
                             // invalid, and the image is always its table's first page.
@@ -2471,6 +2534,8 @@ export class SyncClient {
                                 scopeDigest: frame.scopeDigest,
                             }, {
                                 clearFirst,
+                                isCurrent: () => this.#localResetEpoch === resetEpoch,
+                                onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
                                 effective,
                                 transaction: (fn) => this.#applyBatch((batch) => {
                                     if (frame.rowCount > 0 ||
@@ -2478,7 +2543,9 @@ export class SyncClient {
                                             this.#scopedRowsExist(table, effective))) {
                                         batch.table(table.name);
                                     }
-                                    return fn();
+                                    const result = fn();
+                                    this.#replayOutbox();
+                                    return result;
                                 }),
                             }), section.fresh && !section.cleared);
                         }
@@ -2486,6 +2553,8 @@ export class SyncClient {
                             const segment = decodeRowsSegment(bytes);
                             await this.#applySegmentOrFail(section, summary, (table, clearFirst, effective) => applyRowsSegment(this.#db, this.#schema, table, segment, {
                                 clearFirst,
+                                isCurrent: () => this.#localResetEpoch === resetEpoch,
+                                onProgress: (rowsProcessed) => this.#progress.update({ rowsProcessed }),
                                 effective,
                                 transaction: (fn) => this.#applyBatch((batch) => {
                                     if (segment.blocks.some((block) => block.length > 0) ||
@@ -2493,7 +2562,9 @@ export class SyncClient {
                                             this.#scopedRowsExist(table, effective))) {
                                         batch.table(table.name);
                                     }
-                                    return fn();
+                                    const result = fn();
+                                    this.#replayOutbox();
+                                    return result;
                                 }),
                             }, this.#encryption), section.fresh &&
                                 !section.cleared &&
@@ -2790,6 +2861,19 @@ export class SyncClient {
         if (downloader === undefined) {
             throw new ClientSyncError('sync.invalid_request', 'received SEGMENT_REF but no segment downloader is configured');
         }
+        this.#progress.update({
+            phase: 'download',
+            subscriptionId: sub.id,
+            table: frame.table,
+            segmentId: frame.segmentId,
+            bytesReceived: 0,
+            bytesTotal: frame.byteLength,
+            rowsProcessed: 0,
+            rowsTotal: frame.rowCount,
+        });
+        const onProgress = (bytesReceived) => {
+            this.#progress.update({ bytesReceived });
+        };
         let bytes;
         if (frame.url !== undefined) {
             // §5.4: a url-carrying descriptor MUST be fetched from that URL —
@@ -2806,18 +2890,20 @@ export class SyncClient {
                 // §5.4: MUST NOT start a fetch at/past expiry.
                 throw new ClientSyncError('sync.segment_expired', `signed URL for segment ${frame.segmentId} expired before fetch — re-pull mints fresh descriptors (§5.4)`, true);
             }
-            bytes = await fetchUrl(frame.url);
+            bytes = await fetchUrl(frame.url, onProgress);
         }
         else {
             bytes = await downloader({
                 segmentId: frame.segmentId,
                 table: frame.table,
                 requestedScopesJson: canonicalScopeJson(sub.scopes),
+                onProgress,
             });
         }
         // §5.1: verify the content address before applying; on mismatch the
         // segment is discarded and the cursor/resume token stay unpersisted,
         // so the next pull re-delivers.
+        onProgress(bytes.byteLength);
         const hash = await sha256Hex(bytes);
         if (`sha256:${hash}` !== frame.segmentId) {
             throw new ClientSyncError('sync.invalid_request', `segment ${frame.segmentId} failed content-address verification (§5.1)`, true);

package/dist/database.d.ts

@@ -20,11 +20,12 @@ export interface ClientDatabase {
     /**
      * Optional sqlite-image capability (SPEC §5.3): expose `bytes` as an
      * attached read-only database schema named `alias` for the duration of
-     * `fn`, then detach. Presence of this method is what makes the client
+     * `fn`, awaiting its result before detaching. No transaction spans its awaits.
+     * Presence of this method is what makes the client
      * advertise `accept` bit 2 (§4.2). MUST be called outside any open
      * transaction (SQLite cannot ATTACH inside one); `fn` may open its own.
      */
-    withSqliteImage?<T>(bytes: Uint8Array, alias: string, fn: () => T): T;
+    withSqliteImage?<T>(bytes: Uint8Array, alias: string, fn: () => T | Promise<T>): Promise<T>;
     close(): void;
 }
 /** Attach-schema aliases are code-chosen, never user input — enforce it. */

package/dist/http.d.ts

@@ -16,14 +16,6 @@ export declare function httpSyncTransport(syncUrl: string, options?: HttpTranspo
 export declare function httpRemoteOperationTransport(operationsUrl: string, options?: HttpTransportOptions): RemoteOperationTransport;
 /** WebSocket connector for registered query snapshots. */
 export declare function webSocketRemoteOperationConnector(realtimeUrl: string): RemoteOperationRealtimeConnector;
-/**
- * §5.5 direct endpoint with the `X-Syncular-Scopes` re-authorization
- * header, plus the §5.4 `fetchUrl` capability (advertises accept bit 3).
- * `fetchUrl` sends NO headers at all — the signed URL is the entire
- * grant, and host auth must never leak to CDN/object hosts (§5.4).
- * Resolution (which path a descriptor takes, expiry, no fall-through)
- * lives in the client core, not here.
- */
 export declare function httpSegmentDownloader(segmentsBaseUrl: string, options?: HttpTransportOptions): SegmentDownloader;
 /**
  * §5.9.3/§5.9.5 blob transport: host-authenticated `PUT`/`GET

package/dist/http.js

@@ -97,6 +97,39 @@ export function webSocketRemoteOperationConnector(realtimeUrl) {
  * Resolution (which path a descriptor takes, expiry, no fall-through)
  * lives in the client core, not here.
  */
+async function readSegmentBody(response, onProgress) {
+    const chunks = [];
+    let received = 0;
+    let reported = 0;
+    const reader = response.body?.getReader();
+    if (reader !== undefined) {
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                chunks.push(value);
+                received += value.byteLength;
+                if (received - reported >= 64 * 1024) {
+                    onProgress?.(received);
+                    reported = received;
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    if (received !== reported)
+        onProgress?.(received);
+    const bytes = new Uint8Array(received);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
 export function httpSegmentDownloader(segmentsBaseUrl, options) {
     const doFetch = options?.fetch ?? fetch;
     const direct = async (request) => {
@@ -108,15 +141,15 @@ export function httpSegmentDownloader(segmentsBaseUrl, options) {
         });
         if (!response.ok)
             await throwHttpError(response);
-        return new Uint8Array(await response.arrayBuffer());
+        return readSegmentBody(response, request.onProgress);
     };
-    const fetchUrl = async (url) => {
+    const fetchUrl = async (url, onProgress) => {
         // Deliberately headerless: the URL is the bearer grant (§5.4).
         const response = await doFetch(url);
         if (!response.ok) {
             throw new ClientSyncError('sync.transport_failed', `signed-URL fetch failed with HTTP ${response.status} (§5.4: descriptor invalidated, re-pull to recover)`, true);
         }
-        return new Uint8Array(await response.arrayBuffer());
+        return readSegmentBody(response, onProgress);
     };
     return Object.assign(direct, { fetchUrl });
 }

package/dist/index.d.ts

@@ -40,3 +40,4 @@ export * from './transport.js';
 export * from './window.js';
 export * from './worker-host.js';
 export * from './worker-protocol.js';
+export { ProgressEmitter, type SyncProgress, type SyncProgressListener, } from './progress.js';

package/dist/index.js

@@ -40,3 +40,4 @@ export * from './transport.js';
 export * from './window.js';
 export * from './worker-host.js';
 export * from './worker-protocol.js';
+export { ProgressEmitter, } from './progress.js';

package/dist/node-database.d.ts

@@ -12,7 +12,7 @@ export declare class NodeClientDatabase implements ClientDatabase {
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];
     transaction<T>(fn: () => T): T;
     /** §5.3 image import through a private file attached for one callback. */
-    withSqliteImage<T>(bytes: Uint8Array, alias: string, fn: () => T): T;
+    withSqliteImage<T>(bytes: Uint8Array, alias: string, fn: () => T | Promise<T>): Promise<T>;
     close(): void;
 }
 export declare function openNodeDatabase(path?: string): ClientDatabase;

package/dist/node-database.js

@@ -52,7 +52,7 @@ export class NodeClientDatabase {
         return runTransaction(this.#tx, (sql) => this.db.exec(sql), fn);
     }
     /** §5.3 image import through a private file attached for one callback. */
-    withSqliteImage(bytes, alias, fn) {
+    async withSqliteImage(bytes, alias, fn) {
         assertImageAlias(alias);
         const dir = mkdtempSync(join(tmpdir(), 'syncular-image-'));
         const path = join(dir, 'segment.db');
@@ -60,7 +60,7 @@ export class NodeClientDatabase {
             writeFileSync(path, bytes);
             this.db.prepare(`ATTACH DATABASE ? AS ${alias}`).run(path);
             try {
-                return fn();
+                return await fn();
             }
             finally {
                 this.db.prepare(`DETACH DATABASE ${alias}`).run();

package/dist/progress.d.ts

@@ -0,0 +1,24 @@
+/** Ephemeral sync work, independent of committed change notifications (SPEC §7.6). */
+export interface SyncProgress {
+    readonly attempt: number;
+    readonly state: 'running' | 'complete' | 'failed';
+    readonly phase: 'request' | 'download' | 'import';
+    readonly subscriptionId?: string;
+    readonly table?: string;
+    readonly segmentId?: string | undefined;
+    readonly bytesReceived: number;
+    readonly bytesTotal?: number;
+    readonly rowsProcessed: number;
+    readonly rowsTotal?: number;
+    readonly errorCode?: string;
+}
+export type SyncProgressListener = (progress: SyncProgress) => void;
+/** Shared by the direct client and event-forwarding handles. */
+export declare class ProgressEmitter {
+    #private;
+    clear(): void;
+    snapshot(): SyncProgress | undefined;
+    on(listener: SyncProgressListener): () => void;
+    emit(progress: SyncProgress): void;
+    update(update: Partial<SyncProgress>): void;
+}

package/dist/progress.js

@@ -0,0 +1,42 @@
+/** Shared by the direct client and event-forwarding handles. */
+export class ProgressEmitter {
+    #snapshot;
+    #listeners = new Set();
+    clear() {
+        this.#listeners.clear();
+        this.#snapshot = undefined;
+    }
+    snapshot() {
+        return this.#snapshot;
+    }
+    on(listener) {
+        this.#listeners.add(listener);
+        if (this.#snapshot !== undefined) {
+            try {
+                listener(this.#snapshot);
+            }
+            catch {
+                /* Observers cannot interrupt sync. */
+            }
+        }
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    emit(progress) {
+        const snapshot = Object.freeze({ ...progress });
+        this.#snapshot = snapshot;
+        for (const listener of [...this.#listeners]) {
+            try {
+                listener(snapshot);
+            }
+            catch {
+                /* Observers cannot interrupt sync. */
+            }
+        }
+    }
+    update(update) {
+        if (this.#snapshot?.state === 'running')
+            this.emit({ ...this.#snapshot, ...update });
+    }
+}