recursal/MDN huggingface dataset:
XRLightEstimate: primaryLightDirection property
===============================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The *read-only* **`primaryLightDirection`** property of the `XRLightEstimate` interface returns a `DOMPointReadOnly` representing the direction to the primary light source from the `probeSpace` of an `XRLightProbe`.

Value
-----

A `DOMPointReadOnly` object. If no estimated values from the user's environment are available, the point will be `{ x: 0.0, y: 1.0, z: 0.0, w: 0.0 }`, representing a light shining straight down from above.

Examples
--------

 Within an `XRFrame` loop, you can use the `primaryLightDirection` and `primaryLightIntensity` properties
 to render shadows based on the most prominent light source, for example.


```js
const lightProbe = await xrSession.requestLightProbe();

// frame loop
function onXRFrame(time, xrFrame) {
  let lightEstimate = xrFrame.getLightEstimate(lightProbe);

  // Render lights

  // Available properties
  lightEstimate.primaryLightDirection;
  lightEstimate.primaryLightIntensity;
}
```

Specifications
--------------

| Specification |
| --- |
| WebXR Lighting Estimation API Level 1 # dom-xrlightestimate-primarylightdirection |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `XRLightEstimate.primaryLightIntensity`
* `XRLightProbe.probeSpace`
XRLightEstimate: sphericalHarmonicsCoefficients property
========================================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The *read-only* **`sphericalHarmonicsCoefficients`** property of the `XRLightEstimate` interface returns a `Float32Array` containing 9 spherical harmonics coefficients.

Spherical harmonic lighting is a technique that uses spherical functions instead of standard lighting equations. See Wikipedia for more information.

Value
-----

A `Float32Array` containing 9 spherical harmonics coefficients. The array contains 27 elements in total, with every 3 elements defining red, green, and blue components for each coefficient.

The first 3 elements must be a valid lighting estimate component; the rest may be 0 due to privacy settings or limitations of the device to provide more data.

Examples
--------

Within an `XRFrame` loop, you can use the `sphericalHarmonicsCoefficients` property to light the scene.


```js
const lightProbe = await xrSession.requestLightProbe();

// frame loop
function onXRFrame(time, xrFrame) {
  let lightEstimate = xrFrame.getLightEstimate(lightProbe);

  // Render lights using lightEstimate.sphericalHarmonicsCoefficients
}
```

Specifications
--------------

| Specification |
| --- |
| WebXR Lighting Estimation API Level 1 # dom-xrlightestimate-sphericalharmonicscoefficients |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `XRFrame.getLightEstimate()`
Clipboard: writeText() method
=============================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The **`writeText()`** method of the `Clipboard` interface writes the specified text to the system clipboard, returning a `Promise` that is resolved once the system clipboard has been updated.

Syntax
------


```js
writeText(newClipText)
```

### Parameters

`newClipText`

The string to be written to the clipboard.

### Return value

A `Promise` that is resolved once the clipboard's contents have been updated.

### Exceptions

`NotAllowedError` `DOMException`

Thrown if writing to the clipboard is not allowed.

Security considerations
-----------------------

Writing to the clipboard can only be done in a secure context.

Additional security requirements are covered in the Security consideration section of the API overview topic.

Examples
--------

This example sets the clipboard's contents to the string "<empty clipboard>".


```js
button.addEventListener("click", writeClipboardText("<empty clipboard>"));

async function writeClipboardText(text) {
  try {
    await navigator.clipboard.writeText(text);
  } catch (error) {
    console.error(error.message);
  }
}
```

Specifications
--------------

| Specification |
| --- |
| Clipboard API and events # dom-clipboard-writetext |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Clipboard API
* Image support for Async Clipboard article
* `Clipboard.write()`
* `Clipboard.read()`
* `Clipboard.readText()`
Clipboard: readText() method
============================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The **`readText()`** method of the `Clipboard` interface returns a `Promise` which fulfils with a copy of the textual contents of the system clipboard.

**Note:** To read non-text contents from the clipboard, use the `read()` method instead.
 You can write text to the clipboard using `writeText()`.


Syntax
------


```js
readText()
```

### Parameters

None.

### Return value

A `Promise` that resolves with a string containing the textual contents of the clipboard.

Returns an empty string if the clipboard is empty, does not contain text, or does not include a textual representation among the objects representing the clipboard's contents.

### Exceptions

`NotAllowedError` `DOMException`

Thrown if the access to read the clipboard is not allowed.

`NotFoundError` `DOMException`

Thrown if the clipboard indicates that it contains data that can be represented as a text but is unable to provide a textual representation.

Security considerations
-----------------------

Reading from the clipboard can only be done in a secure context.

Additional security requirements are covered in the Security consideration section of the API overview topic.

Examples
--------

This example retrieves the textual contents of the clipboard and inserts the returned text into a selected element's contents.


```js
const destination = document.getElementById("outbox");
destinationImage.addEventListener("click", () => {
  navigator.clipboard
    .readText()
    .then((clipText) => (destination.innerText = clipText));
});
```

Specifications
--------------

| Specification |
| --- |
| Clipboard API and events # dom-clipboard-readtext |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Clipboard API
* Image support for Async Clipboard article
* `Clipboard.read()`
* `Clipboard.writeText()`
* `Clipboard.write()`
BackgroundFetchEvent: registration property
===========================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`registration`** read-only property of the `BackgroundFetchEvent` interface returns a `BackgroundFetchRegistration` object.

Value
-----

A `BackgroundFetchRegistration`.

Examples
--------

In this example, if the user clicks on the user interface displaying the download progress, this fires the `onbackgroundfetchclick` event. The current `BackgroundFetchRegistration` is returned by calling `event.registration`.


```js
addEventListener("backgroundfetchclick", (event) => {
  console.log(event.registration);
});
```

Specifications
--------------

| Specification |
| --- |
| Background Fetch # dom-backgroundfetchevent-registration |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
BackgroundFetchEvent: BackgroundFetchEvent() constructor
========================================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`BackgroundFetchEvent()`** constructor creates a new `BackgroundFetchEvent` object. This constructor is not typically used as the browser creates these objects itself and provides them to background fetch event callbacks.

Syntax
------


```js
new BackgroundFetchEvent(type, options)
```

### Parameters

`type`

 A string with the name of the event.
 It is case-sensitive and browsers set it to `backgroundfetchabort` or `backgroundfetchclick`.


`options`

An object that, *in addition of the properties defined in `ExtendableEvent()`*, has the following properties:

`registration`

A `BackgroundFetchRegistration` object.


### Return value

A new `BackgroundFetchEvent` object.

Specifications
--------------

| Specification |
| --- |
| Background Fetch # dom-backgroundfetchevent-backgroundfetchevent |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
MessagePort: close() method
===========================

 The **`close()`** method of the `MessagePort`
 interface disconnects the port, so it is no longer active. This stops the flow of
 messages to that port.

**Note:** This feature is available in Web Workers

Syntax
------


```js
close()
```

### Parameters

None.

### Return value

None (`undefined`).

Examples
--------

 In the following code block, you can see a `handleMessage` handler function,
 run when a message is sent back to this document using
 `EventTarget.addEventListener`.


```js
channel.port1.addEventListener("message", handleMessage, false);
function handleMessage(e) {
  para.innerHTML = e.data;
  textInput.value = "";
}

channel.port1.start();
```


You could stop messages being sent at any time using


```js
channel.port1.close();
```

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-messageport-close-dev |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Using channel messaging
MessagePort: postMessage() method
=================================

 The **`postMessage()`** method of the
 `MessagePort` interface sends a message from the port, and optionally,
 transfers ownership of objects to other browsing contexts.

**Note:** This feature is available in Web Workers

Syntax
------


```js
postMessage(message)
postMessage(message, options)
postMessage(message, transfer)
```

### Parameters

`message`

The message you want to send through the channel. This can be of any basic data type. Multiple data items can be sent as an array.

`options` Optional

An optional object containing a `transfer` field with an array of transferable objects to transfer ownership of. The ownership of these objects is given to the destination side and they are no longer usable on the sending side.

`transfer` Optional

An optional array of transferable objects to transfer ownership of. The ownership of these objects is given to the destination side and they are no longer usable on the sending side.

### Return value

None (`undefined`).

Examples
--------

 In the following code block, you can see a new channel being created using the
 `MessageChannel()` constructor. When the
 IFrame has loaded, we pass `MessageChannel.port2` to the IFrame using
 `window.postMessage` along with a message. The iframe receives the message,
 and sends a message back on the `MessageChannel` using `postMessage()`.
 The `handleMessage` handler then responds to a message being sent back from the iframe using
 `onmessage`, putting it into a paragraph —
 `MessageChannel.port1` is listened to, to check when the message arrives.


```js
const channel = new MessageChannel();
const para = document.querySelector("p");

const ifr = document.querySelector("iframe");
const otherWindow = ifr.contentWindow;

ifr.addEventListener("load", iframeLoaded, false);

function iframeLoaded() {
  otherWindow.postMessage("Transferring message port", "\*", [channel.port2]);
}

channel.port1.onmessage = handleMessage;
function handleMessage(e) {
  para.innerHTML = e.data;
}

// in the iframe…

window.addEventListener("message", (event) => {
  const messagePort = event.ports?.[0];
  messagePort.postMessage("Hello from the iframe!");
});
```


For a full working example, see our channel messaging basic demo on GitHub (run it live too).

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-messageport-postmessage-dev |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Using channel messaging
MessagePort: message event
==========================

The **`message`** event is fired on a `MessagePort` object when a message arrives on that channel.

This event is not cancellable and does not bubble.

**Note:** This feature is available in Web Workers

Syntax
------

Use the event name in methods like `addEventListener()`, or set an event handler property.


```js
addEventListener("message", (event) => {});

onmessage = (event) => {};
```

Event type
----------

A `MessageEvent`. Inherits from `Event`.

Event

MessageEventEvent properties
----------------

*This interface also inherits properties from its parent, `Event`.*

`MessageEvent.data` Read only 

The data sent by the message emitter.

`MessageEvent.origin` Read only 

A string representing the origin of the message emitter.

`MessageEvent.lastEventId` Read only 

A string representing a unique ID for the event.

`MessageEvent.source` Read only 

A `MessageEventSource` (which can be a WindowProxy, `MessagePort`, or `ServiceWorker` object) representing the message emitter.

`MessageEvent.ports` Read only 

An array of `MessagePort` objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g. in channel messaging or when sending a message to a shared worker).

Examples
--------

Suppose a script creates a `MessageChannel` and sends one of the ports to a different browsing context, such as another `<iframe>`, using code like this:


```js
const channel = new MessageChannel();
const myPort = channel.port1;
const targetFrame = window.top.frames[1];
const targetOrigin = "https://example.org";

const messageControl = document.querySelector("#message");
const channelMessageButton = document.querySelector("#channel-message");

channelMessageButton.addEventListener("click", () => {
  myPort.postMessage(messageControl.value);
});

targetFrame.postMessage("init", targetOrigin, [channel.port2]);
```


The target can receive the port and start listening for messages on it using code like this:


```js
window.addEventListener("message", (event) => {
  const myPort = event.ports[0];

  myPort.addEventListener("message", (event) => {
    received.textContent = event.data;
  });

  myPort.start();
});
```


Note that the listener must call `MessagePort.start()` before any messages will be delivered to this port. This is only needed when using the `addEventListener()` method: if the receiver uses `onmessage` instead, `start()` is called implicitly:


```js
window.addEventListener("message", (event) => {
  const myPort = event.ports[0];

  myPort.onmessage = (event) => {
    received.textContent = event.data;
  };
});
```

Specifications
--------------

| Specification |
| --- |
| HTML Standard # event-message |
| HTML Standard # handler-messageport-onmessage |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Related events: `messageerror`.
* Using channel messaging
MessagePort: start() method
===========================

 The **`start()`** method of the `MessagePort`
 interface starts the sending of messages queued on the port. This method is only needed
 when using `EventTarget.addEventListener`; it is implied when using
 `onmessage`.

**Note:** This feature is available in Web Workers

Syntax
------


```js
start()
```

### Parameters

None.

### Return value

None (`undefined`).

Examples
--------

 In the following code block, you can see a `handleMessage` handler function,
 run when a message is sent back to this document using `onmessage`:


```js
channel.port1.onmessage = handleMessage;
function handleMessage(e) {
  para.innerHTML = e.data;
}
```


 Another option would be to do this using `EventTarget.addEventListener`,
 however, when this method is used, you need to explicitly call `start()` to
 begin the flow of messages to this document:


```js
channel.port1.addEventListener("message", handleMessage, false);
function handleMessage(e) {
  para.innerHTML = e.data;
  textInput.value = "";
}

channel.port1.start();
```

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-messageport-start-dev |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Using channel messaging
ReadableStream: pipeTo() method
===============================

The **`pipeTo()`** method of the `ReadableStream` interface pipes the current `ReadableStream` to a given `WritableStream` and returns a `Promise` that fulfills when the piping process completes successfully, or rejects if any errors were encountered.

Piping a stream will generally lock it for the duration of the pipe, preventing other readers from locking it.

Syntax
------


```js
pipeTo(destination)
pipeTo(destination, options)
```

### Parameters

`destination`

A `WritableStream` that acts as the final destination for the `ReadableStream`.

`options` Optional

 The options that should be used when piping to the `writable` stream.
 Available options are:


`preventClose`

 If this is set to `true`, the source `ReadableStream` closing will no longer cause the destination `WritableStream` to be closed.
 The method will return a fulfilled promise once this process completes, unless an error is encountered while closing the destination in which case it will be rejected with that error.


`preventAbort`

 If this is set to `true`, errors in the source `ReadableStream` will no longer abort the destination `WritableStream`.
 The method will return a promise rejected with the source's error, or with any error that occurs during aborting the destination.


`preventCancel`

 If this is set to `true`, errors in the destination `WritableStream` will no longer cancel the source `ReadableStream`.
 In this case the method will return a promise rejected with the source's error, or with any error that occurs during canceling the source.
 In addition, if the destination writable stream starts out closed or closing, the source readable stream will no longer be canceled.
 In this case the method will return a promise rejected with an error indicating piping to a closed stream failed, or with any error that occurs during canceling the source.


`signal`

If set to an `AbortSignal` object, ongoing pipe operations can then be aborted via the corresponding `AbortController`.


### Return value

A `Promise` that resolves when the piping process has completed.

### Exceptions

`TypeError`

The `writableStream` and/or `readableStream` objects are not a writable stream/readable stream, or one or both of the streams are locked.

Examples
--------


```js
// Fetch the original image
fetch("png-logo.png")
  // Retrieve its body as ReadableStream
  .then((response) => response.body)
  .then((body) => body.pipeThrough(new PNGTransformStream()))
  .then((rs) => rs.pipeTo(new FinalDestinationStream()));
```


The same example, but using `await`:


```js
(async () => {
  // Fetch the original image
  const response = await fetch("png-logo.png");
  // Retrieve its body as ReadableStream
  response.body
    .pipeThrough(new PNGTransformStream())
    .pipeTo(new FinalDestinationStream());
})();
```

Specifications
--------------

| Specification |
| --- |
| Streams Standard # ref-for-rs-pipe-to④ |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `ReadableStream()` constructor
* Pipe chains
ReadableStream: pipeThrough() method
====================================

The **`pipeThrough()`** method of the `ReadableStream` interface provides a chainable way of piping the current stream through a transform stream or any other writable/readable pair.

Piping a stream will generally lock it for the duration of the pipe, preventing other readers from locking it.

Syntax
------


```js
pipeThrough(transformStream)
pipeThrough(transformStream, options)
```

### Parameters

`transformStream`

 A `TransformStream` (or an object with the structure `{writable, readable}`) consisting of a readable stream and a writable stream working together to transform some data from one form to another.
 Data written to the `writable` stream can be read in some transformed state by the `readable` stream.
 For example, a `TextDecoder`, has bytes written to it and strings read from it, while a video decoder has encoded bytes written to it and uncompressed video frames read from it.


`options` Optional

 The options that should be used when piping to the `writable` stream.
 Available options are:


`preventClose`

If this is set to `true`, closing the source `ReadableStream` will no longer cause the destination `WritableStream` to be closed.

`preventAbort`

If this is set to `true`, errors in the source `ReadableStream` will no longer abort the destination `WritableStream`.

`preventCancel`

If this is set to `true`, errors in the destination `WritableStream` will no longer cancel the source `ReadableStream`.

`signal`

If set to an `AbortSignal` object, ongoing pipe operations can then be aborted via the corresponding `AbortController`.


### Return value

The `readable` side of the `transformStream`.

### Exceptions

`TypeError`

Thrown if the `writable` and/or `readable` property of `transformStream` are undefined.

Examples
--------

In the following example (see Unpack chunks of a PNG for the full code running live, and png-transform-stream for the source code), an image is fetched and its body retrieved as a `ReadableStream`.

Next, we log the contents of the readable stream, use `pipeThrough()` to send it to a new function that creates a gray-scaled version of the stream, then log the new stream's contents too.


```js
// Fetch the original image
fetch("png-logo.png")
  // Retrieve its body as ReadableStream
  .then((response) => response.body)
  .then((rs) => logReadableStream("Fetch Response Stream", rs))
  // Create a gray-scaled PNG stream out of the original
  .then((body) => body.pipeThrough(new PNGTransformStream()))
  .then((rs) => logReadableStream("PNG Chunk Stream", rs));
```

Specifications
--------------

| Specification |
| --- |
| Streams Standard # ref-for-rs-pipe-through② |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `ReadableStream()` constructor
* Pipe chains