@overcrow/mcp 0.0.0 → 0.1.1

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";
+}

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

@@ -0,0 +1,30 @@
+{
+  "schemaVersion": 1,
+  "apiVersion": 1,
+  "id": "com.playervox.overcrow.fps",
+  "version": "1.0.3",
+  "name": {
+    "en": "FPS",
+    "fr": "FPS"
+  },
+  "sizing": {
+    "fit": "both",
+    "preferred": { "width": 110, "height": 44 },
+    "min": { "width": 40, "height": 24 },
+    "max": { "width": 480, "height": 240 }
+  },
+  "requires": ["fps"],
+  "permissions": {
+    "capabilities": ["fps.read"]
+  },
+  "wrapper": {
+    "menu": [
+      {
+        "type": "toggle",
+        "id": "show-label",
+        "label": { "en": "Show “FPS” label", "fr": "Afficher le libellé « FPS »" },
+        "default": true
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,16 @@
+{
+  "name": "overcrow-widget-fps",
+  "version": "1.0.3",
+  "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/fps/style.ocss

@@ -0,0 +1,31 @@
+/* One line; 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. */
+.fps {
+  flex-direction: column;
+  align-items: start;
+  padding: 0 2px;
+}
+
+.line {
+  font-family: var(--font-ui);
+  font-variant-numeric: tabular-nums;
+  color: var(--color-text-muted);
+  white-space: nowrap;
+}
+
+/* A value is primary; no value is muted. */
+.value {
+  font-size: var(--font-size-value);
+  color: var(--color-text);
+}
+
+.value.muted {
+  color: var(--color-text-muted);
+}
+
+/* The unit: 12 px semibold, between the small and button sizes, as the
+   built-in drew it. */
+.small {
+  font-size: 12px;
+  font-weight: 600;
+}

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

@@ -0,0 +1,8 @@
+{
+  "justifications": [
+    {
+      "permission": "capability:fps.read",
+      "text": "Reads the game's presented frame rate from OverCrow, to show it in the widget."
+    }
+  ]
+}

package/dist/content/examples/fps/tests/label.scenario.json

@@ -0,0 +1,63 @@
+{
+  "scenarioVersion": 1,
+  "name": "label",
+  "description": "The “Show FPS label” menu row: the value alone, fresh and kept through a gap (unchanged), then the unit back.",
+  "fixtures": {
+    "subscriptions": {
+      "fps.subscribe": {
+        "fps": 144,
+        "stale": false,
+        "status": "ready"
+      }
+    }
+  },
+  "steps": [
+    {
+      "menu": {
+        "id": "show-label",
+        "value": false
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "144"
+        ],
+        "noText": [
+          "  FPS"
+        ],
+        "image": "value-only"
+      }
+    },
+    {
+      "publish": {
+        "service": "fps.subscribe",
+        "value": {
+          "fps": 144,
+          "stale": true,
+          "status": "ready"
+        }
+      }
+    },
+    {
+      "expect": {
+        "image": "value-only-kept"
+      }
+    },
+    {
+      "menu": {
+        "id": "show-label",
+        "value": true
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "  FPS"
+        ],
+        "image": "kept-with-label",
+        "fault": "none"
+      }
+    }
+  ]
+}

package/dist/content/examples/fps/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/fps/tests/logic.test.mjs

@@ -0,0 +1,60 @@
+// Unit tests of the FPS widget's logic on @overcrow/sdk/testing.
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { installRuntime } from "@overcrow/sdk/testing";
+
+import { loadLogic } from "./load-logic.mjs";
+
+const MESSAGES = {"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."};
+const STATUSES = ["ready", "waiting", "unsupported", "permission_denied", "ambiguous", "events_lost", "unavailable"];
+
+const vm = installRuntime({ host: { grants: ["fps.read"], messages: MESSAGES } });
+const logic = await loadLogic();
+const { state } = await import("@overcrow/sdk");
+
+test("it subscribes once and waits for a first reading", () => {
+  assert.deepEqual(vm.subscriptions.map(({ service }) => service), ["fps.subscribe"]);
+  assert.deepEqual(
+    { fps: state.fps, status: state.status, showLabel: state.showLabel },
+    { fps: null, status: "waiting", showLabel: true },
+  );
+  assert.equal(vm.timers.length, 0, "the host keeps a reading through a gap: no timer");
+});
+
+test("value and colour: a value kept through a gap looks as it did", () => {
+  assert.equal(logic.fpsValue(null), "—");
+  assert.equal(logic.fpsValue(144), "144");
+  assert.equal(logic.valueClass(144), "value");
+  assert.equal(logic.valueClass(null), "value muted");
+});
+
+test("each status has its own sentence", () => {
+  const sentences = STATUSES.map((status) => logic.fpsTooltip(status));
+  assert.equal(new Set(sentences).size, STATUSES.length);
+  assert.ok(sentences.every((sentence) => !sentence.startsWith("hint-")), "every key exists");
+  assert.equal(logic.fpsTooltip("ready"), MESSAGES["hint-ready"]);
+});
+
+test("accessible labels", () => {
+  assert.equal(logic.fpsLabel(144), "144 frames per second");
+  assert.equal(logic.fpsLabel(null), "Frame rate unavailable");
+});
+
+test("updates, a reading kept through a gap and the end of the subscription", () => {
+  vm.push("fps.subscribe", { fps: 144, stale: false, status: "ready" });
+  assert.deepEqual([state.fps, state.status], [144, "ready"]);
+  // The host keeps the value through a gap, marked stale: nothing changes.
+  vm.push("fps.subscribe", { fps: 144, stale: true, status: "ready" });
+  assert.deepEqual([state.fps, state.status], [144, "ready"]);
+  vm.push("fps.subscribe", { fps: null, stale: false, status: "unavailable" });
+  assert.deepEqual([state.fps, state.status], [null, "unavailable"], "the service stopped (W.2)");
+  vm.fail("fps.subscribe", "permission_denied");
+  assert.deepEqual([state.fps, state.status], [null, "unavailable"]);
+});
+
+test("the label row applies at once", () => {
+  vm.setHost({ options: { "show-label": false } });
+  assert.equal(state.showLabel, false);
+  vm.setHost({ options: {} });
+  assert.equal(state.showLabel, true);
+});

package/dist/content/examples/fps/tests/preview.scenario.json

@@ -0,0 +1,29 @@
+{
+  "scenarioVersion": 1,
+  "name": "preview",
+  "description": "A fresh reading of 144 frames per second. The marketplace preview: dark theme, English, 150 %, on the stage colour; scripts/compose-previews.mjs frames it into assets/preview.png.",
+  "host": {
+    "scale": 1500,
+    "background": "#1e242e"
+  },
+  "fixtures": {
+    "subscriptions": {
+      "fps.subscribe": {
+        "fps": 144,
+        "stale": false,
+        "status": "ready"
+      }
+    }
+  },
+  "steps": [
+    {
+      "expect": {
+        "state": "running",
+        "text": [
+          "144"
+        ],
+        "image": "preview"
+      }
+    }
+  ]
+}

package/dist/content/examples/fps/tests/refused.scenario.json

@@ -0,0 +1,20 @@
+{
+  "scenarioVersion": 1,
+  "name": "refused",
+  "description": "Without the fps.read grant the widget asks nothing and shows no value.",
+  "host": {
+    "grants": []
+  },
+  "steps": [
+    {
+      "expect": {
+        "state": "running",
+        "text": [
+          "—"
+        ],
+        "calls": [],
+        "fault": "none"
+      }
+    }
+  ]
+}