Also avoid using `@p` to refer to parameter names in function
documentation, since this isn't valid JSDoc syntax. Use markdown
backticks instead, following conventions in Angular's docs.

The sidebar supports multiple client pages connecting to it
and displaying annotations for all of the connected clients.
As far as I am aware, this functionality is not actually used
anywhere, but this commit fixes an issue where annotations
would be loaded multiple times for some clients if multiple
clients connected.

This was duplicated with varying levels of explanation in several
places.

Although the function is trivial, having it in its own module is useful
for documentation on why it should be used by default.

When the selection is initialized as a result of following
a direct link to an annotation, focus and scroll to the annotation
after it has been successfully fetched from the service.

When the sidebar loads as a result of an '#annotations'
fragment, we do not know which group that annotation is in.

Handle this by first fetching annotations in all groups,
then finding the group containing the selected annotation(s)
and finally filtering the results by that group.

An alternative approach would be to first fetch the
selected annotations in order to determine the group and
then fetching annotations in that group.

This approach however avoids an extra round-trip to the server
in the common case where the total number of annotations across
all groups is less than the default chunk size (200).

widget-controller.js triggers a reload of annotations whenever a
GROUP_FOCUSED event is emitted. Avoid reloading annotations
unnecessarily if group.focus() is called with the currently focused
group.

Extract the logic for paging through search results from
the API into a separate module.

(1/3) Open sidebar and set selection when '#annotations' URL fragment is present

When the sidebar loads in a page with a '#annotations'
URL fragment, the 'annotations' setting will be
passed through to the client as `settings.annotations`.

Use this to initialize the selection so that
the annotation specified by '#annotations:<ID>' is
selected when the client loads.

If the host page's URL contains a '#annotations:' fragment,
open the sidebar automatically when the client loads.

 * Move code for reading Hypothesis configuration from
   the environment into config.js and add tests

 * Read the '#annotations' fragment from the URL and
   pass it to app.html along with any other options
   as query string parameters.

Postgres read support for storage.expand_uri

Enable Chrome extension to detect when H is already present on page

This reworks the way that Hypothesis detects whether it is
already present on the page in embed.js, in a way that
enables it to report back the app.html URL for the
existing instance to the Chrome extension.

The Chrome extension can then update its state for that
tab to reflect the fact that it is not injected.

In this PR, that is done by simply setting the tab state
to inactive. We could in future add an indicator that
the user tried to activate H but that another instance
is already active, or have the extension override the
instance of H on the page.

 * Detect the <link> element added to the page by embed.js,
   rather than window.annotator. This enables detection to work
   when embed.js is run in an isolated world that shares the DOM
   but not the JS environment, as is the case for content scripts
   in Chrome and Firefox.

 * Change unloading to operate by firing an event at the <link>
   element. This enables a content script to trigger unloading
   of H from an isolated JS environment.

 * Change injection of embed.js in the Chrome extension to
   execute embed.js as a content script, rather than by
   adding it as a `<script>` tag. This enables embed.js to
   access extension APIs and also report its result back
   to the extension via the return value of the script.

   A side benefit is that it also avoids a bug in Firefox
   current WebExtensions implementation where `<script>` tags
   added to the page by a content script are not executed.

Simplify API authentication in the client and fix #3083, #2924

Merge pull request #3078 from hypothesis/sheetaluk/281-update-the-toolbar-s-note-icon-tooltip-and-update-the-adder-design

changing adder icons and note icon in toolbar.

Addressing some PR comments.

Changed styling of the adder a bit.
Changed annotatoin icon click on the toolbar to create a new annotation instead of a new page note, when text has been selected.
Added a for attr for icon labels in the adder.

getting scripts/update-icon-font from branch: annotation-card-design-refresh

comitting new woff and icomoon css

showing adder in the middle top of selection rather than mousePosition.

Revert "showing adder in the middle top of selection rather than mousePosition."

This reverts commit 99491e42eb4103953f0cfa87afdd37e5ac8ece4d.

showing adder a little above the mouse position

check for end of text selection after current event loop tick

only show tooltip for toolbar and not adder

cursor pointer for adder labels

some styling

cleaning up css nesting.

more styling :/

Eliminate deadzone in adder buttons

 * Remove the margin between the adder buttons and the
   edge of the toolbar, and apply padding to the buttons instead.
   This removes the deadzone between the edge of the visible toolbar
   and the clickable area.

 * Add pointer cursor for the buttons

 * Use flexbox for laying out the toolbar for consistency
   with how the Adder is laid out

 * Use a transparent background for the individual buttons, so
   that their background does not obscure the rounded borders
   of the toolbar.

removing console.log

Add direct linking feature flag

Add a feature flag for direct linking and
use the link provided by the API to a view of
the annotation in context when this flag is enabled.

The Promise import is no longer needed because
Promise and Object.assign() are polyfilled globally
in polyfills.js

In order to make API requests, the client needs to
fetch a JWT token and then configure 'angular-jwt'
to provide it on subsequent HTTP requests to
API endpoints.

This fairly simple task was complicated by
the inclusion of an emulation of the deprecated
Mozilla IdentityManager API - see https://developer.mozilla.org/en-US/docs/Web/API/IdentityManager

This commit replaces the identity module with
a much simpler implementation that only does
what we actually need at present:

 1. Enable the 'angular-jwt' interceptor which
    adds 'Authorization: Bearer <Token>' headers
    to API HTTP requests.

 2. Provide the JWT interceptor with a function
    which fetches JWT tokens and caches them.

The new implementation fixes two bugs in the previous
implementation:

 1. Cached API tokens were not invalidated properly when
    signing out (#3083).

    (In the old code, 'authPromise' was set to a rejected promise
     after signing out, but 'checkAuthentication()' checked for
     'authPromise' being _null_ when deciding whether to retrieve
     a new token. Consequently API requests made immediately
     after signing in could end up being unauthenticated).

 2. The value of $scope.auth.username and session.state.userid
    could get out of sync (#2924).

    In the new implementation, $scope.auth.username is always
    updated whenever the USER_CHANGED event is emitted and that
    event is always emitted when session.state.userid changes.

Fixes #3083
Fixes #2924

Add a utility script to assist with CoffeeScript -> JS conversion

Convert 'annotation-ui' from CoffeeScript to JS

Remove the MathJax math rendering fallback

It accepts a list of CoffeeScript file paths on stdin
and for each <path>.coffee file in the input, it writes
a <path>.js output file containing the converted,
reformatted source.

The result is ES2015 source so will require some
fixups as long as we're using ES5 in the main app
codebase.

The current transformation process involves:

 1. Performing an initial CoffeeScript -> JS
    conversion with 'decaffeinate'

 2. Applying some fixups for common issues, currently
    done with dumb string modifications.

    In future I might look at writing a Babel transformer.

 3. Parsing the source with Babylon to check that it is valid ES2015
    If not, the user is prompted to go and simplify the CoffeeScript
    so that decaffeinate can process it correctly.

 4. Reformatting the source with typescript-formatter, which
    takes care of indentation and high-level formatting.

 5. Running the source through JSCS' fix mode which deals
    with smaller details.

Since this is a very simple module with no Angular
dependencies, I've also de-Angularized the unit test.

Fix installation of URL polyfill with js-polyfills v0.1.16

js-polyfills v0.1.15 used to install the polyfill on
`this.URL`, where `this` was set to module.exports in
the context of a Browserify bundle. Consequently the result
was available as `require('js-polyfills/url').URL`.

As of v0.1.16 however, it installs the polyfill on `self`,
which is the Window object in the context of the browser
and so `require('js-polyfills/url').URL` is undefined.

Fixes #3064

The MathJax fallback was inadvertently broken during recent
refactoring of the <markdown> component and has long been untested.

This removes the fallback for the moment and in doing so
provides a clearer definition of what math we support -
the subset supported by KaTeX.

Looking at our public annotations, there is very little use
of complex math currently.

When we find a clear use case for it, we can revisit supporting
additional math beyond what KaTeX supports.

See https://trello.com/c/9KkjsO6v/66-remove-the-mathjax-fallback
for more background.

Add extra context to sentry logging

Merge pull request #3057 from hypothesis/sheetaluk/280-when-a-user-replies-focus-on-and-expand-that-reply

Sheetaluk/280 when a user replies focus on and expand that reply

added missing new line.

don't attempt toggleCollapsed if no parent available

adding a test and a comment

simplifying assert

Convert {app, app-controller, widget-controller}.coffee to JS

Adds an issue template

 - Extract the logic computing a numeric key for
   sorting annotations by location into a separate
   module to make testing easier and add tests.

In preparation for upcoming changes as part of direct linking,
convert the entry point and top-level controllers for the app
to JS.

 * Use a CommonJS require to bring in the 'vendor/jwz' dependency.

Travis Sentry sourcemaps

Throwing an exception in the context of a Promise
catch handler inside through.obj() just results in the
exception being silently swallowed.

Pass it to the through2 callback
so that Gulp exits with the correct status.

This commit reworks scripts/gulp/upload-to-sentry.js to allow for
uploading to multiple Sentry projects at once. This allow us to build
the assets once, and upload them to multiple Sentry projects within the
same gulp invocation.