@vscode/web-editors 0.0.2-15 → 0.0.2-151

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.
package/dist/index.d.ts CHANGED
@@ -2,6 +2,7 @@
2
2
  * Copyright (c) Microsoft Corporation. All rights reserved.
3
3
  * Licensed under the MIT License. See License.txt in the project root for license information.
4
4
  *--------------------------------------------------------------------------------------------*/
5
+ import { a as IDisposable, i as Event, n as DocumentTextEdit, r as SyncedTextDocument, t as DocumentTextChange } from "./chunks/syncedTextDocument-BIWK0LCP.js";
5
6
  import { HubRpcConnection, InterfaceClient, InterfaceDefinition, MemberMap } from "@vscode/hubrpc";
6
7
  import { MessageEndpoint, MessageLikeEvent, WindowMessageTransport } from "@vscode/hubrpc/web";
7
8
  import { HubAccessDuration, HubAccessRequest, HubAccessResult } from "@vscode/hubrpc/hub/common";
@@ -2140,14 +2141,25 @@ interface ZodReadonly<T extends SomeType = $ZodType> extends _ZodType<$ZodReadon
2140
2141
  declare const ZodReadonly: $constructor<ZodReadonly>;
2141
2142
  //#endregion
2142
2143
  //#region src/protocol.d.ts
2144
+ /**
2145
+ * The concurrency control both sides use when they announce it: concurrent
2146
+ * edits are transformed against each other instead of one side's being
2147
+ * dropped. See `OtPeer`.
2148
+ */
2149
+ declare const OT_EDIT_TRANSFORM = "ot/1";
2143
2150
  declare const zEditorCapabilities: ZodObject<{
2144
2151
  supportsContentEdits: ZodOptional<ZodBoolean>;
2145
2152
  supportsOptions: ZodOptional<ZodBoolean>;
2153
+ supportsPresentation: ZodOptional<ZodBoolean>;
2154
+ editTransforms: ZodOptional<ZodArray<ZodString>>;
2146
2155
  }, $strip>;
2147
2156
  declare const zHostCapabilities: ZodObject<{
2148
2157
  supportsContentEdits: ZodOptional<ZodBoolean>;
2149
2158
  supportsOptions: ZodOptional<ZodBoolean>;
2150
2159
  supportsForceUpdate: ZodOptional<ZodBoolean>;
2160
+ supportsHostTransport: ZodOptional<ZodBoolean>;
2161
+ supportsPresentation: ZodOptional<ZodBoolean>;
2162
+ editTransform: ZodOptional<ZodString>;
2151
2163
  }, $strip>;
2152
2164
  declare const zTextEdit: ZodObject<{
2153
2165
  offset: ZodNumber;
@@ -2174,15 +2186,55 @@ declare const zWebEditorUpdate: ZodObject<{
2174
2186
  serverRevision: ZodOptional<ZodNumber>;
2175
2187
  acknowledgedClientRevision: ZodOptional<ZodNumber>;
2176
2188
  force: ZodOptional<ZodBoolean>;
2189
+ editTransform: ZodOptional<ZodString>;
2190
+ }, $strip>;
2191
+ /** How an embedding host currently presents the editor. */
2192
+ declare const zPresentationMode: ZodEnum<{
2193
+ inline: "inline";
2194
+ "full-width": "full-width";
2195
+ "full-view": "full-view";
2196
+ }>;
2197
+ /**
2198
+ * Presentation controls the editor asks its embedding host for. The host's own
2199
+ * configuration takes precedence over these preferences.
2200
+ */
2201
+ declare const zPresentationPreferences: ZodObject<{
2202
+ resizable: ZodOptional<ZodBoolean>;
2203
+ fullWidth: ZodOptional<ZodBoolean>;
2204
+ fullView: ZodOptional<ZodBoolean>;
2205
+ minHeight: ZodOptional<ZodNumber>;
2206
+ maxAutomaticHeight: ZodOptional<ZodNumber>;
2177
2207
  }, $strip>;
2178
2208
  type ContentEdit = output<typeof zContentEdit>;
2179
2209
  type TextEdit = output<typeof zTextEdit>;
2180
2210
  type EditorCapabilities = output<typeof zEditorCapabilities>;
2181
2211
  type HostCapabilities = output<typeof zHostCapabilities>;
2182
2212
  type WebEditorUpdate = output<typeof zWebEditorUpdate>;
2183
- type ContentType = "text" | "json";
2213
+ type PresentationMode = output<typeof zPresentationMode>;
2214
+ type PresentationPreferences = output<typeof zPresentationPreferences>;
2215
+ declare const zContentType: ZodEnum<{
2216
+ text: "text";
2217
+ json: "json";
2218
+ }>;
2219
+ type ContentType = output<typeof zContentType>;
2220
+ /**
2221
+ * Identifies a state of the content that the host and the editor share: the
2222
+ * host's and the editor's edits integrated into it. Send it along with
2223
+ * offsets into the content, so that the other side can map them into its
2224
+ * current content (`mapOffset` on `WebEditorHost` and `WebEditorClient`).
2225
+ */
2226
+ interface ContentVersion {
2227
+ readonly serverRevision: number;
2228
+ readonly clientRevision: number;
2229
+ }
2184
2230
  declare const webEditorHostInterface: any;
2185
2231
  declare const webEditorInterface: any;
2232
+ declare const webEditorHostTransportInterface: any;
2233
+ declare const webEditorClientTransportInterface: any;
2234
+ /** Methods the editor exposes to a presenting host. */
2235
+ declare const webEditorPresentationInterface: any;
2236
+ /** Methods a presenting host exposes to the editor. */
2237
+ declare const webEditorPresentationHostInterface: any;
2186
2238
  declare const zEmbeddedAppDescriptor: ZodObject<{
2187
2239
  handleId: ZodString;
2188
2240
  appId: ZodString;
@@ -2205,6 +2257,10 @@ declare const vscodeAppEmbeddingEventsInterface: any;
2205
2257
  type WebEditorHostProxy = InterfaceClient<typeof webEditorHostInterface>;
2206
2258
  /** Typed proxy used by the host to invoke editor methods. */
2207
2259
  type WebEditorProxy = InterfaceClient<typeof webEditorInterface>;
2260
+ type WebEditorHostTransportProxy = InterfaceClient<typeof webEditorHostTransportInterface>;
2261
+ type WebEditorClientTransportProxy = InterfaceClient<typeof webEditorClientTransportInterface>;
2262
+ type WebEditorPresentationProxy = InterfaceClient<typeof webEditorPresentationInterface>;
2263
+ type WebEditorPresentationHostProxy = InterfaceClient<typeof webEditorPresentationHostInterface>;
2208
2264
  /** Typed proxy used by an app to invoke `vscode-app-host` methods. */
2209
2265
  type VsCodeAppHostProxy = InterfaceClient<typeof vscodeAppHostInterface>;
2210
2266
  type VsCodeAppEmbeddingEventsProxy = InterfaceClient<typeof vscodeAppEmbeddingEventsInterface>;
@@ -2273,12 +2329,15 @@ declare function encodeForEditor(text: string, contentType: ContentType): JsonVa
2273
2329
  */
2274
2330
  declare function decodeFromEditor(value: JsonValue, contentType: ContentType, options?: JsonFormatOptions): string;
2275
2331
  //#endregion
2276
- //#region src/utils/event.d.ts
2277
- interface IDisposable {
2278
- dispose(): void;
2332
+ //#region src/hostTransport.d.ts
2333
+ /**
2334
+ * Optional message transport between a web editor and its host.
2335
+ */
2336
+ interface HostTransport {
2337
+ readonly onMessage: Event<JsonValue>;
2338
+ /** Sends a notification to the host. */
2339
+ sendMessage(message: JsonValue): void;
2279
2340
  }
2280
- type EventListener<T> = (event: T) => void;
2281
- type Event<T> = (listener: EventListener<T>) => IDisposable;
2282
2341
  //#endregion
2283
2342
  //#region src/host/WebEditorHost.d.ts
2284
2343
  interface WebEditorHostOptions {
@@ -2289,11 +2348,16 @@ interface WebEditorHostOptions {
2289
2348
  connection: HubRpcConnection;
2290
2349
  /**
2291
2350
  * What the host stores. `text` is plain text; `json` is round-tripped through
2292
- * `JSON.parse` / `JSON.stringify`. Default `text`.
2293
- *
2294
- * The editor announces its own `contentType` in `initialized`. They must match.
2351
+ * `JSON.parse` / `JSON.stringify`. Default `text`. Shorthand for a single
2352
+ * entry in {@link contentTypes}.
2295
2353
  */
2296
2354
  contentType?: ContentType;
2355
+ /**
2356
+ * The content types the host can serve the text as, its preference first.
2357
+ * Overrides {@link contentType}. The editor picks one in `initialized`:
2358
+ * the first of its accepted types that is in this list.
2359
+ */
2360
+ contentTypes?: readonly ContentType[];
2297
2361
  /** Initial text. Default `""`. */
2298
2362
  initialText?: string;
2299
2363
  /** Initial read-only state. Default `false`. */
@@ -2302,6 +2366,14 @@ interface WebEditorHostOptions {
2302
2366
  jsonFormat?: JsonFormatOptions;
2303
2367
  /** Host capabilities advertised on `initialized`. */
2304
2368
  capabilities?: HostCapabilities;
2369
+ /** Optional message transport to expose to the editor. */
2370
+ hostTransport?: HostTransport;
2371
+ /**
2372
+ * The host presents the editor inline (for example as a block in a document)
2373
+ * and exchanges presentation state with editors that support it: see
2374
+ * {@link WebEditorHost.setPresentationMode} and the presentation events.
2375
+ */
2376
+ supportsPresentation?: boolean;
2305
2377
  /** Called when the editor sends malformed input. Defaults to `console.error`. */
2306
2378
  onError?: (message: string, detail?: unknown) => void;
2307
2379
  }
@@ -2309,25 +2381,42 @@ interface WebEditorHostOptions {
2309
2381
  * Host-side façade for the web-editor v0.12 protocol.
2310
2382
  *
2311
2383
  * Owns the canonical text content. Translates between text/JSON form and the
2312
- * structural edits exchanged with the editor. Maintains the revision pair
2313
- * required by the client-authority conflict policy.
2384
+ * structural edits exchanged with the editor.
2385
+ *
2386
+ * Concurrent edits from both sides are merged with operational transformation
2387
+ * when the editor supports it ({@link OT_EDIT_TRANSFORM}). Otherwise the host
2388
+ * maintains the revision pair required by the client-authority conflict
2389
+ * policy, under which conflicting edits are dropped.
2314
2390
  */
2315
2391
  declare class WebEditorHost implements IDisposable {
2316
2392
  private readonly _connection;
2317
2393
  private readonly _editor;
2318
- private readonly _contentType;
2394
+ private readonly _clientTransport;
2395
+ private readonly _presentation;
2396
+ private readonly _contentTypes;
2397
+ /** The type agreed with the editor; the host's preference until then. */
2398
+ private _contentType;
2319
2399
  private readonly _jsonFormat;
2320
2400
  private readonly _onError;
2321
2401
  private readonly _capabilities;
2402
+ private readonly _hostTransportSubscription;
2322
2403
  private _text;
2323
2404
  private _readOnly;
2405
+ private _presentationMode;
2406
+ /** Set while connected to an editor that merges concurrent edits. */
2407
+ private _transform;
2408
+ /** Client-authority policy only. */
2324
2409
  private _serverRevision;
2410
+ /** Client-authority policy only. */
2325
2411
  private _acknowledgedClientRevision;
2326
2412
  private _editorInitialized;
2327
2413
  private _editorCapabilities;
2414
+ private readonly _pendingHostTransportMessages;
2328
2415
  private readonly _onDidChangeText;
2416
+ /** The editor changed the content. `edits` apply to the previous content, in the editor's form. */
2329
2417
  readonly onDidChangeText: Event<{
2330
2418
  text: string;
2419
+ edits: readonly ContentEdit[];
2331
2420
  }>;
2332
2421
  private readonly _onDidInitialize;
2333
2422
  readonly onDidInitialize: Event<{
@@ -2337,12 +2426,38 @@ declare class WebEditorHost implements IDisposable {
2337
2426
  readonly onDidReportSize: Event<{
2338
2427
  height: number;
2339
2428
  }>;
2429
+ private readonly _onDidSetPresentationPreferences;
2430
+ /** The editor replaced its presentation preferences. Only fires with `supportsPresentation`. */
2431
+ readonly onDidSetPresentationPreferences: Event<PresentationPreferences>;
2432
+ private readonly _onDidRequestExitFullView;
2433
+ /** The editor asked to leave full view. Only fires with `supportsPresentation`. */
2434
+ readonly onDidRequestExitFullView: Event<void>;
2340
2435
  constructor(options: WebEditorHostOptions);
2341
2436
  /** The text the host believes the document currently holds. */
2342
2437
  getText(): string;
2343
2438
  /**
2344
- * Push a new full text to the editor. Sent as a `replace` at the document
2345
- * root. If `force`, the editor must adopt it even with pending local edits.
2439
+ * The content type agreed with the editor, in which edits are exchanged.
2440
+ * `undefined` until the editor initialized.
2441
+ */
2442
+ get contentType(): ContentType | undefined;
2443
+ /** The current content's version, to send along with offsets into it. */
2444
+ get version(): ContentVersion;
2445
+ /**
2446
+ * Maps an offset into the string at `path`, which the editor computed on
2447
+ * its content at `version`, into the current content. Call it when the
2448
+ * editor's message arrives: its earlier edits are integrated by then.
2449
+ *
2450
+ * @returns `undefined` if the offset cannot be mapped, for example because
2451
+ * the string was replaced or the content was reset since.
2452
+ */
2453
+ mapOffset(version: ContentVersion, path: readonly string[], offset: number, assoc?: "before" | "after"): number | undefined;
2454
+ /**
2455
+ * Change the text the editor shows.
2456
+ *
2457
+ * When the editor merges concurrent edits, the change is sent as edits
2458
+ * that merge with the editor's unsent edits. Otherwise, and with `force`,
2459
+ * the full text is sent. If `force`, the editor must adopt it even with
2460
+ * pending local edits, which are then discarded.
2346
2461
  */
2347
2462
  setText(text: string, opts?: {
2348
2463
  force?: boolean;
@@ -2354,15 +2469,32 @@ declare class WebEditorHost implements IDisposable {
2354
2469
  */
2355
2470
  reuse(text: string, readOnly: boolean): void;
2356
2471
  getReadOnly(): boolean;
2472
+ /**
2473
+ * Tell the editor how the host presents it. Sent to editors that support
2474
+ * presentation once they initialized, and again after they reconnect.
2475
+ */
2476
+ setPresentationMode(mode: PresentationMode): void;
2357
2477
  setReadOnly(readOnly: boolean): void;
2358
2478
  /**
2359
- * Push fine-grained edits to the editor.
2360
- * The host is responsible for keeping its own `_text` consistent with these edits.
2479
+ * Change the text by fine-grained edits, which are pushed to the editor.
2480
+ * An editor that initializes later receives the changed text.
2361
2481
  */
2362
2482
  applyEdits(edits: readonly ContentEdit[]): void;
2363
2483
  dispose(): void;
2484
+ private _applyTransformedEditorEdit;
2485
+ /** The text after the editor's `edits`, or `undefined` after reporting why they do not apply. */
2486
+ private _applyEditorEdits;
2487
+ /** Edits from `oldText` to `newText` in the editor's form, or `undefined` if either cannot be encoded. */
2488
+ private _diff;
2489
+ private _sendHostEdits;
2364
2490
  private _pushFullUpdate;
2491
+ /**
2492
+ * Sends the full content, which replaces the editor's. Editor edits made
2493
+ * before the editor receives it are discarded on both sides.
2494
+ */
2495
+ private _resetEditor;
2365
2496
  private _pushAcknowledgement;
2497
+ private _pushPresentationMode;
2366
2498
  private _acknowledgeAndRestore;
2367
2499
  }
2368
2500
  //#endregion
@@ -2440,8 +2572,13 @@ interface WebEditorClientOptions {
2440
2572
  * closes it on dispose.
2441
2573
  */
2442
2574
  connection: ConnectionInput;
2443
- /** Editor's content type. Must match what the host expects. Default `text`. */
2575
+ /** The content type the editor accepts. Default `text`. Shorthand for a single entry in {@link contentTypes}. */
2444
2576
  contentType?: ContentType;
2577
+ /**
2578
+ * The content types the editor accepts, most preferred first. Overrides
2579
+ * {@link contentType}. The host picks one; see {@link WebEditorClient.contentType}.
2580
+ */
2581
+ contentTypes?: readonly ContentType[];
2445
2582
  /** Editor capabilities announced to the host. */
2446
2583
  capabilities?: EditorCapabilities;
2447
2584
  /** Optional handler for `getContentSchema` requests from the host. */
@@ -2459,25 +2596,49 @@ interface WebEditorClientState {
2459
2596
  * Calls `host.initialized` immediately, then exposes the current content and
2460
2597
  * read-only flag as observable events. Local edits made through {@link applyEdits}
2461
2598
  * are sent to the host with monotonically increasing client revisions.
2599
+ *
2600
+ * When the host supports it ({@link OT_EDIT_TRANSFORM}), host edits that
2601
+ * arrive while local edits are unacknowledged are transformed against them,
2602
+ * so neither side's edits are lost. Otherwise such host changes are dropped
2603
+ * (client-authority policy).
2462
2604
  */
2463
2605
  declare class WebEditorClient implements IDisposable {
2464
2606
  private readonly _connection;
2465
2607
  private readonly _host;
2608
+ private readonly _hostTransportProxy;
2609
+ private readonly _presentationHost;
2466
2610
  private readonly _onError;
2611
+ private _hostTransport;
2467
2612
  private _content;
2468
2613
  private _readOnly;
2469
2614
  private _options;
2470
2615
  private _hostCapabilities;
2471
- private _clientRevision;
2616
+ private _contentType;
2617
+ private _connected;
2618
+ /** Host messages that arrived before the `initialized` response, which tells how to read them. */
2619
+ private _messagesBeforeConnect;
2620
+ private _presentationMode;
2621
+ private _presentationPreferences;
2622
+ private readonly _pendingHostTransportMessages;
2623
+ private _hostTransportActivated;
2624
+ /** Local edits and their revisions; its pending edits are those the host has not acknowledged. */
2625
+ private readonly _edits;
2626
+ /** Whether the host transforms concurrent edits, as announced with its first content. */
2627
+ private _transform;
2628
+ /** Client-authority policy only. */
2472
2629
  private _basedOnServerRevision;
2473
- /** Number of un-acked local revisions. While > 0 the editor has pending edits. */
2474
- private _pendingLocalEdits;
2475
2630
  private readonly _onDidChangeContent;
2631
+ /**
2632
+ * The content changed: by a local edit, by host edits (after
2633
+ * {@link onDidApplyHostEdits}) or replaced by the host. Listeners must
2634
+ * tolerate content they already show.
2635
+ */
2476
2636
  readonly onDidChangeContent: Event<{
2477
2637
  content: JsonValue;
2478
2638
  force: boolean;
2479
2639
  }>;
2480
2640
  private readonly _onDidApplyHostEdits;
2641
+ /** Host edits were applied; `edits` are relative to the previous content, after transformation against local edits. */
2481
2642
  readonly onDidApplyHostEdits: Event<{
2482
2643
  edits: ContentEdit[];
2483
2644
  content: JsonValue;
@@ -2490,19 +2651,47 @@ declare class WebEditorClient implements IDisposable {
2490
2651
  readonly onDidChangeOptions: Event<{
2491
2652
  options: JsonValue;
2492
2653
  }>;
2654
+ private readonly _onDidChangePresentationMode;
2655
+ /** The embedding host changed how it presents this editor. See {@link getPresentationMode}. */
2656
+ readonly onDidChangePresentationMode: Event<{
2657
+ mode: PresentationMode;
2658
+ }>;
2659
+ private readonly _onDidReceiveHostMessage;
2493
2660
  /** Resolves once the host has acknowledged `initialized`. */
2494
2661
  readonly onDidConnect: Promise<{
2495
2662
  capabilities: HostCapabilities | undefined;
2663
+ contentType: ContentType;
2496
2664
  }>;
2497
2665
  static connect(options: WebEditorClientOptions): Promise<WebEditorClient>;
2498
2666
  constructor(options: WebEditorClientOptions);
2667
+ /**
2668
+ * The content type the host serves, one of the accepted ones; `undefined`
2669
+ * until the host answered `initialized`. Content events fire only after it is set.
2670
+ */
2671
+ get contentType(): ContentType | undefined;
2672
+ private _afterConnect;
2499
2673
  /**
2500
2674
  * The underlying connection. Reuse it to talk to other host interfaces
2501
2675
  * (e.g. `vscode-app-host`) over the same transport instead of opening a
2502
2676
  * second one.
2503
2677
  */
2504
2678
  get connection(): HubRpcConnection;
2679
+ /** Optional notification transport supplied by the web editor host. */
2680
+ get hostTransport(): HostTransport | undefined;
2505
2681
  getContent(): JsonValue;
2682
+ /** The current content's version, to send along with offsets into it. */
2683
+ get version(): ContentVersion;
2684
+ /**
2685
+ * Maps an offset into the string at `path`, which the host computed on its
2686
+ * content at `version`, into the current content. Call it when the host's
2687
+ * message arrives.
2688
+ *
2689
+ * @returns `undefined` if the offset cannot be mapped, for example because
2690
+ * host edits arrived since or the string was replaced.
2691
+ */
2692
+ mapOffset(version: ContentVersion, path: readonly string[], offset: number, assoc?: "before" | "after"): number | undefined;
2693
+ /** The host revision the content is based on. */
2694
+ private get _serverRevision();
2506
2695
  getReadOnly(): boolean;
2507
2696
  getOptions(): JsonValue;
2508
2697
  getHostCapabilities(): HostCapabilities | undefined;
@@ -2512,13 +2701,28 @@ declare class WebEditorClient implements IDisposable {
2512
2701
  */
2513
2702
  applyEdits(edits: readonly ContentEdit[]): void;
2514
2703
  /**
2515
- * Report the editor's current laid-out content height (px) to the host.
2516
- * A host embedding this editor in an iframe uses it to size the frame.
2704
+ * Report the editor's preferred content height (px): the height it needs to
2705
+ * show its content without scrolling, independent of the frame's current
2706
+ * height. A host embedding this editor in an iframe sizes the frame to it.
2517
2707
  */
2518
2708
  reportSize(height: number): void;
2709
+ /**
2710
+ * How an embedding host currently presents this editor, or `undefined` when
2711
+ * the host does not present it inline (for example a standalone editor).
2712
+ */
2713
+ getPresentationMode(): PresentationMode | undefined;
2714
+ /**
2715
+ * Ask a presenting host for presentation controls (resize grips, full view).
2716
+ * Replaces earlier preferences; sent once connected, and ignored by hosts
2717
+ * that do not present the editor inline.
2718
+ */
2719
+ setPresentationPreferences(preferences: PresentationPreferences): void;
2720
+ /** Ask a presenting host to leave full view. */
2721
+ exitFullView(): void;
2519
2722
  dispose(): void;
2520
2723
  private _handleUpdate;
2521
2724
  private _handleApplyContentEdits;
2725
+ private _applyTransformedHostEdits;
2522
2726
  private _acknowledge;
2523
2727
  }
2524
2728
  //#endregion
@@ -2654,7 +2858,309 @@ declare class VsCodeAppHostClient {
2654
2858
  configureEditorAssociation(extension: string, options?: {
2655
2859
  dismissable?: boolean;
2656
2860
  }): Promise<EditorAssociationResult>;
2861
+ /**
2862
+ * This editor tab's view state, or `undefined` when none is set. VS Code
2863
+ * restores it with the tab (for example after a window reload); a newly
2864
+ * opened tab starts without one. Validate it like any other persisted
2865
+ * input, since it may come from an older version of the app.
2866
+ */
2867
+ getViewState(): Promise<unknown>;
2868
+ /**
2869
+ * Replace this editor tab's view state with a JSON value, for example
2870
+ * scroll positions or selections. Use per-app storage for state shared by
2871
+ * every tab. Rejects for values too large to persist and in embedded apps.
2872
+ */
2873
+ setViewState(value: unknown): Promise<void>;
2874
+ }
2875
+ //#endregion
2876
+ //#region src/sync/otPeer.d.ts
2877
+ /**
2878
+ * How to transform two concurrent operations of type `TOp`.
2879
+ *
2880
+ * `transform(winner, loser)` returns `[winner', loser']` such that applying
2881
+ * `loser` then `winner'` gives the same state as applying `winner` then
2882
+ * `loser'`. Where both conflict, `winner` takes precedence.
2883
+ */
2884
+ interface OtType<TOp> {
2885
+ transform(winner: TOp, loser: TOp): readonly [TOp, TOp];
2886
+ }
2887
+ /**
2888
+ * One of the two sides of a session that keeps a document in sync between
2889
+ * two parties who both edit it (the Jupiter algorithm behind most operational
2890
+ * transformation systems).
2891
+ *
2892
+ * Each side applies its own operations immediately and sends them along with
2893
+ * how many of the other side's operations it had applied. When an operation
2894
+ * from the other side arrives, it was made without the local operations the
2895
+ * other side had not seen yet. Those pending operations and the incoming one
2896
+ * are transformed against each other: the incoming one is then applied, and
2897
+ * the pending ones now describe how the local state differs from the other
2898
+ * side's. Once both sides have received everything, they hold the same
2899
+ * document, and no operation was dropped.
2900
+ *
2901
+ * The leader's operations take precedence in conflicts. Exactly one side must
2902
+ * be the leader. Messages must arrive in the order they were sent.
2903
+ *
2904
+ * The leader can also start over from a state it sends in full ({@link reset});
2905
+ * the follower's operations that were made before it received that state are
2906
+ * then discarded on both sides.
2907
+ */
2908
+ declare class OtPeer<TOp> {
2909
+ private readonly _type;
2910
+ readonly role: "leader" | "follower";
2911
+ private _localRevision;
2912
+ private _remoteRevision;
2913
+ private _pending;
2914
+ /** Remote operations made before the remote side saw this local revision are discarded. */
2915
+ private _barrier;
2916
+ constructor(_type: OtType<TOp>, role: "leader" | "follower");
2917
+ /** Number of local operations, including resets. */
2918
+ get localRevision(): number;
2919
+ /** Number of remote operations integrated, including discarded ones. */
2920
+ get remoteRevision(): number;
2921
+ /** Local operations the remote side has not acknowledged yet, oldest first. */
2922
+ get pending(): readonly TOp[];
2923
+ /**
2924
+ * The local operations after `revision`, oldest first: how the local state
2925
+ * differs from the state the remote side had when it had integrated
2926
+ * `revision` and everything local before. `undefined` if they are no
2927
+ * longer known, because they were acknowledged since or a reset happened.
2928
+ */
2929
+ operationsAfter(revision: number): readonly TOp[] | undefined;
2930
+ /**
2931
+ * Records an operation already applied to the local state. Send it with
2932
+ * the returned revision and {@link remoteRevision} as the acknowledgement.
2933
+ */
2934
+ local(op: TOp): number;
2935
+ /**
2936
+ * Integrates an operation from the remote side.
2937
+ *
2938
+ * @param revision The remote side's revision after `op`.
2939
+ * @param acknowledgedRevision How many local operations the remote side had integrated when it made `op`.
2940
+ * @returns The operation to apply to the local state, or `undefined` if
2941
+ * `op` was made before the remote side received the latest reset.
2942
+ */
2943
+ remote(op: TOp, revision: number, acknowledgedRevision: number): TOp | undefined;
2944
+ /** The remote side has integrated all local operations up to `revision`. */
2945
+ acknowledge(revision: number): void;
2946
+ /**
2947
+ * Leader only: the local state is about to be sent in full and replaces
2948
+ * whatever the follower has. Returns the revision of the reset.
2949
+ *
2950
+ * @param remoteRevision Treat remote operations up to this revision as
2951
+ * integrated, to recover when the remote side's revisions got out of step.
2952
+ */
2953
+ reset(remoteRevision?: number): number;
2954
+ /**
2955
+ * Follower only: replaces the local state with the leader's full state at
2956
+ * `revision`. Pending local operations are discarded, as the leader
2957
+ * discards them too.
2958
+ */
2959
+ acceptReset(revision: number): void;
2960
+ }
2961
+ //#endregion
2962
+ //#region src/sync/textOperation.d.ts
2963
+ /** {@link OtType} for {@link TextOperation}s. */
2964
+ declare const textOperationOt: OtType<TextOperation>;
2965
+ /**
2966
+ * A change to a string, as a sequence of components that walk the original
2967
+ * string from start to end: keep (`retain`), add (`insert`) or remove
2968
+ * (`delete`) text. Everything after the last component is kept.
2969
+ *
2970
+ * Operations are normalized (see {@link TextOperationBuilder}), so equal
2971
+ * changes have equal components. Their size depends on the number of edited
2972
+ * regions, not on the length of the string.
2973
+ */
2974
+ declare class TextOperation {
2975
+ readonly components: readonly TextComponent[];
2976
+ static get identity(): TextOperation;
2977
+ /** Converts edits that apply one after another, as on the wire, into one operation. */
2978
+ static fromTextEdits(edits: readonly TextEdit[]): TextOperation;
2979
+ /** Use {@link TextOperationBuilder}, which normalizes the components. */
2980
+ constructor(token: typeof normalizedToken, components: readonly TextComponent[]);
2981
+ get isIdentity(): boolean;
2982
+ /** Length of the shortest string this operation applies to. */
2983
+ get baseSpan(): number;
2984
+ apply(text: string): string;
2985
+ /** Edits in ascending order that, applied one after another, have the effect of this operation. */
2986
+ toTextEdits(): TextEdit[];
2987
+ /** The operation that has the effect of this operation followed by `next`. */
2988
+ compose(next: TextOperation): TextOperation;
2989
+ /**
2990
+ * Transforms two operations on the same string so that each applies after
2991
+ * the other and both orders give the same result (`b'(a(s)) === a'(b(s))`).
2992
+ * Where both insert at the same position, `winner`'s text comes first.
2993
+ *
2994
+ * @returns `[winner', loser']`: `winner'` applies after `loser`, `loser'` after `winner`.
2995
+ */
2996
+ static transform(winner: TextOperation, loser: TextOperation): [TextOperation, TextOperation];
2997
+ /**
2998
+ * Where `offset` in the original string ends up after this operation.
2999
+ * An offset inside deleted text maps to where the deletion happened. Text
3000
+ * inserted exactly at `offset` ends up before the result for
3001
+ * `assoc === "after"` and after it for `assoc === "before"`.
3002
+ */
3003
+ mapOffset(offset: number, assoc?: "before" | "after"): number;
3004
+ equals(other: TextOperation): boolean;
3005
+ toString(): string;
3006
+ }
3007
+ type TextComponent = {
3008
+ readonly kind: "retain";
3009
+ readonly length: number;
3010
+ } | {
3011
+ readonly kind: "insert";
3012
+ readonly text: string;
3013
+ } | {
3014
+ readonly kind: "delete";
3015
+ readonly length: number;
3016
+ };
3017
+ declare const normalizedToken: unique symbol;
3018
+ /**
3019
+ * Builds normalized {@link TextOperation}s: no empty components, adjacent
3020
+ * components of the same kind merged, an insert before a delete at the same
3021
+ * position, and no trailing retain.
3022
+ */
3023
+ declare class TextOperationBuilder {
3024
+ private readonly _components;
3025
+ retain(length: number): this;
3026
+ insert(text: string): this;
3027
+ delete(length: number): this;
3028
+ build(): TextOperation;
3029
+ }
3030
+ //#endregion
3031
+ //#region src/sync/textDiff.d.ts
3032
+ /**
3033
+ * An operation that turns `oldText` into `newText` by replacing everything
3034
+ * between their common prefix and suffix. Linear time, so it stays fast for
3035
+ * large texts; separate changes become one replacement of the text between them.
3036
+ *
3037
+ * The replacement never starts or ends between `\r` and `\n`, so that text
3038
+ * inserted concurrently at its edges cannot split a `\r\n` line break.
3039
+ */
3040
+ declare function diffText(oldText: string, newText: string): TextOperation;
3041
+ //#endregion
3042
+ //#region src/sync/contentOperation.d.ts
3043
+ /** {@link OtType} for lists of {@link ContentEdit}s, as exchanged by web editors. */
3044
+ declare const contentEditsOt: OtType<readonly ContentEdit[]>;
3045
+ /**
3046
+ * Transforms two concurrent lists of {@link ContentEdit}s made on the same
3047
+ * content, so that each list applies after the other and both orders give the
3048
+ * same content.
3049
+ *
3050
+ * Edits at unrelated paths do not interact. String edits at the same path are
3051
+ * merged with {@link TextOperation.transform}. A `replace` overrides every
3052
+ * concurrent edit at or below its path; of two replacements at the same path,
3053
+ * `winner`'s is kept.
3054
+ *
3055
+ * @returns `[winner', loser']`: `winner'` applies after `loser`, `loser'` after `winner`.
3056
+ */
3057
+ declare function transformContentEdits(winner: readonly ContentEdit[], loser: readonly ContentEdit[]): [ContentEdit[], ContentEdit[]];
3058
+ /**
3059
+ * Where `offset` in the string at `path` ends up after `edits`, or `undefined`
3060
+ * if the string was replaced. See {@link TextOperation.mapOffset} for `assoc`.
3061
+ */
3062
+ declare function mapContentOffset(edits: readonly ContentEdit[], path: readonly string[], offset: number, assoc?: "before" | "after"): number | undefined;
3063
+ /** Maps `offset` through each list of edits in turn; `undefined` if `operations` is `undefined` or the offset does not survive an edit. */
3064
+ declare function mapThrough(operations: readonly (readonly ContentEdit[])[] | undefined, path: readonly string[], offset: number, assoc?: "before" | "after"): number | undefined;
3065
+ /**
3066
+ * Edits that turn `oldValue` into `newValue`, as fine-grained as possible so
3067
+ * that they merge with concurrent edits: changed strings become string edits,
3068
+ * objects with the same keys and arrays with the same length are compared
3069
+ * member by member, and anything else is replaced.
3070
+ */
3071
+ declare function diffContent(oldValue: JsonValue, newValue: JsonValue, path?: string[]): ContentEdit[];
3072
+ //#endregion
3073
+ //#region src/documentSync/textDocumentSync.d.ts
3074
+ interface TextDocumentSyncOptions {
3075
+ /** Called for failed or rejected writes. Defaults to `console.error`. */
3076
+ onError?: (message: string, detail?: unknown) => void;
3077
+ }
3078
+ /** Options for the {@link WebEditorHost} of a connected editor. */
3079
+ type TextDocumentEditorOptions = Omit<WebEditorHostOptions, "connection" | "initialText" | "onError">;
3080
+ /**
3081
+ * Keeps a web editor's text and a {@link SyncedTextDocument} in sync while
3082
+ * both change.
3083
+ *
3084
+ * The editor text is the document text plus the editor's changes that are not
3085
+ * in the document yet. Editor changes are written one batch at a time. A
3086
+ * document change that is not such a write, for example an undo, a format on
3087
+ * save or another editor's edit, is transformed against the unwritten editor
3088
+ * changes and sent to the editor, so neither side's changes are lost. A write
3089
+ * the document rejects because it changed meanwhile is transformed the same
3090
+ * way and written again. If the document applies a write differently, for
3091
+ * example with its own line breaks, the editor receives the difference.
3092
+ *
3093
+ * Editors connect through a {@link WebEditorHost}, which merges the editor's
3094
+ * unsent edits with the changes sent to it (operational transformation).
3095
+ * Each (re)loaded editor connects anew.
3096
+ */
3097
+ declare class TextDocumentSync implements IDisposable {
3098
+ private readonly _document;
3099
+ private readonly _onError;
3100
+ /** The document text as last seen. */
3101
+ private _documentText;
3102
+ /** {@link _documentText} with {@link _writing} and {@link _unwritten} applied. */
3103
+ private _text;
3104
+ private _revision;
3105
+ private _writing;
3106
+ /**
3107
+ * Document changes seen while {@link _writing} is in flight. They are
3108
+ * settled when it completes: only then is it known whether the first one
3109
+ * is the write.
3110
+ */
3111
+ private readonly _changesDuringWrite;
3112
+ /** Editor changes after {@link _writing} that are not written yet. */
3113
+ private _unwritten;
3114
+ private _host;
3115
+ private readonly _tracked;
3116
+ private readonly _onDidChangeText;
3117
+ /** Fires after every change of {@link text}. */
3118
+ readonly onDidChangeText: Event<void>;
3119
+ private readonly _onDidSettle;
3120
+ private readonly _subscription;
3121
+ private _disposed;
3122
+ constructor(_document: SyncedTextDocument, options?: TextDocumentSyncOptions);
3123
+ /** The editor text: the document text with the editor changes that are not written yet. */
3124
+ get text(): string;
3125
+ /** Changes with every change of {@link text}. */
3126
+ get revision(): number;
3127
+ /** The version to send along with offsets into {@link text}, while an editor is connected. */
3128
+ get version(): ContentVersion | undefined;
3129
+ /**
3130
+ * Connects a (re)loaded editor, which receives the current text. Replaces
3131
+ * the previous editor's host, which is disposed along with its connection.
3132
+ */
3133
+ connect(connection: HubRpcConnection, options?: TextDocumentEditorOptions): WebEditorHost;
3134
+ /**
3135
+ * Follows `offset` in {@link text} through later changes, until disposed.
3136
+ * With `"after"` (the default), text inserted exactly at the offset ends up
3137
+ * before it.
3138
+ */
3139
+ track(offset: number, assoc?: "before" | "after"): TrackedOffset;
3140
+ /**
3141
+ * Tracks an offset into the text that the editor sent along with
3142
+ * `version`; `undefined` if it cannot be mapped. Call it when the editor's
3143
+ * message arrives.
3144
+ */
3145
+ trackFromEditor(version: ContentVersion, offset: number, assoc?: "before" | "after"): TrackedOffset | undefined;
3146
+ /**
3147
+ * Resolves once every editor change is in the document, so that
3148
+ * {@link text} equals the document text. Rejects if the sync is disposed.
3149
+ */
3150
+ drain(): Promise<void>;
3151
+ dispose(): void;
3152
+ private _acceptEditorChange;
3153
+ private _acceptDocumentChange;
3154
+ /** Someone else changed the document: merges the change with the editor changes that are not written yet. */
3155
+ private _acceptExternalChange;
3156
+ private _write;
3157
+ /** Applies a change that comes from the document to {@link text} and sends it to the editor. */
3158
+ private _applyFromDocument;
3159
+ private _applyToText;
3160
+ }
3161
+ interface TrackedOffset extends IDisposable {
3162
+ readonly offset: number;
2657
3163
  }
2658
3164
  //#endregion
2659
- export { AppContext, type ConnectionInput, ContentEdit, ContentType, EditorAssociationResult, EditorCapabilities, EditorRegistrationStatus, EditorScope, EmbeddedAppAccessOptions, EmbeddedAppDescriptor, EmbeddedAppHandle, EmbeddingContext, type Event, HostCapabilities, type IDisposable, JsonFormatOptions, JsonValue, type MessageEndpoint, type MessageLikeEvent, ScopeRegistration, TextEdit, VsCodeAppEmbeddingEventsProxy, VsCodeAppHostClient, VsCodeAppHostClientOptions, VsCodeAppHostProxy, WebEditorClient, WebEditorClientOptions, WebEditorClientState, WebEditorHost, WebEditorHostOptions, WebEditorHostProxy, WebEditorProxy, WebEditorUpdate, WindowMessageTransport, applyContentEdits, applyTextEdits, createWindowParentConnection, decodeFromEditor, encodeForEditor, vscodeAppEmbeddingEventsInterface, vscodeAppHostInterface, webEditorHostInterface, webEditorInterface };
3165
+ export { AppContext, type ConnectionInput, ContentEdit, ContentType, ContentVersion, DocumentTextChange, DocumentTextEdit, EditorAssociationResult, EditorCapabilities, EditorRegistrationStatus, EditorScope, EmbeddedAppAccessOptions, EmbeddedAppDescriptor, EmbeddedAppHandle, EmbeddingContext, type Event, HostCapabilities, HostTransport, type IDisposable, JsonFormatOptions, JsonValue, type MessageEndpoint, type MessageLikeEvent, OT_EDIT_TRANSFORM, OtPeer, OtType, PresentationMode, PresentationPreferences, ScopeRegistration, SyncedTextDocument, TextComponent, TextDocumentEditorOptions, TextDocumentSync, TextDocumentSyncOptions, TextEdit, TextOperation, TextOperationBuilder, TrackedOffset, VsCodeAppEmbeddingEventsProxy, VsCodeAppHostClient, VsCodeAppHostClientOptions, VsCodeAppHostProxy, WebEditorClient, WebEditorClientOptions, WebEditorClientState, WebEditorClientTransportProxy, WebEditorHost, WebEditorHostOptions, WebEditorHostProxy, WebEditorHostTransportProxy, WebEditorPresentationHostProxy, WebEditorPresentationProxy, WebEditorProxy, WebEditorUpdate, WindowMessageTransport, applyContentEdits, applyTextEdits, contentEditsOt, createWindowParentConnection, decodeFromEditor, diffContent, diffText, encodeForEditor, mapContentOffset, mapThrough, textOperationOt, transformContentEdits, vscodeAppEmbeddingEventsInterface, vscodeAppHostInterface, webEditorClientTransportInterface, webEditorHostInterface, webEditorHostTransportInterface, webEditorInterface, webEditorPresentationHostInterface, webEditorPresentationInterface };
2660
3166
  //# sourceMappingURL=index.d.ts.map