@overcrow/mcp 0.0.0 → 0.1.1

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

@@ -0,0 +1,246 @@
+{
+  "scenarioVersion": 1,
+  "name": "unavailable",
+  "description": "The host could not read the notes: the subscription ends, the widget says so, in French on a light panel here, and subscribes again 5 s later. The notes then show. A failure while a draft is open keeps the draft.",
+  "host": {
+    "locale": "fr",
+    "theme": "light"
+  },
+  "steps": [
+    {
+      "expect": {
+        "text": [
+          "Chargement des notes…"
+        ],
+        "image": "loading-light-fr",
+        "calls": [
+          {
+            "service": "notes.subscribe"
+          }
+        ]
+      }
+    },
+    {
+      "publish": {
+        "service": "notes.subscribe",
+        "error": "unavailable"
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "Impossible de charger ou d’enregistrer les notes. Réessayez."
+        ],
+        "image": "unavailable-light-fr"
+      }
+    },
+    {
+      "advance": {
+        "ms": 5000
+      }
+    },
+    {
+      "expect": {
+        "calls": [
+          {
+            "service": "notes.subscribe"
+          }
+        ]
+      }
+    },
+    {
+      "publish": {
+        "service": "notes.subscribe",
+        "value": {
+          "active": "note-1",
+          "notes": [
+            {
+              "id": "note-1",
+              "title": "Expedition",
+              "body": "Find the northern entrance before sunset.\nBring rope.",
+              "items": [
+                {
+                  "id": "local-1",
+                  "text": "Pack torches",
+                  "checked": true
+                },
+                {
+                  "id": "local-2",
+                  "text": "Sharpen the blade",
+                  "checked": false
+                },
+                {
+                  "id": "local-3",
+                  "text": "Buy healing potions for the whole party before leaving town",
+                  "checked": false
+                }
+              ]
+            },
+            {
+              "id": "note-2",
+              "title": "Build ideas",
+              "body": "Fire sword first, then armor.",
+              "items": []
+            },
+            {
+              "id": "note-3",
+              "title": "A very long note title that must be cut in the selector and in the list",
+              "body": "",
+              "items": [
+                {
+                  "id": "local-4",
+                  "text": "One entry",
+                  "checked": false
+                }
+              ]
+            },
+            {
+              "id": "note-4",
+              "title": "Route",
+              "body": "North gate, then the river.",
+              "items": [
+                {
+                  "id": "local-5",
+                  "text": "Buy a map",
+                  "checked": true
+                }
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "Expedition"
+        ],
+        "image": "back-light-fr"
+      }
+    },
+    {
+      "host": {
+        "mode": "interactive",
+        "locale": "en",
+        "theme": "dark"
+      }
+    },
+    {
+      "pointer": {
+        "click": {
+          "label": "Edit current note"
+        }
+      }
+    },
+    {
+      "pointer": {
+        "click": {
+          "label": "Note title"
+        }
+      }
+    },
+    {
+      "key": {
+        "key": "End"
+      }
+    },
+    {
+      "text": " II"
+    },
+    {
+      "publish": {
+        "service": "notes.subscribe",
+        "error": "unavailable"
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "Notes could not be loaded or saved. Try again."
+        ],
+        "image": "unavailable-dark-en"
+      }
+    },
+    {
+      "advance": {
+        "ms": 5000
+      }
+    },
+    {
+      "publish": {
+        "service": "notes.subscribe",
+        "value": {
+          "active": "note-1",
+          "notes": [
+            {
+              "id": "note-1",
+              "title": "Expedition",
+              "body": "Find the northern entrance before sunset.\nBring rope.",
+              "items": [
+                {
+                  "id": "local-1",
+                  "text": "Pack torches",
+                  "checked": true
+                },
+                {
+                  "id": "local-2",
+                  "text": "Sharpen the blade",
+                  "checked": false
+                },
+                {
+                  "id": "local-3",
+                  "text": "Buy healing potions for the whole party before leaving town",
+                  "checked": false
+                }
+              ]
+            },
+            {
+              "id": "note-2",
+              "title": "Build ideas",
+              "body": "Fire sword first, then armor.",
+              "items": []
+            },
+            {
+              "id": "note-3",
+              "title": "A very long note title that must be cut in the selector and in the list",
+              "body": "",
+              "items": [
+                {
+                  "id": "local-4",
+                  "text": "One entry",
+                  "checked": false
+                }
+              ]
+            },
+            {
+              "id": "note-4",
+              "title": "Route",
+              "body": "North gate, then the river.",
+              "items": [
+                {
+                  "id": "local-5",
+                  "text": "Buy a map",
+                  "checked": true
+                }
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "Expedition •",
+          "Save"
+        ],
+        "image": "draft-kept",
+        "calls": [
+          {
+            "service": "notes.subscribe"
+          }
+        ]
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,154 @@
+<!-- Notes: the active note of the user's notes document, and in
+     Interactive mode the selector, the checks and the editor (parity
+     sheet: playervox-overcrow docs/builtin-parity/notes.md).
+     Each editor is a form bound to the `notes.save` intent. Its title, its
+     body and its checklist rows belong to OverCrow, which fills them from
+     the stored note, keeps the draft and sends their values: they take no
+     `value` here. The logic only decides which rows a form has. A form
+     stays in the view, hidden, while its note has a draft. The form of a
+     new note is there from the click, without a target: its title takes
+     the focus, and OverCrow fills it when the note exists. -->
+<box class="notes" label={t("label")}>
+  <if test={phase(state) == "loading"}>
+    <text class="status">{t("loading")}</text>
+  </if>
+  <if test={phase(state) == "unavailable"}>
+    <text class="error">{t(unavailableKey(state))}</text>
+  </if>
+  <if test={phase(state) == "ready"}>
+    <if test={editable(state)}>
+      <if test={noteCount(state) == 0}>
+        <button class="action primary add" on:activate={create}>
+          <icon class="action-icon" name="plus"/>
+          <text class="action-label">{t("add-note")}</text>
+        </button>
+      </if>
+      <else>
+        <box class="toolbar">
+          <button class="selector" label={t("choose")} disabled={noteCount(state) < 2} on:activate={toggleMenu}>
+            <text class="selector-label">{activeLabel(state)}</text>
+            <if test={state.busy > 0}>
+              <icon class="selector-icon spin" name="loader-circle"/>
+            </if>
+            <else>
+              <icon class={chevronClass(state)} name="chevron-down"/>
+            </else>
+          </button>
+          <button class="icon-button" label={t("edit-current")} tooltip={t("edit-current")} disabled={editing(state)} on:activate={edit(activeId(state))}>
+            <icon name="pencil"/>
+          </button>
+          <button class="icon-button" label={t("add-note")} disabled={full(state)} on:activate={create}>
+            <icon name="plus"/>
+          </button>
+          <button class="icon-button" label={t("delete-current")} tooltip={t("delete-current")} on:activate={remove(activeId(state))}>
+            <icon name="trash-2"/>
+          </button>
+        </box>
+        <if test={state.menu}>
+          <scroll class="list">
+            <for each={state.doc.notes} as="note" key={note.id}>
+              <box class="list-row">
+                <button class={listItemClass(state, note)} on:activate={select(note.id)}>
+                  <text class="list-label">{noteLabel(state, note)}</text>
+                </button>
+                <button class="icon-button small" label={titled("edit-note", note.title)} tooltip={titled("edit-note", note.title)} on:activate={edit(note.id)}>
+                  <icon name="pencil"/>
+                </button>
+                <button class="icon-button small" label={titled("delete-note", note.title)} tooltip={titled("delete-note", note.title)} on:activate={remove(note.id)}>
+                  <icon name="trash-2"/>
+                </button>
+              </box>
+            </for>
+          </scroll>
+        </if>
+      </else>
+    </if>
+    <else>
+      <if test={showsNote(state) && activeId(state) != ""}>
+        <box class="heading">
+          <icon class="heading-icon" name="sticky-note"/>
+          <text class="heading-title">{activeTitle(state)}</text>
+        </box>
+      </if>
+    </else>
+    <if test={state.error != ""}>
+      <text class="error">{t(state.error)}</text>
+    </if>
+    <if test={!editing(state) && activeId(state) != ""}>
+      <scroll class="preview">
+        <if test={showsNote(state) && activeBody(state) != ""}>
+          <text class="body">{activeBody(state)}</text>
+        </if>
+        <if test={showsChecklist(state)}>
+          <if test={!showsNote(state) && editable(state)}>
+            <box class="heading">
+              <icon class="heading-icon" name="list-checks"/>
+              <text class="heading-title">{t("checklist")}</text>
+            </box>
+          </if>
+          <for each={previewItems(state)} as="item" key={item.id}>
+            <box class="item">
+              <if test={editable(state)}>
+                <checkbox class="item-check" checked={checked(state, item)} label={itemLabel(item)} on:change={check(activeId(state), item.id, event.value)}/>
+              </if>
+              <else>
+                <if test={checked(state, item)}>
+                  <icon class="item-icon item-icon-done" name="circle-check" label={t("done")}/>
+                </if>
+                <else>
+                  <icon class="item-icon" name="circle" label={t("todo")}/>
+                </else>
+              </else>
+              <text class={itemClass(state, item)}>{item.text}</text>
+            </box>
+          </for>
+        </if>
+      </scroll>
+    </if>
+  </if>
+  <for each={state.editors} as="editor" key={editor.key}>
+    <form class={editorClass(state, editor)} intent="notes.save" target={editor.note} on:submit={saved(editor.key, event.outcome, event.error)}>
+      <scroll class="fields">
+        <field class="title-field" name="title" autofocus placeholder={t("title-hint")} label={t("title-hint")} on:input={titleInput(editor.key, event.value)} on:keydown={keyed(editor.key, event.key, event.ctrl)}/>
+        <textarea class="body-field" name="body" rows={bodyRows(editor)} label={t("body-label")} on:input={bodyInput(editor.key, event.value)} on:keydown={keyed(editor.key, event.key, event.ctrl)}/>
+        <text class="meta">{t("checklist")}</text>
+        <box class="rows">
+          <for each={editor.rows} as="row" key={row.key}>
+            <box class="row">
+              <if test={rowStored(state, editor, row)}>
+                <checkbox class="row-check" checked={rowChecked(state, editor, row)} label={rowLabel(row)} on:change={check(editor.note, row.id, event.value)}/>
+              </if>
+              <else>
+                <icon class="row-new" name="circle"/>
+              </else>
+              <field class="row-field" name="item" placeholder={rowHint(editor, row)} label={t("item-hint")} on:input={rowInput(editor.key, row.key, event.value)} on:keydown={keyed(editor.key, event.key, event.ctrl)}/>
+              <if test={lastEmpty(editor, row)}>
+                <box class="row-space"/>
+              </if>
+              <else>
+                <button class="icon-button small" label={t("remove-entry")} tooltip={t("remove-entry")} on:activate={dropRow(editor.key, row.key)}>
+                  <icon name="x"/>
+                </button>
+              </else>
+            </box>
+          </for>
+        </box>
+        <if test={rowsFull(editor)}>
+          <text class="hint">{t("checklist-full")}</text>
+        </if>
+      </scroll>
+      <separator class="rule"/>
+      <if test={untitled(editor)}>
+        <text class="hint">{t("add-title")}</text>
+      </if>
+      <box class="actions">
+        <button class={saveClass(state, editor)} submit disabled={!canSave(state, editor)} on:activate={saving(editor.key)}>
+          <text class="action-label">{t("save")}</text>
+        </button>
+        <button class="action" on:activate={cancel(editor.key)}>
+          <text class="action-label">{t("cancel")}</text>
+        </button>
+      </box>
+    </form>
+  </for>
+</box>

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

@@ -0,0 +1,134 @@
+# Performance
+
+`com.playervox.overcrow.performance` — the game's CPU share and memory, the
+temperatures of this computer's CPU and GPU, and the game's frame rate. 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
+
+One row per metric, in this order, as a two-column list (vertical, the
+default) or on one line separated by `·` (horizontal):
+
+| Row | EN / FR label | Value | Amber | Red |
+| --- | --- | --- | --- | --- |
+| Game CPU | CPU | share of all logical processors, `23.0 %`, at most 100 | ≥ 80 % | ≥ 95 % |
+| Game memory | RAM | resident memory in binary gigabytes, `3.0 GB` | never | never |
+| CPU temperature | CPU° | `61.0 °C` or `141.8 °F` | ≥ 80 °C | ≥ 90 °C |
+| GPU temperature | GPU° | the same | ≥ 80 °C | ≥ 90 °C |
+| Frame rate | FPS | an integer, `144` | never | never |
+
+- A row shows only when its menu toggle is on **and** OverCrow has a
+  reading: no dash, no "N/A". The first sample after the game starts has
+  no CPU share yet; the row appears a second or two later.
+- Temperatures compare with their thresholds in °C, even when shown in
+  °F, and convert before rounding.
+- A reading the host keeps through a gap of its source (the frame rate
+  between two samples included) shows exactly as it was: a value shown
+  never disappears and shows no sign of its age.
+- Numbers follow the number format of OverCrow's settings, not the
+  language: `us` 1,234.5 (the default), `fr` 1 234,5, `de` 1.234,5.
+- With nothing to show: "Waiting for game data…" / "En attente des données
+  du jeu…"; with every metric switched off: "No metric selected" /
+  "Aucune mesure sélectionnée".
+
+Values use the interface font with tabular figures. Hovering a row in
+Interactive mode explains it ("Game CPU use across all logical
+processors.", "Observed presentation rate."…); each value's
+accessible name says what it is ("CPU temperature 61.0 °C").
+
+## Platforms
+
+| | Linux | Windows |
+| --- | --- | --- |
+| Game CPU and memory | every process of the game (same Steam app, or the game and its children) | the attached process only |
+| CPU temperature | `k10temp`, `zenpower` or `coretemp` sensors | none: the row and its menu toggle do not appear |
+| GPU temperature | `amdgpu` sensors | the graphics driver's reading, when it gives one |
+| Frame rate | X11 and XWayland game windows | OverCrow's FPS service |
+
+A sensor OverCrow cannot read, or two sensors of the same kind that
+disagree, give no reading: the row stays away.
+
+## Menu
+
+| Row | Type | Default |
+| --- | --- | --- |
+| Layout / Disposition | choice `layout`: Vertical, Horizontal | Vertical |
+| Shown values / Valeurs affichées | group `shown-values`: the five toggles below, in a side flyout | — |
+| Temperature / Température | choice `temperature-unit`: Celsius (°C), Fahrenheit (°F) | Celsius |
+
+The "Shown values" flyout:
+
+| Row | Type | Default |
+| --- | --- | --- |
+| CPU / CPU | toggle `show-cpu` | on |
+| RAM / RAM | toggle `show-ram` | on |
+| CPU temperature / Température CPU | toggle `show-cpu-temperature`, `requires: telemetry.cpuTemperature` | on |
+| GPU temperature / Température GPU | toggle `show-gpu-temperature`, `requires: telemetry.gpuTemperature` | on |
+| FPS / FPS | toggle `show-fps`, `requires: fps` | on |
+
+OverCrow hides a `requires` row while it has no such source. The flyout
+names each value alone (it was "Show CPU" / "Afficher le CPU"… at the
+first level): its title already says what the toggles do, and short
+labels stay whole in the flyout, where a longer one would end with "…". A group only arranges
+the menu: each toggle keeps its ID, so values saved before the toggles
+moved into the flyout still apply.
+
+## Permissions
+
+- `telemetry.read`: the game's CPU share and resident memory, and the
+  computer's temperatures. Not sensitive.
+- `fps.read`: the game's frame rate. Not sensitive.
+
+The widget stores nothing: its menu values are OverCrow's.
+
+## How it works
+
+`telemetry.subscribe` gives `{ cpu, ram, cpuTemperature, gpuTemperature,
+sources }`, or `null` without a game; the host normalizes the CPU share
+to the whole machine and keeps each temperature to its sensor's
+thousandth of a degree. `fps.subscribe` gives `{ fps, stale, status }`;
+the host keeps the game's last rate through a gap of its capture, so the
+widget runs no timer and does not draw `stale`. The widget
+subscribes to the frame rate only while the FPS row is switched on:
+OverCrow measures the frame rate only for a subscriber, so switching the
+row off also stops the measurement.
+
+## Tests
+
+- `tests/logic.test.mjs`, `tests/refused.test.mjs`: the logic on
+  `@overcrow/sdk/testing` (rows and their order, units, thresholds, the
+  °F vectors, number formats, a rate kept through a gap, messages, the menu and
+  the FPS subscription).
+- Scenarios with their reference images:
+  - `render`: every row, vertical, in both themes and languages at 100
+    and 150 %;
+  - `horizontal`: the one-line layout, the same matrix, a frame rate kept
+    through a gap;
+  - `thresholds`: below, amber and red, in both themes, and °F;
+  - `fahrenheit`: the conversion vectors and a negative temperature;
+  - `region`: the `us`, `fr` and `de` number formats;
+  - `stale`: a frame rate kept through a gap, unchanged, then a fresh
+    value, then none;
+  - `sources`: Windows (no CPU temperature), no sensor, the first
+    sample without CPU; `no-fps-source`;
+  - `waiting`, `menu` (every toggle, both choices, "No metric selected",
+    the FPS subscription ending and starting again), `refused`,
+    `telemetry-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 | 7.0 ms (p50), 8.1 ms at most | VM ready in 15–19 ms (p50) |
+| VM memory | 0.59 MiB private, 0.78 MiB PSS | 0.88 MiB private working set, 1.16 MiB private commit |
+| Private memory in all (VM, sandbox helpers, overlay share) | under 6 MB | — |
+| CPU, readings held | 0.03 % of one core, no frame | — |
+| CPU, a telemetry sample and an FPS reading each second | 0.08 % of one core: 3 frames a second, 0.26 ms at p95 | — |
+| VM CPU | one short turn per sample | — |
+
+The egui panel it replaces drew one frame per sample too (0.05 ms each,
+painting only), inside the overlay's own process.

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

@@ -0,0 +1,19 @@
+{
+  "author": "PlayerVox",
+  "spdxLicense": "MIT",
+  "sourceUrl": "https://github.com/Valhallab/playervox-overcrow-releases/tree/main/widgets/performance",
+  "preview": "assets/preview.png",
+  "defaultLocale": "en",
+  "localizations": [
+    {
+      "locale": "en",
+      "name": "Performance",
+      "description": "Game CPU and memory, plus the temperatures this computer exposes."
+    },
+    {
+      "locale": "fr",
+      "name": "Performances",
+      "description": "CPU et mémoire du jeu, et les températures que cet ordinateur expose."
+    }
+  ]
+}

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

@@ -0,0 +1,20 @@
+{
+  "label": "Performance",
+  "waiting": "Waiting for game data…",
+  "no-metric": "No metric selected",
+  "cpu": "CPU",
+  "ram": "RAM",
+  "cpu-temperature": "CPU°",
+  "gpu-temperature": "GPU°",
+  "fps": "FPS",
+  "hint-cpu": "Game CPU use across all logical processors.",
+  "hint-ram": "Game resident memory.",
+  "hint-cpu-temperature": "Host CPU temperature.",
+  "hint-gpu-temperature": "Host GPU temperature.",
+  "hint-fps": "Observed presentation rate.",
+  "name-cpu": "Game CPU use {value} {unit}",
+  "name-ram": "Game memory {value} {unit}",
+  "name-cpu-temperature": "CPU temperature {value} {unit}",
+  "name-gpu-temperature": "GPU temperature {value} {unit}",
+  "name-fps": "{value} frames per second"
+}

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

@@ -0,0 +1,20 @@
+{
+  "label": "Performances",
+  "waiting": "En attente des données du jeu…",
+  "no-metric": "Aucune mesure sélectionnée",
+  "cpu": "CPU",
+  "ram": "RAM",
+  "cpu-temperature": "CPU°",
+  "gpu-temperature": "GPU°",
+  "fps": "FPS",
+  "hint-cpu": "Utilisation du CPU par le jeu sur l’ensemble des processeurs logiques.",
+  "hint-ram": "Mémoire résidente du jeu.",
+  "hint-cpu-temperature": "Température du CPU de l’ordinateur.",
+  "hint-gpu-temperature": "Température du GPU de l’ordinateur.",
+  "hint-fps": "Rythme de présentation observé.",
+  "name-cpu": "Utilisation du CPU par le jeu {value} {unit}",
+  "name-ram": "Mémoire du jeu {value} {unit}",
+  "name-cpu-temperature": "Température CPU {value} {unit}",
+  "name-gpu-temperature": "Température GPU {value} {unit}",
+  "name-fps": "{value} images par seconde"
+}