@overcrow/mcp 0.0.0 → 0.1.1

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);
+}

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

@@ -0,0 +1,12 @@
+{
+  "justifications": [
+    {
+      "permission": "capability:media.read",
+      "text": "Reads the track, artist and cover your music player is playing, to show them."
+    },
+    {
+      "permission": "capability:media.control",
+      "text": "Sends previous, play/pause and next to your music player when you click the widget's buttons in Interactive mode."
+    }
+  ]
+}

package/dist/content/examples/media/tests/covers.scenario.json

@@ -0,0 +1,144 @@
+{
+  "scenarioVersion": 1,
+  "name": "covers",
+  "description": "The host's cover, square or cropped to its centre, a new track's cover, then the cover option off (no slot, and the widget asks the host for none) and on again.",
+  "host": {
+    "mode": "interactive"
+  },
+  "assets": {
+    "aurora": "tests/assets/aurora.png",
+    "horizon": "tests/assets/horizon.png",
+    "tiles": "tests/assets/tiles.png"
+  },
+  "fixtures": {
+    "subscriptions": {
+      "media.subscribe": {
+        "player": "p1",
+        "title": "Beyond the northern lights",
+        "artists": [
+          "The Quiet Expedition"
+        ],
+        "playing": true,
+        "canPrevious": true,
+        "canPlayPause": true,
+        "canNext": true,
+        "cover": "fixture:aurora"
+      }
+    }
+  },
+  "steps": [
+    {
+      "expect": {
+        "state": "running",
+        "calls": [
+          {
+            "service": "media.subscribe",
+            "params": {
+              "cover": true
+            },
+            "outcome": "ok"
+          }
+        ],
+        "image": "square"
+      }
+    },
+    {
+      "publish": {
+        "service": "media.subscribe",
+        "value": {
+          "player": "p1",
+          "title": "Horizon line",
+          "artists": [
+            "The Quiet Expedition"
+          ],
+          "playing": true,
+          "canPrevious": true,
+          "canPlayPause": true,
+          "canNext": true,
+          "cover": "fixture:horizon"
+        }
+      }
+    },
+    {
+      "expect": {
+        "image": "cropped"
+      }
+    },
+    {
+      "publish": {
+        "service": "media.subscribe",
+        "value": {
+          "player": "p1",
+          "title": "Next track",
+          "artists": [
+            "Another band",
+            "A guest"
+          ],
+          "playing": true,
+          "canPrevious": true,
+          "canPlayPause": true,
+          "canNext": true,
+          "cover": "fixture:tiles"
+        }
+      }
+    },
+    {
+      "expect": {
+        "text": [
+          "Next track",
+          "Another band, A guest"
+        ],
+        "image": "next-track"
+      }
+    },
+    {
+      "menu": {
+        "id": "show-cover",
+        "value": false
+      }
+    },
+    {
+      "expect": {
+        "calls": [
+          {
+            "service": "subscription.cancel",
+            "outcome": "ok"
+          },
+          {
+            "service": "media.subscribe",
+            "params": {
+              "cover": false
+            },
+            "outcome": "ok"
+          }
+        ],
+        "image": "cover-off"
+      }
+    },
+    {
+      "menu": {
+        "id": "show-cover",
+        "value": true
+      }
+    },
+    {
+      "expect": {
+        "calls": [
+          {
+            "service": "subscription.cancel",
+            "outcome": "ok"
+          },
+          {
+            "service": "media.subscribe",
+            "params": {
+              "cover": true
+            },
+            "outcome": "ok"
+          }
+        ],
+        "image": "cover-on",
+        "fault": "none"
+      }
+    }
+  ]
+}