Wallive Plugin SDK

TypeScript helpers for building Wallive Island plugins. The SDK wraps Wallive's JSONL stdio protocol; it does not render UI and does not replace the wallivePlugin manifest.

Minimal Plugin

import { createWallivePlugin } from "@wallive/plugin-sdk";

const plugin = createWallivePlugin();

plugin.onAction(({ action }) => {
  plugin.completeAction(action);
});

plugin.ready();
plugin.display({
  id: "hello",
  title: "Hello from SDK",
  state: "success",
  content: {
    type: "message",
    body: "Rendered by Wallive",
  },
  placements: [{ type: "overlay", style: "toast" }],
});

plugin.start();

Manifest v2 Helper

Use definePluginManifest() from a build script or package-generation step to keep runtime, capabilities, and contributions aligned. It returns JSON-safe data for package.json#wallivePlugin.

import {
  commandActivation,
  definePluginManifest,
  windowContribution,
} from "@wallive/plugin-sdk";

export const wallivePlugin = definePluginManifest({
  id: "com.example.workflow",
  displayName: "Workflow",
  entry: "dist/index.js",
  capabilities: {
    hostAPIs: ["display"],
    placements: ["presence"],
  },
  commands: [{
    id: "open",
    title: "Open Workflow",
    activation: commandActivation("window", { windowID: "main" }),
  }],
  windows: [
    windowContribution("main", { title: "Workflow", defaultSize: "wide", primary: true }),
  ],
});

The helper always emits a background runtime and infers missing host APIs, placements, and triggers from legacy permissions plus declared commands, windows, providers, and explicit Display placements. For example, declaring placements: ["activity", "body", "window"] also emits the display host API so display.upsert is not rejected by the host API gate. Legacy permissions: ["presentation"] grants Display API compatibility and legacy Island placements, but it does not grant window; plugin windows require a window placement capability plus a primary/default windows[] contribution. Window command activations must have that primary/default contribution, and an explicit windowID must match it. You can still pass explicit capabilities when a plugin needs a broader static maximum.

Display v2

New plugins should publish semantic Display v2 items with plugin.display(). Wallive owns native rendering, placement arbitration, Island layout, and plugin window chrome.

plugin.display({
  id: "download",
  title: "Downloading wallpaper",
  state: "running",
  priority: "high",
  content: {
    type: "progress",
    progress: 0.42,
    current: 42,
    total: 100,
    unit: "MB",
  },
  placements: [
    { type: "activity", preferredSizeClass: "foreground" },
    { type: "body", size: "hug" },
    { type: "window", windowID: "main", size: "wide", primary: true },
  ],
  actions: [{ id: "cancel", label: "Cancel", role: "destructive" }],
});

The plugin manifest must declare the matching host API and placement capabilities, for example capabilities.hostAPIs: ["display"] and capabilities.placements: ["activity", "body", "window"]. The older plugin.upsert() presentation helpers remain available for compatibility.

The SDK mirrors Wallive's Content/Placement Matrix for authoring feedback. plugin.display(...) and explicit-placement plugin.upsert(...) throw before sending combinations the host would reject, such as list content in activity or detail content in overlay. The host runtime remains the authoritative gate.

Actions

Use the action builders to declare host-owned intents without hand-writing the JSON shape. Wallive still validates the action against the rendered presentation before executing host side effects or notifying the plugin.

import {
  action,
  actionPanel,
  actionSection,
  copyToClipboardIntent,
  openURLIntent,
  pushViewIntent,
  shortcut,
} from "@wallive/plugin-sdk";

plugin.upsert({
  id: "issues",
  kind: "list",
  title: "Issues",
  items: [{ id: "one", title: "Fix release notes" }],
  views: [{ id: "issue-detail", kind: "detail", title: "Issue detail", markdown: "Ready" }],
  actionPanel: actionPanel(
    [
      action("inspect", "Inspect", {
        intent: pushViewIntent("issue-detail"),
        shortcut: shortcut(["cmd"], "o"),
        autoFocus: true,
      }),
    ],
    actionSection("More", [
      action("copy", "Copy", { intent: copyToClipboardIntent("Fix release notes") }),
      action("docs", "Docs", { intent: openURLIntent("https://wallive.app/docs") }),
    ]),
  ),
});

Commands, Preferences, And Host APIs

Wallive sends command launches through host.command. Preferences are host-managed and arrive through host.init, host.command, and host.preferences.changed.

plugin.onCommand(async ({ command }) => {
  const prefs = plugin.getPreferenceValues();
  const last = await plugin.localStorageGetItem("lastRun");
  plugin.upsert({
    id: "refresh",
    kind: "hud",
    title: `Running ${command.commandID}`,
    body: last ?? prefs.token ?? "No previous run",
  });
  await plugin.localStorageSetItem("lastRun", new Date().toISOString());
  plugin.completeCommand(command);
});

plugin.upsert(...), plugin.display(...), plugin.completeCommand(...), and plugin.failCommand(...) calls made while a host.command handler is running automatically inherit command.commandID and Wallive's per-launch command.commandRunID unless you set command scope fields yourself. Window commands use that run scope to focus the plugin window on output from the launched command run.

Convenience wrappers are exported for host-managed storage and feedback:

import { Cache, LocalStorage, showHUD, launchCommand } from "@wallive/plugin-sdk";

await LocalStorage.setItem(plugin, "tokenState", "ok");
await Cache.set(plugin, "profile", JSON.stringify(profile), 60);
await showHUD(plugin, "Done");
await launchCommand(plugin, "refresh");

launchCommand(plugin, commandID, args) sends a same-plugin command.launch request to the Wallive host. The target command must be declared by the same plugin manifest, and Wallive still applies the normal command trigger, argument, preference, enablement, and manifest-access gates before delivering host.command. If the host replies with host.api.response.error, the SDK promise rejects with that error. A plugin-originated command launch is background work; it does not count as a user action and cannot open or focus a plugin window by itself.

System Events

Plugins can subscribe to host-owned events through capabilities.events. Wallive applies manifest access confirmation and privacy projection before sending host.event; plugin code receives it through plugin.onEvent(...).

export const wallivePlugin = definePluginManifest({
  id: "com.example.clipboard",
  displayName: "Clipboard Watcher",
  entry: "dist/index.js",
  capabilities: {
    events: [{
      eventTypes: ["clipboard.changed"],
      payloadFilters: { kind: ["text", "url"] },
      access: "preview",
    }],
    placements: ["activity"],
  },
});

plugin.onEvent(({ event }) => {
  if (event.type !== "clipboard.changed") return;
  plugin.activity({
    id: "clipboard-preview",
    kind: "status",
    title: event.payload.preview ?? event.payload.kind,
    activity: { preferredSizeClass: "foreground" },
  });
});

Surface Layout

Composite plugin views use kind: "surface" plus a constrained layoutTree. Surface leaves reference same-plugin semantic presentations; Wallive owns measurement, wrapping, clipping, scrolling, and rendering.

plugin.upsert({ id: "status", kind: "status", title: "Release", value: "Healthy" });
plugin.upsert({ id: "rollout", kind: "progress", title: "Rollout", progress: 0.42 });
plugin.upsert({
  id: "ops",
  kind: "surface",
  title: "Ops",
  layoutTree: {
    type: "flex",
    direction: "row",
    gap: "sm",
    children: [
      { type: "slot", presentationID: "status", grow: 1 },
      { type: "slot", presentationID: "rollout", basis: "wide" },
    ],
  },
});

Compact Presence

Long-lived status surfaces can stay visible in the compact Island by declaring compactPresence. Wallive still owns rendering and hover behavior; hovering the chip opens the Island focused on that plugin.

plugin.upsert({
  id: "sync",
  kind: "statusMenu",
  title: "Sync",
  state: "success",
  compactPresence: {
    icon: "bolt.horizontal.circle.fill",
    label: "Sync",
    tint: "green",
    priority: 35,
    behavior: "resident",
  },
});

STT Providers

Plugins can declare one speech-to-text provider in package.json#wallivePlugin.sttProvider when they also request the speechTranscription permission. The manifest model list appears in Wallive's Voice Input provider/model pickers. requiresHostEndpoint and requiresHostAPIKey default to true; set either to false when the provider does not need that host setting. Wallive owns microphone capture and sends a temporary WAV path plus the selected provider's host-configured settings only for an active request.

plugin.onSTTTranscribe(async ({ request }) => {
  // request.baseURL / request.apiKey / request.model come from
  // Wallive's Voice Input STT settings for the selected provider.
  // baseURL or apiKey may be empty when the provider declares that it
  // does not need host-provided endpoint or credential fields.
  plugin.completeSTT(request, {
    text: "recognized text",
    language: "en",
  });
});

Use plugin.failSTT(request, message, code) to return a provider error. Wallive correlates responses with requestID. Treat request.apiKey as a request-scoped secret: do not persist or log it.

Runtime Rules

• stdout is reserved for Wallive JSONL protocol messages.
• Write diagnostics to stderr.
• Wallive runs the built JavaScript entrypoint declared by package.json#wallivePlugin.entry.
• Wallive exposes WALLIVE_PLUGIN_ID, WALLIVE_PLUGIN_PROTOCOL_VERSION, and WALLIVE_PLUGIN_STATE_DIR.