@overcrow/mcp 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,341 @@
+# Formulaires et intents d’écriture
+
+Un widget PlayerVox OverCrow reçoit ses entrées par des contrôles
+qu’OverCrow dessine et édite lui-même : boutons, bascules, cases à cocher,
+curseurs, listes déroulantes, champs de texte. La logique en est informée
+par des événements. Un `form` regroupe des contrôles et les valide ensemble.
+Un formulaire lié à un **intent d’écriture** est le moyen, pour un widget,
+de laisser l’utilisateur écrire dans ses notes, publier sa note d’un jeu sur
+PlayerVox ou envoyer un message de chat, sans que le texte passe jamais par
+le code du widget.
+
+Les widgets ne reçoivent d’entrées qu’en mode interactif d’OverCrow. En mode
+passif, un clic traverse le widget jusqu’au jeu : masquez ou désactivez ce
+qui est inutilisable, comme le font les widgets intégrés avec `host.mode`.
+
+## Contrôles
+
+| Élément | Valeur | Événements |
+| --- | --- | --- |
+| `button` | aucune | `activate` |
+| `toggle`, `checkbox` | `checked` | `change` |
+| `slider` | `value`, entre `min` et `max` | `input` pendant le glissement, `change` au relâchement |
+| `select` avec des enfants `option` | `value` de l’option choisie | `change` |
+| `field` | une ligne de texte | `input` à chaque modification, `change` sur Entrée ou quand le focus quitte le champ, `submit` sur Entrée |
+| `textarea` | plusieurs lignes de texte | `input`, `change`, `submit` sur Ctrl+Entrée |
+
+Chacun prend un `label`, son nom accessible, et `disabled`. Leurs attributs
+sont décrits dans [Éléments et attributs](elements.md).
+
+<!-- source: docs/content/examples/countdown/view.ocml -->
+```xml
+    <select class="duration" value={minutesValue(state.minutes)} label={t("duration")} disabled={state.running} on:change={setMinutes}>
+      <for each={state.durations} as="minutes" key={minutes}>
+        <option value={minutesValue(minutes)}>{t("minutes", { count: minutes })}</option>
+      </for>
+    </select>
+```
+
+<!-- source: docs/content/examples/countdown/logic.ts -->
+```ts
+export function setMinutes(event: { value: unknown }): void {
+  const minutes = Number(event.value);
+  if (state.durations.includes(minutes)) {
+    state.minutes = minutes;
+    state.remainingMs = total(minutes);
+  }
+}
+```
+
+La vue lie le contrôle à l’état (`value={…}`, `checked={…}`), et le
+gestionnaire y réécrit la nouvelle valeur. Le détail de `input` et de
+`change` est `{ value }` : un booléen pour une bascule ou une case à cocher,
+un nombre pour un curseur, du texte pour les autres.
+
+<!-- source: docs/content/examples/countdown/view.ocml -->
+```xml
+    <toggle class="repeat" label={t("repeat")} tooltip={t("repeat")} checked={state.repeat} on:change={setRepeat}/>
+```
+
+### Champs de texte
+
+OverCrow édite lui-même le texte d’un `field` ou d’un `textarea` : le point
+d’insertion, la sélection, le copier-coller et les méthodes de saisie des
+langues qui composent leurs caractères. La logique reçoit une copie du texte
+dans chaque événement `input`.
+
+<!-- source: widgets/warframe-market/view.ocml -->
+```xml
+      <field class="query" label={t("search-field")} value={state.query} placeholder={t("placeholder")} max-length="256" on:input={search}/>
+```
+
+<!-- source: widgets/warframe-market/logic.ts -->
+```ts
+export function search(detail: { value: unknown }): void {
+  state.query = typeof detail.value === "string" ? detail.value : "";
+  state.results = searchItems(items, lowered, state.query);
+  state.detail = null;
+  state.loadingOrders = false;
+  state.refreshing = false;
+  state.copy = null;
+  if (state.error === "orders_unavailable") {
+    state.error = null;
+  }
+  selection += 1;
+  stopRefresh();
+  saveQuery();
+}
+```
+
+Lier `value` remplace le contenu du champ : liez-le à l’état qu’écrit votre
+gestionnaire `input`, comme ci-dessus, ou omettez-le et contentez-vous
+d’écouter. `max-length` limite le texte en octets, et `placeholder` affiche
+une indication tant que le champ est vide.
+
+Un champ envoie aussi `keydown` quand vous le demandez, avec la touche et
+ses modificateurs, pour des raccourcis comme Échap pour annuler. Les touches
+qu’OverCrow se réserve (Tab pour déplacer le focus, ses propres raccourcis,
+une composition en cours) ne sont pas transmises.
+
+### Le focus à l’ouverture d’un éditeur
+
+La logique ne peut pas déplacer le focus clavier. Un `field` ou un
+`textarea` qui porte `autofocus` le prend de lui-même quand il apparaît
+pendant que la logique traite une action de l’utilisateur : un clic sur un
+bouton Modifier qui ouvre un éditeur place le point d’insertion dans le
+champ, après son texte, comme le ferait un clic dans ce champ.
+
+<!-- source: widgets/notes/view.ocml -->
+```xml
+        <field class="title-field" name="title" autofocus placeholder={t("title-hint")} label={t("title-hint")} on:input={titleInput(editor.key, event.value)} on:keydown={keyed(editor.key, event.key, event.ctrl)}/>
+```
+
+OverCrow ne donne ce focus que si l’élément apparaît pendant une
+[action de l’utilisateur](services.md#les-appels-qui-demandent-une-action-de-lutilisateur),
+en mode interactif, dans le widget sur lequel l’utilisateur a agi ; quand
+plusieurs de ces éléments apparaissent ensemble, le premier de la vue le
+prend. Un élément qui apparaît au démarrage du widget, depuis un minuteur
+ou depuis la réponse d’un service (y compris après un `await` dans le
+gestionnaire du clic) ne prend pas le focus, pas plus qu’un élément déjà
+affiché : `autofocus` est lu quand l’élément apparaît. Donnez-le à un seul
+champ d’un éditeur, et pas à un champ qui apparaît pendant que
+l’utilisateur saisit, comme une nouvelle ligne d’une liste.
+
+## Formulaires
+
+Un `form` regroupe des contrôles et leur donne un seul événement `submit`.
+On le valide par Entrée dans un `field`, par Ctrl+Entrée dans un `field` ou
+un `textarea`, ou en activant un bouton doté de l’attribut `submit`.
+
+<!-- source: widgets/twitch-chat/view.ocml -->
+```xml
+      <form class="selector" on:submit={join}>
+        <field class="input channel" max-length="26" autofocus placeholder={t("channel-name")} label={t("channel-name")} on:input={channelTyped(event.value)}/>
+        <button class="action" submit disabled={!canJoin(state)}>
+          <text class="action-label">{t("join")}</text>
+        </button>
+      </form>
+```
+
+<!-- source: widgets/twitch-chat/logic.ts -->
+```ts
+export function join(): void {
+  const channel = normalizeChannel(state.channelDraft);
+  if (channel !== null) {
+    joinChannel(channel);
+  }
+}
+```
+
+Ce formulaire n’a pas d’intent : son gestionnaire `submit` lit ce que le
+gestionnaire `input` a gardé dans l’état, puis appelle un service. `submit`
+est une action de l’utilisateur : le gestionnaire peut donc appeler un
+service qui en demande une (`twitch.chat.join` ici).
+
+Un formulaire garde ce que l’utilisateur a saisi tant qu’il reste dans la
+vue. Masquez-le avec `display: none` pour garder un brouillon ; retirez-le
+de la vue pour l’abandonner. Pour repartir de champs vides, donnez au
+formulaire une nouvelle clé dans un `for` : une nouvelle clé, c’est un
+nouveau formulaire.
+
+## Les formulaires qui écrivent des données de l’utilisateur
+
+Trois opérations d’un widget écrivent, dans les données de l’utilisateur, un
+texte que celui-ci a saisi : enregistrer une note, publier la note d’un jeu
+sur PlayerVox avec son avis, et envoyer un message dans un chat Twitch. Ce ne
+sont pas des appels de service. C’est un formulaire doté d’un attribut
+`intent` qui les envoie :
+
+<!-- source: widgets/twitch-chat/view.ocml -->
+```xml
+    <form class={composerClass(state)} intent="twitch.chat.send" target={replyTarget(state)} on:submit={submitted(event.outcome, event.error)}>
+      <if test={state.reply}>
+        <box class="replying">
+          <text class="replying-label">{replyingTo(state)}</text>
+          <button class="icon-button small" label={t("cancel-reply")} tooltip={t("cancel-reply")} on:activate={cancelReply}>
+            <icon name="x"/>
+          </button>
+        </box>
+      </if>
+      <if test={state.sendError != ""}>
+        <text class="error">{t(state.sendError)}</text>
+      </if>
+      <box class="compose">
+        <field class="input message-field" name="message" max-length="500" placeholder={t(composerHint(state))} label={t("message-label")} disabled={!state.canSend} on:input={drafted(event.value)} on:keydown={keyed(event.key)}/>
+        <if test={sendMark(state) != ""}>
+          <text class={sendMarkClass(state)}>{t(sendMark(state))}</text>
+        </if>
+        <button class="action" submit disabled={!canSubmit(state)} on:activate={sendPressed}>
+          <text class="action-label">{t("send")}</text>
+        </button>
+      </box>
+    </form>
+```
+
+Quand l’utilisateur valide un tel formulaire, **OverCrow lit les valeurs des
+contrôles de ce formulaire et les envoie lui-même**. La logique du widget ne
+fournit jamais le texte : un widget ne peut donc ni écrire ce que
+l’utilisateur n’a pas saisi, ni valider sans lui. Le formulaire ne part que
+sur une action de l’utilisateur, en mode interactif, avec la capability
+accordée.
+
+Ce que cela change pour la vue et la logique :
+
+- **Les contrôles appartiennent à OverCrow.** Les contrôles `field`,
+  `textarea` et `slider` du formulaire ne prennent pas de `value` :
+  `overcrow-widget check` le refuse (`view.bound_value`), et OverCrow arrête
+  un widget qui en définit un à l’exécution. Leur attribut `name` indique à
+  quel champ de l’intent chacun correspond.
+- **OverCrow les remplit** là où l’intent le prévoit : le titre, le corps et
+  la liste de tâches de la note, la note publiée par l’utilisateur. Un
+  remplissage envoie l’événement `input` du contrôle avec la valeur, pour
+  que la logique sache ce qui est affiché ; cet événement n’est pas une
+  action de l’utilisateur.
+- **La logique suit par les événements `input`**, pour afficher un compteur
+  ou activer le bouton, et peut désactiver les contrôles.
+- **L’issue arrive dans l’événement `submit` du formulaire** :
+  `event.outcome` vaut `accepted`, `rejected` (avec le
+  [code d’erreur](services.md#erreurs) dans `event.error`) ou `cancelled`.
+  Un formulaire sans intent donne `submitted`.
+
+<!-- source: widgets/playervox-rating/view.ocml -->
+```xml
+      <slider class="criterion-slider" name="gameplay" min="0" max="100" step="1" label={t("gameplay")} disabled={!editable(state)} on:input={scored("gameplay", event.value)}/>
+```
+
+<!-- source: widgets/playervox-rating/logic.ts -->
+```ts
+export function scored(key: CriterionKey, value: number): void {
+  state[key] = value;
+  edited();
+}
+```
+
+<!-- source: widgets/playervox-rating/logic.ts -->
+```ts
+export function submitted(outcome: string, error: ServiceErrorPayload | undefined): void {
+  state.pending = Math.max(0, state.pending - 1);
+  if (state.pending === 0) {
+    answer?.cancel();
+    answer = null;
+  }
+  if (outcome === "accepted") {
+    // The subscription sends the stored rating; nothing is read again.
+    state.saved = true;
+    state.error = "";
+  } else if (outcome !== "cancelled") {
+    state.error = errorKey(error?.code ?? null);
+  }
+}
+```
+
+Une écriture ne change pas d’elle-même ce que dit un abonnement : après une
+note PlayerVox acceptée, `playervox.rating.subscribe` livre la note
+enregistrée, et c’est elle que le widget affiche.
+
+### Les intents
+
+<!-- generated:write-intents -->
+### `notes.save`
+
+Capability `notes.write` ; attribut `target` obligatoire (l’ID de la note ; l’hôte remplit les contrôles liés à partir de cette note). Entrée dans un `field` du formulaire fait passer le focus à son `field` ou `textarea` suivant et ne valide pas ; Ctrl+Entrée et un bouton `submit` valident.
+
+| Champ | Type | Obligatoire | Signification |
+| --- | --- | --- | --- |
+| `title` | texte ≤ 96 octets | oui | `field` ; enregistré sans espaces en début ni en fin, et non vide. |
+| `body` | texte ≤ 8 Kio | non | `textarea` ; enregistré tel qu’il est écrit. |
+| `item` | liste de `NoteItem` ≤ 64 | non | Un `field` par ligne de la liste de tâches, dans l’ordre, chacun ≤ 256 octets. L’hôte retient avec quelle entrée il a rempli chaque champ : une ligne garde l’ID et la coche de cette entrée quelles que soient les lignes que le widget retire ou déplace, et un champ apparu depuis est une nouvelle entrée, non cochée. Les lignes sont enregistrées sans espaces en début ni en fin ; une ligne vide est abandonnée. Une note enregistrée telle qu’elle est déjà stockée est acceptée sans écriture. |
+
+### `playervox.rating.publish`
+
+Capability `playervox.rating.write` ; attribut `target` refusé.
+
+| Champ | Type | Obligatoire | Signification |
+| --- | --- | --- | --- |
+| `gameplay` | entier de 0 à 100 | oui | `slider` ; rempli à partir de la note de l’utilisateur, 50 avant la première. |
+| `art` | entier de 0 à 100 | oui | `slider` ; rempli comme `gameplay`. |
+| `tech` | entier de 0 à 100 | oui | `slider` ; rempli comme `gameplay`. |
+| `review` | texte ≤ 2000 caractères | non | `textarea` ; rempli à partir de l’avis publié. Un avis inchangé n’est pas renvoyé ; un avis vidé est retiré. |
+
+### `twitch.chat.send`
+
+Capability `twitch.chat.compose` ; attribut `target` facultatif (l’ID du message auquel on répond).
+
+| Champ | Type | Obligatoire | Signification |
+| --- | --- | --- | --- |
+| `message` | texte ≤ 500 caractères | oui | `field` ; l’hôte le vide après un envoi réussi. |
+<!-- /generated:write-intents -->
+
+`target` est l’attribut du formulaire qui désigne l’objet écrit :
+l’identifiant de la note pour `notes.save`, l’identifiant du message auquel
+on répond pour `twitch.chat.send`.
+
+### Plusieurs lignes d’un même champ
+
+L’intent `notes.save` prend un champ `item` par ligne de la liste de tâches.
+La logique décide des lignes du formulaire, avec un `for` ; OverCrow remplit
+le champ de chaque ligne à partir de la note enregistrée et retient quelle
+entrée de la liste de tâches il y a placée. Une ligne que la logique retire
+ou déplace garde son entrée, et une ligne ajoutée depuis est une nouvelle
+entrée.
+
+<!-- source: widgets/notes/view.ocml -->
+```xml
+          <for each={editor.rows} as="row" key={row.key}>
+            <box class="row">
+              <if test={rowStored(state, editor, row)}>
+                <checkbox class="row-check" checked={rowChecked(state, editor, row)} label={rowLabel(row)} on:change={check(editor.note, row.id, event.value)}/>
+              </if>
+              <else>
+                <icon class="row-new" name="circle"/>
+              </else>
+              <field class="row-field" name="item" placeholder={rowHint(editor, row)} label={t("item-hint")} on:input={rowInput(editor.key, row.key, event.value)} on:keydown={keyed(editor.key, event.key, event.ctrl)}/>
+```
+
+Dans ce formulaire, Entrée passe au champ suivant au lieu de valider ;
+Ctrl+Entrée ou le bouton `submit` enregistre.
+
+## Confirmations
+
+Deux services suppriment des données de l’utilisateur : `notes.delete` et
+`journal.delete`. Ce sont des appels ordinaires qui demandent une action de
+l’utilisateur. OverCrow demande ensuite à l’utilisateur de confirmer, dans
+une boîte de dialogue qu’il dessine lui-même, hors du widget. L’appel
+aboutit quand l’utilisateur confirme et échoue avec `cancelled` quand il
+refuse. Ne dessinez pas votre propre « Êtes-vous sûr ? » : seule la
+confirmation d’OverCrow compte.
+
+## Points à vérifier pour un formulaire
+
+- Chaque contrôle a un `label`.
+- Les boutons qui ne peuvent pas agir sont `disabled`, et rien de ce qui
+  demande une entrée ne s’affiche en mode passif.
+- Le gestionnaire `submit` traite un refus : `not_connected` quand le compte
+  est déconnecté, `busy` quand l’utilisateur envoie trop vite,
+  `unavailable`.
+- Un formulaire lié à un intent n’a pas de `value` sur ses champs de texte
+  ni sur ses curseurs, et chaque contrôle nommé est un champ de l’intent.
+- Testez-le avec un scénario : les étapes `text` saisissent du texte dans le
+  champ qui a le focus, les étapes `key` appuient sur Entrée, et
+  `expect.intents` vérifie exactement ce qu’OverCrow a envoyé. Voir
+  [Tester un widget](testing.md#steps).

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

@@ -0,0 +1,264 @@
+# Guide du créateur
+
+Ce guide mène un widget PlayerVox OverCrow d’un dossier vide à une
+soumission : créer un projet, modifier sa vue, son style et sa logique, le
+lancer dans OverCrow, le tester, l’empaqueter et le soumettre. Chaque étape
+renvoie à la page qui la traite en détail.
+
+Pour travailler plutôt avec un assistant IA, ajoutez-lui le serveur MCP
+d’OverCrow : voir [MCP](mcp.md).
+
+## 1. Installer les outils
+
+- **`overcrow-widget`**, la CLI des widgets, un seul binaire pour Linux et
+  Windows. Voir [installer la CLI](cli.md#installation).
+- **Node.js 22 ou plus récent** et npm, pour que `check` vérifie les types
+  de votre logique avec le TypeScript du projet et le SDK de npm. Sans lui, la CLI vérifie et
+  empaquette quand même, mais signale que les types n’ont pas été vérifiés.
+- **OverCrow**, pour lancer le widget pendant que vous l’écrivez.
+
+`overcrow-widget doctor` indique ce que votre installation a et ce qui lui
+manque.
+
+## 2. Créer un projet
+
+```sh
+overcrow-widget init my-counter --template counter
+cd my-counter
+npm install
+```
+
+`npm install` installe TypeScript et `@overcrow/sdk` 1.0.0, nommés dans le
+`package.json` du projet.
+
+Les templates sont `blank`, `counter`, `list` et `chart`. L’ID vaut par
+défaut `com.example.<dir>` : passez `--id` avec un nom DNS inversé que vous
+contrôlez (`com.playervox.*` est réservé).
+[Fichiers d’un projet](cli.md#fichiers-dun-projet) liste chaque fichier et
+indique lesquels sont empaquetés ;
+[les types du SDK](cli.md#les-types-du-sdk) explique comment ajouter le SDK
+à un autre projet.
+
+## 3. La vue
+
+`view.ocml` est du balisage : des éléments, des attributs, des expressions
+`{…}` liées à l’état, et des gestionnaires `on:<event>` qui appellent des
+fonctions exportées par la logique.
+
+<!-- source: templates/counter/view.ocml -->
+```xml
+<box class="counter">
+  <text class="value">{state.count}</text>
+  <box class="actions">
+    <button class="step" label={t("decrement")} on:activate={decrement}>
+      <icon name="minus"/>
+    </button>
+    <button class="step" label={t("increment")} on:activate={increment}>
+      <icon name="plus"/>
+    </button>
+  </box>
+</box>
+```
+
+La vue offre aussi `if`, `for` avec une clé obligatoire, et des composants
+locaux : voir [la vue](view.md). Chaque élément et chaque attribut figure
+dans [éléments et attributs](elements.md).
+
+## 4. Le style
+
+`style.ocss` est un sous-ensemble borné de CSS : sélecteurs de classe,
+d’élément, de descendant et d’enfant, états `:hover`, `:active`, `:focus`,
+`:disabled` et `:checked`, mise en page flex et grid, et les tokens du thème
+en `var(--…)`, qui suivent le thème clair ou sombre de l’utilisateur.
+
+<!-- source: templates/counter/style.ocss -->
+```css
+.step {
+  width: var(--icon-button-size);
+  height: var(--icon-button-size);
+  border-radius: var(--radius-md);
+  background: var(--color-surface-raised);
+}
+```
+
+<!-- source: templates/counter/style.ocss -->
+```css
+.step:hover {
+  background: var(--color-surface-hover);
+}
+```
+
+Il n’y a ni `@media`, ni `@import`, ni `url()`, ni `calc()` : une
+propriété ou un sélecteur inconnu est une erreur, il n’est pas ignoré en
+silence. Voir [le style](style.md) et
+[propriétés de style et tokens](style-properties.md).
+
+## 5. La logique
+
+`logic.ts` possède l’état. Déclarez son type une fois, modifiez-le dans vos
+gestionnaires, et la vue suit : après chaque tour, la VM évalue de nouveau
+la vue et n’envoie que ce qui a changé.
+
+<!-- source: templates/counter/logic.ts -->
+```ts
+import { initState } from "@overcrow/sdk";
+
+declare module "@overcrow/sdk" {
+  interface WidgetState {
+    count: number;
+  }
+}
+```
+
+<!-- source: templates/counter/logic.ts -->
+```ts
+export function increment(): void {
+  state.count += 1;
+}
+```
+
+La logique tourne dans une VM enfermée dans un sandbox, pas dans un
+navigateur : il n’y a ni DOM, ni `fetch`, ni `setTimeout`, ni `console`, ni
+`Intl`. Le SDK fournit les minuteurs, les services, des fonctions de
+formatage des heures et des nombres au format régional de l’utilisateur, les
+messages et le dessin. Voir [la logique](logic.md) et la
+[référence du SDK](sdk.md).
+
+## 6. Les messages
+
+`t("key")`, dans la vue ou la logique, lit `locales/en.json` ou
+`locales/fr.json` selon la langue de l’utilisateur et remplit les paramètres
+`{name}`.
+
+<!-- source: templates/counter/locales/en.json -->
+```json
+{
+  "decrement": "Decrease",
+  "increment": "Increase"
+}
+```
+
+Fournissez les deux fichiers ou aucun, avec les mêmes clés. Voir
+[messages](logic.md#messages).
+
+## 7. Vérifier
+
+```sh
+overcrow-widget check
+```
+
+`check` exécute les mêmes validateurs qu’OverCrow : manifeste, vue, style,
+messages, une analyse de la logique selon ce que la VM exécute, le
+TypeScript du projet, et un paquet construit en mémoire puis relu. Chaque
+problème a un code stable, une position et une ligne d’aide ; voir les
+[diagnostics](cli.md#diagnostics).
+
+## 8. Le lancer dans OverCrow
+
+```sh
+overcrow-widget dev
+```
+
+`dev` envoie le widget à l’overlay OverCrow qui tourne sur votre machine et
+le recharge à chaque enregistrement. OverCrow ne le propose que s’il a été
+lancé avec les installations de développement autorisées
+(`OVERCROW_WIDGET_DEVELOPMENT=1` ; `overcrow-widget doctor` affiche les
+commandes). Le widget porte la mention
+**Unverified · development package** ; ses permissions déclarées sont
+accordées pour la session seulement, et rien n’est conservé. Les
+`log.info(…)` de votre logique s’affichent dans le terminal. Voir
+[le canal de développement](dev-channel.md).
+
+## 9. Le tester
+
+Deux sortes de tests, décrites dans [tester un widget](testing.md) :
+
+- des tests unitaires de la logique avec `@overcrow/sdk/testing`, qui
+  exécute votre module avec un temps virtuel et des services simulés ;
+- des scénarios joués par `overcrow-widget test` dans le runtime headless
+  d’OverCrow : la vraie VM et le vrai rendu, des services qui répondent avec
+  des fixtures (des données simulées), et des images comparées à des images
+  de référence.
+
+<!-- source: templates/counter/tests/example.scenario.json -->
+```json
+  "host": { "mode": "interactive" },
+  "steps": [
+    { "expect": { "state": "running", "text": ["0"], "image": "initial" } },
+    { "pointer": { "click": { "label": "Increase" } } },
+    { "expect": { "text": ["1"], "noText": ["0"], "image": "increased", "fault": "none" } }
+  ]
+```
+
+```sh
+overcrow-widget test
+```
+
+## 10. Demander ce dont vous avez besoin
+
+Un widget n’obtient rien par défaut. Pour appeler une API, conserver des
+données ou lire des informations de jeu, déclarez-le dans `manifest.json` ;
+l’utilisateur donne son accord dans le Centre de contrôle avant que le
+widget n’y ait accès. Une règle
+réseau nomme une origine HTTPS, une méthode et un chemin complet, avec des
+paramètres typés :
+
+<!-- source: docs/content/examples/weather/manifest.json -->
+```json
+  "permissions": {
+    "network": [
+      {
+        "origin": "https://api.example.com",
+        "method": "GET",
+        "path": "/v1/forecast/{city}",
+        "pathParams": { "city": { "type": "slug", "maxLength": 32 } },
+        "queryParams": {
+          "units": { "type": "enum", "values": ["metric", "imperial"], "required": true }
+        }
+      }
+    ],
+    "storage": true
+  },
+```
+
+<!-- source: docs/content/examples/weather/logic.ts -->
+```ts
+    const url = `https://api.example.com/v1/forecast/${state.city}?units=${state.units}`;
+    const { status, body } = await http.fetch(url, { as: "json" });
+```
+
+Les données du jeu et du système viennent d’abonnements (`fps.subscribe`,
+`media.subscribe`…), qui mettent votre état à jour jusqu’à ce que vous les
+annuliez. [Services et permissions](services.md) explique ce que chaque
+permission autorise, et [sécurité](security.md) ce qu’un widget ne peut
+jamais faire. L’exemple complet se trouve dans
+[`docs/content/examples/weather`](../examples/weather/).
+
+## 11. Empaqueter
+
+```sh
+overcrow-widget package
+overcrow-widget inspect dist/com.example.my-counter-0.1.0.ocpkg
+```
+
+`package` écrit un `.ocpkg` déterministe dans `dist/` : les mêmes sources
+et la même version de la CLI donnent les mêmes octets sur tous les systèmes.
+`inspect` montre ce qu’un paquet contient et demande, comme le voit un
+relecteur. Un paquet installé localement reste non vérifié ; les
+utilisateurs obtiennent les widgets par le catalogue signé. Voir
+[le paquet](package.md).
+
+## 12. Soumettre
+
+Ajoutez un `listing.json` avec le texte de la marketplace, lancez vous-même
+l’admission, puis ouvrez une pull request qui ajoute votre widget sous
+`widgets/<dir>/`, sur la branche `candidate` du
+[dépôt public](https://github.com/Valhallab/playervox-overcrow-releases) :
+
+```sh
+overcrow-widget admit
+```
+
+`admit` exécute exactement les contrôles de la CI de la marketplace. La
+suite, de la revue au catalogue signé, est décrite dans
+[publication et revue](publishing.md).