@overcrow/mcp 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,139 @@
+{
+  "scenarioVersion": 1,
+  "name": "ticks",
+  "description": "The host advances the value each whole second, without VM timers; hours never wrap; a new anchor re-anchors the display at once.",
+  "fixtures": {
+    "subscriptions": {
+      "session.subscribe": {
+        "elapsedMs": 1999,
+        "at": 0
+      }
+    }
+  },
+  "steps": [
+    {
+      "expect": {
+        "text": [
+          "00:00:01"
+        ],
+        "calls": [
+          {
+            "service": "session.subscribe",
+            "outcome": "ok"
+          }
+        ]
+      }
+    },
+    {
+      "advance": {
+        "ms": 1
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "00:00:02"
+        ]
+      }
+    },
+    {
+      "advance": {
+        "ms": 998
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "00:00:02"
+        ],
+        "noText": [
+          "00:00:03"
+        ]
+      }
+    },
+    {
+      "advance": {
+        "ms": 2
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "00:00:03"
+        ],
+        "calls": []
+      }
+    },
+    {
+      "publish": {
+        "service": "session.subscribe",
+        "value": {
+          "elapsedMs": 90061000,
+          "at": 1001
+        }
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "25:01:01"
+        ]
+      }
+    },
+    {
+      "publish": {
+        "service": "session.subscribe",
+        "value": {
+          "elapsedMs": 359999000,
+          "at": 1001
+        }
+      }
+    },
+    {
+      "advance": {
+        "ms": 1000
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "100:00:00"
+        ],
+        "image": "hundred-hours"
+      }
+    },
+    {
+      "publish": {
+        "service": "session.subscribe",
+        "value": {
+          "elapsedMs": 0,
+          "at": 2001
+        }
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "00:00:00"
+        ],
+        "noText": [
+          "100:00:00"
+        ]
+      }
+    },
+    {
+      "publish": {
+        "service": "session.subscribe",
+        "value": null
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "--:--:--"
+        ],
+        "fault": "none"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,37 @@
+{
+  "scenarioVersion": 1,
+  "name": "unknown",
+  "description": "The game is present but its duration is unknown (null): --:--:--.",
+  "fixtures": {
+    "subscriptions": {
+      "session.subscribe": null
+    }
+  },
+  "steps": [
+    {
+      "expect": {
+        "state": "running",
+        "text": [
+          "--:--:--"
+        ],
+        "image": "unknown-dark"
+      }
+    },
+    {
+      "host": {
+        "theme": "light",
+        "locale": "fr",
+        "scale": 1500
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "--:--:--"
+        ],
+        "image": "unknown-light-fr-150",
+        "fault": "none"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,11 @@
+<!-- Session: the time since the game process started, advanced by the host
+     from the service's anchor (parity sheet: playervox-overcrow
+     docs/builtin-parity/session.md). -->
+<box class="session" label={t("label")}>
+  <if test={state.session}>
+    <elapsed class="value" base={state.session.elapsedMs} at={state.session.at} running={true} format="hh:mm:ss"/>
+  </if>
+  <else>
+    <text class="value">--:--:--</text>
+  </else>
+</box>

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

@@ -0,0 +1,99 @@
+# Manual stopwatch
+
+`com.playervox.overcrow.stopwatch` — a stopwatch to the hundredth of a
+second, `HH:MM:SS.cc`, started, paused and reset with its buttons or with
+OverCrow's global shortcuts. 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 |
+| --- | --- |
+| Zero | `00:00:00.00`, the play button |
+| Running | the time advancing to the hundredth, truncated; the pause button |
+| Paused | the frozen time, the play button |
+| Past 99 hours | hours never wrap: `100:00:00.00` |
+| State unknown, no grant, or the service failed | `--:--:--.--`, no buttons, no reminder |
+
+Below the time, a reminder of the host's two shortcuts, in the host's
+own words for its platform: `Super+Alt+T  Start / pause  ·  Super+Alt+Z
+Reset` on Linux, `Ctrl+Shift+P` and `Ctrl+Shift+R` on Windows. In French:
+`Démarrer / pause`, `Réinitialiser`. The time uses the interface font with
+tabular figures and `.` before the hundredths in both languages.
+
+## Controls
+
+| Mode | Control | Does |
+| --- | --- | --- |
+| Interactive | Play or pause button ("Start" / "Pause", FR "Démarrer" / "Pause") | `stopwatch.toggle` |
+| Interactive | Reset button ("Reset", FR "Réinitialiser") | `stopwatch.reset`: zero, paused |
+| Interactive | Enter or Space on a focused button | the same |
+| Interactive | Hover or focus a button | tooltip `{label} ({chord})`, e.g. "Start (Super+Alt+T)" |
+| Passive | — | no buttons: the time and the reminder only |
+| Any | OverCrow's global shortcuts | the host acts on its stopwatch directly; the widget shows the result |
+
+Each button makes one call on its own gesture; the host refuses a call
+made outside a gesture (`gesture_required`). The state a command returns
+shows at once. A command the host cannot apply (`unavailable`, or
+`stale_context` after a game change) changes nothing on screen.
+
+## Menu
+
+No widget row: only the host's rows.
+
+## Permissions
+
+- `stopwatch.read`: the state of the host's single stopwatch and the
+  labels of its shortcuts. Not sensitive.
+- `stopwatch.control`: start, pause and reset it. Not sensitive. Without
+  it the widget shows no buttons.
+
+The widget stores nothing: the host keeps one stopwatch for as long as it
+runs, resets it when the game changes, and forgets it when it stops. While
+a widget holding `stopwatch.control` is enabled, the host binds the
+shortcuts whenever the game has focus, even when the widget is hidden in
+Passive mode.
+
+## How it works
+
+`stopwatch.subscribe` gives the state as an anchor, `{ running,
+elapsedMs, at, shortcuts }` on the host's monotonic clock, or `null`
+without a game. The view's `elapsed` element (`format="hh:mm:ss.cc"`)
+shows it and the host advances it, at most at 60 Hz while it is running
+and visible: the widget runs no timer and sends nothing while the
+stopwatch runs. `shortcuts.bound` is `false` when another application took
+a chord; the reminder stays, as before, and OverCrow's Control Center
+reports the conflict.
+
+## Tests
+
+- `tests/logic.test.mjs`, `tests/read-only.test.mjs`,
+  `tests/refused.test.mjs`: the logic on `@overcrow/sdk/testing`.
+- Scenarios with their reference images:
+  - `render`: running, with its buttons, in both themes and languages at
+    100 and 150 %;
+  - `states`: zero, running, paused and reset through the buttons, Passive
+    mode, shortcuts seen as updates, Windows chords;
+  - `hundredths`: the host's hundredths, truncated, without calls; hours
+    past 99; a new anchor; no game;
+  - `hidden`, `gesture` (Passive clicks call nothing; a click, Enter and
+    Space each make one call), `errors`, `unknown`, `refused`,
+    `read-only`.
+
+## 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 | 6.9 ms (p50), 7.0 ms at most | VM ready in 14 ms (p50) |
+| VM memory | 0.57–0.58 MiB anonymous | 0.85 MiB private working set |
+| Private memory in all (VM, sandbox helpers, overlay share) | about 5 MB | — |
+| CPU, paused or hidden | 0.03 % of one core, no frame | — |
+| CPU, running and shown | 0.7 % of one core: 59 frames a second of 0.06–0.10 ms | — |
+| VM CPU while running | none: the host advances the value | — |
+
+The egui stopwatch it replaces also drew one frame per display refresh
+while running (0.04 ms each, painting only) and nothing when paused.

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

@@ -0,0 +1,19 @@
+{
+  "author": "PlayerVox",
+  "spdxLicense": "MIT",
+  "sourceUrl": "https://github.com/Valhallab/playervox-overcrow-releases/tree/main/widgets/stopwatch",
+  "preview": "assets/preview.png",
+  "defaultLocale": "en",
+  "localizations": [
+    {
+      "locale": "en",
+      "name": "Manual stopwatch",
+      "description": "A stopwatch to the hundredth of a second, started, paused and reset with its buttons or the host’s shortcuts."
+    },
+    {
+      "locale": "fr",
+      "name": "Chronomètre",
+      "description": "Un chronomètre au centième de seconde, démarré, mis en pause et réinitialisé par ses boutons ou les raccourcis de l’hôte."
+    }
+  ]
+}

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

@@ -0,0 +1,8 @@
+{
+  "label": "Stopwatch",
+  "start": "Start",
+  "pause": "Pause",
+  "reset": "Reset",
+  "with-chord": "{label} ({chord})",
+  "reminder": "{toggle}  Start / pause  ·  {reset}  Reset"
+}

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

@@ -0,0 +1,8 @@
+{
+  "label": "Chronomètre",
+  "start": "Démarrer",
+  "pause": "Pause",
+  "reset": "Réinitialiser",
+  "with-chord": "{label} ({chord})",
+  "reminder": "{toggle}  Démarrer / pause  ·  {reset}  Réinitialiser"
+}

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

@@ -0,0 +1,93 @@
+// Manual stopwatch: the host keeps one stopwatch, which its global shortcuts
+// also drive. The widget shows it and commands it on a gesture. The host
+// sends an anchor (`elapsedMs` at its monotonic `at`) and advances the
+// `elapsed` element itself, hundredths included: the widget has no timer.
+import {
+  hasGrant,
+  host,
+  initState,
+  onHost,
+  stopwatch,
+  t,
+  type Stopwatch,
+} from "@overcrow/sdk";
+
+declare module "@overcrow/sdk" {
+  interface WidgetState {
+    /** The latest state, or `null` while it is unknown. */
+    stopwatch: Stopwatch | null;
+    /** The buttons take input only in Interactive mode. */
+    interactive: boolean;
+  }
+}
+
+const canRead = hasGrant("stopwatch.read");
+const canControl = hasGrant("stopwatch.control");
+
+const state = initState({
+  stopwatch: null as Stopwatch | null,
+  interactive: host.mode === "interactive",
+});
+
+/** The state a subscription update leaves: none after a failure. */
+export function current(update: { ok: boolean; value?: Stopwatch | null }): Stopwatch | null {
+  return update.ok ? (update.value ?? null) : null;
+}
+
+/** The buttons: Interactive mode, the control grant and a known state. */
+export function showControls(interactive: boolean, known: Stopwatch | null): boolean {
+  return interactive && canControl && known !== null;
+}
+
+/** The label of the start/pause button. */
+export function toggleLabel(running: boolean): string {
+  return t(running ? "pause" : "start");
+}
+
+/** A button's tooltip: its label and the host's chord. */
+export function withChord(label: string, chord: string): string {
+  return t("with-chord", { label, chord });
+}
+
+/** The reminder of the host's two shortcuts. */
+export function reminder(shortcuts: Stopwatch["shortcuts"]): string {
+  return t("reminder", { toggle: shortcuts.toggle, reset: shortcuts.reset });
+}
+
+/**
+ * Applies the state a command returned, at once: the next subscription
+ * update carries the same state. A failure (`unavailable` when the host
+ * cannot act) changes nothing, as the host did not act.
+ */
+function command(call: () => Promise<Stopwatch | null>): void {
+  call().then(
+    (next) => {
+      if (canRead) {
+        state.stopwatch = next;
+      }
+    },
+    () => {},
+  );
+}
+
+export function toggle(): void {
+  command(() => stopwatch.toggle());
+}
+
+export function reset(): void {
+  command(() => stopwatch.reset());
+}
+
+onHost((changed) => {
+  if (changed.includes("mode")) {
+    state.interactive = host.mode === "interactive";
+  }
+});
+
+// Without the grant the host would refuse the subscription: show the
+// unknown time instead of asking.
+if (canRead) {
+  stopwatch.subscribe((update) => {
+    state.stopwatch = current(update);
+  });
+}

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

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "apiVersion": 1,
+  "id": "com.playervox.overcrow.stopwatch",
+  "version": "1.0.3",
+  "name": {
+    "en": "Manual stopwatch",
+    "fr": "Chronomètre"
+  },
+  "sizing": {
+    "fit": "both",
+    "preferred": { "width": 330, "height": 72 },
+    "min": { "width": 60, "height": 24 },
+    "max": { "width": 640, "height": 240 }
+  },
+  "permissions": {
+    "capabilities": ["stopwatch.read", "stopwatch.control"]
+  }
+}

package/dist/content/examples/stopwatch/package.json

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

@@ -0,0 +1,54 @@
+/* The time, the buttons beside it in Interactive mode, the shortcut
+   reminder below; 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) and
+   3 px between the lines. */
+.stopwatch {
+  flex-direction: column;
+  align-items: start;
+  gap: 3px;
+  padding: 0 2px;
+}
+
+.row {
+  flex-direction: row;
+  align-items: center;
+  gap: 6px;
+}
+
+/* The UI font with tabular figures: the hundredths never shift. */
+.value {
+  font-family: var(--font-ui);
+  font-size: var(--font-size-value);
+  font-variant-numeric: tabular-nums;
+  color: var(--color-text);
+  white-space: nowrap;
+  margin-right: 2px;
+}
+
+/* The built-in's compact icon buttons: a raised surface, lighter under
+   the pointer or with the keyboard focus. */
+.control {
+  width: var(--icon-button-size);
+  height: var(--icon-button-size);
+  padding: 5px;
+  /* The icon (sized by `font-size`) fills the 12 px content box exactly
+     and is centred in it. */
+  font-size: 12px;
+  justify-content: center;
+  align-items: center;
+  border-radius: var(--radius-sm);
+  background: var(--color-surface-raised);
+  color: var(--color-text);
+}
+
+.control:hover,
+.control:focus {
+  background: var(--color-surface-hover);
+}
+
+.reminder {
+  font-family: var(--font-ui);
+  font-size: var(--font-size-small);
+  color: var(--color-text-muted);
+  white-space: nowrap;
+}

package/dist/content/examples/stopwatch/tests/errors.scenario.json

@@ -0,0 +1,121 @@
+{
+  "scenarioVersion": 1,
+  "name": "errors",
+  "description": "A command the host cannot apply (unavailable, or stale_context after a game change) changes nothing on screen; the next one succeeds.",
+  "host": {
+    "mode": "interactive"
+  },
+  "fixtures": {
+    "calls": {
+      "stopwatch.toggle": [
+        {
+          "error": "unavailable"
+        },
+        {
+          "value": {
+            "running": true,
+            "elapsedMs": 5000,
+            "at": 0,
+            "shortcuts": {
+              "toggle": "Super+Alt+T",
+              "reset": "Super+Alt+Z",
+              "bound": true
+            }
+          }
+        }
+      ],
+      "stopwatch.reset": [
+        {
+          "error": "stale_context"
+        }
+      ]
+    },
+    "subscriptions": {
+      "stopwatch.subscribe": {
+        "running": false,
+        "elapsedMs": 5000,
+        "at": 0,
+        "shortcuts": {
+          "toggle": "Super+Alt+T",
+          "reset": "Super+Alt+Z",
+          "bound": true
+        }
+      }
+    }
+  },
+  "steps": [
+    {
+      "pointer": {
+        "click": {
+          "label": "Start"
+        }
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "00:00:05.00"
+        ],
+        "calls": [
+          {
+            "service": "stopwatch.subscribe",
+            "outcome": "ok"
+          },
+          {
+            "service": "stopwatch.toggle",
+            "outcome": "unavailable"
+          }
+        ],
+        "fault": "none"
+      }
+    },
+    {
+      "pointer": {
+        "click": {
+          "label": "Reset"
+        }
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "00:00:05.00"
+        ],
+        "calls": [
+          {
+            "service": "stopwatch.reset",
+            "outcome": "stale_context"
+          }
+        ],
+        "fault": "none"
+      }
+    },
+    {
+      "pointer": {
+        "click": {
+          "label": "Start"
+        }
+      }
+    },
+    {
+      "advance": {
+        "ms": 250
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "00:00:05.25"
+        ],
+        "calls": [
+          {
+            "service": "stopwatch.toggle",
+            "outcome": "ok"
+          }
+        ],
+        "image": "after-errors",
+        "fault": "none"
+      }
+    }
+  ]
+}