wings-plugin-sdk 0.5.0 → 0.7.0

package/README.md

@@ -1,6 +1,7 @@
 # wings-plugin-sdk
 
-Types, a React hook and a build command for [Wings](https://github.com/josippapez/Wings) plugins.
+The `wings` API types, the page frame, React hooks and the build command for [Wings](https://github.com/josippapez/Wings)
+plugins. The components for plugin pages are in [wings-plugin-ui](../plugin-ui/README.md).
 
 Wings itself gives each plugin the `wings` object at runtime. This package doesn't contain it: it types it, and
 bundles your TypeScript and React into the plain scripts Wings loads.
@@ -9,7 +10,7 @@ bundles your TypeScript and React into the plain scripts Wings loads.
 
 ```sh
 npm install --save-dev wings-plugin-sdk typescript
-npm install --save-dev react react-dom @types/react @types/react-dom   # only for React pages
+npm install --save-dev wings-plugin-ui react react-dom @types/react @types/react-dom   # only for React pages
 ```
 
 `tsconfig.json`:
@@ -33,7 +34,7 @@ npm install --save-dev react react-dom @types/react @types/react-dom   # only fo
 
 Put the code in `src/`, next to `wings-plugin.json`. Every file at the top of `src/` builds to the file of the
 same name, so `src/main.ts` becomes `main.js` and `src/sidebar.tsx` becomes `sidebar.js`. A page that uses
-`wings-plugin-sdk/ui` also gets its `.html` written for it, unless you wrote your own. Folders inside `src/` hold
+`wings-plugin-ui` also gets its `.html` written for it, unless you wrote your own. Folders inside `src/` hold
 the modules they import.
 
 ```sh
@@ -47,11 +48,19 @@ as it is, like the plugins in the Wings repo.
 
 ## Pages
 
-A sidebar, popover, view, tab or settings page is a file in `src/` that calls one of the `show*` functions in
-[UI](#ui). The build writes its HTML. Every `wings.on*` call returns a function that removes the listener, so
-`useBroadcast` and `useMainState`, or your own `useEffect`, clean up when a component goes. The API reference is
+A sidebar, popover, view, tab or settings page is a file in `src/` that calls one of the `show*` functions of
+[wings-plugin-ui](../plugin-ui/README.md). The build writes its HTML. A page that builds its DOM itself, without
+React, gets the same frame from `mountShell(place, options)` in `wings-plugin-sdk/shell`, which returns the element
+to fill. Every `wings.on*` call returns a function that removes the listener, so `useBroadcast` from
+`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
@@ -67,178 +76,3 @@ files your plugin ships, like its own `.html`, `.css` and images. It leaves out
 `package.json` and lock files, `tsconfig*.json`, `README*`, `HANDOVER*`, dotfiles and other `.wings-plugin` files.
 Your folder gets no built files. From a script, `pack(dir, { out })` in `wings-plugin-sdk/build` does the same and
 resolves the package's path.
-
-## UI
-
-`wings-plugin-sdk/ui` lets a page say what it shows and where, and Wings decides how it looks. A page built from
-it never touches the DOM, writes HTML or lays itself out with CSS, so when Wings moves or redesigns a place,
-your page follows without a release.
-
-```tsx
-import { Card, Gauge, Heading, showSidebar, useMainState } from "wings-plugin-sdk/ui";
-
-type Usage = { type: "usage"; percent: number };
-
-function Usage() {
-  // Says hello to your main script once, then shows the newest `usage` message it broadcasts.
-  const usage = useMainState<Usage>("usage");
-  if (!usage) return null;
-  return (
-    <>
-      <Heading>Usage</Heading>
-      <Card>
-        <Gauge label="Today" percent={usage.percent} levels={[75, 90]} />
-      </Card>
-    </>
-  );
-}
-
-showSidebar(<Usage />);
-```
-
-### Places
-
-`showSidebar`, `showPopover`, `showView`, `showTab` and `showSettings` take any React element, your own
-components too, and mount it in that place's shell: Wings' padding, spacing and scrolling for a sidebar, a
-popover, a view (in a modal or a window), a tab or the settings page. Call one per page. `{ fill: true }` lays
-the page out edge to edge with no padding, for a page that scrolls on its own, like a canvas.
-
-You don't write the page's HTML. For `src/sidebar.tsx` that calls one of these, `wings-plugin build` writes
-`sidebar.html` with a mount point, its CSS and its script, titled like the manifest's page. A `sidebar.html` you
-write yourself wins: the build only writes a page that's missing or that it wrote before (it carries a
-`Generated by wings-plugin build` line). A popover's page takes its sidebar's title, the name Wings gives the
-popover too. A page that builds its DOM itself, without React, gets the same shell
-from `mountShell(place, options)` in `wings-plugin-sdk/shell`, which returns the element to fill.
-
-### Talking to main
-
-`useMainState<T>(type, hello?)` returns the newest message of `type` your plugin's other pages broadcast, or
-`null` until one comes. It sends `hello` (`{ type: "hello" }` by default, `null` for none) once when the
-component mounts, so main answers with what it has. `useBroadcast(listener)` gets every message.
-
-### Components
-
-| Component | Props | Renders |
-|---|---|---|
-| `Row`, `Stack` | `gap` (`none`, `xs`, `s`, `m`, `l`), `grow`; `Row` also `align`, `justify`, `wrap`; `as` (`form`, `ul`, `ol` too) | Children side by side or one under the other; as a `ul` or `ol`, a list with no bullets. With `as`, the props and handlers are the element's: `<Row as="form" onSubmit={(e) => e.currentTarget.requestSubmit()}>` has a `HTMLFormElement` |
-| `Text` | `tone` (`muted`, `info`, `success`, `warn`, `danger`), `size` (`small`, `tiny`), `weight` (`medium`, `strong`), `mono`, `numeric`, `truncate`, `clamp`, `grow`, `as` | A span, or the element in `as` |
-| `Title` | `as` (`h1`, `h2`, `h3`), `size` (`large`), `truncate` | A page's or a card's title, like a sprint's name or a setup step's question |
-| `Heading` | `level` (2, 3, 4), `actions` | A small section heading, `h2` by default, with chips or a button on its right |
-| `Card` | `compact`, `as` (`form`, `ul`, `ol` too) | A card, a card that's a form, or a list. Typed for its `as` element like `Row` and `Stack` |
-| `Gauge`, `Meter` | `label`, `percent`, `note`, `tone` or `levels` | A labelled bar with its percentage, or the bar alone, with the meter role |
-| `Stats` | `items: { label, value, tone? }[]` | Small figures side by side, label over value |
-| `Properties` | `items: { label, value }[]` | Label and value pairs |
-| `List`, `ListItem`, `ListButton` | `ordered` and `compact` on `List`, `align` on the rows | A list of rows; a `ListButton` in a `ListItem` makes the row a button |
-| `Dot`, `Spinner` | `tone`, `size`, `label`; `Dot` also `color` | A status dot or a spinner, announced only with a `label`. A dot's `color` comes from your data, like a work item type's `#cc293d` |
-| `Pill`, `Tag` | `tone` | A filled pill, or an outlined tag like a branch |
-| `Loading`, `Empty` | `Empty`: `title`, `detail` | Before the first data, and nothing to show |
-| `Button` | `variant` (`primary`, `ghost`, `danger`), `size` (`small`), `busy` | A button, `type="button"`; `busy` shows a spinner and ignores clicks, keeping focus |
-| `Chip`, `Chips` | `pressed`; `Chips`: `label`, `options`, `value`, `onChange` | A small quiet button, and a group of them that picks one, with `aria-pressed`. An option's other props, like `id`, go to its chip |
-| `Tabs` | `label`, `items`, `value`, `onChange`, `children` | Tabs with arrow keys, Home and End, over their panel |
-| `Field` | `label`, `hint`, `error`, `id`, `inline` | A labelled field that names and describes the input in it. `id` becomes the input's, for a page that puts focus back by id; `inline` puts the label beside it |
-| `FieldGroup` | `label`, `hint`, `error` | Several controls under one label, like checkboxes: a `fieldset` with its `legend`, described by the hint; an error marks each checkbox invalid |
-| `TextInput`, `SearchField`, `Select` | `label`; `Select`: `options`, `value`, `onChange` | Inputs Wings styles; outside a `Field`, `label` names them |
-| `Checkbox` | `checked`, `onChange`, `children` | A checkbox with its label |
-| `Combobox` | `label`, `value`, `onInput`, `options: { value, label, detail? }[]`, `onPick`, `onEnter`, `onKeyDown`, `freeText`, `openOnFocus`, `open`, `filter`, `empty` | A text field with suggestions under it: arrows, Enter, Escape and Tab, and a press outside closes it. With `freeText` it keeps what you type; otherwise it picks one of `options`. `openOnFocus={false}` for a page that puts focus back into it after a render. Without `freeText` the picked label is selected when the field gets focus and after a pick, so typing replaces it. `onEnter(text)` runs on Enter when no option is highlighted, with the typed text, and stops the Enter from submitting a form around it. An `onKeyDown` you pass runs first; `e.preventDefault()` in it skips the combobox's own keys. ArrowDown on a closed combobox opens it and highlights the first option, as in the [WAI-ARIA APG combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/). `open="whileText"` keeps the list shown for as long as the field has text and an option matches, even after Escape, Tab or a press outside (those only clear the highlighted option) and it closes when the text is emptied or an option is picked; `aria-expanded` follows whether the list is shown. Accessibility caveat: the APG pattern has Escape dismiss the popup and treats it as shown only while the user is working in the combobox, so this mode departs from it. Use it only where the suggestions are the page's main content, such as a people search that is useful to keep in view, and not for a field where a stray list would cover other controls |
-| `Menu` | `label`, `items: { id, label, onSelect, tone? }[]`, `align`, `variant`, `size` | A button that opens a menu: arrows, Home, End, Enter, Escape |
-| `Disclosure` | `summary` | More behind a line that opens it |
-
-Every component passes other props, like `id`, `title`, `className`, `onClick` and `aria-*`, to its element.
-`TextInput` and `SearchField` pass `ref` to the input on React 19.
-
-A button that's working on something is `busy`: it shows a spinner, ignores clicks and says so with `aria-busy`
-and `aria-disabled`, and unlike `disabled` it keeps the keyboard focus:
-
-```tsx
-<Button variant="primary" busy={saving} onClick={save}>
-  Save
-</Button>
-```
-
-### Ours or your own
-
-The components are there for a page that looks like the rest of Wings without effort, not a rule. Write your
-own components next to them, and your own CSS: import it from the page, `import "./sidebar.css"`, and the build
-bundles it into `sidebar.css` and links it from the generated page. Match Wings with its variables, which every
-page has:
-
-| Variable | What |
-|---|---|
-| `--wings-fg`, `--wings-muted` | Text, and quieter text |
-| `--wings-surface`, `--wings-hover`, `--wings-pressed`, `--wings-input` | Card, hovered, pressed and input backgrounds |
-| `--wings-hairline`, `--wings-hairline-strong` | Borders |
-| `--wings-ring` | The focus ring |
-| `--wings-primary`, `--wings-primary-fg` | The primary button, and its text |
-| `--wings-info`, `--wings-success`, `--wings-warning`, `--wings-danger` | Tones |
-| `--wings-radius` | A card's corners |
-| `--wings-menu-bg`, `--wings-menu-ring`, `--wings-menu-active`, `--wings-shadow` | A raised layer like a menu or a list of suggestions, as Wings' own menus draw it: its opaque background, its edge, the highlighted option and its shadow |
-| `--wings-font`, `--wings-mono` | Fonts |
-
-```tsx
-// src/sidebar.tsx
-import "./sidebar.css";
-
-function Banner({ children }: { children: string }) {
-  return <div className="banner">{children}</div>;
-}
-```
-
-```css
-/* src/sidebar.css */
-.banner {
-  padding: 8px 10px;
-  border-radius: var(--wings-radius);
-  background: color-mix(in srgb, var(--wings-info) 14%, transparent);
-  color: var(--wings-info);
-}
-```
-
-Wings' base styles cover plain elements (buttons, inputs, selects and the page's font and colours), the `w-*`
-classes and two older helpers, `.muted` and `.card`; nothing else, so your other classes are yours. Your CSS
-loads after Wings', so it wins where you style a component, like `.my-list .w-list-button { height: 24px; }`.
-
-### The class contract
-
-The components render plain elements with `w-*` class names and data attributes, like
-`<div class="w-card" data-size="compact">`, and no styles of their own. Wings styles them in its
-`plugin-ui.css`, which ships with the app, so a Wings update restyles every plugin. The names are a versioned
-public contract: `--wings-ui` on the page's root is its version, `2` now, and a version only adds classes and
-rules. `Meter` sets `--w-value`, how full it is, and a `Dot` with a `color` sets `--w-color`; both are data
-rather than styles.
-
-`w-shell` with `data-place` (`sidebar`, `popover`, `view`, `tab`, `settings`) and `data-fill`; `w-row`,
-`w-stack` with `data-gap`, `data-align`, `data-justify`, `data-wrap`, `data-grow`; `w-text` with `data-tone`,
-`data-size`, `data-weight`, `data-mono`, `data-numeric`, `data-truncate`, `data-clamp`, `data-grow`;
-`w-title` with `data-size`; `w-heading`, `w-heading-row`; `w-card` with `data-size`; `w-gauge`, `w-gauge-label`, `w-gauge-value`,
-`w-gauge-note`, `w-meter` with `data-tone`, `w-meter-fill`; `w-stats`, `w-stat-label`, `w-stat-value`;
-`w-props`, `w-prop`, `w-prop-label`, `w-prop-value`; `w-list` with `data-density`, `w-list-item`,
-`w-list-button` with `data-align`; `w-dot` with `data-tone` or `data-color`; `w-pill`, `w-tag` with `data-tone`; `w-spinner` with `data-size`;
-`w-loading`, `w-empty`, `w-empty-detail`; `w-button` with `data-variant`, `data-size`, `aria-disabled`; `w-chips`, `w-chip`;
-`w-tabs`, `w-tab`; `w-field` with `data-layout`, `w-field-row`, `w-field-label`, `w-field-hint`,
-`w-field-group`, `w-input`, `w-search`, `w-select`, `w-check`; `w-combobox`, `w-listbox`, `w-option`,
-`w-option-label`, `w-option-detail`, `w-option-empty`; `w-menu-root`, `w-menu` with `data-align`, `w-menu-item`
-with `data-tone`; `w-disclosure`. A `ul` or `ol` with `w-row`, `w-stack` or `w-card` loses its bullets.
-
-Version 2 added `w-title`, `Heading`'s levels, `w-field-group`, `w-field-row`, the combobox and menu classes,
-`data-color` on `w-dot`, busy buttons (`aria-disabled` on `w-button`), lists as rows, stacks and cards, and the four raised-layer variables.
-
-### Older Wings
-
-Wings before 0.1.15 has no `w-*` styles, and a Wings with `--wings-ui: 1` lacks version 2's. A page built with
-`wings-plugin-sdk/ui` checks `--wings-ui` when it mounts, and on a Wings without it, or with an older version,
-adds the package's own copy of the styles, before Wings' and your CSS. Since a version only adds rules, the old
-ones Wings has and the new ones from the package fit together. So a plugin works on older Wings without a `minWingsVersion`, and on a current Wings it always gets
-Wings' own styles.
-
-### A linked SDK
-
-With the SDK linked from a local folder (`npm link`, or `link:` in `package.json`) rather than installed,
-TypeScript looks for React next to the SDK's folder. Point it at yours in `tsconfig.json`; the build already
-does:
-
-```json
-"paths": {
-  "react": ["./node_modules/@types/react"],
-  "react/*": ["./node_modules/@types/react/*"]
-}
-```

package/build.d.ts

@@ -3,7 +3,7 @@ export function entries(dir: string): { src: string; out: string }[];
 
 /**
  * Builds the plugin in `dir`: `src/main.ts` to `main.js`, `src/sidebar.tsx` to `sidebar.js`, and so on. CSS a page
- * imports becomes `<name>.css`, and a page that mounts with `wings-plugin-sdk/ui` or `/shell` gets a generated
+ * imports becomes `<name>.css`, and a page that mounts with `wings-plugin-ui` or `wings-plugin-sdk/shell` gets a generated
  * `<name>.html` unless the plugin has its own. With `check`, writes nothing and lists in `stale` the outputs that
  * differ from what's on disk. With `outDir`, writes there instead of `dir`.
  */

package/build.mjs

@@ -2,7 +2,7 @@
 // becomes main.js and src/sidebar.tsx becomes sidebar.js, next to wings-plugin.json. Folders inside src/ hold
 // the modules they import. Wings runs plain scripts, so each file is one bundle with its imports, React too.
 // The CSS a page imports, like `import "./sidebar.css"`, becomes <name>.css, and a page that mounts with
-// wings-plugin-sdk/ui or /shell gets a <name>.html written for it unless the plugin has its own.
+// wings-plugin-ui or wings-plugin-sdk/shell gets a <name>.html written for it unless the plugin has its own.
 import * as esbuild from "esbuild";
 import { zipSync } from "fflate";
 import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -54,12 +54,12 @@ ${hasCss ? `    <link rel="stylesheet" href="${name}.css" />\n` : ""}  </head>
 /** Whether `file` is missing or was written by this build, so the build may write it. */
 const ours = (file) => !existsSync(file) || readFileSync(file, "utf8").includes(GENERATED);
 
-/** Notes whether the bundle imports wings-plugin-sdk's ui or shell, which mount the page themselves. */
+/** Notes whether the bundle imports wings-plugin-ui or wings-plugin-sdk/shell, which mount the page themselves. */
 function shellPlugin(seen) {
   return {
     name: "wings-shell",
     setup(build) {
-      build.onResolve({ filter: /^wings-plugin-sdk\/(ui|shell)$/ }, () => {
+      build.onResolve({ filter: /^(wings-plugin-ui|wings-plugin-sdk\/shell)$/ }, () => {
         seen.shell = true;
         // Resolve as usual.
         return undefined;
@@ -69,8 +69,8 @@ function shellPlugin(seen) {
 }
 
 /**
- * Resolves React from the plugin's folder wherever it's imported, so a page and a linked wings-plugin-sdk (npm
- * link, or link: in package.json) share one React instead of the SDK finding its own, or none.
+ * Resolves React from the plugin's folder wherever it's imported, so a page and a linked wings-plugin-ui (npm
+ * link, or link: in package.json) share one React instead of the package finding its own, or none.
  */
 function oneReact(dir) {
   return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wings-plugin-sdk",
-  "version": "0.5.0",
-  "description": "Types, React hooks, UI components and a build command for Wings plugins.",
+  "version": "0.7.0",
+  "description": "The wings API types, the page frame, React hooks and the build command for Wings plugins.",
   "license": "MIT",
   "type": "module",
   "types": "./wings.d.ts",
@@ -13,21 +13,21 @@
       "types": "./react.d.ts",
       "default": "./react.js"
     },
-    "./ui": {
-      "types": "./ui.d.ts",
-      "default": "./ui.js"
-    },
     "./shell": {
       "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": "tsc -p tsconfig.json && node --test"
+    "test": "node --test"
   },
   "bin": {
     "wings-plugin": "bin.mjs"
@@ -36,12 +36,10 @@
     "wings.d.ts",
     "react.js",
     "react.d.ts",
-    "ui.js",
-    "ui.d.ts",
-    "ui-css.js",
-    "ui-css.d.ts",
     "shell.js",
     "shell.d.ts",
+    "poll.js",
+    "poll.d.ts",
     "build.mjs",
     "build.d.ts",
     "bin.mjs",
@@ -71,7 +69,6 @@
   },
   "devDependencies": {
     "@types/react": "^19.1.8",
-    "jsdom": "^30.1.2",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "typescript": "~6.0.3"

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/shell.d.ts

@@ -9,6 +9,6 @@ export interface ShellOptions {
 
 /**
  * Makes the page's `#app` element (or a new `<main>`) the shell for `place`, and returns it, for a page that
- * builds its DOM itself. React pages use `showSidebar` and the others from `wings-plugin-sdk/ui` instead.
+ * builds its DOM itself. React pages use `showSidebar` and the others from `wings-plugin-ui` instead.
  */
 export function mountShell(place: Place, options?: ShellOptions): HTMLElement;

package/shell.js

@@ -1,28 +1,15 @@
 // The frame a plugin page lives in, without React: where it is, its padding and how it scrolls come from Wings'
-// plugin-ui.css, so a page only says which place it is. wings-plugin-sdk/ui mounts React into it.
-import { fallbackCss, UI_VERSION } from "./ui-css.js";
-
+// plugin-ui.css, so a page only says which place it is. wings-plugin-ui mounts React into it.
 const PLACES = ["sidebar", "popover", "view", "tab", "settings"];
 // Sidebars and popovers change while you look at them, so a screen reader hears what changed.
 const LIVE = new Set(["sidebar", "popover"]);
 
-/** Wings older than the classes this package renders have none, or older ones: bring them, before the page's own CSS. */
-function ensureStyles() {
-  const host = Number(getComputedStyle(document.documentElement).getPropertyValue("--wings-ui")) || 0;
-  if (host >= UI_VERSION || document.querySelector("style[data-wings-ui]")) return;
-  const style = document.createElement("style");
-  style.dataset.wingsUi = String(UI_VERSION);
-  style.textContent = fallbackCss;
-  document.head.prepend(style);
-}
-
 /**
  * Makes the page's `#app` element (or a new `<main>`) the shell for `place`, and returns it. Calling it again
  * returns the same element. `fill` lays the page out edge to edge, for a page that scrolls on its own.
  */
 export function mountShell(place, { fill = false } = {}) {
   if (!PLACES.includes(place)) throw new Error(`Unknown place ${place}: use one of ${PLACES.join(", ")}`);
-  ensureStyles();
   let shell = document.getElementById("app");
   if (!shell) {
     shell = document.createElement("main");

package/wings.d.ts

@@ -102,6 +102,14 @@ 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 +162,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>;
   /**

package/ui-css.d.ts

@@ -1,4 +0,0 @@
-/** The version of the classes wings-plugin-sdk/ui renders. Wings' plugin-ui.css sets it as `--wings-ui`. */
-export const UI_VERSION: number;
-/** The wings-plugin-sdk/ui styles, for Wings versions whose plugin-ui.css doesn't have them yet. */
-export const fallbackCss: string;