@emailmaker/extensions-sandbox 0.9.0-dev.1

package/types.d.ts

@@ -0,0 +1,1002 @@
+/**
+ * Interface for a basic plugin.
+ * Defines the logic for initialization, execution, and cleanup.
+ */
+export interface IPlugin {
+  [name: string]: any;
+  
+  /**
+   * Plugin initialization method.
+   * This method is called immediately after the plugin is created.
+   * Can be synchronous or asynchronous.
+   */
+  init?(): Promise<void> | void;
+
+  /**
+   * Method that is invoked after all plugins have been initialized.
+   * Useful for resolving circular dependencies between plugins.
+   */
+  afterInit?(): Promise<void> | void;
+
+  /**
+   * Plugin disposal method.
+   * This method is called before the plugin system is destroyed.
+   * Used for cleanup and releasing resources.
+   */
+  dispose?(): Promise<void> | void;
+}
+
+
+
+/**
+ * Class-based plugin constructor type.
+ * Defines a constructor that takes a plugin context instance and returns a plugin.
+ */
+export type PluginClassConstructor<Plugin extends IPlugin = IPlugin> = {
+  new(
+    instance: App,
+  ): Plugin;
+};
+
+/**
+ * Function-based plugin constructor type.
+ * Defines a function that takes a plugin context instance and returns a plugin or nothing (void).
+ */
+export type PluginFunctionConstructor<Plugin extends IPlugin = IPlugin> = (instance: App) => void | Plugin;
+
+/**
+ * General plugin constructor type.
+ * Can be either a class-based constructor or a function-based constructor.
+ */
+export type IPluginConstructor<Plugin extends IPlugin = IPlugin> = PluginClassConstructor<Plugin> | PluginFunctionConstructor<Plugin>;
+
+/**
+ * Extracts the instance type of a given plugin constructor.
+ */
+export type InstanceOfPluginType<PluginConstructor> =
+  PluginConstructor extends IPluginConstructor<infer X> ? X : never;
+
+
+
+
+
+/**
+ * The `App` class manages the plugin system within an iframe global context.
+ * It follows the Singleton pattern to ensure only one instance exists.
+ */
+export declare class App {
+
+  /**
+   * Retrieves the singleton instance of `App`.
+   * 
+   * @returns {App} The single instance of `App`.
+   */
+  static get instance(): App;
+
+  /**
+   * Registers a new plugin in the global registry.
+   *
+   * @template Key - The plugin key from `SandboxModules`.
+   * @param {Key} key - The unique identifier of the plugin.
+   * @param {PluginTypeMap[Key]} pluginConstructor - The constructor of the plugin.
+   * 
+   * @example
+   * ```ts
+   * App.registerPlugin('myPlugin', MyPlugin);
+   * ```
+   */
+  static registerPlugin<Key extends keyof PluginTypeMap>(
+    key: Key,
+    pluginConstructor: PluginTypeMap[Key]
+  ): void;
+
+  /**
+   * Retrieves an instance of a plugin by its key or constructor.
+   * If the plugin has not been created before, it will be instantiated.
+   *
+   * @param key - The key of a registered plugin or its constructor.
+   * @returns The instance of the requested plugin.
+   */
+  static use<Key extends keyof PluginTypeMap>(key: Key): InstanceOfPluginType<PluginTypeMap[Key]>;
+  static use<PluginConstructor extends IPluginConstructor>(key: PluginConstructor): InstanceOfPluginType<PluginConstructor>;
+  /**
+   * Retrieves an instance of a registered plugin by its key or constructor.
+   * 
+   * @param {keyof PluginTypeMap | IPluginConstructor<App>} key - The plugin key or constructor.
+   * @returns {IPlugin} The requested plugin instance.
+   */
+  static use(key: keyof PluginTypeMap | IPluginConstructor<App>): IPlugin;
+
+
+  /**
+   * Retrieves an instance of a plugin by its key or constructor.
+   * If the plugin has not been created before, it will be instantiated.
+   *
+   * @param key - The key of a registered plugin or its constructor.
+   * @returns The instance of the requested plugin.
+   */
+  use<Key extends keyof PluginTypeMap>(key: Key): InstanceOfPluginType<PluginTypeMap[Key]>;
+  use<PluginConstructor extends IPluginConstructor<this>>(key: PluginConstructor): InstanceOfPluginType<PluginConstructor>;
+
+  /**
+   * Retrieves an instance of a registered plugin by its key or constructor.
+   * 
+   * @param {keyof PluginTypeMap | IPluginConstructor<App>} key - The plugin key or constructor.
+   * @returns {IPlugin} The requested plugin instance.
+   */
+  use(key: keyof PluginTypeMap | IPluginConstructor<App>): IPlugin;
+
+  /**
+   * Disposes of all active plugins.
+   * This should be called before terminating `App` to release resources.
+   * 
+   * @example
+   * ```ts
+   * app.dispose();
+   * ```
+   */
+  dispose(): void;
+}
+
+
+export interface PluginTypeMap {
+  /**
+   * API for interacting with the `MessageService`.
+   * Provides methods to send and receive messages, as well as manage event listeners.
+   */
+  MessageService: () => MessageService;
+  /**
+   * SyncService provides methods to synchronize and manage HTML document structures.
+   */
+  SyncService:  () => SyncService;
+  /**
+   * Internal synchronization service for documents.
+   */
+  SyncServiceInternals:  () => SyncServiceInternals;
+  /**
+   * Represents a text document.
+   */
+  TextDocument:  () => ITextDocument;
+  /**
+   * Provides mapping functionalities for document text.
+   */
+  Mapping:  () => DocumentMapping;
+  /**
+   * Represents the focus state of the editor.
+   */
+  FocusState:  () => FocusState;
+}
+
+
+type MayBePromise<T> = T | Promise<T>;
+
+export type Identifier<Type0 = any, Type1 = any, Type2 = any> = { type0?: Type0; type1: Type1; type2: Type2 } & string;
+
+export interface IDisposable {
+  dispose(): void;
+}
+
+/**
+ * API for interacting with the `MessageService`.
+ * Provides methods to send and receive messages, as well as manage event listeners.
+ */
+export interface MessageService {
+
+  // /**
+  //  * Creates an instance of the Message Service API.
+  //  *
+  //  * @param {BaseEditor} editor - The editor instance used to obtain the message service.
+  //  */
+  // constructor(editor: BaseEditor);
+
+  /**
+   * Sends a message through `MessageService`.
+   *
+   * @template Type - The type of data being sent in the message.
+   * @param {Identifier<Type>} messageTypeId - The identifier for the message type.
+   * @param {Type} data - The payload to be sent in the message.
+   * @param {boolean} [queued] - Optional parameter indicating whether the message should be queued.
+   * @example
+   * ```ts
+   * messageServiceApi.send('USER_LOGGED_IN', { userId: 123 });
+   * ```
+   */
+  send<Type>(messageTypeId: Identifier<Type>, data: Type, queued?: boolean): void;
+
+  /**
+   * Sends a message without specifying a message type identifier.
+   *
+   * @param {any} data - The payload to be sent in the message.
+   * @param {boolean} [queued] - Optional parameter indicating whether the message should be queued.
+   */
+  send(data: any, queued?: boolean): void;
+
+  /**
+   * Sends an asynchronous message and waits for a response.
+   *
+   * @template Type - The type of data being sent in the message.
+   * @template Result - The expected type of the response.
+   * @param {Identifier<Type, Result>} messageTypeId - The identifier for the message type.
+   * @param {Type} data - The payload to be sent in the message.
+   * @param {boolean} [queued=true] - Optional parameter indicating whether the message should be queued.
+   * @returns {Promise<Result | void>} - A promise resolving to the response result or `void` if no response is expected.
+   * @example
+   * ```ts
+   * const response = await messageServiceApi.sendAsync('FETCH_USER', { userId: 123 });
+   * console.log(response); // { name: "John Doe", age: 30 }
+   * ```
+   */
+  sendAsync<Type, Result>(
+    messageTypeId: Identifier<Type, Result>,
+    data: Type,
+    queued?: boolean,
+  ): Promise<Result | void>;
+
+  /**
+   * Adds a global event listener for message events.
+   *
+   * @param {(e: MessageEvent) => void} listener - The event listener function.
+   * @returns {IDisposable} - An object to remove the subscription.
+   */
+  addListener(listener: (e: MessageEvent) => void): IDisposable;
+
+  /**
+   * Adds a listener for a specific message type.
+   *
+   * @template Type - The type of data in the message.
+   * @param {Identifier<Type>} messageTypeId - The identifier for the message type.
+   * @param {(value: Type) => void} listener - The callback function to execute when the message is received.
+   * @param {number} [priority] - The priority of the listener (higher values execute earlier).
+   * @returns {IDisposable} - An object to remove the subscription.
+   * @example
+   * ```ts
+   * const dispose = messageServiceApi.addListener('USER_LOGGED_IN', (data) => {
+   *   console.log('User logged in:', data);
+   * });
+   *
+   * // To remove the listener:
+   * dispose();
+   * ```
+   */
+  addListener<Type = any>(
+    messageTypeId: Identifier<Type>,
+    listener: (value: Type) => void,
+    priority?: number,
+  ): IDisposable;
+
+  /**
+   * Adds an asynchronous listener for a specific message type.
+   *
+   * @template Type - The type of data in the message.
+   * @template Result - The expected return type from the listener.
+   * @param {Identifier<Type, Result>} messageTypeId - The identifier for the message type.
+   * @param {(value: Type) => MayBePromise<Result>} listener - The callback function that may return a promise.
+   * @param {number} [priority=0] - The priority of the listener.
+   * @returns {IDisposable} - An object to remove the subscription.
+   * @example
+   * ```ts
+   * const dispose = messageServiceApi.addListenerAsync('FETCH_DATA', async (request) => {
+   *   return await fetchDataFromServer(request);
+   * });
+   * ```
+   */
+  addListenerAsync<Type = any, Result = any>(
+    messageTypeId: Identifier<Type, Result>,
+    listener: (value: Type) => MayBePromise<Result>,
+    priority?: number,
+  ): IDisposable;
+
+  /**
+   * Adds a listener for the initialization event.
+   *
+   * @param {(target: unknown) => void} listener - The callback function.
+   * @param {boolean} [immediately=true] - Whether the callback should be triggered immediately if initialization has already occurred.
+   * @param {number} [priority=0] - The priority of the listener.
+   * @returns {IDisposable} - An object to remove the subscription.
+   */
+  onInit(listener: (target: unknown) => void, immediately?: boolean, priority?: number): IDisposable;
+
+  /**
+   * Checks whether initialization has been completed.
+   *
+   * @returns {boolean} - `true` if initialization is complete, otherwise `false`.
+   * @example
+   * ```ts
+   * if (messageServiceApi.isInited()) {
+   *   console.log("Message service is ready!");
+   * }
+   * ```
+   */
+  isInited(): boolean;
+}
+
+
+/**
+ * Represents different types of mutations that can occur in the document.
+ */
+export type MutationType = "Add" | "Remove" | "Attribute" | "Move" | "Update" | "Set" | "ClassList" | "Style" | "Hidden";
+
+export interface AddMutation<T> {
+  readonly type: "Add";
+  readonly parent: T | null;
+  readonly node: T;
+  readonly nextSibling?: T;
+}
+
+export interface RemoveMutation<T> {
+  readonly type: "Remove";
+  readonly node: T;
+}
+
+export interface AttributeMutation<T> {
+  readonly type: "Attribute";
+  readonly node: T;
+  readonly name: string;
+  readonly value?: string | null;
+}
+
+export interface UpdateMutation<T> {
+  readonly type: "Update";
+  readonly prev: T;
+  readonly next: T;
+}
+
+export interface MoveMutation<T> {
+  readonly type: "Move";
+  readonly parent: T | null;
+  readonly node: T;
+  readonly nextSibling?: T;
+}
+
+export interface SetMutation<T> {
+  readonly type: "Set";
+  readonly node: T;
+  readonly data: any;
+}
+
+export interface ClassListMutation<T> {
+  readonly type: "ClassList";
+  readonly node: T;
+  readonly addedClasses?: string[];
+  readonly removedClasses?: string[];
+}
+
+export interface StyleMutation<T> {
+  readonly type: "Style";
+  readonly node: T;
+  readonly value: string | null;
+}
+
+export interface HiddenMutation<T> {
+  readonly type: "Hidden";
+  readonly node: T;
+  readonly value: boolean;
+}
+
+export type Mutation<T> =
+  | AddMutation<T>
+  | RemoveMutation<T>
+  | AttributeMutation<T>
+  | UpdateMutation<T>
+  | MoveMutation<T>
+  | SetMutation<T>
+  | ClassListMutation<T>
+  | StyleMutation<T>
+  | HiddenMutation<T>;
+
+/**
+ * Interface for a disposable object.
+ */
+export interface IDisposable {
+  dispose(): void;
+}
+
+/**
+ * Defines a listener function that receives an array of summaries and returns either void or false.
+ * @param listener - Function that processes summaries.
+ * @param priority - Optional priority value for the listener.
+ * @returns An IDisposable instance.
+ */
+export interface Listener {
+  (listener: (value: Summary[]) => void | false, priority?: number): IDisposable;
+}
+/**
+ * Describes a collection of modifications applied to the DOM.
+ */
+export interface Summary {
+  /**
+   * A list of elements that are now present in the subtree with the specified attribute, 
+   * but were either previously missing from the subtree, lacked the attribute, or both.
+   */
+  added: Node[];
+
+  /**
+   * A list of elements that were previously in the subtree with the specified attribute, 
+   * but are now either removed from the subtree, no longer have the attribute, or both.
+   */
+  removed: Node[];
+
+  /**
+   * A list of nodes that have been moved from one parent to another.
+   */
+  reparented: Node[] | undefined;
+
+  /**
+   * Nodes that remain within the same subtree and have the same parent but 
+   * have changed their order within the parent's child list.
+   */
+  reordered: Node[] | undefined;
+
+  /**
+   * A list of elements that have remained in the subtree with the specified attribute, 
+   * but the value of that attribute has changed.
+   */
+  valueChanged: Node[] | undefined;
+
+  /**
+   * An object that tracks attribute changes. Each key corresponds to an attribute name 
+   * found in `elementAttributes`, and its value is an array of elements that remained 
+   * in the subtree and had their attribute values updated.
+   */
+  attributeChanged: Record<string, Element[]> | undefined;
+
+  /**
+   * A list of character data nodes that existed before and still exist, 
+   * but their text content has changed.
+   */
+  characterDataChanged: Node[] | undefined;
+
+  /**
+   * Retrieves the previous parent node of a given node. The node must be 
+   * included in the removed elements array; otherwise, an error is thrown.
+   *
+   * @param node The node whose previous parent is being retrieved.
+   */
+  getOldParentNode(node: Node): Node;
+
+  /**
+   * Returns the previous value of a specified attribute for an element. 
+   * The element must be included in the `valueChanged` array; otherwise, an error is thrown.
+   *
+   * @param element The element whose previous attribute value is being retrieved.
+   * @param name The name of the attribute to retrieve the previous value for.
+   */
+  getOldAttribute(element: Node, name: string): string;
+
+  /**
+   * Returns the previous text content of a given node. 
+   * The node must be in the `valueChanged` array; otherwise, an error is thrown.
+   *
+   * @param node The node whose previous character data is being retrieved.
+   */
+  getOldCharacterData(node: Node): string;
+
+  /**
+   * Returns the previous sibling of a given node. 
+   * The node must be included in the `reordered` array; otherwise, an error is thrown.
+   *
+   * @param node The node whose previous sibling is being retrieved.
+   */
+  getOldPreviousSibling(node: Node): Node;
+}
+
+/**
+ * Represents an event mechanism that allows adding listeners with an optional priority.
+ *
+ * @template T The type of value emitted by the event.
+ * @param listener A function that receives the event value. If it returns `false`, the event propagation stops.
+ * @param priority A number indicating the priority of the listener. Higher values mean higher priority (default is `0`).
+ * @returns An `IDisposable` that allows removing the listener.
+ */
+export type Event<T> = (listener: (value: T) => void | false, priority: number) => IDisposable;
+
+/**
+ * Defines different types of nodes that can exist in a document structure.
+ */
+export type NodeType = 
+  /** Represents a generic HTML node. */
+  'html' |
+  
+  /** Represents a standard element node. */
+  'element' |
+  
+  /** Represents the root node of a document. */
+  'root' | 
+  
+  /** Represents a comment node. */
+  'comment' |
+  
+  /** Represents a document type declaration. */
+  'doctype';
+
+/**
+ * Represents a synchronized node in a document structure.
+ */
+export interface SyncNode {
+  start: number;
+  end: number;
+  children: SyncNode[];
+  /** The textual content of the node (if applicable). */
+  content?: string;
+
+  /** The type of the node (default is `ELEMENT`). */
+  type: any;
+
+  /** The tag name of the node, if applicable. */
+  tag: string | undefined;
+
+  /** Indicates whether the node is self-closing (default is `false`). */
+  closed?: boolean;
+
+  /** The position where the start tag ends, if known. */
+  startTagEnd: number | undefined;
+
+  /** The position where the end tag starts, if known. */
+  endTagStart: number | undefined;
+
+  /** A collection of attributes associated with the node. */
+  attributes: { [name: string]: string | null } | undefined;
+
+  /** Returns an array of attribute names present in the node. */
+  readonly attributeNames: string[];
+
+  /** Identifies the source that created the node (if applicable). */
+  createdBy?: string;
+
+  /** Indicates whether the node has been modified. */
+  isDirty?: boolean;
+
+  /** Returns the root node of the document tree. */
+  readonly root: SyncNode;
+
+  /**
+   * Checks if the node has the same tag name as the given lowercase tag.
+   *
+   * @param tagInLowerCase The tag name to compare (in lowercase).
+   * @returns `true` if the tag names match, otherwise `false`.
+   */
+  isSameTag(tagInLowerCase: string | undefined): boolean;
+
+  /** Retrieves the first child node, if present. */
+  readonly firstChild: SyncNode | undefined;
+
+  /** Retrieves the last child node, if present. */
+  readonly lastChild: SyncNode | undefined;
+
+  /**
+   * Finds the closest node located before the specified offset.
+   *
+   * @param offset The position to search before.
+   * @returns The nearest node before the given offset.
+   */
+  findNodeBefore(offset: number): SyncNode;
+
+  /**
+   * Finds the node located at the specified offset.
+   *
+   * @param offset The exact position to search.
+   * @returns The node found at the given offset.
+   */
+  findNodeAt(offset: number): SyncNode;
+
+  /**
+   * Searches for a node that matches the given predicate.
+   *
+   * @param predicate A function that returns `true` for the desired node.
+   * @returns The first node that satisfies the predicate, or `undefined` if none match.
+   */
+  find(predicate: (node: SyncNode) => boolean | undefined): SyncNode | undefined;
+
+  /**
+   * Finds the closest ancestor node that satisfies the given condition.
+   *
+   * @param predicate A function that returns `true` for the desired ancestor.
+   * @returns The nearest ancestor node that meets the condition, or `undefined` if none are found.
+   */
+  closest(predicate: (node: SyncNode) => boolean): SyncNode | undefined;
+
+  /** Retrieves all ancestor nodes of the current node. */
+  parents(): SyncNode[];
+
+  /**
+   * Finds the closest matching node from the root, optionally including the current node.
+   *
+   * @param predicate A function that determines whether a node is a match.
+   * @param self Whether to include the current node in the search (default is `true`).
+   * @returns The closest matching node, or `undefined` if none are found.
+   */
+  closestFromRoot(predicate: (node: SyncNode) => boolean, self?: boolean): SyncNode | undefined;
+
+  /**
+   * Determines whether the current node contains the given node as a descendant.
+   *
+   * @param node The node to check.
+   * @returns `true` if the given node is a descendant, otherwise `false`.
+   */
+  contains(node: SyncNode): boolean;
+
+  /**
+   * Creates a copy of the current node.
+   *
+   * @param parent The parent node for the clone (default is `undefined`).
+   * @param startOffset The offset where the clone should begin (default is `this.start`).
+   * @param deep Whether to perform a deep clone, including child nodes (default is `true`).
+   * @returns A new `SyncNode` instance that is a copy of the original.
+   */
+  clone(parent: SyncNode | undefined, startOffse?: number, deep?: boolean): SyncNode;
+}
+
+/**
+ * SyncService provides methods to synchronize and manage HTML document structures.
+ */
+export interface SyncService {
+  /**
+   * Starts a text update session.
+   * This method should be called before making multiple text changes to improve performance.
+   */
+  beginTextUpdate(): void;
+
+  /**
+   * Ends a text update session.
+   * Should be called after making multiple text changes to apply them efficiently.
+   */
+  endTextUpdate(): void;
+
+  /**
+   * Commits all pending document changes.
+   * @param pushUndoStop - Whether to push an undo stop.
+   * @param locked - Whether the commit should be locked.
+   * @returns A promise that resolves when the commit is complete.
+   */
+  commit(pushUndoStop?: boolean, locked?: boolean): Promise<void>;
+
+  /**
+   * Retrieves the mapped parent node of a given node.
+   * @param node - The node whose mapped parent is to be found.
+   * @returns The mapped parent node if available; otherwise, `undefined`.
+   */
+  getMappedParent(node: Node | null): Node | undefined;
+
+  /**
+   * Retrieves the context node of a given node.
+   * @param node - The node whose context is to be determined.
+   * @returns The corresponding context node.
+   */
+  getContext(node: Node): Node;
+
+  /**
+   * Checks whether a given node is inside an external document.
+   * @param node - The node to check.
+   * @returns `true` if the node is in an external document; otherwise, `false`.
+   */
+  isInExternal(node: Node): boolean;
+
+  /**
+   * Determines if a given node is visible in the document.
+   * @param node - The node to check.
+   * @returns `true` if the node is visible; otherwise, `false`.
+   */
+  isVisible(node: Node): boolean;
+
+  /**
+   * Retrieves the closest visible ancestor node of a given node.
+   * @param node - The node to check.
+   * @returns The closest visible node if available; otherwise, `undefined`.
+   */
+  getVisibleNode(node: Node): Node | undefined;
+
+  /**
+   * Corrects the structure of given nodes in the document.
+   * @param nodes - The list of tree nodes to be corrected.
+   */
+  correctNodes(nodes: SyncNode[]): void;
+
+  /**
+   * Gets the inner HTML of a given node.
+   * @param element - The node whose inner HTML should be retrieved.
+   * @returns The inner HTML string.
+   */
+  getInnerHtml(element: Node): string;
+
+  /**
+   * Gets the outer HTML of a given node.
+   * @param element - The node whose outer HTML should be retrieved.
+   * @returns The outer HTML string.
+   */
+  getOuterHtml(element: Node): string;
+
+  /**
+   * Sets the inner HTML of a given node.
+   * @param element - The node whose inner HTML should be updated.
+   * @param innerHTML - The new inner HTML content.
+   */
+  setInnerHtml(element: Node, innerHTML: string): void;
+
+  /**
+   * Retrieves a document element at a given position.
+   * @param position - The position in the document.
+   * @returns The corresponding node if found; otherwise, `undefined`.
+   */
+  getElementByPosition(position: number): Node | undefined;
+
+  /**
+   * Retrieves the text range of a given element.
+   * @param node - The node whose range is to be found.
+   * @param findParent - If `true`, will search for the nearest parent with a defined range.
+   * @returns The range if found; otherwise, `undefined`.
+   */
+  getRangeByElement(node: Node, findParent?: boolean): IRange | undefined;
+
+  /**
+   * Event triggered before a document change occurs.
+   */
+  readonly beforeChange: Event<{
+    domMutations: Mutation<Node>[];
+    treeMutations: Mutation<SyncNode>[];
+  }>;
+
+  /**
+   * Event triggered before committing changes.
+   */
+  readonly beforeCommit: Event<void>;
+
+  /**
+   * Event triggered when a native mutation occurs.
+   */
+  readonly onChange: Event<Summary[]>;
+
+  /**
+   * Event triggered when the document is refreshed.
+   */
+  readonly onRefresh: Event<void>;
+}
+
+
+export interface Edit {
+  range: IRange;
+  text: string;
+}
+
+/**
+ * Internal synchronization service for documents.
+ */
+export interface SyncServiceInternals {
+  /**
+   * Applies edits to the document.
+   * @param source The source of the edits.
+   * @param edits The list of edits.
+   */
+  applyEdits(source: any, edits: Edit[]): void;
+
+  /**
+   * Corrects the offset in the document text.
+   * @param offset The original offset.
+   * @param invert Whether to invert the correction.
+   * @returns The corrected offset.
+   */
+  correctOffset(offset: number, invert?: boolean): number;
+
+  /**
+   * Corrects the text range in the document.
+   * @param range The original range.
+   * @param invert Whether to invert the correction.
+   * @returns The corrected range.
+   */
+  correctRange(range: { start: number, end: number }, invert?: boolean): IRange;
+
+  /**
+   * Saves document changes.
+   * @param pushUndoStop Whether to record an undo stop.
+   * @returns Whether the save was successful.
+   */
+  saveChanges(pushUndoStop?: boolean): boolean;
+
+  /**
+   * Asynchronously saves document changes.
+   * @param pushUndoStop Whether to record an undo stop.
+   * @returns A promise that resolves when the save is complete.
+   */
+  saveChangesAsync(pushUndoStop?: boolean): Promise<void>;
+
+  /**
+   * Checks if there are unsaved changes.
+   * @returns true if there are unsaved changes, otherwise false.
+   */
+  hasChanges(): boolean;
+
+  /**
+   * Event triggered when the document is ready.
+   */
+  onReady: Event<void>;
+}
+
+
+/**
+ * Represents a text change within a document.
+ */
+export interface TextChange {
+  /**
+   * The starting position of the original text.
+   */
+  readonly oldPosition: number;
+  
+  /**
+   * The original text before the change.
+   */
+  readonly oldText: string;
+  
+  /**
+   * The starting position of the new text.
+   */
+  readonly newPosition: number;
+  
+  /**
+   * The new text after the change.
+   */
+  readonly newText: string;
+
+  /**
+   * The length of the original text before the change.
+   */
+  readonly oldLength: number;
+  
+  /**
+   * The end position of the original text.
+   */
+  readonly oldEnd: number;
+
+  /**
+   * The length of the new text after the change.
+   */
+  readonly newLength: number;
+
+  /**
+   * The end position of the new text.
+   */
+  readonly newEnd: number;
+}
+
+/**
+ * Represents the data associated with an edit event.
+ */
+export type EditEventData = {
+  /**
+   * The source of the edit.
+   */
+  source: any;
+  
+  /**
+   * A list of text changes applied in the edit event.
+   */
+  changes: TextChange[];
+};
+
+/**
+ * Represents an event triggered when an edit occurs.
+ */
+export type EditEvent = Event<EditEventData>;
+
+/**
+ * Represents an event triggered when the document content changes.
+ */
+export type ChangedEvent = Event<EditEventData>;
+
+
+/**
+ * Represents a text document.
+ */
+export interface ITextDocument {
+  getText(range?: IRange): string;
+  /**
+   * Applies edits to the document.
+   * @param source The source of the edits.
+   * @param edits The list of edits to apply.
+   */
+  applyEdits(source: any, edits: Edit[]): void;
+
+  /**
+   * Event triggered when the document changes.
+   */
+  onChanged: ChangedEvent;
+
+  /**
+   * Creates a clone of the document.
+   * @returns A new instance of ITextDocument.
+   */
+  clone(): ITextDocument;
+}
+
+/**
+ * Represents the focus state of the editor.
+ */
+export interface FocusState {
+  /**
+   * Indicates whether the editor is currently in focus.
+   */
+  readonly isEditorInFocus: boolean;
+
+  /**
+   * Sets the focus state of the editor.
+   * @param focus Whether the editor should be focused.
+   */
+  setFocus(focus: boolean): void;
+
+  /**
+   * Asynchronously triggered when the editor loses focus.
+   * @param context Optional context.
+   * @returns A promise resolving with an array of summaries.
+   */
+  whenEditorLostFocusAsync(context?: any): Promise<Summary[]>;
+
+  /**
+   * Registers a callback to be executed when the editor loses focus.
+   * @param callback The function to be called with summaries.
+   * @param context Optional context.
+   */
+  whenEditorLostFocus(callback: (summaries: Summary[]) => void, context?: any): void;
+
+  /**
+   * Event listener triggered when the editor loses focus.
+   * @param listener The function to be executed.
+   * @param priority Optional priority of the listener.
+   * @returns A disposable object to remove the listener.
+   */
+  editorLostFocus(listener: (summaries: Summary[]) => void, priority?: number): IDisposable;
+}
+
+/**
+ * Represents a range of text.
+ */
+export interface IRange {
+  /**
+   * The start position of the range.
+   */
+  start: number;
+  
+  /**
+   * The end position of the range.
+   */
+  end: number;
+}
+
+/**
+ * Provides mapping functionalities for document text.
+ */
+export interface DocumentMapping {
+  /**
+   * Corrects an offset within the document.
+   * @param offset The original offset.
+   * @param inverse Whether to invert the correction.
+   * @returns The corrected offset.
+   */
+  correctOffset(offset: number, inverse?: boolean): number;
+
+  /**
+   * Corrects a range within the document.
+   * @param range The original range.
+   * @param inverse Whether to invert the correction.
+   * @returns The corrected range.
+   */
+  correctRange(range: IRange, inverse?: boolean): IRange;
+
+  /**
+   * Checks if a mapped element exists at the given position.
+   * @param position The position to check.
+   * @returns true if a mapped element exists, otherwise false.
+   */
+  isMappedElementInPosition(position: number): boolean;
+
+  /**
+   * Escapes special characters in the given text.
+   * @param text The text to escape.
+   * @returns The escaped text.
+   */
+  escape(text: string): string;
+
+  /**
+   * Unescapes special characters in the given text.
+   * @param text The text to unescape.
+   * @returns The unescaped text.
+   */
+  unescape(text: string): string;
+}