@ghostlytools/sdk 1.2.4 → 1.3.1

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 +10 -4
  2. package/dist/app.js.map +1 -1
  3. package/dist/core.js +2 -2
  4. package/dist/{fakes-JOzOFxn3.js → fakes-Bpy2WRVB.js} +2 -2
  5. package/dist/{fakes-JOzOFxn3.js.map → fakes-Bpy2WRVB.js.map} +1 -1
  6. package/dist/fakes.js +1 -1
  7. package/dist/index.js +2 -2
  8. package/dist/{keet-identity-key-BLli1rE4.js → keet-identity-key-DypfAhWn.js} +2 -2
  9. package/dist/{keet-identity-key-BLli1rE4.js.map → keet-identity-key-DypfAhWn.js.map} +1 -1
  10. package/dist/{src-BqHTnRWH.js → src-CXmIA8pL.js} +889 -119
  11. package/dist/src-CXmIA8pL.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 +22 -0
  17. package/dist/types/core/src/frames.d.ts +5 -0
  18. package/dist/types/core/src/ghostlink.d.ts +76 -3
  19. package/dist/types/core/src/groupCommunity.d.ts +41 -7
  20. package/dist/types/core/src/groupFiles.d.ts +6 -2
  21. package/dist/types/core/src/groupSession.d.ts +38 -5
  22. package/dist/types/core/src/groupSignals.d.ts +2 -0
  23. package/dist/types/core/src/link.d.ts +18 -0
  24. package/dist/types/core/src/miniApp.d.ts +10 -4
  25. package/dist/types/core/src/pairedCapabilities.d.ts +6 -1
  26. package/dist/types/core/src/pkarr.d.ts +6 -0
  27. package/dist/types/core/src/relay.d.ts +38 -4
  28. package/dist/types/core/src/relayBreaker.d.ts +4 -1
  29. package/dist/types/core/src/transport.d.ts +5 -0
  30. package/dist/{verify-RjMx7eW6.js → verify-Bxi3-0i6.js} +2 -2
  31. package/dist/{verify-RjMx7eW6.js.map → verify-Bxi3-0i6.js.map} +1 -1
  32. package/package.json +1 -1
  33. package/dist/src-BqHTnRWH.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-BqHTnRWH.js";
1
+ import { Bi as isBitcoinAddress, _u as newIdentityBinding, da as decodeBolt11, du as emptyIdentityLedger, eu as IDENTITY_MAX_EVIDENCE, lu as IdentityExchange, mu as identityStatement, nx as createIdentity } from "./src-CXmIA8pL.js";
2
2
  import { l as providerDescriptorProblems, o as isNothingSpentError } from "./types-DvtCy3WB.js";
3
- import { i as verifyIdentity, r as descriptorProblems } from "./verify-RjMx7eW6.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-JOzOFxn3.js";
3
+ import { i as verifyIdentity, r as descriptorProblems } from "./verify-Bxi3-0i6.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-Bpy2WRVB.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. */
@@ -98,6 +98,12 @@ export interface DhtDeliveryState {
98
98
  * "the invite was taken" from then on is not the contact's word (`sealedToAnother`).
99
99
  */
100
100
  wasLive?: true;
101
+ /**
102
+ * This side joined, and pinned the inviter from an envelope it put out before anyone joined (sealed with the invite's
103
+ * key, not to this side): that envelope's sequence. Until the inviter shows it was there since (`DhtDelivery.unanswered`),
104
+ * the chat is read as an invite nobody used (`unusedInviteWait`), counted from the join.
105
+ */
106
+ unanswered?: number;
101
107
  }
102
108
  export interface DhtDeliveryView {
103
109
  mode: DeliveryMode;
@@ -155,6 +161,7 @@ export declare class DhtDelivery {
155
161
  private fastUntil;
156
162
  private live;
157
163
  private active;
164
+ private readonly startedAt;
158
165
  /** The next read was asked for (a refresh, a fresh packet of the contact): it is not a background one. */
159
166
  private urgent;
160
167
  /** Reads left that are signaling: the contact is leaving DHT only, and the live link waits on them (`expect`). */
@@ -239,8 +246,18 @@ export declare class DhtDelivery {
239
246
  * 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.
240
247
  */
241
248
  firstControlAfterMs?: number;
249
+ /**
250
+ * This side made the invite, or joined one, then: once no longer awaited, its mailbox is read less often while nobody
251
+ * uses it, or while its inviter never answered the join (`unanswered`) (`unusedInviteWait`).
252
+ */
253
+ inviteMadeAt?: number;
242
254
  });
243
255
  get view(): DhtDeliveryView;
256
+ /**
257
+ * This side joined, and its inviter never answered (`DhtDeliveryState.unanswered`): no envelope of its newer than the
258
+ * one that pinned it, none sealed to this side, no text confirmed, never live (as `sealedToAnother` asks too).
259
+ */
260
+ get unanswered(): boolean;
244
261
  /**
245
262
  * Something signed by a participation key other than the pinned one came in over the chat's invite-derived keys (this
246
263
  * mailbox, the link's signals, a connection to an endpoint whose address a copy of the invite could read): ignored,
@@ -385,6 +402,11 @@ export declare class DhtDelivery {
385
402
  private publishOnTick;
386
403
  /** How long until the next read of the contact's mailbox (WISP 403, poll pace). */
387
404
  get pollMs(): number;
405
+ /**
406
+ * How long ago this side's invite was made (or joined), while nobody used it (or its inviter never answered,
407
+ * `unanswered`) and it is no longer awaited (`AWAITING_PEER_MS`).
408
+ */
409
+ private unusedInviteAge;
388
410
  private schedule;
389
411
  }
390
412
  export declare const DHT_TEXT_REFUSED = "Your contact's app does not accept text over the DHT. It is sent when you are live.";
@@ -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;
@@ -46,6 +46,14 @@ export declare const CROSSED_WAIT_MS = 500;
46
46
  * takes over.
47
47
  */
48
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;
49
57
  /** A joiner gathers its offer while it first looks for the inviter (`dialEarly`) only this soon after the join. */
50
58
  export declare const EARLY_DIAL_JOIN_MS = 60000;
51
59
  /** What a joiner is told when someone else used the invite first (`DhtDeliveryView.inviteTaken`). */
@@ -178,6 +186,14 @@ export declare const MAX_PAIRED_MESSAGE_FRAME: number;
178
186
  * WISP 405 · Status Cards), whose 8 KiB with the text's 16 stay well inside the frame.
179
187
  */
180
188
  export declare function pairedMessageFrame(id: string, ts: number, m: string, preview?: LinkPreview, reply?: WireReply, forwarded?: number, card?: StatusCard): string;
189
+ /** A text whose `paired-message` frame would pass what a session takes: it never arrives, and is refused at send. */
190
+ export declare const PAIRED_FRAME_TOO_LARGE = "Message too long once encoded. Shorten it or send it as a file.";
191
+ /**
192
+ * The `paired-message` frame of this text fits a session (`SESSION_FRAME_MAX`, UTF-16 units of the JSON). Within 16 KiB
193
+ * of UTF-8 a text can still pass it: JSON writes each control character as six (`\u0001`). The preview is left out,
194
+ * as the frame drops one that does not fit.
195
+ */
196
+ export declare function pairedMessageFits(ts: number, m: string, reply?: WireReply, forwarded?: number, card?: StatusCard): boolean;
181
197
  /**
182
198
  * The transport a chat is set to reach and is not on yet (WISP 100, "A chosen transport not reached yet"): waited for,
183
199
  * never failed. `by`: whose choice names it (absent: a policy alone, such as Fallback off, limits the chat to it).
@@ -366,7 +382,10 @@ export interface GhostLinkEvents {
366
382
  onFileProgress?(fileId: string, transferred: number, direction: "in" | "out"): void;
367
383
  onFileComplete?(fileId: string, direction: "in" | "out"): void;
368
384
  onFileFailed?(fileId: string, reason: string, direction: "in" | "out"): void;
369
- /** A files/3 frame (`FILE_FRAMES`), only while both sides agreed `files/3` on the open session. */
385
+ /**
386
+ * A files/3 frame (`FILE_FRAMES`), only while both sides agreed `files/3` on the open session. A file's data that came
387
+ * as a binary message (`files/4`) is the `pf-data` frame it stands for, its `data` the bytes themselves.
388
+ */
370
389
  onFilesFrame?(frame: Record<string, unknown>): void | Promise<void>;
371
390
  /**
372
391
  * files/3 can flow (a session agreed it and is open), or no longer can. Said again, open, after a live
@@ -424,6 +443,11 @@ export interface GhostLinkOptions {
424
443
  servicesSupport?: boolean;
425
444
  /** Offer `files/3` on paired sessions: files of any size, offered, resumed and checked (`chatFiles.ts`). */
426
445
  largeFilesSupport?: boolean;
446
+ /**
447
+ * With `largeFilesSupport`, offer `files/4` on a session whose channel carries binary messages: a file's bytes as
448
+ * they are, not as text (WISP 501 § files/4). The owner's `onFilesFrame` then takes a `pf-data` whose `data` is bytes.
449
+ */
450
+ binaryFilesSupport?: boolean;
427
451
  /** Offer `typing/1` on paired sessions: say and show when either side is writing (1:1 chats, not group edges). */
428
452
  typingSupport?: boolean;
429
453
  /** Offer `react/1` on paired sessions: reactions to messages (1:1 chats, not group edges). */
@@ -1076,6 +1100,8 @@ export declare class GhostLink {
1076
1100
  * the attempt timed out and the next one raced, 32 to 66 s in (zero's VPN lab, 2026-10-13).
1077
1101
  */
1078
1102
  private raceStandingOffer;
1103
+ /** The offer ends (`raceStandingOffer`), and with it going idle what is ranked after WebRTC is dialled (`dialAfterRtc`). */
1104
+ private endUnanswerableOffer;
1079
1105
  /**
1080
1106
  * Back after an absence, this side answers an offer the contact made while it was away (it dials whatever its key):
1081
1107
  * 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
@@ -1121,6 +1147,16 @@ export declare class GhostLink {
1121
1147
  * fast looks for the member's `_tr` end after a few (`PACKET_TRANSPORTS_FAST_ATTEMPTS`).
1122
1148
  */
1123
1149
  private anythingToDial;
1150
+ /**
1151
+ * Neither side can dial the other until something changes, past a first pairing: what the contact runs is known, and
1152
+ * no transport both run has WebRTC on both sides or an endpoint up on both (this side's, and the one its record
1153
+ * describes). A chat that gave its listener up to another (`yieldEndpoint`), or whose contact did, is so. It dials
1154
+ * again when that changes (a listener taken back, `registerEndpoint`; the record describing one, `learnPeerTransports`),
1155
+ * and reads at its own pace meanwhile: looks every 20 s for a dial with nothing to try, and the contact's fast looks
1156
+ * for an offer that could not come, read its key 2.5x to 4x as often as the background pace, for good (bug hunt,
1157
+ * 2026-10-12). A first pairing keeps both: the records are what it is reading for.
1158
+ */
1159
+ private nothingToDialEitherWay;
1124
1160
  private clearRace;
1125
1161
  /**
1126
1162
  * The offer is still unanswered: the transports ranked after WebRTC that are due are dialled now, each once in this
@@ -1128,6 +1164,11 @@ export declare class GhostLink {
1128
1164
  * offer (`attach`); the offer answered first, the native dial is closed.
1129
1165
  */
1130
1166
  private race;
1167
+ /**
1168
+ * This side does not dial on its own: the contact's app does (the lower key), and none of what makes this side dial
1169
+ * anyway holds (a first pairing's role, a restart, WebRTC set aside). Its own dial, chosen by hand, is not retried.
1170
+ */
1171
+ private awaitsContactDial;
1131
1172
  /** A transport of the attempt under way did not connect. */
1132
1173
  private attemptFailed;
1133
1174
  /** The attempt under way ended without going live: kept as the last one, and told. `reason`: why, when nothing was tried. */
@@ -1295,6 +1336,8 @@ export declare class GhostLink {
1295
1336
  get supportsServices(): boolean;
1296
1337
  /** Both sides offer `files/3` on the open session: files of any size, offered and resumed. */
1297
1338
  get supportsLargeFiles(): boolean;
1339
+ /** Both sides offer `files/4` beside `files/3` on the open session: a file's bytes go as binary messages. */
1340
+ get supportsBinaryFiles(): boolean;
1298
1341
  /** Both sides offer `typing/1` on the open session: typing can be said and shown. */
1299
1342
  get supportsTyping(): boolean;
1300
1343
  /** Both sides offer `react/1` on the open session: reactions can be said and confirmed here. */
@@ -1361,7 +1404,12 @@ export declare class GhostLink {
1361
1404
  closeApp(app: string): void;
1362
1405
  /**
1363
1406
  * One data frame of an app open on both sides, on the live session only. An error when it did not go: nothing is
1364
- * kept to send later.
1407
+ * kept to send later. While the channel already holds a quarter of what it may queue (its send budget, or the high
1408
+ * water mark of a WebRTC channel), the frame is refused with `too-fast`, so the chat's messages and pings never wait
1409
+ * behind an app's data on a link slower than it sends (WISP 1200 § In a chat). While a file goes, that quarter sits
1410
+ * above what files may hold (`filesWritable`): files keep the channel at their own line for the whole transfer. While
1411
+ * the file waits for room, the app gets no further than `APP_AHEAD_OF_FILES` ahead of it, so it cannot refill the
1412
+ * channel each time it drains to files' line and keep the file from moving.
1365
1413
  */
1366
1414
  sendAppData(app: string, data: unknown): AppSendError | null;
1367
1415
  /** What the contact had open is gone (`apps/1` is no longer agreed, or this link stopped): each app hears it now. */
@@ -1378,10 +1426,23 @@ export declare class GhostLink {
1378
1426
  private emitFilesSession;
1379
1427
  /** A files/3 frame to the contact, on the open session. False when files/3 cannot flow now. */
1380
1428
  sendFilesFrame(frame: Record<string, unknown>): boolean;
1429
+ /**
1430
+ * A file's bytes to the contact, on the open session: one binary message while both sides agreed `files/4` on it,
1431
+ * the `pf-data` frame with them as base64url text otherwise (WISP 501 § files/4). The form is chosen for each chunk,
1432
+ * so a transfer follows the session it is on. False when files/3 cannot flow now, or the channel has no room.
1433
+ */
1434
+ sendFileData(id: string, offset: number, data: Uint8Array): boolean;
1435
+ /**
1436
+ * Files on a channel: when they last wrote on it, how many wait for room, and how many bytes an app's data has sent
1437
+ * on it beyond theirs since. An app's data gets room above theirs.
1438
+ */
1439
+ private filesUse;
1440
+ private filesUsing;
1381
1441
  /**
1382
1442
  * 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
1383
1443
  * iroh ones throw past 120 KiB) gives files a quarter of it, so a ping, a message or any other frame still fits
1384
- * while a file goes; others keep under the high water mark, as files/2 does.
1444
+ * while a file goes; others keep under the high water mark, as files/2 does. An app's data gets a quarter above that
1445
+ * line meanwhile (`sendAppData`).
1385
1446
  */
1386
1447
  filesWritable(): Promise<void> | undefined;
1387
1448
  /** What each side offers on the open session, for showing why something is unavailable. `peer` is null until it says. */
@@ -1435,6 +1496,18 @@ export declare class GhostLink {
1435
1496
  * Before the pin a held session keeps the chat, as it always did.
1436
1497
  */
1437
1498
  private attachReplacement;
1499
+ private replaceWith;
1500
+ /**
1501
+ * The contact dialled in while this side's own fresh dial holds the chat (`CROSSED_FRESH_MS`): the dials crossed, or
1502
+ * the contact's app ended since that dial and is back. The held session is pinged; heard from within
1503
+ * `CROSSED_PROBE_MS`, the contact holds this side's dial too and its own closes. Not heard from, the contact's dial
1504
+ * takes over.
1505
+ */
1506
+ private crossedProbe;
1507
+ /** Frames heard on the open session, counted from its start: whether the contact answered `probeCrossed`. */
1508
+ private framesHeard;
1509
+ private probeCrossed;
1510
+ private dropCrossedProbe;
1438
1511
  /**
1439
1512
  * Connections that came in on this side's native endpoints. Their address was in the capability record, which before
1440
1513
  * the pin anyone holding a copy of the invite could read: a key other than the pinned one on such a connection proves
@@ -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
  }
@@ -468,11 +489,18 @@ export declare class CommunitySession {
468
489
  outAt(key: string): number | undefined;
469
490
  private outIndex;
470
491
  /**
471
- * Someone the chain removed (not one who left) and who is not back in: nothing it signs is heard any more, even for
472
- * an epoch it was in. What one who left wrote while in the group is still taken and handed on, for the epochs it was
473
- * in (WISP 903 § Leaving and removal): its goodbye reaches the members who were away.
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.
474
497
  */
475
- private wasExpelled;
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;
476
504
  /**
477
505
  * What someone the chain took out is told when it comes back (WISP 903 § Leaving and removal): the commits from where
478
506
  * it says it is (`sync`: its tip, or its locator) up to the one that took it out, and nothing after. Later commits
@@ -577,6 +605,8 @@ export declare class CommunitySession {
577
605
  leave(): Promise<CommunityLeaveFrame | null>;
578
606
  /** Commits the leave requests I hold whose members are still in: the engine calls this on hubs. */
579
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;
580
610
  private out;
581
611
  /**
582
612
  * `mentions`: places of the text that name members, sealed with it (`m`). Never everyone in a community. They
@@ -654,8 +684,12 @@ export declare class CommunitySession {
654
684
  h: string;
655
685
  n: number;
656
686
  }): string;
657
- /** Where I am and what I have, for the member at the other end of an edge that just opened. */
658
- syncFrame(): CommunitySyncFrame;
687
+ /**
688
+ * Where I am and what I have, for the member at the other end of an edge that just opened. `to`: that member, now
689
+ * asked: my answer to its own sync asks nothing more for a while. A second sync went, and its answer took the place of
690
+ * what was left of the first from its start: a member back after 256 messages was handed 288 (2026-10-14).
691
+ */
692
+ syncFrame(to?: string): CommunitySyncFrame;
659
693
  /**
660
694
  * A frame from the edge of member `from` (the author, or a hub relaying it). Returns whether it
661
695
  * was new and valid, so a hub knows to relay it on.
@@ -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
@@ -248,7 +248,11 @@ export interface GroupState {
248
248
  seqEpoch: number;
249
249
  /** My own frames, newest last, for members who missed them. */
250
250
  sent: GroupMessageFrame[];
251
- /** Other members' frames, in the order they arrived, for members who missed them. Absent in states from before revision 0.9. */
251
+ /**
252
+ * Other members' frames, in the order they arrived, for members who missed them. Absent in states from before revision
253
+ * 0.9. With an app that keeps each frame with its message (`GroupSession`'s `onRows`), only the ones from before it
254
+ * did, until newer ones take their place.
255
+ */
252
256
  relay?: GroupMessageFrame[];
253
257
  /** Other members' edits, the latest per message, for members who missed them. Absent in states from before edits were handed on. */
254
258
  relayEdits?: GroupEditFrame[];
@@ -303,6 +307,12 @@ export interface GroupSessionHooks {
303
307
  send(to: string, frame: GroupEdgeFrame): boolean | void;
304
308
  /** Store before it resolves: replay state advances only afterwards. */
305
309
  message(message: GroupIncomingMessage): Promise<void> | void;
310
+ /**
311
+ * A frame kept to hand on that came with no message of its own: message `id`, stored before, said again by its author
312
+ * under a later epoch (WISP 902 § Catch-up, "Frames said again"). An app that keeps the frames with its messages puts
313
+ * this one in the place of that message's.
314
+ */
315
+ kept?(id: string, frame: GroupMessageFrame): Promise<void> | void;
306
316
  /** An edit of a member's message, authenticated as its author (WISP 902 § Edits). Apps without edits leave it out. */
307
317
  edit?(edit: GroupIncomingEdit): Promise<void> | void;
308
318
  /** Roster, epoch or status changed. */
@@ -360,7 +370,6 @@ export interface GroupPinFrame extends WirePin {
360
370
  k: string;
361
371
  sig: string;
362
372
  }
363
- /** What a frame weighs in a log, roughly: its boxes plus the fixed fields around them. */
364
373
  /** What a kept frame counts for against `GROUP_LIMITS.relayBytes`. */
365
374
  export declare const frameBytes: (f: GroupMessageFrame) => number;
366
375
  /**
@@ -391,8 +400,15 @@ export declare class GroupSession {
391
400
  private pendingMeta;
392
401
  /** While `handle` runs: the frames it took that a hub passes on (`handle`'s result). */
393
402
  private passOn;
403
+ /** The frames kept to hand on that the app holds with its messages, oldest first; undefined when the state holds them all. */
404
+ private onRows;
394
405
  /** Set while a save of what received messages changed is due (`persistSoon`). */
395
406
  private saveTimer;
407
+ /**
408
+ * The frames of members who left that each member was handed (`frameKey`), so an app that does not take them (from
409
+ * before revision 2026-10-13, and never marks them seen) is not handed them again at every sync. In memory only.
410
+ */
411
+ private leaversHanded;
396
412
  /** Syncs answered per member, a few a minute (`GROUP_LIMITS.syncAnswers`). In memory only. */
397
413
  private syncsAnswered;
398
414
  /** Catch-up answers still going out, a slice at a time (`handOut`). */
@@ -405,7 +421,12 @@ export declare class GroupSession {
405
421
  private provisional;
406
422
  /** When my chain last moved (a commit made or applied), by `hooks.clock`: frames are said again once it has settled. */
407
423
  private chainMovedAt;
408
- constructor(state: GroupState, hooks: GroupSessionHooks);
424
+ /**
425
+ * `onRows`: the frames the app holds with the messages it stored (`GroupIncomingMessage.frame`), oldest first. Given
426
+ * (empty at first), the app is where frames are kept: the saved state carries none of them, and a message received
427
+ * no longer writes them all again. Absent: they are kept in the state, as before.
428
+ */
429
+ constructor(state: GroupState, hooks: GroupSessionHooks, onRows?: GroupMessageFrame[]);
409
430
  private clock;
410
431
  /** A new group: its genesis commit, signed by the creator, who is its admin. */
411
432
  static create(name: string, now?: number): GroupState;
@@ -508,12 +529,18 @@ export declare class GroupSession {
508
529
  /** A fresh secret without a membership change: whoever holds the old one and is not a member learns nothing new. */
509
530
  rotate(now?: number): Promise<void>;
510
531
  private commit;
511
- /** Someone out of the roster is not handed on any more, whatever they sent while in it (WISP 902 § Catch-up). */
532
+ /**
533
+ * Someone removed is not handed on any more, whatever they sent while in the roster; one who left still is, for the
534
+ * epochs before its leave (WISP 902 § Catch-up).
535
+ */
512
536
  private pruneRelay;
513
537
  /** Another member's edit, kept to hand on: the latest per message; the oldest go once the log is full. False: one as new was kept. */
514
538
  private keepEdit;
515
539
  /** A frame of another member, kept to hand on; the oldest go once the log is full. */
516
540
  private keep;
541
+ /** The frames kept to hand on, oldest first: the state's, then the ones the app holds with its messages. */
542
+ private kept;
543
+ private trimRelay;
517
544
  private pruneSecrets;
518
545
  /** Leaves: my secrets go now; the admin removes me from the roster when it hears. */
519
546
  leave(): Promise<void>;
@@ -652,7 +679,8 @@ export declare class GroupSession {
652
679
  private commitUnlessTurnUnconfirmed;
653
680
  /**
654
681
  * A message, from its author's edge or handed on by another member. Handed on, it is taken only while both are in
655
- * the roster (someone removed is neither heard from nor handed on, #300), and its boxes only with the author's `xs`.
682
+ * the roster (someone removed is neither heard from nor handed on, #300), or from a member in it when its author left
683
+ * after it (`handsOn`), and its boxes only with the author's `xs`.
656
684
  */
657
685
  private receiveMessage;
658
686
  /**
@@ -678,6 +706,11 @@ export declare class GroupSession {
678
706
  private ask;
679
707
  private replayWaiting;
680
708
  private receiveCommit;
709
+ /**
710
+ * Whether a frame of `author` under `epoch` is taken from another member, kept and handed on: while its author is in
711
+ * the roster, or when it left (its removal marked `left`, and it is not back in) and the frame is from before that.
712
+ */
713
+ private handsOn;
681
714
  /** Keeps the admin's mark on a commit that took out a member who left (`GroupCommitFrame.left`) when it holds; true when new. */
682
715
  private takeLeftMark;
683
716
  private apply;