@overcrow/mcp 0.0.0 → 0.1.1

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

@@ -0,0 +1,183 @@
+{
+  "scenarioVersion": 1,
+  "name": "unavailable",
+  "description": "The host's journal source fails: the subscription ends with unavailable, the widget shows it without the last sessions, subscribes again 5 s later and reads the journal the restarted source reports.",
+  "fixtures": {
+    "calls": {
+      "journal.page": [
+        {
+          "value": {
+            "gameName": "Portal 2",
+            "items": [
+              {
+                "id": "00000000-0000-4000-8000-000000000013",
+                "startedAt": 1789929000000,
+                "offsetMinutes": 120,
+                "durationMs": 2700000,
+                "source": "local"
+              },
+              {
+                "id": "00000000-0000-4000-8000-000000000012",
+                "startedAt": 1789844700000,
+                "offsetMinutes": 120,
+                "durationMs": 7920000,
+                "source": "cloud"
+              },
+              {
+                "id": "00000000-0000-4000-8000-000000000011",
+                "startedAt": 1789629300000,
+                "offsetMinutes": 120,
+                "durationMs": 480000,
+                "source": "local"
+              },
+              {
+                "id": "00000000-0000-4000-8000-000000000010",
+                "startedAt": 1789214400000,
+                "offsetMinutes": 120,
+                "durationMs": 14400000,
+                "source": "cloud"
+              },
+              {
+                "id": "00000000-0000-4000-8000-000000000009",
+                "startedAt": 1788640920000,
+                "offsetMinutes": 120,
+                "durationMs": 3660000,
+                "source": "local"
+              }
+            ],
+            "page": 1,
+            "next": "c2",
+            "previous": null
+          }
+        },
+        {
+          "value": {
+            "gameName": "Portal 2",
+            "items": [
+              {
+                "id": "00000000-0000-4000-8000-000000000013",
+                "startedAt": 1789929000000,
+                "offsetMinutes": 120,
+                "durationMs": 2700000,
+                "source": "local"
+              },
+              {
+                "id": "00000000-0000-4000-8000-000000000012",
+                "startedAt": 1789844700000,
+                "offsetMinutes": 120,
+                "durationMs": 7920000,
+                "source": "cloud"
+              },
+              {
+                "id": "00000000-0000-4000-8000-000000000011",
+                "startedAt": 1789629300000,
+                "offsetMinutes": 120,
+                "durationMs": 480000,
+                "source": "local"
+              },
+              {
+                "id": "00000000-0000-4000-8000-000000000010",
+                "startedAt": 1789214400000,
+                "offsetMinutes": 120,
+                "durationMs": 14400000,
+                "source": "cloud"
+              },
+              {
+                "id": "00000000-0000-4000-8000-000000000009",
+                "startedAt": 1788640920000,
+                "offsetMinutes": 120,
+                "durationMs": 3660000,
+                "source": "local"
+              }
+            ],
+            "page": 1,
+            "next": "c2",
+            "previous": null
+          }
+        }
+      ]
+    },
+    "subscriptions": {
+      "journal.subscribe": {
+        "revision": 1,
+        "notice": null
+      }
+    }
+  },
+  "steps": [
+    {
+      "expect": {
+        "text": [
+          "Portal 2"
+        ],
+        "state": "running",
+        "calls": [
+          {
+            "service": "journal.subscribe",
+            "outcome": "ok"
+          },
+          {
+            "service": "journal.page",
+            "outcome": "ok"
+          }
+        ]
+      }
+    },
+    {
+      "publish": {
+        "service": "journal.subscribe",
+        "error": "unavailable"
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "The journal is unavailable. Retrying automatically."
+        ],
+        "noText": [
+          "Portal 2",
+          "Page 1"
+        ],
+        "image": "unavailable"
+      }
+    },
+    {
+      "advance": {
+        "ms": 4999
+      }
+    },
+    {
+      "expect": {
+        "calls": []
+      }
+    },
+    {
+      "advance": {
+        "ms": 1
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "Portal 2",
+          "Page 1"
+        ],
+        "noText": [
+          "The journal is unavailable. Retrying automatically."
+        ],
+        "calls": [
+          {
+            "service": "journal.subscribe",
+            "outcome": "ok"
+          },
+          {
+            "service": "journal.page",
+            "params": {},
+            "outcome": "ok"
+          }
+        ],
+        "image": "recovered"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,52 @@
+<!-- PlayerVox Journal: the finished sessions of the active game, five per
+     page, with the trash and paging buttons in Interactive mode (parity
+     sheet: playervox-overcrow docs/builtin-parity/playervox-journal.md).
+     The host confirms a deletion in its own chrome. -->
+<box class="journal" label={t("label")}>
+  <box class="header">
+    <text class="title">{t("label")}</text>
+    <canvas ref="mark" class="mark" label={t("mark")}/>
+  </box>
+  <if test={message(state.problem, state.notice) != ""}>
+    <text class="message">{message(state.problem, state.notice)}</text>
+  </if>
+  <if test={state.phase == "loading"}>
+    <text class="status">{t("loading")}</text>
+  </if>
+  <if test={state.phase == "idle"}>
+    <text class="status">{t("waiting")}</text>
+  </if>
+  <if test={state.phase == "ready"}>
+    <if test={gameName(state.page) != ""}>
+      <text class="game" tooltip={cutBytes(gameName(state.page), 256)}>{gameName(state.page)}</text>
+    </if>
+    <if test={state.page.items.length == 0}>
+      <text class="status">{t("empty")}</text>
+    </if>
+    <for each={rows(state.page)} as="row" key={row.id}>
+      <separator class="rule"/>
+      <box class="row" label={row.label}>
+        <text class="start">{row.start}</text>
+        <text class="duration">{row.duration}</text>
+        <if test={canRemove(state.interactive)}>
+          <button class="control" label={t("delete")} tooltip={t("delete")} disabled={state.busy} on:activate={remove(row.id)}>
+            <icon name="trash"/>
+          </button>
+        </if>
+      </box>
+    </for>
+    <if test={paged(state.page)}>
+      <box class="footer">
+        <if test={state.interactive}>
+          <button class="control" label={t("previous")} tooltip={t("previous")} disabled={state.busy || state.page.previous == null} on:activate={turn("previous")}>
+            <icon name="chevron-left"/>
+          </button>
+          <button class="control" label={t("next")} tooltip={t("next")} disabled={state.busy || state.page.next == null} on:activate={turn("next")}>
+            <icon name="chevron-right"/>
+          </button>
+        </if>
+        <text class="page">{pageLabel(state.page)}</text>
+      </box>
+    </if>
+  </if>
+</box>

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

@@ -0,0 +1,166 @@
+# My rating (PlayerVox Rating)
+
+`com.playervox.overcrow.playervox.rating` — your own PlayerVox rating of the
+Steam game you play: its grade badge (S+ to F) and score out of 100, and in
+Interactive mode a form with three criteria (Gameplay, Art, Technology) and
+an optional review, to publish or update the rating on PlayerVox. It needs
+your PlayerVox account. 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 |
+| --- | --- |
+| Rated | the game's name, the badge, "93 /100", "Your published rating" / "Votre note publiée" |
+| Not rated yet | the game's name, a neutral `--` badge, "-- /100", "Not rated yet" / "Pas encore noté" |
+| Waiting for PlayerVox | a `--` badge and "Loading…" / "Chargement…": after a game switch too, never the previous game's rating |
+| No game | "Waiting for a game" / "En attente du jeu" |
+| A game without a Steam app ID | "Game not linked" / "Jeu non associé", "Steam game required" / "Jeu Steam requis" |
+| The rating cannot be read | "Rating unavailable" / "Note indisponible", "PlayerVox is unavailable for this game right now." |
+| Offline | the last rating read; OverCrow adds its own notice under the content |
+| No account, a sign-in in progress, an expired session | nothing of the widget: OverCrow covers it with its account panel (link or create an account, reopen the browser, cancel) |
+| No permission to read | "Rating unavailable", "Allow access to your rating in the Control Center.": the widget asks OverCrow nothing |
+
+The score is the mean of the three criteria, rounded half away from zero
+(96, 88 and 94 show "93"); the grade is the mean's: S+ ≥ 90, S ≥ 80, A ≥ 70,
+B ≥ 60, C ≥ 40, D ≥ 20, else F. The badge and the PlayerVox mark are drawn
+from the source shared with PlayerVox Score
+([widgets-shared](../../widgets-shared/README.md)); the badge pulses once
+when a published rating shows or changes, never for a draft.
+
+In Passive mode the widget shows only the published rating: no form, no
+draft.
+
+## The form (Interactive mode)
+
+| Control | |
+| --- | --- |
+| Gameplay, Art / Artistique, Technology / Technique | sliders from 0 to 100 by 1, their value beside them |
+| REVIEW · OPTIONAL / AVIS · FACULTATIF | a text area, "What stood out to you?", at most 2000 characters |
+| The button | "Publish my rating" before the first rating, "Update my rating" after; "Saving…" while OverCrow sends it; "Saved on PlayerVox" once stored, until the next change |
+
+- **The form is OverCrow's.** Its sliders and its review are host-owned
+  controls of a `form` bound to the `playervox.rating.publish` intent: the
+  view gives them no `value`. OverCrow fills them with your published
+  rating, or with 50 / 50 / 50 and an empty review before the first one,
+  and tells the logic each value through the control's `input` event. The
+  logic only follows them, to show the draft's mean and to know whether
+  something changed.
+- **Publishing** takes your gesture: a click on the button, Enter or Space
+  on it, or Ctrl+Enter in the review. OverCrow then sends the values of
+  its own controls; the logic never supplies them and cannot submit the
+  form itself. An unchanged review is not sent again; an emptied one
+  removes the published review.
+- **The button is active** when PlayerVox is reachable and there is
+  something to send: a first rating, or a change. While the score beside
+  the badge is a draft's, the caption reads "Unpublished draft" /
+  "Brouillon non publié".
+- **The draft is kept by OverCrow**: through Passive mode (the form stays
+  in the view, hidden), through a failed publication, and when the rating
+  changes elsewhere while you edit. An untouched form follows the new
+  rating. Another game, or another PlayerVox user, starts from its own
+  rating.
+- **Once stored**, the rating comes back through the subscription: the
+  widget reads nothing again.
+- **Offline**, the form shows "Offline · Your changes stay here until you
+  save them." and takes no input.
+
+### When a publication fails
+
+The draft stays, the button comes back, and a message shows above it:
+
+| OverCrow's answer | Message |
+| --- | --- |
+| `invalid_request` (PlayerVox refused the values, or the game is not released) | "Check the values and try saving again." |
+| `not_connected` (the session ended) | "Your connection expired. Link your account again." |
+| `busy` (another publication is in flight, or too many requests) | "An operation is already in progress. Please try again shortly." |
+| `stale_context` (the game or the account changed meanwhile) | "The account or game changed. Review your changes before saving." |
+| `permission_denied` | "This action is not available for your account." |
+| `unavailable`, `timeout` (no answer from PlayerVox within 30 s) and any other | "PlayerVox is unavailable for this game right now." |
+
+Should OverCrow give no answer at all, the button comes back after 40 s
+with the last message.
+
+## Controls
+
+Tab moves through the three sliders, the review and the button. On a
+slider: the arrow keys move by 1, Page Up and Page Down by 10, Home and
+End to the ends; a click or a drag on the track sets it. The keyboard goes
+to the widget the pointer rests on.
+
+## Menu
+
+No row of its own.
+
+## Size
+
+350 px wide by default, from 280 px; the height fits the content: the
+summary alone in Passive mode, the form below it in Interactive mode.
+
+## Permissions
+
+- `playervox.rating.read`: your own rating of the active game, with the
+  game's name. Sensitive.
+- `playervox.rating.write`: publish a rating and a review through the
+  host-bound form. Sensitive.
+
+As sensitive capabilities rule out the network and the clipboard, the
+widget declares neither, and no storage: it keeps nothing. OverCrow reads
+the rating and sends the publication with your PlayerVox session
+(`api.playervox.com`); it reads the rating only while this widget
+subscribes. With the read permission alone the widget shows the rating and
+no form.
+
+## Tests
+
+- `tests/logic.test.mjs`: the logic on `@overcrow/sdk/testing`: every state's
+  text, the draft's mean and rounding, when the button is active, the
+  Publish, Saving, Saved cycle, each failure's message, the 40 s bound, one
+  pulse per new published rating, the retry of a failed subscription.
+- Scenarios, played in OverCrow's headless runtime
+  (`overcrow-widget test --runtime …`), with their reference images in
+  `tests/reference/`:
+
+  | Scenario | Covers |
+  | --- | --- |
+  | `states` | every state in Passive mode, dark English and light French, 100 % and 150 % |
+  | `form` | the form filled by OverCrow, rated and not rated yet, both themes and languages, 150 %, 280 px wide |
+  | `publish-keyboard` | Tab, an arrow key, Enter on the button, then Ctrl+Enter in the review: what OverCrow sends, Saved |
+  | `publish-pointer` | a first rating with the pointer, then Saving with no answer, `unavailable`, `busy`, `timeout`, `stale_context` and `not_connected` |
+  | `offline` | the last rating, OverCrow's notice, a form that takes no input, then online again |
+  | `account` | OverCrow's account panel signed out, pending and expired, in both modes; no input reaches the widget |
+  | `draft` | the draft through Passive mode and a rating published elsewhere; an untouched form follows; another game |
+  | `bounds` | a long game name; a review cut at 2000 characters by OverCrow's field |
+  | `refused` | no grant: no call, "Rating unavailable" |
+  | `read-only` | the read grant alone: the rating, never the form |
+
+  A publication refused because no gesture made it (`gesture_required`)
+  cannot be played by a scenario, where every submission is a gesture:
+  OverCrow tests it with this package in its own repository.
+
+## Cost
+
+Measured on 2026-10-01 with OverCrow's release build, on an AMD Ryzen 7
+5800X3D Linux workstation and in a Windows 11 virtual machine (2 vCPU),
+with a published rating and its review:
+
+| | Linux | Windows (VM) |
+| --- | --- | --- |
+| Widget start, warm, into the overlay's runtime | 8.7 ms (p50), 8.8 ms at most | VM ready in 14–15 ms (p50) |
+| VM memory | 0.79 MiB private, 0.97 MiB PSS | 1.15 MiB private working set, 1.43 MiB private commit |
+| Private memory in all (VM, sandbox helpers, overlay share) | 8.7–11.2 MB | — |
+| CPU at rest, Passive mode | 0.05 % of one core, no frame | — |
+| CPU at rest, the form open | 0.03–0.05 % of one core, no frame | — |
+| CPU, a slider changed and the rating published every 2 s | 0.30 % of one core: the frames of the keys, the outcome and the badge's pulse (about 36 frames of 0.10 ms), then none | — |
+| CPU, hidden, a new rating every 2 s | 0.05 % of one core | — |
+| VM CPU | one short turn per rating or form value; none at rest | — |
+
+A rating changes when you publish one: the 2 s load is a stress. The
+private memory is above OverCrow's 8 MB goal per widget by up to 3 MB and
+far under its 80 MB ceiling. The egui widget it replaces painted in the
+overlay's own process (0.05 ms a frame in Passive mode, 0.09 ms with its
+form) and repainted each second while a publication was pending; OverCrow
+read the rating whenever that widget was enabled, and now only while this
+widget subscribes. Scenarios render the same images on Linux and Windows,
+pixel for pixel.

package/dist/content/examples/playervox-rating/listing.json

@@ -0,0 +1,19 @@
+{
+  "author": "PlayerVox",
+  "spdxLicense": "MIT",
+  "sourceUrl": "https://github.com/Valhallab/playervox-overcrow-releases/tree/main/widgets/playervox-rating",
+  "preview": "assets/preview.png",
+  "defaultLocale": "en",
+  "localizations": [
+    {
+      "locale": "en",
+      "name": "My rating",
+      "description": "Your own PlayerVox rating of the Steam game you play: its grade and score, and in Interactive mode three criteria and an optional review to publish or update. Needs your PlayerVox account."
+    },
+    {
+      "locale": "fr",
+      "name": "Ma note",
+      "description": "Votre note PlayerVox du jeu Steam auquel vous jouez : son grade et son score, et en mode interactif trois critères et un avis facultatif à publier ou mettre à jour. Nécessite votre compte PlayerVox."
+    }
+  ]
+}

package/dist/content/examples/playervox-rating/locales/en.json

@@ -0,0 +1,35 @@
+{
+  "label": "My PlayerVox rating",
+  "title": "My rating",
+  "mark": "PlayerVox",
+  "waiting": "Waiting for a game",
+  "unsupported": "Game not linked",
+  "steam-required": "Steam game required",
+  "loading": "Loading…",
+  "unavailable": "Rating unavailable",
+  "retrying": "PlayerVox is unavailable for this game right now.",
+  "no-permission": "Allow access to your rating in the Control Center.",
+  "unrated": "Not rated yet",
+  "published": "Your published rating",
+  "draft": "Unpublished draft",
+  "gameplay": "Gameplay",
+  "art": "Art",
+  "tech": "Technology",
+  "grade": "Grade",
+  "no-grade": "No grade",
+  "review-optional": "REVIEW · OPTIONAL",
+  "review-label": "Review, optional",
+  "review-hint": "What stood out to you?",
+  "publish": "Publish my rating",
+  "update": "Update my rating",
+  "saving": "Saving…",
+  "saved": "Saved on PlayerVox",
+  "publish-hint": "Your rating and review will be visible on PlayerVox.",
+  "offline": "Offline · Your changes stay here until you save them.",
+  "error-invalid": "Check the values and try saving again.",
+  "error-expired": "Your connection expired. Link your account again.",
+  "error-busy": "An operation is already in progress. Please try again shortly.",
+  "error-stale": "The account or game changed. Review your changes before saving.",
+  "error-forbidden": "This action is not available for your account.",
+  "error-unavailable": "PlayerVox is unavailable for this game right now."
+}

package/dist/content/examples/playervox-rating/locales/fr.json

@@ -0,0 +1,35 @@
+{
+  "label": "Ma note PlayerVox",
+  "title": "Ma note",
+  "mark": "PlayerVox",
+  "waiting": "En attente du jeu",
+  "unsupported": "Jeu non associé",
+  "steam-required": "Jeu Steam requis",
+  "loading": "Chargement…",
+  "unavailable": "Note indisponible",
+  "retrying": "PlayerVox est indisponible pour ce jeu pour le moment.",
+  "no-permission": "Autorisez l’accès à votre note dans le Centre de contrôle.",
+  "unrated": "Pas encore noté",
+  "published": "Votre note publiée",
+  "draft": "Brouillon non publié",
+  "gameplay": "Gameplay",
+  "art": "Artistique",
+  "tech": "Technique",
+  "grade": "Note",
+  "no-grade": "Pas de note",
+  "review-optional": "AVIS · FACULTATIF",
+  "review-label": "Avis, facultatif",
+  "review-hint": "Qu’est-ce qui vous a marqué ?",
+  "publish": "Publier ma note",
+  "update": "Mettre à jour ma note",
+  "saving": "Enregistrement…",
+  "saved": "Enregistré sur PlayerVox",
+  "publish-hint": "Votre note et votre avis seront visibles sur PlayerVox.",
+  "offline": "Hors ligne · Vos modifications restent ici jusqu’à leur enregistrement.",
+  "error-invalid": "Vérifiez les valeurs et réessayez d’enregistrer.",
+  "error-expired": "Votre connexion a expiré. Reliez votre compte.",
+  "error-busy": "Une opération est en cours. Réessayez dans un instant.",
+  "error-stale": "Le compte ou le jeu a changé. Vérifiez vos modifications avant d’enregistrer.",
+  "error-forbidden": "Cette action n’est pas disponible pour votre compte.",
+  "error-unavailable": "PlayerVox est indisponible pour ce jeu pour le moment."
+}