States
What the user sees in every connection, pane and error state
Every empty, failed and not-installed place has one look (EmptyState),
except a session with no spaces (below): an
SF Symbol (32 pt, light, secondary), a title (15 pt semibold), at most one
selectable text under it (13 pt secondary, up to 3 lines; a program's output
in 12 pt monospaced, up to 12 lines), then an optional command (12 pt
monospaced, tertiary, up to 2 lines), and at most two buttons, the first
one prominent glass, the second glass. In a list or a small panel the same
look is compact (20 pt symbol, 13 pt title, 12 pt text). Where the full look does not fit (a short card), it
is compact, and it scrolls under the card's header when that does not fit either; it never covers the header.
A plugin's install question and the browser's "Open this page?" scroll the same way. Every connecting and loading
place has one loader (Loader): an icon over a small spinner and one line,
and under it at most two lines of what the work is doing.
| State | What the user sees |
|---|---|
| herdr not installed on This Mac (macOS) | a box symbol, "herdr is not installed" over "Ovvi runs on herdr, which keeps your sessions running." (one line, about as wide as the command under it) and the install command (12 pt monospaced, tertiary), and Install herdr (Install herdr); remote machines work without it |
| Installing herdr | the loader "Installing herdr…" with the installer's last line under it, then "Connecting…"; a failure: "herdr did not install" over the installer's last lines and Try Again |
| Connecting | the machine's icon over "Connecting to ‹machine›…" (‹machine› · ‹session› for a session other than default) with a spinner, after 0.3 s, so a fast connect shows nothing. Also from a click on Connect (or a machine just added) until the session answers; ssh's question replaces it while it is up, and it shows again 0.3 s after the answer |
| herdr missing on a remote machine | "herdr is not installed on ‹machine›" over the same line and the install command, and Install herdr, which installs it over SSH |
| herdr older than 0.9.3 | "herdr is too old" over "herdr ‹version› is too old; 0.9.3 or newer needed.", no button: the running server's version counts. The app asks herdr again every 2 s, so the page clears by itself once a newer server runs. |
| A card's terminal stream failed (for example herdr updated but not restarted: the API works, terminal streams fail) | over the card's fill, compact: "The terminal stopped" over herdr's error text, and Retry. The card asks herdr again by itself at most every 5 s, at a snapshot, and keeps the panel meanwhile. Only a stream that fails twice says so: the second time when it opens again while its page answers. After a first failure (a stream that ended with its connection, also while its card was out of view), while the page finds out why a read failed, and while it reconnects, the card shows nothing of its own; once the page answers it loads (its last picture, a spinner after 0.5 s) while its stream opens again |
| herdr server not running on This Mac | the session symbol (a stack, rectangle.stack), "‹session› is not running" (over why a start failed, if one did, until the session answers or the next Start) and Start ‹session› (a launchd job, D47; a second start of the same session joins the one that runs), per page: the page stays open and its other pages are not touched |
| Starting a session (Start ‹session›) | the loader: the session symbol over "Starting ‹session›…", until the session answers or the start fails (up to 10 s) |
| herdr server not running on a remote machine | "‹session› is not running" and Start ‹session›, which starts it with nohup over SSH |
| A window with nothing to restore (launch, ⌘N, a Dock reopen) | the new-window view: Ovvi's icon and name over each machine's sessions; it reads each machine's session list and opens no session by itself |
| SSH auth failed | Disconnected: a network symbol with a slash (network.slash), "Disconnected from ‹machine›" over ssh's message, and Connect |
| Host key changed | Disconnected: ssh's warning with the new fingerprint, and Connect, which fails the same way until the user fixes known_hosts |
| Connection lost (Reconnecting) | the cards dim to 0.5 and take no clicks, and a notice with a spinner says "Reconnecting to ‹machine›…" (‹machine› · ‹session›, as above), with herdr's or ssh's reason as a smaller second line when the failure gives one (for example "Ovvi needs Perl on ‹target›"). It has no ×, sits under a notice when both show, and is small, at the page's bottom as every notice is, so it no longer covers the middle of the cards. A page with no cards (a first connect that failed, a space with no tabs) shows the loader instead, as Connecting does: the machine's icon over the same line and the reason. It is the page's one state: no card shows one of its own (no "The terminal stopped", no error or loader), nor an empty page; the app retries every 2 s without prompts (a remote machine's SSH connection backs off from 2 s to 30 s), then reads a fresh snapshot (Health check). Also when a page's first connect fails while its server runs |
| Reconnecting needs a password, a code or a host key answer | "Disconnected from ‹machine›" over ssh's text, and Connect; the app stops retrying, and only this button may prompt (The SSH connection) |
| Request timed out (10 s) | A write shows the notice "herdr did not answer", with no Retry. A read shows Reconnecting |
| Pane in use on another device | the content (watching) and "In use elsewhere · Take Back" |
| Session controlled in another window | cards dim a little; a bottom capsule "Controlled in another window" with Take Back (Control capsule) |
| Close a pane that runs a program | "Close “‹pane label, else its folder›”?" over "‹program› is running in it and will end, here and in every herdr client. This cannot be undone." (a pane that runs only its shell closes at once) |
| Close a tab, other tabs, tabs to the right or a space | asks only when a pane of them runs a program besides its shell: "‹programs› is (are) running in it (them)." then the pane count and the same warning |
| No spaces | the sidebar's page stays quiet (no rows, no text). The window's content: Ovvi's icon (64 pt), "This session has no spaces" over "A space is a project folder, with its own tabs and terminals.", New Space (⌃⌘T) and Open Folder… (This Mac's folder panel, or a remote machine's folder field) |
| A space with no tabs | "No tabs in ‹space›" and New Tab with its shortcut (herdr closes a space with its last tab, so it shows only for a moment) |
| Move refused by herdr | herdr's reason in words, in the notice |
| A drop step failed | the pane stays where it got to; the notice says so |
| Open Session: the name is not a valid herdr name | no Create row |
| Open Session: the session did not start, or its server did not answer within 10 s | the row's spinner stops, the panel stays open, and a notice capsule in the panel says "Could not start ‹session›." with herdr's reason and Retry |
| Open Session: the page does not connect (herdr's socket fails) | the page shows the reconnecting state |
| Open Session: a running session stopped before it opened | Open starts it, as for a stopped session |
| Open Session: Delete of a stopped session another window shows | that page stays "not running"; its Start makes a new session of that name, with one space in the home folder |
| Open Session: Stop or Delete failed | the notice capsule in the panel says "Could not stop ‹session›." or "Could not delete ‹session›." with herdr's reason and Retry |
| A restored page's session is not running (after a restart of the Mac) | it starts by itself, as its Start does, with no click: "Starting ‹session›…", then the page. On a remote machine the window connects first (it asks what ssh asks, as Connect does). A start that fails shows "‹session› is not running" with why and Start ‹session› to try again. A session deleted since is skipped (on a remote machine that does not answer at launch, its page opens, and its start makes a new session of that name) |
| Detach Session on the last page | Detach Session is disabled; Open Session shows no Detach on its row |
| A write failed | the notice: a capsule with a red symbol and the error, no Retry (a write that timed out may have happened). A notice's buttons are round, as the toast's |
| A write while another write of the session runs | it waits for that one, then runs |
| Go to Directory on a pane that runs a program | the warning notice "A program is running in the pane"; nothing is sent |
| A filter hides every row | compact, with a magnifying glass: "No matching spaces" (sidebar), "No matches in the last ‹count› sessions." or "No sessions found." (Archived Sessions), "No matches" (the palette and the other filter lists) |
| A tab whose split tree the app cannot build | "No layout for this tab" |
| A card's terminal is not settled at the card's size yet (a pane opened for the first time, while herdr resizes its PTY and the program redraws) | the card shows only its fill (a small spinner after 0.5 s); a click anywhere on it, the spinner too, gives it the keyboard, which it keeps once it draws; the terminal fades in over 0.06 s once herdr's frames stop for 0.1 s, or 0.4 s after the first frame (at once with Reduce Motion). A watching card shows its first frame |
| A card visited before comes back (one of the 25 most recently shown, D46) | at once, with what its program printed meanwhile; no fade, no wait |
| A card comes back after it let go of its stream and surface (past the 25 most recently shown, D46) | its last picture shows over a new surface until herdr's frames settle, then the new picture; if the system took the picture back, as a pane opened for the first time (above) |
| A card's size keeps changing (a window drag, a divider drag, the sidebar) | its terminal keeps its grid, clipped at the top left; 150 ms after the last change (or when a window drag ends) it takes the new size and keeps showing its last picture until herdr's frames at the new grid settle (as above), then shows them at once, never blank. The same for a new text size (⌘+, ⌘-). A layout motion (a split, a close, a zoom) gives it its new size once, as it starts |
| Find with no match | "0 of 0", nothing highlighted, no scroll |
| A folder dropped on the Dock icon with no window | a window opens on the new-window view; the space opens once the user picks a session of This Mac and its page is live |
A notification click or an ovvi://float URL that starts the app (no window) | the first window opens that session instead of the new-window view, then selects or floats the pane |
| A folder dropped on the Dock icon while the page in view is not a live page of This Mac | the folders wait for a live page of This Mac in view |
| A done agent the user opens | it stays Done (the green check on its agent row, its icon on the tab and the space) while its pane has the keyboard, also with the app in the background; once another pane, tab, space or session gets the keyboard, it is Idle; its row stays in place |
| A space with no agents | no chevron: nothing to unfold |
How it works: Checks on connect, How a stream ends.