@termix-ssh/plugin-sdk 1.0.11 → 1.0.12

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # 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.

package/PLUGIN-GUIDE.md

@@ -1,6 +1,6 @@
 # Termix plugin guide
 
-SDK 1.0.11 | Plugin API 1.3.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.
@@ -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.
@@ -478,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                                                           |
@@ -485,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
@@ -496,6 +497,95 @@ Slots you can fill include `terminal.toolbar`, `terminal.toolbarStatus`, `termin
 `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
@@ -775,6 +865,7 @@ To run your own registry instead, see https://docs.termix.site/develop/registrie
 | `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                                    |
@@ -794,6 +885,7 @@ To run your own registry instead, see https://docs.termix.site/develop/registrie
 | `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/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]));

package/dist/frontend.d.ts

@@ -222,6 +222,146 @@ export interface TabsApi extends Pick<ShellApi, "openTab" | "openSingletonTab" |
     /** Called once the shell has restored its tabs after login. */
     onReady: (listener: () => void) => Disposer;
 }
+/**
+ * A whole-app layout. Core renders the chosen one inside its providers and an
+ * error boundary; everything it shows comes from useShell(). Declare it in
+ * manifest contributes.layouts and add the ui:layout capability.
+ */
+export interface LayoutContribution {
+    id: string;
+    /** Your own i18n key or plain text, the same as the manifest's label. */
+    label: string;
+    component: ComponentType;
+    /** Shown on phones and narrow windows. The desktop app never uses it. */
+    mobileComponent?: ComponentType;
+    /** Theme to start with when nobody chose one. */
+    defaultTheme?: string;
+}
+/** A tab as a layout sees it. Splits are tabs too, with a `split` field. */
+export interface ShellTabState extends PluginTabRecord {
+    instanceId: string;
+    customLabel?: string;
+    /** Set while the tab sits in a split pane. */
+    parentSplitTabId?: string;
+    openedAt?: number;
+}
+/** What a dock region shows and how it is sized, in Normal-size pixels. */
+export interface ShellDockState {
+    view: string | null;
+    open: boolean;
+    width: number;
+    dragging: boolean;
+    setView: (view: string | null) => void;
+    setWidth: (width: number) => void;
+    /** Starts a drag from the dock's edge, from a mousedown. */
+    startResize: (event: {
+        clientX: number;
+        preventDefault: () => void;
+    }) => void;
+    resetWidth: () => void;
+}
+/** The live shell: state and actions, nothing drawn. Read with useShell(). */
+export interface ShellController {
+    tabs: {
+        list: ShellTabState[];
+        /** What a tab bar shows: tabs not sitting in a split. */
+        topLevel: ShellTabState[];
+        activeId: string;
+        /** True once saved tabs were restored after login. */
+        ready: boolean;
+        /** The user turned on tab numbers. */
+        showNumbers: boolean;
+        setActive: (id: string) => void;
+        reorder: (topLevel: ShellTabState[]) => void;
+        close: (id: string) => Promise<void>;
+        rename: (id: string, label: string) => void;
+        /** Reconnects or reloads a session tab. */
+        refresh: (id: string) => void;
+        reconnectAll: () => void;
+        openSingleton: (type: string) => string | undefined;
+    };
+    split: {
+        /** The split shown now, or null. */
+        activeId: string | null;
+        focusedPaneId: string | null;
+        /** Every split with its panes, for a split menu. */
+        summaries: Array<{
+            id: string;
+            label: string;
+            full: boolean;
+            panes: Array<{
+                id: string;
+                index: number;
+                tabId: string | null;
+                label: string | null;
+            }>;
+        }>;
+        activeFull: boolean;
+        /** Split a tab, apply a preset, unsplit, add to a pane. */
+        handleAction: (action: Record<string, unknown> & {
+            kind: string;
+        }) => void;
+    };
+    hosts: {
+        list: PluginHostRecord[];
+        loading: boolean;
+        loaded: boolean;
+        reload: () => Promise<void>;
+    };
+    regions: {
+        left: ShellDockState & {
+            view: string;
+        };
+        right: ShellDockState;
+        /** What a rail click does: toggles or switches the left dock. */
+        railClick: (view: string) => void;
+        openInRightDock: (view: string) => void;
+        toggleRightDock: () => void;
+    };
+    palette: {
+        isOpen: boolean;
+        open: () => void;
+        close: () => void;
+    };
+    fullscreen: {
+        active: boolean;
+        toggle: () => void;
+    };
+    /** The same callbacks tabs and panels get. */
+    actions: ShellApi;
+    env: {
+        isMobile: boolean;
+        isElectron: boolean;
+        user: {
+            username: string;
+            isAdmin: boolean;
+        };
+        permissions: string[];
+        branding: {
+            appName: string | null;
+            tagline: string | null;
+            logo: string | null;
+        };
+    };
+    /** Core registries, as hooks a layout calls while rendering. */
+    registries: {
+        useRailItems: () => ReadonlyArray<{
+            id: string;
+        } & Record<string, unknown>>;
+        usePanels: () => ReadonlyArray<{
+            id: string;
+        } & Record<string, unknown>>;
+        useTabTypes: () => ReadonlyArray<{
+            id: string;
+        } & Record<string, unknown>>;
+        useDashboardCards: () => ReadonlyArray<{
+            id: string;
+        } & Record<string, unknown>>;
+    };
+    logout: (options?: {
+        manual?: boolean;
+    }) => void;
+}
 export interface RailItemContribution {
     /** Must be declared in manifest contributes.tabs or contributes.panels. */
     id: string;
@@ -886,6 +1026,12 @@ export interface TermixApp extends TermixAppInfo {
     registerSshAuthEditor: (editor: SshAuthEditorContribution) => Disposer;
     registerLoginMethod: (method: LoginMethodContribution) => Disposer;
     registerSecondFactorUI: (factor: SecondFactorContribution) => Disposer;
+    /**
+     * A whole-app layout. Declared in manifest contributes.layouts with the
+     * ui:layout capability. Only the chosen layout's plugin is loaded, so
+     * register it in activate. Needs plugin API 1.4.
+     */
+    registerLayout: (layout: LayoutContribution) => Disposer;
     /**
      * Translates a key from the plugin's own locales, for code outside a
      * component (a toast from activate). Components use useTranslation().
@@ -993,6 +1139,7 @@ export interface PluginHostBridge {
     useTheme: () => {
         theme: "light" | "dark";
     };
+    useShell: () => ShellController | null;
     toast: ToastApi;
     getApi: (pluginId: string) => PluginApiClient;
     getApiFor: (pluginId: string, origin: unknown) => PluginApiClient;
@@ -1154,6 +1301,11 @@ export declare function useCurrentUser(): CurrentUser | null;
 export declare function useTheme(): {
     theme: "light" | "dark";
 };
+/**
+ * The live shell, for a layout. Null outside the signed-in app. Needs plugin
+ * API 1.4.
+ */
+export declare function useShell(): ShellController | null;
 export declare function useToast(): ToastApi;
 export declare function logActivity(type: string, hostId: number, hostName: string): Promise<void>;
 /** Tells the shell hosts were added or changed, so its lists reload. */

package/dist/frontend.js

@@ -98,6 +98,13 @@ export function useCurrentUser() {
 export function useTheme() {
     return requireHost().useTheme();
 }
+/**
+ * The live shell, for a layout. Null outside the signed-in app. Needs plugin
+ * API 1.4.
+ */
+export function useShell() {
+    return requireHost().useShell();
+}
 export function useToast() {
     return requireHost().toast;
 }