Allow host page to restrict which parts of the page can be annotated

[robertknight]

In the context of video transcript annotation, we want some way to constrain annotation to the transcript.

A possible solution is some generic mechanism which allows the page embedding Hypothesis to control which element(s) can be annotated. Some ideas for API:

1. Configuration option

Add a configuration option to the client which specifies element(s) that can be annotated. The configuration should support a serializable representation of the element (eg. CSS selector, element ID), for cases where the configuration is injected as JSON.

For example:

{
  "contentRoot": "#some-container"
}

Or:

{
  "contentElements": ["#container-a", "#container-b"]
}

2. DOM event

Dispatch a DOM event prior to showing the adder, which the host page can intercept to prevent annotation or modify the annotated range. Example of how the host page might achieve this:

document.body.addEventListener('hypothesis:beforeannotate', event => {
  // Modify `event.range` to alter the annotated range, or
  // `event.preventDefault()` to prevent annotation of this region
});

3. JS API

Expose a JavaScript API which allows the host page to interact with the client after it loads and configure behavior like this. We don't currently have any such API in place.

// TBD - How does the host page get the `hypothesisClient` object.
// As a property of a DOM event after the client loads, or via a callback specified
// in client configuration?

// Restrict annotation to `someElement`
hypothesisClient.setContentElements([someElement]);

[robertknight]

Pros of static configuration:

• Easier to specify, especially for less technically adept page authors
• Easier to reason about for debugging

Pros of dynamic APIs:

• Allows changing the annotatable regions over time without reloading the client
• More flexible

For the use case in the video player, I believe static configuration will be adequate.