@overcrow/mcp 0.0.0 → 0.1.1

package/dist/content/examples/playervox-score/tests/unavailable.scenario.json

@@ -0,0 +1,84 @@
+{
+  "scenarioVersion": 1,
+  "name": "unavailable",
+  "description": "The host's score source fails: the subscription ends with unavailable, the widget shows it, subscribes again 5 s later and shows the score the restarted source reports.",
+  "fixtures": {
+    "subscriptions": {
+      "playervox.score.subscribe": {
+        "state": "ready",
+        "name": "Portal 2",
+        "score": 94.2,
+        "grade": "S+",
+        "ratingsCount": 1284,
+        "criteria": {
+          "gameplay": 97.4,
+          "art": 90.1,
+          "tech": 94.6
+        }
+      }
+    }
+  },
+  "steps": [
+    {
+      "expect": {
+        "text": [
+          "Portal 2"
+        ],
+        "state": "running",
+        "calls": [
+          {
+            "service": "playervox.score.subscribe",
+            "outcome": "ok"
+          }
+        ]
+      }
+    },
+    {
+      "publish": {
+        "service": "playervox.score.subscribe",
+        "error": "unavailable"
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "Score unavailable",
+          "Retrying automatically"
+        ],
+        "noText": [
+          "Portal 2"
+        ],
+        "image": "unavailable"
+      }
+    },
+    {
+      "advance": {
+        "ms": 4999
+      }
+    },
+    {
+      "expect": {
+        "calls": []
+      }
+    },
+    {
+      "advance": {
+        "ms": 1
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "Portal 2"
+        ],
+        "calls": [
+          {
+            "service": "playervox.score.subscribe",
+            "outcome": "ok"
+          }
+        ],
+        "image": "recovered"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,51 @@
+<!-- PlayerVox Score: the community grade badge of the active Steam game,
+     its rounded score, rating count, game name and three criteria
+     (parity sheet: playervox-overcrow docs/builtin-parity/playervox-score.md).
+     The badge and the PlayerVox mark are canvases drawn from
+     widgets-shared/playervox-badge; the host animates the badge's pulse. -->
+<box class={rootClass(state)} label={t("label")} tooltip={tooltip(state.score)}>
+  <if test={!badgeOnly(state)}>
+    <box class="header">
+      <if test={state.showTitle}>
+        <text class="title">{title(state.score)}</text>
+      </if>
+      <canvas ref="mark" class="mark" label={t("mark")}/>
+    </box>
+  </if>
+  <box class={mainClass(state)}>
+    <box class="slot">
+      <canvas ref="badge" class={state.badgeClass} label={badgeName(state.score)}/>
+    </box>
+    <if test={hasSide(state)}>
+      <box class="side">
+        <if test={rated(state.score)}>
+          <if test={state.showScore}>
+            <text class="value"><span>{scoreText(state.score)}</span><span class="max">/100</span></text>
+          </if>
+          <if test={state.showVotes}>
+            <text class={votesClass(state.showScore)}>{votes(state.score)}</text>
+          </if>
+        </if>
+        <else>
+          <text class="status">{t(status(state.score).label)}</text>
+          <if test={state.showVotes && status(state.score).hint != ""}>
+            <text class="hint">{t(status(state.score).hint)}</text>
+          </if>
+        </else>
+      </box>
+    </if>
+  </box>
+  <if test={state.showCriteria}>
+    <box class="criteria">
+      <for each={criteria(state.score)} as="criterion" key={criterion.key}>
+        <box class="criterion">
+          <box class="criterion-head">
+            <text class="criterion-name">{criterion.name}</text>
+            <text class="criterion-value">{criterion.text}</text>
+          </box>
+          <progress class={criterion.bar} value={criterion.value} max="100" label={criterion.label}/>
+        </box>
+      </for>
+    </box>
+  </if>
+</box>

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

@@ -0,0 +1,57 @@
+# Session
+
+`com.playervox.overcrow.session` — how long the current game has been
+running, as `HH:MM:SS`. 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 |
+| --- | --- |
+| Running | `01:27:43`; hours never wrap (`25:01:01`, `100:00:00`) |
+| Duration unknown, no grant, or the service failed | `--:--:--` |
+
+The duration counts from the start of the game process, on Linux and
+Windows alike, truncated to whole seconds.
+
+## Menu
+
+No widget row: only the host's rows.
+
+## Permissions
+
+`session.read`: the duration of the active game session, never its
+identity. Not sensitive.
+
+## How it works
+
+`session.subscribe` gives an anchor, `{ elapsedMs, at }` on the host's
+monotonic clock; the view's `elapsed` element shows it and the host
+advances it at each whole second. The widget runs no timer and sends
+nothing while the game runs; a clock change never moves the value. Its
+accessible label is "Session time" / "Temps de session".
+
+## Tests
+
+- `tests/logic.test.mjs`, `tests/refused.test.mjs`: the logic on
+  `@overcrow/sdk/testing`.
+- Scenarios with their reference images: `render` (both themes and
+  languages at 100 and 150 %), `unknown`, `ticks` (whole seconds, past 24
+  and 99 hours, a new anchor, the end of the game), `hidden`, `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.56–0.59 MiB anonymous | similar to the Clock's 0.83 MiB private working set |
+| VM CPU while the game runs | none: the host advances the value | — |
+| Overlay frames | one each second while shown | — |
+
+With the Clock 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/session/listing.json

@@ -0,0 +1,19 @@
+{
+  "author": "PlayerVox",
+  "spdxLicense": "MIT",
+  "sourceUrl": "https://github.com/Valhallab/playervox-overcrow-releases/tree/main/widgets/session",
+  "preview": "assets/preview.png",
+  "defaultLocale": "en",
+  "localizations": [
+    {
+      "locale": "en",
+      "name": "Session",
+      "description": "Shows how long the current game session has lasted."
+    },
+    {
+      "locale": "fr",
+      "name": "Session",
+      "description": "Affiche la durée de la session de jeu en cours."
+    }
+  ]
+}

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

@@ -0,0 +1,3 @@
+{
+  "label": "Session time"
+}

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

@@ -0,0 +1,3 @@
+{
+  "label": "Temps de session"
+}

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

@@ -0,0 +1,26 @@
+// Session: how long the game has been running. The host sends an anchor
+// (`elapsedMs` at its monotonic `at`) and advances the `elapsed` element
+// itself, so the widget has no timer and a clock change never moves it.
+import { hasGrant, initState, session, type Session } from "@overcrow/sdk";
+
+declare module "@overcrow/sdk" {
+  interface WidgetState {
+    /** The latest anchor, or `null` while the duration is unknown. */
+    session: Session | null;
+  }
+}
+
+const state = initState({ session: null as Session | null });
+
+/** The anchor to show: an update's value, or none after a failure. */
+export function anchor(update: { ok: boolean; value?: Session | null }): Session | null {
+  return update.ok ? (update.value ?? null) : null;
+}
+
+// Without the grant the host would refuse the subscription: show the
+// unknown duration instead of asking.
+if (hasGrant("session.read")) {
+  session.subscribe((update) => {
+    state.session = anchor(update);
+  });
+}

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

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "apiVersion": 1,
+  "id": "com.playervox.overcrow.session",
+  "version": "1.0.2",
+  "name": {
+    "en": "Session",
+    "fr": "Session"
+  },
+  "sizing": {
+    "fit": "both",
+    "preferred": { "width": 110, "height": 44 },
+    "min": { "width": 40, "height": 24 },
+    "max": { "width": 480, "height": 240 }
+  },
+  "permissions": {
+    "capabilities": ["session.read"]
+  }
+}

package/dist/content/examples/session/package.json

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

@@ -0,0 +1,16 @@
+/* One value; 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. */
+.session {
+  flex-direction: column;
+  align-items: start;
+  padding: 0 2px;
+}
+
+/* The UI font with tabular figures: the value never shifts. */
+.value {
+  font-family: var(--font-ui);
+  font-size: var(--font-size-value);
+  font-variant-numeric: tabular-nums;
+  color: var(--color-text);
+  white-space: nowrap;
+}

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

@@ -0,0 +1,8 @@
+{
+  "justifications": [
+    {
+      "permission": "capability:session.read",
+      "text": "Reads when the current game session started, to show how long it has lasted."
+    }
+  ]
+}

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

@@ -0,0 +1,45 @@
+{
+  "scenarioVersion": 1,
+  "name": "hidden",
+  "description": "Hidden, nothing is repainted; shown again, the value is current at once.",
+  "fixtures": {
+    "subscriptions": {
+      "session.subscribe": {
+        "elapsedMs": 60000,
+        "at": 0
+      }
+    }
+  },
+  "steps": [
+    {
+      "expect": {
+        "text": [
+          "00:01:00"
+        ]
+      }
+    },
+    {
+      "host": {
+        "visible": false
+      }
+    },
+    {
+      "advance": {
+        "ms": 600000
+      }
+    },
+    {
+      "host": {
+        "visible": true
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "00:11:00"
+        ],
+        "fault": "none"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,37 @@
+// Unit tests of the Session'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 vm = installRuntime({ host: { grants: ["session.read"] } });
+const logic = await loadLogic();
+const { state } = await import("@overcrow/sdk");
+
+test("with the grant, it subscribes once and starts unknown", () => {
+  assert.deepEqual(
+    vm.subscriptions.map(({ service, params }) => ({ service, params })),
+    [{ service: "session.subscribe", params: {} }],
+  );
+  assert.equal(state.session, null);
+  assert.equal(vm.timers.length, 0, "the host advances the value: no timer");
+});
+
+test("each update re-anchors; null and failures show the unknown duration", () => {
+  vm.push("session.subscribe", { elapsedMs: 5_263_000, at: 10 });
+  assert.deepEqual(state.session, { elapsedMs: 5_263_000, at: 10 });
+  vm.push("session.subscribe", { elapsedMs: 0, at: 20 });
+  assert.deepEqual(state.session, { elapsedMs: 0, at: 20 }, "a new process");
+  vm.push("session.subscribe", null);
+  assert.equal(state.session, null, "no active game");
+  vm.push("session.subscribe", { elapsedMs: 1, at: 30 });
+  vm.fail("session.subscribe", "unavailable");
+  assert.equal(state.session, null);
+});
+
+test("anchor", () => {
+  assert.equal(logic.anchor({ ok: false }), null);
+  assert.equal(logic.anchor({ ok: true, value: null }), null);
+  assert.deepEqual(logic.anchor({ ok: true, value: { elapsedMs: 5, at: 1 } }), { elapsedMs: 5, at: 1 });
+});

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

@@ -0,0 +1,28 @@
+{
+  "scenarioVersion": 1,
+  "name": "preview",
+  "description": "A session of 1 h 27 min 43 s. 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": {
+      "session.subscribe": {
+        "elapsedMs": 5263000,
+        "at": 0
+      }
+    }
+  },
+  "steps": [
+    {
+      "expect": {
+        "state": "running",
+        "text": [
+          "01:27:43"
+        ],
+        "image": "preview"
+      }
+    }
+  ]
+}

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

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

package/dist/content/examples/session/tests/refused.test.mjs

@@ -0,0 +1,16 @@
+// Without the session.read grant the logic asks the host nothing.
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { installRuntime } from "@overcrow/sdk/testing";
+
+import { loadLogic } from "./load-logic.mjs";
+
+const vm = installRuntime({ host: { grants: [] } });
+await loadLogic();
+const { state } = await import("@overcrow/sdk");
+
+test("no grant: no subscription, unknown duration", () => {
+  assert.equal(vm.subscriptions.length, 0);
+  assert.equal(vm.calls.length, 0);
+  assert.equal(state.session, null);
+});

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

@@ -0,0 +1,95 @@
+{
+  "scenarioVersion": 1,
+  "name": "render",
+  "description": "A session of 1 h 27 min 43 s, in both themes, both languages, at 100 % and 150 %.",
+  "fixtures": {
+    "subscriptions": {
+      "session.subscribe": {
+        "elapsedMs": 5263000,
+        "at": 0
+      }
+    }
+  },
+  "steps": [
+    {
+      "expect": {
+        "state": "running",
+        "text": [
+          "01:27:43"
+        ],
+        "image": "running-dark-en-100"
+      }
+    },
+    {
+      "host": {
+        "theme": "light"
+      }
+    },
+    {
+      "expect": {
+        "image": "running-light-en-100"
+      }
+    },
+    {
+      "host": {
+        "locale": "fr"
+      }
+    },
+    {
+      "expect": {
+        "image": "running-light-fr-100"
+      }
+    },
+    {
+      "host": {
+        "theme": "dark"
+      }
+    },
+    {
+      "expect": {
+        "image": "running-dark-fr-100"
+      }
+    },
+    {
+      "host": {
+        "scale": 1500
+      }
+    },
+    {
+      "expect": {
+        "image": "running-dark-fr-150"
+      }
+    },
+    {
+      "host": {
+        "theme": "light"
+      }
+    },
+    {
+      "expect": {
+        "image": "running-light-fr-150"
+      }
+    },
+    {
+      "host": {
+        "locale": "en"
+      }
+    },
+    {
+      "expect": {
+        "image": "running-light-en-150"
+      }
+    },
+    {
+      "host": {
+        "theme": "dark"
+      }
+    },
+    {
+      "expect": {
+        "image": "running-dark-en-150",
+        "fault": "none"
+      }
+    }
+  ]
+}