@hydranium/protocol 1.0.0-next.39 → 1.0.0-next.391

package/lib/data/data-server-protocol.d.ts

@@ -9,11 +9,11 @@
 import type { TransferDiagnostic } from '../transfer-diagnostic';
 import type { TransferElement } from '../transfer-element';
 import type { Project } from '../project';
-import type { TransferDocument } from '../transfer-document';
+import type { TransferCreatedDocument, TransferDocument, TransferSavedDocument, TransferWatchedDocument, TransferWrittenDocument } from '../transfer-document';
 import type { CloseModelArgs, FindNextNameArgs, OpenModelArgs, ReferenceContext, ReferenceRequest } from '../model-server';
 import type { ReferenceCandidate, ReferenceTarget } from '../model-service/reference-candidate';
-import type { ProjectsChangedEvent, TransferDocumentDeletedEvent, TransferDocumentSavedEvent, TransferDocumentsBuiltEvent, TransferDocumentUpdatedEvent } from './events';
-import type { GetModelDocumentArgs, GetProjectForUriArgs, TransferSaveDocumentArgs, WatchModelDocumentArgs, TransferUpdateDocumentArgs } from './requests';
+import type { ProjectsChangedEvent, TransferDocumentDeletedEvent, TransferDocumentDirtyChangedEvent, TransferDocumentSavedEvent, TransferDocumentsBuiltEvent, TransferDocumentUpdatedEvent } from './events';
+import type { CloseSessionArgs, CreateModelDocumentArgs, CreateSessionArgs, GetModelDocumentArgs, GetProjectForUriArgs, TransferDeleteDocumentArgs, TransferPersistDocumentArgs, TransferSaveDocumentArgs, WatchModelDocumentArgs, TransferUpdateDocumentArgs, TransferUpdateDocumentsArgs } from './requests';
 /**
  * Document-scoped slice of the data-server wire contract: the per-document
  * lifecycle (get / update / save), the per-`(uri, clientId)` watch
@@ -32,34 +32,77 @@ import type { GetModelDocumentArgs, GetProjectForUriArgs, TransferSaveDocumentAr
  */
 export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
     /**
-     * Open a document for an editor session and return its current state.
-     * Registers `(uri, clientId)` with the multi-client document manager
-     * (so concurrent editors share one built document) and returns the
-     * document at the server's configured target phase — the same shape
-     * {@link getModelDocument} returns, except that `version` is taken from
-     * the text-document store so the caller's first `baseVersion` write
-     * cannot self-conflict. Idempotent in registration terms: opening an
-     * already-open document refreshes the client registration. Note it does
-     * NOT avoid a rebuild — a second client attaching triggers
-     * `refreshContent`, which fires a change event, so mounting a form on a
-     * document already open in a text editor rebuilds it.
+     * Register `args.clientId` as a client session owned by this connection.
+     * Rejects with a `DuplicateClientIdError` code when the id is live anywhere
+     * in the server process, and with a `ReservedClientIdError` code when the
+     * framework reserves it.
      *
-     * The default `DataServer` impl delegates to `ModelService.open` then
-     * reads the built state. Pair with {@link watchModelDocument} to receive
-     * subsequent build-phase events (open returns a one-shot snapshot;
-     * later validation diagnostics arrive on the watch channel).
+     * A request carrying a registered id acts as that session: it writes only
+     * what the session has open, failing with a `DocumentNotOpenError` code
+     * otherwise, and opens nothing implicitly; its open reads the file and takes
+     * no `languageId`, `version` or `text` seed. The session ends with
+     * {@link closeSession} or when the connection closes, and either closes
+     * every document it has open.
+     *
+     * A registration carrying the `resumeToken` an earlier registration of the
+     * same id carried ends that session first, from any connection, so a client
+     * whose connection dropped can register again before the server notices.
+     */
+    createSession(args: CreateSessionArgs): Promise<void>;
+    /**
+     * End a session this connection registered: close every document it has
+     * open, drop its watches, and free its id. A no-op for an id this
+     * connection did not register.
+     */
+    closeSession(args: CloseSessionArgs): Promise<void>;
+    /**
+     * Create a document with `args.text`, open for the session, and return it
+     * as {@link openModelDocument} does, with the version the create made in
+     * `created`. The answer is read after the create, so it can already hold
+     * another client's write or an integrity repair; a write based on
+     * `created.version` then conflicts. It reaches disk with the first save.
+     * Fails when the file exists, any client has the URI open, or a lost
+     * client's unsaved text is held for it, and with a
+     * `SessionClosedError` code when `args.clientId` is not a session
+     * registered on this connection.
+     */
+    createModelDocument(args: CreateModelDocumentArgs): Promise<TransferCreatedDocument<TTransfer, TDiagnostic>>;
+    /**
+     * Write several documents the session has open, all or none: a conflict, a
+     * document not open, or a model for a document whose parse lacks some of
+     * its text fails the whole set before any text applies.
+     * Resolves to the documents in the order given, each with the version its
+     * text took in `written`, once the language client has answered the push
+     * of each, or the server-side bound on that wait passes, as
+     * {@link updateModelDocument} does. Only for a session registered on this
+     * connection.
+     */
+    updateModelDocuments(args: TransferUpdateDocumentsArgs<TTransfer>): Promise<TransferWrittenDocument<TTransfer, TDiagnostic>[]>;
+    /**
+     * Open a document for the client session `clientId` and return its current
+     * state. `clientId` must be a session this connection registered with
+     * {@link createSession}; any other id fails with the closed-session code,
+     * as every document request here does. The document is read from disk
+     * unless a client has it open already, so the request carries no
+     * `languageId`, `version` or `text` seed. Returns the document at
+     * the server's configured target phase, as {@link getModelDocument} does.
+     * A repeat open changes nothing.
+     *
+     * Pair with {@link watchModelDocument} to receive subsequent build-phase
+     * events (open returns a one-shot snapshot; later validation diagnostics
+     * arrive on the watch channel).
      */
-    openModelDocument(args: OpenModelArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+    openModelDocument(args: Pick<OpenModelArgs, 'uri' | 'clientId' | 'options'>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
     /**
-     * Close an editor session for `(uri, clientId)`. Counterpart to
-     * {@link openModelDocument}; the underlying document stays built until
-     * every registered client has closed. The default `DataServer` impl
-     * delegates to `ModelService.close` and ALSO releases any watch for the
-     * same `(uri, clientId)` (closing a session frees its own watch — a
-     * forgotten {@link unwatchModelDocument} would otherwise leak dispatch;
-     * the implicit unwatch is idempotent). `watchModelDocument` is NOT
-     * coupled the other way: opening does not force a watch, so a snapshot
-     * reader can open without streaming.
+     * Close the session's open of `uri`. Counterpart to
+     * {@link openModelDocument}; the document stays open until every client
+     * has closed it, and then the server releases it, by default reverting it
+     * to disk. The default
+     * `DataServer` impl ALSO releases any watch for the same
+     * `(uri, clientId)` (a forgotten {@link unwatchModelDocument} would
+     * otherwise leak dispatch; the implicit unwatch is idempotent).
+     * `watchModelDocument` is NOT coupled the other way: opening does not force
+     * a watch, so a snapshot reader can open without streaming.
      */
     closeModelDocument(args: CloseModelArgs): Promise<void>;
     /**
@@ -70,32 +113,73 @@ export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiag
      */
     getModelDocument(args: GetModelDocumentArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
     /**
-     * Update a document's content. The response carries the latest built
-     * state including diagnostics; callers observe convergence via that
-     * response.
+     * Update a document's content as the session `clientId`, which must have
+     * it open. The response carries the latest built state including
+     * diagnostics. Callers observe convergence via that response. `written`
+     * carries the version the write's text took, which tells a writer whether
+     * the build holds a later text too. It is sent once the language client
+     * has answered the push of the text, or the server-side bound on that wait
+     * passes, as {@link saveModelDocument}'s is, so an editor already shows
+     * the write when it arrives. A model, not text, for a document whose parse
+     * lacks some of its text fails with a `DocumentSyntaxError` code, unless
+     * the write is a `restore`.
      */
-    updateModelDocument(args: TransferUpdateDocumentArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+    updateModelDocument(args: TransferUpdateDocumentArgs<TTransfer>): Promise<TransferWrittenDocument<TTransfer, TDiagnostic>>;
     /**
-     * Persist a document to disk. The response is the post-save document
-     * state (matches the file on disk). Save semantics depend on the
-     * filesystem-provider wiring; rejection paths surface as awaited
-     * promise rejections.
+     * Write a document as the session `clientId`, which must have it open, and
+     * persist it to disk. The response is the build of the text written, with
+     * its version in `persisted`, sent once the language client has answered
+     * the push of that text, applied or refused, or a server-side bound on
+     * that wait passes; it does not wait again for a push that wait already
+     * gave up on and the client has not answered since. Save semantics depend
+     * on the filesystem-provider wiring; rejection paths surface as awaited
+     * promise rejections, as a model for a document whose parse lacks some of
+     * its text does with a `DocumentSyntaxError` code.
      */
-    saveModelDocument(args: TransferSaveDocumentArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+    saveModelDocument(args: TransferSaveDocumentArgs<TTransfer>): Promise<TransferSavedDocument<TTransfer, TDiagnostic>>;
+    /**
+     * Persist the text the server holds for a document the session `clientId`
+     * has open, as it is: no update and no serialisation, so another client's
+     * unsaved text keeps its formatting. `baseVersion` is checked in the step
+     * that takes the text, so text that moved on fails with a `ConflictError`
+     * code. The saved event names this session, whoever wrote the text.
+     * Answers after the same language-client wait as {@link saveModelDocument},
+     * with the document's latest build, read after that wait, so another
+     * session's write during it shows; `persisted` carries the version written.
+     */
+    persistModelDocument(args: TransferPersistDocumentArgs): Promise<TransferSavedDocument<TTransfer, TDiagnostic>>;
+    /**
+     * Delete a document the session `clientId` has open, at once: its file,
+     * then the document, as a deletion a file watcher reports removes it. Every
+     * session's open of it closes and every client hears
+     * {@link DocumentClientProtocol.onDocumentDeleted} naming this session; the
+     * session's own watch is released, as {@link closeModelDocument} releases
+     * it. `baseVersion` is checked in the step that marks the document for
+     * deletion, so text that moved on fails with a `ConflictError` code. A file
+     * already gone deletes only the document; a file that cannot be removed
+     * fails the call and changes nothing. Resolves once the build that removes
+     * the document has run; a read then answers the URI without a model, unless
+     * an editor still has it open, whose buffer the document is built from.
+     */
+    deleteModelDocument(args: TransferDeleteDocumentArgs): Promise<void>;
     /**
      * Start watching `(uri, clientId)`. The server starts dispatching
      * {@link DocumentClientProtocol.onDocumentUpdated} on the paired wire
      * for every build-phase event on `uri`.
      *
-     * Returns `Promise<void>` — the bidirectional pattern means the event
-     * channel is the client interface, not a returned handle. Callers fan
-     * out a single inbound `onDocumentUpdated` to multiple local listeners
-     * with their own `Emitter<T>` (matching Theia's pattern). Pair every
-     * `watchModelDocument` with {@link unwatchModelDocument} when no longer
-     * needed; the server holds the watch record until the matching unwatch
-     * lands.
+     * Answers with the key the watch's events name the document by, whether
+     * a document exists, taken once the watch is in place and the document
+     * is loaded as a read loads it, the text held at that moment, and the
+     * position of the last update or deletion event sent as of it, so an event
+     * the client heard while the watch was in flight tells by its own position
+     * whether it is newer than the answer. No handle: the event channel is the
+     * client interface. Callers fan out a single inbound `onDocumentUpdated` to
+     * multiple local listeners with their own `Emitter<T>` (matching Theia's
+     * pattern). Pair every `watchModelDocument` with
+     * {@link unwatchModelDocument} when no longer needed; the server holds the
+     * watch record until the matching unwatch lands.
      */
-    watchModelDocument(args: WatchModelDocumentArgs): Promise<void>;
+    watchModelDocument(args: WatchModelDocumentArgs): Promise<TransferWatchedDocument>;
     /**
      * Stop watching `(uri, clientId)` previously started by
      * {@link watchModelDocument}. Idempotent — unwatching twice is a no-op.
@@ -171,6 +255,19 @@ export interface ProjectServerProtocol<TProject extends Project = Project> {
  */
 export interface DataServerProtocol<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic, TProject extends Project = Project> extends DocumentServerProtocol<TTransfer, TDiagnostic>, ProjectServerProtocol<TProject> {
 }
+/**
+ * The diagnostic shape a server answers with, read back off its own
+ * declaration.
+ *
+ * This is what lets a client tier stay generic over the server alone and still
+ * describe what it hands back. Both parameters must be inferred: naming
+ * {@link TransferElement} for the transfer instead fails to match while that
+ * parameter is still generic, and a default declared against the constraint
+ * then stops satisfying it.
+ */
+export type DiagnosticOf<TServer> = TServer extends DocumentServerProtocol<infer _TTransfer, infer TDiagnostic> ? TDiagnostic : TransferDiagnostic;
+/** The project shape a server answers with, read back off its own declaration. */
+export type ProjectOf<TServer> = TServer extends ProjectServerProtocol<infer TProject> ? TProject : Project;
 /**
  * Cross-reference / naming slice of the server surface — scope-aware
  * queries that resolve against the language's reference services. NOT part
@@ -181,11 +278,11 @@ export interface DataServerProtocol<TTransfer extends TransferElement, TDiagnost
  * source/URI (an `ElementSource` with no URI resolves to the sole
  * registered language; a multi-language workspace overrides).
  *
- * Generic over the transfer root type only — the resolution result
- * ({@link ReferenceTarget}) carries the resolved node's encoded subtree;
- * candidates and names are diagnostic-free.
+ * Not generic over a server's root type: {@link resolveReference} answers with
+ * a node a reference names, which is no document root, and candidates and
+ * names are diagnostic-free.
  */
-export interface ReferenceServerProtocol<TTransfer extends TransferElement> {
+export interface ReferenceServerProtocol {
     /**
      * List the reference candidates reachable for the property named in `ctx`
      * from its (possibly synthetic) source. Backed by the language's
@@ -197,8 +294,11 @@ export interface ReferenceServerProtocol<TTransfer extends TransferElement> {
      * target's document URI, display fields, and the resolved node's encoded
      * transfer subtree. Resolves via the language's reference services;
      * `undefined` when the reference does not resolve.
+     *
+     * `TElement` is the caller's claim about the target node's type; nothing
+     * checks it, so leave it at the default unless the reference names one type.
      */
-    resolveReference(ref: ReferenceRequest): Promise<ReferenceTarget<TTransfer> | undefined>;
+    resolveReference<TElement extends TransferElement = TransferElement>(ref: ReferenceRequest): Promise<ReferenceTarget<TElement> | undefined>;
     /**
      * Compute the next free name for a new element of `args.type` based on
      * `args.proposal`, unique within the `args.tier` scope (default
@@ -235,6 +335,16 @@ export interface DocumentClientProtocol<TTransfer extends TransferElement, TDiag
      * codepath, not a subscription codepath).
      */
     onDocumentSaved(event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>): void;
+    /**
+     * Delivered when a subscribed document's text starts or stops differing
+     * from its file, as the server last knew it. Gated like
+     * {@link onDocumentSaved}; the answer at any one moment is the `dirty` of
+     * the documents the server sends. After a reconnect, a `DataSession`
+     * delivers here the answer of each document it restored, when that differs
+     * from the last this client was told: the flips while the connection was
+     * down reached no one.
+     */
+    onDocumentDirtyChanged(event: TransferDocumentDirtyChangedEvent): void;
     /**
      * Delivered when a document's backing file was removed. Separate from
      * {@link onDocumentUpdated} for the same reason as {@link onDocumentSaved},

package/lib/data/data-server-protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-server-protocol.d.ts","sourceRoot":"","sources":["../../src/data/data-server-protocol.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"data-server-protocol.d.ts","sourceRoot":"","sources":["../../src/data/data-server-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EACT,uBAAuB,EACvB,gBAAgB,EAChB,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,EACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,aAAa,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC3H,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAChG,OAAO,KAAK,EACT,oBAAoB,EACpB,4BAA4B,EAC5B,iCAAiC,EACjC,0BAA0B,EAC1B,2BAA2B,EAC3B,4BAA4B,EAC9B,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EACT,gBAAgB,EAChB,uBAAuB,EACvB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,0BAA0B,EAC1B,2BAA2B,EAC3B,wBAAwB,EACxB,sBAAsB,EACtB,0BAA0B,EAC1B,2BAA2B,EAC7B,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,sBAAsB,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,SAAS,kBAAkB,GAAG,kBAAkB;IACnI;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtD;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IAE7G;;;;;;;;;OASG;IACH,oBAAoB,CAAC,IAAI,EAAE,2BAA2B,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,uBAAuB,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC;IAE/H;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,UAAU,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IAEhI;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD;;;;;OAKG;IACH,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IAEhG;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,IAAI,EAAE,0BAA0B,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,uBAAuB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IAE3H;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,qBAAqB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IAErH;;;;;;;;;OASG;IACH,oBAAoB,CAAC,IAAI,EAAE,2BAA2B,GAAG,OAAO,CAAC,qBAAqB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IAEhH;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,IAAI,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErE;;;;;;;;;;;;;;;;OAgBG;IACH,kBAAkB,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAEnF;;;OAGG;IACH,oBAAoB,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElE;;;;;;;;;;OAUG;IACH,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB,CAAC,QAAQ,SAAS,OAAO,GAAG,OAAO;IACtE;;;;OAIG;IACH,WAAW,IAAI,OAAO,CAAC,SAAS,QAAQ,EAAE,CAAC,CAAC;IAE5C;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;CAC9E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,kBAAkB,CAChC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3D,QAAQ,SAAS,OAAO,GAAG,OAAO,CAElC,SAAQ,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,qBAAqB,CAAC,QAAQ,CAAC;CAAG;AAE7F;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,CAAC,OAAO,IAC7B,OAAO,SAAS,sBAAsB,CAAC,MAAM,UAAU,EAAE,MAAM,WAAW,CAAC,GAAG,WAAW,GAAG,kBAAkB,CAAC;AAElH,kFAAkF;AAClF,MAAM,MAAM,SAAS,CAAC,OAAO,IAAI,OAAO,SAAS,qBAAqB,CAAC,MAAM,QAAQ,CAAC,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE5G;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,uBAAuB;IACrC;;;;OAIG;IACH,uBAAuB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAE9E;;;;;;;;OAQG;IACH,gBAAgB,CAAC,QAAQ,SAAS,eAAe,GAAG,eAAe,EAChE,GAAG,EAAE,gBAAgB,GACrB,OAAO,CAAC,eAAe,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAC,CAAC;IAElD;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACxD;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,SAAS,kBAAkB,GAAG,kBAAkB;IACnI;;;;OAIG;IACH,iBAAiB,CAAC,KAAK,EAAE,4BAA4B,CAAC,SAAS,EAAE,WAAW,CAAC,GAAG,IAAI,CAAC;IAErF;;;;;;;;;OASG;IACH,eAAe,CAAC,KAAK,EAAE,0BAA0B,CAAC,SAAS,EAAE,WAAW,CAAC,GAAG,IAAI,CAAC;IAEjF;;;;;;;;OAQG;IACH,sBAAsB,CAAC,KAAK,EAAE,iCAAiC,GAAG,IAAI,CAAC;IAEvE;;;;;;;;;OASG;IACH,iBAAiB,CAAC,KAAK,EAAE,4BAA4B,GAAG,IAAI,CAAC;IAE7D;;;;;;;OAOG;IACH,gBAAgB,CAAC,KAAK,EAAE,2BAA2B,GAAG,IAAI,CAAC;CAC7D;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB,CAAC,QAAQ,SAAS,OAAO,GAAG,OAAO;IACtE;;;;;;;;OAQG;IACH,iBAAiB,CAAC,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;CACjE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB,CAChC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3D,QAAQ,SAAS,OAAO,GAAG,OAAO,CAElC,SAAQ,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,qBAAqB,CAAC,QAAQ,CAAC;CAAG"}

package/lib/data/events.d.ts

@@ -9,26 +9,28 @@
 import type { TransferDiagnostic } from '../transfer-diagnostic';
 import type { TransferElement } from '../transfer-element';
 import type { Project } from '../project';
-import type { TransferDocument } from '../transfer-document';
+import type { TextState, TransferDocument } from '../transfer-document';
 /**
  * Why an update event fired. Subscribers filter on reason for behaviour
  * decisions (e.g. dirty-flag handling, undo-history grouping, telemetry):
  *
- * - `'changed'` — the URI appeared in `DocumentBuilder.onUpdate`'s
- *   `changed` list. The framework's underlying primitive is "this URI was
- *   passed to `documentBuilder.update(changed, deleted)`", which spans
- *   `didChange` text-document events, `notifyDidChangeTextDocument` calls,
- *   and any programmatic `documentBuilder.update([uri], [])` invocation.
- *   The name matches Langium's own `changed` parameter — it's vague-on-
- *   purpose because the underlying primitive is.
- * - `'rebuilt'` — the URI was rebuilt as a cascade from another URI's
- *   build (dependency graph re-derivation), without itself being passed to
- *   `documentBuilder.update`. The complement of `'changed'`.
+ * - `'changed'` — the server's first update event for the document's current
+ *   version: its content changed since the last one. A write whose build a
+ *   later write cancelled is still `'changed'` in the build that takes over.
+ * - `'rebuilt'` — a later event for a version the server already delivered,
+ *   whether or not any client watched it then: something the document depends
+ *   on changed, or the document was built again with the same content. The
+ *   complement of `'changed'`.
  * - `'saved'` — emitted by adopters that synthesise a unified update stream
  *   from both `onDocumentUpdated` and `onDocumentSaved`. The framework's own
  *   `dispatchPhaseEvent` does NOT emit `'saved'` — saves take the dedicated
  *   `DataClientProtocol.onDocumentSaved` channel.
  *
+ * The version rule needs a version the server keeps and builds that validate.
+ * For a document no client has opened, or when rebuilds do not validate,
+ * `'changed'` means the URI was passed to `DocumentBuilder.update` for this
+ * build. A document that a validating build skips is `'changed'` every time.
+ *
  * Deletion is deliberately NOT a member. An update event carries a built
  * document, which a deleted one has none of, and the phase-driven path that
  * produces these events never runs for a deleted URI — the builder drops the
@@ -39,43 +41,71 @@ export type TransferDocumentUpdateReason = 'changed' | 'rebuilt' | 'saved';
 /**
  * Delivered on the data-server when a document's content (or existence)
  * changed. Subscribers receive this via `DocumentServerProtocol.watchModelDocument`.
- *
- * The `document` field carries the latest built state — diagnostics + root
- * are coherent with each other at the time the event fired.
  */
 export interface TransferDocumentUpdatedEvent<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
+    /** The latest built state: diagnostics and root are coherent with each other at the time the event fired. */
     document: TransferDocument<TTransfer, TDiagnostic>;
-    /** Stable identifier of the client that triggered the update. */
+    /**
+     * The client whose write this event echoes: the author of the version on a
+     * `'changed'`, and the unknown-client id on a `'rebuilt'`, which echoes no
+     * write. A recipient compares it against its own id to recognise its echo.
+     * The build that follows a document's release names the release id
+     * instead.
+     */
     sourceClientId: string;
+    /** See {@link TransferDocumentUpdateReason} for which reasons the framework sends. */
     reason: TransferDocumentUpdateReason;
+    /**
+     * The position of this event among the update and deletion events the
+     * server sent on this connection, which a watch's answer carries as of
+     * the moment it was taken: a greater one was sent later.
+     */
+    sequence: number;
 }
 /** Callback shape for `DataClientProtocol.onDocumentUpdated`. */
 export type TransferDocumentUpdatedListener<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> = (event: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>) => void;
 /**
- * Delivered on the data-server when a document was persisted to disk via
- * `DataServerProtocol.saveModelDocument`. Distinct from
- * {@link TransferDocumentUpdatedEvent}: subscribers that only care about
- * persistence (external sync, editor "saved" indicators, dirty-flag
- * clear) listen for this event family instead of filtering an update
- * stream for `reason: 'saved'`.
- *
- * The `document` field carries the post-save built state — same shape
- * the synchronous `saveModelDocument` RPC response returns, delivered
- * to subscribers (`DataClientProtocol.onDocumentSaved`) so non-caller
- * clients see the persistence event too.
+ * Delivered on the data-server when a subscribed document was saved to disk,
+ * whichever client saved it, an editor's save through the LSP head included.
+ * Distinct from {@link TransferDocumentUpdatedEvent}: subscribers that only
+ * care about persistence (external sync, editor "saved" indicators,
+ * dirty-flag clear) listen for this event family instead of filtering an
+ * update stream for `reason: 'saved'`.
  */
 export interface TransferDocumentSavedEvent<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
+    /** The latest built state, taken after the save. */
     document: TransferDocument<TTransfer, TDiagnostic>;
     /**
-     * The client whose `saveModelDocument` call produced this. Every subscriber
-     * receives the event including the originator, which already had the same
-     * state as the RPC response — compare against your own id to drop the echo
-     * rather than re-rendering from it.
+     * The client whose save produced this, also when another client wrote the
+     * persisted text: the caller of `saveModelDocument` or
+     * `persistModelDocument`, or `LANGUAGE_CLIENT_ID` for an editor's save
+     * through the LSP head. Every subscriber receives the event, the saving
+     * client included, so compare against your own id to drop the echo.
      */
     sourceClientId: string;
 }
 /** Callback shape for `DataClientProtocol.onDocumentSaved`. */
 export type TransferDocumentSavedListener<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> = (event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>) => void;
+/**
+ * Delivered on the data-server when a watched document's text starts or stops
+ * differing from its file, as the server last knew the file. The current
+ * answer rides on every transfer document the server sends as `text.dirty`;
+ * this carries only its changes, so a client that follows it needs no rebuild
+ * to learn of a save.
+ */
+export interface TransferDocumentDirtyChangedEvent {
+    /** Canonical URI, keyed as the subscription is. */
+    readonly uri: string;
+    /**
+     * The text the answer was decided on. It is sent before that text is
+     * built, so a `text.version` ahead of the model a client holds means an
+     * update at this version or a later one follows. Absent when the document
+     * no longer exists, or when the build that follows its release failed.
+     */
+    readonly text?: TextState;
+}
+/** Callback shape for `DataClientProtocol.onDocumentDirtyChanged`. */
+export type TransferDocumentDirtyChangedListener = (event: TransferDocumentDirtyChangedEvent) => void;
 /**
  * Delivered on the data-server when a document's backing file was removed.
  * Carries no document, and cannot: the state a
@@ -99,11 +129,25 @@ export type TransferDocumentSavedListener<TTransfer extends TransferElement, TDi
  * A watch survives the deletion, so a file that comes back resumes delivering
  * `onDocumentUpdated` to the same subscribers with no re-subscription. A
  * client that responds by closing its editor releases the watch through
- * `closeModelDocument` as usual.
+ * `closeModelDocument` as usual, and `deleteModelDocument` releases the
+ * deleting session's own.
  */
 export interface TransferDocumentDeletedEvent {
     /** Canonical URI of the removed document, keyed as the subscription is. */
     readonly uri: string;
+    /**
+     * The session whose `deleteModelDocument` removed the file, so it can tell
+     * its own deletion from another's; the unknown-client id for a file
+     * removed outside any session, as a file watcher reports one, and for one
+     * a `DataConnection` found gone after a reconnect, which no event named.
+     */
+    readonly sourceClientId: string;
+    /**
+     * The position of this event among the update and deletion events the
+     * server sent on this connection, as on an update; absent on a deletion a
+     * `DataConnection` found after a reconnect, which the server never sent.
+     */
+    readonly sequence?: number;
 }
 /** Callback shape for `DataClientProtocol.onDocumentDeleted`. */
 export type TransferDocumentDeletedListener = (event: TransferDocumentDeletedEvent) => void;

package/lib/data/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/data/events.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,4BAA4B,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,WAAW,4BAA4B,CAC1C,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB;IAE3D,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACnD,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,4BAA4B,CAAC;CACvC;AAED,iEAAiE;AACjE,MAAM,MAAM,+BAA+B,CACxC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,IAC1D,CAAC,KAAK,EAAE,4BAA4B,CAAC,SAAS,EAAE,WAAW,CAAC,KAAK,IAAI,CAAC;AAE1E;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,0BAA0B,CACxC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB;IAE3D,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACnD;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;CACzB;AAED,+DAA+D;AAC/D,MAAM,MAAM,6BAA6B,CACtC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,IAC1D,CAAC,KAAK,EAAE,0BAA0B,CAAC,SAAS,EAAE,WAAW,CAAC,KAAK,IAAI,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,4BAA4B;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACvB;AAED,iEAAiE;AACjE,MAAM,MAAM,+BAA+B,GAAG,CAAC,KAAK,EAAE,4BAA4B,KAAK,IAAI,CAAC;AAE5F;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,2BAA2B;IACzC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,gEAAgE;AAChE,MAAM,MAAM,8BAA8B,GAAG,CAAC,KAAK,EAAE,2BAA2B,KAAK,IAAI,CAAC;AAE1F;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAElE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAoB,CAAC,QAAQ,SAAS,OAAO,GAAG,OAAO;IACrE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;CACvC;AAED,iEAAiE;AACjE,MAAM,MAAM,uBAAuB,CAAC,QAAQ,SAAS,OAAO,GAAG,OAAO,IAAI,CAAC,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/data/events.ts"],"names":[],"mappings":"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"}

package/lib/data/requests.d.ts

@@ -6,7 +6,7 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import type { TransferSaveArgs, TransferUpdateArgs } from '../model-service/args';
+import type { BaseVersion } from '../model-service/base-version';
 /** Get the current state of a single document. The server returns the latest built version. */
 export interface GetModelDocumentArgs {
     /** Document URI. */
@@ -37,27 +37,100 @@ export interface GetProjectForUriArgs {
     uri: string;
 }
 /**
- * Update a document's content. Wire-side projection of the facade's
- * {@link TransferUpdateArgs}; structurally identical so the data-server RPC
- * handler can forward straight to the in-process `ModelService.update`
- * without an args mapping.
+ * Update a document the session `clientId` has open. Generic over `TTransfer`
+ * so adopters parameterise the structured shape against their grammar's
+ * transfer-model overlay; passing a string is always allowed.
  */
-export type TransferUpdateDocumentArgs<TTransfer> = TransferUpdateArgs<TTransfer>;
-/** Persist a document to disk. Wire-side projection of {@link TransferSaveArgs}. */
-export type TransferSaveDocumentArgs<TTransfer> = TransferSaveArgs<TTransfer>;
+export interface TransferUpdateDocumentArgs<TTransfer> {
+    /** Document URI. */
+    uri: string;
+    /** The id of a live session registered on this connection. */
+    clientId: string;
+    /** The whole structured model root, or its serialised textual form. */
+    model: TTransfer | string;
+    /**
+     * What this write was authored against. A `ModelVersion` is compared
+     * against the server's current text-document version for `uri` and throws
+     * `ConflictError` on mismatch; `'any'` writes unconditionally.
+     *
+     * **Required so that an ungated write is a decision rather than an
+     * omission.** An optional gate is indistinguishable from a forgotten one at
+     * the call site, and a file of twenty writes hides the one that lost the
+     * field. Nothing else here can see that, since the defect is an absence.
+     */
+    baseVersion: BaseVersion;
+    /**
+     * Set by a session's restore after a reconnect, which sends its last write
+     * again. A model the server took was written over text that parsed, so it
+     * is written even over text that does not, as it was before the
+     * reconnect. Any other model write over such text is refused with
+     * `DocumentSyntaxError`, a save's even when it sets this.
+     */
+    restore?: boolean;
+}
+/** Update a document the session `clientId` has open, then persist it to disk. */
+export interface TransferSaveDocumentArgs<TTransfer> extends Omit<TransferUpdateDocumentArgs<TTransfer>, 'restore'> {
+}
+/** Persist the text the server holds for a document the session `clientId` has open, without writing a model. */
+export type TransferPersistDocumentArgs = Omit<TransferUpdateDocumentArgs<never>, 'model' | 'restore'>;
+/** Delete a document the session `clientId` has open: its file, then the document. */
+export type TransferDeleteDocumentArgs = Omit<TransferUpdateDocumentArgs<never>, 'model' | 'restore'>;
+/** Register a client session on the connection. */
+export interface CreateSessionArgs {
+    /** The session's id, minted by the client; unique in the server process while the session is live. */
+    clientId: string;
+    /** What the participant is; kept as the server session's `label`. */
+    label?: string;
+    /**
+     * A token the client keeps for the session's lifetime. It is no secret: the
+     * wire carries no authentication. A later `createSession` for the same id
+     * carrying the same token, from any connection, ends the session it names
+     * and registers the id afresh, so a client whose connection dropped before
+     * the server noticed can register again. Without it the id stays refused
+     * until the server notices.
+     */
+    resumeToken?: string;
+}
+/** End a client session registered on the connection. */
+export interface CloseSessionArgs {
+    clientId: string;
+}
+/** Create a document that exists nowhere yet, open for the session creating it. */
+export interface CreateModelDocumentArgs {
+    uri: string;
+    /** The id of a live session registered on this connection. */
+    clientId: string;
+    /** The document's initial content; it reaches disk with the first save. */
+    text: string;
+}
+/**
+ * Write several documents a session has open, all or none. `clientId` is on
+ * the set rather than on each update: an id per update would allow a set
+ * mixing clients, which the server would have to refuse.
+ */
+export interface TransferUpdateDocumentsArgs<TTransfer> {
+    /** The id of a live session registered on this connection. */
+    clientId: string;
+    /**
+     * One entry per document: a set naming one twice, by any spellings that
+     * share its canonical URI, is refused.
+     */
+    updates: Omit<TransferUpdateDocumentArgs<TTransfer>, 'clientId'>[];
+}
 /**
  * Identifies a per-document watch on the data server. Shared by both
  * `watchModelDocument` and `unwatchModelDocument` — the `(uri, clientId)`
  * pair is the watch key, so unwatching names the same watch that was
  * started. The `clientId` identifies the originator the same way it does
- * on facade-side mutations (`TransferUpdateArgs.clientId`,
- * `TransferSaveArgs.clientId`): it keys the per-`(uri, clientId)` watch
- * bucket so multiple watchers on the same wire stay distinct, AND it lets
+ * on the document writes (`TransferUpdateDocumentArgs.clientId`,
+ * `TransferSaveDocumentArgs.clientId`): it keys the per-`(uri, clientId)`
+ * watch bucket so multiple watchers on the same wire stay distinct, AND it lets
  * each watcher recognise its own echo on inbound `onDocumentUpdated` events
  * (the wire shape's `sourceClientId` carries the originating mutation's
  * `clientId`).
  */
 export interface WatchModelDocumentArgs {
+    /** Any spelling that the document URI policy maps to the document. */
     uri: string;
     /** Stable identifier for the watching client. */
     clientId: string;

package/lib/data/requests.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"requests.d.ts","sourceRoot":"","sources":["../../src/data/requests.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAElF,+FAA+F;AAC/F,MAAM,WAAW,oBAAoB;IAClC,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IAClC,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,MAAM,0BAA0B,CAAC,SAAS,IAAI,kBAAkB,CAAC,SAAS,CAAC,CAAC;AAElF,oFAAoF;AACpF,MAAM,MAAM,wBAAwB,CAAC,SAAS,IAAI,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAsB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"requests.d.ts","sourceRoot":"","sources":["../../src/data/requests.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEjE,+FAA+F;AAC/F,MAAM,WAAW,oBAAoB;IAClC,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IAClC,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B,CAAC,SAAS;IAClD,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC;IAC1B;;;;;;;;;OASG;IACH,WAAW,EAAE,WAAW,CAAC;IACzB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,kFAAkF;AAElF,MAAM,WAAW,wBAAwB,CAAC,SAAS,CAAE,SAAQ,IAAI,CAAC,0BAA0B,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAAG;AAEtH,iHAAiH;AACjH,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAAC,0BAA0B,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC,CAAC;AAEvG,sFAAsF;AACtF,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAAC,0BAA0B,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC,CAAC;AAEtG,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAC/B,sGAAsG;IACtG,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC9B,QAAQ,EAAE,MAAM,CAAC;CACnB;AAED,mFAAmF;AACnF,MAAM,WAAW,uBAAuB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B,CAAC,SAAS;IACnD,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,EAAE,IAAI,CAAC,0BAA0B,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC,EAAE,CAAC;CACrE;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAsB;IACpC,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;CACnB"}