wings-plugin-sdk 0.1.0 → 0.2.0

package/README.md

@@ -32,39 +32,191 @@ npm install --save-dev react react-dom @types/react @types/react-dom   # only fo
 ## Build
 
 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 in the plugin folder, so `src/main.ts` becomes `main.js` and `src/sidebar.tsx` becomes `sidebar.js`.
-Folders inside `src/` hold the modules they import.
+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
+the modules they import.
 
 ```sh
-npx wings-plugin build           # writes main.js, sidebar.js, ...
-npx wings-plugin build --check   # fails if a built file is older than its source
+npx wings-plugin pack            # builds and packs the plugin as <id>.wings-plugin, see Pack
+npx wings-plugin build           # builds in place, for a repo that commits its built files
+npx wings-plugin build --check   # fails if a committed built file is older than its source
 ```
 
-Commit the built files. Wings installs a plugin from GitHub as the files in the repo, without building it.
+A plugin in its own repo uses `pack`, and its repo holds only source. `build` is for a folder that Wings loads
+as it is, like the plugins in the Wings repo.
 
-## React pages
+## Pages
 
-A sidebar, popover or view page is your own HTML that loads its built script:
+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
+[plugins/README.md](https://github.com/josippapez/Wings/blob/main/plugins/README.md) in the Wings repo.
+
+## Pack
 
-```html
-<main id="app"></main>
-<script src="sidebar.js"></script>
+A plugin in its own repo doesn't need to commit what it builds. `wings-plugin pack` builds it into a temporary
+folder and zips that as `<id>.wings-plugin`, the file you install in Wings' Plugins manager or attach to a GitHub
+release:
+
+```sh
+npx wings-plugin pack   # writes hello-wings.wings-plugin and prints its path
 ```
 
+The package holds `wings-plugin.json` at its top, every built entry, the generated pages and CSS, and the
+files your plugin ships, like its own `.html`, `.css` and images. It leaves out `src/`, `node_modules`,
+`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 { useState } from "react";
-import { createRoot } from "react-dom/client";
-import { useBroadcast } from "wings-plugin-sdk/react";
-
-function Sidebar() {
-  const [state, setState] = useState<unknown>(null);
-  useBroadcast((message) => setState(message));
-  return <pre>{JSON.stringify(state, null, 2)}</pre>;
+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>
+    </>
+  );
 }
 
-createRoot(document.getElementById("app")!).render(<Sidebar />);
+showSidebar(<Usage />);
 ```
 
-Every `wings.on*` call returns a function that removes the listener, so you can also return it from a
-`useEffect` yourself. The API reference is
-[plugins/README.md](https://github.com/josippapez/Wings/blob/main/plugins/README.md) in the Wings repo.
+### 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 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` | Children side by side or one under the other |
+| `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` |
+| `Heading` | `actions` | A section heading, `h2`, with chips or a button on its right |
+| `Card` | `compact` | A card |
+| `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` | A status dot or a spinner, announced only with a `label` |
+| `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`) | A button, `type="button"` |
+| `Chip`, `Chips` | `pressed`; `Chips`: `label`, `options`, `value`, `onChange` | A small quiet button, and a group of them that picks one, with `aria-pressed` |
+| `Tabs` | `label`, `items`, `value`, `onChange`, `children` | Tabs with arrow keys, Home and End, over their panel |
+| `Field` | `label`, `hint`, `error` | A labelled field that names and describes the input in it |
+| `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 |
+| `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.
+
+### 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-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, `1` now, and a version only adds classes.
+`Meter` sets `--w-value`, how full it is, which is data rather than a style.
+
+`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-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`, `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`; `w-chips`, `w-chip`;
+`w-tabs`, `w-tab`; `w-field`, `w-field-label`, `w-field-hint`, `w-input`, `w-search`, `w-select`, `w-check`;
+`w-disclosure`.
+
+### Older Wings
+
+Wings before 0.1.15 has no `w-*` styles. 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 same styles from the package, before
+your CSS. 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/bin.mjs

@@ -1,19 +1,25 @@
 #!/usr/bin/env node
 // wings-plugin build           builds the plugin in this folder
 // wings-plugin build --check   fails if a built file is older than its source
+// wings-plugin pack            builds the plugin into <id>.wings-plugin, the file Wings installs, without
+//                              writing built files into the folder
 import { relative } from "node:path";
-import { buildPlugin, entries } from "./build.mjs";
+import { buildPlugin, entries, pack } from "./build.mjs";
 
 const [command, ...flags] = process.argv.slice(2);
-if (command !== "build") {
-  console.error("Usage: wings-plugin build [--check]");
+if (command !== "build" && command !== "pack") {
+  console.error("Usage: wings-plugin build [--check] | wings-plugin pack");
   process.exit(2);
 }
 const dir = process.cwd();
 if (!entries(dir).length) {
-  console.error("No plugin to build here: wings-plugin build runs next to wings-plugin.json, with the code in src/.");
+  console.error(`No plugin to ${command} here: wings-plugin ${command} runs next to wings-plugin.json, with the code in src/.`);
   process.exit(1);
 }
+if (command === "pack") {
+  console.log(relative(dir, await pack(dir)));
+  process.exit(0);
+}
 const check = flags.includes("--check");
 const { built, stale } = await buildPlugin(dir, { check });
 for (const { file, bytes } of built) console.log(`${relative(dir, file)}  ${(bytes / 1024).toFixed(1)} KB`);

package/build.d.ts

@@ -2,10 +2,19 @@
 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. With
- * `check`, writes nothing and lists in `stale` the outputs that differ from what's on disk.
+ * 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
+ * `<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`.
  */
 export function buildPlugin(
   dir: string,
-  options?: { check?: boolean; banner?: string },
+  options?: { check?: boolean; banner?: string; outDir?: string },
 ): Promise<{ built: { file: string; bytes: number }[]; stale: string[] }>;
+
+/**
+ * Builds the plugin in `dir` with the files it ships into `<id>.wings-plugin` in `out` (`dir` by default), the
+ * file Wings installs, leaving no built files in `dir`. Leaves out `src/`, `node_modules`, package and lock
+ * files, `tsconfig*.json`, `README*`, `HANDOVER*`, dotfiles and other `.wings-plugin` files. Resolves its path.
+ */
+export function pack(dir: string, options?: { out?: string }): Promise<string>;

package/build.mjs

@@ -1,11 +1,17 @@
 // Builds a plugin's src/ into the files Wings loads. Every file at the top of src/ is one entry, so src/main.ts
 // 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.
 import * as esbuild from "esbuild";
-import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join, parse } from "node:path";
+import { zipSync } from "fflate";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, parse, relative } from "node:path";
 
 const BANNER = "// Built from src/ by wings-plugin build. Edit src/, not this file.";
+/** Marks a page or a stylesheet this build wrote, so it may write it again. A file without it is the plugin's own. */
+const GENERATED = "Generated by wings-plugin build";
 
 /** The entries of the plugin in `dir`: `{ src, out }` for each file at the top of its src/. */
 export function entries(dir) {
@@ -16,35 +22,156 @@ export function entries(dir) {
     .map((f) => ({ src: join(src, f.name), out: join(dir, `${parse(f.name).name}.js`) }));
 }
 
+const escapeHtml = (s) => s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+
+/** The manifest's title for the page in `file`, if a sidebar, popover, view or settings page names it. */
+function pageTitle(dir, file) {
+  const { contributes = {} } = JSON.parse(readFileSync(join(dir, "wings-plugin.json"), "utf8"));
+  const pages = [...(contributes.sidebars ?? []), ...(contributes.views ?? [])];
+  const page = pages.find((p) => p.page === file) ?? pages.find((p) => p.popover?.page === file);
+  if (page) return page.title;
+  if (contributes.settings?.page === file) return "Settings";
+  return parse(file).name;
+}
+
+/** The page Wings loads for an entry that mounts with the ui shell: a mount point, its CSS and its script. */
+function pageHtml(dir, name, src, hasCss) {
+  return `<!doctype html>
+<!-- ${GENERATED} from ${relative(dir, src)}. To write your own, replace this file with one without this line. -->
+<html lang="en">
+  <head>
+    <meta name="generator" content="wings-plugin build" />
+    <title>${escapeHtml(pageTitle(dir, `${name}.html`))}</title>
+${hasCss ? `    <link rel="stylesheet" href="${name}.css" />\n` : ""}  </head>
+  <body>
+    <main id="app"></main>
+    <script src="${name}.js"></script>
+  </body>
+</html>
+`;
+}
+
+/** 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. */
+function shellPlugin(seen) {
+  return {
+    name: "wings-shell",
+    setup(build) {
+      build.onResolve({ filter: /^wings-plugin-sdk\/(ui|shell)$/ }, () => {
+        seen.shell = true;
+        // Resolve as usual.
+        return undefined;
+      });
+    },
+  };
+}
+
+/**
+ * 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.
+ */
+function oneReact(dir) {
+  return {
+    name: "one-react",
+    setup(build) {
+      build.onResolve({ filter: /^react(-dom)?(\/.*)?$/ }, (args) => {
+        if (args.pluginData?.fromPlugin) return undefined;
+        return build.resolve(args.path, { kind: args.kind, resolveDir: dir, pluginData: { fromPlugin: true } });
+      });
+    },
+  };
+}
+
 /**
  * Builds the plugin in `dir`. With `check`, writes nothing and returns the outputs that differ from what's on
- * disk instead, so a release can refuse built files older than their source.
+ * disk instead, so a release can refuse built files older than their source. With `outDir`, writes the outputs
+ * there instead of next to wings-plugin.json; a page's own HTML or CSS in `dir` still wins over a generated one.
  */
-export async function buildPlugin(dir, { check = false, banner = BANNER } = {}) {
+export async function buildPlugin(dir, { check = false, banner = BANNER, outDir = dir } = {}) {
   const built = [];
   const stale = [];
+  const files = [];
   for (const { src, out } of entries(dir)) {
+    const { name } = parse(out);
+    const seen = { shell: false };
     const result = await esbuild.build({
       entryPoints: [src],
+      outfile: out,
       bundle: true,
       format: "iife",
       // WKWebView on the oldest macOS Wings supports.
       target: "safari16",
       jsx: "automatic",
       define: { "process.env.NODE_ENV": '"production"' },
-      banner: { js: banner },
+      banner: { js: banner, css: `/* ${GENERATED} from src/. Edit src/, not this file. */` },
+      plugins: [shellPlugin(seen), oneReact(dir)],
       legalComments: "none",
       minify: true,
       write: false,
       logLevel: "warning",
     });
-    const code = result.outputFiles[0].text;
+    const js = result.outputFiles.find((f) => f.path.endsWith(".js"));
+    const css = result.outputFiles.find((f) => f.path.endsWith(".css"));
+    files.push({ name: `${name}.js`, text: js.text, owned: true });
+    if (css) files.push({ name: `${name}.css`, text: css.text, owned: ours(join(dir, `${name}.css`)) });
+    if (seen.shell && ours(join(dir, `${name}.html`))) files.push({ name: `${name}.html`, text: pageHtml(dir, name, src, Boolean(css)), owned: true });
+  }
+  const foreign = files.filter((f) => !f.owned).map((f) => f.name);
+  if (foreign.length) throw new Error(`${foreign.join(", ")} would be overwritten by the CSS built from src/. Move it into src/ or rename it.`);
+  for (const { name, text } of files) {
+    const file = join(outDir, name);
     if (check) {
-      if (!existsSync(out) || readFileSync(out, "utf8") !== code) stale.push(out);
+      if (!existsSync(file) || readFileSync(file, "utf8") !== text) stale.push(file);
     } else {
-      writeFileSync(out, code);
-      built.push({ file: out, bytes: code.length });
+      writeFileSync(file, text);
+      built.push({ file, bytes: text.length });
     }
   }
   return { built, stale };
 }
+
+/** Files at the top of a plugin folder that are for building it, not for Wings. */
+const SOURCE_ONLY = /^(src|node_modules|package(-lock)?\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?|tsconfig.*\.json|README.*|HANDOVER.*|.*\.wings-plugin)$/;
+
+/** Copies what the plugin ships from `from` to `to`: everything but its source, dependencies and dotfiles. */
+function copyShipped(from, to, top = true) {
+  for (const entry of readdirSync(from, { withFileTypes: true })) {
+    if (entry.name.startsWith(".") || entry.name === "node_modules" || (top && SOURCE_ONLY.test(entry.name))) continue;
+    if (entry.isDirectory()) {
+      mkdirSync(join(to, entry.name));
+      copyShipped(join(from, entry.name), join(to, entry.name), false);
+    } else if (entry.isFile()) copyFileSync(join(from, entry.name), join(to, entry.name));
+  }
+}
+
+/** Every file under `dir`, by its path inside it with `/` between folders. */
+function filesIn(dir, prefix = "") {
+  const out = {};
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = prefix + entry.name;
+    if (entry.isDirectory()) Object.assign(out, filesIn(join(dir, entry.name), `${path}/`));
+    else out[path] = new Uint8Array(readFileSync(join(dir, entry.name)));
+  }
+  return out;
+}
+
+/**
+ * Builds the plugin in `dir` into a temporary folder with the files it ships, and zips that as `<id>.wings-plugin`
+ * in `out` (the plugin folder by default), the file Wings installs. Resolves the package's path. The plugin's
+ * folder gets no built files, so a plugin's own repo doesn't commit them.
+ */
+export async function pack(dir, { out = dir } = {}) {
+  const { id } = JSON.parse(readFileSync(join(dir, "wings-plugin.json"), "utf8"));
+  const tmp = mkdtempSync(join(tmpdir(), "wings-plugin-"));
+  try {
+    copyShipped(dir, tmp);
+    await buildPlugin(dir, { outDir: tmp });
+    const file = join(out, `${id}.wings-plugin`);
+    writeFileSync(file, zipSync(filesIn(tmp), { level: 9 }));
+    return file;
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wings-plugin-sdk",
-  "version": "0.1.0",
-  "description": "Types, React hooks and a build command for Wings plugins.",
+  "version": "0.2.0",
+  "description": "Types, React hooks, UI components and a build command for Wings plugins.",
   "license": "MIT",
   "type": "module",
   "types": "./wings.d.ts",
@@ -13,18 +13,35 @@
       "types": "./react.d.ts",
       "default": "./react.js"
     },
+    "./ui": {
+      "types": "./ui.d.ts",
+      "default": "./ui.js"
+    },
+    "./shell": {
+      "types": "./shell.d.ts",
+      "default": "./shell.js"
+    },
     "./build": {
       "types": "./build.d.ts",
       "default": "./build.mjs"
     }
   },
+  "scripts": {
+    "test": "node --test"
+  },
   "bin": {
-    "wings-plugin": "./bin.mjs"
+    "wings-plugin": "bin.mjs"
   },
   "files": [
     "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",
     "build.mjs",
     "build.d.ts",
     "bin.mjs",
@@ -37,14 +54,19 @@
     "directory": "packages/plugin-sdk"
   },
   "dependencies": {
-    "esbuild": "^0.28.2"
+    "esbuild": "^0.28.2",
+    "fflate": "^0.8.3"
   },
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=19",
+    "react-dom": ">=19"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
+    },
+    "react-dom": {
+      "optional": true
     }
   }
 }

package/shell.d.ts

@@ -0,0 +1,14 @@
+/// <reference path="./wings.d.ts" />
+/** Where a page shows in Wings. Each gets its own padding and spacing from Wings' plugin-ui.css. */
+export type Place = "sidebar" | "popover" | "view" | "tab" | "settings";
+
+export interface ShellOptions {
+  /** Lay the page out edge to edge with no padding, filling the frame, for a page that scrolls on its own. */
+  fill?: boolean;
+}
+
+/**
+ * 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.
+ */
+export function mountShell(place: Place, options?: ShellOptions): HTMLElement;

package/shell.js

@@ -0,0 +1,38 @@
+// 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";
+
+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");
+    shell.id = "app";
+    document.body.append(shell);
+  }
+  shell.classList.add("w-shell");
+  shell.dataset.place = place;
+  shell.toggleAttribute("data-fill", fill);
+  if (LIVE.has(place)) shell.setAttribute("aria-live", "polite");
+  else shell.removeAttribute("aria-live");
+  return shell;
+}

package/ui-css.d.ts

@@ -0,0 +1,4 @@
+/** 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;