index.bs

<h1>Clipboard API and events</h1>

<pre class="metadata">
Shortname: clipboard-apis
Level: none
Group: webediting
Status: w3c/ED
TR: https://un5gmtkzgkj46tygt32g.julianrbryant.com/TR/clipboard-apis/
ED: https://un5gnp8dyv5rcyxcrjjbfp0.julianrbryant.com/clipboard-apis/
Previous Version: from biblio
Repository: w3c/clipboard-apis
!Explainer: <a href="https://github.com/w3c/clipboard-apis/blob/master/explainer.adoc">Async Clipboard API Explainer</a>
Editor: Rakesh Goulikar, Microsoft, ragoulik@microsoft.com, w3cid 153330
Editor: Rohan Raja, Microsoft, roraja@microsoft.com, w3cid 159843
Former Editor: Gary Kacmarcik, Google, garykac@google.com, w3cid 59482
Former Editor: Anupam Snigdha, Microsoft, snianu@microsoft.com, w3cid 126950
Former Editor: Hallvord R. M. Steen, Mozilla, hsteen@mozilla.com, w3cid 42065
Former Editor: Grisha Lyukshin, Microsoft, glyuk@microsoft.com, w3cid 78883
Abstract:
	This document describes APIs for accessing data on the system clipboard. It provides
	operations for overriding the default clipboard actions (cut, copy and paste), and
	for directly accessing the clipboard contents.
Status Text: <p> <strong>Changes to this document may be tracked at <a href="https://github.com/w3c/clipboard-apis">https://github.com/w3c/clipboard-apis</a>.</strong> </p>
</pre>

<pre class="anchors">
urlPrefix: https://un5nj90kzk5vf152hgyfw29h1eja2.julianrbryant.com/multipage/interaction.html#; type: dfn;
	text: drag data store mode
	text: drag data item kind
	text: drag data item type string
	text: concept dnd rw
	text: concept dnd ro
	text: concept dnd p
	text: focusable area
	text: dom anchor
urlPrefix: https://umn0mtkzgkj46tygt32g.julianrbryant.com/TR/html5/browsers.html#; type: dfn;
	text: allowed to show a popup
urlPrefix: https://un5n7d2gw1uu2ekwrpzy49h0br.julianrbryant.com/#; type: dfn;
	text: constructing events
url: https://un5gnp8dyv5rcyxcrjjbfp0.julianrbryant.com/permissions/#permissions-task-source; type: dfn;
	text: permission task source
url: https://un5gnp8dytprcem5tqpfy4k4ym.julianrbryant.com/privacy-principles/#dfn-partition; type: dfn;
	text: partition
	text: partitions
url: https://un5gc39u2f5vf152hgyfw29h1eja2.julianrbryant.com/#storage-key; type: dfn;
	text: storage key
url: https://un5gc39u2f5vf152hgyfw29h1eja2.julianrbryant.com/#obtain-a-storage-key-for-non-storage-purposes; type: dfn;
	text: obtain a storage key for non-storage purposes
</pre>

<pre class="biblio">
{
	"MICROSOFT-CLIP-OP": {
		"title": "About DHTML Data Transfer. Microsoft Developer Network.",
		"href": "https://un5pcb96wf5t1nyda79dnd8.julianrbryant.com/en-us/ie/ms537658(v=vs.94)"
	}
}
</pre>


<h2 id="secintro">Introduction</h2>

	<i>This section is non-normative.</i>

	This specification defines how the system clipboard is exposed to web applications.

	There are two general APIs described in this specification:

	* Clipboard Event API - This API provides a way to hook into the common clipboard
		operations of cutting, copying and pasting so that web application can
		adjust the clipboard data as required.

	* Async Clipboard API - This API provides direct access to read and write the
		clipboard data. Since this is considered to be a <a>powerful feature</a>,
		access to this API is controlled by a permission.

<h2 id="Cases">Use Cases</h2>

	<i>This section is non-normative.</i>

	<h3 id="change-default-clipboard-ops">Changing Default Clipboard Operations</h3>

		There are many scenarios where it is desireable to change the default clipboard
		operations (cut/copy/paste). Here are a few examples:

		<ul>
			<li><strong>Metadata</strong>
			When copying text from a repository of documents, it can be useful for the
			copied text to include metadata about the source of the copied content.

			<li><strong>Rich content editing</strong>
			When copying text which contains hyperlinks or other structure,
			it is often useful to be able to reformat the content to preserve
			important information.
			</li>

			<li><strong>Graphics with built-in semantics</strong>
			In order to make web applications which allow the manipulation of rich
			text, or of graphic content such as [[SVG11]], it is useful to provide a
			mechanism that allows for copying more than just the rendered content.
			</li>

			<li><strong>Mathematical information</strong>
			With content such as mathematics, simply copying rendered text and pasting
			it into another application generally leads to most of the semantics being
			lost. MathML often needs to be transformed to be copied as plain text, for
			example to make sure "to the power of" is shown with the caret "^" sign
			in a formula plain-text input. The XML source could also be placed in the
			clipboard with the appropriate transformation occurring at paste time.
			</li>
		</ul>

	<h3 id="remote-clipboard-sync">Remote Clipboard Synchronization</h3>

		For web applications that communicate with remote devices (e.g., remote access
		or remote shell applications), there is often a need for the clipboard data
		to be kept in sync between the two devices.

		One important aspect of this use case is that it requires access to the
		clipboard in the absense of a user gesture or interaction.

		<div class="example">
		To copy the clipboard data from a remote device to the local clipboard, a web
		application would take the remote clipboard data and then {{Clipboard/write()}}
		the data to the local clipboard.
		</div>

		<div class="example">
		To copy the local clipboard data to a remote device, a web application would
		listen for {{GlobalEventHandlers/clipboardchange}} events, {{Clipboard/read()}} from the clipboard
		whenever it is updated, and then send the new clipboard data to the remote device.
		</div>

	<h3 id="trigger-clipboard-actions">Trigger Clipboard Actions</h3>

		Applications that provide an alternate interface to a user agent sometimes need
		to be able to trigger clipboard actions in the user agent.

		As an example, consider a screen reader application that provides a more accessible
		interface to a standard web browser. While the reader can display content and
		allow the user to interact with it, actions like clipboard copy need
		to occur in the underlying browser to ensure that the clipboard content is set
		correctly (with any metadata added by the browser during copy).

<h2 id="terminolofy">Terminology</h2>

	The term <dfn>editable context</dfn> means any element that is either an
	[=editing host=], a textarea element, or an input element with its type
	attribute set to any of "text", "search", "tel",
	"url", "email", "password" or "number".


<h2 id="model">Model</h2>

	The platform provides a <dfn>system clipboard</dfn>.

	The [=system clipboard=] has a list of [=system clipboard item=]s that are collectively	called the <dfn>system clipboard data</dfn>.

	Each <dfn>system clipboard item</dfn> has a list of [=system clipboard representation=]s.

	Each <dfn>system clipboard representation</dfn> has a <dfn for="system clipboard representation">name</dfn>, which is a string, and <dfn for="system clipboard representation">data</dfn>, which is a sequence of bytes.

<h2 id="clipboard-events-and-interfaces">Clipboard Events</h2>

	<h3 id="clipboard-event-interfaces">Clipboard event interfaces</h3>

		The ClipboardEvent interface extends the {{Event}} interface.

		<div id="clipboardeventinit-idl">

		<pre class="idl" data-highlight="webidl">
		dictionary ClipboardEventInit : EventInit {
		  DataTransfer? clipboardData = null;
		};
		</pre>

		: <dfn for="ClipboardEventInit" data-export>clipboardData</dfn>
		:: A {{DataTransfer}} object to hold data and meta data related to the event.

		</div>
		<div id="clipboardevent-idl">

		<pre class="idl" data-highlight="webidl">
		[Exposed=Window]
		interface ClipboardEvent : Event {
		  constructor(DOMString type, optional ClipboardEventInit eventInitDict = {});
		  readonly attribute DataTransfer? clipboardData;
		};
		</pre>

		: <dfn for="ClipboardEvent" data-export>clipboardData</dfn>

		:: The clipboardData attribute is an instance of the {{DataTransfer}}
			interface which lets a script read and manipulate values on the system
			clipboard during user-initiated copy, cut and paste operations. The
			associated drag data store is a live but filtered view of the system
			clipboard, exposing [=mandatory data types=] the implementation knows
			the script can safely access. For synthetic events, the drag data store
			contains the data added by the script that created the event.
		:: The clipboardData object's {{DataTransfer/items}} and
			{{DataTransfer/files}} properties enable processing of multi-part or
			non-textual data from the clipboard.

		</div>

		The interface can be used to <a lt="constructing events">construct events</a>.
		An example is given below:

		<pre class="example javascript">
			var pasteEvent = new ClipboardEvent('paste');
			pasteEvent.clipboardData.items.add('My string', 'text/plain');
			document.dispatchEvent(pasteEvent);
		</pre>

		Note: Synthetic clipboard events will not actually modify the clipboard or
		the document. In other words, while the script above will fire a paste event,
		the data will not be pasted into the document.

		<!-- Issue: There should be a way a script can check if a clipboard format
		is registered and whether the implementation allows writing this format to
		the clipboard! event.clipboardData.isTypeSupported('mime/type')</em>?
		-->

	<h3 id="clipboard-event-definitions">Clipboard events</h3>

		<h4 id="clipboard-event-clipboardchange">The <dfn event for=GlobalEventHandlers>clipboardchange</dfn> event</h4>

			The {{GlobalEventHandlers/clipboardchange}} event fires whenever the contents of the
			[=system clipboard=] are changed. These changes could be due to any of the
			following (non-exhaustive):

			* User-initiated cut or copy actions
			* Scripts that use the [[#async-clipboard-api]] to write to the clipboard
			* Actions that update the clipboard outside the user agent

			<div class="algorithm" data-algorithm="fire-clipboardchange-event">
			<h5 id="h-fire-clipboardchange-event">To fire a clipboardchange event</h5>

			To <dfn export>fire a clipboardchange event</dfn> given a {{Document}} <var>document</var>:

			1. If <var>document</var> does not have [=sticky activation=] and <var>document</var> does not have permission to read from the clipboard, then return.

			2. Let <var>global</var> be <var>document</var>'s [=relevant global object=].

			3. If <var>document</var> has [=system focus=]:
				1. Let <var>types</var> be a list of [=mandatory data types=] available on the [=system clipboard=].
				2. Let <var>changeId</var> be the result of running [=generate a changeId=] given <var>document</var>.
				3. Let <var>eventInit</var> be a new {{ClipboardChangeEventInit}} dictionary with its {{ClipboardChangeEventInit/types}} member set to <var>types</var> and its {{ClipboardChangeEventInit/changeId}} member set to <var>changeId</var>.
				4. [=Fire an event=] named {{GlobalEventHandlers/clipboardchange}} at <var>global</var>, using {{ClipboardChangeEvent}}, with <var>eventInit</var>.
			4. If <var>document</var> does not have [=system focus=]:
				1. Set <var>document</var>'s <dfn for="Document">clipboardchange pending flag</dfn> to true.

			</div>

			<p class="note">User agents MAY choose to skip firing {{GlobalEventHandlers/clipboardchange}} events for clipboard changes that have been superseded by more recent changes before the event would be delivered. This optimization can improve performance in scenarios where clipboard changes occur in rapid succession, as delivering obsolete change notifications provides no value to web applications while consuming processing resources.</p>

			<div class="algorithm" data-algorithm="document-focus-steps">
			<h5 id="h-document-focus-steps">Document focus steps</h5>

			When a {{Document}} <var>document</var> gains [=system focus=]:

		1. If <var>document</var>'s [=Document/clipboardchange pending flag=] is true:
			1. Set <var>document</var>'s [=Document/clipboardchange pending flag=] to false.
			2. Let <var>types</var> be a list of [=mandatory data types=] available on the [=system clipboard=].
			3. Let <var>changeId</var> be the result of running [=generate a changeId=] given <var>document</var>.
			4. Let <var>eventInit</var> be a new {{ClipboardChangeEventInit}} dictionary with its {{ClipboardChangeEventInit/types}} member set to <var>types</var> and its {{ClipboardChangeEventInit/changeId}} member set to <var>changeId</var>.
			5. Let <var>global</var> be <var>document</var>'s [=relevant global object=].
			6. [=Fire an event=] named {{GlobalEventHandlers/clipboardchange}} at <var>global</var>, using {{ClipboardChangeEvent}}, with <var>eventInit</var>.			</div>

			For documents in nested browsing contexts, the {{GlobalEventHandlers/clipboardchange}} event fires independently in each {{Document}} based on its own focus state. A clipboard change will fire an event in the single document that has [=system focus=] (if that document has [=sticky activation=] or persistent clipboard permissions).

			<strong>Note:</strong> The <code>clipboardchange</code> event is only available after <a href="https://un5nj90kzk5vf152hgyfw29h1eja2.julianrbryant.com/multipage/interaction.html#sticky-activation">sticky activation</a>, unless the document has persistent permission to read from the clipboard. In user agents that support persistent clipboard permissions, sites with such permissions can receive <code>clipboardchange</code> events without sticky activation, as the permission already grants access to more sensitive clipboard data.

			The {{ClipboardChangeEvent/changeId}} provides a unique identifier for each clipboard change operation. For the same clipboard change, all windows and tabs with the same [=storage key=] will receive events with identical {{ClipboardChangeEvent/changeId}} values, enabling applications with multiple windows to deduplicate events and avoid redundant processing. The identifier is [=storage key=]-specific and does not provide cross-[=storage key=] correlation capabilities.

			The {{GlobalEventHandlers/clipboardchange}} event does not bubble and is not cancelable, as it
			is not triggered by a user action but rather by changes to the [=system clipboard=] state.

			<div id="clipboardchangeeventinit-idl">

			<pre class="idl" data-highlight="webidl">
			dictionary ClipboardChangeEventInit : EventInit {
				sequence&lt;DOMString&gt; types = [];
				bigint changeId = 0;
			};
			</pre>

			: <dfn for="ClipboardChangeEventInit" data-export>types</dfn>
			:: A sequence of {{DOMString}} representing the [=mandatory data types=] available on the [=system clipboard=].

			: <dfn for="ClipboardChangeEventInit" data-export>changeId</dfn>
			:: A {{bigint}} representing a unique identifier for the clipboard change operation.

			</div>

			<div id="clipboardchangeevent-idl">

			<pre class="idl" data-highlight="webidl">
			[Exposed=Window]
			interface ClipboardChangeEvent : Event {
				constructor(DOMString type, optional ClipboardChangeEventInit eventInitDict = {});
				readonly attribute FrozenArray&lt;DOMString&gt; types;
				readonly attribute bigint changeId;
			};
			</pre>

			: <dfn for="ClipboardChangeEvent" data-export>types</dfn>
			:: Returns a {{FrozenArray}} of {{DOMString}} objects indicating the [=mandatory data types=] 
				available on the [=system clipboard=] when the event was fired. [=Optional data types=] and
				custom formats are excluded to limit fingerprinting surface.

			: <dfn for="ClipboardChangeEvent" data-export>changeId</dfn>
			:: Returns a {{bigint}} representing a unique identifier for this specific clipboard change operation.
				This identifier is consistent across all windows and tabs with the same [=storage key=] for the same clipboard change,
				enabling applications to deduplicate events when multiple windows receive the same clipboard change notification.
				
				The {{ClipboardChangeEvent/changeId}} is a cryptographically derived 128-bit integer. The only guarantee is that after something is written to the clipboard, {{ClipboardChangeEvent/changeId}} will yield a different value than it did before the write operation.

			</div>

			<div class="algorithm" data-algorithm="clipboardchange-event-steps">
			<h5 id="h-clipboardchange-event-steps">ClipboardChangeEvent constructor steps</h5>

			The <dfn export for="ClipboardChangeEvent">ClipboardChangeEvent(type, eventInitDict)</dfn> constructor steps are:

			1. Set [=this=].{{ClipboardChangeEvent/types}} to a [=list/clone=] of <var ignore=''>eventInitDict</var>["{{ClipboardChangeEventInit/types}}"].
			2. Set [=this=].{{ClipboardChangeEvent/changeId}} to <var ignore=''>eventInitDict</var>["{{ClipboardChangeEventInit/changeId}}"].

			</div>

		<h5 id="h-changeid-generation">ChangeId Generation</h5>

	<div class="algorithm" data-algorithm="generate-changeid">

	To <dfn>generate a changeId</dfn> for a {{Document}} <var>document</var>:

	1. Let <var>globalChangeId</var> be a user agent-specific unique identifier representing the current state of the [=system clipboard=]. This identifier changes each time the [=system clipboard=] is modified, and is reset when the user agent restarts.

	2. Let <var>storageKey</var> be the result of running <a href="https://un5gc39u2f5vf152hgyfw29h1eja2.julianrbryant.com/#obtain-a-storage-key-for-non-storage-purposes">obtain a storage key for non-storage purposes</a> given <var>document</var>'s [=relevant settings object=].

	3. Let <var>storageKeyBytes</var> be some user agent-specific binary representation of <var>storageKey</var>.

	4. Let <var>hashedValue</var> be the result of applying a cryptographic hash function (such as SHA-256) to the concatenation of <var>globalChangeId</var> (as bytes) and <var>storageKeyBytes</var>.

	5. Return a 128-bit integer derived from <var>hashedValue</var> (for example, by taking the first 128 bits of the hash output).

	</div>

		<p class="note">The above algorithm ensures that documents from the same origin and with the same partitioning receive identical change IDs for the same clipboard modification, enabling proper event deduplication across multiple windows and tabs, while preventing cross-partition correlation that could be used for tracking. As Client-side Storage Partitioning changes are incorporated into the storage key definition, this approach will automatically provide anonymization across partitions.</p>

		<p class="note">The {{ClipboardChangeEvent/changeId}} does not persist across browser restarts, as the <var>globalChangeId</var> counter is reset when the user agent restarts. Similarly, when a user clears site data, the affected tabs should be refreshed, which causes event listeners to be re-attached and only receive future events with new change IDs.</p>

		Since synthetic {{GlobalEventHandlers/cut}} and {{GlobalEventHandlers/copy}} events do not update the [=system clipboard=],
		they will not trigger a "clipboardchange" event.

			<div class="example" id="example-clipboardchange-usage">
			The {{GlobalEventHandlers/clipboardchange}} event enables web applications to efficiently monitor
			clipboard changes and provide dynamic user interfaces based on available data formats:

			<pre class="javascript">
			// For applications with multiple windows, track processed change IDs to avoid duplication
			const processedChangeIds = new Set();

			// Listen for clipboard changes
			navigator.clipboard.addEventListener('clipboardchange', (e) => {
				// Deduplicate events across multiple windows using changeId
				if (processedChangeIds.has(e.changeId)) {
					return; // This change has already been processed
				}
				processedChangeIds.add(e.changeId);
				
				// Check what data types are available on the clipboard
				const hasText = e.types.includes('text/plain');
				const hasHTML = e.types.includes('text/html');
				const hasImage = e.types.includes('image/png');
				
				// Update UI based on available formats
				document.getElementById('paste-text-btn').disabled = !hasText;
				document.getElementById('paste-html-btn').disabled = !hasHTML;
				document.getElementById('paste-image-btn').disabled = !hasImage;
				
				// For remote desktop apps, sync clipboard to remote only once per change
				if (hasText || hasHTML || hasImage) {
					syncClipboardToRemote(e.changeId);
				}
			});

			// Alternatively, you can use the onclipboardchange property
			// navigator.clipboard.onclipboardchange = (e) => { ... };
			</pre>

		This event-driven approach is more efficient than polling the clipboard with methods like
		{{Clipboard/read()}} or {{Clipboard/readText()}} and works across browsers that require user activation
		for clipboard access, as the UI can react instantly to clipboard changes without waiting for a timer to fire.
		The {{ClipboardChangeEvent/changeId}} is particularly useful for applications with multiple windows,
		ensuring that each clipboard change is processed only once across all windows with the same [=storage key=].
		</div>		<h4 id="clipboard-event-copy">The <dfn event for=GlobalEventHandlers>copy</dfn> event</h4>

			When the user initiates a copy action, the user agent
			[=fire a clipboard event|fires a clipboard event=] named
			{{GlobalEventHandlers/copy}}.

			If the event is not canceled, the currently selected
			data will be copied to the [=system clipboard=].
			The current document selection is not affected.

			The {{GlobalEventHandlers/copy}} event bubbles, is cancelable, and is composed.

			See [[#copy-action]] for a detailed description of the processing model for
			this event.

			A synthetic {{GlobalEventHandlers/copy}} event can be manually constructed and dispatched, but it
			will not affect the contents of the [=system clipboard=].

		<h4 id="clipboard-event-cut">The <dfn event for=GlobalEventHandlers>cut</dfn> event</h4>

			When the user initiates a cut action, the user agent
			[=fire a clipboard event|fires a clipboard event=] named
			{{GlobalEventHandlers/cut}}.

			In an [=editable context=], if the event is not
			canceled the action will place the currently selected data on the
			[=system clipboard=] and remove the selection from the document.
			The {{GlobalEventHandlers/cut}} event fires before the selected data is removed. When
			the cut operation is completed, the selection is collapsed.

			In a non-[=editable context=], the {{ClipboardEvent/clipboardData}} will
			be an empty list. Note that the {{GlobalEventHandlers/cut}} event will still be fired
			in this case.

			The {{GlobalEventHandlers/cut}} event bubbles, is cancelable, and is composed.

			See [[#cut-action]] for a detailed description of the processing model for
			this event.

			A synthetic {{GlobalEventHandlers/cut}} event can be manually constructed and dispatched, but it
			will not affect the contents of the document or of the [=system clipboard=].

		<h4 id="clipboard-event-paste">The <dfn event for=GlobalEventHandlers>paste</dfn> event</h4>

			When a user initiates a paste action, the user agent
			[=fire a clipboard event|fires a clipboard event=] named
			{{GlobalEventHandlers/paste}}. The event fires before any clipboard data is inserted
			into the document.

			If the cursor is in an [=editable context=], the paste action will
			insert clipboard data in the most suitable format (if any) supported
			for the given context.

			The paste action has no effect in a non-[=editable context=],
			but the {{GlobalEventHandlers/paste}} event fires regardless.

			The {{GlobalEventHandlers/paste}} event bubbles, is cancelable, and is composed.

			See [[#paste-action]] for a detailed description of the processing model for
			this event.

			A synthetic {{GlobalEventHandlers/paste}} event can be manually constructed and dispatched, but it
			will not affect the contents of the document.

	<h3 id="integration-with-other-scripts-and-events">Integration with other scripts and events</h3>

		<h4 id="allow-modify-clipboard">Event handlers that are <dfn export>allowed to modify the clipboard</dfn></h4>

			Event handlers may write to the clipboard if any of the following is
			true:

			* The action which triggers the event is invoked from the user-agent's
				own user interface, e.g. from a "Copy" menu entry or shortcut key.
			* The action which triggers the event is invoked from a scripting thread
				which is [=allowed to show a popup=].

			The implementation <em>may</em> allow other trusted event types to
			modify the clipboard if the implementation authors believe that those
			event types are likely to express user intention. The implementation
			<em>may</em> also support configuration that trusts specific sites or
			apps to modify the clipboard regardless of the origin of the scripting
			thread.

			Synthetic {{GlobalEventHandlers/cut}} and {{GlobalEventHandlers/copy}} events <em>must not</em> modify data on the
			system clipboard.

		<h4 id="allow-read-clipboard">Event handlers that are <dfn>allowed to read from clipboard</dfn></h4>

			Event handlers may read data from the system clipboard if either of the
			following is true

			* The action that triggers the event is invoked from the user-agent's
				own user interface, e.g. a "Paste" menu entry or shortcut key.
			* The script that triggers the action is running on a site which through
				an implementation-dependant mechanism is given permission to read
				data from the clipboard.
			* The action that triggers the event is triggered in an app with
				permissions to read the clipboard.

			Synthetic {{GlobalEventHandlers/paste}} events <em>must not</em> give a script access to data on
			the real system clipboard.

		<h4 id="integration-with-rich-text-editing">Integration with rich text editing APIs</h4>

			If an implementation supports ways to execute clipboard commands through
			scripting, for example by calling the
			<code>document.execCommand()</code> method with the commands "cut",
			"copy" and "paste", the implementation <em>must</em> trigger the
			corresponding action, which again will dispatch the associated clipboard
			event.

			These are the steps to follow when triggering copy, cut or paste actions
			through a scripting API:

			1. Execute the corresponding action synchronously.
			1. Use the action's return value as the return value for the API call.

			Note: Copy and cut commands triggered through a scripting API will only
			affect the contents of the real clipboard if the event is dispatched
			from an event that is trusted and triggered by the user, or if the
			implementation is configured to allow this. Paste commands triggered
			through a scripting API will only fire paste events and give access to
			clipboard contents if the implementation is configured to allow this.
			How implementations can be configured to allow read or write access to
			the clipboard is outside the scope of this specification.

		<h4 id="otherevents">Interaction with other events</h4>

			If the clipboard operation is triggered by keyboard input, the
			implementation <em>must</em> fire the corresponding event that initiates
			the clipboard operation. The event is asynchronous but <em>must</em> be
			dispatched before <b>keyup</b> events for the relevant keys.

			The cut and paste actions <em>may</em> cause the implementation to
			dispatch other supported events, such as textInput, input, change,
			validation events, DOMCharacterDataModified and DOMNodeRemoved /
			DOMNodeInserted. Any such events are queued up to fire after processing
			of the cut/paste event is finished.

			The implementation <em>must not</em> dispatch other input-related events
			like textInput, input, change, and validation events in response to the
			copy operation.

		<h4 id="selection-mod">Event listeners that modify selection or focus</h4>

			If the event listener modifies the selection or [=focusable area=], the clipboard
			action <em>must</em> be completed on the modified selection.

<h2 id="clipboard-event-api">Clipboard Event API</h2>

	The Clipboard Event API allows you to override the default cut, copy
	and paste behavior of the user agent.

	Access to the clipboard is performed using the standard
	{{DataTransfer}} methods to mutate the {{DataTransfer/items}} on a
	{{ClipboardEvent}}'s {{ClipboardEvent/clipboardData}} attribute.
	One consequence of this is that these clipboard APIs can only
	access clipboard data in the context of a {{ClipboardEvent}} handler.

	Note: If you need to access the clipboard outside of a clipboard event
	handler, see [[#async-clipboard-api]].

	Note: The Clipboard Event APIs are synchronous, so they are limited in what they can
	do. Actions which are potentially blocking (like asking for permission or
	transcoding a image) are not supported by these APIs. See [[#async-clipboard-api]]
	for a more powerful API that can support blocking or other time-consuming
	actions.

	<h3 id="override-copy">Overriding the copy event</h3>

		To override the default {{GlobalEventHandlers/copy}} event behavior, a {{GlobalEventHandlers/copy}} event
		handler must be added and this event handler must call
		{{Event/preventDefault()}} to cancel the event.

		Canceling the event is required in order for the [=system clipboard=] to be
		updated with the data in {{ClipboardEvent/clipboardData}}.
		If the {{ClipboardEvent}} is not canceled, then the data from the
		current document selection will be copied instead.

		<pre class="example javascript">
		// Overwrite what is being copied to the clipboard.
		document.addEventListener('copy', function(e) {
			// e.clipboardData is initially empty, but we can set it to the
			// data that we want copied onto the clipboard.
			e.clipboardData.setData('text/plain', 'Hello, world!');
			e.clipboardData.setData('text/html', '&lt;b&gt;Hello, world!&lt;/b&gt;');

			// This is necessary to prevent the current document selection from
			// being written to the clipboard.
			e.preventDefault();
		});
		</pre>

	<h3 id="override-cut">Overriding the cut event</h3>

		To override the default {{GlobalEventHandlers/cut}} event behavior, a {{GlobalEventHandlers/cut}} event
		handler must be added and this event handler must call
		{{Event/preventDefault()}} to cancel the event.

		Canceling the event is required in order for the [=system clipboard=] to be
		updated with the data in {{ClipboardEvent/clipboardData}}.
		If the {{ClipboardEvent}} is not canceled, then the data from the
		current document selection will be copied instead.

		Note that canceling the {{GlobalEventHandlers/cut}} event will also prevent the document from
		being updated (i.e., the current selection will not be removed). The event
		handler will need to manually update the document to remove the currently
		selected text.

		<pre class="example javascript">
		// Overwrite what is copied to the clipboard.
		document.addEventListener('cut', function(e) {
			// e.clipboardData is initially empty, but we can set it to the
			// data that we want copied onto the clipboard as part of the cut.
			// Write the data that we want copied onto the clipboard.
			e.clipboardData.setData('text/plain', 'Hello, world!');
			e.clipboardData.setData('text/html', '&lt;b&gt;Hello, world!&lt;/b&gt;');

			// Since we will be canceling the cut operation, we need to manually
			// update the document to remove the currently selected text.
			deleteCurrentDocumentSelection();

			// This is necessary to prevent the document selection from being
			// written to the clipboard.
			e.preventDefault();
		});
		</pre>

	<h3 id="override-paste">Overriding the paste event</h3>

		To override the default {{GlobalEventHandlers/paste}} event behavior, a {{GlobalEventHandlers/paste}} event
		handler must be added and this event handler must call
		{{Event/preventDefault()}} to cancel the event.

		Canceling the event is required so that the user agent does not update the
		document with data from the [=system clipboard=].

		Note that canceling the {{GlobalEventHandlers/paste}} event will also prevent the document from
		being updated (i.e., nothing will be pasted into the document). The event
		handler will need to manually paste the data into the document.

		Also note that, when pasting, the [=drag data store mode=] flag is
		<a lt="concept dnd ro">read-only</a>, hence calling {{DataTransfer/setData()}} from a
		{{GlobalEventHandlers/paste}} event handler will not modify the data that is
		inserted, and not modify the data on the clipboard.

		<pre class="example javascript">
		// Overwrite what is being pasted onto the clipboard.
		document.addEventListener('paste', function(e) {
			// e.clipboardData contains the data that is about to be pasted.
			if (e.clipboardData.types.indexOf('text/html') > -1) {
				var oldData = e.clipboardData.getData('text/html');
				var newData = '&lt;b&gt;Ha Ha!&lt;/b&gt; ' + oldData;

				// Since we are canceling the paste operation, we need to manually
				// paste the data into the document.
				pasteClipboardData(newData);

				// This is necessary to prevent the default paste action.
				e.preventDefault();
			}
		});
		</pre>

	<h3 id="mandatory-data-types-x"><dfn>Mandatory data types</dfn></h3>

		The implementation must recognize the native OS clipboard format description
		for the following data types, to be able to populate the
		{{DataTransferItemList}} and {{ClipboardItem}} with the correct description for
		paste events, and set the correct data format on the OS clipboard in response to
		copy and cut events.

		<h4 id="reading-from-clipboard">Reading from the clipboard</h4>

			These data types must be exposed by <em>paste</em> events if a
			corresponding native type exists on the clipboard:

			* text/plain
			* text/html
			* image/png

		<h4 id="writing-to-clipboard">Writing to the clipboard</h4>

			These data types must be placed on the clipboard with a corresponding
			native type description if added to a {{DataTransfer}} object during
			<em>copy</em> and <em>cut</em> events.

			* text/plain
			* text/html
			* image/png

			Advisement: Warning! The data types that untrusted scripts are allowed to write to the
			clipboard are limited as a security precaution. Untrusted scripts can
			attempt to exploit security vulnerabilities in local software by placing
			data known to trigger those vulnerabilities on the clipboard.

	<h3 id="optional-data-types-x"><dfn>Optional data types</dfn></h3>

		The implementation MAY recognize the native OS clipboard format description
		for the following data types, to be able to populate the
		{{ClipboardItem}} with the correct description for paste events, and
		set the correct data format on the OS clipboard in response to copy and cut
		events.

			These data types MAY be exposed by UAs if a corresponding native
			type exists on the clipboard:

			* text/uri-list
			* image/svg+xml
			* Custom format [=string/starts with=] `"web "`("web" followed by U+0020 SPACE) prefix
				and suffix (after stripping out `"web "`) passes the [=parsing a MIME type=] check.

	<h3 id="unsanitized-data-types-x"><dfn>Unsanitized data types</dfn></h3>
		<em>This section is non-normative.</em>

			These data types MUST NOT be sanitized by UAs:

			* image/png

			These data types MAY NOT be sanitized by UAs:

			* [=optional unsanitized data types=]

			<dfn>Optional unsanitized data types</dfn> are [=representation/mime type=]s specified by the web authors that MAY NOT be sanitized by the user agent.
			The valid [=optional unsanitized data types=] are listed below:

			* text/html

			<p class=note> [=optional unsanitized data types=] may not be supported by a user agent due to their privacy requirements.</p>

<h2 id="async-clipboard-api">Asynchronous Clipboard API</h2>

	<h3 id="navigator-interface">Navigator Interface</h3>

		<pre class="idl" data-highlight="webidl">
		partial interface Navigator {
		  [SecureContext, SameObject] readonly attribute Clipboard clipboard;
		};
		</pre>

		<div id="navigator-idl" dfn-for="Navigator">

		<div class="algorithm" data-algorithm="navigator-clipboard">
		<h4 id="h-navigator-clipboard"><dfn>clipboard</dfn></h4>
		It is used to execute read/write operations from/to the [=system clipboard=].
		The {{Navigator/clipboard}} getter steps are to return [=this=]'s [=clipboard=] object.
		</div>

		</div><!-- dfn-for Navigator -->

	<h3 id="clipboard-item-interface">ClipboardItem Interface</h3>
		<pre class="idl" data-highlight="webidl">
			typedef Promise&lt;(DOMString or Blob)&gt; ClipboardItemData;

			[SecureContext, Exposed=Window]
			interface ClipboardItem {
				constructor(record&lt;DOMString, ClipboardItemData> items,
				            optional ClipboardItemOptions options = {});

				readonly attribute PresentationStyle presentationStyle;
				readonly attribute FrozenArray&lt;DOMString> types;

				Promise&lt;Blob&gt; getType(DOMString type);

				static boolean supports(DOMString type);
			};

			enum PresentationStyle { "unspecified", "inline", "attachment" };

			dictionary ClipboardItemOptions {
				PresentationStyle presentationStyle = "unspecified";
			};
		</pre>

		<dl class=note>
			<dt><code><var>clipboardItem</var> = new ClipboardItem([<var>items</var>, <var>options</var>])</code></dt>
			<dd>
			Creates a new {{ClipboardItem}} object. <var>items</var> denote [=list of representations=], each [=representation=] has a [=representation/mime type=] and a {{Promise}} to {{Blob}} or {{DOMString}} corresponding to the [=representation/mime type=], <var>options</var> can be used to fill its {{ClipboardItemOptions}},
			as per the example below.

				<pre class="example javascript" highlight=js>
					const format1 = 'text/plain';
					const promise_text_blob = Promise.resolve(new Blob(['hello'], {type: format1}));
					const clipboardItemInput = new ClipboardItem(
						{[format1]: promise_text_blob},
						{presentationStyle: "unspecified"});
				</pre>
			</dd>
			<dt><code><var>clipboardItem</var>.getType(<var>type</var>)</code></dt>
			<dd>Returns a {{Promise}} to the {{Blob}} corresponding to the [=representation/mime type=] <var>type</var>.</dd>

			<dt><code><var>clipboardItem</var>.<var>types</var></code></dt>
			<dd>Returns the list of [=representation/mime type=]s contained in the [=/clipboard item=] object.</dd>

			<dt><code>{{ClipboardItem}}.supports(<var>type</var>)</code></dt>
			<dd>Returns true if <var>type</var> is in [=mandatory data types=] or [=optional data types=], else, returns false.</dd>
		</dl>

		A <dfn>clipboard item</dfn> is conceptually data that the user has expressed a desire to make shareable by invoking a "cut" or "copy" command. A [=/clipboard item=] serves two purposes. First, it allows a website to read data copied by a user to the [=system clipboard=]. Second, it allows a website to write data to the [=system clipboard=].

		<p class=note>
			For example, if a user copies a range of cells from a spreadsheet of a native application, it will result in one [=/clipboard item=]. If a user copies a set of files from their desktop, that list of files will be represented by multiple [=/clipboard item=]s.
		</p>

		Some platforms may support having more than one [=/clipboard item=] at a time on the [=clipboard=], while other platforms replace the previous [=/clipboard item=] with the new one.

		A [=/clipboard item=] has a <dfn>list of representations</dfn>, each <dfn>representation</dfn> with an associated <dfn for=representation>mime type</dfn> (a [=/MIME type=]), an <dfn for="representation">isCustom</dfn> flag, initially |false|, that indicates if this [=representation=] should be treated as a [=web custom format=] (as opposed to a well-known format of the [=system clipboard=]), and <dfn for=representation>data</dfn> (a {{ClipboardItemData}}).

		A <dfn>web custom format</dfn> has [=representation/isCustom=] set to |true|.

		<p class=note>
			In the example where the user copies a range of cells from a spreadsheet, it may be represented as an image (image/png), an HTML table (text/html), or plain text (text/plain), or a web custom format (web text/csv).
		</p>

		Each of these [=/MIME type=]s describe a different [=representation=] of the same [=/clipboard item=] at different levels of fidelity and make the [=/clipboard item=] more consumable by target applications during paste.

		<p class=note>
			Making the range of cells available as an image will allow the user to paste the cells into a photo editing app, while the text/plain format can be used by text editor apps.
		</p>

		A [=/clipboard item=] has a <dfn>presentation style</dfn> (a {{PresentationStyle}}). It helps distinguish whether apps "pasting" a [=/clipboard item=] should insert the contents of an appropriate [=representation=] inline at the point of paste or if it should be treated as an attachment.

		Web apps that support pasting only a single [=/clipboard item=] should use the first [=/clipboard item=].

		<p class=note>
			{{Clipboard/write()}} chooses the last [=/clipboard item=].
		</p>

		Web apps that support pasting more than one [=/clipboard item=] could, for example, provide a user interface that previews the contents of each [=/clipboard item=] and allow the user to choose which one to paste.
		Further, apps are expected to enumerate the [=/MIME type=]s of the [=/clipboard item=] they are pasting and select the one best-suited for the app according to some app-specific algorithm.
		Alternatively, an app can present the user with options on how to paste a [=/clipboard item=], e.g. "paste as image" or "paste formatted text", etc.

		A {{ClipboardItem}} object has an associated <dfn for="ClipboardItem">clipboard item</dfn>, which is a [=/clipboard item=].

		A {{ClipboardItem}} object has an associated <dfn for="ClipboardItem">types array</dfn>, which is a {{FrozenArray}}&lt;{{DOMString}}&gt;.

		To <dfn>create a {{ClipboardItem}} object</dfn>, given a [=/clipboard item=] |clipboardItem| and a Realm |realm|, run these steps:
			1. Let |clipboardItemObject| be a [=new=] {{ClipboardItem}} with |realm|.

			1. Set |clipboardItemObject|'s [=/clipboard item=] to |clipboardItem|.

		The <dfn constructor for="ClipboardItem" lt="ClipboardItem(items, options)"><code>new ClipboardItem(<var>items</var>, <var>options</var>)</code></dfn> constructor steps are:
			1. If |items| is empty, then throw a {{TypeError}}.

			1. If |options| is empty, then set options["presentationStyle"] = "unspecified".

			1. Set [=this=]'s [=ClipboardItem/clipboard item=] to a new [=/clipboard item=].

			1. Set [=this=]'s [=ClipboardItem/clipboard item=]'s [=presentation style=] to |options|["{{ClipboardItemOptions/presentationStyle}}"].

			1. Let |types| be a list of {{DOMString}}.

			1. For each (|key|, |value|) in |items|:

				1. Let |representation| be a new [=representation=].

				1. Let |isCustom| be |false|.
				
				1. If |key| [=string/starts with=] `"web "` prefix, then
				
					1. Remove `"web "` prefix and assign the remaining string to |key|.

					1. Set |isCustom| |true|
					
				1. Set |representation|'s [=representation/isCustom=] flag to |isCustom|.

				1. Let |mimeType| be the result of [=parsing a MIME type=] given |key|.

				1. If |mimeType| is failure, then throw a {{TypeError}}.

				1. If [=this=]'s [=ClipboardItem/clipboard item=]'s [=list of representations=] [=list/contains=] a [=representation=] whose [=representation/MIME type=] is |mimeType| and whose [representation/isCustom] is |isCustom|, then throw a {{TypeError}}.

				<p class=note>The step above prevents collision between mime-types well-known by the user agent and those that are intended by the author to be treated as a custom type.  For example, it would be possible for the author's list of items to contain representations for "text/html" as well as "web text/html".</p>

				1. Set |representation|'s [=representation/MIME type=] to |mimeType|.

				1. Set |representation|'s [=representation/data=] to |value|.

				1. Append |representation| to [=this=]'s [=ClipboardItem/clipboard item=]'s [=list of representations=].

				1. Let |mimeTypeString| be the result of [=serializing a MIME type=] with |mimeType|.
				
				1. If |isCustom| is |true|, prefix |mimeTypeString| with `"web "`.
				
				1. Add |mimeTypeString| to |types|.

			1. Set [=this=]'s [=ClipboardItem/types array=] to the result of running [=create a frozen array=] from |types|.

		<h4 attribute for=ClipboardItem lt=presentationStyle>presentationStyle</h4>
		<p>
			The {{ClipboardItem/presentationStyle}} getter steps are to return [=this=]'s [=ClipboardItem/clipboard item=]'s [=presentation style=].
		</p>

		<h4 attribute for=ClipboardItem lt=types>types</h4>
		<p>
			The {{ClipboardItem/types}} getter steps are to return [=this=]'s [=ClipboardItem/types array=].
		</p>

		<h4 method for=ClipboardItem lt=getType(type)>getType(type)</h4>
		
			This method must run the below steps:

			1. Let |realm| be [=this=]'s [=relevant realm=].

			1. Let |isCustom| be |false|.

			1. If |type| [=string/starts with=] `"web "` prefix, then:
			
				1. Remove `"web "` prefix and assign the remaining string to |type|.

				1. Set |isCustom| to |true|.

			1. Let |mimeType| be the result of [=parsing a MIME type=] given |type|.

			1. If |mimeType| is failure, then throw a {{TypeError}}.

			1. Let |itemTypeList| be [=this=]'s [=ClipboardItem/clipboard item=]'s [=list of representations=].

			1. Let |p| be [=a new promise=] in |realm|.

			1. For each |representation| in |itemTypeList|:

				1. If |representation|'s [=representation/MIME type=] is |mimeType| and |representation|'s [=representation/isCustom=] is |isCustom|, then:

					1. Let |representationDataPromise| be the |representation|'s [=representation/data=].

					1. [=promise/React=] to |representationDataPromise|:

						1. If |representationDataPromise| was fulfilled with value |v|, then:

							1. If |v| is a {{DOMString}}, then follow the below steps:

								1. Let |dataAsBytes| be the result of [=UTF-8 encoding=] |v|.

								1. Let |blobData| be a {{Blob}} created using |dataAsBytes| with its {{Blob/type}} set to |mimeType|, [=serialize a MIME type|serialized=].

								1. Resolve |p| with |blobData|.

							1. If |v| is a {{Blob}}, then follow the below steps:

								1. Resolve |p| with |v|.

						1. If |representationDataPromise| was rejected, then:

							1. [=Reject=] |p| with {{"NotFoundError"}} {{DOMException}} in |realm|.

								Issue: Web developers might be interested in the underlying rejection reason.

					1. Return |p|.

			1. [=Reject=] |p| with {{"NotFoundError"}} {{DOMException}} in |realm|.

			1. Return |p|.

		<h4 method for=ClipboardItem lt=supports(type)>supports(type)</h4>

			This method must run the below steps:

			1. If |type| is in [=mandatory data types=] or [=optional data types=], then return true.

			1. If not, then return false.


	<h3 id="clipboard-interface">Clipboard Interface</h3>

		<pre class="idl" data-highlight="webidl">
		typedef sequence&lt;ClipboardItem&gt; ClipboardItems;

		[SecureContext, Exposed=Window]
		interface Clipboard : EventTarget {
			Promise&lt;ClipboardItems&gt; read(optional ClipboardUnsanitizedFormats formats = {});
			Promise&lt;DOMString&gt; readText();
			Promise&lt;undefined&gt; write(ClipboardItems data);
			Promise&lt;undefined&gt; writeText(DOMString data);
		};

		dictionary ClipboardUnsanitizedFormats {
			sequence&lt;DOMString&gt; unsanitized;
		};
		</pre>

		Some methods of the {{Clipboard}} interface take or return multiple {{ClipboardItem}} objects. However, not all platforms support more than one [=/clipboard item=]; on such platforms, the algorithms below will ignore any {{ClipboardItem}} objects beyond the first one that are passed to {{Clipboard/write()}}, and {{Clipboard/read()}} and {{Clipboard/readText()}} only get one clipboard item from the OS.

		A <dfn>clipboard items</dfn> object is a [=sequence=] of [=/clipboard item=]s.

		<p class="note">
		A web author needs to create a |data| which is an array of {{ClipboardItem}}s in order to write content to [=system clipboard=] using the {{Clipboard/write(data)}} method.
		{{Clipboard/read()}} returns a {{Promise}} to [=clipboard items=] object that represents contents of [=system clipboard data=].
		</p>

		{{ClipboardUnsanitizedFormats/unsanitized}} is a [=sequence=] of {{DOMString}}s corresponding to the [=representation/mime type=] that the author wants to be treated as [=optional unsanitized data types=].

		<p class=note> The {{ClipboardUnsanitizedFormats/unsanitized}} option MAY NOT be supported by the user agent. The web authors shouldn't assume that the content for the MIME types listed in {{ClipboardUnsanitizedFormats/unsanitized}} would be unsanitized as there could be privacy modes where this option may not be allowed.  </p>

		The <dfn>clipboard task source</dfn> is triggered in response to reading or writing of [=system clipboard data=].

		<div id="clipboard-idl" dfn-for="Clipboard">
		<div class="algorithm" data-algorithm="clipboard-read">
		<h4 method for="Clipboard">read(|formats|)</h4>
		The {{Clipboard/read(formats)}} method must run these steps:

			1. Let |realm| be [=this=]'s [=relevant realm=].

			1. Let |p| be [=a new promise=] in |realm|.

			1. If |formats| is not empty, then:

				1. For each |format| in |formats|["{{ClipboardUnsanitizedFormats/unsanitized}}"]:

					1. If |format| is not in [=optional unsanitized data types=], then [=reject=] |p| with |format| {{"NotAllowedError"}} {{DOMException}} in |realm|.

			1. Run the following steps [=in parallel=]:

				1. Let |r| be the result of running [=check clipboard read permission=].

				1. If |r| is false, then:
				
					1. [=Queue a global task=] on the [=permission task source=], given |realm|'s [=realm/global object=], to [=reject=] |p| with {{"NotAllowedError"}} {{DOMException}} in |realm|.

					1. Abort these steps.

				1. Let |data| be a copy of the [=system clipboard data=].

				1. Let |items| be a [=sequence=]&lt;[=/clipboard item=]&gt;.

				1. For each |systemClipboardItem| in |data|:

					1. Let |item| be a new [=/clipboard item=].

					1. For each |systemClipboardRepresentation| in |systemClipboardItem|:

						1. Let |mimeType| be the result of running the [=well-known mime type from os specific format=] algorithm given |systemClipboardRepresentation|'s [=system clipboard representation/name=].
						
						1. If |mimeType| is null, continue this loop.

						1. Let |representation| be a new [=representation=].
						
						1. Set |representation|'s [=representation/MIME type=] to |mimeType|.

						1. Let |isUnsanitized| be |false|.

						1. If |formats| is not empty, then:

							1. For each |format| in |formats|["{{ClipboardUnsanitizedFormats/unsanitized}}"]:

								1. If |format| is equal to [=representation/MIME type=], set |isUnsanitized| to true.

						1. Resolve |representation|'s [=representation/data=] with |systemClipboardRepresentation|'s [=system clipboard representation/data=].

							Issue: It should be possible to read the data asynchronously from the system clipboard after the author calls getType, however, this set of steps implies that data will be provided at the time of read.
						
						1. The user agent, MAY sanitize |representation|'s [=representation/data=], unless |representation|'s [=representation/MIME type=]'s essence is "image/png", which should remain unsanitized to preserve meta data, or if it satisfies the below conditions:
						
							1. |representation|'s [=representation/MIME type=] is in optional [=unsanitized data types=] list.
							
							1. |isUnsanitized| is true.

						1. Append |representation| to |item|'s [=list of representations=].

						1. Set |isUnsanitized| to |false|.
					
					1. If |item|'s [=list of representations=] size is greater than 0, append |item| to |items|.

				1. If |items| has a size > 0, then:
				
						1. Let |firstItem| be |items|[0]
						
						1. Run the [=read web custom format=] algorithm given |firstItem|.
					
				1. 	Else:

						1. Let |customItem| be a new [=/clipboard item=].

						1. Run the [=read web custom format=] algorithm given |customItem|.

						1. If |customItem|'s [=list of representations=] size is greater than 0, append |customItem| to |items|.


				1. [=Queue a global task=] on the [=clipboard task source=], given |realm|'s [=realm/global object=], to perform the below steps:

					1. Let |clipboardItems| be a [=sequence=]&lt;{{ClipboardItem}}&gt;.

					1. For each [=/clipboard item=] |underlyingItem| of |items|:

						1. Let |clipboardItem| be the result of running the steps of [=create a ClipboardItem object=] given |underlyingItem| and |realm|.

						1. Append |clipboardItem| to |clipboardItems|.

					1. Resolve |p| with |clipboardItems|.

			1. Return |p|.

			<div></div>

			<pre class="example javascript" highlight=js>
				const items = await navigator.clipboard.read();
				const textBlob = await items[0].getType("text/plain");
				const text = await (new Response(textBlob)).text();
			</pre>

		</div><!-- read() -->

		<div class="algorithm" data-algorithm="clipboard-readtext">
		<h4 method for="Clipboard">readText()</h4>
		The {{Clipboard/readText()}} method must run these steps:

			1. Let |realm| be [=this=]'s [=relevant realm=].

			1. Let |p| be [=a new promise=] in |realm|.

			1. Run the following steps [=in parallel=]:

				1. Let |r| be the result of running [=check clipboard read permission=].

				1. If |r| is false, then:
				
					1. [=Queue a global task=] on the [=permission task source=], given |realm|'s [=realm/global object=], to [=reject=] |p| with {{"NotAllowedError"}} {{DOMException}} in |realm|.

					1. Abort these steps.

				1. Let |data| be a copy of the [=system clipboard data=].

					Issue: Some OSs contain multiple clipboard (e.g. Linux, "primary", "secondary", "selection"). Define from which of those data is read.

					Issue: Add definition of sanitized copy.

				1. [=Queue a global task=] on the [=clipboard task source=], given |realm|'s [=realm/global object=], to perform the below steps:

					1. For each |systemClipboardItem| in |data|:

						1. For each |systemClipboardRepresentation| in |systemClipboardItem|:

							1. Let |mimeType| be the result of running the [=well-known mime type from os specific format=] algorithm given |systemClipboardRepresentation|'s [=system clipboard representation/name=].
							
							1. If |mimeType| is null, continue this loop.

							1. Let |representation| be a new [=representation=].

							1. If |representation|'s [=representation/MIME type=] [=MIME type/essence=] is "text/plain", then:

								1. Set |representation|'s [=representation/MIME type=] to |mimeType|.

								1. Let |representationDataPromise| be the |representation|'s [=representation/data=].

								1. [=promise/React=] to |representationDataPromise|:

									1. If |representationDataPromise| was fulfilled with value |v|, then:

										1. If |v| is a {{DOMString}}, then follow the below steps:

											1. Resolve |p| with |v|.

											1. Return |p|.

										1. If |v| is a {{Blob}}, then follow the below steps:

											1. Let |string| be the result of [=UTF-8 decoding=] |v|'s underlying byte sequence.

											1. Resolve |p| with |string|.

											1. Return |p|.

									1. If |representationDataPromise| was rejected, then:

										1. [=Reject=] |p| with {{"NotFoundError"}} {{DOMException}} in |realm|.

										1. Return |p|.

					1. [=Reject=] |p| with {{"NotFoundError"}} {{DOMException}} in |realm|.

					1. Return |p|.

			<div></div>

			<pre class="example javascript" highlight=js>
				navigator.clipboard.readText().then(function(data) {
					console.log("Your string: ", data);
				});
			</pre>

		</div><!-- readText() -->

		<div class="algorithm" data-algorithm="clipboard-write">
		<h4 method for="Clipboard">write(|data|)</h4>
		The {{Clipboard/write(data)}} method must run these steps:

			1. Let |realm| be [=this=]'s [=relevant realm=].

			1. Let |p| be [=a new promise=] in |realm|.

			1. Run the following steps [=in parallel=]:

				1. Let |r| be the result of running [=check clipboard write permission=].

					Issue: clipboard-write was removed in https://github.com/w3c/clipboard-apis/pull/164.

				1. If |r| is false, then:
				
					1. [=Queue a global task=] on the [=permission task source=], given |realm|'s [=realm/global object=], to [=reject=] |p| with {{"NotAllowedError"}} {{DOMException}} in |realm|.

					1. Abort these steps.

				1. [=Queue a global task=] on the [=clipboard task source=], given |realm|'s [=realm/global object=], to perform the below steps:

					1. Let |itemList| and |cleanItemList| be an empty [=sequence=]&lt;{{Blob}}&gt;.

					1. Let |dataList| be a [=sequence=]&lt;{{ClipboardItem}}&gt;.

					1. If |data|'s [=list/size=] is greater than 1, and the current operating system does not support multiple native clipboard items on the [=system clipboard=], then add |data|[0] to |dataList|, else, set |dataList| to |data|.

						Issue: when |data| contains multiple items and the operating system supports multiple native clipboard items, the current algorithm writes the items in sequence to the system clipboard instead of writing them collectively.

					1. For each |clipboardItem| in |dataList|:

						1. For each |representation| in |clipboardItem|'s [=ClipboardItem/clipboard item=]'s [=list of representations=]:

							1. Let |representationDataPromise| be the |representation|'s [=representation/data=].

							1. [=promise/React=] to |representationDataPromise|:

								1. If |representationDataPromise| was fulfilled with value |v|, then:

									1. If |v| is a {{DOMString}}, then follow the below steps:

										1. Let |dataAsBytes| be the result of [=UTF-8 encoding=] |v|.

										1. Let |blobData| be a {{Blob}} created using |dataAsBytes| with its {{Blob/type}} set to |representation|'s [=representation/MIME type=].

										1. Add |blobData| to |itemList|.

									1. If |v| is a {{Blob}}, then add |v| to |itemList|.

								1. If |representationDataPromise| was rejected, then:

									1. [=Reject=] |p| with {{"NotAllowedError"}} {{DOMException}} in |realm|.

									1. Abort these steps.

						1. For each |blob| in |itemList|:

							1. Let |type| be the |blob|'s {{Blob/type}}.

							1. If |type| is not in the [=mandatory data types=] or [=optional data types=] list, then [=reject=] |p| with {{"NotAllowedError"}} {{DOMException}} in |realm| and abort these steps.

							1. Let |cleanItem| be an optionally sanitized copy of |blob|.

								Issue: Add definition of sanitized copy.

							1. If sanitization was attempted and was not successfully completed, then follow the below steps:

								1. [=Reject=] |p| with {{"NotAllowedError"}} DOMException in |realm|.
								
								1. Abort these steps.

							1. Append |cleanItem| to |cleanItemList|.

						1. Let |option| be |clipboardItem|'s [=ClipboardItem/clipboard item=]'s [=presentation style=].

						1. [=Write blobs and option to the clipboard=] with |cleanItemList| and |option|.

					1. Resolve |p|.

			1. Return |p|.

			<div></div>

			<pre class="example javascript" highlight=js>
				var data = [new ClipboardItem({ "text/plain": Promise.resolve(new Blob(["Text data"], { type: "text/plain" })) })];
				navigator.clipboard.write(data).then(function() {
					console.log("Copied to clipboard successfully!");
				}, function() {
					console.error("Unable to write to clipboard. :-(");
				});
			</pre>

		</div><!-- write() -->

		<div class="algorithm" data-algorithm="clipboard-writetext">
		<h4 method for="Clipboard">writeText(|data|)</h4>
		The {{Clipboard/writeText(data)}} method must run these steps:

			1. Let |realm| be [=this=]'s [=relevant realm=].

			1. Let |p| be [=a new promise=] in |realm|.

			1. Run the following steps [=in parallel=]:

				1. Let |r| be the result of running [=check clipboard write permission=].

					Issue: clipboard-write was removed in https://github.com/w3c/clipboard-apis/pull/164.

				1. If |r| is false, then:
				
					1. [=Queue a global task=] on the [=permission task source=], given |realm|'s [=realm/global object=], to [=reject=] |p| with {{"NotAllowedError"}} DOMException in |realm|.

					1. Abort these steps.

				1. [=Queue a global task=] on the [=clipboard task source=], given |realm|'s [=realm/global object=], to perform the below steps:

					1. Let |itemList| be an empty [=sequence=]&lt;{{Blob}}&gt;.

					1. Let |textBlob| be a new {{Blob}} created with:
						{{Blob/type}} attribute set to "<code>text/plain;charset=utf-8</code>", and
						its underlying byte sequence set to the [=UTF-8 encoding=] of |data|.
					
						Note: On Windows replace `\n` characters with `\r\n` in |data| before creating |textBlob|.

					1. Add |textBlob| to |itemList|.

					1. Let |option| be set to "unspecified".

					1. [=Write blobs and option to the clipboard=] with |itemList| and |option|.

					1. Resolve |p|.

			1. Return |p|.

			<div></div>

			<pre class="example javascript" highlight=js>
				await navigator.clipboard.writeText("Howdy, partner!");
			</pre>

		</div><!-- writeText() -->

		</div><!-- dfn-for Clipboard -->


<h2 id="clipboard-actions">Clipboard Actions</h2>

	This section defines clipboard actions and the processing model
	for event dispatch.

	Each clipboard action has two flags called [=script-triggered=] and
	[=script-may-access-clipboard=].

	The <dfn>script-triggered</dfn> flag is set if the action runs because
	of a script, for example a <code>document.execCommand()</code> call.
	Future scripting APIs that interact with the clipboard should also use
	these actions, and the [=script-triggered=] flag must be set
	accordingly.

	<div class="algorithm" data-algorithm="script-may-access-clipboard">

	The <dfn>script-may-access-clipboard</dfn> flag is set as follows:

	1. If action is <em>copy</em> or <em>cut</em> and the script thread
		is [=allowed to modify the clipboard=], then

		1. Set the action's [=script-may-access-clipboard=] flag

	1. If action is <em>paste</em> and the script thread is [=allowed to
		read from clipboard=], then

		1. Set the action's [=script-may-access-clipboard=] flag.

	</div><!-- algorithm -->

	<h3 id="copy-action">The copy action</h3>

		<div class="algorithm" data-algorithm="clipboard-copy-action">

		The copy action consists of the following steps:

		1. If the [=script-triggered=] flag is set, then

			1. If the [=script-may-access-clipboard=] flag is unset, then

				1. Return false from the copy action, terminate this algorithm

		1. [=Fire a clipboard event=] named {{GlobalEventHandlers/copy}}

		1. If the event was not canceled, then

			1. Copy the selected contents, if any, to the clipboard.
				Implementations <em>should</em> create alternate text/html and
				text/plain clipboard formats when content in a web page is selected.

			1. [=Fire a clipboard event=] named {{GlobalEventHandlers/clipboardchange}}

		1. Else, if the event was canceled, then

			1. Call the [=write content to the clipboard=] algorithm,
				passing on the {{DataTransferItemList}} list <em>items</em>,
				a <em>clear-was-called</em> flag and a <em>types-to-clear</em>
				list.

		1. Return true from the copy action

		</div><!-- algorithm -->

	<h3 id="cut-action">The cut action</h3>

		<div class="algorithm" data-algorithm="clipboard-cut-action">

		The cut action consists of the following steps:

		1. If the [=script-triggered=] flag is set, then

			1. If the [=script-may-access-clipboard=] flag is unset, then

				1. Return false from the cut action, terminate this algorithm

		1. [=Fire a clipboard event=] named {{GlobalEventHandlers/cut}}

		1. If the event was not canceled, then

			1. If there is a selection in an [=editable context=] where
				cutting is enabled, then

				1. Copy the selected contents, if any, to the clipboard.
					Implementations <em>should</em> create alternate
					text/html and text/plain clipboard formats when content
					in a web page is selected.

				1. Remove the contents of the selection from the document
					and collapse the selection.

				1. [=Fire a clipboard event=] named {{GlobalEventHandlers/clipboardchange}}

				1. Queue tasks to fire any events that should fire due to the
					modification, see
					[[#integration-with-other-scripts-and-events]]
					for details.

			1. Else, if there is no selection or the context is not editable, then

				1. Return false

		1. Else, if the event was canceled, then

			1. Call the [=write content to the clipboard=] algorithm,
				passing on the {{DataTransferItemList}} list <em>items</em>,
				a <em>clear-was-called</em> flag and a <em>types-to-clear</em>
				list.

			1. [=Fire a clipboard event=] named {{GlobalEventHandlers/clipboardchange}}

		1. Return true from the cut action

		</div><!-- algorithm -->

	<h3 id="paste-action">The paste action</h3>

		For the paste action, the [=script-may-access-clipboard=] flag
		depends on an implementation-specific permission mechanism for
		determining what sites or apps may read from the clipboard. When a
		paste action is triggered by a script, the implementation must not
		make clipboard contents available without the user's permission. If
		the permission has not already been granted, the permission prompt
		must include the hostname of the document associated with the script
		thread.

		<div class="algorithm" data-algorithm="clipboard-paste-action">

		The paste action consists of the following steps:

		1. If the [=script-triggered=] flag is set, then

			1. If [=script-may-access-clipboard=] is unset, then

				1. Return false from the paste action, terminate this algorithm

		1. <a href="#fire-a-clipboard-event">Fire a clipboard event</a>
			named {{GlobalEventHandlers/paste}}

		1. If the event was not canceled, then

			1. If there is a selection or cursor in an [=editable context=]
				where pasting is enabled, then

				1. Insert the most suitable content found on the clipboard,
					if any, into the context.

				1. Queue tasks to fire any events that should fire due to
					the modification, see
					[[#integration-with-other-scripts-and-events]] for details.

			1. Else

				1. Return false

		1. Else, if the event was canceled

			1. Return false

		1. Return true from the action

		</div><!-- algorithm -->


<h2 id="clipboard-permissions">Permissions API Integration</h2>

	The [[permissions]] API provides a uniform way for websites to access
	<a>powerful feature</a>s like the clipboard. It allows websites to request permissions
	from users and query which permissions they have.

	For the clipboard, one permission is defined:
	<dfn enum-value for="PermissionName">"clipboard-write"</dfn>

	Note: Clipboard permissions currently only apply to the Async Clipboard API.
	Future versions of this specification may be updated to apply this permission
	to other Clipboard interactions.

	These clipboard permissions are <a>powerful feature</a>s
	permission-related algorithms and types are defined as follows:

	: <a>permission descriptor type</a>
	::
		<pre class="idl">
			dictionary ClipboardPermissionDescriptor : PermissionDescriptor {
				boolean allowWithoutGesture = false;
			};
		</pre>

	There are 4 clipboard permissions:

	* { name: "clipboard-write", allowWithoutGesture: false }
	* { name: "clipboard-write", allowWithoutGesture: true }

	With the following relationships:

	* <code>{ "clipboard-write" + true }</code> is stronger than <code>{ "clipboard-write" + false }</code>

	While user agents MUST support the {{ClipboardPermissionDescriptor}} as described
	in this specification, they, of course, retain complete control over the default
	settings and how (or if) they are exposed to the user.

	<div class="example">
		A user agent that wants to have separate user-settable write controls over the clipboard
		and always require a user gesture would handle each descriptor as follows:

		* <code class="perm">{ "clipboard-write" + false }</code> is exposed for user control
		* <code class="perm">{ "clipboard-write" + true }</code> is always {{PermissionState/denied}}
	</div>

	<h3 id="read-permission">Clipboard read permission</h3>

		<div class="algorithm" data-algorithm="clipboard-read-permission">
		<h4 id="h-clipboard-read-permission"><dfn>check clipboard read permission</dfn></h4>

		1. Let |hasGesture| be true if the [=relevant global object=] of [=this=] has
		    [=transient activation=], false otherwise.

		1. If |hasGesture| then,

			<!-- System paste buttons don't require permission -->
			1. Return true if the current script is running as a result of user
				interaction with a "Paste" element created by the user agent or operating
				system.

		1. Return false.

		</div><!-- algorithm -->

	<h3 id="write-permission">Clipboard write permission</h3>

		<div class="algorithm" data-algorithm="clipboard-write-permission">
		<h4 id="h-clipboard-write-permission"><dfn>check clipboard write permission</dfn></h4>

		1. Let |writeWithoutGesture| be the [=permission state=] of the
			<code>{ name: "clipboard-write", allowWithoutGesture: true }</code>
			permission.

		1. If |writeWithoutGesture| is {{PermissionState/granted}}, then return true.

		1. Let |hasGesture| be true if the [=relevant global object=] of [=this=]
		    has [=transient activation=], false otherwise.

		1. If |hasGesture| then,

			<!-- System paste buttons don't require permission -->
			1. Let |systemCopy| be true if the current script is running as a result of user
				interaction with a "cut" or "copy" element created by the user agent or operating
				system.

			1. If |systemCopy| is true, then return true.

			1. Return the result of [=request permission to use=] the
				<code>{ name: "clipboard-write", allowWithoutGesture: false }</code>
				permission.

				Note: User agents may choose to request a stronger permission that
				will implicitly update this permission.

		1. Return the result of [=request permission to use=] the
			<code>{ name: "clipboard-write", allowWithoutGesture: true }</code>
			permission.

		</div><!-- algorithm -->


<h2 id="security">Security Considerations</h2>

	Enabling authors to change what is copied by a user, or to make an automated
	copy of something that was never selected and allowing unrestricted calls to
	paste information can raise various security concerns.

	Some example scenarios include:

	* A user selects a link and copies it, but a different link is copied to the clipboard.
		The effect of this can range from an unexpected result on pasting to an attempted
		"phishing" attack.
	* (Self-XSS) Shell commands or executable script can be placed in the clipboard with the
		intent that the user will run the pasted content.
	* An image that is specially crafted to exploit bugs in the core OS image handling
		code can be written to the clipboard.

	<h3 id="pasting-html">Pasting HTML and multi-part data</h3>

		<em>This section is non-normative.</em>

		There are certain security risks associated with pasting formatted or
		multi-part data.

		* The user might paste hidden data without realising it is there. This may
			happen if, for example, the markup includes
			&lt;input type="hidden"&gt; tags or HTML comments. Such hidden data
			might contain sensitive information.
		* The user might paste malicious JavaScript into a trusted page.
		* The implementation might grant scripts access to local files the user
			did not intend to expose.

		To determine what policies to use, the factors we consider are:

		* The origin of the data being pasted
		* The origin of data sub-parts such as referenced images
		* The origin of the running script

		This is an overview of the scenarios and the possible security policies:

		<table class="simple">
			<tr>
				<th>Origin of data</th>
				<th>Origin of script</th>
				<th>Rules</th>
			</tr>
			<tr>
				<td rowspan="2">Originates from online source</td>
				<td>Same as data</td>
				<td>Do not sanitize HTML. Do not access any local files.</td>
			</tr>
			<tr>
				<!-- cell span from previous row -->
				<td>Different origin</td>
				<td>Optionally sanitize content. Do not access any local files.</td>
			</tr>
			<tr>
				<td>Originates from local application</td>
				<td>Any</td>
				<td>Do not sanitize HTML. Grant access to local files</td>
			</tr>
		</table>

		Some implementations mitigate the risks associated with pasting rich
		text by stripping potentially malicious content such as SCRIPT elements
		and javascript: links by default when pasting rich text, but allow a
		paste event handler to retrieve and process the original, un-sanitized
		data.

	<h3 id="general-security-policies">General security policies</h3>

		The implementation <em>must not</em> download referenced online
		resources, or expose their contents in the {{DataTransfer/files}} list
		or {{DataTransferItemList}}.

		If the data on the clipboard is not from a local application, the
		implementation <em>must not</em> give access to any referenced local
		files. For example, if the data contains
		&lt;img src="file://localhost/example.jpg"&gt;
		but the data's origin is an online resource, the implementation must not
		add an entry for example.jpg to the clipboardData.items list.

	<h3 id="image-transcode">Transcoding images</h3>

		To prevent malicious image data from being placed on the clipboard, the image
		data may be transcoded to produce a safe version of the image. This prevents websites
		from trying to exploit security vulnerabilities in other applications.

		Implementations should not transcode images being read from the clipboard.
		Transcoding images can lose important metadata (such as the physical resolution
		of an image).
		This is also consistent with other methods in which images can be shared
		with a website (such as `&lt;input type=file&gt;`).

	<h3 id="nuisances">Nuisance considerations</h3>

		Scripts may use the {{DataTransfer}} API to annoy and confuse users by
		altering the data on the system clipboard from copy and cut events. This
		specification does not attempt to prevent such nuisances, though
		implementations may add additional restrictions.

		Implementations must handle scripts that try to place excessive amounts
		of data on the clipboard gracefully.


<h2 id="privacy">Privacy Considerations</h2>

	Because these APIs provide access to the user's clipboard data, there are serious
	privacy concerns due to the possibility that the clipboard will contain
	personally-identifiable information (PII) like names, addresses, or passwords.

	In general, user agents <em>must</em> ensure that untrusted scripts do not get
	uncontrolled access to a user's clipboard data through these APIs.

	<h3 id="privacy-events">Privacy and the Clipboard Event API</h3>

		The Clipboard Event API allows scripts running in the context of a clipboard
		event handler to access a copy of the system clipboard and potentially modify
		the data being written to the clipboard.

		User agents should be aware of the following requirements with regards to
		securing the data accessed by the Clipboard Event API:

		* Objects implementing the {{DataTransfer}} interface to return
			clipboard data <em>must not</em> be available outside the
			ClipboardEvent event handler that the data is provided to.
		* If a script stores a reference to an object implementing the
			{{DataTransfer}} interface to use from outside the ClipboardEvent
			event handler, all methods <em>must</em> be no-ops when called
			outside the expected context.
		* Implementations <em>must not</em> let scripts create synthetic
			clipboard events to get access to real clipboard data (unless the user
			has configured it to do so).

		Even though the Clipboard Event API is not covered by the Clipboard permission,
		user agents may choose to provide a method for the user to disable this API or
		to configure which sites are allowed to access it.

	<h3 id="privacy-async">Privacy and the Asychronous Clipboard API</h3>

		The Asynchronous Clipboard API is a powerful feature because it can allow access
		to the clipboard data from any script (access is not restricted to Clipboard Event
		handlers) and data can be accessed in the absence of a user provided gesture.

		To help prevent abuse, this API <em>must not</em> be available unless the script
		is executing in the context of a document that [=has focus steps|has focus=].

		<h4 id="privacy-permission">Privacy and Clipboard Permission</h4>

			The Clipboard Permission gates access to this API, but user agents get to choose
			the permission defaults and which of these permission settings can be set by the
			user. For example, a user agent may choose to only allow access to the
			Asynchronous Clipboard API when a user gesture is present and always deny script
			requests for access without a gesture.

			User agents may opt to have this permission automatically expire sometime after
			the user grants permission, for example, by having the permission expire:

			* After a set time from when the permission was first granted
			* After a set time from the user's last visit to a site
			* When the user navigates away from the page

	<h3 id="privacy-other">Other Privacy Concerns</h3>

		If the user agent allows clipboard data to be read using
		<code>document.execCommand("paste")</code> then the user agent <em>must</em>
		ensure that the user has explicitly allowed that access to take place.


<h2 id="acknowledge">Acknowledgements</h2>

	<em>This section is non-normative</em>

	The editors would like to acknowledge the contributions of the former
	editors who helped shepherd this specification through various
	meetings and mailing-list discussions to bring it to its current state.

	* Hallvord R. M. Steen

	The editors would also like to acknowledge their intellectual debt to the
	documentation of Data Transfer functionalities from Microsoft
	[[MICROSOFT-CLIP-OP]] and earlier drafts of the [[HTML5]] specification.
	We are also grateful for the draft "safe copy and paste" from Paul Libbrecht
	(this draft is no longer available on the Web).

	And finally, we would like to acknowledge the contributions made by the following:

	Adam Barth,
	Shawn Carnell,
	Daniel Cheng,
	Daniel Dardailler,
	Domenic Denicola,
	Al Gilman,
	James Graham,
	James Greene,
	Ian Hickson,
	Darwin Huang,
	Lachlan Hunt,
	Philip Jägenstedt,
	Anne van Kesteren,
	Marijn Kruisselbrink,
	Aaron Leventhal,
	Jim Ley,
	Paul Libbrecht,
	"Martijn",
	Glenn Maynard,
	Chris Mills,
	ms2ger,
	Ryosuke Niwa,
	Robert O'Callahan,
	Dave Poehlman,
	"ROBO Design",
	Janina Sajka,
	Rich Schwerdtfeger,
	Jonas Sicking,
	Maciej Stachowiak,
	Mihai Sucan,
	Dmitry Titov,
	Ojan Vafai,
	Tarquin Wilton-Jones,
	Tom Wlodkowski,
	Bo Cupp,
	mbrodesser
	and Boris Zbarsky.


<h2 id="algorithms">Appendix A: Algorithms</h2>

	<div class="algorithm" data-algorithm="write-content-to-clipboard">
	<h3 id="to-write-content-to-clipboard"><dfn>write content to the clipboard</dfn></h3>

		: Input
		:: |items|, a {{DataTransferItemList}} list of items to write
		:: |clear-was-called|, a boolean
		:: |types-to-clear|, a list

		: Output
		:: None

		1. If the |items| list is not empty, then

			1. Clear the clipboard

			1. For each part in the list,

				1. If data type is <i>text/plain</i>, then

					1. Ensure encoding is correct per OS and locale conventions

					1. Normalize line endings according to platform conventions

					1. Place text on clipboard with the appropriate OS clipboard
						format description

				1. Else, if data is of a type listed in the
					[=mandatory data types=] list, then

					1. Place part on clipboard with the appropriate OS clipboard
						format description

				1. Else

					1. This is left to the implementation...

						Issue: It's not good to leave things up to the
						implementation. What should happen here?

						Note: Due to limitations in the implementation of operating
						system clipboards, scripts should not assume that custom
						formats will be available to other applications on the
						system. For example, there is a limit to how many custom
						clipboard formats can be registered in Microsoft Windows.
						While it is possible to use any string for
						<a>setData()</a>'s type argument, sticking to the
						[=mandatory data types=] is strongly recommended.

		1. Else, the |items| list is empty. Follow these steps to determine
			whether to clear the clipboard:

			1. If the list of items is empty and the |clear-was-called|
				flag is <i>true</i>, then

				1. If the |types-to-clear| list is empty, then

					1. Clear the clipboard

				1. Else

					1. Remove types in the |types-to-clear| list from the
						clipboard in an operating system and implementation-specific
						way

						Issue: The "remove specific types from clipboard" feature is
						at risk. It doesn't seem all that important, and it's
						unclear if it can be implemented easily across relevant
						platforms.

	</div><!-- algorithm -->

	<div class="algorithm" data-algorithm="write-blobs-to-clipboard">
	<h3 id="to-write-blobs-to-clipboard"><dfn>write blobs and option to the clipboard</dfn></h3>

		: Input
		:: |items|, a [=sequence=]&lt;{{Blob}}&gt;
		:: |presentationStyle|, a [=ClipboardItem/clipboard item=]'s [=presentation style=]

		: Output
		:: None

		1. Let |webCustomFormats| be a [=sequence=]&lt;{{Blob}}&gt;.

		1. For each |item| in |items|:

			1. Let |formatString| be the result of running [=os specific well-known format=] given |item|'s {{Blob/type}}.

			1. If |formatString| is empty then follow the below steps:

				1. Let |webCustomFormatString| be the |item|'s {{Blob/type}}.

				1. Let |webCustomFormat| be an empty {{Blob/type}}.

				1. If |webCustomFormatString| [=string/starts with=] `"web "` prefix, then remove the `"web "` prefix and store the remaining string in |webMimeTypeString|.
				
				1. Let |webMimeType| be the result of [=parsing a MIME type=] given |webMimeTypeString|.

				1. If |webMimeType| is failure, then abort all steps.
				
				1. Let |webCustomFormat|'s {{Blob/type}}'s [=MIME type/essence=] equal to |webMimeType|.
				
				1. Set |item|'s {{Blob/type}} to |webCustomFormat|.

				1. Append |webCustomFormat| to |webCustomFormats|.

			1. Let |payload| be the result of [=UTF-8 decoding=] |item|'s underlying byte sequence.

			1. Insert |payload| and |presentationStyle| into the [=system clipboard=] using |formatString| as the native clipboard format.

			Issue: some OSs contain multiple clipboard (e.g. Linux, "primary", "secondary", "selection"). Define to which of those data is written.

		1. [=Write web custom formats=] given |webCustomFormats|.

	</div><!-- algorithm -->

	<div class="algorithm" data-algorithm="os-specific-well-known-format">
	<h3 id="to-os-specific-well-known-format"><dfn>os specific well-known format</dfn></h3>

		: Input
		:: |mimeType|, a {{Blob/type}}

		: Output
		:: |wellKnownFormat|, a platform specific string type. On Mac it's NSPasteboardType, on Windows it's LPCWSTR and Linux it's a const char*.

		<p class=note>
		For Windows see https://un5n6892w35t1nyda79dnd8.julianrbryant.com/en-us/windows/win32/dataxchg/standard-clipboard-formats and
		https://docs.microsoft.com/en-us/windows/win32/dataxchg/about-atom-tables?redirectedfrom=MSDN
		For Mac see https://un5j2j18xhuv2enuvv18xd8.julianrbryant.com/documentation/appkit/nspasteboardtype
		</p>

		1. Let |wellKnownFormat| be an empty string.

		1. If |mimeType|'s [=MIME type/essence=] is "text/plain", then

				On Windows, follow the convention described below:

				1. Assign CF_UNICODETEXT to |wellKnownFormat|.

				On MacOS, follow the convention described below:

				1. Assign NSPasteboardTypeString to |wellKnownFormat|.

				On Linux, ChromeOS, and Android, follow the convention described below:

				1. Assign "text/plain" to |wellKnownFormat|.

		1. Else, if |mimeType|'s [=MIME type/essence=] is "text/html", then

				On Windows, follow the convention described below:

				1. Assign CF_HTML to |wellKnownFormat|.

				On MacOS, follow the convention described below:

				1. Assign NSPasteboardTypeHTML to |wellKnownFormat|.

				On Linux, ChromeOS, and Android, follow the convention described below:

				1. Assign "text/html" to |wellKnownFormat|.

		1. Else, if |mimeType|'s [=MIME type/essence=] is "image/png", then

				On Windows, follow the convention described below:

				1. Assign "PNG" to |wellKnownFormat|.

				On MacOS, follow the convention described below:

				1. Assign NSPasteboardTypePNG to |wellKnownFormat|.

				On Linux, ChromeOS, and Android, follow the convention described below:

				1. Assign "image/png" to |wellKnownFormat|.

		1. Else, if |mimeType|'s [=MIME type/essence=] is "image/svg+xml", then

				On Windows, follow the convention described below:

				1. Assign CFSTR_MIME_SVG_XML to |wellKnownFormat|.

				On MacOS, follow the convention described below:

				1. Assign UTTypeSVG to |wellKnownFormat|.

				On Linux, ChromeOS, and Android, follow the convention described below:

				1. Assign "image/svg+xml" to |wellKnownFormat|.

		1. Return |wellKnownFormat|.

	</div><!-- algorithm -->

	<div class="algorithm" data-algorithm="well-known-mime-type-from-os-specific-format">
	<h3 id="to-well-known-mime-type-from-os-specific-format"><dfn>well-known mime type from os specific format</dfn></h3>

		: Input
		:: |osFormatName|, a platform specific string type. On Mac it's NSPasteboardType, on Windows it's LPCWSTR and Linux it's a const char*.

		: Output
		:: |mimeType|, a [=/MIME type=]

		<p class=note>
		For Windows see https://un5n6892w35t1nyda79dnd8.julianrbryant.com/en-us/windows/win32/dataxchg/standard-clipboard-formats and
		https://docs.microsoft.com/en-us/windows/win32/dataxchg/about-atom-tables?redirectedfrom=MSDN
		For Mac see https://un5j2j18xhuv2enuvv18xd8.julianrbryant.com/documentation/appkit/nspasteboardtype
		</p>

		On Windows, follow the convention described below:

			1. If |osFormatName| "UnicodeText", then set |mimeTypeString| to "text/plain".

			1. Else, if |osFormatName| "HTML Format", then set |mimeTypeString| to "text/html".

			1. Else, if |osFormatName| "PNG", then set |mimeTypeString| to "image/png".

			1. Else, if |osFormatName| CFSTR_MIME_SVG_XML, then set |mimeTypeString| to "image/svg+xml".


		On MacOS, follow the convention described below:

			1. If |osFormatName| is NSPasteboardTypeString, then set |mimeTypeString| to "text/plain".

			1. Else, if |osFormatName| is NSPasteboardTypeHTML, then set |mimeTypeString| to "text/html".

			1. Else, if |osFormatName| NSPasteboardTypePNG, then set |mimeTypeString| to "image/png".

			1. Else, if |osFormatName| UTTypeSVG, then set |mimeTypeString| to "image/svg+xml".


		On Linux, ChromeOS, and Android, follow the convention described below:

			1. If |osFormatName| is "text/plain", then set |mimeTypeString| to "text/plain".
			
			1. Else, if |osFormatName| "text/html", then set |mimeTypeString| to "text/html".
			
			1. Else, if |osFormatName| "image/png", then set |mimeTypeString| to "image/png".

			1. Else, if |osFormatName| "image/svg+xml", then set |mimeTypeString| to "image/svg+xml".


		1. Let |mimeType| be the result of [=parsing a MIME type=] given |mimeTypeString|.

		1. Return |mimeType|.

	</div><!-- algorithm -->

	<div class="algorithm" data-algorithm="read-web-custom-format">
	<h3 id="to-read-web-custom-format"><dfn>read web custom format</dfn></h3>

		: Input
		:: |item|, a [=/clipboard item=]

		1. Let |webCustomFormatMap| be the [=os specific custom map name=].

		1. Read |webCustomFormatMap| from the [=system clipboard=].

			Issue: specify in more detail the process of reading a |webCustomFormatMap|.

		1. If |webCustomFormatMap| is empty, then return |item|.

		1. Let |webCustomFormatMapString| be the JSON string deserialized from |webCustomFormatMap|.

			Note: Need a JSON reader to deserialize the content from the |webCustomFormatMap|.

		1. For each (|key|, |value|) in |webCustomFormatMapString|:

			1. Let |mimeType| be the result of [=parsing a MIME type=] given |key|.

			1. If |mimeType| is failure, then continue the loop.

			1. Let |representation| be a new [=representation=].

			1. Set |representation|'s [=representation/MIME type=] to |mimeType|.

			1. Set |representation|'s [=representation/isCustom=] flag to |true|.

			1. Read |webCustomFormat| from the [=system clipboard=] given |value|.
			
			1. If the read is successful, then set |representation|'s [=representation/data=] to the resulting data from the [=system clipboard=], else continue the loop.

			1. Append |representation| to |item|'s [=list of representations=].

	</div><!-- algorithm -->
	
	<div class="algorithm" data-algorithm="write-web-custom-format">
	<h3 id="to-write-web-custom-formats"><dfn>write web custom formats</dfn></h3>

		: Input
		:: |items|,  a [=sequence=]&lt;{{Blob}}&gt;

		1. Let |idx| be a number initialized to 0.

		1. Let |webCustomFormatMap| be the [=os specific custom map name=].

		1. Let |webCustomFormatMapString| be an empty JSON string.

		1. For each |item| in |items|:

			1. Let |webCustomFormat| be the [=os specific custom name=].

			1. Let |webCustomFormatIdx| be the result of appending |idx| to |webCustomFormat|.

			1. Insert |item|'s {{Blob/type}} as key and |webCustomFormatIdx| as value into the |webCustomFormatMapString| using a JSON serializer.

				Note: Need a JSON writer to serialize the content into the |webCustomFormatMapString|.

			1. Insert the |item| into the [=system clipboard=] using |webCustomFormatIdx| as the format.

			1. Increment |idx|.

			1. If |idx| is greater than 100, then break from this loop.

		1. Insert the |webCustomFormatMapString| into the [=system clipboard=] using |webCustomFormatMap| as the format.


	</div><!-- algorithm -->

	<div class="algorithm" data-algorithm="os-specific-custom-map-name">
	<h3 id="to-os-specific-custom-map-name"><dfn>os specific custom map name</dfn></h3>

		: Output
		:: |webCustomFormatMap|, a string

		On Windows, follow the convention described below:

		1. Assign "Web Custom Format Map" to |webCustomFormatMap|.

		1. Return |webCustomFormatMap|.

		On MacOS, follow the convention described below:

		1. Assign "org.w3.web-custom-format.map" to |webCustomFormatMap|.

		1. Return |webCustomFormatMap|.

		On Linux, ChromeOS, and Android, follow the convention described below:

		1. Assign "application/web;type=\"custom/formatmap\"" to |webCustomFormatMap|.

		1. Return |webCustomFormatMap|.

	</div><!-- algorithm -->

	<div class="algorithm" data-algorithm="os-specific-custom-name">
	<h3 id="to-os-specific-custom-name"><dfn>os specific custom name</dfn></h3>

		: Output
		:: |webCustomFormat|, a string

		On Windows, follow the convention described below:

		1. Assign "Web Custom Format" to |webCustomFormat|.

		1. Return |webCustomFormat|.

		On MacOS, follow the convention described below:

		1. Assign "org.w3.web-custom-format.type-" to |webCustomFormat|.

		1. Return |webCustomFormat|.

		On Linux, ChromeOS, and Android, follow the convention described below:

		1. Assign "application/web;type="custom/format" to |webCustomFormat|.

		1. Return |webCustomFormat|.

	</div><!-- algorithm -->

	<div class="algorithm" data-algorithm="algo-fire-a-clipboard-event">
	<h3 id="to-fire-a-clipboard-event"><dfn>fire a clipboard event</dfn></h3>

		: Input
		:: |e|, the {{ClipboardEvent}} to fire

		: Output
		:: None

		1. Let |clear-was-called| be <em>false</em>

		1. Let |types-to-clear| be an empty list

		1. Let |clipboard-event-data| be a new {{DataTransfer}} object with an empty
			{{DataTransfer/items}} list.

		1. Let |clipboard-entry| be the sequence number of the current
			clipboard content, or null if the OS clipboard does not support
			sequence numbers

		1. Let |trusted| be <em>true</em> if the event is generated by the
			user agent, <em>false</em> otherwise

		1. Let |target| be set as follows:

			1. If the context is editable, then

				1. Set |target| to be the element that contains the
					start of the visible selection or cursor in document order,
					or [=the body element=] if there is no visible selection or cursor.

			1. Else, if the context is not editable, then

				1. Set |target| to the focused node, or [=the body element=] if no node
					has focus.

		1. Process the event as follows:

			1. If |e| is "paste", then

				1. Set the |clipboard-event-data|'s
					internal [=drag data store mode=] flag to
					<a lt="concept dnd ro">read-only</a>.

				1. If |trusted| is <em>true</em>, or the
					implementation is configured to give script-generated events
					read access to the OS clipboard

					1. For each |clipboard-part| on the OS clipboard, carry out these steps:

						1. If |clipboard-part| contains plain text, then

							1. Ensure the text is in the encoding the
								scripting engine uses internally

							1. Let |new-data| be a new {{DataTransferItem}} with
								[=drag data item kind=] set to <em>string</em> and
								[=drag data item type string=] set to <em>text/plain</em>.

							1. Set |new-data|'s data to the plain text.

							1. Add |new-data| to |clipboard-event-data|'s {{DataTransfer/items}}

						1. If |clipboard-part| represents file
							references, then for each file reference:

							1. Determine MIME type of referenced file

							1. Let |new-data| be a new {{DataTransferItem}} with
								[=drag data item kind=] set to <em>file</em> and
								[=drag data item type string=] set to the
								corresponding MIME type, or
								<code>application/octet-stream</code> if the
								file's type is unknown.

							1. Set |new-data|'s data to the file reference data.

							1. Add |new-data| to |clipboard-event-data|'s {{DataTransfer/items}}

						1. If |clipboard-part| contains HTML- or
							XHTML-formatted text, according to the operating
							system's convention for describing such clipboard
							formats, then

							1. If the implementation supports pasting HTML, then
								the implementation <em>must</em> process the
								markup by calling [=process an html paste event=]
								with |clipboard-part| and |clipboard-event-data|.

						1. If |clipboard-part| contains data in
							another supported binary or text-based format (see
							[=mandatory data types=]), then

							1. Determine the MIME type of the data

							1. Let |new-data| be a new {{DataTransferItem}}
								with [=drag data item kind=] set to
								<em>file</em>, [=drag data item type string=]
								set to the corresponding MIME type

							1. Set |new-data|'s data to be the binary or text-based data.

							1. Add |new-data| to |clipboard-event-data|'s {{DataTransfer/items}}

				1. Update |clipboard-event-data|'s {{DataTransfer/files}} property to match
					entries in |clipboard-event-data|'s {{DataTransfer/items}}.

				1. Update |clipboard-event-data|'s {{DataTransfer/types}} property to match
					entries in |clipboard-event-data|'s {{DataTransfer/items}}.

			1. If |e| is "copy" or "cut", then

				1. Set the associated {{DataTransfer}} object's internal
					[=drag data store mode=] flag to <a lt="concept dnd rw">read/write</a>

		1. Set |e|'s {{ClipboardEvent/clipboardData}} to |clipboard-event-data|.

		1. Set |e|'s {{Event/isTrusted}} to |trusted|.

		1. Set |e|'s {{Event/composed}} to true.

		1. Dispatch the event |e| which bubbles and is cancelable, and which
			uses the {{ClipboardEvent}} interface, at |target|.

			Implementation requirements for access to data during event
			dispatch are defined in [[!HTML]]. Some additional clipboard
			event-specific processing rules are given below:

			Issue: Why here? Why not in the HTML spec?

			1. If a script calls <a>clearData()</a> or
				{{DataTransferItemList/clear()}} and the {{DataTransfer}}
				object's internal [=drag data store mode=] flag is
				<a lt="concept dnd rw">read/write</a>, then

				1. Set the |clear-was-called| flag to true. If an
					argument is given, add the argument to the
					|types-to-clear| list.

			1. If a script calls <a>setData()</a> or modifies items and the
				|clear-was-called| flag is true, then

				1. If the |types-to-clear| list is empty, then

					1. Set the |clear-was-called| flag to false, then

				1. Else, if <a>setData()</a>'s <code>type</code> argument or
					the new item's [=drag data item type string=] is
					found in the |types-to-clear| list, then

					1. Remove it from the list. If the list is now empty,
						set the |clear-was-called| flag to false.

			1. If a script calls <a>getData()</a> or accesses items in the
				{{DataTransferItemList}} and |clipboard-entry| is
				set, then

				1. Check that the clipboard data's sequence number matches
					|clipboard-entry|. If the clipboard no longer
					contains the same entry, set the {{DataTransferItemList}}
					object's internal [=drag data store mode=] to
					<a lt="concept dnd p">protected</a>.

			Advisement: Warning! A malicious script listening to a paste event may set
			up a never-ending loop in order to read what the user places on
			the clipboard in the future. On platforms where a clipboard
			sequence number is not available, other limitations should be
			implemented.

	</div><!-- algorithm -->

	<div class="algorithm" data-algorithm="process-an-html-paste-event">
	<h3 id="to-process-html-paste-event"><dfn>process an HTML paste event</dfn></h3>

		: Input
		:: |clipboard-part|, the clipboard part to process
		:: |clipboard-event-data|, the {{DataTransfer}} object for this event

		: Output
		:: None

		1. Let |new-data| be a new {{DataTransferItem}} with
			[=drag data item kind=] set to <em>Plain Unicode string</em>,
			[=drag data item type string=] set to <em>text/html</em> or
			<em>application/xhtml+xml</em> accordingly.

		1. Extract the markup from |clipboard-part| and use the relevant parser to
			construct a DOM tree.

		1. If the markup's source URL is known, then resolve all relative URLs in
			HREF and SRC attributes using the source URL as base URL, and set the
			respective attributes to the resolved absolute URL.

		1. If the markup's origin is from a local application, then check whether
			there are references to local files and/or other parts of the OS
			clipboard's contents. If such references are found, references to
			sub-parts <em>must</em> be replaced by content-id references using the
			cid: URL scheme [[!RFC2392]]. To do so, process each attribute
			referencing a local file or clipboard part according to the following
			steps:

			Issue: Are these steps necessary? Do we know about native (platform)
			clipboard implementations that support multiple parts with internal
			references?

			Issue: This feature is at risk because it's unclear whether it is
			required, and because it's hard to test in a cross-platform way.

			1. If |clipboard-event-data|'s {{DataTransfer/items}} already
				contains an entry for the referenced file or clipboard part, then

				1. Set |itemNumber| to the index of the existing
					entry.

			1. Else,

				1. Let |new-file-data| be a new {{DataTransferItem}} with
					[=drag data item kind=] set to "file", and
					[=drag data item type string=] set to the MIME type of
					the file or clipboard part if known, or
					<code>application/octet-stream</code> if the
					file's type is unknown.

				1. Let |file-info| be a new {{File}} object with {{File/name}}
					set to the name part of the HTML attribute contents,
					and {{File/lastModified}} set to the
					timestamp of the referenced file or 0 if the entry
					references a clipboard part.

				1. Set |new-file-data|'s internal {{File}} object to |file-info|.

				1. Add |new-file-data| to |clipboard-event-data|'s {{DataTransfer/items}}
					and let |itemNumber| be the index of this entry in the
					{{DataTransferItemList}}.

			1. Update the DOM attribute that referenced the local file or
				clipboard part to contain the string 'cid:' followed by
				|itemNumber|.

		1. Serialize the processed DOM and update |new-data| with the resulting
			HTML code.

		1. Add |new-data| to |clipboard-event-data|'s {{DataTransfer/items}}.


	</div><!-- algorithm -->