wings-plugin-sdk 0.6.0 → 0.8.0

package/README.md

@@ -55,6 +55,12 @@ to fill. Every `wings.on*` call returns a function that removes the listener, so
 `wings-plugin-sdk/react`, or your own `useEffect`, cleans up when a component goes. The API reference is
 [plugins/README.md](https://github.com/josippapez/Wings/blob/main/plugins/README.md) in the Wings repo.
 
+## Polling
+
+Wings is often in the background, and a timer that runs `git` or a network call then costs battery for nothing.
+`pollWhileFocused(tick, ms)` from `wings-plugin-sdk/poll` runs `tick` every `ms` only while a Wings window is in
+front, and once at once when you come back. It uses `wings.onFocus`.
+
 ## Pack
 
 A plugin in its own repo doesn't need to commit what it builds. `wings-plugin pack` builds it into a temporary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wings-plugin-sdk",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "The wings API types, the page frame, React hooks and the build command for Wings plugins.",
   "license": "MIT",
   "type": "module",
@@ -17,14 +17,15 @@
       "types": "./shell.d.ts",
       "default": "./shell.js"
     },
+    "./poll": {
+      "types": "./poll.d.ts",
+      "default": "./poll.js"
+    },
     "./build": {
       "types": "./build.d.ts",
       "default": "./build.mjs"
     }
   },
-  "scripts": {
-    "test": "node --test"
-  },
   "bin": {
     "wings-plugin": "bin.mjs"
   },
@@ -34,6 +35,8 @@
     "react.d.ts",
     "shell.js",
     "shell.d.ts",
+    "poll.js",
+    "poll.d.ts",
     "build.mjs",
     "build.d.ts",
     "bin.mjs",
@@ -66,5 +69,8 @@
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "typescript": "~6.0.3"
+  },
+  "scripts": {
+    "test": "node --test"
   }
-}
+}

package/poll.d.ts

@@ -0,0 +1,7 @@
+/// <reference path="./wings.d.ts" />
+/**
+ * Calls `tick` every `ms` while Wings is focused. When Wings loses focus the timer stops; when it regains focus,
+ * `tick` runs once at once and the timer starts again. `tick` is not called for the state Wings starts in, so
+ * a plugin keeps doing its own first check. Returns a function that stops everything.
+ */
+export function pollWhileFocused(tick: () => void, ms: number, w?: Pick<Wings, "focused" | "onFocus">): () => void;

package/poll.js

@@ -0,0 +1,28 @@
+// A timer that runs only while the user is in Wings.
+
+/**
+ * Calls `tick` every `ms` while Wings is focused. When Wings loses focus the timer stops; when it regains focus,
+ * `tick` runs once at once and the timer starts again. `tick` is not called for the state Wings starts in, so
+ * a plugin keeps doing its own first check. Returns a function that stops everything.
+ */
+export function pollWhileFocused(tick, ms, w = globalThis.wings) {
+  let timer;
+  let wasFocused = w.focused;
+  const start = () => (timer ??= setInterval(tick, ms));
+  const stop = () => {
+    clearInterval(timer);
+    timer = undefined;
+  };
+  if (wasFocused) start();
+  const off = w.onFocus(({ focused }) => {
+    if (focused === wasFocused) return;
+    wasFocused = focused;
+    if (!focused) return stop();
+    tick();
+    start();
+  });
+  return () => {
+    off();
+    stop();
+  };
+}

package/wings.d.ts

@@ -11,6 +11,8 @@ interface WingsPane {
   /** What runs in the pane right now, like `zsh` or `claude`. */
   command: string;
   project: string;
+  /** The id of that project, the same as `project().id`. Needs Wings 0.1.22. */
+  projectId: string;
   /** Set while Claude Code runs in the pane. `startedAt` is when that `claude` started, in ms; a resumed session's transcript also has what came before. */
   session: { sessionId: string; name: string | null; state: string; startedAt: number } | null;
   /** The focused pane of the tab on screen. At most one pane has it, and none while no tab is open. */
@@ -98,10 +100,26 @@ interface WingsExecOptions {
   onOutput?: (line: string) => void;
 }
 
+/** A project (space) as pages see it. */
+interface WingsProject {
+  id: string;
+  name: string;
+  path: string;
+  branch: string | null;
+}
+
 interface Wings {
   // Every `on*` call returns a function that removes the listener, for cleaning up in a React effect.
   /** Every terminal pane, on every change. */
   onPanes(listener: (panes: WingsPane[]) => void): () => void;
+  /**
+   * Whether the user is in Wings: true while any Wings window (the main one or a view window) is in front, false
+   * while another app is. Called once with the current state, then on each change. Needs no permission. Pause timers
+   * while it is false and check once when it turns true, or use `pollWhileFocused` from `wings-plugin-sdk/poll`.
+   */
+  onFocus(listener: (event: { focused: boolean }) => void): () => void;
+  /** The state `onFocus` last reported. True until Wings says otherwise, which it does as soon as the frame is ready. */
+  readonly focused: boolean;
   /**
    * A badge action was clicked. Return a promise: the button spins until it settles (up to 5 min), and a thrown
    * error shows in the card. What it resolves to is ignored.
@@ -154,7 +172,7 @@ interface Wings {
   /** Needs `permissions.notify`. A desktop notification, up to 3 a minute. The title is cut at 64 characters, the body at 256. */
   notify(notification: { title: string; body?: string }): Promise<void>;
   /** Needs `"diff"` in `contributes.ui`. Leave out `patch` to open it loading, then call `updateDiff`. */
-  openDiff(diff: { title: string; subtitle?: string; patch?: string; comments?: WingsComment[] }): Promise<{ id: string }>;
+  openDiff(diff: { title: string; subtitle?: string; /** The repo or folder the diff is of, so Send to agent offers the agent working there first. */ cwd?: string; patch?: string; comments?: WingsComment[] }): Promise<{ id: string }>;
   /** Updates a viewer opened with `openDiff`; ignored once it's closed. `{ comments }` alone keeps the patch, like after a reply. */
   updateDiff(id: string, update: { patch: string; comments?: WingsComment[] } | { comments: WingsComment[] } | { error: string }): Promise<void>;
   /**
@@ -207,8 +225,33 @@ interface Wings {
    * in a window of its own or as a tab in the project on screen (`tab` needs Wings 0.1.15). `as` must be in the
    * view's `opens`, and defaults to the first. A window or tab that's already open comes to the front. The page
    * gets the same `wings` object wherever it opens.
+   *
+   * `args` (JSON, up to 16 KB, only with `as: "tab"`) is what the tab's page reads with `viewArgs`. A tab that's
+   * already open with other args takes the new ones, drops its saved tab state and reloads; a view with `"multiple": true` always opens a
+   * new tab. Needs Wings 0.1.22.
+   */
+  openView(id: string, options?: { as?: "sidebar" | "modal" | "window" | "tab"; args?: unknown }): Promise<void>;
+  /** Where this page shows. `null` in the plugin's main script. Needs Wings 0.1.22. */
+  placement(): "sidebar" | "tab" | "modal" | "window" | null;
+  /** What `openView` passed as `args` when it opened this tab, or `null`. Available at once. Needs Wings 0.1.22. */
+  viewArgs<T = unknown>(): T | null;
+  /**
+   * The project this page is about, or `null` when none is open. A tab page's project is the one the tab belongs to
+   * and never changes; any other page gets the project on screen. Needs Wings 0.1.22.
+   */
+  project(): Promise<WingsProject | null>;
+  /**
+   * Calls the listener with the current project, then each time it changes: the project on screen switched (not for a
+   * tab page), or its branch or name changed. Needs Wings 0.1.22.
+   */
+  onProject(listener: (project: WingsProject | null) => void): () => void;
+  /** In a tab page: the state it last saved with `setTabState`, or `null`. Outside a tab it is `null`. Opening the tab with new `args` clears it. Needs Wings 0.1.22. */
+  tabState<T = unknown>(): Promise<T | null>;
+  /**
+   * In a tab page: saves JSON state, up to 64 KB, on the tab. Wings keeps it across restarts and while the page is
+   * unloaded. Rejects outside a tab or when the state is too big. Needs Wings 0.1.22.
    */
-  openView(id: string, options?: { as?: "sidebar" | "modal" | "window" | "tab" }): Promise<void>;
+  setTabState(state: unknown): Promise<void>;
   /** Closes a sidebar or view wherever it's open. */
   closeView(id: string): Promise<void>;
   /** Opens Wings Settings at the plugin's settings page, `contributes.settings`. Wings 0.1.15 and newer. */