@kition/kit-ui-protocol 0.0.0-stage → 0.2.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.
@@ -0,0 +1,1145 @@
1
+ /**
2
+ * The Kit UI protocol, `kition-kit-ui/1` (Kition platform docs/platform/reference/ui-protocol.md): its messages, and JSON-RPC 2.0
3
+ * over a MessagePort for both sides. A host and an embedded kit UI each make one `KitPeer` on
4
+ * their end of the channel. Framework-free; no dependencies.
5
+ */
6
+ export declare const KIT_UI_PROTOCOL = "kition-kit-ui/1";
7
+ /**
8
+ * The window messages that connect a host and a kit (`kitionKitUi: 1`, protocol section 2): the
9
+ * kit announces each document it loads (`ready`, with an id of its own), the host asks a kit that
10
+ * may have announced before it listened (`hello`), and answers a `ready` with the handshake that
11
+ * hands the kit its port.
12
+ */
13
+ export type KitUiHandshake = {
14
+ kitionKitUi: 1;
15
+ protocol: string;
16
+ id?: string;
17
+ };
18
+ export type KitUiReady = {
19
+ kitionKitUi: 1;
20
+ ready: string;
21
+ id: string;
22
+ };
23
+ export type KitUiHello = {
24
+ kitionKitUi: 1;
25
+ hello: string;
26
+ };
27
+ export declare function isHandshake(data: unknown): data is KitUiHandshake;
28
+ export declare function isReady(data: unknown): data is KitUiReady;
29
+ export declare function isHello(data: unknown): data is KitUiHello;
30
+ /**
31
+ * CSS custom properties the kit applies to its root (protocol section 4). `brand` (section 9):
32
+ * `kit` (the default) lets a kit with a brand color use it for its primary tokens; `host` keeps
33
+ * the host's.
34
+ */
35
+ export type KitTheme = {
36
+ colorScheme: 'light' | 'dark';
37
+ tokens: Record<string, string>;
38
+ brand?: 'kit' | 'host';
39
+ };
40
+ /** A button the host adds to the kit's editor (protocol section 9). */
41
+ export type KitUiHostButton = {
42
+ /** The host's own name for it; `ui/action` reports it. */
43
+ id: string;
44
+ /** `menu:<path>` (end of that menu), `group:<tab>/<group>` (end of that ribbon group), or `action`. */
45
+ place: string;
46
+ /** The label per locale; `en-US` is the fallback. */
47
+ label: Record<string, string>;
48
+ /** A `@kition/kit-editor` icon name, or a `data:image/…` URL. */
49
+ icon?: string;
50
+ /** As `Cmd+Enter`. */
51
+ shortcut?: string;
52
+ disabled?: boolean;
53
+ pressed?: boolean;
54
+ };
55
+ /**
56
+ * The editor's display modes (section 9): `menus` (tabs open as drop-down menus, no command
57
+ * area), `line` (one row of the selected tab's main commands), `classic` (the full ribbon), and
58
+ * `focus` (no chrome but a small floating bar).
59
+ */
60
+ export type KitDisplayMode = 'menus' | 'line' | 'classic' | 'focus';
61
+ /** What the host hides, disables, and adds, and what the person hid (protocol section 9). */
62
+ export type KitUiConfig = {
63
+ hide?: string[];
64
+ disable?: string[];
65
+ add?: KitUiHostButton[];
66
+ personal?: {
67
+ hide?: string[];
68
+ };
69
+ /** The display modes the person may choose (absent or empty: all) and the one the editor opens in. */
70
+ modes?: {
71
+ allowed?: KitDisplayMode[];
72
+ default?: KitDisplayMode;
73
+ };
74
+ };
75
+ /** One element of a kit's editor, as `ui/elements` lists it. */
76
+ export type KitUiElement = {
77
+ id: string;
78
+ kind: string;
79
+ label: string;
80
+ parent: string | null;
81
+ hidden: boolean;
82
+ disabled: boolean;
83
+ };
84
+ /** `KitDocumentInit.comments`: who comments in this session, and how. */
85
+ export type KitCommentAccess = {
86
+ me: string | null;
87
+ name?: string;
88
+ canComment: boolean;
89
+ othersReadOnly: boolean;
90
+ };
91
+ /**
92
+ * Where in a document (minor version 2.1, `KitLinks 1.0` section 2): a diagnostic target's shape
93
+ * (`objectId`, `path`, `page`, `slide`, `sheet`, `cell`) plus `time`, `heading`, and `blockId`, as
94
+ * the document's kit understands them. A kit that cannot show it ignores it.
95
+ */
96
+ export type KitView = {
97
+ objectId?: string;
98
+ path?: string;
99
+ page?: number;
100
+ slide?: number;
101
+ sheet?: string;
102
+ cell?: string;
103
+ time?: number;
104
+ heading?: string[];
105
+ blockId?: string;
106
+ };
107
+ /** A `view` checked: an object with only the known members, each of its type; `null` otherwise or when empty. */
108
+ export declare function parseKitView(value: unknown): KitView | null;
109
+ export type KitDocumentInit = {
110
+ path: string;
111
+ name: string;
112
+ /** The file as it is now; absent when `create` asks for a new document. */
113
+ bytes?: ArrayBuffer;
114
+ version?: string | null;
115
+ /**
116
+ * The document is read-only for this session (a viewer): the kit refuses edits on every path
117
+ * with `error.data.reason` `read-only` and offers no Save. It is fixed for the session; a host
118
+ * that changes it opens the kit again (a new page).
119
+ */
120
+ readOnly?: boolean;
121
+ /**
122
+ * Who comments and how (minor version 1.6; KitModel rule M23): the person's principal
123
+ * id (`null` when unknown) and display name, whether they may write comments (a commenter's
124
+ * document is `readOnly` for its content yet takes comments), and whether threads others opened
125
+ * are read-only history (the document is not co-edited now).
126
+ */
127
+ comments?: KitCommentAccess;
128
+ create?: {
129
+ width: number;
130
+ height: number;
131
+ };
132
+ /**
133
+ * Lent files (standard E5): a same-origin URL of the workspace root that serves ranged reads,
134
+ * and the document's folder in it, for the engine's synchronous reads of linked files.
135
+ */
136
+ lend?: {
137
+ root: string;
138
+ folder: string;
139
+ };
140
+ /**
141
+ * Where in the document to show first (minor version 2.1, section 2): the host opened it from a
142
+ * link or its own navigation (`host/open`, OP3). A kit that can show it scrolls to it and
143
+ * selects it; otherwise it ignores it.
144
+ */
145
+ view?: KitView;
146
+ /**
147
+ * What the person may take out of the document (minor version 2.6, managed co-editing OT5): a
148
+ * kit hides Download, Export, Print, and Share controls the host withholds. Absent: all allowed.
149
+ * Display permissions, not a security boundary: the host enforces them for bytes it serves.
150
+ */
151
+ permissions?: KitDocumentPermissions;
152
+ /** Text the kit draws over its canvas, faint and repeated (minor version 2.6); absent: none. */
153
+ watermark?: KitWatermark | null;
154
+ };
155
+ /** `document.permissions` (minor version 2.6): `export` covers Print too. */
156
+ export type KitDocumentPermissions = {
157
+ download: boolean;
158
+ export: boolean;
159
+ share: boolean;
160
+ };
161
+ /** `document.watermark` (minor version 2.6): at most `WATERMARK_TEXT_LIMIT` characters, no control characters. */
162
+ export type KitWatermark = {
163
+ text: string;
164
+ };
165
+ export declare const WATERMARK_TEXT_LIMIT = 256;
166
+ /** `document.permissions` as a kit reads it: absent, everything is allowed; present, only the flags that are `true`. */
167
+ export declare function parseDocumentPermissions(value: unknown): KitDocumentPermissions;
168
+ /** `document.watermark` as a kit draws it: its text trimmed, or `null` for none or a malformed one. */
169
+ export declare function parseWatermark(value: unknown): KitWatermark | null;
170
+ export type InitializeParams = {
171
+ protocol: string;
172
+ host: {
173
+ name: string;
174
+ version: string;
175
+ };
176
+ document: KitDocumentInit;
177
+ theme: KitTheme;
178
+ locale: string;
179
+ /** The host's own shortcuts, as `Cmd+N`; the kit forwards them (`host/shortcut`). */
180
+ shortcuts: string[];
181
+ /** Optional host methods this host serves: `agent`, `pick-file`, `replica`, `customize`, `lease`, `presence`, `files`, `files-pick`, `print`, `generate`, `action:<id>`, `open-file`, `open-url`, `links-pick`, `fetch-image`. */
182
+ capabilities: string[];
183
+ /**
184
+ * The capability sets this host serves (Kition platform `docs/platform/index.md` section 3, minor version 1.5), such as
185
+ * `KitModel 1.0` or `KitCollab 1.0`; absent from older hosts.
186
+ */
187
+ capabilitySets?: string[];
188
+ /** The UI configuration (section 9); absent means none. */
189
+ ui?: KitUiConfig;
190
+ };
191
+ export type InitializeResult = {
192
+ kit: {
193
+ id: string;
194
+ version: string;
195
+ };
196
+ capabilities: string[];
197
+ };
198
+ export type DocumentState = {
199
+ dirty: boolean;
200
+ revision: number;
201
+ title: string;
202
+ };
203
+ export type WriteMode = 'save' | 'export' | 'create';
204
+ /**
205
+ * A document's replica as the host stores it (capability `replica`, protocol section 7): the KDM
206
+ * snapshot, the blobs it references, and the stamp of the file it was saved with.
207
+ */
208
+ export type StoredReplica = {
209
+ snapshot: ArrayBuffer;
210
+ blobs: ArrayBuffer;
211
+ fileStamp: string;
212
+ };
213
+ /** Kit AI bridge records (standard A7 to A10), as Kition's runtime defines them. */
214
+ /**
215
+ * `context` (minor version 2.9, capability `context`) is what the step acts on and in, as Kit Process
216
+ * Protocol's `context.set` takes it: the ids it acts on (`on`), its part, its time. The kit runs
217
+ * the step in an editor state of the agent's own, so the person's selection, part and time do not
218
+ * move (section 2).
219
+ */
220
+ export type AiStep = {
221
+ command: string;
222
+ params?: Record<string, unknown>;
223
+ context?: {
224
+ on?: Array<string | number>;
225
+ part?: Record<string, unknown>;
226
+ time?: number;
227
+ };
228
+ };
229
+ export type AiRunResult = {
230
+ completed: Array<{
231
+ command: string;
232
+ changed: boolean;
233
+ result: unknown;
234
+ }>;
235
+ saved: boolean;
236
+ closed?: boolean;
237
+ notRun?: number;
238
+ };
239
+ /**
240
+ * `ai/run`'s params. Without `origin` the steps are the agent's (section 2). (2.7) With `origin:
241
+ * "system"` they are the host's own change on the person's behalf (a host feature such as mail
242
+ * sync writing into the open document): no undo step in any history, recorded under the KDM
243
+ * `system` origin with `originLabel` (`ORIGIN_LABEL`; `host` when absent), as Kit Process Protocol's
244
+ * `commands.execute` runs them. Only the host sends it, never for a model's call, and never with
245
+ * `draft`.
246
+ */
247
+ export type AiRunParams = {
248
+ steps: AiStep[];
249
+ save: boolean;
250
+ draft?: boolean;
251
+ origin?: 'system';
252
+ originLabel?: string;
253
+ };
254
+ /** A host feature's name for a change it makes (`originLabel`, minor version 2.7): 1 to 64 letters, digits, `.`, `_`, `-`. */
255
+ export declare const ORIGIN_LABEL: RegExp;
256
+ /** The label of a host's change that names no feature. */
257
+ export declare const HOST_ORIGIN_LABEL = "host";
258
+ /**
259
+ * `error.data.reason` of an `ai/run` step whose parameters the kit's engine refused (minor
260
+ * version 2.7): `data` is `{ reason, command, step, errors }`, `errors` one `{ path, message,
261
+ * expected? }` for each wrong parameter, as Kit Process Protocol's `invalid_params` lists them.
262
+ */
263
+ export declare const INVALID_PARAMS_REASON = "invalid-params";
264
+ /** Who made a change `document/changed` reports: the person, the agent, or (2.7) the host, with its `originLabel`. */
265
+ export type DocumentChangeBy = {
266
+ by: 'person' | 'agent';
267
+ } | {
268
+ by: 'system';
269
+ originLabel: string;
270
+ };
271
+ /**
272
+ * The object model's requests (capability `model`, section 7a; `KitObjectModel 1.0`). `schema` is
273
+ * the kit's KDM schema as the host knows it (`model/schema.json`): a kit whose engine does not
274
+ * describe its own schema runs the batch with it. A refused batch answers an error whose `data`
275
+ * is `ModelErrorData`.
276
+ */
277
+ /** `draft: true` runs the batch on the agent's draft (capability `draft-model`, section 7d). */
278
+ export type ModelBatchParams = {
279
+ origin?: unknown;
280
+ ops?: Array<Record<string, unknown>>;
281
+ load?: Array<Record<string, unknown>>;
282
+ schema?: object;
283
+ draft?: boolean;
284
+ };
285
+ /** `version` is the kit's replica version after the batch, when it has one. */
286
+ export type ModelBatchResult = {
287
+ refs: Record<string, string>;
288
+ results: unknown[];
289
+ loaded: Array<{
290
+ id: string;
291
+ type: string;
292
+ fields: Record<string, unknown>;
293
+ }>;
294
+ version?: ArrayBuffer | null;
295
+ };
296
+ export type ModelErrorData = {
297
+ code: 'invalid-op' | 'not-found' | 'invalid-value' | 'read-only' | 'command-failed';
298
+ index: number | null;
299
+ message: string;
300
+ };
301
+ /**
302
+ * A lease on one scope of a co-edited document (capability `lease`, section 7b): who holds it,
303
+ * and whether that is this session (`self`).
304
+ */
305
+ export type KitLease = {
306
+ scope: string;
307
+ holder: {
308
+ principalId: string;
309
+ name: string;
310
+ self: boolean;
311
+ };
312
+ };
313
+ /** `error.data.reason` of a refused `host/leaseAcquire`: another session holds the scope (its lease in `data.lease`). */
314
+ export declare const LEASE_HELD_REASON = "held";
315
+ /**
316
+ * Where a person's caret is (capability `presence`, section 7e): a text field of a KDM object, and
317
+ * the offset in it, counted in Unicode scalar values as the object model counts text positions.
318
+ */
319
+ export type KitPresenceCaret = {
320
+ object: string;
321
+ field: string;
322
+ offset: number;
323
+ };
324
+ /**
325
+ * What this session shares with the other people in its document (`presence/set`, section 7e):
326
+ * the KDM ids of the objects it has selected, its caret, and what it looks at (`viewport`, the
327
+ * kit's own shape: a page, a slide, a rectangle). A viewer shares it too: where they look, never
328
+ * an edit.
329
+ */
330
+ export type KitPresence = {
331
+ selection: string[];
332
+ caret?: KitPresenceCaret | null;
333
+ viewport?: Record<string, unknown> | null;
334
+ };
335
+ /** Another person in the document (`presence/peers`, section 7e): who, in which color, and what they share. */
336
+ export type KitPeerPresence = {
337
+ principal: string;
338
+ name: string;
339
+ color: string;
340
+ } & KitPresence;
341
+ /** At most this many selected ids travel in one presence (section 7e); the rest are left out. */
342
+ export declare const PRESENCE_SELECTION_LIMIT = 256;
343
+ /**
344
+ * A presence as the other side sent it, checked (neither side trusts the other's shapes): the
345
+ * selection's string ids (at most `PRESENCE_SELECTION_LIMIT`), a well-formed caret, and an object
346
+ * viewport. Anything else is left out; a value that is no object is no presence (`null`).
347
+ */
348
+ export declare function parsePresence(value: unknown): KitPresence | null;
349
+ /** `presence/peers`' list, checked as `parsePresence` does; peers with no principal or name are left out. */
350
+ export declare function parsePeers(value: unknown): KitPeerPresence[];
351
+ /**
352
+ * A conflict object the kit's repair pass recorded (section 7c, standard 2.0 M22): a merge it
353
+ * could not resolve by itself, kept in the document until someone resolves it.
354
+ */
355
+ export type KitConflict = {
356
+ id: string;
357
+ kind: string;
358
+ summary: string;
359
+ };
360
+ /**
361
+ * The schema versions of the kit's document (section 7f, minor version 1.8; standard 2.0 rule
362
+ * M5a): `reads` is the schema version the kit's replica reads, `newestAuthor` the newest one its
363
+ * changes were written under, which is above `reads` when a newer kit edited the document.
364
+ */
365
+ export type KitSchemaReport = {
366
+ reads: number;
367
+ newestAuthor: number;
368
+ };
369
+ /** A `document/schema` report, checked: both are whole numbers and a newer kit edited the document; else `null`. */
370
+ export declare function parseSchemaReport(value: unknown): KitSchemaReport | null;
371
+ /**
372
+ * An agent's draft of the document (capability `draft`, section 7d; standard 2.0 A12 to A15): a
373
+ * fork of the document's replica the agent edits instead of the live document. `open` while the
374
+ * agent works on it, `ready` once it asks for review; `none` when there is no draft.
375
+ */
376
+ export type DraftState = 'none' | 'open' | 'ready';
377
+ export type DraftInfo = {
378
+ state: DraftState;
379
+ revision: number | null;
380
+ };
381
+ /** One object a draft created, changed (`fields`: the differing ones), or deleted. */
382
+ export type DraftObjectChange = {
383
+ id: string;
384
+ type: string;
385
+ fields: string[];
386
+ };
387
+ /** The object-level comparison of a draft with the live document (standard 2.0 A13). */
388
+ export type DraftSummary = {
389
+ created: DraftObjectChange[];
390
+ changed: DraftObjectChange[];
391
+ deleted: DraftObjectChange[];
392
+ texts: Array<{
393
+ id: string;
394
+ field: string;
395
+ before: string;
396
+ after: string;
397
+ }>;
398
+ };
399
+ /** `draft/compare`: the summary, and both sides rendered by the kit's engine (base64 PNGs; null when the engine cannot render). */
400
+ export type DraftComparison = {
401
+ summary: DraftSummary;
402
+ before: string | null;
403
+ after: string | null;
404
+ };
405
+ /** Who a merge is recorded as: the agent, on behalf of the person who started it. */
406
+ export type DraftOrigin = {
407
+ kind: 'agent';
408
+ principal: string;
409
+ label?: string;
410
+ };
411
+ /** What a diagnostic is about (KHP A21); none set means the whole document. Pages and slides count from 1. */
412
+ export type KitDiagnosticTarget = {
413
+ objectId?: string;
414
+ path?: string;
415
+ page?: number;
416
+ slide?: number;
417
+ sheet?: string;
418
+ cell?: string;
419
+ };
420
+ /** One thing a kit found wrong with a document (KHP A21). `code` is stable (`sheet.formula-error`); `fix` is a command hint, never run on its own. */
421
+ export type KitDiagnostic = {
422
+ code: string;
423
+ severity: 'error' | 'warning' | 'info';
424
+ target: KitDiagnosticTarget;
425
+ message: string;
426
+ fix?: {
427
+ command: string;
428
+ params?: Record<string, unknown>;
429
+ };
430
+ };
431
+ /**
432
+ * KitFiles 1.0 (Kition platform `docs/platform/sets/files.md`; Kit UI protocol section 7g, minor version
433
+ * 1.10): files beyond the open document, reached only through file handles the host grants. A
434
+ * handle is an opaque `fh_…` string bound to one session, one kit, and one principal (FA1, FA5);
435
+ * no path of the host's file system ever reaches the kit (FA-P2, UI-F1).
436
+ */
437
+ export declare const FILE_HANDLE_PREFIX = "fh_";
438
+ /** What a handle allows (FA2): `read` (and list a folder), `create` (a new file, or files in a folder), `write` (replace an existing file). */
439
+ export type KitFileRight = 'read' | 'create' | 'write';
440
+ /**
441
+ * A handle's stat (FA3). `name` is a display name, the last segment only, untrusted text for the
442
+ * kit; `version` is the host's opaque version stamp, `null` for a created file not committed yet.
443
+ */
444
+ export type KitFileStat = {
445
+ handle: string;
446
+ name: string;
447
+ kind: 'file' | 'folder';
448
+ size?: number;
449
+ mime?: string;
450
+ version: string | null;
451
+ rights: KitFileRight[];
452
+ };
453
+ /** `files/pick` (FA6): `accept` lists extensions without the dot; `multiple` applies to `open`, `suggestedName` to `save`. */
454
+ export type KitFilesPickParams = {
455
+ purpose: string;
456
+ mode: 'open' | 'folder' | 'save';
457
+ accept: string[];
458
+ multiple?: boolean;
459
+ suggestedName?: string | null;
460
+ };
461
+ /** `files/create` (FA7): `folder` is a folder handle with right `create`; without it, the host creates beside the document. */
462
+ export type KitFilesCreateParams = {
463
+ suggestedName: string;
464
+ mime?: string;
465
+ folder?: string;
466
+ };
467
+ /** `files/write` (FA9): one staged chunk; `offset` is the number of bytes staged so far; `final` commits; `expected` is required on a `write` handle's final chunk. */
468
+ export type KitFilesWriteParams = {
469
+ handle: string;
470
+ bytes: ArrayBuffer;
471
+ offset: number;
472
+ final?: boolean;
473
+ expected?: string | null;
474
+ };
475
+ /** `files/print` (FA11): a PDF the kit rendered, or a handle with right `read` on a PDF. */
476
+ export type KitFilesPrintParams = {
477
+ bytes: ArrayBuffer;
478
+ mime: 'application/pdf';
479
+ title: string;
480
+ } | {
481
+ handle: string;
482
+ title: string;
483
+ };
484
+ /** The reasons a `files/*` request is refused (`error.data.reason` of a `-32000`; KitFiles 1.0 section 10). */
485
+ export declare const FILE_ERROR_REASONS: readonly ["file-not-granted", "not-allowed", "no-gesture", "already-committed", "conflict", "unsaved-edits", "quota", "unsupported", "io-error"];
486
+ export type KitFileErrorReason = (typeof FILE_ERROR_REASONS)[number];
487
+ /** The reason a `files/*` request was refused, from the error the host answered; `null` for any other failure. */
488
+ export declare function fileErrorReason(error: unknown): KitFileErrorReason | null;
489
+ /**
490
+ * Host generation (capability `generate`, protocol section 7j, minor version 2.2; a Kition platform
491
+ * request, not KHP): the kit builds the prompt from what its document holds and asks the host for
492
+ * the model call; the host runs the person's model settings and never hands the kit a key (UI-G2).
493
+ */
494
+ export type KitGeneratePart = {
495
+ type: 'text';
496
+ text: string;
497
+ } | {
498
+ type: 'image';
499
+ mime: string;
500
+ bytes: ArrayBuffer;
501
+ } | {
502
+ type: 'image';
503
+ url: string;
504
+ };
505
+ export type KitGenerateMessage = {
506
+ role: 'system' | 'user';
507
+ parts: KitGeneratePart[];
508
+ };
509
+ export type KitGenerateParams = {
510
+ /** What the kit generates for (section 7j, minor version 2.4): a defined purpose or the kit's own (`isGeneratePurpose`). */
511
+ purpose: KitGeneratePurpose;
512
+ output: 'text' | 'image';
513
+ /** The document's preference, a hint only: the host answers the model it used. */
514
+ model?: string;
515
+ messages: KitGenerateMessage[];
516
+ /** `size` is `WIDTHxHEIGHT`, for images; the host may ignore any of them. */
517
+ options?: {
518
+ maxTokens?: number;
519
+ temperature?: number;
520
+ size?: string;
521
+ };
522
+ };
523
+ export type KitGenerateResult = {
524
+ text?: string;
525
+ image?: {
526
+ mime: string;
527
+ bytes: ArrayBuffer;
528
+ };
529
+ model?: string;
530
+ usage?: {
531
+ inputTokens?: number;
532
+ outputTokens?: number;
533
+ };
534
+ };
535
+ /**
536
+ * The purposes section 7j defines (minor version 2.4), which every host that lists `generate`
537
+ * serves: `ai-field`, an AI field's cell; `rewrite`, text the person selected rewritten as they
538
+ * asked (improve, shorten, expand, change the tone, translate), a suggestion the person accepts
539
+ * or discards before the kit writes it.
540
+ */
541
+ export declare const GENERATE_PURPOSES: readonly ["ai-field", "rewrite"];
542
+ export type KitDefinedGeneratePurpose = (typeof GENERATE_PURPOSES)[number];
543
+ /** A defined purpose, or a kit's own: `<kit>.<name>` (`note.outline` for `kit.note`), which a host MAY refuse. */
544
+ export type KitGeneratePurpose = KitDefinedGeneratePurpose | `${string}.${string}`;
545
+ /**
546
+ * Whether a kit may send `purpose` (section 7j): a defined purpose, or one of its own,
547
+ * `<kit>.<name>`, where `<kit>` is its id without `kit.` (`kitId`; unknown: only defined
548
+ * purposes) and `<name>` lowercase letters, digits, and hyphens.
549
+ */
550
+ export declare function isGeneratePurpose(purpose: unknown, kitId?: string | null): purpose is KitGeneratePurpose;
551
+ /** The reasons a `host/generate` is refused (`error.data.reason` of a `-32000`). */
552
+ export declare const GENERATE_ERROR_REASONS: readonly ["unavailable", "not-allowed", "quota", "refused", "too-large", "timeout", "failed"];
553
+ export type KitGenerateErrorReason = (typeof GENERATE_ERROR_REASONS)[number];
554
+ /**
555
+ * Host actions (capability `action:<id>`, section 7j): a host feature the kit offers a control
556
+ * for, from a person's gesture only. Defined ids: `workflow.run` (`{ workflowId, tableId, recordId }`)
557
+ * and `design.fromRecord` (`{ title, fields, record? }`); other ids are the host's.
558
+ */
559
+ export declare const HOST_ACTION_CAPABILITY_PREFIX = "action:";
560
+ export type KitActionParams = {
561
+ id: string;
562
+ params: Record<string, unknown>;
563
+ };
564
+ export type KitActionResult = {
565
+ done: boolean;
566
+ message?: string;
567
+ };
568
+ /** The reasons a `host/action` is refused (`error.data.reason` of a `-32000`). */
569
+ export declare const ACTION_ERROR_REASONS: readonly ["not-allowed", "no-gesture", "not-found", "failed"];
570
+ export type KitActionErrorReason = (typeof ACTION_ERROR_REASONS)[number];
571
+ /**
572
+ * Host services (minor version 2.6, section 7k; managed co-editing D4): what a kit asks its host
573
+ * for instead of doing it itself, so every kit behaves as a native part of the host. A host lists
574
+ * each service it serves as the capability `service:<id>`.
575
+ */
576
+ export declare const HOST_SERVICE_CAPABILITY_PREFIX = "service:";
577
+ export declare const HOST_SERVICES: readonly ["file.pick", "image.insert", "people.mention", "people.notify", "share.open", "file.rename", "file.saveAs", "access.request", "editor.close", "comment.create"];
578
+ export type KitHostService = (typeof HOST_SERVICES)[number];
579
+ /** A person the host lets this person see (`people.mention`). */
580
+ export type KitPerson = {
581
+ id: string;
582
+ name: string;
583
+ avatar?: string;
584
+ };
585
+ /** Each service's params and result (section 7k). */
586
+ export type KitHostServices = {
587
+ 'file.pick': [KitFilesPickParams, {
588
+ files: KitFileStat[];
589
+ }];
590
+ 'image.insert': [{
591
+ accept?: string[];
592
+ }, {
593
+ image: {
594
+ name: string;
595
+ mime: string;
596
+ bytes: ArrayBuffer;
597
+ } | null;
598
+ }];
599
+ 'people.mention': [{
600
+ query: string;
601
+ limit?: number;
602
+ }, {
603
+ people: KitPerson[];
604
+ }];
605
+ 'people.notify': [{
606
+ people: string[];
607
+ message: string;
608
+ anchor?: KitCommentAnchor;
609
+ }, {
610
+ notified: string[];
611
+ }];
612
+ 'share.open': [Record<string, never>, {
613
+ done: boolean;
614
+ }];
615
+ 'file.rename': [{
616
+ name?: string;
617
+ }, {
618
+ name: string | null;
619
+ }];
620
+ 'file.saveAs': [{
621
+ name?: string;
622
+ format?: string;
623
+ bytes: ArrayBuffer;
624
+ }, {
625
+ path: string | null;
626
+ }];
627
+ 'access.request': [{
628
+ perm: 'edit' | 'comment';
629
+ }, {
630
+ requested: boolean;
631
+ }];
632
+ 'editor.close': [Record<string, never>, {
633
+ closed: boolean;
634
+ }];
635
+ 'comment.create': [{
636
+ anchor: KitCommentAnchor;
637
+ text?: string;
638
+ }, {
639
+ thread: string | null;
640
+ }];
641
+ };
642
+ export type KitServiceParams<S extends KitHostService = KitHostService> = {
643
+ [K in S]: {
644
+ service: K;
645
+ params: KitHostServices[K][0];
646
+ };
647
+ }[S];
648
+ export type KitServiceResult<S extends KitHostService = KitHostService> = KitHostServices[S][1];
649
+ /** The reasons a `host/service` is refused (`error.data.reason` of a `-32000`, UI-V1). */
650
+ export declare const SERVICE_ERROR_REASONS: readonly ["not-allowed", "no-gesture", "cancelled", "not-found", "failed"];
651
+ export type KitServiceErrorReason = (typeof SERVICE_ERROR_REASONS)[number];
652
+ /**
653
+ * Which services a document's permissions allow (UI-V4): comments, mentions and notices need
654
+ * comment rights, inserting and renaming need edit rights, save-as needs download or export,
655
+ * sharing needs share; requesting access and closing need nothing.
656
+ */
657
+ export declare function serviceAllowed(service: KitHostService, document: {
658
+ readOnly?: boolean;
659
+ comments?: {
660
+ canComment?: boolean;
661
+ } | null;
662
+ permissions?: unknown;
663
+ }): boolean;
664
+ /** Limits a host checks a service's params against (UI-V3). */
665
+ export declare const SERVICE_MESSAGE_LIMIT = 2000;
666
+ export declare const SERVICE_PEOPLE_LIMIT = 256;
667
+ /**
668
+ * A comment anchor (section 7k, claim O23): where in the document a host-stored comment points.
669
+ * `ids` are the selection's object ids (`KitPointer 1.0` PT7), `range` a text range in the first
670
+ * id's text, `quote` the text it quoted, `page` the page, `label` what the host's comment list shows.
671
+ */
672
+ export type KitCommentAnchor = {
673
+ ids: string[];
674
+ range?: {
675
+ start: number;
676
+ end: number;
677
+ };
678
+ quote?: string;
679
+ page?: number;
680
+ label?: string;
681
+ };
682
+ /** A host's thread as a kit marks it (`comments/show`). */
683
+ export type KitShownThread = {
684
+ id: string;
685
+ anchor: KitCommentAnchor;
686
+ resolved: boolean;
687
+ count: number;
688
+ };
689
+ export declare const ANCHOR_IDS_LIMIT = 256;
690
+ export declare const ANCHOR_TEXT_LIMIT = 500;
691
+ /**
692
+ * `value` as a comment anchor both sides trust (UI-V3): 1 to 256 string ids, a well-formed range,
693
+ * a quote and label of at most 500 characters, a page at least 0; anything malformed is `null`.
694
+ */
695
+ export declare function parseCommentAnchor(value: unknown): KitCommentAnchor | null;
696
+ /**
697
+ * Checks a `host/service` request against UI-V3: a defined service and its params' shapes and
698
+ * limits. Answers the params as checked, or `null`.
699
+ */
700
+ export declare function parseServiceParams(value: unknown): KitServiceParams | null;
701
+ /**
702
+ * Opening (capabilities `open-file` and `open-url`, section 7i, minor version 2.1; KitLinks 1.0
703
+ * section 5): the kit asks the host to open a workspace file or a web address, only from a
704
+ * person's gesture (OP1, OP6). `linkRef` names the target as the document stores it: a path
705
+ * relative to the document's folder, a bare name the host resolves (LR4), or a replica id.
706
+ */
707
+ export type KitLinkRef = {
708
+ path?: string;
709
+ name?: string;
710
+ docId?: string;
711
+ };
712
+ /** `host/open`: `view` is where to show the target (OP3); `create` makes a missing target first (OP4), with `kit` picking the kit when several create its extension. */
713
+ export type KitOpenParams = {
714
+ link: KitLinkRef;
715
+ view?: KitView;
716
+ placement?: 'tab' | 'beside';
717
+ create?: {
718
+ kit?: string;
719
+ };
720
+ };
721
+ /** `opened` is `false` when the person cancelled a confirmation (OP8). */
722
+ export type KitOpenResult = {
723
+ opened: boolean;
724
+ };
725
+ /** The reasons a `host/open` or `host/openUrl` is refused (`error.data.reason` of a `-32000`; KitLinks 1.0 section 5). */
726
+ export declare const OPEN_ERROR_REASONS: readonly ["not-found", "no-gesture", "no-kit", "not-allowed"];
727
+ export type KitOpenErrorReason = (typeof OPEN_ERROR_REASONS)[number];
728
+ /** The only schemes a host opens (OP7); every other is refused as `not-allowed`. */
729
+ export declare const OPEN_URL_SCHEMES: readonly ["https:", "http:", "mailto:"];
730
+ /** Whether `url` is an absolute address with a scheme a host may open (OP7). */
731
+ export declare function isOpenableUrl(url: unknown): url is string;
732
+ /** A `linkRef` checked: only non-empty string members, at least one of them; `null` otherwise. */
733
+ export declare function parseLinkRef(value: unknown): KitLinkRef | null;
734
+ /** `host/open`'s params checked: a well-formed link, and only the known members of each optional one; `null` without a link. */
735
+ export declare function parseOpenParams(value: unknown): KitOpenParams | null;
736
+ /**
737
+ * Picking a file to link (capability `links-pick`, section 7i, minor version 2.5; rules UI-N2 to
738
+ * UI-N4): the person chooses existing workspace files, which stay where they are. `accept` lists
739
+ * extensions without the dot (at least one); `multiple` lets the person choose several.
740
+ */
741
+ export type KitLinksPickParams = {
742
+ purpose: string;
743
+ accept: string[];
744
+ multiple?: boolean;
745
+ };
746
+ /** A file the person chose to link: `path` relative to the document's folder (HC-P2), `name` its last segment, `version` its stamp. */
747
+ export type KitPickedLink = {
748
+ path: string;
749
+ name: string;
750
+ version: string | null;
751
+ };
752
+ /** `links/pick`'s params checked: a purpose, extensions without the dot (lowercased, at least one), and `multiple`; `null` otherwise. */
753
+ export declare function parseLinksPickParams(value: unknown): KitLinksPickParams | null;
754
+ /**
755
+ * Workspace path `to` as the document at `documentPath` links it (HC-P2): relative to the
756
+ * document's folder, with `../` where `to` is elsewhere (`../libraries/Icons.kdesign`).
757
+ */
758
+ export declare function linkPathFrom(documentPath: string, to: string): string;
759
+ /** The reason a `host/open` or `host/openUrl` was refused, from the error the host answered; `null` for any other failure. */
760
+ export declare function openErrorReason(error: unknown): KitOpenErrorReason | null;
761
+ /**
762
+ * Fetching a picture (capability `fetch-image`, section 7l, minor version 2.8): a picture the
763
+ * person pasted or dropped by its web address (an `<img>` in pasted HTML). The kit loads nothing
764
+ * from the network (UI-K1), so the host downloads it, from public addresses only, and answers its
765
+ * bytes; the kit keeps them as it keeps a pasted file. `mime` is one of `FETCH_IMAGE_TYPES`.
766
+ */
767
+ export type KitFetchImageResult = {
768
+ bytes: ArrayBuffer;
769
+ mime: KitFetchImageType;
770
+ };
771
+ /** The pictures a host answers `host/fetchImage` with; any other response is refused as `unsupported`. */
772
+ export declare const FETCH_IMAGE_TYPES: readonly ["image/png", "image/jpeg", "image/gif", "image/webp", "image/svg+xml", "image/avif"];
773
+ export type KitFetchImageType = (typeof FETCH_IMAGE_TYPES)[number];
774
+ /**
775
+ * The reasons a `host/fetchImage` is refused (`error.data.reason` of a `-32000`): `not-allowed`
776
+ * (not an `https:` or `http:` address, or one on the person's computer or local network),
777
+ * `unsupported` (not a picture), `quota` (larger than the host keeps), `io-error` (the download
778
+ * failed), `read-only` (the document is read-only).
779
+ */
780
+ export declare const FETCH_IMAGE_ERROR_REASONS: readonly ["not-allowed", "unsupported", "quota", "io-error", "read-only"];
781
+ export type KitFetchImageErrorReason = (typeof FETCH_IMAGE_ERROR_REASONS)[number];
782
+ /** Whether `url` is an absolute `https:` or `http:` address, the only ones a host fetches. */
783
+ export declare function isFetchableUrl(url: unknown): url is string;
784
+ /** The reason a `host/fetchImage` was refused, from the error the host answered; `null` for any other failure. */
785
+ export declare function fetchImageErrorReason(error: unknown): KitFetchImageErrorReason | null;
786
+ /** The reason a `host/generate` or `host/action` was refused, from the error the host answered; `null` for any other failure. */
787
+ export declare function hostRequestErrorReason(error: unknown): KitGenerateErrorReason | KitActionErrorReason | null;
788
+ /** Requests the host sends, with their params and results. */
789
+ export type HostToKit = {
790
+ 'ui/initialize': [InitializeParams, InitializeResult];
791
+ 'document/state': [Record<string, never>, DocumentState];
792
+ 'document/save': [Record<string, never>, {
793
+ saved: boolean;
794
+ version: string | null;
795
+ }];
796
+ /** The engine's diagnostics on the document (capability `check`, minor version 1.9), errors first; `draft: true` checks the agent's draft. */
797
+ 'document/check': [{
798
+ draft?: boolean;
799
+ }, {
800
+ diagnostics: KitDiagnostic[];
801
+ }];
802
+ /** `draft: true` (capability `draft`) inspects, runs on, and previews the agent's draft instead of the live document; `ai/run` opens one if there is none. */
803
+ 'ai/inspect': [{
804
+ draft?: boolean;
805
+ context?: AiStep['context'];
806
+ part?: number;
807
+ }, Record<string, unknown>];
808
+ 'ai/commands': [{
809
+ query: string;
810
+ }, Array<Record<string, unknown>>];
811
+ 'ai/run': [AiRunParams, AiRunResult];
812
+ /** (2.9, capability `changes`) The replica's version, base64, as Kit Process Protocol's `model.version`. */
813
+ 'ai/version': [Record<string, never>, {
814
+ version: string;
815
+ }];
816
+ /** Read-only kit callbacks, in the agent's call context (capability `premises`). */
817
+ 'ai/premise': [{
818
+ method: string;
819
+ params: Record<string, unknown>;
820
+ }, unknown];
821
+ /**
822
+ * (2.9, capability `changes`) What changed since the version `since`, as Kit Process Protocol's
823
+ * `model.changes`: the change set and the version now, or `changes: null` and why. `schema` is
824
+ * the kit's, as for `model/describe`.
825
+ */
826
+ 'ai/changes': [{
827
+ since: string;
828
+ schema?: object;
829
+ }, {
830
+ changes: Record<string, unknown> | null;
831
+ unavailable?: string;
832
+ version: string;
833
+ }];
834
+ 'ai/preview': [{
835
+ maxSize: number;
836
+ draft?: boolean;
837
+ }, {
838
+ png: string;
839
+ }];
840
+ /** The draft (capability `draft`, section 7d). */
841
+ 'draft/state': [Record<string, never>, DraftInfo];
842
+ /** The agent asks for review; the agent may call it (through its host). */
843
+ 'draft/ready': [Record<string, never>, DraftInfo];
844
+ /** Sends a draft back to the agent; the agent may call it. */
845
+ 'draft/reopen': [Record<string, never>, DraftInfo];
846
+ 'draft/compare': [{
847
+ maxSize?: number;
848
+ schema?: object;
849
+ }, DraftComparison];
850
+ /** The person's explicit approval only, never a model's: takes the draft into the document as one undo step, and closes it. */
851
+ 'draft/merge': [{
852
+ origin: DraftOrigin;
853
+ schema?: object;
854
+ }, {
855
+ merged: boolean;
856
+ summary: DraftSummary;
857
+ }];
858
+ /** The person's explicit approval only: drops the draft; the document is untouched. */
859
+ 'draft/discard': [Record<string, never>, DraftInfo];
860
+ /** The editor's elements and their state (section 9). */
861
+ 'ui/elements': [Record<string, never>, KitUiElement[]];
862
+ 'replica/version': [Record<string, never>, {
863
+ version: ArrayBuffer;
864
+ }];
865
+ 'replica/export': [{
866
+ since: ArrayBuffer;
867
+ }, {
868
+ changes: ArrayBuffer;
869
+ blobs: ArrayBuffer;
870
+ }];
871
+ /** `damage` is what went stale on screen, as the kit's engine reports it. */
872
+ 'replica/import': [{
873
+ changes: ArrayBuffer;
874
+ blobs: ArrayBuffer;
875
+ }, {
876
+ damage: unknown;
877
+ }];
878
+ /** The replica's own id, when the kit's engine has one (minor version 1.3); `null` otherwise. */
879
+ 'replica/info': [Record<string, never>, {
880
+ docId: string | null;
881
+ }];
882
+ 'model/describe': [{
883
+ schema?: object;
884
+ }, Record<string, unknown>];
885
+ 'model/batch': [ModelBatchParams, ModelBatchResult];
886
+ /** Whether the kit finds each anchor in the document now (minor version 2.6, capability `comment-anchors`, section 7k). */
887
+ 'comments/locate': [{
888
+ anchors: KitCommentAnchor[];
889
+ }, {
890
+ found: boolean[];
891
+ }];
892
+ };
893
+ /** Notifications the host sends. */
894
+ export type HostNotifications = {
895
+ 'document/fileChanged': {
896
+ version: string;
897
+ };
898
+ /**
899
+ * The file is now `version`, and this session's document already holds what it holds (minor
900
+ * version 2.6): another session of a co-edited room saved a state this replica has. The kit takes
901
+ * `version` as the one it last read or wrote, keeps its unsaved mark, and raises no conflict.
902
+ */
903
+ 'document/held': {
904
+ version: string;
905
+ };
906
+ 'ui/theme': {
907
+ theme: KitTheme;
908
+ };
909
+ 'ui/locale': {
910
+ locale: string;
911
+ };
912
+ 'ui/focus': Record<string, never>;
913
+ /** Replaces the UI configuration (section 9). */
914
+ 'ui/configure': {
915
+ ui: KitUiConfig;
916
+ };
917
+ /** The document's leases changed (capability `lease`, section 7b): the whole list. */
918
+ 'lease/changed': {
919
+ leases: KitLease[];
920
+ };
921
+ /** The other people in the document and what they share changed (capability `presence`, section 7e): the whole list. */
922
+ 'presence/peers': {
923
+ peers: KitPeerPresence[];
924
+ };
925
+ /** The host revoked these handles, or they expired (KitFiles FA4); later calls with them fail `file-not-granted`. */
926
+ 'files/revoked': {
927
+ handles: string[];
928
+ };
929
+ /** Shows `view` in the open document (minor version 2.1, section 7i; OP3), as `document.view` does for a new editor. */
930
+ 'document/reveal': {
931
+ view: KitView;
932
+ };
933
+ /** The host's comment threads the kit marks (minor version 2.6, capability `comment-anchors`, section 7k): the whole list. */
934
+ 'comments/show': {
935
+ threads: KitShownThread[];
936
+ };
937
+ };
938
+ /** Requests the kit sends. */
939
+ export type KitToHost = {
940
+ 'host/read': [{
941
+ path: string;
942
+ offset?: number;
943
+ length?: number;
944
+ }, {
945
+ bytes: ArrayBuffer;
946
+ version: string;
947
+ size: number;
948
+ }];
949
+ 'host/stamp': [{
950
+ path: string;
951
+ }, {
952
+ version: string | null;
953
+ }];
954
+ 'host/write': [{
955
+ path: string;
956
+ bytes: ArrayBuffer;
957
+ mode: WriteMode;
958
+ expected?: string | null;
959
+ }, {
960
+ path: string;
961
+ version: string;
962
+ }];
963
+ 'host/pick': [{
964
+ purpose: string;
965
+ accept: string[];
966
+ }, {
967
+ path: string | null;
968
+ }];
969
+ 'host/openAgent': [{
970
+ prompt?: string;
971
+ }, Record<string, never>];
972
+ 'host/replicaRead': [{
973
+ path: string;
974
+ }, StoredReplica | null];
975
+ 'host/replicaWrite': [{
976
+ path: string;
977
+ } & StoredReplica, Record<string, never>];
978
+ /** Keeps what the person hid (capability `customize`, section 9). */
979
+ 'host/customize': [{
980
+ personal: {
981
+ hide: string[];
982
+ };
983
+ }, Record<string, never>];
984
+ /**
985
+ * Takes (or renews) the lease on `scope` and keeps it until `host/leaseRelease` or the kit
986
+ * closes (capability `lease`, section 7b). `lease` is `null` when there is nobody to coordinate
987
+ * with (the document is not co-edited, or the host is offline): the kit goes ahead.
988
+ */
989
+ 'host/leaseAcquire': [{
990
+ scope: string;
991
+ ttl?: number;
992
+ }, {
993
+ lease: KitLease | null;
994
+ }];
995
+ 'host/leaseRelease': [{
996
+ scope: string;
997
+ }, Record<string, never>];
998
+ /** The document's leases now (capability `lease`). */
999
+ 'host/leases': [Record<string, never>, {
1000
+ leases: KitLease[];
1001
+ }];
1002
+ /** Shows the host's picker (capability `files-pick`, section 7g); only from a person's gesture. Empty when the person cancels. */
1003
+ 'files/pick': [KitFilesPickParams, {
1004
+ files: KitFileStat[];
1005
+ }];
1006
+ /** A new file handle with right `create` (capability `files`): an unused name, never an existing file (FA7). */
1007
+ 'files/create': [KitFilesCreateParams, KitFileStat];
1008
+ 'files/stat': [{
1009
+ handle: string;
1010
+ }, KitFileStat];
1011
+ /** At most `length` bytes from `offset`; possibly fewer. `size` is the whole file's size. */
1012
+ 'files/read': [{
1013
+ handle: string;
1014
+ offset?: number;
1015
+ length?: number;
1016
+ }, {
1017
+ bytes: ArrayBuffer;
1018
+ version: string;
1019
+ size: number;
1020
+ }];
1021
+ /** A folder handle's entries that match the grant's `accept`, not recursively, each with right `read`. */
1022
+ 'files/list': [{
1023
+ handle: string;
1024
+ }, {
1025
+ files: KitFileStat[];
1026
+ }];
1027
+ /** One staged chunk; `{ version }` once `final` commits it (FA9). */
1028
+ 'files/write': [KitFilesWriteParams, {
1029
+ version?: string;
1030
+ }];
1031
+ /** Drops handles; never an error, even for unknown or expired ones. */
1032
+ 'files/release': [{
1033
+ handles: string[];
1034
+ }, Record<string, never>];
1035
+ /** Shows the system's print dialog (capability `print`); only from a person's gesture. */
1036
+ 'files/print': [KitFilesPrintParams, {
1037
+ printed: boolean;
1038
+ }];
1039
+ /** A model call the host runs for the kit (capability `generate`, section 7j). Image bytes are transferred. */
1040
+ 'host/generate': [KitGenerateParams, KitGenerateResult];
1041
+ /** Runs one of the host's actions (capability `action:<id>`, section 7j); only from a person's gesture. */
1042
+ 'host/action': [KitActionParams, KitActionResult];
1043
+ /** Opens a workspace file in the host (capability `open-file`, section 7i); only from a person's gesture. */
1044
+ 'host/open': [KitOpenParams, KitOpenResult];
1045
+ /** Opens a web address in the system's browser or mail client (capability `open-url`, section 7i); only from a person's gesture. */
1046
+ 'host/openUrl': [{
1047
+ url: string;
1048
+ }, KitOpenResult];
1049
+ /** Asks the person for existing workspace files to link, never copied (capability `links-pick`, section 7i); only from a person's gesture. Empty when the person cancels. */
1050
+ 'links/pick': [KitLinksPickParams, {
1051
+ links: KitPickedLink[];
1052
+ }];
1053
+ /** Asks the host for one of its services (capability `service:<id>`, section 7k); only from a person's gesture. */
1054
+ 'host/service': [KitServiceParams, KitServiceResult];
1055
+ /** Downloads a picture the person pasted or dropped by its web address (capability `fetch-image`, section 7l). */
1056
+ 'host/fetchImage': [{
1057
+ url: string;
1058
+ }, KitFetchImageResult];
1059
+ };
1060
+ /** Notifications the kit sends. */
1061
+ export type KitNotifications = {
1062
+ 'document/changed': DocumentState & DocumentChangeBy;
1063
+ 'host/notify': {
1064
+ level: 'info' | 'success' | 'warning' | 'error';
1065
+ title: string;
1066
+ description?: string;
1067
+ };
1068
+ 'host/shortcut': {
1069
+ key: string;
1070
+ code: string;
1071
+ meta: boolean;
1072
+ ctrl: boolean;
1073
+ shift: boolean;
1074
+ alt: boolean;
1075
+ };
1076
+ 'replica/changed': {
1077
+ version: ArrayBuffer;
1078
+ };
1079
+ /** A host button was pressed (section 9). */
1080
+ 'ui/action': {
1081
+ id: string;
1082
+ document: {
1083
+ path: string;
1084
+ dirty: boolean;
1085
+ revision: number;
1086
+ };
1087
+ };
1088
+ /** The document's unresolved conflict objects changed (section 7c): the whole list. */
1089
+ 'document/conflicts': {
1090
+ conflicts: KitConflict[];
1091
+ };
1092
+ /** A newer kit edited the document (section 7f): the host shows a notice that never blocks. */
1093
+ 'document/schema': KitSchemaReport;
1094
+ /** The agent's draft opened, changed, became ready or open again, or closed (capability `draft`). */
1095
+ 'draft/changed': DraftInfo;
1096
+ /** What this session shares with the other people in the document changed (capability `presence`, section 7e). */
1097
+ 'presence/set': KitPresence;
1098
+ /** The person clicked a host thread's marker (capability `comment-anchors`, section 7k): the host opens the thread. */
1099
+ 'comments/activated': {
1100
+ id: string;
1101
+ };
1102
+ };
1103
+ /** A failed request: the JSON-RPC error the other side answered. */
1104
+ export declare class KitRpcError extends Error {
1105
+ readonly code: number;
1106
+ readonly data?: unknown | undefined;
1107
+ constructor(code: number, message: string, data?: unknown | undefined);
1108
+ }
1109
+ /**
1110
+ * One side of the protocol on a MessagePort. `Out` and `In` are the request maps this side sends
1111
+ * and answers; `OutN` and `InN` the notifications.
1112
+ */
1113
+ export declare class KitPeer<Out extends Record<string, [unknown, unknown]>, In extends Record<string, [unknown, unknown]>, OutN extends Record<string, unknown>, InN extends Record<string, unknown>> {
1114
+ private readonly port;
1115
+ private readonly prefix;
1116
+ private next;
1117
+ private pending;
1118
+ private handlers;
1119
+ private listeners;
1120
+ private closed;
1121
+ constructor(port: MessagePort, prefix: 'h' | 'k');
1122
+ /** Answers requests for `method`; a thrown error becomes a JSON-RPC error. */
1123
+ handle<M extends keyof In & string>(method: M, handler: (params: In[M][0]) => In[M][1] | Promise<In[M][1]>): void;
1124
+ on<M extends keyof InN & string>(method: M, listener: (params: InN[M]) => void): () => boolean;
1125
+ /** `transfer` hands the params' ArrayBuffers over instead of copying them (the sender loses them). */
1126
+ request<M extends keyof Out & string>(method: M, params: Out[M][0], options?: {
1127
+ transfer?: boolean;
1128
+ }): Promise<Out[M][1]>;
1129
+ notify<M extends keyof OutN & string>(method: M, params: OutN[M]): void;
1130
+ close(): void;
1131
+ private post;
1132
+ private receive;
1133
+ }
1134
+ /** The host's end: sends host-to-kit requests, answers the kit's. */
1135
+ export type HostPeer = KitPeer<HostToKit, KitToHost, HostNotifications, KitNotifications>;
1136
+ /** The kit's end. */
1137
+ export type KitSidePeer = KitPeer<KitToHost, HostToKit, KitNotifications, HostNotifications>;
1138
+ /** `Cmd+N` and the like, against a key event: `Cmd` is Meta on macOS and Control elsewhere. */
1139
+ export declare function matchesShortcut(shortcut: string, event: {
1140
+ key: string;
1141
+ metaKey: boolean;
1142
+ ctrlKey: boolean;
1143
+ shiftKey: boolean;
1144
+ altKey: boolean;
1145
+ }, mac: boolean): boolean;