uweb/misc/ebrowser/README.md

Ebrowser: keyboard-friendly minimal suckless web browser

Ebrowser is designed with the philosophy of Android uweb browser (gitlab).

• lightweight (less than 20k bytes) without bundled electron.
• much less memory footprint than edge/chrome browser and highly performant.
• keyboard friendly with vim-style keymaps and command line support in address bar.
• global redirection to bypass censorship.
• user CSS/JS at will. Ex. pressing "md" in no-focus mode to preview markdown file.
• global CSS/JS for all sites at will.
• CSS/JS for domains, similar to uweb, but use sitejs/[domain].js or sitecss/[domain].css, not [domain root].js/css.
• customizable.

Note: Usually electron apps are heavyweight as they use browsers for simple things. Ebrowser uses core chromium effectively and very lightweight. Recommend to install electron separately.

Installing (for Windows, MacOS and Linux)

Install with prebuilt binaries

You can find prebuilt binaries here.

Install with nodejs

npm install electron
npm install ebrowser

Run ebrowser

electron ~/node_modules/ebrowser

Later on, you can run "npm install electron" to update electron/chromium or "npm install ebrowser" to update ebrowser independently.

Update app quickly without updating chromium

Pressing "Alt" to show the menu bar and choose "Check for updates" under "Help". OR

Type ":update" in the address bar and press "enter" key to update.

Mirror urls could be used like ":update https://uwebzh.netlify.app/misc/ebrowser". All the mirrors listed on uweb browser could be used. The update url needs to be changed accordingly to be the folder "misc/ebrowser" under the mirror site root url.

Key shortcuts

• Alt: show menu
• ALT+<-: go backward
• ALT+->: go forward
• CTRL+C: stop loading
• CTRL+G: address bar to show page url
• CTRL+L: focus to address bar
• CTRL+T: new Tab
• CTRL+SHIFT+T: restore closed Tab
• CTRL+TAB: switch to next tab
• CTRL+SHIFT+TAB: switch to previous tab
• CTRL+W: close Tab
• CTRL+SHIFT+R: enable global redirection ("gredirect.json")
• CTRL+R: disable global redirection
• ESC: remove focus. similar to vi normal mode.
• F1: Help
• F5: page refresh/reload
• F12: devtools

Address bar commands

Like any popular browser, the very first word in address bar if defined in "search.json" identifies a search engine. Moreover, the address bar serves as command line interface:

• "/" for find-in-page
• ":" for address bar commands
  • ac [bookmark/history path w/o ext] : load ".rec" file for autocomplete.
  • b [bookmarkfilename w/o ext] : bookmark current page in file.
  • bjs : Browser-level JavaScript execution.
  • bml [filename w/o extension]: load/execute the javascript file.
  • cert : allow invalid certificates w/o arguments, otherwise restore to default.
  • clear : the arguments could be
    • cache : clear cache
    • dns : clear dns cache
    • storage: clear site storage data.
    • {options}
  • ext [extension path]: load unpacked Chrome extension.
  • gr [gredirect index]: global redirection with corresponding index. Use the first global redirection url if no argument. Disable global redirection with any index out of the range.
  • js [js code] : execute JS code at OS level. Note: "javascript:..." is special url and thus works in the current web page, while ":js ..." commands can do any OS operations.
  • nc/uc : No Cookie forwarding/Use Cookie forwarding with global redirection.
  • nr/ur for No/Use "redirect.json" for domain redirection.
  • np : no proxy.
  • up [proxyName] : use proxy. privous proxy or the first proxy in proxy.json w/o [proxyName]. ":up" command also disables global and domain redirections, which are not restored by ":np".
  • ua [useragentName] : set user agent for future tabs. default user agent w/o arguments.
  • update [filename] : update the app w/o argument, otherwise retrive the [filename] from remote. The filename could be any file on mirror sites (this repository is part of it).
  • pdf [filename w/o extension] {options} : print to PDF file. All arguments are optional; empty option "{}" to capture long screenshot as vector graphics.
• "!" address bar commands
  "!xx ..." evaluates "xx.js" with the whole text as arguments[0].
• i: internal urls, which will be consistent with uweb.
  • "i:0/js/xxx.js:[url]" loads the "[url]" with bookmarklet "js/xxx.js".

Commands in no-focus mode (this mode is similar to vi Normal mode)

Pressing "ESC" to enter no-focus mode if not sure.

• ":" for address bar commands
• "/" for find-in-page with address bar
• "!" for "!" address bar commands

The other commands are defined in "mapkeys.json", which will map keys to address bar commands.

Configuration files

• "config": lines of address bar commands.
• "search.json": search engines as shortcut-queryUrl pairs, where "%s" would be replaced by search query.
• "default.autoc": predefined strings for address bar auto completion.
• "gredirect.json": global redirection urls as array of urls
• "redirect.json": domain-replacementDomain pairs, default to be applied.
• "mapkeys.json": keys-addressbarCommands pairs. The addressbar commands are multiple lines of address bar command separated by "\n".
• "proxy.json": name-ProxyConfig pairs
• "uas.json" : name-useragent pairs.
• Customized menus: json files as array of strings with menuitem name and address bar commands alternately.
  • "menu.json": array of strings for user-defined menus. The array has submenu name and address bar commands alternately. The odd-indexed strings are address bar commands with "%u" as the downloaded url.
  • "select.json": to define menus for text selections. The odd-indexed strings are address bar commands with "%s" as the text selection.
  • "download.json" : array of strings to define context menu and buttons for downloading dialog. The even-indexed strings are texts to show on the button. The odd-indexed strings are address bar commands with "%u" as the downloaded url.

Javascript at three levels

• Web page: url like "javascript:" or bookmarklet command ":bml" runs in web page.
• Browser (or renderer process) :
  • ":bjs" to execute the following js code at browser level.
  • "!xx" evaluates "xx.js", which could manipulate address bar etc.
• OS level (or main process) : ":js" to execute the following js code with all OS APIs available.

examples for ":js"/":bjs" commands

:js bJS=true //allow external Javascript files for web pages
:js bJS=false //disallow external Javascript files for web pages
:bjs bHistory=true //to record url history
:bjs bQueryHistory=true //to record query/command history

New usages

• Vector designing with web tech to replace Adobe Illustrator/Inkscape.

  • Design with web tech.

  • Printing to pdf with customized paper size.

  • Magnify the pdf paper size to the required size.

  OR

  • Adjust window width and use addressbar command line ":Pdf {}" to export vector graphics.
  • Use imageMagick to convert to any other vector graphics format.

License

You can copy or modify the code/program under the terms of the GPL3.0 or later versions.