@ghostlytools/sdk 1.2.3 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/dist/app.js +15 -4
  2. package/dist/app.js.map +1 -1
  3. package/dist/core.js +2 -2
  4. package/dist/{fakes-CBIuqo5e.js → fakes-BlpK1WuW.js} +2 -2
  5. package/dist/{fakes-CBIuqo5e.js.map → fakes-BlpK1WuW.js.map} +1 -1
  6. package/dist/fakes.js +1 -1
  7. package/dist/index.js +2 -2
  8. package/dist/{keet-identity-key-BylxCPl4.js → keet-identity-key-GE5nr3zt.js} +2 -2
  9. package/dist/{keet-identity-key-BylxCPl4.js.map → keet-identity-key-GE5nr3zt.js.map} +1 -1
  10. package/dist/{src-DCeLPsi-.js → src-JQitqFJD.js} +1038 -137
  11. package/dist/src-JQitqFJD.js.map +1 -0
  12. package/dist/testing.js +3 -3
  13. package/dist/types/core/src/appBundle.d.ts +28 -0
  14. package/dist/types/core/src/chatFiles.d.ts +41 -1
  15. package/dist/types/core/src/datalink.d.ts +13 -7
  16. package/dist/types/core/src/dhtDelivery.d.ts +9 -0
  17. package/dist/types/core/src/engineErrors.d.ts +1 -0
  18. package/dist/types/core/src/frames.d.ts +5 -0
  19. package/dist/types/core/src/ghostlink.d.ts +83 -8
  20. package/dist/types/core/src/groupCommunity.d.ts +37 -1
  21. package/dist/types/core/src/groupFiles.d.ts +6 -2
  22. package/dist/types/core/src/groupSession.d.ts +57 -6
  23. package/dist/types/core/src/groupSignals.d.ts +2 -0
  24. package/dist/types/core/src/link.d.ts +15 -0
  25. package/dist/types/core/src/miniApp.d.ts +15 -4
  26. package/dist/types/core/src/pairedCapabilities.d.ts +6 -1
  27. package/dist/types/core/src/pkarr.d.ts +6 -0
  28. package/dist/types/core/src/relay.d.ts +60 -4
  29. package/dist/types/core/src/transport.d.ts +12 -0
  30. package/dist/{verify-DBGw6wYt.js → verify-afQj9kHW.js} +2 -2
  31. package/dist/{verify-DBGw6wYt.js.map → verify-afQj9kHW.js.map} +1 -1
  32. package/package.json +1 -1
  33. package/dist/src-DCeLPsi-.js.map +0 -1
package/dist/testing.js CHANGED
@@ -1,7 +1,7 @@
1
- import { $l as emptyIdentityLedger, Fi as isBitcoinAddress, Hl as IDENTITY_MAX_EVIDENCE, Zl as IdentityExchange, au as newIdentityBinding, nu as identityStatement, oa as decodeBolt11, zb as createIdentity } from "./src-DCeLPsi-.js";
1
+ import { Bi as isBitcoinAddress, Ql as IDENTITY_MAX_EVIDENCE, da as decodeBolt11, ex as createIdentity, fu as identityStatement, hu as newIdentityBinding, lu as emptyIdentityLedger, su as IdentityExchange } from "./src-JQitqFJD.js";
2
2
  import { l as providerDescriptorProblems, o as isNothingSpentError } from "./types-DvtCy3WB.js";
3
- import { i as verifyIdentity, r as descriptorProblems } from "./verify-DBGw6wYt.js";
4
- import { _ as fakeAddress, a as fakeAccount, b as fakeOnchain, c as fakeKeySign, d as fakeRecord, f as fakeRecordText, g as TEST_PROVIDERS_FLAG, h as FakeOnchainProvider, i as TEST_IDENTITIES_FLAG, l as fakeKeySubject, m as FakeLightningProvider, n as FAKE_ISSUER, o as fakeAccountToken, p as testIdentitiesEnabled, r as FAKE_RECORD_HOST, s as fakeKey, t as FAKE_IDENTITY_PROVIDERS, u as fakeKeyring, v as fakeInvoice, x as testProvidersEnabled, y as fakeLightning } from "./fakes-CBIuqo5e.js";
3
+ import { i as verifyIdentity, r as descriptorProblems } from "./verify-afQj9kHW.js";
4
+ import { _ as fakeAddress, a as fakeAccount, b as fakeOnchain, c as fakeKeySign, d as fakeRecord, f as fakeRecordText, g as TEST_PROVIDERS_FLAG, h as FakeOnchainProvider, i as TEST_IDENTITIES_FLAG, l as fakeKeySubject, m as FakeLightningProvider, n as FAKE_ISSUER, o as fakeAccountToken, p as testIdentitiesEnabled, r as FAKE_RECORD_HOST, s as fakeKey, t as FAKE_IDENTITY_PROVIDERS, u as fakeKeyring, v as fakeInvoice, x as testProvidersEnabled, y as fakeLightning } from "./fakes-BlpK1WuW.js";
5
5
  import { afterEach, describe, expect, it, vi } from "vitest";
6
6
  //#region ../browser/src/engine/paymentAdapters/providers/contractSuite.ts
7
7
  var WAIT = 1e4;
@@ -150,8 +150,36 @@ export type AppBundleReading = {
150
150
  reason: AppBundleRefusal;
151
151
  detail?: string;
152
152
  };
153
+ /**
154
+ * Lets the thread go for one turn: what waits (input, drawing, timers, port messages, IndexedDB answers) runs, then the
155
+ * caller goes on. A message to itself, queued behind the page's other tasks. Never `scheduler.yield()`: in Chromium its
156
+ * continuation outranks every normal task, so a paced read of 4096 revocations held the page's timers, its apps' broker
157
+ * ports and IndexedDB for the whole 1.8 s. Never `setTimeout(0)` but as the last resort: from the fifth nested timer on
158
+ * the browser waits at least 4 ms (HTML's clamp), which made that read take 60% longer than the work, and a hidden tab
159
+ * runs timers once a second.
160
+ */
161
+ export declare function yieldThread(): Promise<void>;
162
+ /**
163
+ * A pause for a loop of short steps: `await pause()` after each step lets the thread go once `sliceMs` of work has
164
+ * run since the last time, and answers at once otherwise.
165
+ */
166
+ export declare function pacer(sliceMs: number): () => Promise<void> | undefined;
167
+ /**
168
+ * SHA-256 of bytes that may be a whole bundle, for a client whose engine shares its page's thread: `sha256` in
169
+ * JavaScript takes about 12 ms per MiB on a desktop CPU, so 16 MiB in one run is a page that draws nothing and takes no
170
+ * input for 200 ms. With `crypto.subtle` the bytes are hashed off the thread; without it (a page not served over
171
+ * HTTPS), a slice at a time with a pause between slices. The bytes must not change until it answers.
172
+ */
173
+ export declare function sha256Paced(bytes: Uint8Array): Promise<Uint8Array>;
153
174
  /** Reads and checks a bundle (the order of the checks is part of the format: see above). */
154
175
  export declare function readAppBundle(bytes: Uint8Array): AppBundleReading;
176
+ /**
177
+ * `readAppBundle` for a client whose engine shares its page's thread: the same checks in the same order, with the same
178
+ * refusals, and each file hashed by `sha256Paced`, one after the other, with the thread let go between files every
179
+ * `HASH_SLICE_MS` (64 files of 64 KiB, each hashed at once, held it for 50 ms). The bytes must not change until it
180
+ * answers.
181
+ */
182
+ export declare function readAppBundleAsync(bytes: Uint8Array): Promise<AppBundleReading>;
155
183
  /** Puts a bundle's parts together, checking nothing: for builders, and for tests that need a broken bundle. */
156
184
  export declare function assembleAppBundle(manifestBytes: Uint8Array, statementBytes: Uint8Array, files: Uint8Array[]): Uint8Array;
157
185
  /** What a publisher writes: every manifest field but `publisher` and `files`, which the bundle's contents decide. */
@@ -28,6 +28,11 @@ export declare const FILE_LIMITS: {
28
28
  readonly chunkBytes: number;
29
29
  /** Bytes a sender has sent and not seen confirmed: throughput is this per round trip. */
30
30
  readonly windowBytes: number;
31
+ /**
32
+ * Bytes all of a chat's files have sent and not seen confirmed, together. Three files' windows at once were 3 MiB, and
33
+ * as base64 text past what a session's receive queue holds (`SESSION_RECEIVE_PENDING`, 3.75 MiB).
34
+ */
35
+ readonly chatWindowBytes: number;
31
36
  /** A receiver asks its person before taking a file larger than this. */
32
37
  readonly askAboveBytes: number;
33
38
  /** Files taken without asking, per contact, while stored. Past it, every file is asked about. */
@@ -134,6 +139,11 @@ export type RefuseReason = "declined" | "no-room" | "too-many" | "damaged" | "ca
134
139
  export interface ChatFilesHost {
135
140
  /** Sends a frame on the open session; false when there is none. */
136
141
  send(frame: Record<string, unknown>): boolean;
142
+ /**
143
+ * Sends a file's bytes at `offset` in the form the open session agreed (WISP 501 § files/4): a binary message, or
144
+ * the `pf-data` frame; false when there is no session or it has no room. A host without it gets `pf-data` through `send`.
145
+ */
146
+ sendData?(id: string, offset: number, data: Uint8Array): boolean;
137
147
  /**
138
148
  * A new offer from the contact: take it, ask the person, or refuse it. `again`: a file taken here without asking
139
149
  * that ended (failed, or stopped by the sender) and is offered again; it counts against the same limits as a new one.
@@ -162,6 +172,21 @@ export interface ChatFilesHost {
162
172
  resend?(record: FileTransferRecord, sent: number): boolean;
163
173
  now?(): number;
164
174
  }
175
+ /**
176
+ * files/4 (WISP 501 § files/4): a chunk as one binary message of the session, in place of the base64url text of a
177
+ * `pf-data` frame, which is a third more than the bytes it carries:
178
+ *
179
+ * kind 0x04 (1) | id length (1) | id (ASCII) | offset (8, big endian) | data (1 to `FILE_LIMITS.chunkBytes`)
180
+ */
181
+ export declare const FILE_DATA_KIND = 4;
182
+ /** The binary message for the bytes of file `id` at `offset`. Throws on what no receiver would take. */
183
+ export declare function encodeFileData(id: string, offset: number, data: Uint8Array): Uint8Array;
184
+ /** What a binary message from the contact says, or null when it is not a well-formed file data message. `data` is a view of `message`. */
185
+ export declare function decodeFileData(message: Uint8Array): {
186
+ id: string;
187
+ offset: number;
188
+ data: Uint8Array;
189
+ } | null;
165
190
  /** What a refusal means to the sender's person. */
166
191
  export declare function refusalText(why: string, room?: number): {
167
192
  state: TransferState;
@@ -170,6 +195,10 @@ export declare function refusalText(why: string, room?: number): {
170
195
  export declare class ChatFiles {
171
196
  private readonly host;
172
197
  private readonly entries;
198
+ /** Files sending that may have bytes not confirmed yet: what `inFlight` adds up (the rest are left out as it goes). */
199
+ private readonly moving;
200
+ /** Files that stopped sending for the chat's window alone: they go on once another's bytes are confirmed. */
201
+ private readonly held;
173
202
  private attached;
174
203
  private peerRoomValue;
175
204
  constructor(host: ChatFilesHost);
@@ -188,6 +217,7 @@ export declare class ChatFiles {
188
217
  private moved;
189
218
  private changed;
190
219
  private send;
220
+ private sendData;
191
221
  /** A session that agreed files/3 is open: say what fits here, then offer again what is not finished. */
192
222
  attach(): void;
193
223
  /** The session went: nothing moves until the next one. What was received is made durable. */
@@ -202,7 +232,13 @@ export declare class ChatFiles {
202
232
  private armStall;
203
233
  private source;
204
234
  private chunkAt;
235
+ /** Whether this file's own window lets it send more. */
236
+ private fileMayPump;
205
237
  private shouldPump;
238
+ /** Bytes this chat's files sent and have not seen confirmed. */
239
+ private inFlight;
240
+ /** Bytes were confirmed, or a file stopped sending: the files the chat's window held go on, before the one that freed it. */
241
+ private wakeHeld;
206
242
  /**
207
243
  * Whether the next `length` bytes go. Within the file's size they always do; past it the receiver is having parts
208
244
  * sent again, which nothing it says bounds, so this side does.
@@ -220,7 +256,11 @@ export declare class ChatFiles {
220
256
  */
221
257
  private discardStored;
222
258
  private target;
223
- /** An accepted file goes when a session is open and fewer than three others arrive at once. */
259
+ /**
260
+ * An accepted file goes when a session is open and fewer than three others arrive at once. One whose target is still
261
+ * being opened counts among the three: counted only once active, every file offered or queued meanwhile went too, and
262
+ * the windows of ten files and more at once overflowed the session's receive queue.
263
+ */
224
264
  private startIncoming;
225
265
  /** The next file waiting its turn, once one ends. */
226
266
  private startNext;
@@ -66,7 +66,9 @@ export declare const CONNECT_TIMEOUT_MS = 90000;
66
66
  * settle); where they do not, every offer of a first pairing waited the full 5 s, twice when the inviter offered too
67
67
  * (One's e2e runs: 13 offers of 89 at 5 s, 9 more at 1.3-3 s, 2026-10-05). An offer without one still connects to most
68
68
  * contacts (their checks learn this side's address from its own); behind a restricted NAT on the contact's side it may
69
- * not, and the next offer of the chat then waits as long as it takes (`fullGather`).
69
+ * not, and the next offer of the chat then waits as long as it takes (`fullGather`). An answer is bounded the same way:
70
+ * it waited the full 5 s, and two CLI daemons whose STUN server swallowed every request went live 10 s after the offer
71
+ * rather than 2 s (calls bug hunt, 2026-10-12).
70
72
  */
71
73
  export declare const OFFER_HOST_GATHER_MS = 2000;
72
74
  /** The data link keeps collecting this long after the candidate it waited for came (a call keeps 400 ms). */
@@ -101,12 +103,13 @@ export declare class DataLink {
101
103
  private pc;
102
104
  private myOfferTs;
103
105
  /**
104
- * An offer of this side's that went without a public candidate came to nothing (it was answered, and no path
105
- * connected): the next one waits for its STUN servers as long as it takes (`ICE_GATHERING_TIMEOUT_MS`).
106
+ * An offer or answer of this side's that went without a public candidate came to nothing (both descriptions were
107
+ * exchanged, and no path connected): the next one waits for its STUN servers as long as it takes
108
+ * (`ICE_GATHERING_TIMEOUT_MS`).
106
109
  */
107
110
  private fullGather;
108
- /** The offer out has no public candidate (as it went: the connection's description gains any that come later). */
109
- private offerLacksPublic;
111
+ /** The offer or answer out has no public candidate (as it went: the connection's description gains any that come later). */
112
+ private sentLacksPublic;
110
113
  private lastSignalTs;
111
114
  /** The peer's description as this connection was given it: Chrome shows it as `remoteDescription` only once applied. */
112
115
  private remoteSdp;
@@ -148,7 +151,10 @@ export declare class DataLink {
148
151
  */
149
152
  get fingerprints(): [string, string] | null;
150
153
  close(): void;
151
- /** This side's offer went with no public candidate, was answered, and came to nothing: the next offer gathers for as long as it takes. */
154
+ /**
155
+ * This side's offer went with no public candidate and was answered, or its answer went with none, and it came to
156
+ * nothing: the next offer or answer gathers for as long as it takes.
157
+ */
152
158
  private noteNoPublic;
153
159
  /**
154
160
  * What this attempt says about direct connections if it ends now without opening: nothing unless both descriptions
@@ -159,7 +165,7 @@ export declare class DataLink {
159
165
  /**
160
166
  * The attempt on this connection failed (it timed out, ICE failed or closed, its channel closed). An answer the
161
167
  * offerer may not have read yet is made again for the same offer while it still stands (`REANSWERS`); anything
162
- * else goes back to idle.
168
+ * else goes back to idle. `byConnection`: the connection said so itself, rather than a timer of this link's.
163
169
  */
164
170
  private failed;
165
171
  /** The answer to this side's offer did not go in (`ANSWER_REFUSED_REDIALS`): the attempt ends, and the caller may offer again now. */
@@ -141,6 +141,10 @@ export declare const emptyDhtDeliveryState: () => DhtDeliveryState;
141
141
  export declare class DhtDelivery {
142
142
  private readonly options;
143
143
  private state;
144
+ /** The state as last saved: a save that would write the same row again is skipped. */
145
+ private saved?;
146
+ /** The sequence of the last envelope signed here; the state's is the highest set aside (`SEQUENCE_BLOCK`). */
147
+ private sequence;
144
148
  private mode;
145
149
  private running;
146
150
  private ticking;
@@ -151,6 +155,7 @@ export declare class DhtDelivery {
151
155
  private fastUntil;
152
156
  private live;
153
157
  private active;
158
+ private readonly startedAt;
154
159
  /** The next read was asked for (a refresh, a fresh packet of the contact): it is not a background one. */
155
160
  private urgent;
156
161
  /** Reads left that are signaling: the contact is leaving DHT only, and the live link waits on them (`expect`). */
@@ -235,6 +240,8 @@ export declare class DhtDelivery {
235
240
  * burst of an app coming back (bug hunt r7a). A text, a receipt, a new mode or a new capability revision still go at once.
236
241
  */
237
242
  firstControlAfterMs?: number;
243
+ /** This side made the invite, then: once no longer awaited, its mailbox is read less often while nobody uses it (`unusedInviteWait`). */
244
+ inviteMadeAt?: number;
238
245
  });
239
246
  get view(): DhtDeliveryView;
240
247
  /**
@@ -381,6 +388,8 @@ export declare class DhtDelivery {
381
388
  private publishOnTick;
382
389
  /** How long until the next read of the contact's mailbox (WISP 403, poll pace). */
383
390
  get pollMs(): number;
391
+ /** How long ago this side's invite was made, while nobody used it and it is no longer awaited (`AWAITING_PEER_MS`). */
392
+ private unusedInviteAge;
384
393
  private schedule;
385
394
  }
386
395
  export declare const DHT_TEXT_REFUSED = "Your contact's app does not accept text over the DHT. It is sent when you are live.";
@@ -24,6 +24,7 @@ export declare const ENGINE_ERRORS: {
24
24
  readonly notEnoughSats: "Not enough sats in your wallet";
25
25
  readonly noSharedMint: "You share no mint with this contact";
26
26
  readonly ecashAlreadySpent: "This ecash was already spent somewhere else";
27
+ readonly ecashBeingReceived: "This ecash is already being received";
27
28
  readonly ecashOtherUnit: "This ecash is in {unit}: only sat ecash can be redeemed here";
28
29
  readonly reviewedEcashSpent: "The ecash for this payment was already spent somewhere else. Nothing was sent, and your balance now shows what the mint still holds.";
29
30
  readonly reviewedSatsGone: "The sats this payment was reviewed with went to another payment. Nothing was sent: review it again.";
@@ -202,6 +202,11 @@ export interface FrameChannel {
202
202
  * WebRTC data channel does, and a sender only keeps under `LIMITS.sendHighWaterMark`.
203
203
  */
204
204
  readonly sendBudget?: number;
205
+ /**
206
+ * It carries binary messages as well as text (WISP 100 § Text and binary messages): a WebRTC data channel does.
207
+ * Absent: text only, as the Iroh channels are, and nothing binary is offered or sent on it.
208
+ */
209
+ readonly binary?: boolean;
205
210
  close(): void;
206
211
  onMessage: ((data: string | Uint8Array) => void) | null;
207
212
  onClose: (() => void) | null;
@@ -31,14 +31,29 @@ import { type PairingProgress, type PairingRole } from "./pairingProgress.js";
31
31
  export declare const DHT_PIN_GRACE_MS = 10000;
32
32
  /** Back after a restart (`resume`), dials wait this long at most for the native endpoint that carried the chat to start. */
33
33
  export declare const RESUME_WAIT_MS = 10000;
34
- /** Two dials crossing: how long the lower key's side waits for its own to connect before it takes the contact's. */
35
- export declare const CROSSED_WAIT_MS = 3000;
34
+ /**
35
+ * Two dials crossing: how long the lower key's side waits for its own to connect before it takes the contact's. Two
36
+ * dials that both go through connect within a round trip of each other: each side's preface goes out as the other's
37
+ * dial reaches it. One not connected by then has stalled (a HyperDHT stream that opened and carries nothing, dialled
38
+ * again only 2 s later) or goes to an endpoint the contact no longer runs: waiting for it held a working connection
39
+ * back 0.9-1.9 s (DHT-direct lab, 5 of 20 first pairings). Taken, this side's dial is closed when it lands, and on the
40
+ * contact's side it never authenticates (`attachReplacement`).
41
+ */
42
+ export declare const CROSSED_WAIT_MS = 500;
36
43
  /**
37
44
  * A session this side dialled this recently is one a crossing dial of the contact's may meet (both connected): the
38
45
  * lower key keeps its own. Older, the session is one the contact has since lost (its app restarted), and its dial
39
46
  * takes over.
40
47
  */
41
48
  export declare const CROSSED_FRESH_MS = 10000;
49
+ /**
50
+ * A dial of the contact's that meets such a session waits this long for that session to answer a ping. It answers when
51
+ * the dials crossed (the contact holds this side's dial too); it does not when the contact's app ended since and is
52
+ * back: its dial then takes over. Refused outright, that dial left the contact waiting for the dead session's end, 16.6
53
+ * to 18.9 s (CLI daemons over HyperDHT, the contact killed 1 to 3 s after this side's knock, 5 of 5). A round trip is
54
+ * 7 ms on loopback and under 0.5 s over a relayed Iroh.
55
+ */
56
+ export declare const CROSSED_PROBE_MS = 1500;
42
57
  /** A joiner gathers its offer while it first looks for the inviter (`dialEarly`) only this soon after the join. */
43
58
  export declare const EARLY_DIAL_JOIN_MS = 60000;
44
59
  /** What a joiner is told when someone else used the invite first (`DhtDeliveryView.inviteTaken`). */
@@ -359,7 +374,10 @@ export interface GhostLinkEvents {
359
374
  onFileProgress?(fileId: string, transferred: number, direction: "in" | "out"): void;
360
375
  onFileComplete?(fileId: string, direction: "in" | "out"): void;
361
376
  onFileFailed?(fileId: string, reason: string, direction: "in" | "out"): void;
362
- /** A files/3 frame (`FILE_FRAMES`), only while both sides agreed `files/3` on the open session. */
377
+ /**
378
+ * A files/3 frame (`FILE_FRAMES`), only while both sides agreed `files/3` on the open session. A file's data that came
379
+ * as a binary message (`files/4`) is the `pf-data` frame it stands for, its `data` the bytes themselves.
380
+ */
363
381
  onFilesFrame?(frame: Record<string, unknown>): void | Promise<void>;
364
382
  /**
365
383
  * files/3 can flow (a session agreed it and is open), or no longer can. Said again, open, after a live
@@ -417,6 +435,11 @@ export interface GhostLinkOptions {
417
435
  servicesSupport?: boolean;
418
436
  /** Offer `files/3` on paired sessions: files of any size, offered, resumed and checked (`chatFiles.ts`). */
419
437
  largeFilesSupport?: boolean;
438
+ /**
439
+ * With `largeFilesSupport`, offer `files/4` on a session whose channel carries binary messages: a file's bytes as
440
+ * they are, not as text (WISP 501 § files/4). The owner's `onFilesFrame` then takes a `pf-data` whose `data` is bytes.
441
+ */
442
+ binaryFilesSupport?: boolean;
420
443
  /** Offer `typing/1` on paired sessions: say and show when either side is writing (1:1 chats, not group edges). */
421
444
  typingSupport?: boolean;
422
445
  /** Offer `react/1` on paired sessions: reactions to messages (1:1 chats, not group edges). */
@@ -700,10 +723,15 @@ export declare class GhostLink {
700
723
  * was the app's in the background, not a restart (`resumeAfterAbsence`).
701
724
  */
702
725
  private offered?;
726
+ /**
727
+ * The WebRTC offer this side's dial made last, fallback allowed or not: one made before the contact's record was read
728
+ * races once it is (`raceStandingOffer`).
729
+ */
730
+ private offerMade?;
703
731
  /** The attempt (its epoch) whose direct transports were knocked on as its offer went out (`knockEarly`), and whether that is under way. */
704
732
  private knockedEarly;
705
733
  private knockingEarly;
706
- /** When that offer's answer was applied (`RACE_ANSWERED_MS`); 0 while the data link is not connecting on it. */
734
+ /** When this side's offer's answer was applied (`RACE_ANSWERED_MS`); 0 while the data link is not connecting on it. */
707
735
  private answeredAt;
708
736
  /** This side's offer is out unanswered, or answered and not connected yet: what is ranked after WebRTC may race it. */
709
737
  private get offerOut();
@@ -1056,6 +1084,14 @@ export declare class GhostLink {
1056
1084
  * it) or `RACE_RELAYED_MS` (a relayed one), those are dialled too, the offer standing meanwhile.
1057
1085
  */
1058
1086
  private scheduleRace;
1087
+ /**
1088
+ * This side's offer went out before the contact's record was read (a joiner's early one, `dialEarly`): nothing was
1089
+ * known of what the contact runs, so it was made with no fallback and nothing raced it. Once the record says, and both
1090
+ * sides allow it, the offer races what both run as one made then would: answered and not connected `RACE_ANSWERED_MS`
1091
+ * later, the relayed ones too. Behind a VPN that drops UDP, a first pairing went live over the relayed Iroh only once
1092
+ * the attempt timed out and the next one raced, 32 to 66 s in (zero's VPN lab, 2026-10-13).
1093
+ */
1094
+ private raceStandingOffer;
1059
1095
  /**
1060
1096
  * Back after an absence, this side answers an offer the contact made while it was away (it dials whatever its key):
1061
1097
  * the contact looks for that answer at the pace of an offer out a while (every 8 s on the relays), and its attempt may
@@ -1101,6 +1137,16 @@ export declare class GhostLink {
1101
1137
  * fast looks for the member's `_tr` end after a few (`PACKET_TRANSPORTS_FAST_ATTEMPTS`).
1102
1138
  */
1103
1139
  private anythingToDial;
1140
+ /**
1141
+ * Neither side can dial the other until something changes, past a first pairing: what the contact runs is known, and
1142
+ * no transport both run has WebRTC on both sides or an endpoint up on both (this side's, and the one its record
1143
+ * describes). A chat that gave its listener up to another (`yieldEndpoint`), or whose contact did, is so. It dials
1144
+ * again when that changes (a listener taken back, `registerEndpoint`; the record describing one, `learnPeerTransports`),
1145
+ * and reads at its own pace meanwhile: looks every 20 s for a dial with nothing to try, and the contact's fast looks
1146
+ * for an offer that could not come, read its key 2.5x to 4x as often as the background pace, for good (bug hunt,
1147
+ * 2026-10-12). A first pairing keeps both: the records are what it is reading for.
1148
+ */
1149
+ private nothingToDialEitherWay;
1104
1150
  private clearRace;
1105
1151
  /**
1106
1152
  * The offer is still unanswered: the transports ranked after WebRTC that are due are dialled now, each once in this
@@ -1275,6 +1321,8 @@ export declare class GhostLink {
1275
1321
  get supportsServices(): boolean;
1276
1322
  /** Both sides offer `files/3` on the open session: files of any size, offered and resumed. */
1277
1323
  get supportsLargeFiles(): boolean;
1324
+ /** Both sides offer `files/4` beside `files/3` on the open session: a file's bytes go as binary messages. */
1325
+ get supportsBinaryFiles(): boolean;
1278
1326
  /** Both sides offer `typing/1` on the open session: typing can be said and shown. */
1279
1327
  get supportsTyping(): boolean;
1280
1328
  /** Both sides offer `react/1` on the open session: reactions can be said and confirmed here. */
@@ -1341,7 +1389,10 @@ export declare class GhostLink {
1341
1389
  closeApp(app: string): void;
1342
1390
  /**
1343
1391
  * One data frame of an app open on both sides, on the live session only. An error when it did not go: nothing is
1344
- * kept to send later.
1392
+ * kept to send later. While the channel already holds a quarter of what it may queue (its send budget, or the high
1393
+ * water mark of a WebRTC channel), the frame is refused with `too-fast`, so the chat's messages and pings never wait
1394
+ * behind an app's data on a link slower than it sends (WISP 1200 § In a chat). While a file goes, that quarter sits
1395
+ * above what files may hold (`filesWritable`): files keep the channel at their own line for the whole transfer.
1345
1396
  */
1346
1397
  sendAppData(app: string, data: unknown): AppSendError | null;
1347
1398
  /** What the contact had open is gone (`apps/1` is no longer agreed, or this link stopped): each app hears it now. */
@@ -1358,10 +1409,20 @@ export declare class GhostLink {
1358
1409
  private emitFilesSession;
1359
1410
  /** A files/3 frame to the contact, on the open session. False when files/3 cannot flow now. */
1360
1411
  sendFilesFrame(frame: Record<string, unknown>): boolean;
1412
+ /**
1413
+ * A file's bytes to the contact, on the open session: one binary message while both sides agreed `files/4` on it,
1414
+ * the `pf-data` frame with them as base64url text otherwise (WISP 501 § files/4). The form is chosen for each chunk,
1415
+ * so a transfer follows the session it is on. False when files/3 cannot flow now, or the channel has no room.
1416
+ */
1417
+ sendFileData(id: string, offset: number, data: Uint8Array): boolean;
1418
+ /** Files on a channel: when they last wrote on it, and how many wait for room. An app's data gets room above theirs. */
1419
+ private filesUse;
1420
+ private filesUsing;
1361
1421
  /**
1362
1422
  * Resolves once the open session can take another files/3 data frame; undefined when it can now. A channel with a send budget (native and
1363
1423
  * iroh ones throw past 120 KiB) gives files a quarter of it, so a ping, a message or any other frame still fits
1364
- * while a file goes; others keep under the high water mark, as files/2 does.
1424
+ * while a file goes; others keep under the high water mark, as files/2 does. An app's data gets a quarter above that
1425
+ * line meanwhile (`sendAppData`).
1365
1426
  */
1366
1427
  filesWritable(): Promise<void> | undefined;
1367
1428
  /** What each side offers on the open session, for showing why something is unavailable. `peer` is null until it says. */
@@ -1399,8 +1460,8 @@ export declare class GhostLink {
1399
1460
  * Both sides dialled at once (two apps back after a restart, each knocking): the lower key's dial carries the chat, on
1400
1461
  * both sides; the higher key's side takes it over as a replacement (`attachReplacement`). Here, on the lower key's
1401
1462
  * side, the contact's connection waits: dropped once this side's own dial connects, taken if that dial fails, or has
1402
- * not connected within `CROSSED_WAIT_MS` (the contact may be dialling an app that is not up yet, for as long as its
1403
- * dial takes to give up).
1463
+ * not connected within `CROSSED_WAIT_MS` (it stalled, or goes to an endpoint the contact no longer runs, for as long
1464
+ * as it takes to give up).
1404
1465
  */
1405
1466
  private crossed;
1406
1467
  private parkCrossed;
@@ -1415,6 +1476,18 @@ export declare class GhostLink {
1415
1476
  * Before the pin a held session keeps the chat, as it always did.
1416
1477
  */
1417
1478
  private attachReplacement;
1479
+ private replaceWith;
1480
+ /**
1481
+ * The contact dialled in while this side's own fresh dial holds the chat (`CROSSED_FRESH_MS`): the dials crossed, or
1482
+ * the contact's app ended since that dial and is back. The held session is pinged; heard from within
1483
+ * `CROSSED_PROBE_MS`, the contact holds this side's dial too and its own closes. Not heard from, the contact's dial
1484
+ * takes over.
1485
+ */
1486
+ private crossedProbe;
1487
+ /** Frames heard on the open session, counted from its start: whether the contact answered `probeCrossed`. */
1488
+ private framesHeard;
1489
+ private probeCrossed;
1490
+ private dropCrossedProbe;
1418
1491
  /**
1419
1492
  * Connections that came in on this side's native endpoints. Their address was in the capability record, which before
1420
1493
  * the pin anyone holding a copy of the invite could read: a key other than the pinned one on such a connection proves
@@ -1423,6 +1496,8 @@ export declare class GhostLink {
1423
1496
  private readonly dialedIn;
1424
1497
  /** Connections whose session started with no key pinned nor named by the invite. */
1425
1498
  private readonly openedUnpinned;
1499
+ /** The WebRTC offer under way was made or answered with no key pinned nor named by the invite (its channel opens later). */
1500
+ private rtcStartedUnpinned;
1426
1501
  /**
1427
1502
  * `migration`: the channel is a candidate that takes over from the session open now once it authenticated. With a
1428
1503
  * `plan`, a live switch both sides agreed; without one, a replacement (`attachReplacement`): the contact dialled
@@ -59,6 +59,8 @@ export declare const COMMUNITY_LIMITS: {
59
59
  /** Commits in one welcome or chain piece. */
60
60
  readonly chainPiece: 100;
61
61
  readonly pendingLeaves: 64;
62
+ /** Leaves whose mark (`group-left`) is kept, and the epochs one names. */
63
+ readonly leftMarks: 64;
62
64
  /**
63
65
  * Syncs of one member answered in `syncWindowMs`: each answer may carry the chain's tail, secrets and the whole
64
66
  * store. A member catching up asks every five seconds at most, and every member syncs every thirty; one asking more
@@ -116,6 +118,8 @@ export declare function rosterHash(roster: Roster): string;
116
118
  /** The id of a community group: from its creator and a nonce, so no other genesis can claim it. */
117
119
  export declare function communityGroupId(creator: string, nonce: string): string;
118
120
  export declare const leaveStatement: (g: string, s: string) => Uint8Array<ArrayBufferLike>;
121
+ /** What the member who committed a leave (`h`) had heard of the leaver then: `e:h16` → its highest number there. */
122
+ export declare const leftStatement: (g: string, h: string, hi: Record<string, number>) => Uint8Array<ArrayBufferLike>;
119
123
  /** The secret of an epoch that adds, re-roles or re-links: from the previous one and the commit. */
120
124
  export declare function derivedSecret(previous: Uint8Array, untaggedHash: string): Uint8Array;
121
125
  /**
@@ -199,6 +203,18 @@ export interface CommunityLeaveFrame {
199
203
  s: string;
200
204
  ls: string;
201
205
  }
206
+ /**
207
+ * The mark of a leave (`h`, the commit's full hash), signed by the member who committed it: how far it had heard the
208
+ * leaver in each epoch. What the leaver wrote past it is not taken (WISP 903 § Leaving and removal).
209
+ */
210
+ export interface CommunityLeftFrame {
211
+ t: "group-left";
212
+ v: 2;
213
+ g: string;
214
+ h: string;
215
+ hi: Record<string, number>;
216
+ sig: string;
217
+ }
202
218
  /** The seed of the link's current entry key, sealed to one member: after a `link` commit, or at a sync. */
203
219
  export interface CommunityEntryFrame {
204
220
  t: "group-entry";
@@ -236,7 +252,7 @@ export interface CommunityWelcomeFrame {
236
252
  rv: SealedSecret;
237
253
  entry: SealedSecret;
238
254
  }
239
- export type CommunityFrame = CommunityMessageFrame | CommunityCommitFrame | CommunitySecretFrame | CommunitySecretsFrame | CommunitySyncFrame | CommunityLeaveFrame | CommunityEntryFrame | GroupMetaFrame;
255
+ export type CommunityFrame = CommunityMessageFrame | CommunityCommitFrame | CommunitySecretFrame | CommunitySecretsFrame | CommunitySyncFrame | CommunityLeaveFrame | CommunityLeftFrame | CommunityEntryFrame | GroupMetaFrame;
240
256
  export type CommunityStatus = "active" | "left" | "removed" | "forked" | "lost";
241
257
  export interface CommunityState {
242
258
  id: string;
@@ -286,6 +302,11 @@ export interface CommunityState {
286
302
  s: string;
287
303
  ls: string;
288
304
  }[];
305
+ /** Leave commit (full hash) → its mark, as its committer signed it (`group-left`), oldest first. Absent in older states. */
306
+ left?: Record<string, {
307
+ hi: Record<string, number>;
308
+ sig: string;
309
+ }>;
289
310
  /** The group's metadata (its picture), as the admin last signed it and I accepted it. */
290
311
  meta?: GroupMeta;
291
312
  }
@@ -467,6 +488,19 @@ export declare class CommunitySession {
467
488
  /** When the chain took them out (the commit's time, by its signer's clock), if it did and they are not back in. */
468
489
  outAt(key: string): number | undefined;
469
490
  private outIndex;
491
+ /**
492
+ * Whether a frame of someone the chain took out is still heard. A member removed is heard no more, even for an epoch
493
+ * it was in. What one who left wrote while in the group is taken and handed on, its goodbye included, up to what the
494
+ * member who committed the leave had heard of it then (its `group-left` mark), never past it: the leaver still holds
495
+ * those epochs' secrets, and anything it signs later is not heard (WISP 903 § Leaving and removal). No mark here
496
+ * (one not come yet, or a committer's app before it) and nothing of it is heard.
497
+ */
498
+ private heardAfterOut;
499
+ /** The mark of a leave on my branch, as a frame to hand on (see `heardAfterOut`). */
500
+ private leftFrame;
501
+ private keepLeft;
502
+ /** A leave's mark, from the member who committed it: kept when it is that member's, for a leave I hold. */
503
+ private receiveLeft;
470
504
  /**
471
505
  * What someone the chain took out is told when it comes back (WISP 903 § Leaving and removal): the commits from where
472
506
  * it says it is (`sync`: its tip, or its locator) up to the one that took it out, and nothing after. Later commits
@@ -571,6 +605,8 @@ export declare class CommunitySession {
571
605
  leave(): Promise<CommunityLeaveFrame | null>;
572
606
  /** Commits the leave requests I hold whose members are still in: the engine calls this on hubs. */
573
607
  commitPendingLeaves(now?: number): Promise<number>;
608
+ /** Signs and says how far I had heard a member whose leave I just committed (`group-left`). */
609
+ private markLeft;
574
610
  private out;
575
611
  /**
576
612
  * `mentions`: places of the text that name members, sealed with it (`m`). Never everyone in a community. They
@@ -31,8 +31,12 @@ export declare const GROUP_FILE_LIMITS: {
31
31
  readonly heardAhead: 256;
32
32
  /** Message ids in one `group-have`. */
33
33
  readonly haveIds: 32;
34
- /** A private group's `group-have` goes on an edge at most this often; a community's, from a member, every `communityHaveEveryMs`. */
35
- readonly haveEveryMs: 10000;
34
+ /**
35
+ * `group-have` frames a private group's edge takes in `haveWindowMs`: what is to say is gathered for a second, then
36
+ * goes. A community's, from a member, goes every `communityHaveEveryMs`.
37
+ */
38
+ readonly haveFrames: 10;
39
+ readonly haveWindowMs: 10000;
36
40
  readonly communityHaveEveryMs: 60000;
37
41
  /**
38
42
  * How long a want waits for an offer before the next holder is asked; a transfer that does not move for as long is