@overcrow/mcp 0.0.0 → 0.1.1

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();

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

@@ -0,0 +1,44 @@
+{
+  "schemaVersion": 1,
+  "apiVersion": 1,
+  "id": "com.playervox.overcrow.clock",
+  "version": "1.0.2",
+  "name": {
+    "en": "Clock",
+    "fr": "Horloge"
+  },
+  "sizing": {
+    "fit": "both",
+    "preferred": { "width": 110, "height": 60 },
+    "min": { "width": 40, "height": 24 },
+    "max": { "width": 480, "height": 240 }
+  },
+  "wrapper": {
+    "menu": [
+      {
+        "type": "toggle",
+        "id": "show-seconds",
+        "label": { "en": "Show seconds", "fr": "Afficher les secondes" },
+        "default": false
+      },
+      {
+        "type": "toggle",
+        "id": "show-date",
+        "label": { "en": "Show date", "fr": "Afficher la date" },
+        "default": true
+      },
+      {
+        "type": "choice",
+        "id": "date-format",
+        "label": { "en": "Date format", "fr": "Format de date" },
+        "visibleWhen": "show-date",
+        "choices": [
+          { "value": "day-month-year", "label": { "en": "dd/mm/yyyy", "fr": "jj/mm/aaaa" } },
+          { "value": "year-month-day", "label": { "en": "yyyy-mm-dd", "fr": "aaaa-mm-jj" } },
+          { "value": "month-day-year", "label": { "en": "mm/dd/yyyy", "fr": "mm/jj/aaaa" } }
+        ],
+        "default": "day-month-year"
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,16 @@
+{
+  "name": "overcrow-widget-clock",
+  "version": "1.0.2",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "check": "overcrow-widget check",
+    "package": "overcrow-widget package",
+    "test": "node --test tests/*.test.mjs"
+  },
+  "devDependencies": {
+    "@overcrow/sdk": "1.0.0",
+    "typescript": "6.0.3"
+  }
+}

package/dist/content/examples/clock/style.ocss

@@ -0,0 +1,26 @@
+/* One compact column: the time over the date, 1 px apart. The wrapper
+   draws the panel and its 8 px margin; the content adds 2 px on the
+   sides: the built-in's 10 × 8 px margin. */
+.clock {
+  flex-direction: column;
+  align-items: start;
+  row-gap: 1px;
+  padding: 0 2px;
+}
+
+/* Values use the UI font with tabular figures, so they never shift. */
+.time {
+  font-family: var(--font-ui);
+  font-size: var(--font-size-value);
+  font-variant-numeric: tabular-nums;
+  color: var(--color-text);
+  white-space: nowrap;
+}
+
+.date {
+  font-family: var(--font-ui);
+  font-size: var(--font-size-small);
+  font-variant-numeric: tabular-nums;
+  color: var(--color-text-muted);
+  white-space: nowrap;
+}

package/dist/content/examples/clock/tests/hidden.scenario.json

@@ -0,0 +1,68 @@
+{
+  "scenarioVersion": 1,
+  "name": "hidden",
+  "description": "Hidden, the clock gets no tick; shown again, it shows the current time at once.",
+  "host": {
+    "zone": {
+      "offsetMinutes": 120
+    },
+    "startAt": 1784290122000,
+    "options": {
+      "show-seconds": true
+    }
+  },
+  "steps": [
+    {
+      "expect": {
+        "text": [
+          "14:08:42"
+        ]
+      }
+    },
+    {
+      "host": {
+        "visible": false
+      }
+    },
+    {
+      "advance": {
+        "ms": 300000
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "14:08:42"
+        ],
+        "noText": [
+          "14:13:42"
+        ]
+      }
+    },
+    {
+      "host": {
+        "visible": true
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "14:13:42"
+        ]
+      }
+    },
+    {
+      "advance": {
+        "ms": 1000
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "14:13:43"
+        ],
+        "fault": "none"
+      }
+    }
+  ]
+}

package/dist/content/examples/clock/tests/load-logic.mjs

@@ -0,0 +1,22 @@
+// Compiles this widget's logic.ts with the project's TypeScript into
+// dist/ and imports it, after the test installed its runtime
+// (`@overcrow/sdk/testing`), as the VM runs logic.js after its prelude.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import ts from "typescript";
+
+export async function loadLogic() {
+  const root = new URL("../", import.meta.url);
+  const source = readFileSync(new URL("logic.ts", root), "utf8");
+  const { outputText } = ts.transpileModule(source, {
+    compilerOptions: {
+      module: ts.ModuleKind.ES2022,
+      target: ts.ScriptTarget.ES2023,
+      verbatimModuleSyntax: true,
+    },
+  });
+  mkdirSync(new URL("dist/", root), { recursive: true });
+  // One file per test process: test files run in parallel.
+  const output = new URL(`dist/logic-${process.pid}.mjs`, root);
+  writeFileSync(output, outputText);
+  return import(output.href);
+}

package/dist/content/examples/clock/tests/logic.test.mjs

@@ -0,0 +1,89 @@
+// Unit tests of the Clock's logic on @overcrow/sdk/testing: virtual time,
+// the host's region and menu values, no VM.
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { installRuntime } from "@overcrow/sdk/testing";
+
+import { loadLogic } from "./load-logic.mjs";
+
+// 14:08:42.250 in UTC+2, 2026-07-17.
+const START = Date.UTC(2026, 6, 17, 12, 8, 42, 250);
+const vm = installRuntime({
+  now: START,
+  host: {
+    region: { numberFormat: "us", dateOrder: "mdy", offsetMinutes: 120 },
+    messages: { label: "Local time {time}", "label-date": "Local time {time}, {date}" },
+  },
+});
+const logic = await loadLogic();
+const { state } = await import("@overcrow/sdk");
+
+test("defaults: date on, day/month/year, no seconds, whatever the region's order", () => {
+  assert.deepEqual(
+    { seconds: state.seconds, showDate: state.showDate, order: state.order },
+    { seconds: false, showDate: true, order: "dmy" },
+  );
+  assert.equal(logic.clockTime(state.now, state.seconds), "14:08");
+  assert.equal(logic.clockDate(state.now, state.order), "17/07/2026");
+  assert.equal(
+    logic.clockLabel(state.now, false, true, "dmy"),
+    "Local time 14:08, 17/07/2026",
+  );
+  assert.equal(logic.clockLabel(state.now, true, false, "dmy"), "Local time 14:08:42");
+});
+
+test("the three date formats and an unknown stored value", () => {
+  const formats = {};
+  for (const [value, order] of Object.entries(logic.DATE_ORDERS)) {
+    formats[value] = logic.clockDate(START, order);
+  }
+  assert.deepEqual(formats, {
+    "day-month-year": "17/07/2026",
+    "year-month-day": "2026-07-17",
+    "month-day-year": "07/17/2026",
+  });
+  vm.setHost({ options: { "date-format": "week-day" } });
+  assert.equal(state.order, "dmy", "an unknown value falls back to the default");
+  vm.setHost({ options: {} });
+});
+
+test("24-hour, zero padded", () => {
+  const night = Date.UTC(2026, 0, 1, 23, 5, 9);
+  assert.equal(logic.clockTime(night, true), "01:05:09");
+  assert.equal(logic.clockTime(Date.UTC(2026, 0, 1, 11, 0, 0), false), "13:00");
+});
+
+test("one timer at the next local minute, then each minute", () => {
+  assert.equal(vm.timers.length, 1);
+  assert.equal(vm.timers[0].dueAt, Date.UTC(2026, 6, 17, 12, 9));
+  vm.advance(Date.UTC(2026, 6, 17, 12, 9) - vm.now);
+  assert.equal(logic.clockTime(state.now, state.seconds), "14:09");
+  assert.deepEqual(
+    vm.timers.map(({ intervalMs, repeat }) => ({ intervalMs, repeat })),
+    [{ intervalMs: 60_000, repeat: true }],
+  );
+  assert.equal(vm.advance(120_000), 2);
+  assert.equal(logic.clockTime(state.now, state.seconds), "14:11");
+});
+
+test("turning seconds on re-arms at once on seconds, and off again on minutes", () => {
+  vm.advance(7_500);
+  vm.setHost({ options: { "show-seconds": true } });
+  assert.equal(state.seconds, true);
+  assert.equal(logic.clockTime(state.now, state.seconds), "14:11:07", "shown at once");
+  assert.equal(vm.timers.length, 1, "the minute timer is gone");
+  vm.advance(500);
+  assert.equal(logic.clockTime(state.now, state.seconds), "14:11:08");
+  vm.advance(1_000);
+  assert.equal(logic.clockTime(state.now, state.seconds), "14:11:09");
+  vm.setHost({ options: { "show-seconds": false, "show-date": false } });
+  assert.equal(state.showDate, false);
+  assert.equal(vm.timers.length, 1);
+  assert.equal(vm.timers[0].dueAt, Date.UTC(2026, 6, 17, 12, 12));
+  vm.setHost({ options: {} });
+});
+
+test("a new UTC offset shows at once", () => {
+  vm.setHost({ region: { numberFormat: "us", dateOrder: "mdy", offsetMinutes: -240 } });
+  assert.equal(logic.clockTime(state.now, state.seconds), "08:11");
+});

package/dist/content/examples/clock/tests/options.scenario.json

@@ -0,0 +1,108 @@
+{
+  "scenarioVersion": 1,
+  "name": "options",
+  "description": "Each menu row, applied from the menu at 14:08:42 local time: seconds, the three date orders, the date hidden.",
+  "host": {
+    "zone": {
+      "offsetMinutes": 120
+    },
+    "startAt": 1784290122000
+  },
+  "steps": [
+    {
+      "menu": {
+        "id": "show-seconds",
+        "value": true
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "14:08:42",
+          "17/07/2026"
+        ],
+        "image": "seconds-dark"
+      }
+    },
+    {
+      "host": {
+        "theme": "light"
+      }
+    },
+    {
+      "expect": {
+        "image": "seconds-light"
+      }
+    },
+    {
+      "host": {
+        "theme": "dark"
+      }
+    },
+    {
+      "menu": {
+        "id": "show-seconds",
+        "value": false
+      }
+    },
+    {
+      "menu": {
+        "id": "date-format",
+        "value": "year-month-day"
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "14:08",
+          "2026-07-17"
+        ],
+        "image": "year-month-day"
+      }
+    },
+    {
+      "menu": {
+        "id": "date-format",
+        "value": "month-day-year"
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "14:08",
+          "07/17/2026"
+        ],
+        "image": "month-day-year"
+      }
+    },
+    {
+      "menu": {
+        "id": "show-date",
+        "value": false
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "14:08"
+        ],
+        "noText": [
+          "07/17/2026"
+        ],
+        "image": "time-only-dark"
+      }
+    },
+    {
+      "host": {
+        "theme": "light",
+        "scale": 1500
+      }
+    },
+    {
+      "expect": {
+        "image": "time-only-light-150",
+        "fault": "none"
+      }
+    }
+  ]
+}