@overcrow/mcp 0.0.0 → 0.1.0

package/dist/content/examples/media/README.md

@@ -0,0 +1,147 @@
+# Media
+
+`com.playervox.overcrow.media` — the track a music or video player of this
+computer is playing: its cover, its title in bold and its artists, and in
+Interactive mode the player's previous, play/pause and next buttons. 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 |
+| --- | --- |
+| A track | the square cover, the title in bold, the artists below it |
+| Playing / paused or stopped | the middle button shows pause ("Pause") / play ("Play", FR "Lire"); nothing else differs |
+| No cover, or it is loading | a raised square with a music note in its place |
+| No artist | the artist row is left out; the cover shrinks to the title's height |
+| No title | "Unknown title" / "Titre inconnu" |
+| No player | "No active media" / "Aucun média actif", with the cover's placeholder |
+| The player went away | the same: the previous track is gone at once |
+| The media source failed | "No active media" and, below it, "Media is temporarily unavailable." / "Le média est temporairement indisponible."; the widget asks again 5 s later |
+| No permission | "No active media": the widget asks OverCrow nothing |
+
+- The cover is square, cropped to its centre, with 6 px corners, as tall as
+  the title and artist rows beside it and centred on them.
+- Title and artists stay on one line each; line breaks in the player's text
+  become spaces. Several artists are joined with ", ".
+- A title wider than its column scrolls back and forth: it waits 2 s,
+  travels at 18 px/s (scaled with the content) until its end shows, waits
+  2 s, travels back. It restarts on a new title or a new width, and does
+  not move while the widget is hidden. With "Scroll long titles" off it
+  ends with an ellipsis. The artists never scroll: they end with an
+  ellipsis, and hovering them shows them whole.
+- The title's accessible name is the whole, unscrolled title; the cover and
+  its placeholder are "Cover artwork" / "Pochette".
+- The width is the one you set: a long title never widens the widget. The
+  height follows the content, and Passive mode, without buttons, is lower.
+
+The player's text is shown as it comes, in any language; only the widget's
+own messages and labels follow OverCrow's language.
+
+## Controls
+
+| Mode | Control | Does |
+| --- | --- | --- |
+| Interactive | Previous ("Previous" / "Précédent") | `media.previous` |
+| Interactive | Play or pause ("Play" / "Lire", "Pause") | `media.playPause` |
+| Interactive | Next ("Next" / "Suivant") | `media.next` |
+| Interactive | Enter or Space on a focused button | the same |
+| Interactive | Hover or focus a button, the title or the artists | its tooltip |
+| Passive | — | no buttons, no tooltips: the track only |
+
+A button shows only when the player offers its action: it is left out, not
+greyed. Each click is one call, on its own gesture (OverCrow refuses a call
+made outside one, `gesture_required`), and names the player shown. The
+player's new state arrives with the next update; a call OverCrow cannot
+apply — another player took over (`stale_context`), the player dropped the
+action (`unsupported`), no player (`unavailable`) — changes nothing on
+screen.
+
+## Menu
+
+| Row | Type | Default |
+| --- | --- | --- |
+| Show cover artwork / Afficher la pochette | toggle `show-cover` | on |
+| Scroll long titles / Faire défiler les titres longs | toggle `scroll-title` | on |
+
+With the cover off, the cover's slot goes, and the widget asks OverCrow for
+no cover: OverCrow then reads no cover file and contacts no image server
+for it.
+
+## Permissions
+
+- `media.read`: the current player's title, artists, playing state, the
+  actions it offers, and its cover as an image OverCrow decoded. Sensitive:
+  it tells what you listen to.
+- `media.control`: previous, play/pause and next. Sensitive. Without it the
+  widget shows no buttons.
+
+As sensitive capabilities rule out the network and the clipboard, the
+widget declares neither, and no storage: it keeps nothing.
+
+## Platforms
+
+| | Linux | Windows |
+| --- | --- | --- |
+| Source | MPRIS players on the session bus | the system's current media session |
+| Which player | the playing one, else a paused one, else a stopped one; on a tie the first by bus name | the one Windows shows as current |
+| Artists | up to 8, joined with ", " | the one text the player gives |
+| Cover | the player's art URL: a local file in a cache, music or temporary folder, or an image from Spotify, YouTube or Tidal | the session's thumbnail |
+
+OverCrow runs its media source only while a widget subscribes, and loads
+covers only for a widget that asks for them. It hands the widget a cover
+of at most 256 px as an `asset:` handle: the widget never sees a URL, a
+file path or a player's bus name. The same values give the same pixels on
+both systems.
+
+## How it works
+
+`media.subscribe({ cover })` gives `null` without a player, or `{ player,
+title, artists, playing, canPrevious, canPlayPause, canNext, cover }`;
+`player` is an opaque ID the buttons pass back. The view draws `cover` with
+an `image` and the title with `text-overflow: marquee`: OverCrow measures,
+scrolls and holds it, so the widget runs no timer and sends nothing while a
+title scrolls. When OverCrow's media source fails, the subscription ends
+with `unavailable`; the widget shows it and subscribes again after 5 s,
+which restarts the source.
+
+## Tests
+
+- `tests/logic.test.mjs`, `tests/refused.test.mjs`: the logic on
+  `@overcrow/sdk/testing`.
+- Scenarios with their reference images, covers drawn by
+  `tests/assets/generate.mjs` (synthetic images, no real album art):
+  - `render`: a playing track with its cover and buttons, in both themes and
+    languages at 100 and 150 %, and in Passive mode;
+  - `states`: no player, paused, no artist, unknown title (EN, FR), only
+    play/pause, no button, no cover (dark, light), the player gone;
+  - `covers`: a square cover, a wide one cropped to its centre, a new
+    track's cover, the cover option off and on (and the subscription it
+    makes);
+  - `marquee`: the pause at the start, the travel, the pause at the end, the
+    way back, the ellipsis with the option off, 150 %;
+  - `gesture`: Passive clicks call nothing; each button by click, Enter and
+    Space, with its player; refusals; a tooltip;
+  - `unavailable`: the failure's message (EN, FR), the new subscription
+    5 s later and the player it brings;
+  - `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),
+at 320 px wide with a 256 px cover:
+
+| | Linux | Windows (VM) |
+| --- | --- | --- |
+| Widget start, warm, into the overlay's runtime | 6.9 ms (p50), 8.0 ms at most | VM ready in 14 ms (p50) |
+| VM memory, cover included | 0.64 MiB private, 0.82 MiB PSS: the VM holds the cover's handle, not its pixels | 0.90 MiB private working set, 1.18 MiB private commit |
+| Private memory in all (VM, sandbox helpers, overlay share with the cover) | under 7 MB | — |
+| CPU, a track held | 0.03 % of one core, no frame | — |
+| CPU, a long title scrolling | 0.15 % of one core: one frame per physical pixel it moves (18 a second at 100 %), 0.07 ms each, none during its pauses | — |
+| CPU, a new track and cover every 2 s | 0.05 % of one core: one frame per track | — |
+| VM CPU | one short turn per track; none while a title scrolls | — |
+
+The egui widget it replaces repainted a scrolling title at 30 Hz (0.04 ms
+each, painting only), inside the overlay's own process, and OverCrow polled
+the players every second whatever the widgets showed.

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

@@ -0,0 +1,19 @@
+{
+  "author": "PlayerVox",
+  "spdxLicense": "MIT",
+  "sourceUrl": "https://github.com/Valhallab/playervox-overcrow-releases/tree/main/widgets/media",
+  "preview": "assets/preview.png",
+  "defaultLocale": "en",
+  "localizations": [
+    {
+      "locale": "en",
+      "name": "Media",
+      "description": "The track your music player is playing, with its cover, and previous, play/pause and next buttons in Interactive mode."
+    },
+    {
+      "locale": "fr",
+      "name": "Média",
+      "description": "Le morceau que joue votre lecteur de musique, avec sa pochette, et les boutons précédent, lecture/pause et suivant en mode interactif."
+    }
+  ]
+}

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

@@ -0,0 +1,11 @@
+{
+  "label": "Media",
+  "no-media": "No active media",
+  "unavailable": "Media is temporarily unavailable.",
+  "unknown-title": "Unknown title",
+  "cover": "Cover artwork",
+  "previous": "Previous",
+  "play": "Play",
+  "pause": "Pause",
+  "next": "Next"
+}

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

@@ -0,0 +1,11 @@
+{
+  "label": "Média",
+  "no-media": "Aucun média actif",
+  "unavailable": "Le média est temporairement indisponible.",
+  "unknown-title": "Titre inconnu",
+  "cover": "Pochette",
+  "previous": "Précédent",
+  "play": "Lire",
+  "pause": "Pause",
+  "next": "Suivant"
+}

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

@@ -0,0 +1,191 @@
+// Media: the track a desktop player is playing, its cover and, in
+// Interactive mode, the player's previous / play-pause / next buttons. The
+// host picks the player (MPRIS on Linux, the system's current session on
+// Windows), decodes the cover into an `asset:` handle and scrolls an
+// overflowing title (`text-overflow: marquee`): the widget only lays out.
+import {
+  hasGrant,
+  host,
+  initState,
+  media,
+  onHost,
+  option,
+  t,
+  timers,
+  type Media,
+  type Subscription,
+  type Timer,
+} from "@overcrow/sdk";
+
+declare module "@overcrow/sdk" {
+  interface WidgetState {
+    /** The current player, or `null` without one. */
+    media: Media | null;
+    /** The host's media source failed; it retries on the next subscription. */
+    unavailable: boolean;
+    /** The buttons take input only in Interactive mode. */
+    interactive: boolean;
+    showCover: boolean;
+    scrollTitle: boolean;
+  }
+}
+
+/**
+ * After the host ends the subscription with a failure (its media source
+ * failed), the widget subscribes again this much later; the host restarts
+ * its source for the new subscription.
+ */
+export const RETRY_MS = 5_000;
+
+const canRead = hasGrant("media.read");
+const canControl = hasGrant("media.control");
+
+const state = initState({
+  media: null as Media | null,
+  unavailable: false,
+  interactive: host.mode === "interactive",
+  showCover: option("show-cover", true),
+  scrollTitle: option("scroll-title", true),
+});
+
+/** Provider text on one line: line breaks never make a second row. */
+export function oneLine(text: string): string {
+  return text.replace(/\s*[\r\n]+\s*/g, " ").trim();
+}
+
+/** The title, or "Unknown title" without one. */
+export function title(current: Media): string {
+  const text = current.title === null ? "" : oneLine(current.title);
+  return text === "" ? t("unknown-title") : text;
+}
+
+/** The artists on one line, or nothing: the row is then left out. */
+export function artists(current: Media): string {
+  return current.artists
+    .map(oneLine)
+    .filter((artist) => artist !== "")
+    .join(", ");
+}
+
+/**
+ * The cover's size class: as tall as the title and artist rows, or as one
+ * row without artists or without a player (the placeholder).
+ */
+export function coverClass(current: Media | null, cover: string | null): string {
+  const size = current !== null && artists(current) !== "" ? "cover tall" : "cover short";
+  return cover === null ? `${size} placeholder` : size;
+}
+
+/** The title scrolls when it overflows, or ends with an ellipsis. */
+export function titleClass(scroll: boolean): string {
+  return scroll ? "title scrolling" : "title";
+}
+
+export function rootClass(showCover: boolean): string {
+  return showCover ? "media with-cover" : "media";
+}
+
+/** One transport button. */
+export interface Control {
+  key: "previous" | "play-pause" | "next";
+  icon: string;
+  label: string;
+}
+
+/**
+ * The buttons the player supports, in the order previous, play/pause,
+ * next: an unsupported action has no button. None in Passive mode or
+ * without the control grant.
+ */
+export function controls(current: Media | null, interactive: boolean): Control[] {
+  if (!interactive || !canControl || current === null) {
+    return [];
+  }
+  const list: Control[] = [];
+  if (current.canPrevious) {
+    list.push({ key: "previous", icon: "skip-back", label: t("previous") });
+  }
+  if (current.canPlayPause) {
+    list.push(
+      current.playing
+        ? { key: "play-pause", icon: "pause", label: t("pause") }
+        : { key: "play-pause", icon: "play", label: t("play") },
+    );
+  }
+  if (current.canNext) {
+    list.push({ key: "next", icon: "skip-forward", label: t("next") });
+  }
+  return list;
+}
+
+/**
+ * Sends a button's action to the player shown. The host refuses it with
+ * `stale_context` when another player replaced it meanwhile and with
+ * `unsupported` when the player no longer offers the action; the next
+ * update shows the player's state either way, so a failure shows nothing.
+ */
+export function activate(key: Control["key"]): void {
+  const current = state.media;
+  if (current === null) {
+    return;
+  }
+  const params = { player: current.player };
+  const call =
+    key === "previous" ? media.previous(params) : key === "next" ? media.next(params) : media.playPause(params);
+  call.catch(() => {});
+}
+
+let subscription: Subscription | null = null;
+let retry: Timer | null = null;
+
+function subscribe(): void {
+  retry = null;
+  const current = media.subscribe({ cover: state.showCover }, (update) => {
+    if (update.ok) {
+      state.media = update.value;
+      state.unavailable = false;
+      return;
+    }
+    // The subscription ended: the host's source failed. Show it and ask
+    // again later; hidden, the timer waits until the widget shows.
+    if (subscription === current) {
+      subscription = null;
+      state.media = null;
+      state.unavailable = true;
+      retry = timers.after(RETRY_MS, subscribe);
+    }
+  });
+  subscription = current;
+}
+
+/** Subscribes again, for the cover option; the host sends the value at once. */
+function resubscribe(): void {
+  retry?.cancel();
+  retry = null;
+  subscription?.cancel();
+  subscription = null;
+  subscribe();
+}
+
+onHost((changed) => {
+  if (changed.includes("mode")) {
+    state.interactive = host.mode === "interactive";
+  }
+  if (changed.includes("options")) {
+    state.scrollTitle = option("scroll-title", true);
+    const showCover = option("show-cover", true);
+    if (showCover !== state.showCover) {
+      state.showCover = showCover;
+      // Without the cover the host loads none: the subscription says so.
+      if (canRead && !state.unavailable) {
+        resubscribe();
+      }
+    }
+  }
+});
+
+// Without the grant the host would refuse the subscription: show that no
+// media plays instead of asking.
+if (canRead) {
+  subscribe();
+}

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

@@ -0,0 +1,35 @@
+{
+  "schemaVersion": 1,
+  "apiVersion": 1,
+  "id": "com.playervox.overcrow.media",
+  "version": "1.0.2",
+  "name": {
+    "en": "Media",
+    "fr": "Média"
+  },
+  "sizing": {
+    "fit": "height",
+    "preferred": { "width": 320, "height": 160 },
+    "min": { "width": 160, "height": 24 },
+    "max": { "width": 900, "height": 240 }
+  },
+  "permissions": {
+    "capabilities": ["media.read", "media.control"]
+  },
+  "wrapper": {
+    "menu": [
+      {
+        "type": "toggle",
+        "id": "show-cover",
+        "label": { "en": "Show cover artwork", "fr": "Afficher la pochette" },
+        "default": true
+      },
+      {
+        "type": "toggle",
+        "id": "scroll-title",
+        "label": { "en": "Scroll long titles", "fr": "Faire défiler les titres longs" },
+        "default": true
+      }
+    ]
+  }
+}

package/dist/content/examples/media/package.json

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

@@ -0,0 +1,148 @@
+/* The cover on the left, as tall as the title and artist rows and centred
+   on them; the text column beside it, the buttons and the source message
+   under the text. 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), 8 px
+   beside the cover and 2 px between the rows. The width is the user's:
+   long text never widens the panel. */
+.media {
+  display: grid;
+  grid-template-columns: minmax(0px, 1fr);
+  column-gap: 8px;
+  row-gap: 2px;
+  padding: 0 2px;
+}
+
+.with-cover {
+  grid-template-columns: auto minmax(0px, 1fr);
+}
+
+.with-cover .cover {
+  grid-column: 1;
+  grid-row: 1;
+}
+
+.with-cover .meta,
+.with-cover .controls,
+.with-cover .message {
+  grid-column: 2;
+}
+
+.with-cover .meta {
+  grid-row: 1;
+}
+
+/* Fixed line heights keep the cover exactly as tall as the rows beside
+   it: 18 px for the title, 2 px, 16 px for the artists. */
+.cover {
+  align-self: center;
+  border-radius: var(--radius-sm);
+  object-fit: cover;
+  overflow: hidden;
+}
+
+.cover.tall {
+  width: 36px;
+  height: 36px;
+}
+
+.cover.short {
+  width: 18px;
+  height: 18px;
+}
+
+/* No cover: the music icon on a raised square, inset by 28 %. */
+.placeholder {
+  background: var(--color-surface-raised);
+  align-items: center;
+  justify-content: center;
+  color: var(--color-text-muted);
+}
+
+.cover-icon {
+  width: 44%;
+  height: 44%;
+}
+
+.meta {
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0px;
+}
+
+.title {
+  font-family: var(--font-ui);
+  font-size: var(--font-size-body);
+  font-weight: 700;
+  line-height: 18px;
+  color: var(--color-text);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.title.scrolling {
+  text-overflow: marquee;
+}
+
+.artist {
+  font-family: var(--font-ui);
+  font-size: 12px;
+  line-height: 16px;
+  color: var(--color-text-muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.empty {
+  font-family: var(--font-ui);
+  font-size: var(--font-size-body);
+  line-height: 18px;
+  color: var(--color-text-muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.message {
+  font-family: var(--font-ui);
+  font-size: var(--font-size-small);
+  color: var(--color-text-muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.controls {
+  flex-direction: row;
+  gap: 3px;
+}
+
+/* The built-in's compact icon buttons: raised with a border, lighter under
+   the pointer or with the keyboard focus, the accent while pressed. The
+   icon (sized by `font-size`) fills the 12 px content box exactly and is
+   centred in it. */
+.control {
+  width: var(--icon-button-size);
+  height: var(--icon-button-size);
+  padding: 4px;
+  border: 1px solid var(--color-border);
+  font-size: 12px;
+  justify-content: center;
+  align-items: center;
+  border-radius: var(--radius-sm);
+  background: var(--color-surface-raised);
+  color: var(--color-text-secondary);
+}
+
+.control:hover,
+.control:focus {
+  background: var(--color-surface-hover);
+  color: var(--color-text);
+}
+
+.control:active {
+  background: var(--color-accent-soft);
+  border-color: var(--color-accent);
+  color: var(--color-accent-hover);
+}