Skip to main content

Frames

From Termix 26.11.2, the frontend of a plugin made for plugin API 2 never runs in the app's page. Termix loads it into sandboxed frames. Each frame has its own origin, no login cookie and no way into the rest of the page or into other plugins. Your code stays the same: activate(app), the SDK hooks and the UI kit work as before, with the same look, fonts and theme.

Official plugins that are the shell itself (a layout, a theme or a login method) still run in the page.

How your plugin runs​

  • One hidden background frame runs activate and keeps what has no screen of its own: actions, command palette entries and groups, keybinding actions, rail badges, host dots, companion defaults and shell.overlay components.
  • Every screen you register is its own frame that runs activate too: tabs, panels, dashboard cards, companions, homepage widgets, settings components, host editor sections and slot components.
  • app.frame.role is "background" or "view". Skip polling and timers in views.
  • Each frame has its own module state. Code that opens a dialog from anywhere (a palette entry, a keybinding) should live in the background frame, next to the shell.overlay component that shows it.

What crosses to Termix​

What you register reaches Termix as data:

  • Icons must come from lucide-react. Termix draws them by name.
  • Functions become calls into your frame. A callback Termix reads while it draws (when, label, items, visible, validate) answers its default first and your answer a moment later. Keep these cheap.
  • A companion's getHandle() gives a handle whose methods return promises. sendInput and paste need terminal.sendToActive or terminal.sendToSession in your manifest uses.
  • A popover or menu can't leave its frame. Keep menus in tabs and panels, not in small slots.
  • A component in another plugin's slot sizes itself the way that slot's owner says: declareActionSlot({ id, accepts, fit }) with fit "inline" (as wide and tall as the content, for row items and badges), "content" (full width) or "fill" (the whole box). Without a fit, Termix guesses from the slot id. A fallback element the owner passes in stays outside the frame and shows while your component draws nothing.

Not available in a frame: host badges, host status indicators and host editor toolbar items with a component. Give them useDot or useValue instead: useValue returns a plain value (bars, a stat, a badge, a dot or text) that Termix draws, and it runs in your background frame once per row on screen.

  • useShell() in a frame is read only: the open tabs, the active tab, split summaries, the user and whether it is a phone. tabs.setActive works right after the person used your frame.
  • A background frame keeps running only while something needs it: a value in use, an action, a view of your plugin or live work it started in activate (timers, sockets, subscriptions). Otherwise it stops after 3 idle minutes and Termix answers from what it remembered.
  • To make someone prove a second factor, call app.stepUp(). Termix shows its own prompt and your frame only gets true or false.

Other plugins' parts​

A frame can show other plugins' parts: a slot you declared, an id under your own plugin id, or any id listed in manifest contributes.uses. Read them as always, with useSlotContributions, ComponentSlot, useExtensions, getExtension, usePluginComponent or PluginComponent. Each one is a placeholder: Termix draws the other plugin's own frame over that spot, clipped to yours. You never get a handle on it and it never learns about you. Draw it with ForeignSlot from the UI kit to set a class, a style or interactive={false}.

What needs a click​

A frame can't act on its own for things that reach outside it. A background frame shows a dialog over the whole app only right after the person ran one of your actions, palette entries, keybindings or slot buttons. Opening a link, the clipboard and revoking API keys need a click in your frame just before, and a download one in the last two minutes.

Nothing in a frame loads from another site. Pictures, video and fonts come from your own assets, data: or blob: URLs. For a picture from elsewhere, fetch /plugins/<your id>/image?url=<address> (needs network:outbound or network:sockets) and show the blob.

Network and data​

  • app.api, app.fetch and app.wsUrl reach only your own routes and sockets. Termix gives the frame a short token for that and renews it.
  • The hooks and the UI kit read Termix through the shell, which allows a fixed list: the signed-in user, their permissions, hosts (with only your own host settings), credentials without secrets, your own settings, operations, waiting approvals and recent activity. Saved passwords are not available.
  • A frame can read waiting approvals but never decide one. Decide from a route of your own with ctx.operations.approvals.decide (SDK 2.5.0, needs operations:approve): it works only inside one of your requests, the person on that request decides with their own rights, and API keys are refused.
  • invokeAction runs your own actions and the action ids listed in your manifest uses.
  • Opening links, downloads, the clipboard, toasts and confirms go through the shell. localStorage works and is kept per plugin.
  • The frame can only load code from your plugin's own asset folder and can only talk to your own routes.

Checking your plugin​

checkFrameApp from @termix-ssh/plugin-sdk/testing (SDK 2.1.0) runs activate the way a frame does and lists anything that would not reach Termix:

import { checkFrameApp } from "@termix-ssh/plugin-sdk/testing";
import manifest from "../../manifest.json";
import * as plugin from "../../src/frontend";

it("runs in a frame", async () => {
const { problems } = await checkFrameApp(plugin, { manifest });
expect(problems).toEqual([]);
});

checkFrameViews (SDK 2.5.0) goes further. It renders every view you register (tabs, panels, cards, companions, settings, host editor sections, slot components, extensions) with a test shell and sends every request they make through the same list Termix uses for frames. refused lists the requests a frame would be refused:

import { checkFrameViews } from "@termix-ssh/plugin-sdk/testing";

it("asks Termix only for what a frame may read", async () => {
const { refused } = await checkFrameViews(plugin, {
manifest,
hosts: [host],
});
expect(refused).toEqual([]);
});

Your own routes answer {} unless you pass respond(method, path). errors lists views that threw with that test data, which is not a frame problem by itself.