A hit region A is an ancestor region of a hit region B if B has a parent and its parent is either A or another hit region for which A is an ancestor region.

The region identified by the ID ID in a bitmap bitmap is the value returned by the following algorithm (which can return a hit region or nothing):

1. If ID is null, return nothing and abort these steps.

2. Let list be the hit region list associated with bitmap.

3. If there is a hit region in list whose ID is a case-sensitive match for ID, then return that hit region and abort these steps.

4. Otherwise, return nothing.

The region representing the control control for a bitmap bitmap is the value returned by the following algorithm (which can return a hit region or nothing):

1. Let list be the hit region list associated with bitmap.

2. If there is a hit region in list whose control is control, then return that hit region and abort these steps.

3. Otherwise, return nothing.

The control represented by a region region for a canvas element ancestor is the value returned by the following algorithm (which can return an element or nothing):

1. If region has no control, return nothing and abort these steps.

2. Let control be region's control.

3. If control is not a descendant of ancestor, then return nothing and abort these steps.

4. Otherwise, return control.

The cursor for a hit region region of a canvas element ancestor is the value returned by the following algorithm:

1. Loop: If region has a cursor specification other than "inherit", then return that hit region's cursor specification and abort these steps.

2. If region has a parent, then let region be that hit region's parent, and return to the step labeled loop.

3. Otherwise, return the used value of the 'cursor' property for the canvas element, if any; if there isn't one, return 'auto'. [CSSUI]

The region for a pixel pixel on a bitmap bitmap is the value returned by the following algorithm (which can return a hit region or nothing):

1. Let list be the hit region list associated with bitmap.

2. If there is a hit region in list whose set of pixels contains pixel, then return that hit region and abort these steps.

3. Otherwise, return nothing.

To clear regions that cover the pixels pixels on a bitmap bitmap, the user agent must run the following steps:

1. Let list be the hit region list associated with bitmap.

2. Remove all pixels in pixels from the set of pixels of each hit region in list.

3. Garbage-collect the regions of bitmap.

To garbage-collect the regions of a bitmap bitmap, the user agent must run the following steps:

1. Let list be the hit region list associated with bitmap.

2. Loop: Let victim be the first hit region in list to have an empty set of pixels and a zero child count, if any. If there is no such hit region, abort these steps.

3. If victim has a parent, then decrement that hit region's child count by one.

4. Remove victim from list.

5. Jump back to the step labeled loop.

Adding a new region and calling clearRect() are the two ways this clearing algorithm can be invoked. The hit region list itself is also reset when the rendering context is reset, e.g. when a CanvasRenderingContext2D object is bound to or unbound from a canvas, or when the dimensions of the bitmap are changed.

---

When the addHitRegion() method is invoked, the user agent must run the following steps:

1. Let arguments be the dictionary object provided as the method's argument.

2. If the arguments object's path member is not null, let source path be the path member's value. Otherwise, let it be the CanvasRenderingContext2D object's current default path.

3. Transform all the coordinates and lines in source path by the current transform matrix, if the arguments object's path member is not null.

4. Let specified pixels be the pixels contained in source path, using the fill rule indicated by the fillRule member.

5. If the arguments object's id member is the empty string, let it be null instead.

6. If the arguments object's id member is not null, then let previous region for this ID be the region identified by the ID given by the id member's value in this scratch bitmap, if any. If the id member is null or no such region currently exists, let previous region for this ID be null.

7. If the arguments object's parent member is the empty string, let it be null instead.

8. If the arguments object's parent member is not null, then let parent region be the region identified by the ID given by the parent member's value in the scratch bitmap, if any. If the parent member is null or no such region currently exists, let parent region be null.

9. If the arguments object's label member is the empty string, let it be null instead.

10. If any of the following conditions are met, throw a NotSupportedError exception and abort these steps.

    • The arguments object's control and label members are both non-null.
    • The arguments object's control and role members are both non-null.
    • The arguments object's role member's value is the empty string, and the label member's value is either null or the empty string.
    • The specified pixels has no pixels.
    • The arguments object's control member is not null but is neither an a element that represents a hyperlink, a button element, an input element whose type attribute is in one of the Checkbox or Radio Button states, nor an input element that is a button.
    • The parent region is not null but has a control.
    • The previous region for this ID is the same hit region as the parent region.
    • The previous region for this ID is an ancestor region of the parent region.

11. If the parent member is not null but parent region is null, then throw a NotFoundError exception and abort these steps.

12. If any of the following conditions are met, throw a SyntaxError exception and abort these steps.

    • The arguments object's cursor member is not null but is neither an ASCII case-insensitive match for the string "inherit", nor a valid CSS 'cursor' property value. [CSSUI]
    • The arguments object's role member is not null but its value is not an ordered set of unique space-separated tokens whose tokens are all case-sensitive matches for names of non-abstract WAI-ARIA roles. [ARIA]

13. Let region be a newly created hit region, with its information configured as follows:

    Hit region's set of pixels

    The specified pixels

    Hit region's bounding circumference

    A user-agent-defined shape that wraps the pixels contained in source path. (In the simplest case, this can just be the bounding rectangle; this specification allows it to be any shape in order to allow other interfaces.)

    Hit region's ID

    If the arguments object's id member is not null: the value of the id member. Otherwise, region has no id.

    Hit region's parent

    If parent region is not null: parent region. Otherwise, region has no parent.

    Hit region's child count

    Initially zero.

    Hit region's cursor specification

    If parent region is not null: parent region. Otherwise, region has no parent.

    Hit region's control

    If the arguments object's control member is not null: the value of the control member. Otherwise, region has no control.

    Hit region's label

    If the arguments object's label member is not null: the value of the label member. Otherwise, region has no label.

    Hit region's ARIA role

    If the arguments object's role member is not null: the value of the role member (which might be the empty string). Otherwise, if the arguments object's label member is not null: the empty string. Otherwise, region has no ARIA role.

14. If the arguments object's cursor member is not null, then act as if a CSS rule for the canvas element setting its 'cursor' property had been seen, whose value was the hit region's cursor specification.

    For example, if the user agent prefetches cursor values, this would cause that to happen in response to an appropriately-formed addHitRegion() call.

15. If the arguments object's control member is not null, then let previous region for the control be the region representing the control given by the control member's value for this scratch bitmap, if any. If the control member is null or no such region currently exists, let previous region for the control be null.

16. If there is a previous region with this control, remove it from the scratch bitmap's hit region list; then, if it had a parent region, decrement that hit region's child count by one.

17. If there is a previous region with this ID, remove it, and all hit regions for which it is an ancestor region, from the scratch bitmap's hit region list; then, if it had a parent region, decrement that hit region's child count by one.

18. If there is a parent region, increment its hit region's child count by one.

19. Clear regions that cover the pixels in region's set of pixels on this scratch bitmap.

20. Add region to the scratch bitmap's element's hit region list.

When the removeHitRegion() method is invoked, the user agent must run the following steps:

1. Let region be the region identified by the ID given by the method's argument in the rendering context's scratch bitmap. If no such region currently exists, abort these steps.

   If the method's argument is the empty string, then no region will match.

2. Remove region, and all hit regions for which it is an ancestor region, from the rendering context's scratch bitmap's hit region list; then, if it had a parent region, decrement that hit region's child count by one.

3. Garbage-collect the regions of the rendering context's scratch bitmap.

partial interface MouseEvent {
  readonly attribute DOMString? region;
};

partial dictionary MouseEventInit {
  DOMString? region;
};

The region attribute on MouseEvent objects must return the value it was initialized to. When the object is created, this attribute must be initialized to null. It represents the hit region's ID if the mouse was over a hit region when the event was fired.

When a MouseEvent is to be fired at a canvas element by the user agent in response to a pointing device action, if the canvas element has a hit region list, the user agent must instead follow these steps. If these steps say to act as normal, that means that the event must be fired as it would have had these requirements not been applied.

1. If the pointing device is not indicating a pixel on the canvas, act as normal and abort these steps.

2. Let pixel be the pixel indicated by the pointing device.

3. Let region be the hit region that is the region for the pixel pixel on this canvas element's bitmap, if any.

4. If there is no region, then act as normal and abort these steps.

5. Let id be the region's ID, if any.

6. If there is an id, then initialize the event object's region attribute to id.

7. Let control be the control represented by region for this canvas element, if any.

8. If there is a control, then target the event object at control instead of the canvas element.

9. Continue dispatching the event, but with the updated event object and target as given in the above steps.

---

When a user's pointing device cursor is positioned over a canvas element, user agents should render the pointing device cursor according to the cursor specification described by the cursor for the hit region that is the region for the pixel that the pointing device designates on the canvas element's bitmap.

---

User agents are encouraged to make use of the information present in a canvas element's hit region list to improve the accessibility of canvas elements.

Each hit region should be handled in a fashion equivalent to a node in a virtual DOM tree rooted at the canvas element. The hierarchy of this virtual DOM tree must match the hierarchy of the hit regions, as described by the parent of each region. Regions without a parent must be treated as children of the canvas element for the purpose of this virtual DOM tree. For each node in such a DOM tree, the hit region's bounding circumference gives the region of the screen to use when representing the node (if appropriate).

The semantics of a hit region for the purposes of this virtual DOM tree are those of the the control represented by the region, if it has one, or else of a non-interactive element whose ARIA role, if any, is that given by the hit region's ARIA role, and whose textual representation, if any, is given by the hit region's label.

For the purposes of accessibility tools, when an element C is a descendant of a canvas element and there is a region representing the control C for that canvas element's bitmap, then the element's position relative to the document should be presented as if it was that region in the canvas element's virtual DOM tree.

The semantics of a hit region for the purposes of this virtual DOM tree are those of the the control represented by the region, if it has one, or else of a non-interactive element whose ARIA role, if any, is that given by the hit region's ARIA role, and whose textual representation, if any, is given by the hit region's label.

Thus, for instance, a user agent on a touch-screen device could provide haptic feedback when the user croses over a hit region's bounding circumference, and then read the hit region's label to the user. Similarly, a desktop user agent with a virtual accessibility focus separate from the keyboard input focus could allow the user to navigate through the hit regions, using the virtual DOM tree described above to enable hierarchical navigation. When an interactive control inside the canvas element is focused, if the control has a corresponding region, then that hit region's bounding circumference could be used to determine what area of the display to magnify.