hiro/tridactyl
1
0
Fork 0
mirror of https://github.com/vale981/tridactyl synced 2025-03-04 09:01:39 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

Reformat docs with prettier

Browse source
This commit is contained in:
Sumner Evans 2018-05-23 23:07:58 -06:00
parent d2ca0bea52
commit a132f0922e
No known key found for this signature in database
GPG key ID: 8904527AB50022FD
13 changed files with 280 additions and 318 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

114
doc/amo.md
View file

@ -1,86 +1,58 @@
## Control your browser with your keyboard *only*.
## Control your browser with your keyboard _only_.
Replace Firefox's control mechanism with one modelled on VIM. This is a "Firefox Quantum" replacement for VimFX, Vimperator and Pentadactyl.
Most common tasks you want your browser to perform are bound to a single key
press:
Replace Firefox's control mechanism with one modelled on VIM. This is a "Firefox Quantum" replacement for VimFX, Vimperator and Pentadactyl. Most common tasks you want your browser to perform are bound to a single key press:
- You want to open a new tab? Hit `t`.
- You want to follow that link? Hit `f` and type the displayed label. (Note: hint characters should be typed in lowercase.)
- You want to go to the bottom of the page? Hit `G`. Or the top? `gg`.
- You want to focus the text field on Wikipedia to search for another term? `gi`.
- Switch to the next tab? `gt`.
- Go back in time? `H`.
- Notice that this tab is rubbish and you want to close it? `d`.
- Regret that decision? `u` restores it.
- Want to write something in Vim? `Ctrl-i` in a text box opens it in Vim, if
you have `:native` working.
- Temporarily disable all that magic because you can't stand it? `Shift-Insert`.
- But how do you use your browser now? `Shift-Insert` again and we're back on.
* You want to open a new tab? Hit `t`.
* You want to follow that link? Hit `f` and type the displayed label. (Note: hint characters should be typed in lowercase.)
* You want to go to the bottom of the page? Hit `G`. Or the top? `gg`.
* You want to focus the text field on Wikipedia to search for another term? `gi`.
* Switch to the next tab? `gt`.
* Go back in time? `H`.
* Notice that this tab is rubbish and you want to close it? `d`.
* Regret that decision? `u` restores it.
* Want to write something in Vim? `Ctrl-i` in a text box opens it in Vim, if you have `:native` working.
* Temporarily disable all that magic because you can't stand it? `Shift-Insert`.
* But how do you use your browser now? `Shift-Insert` again and we're back on.
The list could go on a bit here, but I guess you'll get the point. If you feel
lost sometimes `:help` might help you a lot, and there's always `:tutor`.
The list could go on a bit here, but I guess you'll get the point. If you feel lost sometimes `:help` might help you a lot, and there's always `:tutor`.
**Highlighted features:**
- follow any link on the site with just 2-3 key presses.
- switch to any open tab by searching for its URL or title or entering its ID.
- easy customizable search settings
- bind any supported command or commands to the key (sequence) of your liking
- great default bindings (if you're used to Pentadactyl or Vimperator)
* follow any link on the site with just 2-3 key presses.
* switch to any open tab by searching for its URL or title or entering its ID.
* easy customizable search settings
* bind any supported command or commands to the key (sequence) of your liking
* great default bindings (if you're used to Pentadactyl or Vimperator)
This add-on is very usable, but is in an early stage of development. We intend
to implement the majority of Vimperator's features.
This add-on is very usable, but is in an early stage of development. We intend to implement the majority of Vimperator's features.
You can get beta builds from [our website][betas].
**Permissions:**
Since Tridactyl aims to provide all the features Vimperator and Pentadactyl
had, it requires quite a few permissions. Here we describe the specific
permissions and why we need them.
Since Tridactyl aims to provide all the features Vimperator and Pentadactyl had, it requires quite a few permissions. Here we describe the specific permissions and why we need them.
- Access your data for all websites:
* This is Mozilla's way of saying that Tridactyl can read the content of web
pages. This is necessary in order to e.g. find the links you can follow
with the `:hint` command (bound to `f` by default).
- Exchange messages with programs other than Firefox
* This permission is required for Tridactyl to interact with your
operating system (opening your editor to edit text areas, sending links to
your video player, reading a configuration file from your disk...). This
is possible thanks to an external executable we provide. If you feel this
gives Tridactyl too much power you can chose not to install the external
executable: Tridactyl will still work but won't be able to start external
programs.
- Read and modify bookmarks:
* Tridactyl's command line has a powerful autocompletion mechanism. In
order to be able to autocomplete your bookmarks, Tridactyl needs to read
them.
- Clear recent browsing history, cookies, and related data:
* Tridactyl implements the `:sanitise` command Vimperator and Pentadactyl
had. It works a bit like the "Clear All History" dialog you can access by
pressing `Ctrl+Shift+Del` on default Firefox.
- Get data from the clipboard:
* If your clipboard contains a URL, pressing `p` will make Tridactyl follow
this URL in the current tab.
- Input data to the clipboard:
* Tridactyl lets you copy various elements to the clipboard such as a page's
URL with `yy`, a link's URL with `;y` or the content of an HTML element
with `;p`.
- Download files and read and modify the browser's download history:
* By pressing `;s`, `;S`, `;a` and `;A` you can save documents and pictures
from a page to your download folder.
- Access browsing history:
* The URLs of websites you've visited previously can be suggested as
arguments for `:tabopen` and similar commands.
- Access recently closed tabs:
* If you've accidentally closed a tab or window, Tridactyl will let you open
it again with the `:undo` command which is bound to `u` by default.
- Access browser tabs:
* Tridactyl provides a quick tab-switching menu/command with the `:buffer`
command (bound to `b`). This permission is also required to close, move,
and pin tabs, amongst other things.
- Access browser activity during navigation:
* This is needed for Tridactyl to be able to go back to normal mode every
time you open a new page. In the future we may use it for autocommands.
* Access your data for all websites:
* This is Mozilla's way of saying that Tridactyl can read the content of web pages. This is necessary in order to e.g. find the links you can follow with the `:hint` command (bound to `f` by default).
* Exchange messages with programs other than Firefox
* This permission is required for Tridactyl to interact with your operating system (opening your editor to edit text areas, sending links to your video player, reading a configuration file from your disk...). This is possible thanks to an external executable we provide. If you feel this gives Tridactyl too much power you can chose not to install the external executable: Tridactyl will still work but won't be able to start external programs.
* Read and modify bookmarks:
* Tridactyl's command line has a powerful autocompletion mechanism. In order to be able to autocomplete your bookmarks, Tridactyl needs to read them.
* Clear recent browsing history, cookies, and related data:
* Tridactyl implements the `:sanitise` command Vimperator and Pentadactyl had. It works a bit like the "Clear All History" dialog you can access by pressing `Ctrl+Shift+Del` on default Firefox.
* Get data from the clipboard:
* If your clipboard contains a URL, pressing `p` will make Tridactyl follow this URL in the current tab.
* Input data to the clipboard:
* Tridactyl lets you copy various elements to the clipboard such as a page's URL with `yy`, a link's URL with `;y` or the content of an HTML element with `;p`.
* Download files and read and modify the browser's download history:
* By pressing `;s`, `;S`, `;a` and `;A` you can save documents and pictures from a page to your download folder.
* Access browsing history:
* The URLs of websites you've visited previously can be suggested as arguments for `:tabopen` and similar commands.
* Access recently closed tabs:
* If you've accidentally closed a tab or window, Tridactyl will let you open it again with the `:undo` command which is bound to `u` by default.
* Access browser tabs:
* Tridactyl provides a quick tab-switching menu/command with the `:buffer` command (bound to `b`). This permission is also required to close, move, and pin tabs, amongst other things.
* Access browser activity during navigation:
* This is needed for Tridactyl to be able to go back to normal mode every time you open a new page. In the future we may use it for autocommands.
[betas]: https://tridactyl.cmcaine.co.uk/betas/?sort=time&order=desc

15
doc/architecture.md
View file

@ -4,15 +4,14 @@
A broad outline is thus:
1. A user presses a key, triggering a keyEvent
2. The parser picker chooses which parser to send it to based on the current mode
3. The mode parser adds the key to its internal state, and can call an `update()` function to update, e.g, the status line / autocompletion
4. Upon receiving a terminal character, the parser translates the series of keypresses into an `ex` string (e.g, ":scrollPage 1")
5. This `ex` string is sent to the `ex str` parser, and converted into an internal Tridactyl function, e.g. `commmands.scrollPage(1)`, or if not possible, we report an error to the user
6. These functions then interface with the WebExtensions API and will hide any message passing that needs to occur. If the function fails, it reports an error as in step 5.
1. A user presses a key, triggering a keyEvent
2. The parser picker chooses which parser to send it to based on the current mode
3. The mode parser adds the key to its internal state, and can call an `update()` function to update, e.g, the status line / autocompletion
4. Upon receiving a terminal character, the parser translates the series of keypresses into an `ex` string (e.g, ":scrollPage 1")
5. This `ex` string is sent to the `ex str` parser, and converted into an internal Tridactyl function, e.g. `commmands.scrollPage(1)`, or if not possible, we report an error to the user
6. These functions then interface with the WebExtensions API and will hide any message passing that needs to occur. If the function fails, it reports an error as in step 5.
browser -> keyEvents -> parser picker -> mode parser -> terminal character -> ex command -> "ex str" parser -> (function | error) -> browser
browser -> keyEvents -> parser picker -> mode parser -> terminal character -> ex command -> "ex str" parser -> (function | error) -> browser
The process for "BrowserEvents", which occur when the user or some other code manipulates the browser through some non-Tridactyl method is similar, but we skip the parser picker step for now.

102
doc/archive.md
View file

@ -2,15 +2,15 @@
Non-objectives for v1:
* insert mode (embedded (n)vim would be good for future)
* caret or visual mode - I'm not good enough at vim to find these easier than selecting with the mouse, and they require text motions, which I would prefer to delegate to vim.
* insert mode (embedded (n)vim would be good for future)
* caret or visual mode - I'm not good enough at vim to find these easier than selecting with the mouse, and they require text motions, which I would prefer to delegate to vim.
Prior art:
* pentadactyl/vimperator - dying with XUL
* cVim/vimium/saka-key
* vimfx - transitioning to WebExtensions, but no ex commands
* qutebrowser/jumanji - see [standalone.md](doc/standalone.md).
* pentadactyl/vimperator - dying with XUL
* cVim/vimium/saka-key
* vimfx - transitioning to WebExtensions, but no ex commands
* qutebrowser/jumanji - see [standalone.md](doc/standalone.md).
## WebExtensions
@ -22,12 +22,12 @@ cVim and vimium implement some kind of vim experience using webextensions. Neith
#### Common issues
1. can't operate on some URLs (chrome store, chrome://, view-source://)
2. can't escape location bar
3. can't hide chrome UI
4. can't suppress all chrome keybinds
5. can't override some browser shortcuts
6. bad js kills the UI (but the same bad js locks up the whole of firefox, so y'know...)
1. can't operate on some URLs (chrome store, chrome://, view-source://)
2. can't escape location bar
3. can't hide chrome UI
4. can't suppress all chrome keybinds
5. can't override some browser shortcuts
6. bad js kills the UI (but the same bad js locks up the whole of firefox, so y'know...)
In conclusion, a privileged keyboard webextension will help with #1,2,4,5; #3,#1 (for visual changes) and maybe #2 need a ui API. #1 might not be applicable to ff content scripts.
@ -39,15 +39,15 @@ Very lightweight, but what is there is actually really nice. Easily fixable issu
Missing:
* command mode
* jumplist
* :js
* lots more.
* command mode
* jumplist
* :js
* lots more.
Improvements over vimperator:
* regex search
* buffer switch between windows
* regex search
* buffer switch between windows
#### vrome
@ -57,12 +57,12 @@ Vim mode chromium plugin written at least partly in coffeescript. Source is not
Missing:
* map!
* sensible default maps
* UI style
* documentation for users or developers
* plugin/eval support
* jumplist, etc
* map!
* sensible default maps
* UI style
* documentation for users or developers
* plugin/eval support
* jumplist, etc
May be worth taking code from, could consider forking it, but would need to review code more carefully for quality issues.
@ -74,58 +74,58 @@ Written in uncommented javascript. But user experience is pretty good. Autocompl
Missing:
* decent documentation
* can't map some characters that vimium can
* jumplist
* decent documentation
* can't map some characters that vimium can
* jumplist
Improvements over vimperator:
* autocompletion is much faster
* allegedly lets you edit with vim
* autocompletion is much faster
* allegedly lets you edit with vim
## Architecture
*This is an early draft and may be entirely replaced.*
_This is an early draft and may be entirely replaced._
ex-commands as functions (typed and with helper functions in some other scope):
* open(url)
* scroll(x=+10)
* mark(<elem>)
* map(actions, keys)
* ...
* open(url)
* scroll(x=+10)
* mark(<elem>)
* map(actions, keys)
* ...
helper functions for actions:
* scroll-x, scroll-y
* jumplist.get/getrelative/store
* undo-tab-deletion
* scroll-x, scroll-y
* jumplist.get/getrelative/store
* undo-tab-deletion
Count and range:
* given as arguments?
* just repeat the call 'count' times?
* given as arguments?
* just repeat the call 'count' times?
for default actions, a mapping from key to helper function.
Generated parsers (command and normal mode):
* command mode pretty conventional. Include type checking.
* For auto-complete to work, need to be able to parse partial results sensibly.
* actions will be a slightly weirder grammar:
* More permissive
* Time sensitive
* command mode pretty conventional. Include type checking.
* For auto-complete to work, need to be able to parse partial results sensibly.
* actions will be a slightly weirder grammar:
* More permissive
* Time sensitive
* In vim, actions compose as you write them (d takes a motion as an argument, for example), I can't think of any examples of this in vimperator: actions sometimes take a count or argument, but that argument is never an action.
* In vim, actions compose as you write them (d takes a motion as an argument, for example), I can't think of any examples of this in vimperator: actions sometimes take a count or argument, but that argument is never an action.
* If actions did compose, we would have to give them types, as vim does for motions, and the parsing would be less trivial.
* If actions did compose, we would have to give them types, as vim does for motions, and the parsing would be less trivial.
Autocomplete functions for commands:
* Split from implementation of command.
* Could perhaps be automatic from command's parameter types?
* Split from implementation of command.
* Could perhaps be automatic from command's parameter types?
Some actions have their own interactive mini-mode:
* hints
* searching
* hints
* searching

69
doc/bug-message.md
View file

@ -2,7 +2,6 @@
See also [content-scripts-bug.md](content-scripts-bug.md).
Vimperator and pentadactyl are addons that replace most of the Firefox UX with a keyboard-focused interface inspired by Vim. They enjoy moderate popularity and are particularly highlighted as "interesting add-ons" for porting on the Mozilla wiki[0].
From now on I'll just say "Vimperator" instead of "Vimperator and pentadactyl" or similar.
@ -19,21 +18,21 @@ The main drawback of this approach is that the content scripts aren't injected i
Users of Vimperator-like addons cannot:
1. Use vimperator at all on some URLs (about:\*, addons.mozilla.org)
1. Show and control the command line
2. Use any keyboard shortcuts
3. Use any commands or shortcuts that need to access the page's DOM.
* Includes: history control, scrolling, searching, hint mode, etc.
2. Hide UI elements
* Vimperator aims to replace the entire UI, so the old Firefox UI is not used at all. This frees up valuable real estate on small screens, such as laptops.
3. Escape from browser UI elements (especially the location bar)
4. Suppress/shadow all browser keybinds
5. Configure vimperator from the kind of config files they expect from other unix programs (and especially vim)
* In particular users expect to have something like ~/.vimperatorrc for their config and to be able to install additional plugins to something like ~/.vimperator/plugins; something like ~/.config/vimperator/ would also be acceptable.
1. Use vimperator at all on some URLs (about:\*, addons.mozilla.org)
1. Show and control the command line
2. Use any keyboard shortcuts
3. Use any commands or shortcuts that need to access the page's DOM.
* Includes: history control, scrolling, searching, hint mode, etc.
2. Hide UI elements
* Vimperator aims to replace the entire UI, so the old Firefox UI is not used at all. This frees up valuable real estate on small screens, such as laptops.
3. Escape from browser UI elements (especially the location bar)
4. Suppress/shadow all browser keybinds
5. Configure vimperator from the kind of config files they expect from other unix programs (and especially vim)
* In particular users expect to have something like ~/.vimperatorrc for their config and to be able to install additional plugins to something like ~/.vimperator/plugins; something like ~/.config/vimperator/ would also be acceptable.
In Firefox there is a new, sixth problem:
6. Vimperator cannot open certain restricted URLs
6. Vimperator cannot open certain restricted URLs
The issues are in rough importance order, apart from 6, which should be higher.
@ -63,8 +62,8 @@ Leechblock is another addon that has a legitimate reason to access a restricted
My understanding is that Firefox developers do not want to permit content scripts to run on restricted pages because of the possibility of privilege escalation. This is normally bad for two reasons:
1. Security of the user
2. Stability of the browser: addons using exposed APIs they shouldn't will break more on updates, etc.
1. Security of the user
2. Stability of the browser: addons using exposed APIs they shouldn't will break more on updates, etc.
I don't think either of these issues matter for an addon like vimperator. Vimperator is expected and essentially required to be able to read every keystroke the user makes on every page, control network access, control ui (including display of URLs and https status), etc. Let's say running a content script in about:addons might let us privilege escalate to control the whole browser. The only new warning we need to give users is that this addon can potentially run arbitrary code as your user on the host system, which vimperator could do anyway in a slightly roundabout fashion by redirecting any executable or source code the user downloads to some malware.
@ -76,11 +75,11 @@ Regarding stability, the risk of exposing APIs that shouldn't be used only reall
If the Firefox developers are adamant that no addon be permitted to access the DOM of restricted pages, then we have to work around that limitation with new APIs. This is the best I can come up with, but it relies again on lydell's abandoned keyboard API:
1. The command line/statusline moves into a toolbar. Toolbar must be permitted to expand or overlay page content to show autocompletion and to talk to content and background scripts.
2. The proposed keyboard API allows vimperator to capture keypresses within restricted pages, so we can still call most vimperator functions, but any that need to access the DOM of the restricted page won't work.
3. The keyboardshortcuts API also proposed by the vimFx developer ("simple functions to trigger standard Firefox keyboard shortcuts programmatically") will allow some of the simple features we otherwise need DOM access for to work, examples: scrolling, history navigation, stop loading, etc. More advanced features such as hint mode, marks, insert, visual and caret mode and searching will not work.
1. The command line/statusline moves into a toolbar. Toolbar must be permitted to expand or overlay page content to show autocompletion and to talk to content and background scripts.
2. The proposed keyboard API allows vimperator to capture keypresses within restricted pages, so we can still call most vimperator functions, but any that need to access the DOM of the restricted page won't work.
3. The keyboardshortcuts API also proposed by the vimFx developer ("simple functions to trigger standard Firefox keyboard shortcuts programmatically") will allow some of the simple features we otherwise need DOM access for to work, examples: scrolling, history navigation, stop loading, etc. More advanced features such as hint mode, marks, insert, visual and caret mode and searching will not work.
These three fix the main problem in the chrome addons of getting stuck and having to use a different UI on some pages is mostly removed (remember, the whole point of vimperator is to replace the default UI/UX). It is important to highlight, however, that users losing hint mode on about: pages is a real UX hit because hint mode is the main way that users select and follow links in vimperator.
These three fix the main problem in the chrome addons of getting stuck and having to use a different UI on some pages is mostly removed (remember, the whole point of vimperator is to replace the default UI/UX). It is important to highlight, however, that users losing hint mode on about: pages is a real UX hit because hint mode is the main way that users select and follow links in vimperator.
I can't think of an easy way of allowing hinting without DOM access. A built-in hinting API is probably the only sensible way; but seems like a high maintenance burden on Firefox (unless you want to enable hinting mode in normal Firefox, which would be cool). A less sensible proposal would be to tell us where and what the anchor tags are and let us overlay the page with just the labels in a new, mostly transparent window.
@ -88,22 +87,22 @@ I can't think of an easy way of allowing hinting without DOM access. A built-in
## List of new required WebExtension APIs
* keyboard incl. function to escape browser location bar
* https://bugzilla.mozilla.org/show_bug.cgi?id=1215061
* theming or some other API must support completely hiding most UI elements.
* permission to programmatically navigate to restricted URLs
* https://bugzilla.mozilla.org/show_bug.cgi?id=1261289
* https://bugzilla.mozilla.org/show_bug.cgi?id=1298215
* filesystem
* https://bugzilla.mozilla.org/show_bug.cgi?id=1246236
* either:
* a permission allowing content scripts to run on restricted pages.
* or...
* keyboardshortcuts
* toolbar/custom html+css+js ui element with ability to expand or (preferably) overlay the tab window.
* https://bugzilla.mozilla.org/show_bug.cgi?id=1215064
* And for more functionality:
* hinting
* keyboard incl. function to escape browser location bar
* https://bugzilla.mozilla.org/show_bug.cgi?id=1215061
* theming or some other API must support completely hiding most UI elements.
* permission to programmatically navigate to restricted URLs
* https://bugzilla.mozilla.org/show_bug.cgi?id=1261289
* https://bugzilla.mozilla.org/show_bug.cgi?id=1298215
* filesystem
* https://bugzilla.mozilla.org/show_bug.cgi?id=1246236
* either:
* a permission allowing content scripts to run on restricted pages.
* or...
* keyboardshortcuts
* toolbar/custom html+css+js ui element with ability to expand or (preferably) overlay the tab window.
* https://bugzilla.mozilla.org/show_bug.cgi?id=1215064
* And for more functionality:
* hinting
## What's this hint mode thing, anyway?

28
doc/content-scripts-bug.md
View file

@ -4,14 +4,14 @@ Disallowing content scripts from running on certain pages is a big change from p
## Risks as we understand them
1. Privilege escalation from WebExtension to full control of the browser allows:
1. Malicious addons to do more to the host system and to Firefox internals
2. Malware to target privileged addons
3. Addon developers to reduce the stability of Firefox by deliberately or accidentally but not maliciously escaping the sandbox
1. Privilege escalation from WebExtension to full control of the browser allows:
1. Malicious addons to do more to the host system and to Firefox internals
2. Malware to target privileged addons
3. Addon developers to reduce the stability of Firefox by deliberately or accidentally but not maliciously escaping the sandbox
## Additional risks as articulated on #WebExtensions
2. The necessary severe warnings to the user are problematic for usability, security and other reasons.
2. The necessary severe warnings to the user are problematic for usability, security and other reasons.
Is this a fair characterisation of the risks?
@ -21,18 +21,18 @@ From a security perspective, we believe the user suffers very little from the pr
Without restricted pages:
1. Inspect the value of all form fields
1. Steal all user credentials, typed or automatically entered.
2. Rewrite download links
1. Fool users into installing malware.
1. Inspect the value of all form fields
1. Steal all user credentials, typed or automatically entered.
2. Rewrite download links
1. Fool users into installing malware.
With privilege escalation, all the above plus:
3. Control addon installation
1. Install more addons as it pleases
2. Prevent uninstallation of addons
4. Access Firefox sync data and logins/password database
5. Run arbitrary code as the Firefox process
3. Control addon installation
1. Install more addons as it pleases
2. Prevent uninstallation of addons
4. Access Firefox sync data and logins/password database
5. Run arbitrary code as the Firefox process
Now, 3, 4 and 5 are bad, but they're only slightly worse for the user than 1 and 2.

63
doc/escalating-privilege.md
View file

@ -2,37 +2,40 @@
Useful workarounds and methods to get the power we want in the brave new world of webextensions.
- Function in newtab
- [chrome_url_overrides](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/chrome_url_overrides)
- Function in home page
- [chrome_settings_overrides](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/chrome_settings_overrides)
- (Downside for both is that we need to reimplement a useful home and newtab page)
* Function in newtab
* [chrome_url_overrides](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/chrome_url_overrides)
* Function in home page
* [chrome_settings_overrides](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/chrome_settings_overrides)
* (Downside for both is that we need to reimplement a useful home and newtab page)
- Shell and write access to filesystem
- [Native_messaging](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Native_messaging)
- Hiding firefox chrome
- API proposal for hiding tabstrip (but not nav bar): [Bug 1332447](https://api-dev.bugzilla.mozilla.org/show_bug.cgi?id=1332447)
- :Gijs discusses why nav bar can't be hidden, but I still don't get why whatever happens in fullscreen can't just also happen in windowed mode.
- Hiding with userChrome.css
- http://kb.mozillazine.org/Chrome_element_names_and_IDs
- e.g. "#tabbrowser-tabs { visibility: collapse !important; }"
- requires restart, probably
* Shell and write access to filesystem
* [Native_messaging](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Native_messaging)
* Hiding firefox chrome
- Commandline thru toolbar API
- [Bug 1215064](https://bugzilla.mozilla.org/show_bug.cgi?id=1215064)
- As currently envisioned, size is fixed, I think
- Commandline thru HTML injection into webcontent
- Dangerous, see [Bug 1287590](https://bugzilla.mozilla.org/show_bug.cgi?id=1287590)
- Shadow DOM would probably be simpler than iframe, but not implemented yet [Bug 1205323](https://bugzilla.mozilla.org/show_bug.cgi?id=1205323)
- Commandline thru search suggestions on the omnibar (this is a bit mad)
- [chrome_settings_overrides](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/chrome_settings_overrides)
* API proposal for hiding tabstrip (but not nav bar): [Bug 1332447](https://api-dev.bugzilla.mozilla.org/show_bug.cgi?id=1332447)
* :Gijs discusses why nav bar can't be hidden, but I still don't get why whatever happens in fullscreen can't just also happen in windowed mode.
* Hiding with userChrome.css
* http://kb.mozillazine.org/Chrome_element_names_and_IDs
* e.g. "#tabbrowser-tabs { visibility: collapse !important; }"
* requires restart, probably
- [Find API](https://bug1332144.bmoattachments.org/attachment.cgi?id=8905651)
- [Bug 1332144](https://bugzilla.mozilla.org/show_bug.cgi?id=1332144)
- [Demo](https://github.com/Allasso/Find_API_demo_WE_advanced)
- How to replicate find links? Do we care?
- Can this be used to exfiltrate info about about pages?
* Commandline thru toolbar API
* [Bug 1215064](https://bugzilla.mozilla.org/show_bug.cgi?id=1215064)
* As currently envisioned, size is fixed, I think
* Commandline thru HTML injection into webcontent
* Dangerous, see [Bug 1287590](https://bugzilla.mozilla.org/show_bug.cgi?id=1287590)
* Shadow DOM would probably be simpler than iframe, but not implemented yet [Bug 1205323](https://bugzilla.mozilla.org/show_bug.cgi?id=1205323)
* Commandline thru search suggestions on the omnibar (this is a bit mad)
- Can't navigate to restricted URLs
- [about:](https://bugzilla.mozilla.org/show_bug.cgi?id=1371793)
- [file:](https://bugzilla.mozilla.org/show_bug.cgi?id=1266960)
* [chrome_settings_overrides](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/chrome_settings_overrides)
* [Find API](https://bug1332144.bmoattachments.org/attachment.cgi?id=8905651)
* [Bug 1332144](https://bugzilla.mozilla.org/show_bug.cgi?id=1332144)
* [Demo](https://github.com/Allasso/Find_API_demo_WE_advanced)
* How to replicate find links? Do we care?
* Can this be used to exfiltrate info about about pages?
* Can't navigate to restricted URLs
* [about:](https://bugzilla.mozilla.org/show_bug.cgi?id=1371793)
* [file:](https://bugzilla.mozilla.org/show_bug.cgi?id=1266960)

64
doc/hinting.md
View file

@ -1,21 +1,21 @@
## Components
- Iterable of visible links on page
* Iterable of visible links on page
- Algorithm for choosing hint characters for each link
* Algorithm for choosing hint characters for each link
- Mode for controller and excmd to refine and select hints:
- I imagine `:hint` to start
- `:hint j` to refine to only hints starting with j
- `:hint jk` to refine to hints starting with jk
- To make maps easier we can have `:hintaddchar j` and have the state of the current hintstr stored content-side.
* Mode for controller and excmd to refine and select hints:
* I imagine `:hint` to start
* `:hint j` to refine to only hints starting with j
* `:hint jk` to refine to hints starting with jk
* To make maps easier we can have `:hintaddchar j` and have the state of the current hintstr stored content-side.
## Improvements
Hinting modes should be flexible on both
1. What is hinted (links, anchorpoints, frames, input elements, etc)
2. What is done with the selected link (follow, yank, focus)
1. What is hinted (links, anchorpoints, frames, input elements, etc)
2. What is done with the selected link (follow, yank, focus)
## Vimperator hint modes:
@ -23,35 +23,35 @@ Hinting modes should be flexible on both
```
string(default: //input[not(@type='hidden' or @disabled)] | //xhtml:input[not(@type='hidden')] | //a | //xhtml:a | //area | //xhtml:area | //iframe | //xhtml:iframe | //textarea | //xhtml:textarea | //button | //xhtml:button | //select | //xhtml:select | //\*[@onclick or @onmouseover or @onmousedown or @onmouseup or @oncommand or @role='link'or @role='button' or @role='checkbox' or @role='combobox' or @role='listbox' or @role='listitem' or @role='menuitem' or @role='menuitemcheckbox' or @role='menuitemradio' or @role='option' or @role='radio' or @role='scrollbar' or @role='slider' or @role='spinbutton' or @role='tab' or @role='textbox' or @role='treeitem' or @tabindex])
XPath string of hintable elements activated by f and F
```
Extended hint modes:
```
; Focus hint
? Show information for hint
s Save link
S Save object
a Save link with prompt
A Save object with prompt
f Focus frame
o Follow hint
t Follow hint in a new tab
b Follow hint in a background tab
w Follow hint in a new window
F Open multiple hints in tabs
O Generate an ':open URL' using hint
T Generate a ':tabopen URL' using hint
W Generate a ':winopen URL' using hint
v View hint source
V View hint source in external editor
y Yank hint location
Y Yank hint description
; Focus hint
? Show information for hint
s Save link
S Save object
a Save link with prompt
A Save object with prompt
f Focus frame
o Follow hint
t Follow hint in a new tab
b Follow hint in a background tab
w Follow hint in a new window
F Open multiple hints in tabs
O Generate an ':open URL' using hint
T Generate a ':tabopen URL' using hint
W Generate a ':winopen URL' using hint
v View hint source
V View hint source in external editor
y Yank hint location
Y Yank hint description
# Yank hint anchor URL
c Open context menu
i Show media object
I Show media object in a new tab
c Open context menu
i Show media object
I Show media object in a new tab
x Show hint's title or alt text
```

53
doc/ideas.md
View file

@ -2,73 +2,60 @@
Vimperator is going to die once Firefox deprecates XUL and switches webextensions. Needs fixing, or nobody will be able to use the internet any more.
Valiant efforts have been begun to sort out some parts of Firefox's WebExtension implementation:
https://bugzilla.mozilla.org/show_bug.cgi?id=1215061
Valiant efforts have been begun to sort out some parts of Firefox's WebExtension implementation: https://bugzilla.mozilla.org/show_bug.cgi?id=1215061
This only deals with the keyboard binding aspect. We need to think about the GUI / hinting etc: we need to make sure everything we want to have in Vimperator is possible using WebExtensions.
Chrome et al. already use WebExtensions, and there are a few vim-like extensions for it, such as cVim/Vimium. It would make sense to look at how these extensions work and see what is not currently possible in Firefox. An obvious part of what they cannot do is change the GUI of the browser. Vimperator allows you to hide parts of the browser when they are not needed.
It would also be sensible to have a list of ideal things that can't currently be done in Vimperator, e.g. embedding Vim client, that we would like. (look at Petrosaur)
There is currently a magic console in Firefox that we could perhaps hijack, which is built on GCLI:
https://developer.mozilla.org/en/docs/Tools/GCLI
https://github.com/joewalker/gcli/blob/master/docs/index.md -- even says that it could be used as part of a browser extension
There is currently a magic console in Firefox that we could perhaps hijack, which is built on GCLI: https://developer.mozilla.org/en/docs/Tools/GCLI https://github.com/joewalker/gcli/blob/master/docs/index.md -- even says that it could be used as part of a browser extension
# Avoiding JavaScript:
CoffeeScript; EMScripten, ELM, Node.js (interpretereter?)
(broccoli)
What is NPM? Browserify is dependency management
CoffeeScript; EMScripten, ELM, Node.js (interpretereter?) (broccoli) What is NPM? Browserify is dependency management
# Useful libraries
PEG - parses stuff (e.g. command input)
# cVim
Code not well documented, could glean useful stuff from just stripping out what Chrome API is used
## Useful links:
https://www.codementor.io/gmuresan/building-a-chrome-extension-reactjs-broccoli-sass-du1081zv0
# Useful links
https://developer.chrome.com/extensions/commands
https://github.com/lydell/webextension-keyboard
https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts
https://github.com/shinglyu/QuantumVim - Vimium style stuff in WebExtensions
https://github.com/mishoo/UglifyJS2 - Minify JS: check that compiling to Firefox addon doesn't already do this
https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API
http://arcturo.github.io/library/coffeescript/ - Coffee Script textbook
https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Getting_started_with_web-ext - web-ext will automatically reload a changed extension
https://developer.chrome.com/extensions/commands https://github.com/lydell/webextension-keyboard https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts https://github.com/shinglyu/QuantumVim - Vimium style stuff in WebExtensions https://github.com/mishoo/UglifyJS2 - Minify JS: check that compiling to Firefox addon doesn't already do this https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API http://arcturo.github.io/library/coffeescript/ - Coffee Script textbook https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Getting_started_with_web-ext - web-ext will automatically reload a changed extension
# Names
Tridactyl (like Pentadactyl, but worse, last cuturally relevant in 2005 like Salad Fingers)
# Features we really really want
- Hiding misc UI (tabs, menu, urlbar, etc.)
- Interacting with other addons (simulating presses on buttons?)
- ]][[ to inc/dec url
- command line for opening tabs/completion/interacting with addons/changing settings
- "buffer" tab searching / tab groups?
- searching for tabs between windows?
* Hiding misc UI (tabs, menu, urlbar, etc.)
* Interacting with other addons (simulating presses on buttons?)
* ]][[ to inc/dec url
* command line for opening tabs/completion/interacting with addons/changing settings
* "buffer" tab searching / tab groups?
* searching for tabs between windows?
# Features we need less?
autocmds?
macros?
autocmds? macros?
# Vimium notes
Uses descriptors a lot - what even are they?
Loading into firefox doesn't give any errors / doesn't seem to expose any functions?
Uses descriptors a lot - what even are they? Loading into firefox doesn't give any errors / doesn't seem to expose any functions?
# Other stuff
Would be nice to have self-writing documentation, for autocmd use etc?
Could use .litcoffee for markdown comments in code.
Would be nice to have self-writing documentation, for autocmd use etc? Could use .litcoffee for markdown comments in code.
History seems to be window.history.go(), presumably in a content script?

4
doc/mvp.md
View file

@ -25,12 +25,12 @@ Commands:
buffer {N}
## modes
normal
insert
find {phrase} {direction=+/-1}
hints {open|tabopen|winopen|yank}
## search-likes
{page, google, amazon} {phrase}

10
doc/parser.md
View file

@ -3,11 +3,11 @@
We need to parse series of keypresses into `ex` commands, and then parse those commands into internal functions. We also need autocompletion of commands (maybe also in normal mode, qutebrowser style, to aid their discoverability), and the parser needs to change in real-time such that binds can be remapped.
We are considering:
- writing our own parser
- Nearley: https://github.com/Hardmath123/nearley
- Upsides: uses Earley, can use CoffeeScript
- PEG.js
- Downsides: uses PEG
* writing our own parser
* Nearley: https://github.com/Hardmath123/nearley
* Upsides: uses Earley, can use CoffeeScript
* PEG.js
* Downsides: uses PEG
Currently, we are erring on the side of writing our own parser, as neither of the other options allow for changing the parser sensibly, and do not seem to support partial matches. Generally, neither seem to be written with the expectation of interactive uses.

47
doc/standalone.md
View file

@ -2,21 +2,21 @@
Some small browsers exist that use webkit/webengine for the heavy lifting. Two notable examples even have vim-like interfaces: qutebrowser and jumanji.
Extending them *might* be easy, depending on the quality of the existing code base. We also need to evaluate these projects for maintainability: they're obviously going to have much less development power.
Extending them _might_ be easy, depending on the quality of the existing code base. We also need to evaluate these projects for maintainability: they're obviously going to have much less development power.
If it's comparable to this project done in webextensions, then we might want to just build our own/fork/contribute.
But what do we lose? What do the non-gecko bits of firefox do? What's left in the chrome repo if you remove webengine? I don't really know.
But what do we lose? What do the non-gecko bits of firefox do? What's left in the chrome repo if you remove webengine? I don't really know.
* Kerning/font presentation code? (text in qutebrowser looks bad on Windows, don't know why)
* Cross-platform OS shit
* Firefox sync is neat and would be missed.
* safebrowsing?
* how much security stuff in engine/vs browser?
* webm, webgl and similar? Presumably handled either by the engine or externally, but maybe picking and maintaining link to external thing is expensive.
* flash handling?
* What UI stuff are we not replacing?
* developer tools (neat, but no reason for us to re-implement).
* Kerning/font presentation code? (text in qutebrowser looks bad on Windows, don't know why)
* Cross-platform OS shit
* Firefox sync is neat and would be missed.
* safebrowsing?
* how much security stuff in engine/vs browser?
* webm, webgl and similar? Presumably handled either by the engine or externally, but maybe picking and maintaining link to external thing is expensive.
* flash handling?
* What UI stuff are we not replacing?
* developer tools (neat, but no reason for us to re-implement).
We also lose access to the existing addon/extension repos. Maybe if we implemented webextension support in our own browser we'd get them back? Don't know how difficult that is.
@ -26,19 +26,18 @@ What addons do I use and would I miss them?
Should be part of the browser anyway:
* stylish --> :style, or maybe .vimperator/styles/ (with magic comments?)
* greasemonkey --> builtin/extensions/autocmds
* site blocker --> /etc/hosts
* stylish --> :style, or maybe .vimperator/styles/ (with magic comments?)
* greasemonkey --> builtin/extensions/autocmds
* site blocker --> /etc/hosts
Maybe not:
* element hiding rules (ublock) not supported
* tree tabs --> better :buffer?
* lazarus form recovery is brilliant...
* noscript is shit anyway
* hide fedora is neat, but maybe just an element hiding list? Maybe it does have to parse differently.
* example of neat addon that a smaller browser wouldn't have available, anyway.
* ref control is neat, but the UI is pants. Would be easy to build an ex-mode interface.
* pwgen is trivial
* https everywhere --> builtin?
* element hiding rules (ublock) not supported
* tree tabs --> better :buffer?
* lazarus form recovery is brilliant...
* noscript is shit anyway
* hide fedora is neat, but maybe just an element hiding list? Maybe it does have to parse differently.
* example of neat addon that a smaller browser wouldn't have available, anyway.
* ref control is neat, but the UI is pants. Would be easy to build an ex-mode interface.
* pwgen is trivial
* https everywhere --> builtin?

11
doc/wishlist.md
View file

@ -1,8 +1,9 @@
# Stuff we'd like but maybe we might not be able to do
- Better link hinting
- One hint per identical link? (e.g. BBC News homepage works badly without this)
- Some links need simulated mouse click (e.g. JS)
* Better link hinting
- Better normal mode motions
- e.g, "next heading"
* One hint per identical link? (e.g. BBC News homepage works badly without this)
* Some links need simulated mouse click (e.g. JS)
* Better normal mode motions
* e.g, "next heading"

18
doc/workflow.md
View file

@ -1,18 +1,20 @@
# Playing with Firefox background scripts
1. about:debugging - load temporary addon
2. click "debug"
3. click "console"
4. disable most things apart from logging
5. have fun
1. about:debugging - load temporary addon
2. click "debug"
3. click "console"
4. disable most things apart from logging
5. have fun
# Playing with content scripts
1. about:debugging
2. dunno the rest
1. about:debugging
2. dunno the rest
# Experimental WebExtension API addons
1. complicated, but Colin knows a bit.
1. complicated, but Colin knows a bit.
# Compiling CoffeeScript
coffee -c script.coffee