diff --git a/README.md b/README.md index 63fcc50..897c89d 100755 --- a/README.md +++ b/README.md @@ -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 | diff --git a/client/browser_tools_test.go b/client/browser_tools_test.go index 97ee1be..4af08b7 100644 --- a/client/browser_tools_test.go +++ b/client/browser_tools_test.go @@ -3,6 +3,8 @@ package main import ( "bytes" "encoding/base64" + "fmt" + "strings" "testing" "github.com/gdamore/tcell/v2" @@ -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") + } + } + }) + } + } +} diff --git a/client/navigation_ui.go b/client/navigation_ui.go index 12884eb..dbeefc1 100644 --- a/client/navigation_ui.go +++ b/client/navigation_ui.go @@ -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 { diff --git a/docs/browser-tools.md b/docs/browser-tools.md index 9eedcbb..9165275 100644 --- a/docs/browser-tools.md +++ b/docs/browser-tools.md @@ -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 diff --git a/docs/getting-started.md b/docs/getting-started.md index 520bd53..84487c7 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -58,10 +58,12 @@ 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 @@ -69,7 +71,7 @@ Click a field and type normally. Page keys include arrows, Tab/Shift+Tab, Enter, 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 diff --git a/docs/quickstart.md b/docs/quickstart.md index be0a3fb..caa06e1 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -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. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index e6d9c7b..24a422b 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -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 diff --git a/docs/vimium.md b/docs/vimium.md index b958b17..2cdb187 100644 --- a/docs/vimium.md +++ b/docs/vimium.md @@ -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. diff --git a/scripts/build-website.mjs b/scripts/build-website.mjs index 813890d..2c04924 100644 --- a/scripts/build-website.mjs +++ b/scripts/build-website.mjs @@ -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'], diff --git a/tests/website/site.test.cjs b/tests/website/site.test.cjs index 398b93b..a1a6a42 100644 --- a/tests/website/site.test.cjs +++ b/tests/website/site.test.cjs @@ -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}`);