@overcrow/mcp 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,352 @@
+# La vue
+
+`view.ocml` décrit ce qu’affiche un widget PlayerVox OverCrow : un arbre
+d’éléments, lié à l’état du widget par des expressions `{…}`. Il ressemble à
+du HTML ou à du JSX, mais ce n’est ni l’un ni l’autre : le jeu d’éléments
+est fermé, il n’y a pas de DOM et la vue ne contient aucun script. OverCrow
+met en page et dessine l’arbre lui-même.
+
+<!-- source: templates/list/view.ocml -->
+```xml
+<box class="checklist">
+  <text class="title">{t("title")}</text>
+  <list class="items" item-height="32">
+    <for each={state.items} as="item" key={item.id}>
+      <box class="row">
+        <checkbox label={item.text} checked={item.done} on:change={setDone(item.id, event.value)}/>
+        <text class={item.done ? "text done" : "text"}>{item.text}</text>
+        <button class="remove" label={t("remove")} on:activate={remove(item.id)}>
+          <icon name="x"/>
+        </button>
+      </box>
+    </for>
+  </list>
+  <text class="summary">{t("remaining", { count: remaining(state.items) })}</text>
+</box>
+```
+
+C’est le template de liste de tâches : un titre, une `list` défilante qui
+répète une ligne par entrée, et un résumé. La logique exporte `setDone`,
+`remove` et `remaining` ; `t` lit les messages de `locales/`.
+
+La vue est compilée quand vous empaquetez le widget : `overcrow-widget check`
+signale chaque erreur avec sa ligne et sa colonne. Un élément, un attribut ou
+un événement inconnu est une erreur, jamais ignorée. Le fichier source
+lui-même n’est pas livré.
+
+## Balisage
+
+- Le fichier est en UTF-8, sans marque d’ordre des octets.
+- Le document est une liste de nœuds de premier niveau : des déclarations
+  `<component>` et les enfants de la racine du widget, qui est une `box`.
+- Les éléments s’écrivent en minuscules : `<name …>…</name>` ou
+  `<name …/>`.
+- La valeur d’un attribut est un texte entre guillemets (`"…"` ou `'…'`),
+  une expression (`{…}`), ou rien, ce qui vaut `true` : `<button submit>`.
+  Les attributs sont séparés par des blancs et ne se répètent jamais.
+- Les commentaires s’écrivent `<!-- … -->`, sans `--` à l’intérieur.
+- DOCTYPE, instructions de traitement, sections CDATA et espaces de noms
+  sont refusés.
+
+Les entités sont `&amp;` `&lt;` `&gt;` `&quot;` `&apos;` `&lbrace;`
+`&rbrace;` `&nbsp;`, ainsi que `&#…;` ou `&#x…;` pour tout caractère qui
+n’est pas un caractère de contrôle. Un `{` ou un `}` littéral dans une
+valeur entre guillemets, comme un `}` isolé dans du texte, est refusé :
+écrivez `&lbrace;` et `&rbrace;`.
+
+## Éléments
+
+Chaque élément a un contenu fixe, un jeu d’attributs et les événements qu’il
+peut envoyer. Les conteneurs (`box`, `scroll`, `list`, `form`, `popover`,
+`button`) contiennent d’autres éléments ; `text` contient du texte et des
+enfants en ligne ; les autres sont des feuilles qu’OverCrow dessine :
+`icon`, `image`, `toggle`, `slider`, `field`, `chart`, `gauge`…
+
+<!-- generated:element-list -->
+| Élément | Signification |
+| --- | --- |
+| [`box`](elements.md#box) | Conteneur générique ; la mise en page flex ou grid vient du style. La racine de la vue est un `box`. |
+| [`scroll`](elements.md#scroll) | Conteneur qui rogne son contenu et que l’hôte fait défiler à la molette, par glissement et au clavier. |
+| [`list`](elements.md#list) | Liste à défilement vertical dont les enfants ne sont mis en page et peints que lorsqu’ils sont visibles. |
+| [`text`](elements.md#text) | Bloc de texte avec retour à la ligne ; ses enfants en ligne suivent le texte (une ligne de chat avec des emotes). |
+| [`span`](elements.md#span) | Portion de texte stylée à l’intérieur d’un `text`. |
+| [`icon`](elements.md#icon) | Icône Lucide teintée par `color`, dimensionnée par `font-size` sauf si `width` et `height` sont définis. |
+| [`image`](elements.md#image) | Image matricielle du paquet, ou image remise par un service (identifiant `asset:`) ; `object-fit` s’applique. |
+| [`avatar`](elements.md#avatar) | Image ronde, avec un texte de remplacement tant que l’image manque ou n’a pas pu être chargée. |
+| [`badge`](elements.md#badge) | Courte pastille de texte. |
+| [`button`](elements.md#button) | Contrôle activable ; ses enfants (icône, texte) forment son contenu. |
+| [`toggle`](elements.md#toggle) | Bascule activé/désactivé. |
+| [`checkbox`](elements.md#checkbox) | Case à cocher (listes de tâches). |
+| [`slider`](elements.md#slider) | Curseur sur un intervalle numérique ; le glissement est géré par l’hôte. |
+| [`select`](elements.md#select) | Liste déroulante ; la liste ouverte est dessinée par l’hôte. |
+| [`option`](elements.md#option) | Choix d’un `select` ; son texte est le libellé affiché. |
+| [`field`](elements.md#field) | Champ de texte d’une ligne, édité par l’hôte, méthodes de saisie (IME) comprises. |
+| [`textarea`](elements.md#textarea) | Champ de texte de plusieurs lignes, édité par l’hôte, méthodes de saisie (IME) comprises. |
+| [`form`](elements.md#form) | Regroupe des contrôles nommés. Avec `intent`, la validation envoie leurs valeurs à un service d’écriture directement depuis l’hôte ; la logique du widget ne fournit jamais ce contenu. |
+| [`elapsed`](elements.md#elapsed) | Durée affichée que l’hôte fait avancer à partir d’un repère donné par un service : un chronomètre qui tourne ne demande aucun travail à la logique. Stylé comme `text` ; repeint seulement quand le texte affiché change, au plus à 60 Hz, et jamais quand le widget est masqué. |
+| [`progress`](elements.md#progress) | Barre de progression horizontale. |
+| [`gauge`](elements.md#gauge) | Jauge en anneau ou en arc. |
+| [`chart`](elements.md#chart) | Graphique en ligne, en aire, en barres ou sparkline, dessiné par l’hôte. |
+| [`series`](elements.md#series) | Une série de données d’un `chart`, colorée par `color`. |
+| [`separator`](elements.md#separator) | Filet de séparation entre deux groupes. |
+| [`canvas`](elements.md#canvas) | Surface que l’hôte peint à partir de la dernière liste de commandes passée à `draw`. |
+| [`popover`](elements.md#popover) | Panneau flottant ancré à un élément, dessiné au-dessus du contenu et rogné au cadre du widget (listes déroulantes, menus contextuels). |
+<!-- /generated:element-list -->
+
+[Éléments et attributs](elements.md) donne les attributs et les événements
+de chacun.
+
+## Texte
+
+Le texte n’est admis que dans `text`, `span`, `badge` et `option`. Un `text`
+contient soit du texte, soit des enfants en ligne (`span`, `icon`, `image`),
+jamais les deux : pour styler un seul mot, placez chaque segment dans un
+`span`.
+
+<!-- source: widgets/performance/view.ocml -->
+```xml
+      <text class={row.valueClass} label={row.name} tooltip={row.hint}><span>{row.value}</span><if test={row.unit != ""}><span class="unit">{row.unit}</span></if></text>
+```
+
+Les blancs suivent la règle de JSX :
+
+- les tabulations deviennent des espaces ;
+- un saut de ligne entre deux mots devient une espace ;
+- un saut de ligne accolé à une balise ou à une expression disparaît avec
+  son indentation ;
+- une suite de blancs accolée à une balise est supprimée ; entre deux
+  expressions sur la même ligne, elle est conservée.
+
+Un saut de ligne avant une expression supprime donc l’espace qui la
+précède : écrivez `you have {state.count} messages` sur une seule ligne pour
+garder les deux espaces, ou écrivez `&#32;` là où il vous faut une espace
+que la règle supprimerait.
+
+## Attributs
+
+Une valeur entre guillemets est convertie dans le type de l’attribut et
+vérifiée à la compilation de la vue :
+
+| Type | Valeur entre guillemets |
+| --- | --- |
+| booléen | `true` ou `false` ; l’attribut seul vaut `true` |
+| entier | un entier décimal, sans zéro initial |
+| nombre | un nombre décimal, sans exposant |
+| liste de nombres | des nombres séparés par des espaces : `values="12 18.5 30"` |
+| texte, identifiant | le texte lui-même |
+| image | un fichier du paquet : `src="assets/logo.png"` |
+
+`attr={expression}`, en revanche, lie l’attribut à une expression ; OverCrow
+vérifie chaque valeur qu’envoie le widget. Les valeurs qui n’existent qu’à
+l’exécution du widget, comme une image fournie par un service, doivent être
+liées.
+
+Cinq attributs existent sur tous les éléments :
+
+<!-- generated:common-attributes -->
+| Attribut | Type | Obligatoire | Signification |
+| --- | --- | --- | --- |
+| `class` | liste de classes | non | Classes de style : des noms distincts, séparés par une espace. |
+| `ref` | nom de `ref` statique | non | Nom par lequel `draw` désigne ce `canvas` et par lequel un attribut tel que `anchor` d’un `popover` désigne cet élément. Statique, unique dans la vue, et interdit dans un `for` ou dans le corps d’un composant, où il nommerait plusieurs éléments. |
+| `label` | texte ≤ 256 octets | non | Nom accessible ; obligatoire sur les contrôles qui ne montrent qu’une icône. |
+| `tooltip` | texte ≤ 256 octets | non | Texte brut que l’hôte affiche au survol ou au focus. |
+| `on` | noms d’événements triés | non | Événements transmis à la logique ; s’écrit `on:<event>` dans la vue. |
+<!-- /generated:common-attributes -->
+
+`class` est le point d’accroche du [style](style.md). `label` est le nom
+accessible de l’élément : donnez-en un à chaque contrôle dont le contenu est
+une icône.
+
+### Nommer un élément : `ref`
+
+`ref="name"` donne un nom à un élément. Ce nom sert à deux choses :
+`draw(name, commands)` dessine dans le `canvas` de ce nom, et un `popover`
+se place contre l’élément que nomme son `anchor`.
+
+<!-- source: docs/content/examples/countdown/view.ocml -->
+```xml
+<box ref="panel" class="countdown" on:contextmenu={openMenu}>
+```
+
+<!-- source: docs/content/examples/countdown/view.ocml -->
+```xml
+<popover anchor="panel" placement="pointer" open={state.menu} on:dismiss={closeMenu}>
+  <button class="menu-row" on:activate={resetRounds}>
+    <text class="menu-text">{t("reset-rounds")}</text>
+  </button>
+</popover>
+```
+
+Un `ref` s’écrit toujours entre guillemets et il est unique dans la vue. Il
+est refusé dans un `for` ou dans un composant, où il nommerait plusieurs
+éléments.
+
+## Événements
+
+`on:event={handler}` demande à OverCrow d’envoyer à la logique un événement
+de l’élément. Sans cela, le widget ignore tout de l’événement : OverCrow ne
+lui signale ni les mouvements du pointeur ni les appuis de touches qu’il n’a
+pas demandés.
+
+Un gestionnaire s’écrit de deux façons :
+
+- **le nom d’une fonction** exportée par la logique, appelée avec le détail
+  de l’événement : `on:activate={increment}` ;
+- **un appel**, avec les arguments de votre choix ; `event` y désigne le
+  détail de l’événement : `on:change={setDone(item.id, event.value)}`.
+
+<!-- source: templates/list/view.ocml -->
+```xml
+        <checkbox label={item.text} checked={item.done} on:change={setDone(item.id, event.value)}/>
+        <text class={item.done ? "text done" : "text"}>{item.text}</text>
+        <button class="remove" label={t("remove")} on:activate={remove(item.id)}>
+          <icon name="x"/>
+        </button>
+```
+
+Les événements sont `activate`, `contextmenu`, `wheel`, `keydown`, `input`,
+`change`, `submit`, `focus`, `blur`, `reachend`, `stick` et `dismiss` ;
+[événements](elements.md#événements) décrit chacun d’eux et le détail qu’il
+transporte, et chaque [élément](elements.md#éléments) liste ceux qu’il
+envoie. Certains sont des actions de l’utilisateur, pendant lesquelles un
+widget peut appeler un service protégé ; voir
+[les appels qui demandent une action de l’utilisateur](services.md#les-appels-qui-demandent-une-action-de-lutilisateur).
+Les widgets ne reçoivent d’entrées qu’en mode interactif d’OverCrow : en
+mode passif, les clics les traversent et atteignent le jeu.
+
+## Conditions, boucles et composants
+
+<!-- generated:constructs -->
+| Syntaxe | Signification |
+| --- | --- |
+| `{expr}` | Insère la valeur d’une expression dans du texte ou dans la valeur d’un attribut. |
+| `<if test={expr}> … <else-if test={expr}> … <else>` | Sous-arbre conditionnel. |
+| `<for each={expr} as="item" key={expr}>` | Répète un sous-arbre ; `key` est obligatoire et doit être unique parmi les éléments répétés. |
+| `<component name="x" props="a b"> … <slot/> … </component>` | Composant local, avec ses propriétés déclarées et un emplacement (`slot`), utilisé sous la forme `<x a={…}>`. |
+| `on:<event>={handler}` | Abonne l’élément à l’un de ses événements et nomme le gestionnaire de la logique. |
+<!-- /generated:constructs -->
+
+### `if`, `else-if`, `else`
+
+<!-- source: widgets/stopwatch/view.ocml -->
+```xml
+        <if test={state.stopwatch.running}>
+          <icon name="pause"/>
+        </if>
+        <else>
+          <icon name="play"/>
+        </else>
+```
+
+`else-if` et `else` suivent directement un `if` : seuls des blancs et des
+commentaires peuvent les en séparer.
+
+### `for`
+
+`for` répète ses enfants pour chaque entrée d’une liste. `each`, `as` et
+`key` sont tous obligatoires, et la clé doit être unique parmi les entrées
+répétées : c’est grâce à elle qu’OverCrow sait quelle ligne a bougé, est
+apparue ou a disparu.
+
+<!-- source: widgets/warframe-market/view.ocml -->
+```xml
+      <for each={state.results} as="item" key={item.slug}>
+        <button class="result" label={item.name} on:activate={select(item.slug)}>
+          <text class="result-name">{item.name}</text>
+          <icon class="result-arrow" name="chevron-right"/>
+        </button>
+      </for>
+```
+
+Pour une longue liste, placez le `for` dans un élément `list` : OverCrow ne
+met en page et ne dessine que les lignes visibles.
+
+### Composants
+
+Un composant est un morceau de vue doté d’un nom et de propriétés déclarées,
+à écrire une fois et à utiliser plusieurs fois. Il est local à la vue.
+
+<!-- source: docs/content/examples/countdown/view.ocml -->
+```xml
+<component name="stat" props="name value">
+  <box class="stat">
+    <text class="stat-name">{name}</text>
+    <text class="stat-value">{value}</text>
+  </box>
+</component>
+```
+
+<!-- source: docs/content/examples/countdown/view.ocml -->
+```xml
+  <stat name={t("state")} value={stateText(state.running, state.remainingMs)}/>
+```
+
+- Les composants se déclarent au premier niveau, une seule fois chacun,
+  sous un nom qui n’est pas celui d’un élément.
+- Le corps ne voit que ses propres propriétés, pas les noms visibles là où
+  le composant est utilisé. Passez-lui ce dont il a besoin.
+- Une utilisation ne passe que des propriétés déclarées. Une propriété entre
+  guillemets est un texte ; liez-la (`value={5}`) pour tout autre type.
+- Un corps peut contenir un seul `<slot/>`, où vont les enfants de chaque
+  utilisation.
+- Un composant ne peut pas se contenir lui-même, et une utilisation
+  n’accepte pas de gestionnaires `on:` : placez-les sur des éléments du
+  corps.
+
+`if`, `for` et les composants sont transparents pour les règles de contenu :
+leurs enfants doivent convenir à l’élément qui les entoure.
+
+## Expressions
+
+Les expressions forment un sous-ensemble de JavaScript, réduit et strict :
+
+- les littéraux : nombres (`0`, `12`, `1.5`), chaînes, `true`, `false`,
+  `null`, littéraux de tableau et d’objet ;
+- les noms de la portée et leurs membres : `a.b`, `a?.b`, `a[i]`,
+  `a?.[i]` ;
+- les opérateurs : `!`, `-` et `+` unaires, `* / %`, `+ -`, `< <= > >=`,
+  `== != === !==`, `&&`, `||`, `??`, et `a ? b : c`. `??` ne se combine pas
+  avec `&&` ou `||` sans parenthèses ;
+- les appels de fonctions exportées par la logique, par leur nom seul :
+  `remaining(state.items)`. `t(key, params)` en fait partie.
+
+Les noms de la portée sont `state`, les noms `as` des `for` englobants, les
+propriétés du composant englobant, et `event` dans un gestionnaire. Un nom
+ne peut pas en masquer un autre.
+
+Il n’y a ni affectation, ni fonction fléchée ou littérale, ni `new`, ni
+`this`, ni littéral de gabarit, ni expression régulière, ni appel de
+méthode, ni globale : tout ce qui dépasse un calcul simple a sa place dans
+une fonction de la logique. C’est ce qui permet de vérifier la vue : à
+l’empaquetage du widget, chaque expression est compilée en une fonction de
+`logic.js`, et la vue elle-même ne contient aucun code.
+
+<!-- source: templates/list/view.ocml -->
+```xml
+        <text class={item.done ? "text done" : "text"}>{item.text}</text>
+```
+
+Les mots réservés de JavaScript, `constructor`, `prototype`, `eval`,
+`undefined`, `globalThis`, `overcrow` et tout nom qui commence par `__` sont
+refusés.
+
+## Quand la vue est incorrecte
+
+Chaque problème est un diagnostic de `overcrow-widget check`, doté d’un code
+stable :
+
+| Code | Problème |
+| --- | --- |
+| `view.syntax`, `view.encoding`, `view.size`, `view.invalid_entity` | Le fichier n’est pas un balisage bien formé. |
+| `view.unknown_element`, `view.invalid_parent` | Un élément qui n’existe pas, ou placé là où il ne peut pas être. |
+| `view.unknown_attribute`, `view.duplicate_attribute`, `view.invalid_attribute`, `view.missing_attribute` | Un attribut que l’élément n’a pas, écrit deux fois, de valeur incorrecte, ou obligatoire et absent. |
+| `view.unknown_event`, `view.invalid_handler` | Un événement que l’élément n’envoie pas (ou posé sur l’utilisation d’un composant), ou un gestionnaire qui n’est ni un nom ni un appel. |
+| `view.expression_syntax`, `view.expression_too_long`, `view.expression_too_deep`, `view.expression_too_many_entries` | Une expression hors du sous-ensemble ou de ses limites. |
+| `view.reserved_name`, `view.unknown_name` | Un nom refusé, ou absent de la portée. |
+| `view.invalid_text` | Du texte là où l’élément n’en accepte pas, ou mêlé à des enfants en ligne. |
+| `view.invalid_component`, `view.recursive_component`, `view.invalid_slot`, `view.invalid_construct` | Un composant, un slot, un `if` ou un `for` qui enfreint ses règles. |
+| `view.invalid_ref`, `view.unknown_ref` | Un `ref` qui n’est pas unique ou qui se trouve dans un `for`, ou un `anchor` qui n’en nomme aucun. |
+| `view.missing_asset` | Une image statique absente de `assets/`. |
+| `view.bound_value` | Un `value` sur un contrôle d’un formulaire lié à un intent d’écriture ; voir [les formulaires](forms.md#les-formulaires-qui-écrivent-des-données-de-lutilisateur). |
+| `view.too_many_elements`, `view.too_many_components`, `view.too_many_children`, `view.too_many_expressions`, `view.too_deep` | Une [limite](limits.md) de la vue est dépassée. |
+| `logic.missing_export` | La vue appelle une fonction que la logique n’exporte pas. |

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

@@ -0,0 +1,81 @@
+# Widgets de référence
+
+Les widgets intégrés de PlayerVox OverCrow sont des widgets ordinaires,
+écrits avec le SDK public, empaquetés par `overcrow-widget` et publiés dans
+le catalogue signé comme les vôtres. Leurs sources se trouvent dans
+[`widgets/`](../../../widgets/), dans le dépôt public, sous licence MIT :
+lisez-les, copiez-les et servez-vous-en comme point de départ.
+
+<!-- generated:widgets -->
+| Widget | Description | ID | Permissions | Sources |
+| --- | --- | --- | --- | --- |
+| **Horloge** | Affiche l’heure locale et, en option, la date, au format 24 heures. | `com.playervox.overcrow.clock` | aucune | [widgets/clock/](../../../widgets/clock/) |
+| **FPS** | Affiche la fréquence d’images présentée par le jeu, quand l’hôte dispose d’une source. | `com.playervox.overcrow.fps` | `fps.read` | [widgets/fps/](../../../widgets/fps/) |
+| **Média** | Le morceau que joue votre lecteur de musique, avec sa pochette, et les boutons précédent, lecture/pause et suivant en mode interactif. | `com.playervox.overcrow.media` | `media.read`, `media.control` | [widgets/media/](../../../widgets/media/) |
+| **Notes** | Vos notes et listes de tâches par-dessus le jeu : jusqu’à huit notes, chacune avec un texte libre et une liste de tâches, les mêmes pour tous les jeux. Lisez-les en mode passif ; en mode interactif, choisissez, créez, supprimez et modifiez-les dans le widget, et cochez les éléments. Elles restent sur cet ordinateur. | `com.playervox.overcrow.notes` | `notes.read`, `notes.write` | [widgets/notes/](../../../widgets/notes/) |
+| **Performances** | CPU et mémoire du jeu, et les températures que cet ordinateur expose. | `com.playervox.overcrow.performance` | `telemetry.read`, `fps.read` | [widgets/performance/](../../../widgets/performance/) |
+| **Journal de sessions** | Les sessions de jeu terminées de votre jeu, de la plus récente à la plus ancienne : date, heure de début et durée, cinq par page. Enregistrées sur votre appareil sans compte, fusionnées avec votre journal PlayerVox si vous synchronisez. Supprimez une session après confirmation. | `com.playervox.overcrow.playervox.journal` | `journal.read`, `journal.delete` | [widgets/playervox-journal/](../../../widgets/playervox-journal/) |
+| **Ma note** | Votre note PlayerVox du jeu Steam auquel vous jouez : son grade et son score, et en mode interactif trois critères et un avis facultatif à publier ou mettre à jour. Nécessite votre compte PlayerVox. | `com.playervox.overcrow.playervox.rating` | `playervox.rating.read`, `playervox.rating.write` | [widgets/playervox-rating/](../../../widgets/playervox-rating/) |
+| **Avis des joueurs** | Ce que les joueurs de PlayerVox pensent du jeu auquel vous jouez : trois avis par page avec la note et le score de chaque joueur, dans votre langue quand une traduction existe. Limitez-les aux joueurs que vous suivez depuis le menu du widget. Nécessite votre compte PlayerVox. | `com.playervox.overcrow.playervox.reviews` | `playervox.reviews.read` | [widgets/playervox-reviews/](../../../widgets/playervox-reviews/) |
+| **Note PlayerVox** | La note de la communauté PlayerVox pour votre jeu Steam, avec son score, son nombre de votes et trois critères. Sans compte ; le badge reste toujours visible. | `com.playervox.overcrow.playervox.score` | `playervox.score.read` | [widgets/playervox-score/](../../../widgets/playervox-score/) |
+| **Session** | Affiche la durée de la session de jeu en cours. | `com.playervox.overcrow.session` | `session.read` | [widgets/session/](../../../widgets/session/) |
+| **Chronomètre** | Un chronomètre au centième de seconde, démarré, mis en pause et réinitialisé par ses boutons ou les raccourcis de l’hôte. | `com.playervox.overcrow.stopwatch` | `stopwatch.read`, `stopwatch.control` | [widgets/stopwatch/](../../../widgets/stopwatch/) |
+| **Chat Twitch** | Lisez et envoyez des messages dans le chat Twitch public de votre choix : vos chaînes favorites, l’historique défilant avec emotes et réponses en mode interactif, les derniers messages qui s’effacent en mode passif. Nécessite votre compte Twitch. | `com.playervox.overcrow.twitch.chat` | `twitch.chat.read`, `twitch.chat.compose` | [widgets/twitch-chat/](../../../widgets/twitch-chat/) |
+| **Marché Warframe** | Recherche les objets PC publics dans un catalogue en cache, affiche les vendeurs et acheteurs en ligne d’un objet dans deux onglets et copie un message d’échange sur un clic. | `com.playervox.overcrow.warframe.market` | `network`, `storage`, `clipboardWrite` | [widgets/warframe-market/](../../../widgets/warframe-market/) |
+<!-- /generated:widgets -->
+
+## Ce que contient le dossier d’un widget
+
+- les sources du paquet : `manifest.json`, `view.ocml`, `style.ocss`,
+  `logic.ts`, `locales/`, `LICENSE` ;
+- `listing.json`, son texte pour la marketplace ;
+- `assets/preview.png`, son aperçu dans la marketplace : l’image de son
+  scénario `preview`, cadrée et mise en scène par
+  `node scripts/compose-previews.mjs` ;
+- `tests/` : les tests unitaires de la logique, et des scénarios avec leurs
+  images de référence dans les deux thèmes, les deux langues et deux
+  échelles, joués par `overcrow-widget test` dans le runtime headless
+  d’OverCrow ;
+- `README.md` : ce qu’il affiche, son menu, ses permissions, son
+  fonctionnement et son coût.
+
+## Ce que chacun montre
+
+| Pour voir comment… | Lisez |
+| --- | --- |
+| se déclencher à chaque minute ou seconde de l’heure locale, suivre une option du menu | Horloge |
+| s’abonner à un service et afficher une valeur manquante | FPS, Session |
+| disposer une liste de valeurs en grille, masquer une ligne du menu que la machine ne peut pas alimenter | Performances |
+| afficher une image fournie par OverCrow, relancer un abonnement qui s’est terminé | Média |
+| commander un service sur une action de l’utilisateur, laisser OverCrow faire avancer une durée | Chronomètre |
+| modifier du texte avec un formulaire lié à un intent d’écriture, conserver des brouillons | Notes, Ma note |
+| dessiner sur un canvas | Note PlayerVox, Ma note |
+| parcourir un service page par page et réagir à une révision | Avis des joueurs, Journal de sessions |
+| maintenir une longue liste défilante sur sa fin, envoyer un message | Chat Twitch |
+| appeler une API HTTP, la mettre en cache dans le stockage, copier dans le presse-papiers | Marché Warframe |
+
+Marché Warframe n’est pas un widget intégré : widget PlayerVox du catalogue,
+installé à la demande, il montre des routes réseau avec une limite de
+réponse déclarée, le stockage pour un catalogue en cache et une copie dans
+le presse-papiers sur un clic.
+
+## Travailler sur l’un d’eux
+
+Depuis une copie de travail du dépôt, liez aux widgets le SDK de cette
+révision, puis vérifiez l’un d’eux, empaquetez-le et lancez ses tests
+unitaires :
+
+```sh
+node scripts/prepare-widgets.mjs
+overcrow-widget check widgets/clock
+overcrow-widget package widgets/clock
+node --test widgets/clock/tests/logic.test.mjs
+```
+
+`prepare-widgets.mjs` demande que le SDK soit construit d’abord (`npm ci`
+puis `npm run build` dans `sdk/`). Les quatre templates
+d’`overcrow-widget init` se trouvent dans
+[`templates/`](../../../templates/), et deux exemples complets, écrits pour
+ces pages, dans [`docs/content/examples/`](../examples/) : `weather` appelle
+une API HTTP et `countdown` utilise un minuteur, un canvas, un menu
+contextuel et le stockage.

package/dist/content/examples/clock/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valhallab SASU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/content/examples/clock/README.md

@@ -0,0 +1,75 @@
+# Clock
+
+`com.playervox.overcrow.clock` — the local time of day and, optionally, the
+date on a second line. A built-in of OverCrow, written against the public
+`@overcrow/sdk` and packaged with `overcrow-widget` like any creator's
+widget. MIT.
+
+## What it shows
+
+| State | Shows |
+| --- | --- |
+| Default | `14:08` over `17/07/2026` |
+| Seconds on | `14:08:42` |
+| Date off | the time alone |
+| Date format | `dd/mm/yyyy` (default), `yyyy-mm-dd` or `mm/dd/yyyy`, whatever the user's regional date order |
+
+Always 24-hour and zero padded, in English and French alike. The time is
+local: the VM's clock is UTC, and the SDK applies the host's UTC offset
+(`host.region`), which the host sends again at each summer time change.
+
+## Menu
+
+| Row | Type | Default |
+| --- | --- | --- |
+| Show seconds / Afficher les secondes | toggle `show-seconds` | off |
+| Show date / Afficher la date | toggle `show-date` | on |
+| Date format / Format de date | choice `date-format`, shown while the date is | `day-month-year` |
+
+## Permissions
+
+None. The widget reads no service.
+
+## How it works
+
+- `timers.atEach("minute" | "second", tick)`: one repeating host timer
+  aligned on the local boundary, one VM turn per tick; a tick that drifted
+  re-aligns it. No tick while hidden; the time is current at once when the
+  widget is shown again.
+- `onHost`: a menu change re-arms the timer at the new unit at once, and a
+  new UTC offset shows at once.
+- The accessible label is "Local time {time}, {date}" /
+  "Heure locale {time}, {date}".
+
+## Tests
+
+- `tests/logic.test.mjs`: the logic on `@overcrow/sdk/testing` (formats,
+  defaults, the timer and its re-arming).
+- Scenarios, played by `overcrow-widget test` in OverCrow's headless
+  runtime, with their reference images: `render` (both themes and
+  languages at 100 and 150 %), `options` (each menu row), `ticks` (minutes,
+  seconds, midnight), `hidden`, `summer-time` (both changes).
+
+```sh
+node ../../scripts/prepare-widgets.mjs
+overcrow-widget check && overcrow-widget package
+node --test tests/*.test.mjs
+overcrow-widget test --runtime <overcrow-widget-headless>
+```
+
+## Cost
+
+Measured on 2026-09-30 with OverCrow's release build, on an AMD Ryzen 7
+5800X3D Linux workstation and in a Windows 11 virtual machine (2 vCPU):
+
+| | Linux | Windows (VM) |
+| --- | --- | --- |
+| VM start (spawn → ready) | 1.9 ms | 13.5–14.5 ms, sandboxed |
+| Widget start, warm, into the overlay's runtime | 7 ms at most | — |
+| VM memory | 0.55 MiB anonymous | 0.83 MiB private working set |
+| VM CPU per tick, seconds shown | about 95 µs, one VM turn | — |
+| Overlay frames | one each minute (each second with seconds) | — |
+
+With the Session and FPS widgets beside it, the overlay's process grows by
+about 2 MB per widget and stays at 0.1 % of one core; nothing runs while
+the overlay is hidden.

package/dist/content/examples/clock/listing.json

@@ -0,0 +1,19 @@
+{
+  "author": "PlayerVox",
+  "spdxLicense": "MIT",
+  "sourceUrl": "https://github.com/Valhallab/playervox-overcrow-releases/tree/main/widgets/clock",
+  "preview": "assets/preview.png",
+  "defaultLocale": "en",
+  "localizations": [
+    {
+      "locale": "en",
+      "name": "Clock",
+      "description": "Shows the local time of day and, optionally, the date, in a 24-hour format."
+    },
+    {
+      "locale": "fr",
+      "name": "Horloge",
+      "description": "Affiche l’heure locale et, en option, la date, au format 24 heures."
+    }
+  ]
+}

package/dist/content/examples/clock/locales/en.json

@@ -0,0 +1,4 @@
+{
+  "label": "Local time {time}",
+  "label-date": "Local time {time}, {date}"
+}

package/dist/content/examples/clock/locales/fr.json

@@ -0,0 +1,4 @@
+{
+  "label": "Heure locale {time}",
+  "label-date": "Heure locale {time}, {date}"
+}

package/dist/content/examples/clock/logic.ts

@@ -0,0 +1,85 @@
+// Clock: the local time of day, 24-hour, and the date in the order the user
+// chose in the widget menu. The VM's clock is UTC: the SDK formats from the
+// host's UTC offset, and its timer wakes at each minute (or second) of local
+// time.
+import {
+  formatDate,
+  formatTime,
+  initState,
+  onHost,
+  option,
+  t,
+  timers,
+  type DateOrder,
+  type Timer,
+} from "@overcrow/sdk";
+
+/** The `date-format` menu values and the date order each one means. */
+export const DATE_ORDERS: Readonly<Record<string, DateOrder>> = {
+  "day-month-year": "dmy",
+  "year-month-day": "ymd",
+  "month-day-year": "mdy",
+};
+
+declare module "@overcrow/sdk" {
+  interface WidgetState {
+    now: number;
+    seconds: boolean;
+    showDate: boolean;
+    order: DateOrder;
+  }
+}
+
+/** The menu values, with their defaults. */
+export function menuValues(): { seconds: boolean; showDate: boolean; order: DateOrder } {
+  return {
+    seconds: option("show-seconds", false),
+    showDate: option("show-date", true),
+    order: DATE_ORDERS[option("date-format", "day-month-year")] ?? "dmy",
+  };
+}
+
+const state = initState({ now: Date.now(), ...menuValues() });
+
+export function clockTime(now: number, seconds: boolean): string {
+  return formatTime(now, { seconds });
+}
+
+export function clockDate(now: number, order: DateOrder): string {
+  return formatDate(now, { order });
+}
+
+export function clockLabel(now: number, seconds: boolean, showDate: boolean, order: DateOrder): string {
+  const time = clockTime(now, seconds);
+  return showDate ? t("label-date", { time, date: clockDate(now, order) }) : t("label", { time });
+}
+
+let clock: Timer | undefined;
+
+function tick(): void {
+  state.now = Date.now();
+}
+
+/** Ticks at each second or minute of local time, and shows the time now. */
+function start(): void {
+  clock?.cancel();
+  clock = timers.atEach(state.seconds ? "second" : "minute", tick);
+  tick();
+}
+
+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();
+  }
+});
+
+start();