@interncom/diplomatic 0.2.7 → 0.3.0

package/dist/web/openClient.d.ts

@@ -0,0 +1,141 @@
+import { IClock } from "./shared/clock";
+import type { IStateManager } from "./shared/types";
+import type { IClient, IStore } from "./types";
+/**
+ * How to construct the Worker you pass to {@link openDiplomaticClient} /
+ * {@link WorkerClient.connect} / `useClient`.
+ *
+ * The library accepts only a live `Worker` instance. Instantiation is bundler-
+ * and hosting-specific — the app owns that step so DIPLOMATIC never guesses a
+ * script URL that would 404 under a different tool.
+ *
+ * The worker entry is the package export `@interncom/diplomatic/worker`
+ * (built as `worker.mjs` in the published package). It must run as a
+ * **module** worker (`type: "module"`).
+ *
+ * ## Vite (recommended for SPA templates)
+ *
+ * ```ts
+ * import DiplomaticWorker from "@interncom/diplomatic/worker?worker";
+ * const worker = new DiplomaticWorker();
+ * await openDiplomaticClient({ state, worker });
+ * ```
+ *
+ * `?worker` makes Vite emit a real worker asset and a constructor. Create the
+ * instance once (module scope or `useMemo`/`useRef`) — not on every render.
+ *
+ * ## webpack / Rollup / esbuild / Parcel (`new URL` + import.meta.url)
+ *
+ * Point at the package worker file so the bundler copies it next to the app:
+ *
+ * ```ts
+ * const worker = new Worker(
+ *   new URL("@interncom/diplomatic/worker", import.meta.url),
+ *   { type: "module" },
+ * );
+ * ```
+ *
+ * If the package path does not resolve, import the built file explicitly:
+ *
+ * ```ts
+ * const worker = new Worker(
+ *   new URL(
+ *     "../node_modules/@interncom/diplomatic/dist/worker.mjs",
+ *     import.meta.url,
+ *   ),
+ *   { type: "module" },
+ * );
+ * ```
+ *
+ * (Exact relative path depends on your app layout; prefer the package export
+ * when your bundler supports it.)
+ *
+ * ## Plain HTML / CDN / static hosting (no bundler)
+ *
+ * Host `worker.mjs` (from the package `dist/`) as a same-origin static asset,
+ * then:
+ *
+ * ```html
+ * <script type="module">
+ *   import { openDiplomaticClient } from "https://cdn.example/diplomatic.js";
+ *   const worker = new Worker("/path/to/worker.mjs", { type: "module" });
+ *   const { client } = await openDiplomaticClient({ state, worker });
+ * </script>
+ * ```
+ *
+ * The worker script must be **same-origin** (or CORS-enabled for classic
+ * workers; module workers generally need same-origin). Do not invent a path
+ * into `node_modules` from the browser — copy or serve the built file.
+ *
+ * ## React (`useClient`)
+ *
+ * Same rules: build the Worker once, pass the instance:
+ *
+ * ```ts
+ * import DiplomaticWorker from "@interncom/diplomatic/worker?worker";
+ * const syncWorker = new DiplomaticWorker(); // module scope
+ * useClient({ seed, host, worker: syncWorker });
+ * ```
+ *
+ * ## Lifecycle
+ *
+ * Workers die with the page (tab close / full navigation). Mid-session death
+ * is rare; if you recreate a Worker yourself, open a new client against it.
+ * `dispose` / `WorkerClient.terminate` stops the worker DIPLOMATIC is using.
+ */
+type OpenDiplomaticClientBase = {
+    state: IStateManager;
+    clock?: IClock;
+    /** Max wait for worker ready when using a worker (default 15s). */
+    readyTimeoutMs?: number;
+    /**
+     * Debounce local write → worker sync (default `defaultSyncDebounceMs`).
+     * Use `0` in tests for an immediate upload-queue handoff.
+     */
+    syncDebounceMs?: number;
+};
+/**
+ * Worker path: protocol sync off the main thread. Main and worker both use
+ * IndexedDB (shared durable state). A custom `store` is a type error and a
+ * runtime error — the worker always opens IDB, so a MemoryStore (etc.) on
+ * main would silently diverge.
+ */
+export type OpenDiplomaticClientWorkerOptions = OpenDiplomaticClientBase & {
+    /**
+     * App-constructed sync Worker (see module docs above for how to create it).
+     * Misconfiguration or ready timeout throws — no silent main-thread fallback.
+     */
+    worker: Worker;
+    store?: never;
+};
+/**
+ * Main-thread path: SyncClient on the page. Optional custom store; default is
+ * IndexedDB. No automatic memory fallback when IndexedDB is missing.
+ */
+export type OpenDiplomaticClientMainOptions = OpenDiplomaticClientBase & {
+    worker?: undefined;
+    /**
+     * Protocol message store. Default: IndexedDB (`openIDBStore`).
+     * Pass explicitly for non-IDB backends (e.g. `new MemoryStore(crypto)`).
+     * Incompatible with `worker` (see {@link OpenDiplomaticClientWorkerOptions}).
+     */
+    store?: IStore<URL>;
+};
+export type OpenDiplomaticClientOptions = OpenDiplomaticClientWorkerOptions | OpenDiplomaticClientMainOptions;
+export type OpenedDiplomaticClient = {
+    client: IClient<URL>;
+    /** Where protocol sync is running. */
+    mode: "worker" | "main";
+    /** Tear down worker or disconnect main client. */
+    dispose: () => void;
+};
+/**
+ * Open a browser client.
+ *
+ * - **Worker path:** pass `worker` (already constructed). Always IndexedDB.
+ * - **Main path:** omit `worker` → SyncClient on the page; optional `store`.
+ *
+ * See {@link OpenDiplomaticClientOptions} for Worker instantiation recipes.
+ */
+export declare function openDiplomaticClient(opts: OpenDiplomaticClientOptions): Promise<OpenedDiplomaticClient>;
+export {};

package/dist/web/progress.d.ts

@@ -0,0 +1,24 @@
+/** Sync / import progress phase ticks.
+ *
+ * Exposed only via `IDiplomaticClientXferState.progress` on `client.xferState`
+ * (get + listen / `useClientXferState`). There is no separate progress channel. */
+export type SyncPhase = "peek" | "push" | "pull" | "apply" | "import" | "idle";
+export interface SyncProgressEvent {
+    phase: SyncPhase;
+    /** Host label when the work is host-scoped. */
+    host?: string;
+    /** Items completed in this phase so far (when known). */
+    done?: number;
+    /** Total items for this phase (when known up front). */
+    total?: number;
+    /** Bytes completed (optional; push/pull soft budgets). */
+    bytesDone?: number;
+    /** Bytes total for the phase snapshot (optional). */
+    bytesTotal?: number;
+}
+/** Resting progress when no sync/import is in flight. */
+export declare const idleProgress: SyncProgressEvent;
+export type ProgressFn = (ev: SyncProgressEvent) => void;
+export declare const defaultPeekProgressEvery = 50;
+/** Emit when `done` is 1, every `every` heads, and on the final head. */
+export declare function shouldEmitItemProgress(done: number, total: number, every: number): boolean;

package/dist/web/react/useClient.d.ts

@@ -1,17 +1,51 @@
-import { SyncClient } from "../client";
-import { HostHandle, IHostConnectionInfo, IStateManager, MasterSeed } from "../shared/types";
-import type { IDiplomaticClientState, IDiplomaticClientXferState } from "../types";
 import { IEntDB } from "../entdb/entdb";
 import { IClock } from "../shared/clock";
-export declare function useClientState<Handle extends HostHandle>(client: SyncClient<Handle>): IDiplomaticClientState | undefined;
-export declare function useClientXferState<Handle extends HostHandle>(client: SyncClient<Handle>): IDiplomaticClientXferState | undefined;
-export declare function useSyncOnResume<Handle extends HostHandle>(client: SyncClient<Handle>): void;
-export declare function useClient({ clock, seed, host }: {
+import { IHostConnectionInfo, IStateManager, MasterSeed } from "../shared/types";
+import type { IClient, IDiplomaticClientState, IDiplomaticClientXferState, IStore } from "../types";
+export declare function useClientState(client: Pick<IClient<URL>, "clientState">): IDiplomaticClientState | undefined;
+export declare function useClientXferState(client: Pick<IClient<URL>, "xferState">): IDiplomaticClientXferState | undefined;
+export declare function useSyncOnResume(client: Pick<IClient<URL>, "connect" | "sync">): void;
+type UseClientBase = {
     clock?: IClock;
     seed?: MasterSeed;
     host?: IHostConnectionInfo<URL>;
-}): {
-    client?: SyncClient<URL>;
+    readyTimeoutMs?: number;
+};
+/**
+ * Worker path: always IndexedDB on main + worker. Custom `store` is forbidden
+ * (type + runtime) so durable state cannot diverge.
+ *
+ * Vite:
+ *   import DiplomaticWorker from "@interncom/diplomatic/worker?worker";
+ *   const syncWorker = new DiplomaticWorker();
+ *   useClient({ worker: syncWorker, seed, host });
+ */
+export type UseClientWorkerOptions = UseClientBase & {
+    /**
+     * App-constructed sync Worker. Create once (module scope or useMemo/useRef),
+     * not each render. See `openDiplomaticClient` for instantiation recipes.
+     */
+    worker: Worker;
+    store?: never;
+};
+/**
+ * Main-thread path. Optional custom store; default IndexedDB.
+ */
+export type UseClientMainOptions = UseClientBase & {
+    worker?: undefined;
+    /**
+     * Protocol store override. Default: IndexedDB. Pass explicitly for
+     * MemoryStore or other backends. Incompatible with `worker`.
+     */
+    store?: IStore<URL>;
+};
+export type UseClientOptions = UseClientWorkerOptions | UseClientMainOptions;
+export declare function useClient(opts?: UseClientOptions): {
+    client?: IClient<URL>;
     entDB?: IEntDB;
     stateMgr: IStateManager;
+    mode?: "worker" | "main";
+    /** Set when open/init fails (e.g. misconfigured worker). */
+    error?: Error;
 };
+export {};

package/dist/web/saveBlob.d.ts

@@ -0,0 +1,2 @@
+/** Trigger a browser file download for a Blob (main thread only). */
+export declare function saveBlob(blob: Blob, filename: string): void;

package/dist/web/shared/singleton.d.ts

@@ -11,6 +11,7 @@ export declare class SingletonStateManager implements IStateManager {
     constructor(singletonType: string);
     apply(messages: IMessage[]): Promise<Status[]>;
     clear: () => Promise<Status>;
+    notify: (types: Iterable<string>) => void;
     on: (event: string, listener: () => void) => void;
     off: (event: string, listener: () => void) => void;
 }

package/dist/web/shared/types.d.ts

@@ -165,8 +165,13 @@ export interface ITransport {
 }
 export interface IStateManager {
     apply: (msgs: IMessage[]) => Promise<Status[]>;
-    /** Drop local application state (e.g. EntDB) and notify subscribers. */
+    /** Drop local application state and notify subscribers. */
     clear: () => Promise<Status>;
+    /**
+     * Notify type subscribers without applying msgs (e.g. after a peer thread
+     * updated shared application state in IndexedDB).
+     */
+    notify: (types: Iterable<string>) => void;
     on: (type: string, listener: () => void) => void;
     off: (type: string, listener: () => void) => void;
 }

package/dist/web/state.d.ts

@@ -8,10 +8,15 @@ export declare class StateManager implements IStateManager {
     applier: Applier;
     private emitter;
     private clearer;
-    constructor(applier: Applier, clearer: () => Promise<Status>);
+    private onTypes;
+    constructor(applier: Applier, clearer: () => Promise<Status>, 
+    /** Optional hook after a successful apply batch (e.g. worker dirty signal). */
+    onTypes?: (types: Set<string>) => void);
     apply: (msgs: IMessage[]) => Promise<Status[]>;
-    /** Clear underlying store (e.g. EntDB) and notify all type subscribers. */
+    /** Clear application state and notify all type subscribers. */
     clear: () => Promise<Status>;
+    /** Notify type subscribers without applying msgs (shared-IDB peer updates). */
+    notify: (types: Iterable<string>) => void;
     on: (opType: string, listener: () => void) => void;
     off: (opType: string, listener: () => void) => void;
 }

package/dist/web/stores/idb/msgs.d.ts

@@ -1,19 +1,18 @@
 import { Status } from "../../shared/consts";
 import { ICrypto } from "../../shared/types";
 import { EntityID, Hash } from "../../shared/types";
-import { IMessageStore, IStoredMessage, IStoredMessageData } from "../../types";
+import { IMessageStore, IStorableMessage, IStoredMessage } from "../../types";
 export declare class IDBMessageStore implements IMessageStore {
     private crypto;
     db: IDBDatabase;
     constructor(db: IDBDatabase, crypto: ICrypto);
-    add(messages: {
-        key: Hash;
-        data: IStoredMessageData;
-    }[]): Promise<Status[]>;
+    add(messages: IStorableMessage[]): Promise<Status[]>;
     del(keys: Iterable<Hash>): Promise<void>;
     get(key: Hash): Promise<IStoredMessage | undefined>;
     has(key: Hash): Promise<boolean>;
     list(): Promise<Iterable<IStoredMessage>>;
     last(eid: EntityID): Promise<IStoredMessage | undefined>;
+    listUnapplied(): Promise<IStoredMessage[]>;
+    markApplied(keys: Iterable<Hash>): Promise<void>;
     wipe(): Promise<void>;
 }

package/dist/web/stores/idb/store.d.ts

@@ -10,6 +10,10 @@ export declare const HOSTS_TABLE = "hosts";
 export declare const UPLOAD_QUEUE_TABLE = "uploadQueue";
 export declare const DOWNLOAD_QUEUE_TABLE = "downloadQueue";
 export declare const MESSAGES_TABLE = "messages";
+/** Index on messages.apld — pending apply is apld === false. */
+export declare const MESSAGES_APLD_INDEX = "apld";
+/** Schema version: v3 adds messages.apld index for the apply queue. */
+export declare const DIPLOMATIC_STORE_DB_VERSION = 3;
 export declare class IDBStore implements IStore<URL> {
     seed: IDBSeedStore;
     hosts: IDBHostStore;

package/dist/web/stores/memory/msgs.d.ts

@@ -1,19 +1,18 @@
 import { ICrypto } from "../../shared/types";
 import { EntityID, Hash } from "../../shared/types";
-import { IMessageStore, IStoredMessage, IStoredMessageData } from "../../types";
+import { IMessageStore, IStorableMessage, IStoredMessage, IStoredMessageData } from "../../types";
 import { Status } from "../../shared/consts";
 export declare class MemoryMessageStore implements IMessageStore {
     private crypto;
     messages: Map<string, IStoredMessageData>;
     constructor(crypto: ICrypto);
-    add(messages: {
-        key: Hash;
-        data: IStoredMessageData;
-    }[]): Promise<Status[]>;
+    add(messages: IStorableMessage[]): Promise<Status[]>;
     del(keys: Iterable<Hash>): Promise<void>;
     get(key: Hash): Promise<IStoredMessage | undefined>;
     has(key: Hash): Promise<boolean>;
     list(): Promise<Iterable<IStoredMessage>>;
     last(eid: EntityID): Promise<IStoredMessage | undefined>;
+    listUnapplied(): Promise<IStoredMessage[]>;
+    markApplied(keys: Iterable<Hash>): Promise<void>;
     wipe(): Promise<void>;
 }

package/dist/web/sync.d.ts

@@ -3,7 +3,8 @@ import { IClock } from "./shared/clock";
 import { Status } from "./shared/consts";
 import { Enclave } from "./shared/enclave";
 import { Hash, HostHandle, IBag, ICrypto } from "./shared/types";
-import { IDownloadMessage, IHostRow, IMsgParts, IStore, IStoredMessageData } from "./types";
+import { ProgressFn } from "./progress";
+import { IDownloadMessage, IHostRow, IMsgParts, IStore, type IStoredMessageWrite } from "./types";
 /** Default soft cap for one push/pull request (~1 MiB). Apps with large
  * payloads (e.g. media) should raise maxPushBytes / maxPullBytes. */
 export declare const defaultMaxPushBytes: number;
@@ -19,6 +20,10 @@ export interface ISyncParams<Handle extends HostHandle> {
     maxPushBytes?: number;
     /** Soft max body bytes (head.len) per pull request. Oversized items go alone. */
     maxPullBytes?: number;
+    /** Optional progress sink (phases + item/batch ticks). */
+    onProgress?: ProgressFn;
+    /** Peek progress stride in heads (default `defaultPeekProgressEvery`). */
+    peekProgressEvery?: number;
 }
 /** Push one batch of sealed bags; deq successes; advance lastSeq from store. */
 export declare function pushBatch<Handle extends HostHandle>(conn: Pick<DiplomaticClientAPI<Handle>, "push">, store: IStore<Handle>, hostLabel: string, bags: IBag[], hashes: Hash[]): Promise<Status>;
@@ -27,14 +32,14 @@ export declare function pullBatch<Handle extends HostHandle>(conn: Pick<Diplomat
     enqueueUpload: boolean;
     triggerUpload: boolean;
 }) => Promise<Status[]>): Promise<Status>;
-export declare function syncPeek<Handle extends HostHandle>({ conn, store, enclave, host, crypto }: ISyncParams<Handle>): Promise<Status>;
-export declare function syncPush<Handle extends HostHandle>({ conn, store, host, maxPushBytes }: ISyncParams<Handle>): Promise<Status>;
-export declare function syncPull<Handle extends HostHandle>({ conn, store, enclave, host, crypto, maxPullBytes }: ISyncParams<Handle>, apply: (parts: IMsgParts[], options?: {
+export declare function syncPeek<Handle extends HostHandle>({ conn, store, enclave, host, crypto, onProgress, peekProgressEvery, }: ISyncParams<Handle>): Promise<Status>;
+export declare function syncPush<Handle extends HostHandle>({ conn, store, host, maxPushBytes, onProgress }: ISyncParams<Handle>): Promise<Status>;
+export declare function syncPull<Handle extends HostHandle>({ conn, store, enclave, host, crypto, maxPullBytes, onProgress, }: ISyncParams<Handle>, apply: (parts: IMsgParts[], options?: {
     enqueueUpload: boolean;
     triggerUpload: boolean;
 }) => Promise<Status[]>): Promise<Status>;
-export declare function msg2StoredMsgData({ head, body }: IMsgParts): IStoredMessageData;
-export declare function handleNotif<Handle extends HostHandle>(bytes: Uint8Array, { conn, store, enclave, host, crypto, clock, maxPullBytes, maxPushBytes, }: ISyncParams<Handle>, apply: (parts: IMsgParts[], options?: {
+export declare function msg2StoredMsgData({ head, body }: IMsgParts): IStoredMessageWrite;
+export declare function handleNotif<Handle extends HostHandle>(bytes: Uint8Array, { conn, store, enclave, host, crypto, clock, maxPullBytes, maxPushBytes, onProgress, peekProgressEvery, }: ISyncParams<Handle>, apply: (parts: IMsgParts[], options?: {
     enqueueUpload: boolean;
     triggerUpload: boolean;
 }) => Promise<Status[]>, scheduleSync: () => void): Promise<void>;

package/dist/web/types.d.ts

@@ -1,3 +1,4 @@
+import type { SyncProgressEvent } from "./progress";
 import { Status } from "./shared/consts";
 import type { Enclave } from "./shared/enclave";
 import type { EncodedMessage } from "./shared/message";
@@ -13,9 +14,15 @@ export interface IDiplomaticClientState {
     hasHost: boolean;
     connected: boolean;
 }
+/**
+ * Transfer / sync activity: queue depths + current phase progress.
+ * Subscribe via `xferState.listen` / `useClientXferState`; snapshot with `get()`.
+ */
 export interface IDiplomaticClientXferState {
     numUploads: number;
     numDownloads: number;
+    /** Latest sync/import phase tick; `{ phase: "idle" }` when not in flight. */
+    progress: SyncProgressEvent;
 }
 export type Applier = (ops: IOp[]) => Promise<{
     stats: Status[];
@@ -58,21 +65,45 @@ export interface IDownloadQueue {
     count: () => Promise<number>;
     wipe(): Promise<void>;
 }
+/**
+ * Archive fields shared by read and write.
+ * `apld`: true once the msg has been applied by the application state manager;
+ * false while still pending apply.
+ */
+export interface IStoredMessageFields {
+    eid: EntityID;
+    off?: number;
+    ctr?: number;
+    body?: EncodedMessage;
+}
+/**
+ * What may come back from IDB (pre-apld rows can omit the field).
+ * Prefer {@link normalizeStoredMessageData} before use.
+ */
+export interface IStoredMessageData extends IStoredMessageFields {
+    apld?: boolean;
+}
+/**
+ * Required shape for every put into the message archive.
+ * Callers must set `apld` (false until applied, then true).
+ */
+export type IStoredMessageWrite = IStoredMessageFields & {
+    apld: boolean;
+};
 export interface IStorableMessage {
     key: Hash;
-    data: IStoredMessageData;
+    data: IStoredMessageWrite;
 }
 export interface IStoredMessage {
     hash: Hash;
     head: IMessageHead;
     body?: EncodedMessage;
+    applied: boolean;
 }
-export interface IStoredMessageData {
-    eid: EntityID;
-    off?: number;
-    ctr?: number;
-    body?: EncodedMessage;
-}
+/** Coerce legacy rows missing `apld` to pending (`false`). */
+export declare function normalizeStoredMessageData(data: IStoredMessageData): IStoredMessageWrite;
+/** Pending apply when not yet marked applied. */
+export declare function isPendingApply(data: IStoredMessageData): boolean;
 export declare function toStoredMessage(hash: Hash, data: IStoredMessageData, crypto: ICrypto): Promise<IStoredMessage>;
 export interface IMessageStore {
     add: (messages: IStorableMessage[]) => Promise<Status[]>;
@@ -81,6 +112,10 @@ export interface IMessageStore {
     del: (keys: Iterable<Hash>) => Promise<void>;
     list: () => Promise<Iterable<IStoredMessage>>;
     last: (eid: EntityID) => Promise<IStoredMessage | undefined>;
+    /** Messages stored but not yet applied (apld === false). */
+    listUnapplied: () => Promise<IStoredMessage[]>;
+    /** Mark archive rows as applied (apld = true). */
+    markApplied: (keys: Iterable<Hash>) => Promise<void>;
     wipe(): Promise<void>;
 }
 export interface IStore<Handle extends HostHandle> {

package/dist/web/worker/client.d.ts

@@ -0,0 +1,77 @@
+import { IClock } from "../shared/clock";
+import { Status } from "../shared/consts";
+import type { EntityID, IHostConnectionInfo, IInsertParams, IMessageHead, IStateManager, IUpsertParams, MasterSeed, SerializedContent } from "../shared/types";
+import type { ValStat } from "../shared/valstat";
+import type { IClient, IDiplomaticClientState, IDiplomaticClientXferState, IStateEmitter, IStore } from "../types";
+/**
+ * Options for attaching to an app-owned sync Worker.
+ *
+ * Provide a live `Worker` — the library never constructs one. See
+ * `openDiplomaticClient` for bundler/CDN instantiation recipes.
+ */
+export type WorkerClientOptions = {
+    /** Already-constructed module Worker running `@interncom/diplomatic/worker`. */
+    worker: Worker;
+    /** Max wait for worker `ready` (default 15s). Failures throw; no fallback. */
+    readyTimeoutMs?: number;
+    clock?: IClock;
+    /**
+     * Debounce local write → worker `sync` (default {@link defaultSyncDebounceMs}).
+     * Use `0` in tests for immediate handoff (no timers).
+     */
+    syncDebounceMs?: number;
+};
+export declare class WorkerClient implements IClient<URL> {
+    private worker;
+    private state;
+    /** Main-thread writer: msg archive + local apply for fast UI. */
+    private local;
+    private nextId;
+    private pending;
+    private ready;
+    private resolveReady;
+    private rejectReady;
+    /** Debounced local write → worker upload/sync. */
+    private scheduledSync;
+    private cachedClientState;
+    private cachedXferState;
+    clientState: IStateEmitter<IDiplomaticClientState>;
+    xferState: IStateEmitter<IDiplomaticClientXferState>;
+    private constructor();
+    private failReady;
+    /**
+     * Run any pending debounced worker sync now and await it.
+     * Useful in tests (with real debounce) or after a burst of local writes.
+     */
+    flushScheduledSync(): Promise<void>;
+    /**
+     * Attach to an app-provided Worker. `store` is the shared protocol IDB (main
+     * connection) used for local msg writes; worker opens its own connection.
+     * Throws if the worker never becomes ready — does not fall back to main thread.
+     */
+    static connect(state: IStateManager, store: IStore<URL>, opts: WorkerClientOptions): Promise<WorkerClient>;
+    /** Lightweight RPC check after connect. */
+    ping(): Promise<void>;
+    /** Terminate the worker (drops protocol DB connection in that thread). */
+    terminate(): void;
+    private onMessage;
+    private allocId;
+    private request;
+    private requestStatus;
+    private serializeHost;
+    setSeed(seed: MasterSeed): Promise<void>;
+    link(host: IHostConnectionInfo<URL>, connect?: boolean): Promise<void>;
+    unlink(label: string): Promise<void>;
+    connect(listen?: boolean, sync?: boolean): Promise<void>;
+    disconnect(): Promise<void>;
+    /** Local UI write: archive + apply on main (fast UI); upload/sync via worker. */
+    insertRaw(content: SerializedContent): Promise<ValStat<IMessageHead>>;
+    upsertRaw(eid: EntityID, content: SerializedContent | undefined, force?: boolean): Promise<ValStat<IMessageHead>>;
+    insert<T = unknown>(op: IInsertParams<T>): Promise<ValStat<IMessageHead>>;
+    upsert<T = unknown>(op: IUpsertParams<T>, force?: boolean): Promise<ValStat<IMessageHead>>;
+    delete(eid: EntityID): Promise<ValStat<IMessageHead>>;
+    sync(): Promise<Status>;
+    wipe(): Promise<void>;
+    import(file: File): Promise<Status>;
+    export(filename: string, _extension?: string): Promise<Status>;
+}

package/dist/web/worker/entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/web/worker/protocol.d.ts

@@ -0,0 +1,125 @@
+import type { Status } from "../shared/consts";
+import type { IMessageHead } from "../shared/types";
+import type { SyncProgressEvent } from "../progress";
+import type { IDiplomaticClientState, IDiplomaticClientXferState } from "../types";
+/** Host identity as plain data (URL → string for structured clone). */
+export interface SerializedHost {
+    handle: string;
+    label: string;
+    idx: number;
+}
+export type WorkerCmd = {
+    id: number;
+    op: "ping";
+} | {
+    id: number;
+    op: "setSeed";
+    seed: Uint8Array;
+} | {
+    id: number;
+    op: "link";
+    host: SerializedHost;
+    connect?: boolean;
+} | {
+    id: number;
+    op: "unlink";
+    label: string;
+} | {
+    id: number;
+    op: "connect";
+    listen?: boolean;
+    sync?: boolean;
+} | {
+    id: number;
+    op: "disconnect";
+} | {
+    id: number;
+    op: "sync";
+} | {
+    id: number;
+    op: "wipe";
+} | {
+    id: number;
+    op: "insertRaw";
+    body: Uint8Array;
+} | {
+    id: number;
+    op: "upsertRaw";
+    eid: Uint8Array;
+    body?: Uint8Array;
+    force?: boolean;
+} | {
+    id: number;
+    op: "insert";
+    params: {
+        type: string;
+        body: unknown;
+        gid?: string;
+        pid?: Uint8Array;
+    };
+} | {
+    id: number;
+    op: "upsert";
+    params: {
+        type: string;
+        body: unknown;
+        eid?: Uint8Array;
+        gid?: string;
+        pid?: Uint8Array;
+    };
+    force?: boolean;
+} | {
+    id: number;
+    op: "delete";
+    eid: Uint8Array;
+} | {
+    id: number;
+    op: "import";
+    bytes: Uint8Array;
+} | {
+    id: number;
+    op: "export";
+} | {
+    id: number;
+    op: "getClientState";
+} | {
+    id: number;
+    op: "getXferState";
+};
+export type WorkerReply = {
+    kind: "reply";
+    id: number;
+    ok: true;
+    result?: unknown;
+} | {
+    kind: "reply";
+    id: number;
+    ok: false;
+    status: Status;
+};
+export type WorkerEvent = {
+    kind: "ready";
+} | {
+    kind: "clientState";
+    state: IDiplomaticClientState;
+}
+/** Queues + sync phase progress (see IDiplomaticClientXferState.progress). */
+ | {
+    kind: "xferState";
+    state: IDiplomaticClientXferState;
+}
+/** Application state (e.g. EntDB) changed for these op types; re-read IDB. */
+ | {
+    kind: "dirty";
+    types: string[];
+} | {
+    kind: "wiped";
+} | WorkerReply;
+export declare function isWorkerEvent(data: unknown): data is WorkerEvent;
+export declare function isWorkerCmd(data: unknown): data is WorkerCmd;
+/** Narrow helpers for typed replies (avoid casts at call sites). */
+export declare function headFromUnknown(v: unknown): IMessageHead | undefined;
+export declare function statusFromUnknown(v: unknown): Status | undefined;
+export declare function clientStateFromUnknown(v: unknown): IDiplomaticClientState | undefined;
+export declare function progressFromUnknown(v: unknown): SyncProgressEvent | undefined;
+export declare function xferStateFromUnknown(v: unknown): IDiplomaticClientXferState | undefined;