@overcrow/mcp 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "types": [],
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true
+  },
+  "include": ["logic.ts"]
+}

package/dist/content/examples/clock/view.ocml

@@ -0,0 +1,8 @@
+<!-- Clock: the local time of day and, optionally, the date on a second line
+     (parity sheet: playervox-overcrow docs/builtin-parity/clock.md). -->
+<box class="clock" label={clockLabel(state.now, state.seconds, state.showDate, state.order)}>
+  <text class="time">{clockTime(state.now, state.seconds)}</text>
+  <if test={state.showDate}>
+    <text class="date">{clockDate(state.now, state.order)}</text>
+  </if>
+</box>

package/dist/content/examples/countdown/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) the authors of Countdown
+
+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/countdown/listing.json

@@ -0,0 +1,10 @@
+{
+  "author": "Example Studio",
+  "spdxLicense": "MIT",
+  "sourceUrl": "https://github.com/example/countdown-widget",
+  "defaultLocale": "en",
+  "localizations": [
+    { "locale": "en", "name": "Countdown", "description": "A countdown of a few minutes that counts the rounds you finish." },
+    { "locale": "fr", "name": "Compte à rebours", "description": "Un compte à rebours de quelques minutes, qui compte les tours terminés." }
+  ]
+}

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

@@ -0,0 +1,15 @@
+{
+  "duration": "Duration",
+  "minutes": "{count} min",
+  "pause": "Pause",
+  "remaining": "Time left",
+  "repeat": "Start again when it ends",
+  "reset-rounds": "Reset the rounds",
+  "rounds": "Rounds",
+  "rounds-drawn": "{count} finished rounds",
+  "start": "Start",
+  "state": "State",
+  "state-done": "Finished",
+  "state-paused": "Paused",
+  "state-running": "Running"
+}

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

@@ -0,0 +1,15 @@
+{
+  "duration": "Durée",
+  "minutes": "{count} min",
+  "pause": "Mettre en pause",
+  "remaining": "Temps restant",
+  "repeat": "Recommencer à la fin",
+  "reset-rounds": "Remettre les tours à zéro",
+  "rounds": "Tours",
+  "rounds-drawn": "{count} tours terminés",
+  "start": "Démarrer",
+  "state": "État",
+  "state-done": "Terminé",
+  "state-paused": "En pause",
+  "state-running": "En cours"
+}

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

@@ -0,0 +1,179 @@
+// A countdown of a few minutes. It counts the rounds the user finished,
+// keeps that count in the widget's storage and draws one dot per round.
+import {
+  draw,
+  formatDuration,
+  initState,
+  log,
+  onHost,
+  onMenu,
+  option,
+  storage,
+  t,
+  timers,
+  type DrawCommand,
+  type Timer,
+} from "@overcrow/sdk";
+
+const MINUTE = 60_000;
+/** Dots drawn at most; the count itself goes on. */
+const MAX_DOTS = 12;
+
+declare module "@overcrow/sdk" {
+  interface WidgetState {
+    durations: number[];
+    minutes: number;
+    remainingMs: number;
+    running: boolean;
+    repeat: boolean;
+    rounds: number;
+    showRounds: boolean;
+    menu: boolean;
+  }
+}
+
+const state = initState({
+  durations: [5, 15, 25, 50],
+  minutes: 25,
+  remainingMs: 25 * MINUTE,
+  running: false,
+  repeat: false,
+  rounds: 0,
+  showRounds: option("show-rounds", true),
+  menu: false,
+});
+
+export function total(minutes: number): number {
+  return minutes * MINUTE;
+}
+
+/** `24:59`, counted down to the second. */
+export function timeLeft(ms: number): string {
+  return formatDuration(Math.ceil(ms / 1000) * 1000);
+}
+
+/** The value of an `option` is text. */
+export function minutesValue(minutes: number): string {
+  return String(minutes);
+}
+
+export function ringClass(ms: number): string {
+  return ms === 0 ? "ring done" : "ring";
+}
+
+export function startLabel(running: boolean): string {
+  return t(running ? "pause" : "start");
+}
+
+export function stateText(running: boolean, ms: number): string {
+  return t(running ? "state-running" : ms === 0 ? "state-done" : "state-paused");
+}
+
+/** One dot per finished round, on the `dots` canvas. */
+function paint(): void {
+  const dots: DrawCommand[] = [];
+  for (let index = 0; index < Math.min(state.rounds, MAX_DOTS); index += 1) {
+    dots.push(["circle", 6 + index * 14, 6, 4], ["fill", "var(--color-accent)"]);
+  }
+  draw("dots", dots);
+}
+
+function setRounds(rounds: number): void {
+  state.rounds = rounds;
+  paint();
+  // Storage needs the user's consent: without it the count lasts as long
+  // as the widget runs.
+  storage.set({ key: "rounds", value: rounds }).catch(() => {});
+}
+
+let ticker: Timer | undefined;
+/** When the running countdown ends, in `Date.now()` time. */
+let endsAt = 0;
+
+function stop(): void {
+  ticker?.cancel();
+  ticker = undefined;
+  state.running = false;
+}
+
+function start(): void {
+  if (state.remainingMs === 0) {
+    state.remainingMs = total(state.minutes);
+  }
+  endsAt = Date.now() + state.remainingMs;
+  state.running = true;
+  ticker = timers.every(250, tick);
+}
+
+// A timer does not tick while the widget is hidden: the time left comes
+// from the clock, not from the number of ticks.
+function tick(): void {
+  state.remainingMs = Math.max(0, endsAt - Date.now());
+  if (state.remainingMs > 0) {
+    return;
+  }
+  stop();
+  setRounds(state.rounds + 1);
+  log.info(`round ${state.rounds} finished`);
+  if (state.repeat) {
+    start();
+  }
+}
+
+export function toggle(): void {
+  if (state.running) {
+    stop();
+  } else {
+    start();
+  }
+}
+
+export function setMinutes(event: { value: unknown }): void {
+  const minutes = Number(event.value);
+  if (state.durations.includes(minutes)) {
+    state.minutes = minutes;
+    state.remainingMs = total(minutes);
+  }
+}
+
+export function setRepeat(event: { value: unknown }): void {
+  state.repeat = event.value === true;
+}
+
+export function openMenu(): void {
+  state.menu = true;
+}
+
+export function closeMenu(): void {
+  state.menu = false;
+}
+
+export function resetRounds(): void {
+  state.menu = false;
+  setRounds(0);
+}
+
+// The `reset-rounds` row of the options menu does the same as the button
+// of the context menu.
+onMenu((row) => {
+  if (row === "reset-rounds") {
+    resetRounds();
+  }
+});
+
+onHost((changed) => {
+  if (changed.includes("options")) {
+    state.showRounds = option("show-rounds", true);
+    paint();
+  }
+});
+
+storage.get({ key: "rounds" }).then(
+  (stored) => {
+    if (typeof stored === "number" && Number.isInteger(stored) && stored > 0) {
+      state.rounds = stored;
+      paint();
+    }
+  },
+  () => {},
+);

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

@@ -0,0 +1,34 @@
+{
+  "schemaVersion": 1,
+  "apiVersion": 1,
+  "id": "com.example.countdown",
+  "version": "1.0.0",
+  "name": { "en": "Countdown", "fr": "Compte à rebours" },
+  "sizing": {
+    "fit": "none",
+    "preferred": { "width": 220, "height": 190 },
+    "min": { "width": 180, "height": 160 },
+    "max": { "width": 480, "height": 400 }
+  },
+  "permissions": {
+    "storage": true
+  },
+  "wrapper": {
+    "menu": [
+      {
+        "type": "toggle",
+        "id": "show-rounds",
+        "label": { "en": "Show finished rounds", "fr": "Afficher les tours terminés" },
+        "icon": "circle-check",
+        "default": true
+      },
+      {
+        "type": "action",
+        "id": "reset-rounds",
+        "label": { "en": "Reset the rounds", "fr": "Remettre les tours à zéro" },
+        "icon": "rotate-ccw",
+        "visibleWhen": "show-rounds"
+      }
+    ]
+  }
+}

package/dist/content/examples/countdown/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "overcrow-example-countdown",
+  "version": "1.0.0",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "check": "overcrow-widget check",
+    "package": "overcrow-widget package"
+  },
+  "devDependencies": {
+    "@overcrow/sdk": "1.0.0",
+    "typescript": "6.0.3"
+  }
+}

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

@@ -0,0 +1,94 @@
+.countdown {
+  flex-direction: column;
+  gap: var(--space-3);
+  padding: var(--space-4);
+}
+
+/* The time sits in the middle of the ring: both share one grid cell. */
+.dial {
+  display: grid;
+  grid-template-columns: 72px;
+  grid-template-rows: 72px;
+  justify-content: center;
+  justify-items: center;
+  align-items: center;
+}
+
+.ring {
+  grid-column: 1;
+  grid-row: 1;
+  width: 72px;
+  height: 72px;
+  color: var(--color-accent);
+}
+
+.ring.done {
+  color: var(--color-success);
+  animation: countdown-pulse 800ms ease-in-out 3 alternate;
+}
+
+@keyframes countdown-pulse {
+  from { opacity: 1; }
+  to { opacity: 0.4; }
+}
+
+.time {
+  grid-column: 1;
+  grid-row: 1;
+  font-family: var(--font-mono);
+  font-size: var(--font-size-body);
+  font-variant-numeric: tabular-nums;
+}
+
+.controls {
+  align-items: center;
+  gap: var(--space-2);
+}
+
+.duration {
+  flex-grow: 1;
+}
+
+.start {
+  width: var(--control-height);
+  height: var(--control-height);
+  justify-content: center;
+  align-items: center;
+  border-radius: var(--radius-md);
+  background: var(--color-surface-raised);
+  transition: background-color var(--duration-fast) ease-out;
+}
+
+.start:hover {
+  background: var(--color-surface-hover);
+}
+
+.start:focus {
+  border: 1px solid var(--color-accent);
+}
+
+.repeat:checked {
+  color: var(--color-accent);
+}
+
+.stat {
+  justify-content: space-between;
+  font-size: var(--font-size-small);
+}
+
+.stat-name {
+  color: var(--color-text-muted);
+}
+
+.dots {
+  height: 12px;
+}
+
+.menu-row {
+  padding: var(--space-2) var(--space-4);
+  border-radius: var(--radius-sm);
+}
+
+.menu-row:hover {
+  background: var(--color-surface-hover);
+}

package/dist/content/examples/countdown/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "types": [],
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true
+  },
+  "include": ["logic.ts"]
+}

package/dist/content/examples/countdown/view.ocml

@@ -0,0 +1,42 @@
+<!-- A countdown: a ring that empties, a duration chosen in a list, and the
+     finished rounds drawn as dots. A right click opens a small menu. -->
+<component name="stat" props="name value">
+  <box class="stat">
+    <text class="stat-name">{name}</text>
+    <text class="stat-value">{value}</text>
+  </box>
+</component>
+
+<box ref="panel" class="countdown" on:contextmenu={openMenu}>
+  <box class="dial">
+    <gauge class={ringClass(state.remainingMs)} value={state.remainingMs} max={total(state.minutes)} label={t("remaining")}/>
+    <text class="time">{timeLeft(state.remainingMs)}</text>
+  </box>
+  <box class="controls">
+    <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>
+    <button class="start" label={startLabel(state.running)} on:activate={toggle}>
+      <if test={state.running}>
+        <icon name="pause"/>
+      </if>
+      <else>
+        <icon name="play"/>
+      </else>
+    </button>
+    <toggle class="repeat" label={t("repeat")} tooltip={t("repeat")} checked={state.repeat} on:change={setRepeat}/>
+  </box>
+  <stat name={t("state")} value={stateText(state.running, state.remainingMs)}/>
+  <if test={state.showRounds}>
+    <stat name={t("rounds")} value={state.rounds}/>
+    <canvas ref="dots" class="dots" label={t("rounds-drawn", { count: state.rounds })}/>
+  </if>
+</box>
+
+<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>

package/dist/content/examples/fps/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/fps/README.md

@@ -0,0 +1,64 @@
+# FPS
+
+`com.playervox.overcrow.fps` — the frame rate the game presents, observed
+from outside the game. 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 |
+| --- | --- |
+| A reading | `144  FPS` (the unit muted, 12 px semibold) |
+| A gap of the capture | the last reading, exactly as it was |
+| No reading yet | `—  FPS`, muted |
+| Label off | the value alone |
+
+Hovering the widget in Interactive mode shows one sentence, the
+measurement status's (`ready`, `waiting`, `unsupported`,
+`permission_denied`, `ambiguous`, `events_lost`, `unavailable`).
+
+## Menu
+
+| Row | Type | Default |
+| --- | --- | --- |
+| Show “FPS” label / Afficher le libellé « FPS » | toggle `show-label` | on |
+
+## Permissions
+
+`fps.read` (not sensitive), and `requires: ["fps"]`: on a machine without a
+frame-rate source OverCrow neither starts nor shows the widget, and keeps
+its place for when the source comes back.
+
+## How it works
+
+`fps.subscribe` gives `{ fps, stale, status }`; the host keeps the last
+value of the game through a gap of its capture until the next one, so the
+widget runs no timer and shows the value as it is: a value shown never
+disappears and shows no sign of its age (`stale` is not drawn). The
+accessible label is "144 frames per second" or "Frame rate unavailable".
+
+## Tests
+
+- `tests/logic.test.mjs`: the logic on `@overcrow/sdk/testing` (value,
+  colour, sentences, labels, updates, the label row).
+- Scenarios with their reference images: `render` (both themes and
+  languages at 100 and 150 %), `stale` (a reading kept through a gap looks
+  unchanged), `unavailable` (the statuses, the
+  service stopping), `label`, `refused`.
+
+## 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) |
+| --- | --- | --- |
+| Widget start, warm, into the overlay's runtime | 7 ms at most | — |
+| VM memory | 0.55–0.59 MiB anonymous | similar to the Clock's 0.83 MiB private working set |
+| VM CPU | one short turn per new reading | — |
+| Overlay frames | one per new reading | — |
+
+With the Clock and Session widgets beside it, the overlay's process grows
+by about 2 MB per widget and stays at 0.15 % of one core with a reading
+each second; nothing runs while the overlay is hidden.

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

@@ -0,0 +1,19 @@
+{
+  "author": "PlayerVox",
+  "spdxLicense": "MIT",
+  "sourceUrl": "https://github.com/Valhallab/playervox-overcrow-releases/tree/main/widgets/fps",
+  "preview": "assets/preview.png",
+  "defaultLocale": "en",
+  "localizations": [
+    {
+      "locale": "en",
+      "name": "FPS",
+      "description": "Shows the game’s presented frame rate, when the host has a frame rate source."
+    },
+    {
+      "locale": "fr",
+      "name": "FPS",
+      "description": "Affiche la fréquence d’images présentée par le jeu, quand l’hôte dispose d’une source."
+    }
+  ]
+}

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

@@ -0,0 +1,11 @@
+{
+  "label": "{fps} frames per second",
+  "label-none": "Frame rate unavailable",
+  "hint-ready": "Frames the game presented, observed from outside the game: its presentation rate, not the refresh rate of the display.",
+  "hint-waiting": "Waiting for frames from the game window. A paused game keeps this value unavailable.",
+  "hint-unsupported": "The frame rate of this game window cannot be measured on this system.",
+  "hint-permission_denied": "OverCrow was denied access to the game's frame events.",
+  "hint-ambiguous": "Several presentation sources prevent a reliable FPS measurement.",
+  "hint-events_lost": "Frame events were lost. No reliable FPS measurement is available.",
+  "hint-unavailable": "FPS capture is not available. See Diagnostics in the Control Center."
+}

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

@@ -0,0 +1,11 @@
+{
+  "label": "{fps} images par seconde",
+  "label-none": "FPS indisponibles",
+  "hint-ready": "Images présentées par le jeu, observées de l’extérieur du jeu : son rythme de présentation, pas la fréquence de l’écran.",
+  "hint-waiting": "En attente d’images de la fenêtre de jeu. Un jeu en pause laisse cette valeur indisponible.",
+  "hint-unsupported": "Les FPS de cette fenêtre de jeu ne peuvent pas être mesurés sur ce système.",
+  "hint-permission_denied": "OverCrow s’est vu refuser l’accès aux événements d’image du jeu.",
+  "hint-ambiguous": "Plusieurs sources de présentation empêchent une mesure fiable des FPS.",
+  "hint-events_lost": "Des événements d’image ont été perdus. Aucune mesure fiable des FPS n’est disponible.",
+  "hint-unavailable": "La capture FPS n’est pas disponible. Ouvrez Diagnostic dans le Centre de contrôle."
+}

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

@@ -0,0 +1,64 @@
+// FPS: the game's presented frame rate. The host measures it outside the
+// game and keeps the last value through a gap until the next one; the
+// widget shows it as it is, with no sign of its age (a value shown never
+// disappears or changes look while the game runs), and a sentence for each
+// measurement status.
+import { fps, hasGrant, initState, onHost, option, t, type Fps } from "@overcrow/sdk";
+
+type Status = Fps["status"];
+
+declare module "@overcrow/sdk" {
+  interface WidgetState {
+    fps: number | null;
+    status: Status;
+    showLabel: boolean;
+  }
+}
+
+const state = initState({
+  fps: null as number | null,
+  status: "waiting" as Status,
+  showLabel: option("show-label", true),
+});
+
+/** The integer value, or an em dash without one. */
+export function fpsValue(value: number | null): string {
+  return value === null ? "—" : String(Math.round(value));
+}
+
+/** A value is primary, fresh or kept through a gap; no value is muted. */
+export function valueClass(value: number | null): string {
+  return value === null ? "value muted" : "value";
+}
+
+export function fpsLabel(value: number | null): string {
+  return value === null ? t("label-none") : t("label", { fps: fpsValue(value) });
+}
+
+/** The hover sentence of the measurement status. */
+export function fpsTooltip(status: Status): string {
+  return t(`hint-${status}`);
+}
+
+/** The state an update, or a failure of the subscription, leaves. */
+export function reading(
+  update: { ok: true; value: Fps } | { ok: false },
+): Pick<Fps, "fps" | "status"> {
+  return update.ok
+    ? { fps: update.value.fps, status: update.value.status }
+    : { fps: null, status: "unavailable" };
+}
+
+onHost((changed) => {
+  if (changed.includes("options")) {
+    state.showLabel = option("show-label", true);
+  }
+});
+
+if (hasGrant("fps.read")) {
+  fps.subscribe((update) => {
+    Object.assign(state, reading(update));
+  });
+} else {
+  state.status = "unavailable";
+}