index.bs

<pre class="metadata">
Title: Writing Assistance APIs
Shortname: writing-assistance
Level: None
Status: CG-DRAFT
Group: webml
Repository: webmachinelearning/writing-assistance-apis
URL: https://webmachinelearning.github.io/writing-assistance-apis
Editor: Domenic Denicola, Google https://www.google.com/, d@domenic.me, https://domenic.me/
Abstract: The summarizer, writer, and rewriter APIs provide high-level interfaces to call on a browser or operating system's built-in language model to help with writing tasks.
Markup Shorthands: markdown yes, css no
Complain About: accidental-2119 yes, missing-example-ids yes
Assume Explicit For: yes
Default Biblio Status: current
Boilerplate: omit conformance
Indent: 2
Die On: warning
</pre>

<pre class="link-defaults">
spec:infra; type:dfn; text:user agent
</pre>
<pre class="anchors">
urlPrefix: https://tc39.es/ecma402/; spec: ECMA-402
  type: dfn
    text: [[AvailableLocales]]; url: sec-internal-slots
    text: Unicode canonicalized locale identifier; url: sec-language-tags
  type: abstract-op
    text: LookupMatchingLocaleByBestFit; url: sec-lookupmatchinglocalebybestfit
    text: IsStructurallyValidLanguageTag; url: sec-isstructurallyvalidlanguagetag
    text: CanonicalizeUnicodeLocaleId; url: sec-canonicalizeunicodelocaleid
</pre>

<style>
dl.props { display: grid; grid-template-columns: max-content auto; row-gap: 0.25em; column-gap: 1em; }
dl.props > dt { grid-column-start: 1; margin: 0; }
dl.props > dd { grid-column-start: 2; margin: 0; }
p + dl.props { margin-top: -0.5em; }

.enum-table tbody th { white-space: nowrap; }
</style>

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

For now, see the [explainer]([REPOSITORYURL]).

<h2 id="shared-ai-api">Shared AI APIs and infrastructure</h2>

<xmp class="idl">
partial interface WindowOrWorkerGlobalScope {
  [Replaceable, SecureContext] readonly attribute AI ai;
};

[Exposed=(Window,Worker), SecureContext]
interface AI {};

[Exposed=(Window,Worker), SecureContext]
interface AICreateMonitor : EventTarget {
  attribute EventHandler ondownloadprogress;
};

callback AICreateMonitorCallback = undefined (AICreateMonitor monitor);

enum AICapabilityAvailability { "readily", "after-download", "no" };
</xmp>

Each {{WindowOrWorkerGlobalScope}} has an <dfn for="WindowOrWorkerGlobalScope">AI namespace</dfn>, an {{AI}} object. Upon creation of the {{WindowOrWorkerGlobalScope}} object, its [=WindowOrWorkerGlobalScope/AI namespace=] must be set to a [=new=] {{AI}} object created in the {{WindowOrWorkerGlobalScope}} object's [=relevant realm=].

The <dfn attribute for="WindowOrWorkerGlobalScope">ai</dfn> getter steps are to return [=this=]'s [=WindowOrWorkerGlobalScope/AI namespace=].

<hr>

[=Tasks=] queued by this specification use the <dfn>AI task source</dfn>.

<hr>

The following are the [=event handlers=] (and their corresponding [=event handler event types=]) that must be supported, as [=event handler IDL attributes=], by all {{AICreateMonitor}} objects:

<table>
  <thead>
    <tr>
      <th>[=Event handler=]
      <th>[=Event handler event type=]
  <tbody>
    <tr>
      <td><dfn attribute for="AICreateMonitor">ondownloadprogress</dfn>
      <td><dfn event for="AICreateMonitor">downloadprogress</dfn>
</table>

<h2 id="summarizer-api">The summarizer API</h2>

<xmp class="idl">
partial interface AI {
  readonly attribute AISummarizerFactory summarizer;
};

[Exposed=(Window,Worker), SecureContext]
interface AISummarizerFactory {
  Promise<AISummarizer> create(optional AISummarizerCreateOptions options = {});
  Promise<AISummarizerCapabilities> capabilities();
};

[Exposed=(Window,Worker), SecureContext]
interface AISummarizer {
  Promise<DOMString> summarize(
    DOMString input,
    optional AISummarizerSummarizeOptions options = {}
  );
  ReadableStream summarizeStreaming(
    DOMString input,
    optional AISummarizerSummarizeOptions options = {}
  );

  readonly attribute DOMString sharedContext;
  readonly attribute AISummarizerType type;
  readonly attribute AISummarizerFormat format;
  readonly attribute AISummarizerLength length;

  undefined destroy();
};

[Exposed=(Window,Worker), SecureContext]
interface AISummarizerCapabilities {
  readonly attribute AICapabilityAvailability available;

  AICapabilityAvailability createOptionsAvailable(
    optional AISummarizerCreateCoreOptions options = {}
  );
  AICapabilityAvailability languageAvailable(DOMString languageTag);
};

dictionary AISummarizerCreateCoreOptions {
  AISummarizerType type = "key-points";
  AISummarizerFormat format = "markdown";
  AISummarizerLength length = "short";
};

dictionary AISummarizerCreateOptions : AISummarizerCreateCoreOptions {
  AbortSignal signal;
  AICreateMonitorCallback monitor;

  DOMString sharedContext;
};

dictionary AISummarizerSummarizeOptions {
  AbortSignal signal;
  DOMString context;
};

enum AISummarizerType { "tl;dr", "teaser", "key-points", "headline" };
enum AISummarizerFormat { "plain-text", "markdown" };
enum AISummarizerLength { "short", "medium", "long" };
</xmp>

Each {{AI}} has an <dfn for="AI">summarizer factory</dfn>, an {{AISummarizerFactory}} object. Upon creation of the {{AI}} object, its [=AI/summarizer factory=] must be set to a [=new=] {{AISummarizerFactory}} object created in the {{AI}} object's [=relevant realm=].

The <dfn attribute for="AI">summarizer</dfn> getter steps are to return [=this=]'s [=AI/summarizer factory=].

<h3 id="summarizer-creation">Creation</h3>

<div algorithm>
  The <dfn method for="AISummarizerFactory">create(|options|)</dfn> method steps are:

  1. If [=this=]'s [=relevant global object=] is a {{Window}} whose [=associated Document=] is not [=Document/fully active=], then return [=a promise rejected with=] an "{{InvalidStateError}}" {{DOMException}}.

  1. If |options|["{{AISummarizerCreateOptions/signal}}"] [=map/exists=] and is [=AbortSignal/aborted=], then return [=a promise rejected with=] |options|["{{AISummarizerCreateOptions/signal}}"]'s [=AbortSignal/abort reason=].

  1. Let |fireProgressEvent| be an algorithm taking two arguments that does nothing.

  1. If |options|["{{AISummarizerCreateOptions/monitor}}"] [=map/exists=], then:

    1. Let |monitor| be a [=new=] {{AICreateMonitor}} created in [=this=]'s [=relevant realm=].

    1. [=Invoke=] |options|["{{AISummarizerCreateOptions/monitor}}"] with « |monitor| » and "`rethrow`".

      If an exception |e| is thrown, return [=a promise rejected with=] |e|.

    1. Set |fireProgressEvent| to an algorithm taking arguments |loaded| and |total|, which performs the following steps:

      1. [=Assert=]: this algorithm is running [=in parallel=].

      1. [=Queue a global task=] on the [=AI task source=] given [=this=]'s [=relevant global object=] to perform the following steps:

        1. [=Fire an event=] named {{AICreateMonitor/downloadprogress}} at |monitor|, using {{ProgressEvent}}, with the {{ProgressEvent/loaded}} attribute initialized to |loaded|, the {{ProgressEvent/total}} attribute initialized to |total|, and the {{ProgressEvent/lengthComputable}} attribute initialized to true.

  1. Let |abortedDuringDownload| be false.

    <p class="note">This variable will be written to from the [=event loop=], but read from [=in parallel=].

  1. If |options|["{{AISummarizerCreateOptions/signal}}"] [=map/exists=], then [=AbortSignal/add|add the following abort steps=] to |options|["{{AISummarizerCreateOptions/signal}}"]:

    1. Set |abortedDuringDownload| to true.

  1. Let |promise| be [=a new promise=] created in [=this=]'s [=relevant realm=].

  1. [=In parallel=]:

    1. Let |availability| be the [=current summarizer create options availability=] given |options|["{{AISummarizerCreateCoreOptions/type}}"], |options|["{{AISummarizerCreateCoreOptions/format}}"], and |options|["{{AISummarizerCreateCoreOptions/length}}"].

    1. Switch on |availability|:

    <dl class="switch">
      : null
      ::
        1. [=Reject=] |promise| with an "{{UnknownError}}" {{DOMException}}.

        1. Abort these steps.

      : "{{AICapabilityAvailability/no}}"
      ::
        1. [=Reject=] |promise| with a "{{NotSupportedError}}" {{DOMException}}.

        1. Abort these steps.

      : "{{AICapabilityAvailability/readily}}"
      ::
        1. If [=initializing the summarization model=] given |promise| and |options| returns false, then abort these steps.

        1. Let |totalBytes| be the total size of the previously-downloaded summarization capabilities, in bytes.

        1. [=Assert=]: |totalBytes| is greater than 0.

        1. Perform |fireProgressEvent| given 0 and |totalBytes|.

        1. Perform |fireProgressEvent| given |totalBytes| and |totalBytes|.

        1. [=Finalize summarizer creation=] given |promise| and |options|.

      : "{{AICapabilityAvailability/after-download}}"
      ::
        1. Initiate the download process for everything the user agent needs to summarize text according to |options|["{{AISummarizerCreateCoreOptions/type}}"], |options|["{{AISummarizerCreateCoreOptions/format}}"], or |options|["{{AISummarizerCreateCoreOptions/length}}"].

        1. Run the following steps, but [=abort when=] |abortedDuringDownload| becomes true:

          1. Wait for the total number of bytes to be downloaded to become determined, and let that number be |totalBytes|.

          1. Let |lastProgressTime| be the [=monotonic clock=]'s [=monotonic clock/unsafe current time=].

          1. Perform |fireProgressEvent| given 0 and |totalBytes|.

          1. While true:

            1. If one or more bytes have been downloaded, then:

              1. If the [=monotonic clock=]'s [=monotonic clock/unsafe current time=] minus |lastProgressTime| is greater than 50 ms, then:

                1. Let |bytesSoFar| be the number of bytes downloaded so far.

                1. [=Assert=]: |bytesSoFar| is greater than 0 and less than or equal to |totalBytes|.

                1. Perform |fireProgressEvent| given |bytesSoFar| and |totalBytes|.

                1. If |bytesSoFar| equals |totalBytes|, then [=iteration/break=].

                1. Set |lastProgressTime| to the [=monotonic clock=]'s [=monotonic clock/unsafe current time=].

            1. Otherwise, if downloading has failed and cannot continue, then:

              1. [=Queue a global task=] on the [=AI task source=] given [=this=]'s [=relevant global object=] to [=reject=] |promise| with a "{{NetworkError}}" {{DOMException}}.

              1. Abort these steps.

        1. [=If aborted=], then:
          1. [=Queue a global task=] on the [=AI task source=] given [=this=]'s [=relevant global object=] to perform the following steps:

            1. [=Assert=]: |options|["{{AISummarizerCreateOptions/signal}}"]'s is [=AbortSignal/aborted=].

            1. [=Reject=] |promise| with |options|["{{AISummarizerCreateOptions/signal}}"]'s [=AbortSignal/abort reason=].

          1. Abort these steps.

        1. If [=initializing the summarization model=] given |promise| and |options| returns false, then abort these steps.

        1. [=Finalize summarizer creation=] given |promise| and |options|.
    </dl>

  1. Return |promise|.
</div>

<div algorithm>
  To <dfn>initialize the summarization model</dfn>, given a {{Promise}} |promise| and an {{AISummarizerCreateOptions}} |options|:

  1. [=Assert=]: these steps are running [=in parallel=].

  1. Perform any necessary initialization operations for the AI model backing the [=user agent=]'s summarization capabilities.

    This could include loading the model into memory, loading |options|["{{AISummarizerCreateOptions/sharedContext}}"] into the model's context window, or loading any fine-tunings necessary to support |options|["{{AISummarizerCreateCoreOptions/type}}"], |options|["{{AISummarizerCreateCoreOptions/format}}"], or |options|["{{AISummarizerCreateCoreOptions/length}}"].

  1. If initialization failed for any reason, then:

    1. [=Queue a global task=] on the [=AI task source=] given |promise|'s [=relevant global object=] to [=reject=] |promise| with an "{{OperationError}}" {{DOMException}}.

    1. Return false.

  1. Return true.
</div>

<div algorithm>
  To <dfn>finalize summarizer creation</dfn>, given a {{Promise}} |promise| and an {{AISummarizerCreateOptions}} |options|:

  1. [=Assert=]: these steps are running [=in parallel=].

  1. [=Assert=]: the [=current summarizer create options availability=] for |options|["{{AISummarizerCreateCoreOptions/type}}"], |options|["{{AISummarizerCreateCoreOptions/format}}"], and |options|["{{AISummarizerCreateCoreOptions/length}}"] is "{{AICapabilityAvailability/readily}}".

  1. [=Queue a global task=] on the [=AI task source=] given |promise|'s [=relevant global object=] to perform the following steps:

    1. If |options|["{{AISummarizerCreateOptions/signal}}"] [=map/exists=] and is [=AbortSignal/aborted=], then:

      1. [=Reject=] |promise| with |options|["{{AISummarizerCreateOptions/signal}}"]'s [=AbortSignal/abort reason=].

      1. Abort these steps.

      <p class="note">This check is necessary in case any code running on the [=agent/event loop=] caused the {{AbortSignal}} to become [=AbortSignal/aborted=] before this [=task=] ran.

    1. Let |summarizer| be a new {{AISummarizer}} object, created in |promise|'s [=relevant realm=], with

      <dl class="props">
        : [=AISummarizer/shared context=]
        :: |options|["{{AISummarizerCreateOptions/sharedContext}}"] if it [=map/exists=]; otherwise null

        : [=AISummarizer/summary type=]
        :: |options|["{{AISummarizerCreateCoreOptions/type}}"]

        : [=AISummarizer/summary format=]
        :: |options|["{{AISummarizerCreateCoreOptions/format}}"]

        : [=AISummarizer/summary length=]
        :: |options|["{{AISummarizerCreateCoreOptions/length}}"]
      </dl>

    1. If |options|["{{AISummarizerCreateOptions/signal}}"] [=map/exists=], then [=AbortSignal/add|add the following abort steps=] to |options|["{{AISummarizerCreateOptions/signal}}"]:

      1. [=AISummarizer/Destroy=] |summarizer| with |options|["{{AISummarizerCreateOptions/signal}}"]'s [=AbortSignal/abort reason=].

    1. [=Resolve=] |promise| with |summarizer|.
</div>

<h3 id="summarizer-capabilities">Capabilities</h3>

<div algorithm>
  The <dfn method for="AISummarizerFactory">capabilities()</dfn> method steps are:

  1. If [=this=]'s [=relevant global object=] is a {{Window}} whose [=associated Document=] is not [=Document/fully active=], then return [=a promise rejected with=] an "{{InvalidStateError}}" {{DOMException}}.

  1. Let |promise| be [=a new promise=] created in [=this=]'s [=relevant realm=].

  1. [=In parallel=]:

    1. Let |availableCreateOptions| be a new [=map=] from [=tuples=] of ({{AISummarizerType}}, {{AISummarizerFormat}}, {{AISummarizerLength}}) values to {{AICapabilityAvailability}} values, initially empty.

    1. [=list/For each=] |type| of {{AISummarizerType}}'s [=enumeration values=]:

      1. [=list/For each=] |format| of {{AISummarizerFormat}}'s [=enumeration values=]:

        1. [=list/For each=] |length| of {{AISummarizerLength}}'s [=enumeration values=]:

          1. Set |availableCreateOptions|[(|type|, |format|, |length|)] to the [=current summarizer create options availability=] given |type|, |format|, and |length|.

    1. Let « |readilyAvailableLanguages|, |afterDownloadAvailableLanguages| » be the [=current summarizer language availabilities=].

    1. If |readilyAvailableLanguages| is null, |afterDownloadAvailableLanguages| is null, or |availableCreateOptions|'s [=map/values=] [=list/contains=] null, then [=queue a global task=] on the [=AI task source=] given [=this=] to perform the following steps:

      1. [=Reject=] |promise| with an "{{UnknownError}}" {{DOMException}}.

    1. Otherwise, [=queue a global task=] on the [=AI task source=] given [=this=] to perform the following steps:

      1. Let |capabilitiesObject| be a new {{AISummarizerCapabilities}} object, created in [=this=]'s [=relevant realm=], with

        <dl class="props">
          : [=AISummarizerCapabilities/available create options=]
          :: |availableCreateOptions|
          : [=AISummarizerCapabilities/readily available languages=]
          :: |readilyAvailableLanguages|
          : [=AISummarizerCapabilities/after-download available languages=]
          :: |afterDownloadAvailableLanguages|
        </dl>

      1. [=Resolve=] |promise| with |capabilitiesObject|.
</div>

<hr>

Every {{AISummarizerCapabilities}} has an <dfn for="AISummarizerCapabilities">available create options</dfn>, a [=map=] from [=tuples=] of ({{AISummarizerType}}, {{AISummarizerFormat}}, {{AISummarizerLength}}) values to {{AICapabilityAvailability}} values, set during creation.

Every {{AISummarizerCapabilities}} has an <dfn for="AISummarizerCapabilities">readily available languages</dfn>, a [=set=] of strings representing BCP 47 language tags, set during creation.

Every {{AISummarizerCapabilities}} has an <dfn for="AISummarizerCapabilities">after-download available languages</dfn>, a [=set=] of strings representing BCP 47 language tags, set during creation.

<div algorithm>
  The <dfn attribute for="AISummarizerCapabilities">available</dfn> getter steps are:

  1. If [=this=]'s [=AISummarizerCapabilities/readily available languages=] and [=AISummarizerCapabilities/after-download available languages=] [=map/is empty|are empty=], then return "{{AICapabilityAvailability/no}}".

  1. If [=this=]'s all of [=this=]'s [=AISummarizerCapabilities/available create options=] [=map/values=] are "{{AICapabilityAvailability/no}}", then return "{{AICapabilityAvailability/no}}".

  1. If [=this=]'s [=AISummarizerCapabilities/readily available languages=] [=map/is empty|are empty=], then return "{{AICapabilityAvailability/after-download}}".

  1. Return "{{AICapabilityAvailability/readily}}".
</div>

<div algorithm>
  The <dfn method for="AISummarizerCapabilities">createOptionsAvailable(|options|)</dfn> method steps are:

  1. Return [=this=]'s [=AISummarizerCapabilities/available create options=][(|options|["{{AISummarizerCreateCoreOptions/type}}"], |options|["{{AISummarizerCreateCoreOptions/format}}"], |options|["{{AISummarizerCreateCoreOptions/length}}"])].
</div>

<div algorithm>
  The <dfn method for="AISummarizerCapabilities">languageAvailable(|languageTag|)</dfn> method steps are:

  1. If [$IsStructurallyValidLanguageTag$](|languageTag|) is false, then throw a {{TypeError}}.

  1. Set |languageTag| to [$CanonicalizeUnicodeLocaleId$](|languageTag|).

  1. Let |bestReadilyAvailableMatch| be [$LookupMatchingLocaleByBestFit$]([=this=]'s [=AISummarizerCapabilities/readily available languages=], |languageTag|).

  1. If |bestReadilyAvailableMatch| is not undefined, then return "{{AICapabilityAvailability/readily}}".

     <p class="note">|bestReadilyAvailableMatch|.\[[locale]] contains the actual language tag from [=this=]'s [=AISummarizerCapabilities/readily available languages=], which might be different from |languageTag|.

  1. Let |bestAfterDownloadAvailableMatch| be [$LookupMatchingLocaleByBestFit$]([=this=]'s [=AISummarizerCapabilities/after-download available languages=], |languageTag|).

  1. If |bestAfterDownloadAvailableMatch| is not undefined, then return "{{AICapabilityAvailability/after-download}}".

     <p class="note">|bestAfterDownloadAvailableMatch|.\[[locale]] contains the actual language tag from [=this=]'s [=AISummarizerCapabilities/after-download available languages=], which might be different from |languageTag|.

  1. Return "{{AICapabilityAvailability/no}}".
</div>

<hr>

<div algorithm>
  The <dfn>current summarizer create options availability</dfn>, given a {{AISummarizerType}} |type|, {{AISummarizerFormat}} |format|, and an {{AISummarizerLength}} |length|, is given by the following steps. They return an {{AICapabilityAvailability}} value or null.

  1. [=Assert=]: this algorithm is running [=in parallel=].

  1. If the user agent supports summarizing text into the type of summary described by |type|, in the format described by |format|, and with the length guidance given by |length| without performing any downloading operations, then return "{{AICapabilityAvailability/readily}}".

  1. If the user agent believes it can summarize text according to |type|, |format|, and |length|, but only after performing a download (e.g., of an AI model or fine-tuning), then return "{{AICapabilityAvailability/after-download}}".

  1. If there is some error attempting to determine whether the user agent supports summarizing text, which the user agent believes to be transient (such that re-querying the [=current summarizer create options availability=] could stop producing such an error), then return null.

  1. Otherwise, return "{{AICapabilityAvailability/no}}".
</div>

<div algorithm>
  The <dfn>current summarizer language availabilities</dfn> are given by the following steps. They return a [=list=] containing two [=list/items=]; the items each are [=sets=] of strings representing [=Unicode canonicalized locale identifiers=], or null. [[!ECMA-402]]

  1. [=Assert=]: this algorithm is running [=in parallel=].

  1. If there is some error attempting to determine whether the user agent supports summarizing text, which the user agent believes to be transient (such that re-querying the [=current summarizer language availabilities=] could stop producing such an error), then return « null, null ».

  1. Let |readilyAvailableLanguages| and |afterDownloadAvailableLanguages| be empty [=sets=].

  1. [=list/For each=] human language |languageTag|, represented as a [=Unicode canonicalized locale identifier=], for which the user agent supports summarizing text written in that language, without performing any downloading operations:

    1. [=set/Append=] |languageTag| to |readilyAvailableLanguages|.

  1. [=list/For each=] human language |languageTag|, represented as a [=Unicode canonicalized locale identifier=], for which the user agent believes it can summarize text written in that language, but only after performing a download (e.g., of an AI model or fine-tuning):

    1. [=Assert=]: |readilyAvailableLanguages| does not [=set/contain=] |languageTag|.

    1. [=set/Append=] |languageTag| to |afterDownloadAvailableLanguages|.

  1. If the [=set/union=] of |readilyAvailableLanguages| and |afterDownloadAvailableLanguages| does not meet the [=language tag set completeness rules=], then:

    1. Let |missingLanguageTags| be the [=set=] of missing language tags necessary to meet the [=language tag set completeness rules=].

    1. [=set/For each=] |languageTag| of |missingLanguageTags|:

      1. <span id="readily-or-after-download-implementation-defined"></span> [=set/Append=] |languageTag| to either |readilyAvailableLanguages| or |afterDownloadAvailableLanguages|. Which of the two sets to append to is [=implementation-defined=], and should be guided by considerations similar to that of [$LookupMatchingLocaleByBestFit$] in terms of keeping "best fallback languages" together.

  1. Return « |readilyAvailableLanguages|, |afterDownloadAvailableLanguages| ».
</div>

<div algorithm>
  The <dfn>language tag set completeness rules</dfn> state that for every [=set/item=] |languageTag|, if |languageTag| has more than one subtag, then the set must also contain a less narrow language tag with the same language subtag and a strict subset of the same following subtags (i.e., omitting one or more).

  <p class="note">This definition is intended to align with that of [=[[AvailableLocales]]=] in <cite>ECMAScript Internationalization API Specification</cite>. [[ECMA-402]]

  <div class="example" id="example-subtags-intro">
    This means that if an implementation supports summarization of "`de-DE`" text, it will also count as supporting "`de`" text.

    The converse direction is supported not by the [=language tag set completeness rules=], but instead by the use of [$LookupMatchingLocaleByBestFit$], which ensures that if an implementation supports summarizing "`de`" text, it also counts as supporting summarization of "`de-CH`", "`de-Latn-CH`", etc.
  </div>

  <div class="example" id="example-subtags-chinese">
    A common setup seen in today's software is to support two types of written Chinese: "traditional Chinese" and "simplified Chinese". Let's suppose that the user agent supports summarizing text written in traditional Chinese readily, and simplified Chinese after a download.

    One way this could be implemented would be for [=current summarizer language availabilities=] to return that « "`zh-Hant`" » is readily available, and « "`zh`", "`zh-Hans`" » is available after download. This return value conforms to the requirements of the [=language tag set completeness rules=], in ensuring that "`zh`" is present. Per <a class="allow-2119" href="#readily-or-after-download-implementation-defined">the "should"-level guidance</a>, the implementation has determined that "`zh`" belongs in the list of after-download available languages, with "`zh-Hans`", instead of in the list of readily available languages, with "`zh-Hant`".

    Combined with the use of [$LookupMatchingLocaleByBestFit$], this means {{AISummarizerCapabilities/languageAvailable()}} will give the following answers:

    <xmp class="language-js">
    c.languageAvailable("zh") === "after-download";
    c.languageAvailable("zh-Hant") === "readily";
    c.languageAvailable("zh-Hans") === "after-download";

    c.languageAvailable("zh-TW") === "readily";          // zh-TW will best-fit to zh-Hant
    c.languageAvailable("zh-HK") === "readily";          // zh-HK will best-fit to zh-Hant
    c.languageAvailable("zh-CN") === "after-download";   // zh-CN will best-fit to zh-Hans

    c.languageAvailable("zh-BR") === "after-download";   // zh-BR will best-fit to zh
    c.languageAvailable("zh-Kana") === "after-download"; // zh-Kana will best-fit to zh
    </xmp>
  </div>
</div>

<h3 id="the-aisummarizer-class">The {{AISummarizer}} class</h3>

Every {{AISummarizer}} has a <dfn for="AISummarizer">shared context</dfn>, a [=string=]-or-null, set during creation.

Every {{AISummarizer}} has a <dfn for="AISummarizer">summary type</dfn>, an {{AISummarizerType}}, set during creation.

Every {{AISummarizer}} has a <dfn for="AISummarizer">summary format</dfn>, an {{AISummarizerFormat}}, set during creation.

Every {{AISummarizer}} has a <dfn for="AISummarizer">summary length</dfn>, an {{AISummarizerLength}}, set during creation.

Every {{AISummarizer}} has a <dfn for="AISummarizer">destruction reason</dfn>, a JavaScript value, initially undefined.

Every {{AISummarizer}} has a <dfn for="AISummarizer">destroyed</dfn> boolean, initially false.

<p class="note">This value is separate from the [=AISummarizer/destruction reason=] so that it can be read from [=in parallel=] during the summarization process.

<hr>

The <dfn attribute for="AISummarizer">sharedContext</dfn> getter steps are to return [=this=]'s [=AISummarizer/shared context=].

The <dfn attribute for="AISummarizer">type</dfn> getter steps are to return [=this=]'s [=AISummarizer/summary type=].

The <dfn attribute for="AISummarizer">format</dfn> getter steps are to return [=this=]'s [=AISummarizer/summary format=].

The <dfn attribute for="AISummarizer">length</dfn> getter steps are to return [=this=]'s [=AISummarizer/summary length=].

<hr>

<div algorithm>
  The <dfn method for="AISummarizer">summarize(|input|, |options|)</dfn> method steps are:

  1. If [=this=]'s [=relevant global object=] is a {{Window}} whose [=associated Document=] is not [=Document/fully active=], then return [=a promise rejected with=] an "{{InvalidStateError}}" {{DOMException}}.

  1. If [=this=]'s [=AISummarizer/destroyed=] is true, then return [=a promise rejected with=] [=this=]'s [=AISummarizer/destruction reason=].

  1. If |options|["{{AISummarizerSummarizeOptions/signal}}"] [=map/exists=] and is [=AbortSignal/aborted=], then return [=a promise rejected with=] |options|["{{AISummarizerSummarizeOptions/signal}}"]'s [=AbortSignal/abort reason=].

  1. Let |abortedDuringSummarization| be false.

    <p class="note">This variable will be written to from the [=event loop=], but read from [=in parallel=].

  1. If |options|["{{AISummarizerSummarizeOptions/signal}}"] [=map/exists=], then [=AbortSignal/add|add the following abort steps=] to |options|["{{AISummarizerSummarizeOptions/signal}}"]:

    1. Set |abortedDuringSummarization| to true.

  1. Let |promise| be [=a new promise=] created in [=this=]'s [=relevant realm=].

  1. Let |context| be |options|["{{AISummarizerSummarizeOptions/context}}"] if it [=map/exists=]; otherwise null.

  1. [=In parallel=]:

    1. Let |summary| be the empty string.

    1. Let |chunkProduced| be the following steps given a [=string=] |chunk|:

      1. [=Queue a global task=] on the [=AI task source=] given [=this=]'s [=relevant global object=] to perform the following steps:

        1. If |abortedDuringSummarization| is true, then:

          1. [=Reject=] |promise| with |options|["{{AISummarizerSummarizeOptions/signal}}"]'s [=AbortSignal/abort reason=].

          1. Abort these steps.

        1. If [=this=]'s [=AISummarizer/destroyed=] is true, then:

          1. [=Reject=] |promise| with [=this=]'s [=AISummarizer/destruction reason=].

          1. Abort these steps.

        1. Append |chunk| to |summary|.

    1. Let |done| be the following steps:

      1. [=Queue a global task=] on the [=AI task source=] given [=this=]'s [=relevant global object=] to perform the following steps:

        1. If |abortedDuringSummarization| is true, then:

          1. [=Reject=] |promise| with |options|["{{AISummarizerSummarizeOptions/signal}}"]'s [=AbortSignal/abort reason=].

          1. Abort these steps.

        1. If [=this=]'s [=AISummarizer/destroyed=] is true, then:

          1. [=Reject=] |promise| with [=this=]'s [=AISummarizer/destruction reason=].

          1. Abort these steps.

        1. [=Resolve=] |promise| with |summary|.

    1. Let |error| be the following steps given [=summarization error information=] |errorInfo|:

      1. [=Queue a global task=] on the [=AI task source=] given [=this=]'s [=relevant global object=] to perform the following steps:

        1. If |abortedDuringSummarization| is true, then:

          1. [=Reject=] |promise| with |options|["{{AISummarizerSummarizeOptions/signal}}"]'s [=AbortSignal/abort reason=].

          1. Abort these steps.

        1. Let |exception| be the result of [=exception/creating=] a {{DOMException}} with name given by |errorInfo|'s [=summarization error information/error name=], using |errorInfo|'s [=summarization error information/error information=] to populate the message appropriately.

        1. [=Reject=] |promise| with |exception|.

    1. Let |stopProducing| be the following steps:

      1. Return |abortedDuringSummarization|.

    1. [=Summarize=] |input| given [=this=]'s [=AISummarizer/shared context=], |context|, [=this=]'s [=AISummarizer/summary type=], [=this=]'s [=AISummarizer/summary format=], [=this=]'s [=AISummarizer/summary length=], |chunkProduced|, |done|, |error|, and |stopProducing|.

  1. Return |promise|.
</div>

<div algorithm>
  The <dfn method for="AISummarizer">summarizeStreaming(|input|, |options|)</dfn> method steps are:

  1. If [=this=]'s [=relevant global object=] is a {{Window}} whose [=associated Document=] is not [=Document/fully active=], then return [=a promise rejected with=] an "{{InvalidStateError}}" {{DOMException}}.

  1. If [=this=]'s [=AISummarizer/destroyed=] is true, then return [=a promise rejected with=] [=this=]'s [=AISummarizer/destruction reason=].

  1. If |options|["{{AISummarizerSummarizeOptions/signal}}"] [=map/exists=] and is [=AbortSignal/aborted=], then return [=a promise rejected with=] |options|["{{AISummarizerSummarizeOptions/signal}}"]'s [=AbortSignal/abort reason=].

  1. Let |abortedDuringSummarization| be false.

    <p class="note">This variable tracks web developer aborts via the |options|["{{AISummarizerSummarizeOptions/signal}}"] {{AbortSignal}}, which are surfaced as errors. It will be written to from the [=event loop=], but sometimes read from [=in parallel=].

  1. If |options|["{{AISummarizerSummarizeOptions/signal}}"] [=map/exists=], then [=AbortSignal/add|add the following abort steps=] to |options|["{{AISummarizerSummarizeOptions/signal}}"]:

    1. Set |abortedDuringSummarization| to true.

  1. Let |stream| be a [=new=] {{ReadableStream}} created in [=this=]'s [=relevant realm=].

  1. Let |canceledDuringSummarization| be false.

    <p class="note">This variable tracks web developer [=ReadableStream/cancel|stream cancelations=] via {{ReadableStream/cancel()|stream.cancel()}}, which are not surfaced as errors.  It will be written to from the [=event loop=], but sometimes read from [=in parallel=].

  1. [=ReadableStream/Set up=] |stream| with <i>[=ReadableStream/set up/cancelAlgorithm=]</i> set to the following steps (ignoring the <var ignore>reason</var> argument):

    1. Set |canceledDuringSummarization| to true.

  1. Let |context| be |options|["{{AISummarizerSummarizeOptions/context}}"] if it [=map/exists=]; otherwise null.

  1. [=In parallel=]:

    1. Let |chunkProduced| be the following steps given a [=string=] |chunk|:

      1. [=Queue a global task=] on the [=AI task source=] given [=this=]'s [=relevant global object=] to perform the following steps:

        1. If |abortedDuringSummarization| is true, then:

          1. [=ReadableStream/Error=] |stream| with |options|["{{AISummarizerSummarizeOptions/signal}}"]'s [=AbortSignal/abort reason=].

          1. Abort these steps.

        1. If [=this=]'s [=AISummarizer/destroyed=] is true, then:

          1. [=ReadableStream/Error=] |stream| with [=this=]'s [=AISummarizer/destruction reason=].

          1. Abort these steps.

        1. [=ReadableStream/Enqueue=] |chunk| into |stream|.

    1. Let |done| be the following steps:

      1. [=Queue a global task=] on the [=AI task source=] given [=this=]'s [=relevant global object=] to perform the following steps:

        1. If |abortedDuringSummarization| is true, then:

          1. [=ReadableStream/Error=] |stream| with |options|["{{AISummarizerSummarizeOptions/signal}}"]'s [=AbortSignal/abort reason=].

          1. Abort these steps.

        1. If [=this=]'s [=AISummarizer/destroyed=] is true, then:

          1. [=ReadableStream/Error=] |stream| with [=this=]'s [=AISummarizer/destruction reason=].

          1. Abort these steps.

        1. [=ReadableStream/Close=] |stream|.

    1. Let |error| be the following steps given [=summarization error information=] |errorInfo|:

      1. [=Queue a global task=] on the [=AI task source=] given [=this=]'s [=relevant global object=] to perform the following steps:

        1. If |abortedDuringSummarization| is true, then:

          1. [=ReadableStream/Error=] |stream| with |options|["{{AISummarizerSummarizeOptions/signal}}"]'s [=AbortSignal/abort reason=].

          1. Abort these steps.

        1. If [=this=]'s [=AISummarizer/destroyed=] is true, then:

          1. [=ReadableStream/Error=] |stream| with [=this=]'s [=AISummarizer/destruction reason=].

          1. Abort these steps.

        1. Let |exception| be the result of [=exception/creating=] a {{DOMException}} with name given by |errorInfo|'s [=summarization error information/error name=], using |errorInfo|'s [=summarization error information/error information=] to populate the message appropriately.

        1. [=ReadableStream/Error=] |stream| with |exception|.

    1. Let |stopProducing| be the following steps:

      1. If any of |abortedDuringSummarization|, |canceledDuringSummarization|, or [=this=]'s [=AISummarizer/destroyed=] are true, then return true.

      1. Return false.

    1. [=Summarize=] |input| given [=this=]'s [=AISummarizer/shared context=], |context|, [=this=]'s [=AISummarizer/summary type=], [=this=]'s [=AISummarizer/summary format=], [=this=]'s [=AISummarizer/summary length=], |chunkProduced|, |done|, |error|, and |stopProducing|.

  1. Return |stream|.
</div>

<div algorithm>
  To <dfn>summarize</dfn> a string |input|, given a string-or-null |sharedContext|, a string-or-null |context|, an {{AISummarizerType}} |type|, an {{AISummarizerFormat}} |format|, an {{AISummarizerLength}} |length|, an algorithm |chunkProduced| that takes a string and returns nothing, an algorithm |done| that takes no arguments and returns nothing, an algorithm |error| that takes [=summarization error information=] and returns nothing, and an algorithm |stopProducing| that takes no arguments and returns a boolean:

  1. [=Assert=]: this algorithm is running [=in parallel=].

  1. [=Assert=]: the [=current summarizer create options availability=] given |type|, |format|, and |length| is "{{AICapabilityAvailability/readily}}".

     <p class="note">Otherwise, the {{AISummarizer}} object would not have been created.

  1. In an [=implementation-defined=] manner, subject to the following guidelines, begin the processs of summarizing |input| into a string.

     If they are non-null, |sharedContext| and |context| should be used to aid in the summarization by providing context on how the web developer wishes the input to be summarized.

     The summarization should conform to the guidance given by |type|, |format|, and |length|, in the definitions of each of their enumeration values.

  1. While true:

    1. Wait for the next chunk of summarization data to be produced, for the summarization process to finish, or for the result of calling |stopProducing| to become true.

    1. If such a chunk is successfully produced:

      1. Let it be represented as a [=string=] |chunk|.

      1. Perform |chunkProduced| given |chunk|.

    1. Otherwise, if the summarization process has finished:

      1. Perform |done|.

      1. [=iteration/Break=].

    1. Otherwise, if |stopProducing| returns true, then [=iteration/break=].

       <p class="note">The caller will handle signaling cancelation or aborting as necessary.

    1. Otherwise, if an error occurred during summarization:

      1. Let the error be represented as [=summarization error information=] |errorInfo| according to the guidance in [[#summarizer-errors]].

      1. Perform |error| given |errorInfo|.

      1. [=iteration/Break=].
</div>

<hr>

<div algorithm>
  <p>The <dfn method for="AISummarizer">destroy()</dfn> method steps are to [=AISummarizer/destroy=] [=this=] given a new "{{AbortError}}" {{DOMException}}.
</div>

<div algorithm>
  To <dfn for="AISummarizer">destroy</dfn> an {{AISummarizer}} |summarizer|, given a JavaScript value |reason|:

  1. Set |summarizer|'s [=AISummarizer/destroyed=] to true.

  1. Set |summarizer|'s [=AISummarizer/destruction reason=] to |reason|.

  1. The user agent should release any resources associated with |summarizer|, such as AI models loaded during [=initialize the summarization model=], as long as those resources are not needed for other ongoing operations.
</div>

<h3 id="summarizer-options">Options</h3>

The [=summarize=] algorithm's details are [=implementation-defined=], as they are expected to be powered by an AI model. However, it is intended to be controllable by the web developer through the {{AISummarizerType}}, {{AISummarizerFormat}}, and {{AISummarizerLength}} enumerations.

This section gives normative guidance on how the implementation of [=summarize=] should use each enumeration value to guide the summarization process.

<table class="data enum-table">
  <caption>{{AISummarizerType}} values</caption>
  <thead>
    <tr>
      <th>Value
      <th>Meaning
  <tbody>
    <tr>
      <th>"<dfn enum-value for="AISummarizerType">tl;dr</dfn>"
      <td>
        <p>The summary should be short and to the point, providing a quick overview of the input, suitable for a busy reader.
    <tr>
      <th>"<dfn enum-value for="AISummarizerType">teaser</dfn>"
      <td>
        <p>The summary should focus on the most interesting or intriguing parts of the input, designed to draw the reader in to read more.
    <tr>
      <th>"<dfn enum-value for="AISummarizerType">key-points</dfn>"
      <td>
        <p>The summary should extract the most important points from the input, presented as a bulleted list.
    <tr>
      <th>"<dfn enum-value for="AISummarizerType">headline</dfn>"
      <td>
        <p>The summary should effectively contain the main point of the input in a single sentence, in the format of an article headline.
</table>

<table class="data enum-table">
  <caption>{{AISummarizerLength}} values</caption>
  <thead>
    <tr>
      <th>Value
      <th>Meaning
  <tbody>
    <tr>
      <th>"<dfn enum-value for="AISummarizerLength">short</dfn>"
      <td>
        <p>The guidance is dependent on the value of {{AISummarizerType}}:

        <dl class="switch">
          : "{{AISummarizerType/tl;dr}}"
          : "{{AISummarizerType/teaser}}"
          :: The summary should fit within 1 sentence.
          : "{{AISummarizerType/key-points}}"
          :: The summary should consist of no more than 3 bullet points.
          : "{{AISummarizerType/headline}}"
          :: The summary should use no more than 12 words.
        </dl>
    <tr>
      <th>"<dfn enum-value for="AISummarizerLength">medium</dfn>"
      <td>
        <p>The guidance is dependent on the value of {{AISummarizerType}}:

        <dl class="switch">
          : "{{AISummarizerType/tl;dr}}"
          : "{{AISummarizerType/teaser}}"
          :: The summary should fit within 1 short paragraph.
          : "{{AISummarizerType/key-points}}"
          :: The summary should consist of no more than 5 bullet points.
          : "{{AISummarizerType/headline}}"
          :: The summary should use no more than 17 words.
        </dl>
    <tr>
      <th>"<dfn enum-value for="AISummarizerLength">long</dfn>"
      <td>
        <p>The guidance is dependent on the value of {{AISummarizerType}}:

        <dl class="switch">
          : "{{AISummarizerType/tl;dr}}"
          : "{{AISummarizerType/teaser}}"
          :: The summary should fit within 1 paragraph.
          : "{{AISummarizerType/key-points}}"
          :: The summary should consist of no more than 7 bullet points.
          : "{{AISummarizerType/headline}}"
          :: The summary should use no more than 22 words.
        </dl>
</table>

<p class="note">As with all "<span class="ignore-2119">should"-level guidance, user agents might not conform perfectly to these. Especially in the case of counting words, it's expected that language models might not conform perfectly.

<table class="data enum-table">
  <caption>{{AISummarizerFormat}} values</caption>
  <thead>
    <tr>
      <th>Value
      <th>Meaning
  <tbody>
    <tr>
      <th>"<dfn enum-value for="AISummarizerFormat">plain-text</dfn>"
      <td>
        <p>The summary should not contain any formatting or markup language.
    <tr>
      <th>"<dfn enum-value for="AISummarizerFormat">markdown</dfn>"
      <td>
        <p>The summary should be formatted using the Markdown markup language, ideally as valid CommonMark. [[!COMMONMARK]]
</table>

<h3 id="summarizer-errors">Errors</h3>

A <dfn>summarization error information</dfn> is a [=struct=] with the following items:

: <dfn for="summarization error information">error name</dfn>
:: a [=string=] that will be used for the {{DOMException}}'s [=DOMException/name=].
: <dfn for="summarization error information">error information</dfn>
:: other information necessary to create a useful {{DOMException}} for the web developer. (Typically, just an exception message.)

When summarization fails, the following possible reasons may be surfaced to the web developer. This table lists the possible {{DOMException}} [=DOMException/names=] and the cases in which an implementation should use them:

<table class="data">
  <thead>
    <tr>
      <th>{{DOMException}} [=DOMException/name=]
      <th>Scenarios
  <tbody>
    <tr>
      <td>"{{NotAllowedError}}"
      <td>
        <p>Summarization is disabled by user choice or user agent policy.
    <tr>
      <td>"{{NotReadableError}}"
      <td>
        <p>The summarization output was filtered by the user agent, e.g., because it was detected to be harmful, inaccurate, or nonsensical.
    <tr>
      <td>"{{NotSupportedError}}"
      <td>
        <p>The input to be summarized was in a language that the user agent does not support summarizing.
        <p>The summarization output was detected to be in a language that the user agent does not have sufficient quality control for and is not willing to support.
    <tr>
      <td>"{{QuotaExceededError}}"
      <td>
        <p>The input to be summarized was too large for the user agent to handle.
    <tr>
      <td>"{{UnknownError}}"
      <td>
        <p>All other scenarios, or if the user agent would prefer not to disclose the failure reason.
</table>

<p class="note">This table does not give the complete list of exceptions that can be surfaced by {{AISummarizer/summarize()|summarizer.summarize()}} and {{AISummarizer/summarize()|summarizer.summarizeStreaming()}}. It only contains those which can come from the [=implementation-defined=] [=summarize=] algorithm.