zidane-ui/ terminal/ headless
import { … } from 'zidane-ui/terminal/headless'ui/src/terminal/headless/index.ts
Functions#
createMemoryTerminalLayoutsFunction#
Creates TerminalLayouts held in memory, per scope key.
function createMemoryTerminalLayouts(): TerminalLayoutsReturns
createTerminalStoreFunction#
Creates the TerminalStore over a host. An app creates one per page
and hands it to TerminalProvider (code outside React reads it too).
function createTerminalStore(host: TerminalHost): TerminalStoreParameters
| Name | Type | Description |
|---|---|---|
| host | TerminalHost | The terminal host. |
Returns
scopeOfTerminalKeyFunction#
The scope a key names when nothing better is known (a reload after a signal from an unknown scope).
function scopeOfTerminalKey(key: string): TerminalScopeParameters
| Name | Type | Description |
|---|---|---|
| key | string | A |
Returns
terminalProjectKeyFunction#
The key of a project's or a draft's list, as the host names it (root, draftId).
function terminalProjectKey(signal: { draftId?: string; root: string }): stringParameters
| Name | Type | Description |
|---|---|---|
| signal | { draftId?: string; root: string } | The project root and the draft, if any. |
Returns
stringterminalScopeKeyFunction#
A scope's identity: the session id when bound, else draft:<id> or
project:<root> (a session id never starts with either).
function terminalScopeKey(scope: TerminalScope): stringParameters
| Name | Type | Description |
|---|---|---|
| scope | TerminalScope | The scope. |
Returns
stringClasses#
TerminalStoreClass#
The terminal store: every scope's terminals, the live views, the layouts.
class TerminalStoreConstructor
new TerminalStore(host: TerminalHost)Parameters
| Name | Type | Description |
|---|---|---|
| host | TerminalHost | The terminal host. |
Returns
Properties
| Name | Type | Description |
|---|---|---|
| hostreadonly | TerminalHost | The host the store reads and acts through. |
| layoutsreadonly | TerminalLayouts | Where the per-scope layouts live: the host's, else in memory. |
Methods
addView()
addView(terminalId: string, view: TerminalViewSink): () => voidRegisters a live view of terminalId; returns its unregister.
Parameters
| Name | Type | Description |
|---|---|---|
| terminalId | string | The terminal it shows. |
| view | TerminalViewSink | What it does with the terminal's signals. |
Returns
() => voidadoptDraft()
adoptDraft(draft: TerminalScope, session: TerminalScope): Promise<void>Hands the draft's terminals to the session created from it. Shown in the session at once (the host's lists follow); a failed hand-over (or a host that cannot hand over) gives them back to the project, never leaving them tied to a draft nobody shows.
Parameters
| Name | Type | Description |
|---|---|---|
| draft | TerminalScope | The draft's scope. |
| session | TerminalScope | The session's scope. |
Returns
Promise<void>autoOpen()
autoOpen(
scope: TerminalScope,
placement: TerminalPlacement,
measure?: () => TerminalGrid | null,
): Promise<void>Opens a terminal for the user when a placement is opened on a scope with
none of theirs (none at all, or only the agent's). The drawer opens one
only when the user opened it (toggleDrawer). A drawer open because the
scope copied its project's layout, or left open before a relaunch, starts
no shell: otherwise every session visited would keep one. Skipped while
another open is in flight (the keybinding opens the drawer and a terminal
at once).
Parameters
| Name | Type | Description |
|---|---|---|
| scope | TerminalScope | The scope. |
| placement | TerminalPlacement | The placement that opened. |
| measure? | () => TerminalGrid | null | Measures the grid the area fits, once the state is in. |
Returns
Promise<void>close()
close(scope: ScopeRef, terminalId: string): Promise<void>Closes a terminal.
Parameters
| Name | Type | Description |
|---|---|---|
| scope | ScopeRef | The scope or its key (where an error shows). |
| terminalId | string | The terminal. |
Returns
Promise<void>dismissError()
dismissError(scope: ScopeRef): voidClears the scope's error.
Parameters
| Name | Type | Description |
|---|---|---|
| scope | ScopeRef | The scope or its key. |
ensure()
ensure(scope: TerminalScope): Promise<void>Loads the scope's state once (callers mount per scope).
Parameters
| Name | Type | Description |
|---|---|---|
| scope | TerminalScope | The scope. |
Returns
Promise<void>forget()
forget(scope: ScopeRef): voidForgets a scope whose session was deleted. One a view still shows is kept, and stays after the view goes (one entry per such scope); a later signal for the scope starts it afresh.
Parameters
| Name | Type | Description |
|---|---|---|
| scope | ScopeRef | The scope or its key. |
get()
get(scope: ScopeRef | null): ScopeTerminalsA scope's terminals (by its scope or key).
Parameters
| Name | Type | Description |
|---|---|---|
| scope | ScopeRef | null | The scope or its key; |
Returns
layout()
layout(scope: TerminalScope): TerminalLayoutThe scope's layout (drawer, order, agent filter).
Parameters
| Name | Type | Description |
|---|---|---|
| scope | TerminalScope | The scope. |
Returns
open()
open(
scope: TerminalScope,
target?: TerminalTarget,
size?: TerminalGrid,
): Promise<TerminalInfo | null>Opens a terminal and makes it active. Resolves null when it failed (see error).
Parameters
| Name | Type | Description |
|---|---|---|
| scope | TerminalScope | The scope. |
| target? | TerminalTarget | A session's terminal: in its environment or on the user's machine. Ignored without a session. |
| size? | TerminalGrid | The first grid. Default: the last one fitted, else 80×24. |
Returns
Promise<TerminalInfo | null>openInDrawer()
openInDrawer(scope: TerminalScope): voidOpens the drawer and a new terminal in it.
Parameters
| Name | Type | Description |
|---|---|---|
| scope | TerminalScope | The scope. |
panelOnScreen()
panelOnScreen(scope: ScopeRef): booleanWhether the side panel's Terminal tab is on screen for the scope.
Parameters
| Name | Type | Description |
|---|---|---|
| scope | ScopeRef | The scope or its key. |
Returns
booleanrefresh()
refresh(scope: TerminalScope): Promise<void>Reads the scope's state again (one read in flight per scope).
Parameters
| Name | Type | Description |
|---|---|---|
| scope | TerminalScope | The scope. |
Returns
Promise<void>releaseDraft()
releaseDraft(draftId: string): Promise<void>Gives the draft's terminals back to the project (a discarded draft). Never rejects.
Parameters
| Name | Type | Description |
|---|---|---|
| draftId | string | The draft. |
Returns
Promise<void>restart()
restart(scope: ScopeRef, terminalId: string): Promise<void>Restarts a terminal's process.
Parameters
| Name | Type | Description |
|---|---|---|
| scope | ScopeRef | The scope or its key (where an error shows). |
| terminalId | string | The terminal. |
Returns
Promise<void>reveal()
reveal(scope: ScopeRef, terminalId: string, placement: TerminalPlacement): voidMakes terminalId the active terminal, focused by placement, with no
shell auto-opened over it (revealTerminal picks the placement).
Parameters
| Name | Type | Description |
|---|---|---|
| scope | ScopeRef | The scope or its key. |
| terminalId | string | The terminal. |
| placement | TerminalPlacement | The placement that focuses it. |
revealTerminal()
revealTerminal(scope: TerminalScope, terminalId: string): voidShows one of the scope's terminals, focused: in the side panel's Terminal tab when it is on screen, else in the drawer, opened for it. Opening the drawer this way starts no shell of the user's, and the strip shows the agent's terminals again when it hid the one revealed.
Parameters
| Name | Type | Description |
|---|---|---|
| scope | TerminalScope | The scope. |
| terminalId | string | The terminal. |
runIn()
runIn(scope: TerminalScope, input: string): Promise<TerminalInfo | null>Opens a new terminal in the scope, shows it, and types input into it (a
reply's shell block, Run in a terminal). The shell reads what was typed
once it starts. Resolves with the terminal, or null when none opened
(the scope's error says why).
Parameters
| Name | Type | Description |
|---|---|---|
| scope | TerminalScope | The scope. |
| input | string | What to type, newline included to run it. |
Returns
Promise<TerminalInfo | null>setActive()
setActive(scope: ScopeRef, terminalId: string): voidMakes terminalId the scope's active terminal.
Parameters
| Name | Type | Description |
|---|---|---|
| scope | ScopeRef | The scope or its key. |
| terminalId | string | The terminal. |
setFittedSize()
setFittedSize(scope: TerminalScope, size: TerminalGrid | null): voidRemembers the grid the scope's terminal area fits: new terminals start at it.
Parameters
| Name | Type | Description |
|---|---|---|
| scope | TerminalScope | The scope. |
| size | TerminalGrid | null | The grid, or |
setHidden()
setHidden(scope: ScopeRef, terminalId: string, hidden: boolean): Promise<void>Hides a terminal from the agent, or shows it again.
Parameters
| Name | Type | Description |
|---|---|---|
| scope | ScopeRef | The scope or its key (where an error shows). |
| terminalId | string | The terminal. |
| hidden | boolean | Hide it. |
Returns
Promise<void>showPanel()
showPanel(scope: ScopeRef): () => voidThe side panel's Terminal tab shows the scope's terminals, on screen; returns its unregister.
Parameters
| Name | Type | Description |
|---|---|---|
| scope | ScopeRef | The scope or its key. |
Returns
() => voidshowPlacement()
showPlacement(scope: ScopeRef): () => voidA placement (drawer, panel tab) is showing the scope's terminals; clears the badge. Returns its unregister.
Parameters
| Name | Type | Description |
|---|---|---|
| scope | ScopeRef | The scope or its key. |
Returns
() => voidsubscribe()
subscribe(listener: () => void): () => voidRegisters a listener called after any scope changed. Returns its unsubscribe.
Parameters
| Name | Type | Description |
|---|---|---|
| listener | () => void | Called after each change. |
Returns
() => voidtakeFocus()
takeFocus(scope: ScopeRef, seq: number): voidThe placement took focus request seq: drop it (a newer request stays).
Parameters
| Name | Type | Description |
|---|---|---|
| scope | ScopeRef | The scope or its key. |
| seq | number | The request taken. |
terminal()
terminal(terminalId: string): TerminalInfo | nullThe terminal with this id, in whichever scope holds it.
Parameters
| Name | Type | Description |
|---|---|---|
| terminalId | string | The terminal. |
Returns
TerminalInfo | nulltoggleDrawer()
toggleDrawer(scope: TerminalScope): voidShows or hides the scope's drawer.
Parameters
| Name | Type | Description |
|---|---|---|
| scope | TerminalScope | The scope. |
updateLayout()
updateLayout(scope: TerminalScope, patch: Partial<TerminalLayout>): voidChanges the scope's layout.
Parameters
| Name | Type | Description |
|---|---|---|
| scope | TerminalScope | The scope. |
| patch | Partial<TerminalLayout> | The fields to change. |
Constants#
DEFAULT_TERMINAL_LABELSConstant#
The default English strings of the terminal components.
const DEFAULT_TERMINAL_LABELS: { terminalActions: string; terminalAddToChat: string; terminalAddToChatNowhere: string; terminalClear: string; terminalClose: (title: string) => string; terminalConnecting: string; terminalCopy: string; terminalCouldNotLoad: (message: string) => string; terminalDisconnected: string; terminalDismissError: string; terminalDrawer: string; terminalExitedPlain: string; terminalExitedWith: (code: number) => string; terminalFailedToStart: string; terminalGlyphAgent: string; terminalGlyphDisconnected: string; terminalGlyphError: string; terminalGlyphStarting: string; terminalHiddenFromAgent: string; terminalHiddenFromAgentIcon: string; terminalHide: string; terminalHideAgentTerminals: string; terminalHideFromAgent: string; terminalLinkOnServer: (serverName: string) => string; terminalNew: string; terminalNewLocal: string; terminalNoneOpen: string; terminalNotAvailable: string; terminalOpenSettings: string; terminalPaste: string; terminalReconnect: string; terminalRestart: string; terminalRestartAction: string; terminalShow: string; terminalShowAgentTerminals: string; terminalShowToAgent: string; terminalStartedByAgent: (taskId?: string) => string; terminalStarting: string; terminalStopAgentTask: (title: string) => string; terminalTabs: string; terminalToggleLabel: (open: boolean, startedByAgent: number) => string; terminalUnreachable: string }DEFAULT_TERMINAL_LAYOUTConstant#
The layout of a scope nobody changed.
const DEFAULT_TERMINAL_LAYOUT: TerminalLayoutInterfaces#
ScopeTerminalsInterface#
One scope's terminals as the components read them.
interface ScopeTerminalsProperties
| Name | Type | Description |
|---|---|---|
| activeId | string | null | The active terminal. |
| error | string | null | The last failed call (open, restart, …), shown until the next success. |
| focus | TerminalFocusRequest | null | A revealed terminal waiting for its placement to focus it. |
| state | TerminalSessionState | null | Null until the first |
| unseenAgent | number | Agent terminals that started while nothing showed terminals (sessions only). |
TerminalAttachResultInterface#
What a client needs to start showing a terminal: its history, and where live output resumes.
interface TerminalAttachResultProperties
| Name | Type | Description |
|---|---|---|
| data | string | Output history to show first. |
| offset | number | Character offset where live output resumes. |
| terminal | TerminalInfo | The terminal that was attached. |
TerminalDataSignalInterface#
A batch of a terminal's output starting at stream offset offset (or, for a reset, its history up to there).
interface TerminalDataSignalProperties
| Name | Type | Description |
|---|---|---|
| data | string | The output. |
| offset | number | Stream offset of the first character of |
| terminalId | string | The terminal. |
TerminalFocusRequestInterface#
A terminal revealed on request, for the placement it was revealed in to focus once (takeFocus).
interface TerminalFocusRequestProperties
| Name | Type | Description |
|---|---|---|
| placement | TerminalPlacement | The placement that focuses it. |
| seq | number | Increases with every request. |
| terminalId | string | The terminal. |
TerminalGridInterface#
A grid size in cells.
interface TerminalGridProperties
| Name | Type | Description |
|---|---|---|
| cols | number | Columns. |
| rows | number | Rows. |
TerminalHostInterface#
The terminal host.
interface TerminalHostProperties
| Name | Type | Description |
|---|---|---|
| layouts? | TerminalLayouts | Where the per-scope terminal layouts live. Absent: they last as long as the page. |
| ack | (terminalId: string, clientId: string, offset: number) => Promise<void> | A view wrote the output up to |
| adoptDraft? | (draftId: string, sessionId: string) => Promise<{ adopted: string[] }> | Moves a draft's terminals into the session it became; resolves with the ids moved. Absent: they go back to the project. |
| attach | (terminalId: string, clientId: string) => Promise<TerminalAttachResult> | Attaches a view ( |
| close | (terminalId: string) => Promise<void> | Closes a terminal (an agent's: ends its task). |
| detach | (terminalId: string, clientId: string) => Promise<void> | Detaches a view. |
| listen | (sink: TerminalSignalSink) => () => void | Starts telling |
| open | (scope: TerminalScope, options: TerminalOpenOptions) => Promise<TerminalInfo> | Opens a terminal in the scope, at that size. |
| releaseDraft? | (draftId: string) => Promise<void> | Gives a draft's terminals back to the project (the draft was discarded). Absent: nothing to give back. |
| resize | (terminalId: string, clientId: string, cols: number, rows: number, claim: boolean) => Promise<void> | A view asks for a grid size; |
| restart? | (terminalId: string) => Promise<void> | Restarts a terminal's process. Absent: no Restart. |
| setHidden? | (terminalId: string, hidden: boolean) => Promise<void> | Hides a session's terminal from its agent, or shows it again. Absent: no such toggle. |
| state | (scope: TerminalScope) => Promise<TerminalSessionState> | The scope's terminals and whether this host can run them. Rejects when they cannot be read. |
| write | (terminalId: string, data: string, from?: TerminalWriteOrigin) => Promise<void> | Sends input (typing, a paste, an emulator reply). |
TerminalInfoInterface#
Description of one terminal, as the host reports it to clients.
interface TerminalInfoProperties
| Name | Type | Description |
|---|---|---|
| cols | number | Width in character cells. |
| createdAt | number | Creation time in epoch ms. |
| cwd | string | Working directory the terminal started in. |
| environment | string | Environment kind it runs in ( |
| error? | string | Failure message, when |
| exitCode? | number | Exit code, once the process has exited. |
| hiddenFromAgent | boolean | The agent's terminal tools skip it. |
| id | string | Terminal id. |
| label | string | Stable name ("Terminal 2", or the agent's command). |
| lastActivityAt | number | Time of the last output or input in epoch ms. |
| owner | TerminalOwner | Who started the terminal. |
| program? | string | The program in the foreground, for terminals on this machine. |
| rows | number | Height in character cells. |
| scope? | TerminalProjectScope | Set on project / draft terminals ( |
| sessionId | string | The session it belongs to; |
| sizeSeq | number | Bumped on every size change: signals and attach replies reach a view by different routes, so it keeps the newest size, not the last to arrive. |
| status | TerminalStatus | Connection and process state. |
| target | TerminalTarget | Where the terminal runs. |
| taskId? | string | The background task it runs (agent terminals). |
| title? | string | Title the program set (OSC 0/2), if any. |
TerminalLayoutInterface#
A scope's terminal layout.
interface TerminalLayoutProperties
| Name | Type | Description |
|---|---|---|
| terminalHeight | number | null | The drawer's height (px); |
| terminalHideAgent | boolean | The tab strip leaves the agent's terminals out. |
| terminalOpen | boolean | The drawer under the chat is shown. |
| terminalOrder | readonly string[] | Terminal ids in the user's dragged order ( |
TerminalLayoutsInterface#
Where the per-scope layouts live.
interface TerminalLayoutsProperties
| Name | Type | Description |
|---|---|---|
| get | (scope: TerminalScope) => TerminalLayout | The scope's layout. The same object until it changes (components read it with |
| show? | (scope: TerminalScope) => void | A component shows the scope (the app may seed its layout from the project's). Absent: nothing to do. |
| subscribe | (listener: () => void) => () => void | Registers a listener called after any layout changed. Returns its unsubscribe. |
| update | (scope: TerminalScope, patch: Partial<TerminalLayout>) => void | Changes the scope's layout. |
TerminalOpenOptionsInterface#
Where a new terminal starts, and its first grid size.
interface TerminalOpenOptionsProperties
| Name | Type | Description |
|---|---|---|
| cols | number | Columns. |
| rows | number | Rows. |
| target? | TerminalTarget | A session's terminal: in its environment ( |
TerminalScopeInterface#
Whose terminals a store entry, a drawer or a panel shows.
interface TerminalScopeProperties
| Name | Type | Description |
|---|---|---|
| cwd | string | Where a terminal without session opens. |
| draft? | string | The new-chat draft (never together with |
| root | string | The project root: a scope without session or draft is keyed by it. |
| session? | string | The session the terminals are a session's. |
TerminalSessionStateInterface#
The terminals of one session and whether this host can run them.
interface TerminalSessionStateProperties
| Name | Type | Description |
|---|---|---|
| available | boolean | False when this host can't run terminals (the GUI without the daemon). |
| environment | { kind: string; remote: boolean } | Kind of the session's environment, and whether it runs somewhere else. |
| reason? | string | Why not, when |
| terminals | TerminalInfo[] | Terminals of the session. |
TerminalSignalSinkInterface#
What the host tells the store, as it happens.
interface TerminalSignalSinkProperties
| Name | Type | Description |
|---|---|---|
| output | (signal: TerminalDataSignal) => void | Output of a terminal some view is attached to. |
| projectChanged | (signal: { draftId?: string; root: string; terminals: TerminalInfo[] }) => void | A project's ( |
| relink | (connected: boolean) => void | The link to what runs the terminals changed (a daemon restarted, a
connection came back): every scope reloads, and with |
| reset | (signal: TerminalDataSignal) => void | A view fell too far behind: its content is replaced with the terminal's history. |
| sessionChanged | (sessionId: string, terminals: TerminalInfo[]) => void | A session's full list of terminals changed (its agent started one, one exited…). |
TerminalViewSinkInterface#
What a view does with the signals of the terminal it shows.
interface TerminalViewSinkProperties
| Name | Type | Description |
|---|---|---|
| output | (offset: number, data: string) => void | Live output from |
| reattach | () => void | The link came back: attach again from scratch. |
| reset | (offset: number, data: string) => void | The view's content is replaced with the history up to |
TerminalWriteOriginInterface#
What a view sends along with a write.
interface TerminalWriteOriginProperties
| Name | Type | Description |
|---|---|---|
| clientId | string | The view writing. |
| response? | boolean | The emulator's answer to a query in the output, not typing (the host keeps only the size owner's). |
Types#
TerminalLabelsType#
The shape of the terminal label dictionary.
type TerminalLabels = typeof DEFAULT_TERMINAL_LABELSTerminalPlacementType#
Where a scope's terminals show: the drawer under the chat, or the side panel's Terminal tab.
type TerminalPlacement = 'drawer' | 'panel'TerminalTargetType#
Where it runs: the session's environment, or this machine in the project.
type TerminalTarget = 'session' | 'local'