add iTerm.annotation() method

See https://iterm2.com/documentation-escape-codes.html

example.js

@@ -3,3 +3,9 @@ const fs = require('fs');
 const ansiEscapes = require('.');
 
 console.log(ansiEscapes.image(fs.readFileSync('fixture.jpg'), {width: 15}));
+
+const text = 'this text will be annotated';
+console.log(ansiEscapes.cursorSavePosition);
+console.log(text);
+console.log(ansiEscapes.cursorRestorePosition);
+console.log(ansiEscapes.iTerm.annotation('this is an annotation', {length: text.length}));

index.d.ts

@@ -25,6 +25,23 @@ declare namespace ansiEscapes {
 
 		readonly preserveAspectRatio?: boolean;
 	}
+
+	interface AnnotationOptions {
+		/**
+		Nonzero number of cells to annotate. Defaults to remainder of line
+		*/
+		readonly length?: number;
+
+		/**
+		Starting X coordinate; defaults to cursor position; must be used with `y` and `length`
+		 */
+		readonly x?: number;
+
+		/**
+		Starting Y coordinate; defaults to cursor position; must be used with `x` and `length`
+		*/
+		readonly y?: number;
+	}
 }
 
 declare const ansiEscapes: {
@@ -193,6 +210,15 @@ declare const ansiEscapes: {
 		@param cwd - Current directory. Default: `process.cwd()`.
 		*/
 		setCwd(cwd: string): string;
+
+		/**
+		Creates an escape code to display an "annotation" in iTerm2.
+
+		@param message - Message to display within annotation
+		@param options - Options to control display of annotation
+		@returns Escape code which will create an annotation when displayed in terminal
+		*/
+		annotation(message: string, options?: ansiEscapes.AnnotationOptions): string;
 	};
 
 	// TODO: remove this in the next major version

index.js

@@ -128,5 +128,26 @@ ansiEscapes.image = (buffer, options = {}) => {
 };
 
 ansiEscapes.iTerm = {
-	setCwd: (cwd = process.cwd()) => `${OSC}50;CurrentDir=${cwd}${BEL}`
+	setCwd: (cwd = process.cwd()) => `${OSC}50;CurrentDir=${cwd}${BEL}`,
+
+	annotation: (message, options = {}) => {
+		let ret = `${OSC}1337;`;
+		const hasX = typeof options.x !== 'undefined';
+		const hasY = typeof options.y !== 'undefined';
+		if ((hasX || hasY) && !(hasX && hasY && typeof options.length !== 'undefined')) {
+			throw new Error('`x`, `y` and `length` must be defined when `x` or `y` is defined');
+		}
+
+		ret += options.hidden ? 'AddHiddenAnnotation=' : 'AddAnnotation=';
+		if (options.length > 0) {
+			ret +=
+					(hasX ?
+						[message, options.length, options.x, options.y] :
+						[options.length, message]).join('|');
+		} else {
+			ret += message;
+		}
+
+		return ret + BEL;
+	}
 };

readme.md

@@ -175,6 +175,37 @@ Default: `process.cwd()`
 
 [Inform iTerm2](https://www.iterm2.com/documentation-escape-codes.html) of the current directory to help semantic history and enable [Cmd-clicking relative paths](https://coderwall.com/p/b7e82q/quickly-open-files-in-iterm-with-cmd-click).
 
+### iTerm.annotation(message, options?)
+
+#### message
+
+Type: `string`<br>
+
+The annotation contents.
+
+#### options
+
+Type: `object`
+
+##### length
+
+Type: `number`
+
+If present, annotate `length` number of cells.  Defaults to the remainder of the line.
+
+##### x
+##### y
+
+Type: `number`
+
+X/Y coordinates at which to begin annotation. If specified, `x`, `y`, *and* `length` are all required.
+
+##### hidden
+
+Type: `boolean`
+Default: `false`
+
+If `true`, create a "hidden" annotation.
 
 ## Related