tuzig/terminal7

A Next Generation Terminal running over WebRTC

Terminal7 - A touchable terminal multiplexer running over WebRTC

Terminal7 is a terminal that includes a terminal multiplexer made for modern web clients and real time communications over WebRTC. A reincaranation of tmux and screen, Terminal7 is a hybrid app that designed for smart clients.

The code here is in vanilla TypeSctipt, relying chiefly on the following projects:

• CapacitorJS for app packaging & plugins
• Xterm.js for terminal emulation
• noble-ed25519 for key generation
• pion.ly for the WebRTC backend
• Vite for packaging
• Vitest for testing
• Docker compose for acceptance tests
• Playwright for end-to-end tests
• MailHog for an SMRP test double

For networking we use SSH or WebRTC, the web standard for real time communications. WebRTC is UDP based with wide support and a great implmentation in go - pion/webrtc - that we use as a base for our server's agent.

If you're having problems with your first connection, please refer to our troubleshooting guide.

We welcome new contributors and are happy to help, talk to us on our discord server.

Getting Started

You can get Terminal7 for free from the App Store or Google Play.

To run from source, you should start by forking the repo (or using tuzig/terminal7 if you just want to test), cloning it and from it's root run:

yarn install
yarn test
yarn start

then point your browser at the printed URL, usually http://localhost:5173.

Installing the server

To connect from the browser you'll need the webexec agent running. webexec is an open source WebRTC server written in go and based on pion. Terminal7 should offer to install it for you, but if it doesn't, open TWR and run install to ensure your agent is up.

If you that doesn't work you can install webexec using go:

go install github.com/tuzig/webexec@latest
webexec start

If you don't have go, you can use our line installer to download the binary for your system and start it:

  bash <(curl -sL https://get.webexec.sh)

webexec will start an HTTP WHIP server on port 7777, waiting for the client to connect. If pperbook user is set, webexec will also connect to peerbook.io so it can accept connections even when behind-the-NAT.

webexec's CLI has a growing set of commands, use webexec to get help on the current set.

Clipboard integration

Terminal7 has a clipboard integration that works over WebRTC. From the CLI you can:

• webexec copy < FILE to get the file into the client's clipboard
• webexec paste to print rhe client's clipboard to stdout

If no peer are actives, e.g. you're using a classic terminal, webexec will look for the tools:

• pbcopy, pbpaste on MacOS
• xclip, xsel on Linux

neovim integration will let you use use the + and * named buffer to copy to and from the clipboard. Just 12 lines in your init.lua:

    vim.g.clipboard = {
        name = 'webexec',
        copy = {
            ["+"] = {'webexec', 'copy'},
            ["*"] = {'webexec', 'copy'},
        },
        paste = {
            ["+"] = {'webexec', 'paste'},
            ["*"] = {'webexec', 'paste'},
        },
        cache_enabled = true,
    }

When webexec is not install, neovim will try the default clipboard tools like xclip or pbcopy.

Running the acceptance tests

TL;DR: run docker and ./aatp/run

Terminal7 has a suite of acceptance tests that run over a docker compose virtual lab. They include end-to-end tests and run on PRs to ensure the code is solid. To learn more about the tests, please refer to ./aatp/README.md documentation.

terminal7's Issues

Handle window.onresize

When I flip my tablet, the layout stay the same but the size in rows and cols changes. When this happens we need to call fit() on all panes and send the new sizes. This requires API changes - adding support for an array as the value of resize_pty.

Long tap on a tab name should let you change its name

Changing the <a> element to a <input>

Split where the finger swipes

Today we split the screen 50/50. It's smarter to read the finger's position and split accordingly.

terminal7's paneMargin should be in pixels in css

Completely remove the Terminal7.paneMargin and use css margin to set it.

Support iOS Multitasking

Add index.html to the test

Today the tests runs with an empty index.html as a result all the code that adds elements to the screen is enclosed in an if (elem != null) . It's not only an eye sore, but it also means that there's quite a bit of code that is not covered by the tests.

Improve visibility & usability by evenly distributing buttons

In the navbar and tabbar we should try and fill the entire bar where each button takes has the same width

When In home page, globe's colour should be magenta

In general, the current page/function is coloured in magenta.

Getting empty screen space when closing panes

Start with a |- layout and split the bottom right pane. Next, focus on the large pane on the left and hit d to close it:

Add a bit of padding to each temrinal element

Add a css bit:

.xterm { margin: 10px; }

Adds a bit of margin to the terminal text but confused the xtermjs's fit plugin which resulted in the having the last line hidden.

Let the user drag a tab name to the trash

A 15 year old playing with the prototype tried dragging the tab name to the trash.

The UI should allow him to do it.

Make the Trash Button work

When clicking the trash the current pane should be closed

Loosing tab name and place in the tab abr

To recreate long press on "Tab 1" and lose focus without entering any keys.

support double CTRL-a

Just pass it on and we can control tmux.

Make the Looking glass work

Clicking the looking glass should turn the nav bar into an input field and let me key for a search string. After each letter I key, matched strings are scrolled to and highlighted in the active pane.

Clicking enter looks for the previous match in the terminal buffer.

Notify when webexec is not running on the server

This is what we display today:

Tell the user to run pgrep webexec on the server to ensure it's running

Loosing gestures after zoom-in-out

To recreate start with a |- layout and choose the bottom left pane. zoom in, zoom out. Swipe on one of the other panes and you get... nothing. I suspect zooming in confuses hammerjs and we need to either find a better way to zoom or reset hammerjs on all the other panes after zoom out.

make it possible to map every button to ESC and other special keys

https://youtu.be/yknLnJ287pY?t=85

Support The Clipbboard

This issue is waiting for tuzig/webexec#29 

webexec's API will add get_clipboard and
set_clipboard commands. This should allow the user
off a properly configured nvim to yank a line vim
and get it in the iPad's clipboard.

In Disconnect modal, rename "Shutdown" to "Close"

and make it work.

Add a server command to the welcome message

Here' the message:

---

To start a connection run this command on your server and enter its IP addres:

$ webexec <offer>

dev host address: __________

---

The is the same offer we use in the body of a post to /connect. When the user enters the address, t7 will try to connect to the server.

Add pane navigation keys

Let the user move between panes by using CTRL hjkl like I'm used from tmux-vim-navigator

Package as an iPadOS app

probably using cordova

Handle the "!" button

The ! creates a new window and moves the active pane there.

Close window on its last pane closing

There should be two ways of closing a window:

• Closing its last pane
• Pressing the trash

Fix pane.fix vertical overflow

It's probably because of how we work with xtermjs fit add-on.

Fix the + & ! buttons height

Make them smaller, same size as the buttons on the nav bar.

Fix zoom

Zoom-in-zoom-out works only once.

Add a leader key

Today, all the commands are just CTRL key combination. For example CTRL-z is used to zoom in. The problem with that is that CTRL-z is important for the shell and we should be smarter and imitate tmux that have a leader key used as prefix to all command keys. The default leader is CTRL-b but most people change it to CTRL-a which should be out default leader.

Zoom in does not change the terminal's size

To recreate, login and split the window, run htop on one of the pane and press CTRL-z to zoom in. htop should take all of the screen and not:

)

When zooming using the keyboard terminal7 disconnects from the keyboard

Make CSS meaningful and responsive

We need to support both iPad screen sizes in portrait & landscape orientation. In the future we'll have more screen sizes so it's better to make it responsive.

To recommended process is:

• learn the design
• come up with a sensible hierarchy
• ensure meaningful names
• code it all in src/css/terminal7.css
• open a PR

Support pan on panes borders

When the user pans a border between two panes he wants to resizes the cells on both side of the border.

Split should happen where the finger splits

Today the place where the pane splits seems a bit random.

Handle tab names overflow

When opening many tabs the tab bar is running out of space and tab names are displayed on the the navbar. Instead we should have a burger button, that holds the window names that don't fit the screen, like Tab 6 and Tab 7 below :

Make the buttons 3d

as in : https://superdevresources.com/3d-css-button/

Add re-sizing notification

To keep things transparent and to make sure our resize works (which probably doesn't...) we need to add an indication of size change. When we get an Ack on a resize request we will display, roughly at the center of the pane the new dimensions as in "24x80" for a second and fade it away.

On closing the last pane of the second tab

weird shit happens and you go back to home instead on going back to the first tab.

Add the "new window" button

We're missing a button - a + - displayed at the right of the #tabbar . Clicking on the button will create a new window with a single, focused pane. For now, use numbers for the window name. Renaming windows is another issue.

Support pinch

Pinch will let the user change a pane's font size. When the gesture ends, fit() should be called on all the cells so that terminals will grow to fill their containing element.

Failing to reconnect when changing wifi

To recreate, connect to a remote host, change the wifi and try to reconnect.

Add connectivity indicators

Add two indicators one for the network connectivity and one for host communications.

Store & restore the windows layout

Windows layout should be saved to local storage and read when re-connecting to the server. The layout is removed from storage only when the user asks to close the host.

Support "press" on a server @ home page

press should pop up a modal allowing us to:

• connect|disconnectd
• edit
• delete

Use two fingers to scroll

Using a single finger to scroll makes terminal7 split vertically occasionally. By switching to two fingers scrolling we avoid the confusion and making sure scrolling won't split the pane.

Add a chaos monkey test

Write a test that splits a few times and than close the panes in random. Assert the last pane takes the entire screen and that document is clean.

Don't remember hosts when the user asks not to

When the user unchecks the "remember host" checkbox the host shouldn't appear on the home pages and shouldn't be stored to the db

When zoomed in disconnect modal doesn't show

to recreate: zoom in on a pane, disconnect the wifi. wait 5 seconds and press and zoom out. The disconnect dialog is there, it's probably with a lower z-index than the zoomed pane.

Serialize layouts to/from tmux format

For easier debugging and tmux compatibility we need text serialization. Here's what it looks like in tmux:

0c36,173x44,0,0{80x44,0,0,4,92x44,81,0[92x21,81,0,5,92x22,81,22,29]}]

The first number is a checksum, followed by size of offsets of every cell with {} to donate a vertical split groups of cells and [] for horizontal one.

Support key repeat

Today, when you hold a key down you get the key you pressed only once.