Layouts
A layout draws the whole app: the rail, the sidebar, the tab bar and the screens around the tabs. Termix has no layout of its own. The one people use by default is the bundled Classic Layout plugin, and you can write another.
Layouts need Termix 26.10.3 and engine.api ^1.4.
A layout draws the shell, so it runs in the page, not in a sandboxed frame like other plugin screens. Termix 26.11.2 only let official layouts do that. From Termix 26.11.3 an admin can let community layouts and themes run there too: Plugins, Registries, turn on Community layouts and themes. A layout in the page can see and do anything the signed in user can, so the admin is warned before it turns on. Without it, a community layout can't register and the app shows the repair screen. A layout that also asks for another shell part, like sync:provide, always stays in a frame.
Declare it
{
"capabilities": ["ui:layout"],
"contributes": {
"layouts": [
{
"id": "my-layout",
"label": "layout.name",
"description": "layout.description",
"defaultTheme": "dark"
}
]
}
}
ui:layout is high risk, because a layout draws every screen. Admins see that when they install it. defaultTheme is the theme people get with this layout when nobody picked one.
Register it
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, palette button, your own chrome */}</header>
<SurfaceScope kind="tab">
<ShellConfirmCapture />
<TabStage />
</SurfaceScope>
</div>
);
}
export function activate(app: TermixApp) {
app.registerLayout({
id: "my-layout",
label: "layout.name",
component: MyLayout,
});
}
Pass mobileComponent for phones and narrow windows. The desktop app always uses component.
What Termix keeps
Your layout only draws. Termix keeps the state, so switching layouts never closes a session.
useShell()gives the live shell: tabs, splits, hosts, the docks, the command palette and the user. The registries (tab types, panels, rail items, palette entries, keybindings, actions, slots and dashboard cards) are there as hooks.TabStageis where tabs show. Place it anywhere. Tabs are never remounted when it moves, so a terminal keeps its connection.- Providers for the theme, branding, preferences, server status and surfaces wrap your layout. An error boundary does too.
- Your layout draws the command palette. Termix keeps whether it is open (
shell.palette.isOpen, and Ctrl+K callsshell.palette.open()) and what goes in it: hosts, rail items and the entries plugins register withusePaletteEntries. - Overlays and onboarding stay in Termix.
Settings, Manage and the rest
Screens like Settings, Manage and the Dashboard belong to the layout. Register them as tab types in your layout plugin. Classic Layout does this and also offers its host list and Dashboard as components other plugins can place. Only the chosen layout is loaded, so another layout cannot use Classic Layout's tab types or components.
- Termix always keeps a home tab with the id
dashboard.useShell()leaves it out until a plugin registers adashboardtab type, so a layout without a home screen has no empty tab to show. - When someone switches layouts, Termix closes the tabs the old layout plugin declared, since nothing can draw them anymore.
- A layout without a settings screen should still show
LookSettingsfrom@termix-ssh/plugin-sdk/ui, so people can switch back.shell.tabs.openSingleton("plugins")opens the Plugins tab, which works in every layout.
When it breaks
If a layout fails to load or crashes twice, Termix opens the repair screen instead of a blank page. A fix to a layout is a plugin release, not a Termix release.
For an example, read Plugin-Classic-Layout. It reads the shell with useShellController(), which exposes more than useShell() and can change with Termix. Start from useShell() in your own layout.