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(text);
+process.stdout.write(ansiEscapes.cursorPrevLine);
+console.log(ansiEscapes.iTerm.annotation('this is an annotation', {length: text.length}));
+console.log();

index.d.ts

@@ -25,6 +25,28 @@ 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;
+
+		/**
+		If `true`, create a "hidden" annotation. Annotations created this way can be shown using the "Show Annotations" iTerm command.
+		*/
+		readonly isHidden?: boolean;
+	}
 }
 
 declare const ansiEscapes: {
@@ -193,6 +215,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');
+		}
+		message = message.replace(/\|/g, '\|');
+		ret += options.isHidden ? '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;
+	}
 };

index.test-d.ts

@@ -45,3 +45,4 @@ expectType<string>(
 	ansiEscapes.image(new Buffer(1), {preserveAspectRatio: false})
 );
 expectType<string>(ansiEscapes.iTerm.setCwd('/foo/bar'));
+expectType<string>(ansiEscapes.iTerm.annotation('foo bar'));

readme.md

@@ -175,6 +175,50 @@ 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?)
+
+Create an annotation.  An annotation looks like this when shown:
+
+![screenshot of iTerm annotation](https://user-images.githubusercontent.com/924465/64382136-b60ac700-cfe9-11e9-8a35-9682e8dc4b72.png)
+
+See the [iTerm Proprietary Escape Codes documentation](https://iterm2.com/documentation-escape-codes.html) for more information.
+
+#### message
+
+Type: `string`
+
+Message to display within annotation.
+
+#### options
+
+Type: `object`
+
+Options to control display of annotation.
+
+##### length
+
+Type: `number`
+
+Nonzero number of cells to annotate. Defaults to remainder of line.
+
+##### x
+
+Type: `number`
+
+Starting X coordinate; defaults to cursor position; must be used with `y` and `length`.
+
+##### y
+
+Type: `number`
+
+Starting Y coordinate; defaults to cursor position; must be used with `x` and `length`.
+
+##### isHidden
+
+Type: `boolean`
+Default: `false`
+
+If `true`, create a "hidden" annotation. Annotations created this way can be shown using the "Show Annotations" iTerm command.
 
 ## Related