Editorial review: Document the Summarizer API

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

@@ -0,0 +1,48 @@
+---
+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 summarizer download.
+
+EDITORIAL: Again, I'm not really sure about exactly what this is showing the progress of.
+
+## 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,52 @@
+---
+title: CreateMonitor
+slug: Web/API/CreateMonitor
+page-type: web-api-interface
+status:
+  - experimental
+browser-compat: api.CreateMonitor
+---
+
+{{APIRef("Summarizer API")}}{{SeeCompatTable}}
+
+The **`CreateMonitor`** interface of the Writing Assistance APIs ({{domxref("Summarizer API", "Summarizer API", "", "nocode")}} provides information on the progress of a summarizer download.
+
+{{InheritanceDiagram}}
+
+## Events
+
+_Inherits events from its parent, {{DOMxRef("EventTarget")}}._
+
+- {{domxref("CreateMonitor/downloadprogress_event", "downloadprogress")}} {{Experimental_Inline}}
+  - : Fired when progress is made on the summarizer download.
+
+## Examples
+
+```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);
+```
+
+EDITORIAL: I can get this to work, but I'm not really sure what exactly it is monitoring progress of. It would be good to get some more information on this.
+
+## 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,107 @@
+---
+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 an array containing a single value representing the browser's primary language.
+    - `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 an array containing a single value representing the browser's primary language.
+    - `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 a string representing the browser's primary language.
+    - `type`
+      - : An enumerated value specifying the {{domxref("Summarizer.type", "type")}} of summary you want this `Summarizer` to generate. defaults to `key-points`.
+
+EDITORIAL: I don't actually know what the language-related properties default to, or how the browser determines whether a language value is valid for particular browser or not. Needs to be researched.
+
+### 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.
+- `downloadable`
+  - : The browser does not support the given configuration, but it could do if an updated language model were downloaded.
+- `downloading`
+  - : The browser does not support the given configuration, but it will do when a currently-downloading language model update finishes.
+- `unavailable`
+  - : The browser does not support the given configuration.
+
+EDITORIAL: I am guessing at how language model updates are identified and downloaded. Is this something that is done programmatically, or does the app need to instruct the user to do so? I'm assuming how this is handled will be implementation-dependant, but we ought to given an example of how Chrome does it. I probably need to give some more details on "best fit" languages, as per the example mentioned in the spec. More research needed.
+
+### 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 availability = await Summarizer.availability({
+  type: "tl;dr",
+  length: "short",
+  format: "markdown",
+  expectedInputLanguages: ["en-US"],
+  outputLanguage: "en-US",
+});
+```
+
+### 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,91 @@
+---
+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 an array containing a single value representing the browser's primary language.
+    - `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 an array containing a single value representing the browser's primary language.
+    - `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/reporting code to be run in response to LLM download progress.
+    - `outputLanguage`
+      - : A string specifying the expected language of summaries generated by the `Summarizer`, which should be a valid BCP 47 language tag. Defaults to a string representing the browser's primary language.
+    - `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`.
+
+EDITORIAL: I don't actually know what the language-related properties default to, or how the browser determines whether a language value is valid for particular browser or not. Needs to be researched.
+
+EDITORIAL: I also don't know what the monitor functionality does or how it works. Again, needs researching.
+
+EDITORIAL: Aborting the call via an abort signal doesn't seem to work. Am I missing something?
+
+### 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();
+```
+
+EDITORIAL: From reading the spec, it sounds like I need to use this along with an `AbortController`, but I'm not sure what this would look like.
+
+## 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.