@overcrow/mcp 0.0.0 → 0.1.1

package/dist/content/docs/fr/result-shapes.md

@@ -0,0 +1,333 @@
+# Formes de résultat
+
+Ce que répondent les services de PlayerVox OverCrow : la forme de chaque
+résultat et de chaque mise à jour d’abonnement. Le SDK exporte pour chaque
+forme un type TypeScript du même nom : la logique n’a donc jamais à les
+décrire à la main.
+
+<!-- source: widgets/stopwatch/logic.ts -->
+```ts
+declare module "@overcrow/sdk" {
+  interface WidgetState {
+    /** The latest state, or `null` while it is unknown. */
+    stopwatch: Stopwatch | null;
+    /** The buttons take input only in Interactive mode. */
+    interactive: boolean;
+  }
+}
+```
+
+Le widget Chronomètre garde dans son état la dernière valeur `Stopwatch`, et
+la vue en lit les membres :
+
+<!-- source: widgets/stopwatch/view.ocml -->
+```xml
+      <elapsed class="value" base={state.stopwatch.elapsedMs} at={state.stopwatch.at} running={state.stopwatch.running} format="hh:mm:ss.cc"/>
+```
+
+## Lire une forme
+
+- Une forme est un enregistrement exact : chaque membre est présent, et un
+  membre sans valeur vaut `null` ; il n’est jamais absent.
+- « texte ou `null` » signifie que le membre peut valoir `null` : testez-le
+  avant de l’afficher.
+- Un entier est inférieur à 2^53 : il est donc exact en JavaScript. Les
+  temps sont en millisecondes : « Millisecondes Unix » compte depuis 1970 en
+  UTC, comme `Date.now()`.
+- Un membre accompagné de `offsetMinutes` est un horodatage à mettre en
+  forme avec ce décalage UTC ; voir
+  [heure, dates et nombres](logic.md#heure-dates-et-nombres).
+- Un identifiant `asset:` est une image qu’OverCrow détient pour le widget :
+  liez-le au `src` d’une `image` ou d’un `avatar`, ou dessinez-le sur un
+  canvas. Ce n’est pas une URL, et ses octets ne peuvent pas être lus.
+- Un abonnement dont la forme est « … ou `null` » livre `null` quand il n’y
+  a rien à afficher : pas de jeu actif, pas de lecteur multimédia.
+
+La [référence des services](service-reference.md) indique quel service donne
+quelle forme.
+
+## Formes
+
+<!-- generated:result-shapes -->
+### `HttpResponse`
+
+Réponse de `http.fetch`. `{ status, contentType }` ou `{ status, asset }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `status` | entier | Code d’état HTTP. |
+| `contentType` | texte ou `null` | Type de média de la réponse ; le SDK y ajoute le corps décodé, `body`. |
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `status` | entier | Code d’état HTTP. |
+| `asset` | identifiant `asset:` | L’image décodée (`as: "image"`). |
+
+### `GameEvent`
+
+Un événement de jeu. `{ event, at }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `event` | texte | Un événement de jeu déclaré. |
+| `at` | entier | Horloge monotone de l’hôte, en ms. |
+
+### `Session`
+
+Durée de la session du jeu actif. `{ elapsedMs, at }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `elapsedMs` | entier | Temps écoulé depuis le démarrage du processus du jeu. |
+| `at` | entier | Instant de l’horloge monotone de l’hôte, en ms, auquel `elapsedMs` a été mesuré. |
+
+### `Telemetry`
+
+Ressources utilisées par le jeu actif. `{ cpu, ram, cpuTemperature, gpuTemperature, sources }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `cpu` | nombre ou `null` | Part du jeu dans toute la machine, en %, de 0 à 100. |
+| `ram` | entier ou `null` | Mémoire résidente du jeu, en octets. |
+| `cpuTemperature` | nombre ou `null` | °C. |
+| `gpuTemperature` | nombre ou `null` | °C. |
+| `sources` | `{ cpuTemperature, gpuTemperature }` | Capteurs dont l’hôte dispose. |
+| `sources.cpuTemperature` | booléen | L’hôte dispose d’un capteur pour le CPU. |
+| `sources.gpuTemperature` | booléen | L’hôte dispose d’un capteur pour le GPU. |
+
+### `Fps`
+
+Fréquence d’images du jeu actif. `{ fps, stale, status }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `fps` | entier ou `null` | Images par seconde. |
+| `stale` | booléen | Aucune mesure depuis 3 s. |
+| `status` | `ready` \| `waiting` \| `unsupported` \| `permission_denied` \| `ambiguous` \| `events_lost` \| `unavailable` | État de la mesure. |
+
+### `Stopwatch`
+
+Le chronomètre manuel. `{ running, elapsedMs, at, shortcuts }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `running` | booléen | Il tourne. |
+| `elapsedMs` | entier | Temps écoulé à l’instant `at`. |
+| `at` | entier | Instant de l’horloge monotone de l’hôte, en ms, auquel `elapsedMs` a été mesuré. |
+| `shortcuts` | `{ toggle, reset, bound }` | Raccourcis du chronomètre. |
+| `shortcuts.toggle` | texte | Raccourci clavier, mis en forme par l’hôte. |
+| `shortcuts.reset` | texte | Raccourci clavier, mis en forme par l’hôte. |
+| `shortcuts.bound` | booléen | Les raccourcis sont actifs. |
+
+### `Media`
+
+Le lecteur multimédia courant. `{ player, title, artists, playing, canPrevious, canPlayPause, canNext, cover }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `player` | texte | ID opaque du lecteur courant. |
+| `title` | texte ou `null` | Titre du morceau. |
+| `artists` | liste de textes | Artistes. |
+| `playing` | booléen | En cours de lecture. |
+| `canPrevious` | booléen | Le lecteur sait passer au morceau précédent. |
+| `canPlayPause` | booléen | Le lecteur sait lire et mettre en pause. |
+| `canNext` | booléen | Le lecteur sait passer au morceau suivant. |
+| `cover` | identifiant `asset:` ou `null` | Pochette, de 512 px au plus. |
+
+### `NoteItem`
+
+Une entrée de liste de tâches. `{ id, text, checked }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `id` | texte ou `null` | ID de l’entrée. |
+| `text` | texte | Texte. |
+| `checked` | booléen | Cochée. |
+
+### `Note`
+
+Une note. `{ id, title, body, items }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `id` | texte ou `null` | ID de la note. |
+| `title` | texte | Titre. |
+| `body` | texte | Texte courant. |
+| `items` | liste de [`NoteItem`](#noteitem) | Liste de tâches. |
+
+### `Notes`
+
+Le document de notes de l’utilisateur. `{ active, notes }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `active` | texte ou `null` | ID de la note active. |
+| `notes` | liste de [`Note`](#note) | Notes. |
+
+### `CreatedNote`
+
+Réponse de `notes.create`. `{ note }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `note` | [`Note`](#note) | La nouvelle note. |
+
+### `Score`
+
+Note PlayerVox du jeu actif. `{ state, name, score, grade, ratingsCount, criteria }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `state` | `idle` \| `unsupported` \| `loading` \| `ready` \| `no_ratings` \| `not_found` \| `unavailable` | État de la note : `idle` sans jeu actif, `unsupported` pour un jeu sans ID d’application Steam, `loading` jusqu’à la première réponse pour ce jeu (jamais le score du jeu précédent), `ready` et `no_ratings` avec le score, `not_found` pour un jeu que PlayerVox ne reconnaît pas, `unavailable` pendant que l’hôte réessaie. Tout état autre que `ready` et `no_ratings` a un nom et un score `null`, le grade `--`, aucun vote et des critères `null`. |
+| `name` | texte ou `null` | Nom du jeu. |
+| `score` | nombre ou `null` | 0–100. |
+| `grade` | `S+` \| `S` \| `A` \| `B` \| `C` \| `D` \| `F` \| `--` | Grade correspondant au score. |
+| `ratingsCount` | entier | Nombre de votes. |
+| `criteria` | `{ gameplay, art, tech }` | Scores des critères. |
+| `criteria.gameplay` | nombre ou `null` | 0–100. |
+| `criteria.art` | nombre ou `null` | 0–100. |
+| `criteria.tech` | nombre ou `null` | 0–100. |
+
+### `Rating`
+
+La note PlayerVox que l’utilisateur a donnée au jeu actif. `{ gameplay, art, tech, review, publishedAt, offsetMinutes }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `gameplay` | entier | 0–100. |
+| `art` | entier | 0–100. |
+| `tech` | entier | 0–100. |
+| `review` | texte ou `null` | Texte de l’avis. |
+| `publishedAt` | entier ou `null` | Millisecondes Unix. |
+| `offsetMinutes` | entier ou `null` | Décalage UTC, en minutes, avec lequel afficher l’horodatage. |
+
+### `RatingState`
+
+La note que l’utilisateur a lui-même donnée au jeu actif, avec son état. `{ state, name, offline, rating }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `state` | `idle` \| `unsupported` \| `loading` \| `ready` \| `unavailable` | État de la note : `idle` sans jeu actif, `unsupported` pour un jeu sans ID d’application Steam, `loading` jusqu’à la première réponse pour ce jeu et ce compte (jamais la note du jeu précédent), `ready` avec la note, `unavailable` pendant que l’hôte retente une lecture qui a échoué. Tout état autre que `ready` a un nom et une note `null`. |
+| `name` | texte ou `null` | Nom du jeu sur PlayerVox. |
+| `offline` | booléen | PlayerVox est injoignable : la note est la dernière lue, et `playervox.rating.publish` répond `not_connected`. |
+| `rating` | [`Rating`](#rating) ou `null` | La note de l’utilisateur ; `null` avant la première. |
+
+### `Review`
+
+Un avis de joueur. `{ id, author, grade, score, text, original, hidden, publishedAt, offsetMinutes }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `id` | texte | ID de l’avis. |
+| `author` | texte | Nom de l’auteur. |
+| `grade` | `S+` \| `S` \| `A` \| `B` \| `C` \| `D` \| `F` \| `--` | Grade. |
+| `score` | entier | 0–100. |
+| `text` | texte ou `null` | Texte, traduit quand une traduction existe. |
+| `original` | texte ou `null` | Texte non traduit quand `text` est une traduction ; `null` sinon. |
+| `hidden` | booléen | Masqué par la communauté : n’affichez le texte que lorsque l’utilisateur le demande. |
+| `publishedAt` | entier | Millisecondes Unix. |
+| `offsetMinutes` | entier | Décalage UTC, en minutes, avec lequel afficher l’horodatage. |
+
+### `ReviewsState`
+
+Les avis des joueurs sur le jeu actif : ce qu’il faut lire, non les avis eux-mêmes. `{ state, revision, offline }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `state` | `idle` \| `unsupported` \| `ready` | `idle` sans jeu actif, `unsupported` pour un jeu sans ID d’application Steam, `ready` quand `playervox.reviews.page` lit les avis du jeu. |
+| `revision` | entier | Change chaque fois que les avis à lire changent : autre jeu, autre compte PlayerVox, ou avis modifiés sur PlayerVox. |
+| `offline` | booléen | PlayerVox est injoignable : `playervox.reviews.page` répond `not_connected`. |
+
+### `ReviewsPage`
+
+Une page d’avis de joueurs. `{ gameName, items, page, totalPages, count }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `gameName` | texte | Nom du jeu sur PlayerVox. |
+| `items` | liste de [`Review`](#review) | Avis. |
+| `page` | entier | Numéro de la page. |
+| `totalPages` | entier | Nombre de pages. |
+| `count` | entier | Nombre d’avis. |
+
+### `JournalSession`
+
+Une session du journal. `{ id, startedAt, offsetMinutes, durationMs, source }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `id` | texte | ID de la session. |
+| `startedAt` | entier | Millisecondes Unix. |
+| `offsetMinutes` | entier | Décalage UTC, en minutes, avec lequel afficher l’horodatage. |
+| `durationMs` | entier | Durée. |
+| `source` | `local` \| `cloud` | Où la session est enregistrée. |
+
+### `JournalState`
+
+Le journal du jeu actif. `{ revision, notice }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `revision` | entier | Change chaque fois que le journal fusionné du jeu actif change. |
+| `notice` | `offline` \| `storage_unavailable` \| `full` \| `expired` \| `busy` \| `unavailable` ou `null` | État du journal à afficher au-dessus des sessions : `offline` la synchronisation est hors ligne (les sessions locales restent), `storage_unavailable` le journal local est illisible, `full` le journal local est plein, `expired` la connexion à PlayerVox a expiré, `busy` PlayerVox demande de réessayer plus tard, `unavailable` tout autre échec ; `null` quand il n’y en a pas. |
+
+### `JournalPage`
+
+Une page du journal du jeu. `{ gameName, items, page, next, previous }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `gameName` | texte | Jeu actif ; vide quand l’hôte n’a pas de nom. |
+| `items` | liste de [`JournalSession`](#journalsession) | Sessions, de la plus récente à la plus ancienne. |
+| `page` | entier | Numéro de la page, à partir de 1. |
+| `next` | texte ou `null` | Curseur de la page suivante. |
+| `previous` | texte ou `null` | Curseur de la page précédente. |
+
+### `ChatFragment`
+
+Une portion de texte ou une emote d’un message de chat. `{ text }` ou `{ emote, alt }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `text` | texte | Portion de texte. |
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `emote` | identifiant `asset:` | Image de l’emote. |
+| `alt` | texte | Nom de l’emote. |
+
+### `ChatMessage`
+
+Un message de chat. `{ id, author, color, badges, fragments, reply, deleted, receivedAt }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `id` | texte | ID du message. |
+| `author` | texte | Nom de l’auteur. |
+| `color` | texte ou `null` | Couleur de l’auteur, `#rrggbb`. |
+| `badges` | liste d’identifiants `asset:` | Images des badges. |
+| `fragments` | liste de [`ChatFragment`](#chatfragment) | Portions du contenu. |
+| `reply` | `{ author, text }` ou `null` | Le message auquel celui-ci répond. |
+| `reply.author` | texte | Auteur du message auquel celui-ci répond. |
+| `reply.text` | texte | Texte du message auquel celui-ci répond. |
+| `deleted` | booléen | Supprimé par un modérateur. |
+| `receivedAt` | entier | Moment où l’hôte a reçu le message, en millisecondes Unix de l’horloge de l’hôte : comparez-le à `Date.now()` pour connaître l’âge d’un message (l’estompage du mode passif), y compris après un `reset`. |
+
+### `TwitchChat`
+
+État du chat Twitch. `{ account, channel, joinState, failure, favorites, canSend, generation, reset, messages, removed, skipped }`
+
+| Membre | Forme | Signification |
+| --- | --- | --- |
+| `account` | `signed_out` \| `pending` \| `connected` \| `expired` | État du compte Twitch ; la connexion est affichée par l’hôte. |
+| `channel` | texte ou `null` | Identifiant de la chaîne rejointe. |
+| `joinState` | `idle` \| `connecting` \| `joined` \| `reconnecting` \| `failed` | État de la connexion à la chaîne. |
+| `failure` | `channel_unavailable` \| `connection` \| `provider` \| `limit` ou `null` | Pourquoi `joinState` vaut `failed`, sous la forme d’une catégorie fixe : la chaîne n’existe pas ou refuse le compte, la connexion a échoué, Twitch a répondu quelque chose d’inattendu, ou un autre widget occupe l’unique connexion de l’hôte au chat (`limit`). `null` dans tout autre état. Un échec lié au compte n’y figure pas : c’est l’hôte qui l’affiche. |
+| `favorites` | liste de textes | Chaînes favorites. |
+| `canSend` | booléen | Un message peut être envoyé maintenant. |
+| `generation` | entier | Change avec la chaîne ou le compte. |
+| `reset` | booléen | `messages` remplace toute la liste. |
+| `messages` | liste de [`ChatMessage`](#chatmessage) | Messages, du plus ancien au plus récent : toute la liste avec `reset` ; sinon les nouveaux messages, à ajouter, et les messages modifiés, qui remplacent sur place celui de même `id`. |
+| `removed` | liste de textes | ID des messages retirés. |
+| `skipped` | entier | Nouveaux messages que l’hôte a laissés de côté depuis la mise à jour précédente, parce que le chat va plus vite qu’il ne transmet ; 0 avec `reset`. Un retrait n’est jamais laissé de côté. |
+<!-- /generated:result-shapes -->

package/dist/content/docs/fr/sdk.md

@@ -0,0 +1,301 @@
+# Référence du SDK
+
+`@overcrow/sdk` 1.0 est l’API de la logique d’un widget PlayerVox OverCrow :
+l’état, les données de l’hôte, les services, les minuteurs, le dessin, le
+menu d’options, les messages, les journaux et le formatage. Cette page liste
+tous les exports du paquet. [La logique](logic.md) et
+[Services et permissions](services.md) expliquent comment s’en servir.
+
+Le SDK est sur npm, et la commande ci-dessous l’ajoute à un projet. Un
+projet créé par `overcrow-widget init` le liste déjà : lancez-y
+`npm install`.
+
+```sh
+npm install --save-dev --save-exact @overcrow/sdk@1.0.0
+```
+
+<!-- source: widgets/clock/logic.ts -->
+```ts
+import {
+  formatDate,
+  formatTime,
+  initState,
+  onHost,
+  option,
+  t,
+  timers,
+  type DateOrder,
+  type Timer,
+} from "@overcrow/sdk";
+```
+
+Le SDK est assemblé dans le `logic.js` du widget à l’empaquetage et
+s’exécute dans la VM du widget ; le charger ailleurs lève une erreur. Les
+parties inutilisées sont retirées du script assemblé. C’est une commodité,
+pas une barrière de sécurité : OverCrow vérifie chaque appel, chaque
+paramètre et chaque valeur qui sort de la VM.
+
+| Export | Nature | Résumé |
+| --- | --- | --- |
+| `SDK_VERSION` | constante | `"1.0.0"`. |
+| `RUNTIME_SURFACE` | constante | `"0.1"`, la version de l’interface intégrée de la VM dont ce SDK a besoin. |
+
+## État et vue
+
+| Export | Nature | Résumé |
+| --- | --- | --- |
+| `state` | constante | L’objet d’état du widget. Modifiez-le ; après chaque tour, la VM réévalue la vue et n’envoie que les différences. |
+| `WidgetState` | interface | Type de `state` ; déclarez ses membres par augmentation de module. Les membres non déclarés sont `unknown`. |
+| `initState(initial)` | fonction | Copie `initial` dans `state` et renvoie `state` avec le type de `initial`. Appelez-la une seule fois, pendant le chargement du module. |
+| `registerView(table)` | fonction | Enregistre les expressions et les gestionnaires compilés de la vue. L’outil en ligne de commande génère cet appel : un widget ne l’écrit jamais. |
+| `ViewTable` | type | La table que prend `registerView`. |
+| `Expression` | type | `(state, scope) => value` : une expression compilée de la vue. |
+| `Handler` | type | `(state, scope, event) => void` : un gestionnaire compilé de la vue. |
+| `NodeEvent<E>` | interface | `{ type, detail }` d’un événement ; `detail` vaut `EventDetailMap[E]`. |
+| `Scope` | interface | Les noms à la portée d’une expression : entrées d’un `for`, propriétés d’un composant. |
+
+<!-- source: templates/chart/logic.ts -->
+```ts
+declare module "@overcrow/sdk" {
+  interface WidgetState {
+    values: number[];
+  }
+}
+
+const state = initState({ values: [50] as number[] });
+```
+
+## Données de l’hôte
+
+| Export | Nature | Résumé |
+| --- | --- | --- |
+| `host` | constante | Objet figé dont les membres donnent toujours les dernières valeurs envoyées par OverCrow. |
+| `HostData` | interface | Type de `host` : `locale`, `messages`, `theme`, `region`, `scale` (en millièmes), `viewport`, `mode`, `visible`, `options`, `grants`. |
+| `onHost(listener)` | fonction | Appelle `listener` avec les noms des membres de `host` qu’OverCrow vient d’envoyer (`options` après un changement dans le menu, `visible` quand le widget est affiché ou masqué, `region`…), avant la réévaluation de la vue. Renvoie `{ cancel() }`. |
+| `HostKey` | type | Le nom d’un membre de `HostData`. |
+| `HostListener` | type | Un écouteur de `onHost`. |
+| `Viewport` | interface | `{ width, height }`, en pixels logiques. |
+| `hasGrant(capability)` | fonction | Indique si l’utilisateur a accordé une capability. |
+| `option(id, fallback)` | fonction | La valeur enregistrée d’une ligne du menu d’options, ou `fallback` quand il n’y en a pas ou qu’elle est d’un autre type. |
+| `MenuValue` | type | `boolean \| number \| string`. |
+| `Widened<T>` | type | Le type du résultat de `option` : une valeur de repli `false` donne `boolean`. |
+
+<!-- source: widgets/clock/logic.ts -->
+```ts
+onHost((changed) => {
+  if (changed.includes("options")) {
+    const values = menuValues();
+    const unitChanged = values.seconds !== state.seconds;
+    Object.assign(state, values);
+    if (unitChanged) {
+      start();
+    }
+  }
+  // A new UTC offset (time zone or summer time) shows at once.
+  if (changed.includes("region")) {
+    tick();
+  }
+});
+```
+
+## Services
+
+Chaque service répond par l’intermédiaire d’OverCrow, qui vérifie à chaque
+appel sa permission ou sa capability, ses paramètres et l’action de
+l’utilisateur.
+
+| Export | Nature | Résumé |
+| --- | --- | --- |
+| `storage` | espace de noms | `get({ key })`, `set({ key, value })`, `remove({ key })`, `keys()`. Permission `storage`. |
+| `http` | espace de noms | `fetch(url, { as, method?, body?, contentType? })`. Permission `network`. |
+| `clipboard` | espace de noms | `writeText({ text })`, pendant une action de l’utilisateur. Permission `clipboardWrite`. |
+| `gameEvents` | espace de noms | `subscribe(listener)`. Permission `gameEvents`. |
+| `session` | espace de noms | `subscribe(listener)`. Capability `session.read`. |
+| `telemetry` | espace de noms | `subscribe(listener)`. Capability `telemetry.read`. |
+| `fps` | espace de noms | `subscribe(listener)`. Capability `fps.read`. |
+| `media` | espace de noms | `subscribe({ cover? }, listener)` ; `previous`, `playPause`, `next({ player? })` pendant une action de l’utilisateur. |
+| `stopwatch` | espace de noms | `subscribe(listener)` ; `toggle()`, `reset()` pendant une action de l’utilisateur. |
+| `notes` | espace de noms | `subscribe(listener)` ; `create()`, `select({ note })`, `setItem({ note, item, checked })`, `delete({ note })` pendant une action de l’utilisateur. |
+| `playervox` | espace de noms | `score.subscribe`, `rating.subscribe`, `reviews.subscribe`, `reviews.page({ page?, followedOnly? })`. |
+| `journal` | espace de noms | `subscribe(listener)` ; `page({ cursor? })` ; `delete({ session })` pendant une action de l’utilisateur, après confirmation de celui-ci. |
+| `twitch` | espace de noms | `chat.subscribe(listener)` ; `chat.join({ channel })`, `chat.leave()`, `chat.favorite({ channel, favorite })` pendant une action de l’utilisateur. |
+| `call(service, params?)` | fonction | Appelle par son nom n’importe quel service qui répond une seule fois. |
+| `subscribe(service, params, listener)` | fonction | S’abonne par son nom à n’importe quel service d’abonnement. |
+| `ServiceError` | classe | Le rejet d’un appel en échec : `code` est un `ServiceErrorCode`. |
+| `Listener<T>` | type | `(update: SubscriptionUpdate<T>) => void`. |
+| `SubscriptionUpdate<T>` | type | `{ ok: true, value, final }` ou `{ ok: false, error, final: true }`. |
+| `Subscription` | interface | `cancel()` ; un nouvel appel ne fait rien. |
+| `ServiceParams<N>` | type | Les paramètres du service `N`. |
+| `ServiceResult<N>` | type | Le résultat, ou la mise à jour, du service `N`. |
+| `FetchOptions<A>` | interface | Les options de `http.fetch`. |
+| `FetchResponse<A>` | type | `{ status, contentType, body }`, ou `{ status, asset }` pour `as: "image"`. |
+| `BodyType` | type | `"json" \| "text" \| "bytes" \| "image"`. |
+| `BodyTypes` | interface | Le corps décodé de chaque type de corps. |
+| `HttpMethod` | type | Les méthodes des règles réseau. |
+| `HttpServices` | interface | Type de `http`. |
+
+L’écouteur vient toujours en dernier, et un service sans paramètres n’en
+prend aucun :
+
+<!-- source: widgets/fps/logic.ts -->
+```ts
+  fps.subscribe((update) => {
+    Object.assign(state, reading(update));
+  });
+```
+
+<!-- source: widgets/media/logic.ts -->
+```ts
+  const current = media.subscribe({ cover: state.showCover }, (update) => {
+    if (update.ok) {
+      state.media = update.value;
+      state.unavailable = false;
+      return;
+    }
+    // The subscription ended: the host's source failed. Show it and ask
+    // again later; hidden, the timer waits until the widget shows.
+    if (subscription === current) {
+      subscription = null;
+      state.media = null;
+      state.unavailable = true;
+      retry = timers.after(RETRY_MS, subscribe);
+    }
+  });
+```
+
+`http.fetch` envoie un corps de type chaîne en `text/plain` et tout autre
+corps en JSON, sauf si `contentType` en dit autrement, et décode la réponse
+comme le demande `as`. Une réponse sans corps donne `null`, `""` ou un
+`ArrayBuffer` vide.
+
+Les types des autres espaces de noms sont générés à partir du schéma :
+`ClipboardServices`, `FpsServices`, `GameEventsServices`,
+`JournalServices`, `MediaServices`, `NotesServices`, `PlayervoxServices`,
+`SessionServices`, `StopwatchServices`, `StorageServices`,
+`TelemetryServices` et `TwitchServices`. Chaque service est décrit dans la
+[référence des services](service-reference.md).
+
+## Minuteurs
+
+| Export | Nature | Résumé |
+| --- | --- | --- |
+| `timers` | espace de noms | `after(ms, callback)`, `every(ms, callback)`, `atEach(unit, callback)`. |
+| `Timer` | interface | `cancel()` ; un nouvel appel ne fait rien. |
+
+- 16 minuteurs au plus, jamais plus courts que 100 ms : un intervalle plus
+  court est porté à cette valeur.
+- Aucun minuteur ne se déclenche tant que le widget est masqué. Un minuteur
+  répétitif saute les déclenchements manqués ; un minuteur à usage unique
+  arrivé à échéance pendant ce temps se déclenche une fois quand le widget
+  réapparaît.
+- `atEach("second" | "minute" | "hour" | "day", callback)` appelle
+  `callback` à chaque changement d’unité de l’heure locale de l’utilisateur,
+  et une fois quand le widget réapparaît. Il se réveille aussi quand le
+  décalage UTC de l’utilisateur change.
+
+<!-- source: widgets/media/logic.ts -->
+```ts
+      retry = timers.after(RETRY_MS, subscribe);
+```
+
+## Dessin, menu, messages et journal
+
+| Export | Nature | Résumé |
+| --- | --- | --- |
+| `draw(ref, commands)` | fonction | Remplace les commandes du `canvas` dont le `ref` est donné. |
+| `onMenu(handler)` | fonction | Reçoit l’identifiant de chaque ligne `action` du menu d’options que l’utilisateur choisit. |
+| `t(key, params?)` | fonction | Le message de la langue active, où chaque `{name}` est remplacé par `params.name` ; la clé elle-même quand il n’y a pas de message. |
+| `MessageParams` | type | `Record<string, string \| number>`. |
+| `log` | espace de noms | `debug`, `info`, `warn`, `error(text)` : affichés par `overcrow-widget dev`, ignorés pour un widget installé. |
+
+Les commandes de dessin sont des tuples typés, listés dans
+[Dessin](logic.md#dessin).
+
+<!-- source: docs/content/examples/countdown/logic.ts -->
+```ts
+    dots.push(["circle", 6 + index * 14, 6, 4], ["fill", "var(--color-accent)"]);
+```
+
+## Heure, dates et nombres
+
+La VM n’a pas d’`Intl`, et son heure locale est UTC : `Date` ne donne jamais
+l’heure de l’utilisateur. Ces fonctions formatent à partir de `host.region`.
+Les nombres suivent le format de nombre de l’utilisateur (`1,234.5`,
+`1 234,5` ou `1.234,5`), quelle que soit la langue de l’interface ; les
+dates sont numériques, dans l’ordre de date de l’utilisateur ; les heures
+s’affichent sur 24 heures. Chaque fonction accepte aussi ses valeurs
+régionales en options : elle peut ainsi tourner dans un test unitaire, hors
+de la VM.
+
+| Export | Nature | Résumé |
+| --- | --- | --- |
+| `localTime(ms, offsetMinutes?)` | fonction | Les champs `LocalTime` d’un instant dans le décalage UTC de l’utilisateur, ou dans l’`offsetMinutes` d’un horodatage de service. |
+| `formatTime(ms, options?)` | fonction | `14:08`, ou `14:08:42` avec `seconds: true`. |
+| `formatDate(ms, options?)` | fonction | `17/07/2026` (`dmy`), `07/17/2026` (`mdy`), `2026-07-17` (`ymd`). |
+| `formatNumber(value, options?)` | fonction | Les séparateurs du format de nombre de l’utilisateur ; `minimumFractionDigits`, `maximumFractionDigits` (3 par défaut), `grouping`. |
+| `formatDuration(ms, options?)` | fonction | `04:05`, `1:02:03`, `04:05.67` avec `hundredths: true` ; tronquée, comme l’affiche un chronomètre. |
+| `delayToNext(unit, nowMs, region?)` | fonction | Les millisecondes jusqu’au prochain changement d’unité de l’heure locale, jamais au-delà du prochain changement de décalage UTC. |
+| `LocalTime` | interface | `year`, `month` (1 à 12), `day`, `weekday` (0 pour dimanche), `hour`, `minute`, `second`, `millisecond`. |
+| `TimeUnit` | type | `"second" \| "minute" \| "hour" \| "day"`. |
+| `TimeOptions` | interface | `offsetMinutes`. |
+| `DateOptions` | interface | `offsetMinutes`, `order`. |
+| `ClockOptions` | interface | `offsetMinutes`, `seconds`. |
+| `NumberOptions` | interface | Les options de `formatNumber`. |
+| `DurationOptions` | interface | `hours`, `hundredths`, `format`. |
+
+<!-- source: widgets/clock/logic.ts -->
+```ts
+export function clockDate(now: number, order: DateOrder): string {
+  return formatDate(now, { order });
+}
+```
+
+Les noms de mois et de jours de la semaine, l’affichage sur 12 heures et les
+règles de pluriel ne font pas partie de la version 1.0.
+
+## Types générés
+
+Ces types sont générés à partir du schéma des widgets : ils correspondent
+donc toujours à ce qu’OverCrow accepte.
+
+| Export | Résumé |
+| --- | --- |
+| `ServiceName`, `CallServiceName`, `SubscribeServiceName`, `GestureServiceName` | Les noms de service : tous, ceux qui répondent une seule fois, les abonnements, et ceux qui demandent une action de l’utilisateur. |
+| `ServiceParamsMap`, `ServiceResultMap` | Les paramètres et le résultat de chaque service. |
+| `ServiceErrorCode`, `ServiceErrorPayload` | Les [codes d’erreur](services.md#erreurs), et la valeur `{ code }` qui en porte un. |
+| `Session`, `Telemetry`, `Fps`, `Stopwatch`, `Media`, `Notes`, `Note`, `NoteItem`, `CreatedNote`, `Score`, `Rating`, `RatingState`, `Review`, `ReviewsState`, `ReviewsPage`, `JournalState`, `JournalPage`, `JournalSession`, `TwitchChat`, `ChatMessage`, `ChatFragment`, `GameEvent`, `HttpResponse` | Les [formes de résultat](result-shapes.md). |
+| `Permission`, `Capability`, `SensitiveCapability`, `CapabilityServices`, `PermissionServices` | Les permissions et les capabilities du manifeste, et les services que chacune autorise. |
+| `Locale`, `Theme`, `Mode`, `Region`, `NumberFormat`, `DateOrder` | Les valeurs de `host`. |
+| `EventName`, `GestureEventName`, `EventDetailMap`, `NamedKey` | Les événements de la vue, ceux qui sont des actions de l’utilisateur, leurs détails, et les touches nommées de `keydown`. |
+| `DrawCommand`, `DrawCommandName`, `Color` | Les commandes et les couleurs du canvas. |
+| `TokenName`, `ColorToken`, `LengthToken`, `FontSizeToken`, `FontFamilyToken`, `TimeToken`, `ShadowToken` | Les [tokens du design system](style-properties.md#tokens-du-design-system). |
+| `IconName` | Les noms des [icônes](style-properties.md#icônes). |
+| `MenuRowType`, `HostFeature` | Les types de ligne du menu d’options, et les sources de données de `requires`. |
+| `JsonValue`, `AssetHandle`, `ImageSource` | Toute valeur JSON ; un identifiant d’image donné par un service ; une image du paquet ou un tel identifiant. |
+
+## Constantes de limites
+
+Les [limites](limits.md) que la logique d’un widget doit respecter sont
+exportées sous forme de constantes, pour que le code ne répète jamais un
+nombre : `MAX_TIMERS`, `MIN_TIMER_INTERVAL_MS`, `MAX_SERVICE_CALLS_IN_FLIGHT`,
+`MAX_SUBSCRIPTIONS`, `MAX_STORAGE_KEYS`, `MAX_STORAGE_KEY_BYTES`,
+`MAX_STORAGE_VALUE_BYTES`, `STORAGE_QUOTA_BYTES`, `MAX_REQUEST_URL_BYTES`,
+`MAX_HTTP_REQUEST_BYTES`, `MAX_HTTP_RESPONSE_BYTES`,
+`MAX_HTTP_DECLARED_RESPONSE_BYTES`, `MAX_CLIPBOARD_BYTES`,
+`MAX_OBJECT_ID_BYTES`, `MAX_NOTES`, `MAX_NOTE_ITEMS`,
+`MAX_NOTE_TITLE_BYTES`, `MAX_NOTE_BODY_BYTES`, `MAX_NOTE_ITEM_BYTES`,
+`MAX_REVIEW_CHARS`, `MAX_CHAT_CHANNEL_BYTES`, `MAX_CHAT_MESSAGE_CHARS`,
+`MAX_CHAT_FRAGMENTS`, `MAX_CHAT_FAVORITES`, `MAX_DRAW_COMMANDS`,
+`MAX_DRAW_STATE_DEPTH`, `MAX_PATH_POINTS`, `MAX_PATCH_BYTES`,
+`MAX_SCENE_NODES`, `MAX_CHILDREN`, `MAX_NODE_TEXT_BYTES`,
+`MAX_ATTRIBUTE_TEXT_BYTES`, `MAX_LABEL_BYTES`, `MAX_FIELD_TEXT_BYTES`,
+`MAX_LOCALE_ENTRIES`, `MAX_LOG_BYTES`, `VM_HEAP_BYTES`,
+`VM_MAX_HEAP_BYTES`, `VM_TURN_BUDGET_MS`, `VM_JOBS_PER_TURN` et
+`VM_MESSAGES_PER_TURN`.
+
+## Tests unitaires : `@overcrow/sdk/testing`
+
+Un second point d’entrée, jamais assemblé dans un widget, remplace OverCrow
+dans un test unitaire de la logique : `installRuntime()` fournit un temps
+virtuel, fait aboutir les appels de service et pousse les valeurs des
+abonnements. Voir les [tests unitaires](testing.md#tests-unitaires).