dom/webidl/Document.webidl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  *
   6  * https://dom.spec.whatwg.org/#interface-document
   7  * https://html.spec.whatwg.org/multipage/dom.html#the-document-object
   8  * https://html.spec.whatwg.org/multipage/obsolete.html#other-elements%2C-attributes-and-apis
   9  * https://fullscreen.spec.whatwg.org/#api
  10  * https://w3c.github.io/pointerlock/#extensions-to-the-document-interface
  11  * https://w3c.github.io/pointerlock/#extensions-to-the-documentorshadowroot-mixin
  12  * https://w3c.github.io/page-visibility/#extensions-to-the-document-interface
  13  * https://drafts.csswg.org/cssom/#extensions-to-the-document-interface
  14  * https://drafts.csswg.org/cssom-view/#extensions-to-the-document-interface
  15  * https://wicg.github.io/feature-policy/#policy
  16  * https://wicg.github.io/scroll-to-text-fragment/#feature-detectability
  17  */
  18
  19 interface ContentSecurityPolicy;
  20 interface Principal;
  21 interface WindowProxy;
  22 interface nsISupports;
  23 interface URI;
  24 interface nsIDocShell;
  25 interface nsILoadGroup;
  26 interface nsIReferrerInfo;
  27 interface nsICookieJarSettings;
  28 interface nsIPermissionDelegateHandler;
  29 interface XULCommandDispatcher;
  30
  31 enum VisibilityState { "hidden", "visible" };
  32
  33 /* https://dom.spec.whatwg.org/#dictdef-elementcreationoptions */
  34 dictionary ElementCreationOptions {
  35   DOMString is;
  36
  37   [ChromeOnly]
  38   DOMString pseudo;
  39 };
  40
  41 /* https://dom.spec.whatwg.org/#interface-document */
  42 [Exposed=Window]
  43 interface Document : Node {
  44   [Throws]
  45   constructor();
  46
  47   [Throws]
  48   readonly attribute DOMImplementation implementation;
  49   [Pure, Throws, BinaryName="documentURIFromJS", NeedsCallerType]
  50   readonly attribute DOMString URL;
  51   [Pure, Throws, BinaryName="documentURIFromJS", NeedsCallerType]
  52   readonly attribute DOMString documentURI;
  53   [Pure]
  54   readonly attribute DOMString compatMode;
  55   [Pure]
  56   readonly attribute DOMString characterSet;
  57   [Pure,BinaryName="characterSet"]
  58   readonly attribute DOMString charset; // legacy alias of .characterSet
  59   [Pure,BinaryName="characterSet"]
  60   readonly attribute DOMString inputEncoding; // legacy alias of .characterSet
  61   [Pure]
  62   readonly attribute DOMString contentType;
  63
  64   [Pure]
  65   readonly attribute DocumentType? doctype;
  66   [Pure]
  67   readonly attribute Element? documentElement;
  68   [Pure]
  69   HTMLCollection getElementsByTagName(DOMString localName);
  70   [Pure, Throws]
  71   HTMLCollection getElementsByTagNameNS(DOMString? namespace, DOMString localName);
  72   [Pure]
  73   HTMLCollection getElementsByClassName(DOMString classNames);
  74
  75   // These DOM methods cannot be accessed by UA Widget scripts
  76   // because the DOM element reflectors will be in the content scope,
  77   // instead of the desired UA Widget scope.
  78   [CEReactions, NewObject, Throws, Func="IsNotUAWidget"]
  79   Element createElement(DOMString localName, optional (ElementCreationOptions or DOMString) options = {});
  80   [CEReactions, NewObject, Throws, Func="IsNotUAWidget"]
  81   Element createElementNS(DOMString? namespace, DOMString qualifiedName, optional (ElementCreationOptions or DOMString) options = {});
  82   [NewObject]
  83   DocumentFragment createDocumentFragment();
  84   [NewObject, Func="IsNotUAWidget"]
  85   Text createTextNode(DOMString data);
  86   [NewObject, Func="IsNotUAWidget"]
  87   Comment createComment(DOMString data);
  88   [NewObject, Throws]
  89   ProcessingInstruction createProcessingInstruction(DOMString target, DOMString data);
  90
  91   [CEReactions, Throws, Func="IsNotUAWidget"]
  92   Node importNode(Node node, optional boolean deep = false);
  93   [CEReactions, Throws, Func="IsNotUAWidget"]
  94   Node adoptNode(Node node);
  95
  96   [NewObject, Throws, NeedsCallerType]
  97   Event createEvent(DOMString interface);
  98
  99   [NewObject, Throws]
 100   Range createRange();
 101
 102   // NodeFilter.SHOW_ALL = 0xFFFFFFFF
 103   [NewObject, Throws]
 104   NodeIterator createNodeIterator(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null);
 105   [NewObject, Throws]
 106   TreeWalker createTreeWalker(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null);
 107
 108   // NEW
 109   // No support for prepend/append yet
 110   // undefined prepend((Node or DOMString)... nodes);
 111   // undefined append((Node or DOMString)... nodes);
 112
 113   // These are not in the spec, but leave them for now for backwards compat.
 114   // So sort of like Gecko extensions
 115   [NewObject, Throws]
 116   CDATASection createCDATASection(DOMString data);
 117   [NewObject, Throws]
 118   Attr createAttribute(DOMString name);
 119   [NewObject, Throws]
 120   Attr createAttributeNS(DOMString? namespace, DOMString name);
 121 };
 122
 123 // https://html.spec.whatwg.org/multipage/dom.html#the-document-object
 124 partial interface Document {
 125   [Pref="dom.webcomponents.shadowdom.declarative.enabled", Throws]
 126   static Document parseHTMLUnsafe((TrustedHTML or DOMString) html);
 127
 128   [PutForwards=href, LegacyUnforgeable] readonly attribute Location? location;
 129   [SetterThrows]                           attribute DOMString domain;
 130   readonly attribute UTF8String referrer;
 131   [Throws] attribute DOMString cookie;
 132   readonly attribute DOMString lastModified;
 133   readonly attribute DOMString readyState;
 134
 135   // DOM tree accessors
 136   //(Not proxy yet)getter object (DOMString name);
 137   [CEReactions, SetterThrows, Pure]
 138            attribute DOMString title;
 139   [CEReactions, Pure]
 140            attribute DOMString dir;
 141   [CEReactions, Pure, SetterThrows]
 142            attribute HTMLElement? body;
 143   [Pure]
 144   readonly attribute HTMLHeadElement? head;
 145   [SameObject] readonly attribute HTMLCollection images;
 146   [SameObject] readonly attribute HTMLCollection embeds;
 147   [SameObject] readonly attribute HTMLCollection plugins;
 148   [SameObject] readonly attribute HTMLCollection links;
 149   [SameObject] readonly attribute HTMLCollection forms;
 150   [SameObject] readonly attribute HTMLCollection scripts;
 151   [Pure]
 152   NodeList getElementsByName(DOMString elementName);
 153   //(Not implemented)readonly attribute DOMElementMap cssElementMap;
 154
 155   // dynamic markup insertion
 156   [CEReactions, Throws]
 157   Document open(optional DOMString unused1, optional DOMString unused2); // both arguments are ignored
 158   [CEReactions, Throws]
 159   WindowProxy? open(UTF8String url, DOMString name, DOMString features);
 160   [CEReactions, Throws]
 161   undefined close();
 162   [CEReactions, Throws]
 163   undefined write((TrustedHTML or DOMString)... text);
 164   [CEReactions, Throws]
 165   undefined writeln((TrustedHTML or DOMString)... text);
 166
 167   // user interaction
 168   [Pure]
 169   readonly attribute WindowProxy? defaultView;
 170   [Throws]
 171   boolean hasFocus();
 172   [CEReactions, SetterThrows, SetterNeedsSubjectPrincipal]
 173            attribute DOMString designMode;
 174   [CEReactions, Throws, NeedsSubjectPrincipal]
 175   boolean execCommand(DOMString commandId, optional boolean showUI = false,
 176                       optional (TrustedHTML or DOMString) value = "");
 177   [Throws, NeedsSubjectPrincipal]
 178   boolean queryCommandEnabled(DOMString commandId);
 179   [Throws]
 180   boolean queryCommandIndeterm(DOMString commandId);
 181   [Throws]
 182   boolean queryCommandState(DOMString commandId);
 183   [Throws, NeedsCallerType]
 184   boolean queryCommandSupported(DOMString commandId);
 185   [Throws]
 186   DOMString queryCommandValue(DOMString commandId);
 187   //(Not implemented)readonly attribute HTMLCollection commands;
 188
 189   // special event handler IDL attributes that only apply to Document objects
 190   [LegacyLenientThis] attribute EventHandler onreadystatechange;
 191
 192   // Gecko extensions?
 193                 attribute EventHandler onbeforescriptexecute;
 194                 attribute EventHandler onafterscriptexecute;
 195
 196   /**
 197    * True if this document is synthetic : stand alone image, video, audio file,
 198    * etc.
 199    */
 200   [Func="IsChromeOrUAWidget"] readonly attribute boolean mozSyntheticDocument;
 201   /**
 202    * Returns the script element whose script is currently being processed.
 203    *
 204    * @see <https://developer.mozilla.org/en/DOM/document.currentScript>
 205    */
 206   [Pure]
 207   readonly attribute Element? currentScript;
 208   /**
 209    * Release the current mouse capture if it is on an element within this
 210    * document.
 211    *
 212    * @see <https://developer.mozilla.org/en/DOM/document.releaseCapture>
 213    */
 214   [Deprecated=DocumentReleaseCapture, Pref="dom.mouse_capture.enabled"]
 215   undefined releaseCapture();
 216   /**
 217    * Use the given DOM element as the source image of target |-moz-element()|.
 218    *
 219    * This function introduces a new special ID (called "image element ID"),
 220    * which is only used by |-moz-element()|, and associates it with the given
 221    * DOM element.  Image elements ID's have the higher precedence than general
 222    * HTML id's, so if |document.mozSetImageElement(<id>, <element>)| is called,
 223    * |-moz-element(#<id>)| uses |<element>| as the source image even if there
 224    * is another element with id attribute = |<id>|.  To unregister an image
 225    * element ID |<id>|, call |document.mozSetImageElement(<id>, null)|.
 226    *
 227    * Example:
 228    * <script>
 229    *   canvas = document.createElement("canvas");
 230    *   canvas.setAttribute("width", 100);
 231    *   canvas.setAttribute("height", 100);
 232    *   // draw to canvas
 233    *   document.mozSetImageElement("canvasbg", canvas);
 234    * </script>
 235    * <div style="background-image: -moz-element(#canvasbg);"></div>
 236    *
 237    * @param aImageElementId an image element ID to associate with
 238    * |aImageElement|
 239    * @param aImageElement a DOM element to be used as the source image of
 240    * |-moz-element(#aImageElementId)|. If this is null, the function will
 241    * unregister the image element ID |aImageElementId|.
 242    *
 243    * @see <https://developer.mozilla.org/en/DOM/document.mozSetImageElement>
 244    */
 245   [UseCounter]
 246   undefined mozSetImageElement(DOMString aImageElementId,
 247                                Element? aImageElement);
 248
 249   [ChromeOnly]
 250   readonly attribute URI? documentURIObject;
 251
 252   /**
 253    * Current referrer policy - one of the referrer policy value from
 254    * ReferrerPolicy.webidl.
 255    */
 256   [ChromeOnly]
 257   readonly attribute ReferrerPolicy referrerPolicy;
 258
 259     /**
 260    * Current referrer info, which holds all referrer related information
 261    * including referrer policy and raw referrer of document.
 262    */
 263   [ChromeOnly]
 264   readonly attribute nsIReferrerInfo referrerInfo;
 265
 266 };
 267
 268 // https://html.spec.whatwg.org/multipage/obsolete.html#other-elements%2C-attributes-and-apis
 269 partial interface Document {
 270   [CEReactions] attribute [LegacyNullToEmptyString] DOMString fgColor;
 271   [CEReactions] attribute [LegacyNullToEmptyString] DOMString linkColor;
 272   [CEReactions] attribute [LegacyNullToEmptyString] DOMString vlinkColor;
 273   [CEReactions] attribute [LegacyNullToEmptyString] DOMString alinkColor;
 274   [CEReactions] attribute [LegacyNullToEmptyString] DOMString bgColor;
 275
 276   [SameObject] readonly attribute HTMLCollection anchors;
 277   [SameObject] readonly attribute HTMLCollection applets;
 278
 279   undefined clear();
 280   // @deprecated These are old Netscape 4 methods. Do not use,
 281   //             the implementation is no-op.
 282   // XXXbz do we actually need these anymore?
 283   undefined captureEvents();
 284   undefined releaseEvents();
 285
 286   [SameObject] readonly attribute HTMLAllCollection all;
 287 };
 288
 289 // https://fullscreen.spec.whatwg.org/#api
 290 partial interface Document {
 291   // Note: Per spec the 'S' in these two is lowercase, but the "Moz"
 292   // versions have it uppercase.
 293   [LegacyLenientSetter, Unscopable]
 294   readonly attribute boolean fullscreen;
 295   [BinaryName="fullscreen"]
 296   readonly attribute boolean mozFullScreen;
 297   [LegacyLenientSetter, NeedsCallerType]
 298   readonly attribute boolean fullscreenEnabled;
 299   [BinaryName="fullscreenEnabled", NeedsCallerType]
 300   readonly attribute boolean mozFullScreenEnabled;
 301
 302   [NewObject]
 303   Promise<undefined> exitFullscreen();
 304   [NewObject, BinaryName="exitFullscreen"]
 305   Promise<undefined> mozCancelFullScreen();
 306
 307   // Events handlers
 308   attribute EventHandler onfullscreenchange;
 309   attribute EventHandler onfullscreenerror;
 310 };
 311
 312 // https://w3c.github.io/pointerlock/#extensions-to-the-document-interface
 313 // https://w3c.github.io/pointerlock/#extensions-to-the-documentorshadowroot-mixin
 314 partial interface Document {
 315   undefined exitPointerLock();
 316
 317   // Event handlers
 318   attribute EventHandler onpointerlockchange;
 319   attribute EventHandler onpointerlockerror;
 320 };
 321
 322 // Mozilla-internal document extensions specific to error pages.
 323 partial interface Document {
 324   [Func="Document::CallerIsTrustedAboutCertError", NewObject]
 325   Promise<any> addCertException(boolean isTemporary);
 326
 327   [Func="Document::CallerIsTrustedAboutHttpsOnlyError"]
 328   undefined reloadWithHttpsOnlyException();
 329
 330   [Func="Document::CallerIsTrustedAboutCertError", Throws]
 331   FailedCertSecurityInfo getFailedCertSecurityInfo();
 332
 333   [Func="Document::CallerIsTrustedAboutNetError", Throws]
 334   NetErrorInfo getNetErrorInfo();
 335 };
 336
 337 // https://w3c.github.io/page-visibility/#extensions-to-the-document-interface
 338 partial interface Document {
 339   readonly attribute boolean hidden;
 340   readonly attribute VisibilityState visibilityState;
 341            attribute EventHandler onvisibilitychange;
 342 };
 343
 344 // https://drafts.csswg.org/cssom/#extensions-to-the-document-interface
 345 partial interface Document {
 346     attribute DOMString? selectedStyleSheetSet;
 347     readonly attribute DOMString? lastStyleSheetSet;
 348     readonly attribute DOMString? preferredStyleSheetSet;
 349     [Constant]
 350     readonly attribute DOMStringList styleSheetSets;
 351     undefined enableStyleSheetsForSet (DOMString? name);
 352 };
 353
 354 dictionary CaretPositionFromPointOptions {
 355   [Pref="dom.shadowdom.new_caretPositionFromPoint_behavior.enabled"]
 356   sequence<ShadowRoot> shadowRoots = [];
 357 };
 358
 359 // https://drafts.csswg.org/cssom-view/#extensions-to-the-document-interface
 360 partial interface Document {
 361     CaretPosition? caretPositionFromPoint(float x, float y, optional CaretPositionFromPointOptions options = {});
 362
 363     readonly attribute Element? scrollingElement;
 364 };
 365
 366 // https://drafts.csswg.org/web-animations/#extensions-to-the-document-interface
 367 partial interface Document {
 368   readonly attribute DocumentTimeline timeline;
 369 };
 370
 371 // https://svgwg.org/svg2-draft/struct.html#InterfaceDocumentExtensions
 372 partial interface Document {
 373   [BinaryName="SVGRootElement"]
 374   readonly attribute SVGSVGElement? rootElement;
 375 };
 376
 377 //  Mozilla extensions of various sorts
 378 partial interface Document {
 379   // Creates a new XUL element regardless of the document's default type.
 380   [ChromeOnly, CEReactions, NewObject, Throws]
 381   Element createXULElement(DOMString localName, optional (ElementCreationOptions or DOMString) options = {});
 382   // Wether the document was loaded using a nsXULPrototypeDocument.
 383   [ChromeOnly]
 384   readonly attribute boolean loadedFromPrototype;
 385
 386   // The principal to use for the storage area of this document
 387   [ChromeOnly]
 388   readonly attribute Principal effectiveStoragePrincipal;
 389
 390   // You should probably not be using this principal getter since it performs
 391   // no checks to ensure that the partitioned principal should really be used
 392   // here.  It is only designed to be used in very specific circumstances, such
 393   // as when inheriting the document/storage principal.
 394   [ChromeOnly]
 395   readonly attribute Principal partitionedPrincipal;
 396
 397   // The cookieJarSettings of this document
 398   [ChromeOnly]
 399   readonly attribute nsICookieJarSettings cookieJarSettings;
 400
 401   // Touch bits
 402   // XXXbz I can't find the sane spec for this stuff, so just cribbing
 403   // from our xpidl for now.
 404   [NewObject, Func="nsGenericHTMLElement::LegacyTouchAPIEnabled"]
 405   Touch createTouch(optional Window? view = null,
 406                     optional EventTarget? target = null,
 407                     optional long identifier = 0,
 408                     optional long pageX = 0,
 409                     optional long pageY = 0,
 410                     optional long screenX = 0,
 411                     optional long screenY = 0,
 412                     optional long clientX = 0,
 413                     optional long clientY = 0,
 414                     optional long radiusX = 0,
 415                     optional long radiusY = 0,
 416                     optional float rotationAngle = 0,
 417                     optional float force = 0);
 418   // XXXbz a hack to get around the fact that we don't support variadics as
 419   // distinguishing arguments yet.  Once this hack is removed. we can also
 420   // remove the corresponding overload on Document, since Touch... and
 421   // sequence<Touch> look the same in the C++.
 422   [NewObject, Func="nsGenericHTMLElement::LegacyTouchAPIEnabled"]
 423   TouchList createTouchList(Touch touch, Touch... touches);
 424   // XXXbz and another hack for the fact that we can't usefully have optional
 425   // distinguishing arguments but need a working zero-arg form of
 426   // createTouchList().
 427   [NewObject, Func="nsGenericHTMLElement::LegacyTouchAPIEnabled"]
 428   TouchList createTouchList();
 429   [NewObject, Func="nsGenericHTMLElement::LegacyTouchAPIEnabled"]
 430   TouchList createTouchList(sequence<Touch> touches);
 431
 432   [ChromeOnly]
 433   attribute boolean styleSheetChangeEventsEnabled;
 434
 435   [ChromeOnly]
 436   attribute boolean devToolsAnonymousAndShadowEventsEnabled;
 437
 438   [ChromeOnly, BinaryName="contentLanguageForBindings"] readonly attribute DOMString contentLanguage;
 439
 440   [ChromeOnly] readonly attribute nsILoadGroup? documentLoadGroup;
 441
 442   // Blocks the initial document parser until the given promise is settled.
 443   [ChromeOnly, NewObject]
 444   Promise<any> blockParsing(Promise<any> promise,
 445                             optional BlockParsingOptions options = {});
 446
 447   [Func="nsContentUtils::IsSystemOrPDFJS", BinaryName="blockUnblockOnloadForSystemOrPDFJS"]
 448   undefined blockUnblockOnload(boolean block);
 449
 450   // like documentURI, except that for error pages, it returns the URI we were
 451   // trying to load when we hit an error, rather than the error page's own URI.
 452   [ChromeOnly] readonly attribute URI? mozDocumentURIIfNotForErrorPages;
 453
 454   // A promise that is resolved when we have both fired DOMContentLoaded and
 455   // are ready to start layout.
 456   // This is used for the  "document_idle" webextension script injection point.
 457   [ChromeOnly, Throws]
 458   readonly attribute Promise<undefined> documentReadyForIdle;
 459
 460   // Lazily created command dispatcher, returns null if the document is not
 461   // chrome privileged.
 462   [ChromeOnly]
 463   readonly attribute XULCommandDispatcher? commandDispatcher;
 464
 465   [ChromeOnly]
 466   attribute boolean devToolsWatchingDOMMutations;
 467
 468   /**
 469    * Returns all the shadow roots connected to the document, in no particular
 470    * order, and without regard to open/closed-ness. Also returns UA widgets
 471    * (like <video> controls), which can be checked using
 472    * ShadowRoot.isUAWidget().
 473    */
 474   [ChromeOnly]
 475   sequence<ShadowRoot> getConnectedShadowRoots();
 476
 477   /**
 478    * By default, we don't send resizes to inactive top browsers.
 479    * Some callers (as of this writing the window sizing code and puppeteer)
 480    * need to trigger these resizes.
 481    *
 482    * @param aIncludeInactive whether to include background tabs.
 483    */
 484   [ChromeOnly]
 485   undefined synchronouslyUpdateRemoteBrowserDimensions(optional boolean aIncludeInactive = false);
 486 };
 487
 488 dictionary BlockParsingOptions {
 489   /**
 490    * If true, blocks script-created parsers (created via document.open()) in
 491    * addition to network-created parsers.
 492    */
 493   boolean blockScriptCreated = true;
 494 };
 495
 496 // Extension to give chrome JS the ability to determine when a document was
 497 // created to satisfy an iframe with srcdoc attribute.
 498 partial interface Document {
 499   [ChromeOnly] readonly attribute boolean isSrcdocDocument;
 500 };
 501
 502
 503 // Extension to give chrome JS the ability to get the underlying
 504 // sandbox flag attribute
 505 partial interface Document {
 506   [ChromeOnly] readonly attribute DOMString? sandboxFlagsAsString;
 507 };
 508
 509
 510 /**
 511  * Chrome document anonymous content management.
 512  * This is a Chrome-only API that allows inserting fixed positioned anonymous
 513  * content on top of the current page displayed in the document.
 514  */
 515 partial interface Document {
 516   /**
 517    * If aForce is true, tries to update layout to be able to insert the element
 518    * synchronously.
 519    */
 520   [ChromeOnly, NewObject, Throws]
 521   AnonymousContent insertAnonymousContent(optional boolean aForce = false);
 522
 523   /**
 524    * Removes the element inserted into the CanvasFrame given an AnonymousContent
 525    * instance.
 526    */
 527   [ChromeOnly]
 528   undefined removeAnonymousContent(AnonymousContent aContent);
 529 };
 530
 531 // http://w3c.github.io/selection-api/#extensions-to-document-interface
 532 partial interface Document {
 533   [Throws]
 534   Selection? getSelection();
 535 };
 536
 537 // https://github.com/whatwg/html/issues/3338
 538 partial interface Document {
 539   [Pref="dom.storage_access.enabled", NewObject]
 540   Promise<boolean> hasStorageAccess();
 541   [Pref="dom.storage_access.enabled", NewObject]
 542   Promise<undefined> requestStorageAccess();
 543   // https://github.com/privacycg/storage-access/pull/100
 544   [Pref="dom.storage_access.forward_declared.enabled", NewObject]
 545   Promise<undefined> requestStorageAccessUnderSite(DOMString serializedSite);
 546   [Pref="dom.storage_access.forward_declared.enabled", NewObject]
 547   Promise<undefined> completeStorageAccessRequestFromSite(DOMString serializedSite);
 548 };
 549
 550 // A privileged API to give chrome privileged code and the content script of the
 551 // webcompat extension the ability to request the storage access for a given
 552 // third party.
 553 partial interface Document {
 554   [Func="Document::CallerCanAccessPrivilegeSSA", NewObject]
 555   Promise<undefined> requestStorageAccessForOrigin(DOMString thirdPartyOrigin, optional boolean requireUserInteraction = true);
 556 };
 557
 558 // Extension to give chrome JS the ability to determine whether
 559 // the user has interacted with the document or not.
 560 partial interface Document {
 561   [ChromeOnly] readonly attribute boolean userHasInteracted;
 562 };
 563
 564 // Extension to give chrome JS the ability to simulate activate the document
 565 // by user gesture.
 566 partial interface Document {
 567   [ChromeOnly]
 568   undefined notifyUserGestureActivation();
 569   // For testing only.
 570   [ChromeOnly]
 571   undefined clearUserGestureActivation();
 572   [ChromeOnly]
 573   readonly attribute boolean hasBeenUserGestureActivated;
 574   [ChromeOnly]
 575   readonly attribute boolean hasValidTransientUserGestureActivation;
 576   [ChromeOnly]
 577   readonly attribute DOMHighResTimeStamp lastUserGestureTimeStamp;
 578   [ChromeOnly]
 579   boolean consumeTransientUserGestureActivation();
 580 };
 581
 582 // Extension to give chrome JS the ability to set an event handler which is
 583 // called with certain events that happened while events were suppressed in the
 584 // document or one of its subdocuments.
 585 partial interface Document {
 586   [ChromeOnly]
 587   undefined setSuppressedEventListener(EventListener? aListener);
 588 };
 589
 590 // Allows frontend code to query a CSP which needs to be passed for a
 591 // new load into docshell. Further, allows to query the CSP in JSON
 592 // format for testing purposes.
 593 partial interface Document {
 594   [ChromeOnly] readonly attribute ContentSecurityPolicy? csp;
 595   [ChromeOnly] readonly attribute DOMString cspJSON;
 596 };
 597
 598 partial interface Document {
 599   [Func="Document::DocumentSupportsL10n"] readonly attribute DocumentL10n? l10n;
 600   [Func="Document::DocumentSupportsL10n"] readonly attribute boolean hasPendingL10nMutations;
 601 };
 602
 603 Document includes XPathEvaluatorMixin;
 604 Document includes GlobalEventHandlers;
 605 Document includes TouchEventHandlers;
 606 Document includes ParentNode;
 607 Document includes OnErrorEventHandlerForNodes;
 608 Document includes GeometryUtils;
 609 Document includes FontFaceSource;
 610 Document includes DocumentOrShadowRoot;
 611
 612 // https://w3c.github.io/webappsec-feature-policy/#idl-index
 613 partial interface Document {
 614     [SameObject, Pref="dom.security.featurePolicy.webidl.enabled"]
 615     readonly attribute FeaturePolicy featurePolicy;
 616 };
 617
 618 // Extension to give chrome JS the ability to specify a non-default keypress
 619 // event model.
 620 partial interface Document {
 621   /**
 622    * setKeyPressEventModel() is called when we need to check whether the web
 623    * app requires specific keypress event model or not.
 624    *
 625    * @param aKeyPressEventModel  Proper keypress event model for the web app.
 626    *   KEYPRESS_EVENT_MODEL_DEFAULT:
 627    *     Use default keypress event model.  I.e., depending on
 628    *     "dom.keyboardevent.keypress.set_keycode_and_charcode_to_same_value"
 629    *     pref.
 630    *   KEYPRESS_EVENT_MODEL_SPLIT:
 631    *     Use split model.  I.e, if keypress event inputs a character,
 632    *     keyCode should be 0.  Otherwise, charCode should be 0.
 633    *   KEYPRESS_EVENT_MODEL_CONFLATED:
 634    *     Use conflated model.  I.e., keyCode and charCode values of each
 635    *     keypress event should be set to same value.
 636    */
 637   [ChromeOnly]
 638   const unsigned short KEYPRESS_EVENT_MODEL_DEFAULT = 0;
 639   [ChromeOnly]
 640   const unsigned short KEYPRESS_EVENT_MODEL_SPLIT = 1;
 641   [ChromeOnly]
 642   const unsigned short KEYPRESS_EVENT_MODEL_CONFLATED = 2;
 643   [ChromeOnly]
 644   undefined setKeyPressEventModel(unsigned short aKeyPressEventModel);
 645 };
 646
 647 // Extensions to return information about about the nodes blocked by the
 648 // Safebrowsing API inside a document.
 649 partial interface Document {
 650   /*
 651    * Number of nodes that have been blocked by the Safebrowsing API to prevent
 652    * tracking, cryptomining and so on. This method is for testing only.
 653    */
 654   [ChromeOnly, Pure]
 655   readonly attribute long blockedNodeByClassifierCount;
 656
 657   /*
 658    * List of nodes that have been blocked by the Safebrowsing API to prevent
 659    * tracking, fingerprinting, cryptomining and so on. This method is for
 660    * testing only.
 661    */
 662   [ChromeOnly, Pure]
 663   readonly attribute NodeList blockedNodesByClassifier;
 664 };
 665
 666 // Extension to programmatically simulate a user interaction on a document,
 667 // used for testing.
 668 partial interface Document {
 669   [ChromeOnly, BinaryName="setUserHasInteracted"]
 670   undefined userInteractionForTesting();
 671 };
 672
 673 // Extension for permission delegation.
 674 partial interface Document {
 675   [ChromeOnly, Pure]
 676   readonly attribute nsIPermissionDelegateHandler permDelegateHandler;
 677 };
 678
 679 // Extension used by the password manager to infer form submissions.
 680 partial interface Document {
 681   /*
 682    * Set whether the document notifies an event when a fetch or
 683    * XHR completes successfully.
 684    */
 685   [ChromeOnly]
 686   undefined setNotifyFetchSuccess(boolean aShouldNotify);
 687
 688   /*
 689    * Set whether a form and a password field notify an event when it is
 690    * removed from the DOM tree.
 691    */
 692   [ChromeOnly]
 693   undefined setNotifyFormOrPasswordRemoved(boolean aShouldNotify);
 694 };
 695
 696 // Extension to allow chrome code to detect initial about:blank documents.
 697 partial interface Document {
 698   [ChromeOnly]
 699   readonly attribute boolean isInitialDocument;
 700 };
 701
 702 // Extension to allow chrome code to get some wireframe-like structure.
 703 enum WireframeRectType {
 704   "image",
 705   "background",
 706   "text",
 707   "unknown",
 708 };
 709 dictionary WireframeTaggedRect {
 710   unrestricted double x = 0;
 711   unrestricted double y = 0;
 712   unrestricted double width = 0;
 713   unrestricted double height = 0;
 714   unsigned long color = 0; // in nscolor format
 715   WireframeRectType type;
 716   Node? node;
 717 };
 718 [GenerateInit]
 719 dictionary Wireframe {
 720   unsigned long canvasBackground = 0; // in nscolor format
 721   sequence<WireframeTaggedRect> rects;
 722   unsigned long version = 1; // Increment when the wireframe structure changes in backwards-incompatible ways
 723 };
 724 partial interface Document {
 725   [ChromeOnly]
 726   Wireframe? getWireframe(optional boolean aIncludeNodes = false);
 727 };
 728
 729 partial interface Document {
 730   // Returns true if the document is the current active document in a browsing
 731   // context which isn't in bfcache.
 732   [ChromeOnly]
 733   boolean isActive();
 734 };
 735
 736 Document includes NonElementParentNode;
 737
 738 /**
 739  * Extension to add the fragmentDirective property.
 740  * https://wicg.github.io/scroll-to-text-fragment/#feature-detectability
 741  */
 742 partial interface Document {
 743     [Pref="dom.text_fragments.enabled", SameObject]
 744     readonly attribute FragmentDirective fragmentDirective;
 745 };
 746
 747 // https://drafts.csswg.org/css-view-transitions-1/#additions-to-document-api
 748 partial interface Document {
 749   [Pref="dom.viewTransitions.enabled"]
 750   ViewTransition startViewTransition(optional ViewTransitionUpdateCallback updateCallback);
 751 };
 752
 753 // https://github.com/w3c/csswg-drafts/pull/10767 for the name divergence in the spec
 754 callback ViewTransitionUpdateCallback = Promise<any> ();