Shell layer chrome

Interaction design for OpenShellOrg display and control layers.

Core claim

TUIs belong on ephemeral overlays, not in stdout. Users should see pasted instructions before they run, track multi-step blocks, and cancel without guessing what half-ran.

Prompt gutter and auto-help

Open Shell reserves a gutter band (display overlay, not stdout) left of context tokens. When prohelp matches the input buffer, a ? help affordance appears there automatically — users do not type --help first.

Trust affordance: spontaneous ? signals "this shell knows this command has help." Hiding help behind memorized flags erodes confidence.

Glyph choices

Glyph HCI verdict

⍰ (U+2370)

Rejected in user testing — poor monospace visibility

Raw ?

Acceptable v0 fallback

Custom TUI glyph (overlay-drawn)

v1 target — legible at small sizes; not tied to terminal font cell

Placement

  • Primary: gutter at prompt start (before grey app tokens) — recommended

  • Secondary: inline ghost ? after matched command prefix when terminal is narrow

Gutter also carries shell-owned list chrome (▶, ▪, A–Z markers) so CLIs stop spamming printf arrows into stdout.

Top context bar: host chrome vs overlay

Open Shell is mode-engaged: it tries to insert the top context bar into the parent terminal’s native chrome first (OpenShellOrg terminal fork is first-class). Hovering that bar over the shell is an inferior placement for always-on session chrome. If probe/offer is rejected or unsupported → same bar on the display-overlay stack (never stdout).

Users should barely notice except native host chrome feels more app-like. Spec: host chrome negotiation.

Demo simulates both with a Host chrome | Overlay control (labeled simulation).

Host chrome vs hover widgets

Keep the distinction clear:

  • Host chrome (inserted) — shell top bar; optional stacked app top bar under it for the active CLI

  • Hover widgets — host-owned floats over terminal content (color picker, GUI editor, file upload, …​) — not a substitute for inserted session chrome

Spec: host native widgets. Demo mock for Widget: Host | Overlay is future work (skip until cheap).

Typography (cell font)

Open Shell’s curated default terminal/cell face is Consolas (system font — not bundled), chosen so monospace fits non-monospace dew/host chrome and the context bar. Users may override; fallback: Cascadia Mono → Courier New → monospace.

Spec: typography @ shell-architecture. Demo CSS: shell-context-demo. == Prompt line modes

Always-on top context bar hosts a line mode control (1-line / 2-line):

  • 2-line — context bar above; gutter (with ▶) + command below (preferred Open Shell default)

  • 1-line — classic combined row for muscle-memory compare

Both keep token focus, gutter ?, and ▶ interactive. Detail: shell context chrome and OpenShellOrg prompt-spatial-layout.

Paste preview overlay

Layout

+--------------------------------------------------+
| PASTE PREVIEW (5 lines visible, framed)          |
| line 1 of pasted block                           |
| line 2 ...                                       |
|        [ PgUp / PgDn scroll ]  Enter accept Esc  |
+--------------------------------------------------+
| [gcloud: ftn]  user@host:path >                  |
| normal command output below...                   |
+--------------------------------------------------+

  • Frame uses TUI outline — visually distinct from scrollback

  • Overlay sits above output; disappears after accept/reject

  • Not copied when user pipes session log (unless opt-in audit)

Stepped execution tracker

After accept, overlay may compress to a checklist:

  • Done steps: checked, muted

  • Current step: highlighted

  • Failed step: error color + jump focus on base layer output

Cancel during steps: control plane surfaces honest copy ("remaining steps aborted; step 2 may have changed files").

Control-plane focus

Invisible routing layer — user sees focus through chrome state:

Focus target Visual hint

Overlay

Top frame border bright; input line dimmed

Context token

Token focus ring (shell context chrome)

Base input

Normal prompt; overlay hidden

Mode swap UI

Prefer one selector control (dropdown in always-on strip), not two equal buttons for UNIX vs Nu.

  • Label shows current mode plainly: unix / structured

  • Keyboard: Ctrl+PgUp/Ctrl+PgDn cycles — document in overlay help

  • Avoid implying one mode is "secondary"

Startup layout

Startup document renders in overlay zone — welcome columns, env-health, context summary. Dismisses on first keystroke or timeout; never floods scrollback.

Naming note

Public runtime: Open Shell — not proshell (prohelp must stay shell-agnostic).

Demo (planned)

Shell layer desk — paste preview + step tracker + mode selector mockup.

Literature