@overcrow/mcp 0.0.0 → 0.1.0

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/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"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,96 @@
+{
+  "scenarioVersion": 1,
+  "name": "render",
+  "description": "A fresh reading of 144 with the unit, in both themes, both languages, at 100 % and 150 %.",
+  "fixtures": {
+    "subscriptions": {
+      "fps.subscribe": {
+        "fps": 144,
+        "stale": false,
+        "status": "ready"
+      }
+    }
+  },
+  "steps": [
+    {
+      "expect": {
+        "state": "running",
+        "text": [
+          "144"
+        ],
+        "image": "fresh-dark-en-100"
+      }
+    },
+    {
+      "host": {
+        "theme": "light"
+      }
+    },
+    {
+      "expect": {
+        "image": "fresh-light-en-100"
+      }
+    },
+    {
+      "host": {
+        "locale": "fr"
+      }
+    },
+    {
+      "expect": {
+        "image": "fresh-light-fr-100"
+      }
+    },
+    {
+      "host": {
+        "theme": "dark"
+      }
+    },
+    {
+      "expect": {
+        "image": "fresh-dark-fr-100"
+      }
+    },
+    {
+      "host": {
+        "scale": 1500
+      }
+    },
+    {
+      "expect": {
+        "image": "fresh-dark-fr-150"
+      }
+    },
+    {
+      "host": {
+        "theme": "light"
+      }
+    },
+    {
+      "expect": {
+        "image": "fresh-light-fr-150"
+      }
+    },
+    {
+      "host": {
+        "locale": "en"
+      }
+    },
+    {
+      "expect": {
+        "image": "fresh-light-en-150"
+      }
+    },
+    {
+      "host": {
+        "theme": "dark"
+      }
+    },
+    {
+      "expect": {
+        "image": "fresh-dark-en-150",
+        "fault": "none"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,91 @@
+{
+  "scenarioVersion": 1,
+  "name": "stale",
+  "description": "The host keeps the reading through a gap of its capture and marks it stale: the number stays exactly as it was, with no sign of its age; a new sample replaces it.",
+  "fixtures": {
+    "subscriptions": {
+      "fps.subscribe": {
+        "fps": 144,
+        "stale": false,
+        "status": "ready"
+      }
+    }
+  },
+  "steps": [
+    {
+      "publish": {
+        "service": "fps.subscribe",
+        "value": {
+          "fps": 144,
+          "stale": true,
+          "status": "ready"
+        }
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "144"
+        ],
+        "image": "kept-dark-en",
+        "noText": [
+          "old",
+          "ancien"
+        ]
+      }
+    },
+    {
+      "host": {
+        "theme": "light"
+      }
+    },
+    {
+      "expect": {
+        "image": "kept-light-en"
+      }
+    },
+    {
+      "host": {
+        "locale": "fr",
+        "theme": "dark"
+      }
+    },
+    {
+      "expect": {
+        "image": "kept-dark-fr"
+      }
+    },
+    {
+      "host": {
+        "scale": 1500,
+        "theme": "light"
+      }
+    },
+    {
+      "expect": {
+        "image": "kept-light-fr-150"
+      }
+    },
+    {
+      "publish": {
+        "service": "fps.subscribe",
+        "value": {
+          "fps": 60,
+          "stale": false,
+          "status": "ready"
+        }
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "60"
+        ],
+        "noText": [
+          "144"
+        ],
+        "fault": "none"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,111 @@
+{
+  "scenarioVersion": 1,
+  "name": "unavailable",
+  "description": "No value: an em dash, muted, for each status without a reading, including the service stopping mid-session (W.2).",
+  "fixtures": {
+    "subscriptions": {
+      "fps.subscribe": {
+        "fps": null,
+        "stale": false,
+        "status": "waiting"
+      }
+    }
+  },
+  "steps": [
+    {
+      "expect": {
+        "text": [
+          "—"
+        ],
+        "image": "none-dark"
+      }
+    },
+    {
+      "host": {
+        "theme": "light"
+      }
+    },
+    {
+      "expect": {
+        "image": "none-light"
+      }
+    },
+    {
+      "host": {
+        "theme": "dark"
+      }
+    },
+    {
+      "publish": {
+        "service": "fps.subscribe",
+        "value": {
+          "fps": 33,
+          "stale": false,
+          "status": "ready"
+        }
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "33"
+        ]
+      }
+    },
+    {
+      "publish": {
+        "service": "fps.subscribe",
+        "value": {
+          "fps": null,
+          "stale": false,
+          "status": "unavailable"
+        }
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "—"
+        ],
+        "noText": [
+          "33"
+        ]
+      }
+    },
+    {
+      "publish": {
+        "service": "fps.subscribe",
+        "value": {
+          "fps": null,
+          "stale": false,
+          "status": "unsupported"
+        }
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "—"
+        ]
+      }
+    },
+    {
+      "publish": {
+        "service": "fps.subscribe",
+        "value": {
+          "fps": null,
+          "stale": false,
+          "status": "ambiguous"
+        }
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "—"
+        ],
+        "fault": "none"
+      }
+    }
+  ]
+}

package/dist/content/examples/fps/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/fps/view.ocml

@@ -0,0 +1,11 @@
+<!-- FPS: the game's presented frame rate, observed from outside the game
+     (parity sheet: playervox-overcrow docs/builtin-parity/fps.md). One text
+     keeps the value and the unit on one baseline. -->
+<box class="fps" label={fpsLabel(state.fps)} tooltip={fpsTooltip(state.status)}>
+  <text class="line">
+    <span class={valueClass(state.fps)}>{fpsValue(state.fps)}</span>
+    <if test={state.showLabel}>
+      <span class="small">&nbsp;&nbsp;FPS</span>
+    </if>
+  </text>
+</box>

package/dist/content/examples/media/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.