Captured Surface Control

We define a concept of an integer "zoom level" that can be applied to display surfaces of any type, and which is independent of the user agent and the platform. It is expected that in the case of browser display surfaces, this concept will match the concept of zoom level that user agents typically exposed to the user.

• The default zoom level of any display surface is defined to be 100. All implementations must support this value for all display surface of any type.
• Decreasing zoom level values represent "zooming out". The minimum theoretical value is 1; however, user agents may cap their support for "zooming out" at a larger values, with 100 being the largest permissible minimum value, representing lack of support for "zooming out".
• Increasing values represent "zooming in". This specification does not mandate a theoretical maximum. The smallest possible maximum is 100, which represents lack of support for "zooming in".

For a given display surface of type surfaceType, we define the user agent's set of supported zoom levels for surfaceType as a non-empty set of integers including at least the default zoom level (100), and not including any integers lesser than 1.

We define the permitted event types for setZoomLevel as a set composed of the following event types:

• "click"
• "input"

WebIDLpartial interface CaptureController {
  sequence<long> getSupportedZoomLevels();
  long getZoomLevel();
  Promise<undefined> setZoomLevel(long zoomLevel);
  attribute EventHandler oncapturedzoomlevelchange;
};

getSupportedZoomLevels()

This method allows applications to discover the set of zoom levels supported by the user agent.

When invoked, the user agent MUST run the following steps:

1. If this is not actively capturing, throw an "InvalidStateError" DOMException.
2. Let surfaceType be this.[[DisplaySurfaceType]].
3. If surfaceType is not a supported display surface type, throw a "NotSupportedError" DOMException.
4. Return a monotonically increasing sequence containing all of the values in the supported zoom levels for surfaceType.

getZoomLevel()

This method allows applications to discover the captured display surface's zoom level.

When invoked, the user agent MUST run the following steps:

1. If this is not actively capturing, throw an "InvalidStateError" DOMException.
2. If this.[[DisplaySurfaceType]] is not a supported display surface type, throw a "NotSupportedError" DOMException.
3. Return this.[[Source]]'s zoom level.

setZoomLevel()

This method allows applications to set the captured display surface's zoom level.

When invoked, the user agent MUST run the following steps:

1. If this is not actively capturing, return a promise rejected with a DOMException object whose name attribute has the value InvalidStateError.
2. Let surfaceType be this.[[DisplaySurfaceType]].
3. If surfaceType is not a supported display surface type, return a promise rejected with a DOMException object whose name attribute has the value NotSupportedError.

4. Ensure that the code is running from within the context of an event handler which was triggered by the browser agent firing a trusted event, triggered by the user interacting with the user agent. To do so, run the following steps:

   1. Let currentEvent be Window.event.
   2. If currentEvent is undefined, return a promise rejected with a DOMException object whose name attribute has the value InvalidStateError.
   3. If currentEvent.isTrusted is false, return a promise rejected with a DOMException object whose name attribute has the value InvalidStateError.
   4. If currentEvent.type is not in permitted event types for setZoomLevel, return a promise rejected with a DOMException object whose name attribute has the value InvalidStateError.
      Note

      It follows from these steps that setZoomLevel() is only callable with transient activation, because permitted event types for setZoomLevel only contains event types that confer this activation.

      In fact, our API shape implies a stronger guarantee - whereas transient activation persists for several seconds after the user action, the API shape here limits setZoomLevel() to being called immediately following the user's action.

5. Let targetZoomLevel be the method's first argument.
6. If targetZoomLevel is not included in the user agent's set of supported zoom levels for surfaceType, return a promise rejected with a DOMException object whose name attribute has the value InvalidStateError.
7. Let P be a new Promise.

8. Run the following steps in parallel:

   1. Request permission to use a PermissionDescriptor with its name member set to "captured-surface-control". If the result of the request is "denied", reject P with a new DOMException object whose name is NotAllowedError and abort these steps.
   2. Set this.[[Source]]'s zoom level to targetZoomLevel.
   3. Resolve P.
9. Return P.

oncapturedzoomlevelchange

The user agent MUST fire a blank event on this EventHandler whenever this.[[Source]]'s zoom level changes.

Note

Examples of causes include:

• The user interacted with the user agent to change the zoom level of a captured tab.
• The capturing application called setZoomLevel().
• The user changed the shared display surface, choosing one which has a different zoom level.

WebIDLdictionary ForwardedGestures {
  boolean wheel = false;
};

wheel

Whether the application calling forwardGestures() wants wheel events to be forwarded from the indicated element to the captured surface.

WebIDLpartial interface CaptureController {
  constructor();
  Promise<undefined> forwardGestures(
      HTMLElement element,
      optional ForwardedGestures gestures = {});
};

constructor

CaptureController's constructor is extended to also define and initialize the following internal slots:

Internal Slot	Initial value
[[GestureForwardingElementsMap]]	Empty map

forwardGestures()

This method allows applications to automatically forward gesture events (e.g. wheel events) from an HTMLElement to the viewport of a captured display surface.

When invoked, the user agent MUST run the following steps:

1. If this is not actively capturing, return a promise rejected with a DOMException object whose name attribute has the value InvalidStateError.
2. Let surfaceType be this.[[DisplaySurfaceType]].
3. If surfaceType is not a supported display surface type, return a promise rejected with a DOMException object whose name attribute has the value NotSupportedError.
4. Let element be the method's first argument.
5. Let gestures be the method's second argument.
6. Let P be a new Promise.
7. Run the following steps in parallel:
   1. Get the current permission state of "captured-surface-control". If the result is NOT "granted", and the relevant global object does NOT have transient activation, return a promise rejected with a DOMException object whose name attribute has the value InvalidStateError.
      Note

      This step ensures that on the one hand, permission prompts are not be shown without transient activation, while on the one hand, if the permission is already "granted", forwardGestures() may be called immediately after getDisplayMedia() resolves, even if the transient activation that permitted the call to forwardGestures() has since expired.

   2. Request permission to use a PermissionDescriptor with its name member set to "captured-surface-control". If the result of the request is "denied", reject P with a new DOMException object whose name is NotAllowedError and abort these steps.
   3. Let map be this.[[GestureForwardingElementsMap]].
   4. If map[element] exists, remove an event listener with element as eventTarget and map[element] as listener.
   5. Set this.[[GestureForwardingElement]] to element.
   6. Set this.[[GestureForwardingEventListener]] to null.
   7. If this.[[GestureForwardingElement]] is null, resolve P and abort these steps.
   8. Set this.[[GestureForwardingEventListener]] to an event listener defined as follows:

      type

      wheel

      callback

      The result of creating a new Web IDL EventListener instance representing a reference to a function of one argument of type Event event. This function executes the forward wheel event algorithm given this and event.

   9. Add an event listener with:

      • this.[[GestureForwardingElement]] as eventTarget.
      • this.[[GestureForwardingEventListener]] as listener.
   10. Resolve P.
8. Return P.

To determine if a CaptureController controller is actively capturing, run the following steps:

1. Let source be controller.[[Source]].
2. If source is null, return false.
3. If source has been stopped, return false.
4. Return true.

To determine if a display surface surfaceType is supported display surface type, run the following steps:

1. If surfaceType is browser, return true.
2. Return false.

The forward wheel event algorithm takes a CaptureController controller and a WheelEvent event, and runs the following steps:

1. If controller is not actively capturing, abort these steps.
2. Let surfaceType be controller.[[DisplaySurfaceType]].
3. If surfaceType is not a supported display surface type, abort these steps.
4. Run the following steps in parallel:
   1. Get the current permission state of "captured-surface-control". If the result is NOT "granted", abort these steps.
   2. If event.isTrusted is false, abort these steps.
   3. Let [scaledX, scaledY] be the result of the scale element coordinates algorithm on [event.offsetX, event.offsetY] and this.[[GestureForwardingElement]].
   4. Fire an event named "wheel" using WheelEvent with the x attribute initialized to scaledX, the y attribute initialized to scaledY, the deltaX attribute initialized to event.deltaX and the deltaY attribute initialized to event.deltaY, at controller.[[Source]]'s viewport.

The scale element coordinates algorithm takes double coordinates [x, y] and a CaptureController controller, and run the following steps:

1. Let scaleFactorX be (x / controller.[[GestureForwardingElement]].getBoundingClientRect().width).
2. Let scaleFactorX be (x / controller.[[GestureForwardingElement]].getBoundingClientRect().height).
3. Let surfaceWidth be controller.[[Source]]'s viewport's width.
4. Let surfaceHeight be controller.[[Source]]'s viewport's height.
5. Let scaledX be (scaleFactorX * surfaceWidth).
6. Let scaledY be (scaleFactorY * surfaceHeight).
7. Return [scaledX, scaledY].

setZoomLevel() is only callable from event handlers of specific event types - the permitted event types for setZoomLevel. These are events dispatched directly by the user agent, triggered by user interaction. This specification intentionally excludes from this set such events as "mousemove", which users are liable to trigger inadvertently.

The shape of forwardGestures() is intentionally chosen to limit the capturing application's control. The application designates a specific element which, when the user scrolls over it, the corresponding wheel events are forwarded to the captured application. This is in intentional contrast to a prior API shape, sendWheel(), whereby the capturing application could instigate scrolling of the captured application at any time.

This specification does not limit the type of Element for which either setZoomLevel() or forwardGestures() work. Such a limitation would accomplish nothing, because malicious applications could always overlay transparent permitted Element types on top of visible non-permitted Elements, thereby bypassing this restriction.

The limitation of interaction types is sufficient. This is accomplished by forwardGestures() through its shape, and by setZoomLevel() through its gating on event types.