@overcrow/mcp 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,210 @@
+// Performance: the attached game's CPU share and resident memory, the host's
+// CPU and GPU temperatures and the game's frame rate. A row shows when its
+// menu toggle is on and the host has a reading; nothing is ever shown as
+// "—". The host normalizes the CPU share, drops the rows of the sensors it
+// lacks from the menu (`requires`) and keeps each reading through a gap of
+// its source: the widget only formats, colours and lays out.
+import {
+  formatNumber,
+  fps,
+  hasGrant,
+  initState,
+  onHost,
+  option,
+  t,
+  telemetry,
+  type Subscription,
+  type Telemetry,
+} from "@overcrow/sdk";
+
+/** The menu values the rows depend on. */
+export interface Shown {
+  cpu: boolean;
+  ram: boolean;
+  cpuTemperature: boolean;
+  gpuTemperature: boolean;
+  fps: boolean;
+  fahrenheit: boolean;
+}
+
+/** The frame rate part the rows use. The host keeps a value through a gap
+ * of its capture and marks it `stale`; the row shows it as it is: a value
+ * shown never disappears and shows no sign of its age. */
+export interface Rate {
+  fps: number | null;
+  stale: boolean;
+}
+
+/** One metric as the view draws it. */
+export interface Row {
+  key: string;
+  label: string;
+  value: string;
+  /** `value`, `value warning` or `value critical`. */
+  valueClass: string;
+  /** The unit after a thin space, or nothing. */
+  unit: string;
+  hint: string;
+  /** The accessible name, which also tells the two "CPU" rows apart. */
+  name: string;
+  /** The first row has no separator in the horizontal layout. */
+  first: boolean;
+}
+
+declare module "@overcrow/sdk" {
+  interface WidgetState {
+    telemetry: Telemetry | null;
+    rate: Rate | null;
+    layout: string;
+    shown: Shown;
+  }
+}
+
+/** Binary gigabytes, as Windows Task Manager counts memory. */
+const GIGABYTE = 1024 ** 3;
+const CPU_WARNING = 80;
+const CPU_CRITICAL = 95;
+/** Temperature thresholds, compared in °C whatever the unit shown. */
+const TEMPERATURE_WARNING = 80;
+const TEMPERATURE_CRITICAL = 90;
+
+const ONE_DECIMAL = { minimumFractionDigits: 1, maximumFractionDigits: 1 } as const;
+
+function shown(): Shown {
+  return {
+    cpu: option("show-cpu", true),
+    ram: option("show-ram", true),
+    cpuTemperature: option("show-cpu-temperature", true),
+    gpuTemperature: option("show-gpu-temperature", true),
+    fps: option("show-fps", true),
+    fahrenheit: option("temperature-unit", "celsius") === "fahrenheit",
+  };
+}
+
+const state = initState({
+  telemetry: null as Telemetry | null,
+  rate: null as Rate | null,
+  layout: option("layout", "vertical"),
+  shown: shown(),
+});
+
+/** The colour class of a value past its warning or critical threshold. */
+export function severity(value: number, warning: number, critical: number): string {
+  if (value >= critical) {
+    return "value critical";
+  }
+  return value >= warning ? "value warning" : "value";
+}
+
+/** A temperature in the chosen unit, converted before rounding. */
+export function temperature(celsius: number, fahrenheit: boolean): { value: string; unit: string } {
+  return fahrenheit
+    ? { value: formatNumber(celsius * 1.8 + 32, ONE_DECIMAL), unit: "°F" }
+    : { value: formatNumber(celsius, ONE_DECIMAL), unit: "°C" };
+}
+
+/** A unit keeps a thin space from its number, as the built-in's 2 px gap. */
+const spaced = (unit: string): string => (unit === "" ? "" : `\u2009${unit}`);
+
+/** The rows to draw, in the fixed order CPU, RAM, CPU and GPU temperatures, FPS. */
+export function rows(sample: Telemetry | null, rate: Rate | null, show: Shown): Row[] {
+  const list: Omit<Row, "first">[] = [];
+  const metric = (key: string, value: string, unit: string, valueClass: string): void => {
+    list.push({
+      key,
+      label: t(key),
+      value,
+      valueClass,
+      unit: spaced(unit),
+      hint: t(`hint-${key}`),
+      name: t(`name-${key}`, { value, unit }),
+    });
+  };
+  if (show.cpu && sample?.cpu != null) {
+    metric("cpu", formatNumber(sample.cpu, ONE_DECIMAL), "%", severity(sample.cpu, CPU_WARNING, CPU_CRITICAL));
+  }
+  if (show.ram && sample?.ram != null) {
+    metric("ram", formatNumber(sample.ram / GIGABYTE, ONE_DECIMAL), "GB", "value");
+  }
+  for (const key of ["cpu-temperature", "gpu-temperature"] as const) {
+    const celsius = key === "cpu-temperature" ? sample?.cpuTemperature : sample?.gpuTemperature;
+    const wanted = key === "cpu-temperature" ? show.cpuTemperature : show.gpuTemperature;
+    if (wanted && celsius != null) {
+      const { value, unit } = temperature(celsius, show.fahrenheit);
+      metric(key, value, unit, severity(celsius, TEMPERATURE_WARNING, TEMPERATURE_CRITICAL));
+    }
+  }
+  if (show.fps && rate !== null && rate.fps !== null) {
+    const value = formatNumber(Math.round(rate.fps), { maximumFractionDigits: 0 });
+    list.push({
+      key: "fps",
+      label: t("fps"),
+      value,
+      valueClass: "value",
+      unit: "",
+      hint: t("hint-fps"),
+      name: t("name-fps", { value }),
+    });
+  }
+  return list.map((row, index) => ({ ...row, first: index === 0 }));
+}
+
+/** Why no row shows: every metric switched off, or no reading yet. */
+export function emptyMessage(show: Shown): string {
+  const any = show.cpu || show.ram || show.cpuTemperature || show.gpuTemperature || show.fps;
+  return t(any ? "waiting" : "no-metric");
+}
+
+export function rootClass(layout: string): string {
+  return layout === "horizontal" ? "performance horizontal" : "performance vertical";
+}
+
+/** The telemetry an update leaves: none after a failure. */
+export function sampleOf(update: { ok: true; value: Telemetry | null } | { ok: false }): Telemetry | null {
+  return update.ok ? update.value : null;
+}
+
+/** The frame rate an update leaves: none after a failure. */
+export function rateOf(
+  update: { ok: true; value: { fps: number | null; stale: boolean } } | { ok: false },
+): Rate | null {
+  return update.ok ? { fps: update.value.fps, stale: update.value.stale } : null;
+}
+
+// The host measures the frame rate only while a widget subscribes to it:
+// the subscription follows the FPS row's toggle, so no capture runs for a
+// hidden row.
+const canReadFps = hasGrant("fps.read");
+let rateSubscription: Subscription | null = null;
+
+function followFpsToggle(): void {
+  const wanted = canReadFps && state.shown.fps;
+  if (wanted && rateSubscription === null) {
+    rateSubscription = fps.subscribe((update) => {
+      state.rate = rateOf(update);
+      if (!update.ok) {
+        // The subscription ended: switching the row off and on retries.
+        rateSubscription = null;
+      }
+    });
+  } else if (!wanted && rateSubscription !== null) {
+    rateSubscription.cancel();
+    rateSubscription = null;
+    state.rate = null;
+  }
+}
+
+onHost((changed) => {
+  if (changed.includes("options")) {
+    state.layout = option("layout", "vertical");
+    state.shown = shown();
+    followFpsToggle();
+  }
+});
+
+if (hasGrant("telemetry.read")) {
+  telemetry.subscribe((update) => {
+    state.telemetry = sampleOf(update);
+  });
+}
+followFpsToggle();

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

@@ -0,0 +1,83 @@
+{
+  "schemaVersion": 1,
+  "apiVersion": 1,
+  "id": "com.playervox.overcrow.performance",
+  "version": "1.0.2",
+  "name": {
+    "en": "Performance",
+    "fr": "Performances"
+  },
+  "sizing": {
+    "fit": "both",
+    "preferred": { "width": 180, "height": 150 },
+    "min": { "width": 24, "height": 24 },
+    "max": { "width": 800, "height": 400 }
+  },
+  "permissions": {
+    "capabilities": ["telemetry.read", "fps.read"]
+  },
+  "wrapper": {
+    "menu": [
+      {
+        "type": "choice",
+        "id": "layout",
+        "label": { "en": "Layout", "fr": "Disposition" },
+        "choices": [
+          { "value": "vertical", "label": { "en": "Vertical", "fr": "Verticale" } },
+          { "value": "horizontal", "label": { "en": "Horizontal", "fr": "Horizontale" } }
+        ],
+        "default": "vertical"
+      },
+      {
+        "type": "group",
+        "id": "shown-values",
+        "label": { "en": "Shown values", "fr": "Valeurs affichées" },
+        "rows": [
+          {
+            "type": "toggle",
+            "id": "show-cpu",
+            "label": { "en": "CPU", "fr": "CPU" },
+            "default": true
+          },
+          {
+            "type": "toggle",
+            "id": "show-ram",
+            "label": { "en": "RAM", "fr": "RAM" },
+            "default": true
+          },
+          {
+            "type": "toggle",
+            "id": "show-cpu-temperature",
+            "label": { "en": "CPU temperature", "fr": "Température CPU" },
+            "requires": "telemetry.cpuTemperature",
+            "default": true
+          },
+          {
+            "type": "toggle",
+            "id": "show-gpu-temperature",
+            "label": { "en": "GPU temperature", "fr": "Température GPU" },
+            "requires": "telemetry.gpuTemperature",
+            "default": true
+          },
+          {
+            "type": "toggle",
+            "id": "show-fps",
+            "label": { "en": "FPS", "fr": "FPS" },
+            "requires": "fps",
+            "default": true
+          }
+        ]
+      },
+      {
+        "type": "choice",
+        "id": "temperature-unit",
+        "label": { "en": "Temperature", "fr": "Température" },
+        "choices": [
+          { "value": "celsius", "label": { "en": "Celsius (°C)", "fr": "Celsius (°C)" } },
+          { "value": "fahrenheit", "label": { "en": "Fahrenheit (°F)", "fr": "Fahrenheit (°F)" } }
+        ],
+        "default": "celsius"
+      }
+    ]
+  }
+}

package/dist/content/examples/performance/package.json

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

@@ -0,0 +1,75 @@
+/* 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. Labels are uppercase
+   captions, values the UI font with tabular figures, coloured past their
+   thresholds; units stay muted. */
+.performance {
+  padding: 0 2px;
+}
+
+/* Vertical: a label column as wide as the widest label, then the values,
+   each row on one baseline; with the wrapper's 8 px, the built-in's
+   16 × 11 px margin (its 6 px inner margin and 3 px above and below each
+   row). */
+.vertical {
+  display: grid;
+  grid-template-columns: max-content max-content;
+  column-gap: 12px;
+  row-gap: 6px;
+  align-items: baseline;
+  padding: 3px 8px;
+}
+
+/* Horizontal: one line of label, value and unit, separated by a dot. */
+.horizontal {
+  flex-direction: row;
+  align-items: baseline;
+}
+
+.horizontal .label {
+  margin-right: 4px;
+}
+
+.label {
+  font-family: var(--font-ui);
+  font-size: var(--font-size-caption);
+  font-weight: 600;
+  letter-spacing: 0.4px;
+  color: var(--color-text-muted);
+  white-space: nowrap;
+}
+
+.value {
+  font-family: var(--font-ui);
+  font-size: var(--font-size-button);
+  font-variant-numeric: tabular-nums;
+  color: var(--color-text);
+  white-space: nowrap;
+}
+
+.value.warning {
+  color: var(--color-warning);
+}
+
+.value.critical {
+  color: var(--color-danger);
+}
+
+.unit {
+  font-size: var(--font-size-small);
+  font-weight: 600;
+  color: var(--color-text-muted);
+}
+
+.separator {
+  font-family: var(--font-ui);
+  font-size: var(--font-size-small);
+  color: var(--color-text-subtle);
+  margin: 0 5px;
+}
+
+.empty {
+  font-family: var(--font-ui);
+  font-size: var(--font-size-small);
+  color: var(--color-text-muted);
+  white-space: nowrap;
+}

package/dist/content/examples/performance/tests/fahrenheit.scenario.json

@@ -0,0 +1,110 @@
+{
+  "scenarioVersion": 1,
+  "name": "fahrenheit",
+  "description": "°F converts the sensor's reading before rounding to one decimal: 0 → 32.0, 62.345 → 62.3 °C / 144.2 °F, 37.677 → 37.7 / 99.8, −12.678 → −12.7 / 9.2.",
+  "fixtures": {
+    "subscriptions": {
+      "telemetry.subscribe": {
+        "cpu": 23.0,
+        "ram": 3221225472,
+        "cpuTemperature": 61.0,
+        "gpuTemperature": 67.0,
+        "sources": {
+          "cpuTemperature": true,
+          "gpuTemperature": true
+        }
+      },
+      "fps.subscribe": {
+        "fps": 144,
+        "stale": false,
+        "status": "ready"
+      }
+    }
+  },
+  "steps": [
+    {
+      "publish": {
+        "service": "telemetry.subscribe",
+        "value": {
+          "cpu": 23.0,
+          "ram": 3221225472,
+          "cpuTemperature": 62.345,
+          "gpuTemperature": 37.677,
+          "sources": {
+            "cpuTemperature": true,
+            "gpuTemperature": true
+          }
+        }
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "62.3",
+          "37.7"
+        ]
+      }
+    },
+    {
+      "menu": {
+        "id": "temperature-unit",
+        "value": "fahrenheit"
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "144.2",
+          "99.8"
+        ],
+        "noText": [
+          "144.1",
+          "99.9"
+        ],
+        "image": "fahrenheit-dark-en"
+      }
+    },
+    {
+      "publish": {
+        "service": "telemetry.subscribe",
+        "value": {
+          "cpu": 23.0,
+          "ram": 3221225472,
+          "cpuTemperature": -12.678,
+          "gpuTemperature": 0,
+          "sources": {
+            "cpuTemperature": true,
+            "gpuTemperature": true
+          }
+        }
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "9.2",
+          "32.0"
+        ],
+        "noText": [
+          "9.1"
+        ]
+      }
+    },
+    {
+      "menu": {
+        "id": "temperature-unit",
+        "value": "celsius"
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "-12.7",
+          "0.0"
+        ],
+        "image": "celsius-negative-dark-en",
+        "fault": "none"
+      }
+    }
+  ]
+}

package/dist/content/examples/performance/tests/horizontal.scenario.json

@@ -0,0 +1,96 @@
+{
+  "scenarioVersion": 1,
+  "name": "horizontal",
+  "description": "The one-line layout: label, value and unit per metric, a dot between them, on one baseline; both themes and languages, 100 % and 150 %.",
+  "host": {
+    "options": {
+      "layout": "horizontal"
+    }
+  },
+  "fixtures": {
+    "subscriptions": {
+      "telemetry.subscribe": {
+        "cpu": 23.0,
+        "ram": 3221225472,
+        "cpuTemperature": 61.0,
+        "gpuTemperature": 67.0,
+        "sources": {
+          "cpuTemperature": true,
+          "gpuTemperature": true
+        }
+      },
+      "fps.subscribe": {
+        "fps": 144,
+        "stale": false,
+        "status": "ready"
+      }
+    }
+  },
+  "steps": [
+    {
+      "expect": {
+        "text": [
+          "CPU",
+          "23.0",
+          "·",
+          "144"
+        ],
+        "image": "line-dark-en-100"
+      }
+    },
+    {
+      "host": {
+        "theme": "light",
+        "locale": "fr"
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "CPU°"
+        ],
+        "image": "line-light-fr-100"
+      }
+    },
+    {
+      "host": {
+        "scale": 1500
+      }
+    },
+    {
+      "expect": {
+        "image": "line-light-fr-150"
+      }
+    },
+    {
+      "host": {
+        "theme": "dark",
+        "locale": "en"
+      }
+    },
+    {
+      "expect": {
+        "image": "line-dark-en-150"
+      }
+    },
+    {
+      "publish": {
+        "service": "fps.subscribe",
+        "value": {
+          "fps": 144,
+          "stale": true,
+          "status": "ready"
+        }
+      }
+    },
+    {
+      "expect": {
+        "image": "line-kept-dark-en-150",
+        "fault": "none",
+        "noText": [
+          " old"
+        ]
+      }
+    }
+  ]
+}

package/dist/content/examples/performance/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);
+}