@overcrow/mcp 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,192 @@
+{
+  "scenarioVersion": 1,
+  "name": "unavailable",
+  "description": "OverCrow ends the subscription when its reviews source fails: the widget says so, keeps nothing of the page it showed, and subscribes again five seconds later; hidden, it waits until it shows again.",
+  "fixtures": {
+    "calls": {
+      "playervox.reviews.page": [
+        {
+          "value": {
+            "gameName": "Portal 2",
+            "items": [
+              {
+                "id": "r31",
+                "author": "Mira_Quill",
+                "grade": "S+",
+                "score": 94,
+                "text": "The co-op campaign is the best puzzle design I have played in years. Every chamber teaches one idea, then twists it twice before letting you go, and the writing never gets in the way of the thinking. My only complaint is the loading between chambers.",
+                "original": null,
+                "hidden": false,
+                "publishedAt": 1789900200000,
+                "offsetMinutes": 120
+              },
+              {
+                "id": "r30",
+                "author": "Kestrel42",
+                "grade": "A",
+                "score": 74,
+                "text": "Solid puzzles, short story.",
+                "original": null,
+                "hidden": false,
+                "publishedAt": 1789813800000,
+                "offsetMinutes": 120
+              },
+              {
+                "id": "r29",
+                "author": "Tavish",
+                "grade": "D",
+                "score": 38,
+                "text": "Runs badly on my laptop.\nCrashed twice in chapter 3.",
+                "original": null,
+                "hidden": false,
+                "publishedAt": 1789381800000,
+                "offsetMinutes": 120
+              }
+            ],
+            "page": 1,
+            "totalPages": 3,
+            "count": 7
+          }
+        }
+      ]
+    }
+  },
+  "steps": [
+    {
+      "expect": {
+        "text": [
+          "Loading…"
+        ],
+        "calls": [
+          {
+            "service": "playervox.reviews.subscribe"
+          }
+        ]
+      }
+    },
+    {
+      "publish": {
+        "service": "playervox.reviews.subscribe",
+        "error": "unavailable"
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "The reviews are unavailable. Retrying automatically."
+        ],
+        "noText": [
+          "Loading…"
+        ],
+        "image": "source-failed",
+        "calls": []
+      }
+    },
+    {
+      "advance": {
+        "ms": 4900
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "The reviews are unavailable. Retrying automatically."
+        ],
+        "calls": []
+      }
+    },
+    {
+      "advance": {
+        "ms": 100
+      }
+    },
+    {
+      "expect": {
+        "calls": [
+          {
+            "service": "playervox.reviews.subscribe"
+          }
+        ]
+      }
+    },
+    {
+      "publish": {
+        "service": "playervox.reviews.subscribe",
+        "value": {
+          "state": "ready",
+          "revision": 1,
+          "offline": false
+        }
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "7 reviews",
+          "Mira_Quill"
+        ],
+        "noText": [
+          "The reviews are unavailable. Retrying automatically."
+        ],
+        "image": "recovered",
+        "calls": [
+          {
+            "service": "playervox.reviews.page",
+            "params": {
+              "page": 1,
+              "followedOnly": false
+            },
+            "outcome": "ok"
+          }
+        ]
+      }
+    },
+    {
+      "publish": {
+        "service": "playervox.reviews.subscribe",
+        "error": "unavailable"
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "The reviews are unavailable. Retrying automatically."
+        ],
+        "noText": [
+          "7 reviews",
+          "Mira_Quill",
+          "Portal 2"
+        ]
+      }
+    },
+    {
+      "host": {
+        "visible": false
+      }
+    },
+    {
+      "advance": {
+        "ms": 60000
+      }
+    },
+    {
+      "expect": {
+        "calls": []
+      }
+    },
+    {
+      "host": {
+        "visible": true
+      }
+    },
+    {
+      "expect": {
+        "calls": [
+          {
+            "service": "playervox.reviews.subscribe"
+          }
+        ]
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,110 @@
+<!-- Player reviews: three PlayerVox reviews of the active game per page,
+     each with its player's grade badge, name, date, score and text, and
+     the paging footer (parity sheet: playervox-overcrow
+     docs/builtin-parity/playervox-circle.md). The buttons show in
+     Interactive mode. A page holds at most three reviews, so each has its
+     own badge canvas, passed to the card through its slot. -->
+<component name="review-card" props="row">
+  <separator class="rule"/>
+  <box class="review" label={row.label}>
+    <box class="head">
+      <slot/>
+      <box class="who">
+        <text class="author" tooltip={row.authorTip}>{row.author}</text>
+        <text class="date">{row.date}</text>
+      </box>
+      <text class="score">{row.score}</text>
+    </box>
+    <if test={row.masked}>
+      <text class="note">{t("hidden")}</text>
+      <if test={state.interactive}>
+        <box class="actions">
+          <button class="link" on:activate={reveal(row.id)}>
+            <text class="link-text">{t("reveal")}</text>
+          </button>
+        </box>
+      </if>
+    </if>
+    <else-if test={row.text != ""}>
+      <text class={row.textClass}>{row.text}</text>
+      <if test={row.actions}>
+        <box class="actions">
+          <if test={row.fold != ""}>
+            <button class="link" on:activate={toggleFold(row.id)}>
+              <text class="link-text">{row.fold}</text>
+            </button>
+          </if>
+          <if test={row.translated}>
+            <text class="note">{t("translated")}</text>
+          </if>
+          <if test={row.language != ""}>
+            <button class="link" on:activate={toggleLanguage(row.id)}>
+              <text class="link-text">{row.language}</text>
+            </button>
+          </if>
+        </box>
+      </if>
+      <else-if test={row.translated}>
+        <text class="note">{t("translated")}</text>
+      </else-if>
+    </else-if>
+  </box>
+</component>
+
+<box class={state.offline ? "reviews offline" : "reviews"} label={t("label")}>
+  <box class="header">
+    <text class="title">{t("label")}</text>
+    <canvas ref="mark" class="mark" label={t("mark")}/>
+  </box>
+  <if test={gameName(state.page) != ""}>
+    <text class="game" tooltip={cutBytes(gameName(state.page), 256)}>{gameName(state.page)}</text>
+  </if>
+  <if test={message(state.problem) != ""}>
+    <text class="message">{message(state.problem)}</text>
+  </if>
+  <if test={state.phase == "loading"}>
+    <text class="status">{state.offline ? t("offline") : t("loading")}</text>
+  </if>
+  <if test={state.phase == "idle"}>
+    <text class="status">{t("waiting")}</text>
+  </if>
+  <if test={state.phase == "unsupported"}>
+    <text class="status">{t("unsupported")}</text>
+  </if>
+  <if test={state.phase == "ready"}>
+    <if test={!has(state.page, 0)}>
+      <text class="status">{emptyText(state.followedOnly)}</text>
+    </if>
+    <else>
+      <scroll class="list">
+        <review-card row={row(state.page, state.reading, state.interactive, 0)}>
+          <canvas ref="badge-0" class="grade" label={row(state.page, state.reading, state.interactive, 0).badge}/>
+        </review-card>
+        <if test={has(state.page, 1)}>
+          <review-card row={row(state.page, state.reading, state.interactive, 1)}>
+            <canvas ref="badge-1" class="grade" label={row(state.page, state.reading, state.interactive, 1).badge}/>
+          </review-card>
+        </if>
+        <if test={has(state.page, 2)}>
+          <review-card row={row(state.page, state.reading, state.interactive, 2)}>
+            <canvas ref="badge-2" class="grade" label={row(state.page, state.reading, state.interactive, 2).badge}/>
+          </review-card>
+        </if>
+      </scroll>
+      <box class="footer">
+        <text class="count">{countText(state.page)}</text>
+        <if test={state.interactive}>
+          <button class="control" label={t("previous")} tooltip={t("previous")} disabled={!canTurn(state.page, "previous", state.busy, state.offline)} on:activate={turn("previous")}>
+            <icon name="chevron-left"/>
+          </button>
+        </if>
+        <text class="pager" label={pagerLabel(state.page)} tooltip={t("page")}>{pagerText(state.page)}</text>
+        <if test={state.interactive}>
+          <button class="control" label={t("next")} tooltip={t("next")} disabled={!canTurn(state.page, "next", state.busy, state.offline)} on:activate={turn("next")}>
+            <icon name="chevron-right"/>
+          </button>
+        </if>
+      </box>
+    </else>
+  </if>
+</box>

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

@@ -0,0 +1,131 @@
+# PlayerVox score
+
+`com.playervox.overcrow.playervox.score` — the public PlayerVox community
+grade of the Steam game you play: a grade badge (S+ to F), the rounded
+overall score out of 100, the game's name on PlayerVox, the rating count
+and, if you want, the Gameplay, Art and Technology criteria. No PlayerVox
+account is needed. 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 badge, "94 /100", "1,284 ratings", the game's name |
+| Not rated yet | a neutral `--` badge, "Not rated yet" / "Pas encore noté", "No ratings yet" / "Aucun vote", the game's name |
+| Waiting for PlayerVox | a `--` badge and "Loading…" / "Chargement…": after a game switch, never the previous game's score |
+| 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" |
+| A game PlayerVox does not know, or cannot tell apart | "Game not found" / "Jeu introuvable", "On PlayerVox" / "Sur PlayerVox" |
+| PlayerVox unreachable, busy or failing | "Score unavailable" / "Note indisponible", "Retrying automatically" / "Nouvel essai automatique"; an earlier score is not kept |
+| No permission | "Score unavailable": the widget asks OverCrow nothing |
+
+Without a score the title reads "Community rating" / "Note communautaire".
+A status's second line shows only with the rating count option on.
+
+- **The badge.** A 56 px rounded square with a black face and a 3 px border
+  in the grade's colour, turned by 4° with its letter in the display face.
+  `--` is square, grey on a translucent face. S+ has a faint static glow.
+  The badge is drawn by the widget in a canvas, from the source it shares
+  with PlayerVox Rating ([widgets-shared](../../widgets-shared/README.md)).
+- **Grades** come from OverCrow, on the raw score: S+ ≥ 90, S ≥ 80,
+  A ≥ 70, B ≥ 60, C ≥ 40, D ≥ 20, else F. 89.6 shows "90" with grade S.
+  Numbers round half away from zero (72.5 shows 73).
+
+  | Grade | S+ | S | A | B | C | D | F, `--` |
+  | --- | --- | --- | --- | --- | --- | --- | --- |
+  | Colour | `#9ae600` | `#7ccf00` | `#00d3f3` | `#fdc700` | `#fe9a00` | `#e7000b` | `#52525c` |
+
+  The same colours serve both themes: the badge keeps its black face on a
+  light panel.
+- **The pulse.** When a score shows or changes (another grade or number),
+  the badge grows to 108 % and back once, in 600 ms. OverCrow animates it:
+  the widget sends one class change, nothing moves once it ends, and a
+  hidden widget draws nothing. A new rating count alone, a status or `--`
+  never pulses.
+- **The count** uses your number format ("1,284 ratings", FR "1 284 votes"),
+  in the singular only for exactly one.
+- **The criteria**, 220 px wide: the name, the rounded value or `--` when
+  PlayerVox has none (a real 0 shows "0"), and a 3 px bar in the colour of
+  that value's own grade.
+- **The title** stays on one line, ending with an ellipsis. The PlayerVox
+  mark keeps the header's right corner, the title shown or not. Hovering
+  the widget shows the game's name, or the status.
+- **Accessible names:** the badge "Grade S+, 94/100" / "Note S+, 94/100" or
+  "No grade" / "Pas de note"; each bar "Gameplay: 97".
+- **Size.** Fitted to its content, 64 to 220 px of content wide (220 with
+  the criteria), within the host frame and its 10 × 8 px margin; the badge
+  alone is a 64 px square within the frame's 8 px margin.
+
+## Controls
+
+None: no click, no key. In Interactive mode the host moves and resizes the
+widget; hovering shows the tooltip.
+
+## Menu
+
+| Row | Type | Default |
+| --- | --- | --- |
+| Show overall score / Afficher le score global | toggle `show-score` | on |
+| Show three criteria / Afficher les trois critères | toggle `show-criteria` | off |
+| Show game title / Afficher le nom du jeu | toggle `show-title` | on |
+| Show rating count / Afficher le nombre de notes | toggle `show-votes` | on |
+
+No row hides the badge. With every row off, the widget is the badge alone;
+set the background opacity to 0 % for the look without a panel (OverCrow
+does so when it moves an egui badge-only Score to this widget).
+
+## Permissions
+
+- `playervox.score.read`: the public PlayerVox score of the active game.
+  Sensitive: the score and the game's name tell which game you play.
+
+As a sensitive capability rules out the network and the clipboard, the
+widget declares neither, and no storage: it keeps nothing. OverCrow fetches
+the score (`api.playervox.com`, anonymously), refreshes it every five
+minutes and on PlayerVox's live updates, and backs off after failures; it
+does so only while this widget subscribes.
+
+## Tests
+
+- `tests/logic.test.mjs`: the logic on `@overcrow/sdk/testing`: the badge's
+  commands per grade, one pulse per new score, rounding, the count's
+  plural and number format, every state's text, the tooltip's bound, the
+  criteria, the options and the retry.
+- Scenarios, played in OverCrow's headless runtime
+  (`overcrow-widget test --runtime …`), with their reference images in
+  `tests/reference/`:
+
+  | Scenario | Covers |
+  | --- | --- |
+  | `states` | every state, dark English and light French, 100 % and 150 % |
+  | `grades` | the seven grades with the criteria, a real 0, missing criteria, rounding, light theme, 150 % in French |
+  | `options` | the badge alone (both themes, 150 %), each toggle, a long title, a large count, a single rating |
+  | `pulse` | the pulse's peak and end, none for the same score or a status |
+  | `unavailable` | the host's source failing, then the new subscription 5 s later |
+  | `refused` | no grant: no call, "Score unavailable" |
+  | `signed-out` | signed out of PlayerVox: the score, no account panel |
+
+## 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),
+with a rated game and the default rows:
+
+| | Linux | Windows (VM) |
+| --- | --- | --- |
+| Widget start, warm, into the overlay's runtime | 8.5 ms (p50), 12.4 ms at most | VM ready in 16–20 ms (p50) |
+| VM memory | 0.73 MiB private, 0.91 MiB PSS | 1.08 MiB private working set, 1.36 MiB private commit |
+| Private memory in all (VM, sandbox helpers, overlay share) | 6.5–8.6 MB | — |
+| CPU, a score held | 0.03 % of one core, no frame | — |
+| CPU, a new score and its pulse every 2 s | 0.23 % of one core: about 36 frames of 0.05 ms per pulse, then none | — |
+| CPU, hidden, a new score every 2 s | 0.05–0.07 % of one core: no pulse frame | — |
+| VM CPU | one short turn per score; none during the pulse | — |
+
+Scores change only when PlayerVox publishes an update or at the five-minute
+refresh: the 2 s load is a stress. The egui widget it replaces had no pulse
+and painted in the overlay's own process (0.04 ms a frame); OverCrow fetched
+the score 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-score/listing.json

@@ -0,0 +1,19 @@
+{
+  "author": "PlayerVox",
+  "spdxLicense": "MIT",
+  "sourceUrl": "https://github.com/Valhallab/playervox-overcrow-releases/tree/main/widgets/playervox-score",
+  "preview": "assets/preview.png",
+  "defaultLocale": "en",
+  "localizations": [
+    {
+      "locale": "en",
+      "name": "PlayerVox score",
+      "description": "The PlayerVox community grade of your Steam game, with its score, rating count and three criteria. No account needed; the badge is always shown."
+    },
+    {
+      "locale": "fr",
+      "name": "Note PlayerVox",
+      "description": "La note de la communauté PlayerVox pour votre jeu Steam, avec son score, son nombre de votes et trois critères. Sans compte ; le badge reste toujours visible."
+    }
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "label": "PlayerVox score",
+  "community": "Community rating",
+  "mark": "PlayerVox",
+  "waiting": "Waiting for a game",
+  "unsupported": "Game not linked",
+  "steam-required": "Steam game required",
+  "loading": "Loading…",
+  "unrated": "Not rated yet",
+  "no-votes": "No ratings yet",
+  "not-found": "Game not found",
+  "on-playervox": "On PlayerVox",
+  "unavailable": "Score unavailable",
+  "retrying": "Retrying automatically",
+  "votes-one": "{count} rating",
+  "votes-other": "{count} ratings",
+  "gameplay": "Gameplay",
+  "art": "Art",
+  "tech": "Technology",
+  "grade": "Grade",
+  "no-grade": "No grade",
+  "criterion": "{name}: {value}"
+}

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

@@ -0,0 +1,23 @@
+{
+  "label": "Note PlayerVox",
+  "community": "Note communautaire",
+  "mark": "PlayerVox",
+  "waiting": "En attente du jeu",
+  "unsupported": "Jeu non associé",
+  "steam-required": "Jeu Steam requis",
+  "loading": "Chargement…",
+  "unrated": "Pas encore noté",
+  "no-votes": "Aucun vote",
+  "not-found": "Jeu introuvable",
+  "on-playervox": "Sur PlayerVox",
+  "unavailable": "Note indisponible",
+  "retrying": "Nouvel essai automatique",
+  "votes-one": "{count} vote",
+  "votes-other": "{count} votes",
+  "gameplay": "Gameplay",
+  "art": "Artistique",
+  "tech": "Technique",
+  "grade": "Note",
+  "no-grade": "Pas de note",
+  "criterion": "{name} : {value}"
+}