Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,9 +79,17 @@ If you want sharp terminal text on any terminal, Carbonyl and Browsh are good ch

- **Terminal multiplexers:** tmux, screen, and herdr do not work well yet. Run Termium directly in the terminal window.
- **Docker:** Chromium's sandbox needs namespaces that Docker's default seccomp profile blocks. Run the container with `--security-opt seccomp=unconfined`.
- **Text is pixels:** page text is part of the image, so you cannot select it as terminal text, and screen readers do not see it.
- **Text is pixels:** page text is part of the image, so terminal-native selection and screen readers cannot read it. On `main`, select inside the webpage and use **F10 → Copy selected text** (F8); see [Browser tools](docs/browser-tools.md).
- **Platforms:** no native Windows or Linux ARM64 packages yet.

## Browser tools on main

Open **F10** or click **Menu** for **Developer tools** (F12), **Copy selected text**
(F8), and **Extensions**. Drag to select text, copy through the terminal clipboard,
and paste with your terminal's paste shortcut. Load unpacked extensions with
`termium --extension /path/to/extension`. These additions are on `main`, pending
the next release. [Controls, availability and limits](docs/browser-tools.md).

## Documentation

| Guide | What it covers |
Expand Down
57 changes: 57 additions & 0 deletions client/browser_tools_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ package main
import (
"bytes"
"encoding/base64"
"fmt"
"strings"
"testing"

"github.com/gdamore/tcell/v2"
Expand Down Expand Up @@ -47,3 +49,58 @@ func TestBrowserToolsKeysAndClipboard(t *testing.T) {
t.Fatal("paste triggered developer tools")
}
}

// Exercise the menu users see, including scrolling in a short terminal. Keep
// labels and action routing covered together rather than invoking action IDs.
func TestBrowserToolsMenuKeyboardAndMouse(t *testing.T) {
for _, name := range []string{"Developer tools", "Copy selected text", "Extensions"} {
for _, mouse := range []bool{false, true} {
t.Run(fmt.Sprintf("%s/mouse=%t", name, mouse), func(t *testing.T) {
screen := uiScreen(t, 80, 10)
kh, ops := recorder()
kh.state = pb.BrowserState{ActiveTabId: "tab", Generation: 7}
kh.globalKey(key(tcell.KeyF10), false)
found := false
for i := 0; i < len(kh.menuLabels()); i++ {
if strings.HasPrefix(kh.menuLabels()[kh.menuIndex], name) {
found = true
break
}
kh.HandleKeyEvent(screen, key(tcell.KeyDown))
}
if !found {
t.Fatal("menu entry missing")
}
kh.Draw(screen)
if mouse {
rect := kh.menuRect()
y := rect.Min.Y + 1 + kh.menuIndex - kh.menuStart()
if y <= rect.Min.Y || y >= rect.Max.Y-1 {
t.Fatal("entry is offscreen")
}
kh.HandleMouseEvent(screen, tcell.NewEventMouse(rect.Min.X+2, y, tcell.Button1, 0))
} else {
kh.HandleKeyEvent(screen, key(tcell.KeyEnter))
}
if kh.menu || len(*ops) != 1 {
t.Fatal("menu did not dispatch and close")
}
op := (*ops)[0]
switch name {
case "Developer tools":
if op.navigation == nil || op.navigation.Action != pb.NavigationAction_DEVTOOLS {
t.Fatal("wrong tools action")
}
case "Extensions":
if op.navigation == nil || op.navigation.Action != pb.NavigationAction_EXTENSIONS {
t.Fatal("wrong extensions action")
}
case "Copy selected text":
if op.selection == nil || op.selection.TabId != "tab" || op.selection.Generation != 7 {
t.Fatal("copy lost selection target")
}
}
})
}
}
}
2 changes: 1 addition & 1 deletion client/navigation_ui.go
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ func (kh *KeyboardHandler) Draw(s tcell.Screen) {
}
}
if kh.help {
lines := []string{"Termium shortcuts", "", "Ctrl+L Address (select all)", "Alt+Left / Alt+Right Back / Forward", "Alt+Home Home page", "Ctrl+R or F5 Reload / Stop", "F10 Menu F6 Mouse keys", "F12 Developer tools F8/Ctrl+C Copy", "Paste using your terminal paste shortcut", "Ctrl+Q Quit Escape x3 Emergency exit", "", "Vimium: f/F links · hjkl scroll · i insert", "t new tab · J/K switch · x close · X reopen", "? Vimium help · Escape cancels a mode", "Ctrl+T new tab · Ctrl+W close tab", "Mouse: click, drag, wheel, right/middle buttons.", "Mouse keys: arrows/hjkl, Enter click, Space drag,", "r right-click, m middle-click, u/d scroll.", "", "Enter or Escape to close"}
lines := []string{"Termium shortcuts", "", "Ctrl+L Address (select all)", "Alt+Left / Alt+Right Back / Forward", "Alt+Home Home page", "Ctrl+R or F5 Reload / Stop", "F10 Menu F6 Mouse keys", "F12 Developer tools F8/Ctrl+C Copy", "Paste using your terminal paste shortcut", "F10: Extensions manager · load with --extension", "Ctrl+Q Quit Escape x3 Emergency exit", "", "Vimium: f/F links · hjkl scroll · i insert", "t new tab · J/K switch · x close · X reopen", "? Vimium help · Escape cancels a mode", "Ctrl+T new tab · Ctrl+W close tab", "Mouse: click, drag, wheel, right/middle buttons.", "Mouse keys: arrows/hjkl, Enter click, Space drag,", "r right-click, m middle-click, u/d scroll.", "", "Enter or Escape to close"}
drawOverlay(s, lines)
}
if kh.quitConfirm {
Expand Down
23 changes: 23 additions & 0 deletions docs/browser-tools.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,28 @@
# Developer tools, clipboard and extensions

These features are on the development branch `main`; they are not in the latest
published release yet. Updating from source makes them available. See
[development setup](development.md) and [release availability](installation.md).

## Find the tools in Menu

Click **Menu** in the top bar or press **F10**. Use Up/Down (or Tab/Shift+Tab)
and Enter, or click an item. Escape closes the menu. On short terminals, keep
moving down to reveal the remaining entries.

| Menu item | What it does | Shortcut |
| --- | --- | --- |
| Developer tools | Opens Chromium's inspector for the current page | F12 |
| Copy selected text | Sends the page's selection to the terminal clipboard | F8 or Ctrl+C in page focus |
| Extensions | Opens Chromium's extension manager to inspect extensions and options | Menu only |
| Mouse keys | Enables keyboard movement, clicking and selection by dragging | F6 |
| Shortcut help | Shows Termium's inline key reference | F1 |

Paste uses your terminal's paste command; there is no menu action that reads the
host clipboard. Loading an unpacked extension uses `--extension` at launch;
**Extensions** opens the manager, not a terminal file picker. Sound is still
being investigated and has no playback or mute control in Menu yet.

## Inspect a page

Press **F12**, or choose **Developer tools** from the F10 menu. Termium opens
Expand Down
6 changes: 4 additions & 2 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,18 +58,20 @@ Press **Ctrl+L** or click the address field. Its contents are selected, so start
| F10 | Open or close Menu |
| F1 | Shortcut help |
| F6 | Toggle mouse keys |
| F12 | Open developer tools for the current page |
| F8 or Ctrl+C in page focus | Copy selected page text |
| Ctrl+Q | Quit confirmation |
| Escape three times rapidly | Emergency exit, including during dialogs |

Use Menu when a terminal intercepts a shortcut. Menu supports mouse clicks, Up/Down, Tab/Shift+Tab, Enter, and Escape. It contains tab controls, navigation, address, mouse keys, help, and Quit.
Use Menu when a terminal intercepts a shortcut. Menu supports mouse clicks, Up/Down, Tab/Shift+Tab, Enter, and Escape. It contains tab controls, navigation, address, mouse keys, **Developer tools**, **Copy selected text**, **Extensions**, help, and Quit. On short terminals, use Down or Tab to reveal more entries. The browser tools are currently available on `main`, pending release; see [Browser tools](browser-tools.md).

## Interact with a page

Click a field and type normally. Page keys include arrows, Tab/Shift+Tab, Enter, Backspace/Delete, Home/End, Page Up/Down, and modifier combinations that your terminal can report. The application shortcuts above remain reserved. Outside text fields, bundled [Vimium](vimium.md) handles navigation: **f** shows link hints, **j/k** scroll, **t** opens a tab, **J/K** switch tabs, and **x/X** close/reopen a tab. Press **?** for Vimium help or **F1** for Termium help.

Mouse support includes left/right/middle buttons, hover, double/triple clicks, held-button dragging, wheel scrolling, and back/forward buttons when reported by the terminal. Shift+wheel scrolls horizontally. Drags remain captured until release, including a release outside the page area. Pointer accuracy is limited to the center of a terminal cell.

Use your terminal's paste command. Bracketed paste inserts literal text; pasted text cannot activate Termium shortcuts. Middle-click opens links in tabs; select them from the top row or all-tabs picker. Host clipboard integration and native browser file choosers remain limited; see [Vimium limitations](vimium.md#help-and-limits).
Drag to select page text, then use **Menu → Copy selected text**, **F8**, or **Ctrl+C** in page focus. Copy requires your terminal to permit OSC 52 clipboard writes. Use your terminal's paste command (commonly Ctrl+Shift+V on Linux or Cmd+V on macOS); bracketed paste inserts literal text without activating Termium shortcuts. Middle-click opens links in tabs. See [Browser tools](browser-tools.md) for clipboard limits, developer tools and loading extensions. Native browser file choosers remain limited.

## Mouse keys

Expand Down
4 changes: 3 additions & 1 deletion docs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,9 @@ Setup supplies the private runtime, downloads and verifies Chromium and Vimium,
- **F1**: Termium help. **?**: Vimium help.
- **Ctrl+Q**, then **Enter**: quit.

The top bar also has tabs, Back, Forward, Reload, an address field, and Menu. Mouse clicks, dragging, and scrolling work alongside keyboard navigation.
The top bar also has tabs, Back, Forward, Reload, an address field, and Menu (**F10**). Mouse clicks, dragging, and scrolling work alongside keyboard navigation.

On the development build, Menu also includes **Developer tools** (F12), **Copy selected text** (F8), and **Extensions**. Paste with your terminal's paste shortcut. See [Browser tools](browser-tools.md) for availability, selection, clipboard requirements, and unpacked extension loading.

Kitty or sixel graphics are selected automatically, with an ASCII graphics fallback when neither is available. To try the fallback explicitly, use `termium --renderer tcell` in a new terminal.

Expand Down
17 changes: 16 additions & 1 deletion docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,22 @@ For sixel, try `--palette websafe`. A smaller terminal window can also reduce re

## Keyboard shortcuts behave unexpectedly

Arrow keys normally go to the page. If they move a local cursor, press F6 or Escape to leave mouse keys mode. Termium reserves Ctrl+L, Ctrl+T, Ctrl+W, Ctrl+Q, Ctrl+R, Alt+Left/Right, F1, F5, F6, and F10; other supported page keys pass through. Terminals may intercept modifiers or mouse buttons before Termium receives them. Consult the [current controls](getting-started.md) and [Vimium navigation](vimium.md).
Arrow keys normally go to the page. If they move a local cursor, press F6 or Escape to leave mouse keys mode. Termium reserves Ctrl+L, Ctrl+T, Ctrl+W, Ctrl+Q, Ctrl+R, Alt+Left/Right, Alt+Home, F1, F5, F6, F8, F10, and F12, plus Ctrl+C while page input is focused; other supported page keys pass through. Terminals may intercept modifiers or mouse buttons before Termium receives them. Consult the [current controls](getting-started.md) and [Vimium navigation](vimium.md).

## Copy, paste, or developer tools are missing

These tools are on `main` and are not in the latest published release yet. A
source checkout does not update an installed executable: rebuild/install from
source as described in [development](development.md). Open **F10 → Developer
tools**, **Copy selected text**, or **Extensions** if your terminal intercepts
the function keys. Keep moving down in a short menu to reveal additional items.

If copy says “No text selected”, select text inside the webpage first. If it says
“Copy sent to terminal clipboard” but the clipboard does not change, check your
terminal's OSC 52 permissions. That message confirms sending, not acceptance.
Paste with the terminal's paste shortcut, not bare Ctrl+V. Extensions must be
unpacked directories supplied with `--extension`; the menu opens their manager.
See [Browser tools](browser-tools.md) for the full behavior and limits.

## Termium stops responding

Expand Down
4 changes: 2 additions & 2 deletions docs/vimium.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,9 +49,9 @@ Leave this mode before typing into a page field. Outside mouse keys mode, webpag

## Help and limits

**F1** opens terminal help and **F10** opens Menu. These remain usable on browser-owned pages. Termium reserves Ctrl+L, Ctrl+T, Ctrl+W, Ctrl+Q, Ctrl+R, Alt+Left/Right, Alt+Home, F1, F5, F6, and F10. A terminal may intercept keys before Termium receives them.
**F1** opens terminal help and **F10** opens Menu. These remain usable on browser-owned pages. Termium reserves Ctrl+L, Ctrl+T, Ctrl+W, Ctrl+Q, Ctrl+R, Alt+Left/Right, Alt+Home, F1, F5, F6, F8, F10, and F12, plus Ctrl+C while page input is focused. A terminal may intercept keys before Termium receives them.

Vimium cannot inject into Chromium's protected pages, including `chrome://` pages. Termium shows an unavailable status there; use Ctrl+L or Menu. The bundled welcome page supports Vimium. Native file choosers, host clipboard integration, persistent profiles, and full popup-window behavior are not supported commitments yet. Vimium clipboard commands target Chromium's environment, which may differ from the terminal host over SSH or WSL.
Vimium cannot inject into Chromium's protected pages, including `chrome://` pages. Termium shows an unavailable status there; use Ctrl+L or Menu. The bundled welcome page supports Vimium. Native file choosers, persistent profiles, and full popup-window behavior remain limited. Termium's **Menu → Copy selected text** / **F8** sends the page selection to the terminal clipboard using OSC 52; paste uses the terminal's own paste shortcut. Vimium clipboard commands target Chromium's environment, which may differ from the terminal host over SSH or WSL. [Browser tools](browser-tools.md) describes the development-build features and their menu entries.

Smooth scrolling is disabled and hints use static, high-contrast styling to reduce graphics work. The webpage and Vimium overlays still travel through Chromium screenshots and the selected Kitty, sixel, or character renderer. Character mode cannot make screenshot text as readable as a graphics terminal.

Expand Down
1 change: 1 addition & 0 deletions scripts/build-website.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ const docs = [
['installation', 'Installation', 'Build, install, and launch Termium.', 'Start here'],
['getting-started', 'Getting started', 'Your first page, mouse input, menus, and home-page settings.', 'Start here'],
['vimium', 'Keyboard & tabs', 'Vimium bindings, real tabs, and the mouse keys.', 'Using Termium'],
['browser-tools', 'Browser tools', 'Developer tools, selection, copy/paste, and unpacked extensions.', 'Using Termium'],
['terminals', 'Terminal support', 'Kitty, sixel, ASCII graphics, and graphics performance.', 'Using Termium'],
['troubleshooting', 'Troubleshooting', 'Resolve display, navigation, and startup problems.', 'Using Termium'],
['development', 'Development', 'Build from source and contribute a change.', 'Contributing'],
Expand Down
3 changes: 2 additions & 1 deletion tests/website/site.test.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,8 @@ test('public site is complete, links resolve, and the welcome page stays separat
if (url.hash) anchors.push([url.pathname, decodeURIComponent(url.hash.slice(1))]);
}
}
assert.equal(visited.size, 11, 'Expected product page, docs index, and nine guides');
assert.equal(visited.size, 12, 'Expected product page, docs index, and ten guides');
assert.ok(visited.has('/docs/browser-tools/'), 'Browser tools must be reachable from the public documentation');
for (const [route, id] of anchors) {
await page.goto(origin + route);
assert.ok(await page.evaluate(id => !!document.getElementById(id), id), `Broken fragment ${route}#${id}`);
Expand Down
Loading