Editorial review: Document the Summarizer API

files/en-us/web/api/createmonitor/downloadprogress_event/index.md

@@ -0,0 +1,46 @@
+---
+title: "CreateMonitor: downloadprogress event"
+short-title: downloadprogress
+slug: Web/API/CreateMonitor/downloadprogress_event
+page-type: web-api-event
+status:
+  - experimental
+browser-compat: api.CreateMonitor.downloadprogress_event
+---
+
+{{APIRef("Summarizer API")}}{{SeeCompatTable}}
+
+The **`downloadprogress`** event of the {{domxref("CreateMonitor")}} interface is fired when progress is made on the AI model download.
+
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+
+```js
+addEventListener("downloadprogress", (event) => {});
+
+ondownloadprogress = (event) => {};
+```
+
+## Event type
+
+A {{domxref("ProgressEvent")}}. Inherits from {{domxref("Event")}}.
+
+{{InheritanceDiagram("ProgressEvent")}}
+
+## Examples
+
+See the main {{domxref("CreateMonitor")}} page for an example.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using)
+- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev.

files/en-us/web/api/createmonitor/index.md

@@ -0,0 +1,60 @@
+---
+title: CreateMonitor
+slug: Web/API/CreateMonitor
+page-type: web-api-interface
+status:
+  - experimental
+browser-compat: api.CreateMonitor
+---
+
+{{APIRef("Summarizer API")}}{{SeeCompatTable}}
+
+The **`CreateMonitor`** interface provides information on the progress of an AI model download or some fine-tuning data for the model.
+
+It can be used via:
+
+- {{domxref("Summarizer.create_static", "Summarizer.create()")}}
+- {{domxref("LanguageDetector.create_static", "LanguageDetector.create()")}}
+- {{domxref("Translator.create_static", "Translator.create()")}}
+
+{{InheritanceDiagram}}
+
+## Events
+
+_Inherits events from its parent, {{DOMxRef("EventTarget")}}._
+
+- {{domxref("CreateMonitor/downloadprogress_event", "downloadprogress")}} {{Experimental_Inline}}
+  - : Fired when progress is made on the AI model download.
+
+## Examples
+
+### Basic `CreateMonitor` usage
+
+A `CreateMonitor` instance is used via the `monitor` property of an AI API's `create()` method ({{domxref("Summarizer.create_static", "Summarizer.create()")}} is shown below). The `monitor` property takes a callback function as a value, the argument of which is the `CreateMonitor` instance. You can then monitor download progress via the instance's {{domxref("CreateMonitor/downloadprogress_event", "downloadprogress")}} event.
+
+```js
+const summarizer = await Summarizer.create({
+  sharedContext:
+    "A general summary to help a user decide if the text is worth reading",
+  monitor: (monitor) => {
+    monitor.addEventListener("downloadprogress", (e) => {
+      console.log(`download progress: ${e.loaded}/${e.total}`);
+    });
+  },
+});
+
+const summary = await summarizer.summarize(myText);
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using)
+- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev.

files/en-us/web/api/summarizer/availability_static/index.md

@@ -0,0 +1,118 @@
+---
+title: "Summarizer: availability() static method"
+short-title: availability()
+slug: Web/API/Summarizer/availability_static
+page-type: web-api-static-method
+browser-compat: api.Summarizer.availability_static
+---
+
+{{APIRef("Summarizer API")}}{{securecontext_header}}
+
+The **`availability()`** static method of the {{domxref("Summarizer")}} interface returns an enumerated value that indicates whether the browser AI model supports (or will support) a given `Summarizer` configuration.
+
+## Syntax
+
+```js-nolint
+Summarizer.availability()
+Summarizer.availability(options)
+```
+
+### Parameters
+
+- `options` {{optional_inline}}
+
+  - : An options object specifying a possible configuration for a `Summarizer`. Possible values include:
+
+    - `expectedInputLanguages`
+      - : An array of strings equal to [BCP 47 language tags](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) (as specified in [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646)) specifying the expected languages of the input text. Defaults to `["en"]`.
+    - `expectedContextLanguages`
+      - : An array of strings equal to BCP 47 language tags specifying the expected languages of any provided context strings (either the [`sharedContext`](#sharedContext) passed to the `Summarizer`, or a `context` specified during a {{domxref("Summarizer.summarize", "summarize()")}} or {{domxref("Summarizer.summarizeStreaming", "summarizeStreaming()")}} call). Defaults to `["en"]`.
+    - `format`
+      - : An enumerated value specifying the text {{domxref("Summarizer.format", "format")}} you want summaries returned in. defaults to `markdown`.
+    - `length`
+      - : An enumerated value specifying the relative {{domxref("Summarizer.length", "length")}} for the generated summaries. defaults to `short`.
+    - `outputLanguage`
+      - : A string equal to a BCP 47 language tag specifying the expected language of summaries generated by the `Summarizer`. Defaults to `en`.
+    - `type`
+      - : An enumerated value specifying the {{domxref("Summarizer.type", "type")}} of summary you want this `Summarizer` to generate. defaults to `key-points`.
+
+### Return value
+
+A {{jsxref("Promise")}} that fulfills with an enumerated value indicating whether support is available (or will be available) for a given `Summarizer` configuration, or `null` if support could not be determined.
+
+Possible values include:
+
+- `available`
+  - : The browser supports the given configuration and can be used immediately.
+- `downloadable`
+  - : The browser does support the given configuration, but it first needs to download an AI model, or some fine-tuning data for the model.
+- `downloading`
+  - : The browser does support the given configuration, but it has to finish an ongoing download before it can proceed.
+- `unavailable`
+  - : The browser does not support the given configuration.
+
+### Exceptions
+
+- `NotAllowedError` {{domxref("DOMException")}}
+  - : Thrown if usage of the Summarizer API is blocked by a {{httpheader('Permissions-Policy/summarizer','summarizer')}} {{httpheader("Permissions-Policy")}}.
+- `NotSupportedError` {{domxref("DOMException")}}
+  - : Thrown if the provided `context` is not in language the `Summarizer` supports.
+- `UnknownError` {{domxref("DOMException")}}
+  - : Thrown if the `measureInputUsage()` call failed for any other reason, or a reason the user agent did not wish to disclose.
+
+## Examples
+
+### Basic `availability()` usage
+
+```js
+const options = {
+  sharedContext: "This is a scientific article",
+  type: "key-points",
+  format: "markdown",
+  length: "medium",
+};
+
+const availability = await Summarizer.availability(options);
+let summarizer;
+if (availability === "unavailable") {
+  // The Summarizer API isn't usable
+  return;
+} else if (availability === "available") {
+  // The Summarizer API can be used immediately
+  summarizer = await Summarizer.create(options);
+} else {
+  // The Summarizer API can be used after the model is downloaded
+  summarizer = await Summarizer.create(options);
+  summarizer.addEventListener("downloadprogress", (e) => {
+    console.log(`Downloaded ${e.loaded * 100}%`);
+  });
+}
+```
+
+### Detecting language support
+
+```js
+async function langSupport(lang) {
+  const availability = await Summarizer.availability({
+    expectedInputLanguages: [lang],
+  });
+  return availability;
+}
+
+langSupport("en-US");
+langSupport("fr");
+langSupport("zh-CN");
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using)
+- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev.

files/en-us/web/api/summarizer/create_static/index.md

@@ -0,0 +1,85 @@
+---
+title: "Summarizer: create() static method"
+short-title: create()
+slug: Web/API/Summarizer/create_static
+page-type: web-api-static-method
+browser-compat: api.Summarizer.create_static
+---
+
+{{APIRef("Summarizer API")}}{{securecontext_header}}
+
+The **`create()`** static method of the {{domxref("Summarizer")}} interface creates a new `Summarizer` instance from which to generate summaries.
+
+## Syntax
+
+```js-nolint
+Summarizer.create()
+Summarizer.create(options)
+```
+
+### Parameters
+
+- `options` {{optional_inline}}
+
+  - : An object specifying configuration options for the `Summarizer`. Possible values include:
+
+    - `expectedInputLanguages`
+      - : An array of strings specifying the expected languages of the input text, which should be valid [BCP 47 language tags](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) (as specified in [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646)). Defaults to `["en"]`.
+    - `expectedContextLanguages`
+      - : An array of strings specifying the expected languages of any provided context strings (either the [`sharedContext`](#sharedContext) passed to the `Summarizer`, or a `context` specified during a {{domxref("Summarizer.summarize", "summarize()")}} or {{domxref("Summarizer.summarizeStreaming", "summarizeStreaming()")}} call), which should be valid BCP 47 language tags. Defaults to `["en"]`.
+    - `format`
+      - : An enumerated value specifying the text {{domxref("Summarizer.format", "format")}} you want summaries returned in. defaults to `markdown`.
+    - `length`
+      - : An enumerated value specifying the relative {{domxref("Summarizer.length", "length")}} for the generated summaries. defaults to `short`.
+    - `monitor`
+      - : A callback function with a {{domxref("CreateMonitor")}} argument that enables monitoring download progress of the AI model.
+    - `outputLanguage`
+      - : A string specifying the expected language of summaries generated by the `Summarizer`, which should be a valid BCP 47 language tag. Defaults to `en`.
+    - `sharedContext`
+      - : A {{domxref("Summarizer.sharedContext", "sharedContext")}} string describing the context the pieces of text to summarize are being used in, which helps the `Summarizer` generate more suitable summaries.
+    - `signal`
+      - : An {{domxref("AbortSignal")}} object instance, which allows the `create()` operation to be aborted via the associated {{domxref("AbortController")}}.
+    - `type`
+      - : An enumerated value specifying the {{domxref("Summarizer.type", "type")}} of summary you want this `Summarizer` to generate. defaults to `key-points`.
+
+### Return value
+
+A {{jsxref("Promise")}} that fulfills with a `Summarizer` object instance.
+
+### Exceptions
+
+- `NotAllowedError` {{domxref("DOMException")}}
+  - : Thrown if usage of the Summarizer API is blocked by a {{httpheader('Permissions-Policy/summarizer','summarizer')}} {{httpheader("Permissions-Policy")}}.
+- `NotSupportedError` {{domxref("DOMException")}}
+  - : Thrown if any of the language tags specified in `expectedContextLanguages`, `expectedInputLanguages`, or `outputLanguage` are invalid, or not supported.
+- `OperationError` {{domxref("DOMException")}}
+  - : General-purpose exception thrown if `Summarizer` creation failed for any other reason.
+
+## Examples
+
+### Basic `Summarizer` creation
+
+```js
+const summarizer = await Summarizer.create({
+  sharedContext:
+    "A general summary to help a user decide if the text is worth reading",
+  type: "tl;dr",
+  length: "short",
+  format: "markdown",
+  expectedInputLanguages: ["en-US"],
+  outputLanguage: "en-US",
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using)
+- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev.

files/en-us/web/api/summarizer/destroy/index.md

@@ -0,0 +1,57 @@
+---
+title: "Summarizer: destroy() method"
+short-title: destroy()
+slug: Web/API/Summarizer/destroy
+page-type: web-api-instance-method
+status:
+  - experimental
+browser-compat: api.Summarizer.destroy
+---
+
+{{APIRef("Summarizer API")}}{{SeeCompatTable}}
+
+The **`destroy()`** method of the {{domxref("Summarizer")}} interface destroys the `Summarizer` instance it is called on.
+
+## Syntax
+
+```js-nolint
+destroy()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+None ({{jsxref("undefined")}}).
+
+## Examples
+
+### Basic `destroy()` usage
+
+```js
+const summarizer = await Summarizer.create({
+  sharedContext:
+    "A general summary to help a user decide if the text is worth reading",
+  type: "tl;dr",
+  length: "short",
+});
+
+// ...
+
+summarizer.destroy();
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using)
+- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev.