kestrel

General browser utilities.

The extension hasn't been submitted to FireFox addons just yet, but you can track it from the AMO project.

Table of Contents

• Features
• FAQ
  • How Are Permissions Used?
  • How Do I Change Kestrel's Default Activation Command?
• Usage
  • Development
• Screenshots
• Roadmap
  • High Priority
  • Medium Priority
  • Low Priority
  • Planned Features
• Changelog
  • v1.0
• Docs
  • Kestrel Query Language
• Motivation
• License

Features

TODO: Update [x] represents APIs utilised to make the feature work.

• Disable all links, to prevent yourself from going down an internet rabbit hole [none]
• Hide media (images/video) [none]
• Open all links in the same tab [none]
• Refresh tabs [tabs]
• Scroll to x [none]
• Show media (images/video) [none]
• Toggle animations [none]
• Edit page [none] {in-progress}
• Mini-map [none] {in-progress}
• Image manipulation utilities on .png, .jpeg, and .jpg images [none] {in-progress}

FAQ

TODO: Finish section

How Are Permissions Used

The features section lists the permissions that each feature uses.

TODO: General overview of how permissions are used

TODO: instances of permission usage, e.g. https://github.com/hvlck/kestrel/search?q=browser.tabs.&unscoped_q=browser.tabs.

How Do I Change Kestrel's Default Activation Command

See this article from Mozilla.

Does Kestrel Collect Analytics or Data of Any Kind

No, not now and not ever.

I Don't Understand Something

Your best bet is the wiki.

Usage

There's not much to see right now. The main part is activated with Alt+Shift+A. Why Alt+Shift+A? All the keys can be hit with one hand.

Development

Requirements

• npm

1. Download Kestrel's source
2. Run yarn install
3. Run yarn run start
4. You're good to go!

Please use web-ext for linting.

Screenshots

TODO: Finish section

Roadmap

• Performance Testing with about:performance [meta]
• Things for AMO release (user docs, copy, etc.)
• Update version

General

High

• Typescript rewrite [meta] {in-progress}
• Security [bug] {in-progress}
• Anti-fingerprinting
• Tests [meta]
• AMO meta [meta]
• Project meta [meta]

Medium

• Rename KQL, functioning KQL
• Jump to X in page, similar to VSCode's
• Update features [meta]
• Finish image filtering utilities
  • Cropping
  • Rotation
  • Toolbar styling
• Refactoring [meta]
• Better onboarding/user-friendly docs [meta] {in-progress}
• Dropdown functions
  • Copy page <title> to clipboard

Low

• Better docs (diagrams, etc.) [meta]
• Logical ordering of variables and whatnot [meta]
• Homepage [meta] {in-progress}
• Better icons
  • Different icons for page-action and browser-action
• open link in new tab [context-menu]
• copy/paste format conversion [context-menu]
  • highlight, right click, copy text into selected format

Planned Features

• Add hide media into background task [background]
• Arrange tabs by title and url (maybe others, e.g. most text?) [browser-action]
• Minimal mode - basic stylesheet (customisable), table of contents, small amount of site metadata (similar to reader mode, but will open automatically in all sites) [check browser settings API to disable CSS on load?] [browser-action]
• Page size [page-action]
• Tab history traversing (show older history visually, e.g. URLs or title, commands to go back and forward easily) [browser-action]
• Tab splitting (open half in a new window, or split by title/url/other) [browser-action]
• Page rich editing (e.g. create elements, customize them)/downloading [browser-action] {in-progress}
• Tab workspaces (launch multiple preset tabs or windows, save multiple window configurations; these aren't containers, but used for opening sites related to something, such as GitHub and MDN for a workspace called "Programming") [browser-action]
• KQL [browser-action]
  • Things on the Searching · hvlck/kestrel Wiki · GitHub page
  • Workspace searching
  • Search hidden text content [browser action]
  • Search within a portion of the page (highlighted, viewport, etc.) [browser-action]
  • Search within viewport, section (current heading to next), and selected/highlighted text [browser-action]
• User-set aliases for commands [settings]
• Standard video controls (and ability to change playback speed) [background]
• Automatic unit conversion (time, metric-imperial, etc.) in website text [background]
• View individual workspace history (e.g. history for workspace, "Generic Research Project") [browser-action]

Abandoned/Ultra-Low Priority

• User-set activation/close command [feature] [abandoned - see ]

Changelog

v1.0

• Switched from injection-based approach to a browser-action-based approach
• Some internal updates

Docs

Internal docs are commented within the relevant file.

File structure:

readme.md - meta information
license - MIT
    /meta/ - meta
        /icon - icon generation files
            index.html - icon generation
    /src/ - extension
        manifest.json - WebExtension manifest
        /background - background scripts
            main.js - primary background script, controls injection logic
            scriptApi.js - userscript API
        /browser_action - extension browser action
            index.html - popup shell
            kestrel.js - logic for commands
            ui.css - styling for command palette
            ui.js - logic for command palette interaction
        /icons - kestrel icons
        /injections - files for commands that require injections
            /automatic - scripts injected into every page (if enabled) using UserScript API (see /background/scriptApi.js)
            /commands - individual command scripts
            /minimap - injection files for minimap command
            info.js - page scraping for the page action
        /libs - libraries and files used across multiple folders
            /themes - various themes
            commands.js - list of commands, aliases, and callbacks
            index.css - base stylesheet for all pages
            utils.js - utility
            webUtils - utilities for webextension APIs
        /page_action - extension page action
            index.css - styling
            index.html - shell
            index.js - display
        /pages
            /guide - kestrel guide
            /media - images
            /settings - extension settings page
                index.html - settings page
                settings.css - form styling, some stlying specific to /settings
                settings.js - object with settings, descriptions, etc.
                update.js - settings page logic
            changelog.js - generates a version number from the manifest (and a link to the changelog)

Messaging between extension parts

[[Raw Mermaid]]

graph LR
  subgraph Background To Injection
    cmd["User uses activation command"] --> ui["Show/hide user interface"]
  end
  subgraph Injection To Background
    c["Settings command"] --> s["Open settings"]
    ref["Hard/soft refresh command"] --> p["Uses Tabs API to refresh all tabs"]
    inj["Injection commands"] --> e["Script/stylesheet injection"]
  end
  subgraph Settings to Background
    stb["User changes background task"] --> us["Script (un)registered using UserScripts API"]
  end

Extension storage (all are customised in the options page)

automatic - automatic tasks, and whether they're enabled [Object]
{
    scriptName: Boolean // script name corresponds to a file in /injections/automatic
}

automaticsettings - settings for automatic tasks [Object]
{
    scriptName: {
        ...settings: value // not all scripts have settings
    }
}

browseraction - status of browser action (enabled/disabled) [Boolean]
browseraction: Boolean

commands - all commands, and whether they're enabled [Object]
{
    "name": {
        on: Boolean, // enabled/disabled
        callback: String, // internal callback, injection file name
        name: String // text displayed in command palette
    } // these correspond to taita commands
      // see https://github.com/hvlck/taita/#setup
}

theme - kestrel's theme (light, dark, or operating-system-default, which uses the (prefers-color-scheme) media query) [String]

Kestrel Query Language

Spec for KQL, which will be used for searching for information across tabs.

Motivation

Kestrel is simply a collection of utilities that I wished browsers included (and they may, I probably just didn't find them), wrapped in convenience (as opposed to several hundred small UserScripts). I've built it to present as little overhead on general performance as possible, but there's still much to be done.

License

MIT