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
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,7 @@ If you want sharp terminal text on any terminal, Carbonyl and Browsh are good ch
| --- | --- |
| [Installation](docs/installation.md) | One-command setup, availability, and platform targets |
| [Getting started](docs/getting-started.md) | Opening pages, typing, dialogs, and quitting |
| [Browser tools](docs/browser-tools.md) | Developer tools (F12), text copy/paste, and unpacked extensions |
| [Terminal support](docs/terminals.md) | Graphics modes and compatibility |
| [Troubleshooting](docs/troubleshooting.md) | Display issues, startup failures, and bug reports |
| [Vimium and tabs](docs/vimium.md) | Bundled keyboard navigation, tabs, mouse coexistence, and limitations |
Expand All @@ -96,7 +97,7 @@ If you want sharp terminal text on any terminal, Carbonyl and Browsh are good ch

1. **Multiplexers:** tmux and screen support.
2. **Distribution:** Homebrew and AUR packages, more clean-machine testing, automated dependency updates.
3. **Browser polish:** persistent browsing sessions, clipboard integration, dark mode that follows your terminal.
3. **Browser polish:** persistent browsing sessions, richer clipboard formats, dark mode that follows your terminal.
4. **Native Windows:** add native packages; Windows through WSL2 is supported today.

The [installation plan](docs/plans/one-command-install.md) and [browser UI plan](docs/plans/browser-ui.md) define the work and release checks. See [GitHub Releases](https://github.com/codr1/termium/releases) for native packages and release notes.
Expand Down
49 changes: 49 additions & 0 deletions client/browser_tools_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
package main

import (
"bytes"
"encoding/base64"
"testing"

"github.com/gdamore/tcell/v2"
pb "termium/client/pb"
)

func TestBrowserToolsKeysAndClipboard(t *testing.T) {
_ = uiScreen(t, 100, 40)
kh, ops := recorder()
kh.state = pb.BrowserState{ActiveTabId: "tab", Generation: 7}
kh.globalKey(key(tcell.KeyF12), false)
if len(*ops) != 1 || (*ops)[0].navigation.Action != pb.NavigationAction_DEVTOOLS {
t.Fatal("F12 did not open tools")
}
kh.globalKey(key(tcell.KeyF8), false)
if len(*ops) != 2 || (*ops)[1].selection.TabId != "tab" || (*ops)[1].selection.Generation != 7 {
t.Fatal("copy lost target identity")
}
old := graphicsOutput
var output bytes.Buffer
graphicsOutput = &output
t.Cleanup(func() { graphicsOutput = old })
text := "世界\n\x1b]52;c;malicious\a"
kh.result(operationResult{clipboard: &text})
want := "\x1b]52;c;" + base64.StdEncoding.EncodeToString([]byte(text)) + "\a"
if output.String() != want {
t.Fatalf("clipboard must encode content, got %q", output.String())
}
output.Reset()
kh.result(operationResult{clipboard: &text, stale: true})
if output.Len() != 0 {
t.Fatal("stale copy changed clipboard")
}
empty := ""
kh.result(operationResult{clipboard: &empty})
if output.Len() != 0 {
t.Fatal("empty selection cleared clipboard")
}
kh.pasteEvent(true)
kh.globalKey(key(tcell.KeyF12), false)
if len(*ops) != 2 {
t.Fatal("paste triggered developer tools")
}
}
16 changes: 16 additions & 0 deletions client/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,11 @@ import (
"flag"
"fmt"
"os"
"path/filepath"
)

type Config struct {
Extensions []string
InitialURL string
Homepage string
SetHomepage string
Expand All @@ -29,6 +31,17 @@ type Config struct {

func parseFlags() (*Config, error) {
cfg := &Config{}
flag.Func("extension", "Load an unpacked Chromium extension directory (repeatable)", func(value string) error {
absolute, err := filepath.Abs(value)
if err != nil {
return err
}
if value == "" {
return fmt.Errorf("extension directory is required")
}
cfg.Extensions = append(cfg.Extensions, absolute)
return nil
})

showVersion := false
flag.BoolVar(&showVersion, "version", false, "Print version and exit")
Expand Down Expand Up @@ -117,6 +130,9 @@ func parseFlags() (*Config, error) {
}

// Validate server address format
if cfg.ServerAddr != "" && len(cfg.Extensions) > 0 {
return nil, fmt.Errorf("--extension applies to a local browser; configure extensions on the remote server")
}
if cfg.ServerAddr != "" {
// TODO: Add validation for ip:port format
}
Expand Down
12 changes: 12 additions & 0 deletions client/input_dispatcher.go
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,13 @@ import (
)

type browserOperation struct {
selection *pb.NavigationRequest
input *pb.InputEvent
navigation *pb.NavigationRequest
viewport *pb.ViewportSize
}
type operationResult struct {
clipboard *string
operation browserOperation
state *pb.BrowserState
err error
Expand Down Expand Up @@ -105,6 +107,9 @@ func (d *inputDispatcher) run() {
if o.input != nil {
generation = o.input.Generation
}
if o.selection != nil {
generation = o.selection.Generation
}
if o.navigation != nil {
generation = o.navigation.Generation
}
Expand All @@ -128,6 +133,13 @@ func (d *inputDispatcher) run() {
result := operationResult{operation: o}
var trailer metadata.MD
switch {
case o.selection != nil:
var reply *pb.Message
reply, result.err = d.client.GetSelection(ctx, o.selection, grpc.Trailer(&trailer))
if reply != nil && result.err == nil {
result.state = reply.State
result.clipboard = &reply.Text
}
case o.input != nil:
var reply *pb.Message
reply, result.err = d.client.SendInput(ctx, o.input, grpc.Trailer(&trailer))
Expand Down
32 changes: 32 additions & 0 deletions client/keyboard.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ package main

import (
"context"
"encoding/base64"
"fmt"
"image"
"net/url"
Expand Down Expand Up @@ -127,6 +128,24 @@ func (kh *KeyboardHandler) applyState(state *pb.BrowserState) {
}
}
func (kh *KeyboardHandler) result(result operationResult) {
if result.clipboard != nil && result.err == nil && !result.stale {
text := *result.clipboard
if text == "" {
kh.status = "No text selected"
return
}
if len(text) > 64*1024 {
kh.status = "Selection exceeds clipboard limit"
return
}
_, err := fmt.Fprintf(graphicsOutput, "\x1b]52;c;%s\a", base64.StdEncoding.EncodeToString([]byte(text)))
if err != nil {
kh.status = err.Error()
} else {
kh.status = "Copy sent to terminal clipboard"
}
return
}
if result.operation.navigation != nil {
if kh.pendingNavigation != nil && kh.pendingNavigation != result.operation.navigation {
// A newer address/tab command owns the editor and loading state.
Expand Down Expand Up @@ -271,6 +290,15 @@ func (kh *KeyboardHandler) action(id string) {
return
}
switch id {
case "devtools":
kh.navigate(pb.NavigationAction_DEVTOOLS, "")
case "extensions":
kh.navigate(pb.NavigationAction_EXTENSIONS, "")
case "copy":
kh.menu = false
if kh.submit == nil || !kh.submit(browserOperation{selection: &pb.NavigationRequest{TabId: kh.state.ActiveTabId, Generation: kh.state.Generation}}) {
kh.status = "Input queue is busy; try again"
}
case "home":
kh.navigate(pb.NavigationAction_HOME, "")
case "address":
Expand Down Expand Up @@ -346,6 +374,10 @@ func (kh *KeyboardHandler) globalKey(ev *tcell.EventKey, modal bool) (bool, bool
switch {
case ctrl(ev, tcell.KeyCtrlL, 'l'):
kh.openAddress()
case ev.Key() == tcell.KeyF12:
kh.action("devtools")
case ev.Key() == tcell.KeyF8 || (kh.focus == "page" && ctrl(ev, tcell.KeyCtrlC, 'c')):
kh.action("copy")
case ev.Key() == tcell.KeyF10:
kh.action("menu")
case ev.Key() == tcell.KeyF1:
Expand Down
6 changes: 3 additions & 3 deletions client/navigation_ui.go
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import (
"image"
)

var menuIDs = []string{"newtab", "closetab", "reopentab", "tabs", "home", "back", "forward", "reload", "address", "pointer", "help", "quit"}
var menuIDs = []string{"newtab", "closetab", "reopentab", "tabs", "home", "back", "forward", "reload", "address", "pointer", "devtools", "copy", "extensions", "help", "quit"}

func (kh *KeyboardHandler) menuLabels() []string {
if kh.tabsMenu {
Expand All @@ -28,7 +28,7 @@ func (kh *KeyboardHandler) menuLabels() []string {
if kh.pointerMode {
pointer = "Mouse keys: on F6"
}
return []string{"New tab Ctrl+T", "Close tab Ctrl+W", "Reopen closed tab X", "All tabs", "Home Alt+Home", "Back Alt+Left", "Forward Alt+Right", reload, "Open address Ctrl+L", pointer, "Shortcut help F1", "Quit Ctrl+Q"}
return []string{"New tab Ctrl+T", "Close tab Ctrl+W", "Reopen closed tab X", "All tabs", "Home Alt+Home", "Back Alt+Left", "Forward Alt+Right", reload, "Open address Ctrl+L", pointer, "Developer tools F12", "Copy selected text F8", "Extensions", "Shortcut help F1", "Quit Ctrl+Q"}
}
func (kh *KeyboardHandler) menuRect() image.Rectangle {
width := min(34, sDims.Width)
Expand Down 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", "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", "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
3 changes: 3 additions & 0 deletions client/server_launcher.go
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,9 @@ func startServer() error {
}

args := []string{loc.scriptPath}
for _, directory := range cfg.Extensions {
args = append(args, "--extension", directory)
}
if cfg.Homepage != "" {
args = append(args, "--homepage", cfg.Homepage)
}
Expand Down
3 changes: 3 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ Start with [Quickstart](quickstart.md): install, open your first page, and learn
- [Terminal support](terminals.md): choosing a display mode when troubleshooting.
- [Troubleshooting](troubleshooting.md): resolving problems and reporting bugs.
- [Vimium and tabs](vimium.md): keyboard navigation, real tabs, and mouse coexistence.
- [Browser tools](browser-tools.md): developer tools, text copy/paste, and unpacked extensions.

## Contributor guides

Expand All @@ -23,4 +24,6 @@ Start with [Quickstart](quickstart.md): install, open your first page, and learn
- [Browser UI architecture](plans/browser-ui.md): bundled Vimium, tab identity, and keyboard routing.
- [Graphics audit](plans/rendering-audit.md): Kitty/Sixel correctness, measured encoding costs, performance priorities, and help UI integration.

- [Browser audio research](research/browser-audio.md): headless playback feasibility and a local audio-sink proof.

Pages marked **planned** describe work that has not shipped. The usage guides describe the current application.
58 changes: 58 additions & 0 deletions docs/browser-tools.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Developer tools, clipboard and extensions

## Inspect a page

Press **F12**, or choose **Developer tools** from the F10 menu. Termium opens
Chromium's built-in DevTools in a separate Termium tab, initially showing
Elements. Use its panels to inspect HTML/CSS, run console commands, examine
network requests, and debug scripts. Mouse and keyboard input work in the tools.
Vimium does not run on this browser-internal page.

Switch between the page and its tools using the tab bar or F10 → All tabs.
Ctrl+W closes the tools without closing the inspected page. Closing the inspected
page also removes its tools. Termium keeps one inspector at a time; opening tools
for another page replaces the previous inspector. No debugging TCP port is opened.
Breakpoints pause the inspected page, so its frames and input can stop until you
resume execution in DevTools.

## Select, copy and paste

Select webpage text by dragging with the mouse, using mouse keys (F6, Space to
hold/release a drag), or using the page's keyboard selection controls. Press
**F8** or **Ctrl+C** while page input is focused, or choose **Copy selected text**
in F10. Text selections in inputs, textareas, focused frames and open shadow DOM
are supported. Password fields are excluded. A selection may contain up to 64 KiB
of UTF-8 text; empty selections leave the clipboard alone.

Copy uses the terminal's OSC 52 clipboard support. Your terminal must allow it;
“Copy sent to terminal clipboard” confirms sending the request, not permission
from the terminal. It also works over SSH when the local terminal supports OSC 52.
Copy is plain text, not HTML or images, and does not grant webpages clipboard-read
permission. Ctrl+C in the address editor retains its local editor behavior.

Paste with your **terminal's paste shortcut** (commonly Ctrl+Shift+V on Linux or
Cmd+V on macOS). Termium forwards bracketed paste as literal text to the focused
page input, including Unicode and newlines, without interpreting it as Vimium
commands. A bare Ctrl+V key is not a portable request to read the host clipboard.
Clipboard access from a website's own JavaScript remains subject to Chromium's
permissions; this feature is the explicit Termium copy action.

## Load extensions

Pass an unpacked Chromium extension directory containing `manifest.json`:

```sh
termium --extension /path/to/extension https://example.com
termium --extension /path/to/first --extension "/path/with spaces/second"
```

Directories are resolved from your current working directory. Requested
extensions load before the initial page; Vimium remains installed. Invalid or
incompatible extensions produce a browser-startup error rather than being skipped.
Only load extensions you trust with the pages you browse.

Choose **Extensions** from F10 to view Chromium's extension manager, including
extension details and options. Loading is session-specific: supply the arguments
again on the next launch. This does not install CRX files or implement Chrome Web
Store installation, toolbar action buttons, or profile persistence. With a remote
Termium server, configure `--extension` on that server instead of the client.
49 changes: 49 additions & 0 deletions docs/research/browser-audio.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Browser audio feasibility — 2026-10-01

Sound is feasible without moving audio through Go, gRPC or the terminal graphics
protocol when Chromium runs on the user's machine. Chromium can use the host's
normal audio output. This investigation does not enable audio in Termium yet.

## Source evidence

The installed Puppeteer launcher adds `--mute-audio` for headless launches.
Termium launches `headless: true` without filtering that default. Puppeteer's
[official launch documentation](https://pptr.dev/next/api/puppeteer.puppeteernode.launch)
explicitly demonstrates `ignoreDefaultArgs: ['--mute-audio']`.

For an eventual implementation, remove only that default flag and provide an
explicit mute control. Preserve normal autoplay and user-gesture requirements;
there is no need to grant microphone access or disable autoplay protections.
Audio playback is separate from audio capture.

[WSLg](https://github.com/microsoft/wslg) provides an audio server for Linux apps.
An SSH session does not imply audio forwarding: unmuting a browser on a remote
server would play on that server's configured output. Remote sound would need a
separate audio transport and client playback, not a Sixel/Kitty extension.

## Local proof

Host: harpe, Linux under WSL, PulseAudio server `unix:/mnt/wslg/PulseServer`.
A private null sink was created for this test; the browser's `PULSE_SINK` selected
it. Only that sink's monitor was recorded. No default device was changed and no
sound was played through the user's speakers. The sink was unloaded afterward.

Two fresh headless Chromium launches used identical pages. A real CDP-dispatched
button click started a low-gain Web Audio oscillator; AudioContext reported
`running` in both. Raw mono PCM was observed through `parec` at 48 kHz, signed
16-bit little endian. Each run waited 1.8 seconds after the click; recording also
included startup/shutdown, so sample totals are not a latency measurement.

| Launch | Recorded samples | Nonzero samples | Peak absolute PCM amplitude |
|---|---:|---:|---:|
| Default Puppeteer mute | 38,841 | 0 | 0 |
| Remove `--mute-audio` | 38,795 | 4,452 | 1,639 |

This proves audio reaches a host audio sink here. It does not verify physical
speakers, codecs on every site, native macOS output, synchronization with Termium's
rendered frames, or remote playback. Before enabling by default, test those local
platform paths, playback/pause across tabs, browser shutdown, and mute behavior.
No performance claim is made.

Probe and raw log: `/tmp/termium-audio-20261001/{probe.cjs,result.log}` on harpe.
The probe uses only synthetic audio and a dedicated sink.
3 changes: 3 additions & 0 deletions proto/bc.proto
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ service BrowserControl {
rpc GetCurrentUrl (Empty) returns (Url) {}
rpc GetBrowserState (Empty) returns (BrowserState) {}
rpc BrowserCommand (NavigationRequest) returns (BrowserState) {}
rpc GetSelection (NavigationRequest) returns (Message) {}
rpc SendInput (InputEvent) returns (Message) {}
// Paced clients request only as much capture work as they can present.
rpc CaptureScreenshot (ScreenshotRequest) returns (Screenshot) {}
Expand Down Expand Up @@ -84,6 +85,8 @@ enum NavigationAction {
CLOSE_TAB = 7;
REOPEN_TAB = 8;
HOME = 9;
DEVTOOLS = 10;
EXTENSIONS = 11;
}

message NavigationRequest {
Expand Down
5 changes: 4 additions & 1 deletion server/src/browser-controls.ts
Original file line number Diff line number Diff line change
Expand Up @@ -324,7 +324,10 @@ export class BrowserControls {
const cdp = await this.session(); this.x = event.x; this.y = event.y;
if (inputTraceEnabled) inputTrace('pointer.session', { session: cdp.id() });
const base = { x: event.x, y: event.y, modifiers: event.modifiers };
await cdp.send('Input.dispatchMouseEvent', { ...base, type: 'mouseMoved', buttons: this.held });
// Chromium needs the active button as well as the held mask
// to treat this as a drag (including text selection).
const button = this.held & 1 ? 'left' : this.held & 2 ? 'right' : this.held & 4 ? 'middle' : 'none';
await cdp.send('Input.dispatchMouseEvent', { ...base, type: 'mouseMoved', buttons: this.held, button });
if (event.kind === InputKind.WHEEL_INPUT) {
await cdp.send('Input.dispatchMouseEvent', { ...base, type: 'mouseWheel', buttons: this.held, deltaX: event.deltaX, deltaY: event.deltaY });
break;
Expand Down
Loading
Loading