@termix-ssh/plugin-sdk 1.0.10 → 1.0.12

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 1.0.12
+
+Plugin API 1.4.0.
+
+### Added
+
+- `contributes.layouts` and `app.registerLayout()` for a whole-app layout, with the `ui:layout` capability. Needs `engine.api` 1.4
+- `contributes.themes` for CSS-only themes, with the `ui:theme` capability. `termix-plugin validate` checks theme CSS and `pack` ships it
+- `useShell()` gives a layout the live shell: tabs, splits, hosts, docks, the command palette and the registries. The shell's home tab is left out until some plugin registers a `dashboard` tab type
+- `TabStage` and `ShellConfirmCapture` in `@termix-ssh/plugin-sdk/ui`, for a layout to place tabs
+- `validateThemeCss()` in `@termix-ssh/plugin-sdk/manifest`
+- `@termix-ssh/plugin-sdk/ui` also exports what a whole layout is built from: the API client, shared types, hooks, `useShellController()` and `APP_VERSION`. These reach into core, so they can change with a core release
+- `@termix-ssh/plugin-sdk/testing-host` exports the registries and permission seam a layout's own tests fill directly
+- A plugin that only holds themes needs no source: `termix-plugin build` writes an empty backend and `validate` does not ask for a frontend
+- `termix-plugin validate` flags `ui:layout` or `ui:theme` with nothing contributed, and a layout plugin with no frontend
+
+### Fixed
+
+- The manifest JSON schema lists the `notify:hub` and `plugins:read` capabilities
+- Plugin tests and type checks work with the SDK linked from a local Termix checkout
+
+## 1.0.11
+
+Plugin API 1.3.0.
+
+### Added
+
+- `ctx.auth.issueUserToken()` mints a short-lived session for a user, for calling Termix's own API as them from background work. Needs `users:impersonate` and `engine.api` 1.3
+- `ctx.users.getLocale()` reads a user's UI language. Needs `users:read` and `engine.api` 1.3
+
 ## 1.0.10
 
 ### Changed

package/PLUGIN-GUIDE.md

@@ -1,6 +1,6 @@
 # Termix plugin guide
 
-SDK 1.0.10 | Plugin API 1.2.0
+SDK 1.0.12 | Plugin API 1.4.0
 
 This guide is for anyone, person or AI coding tool, building a Termix plugin. It ships inside
 `@termix-ssh/plugin-sdk`, so the copy in your `node_modules` always matches the SDK you have installed.
@@ -105,7 +105,7 @@ Before you call a change finished:
 - [ ] `npm run build` passes
 - [ ] `npm run format:check` passes
 - [ ] `npx termix-plugin migrations --check` passes (you ran `npm run migrations` after changing tables)
-- [ ] New strings are in `locales/en.json`
+- [ ] New strings are in `locales/en.json`, and `plugin.name` / `plugin.description` match the manifest
 - [ ] New routes have an `@openapi` block and a test, including without the permission
 - [ ] New env vars are listed in `env` in the manifest
 - [ ] `docs/` and the "About this plugin" section of `AGENTS.md` still match what the plugin does
@@ -175,7 +175,7 @@ Unknown fields are refused at every level, so a typo fails validation. The schem
 
 `contributes` holds `tabs`, `panels`, `dashboardCards`, `actions`, `actionSlots`, `permissions`,
 `settings`, `protocols`, `auth`, `syncEntities`, `keybindingActions`, `http`, `guest`, `guestViews`,
-`uiPresets` and `uses`. Frontend `register*` calls need their ids declared here first.
+`uiPresets`, `uses`, `layouts` and `themes`. Frontend `register*` calls need their ids declared here first.
 
 Capabilities and permissions are different things. A capability (`hosts:read`, with a colon) is what your
 code may reach. A permission (`hello.use`, with a dot) is what a user may do.
@@ -225,6 +225,8 @@ Bundled as ESM for Node 22+ into `dist/backend.js`. Backend imports of your own
 | `audit.record`         | none                             | Write your own audit line                                      |
 | `sync`                 | none                             | Sync your tables to a linked desktop                           |
 | `auth`                 | `auth:provide`                   | Login methods, second factors, SSH auth types                  |
+| `auth.issueUserToken`  | `users:impersonate`              | A short-lived session for calling Termix's API as a user       |
+| `users.getLocale`      | `users:read`                     | A user's UI language                                           |
 | `system`               | `system:tls`                     | The server's HTTPS certificate                                 |
 | `plugins.list()`       | `plugins:read`                   | Which plugins are installed                                    |
 | `asUser(userId, fn)`   | always audited                   | Run background work as a user                                  |
@@ -237,6 +239,13 @@ In a route the actor is the signed-in user, set by Termix. `ctx.currentActor()`
 work with no request (a timer, an event) uses `ctx.asUser(userId, fn)`, which is audited and still applies
 that user's permissions.
 
+Background work that must call Termix's own HTTP API (the Termix CLI, say) asks for a session with
+`ctx.auth.issueUserToken(userId, { purpose, ttlSeconds })` and sends it as `Authorization: Bearer <token>`.
+It needs `users:impersonate` and `engine.api` `^1.3`, lasts 300 seconds by default and 900 at most, and is
+audited as `plugin_user_token_issued`. The user's permissions apply, and it is refused on routes that change
+their password, second factors, API keys or linked logins. `ctx.users.getLocale(userId)` gives the user's
+UI language, like `zh_CN`, or null, for writing to them in it.
+
 ### Routes
 
 Routes live at `/plugin-api/<id>/`, sockets at `/plugin-ws/<id>/`, on the main Termix port. You never need
@@ -469,6 +478,7 @@ your plugin's error boundary and Suspense.
 | `registerComponent`, `registerExtension`                                           | Offer a component by id, add to an extension point                |
 | `registerOnboardingStep`                                                           | A first run setup step                                            |
 | `registerLoginMethod`, `registerSecondFactorUI`, `registerSshAuthEditor`           | Sign in UI                                                        |
+| `registerLayout`                                                                   | A whole-app layout (`contributes.layouts`, API 1.4)               |
 | `api`                                                                              | Axios client for your `/plugin-api/<id>/` routes, auth included   |
 | `fetch(path)`, `wsUrl(path)`                                                       | Raw fetch for streams, socket URL and auth                        |
 | `docs`, `tabs`, `confirm`, `listHosts`, `getHost`, `t`, `hasPermission`, `desktop` | Helpers                                                           |
@@ -476,7 +486,7 @@ your plugin's error boundary and Suspense.
 
 Hooks from `@termix-ssh/plugin-sdk/frontend`: `useTranslation`, `usePermission`, `useSettings`, `useHost`,
 `useHosts`, `usePluginApi`, `useCurrentUser`, `useTheme`, `useToast`, `useDocsUrl`, `useTabs`,
-`useSlotContributions`, `useSshAuthTypes`, `useExtensions`.
+`useSlotContributions`, `useSshAuthTypes`, `useExtensions`, `useShell`.
 
 Shared from Termix and never bundled: `react`, `react-dom`, `i18next`, `react-i18next`, `sonner` and the
 SDK's `frontend` and `ui`. Anything else, like `lucide-react`, is bundled. A host your code gets only carries
@@ -484,9 +494,98 @@ your own host settings, under `host.pluginSettings[<id>]`.
 
 Slots you can fill include `terminal.toolbar`, `terminal.toolbarStatus`, `terminal.sidePanel`,
 `terminal.overlay`, `dashboard.counters`, `dashboard.hostMetrics`, `admin.userTabs`, `hosts.importMenu`,
-`hosts.panel`, `credentials.badges`, `shell.overlay` and `tab.menu`. See
+`hosts.panel`, `credentials.badges`, `shell.overlay`, `shell.rightEdge` and `tab.menu`. See
 https://docs.termix.site/develop/more-extension-points.
 
+## Layouts and themes
+
+A plugin can replace the whole app layout or add themes (API 1.4). Users pick both in Settings, Appearance;
+admins set the default for everyone.
+
+A layout is declared in `contributes.layouts` (`id`, `label`, optional `description` and `defaultTheme`) and
+needs the `ui:layout` capability, which admins see as high risk because a layout draws every screen. Register
+it in `activate`:
+
+```tsx
+import { useShell, type TermixApp } from "@termix-ssh/plugin-sdk/frontend";
+import {
+  ShellConfirmCapture,
+  SurfaceScope,
+  TabStage,
+} from "@termix-ssh/plugin-sdk/ui";
+
+function MyLayout() {
+  const shell = useShell();
+  if (!shell) return null;
+  return (
+    <div className="flex h-dvh w-screen flex-col bg-background">
+      <header>
+        {/* tabs from shell.tabs.topLevel, shell.palette.open() and so on */}
+      </header>
+      <SurfaceScope kind="tab">
+        <ShellConfirmCapture />
+        <TabStage />
+      </SurfaceScope>
+    </div>
+  );
+}
+
+export function activate(app: TermixApp) {
+  app.registerLayout({
+    id: "my-layout",
+    label: "layout.name",
+    component: MyLayout,
+  });
+}
+```
+
+- `useShell()` is the live shell with nothing drawn: tabs, splits, hosts, the left and right docks, the
+  command palette, the registries as hooks and the user. Core keeps all the state, so switching layouts keeps
+  every session.
+- `TabStage` is where tabs show. Place it anywhere; tabs are never remounted when it moves, so a terminal
+  keeps its connection. Wrap it in `SurfaceScope kind="tab"` with a `ShellConfirmCapture` inside, so
+  close questions and inline views show over the tab area. Overlays and onboarding stay in core.
+- The layout draws the command palette. Core keeps whether it is open (`palette.isOpen`, Ctrl+K calls
+  `palette.open()`) and what is in it (`usePaletteEntries`, `usePaletteGroups`, rail items, hosts).
+- The shell always keeps a home tab with the id and type `dashboard`. `useShell()` leaves it out until some
+  plugin registers a `dashboard` tab type, so a layout without a home screen has no empty tab to draw.
+- Settings, Manage and the host editor belong to Classic Layout. A layout without them should still render
+  `LookSettings` somewhere so people can switch back. `tabs.openSingleton("plugins")` opens core's own
+  Plugins tab in any layout. Switching layouts closes the tabs the old layout's plugin declared.
+- `mobileComponent` is used on phones and narrow windows. The desktop app always gets `component`.
+- Only the chosen layout's plugin is loaded. If it fails to load or crashes twice, Termix shows a repair
+  screen where people can switch, reset, update, turn it off or (for a bundled plugin) restore the copy that
+  shipped. `?safe-layout=1` opens it any time.
+- Termix has no layout of its own. The default is the bundled Classic Layout plugin
+  (https://github.com/Termix-SSH/Plugin-Classic-Layout), which is also a full example. It owns the rail,
+  sidebar, tab bar, docks, Dashboard, Manage, Settings and command palette, registers the `dashboard`,
+  `host-manager` and `settings` tab types, and offers the host list and dashboard as the components
+  `classic-layout.hostTree` and `classic-layout.dashboard` for other plugins to place with `PluginComponent`.
+  It reads the shell with `useShellController()` from `@termix-ssh/plugin-sdk/ui`, which exposes more than
+  `useShell()` and may change with Termix. A third party layout should start from `useShell()`.
+- Example Top Bar Layout (https://github.com/Termix-SSH/Plugin-Example-Topbar-Layout) is a small third party
+  style layout built only on `useShell()`, `TabStage` and `@termix-ssh/plugin-sdk/ui`, with a phone version.
+
+A theme is CSS only. Declare it in `contributes.themes` (`id`, `label`, `mode` light or dark, `css` path,
+optional `swatch` colors for the picker) with the `ui:theme` capability. The id becomes a class on `<html>`,
+so the file may only hold rules whose selectors start with `.<id>`, `:root.<id>` or `html.<id>`, optionally
+inside `@media` or `@supports`. `@import`, `url()` to another host and other at-rules are refused by
+`termix-plugin validate` and by the server. Set the same tokens core's themes set (`--background`,
+`--foreground`, `--card`, `--border`, `--muted` and the rest).
+
+A plugin that only holds themes needs no code. Leave out `src/`: `termix-plugin build` writes an empty backend and
+`validate` does not ask for a frontend. Keep the CSS in `themes/` and a test that checks it with
+`validateThemeCss()`. Notes:
+
+- A theme with the id of a built-in (`light` or `dark`) replaces core's basic copy while the plugin runs.
+- The first theme a bundled default-look plugin lists is the default for new installs.
+- Themes show in the picker in the order core lists its own, then the plugin's order.
+- A theme someone saved that no longer exists shows as System. It comes back when the plugin does.
+- Accent color, UI font, font size and density are not part of a theme. Core applies them on top.
+- Bundled Classic Themes (https://github.com/Termix-SSH/Plugin-Classic-Themes) is a full example, and
+  Example Theme (https://github.com/Termix-SSH/Plugin-Example-Theme) a small one with one light and one dark
+  theme.
+
 ## Looking native
 
 Build UI from `@termix-ssh/plugin-sdk/ui` so it matches Termix and follows the theme. The full list of
@@ -538,6 +637,20 @@ Plurals use `_one` and `_other` with `t("hosts", { count })`. Other languages go
 `locales/translated/<code>.json` (like `de_DE.json`) with the same keys. Keep `{{placeholders}}` as they are.
 Untranslated strings show in English.
 
+Termix shows your plugin's name and description in the plugin manager, the setup picker and settings.
+Put them in `locales/en.json` as `plugin.name` and `plugin.description`, with the same text as `name` and
+`description` in the manifest, so they get translated too. Without them, the English manifest text shows in
+every language.
+
+```json
+{
+  "plugin": {
+    "name": "Host Metrics",
+    "description": "Live CPU, memory, disk, network and GPU stats."
+  }
+}
+```
+
 ## Docs
 
 `docs/index.md` is the first page: what the plugin does in a sentence or two, how to turn it on, how to use
@@ -740,37 +853,39 @@ To run your own registry instead, see https://docs.termix.site/develop/registrie
 
 ## Capabilities
 
-| Capability           | Risk     | What it allows                                         |
-| -------------------- | -------- | ------------------------------------------------------ |
-| `credentials:read`   | critical | Read stored secrets for hosts the user can reach       |
-| `system:tls`         | critical | Replace the HTTPS certificate, answer CA domain checks |
-| `ssh:connect`        | high     | Run any command on hosts, with the user's access       |
-| `process:spawn`      | high     | Run programs on the Termix server                      |
-| `users:write`        | high     | Add users and change their roles                       |
-| `users:impersonate`  | high     | Run background work as another user, audited           |
-| `db:core-refs`       | high     | Query core users, roles and hosts tables (read only)   |
-| `auth:provide`       | high     | Add login methods, second factors, SSH auth types      |
-| `device:serial`      | high     | Open serial and USB ports on the server                |
-| `notify:hub`         | high     | Receive every alert (the alerts hub only)              |
-| `hosts:write`        | medium   | Add and edit hosts                                     |
-| `credentials:use`    | medium   | Connect with saved credentials without seeing them     |
-| `credentials:write`  | medium   | Save new credentials                                   |
-| `network:outbound`   | medium   | Outbound HTTP through `ctx.fetch`                      |
-| `network:serve`      | medium   | HTTP routes and sockets                                |
-| `network:broadcast`  | medium   | Local network broadcasts, like Wake-on-LAN             |
-| `users:read`         | medium   | Usernames and roles                                    |
-| `events:core`        | medium   | Listen to core events                                  |
-| `notify:send`        | medium   | Send alerts                                            |
-| `audit:read`         | medium   | Read the audit log                                     |
-| `desktop:window`     | medium   | Open windows in the desktop app                        |
-| `hosts:read`         | low      | Read hosts the user can see                            |
-| `db:own`             | low      | Your own tables                                        |
-| `kv:own`             | low      | Small key value state                                  |
-| `files:own`          | low      | Your own folder on disk                                |
-| `secrets:own`        | low      | Your own encrypted secrets                             |
-| `settings:read-core` | low      | Read Termix server settings                            |
-| `plugins:read`       | low      | See installed plugins                                  |
-| `ui:surface`         | low      | Add tabs, panels and settings                          |
+| Capability           | Risk     | What it allows                                          |
+| -------------------- | -------- | ------------------------------------------------------- |
+| `credentials:read`   | critical | Read stored secrets for hosts the user can reach        |
+| `system:tls`         | critical | Replace the HTTPS certificate, answer CA domain checks  |
+| `ssh:connect`        | high     | Run any command on hosts, with the user's access        |
+| `process:spawn`      | high     | Run programs on the Termix server                       |
+| `users:write`        | high     | Add users and change their roles                        |
+| `users:impersonate`  | high     | Act as another user, or get a session for them, audited |
+| `db:core-refs`       | high     | Query core users, roles and hosts tables (read only)    |
+| `auth:provide`       | high     | Add login methods, second factors, SSH auth types       |
+| `device:serial`      | high     | Open serial and USB ports on the server                 |
+| `notify:hub`         | high     | Receive every alert (the alerts hub only)               |
+| `ui:layout`          | high     | Replace the whole app layout                            |
+| `hosts:write`        | medium   | Add and edit hosts                                      |
+| `credentials:use`    | medium   | Connect with saved credentials without seeing them      |
+| `credentials:write`  | medium   | Save new credentials                                    |
+| `network:outbound`   | medium   | Outbound HTTP through `ctx.fetch`                       |
+| `network:serve`      | medium   | HTTP routes and sockets                                 |
+| `network:broadcast`  | medium   | Local network broadcasts, like Wake-on-LAN              |
+| `users:read`         | medium   | Usernames, roles and UI language                        |
+| `events:core`        | medium   | Listen to core events                                   |
+| `notify:send`        | medium   | Send alerts                                             |
+| `audit:read`         | medium   | Read the audit log                                      |
+| `desktop:window`     | medium   | Open windows in the desktop app                         |
+| `hosts:read`         | low      | Read hosts the user can see                             |
+| `db:own`             | low      | Your own tables                                         |
+| `kv:own`             | low      | Small key value state                                   |
+| `files:own`          | low      | Your own folder on disk                                 |
+| `secrets:own`        | low      | Your own encrypted secrets                              |
+| `settings:read-core` | low      | Read Termix server settings                             |
+| `plugins:read`       | low      | See installed plugins                                   |
+| `ui:surface`         | low      | Add tabs, panels and settings                           |
+| `ui:theme`           | low      | Add color themes, CSS only                              |
 
 An update that adds a capability waits for an admin to approve it.
 

package/cli/commands/build.mjs

@@ -5,7 +5,12 @@ import { fileURLToPath } from "node:url";
 import * as esbuild from "esbuild";
 import { BACKEND_EXTERNALS, FRONTEND_EXTERNALS } from "../lib/externals.mjs";
 import { staticUrlImports } from "../lib/static-url-imports.mjs";
-import { readManifest, resolveEntry, copyDir } from "../lib/plugin-dir.mjs";
+import {
+  readManifest,
+  resolveEntry,
+  copyDir,
+  isThemeOnly,
+} from "../lib/plugin-dir.mjs";
 import { openapi } from "./openapi.mjs";
 import { splitByCoreClasses } from "../lib/css-classes.mjs";
 
@@ -232,32 +237,41 @@ export async function build({ cwd }) {
   fs.mkdirSync(outDir, { recursive: true });
 
   const backendEntry = resolveEntry(cwd, BACKEND_ENTRIES);
-  if (!backendEntry) {
+  if (!backendEntry && !isThemeOnly(manifest)) {
     throw new Error(
       `${pluginId}: no backend entry (looked for ${BACKEND_ENTRIES.join(", ")})`,
     );
   }
 
-  await esbuild.build({
-    entryPoints: [backendEntry],
-    outfile: path.join(outDir, "backend.js"),
-    bundle: true,
-    format: "esm",
-    platform: "node",
-    target: "node22",
-    sourcemap: true,
-    logLevel: "warning",
-    // A native dependency's compiled .node binary is resolved by the
-    // package's own relative paths, which break once esbuild inlines its JS
-    // elsewhere. Declaring it in nativeDependencies keeps it a real
-    // node_modules import instead, resolved at runtime like a host-provided
-    // package.
-    external: [...BACKEND_EXTERNALS, ...(manifest.nativeDependencies ?? [])],
-    loader: BINARY_LOADERS,
-    // Bundled CJS deps still call require() for Node builtins at runtime.
-    // ESM has no ambient require, so give esbuild's require shim a real one.
-    banner: { js: REQUIRE_BANNER },
-  });
+  if (backendEntry) {
+    await esbuild.build({
+      entryPoints: [backendEntry],
+      outfile: path.join(outDir, "backend.js"),
+      bundle: true,
+      format: "esm",
+      platform: "node",
+      target: "node22",
+      sourcemap: true,
+      logLevel: "warning",
+      // A native dependency's compiled .node binary is resolved by the
+      // package's own relative paths, which break once esbuild inlines its JS
+      // elsewhere. Declaring it in nativeDependencies keeps it a real
+      // node_modules import instead, resolved at runtime like a host-provided
+      // package.
+      external: [...BACKEND_EXTERNALS, ...(manifest.nativeDependencies ?? [])],
+      loader: BINARY_LOADERS,
+      // Bundled CJS deps still call require() for Node builtins at runtime.
+      // ESM has no ambient require, so give esbuild's require shim a real one.
+      banner: { js: REQUIRE_BANNER },
+    });
+  } else {
+    // Core loads every plugin through a backend entry, so a theme only
+    // plugin gets an empty one.
+    fs.writeFileSync(
+      path.join(outDir, "backend.js"),
+      "export function activate() {}\n",
+    );
+  }
 
   for (const worker of readWorkerEntries(cwd, pluginId)) {
     await esbuild.build({

package/cli/commands/pack.mjs

@@ -1,7 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
 import { readManifest } from "../lib/plugin-dir.mjs";
-import { collectFiles, createTmxplug } from "../lib/tmxplug.mjs";
+import {
+  collectFiles,
+  createTmxplug,
+  themeFiles,
+  TMXPLUG_CONTENTS,
+} from "../lib/tmxplug.mjs";
 import { sha256 } from "../lib/signing.mjs";
 import { validate } from "./validate.mjs";
 
@@ -32,7 +37,12 @@ export async function pack({ cwd, args = [] }) {
   fs.mkdirSync(outDir, { recursive: true });
   const outfile = path.join(outDir, `${pluginId}-${version}.tmxplug`);
 
-  const archive = createTmxplug(cwd, collectFiles(cwd));
+  const archive = createTmxplug(
+    cwd,
+    collectFiles(cwd, [
+      ...new Set([...TMXPLUG_CONTENTS, ...themeFiles(manifest)]),
+    ]),
+  );
   fs.writeFileSync(outfile, archive);
 
   console.log(`packed ${path.basename(outfile)}`);

package/cli/commands/validate.mjs

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { readManifest } from "../lib/plugin-dir.mjs";
+import { readManifest, isThemeOnly } from "../lib/plugin-dir.mjs";
 
 /**
  * The manifest rules live in src/manifest.ts, which the server uses too, so
@@ -17,7 +17,7 @@ export async function loadSdkModule(name) {
 
 export async function validate({ cwd }) {
   const raw = readManifest(cwd);
-  const { parseManifest } = await loadSdkModule("manifest");
+  const { parseManifest, validateThemeCss } = await loadSdkModule("manifest");
   const { errors } = parseManifest(raw);
 
   const problems = [...errors];
@@ -25,7 +25,8 @@ export async function validate({ cwd }) {
   // The manifest names files. They have to be there.
   const referenced = [
     raw.backend ?? "dist/backend.js",
-    raw.frontend ?? "dist/frontend.js",
+    // A theme only plugin has no frontend code.
+    ...(isThemeOnly(raw) ? [] : [raw.frontend ?? "dist/frontend.js"]),
     raw.locales ?? "locales",
   ];
   for (const rel of referenced) {
@@ -34,6 +35,8 @@ export async function validate({ cwd }) {
     }
   }
 
+  problems.push(...validateThemeFiles(cwd, raw, validateThemeCss));
+  problems.push(...validateLookCapabilities(cwd, raw));
   problems.push(
     ...(await validateMigrations(cwd, raw.id ?? path.basename(cwd))),
   );
@@ -53,6 +56,63 @@ export async function validate({ cwd }) {
   console.log(`ok  ${raw.id ?? path.basename(cwd)}`);
 }
 
+/** Every declared theme file exists and holds only CSS a theme may hold. */
+export function validateThemeFiles(cwd, raw, validateThemeCss) {
+  const problems = [];
+  const themes = raw?.contributes?.themes;
+  if (!Array.isArray(themes)) return problems;
+  for (const theme of themes) {
+    if (typeof theme?.css !== "string" || typeof theme?.id !== "string") {
+      continue;
+    }
+    const file = path.join(cwd, theme.css);
+    if (!fs.existsSync(file)) {
+      problems.push(`theme ${theme.id}: ${theme.css} does not exist`);
+      continue;
+    }
+    for (const error of validateThemeCss(
+      fs.readFileSync(file, "utf8"),
+      theme.id,
+    )) {
+      problems.push(`theme ${theme.id}: ${error}`);
+    }
+  }
+  return problems;
+}
+
+/**
+ * ui:layout and ui:theme must match what the manifest contributes, both
+ * ways. The manifest check already flags a contribution without its
+ * capability; this flags a capability with nothing behind it, and a layout
+ * with no frontend to register it.
+ */
+export function validateLookCapabilities(cwd, raw) {
+  const problems = [];
+  const capabilities = Array.isArray(raw?.capabilities) ? raw.capabilities : [];
+  const layouts = raw?.contributes?.layouts;
+  const themes = raw?.contributes?.themes;
+  const hasLayouts = Array.isArray(layouts) && layouts.length > 0;
+  const hasThemes = Array.isArray(themes) && themes.length > 0;
+  if (capabilities.includes("ui:layout") && !hasLayouts) {
+    problems.push('"ui:layout" is declared but contributes.layouts is empty');
+  }
+  if (capabilities.includes("ui:theme") && !hasThemes) {
+    problems.push('"ui:theme" is declared but contributes.themes is empty');
+  }
+  if (hasLayouts) {
+    const entries = ["index.tsx", "index.ts", "index.mjs", "index.js"];
+    const frontend = entries.some((entry) =>
+      fs.existsSync(path.join(cwd, "src", "frontend", entry)),
+    );
+    if (!frontend && raw.frontend === undefined) {
+      problems.push(
+        "contributes.layouts needs a frontend that calls app.registerLayout",
+      );
+    }
+  }
+  return problems;
+}
+
 /** Env vars core sets for everyone, so a plugin need not list them. */
 const CORE_ENV = new Set([
   "DATA_DIR",

package/cli/lib/plugin-dir.mjs

@@ -14,6 +14,17 @@ export function readManifest(cwd) {
 }
 
 /** The first of these that exists, or null. */
+/** Only themes: CSS files and no code, so no source entry is needed. */
+export function isThemeOnly(manifest) {
+  const capabilities = manifest.capabilities ?? [];
+  return (
+    capabilities.length > 0 &&
+    capabilities.every((capability) => capability === "ui:theme") &&
+    Array.isArray(manifest.contributes?.themes) &&
+    manifest.contributes.themes.length > 0
+  );
+}
+
 export function resolveEntry(cwd, candidates) {
   for (const candidate of candidates) {
     const full = path.join(cwd, candidate);

package/cli/lib/tmxplug.mjs

@@ -2,6 +2,15 @@ import fs from "node:fs";
 import path from "node:path";
 import zlib from "node:zlib";
 
+/** Theme CSS files a manifest declares, which travel with the plugin too. */
+export function themeFiles(manifest) {
+  const themes = manifest?.contributes?.themes;
+  if (!Array.isArray(themes)) return [];
+  return themes
+    .map((theme) => theme?.css)
+    .filter((css) => typeof css === "string");
+}
+
 /** What a .tmxplug holds, in the order the spec lists it. */
 export const TMXPLUG_CONTENTS = [
   "manifest.json",

package/dist/backend.d.ts

@@ -1223,6 +1223,18 @@ export interface PluginSecondFactor {
     /** Removes the user's enrolment. Called by the admin reset. */
     reset?: (userId: string) => Promise<void>;
 }
+export interface PluginUserTokenOptions {
+    /** Why the token exists, kept in the audit log and on the session. */
+    purpose: string;
+    /** Seconds until it expires. Defaults to 300 and is capped at 900. */
+    ttlSeconds?: number;
+}
+export interface PluginUserToken {
+    /** Send as `Authorization: Bearer <token>` to core's own API. */
+    token: string;
+    /** ISO time the session ends. */
+    expiresAt: string;
+}
 /**
  * Login methods, second factors and SSH auth types. Every register call needs
  * auth:provide and a matching contributes.auth entry, and is undone on
@@ -1278,6 +1290,22 @@ export interface PluginAuth {
      * delete a provider people still sign in with.
      */
     countLinkedUsers: (provider: string) => Promise<number>;
+    /**
+     * A short-lived session for an existing user, for calling core's own HTTP
+     * API as them from work with no request behind it, like a scheduled task
+     * driving the Termix CLI. The user's RBAC applies unchanged. Needs
+     * users:impersonate, not auth:provide, and every call is audited.
+     *
+     * The session is marked with the plugin and purpose. It cannot change the
+     * user's password, second factors, API keys or linked logins, so it can
+     * never outlive itself.
+     */
+    issueUserToken: (userId: string, options: PluginUserTokenOptions) => Promise<PluginUserToken>;
+}
+/** What a plugin may learn about a user. Needs users:read. */
+export interface PluginUsers {
+    /** The user's UI language, like "zh_CN", or null when they never chose one. */
+    getLocale: (userId: string) => Promise<string | null>;
 }
 export interface PluginOpenIsolatedWindowRequest {
     /** http(s) only. Refused when it points anywhere else. */
@@ -1738,8 +1766,13 @@ export interface PluginContext {
     readonly hosts: PluginHosts;
     /** SSH through core's connect pipeline. Needs ssh:connect and credentials:use. */
     readonly ssh: PluginSsh;
-    /** Login methods, second factors and SSH auth types. Needs auth:provide. */
+    /**
+     * Login methods, second factors and SSH auth types. Needs auth:provide,
+     * except issueUserToken, which needs users:impersonate.
+     */
     readonly auth: PluginAuth;
+    /** What a plugin may learn about a user. Needs users:read. */
+    readonly users: PluginUsers;
     /** Opens Electron windows outside the main renderer. Needs desktop:window. */
     readonly desktop: PluginDesktop;
     /** Host protocol credentials and the user's saved SSH keys. See PluginCredentials. */
@@ -1763,8 +1796,9 @@ export interface PluginContext {
      * no request behind it. Always audited, and every core API inside still
      * applies that user's RBAC.
      *
-     * Needs users:impersonate. That and a `userId` option on services.get or
-     * secrets.getShared are the only ways a plugin can name a user.
+     * Needs users:impersonate. That, auth.issueUserToken and a `userId` option
+     * on services.get or secrets.getShared are the only ways a plugin can act
+     * as a user it names.
      */
     asUser: <T>(userId: string, fn: () => Promise<T> | T) => Promise<T>;
     /** The acting user for the current call, when there is one. */

package/dist/capabilities.js

@@ -35,6 +35,7 @@ export const CAPABILITY_CATALOG = [
     entry("auth:provide", "high"),
     entry("device:serial", "high"),
     entry("notify:hub", "high"),
+    entry("ui:layout", "high"),
     entry("hosts:write", "medium"),
     entry("credentials:use", "medium"),
     entry("credentials:write", "medium"),
@@ -54,6 +55,7 @@ export const CAPABILITY_CATALOG = [
     entry("settings:read-core", "low"),
     entry("plugins:read", "low"),
     entry("ui:surface", "low"),
+    entry("ui:theme", "low"),
 ];
 export const CAPABILITY_IDS = CAPABILITY_CATALOG.map((capability) => capability.id);
 const BY_ID = new Map(CAPABILITY_CATALOG.map((capability) => [capability.id, capability]));